OrderSequenceGenerator 1.0.2

OrderSequenceGenerator

A high-performance, atomic order and sequence number generator for .NET 8 using PostgreSQL.

• Zero Manual SQL Setup: Automatically creates your database table, columns, and unique constraints when your application starts.
• 17 Ready-to-Use Patterns: Built-in support for e-Seba, retail, POS, tax invoices, and custom formats.
• 100% Concurrency Safe: Uses atomic database operations (INSERT ... ON CONFLICT DO UPDATE) to guarantee zero duplicate numbers and zero gaps.
• Interactive Setup Tool: Includes a PowerShell script (walkthrough.ps1) that copies itself to your project to help you test patterns and database settings.

🚀 Quick Start (3 Easy Steps)

Step 1: Install the Package

Run this command in your project folder:

dotnet add package OrderSequenceGenerator

Step 2: Build Your Project

Build your application to automatically copy the interactive setup tool into your project folder:

dotnet build

Note: Building your project places walkthrough.ps1 in your project root folder.

Step 3: Run the Setup Assistant (Optional)

Run the script to preview patterns and verify your database connection:

.\walkthrough.ps1

🛠️ How to Use in C#

1. Register the Service in Program.cs

Add the generator to your application services. You do not need to write any SQL—the library creates the table and all required columns automatically.

using OrderSequenceGenerator;
using OrderSequenceGenerator.Extensions;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddOrderSequenceGenerator(options =>
{
    // Provide your PostgreSQL connection string
    options.ConnectionString = builder.Configuration.GetConnectionString("DefaultConnection")!;
    
    // Choose a pattern (preset or custom)
    options.Pattern = OrderPatterns.ESebaCompact; // Format: {DISTRICT}{yyyy}{PREFIX}{MM}{dd}{SEQ:4}
    
    // Automatically create table and columns on startup
    options.AutoMigrate = true;
    
    // Optional: customize the table name (default is "order_sequence")
    options.TableName = "order_sequence";
});

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

2. Generate Numbers in Your Controllers or Services

Inject IOrderSequenceGenerator and call NextAsync. Date values (yyyy, MM, dd) are filled in automatically using the current UTC time.

ASP.NET Core Controller Example:

using Microsoft.AspNetCore.Mvc;
using OrderSequenceGenerator;

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

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

    [HttpPost]
    public async Task<IActionResult> CreateOrder([FromBody] CreateOrderRequest request)
    {
        // Pass your custom token values as an object:
        string orderNumber = await _generator.NextAsync(new
        {
            District = request.District, // Example: "MN051"
            Prefix = "E"
        });

        // Returns: "MN05120260909E0001"
        return Ok(new { OrderNumber = orderNumber });
    }
}

Minimal API Example:

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

Using a Dictionary:

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

string orderNumber = await _generator.NextAsync(tokens);

Getting Only the Numeric Value:

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

🧩 Built-in Pattern Presets

You can use any of the 17 built-in patterns from OrderPatterns:

🎨 Creating Custom Patterns

You can define any pattern format using standard tokens:

options.Pattern = "{COMPANY}-{BRANCH}-{yyyyMMdd}-{SEQ:5}";

• Date Tokens: {yyyy} (4-digit year), {yy} (2-digit year), {MM} (2-digit month), {dd} (2-digit day), {yyyyMMdd}, {yyMMdd}.
• Sequence Token: {SEQ:N} where N is the number of digits to pad (e.g. {SEQ:4} gives 0001).
• Custom Tokens: Any word like {COMPANY}, {BRANCH}, or {DEPT}. The library creates matching database columns automatically.

🧪 Testing in Unit Tests (Without a Database)

To run unit tests or develop offline without PostgreSQL, use the in-memory store:

services.AddInMemoryOrderSequenceGenerator(options =>
{
    options.Pattern = OrderPatterns.StandardRetail;
});

🗄️ How Database Storage Works

When AutoMigrate = true is enabled, the library automatically creates the table structure in PostgreSQL:

1. id: Primary key (BIGSERIAL PRIMARY KEY).
2. Scope Columns: Created automatically for each token in your pattern (for example: district, prefix, year, month, day).
3. sequence: Current counter value (BIGINT NOT NULL DEFAULT 0).
4. updated_at: Last updated timestamp (TIMESTAMP WITH TIME ZONE).
5. Unique Constraint: A composite unique constraint ensures each combination of scope values maintains its own independent sequence.

Concurrency Safety

All numbers are generated using an atomic query:

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 numbers and zero gaps, even under heavy concurrent load across multiple servers.

📄 License

This project is licensed under the MIT License.