@mbc-cqrs-serverless/sequence

@mbc-cqrs-serverless/sequence

Robust sequence number generation for the MBC CQRS Serverless framework. Generate unique, formatted sequence numbers with automatic rotation support for invoices, orders, tickets, and more.

Features

• Atomic Counter: DynamoDB-based atomic operations ensure no duplicates
• Flexible Rotation: Reset sequences by fiscal year, year, month, or day
• Custom Formatting: Configure prefixes, padding, and format patterns
• Multi-tenant: Isolated sequences per tenant
• Hierarchical Codes: Support up to 5 levels of code hierarchy

Installation

npm install @mbc-cqrs-serverless/sequence

Quick Start

1. Register the Module

import { Module } from '@nestjs/common';
import { SequencesModule } from '@mbc-cqrs-serverless/sequence';

@Module({
  imports: [
    SequencesModule.register({
      enableController: true, // Optional: enable REST endpoints
    }),
  ],
})
export class AppModule {}

2. Generate Sequence Numbers

import { Injectable } from '@nestjs/common';
import { SequencesService, RotateByEnum } from '@mbc-cqrs-serverless/sequence';
import { getUserContext, IInvoke } from '@mbc-cqrs-serverless/core';

@Injectable()
export class InvoiceService {
  constructor(private readonly sequencesService: SequencesService) {}

  async createInvoice(opts: { invokeContext: IInvoke }) {
    const { tenantCode } = getUserContext(opts.invokeContext);

    const seq = await this.sequencesService.generateSequenceItem(
      {
        tenantCode,
        typeCode: 'INVOICE',
        rotateBy: RotateByEnum.FISCAL_YEARLY,
      },
      opts,
    );

    console.log(seq.no);          // 1
    console.log(seq.formattedNo); // "INV-0001" (based on master data format)
    console.log(seq.issuedAt);    // Date object

    return seq;
  }
}

API Reference

SequencesService

Method	Description
generateSequenceItem(dto, options)	Generate sequence using master data configuration
generateSequenceItemWithProvideSetting(dto, options)	Generate sequence with inline settings

GenerateFormattedSequenceDto

Property	Type	Required	Description
tenantCode	string	Yes	Tenant identifier
typeCode	string	Yes	Sequence type (e.g., 'INVOICE', 'ORDER')
rotateBy	RotateByEnum	No	Rotation strategy
date	Date	No	Date for sequence (default: now)
prefix	string	No	Prefix to add before formatted number
postfix	string	No	Postfix to add after formatted number
params	object	No	Additional parameters (code1-code5)

RotateByEnum

Value	Description	Example Reset
FISCAL_YEARLY	Reset on fiscal year start (April 1st in Japan)	Apr 1, 2024
YEARLY	Reset on calendar year	Jan 1, 2024
MONTHLY	Reset each month	First of each month
DAILY	Reset each day	Every day
NONE	Never reset, continuous increment	Never

SequenceEntity (Return Type)

{
  id: string;        // Unique identifier
  no: number;        // Raw sequence number
  formattedNo: string; // Formatted sequence string
  issuedAt: Date;    // Timestamp of generation
}

Usage Examples

Fiscal Year Rotation (Japan)

Sequences reset on April 1st:

const seq = await this.sequencesService.generateSequenceItem(
  {
    tenantCode: 'MBC',
    typeCode: 'INVOICE',
    rotateBy: RotateByEnum.FISCAL_YEARLY,
  },
  opts,
);
// FY2024: INV-0001, INV-0002, ...
// FY2025 (after Apr 1): INV-0001, INV-0002, ...

Monthly Rotation

Sequences reset on the first of each month:

const seq = await this.sequencesService.generateSequenceItem(
  {
    tenantCode: 'MBC',
    typeCode: 'ORDER',
    rotateBy: RotateByEnum.MONTHLY,
  },
  opts,
);
// January: ORD-202401-0001, ORD-202401-0002
// February: ORD-202402-0001, ORD-202402-0002

Daily Rotation

Sequences reset every day:

const seq = await this.sequencesService.generateSequenceItem(
  {
    tenantCode: 'MBC',
    typeCode: 'TICKET',
    rotateBy: RotateByEnum.DAILY,
  },
  opts,
);
// Day 1: TKT-20240115-001, TKT-20240115-002
// Day 2: TKT-20240116-001, TKT-20240116-002

Hierarchical Sequences

Use code1-code5 for hierarchical sequence numbers:

const seq = await this.sequencesService.generateSequenceItem(
  {
    tenantCode: 'MBC',
    typeCode: 'PRODUCT',
    params: {
      code1: 'ELECTRONICS',
      code2: 'PHONES',
    },
    rotateBy: RotateByEnum.YEARLY,
  },
  opts,
);
// Each category has its own sequence: ELECTRONICS-PHONES-0001

Custom Settings (No Master Data)

Provide format settings directly without master data lookup:

const seq = await this.sequencesService.generateSequenceItemWithProvideSetting(
  {
    tenantCode: 'MBC',
    typeCode: 'CUSTOM',
    format: '%%year%%-%%month#:0>2%%-%%no#:0>4%%',
    rotateBy: RotateByEnum.MONTHLY,
    prefix: 'DOC-',
  },
  opts,
);
// Result: DOC-2024-01-0001

Format Patterns

Format strings use %%key%% syntax with optional padding:

Pattern	Output	Description
%%no%%	1	Raw number
%%no#:0>4%%	0001	Zero-padded to 4 digits
%%year%%	2024	Current year
%%month%%	1	Current month (1-12)
%%month#:0>2%%	01	Zero-padded month
%%day%%	15	Current day
%%fiscal_year%%	71	Fiscal year number
%%code1%%	DEPT	Hierarchical code 1

Master Data Configuration

The generateSequenceItem method reads format configuration from master data:

{
  "pk": "MASTER#MBC",
  "sk": "MASTER_DATA#INVOICE",
  "format": "%%year%%-%%no#:0>4%%",
  "startMonth": 4,
  "registerDate": "2024-04-01"
}

Concurrent Access Safety

All sequence operations use DynamoDB atomic counters, ensuring thread-safe generation:

// Safe for concurrent requests
const results = await Promise.all([
  sequencesService.generateSequenceItem({ tenantCode, typeCode: 'ORDER' }, opts),
  sequencesService.generateSequenceItem({ tenantCode, typeCode: 'ORDER' }, opts),
  sequencesService.generateSequenceItem({ tenantCode, typeCode: 'ORDER' }, opts),
]);
// Results: [{ no: 1 }, { no: 2 }, { no: 3 }] - guaranteed unique

Related Packages

Package	Description
@mbc-cqrs-serverless/core	Core CQRS framework
@mbc-cqrs-serverless/master	Master data for sequence formats

Documentation

Full documentation available at https://mbc-cqrs-serverless.mbc-net.com/

• Sequence Service Guide
• Build a Todo App Tutorial

License

Copyright 2024-2025, Murakami Business Consulting, Inc. https://www.mbc-net.com/

This project is under the MIT License.