OrderSequenceGenerator 1.0.1

OrderSequenceGenerator

Zero-setup, high-performance, atomic order and application numbering generator for .NET 8 backed by PostgreSQL.

• Zero Manual SQL: Automatically provisions PostgreSQL tables, columns matching pattern tokens, and unique composite constraints on application startup.
• 17 Industry Presets: Pre-configured e-Seba, retail, POS, tax invoice, and custom patterns.
• 100% Concurrency Safe: Uses atomic INSERT ... ON CONFLICT (...) DO UPDATE ... RETURNING sequence to guarantee zero gaps and zero duplicate numbers under extreme concurrency.
• Automatic Walkthrough Script: Installing this NuGet package automatically places walkthrough.ps1 into the consumer project root for interactive command-line testing and setup!

📦 Installation

Install via the .NET Core CLI:

dotnet add package OrderSequenceGenerator

Or via the Package Manager Console in Visual Studio:

Install-Package OrderSequenceGenerator

🛠️ Step 1: Interactive Terminal Setup (walkthrough.ps1)

The moment you install this package and run dotnet build, walkthrough.ps1 is automatically delivered to your project root.

Open PowerShell in your project folder and run:

.\walkthrough.ps1

This interactive CLI tool allows you to:

1. Preview all 17 pattern styles and live sample numbers.
2. Select or enter any custom numbering pattern.
3. Test your PostgreSQL connection interactively.
4. Preview the exact SQL DDL and inspect the generated columns.
5. Test atomic sequence increments directly in your terminal.

🚀 Step 2: C# Setup & Registration (Zero Manual SQL)

Add the generator in your Program.cs. With AutoMigrate = true, you do not need to write migrations or SQL scripts—the engine derives all table columns directly from your pattern!

Example 1: e-Seba Government Pattern

using OrderSequenceGenerator;
using OrderSequenceGenerator.Extensions;

var builder = WebApplication.CreateBuilder(args);

// Register with PostgreSQL atomic persistence
builder.Services.AddOrderSequenceGenerator(options =>
{
    options.ConnectionString = builder.Configuration.GetConnectionString("DefaultConnection")!;
    
    // Choose from built-in presets:
    options.Pattern = OrderPatterns.ESebaCompact; // "{DISTRICT}{yyyy}{PREFIX}{MM}{dd}{SEQ:4}"
    
    // Optional configuration:
    options.TableName = "order_sequence"; // default table name
    options.AutoMigrate = true;           // auto-creates columns matching pattern tokens!
});

var app = builder.Build();
app.Run();

Example 2: Standard Retail / E-Commerce Pattern

builder.Services.AddOrderSequenceGenerator(options =>
{
    options.ConnectionString = builder.Configuration.GetConnectionString("DefaultConnection")!;
    options.Pattern = OrderPatterns.StandardRetail; // "{PREFIX}-{yyyyMMdd}-{SEQ:4}"
    options.AutoMigrate = true;
});

Example 3: Custom Organization / Multi-Branch Pattern

You can define any combination of tokens:

builder.Services.AddOrderSequenceGenerator(options =>
{
    options.ConnectionString = builder.Configuration.GetConnectionString("DefaultConnection")!;
    // Defines custom tokens: {COMPANY}, {DEPT}, {BRANCH}
    options.Pattern = "{COMPANY}-{DEPT}-{BRANCH}-{yyyyMMdd}-{SEQ:5}";
    options.AutoMigrate = true; // Automatically creates columns: company, dept, branch, year, month, day
});

💻 Step 3: Generating Sequences in Code

Inject IOrderSequenceGenerator into any Controller, Minimal API endpoint, or Service.

In an ASP.NET Core Controller:

using Microsoft.AspNetCore.Mvc;
using OrderSequenceGenerator;

[ApiController]
[Route("api/[controller]")]
public class ApplicationsController : ControllerBase
{
    private readonly IOrderSequenceGenerator _generator;

    public ApplicationsController(IOrderSequenceGenerator generator)
    {
        _generator = generator;
    }

    [HttpPost]
    public async Task<IActionResult> CreateApplication([FromBody] ApplicationRequest request)
    {
        // Pass custom pattern tokens as an anonymous object:
        // (Date tokens yyyy, MM, dd are automatically populated from UTC now!)
        string appNumber = await _generator.NextAsync(new
        {
            District = request.District, // "MN051"
            Prefix = "E"
        });

        // Generated output: "MN05120260909E0001"
        return Ok(new 
        { 
            ApplicationNumber = appNumber, 
            Status = "Created" 
        });
    }
}

In a Minimal API:

app.MapPost("/api/orders", async (IOrderSequenceGenerator generator) =>
{
    string orderNo = await generator.NextAsync(new { Prefix = "ORD" });
    return Results.Ok(new { OrderNumber = orderNo }); // e.g. "ORD-20260909-0001"
});

Using a Dictionary:

var tokenValues = new Dictionary<string, string>
{
    { "DISTRICT", "MN051" },
    { "PREFIX", "E" }
};

string sequenceNo = await _generator.NextAsync(tokenValues);

Getting Just the Raw Numeric Sequence:

long rawNumber = await _generator.NextRawSequenceAsync(new { District = "MN051", Prefix = "E" });
// Returns: 1, 2, 3...

🧪 Unit Testing / Local Offline Scenarios

For unit tests or development environments without a live PostgreSQL database, use the in-memory provider:

// In your test project or mock setup:
services.AddInMemoryOrderSequenceGenerator(options =>
{
    options.Pattern = OrderPatterns.ESebaCompact;
});

📋 17 Built-In Pattern Presets

🗄️ How the Database Schema Works

When AutoMigrate = true is enabled, the library inspects your pattern string and provisions PostgreSQL idempotently:

1. Primary Key: id BIGSERIAL PRIMARY KEY.
2. Dynamic Columns: A column is created for each custom token and date token found in the template string:
   • {DISTRICT} $\rightarrow$ district VARCHAR(50) NOT NULL
   • {PREFIX} $\rightarrow$ prefix VARCHAR(50) NOT NULL
   • {yyyy} $\rightarrow$ year INTEGER NOT NULL
   • {MM} $\rightarrow$ month INTEGER NOT NULL
   • {dd} $\rightarrow$ day INTEGER NOT NULL
3. Sequence Counter: sequence BIGINT NOT NULL DEFAULT 0.
4. Audit Timestamp: updated_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT CURRENT_TIMESTAMP.
5. Composite Unique Constraint: A constraint UQ_<tableName>_scope UNIQUE (<token_columns>) guarantees that each unique combination of scope values maintains its own atomic sequence counter.

Atomic Concurrency Guarantee

All sequence numbers are generated using PostgreSQL atomic upsert:

INSERT INTO order_sequence (district, prefix, year, month, day, sequence, updated_at)
VALUES (@district, @prefix, @year, @month, @day, 1, CURRENT_TIMESTAMP)
ON CONFLICT (district, prefix, year, month, day)
DO UPDATE SET sequence = order_sequence.sequence + 1, updated_at = CURRENT_TIMESTAMP
RETURNING sequence;

This guarantees zero duplicate sequence numbers and zero gaps, even under high load across distributed servers.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.