OrderSequenceGenerator 1.0.0

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!

🚀 Quick Start (Zero Manual Setup)

1. Register in Program.cs

using OrderSequenceGenerator;
using OrderSequenceGenerator.Extensions;

var builder = WebApplication.CreateBuilder(args);

// Zero manual SQL setup! Table & columns matching the pattern are created automatically.
builder.Services.AddOrderSequenceGenerator(options =>
{
    options.ConnectionString = builder.Configuration.GetConnectionString("DefaultConnection")!;
    
    // Choose from 17 built-in presets:
    options.Pattern = OrderPatterns.ESebaCompact; // "{DISTRICT}{yyyy}{PREFIX}{MM}{dd}{SEQ:4}"
    // Or specify any custom pattern:
    // options.Pattern = "{BRANCH}-{STORE}-{yyyyMMdd}-{SEQ:5}";

    options.TableName = "order_sequence"; // default table
    options.AutoMigrate = true;           // auto-creates columns matching pattern tokens!
});

2. Generate Sequence in Your Controller or Service

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)
    {
        // Date tokens (yyyy, MM, dd) are automatically filled from UTC now!
        string orderNo = await _generator.NextAsync(new
        {
            District = request.District, // "MN051"
            Prefix = "E"
        });

        // Returns: "MN0512026E09090001"
        return Ok(new { OrderNumber = orderNo });
    }
}

🛠️ Interactive Terminal Walkthrough

When you add this package to your project, walkthrough.ps1 is automatically delivered to your project root.

Run:

.\walkthrough.ps1

This interactive assistant allows you to:

1. Preview all 17 pattern styles and sample outputs.
2. Test database connection against PostgreSQL.
3. Automatically execute the exact table DDL.
4. Test atomic increments directly in your terminal.

📋 Pattern Presets Reference

📦 Database Structure

Created automatically by AutoMigrate = true:

• id BIGSERIAL PRIMARY KEY
• Dynamically generated columns for every custom token in pattern (e.g. district VARCHAR(50), prefix VARCHAR(50), year INT, month INT, day INT)
• sequence BIGINT NOT NULL DEFAULT 0
• updated_at TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
• CONSTRAINT UQ_<tableName>_scope UNIQUE (<token_columns>)