README

Framework-agnostic auto-numbering and sequence generation package.

Overview

Nexus\Sequencing provides a robust, atomic, and transaction-safe system for generating unique sequential identifiers (e.g., invoice numbers, order IDs, reference codes) with customizable patterns, counter management, and advanced features like gap filling, bulk generation, and pattern versioning.

Key Features

Framework-Agnostic Core: Pure PHP logic with no Laravel dependencies
Atomic Number Generation: Database-level locking (SELECT FOR UPDATE) ensures zero duplicates
Transaction-Safe: Counter increments roll back if the parent transaction fails
Flexible Patterns: Support for variables like {YEAR}, {MONTH}, {COUNTER}, and custom context variables
Counter Reset Strategies: Daily, Monthly, Yearly, Never, or custom count-based resets
Preview Mode: Preview the next number without consuming the counter
Gap Management: Fill gaps from voided/cancelled numbers or report gaps
Bulk Generation: Generate multiple numbers atomically with optimized locking
Pattern Versioning: Support time-based pattern changes with effective dates
Exhaustion Monitoring: Detect when counters approach maximum values
Number Reservation: Reserve numbers temporarily with configurable TTL
Validation: Validate if a given number matches a pattern's format

Architecture

This package follows the Nexus monorepo architecture:

packages/Sequencing/: Framework-agnostic business logic (the "engine")
apps/Atomy/: Laravel implementation with Eloquent models, migrations, and repositories

Package Structure

packages/Sequencing/
├── composer.json
├── LICENSE
├── README.md
└── src/
    ├── Contracts/              # All interfaces
    │   ├── SequenceInterface.php
    │   ├── SequenceRepositoryInterface.php
    │   ├── SequenceAuditInterface.php
    │   ├── CounterRepositoryInterface.php
    │   ├── ReservationRepositoryInterface.php
    │   └── GapRepositoryInterface.php
    ├── Exceptions/             # Domain exceptions
    │   ├── InvalidPatternException.php
    │   ├── SequenceExhaustedException.php
    │   ├── SequenceNotFoundException.php
    │   ├── SequenceLockedException.php
    │   ├── CounterOverflowException.php
    │   ├── PatternCollisionException.php
    │   ├── InvalidResetPeriodException.php
    │   └── ReservationExpiredException.php
    ├── ValueObjects/           # Immutable value objects
    │   ├── ResetPeriod.php
    │   ├── OverflowBehavior.php
    │   ├── GapPolicy.php
    │   ├── PatternVariable.php
    │   └── SequenceMetrics.php
    └── Services/               # Business logic
        ├── SequenceManager.php
        ├── PatternParser.php
        ├── CounterService.php
        ├── BulkGeneratorService.php
        ├── GapManager.php
        ├── ReservationService.php
        ├── PatternVersionManager.php
        ├── PatternMigrationService.php
        ├── ExhaustionMonitor.php
        ├── SequenceValidationService.php
        └── SequenceMetricsService.php

Core Concepts

1. Sequence Definition

A sequence is defined by:

Name: Unique identifier (e.g., invoice_number, po_number)
Scope: Optional scope identifier for multi-tenant or partitioned sequences
Pattern: Template with variables (e.g., INV-{YEAR}-{COUNTER:5})
Reset Period: When the counter resets (Daily, Monthly, Yearly, Never)
Step Size: Increment value (default: 1)
Reset Limit: Counter-based reset (e.g., reset after 1000 numbers)
Gap Policy: How to handle gaps in sequences
Overflow Behavior: What to do when counter reaches maximum

2. Pattern Variables

Built-in variables:

{YEAR} - Full year (e.g., 2025)
{YY} - Short year (e.g., 25)
{MONTH} - Month with leading zero (01-12)
{DAY} - Day with leading zero (01-31)
{COUNTER} - Sequential counter
{COUNTER:5} - Counter with padding (00001, 00002, etc.)

Custom context variables:

{DEPARTMENT} - Provided at generation time
{BRANCH} - Provided at generation time
Any custom variable you define

3. Reset Periods

Control when counters reset:

Never: Counter never resets (monotonically increasing)
Daily: Counter resets at midnight
Monthly: Counter resets on the 1st of each month
Yearly: Counter resets on January 1st

4. Gap Policies

Handle missing numbers in sequences:

allow_gaps: Default behavior, gaps are allowed (e.g., when transactions fail)
fill_gaps: Reuse voided/cancelled numbers to fill gaps
report_gaps_only: Track gaps but don't fill them

5. Overflow Behavior

Define what happens when counter approaches maximum:

throw_exception: Throw SequenceExhaustedException
switch_pattern: Automatically migrate to a new pattern
extend_padding: Increase padding size (e.g., 9999 → 10000)

Usage Example

Generating a Number

use Nexus\Sequencing\Services\SequenceManager;

// Inject via dependency injection
public function __construct(
    private readonly SequenceManager $sequenceManager
) {}

// Generate the next number
$invoiceNumber = $this->sequenceManager->generate(
    sequenceName: 'invoice_number',
    scopeIdentifier: 'tenant_123',
    contextVariables: [
        'DEPARTMENT' => 'SALES',
    ]
);
// Result: "INV-2025-SALES-00001"

Previewing the Next Number

$preview = $this->sequenceManager->preview(
    sequenceName: 'invoice_number',
    scopeIdentifier: 'tenant_123'
);
// Result: "INV-2025-SALES-00002" (counter not incremented)

Bulk Generation

$numbers = $this->bulkGenerator->generateBulk(
    sequenceName: 'ticket_number',
    count: 100
);
// Result: ["TKT-00001", "TKT-00002", ..., "TKT-00100"]

Reserving Numbers

// Reserve 10 numbers for batch processing
$reservedNumbers = $this->reservationService->reserve(
    sequenceName: 'order_number',
    count: 10,
    ttlMinutes: 30
);
// Result: ["ORD-001", "ORD-002", ..., "ORD-010"]

// Release unused numbers
$this->reservationService->release(
    sequenceName: 'order_number',
    numbers: ['ORD-005', 'ORD-008']
);

Gap Management

// Report on gaps in a sequence
$gapReport = $this->gapManager->getGapReport(
    sequenceName: 'invoice_number'
);
// Result: ["INV-00005", "INV-00012", "INV-00023"]

// Reclaim a gap (for fill_gaps policy)
$this->gapManager->reclaimGap(
    sequenceName: 'invoice_number',
    number: 'INV-00005'
);

Business Rules

Immutability: Generated numbers cannot be changed once consumed
Atomicity: Database-level locking ensures no duplicates
Transaction Safety: Counter increments roll back with parent transaction
Uniqueness: Sequence name + scope identifier forms a composite key
Manual Override: Overridden values must be greater than the last generated number
Preview Safety: Previewing does not increment the counter
Gap Reclaim: Only voided/cancelled numbers can be reclaimed (if gap_policy allows)

Integration with Atomy

The Laravel application (apps/Atomy) provides:

Eloquent Models: Sequence, SequenceCounter, SequenceReservation, SequenceGap
Repository Implementations: DbSequenceRepository, DbCounterRepository, etc.
Migrations: Database schema for sequences and counters
Service Provider: IoC bindings for dependency injection
API Endpoints: RESTful API for sequence management
Configuration: Tenant-specific sequence definitions

Requirements Coverage

This package fulfills all requirements defined in REQUIREMENTS.csv:

✅ ARC-SEQ-0019 to ARC-SEQ-0026: Architectural requirements (framework-agnostic, interfaces, repositories)
✅ BUS-SEQ-0043 to BUS-SEQ-0239: Business requirements (immutability, atomicity, padding, overrides)
✅ FUN-SEQ-0210 to FUN-SEQ-0245: Functional requirements (generation, preview, bulk, gaps, versioning)
✅ PER-SEQ-0329, PER-SEQ-0336: Performance requirements (< 50ms generation, concurrent requests)

📖 Documentation

Package Documentation

Additional Resources

IMPLEMENTATION_SUMMARY.md - Implementation progress
REQUIREMENTS.md - Requirements
TEST_SUITE_SUMMARY.md - Tests
VALUATION_MATRIX.md - Valuation

License

MIT License. See LICENSE for details.

Contributing

This package is part of the Nexus monorepo. See the main ARCHITECTURE.md for contribution guidelines.

azaharizaman / nexus-sequencing

Maintainers

Package info

Statistics

Security