Folio Generator (TypeScript)

A robust and flexible TypeScript library to generate sequential alphanumeric codes (folios). It supports custom padding, separators, and collision handling, with full type safety.

Features

• Sequential Generation: Automatically increments numbers and letters (e.g., A00001 -> A00002, A99999 -> B00001).
• Customizable Format: Configure padding length and separators (e.g., A-001).
• Collision Handling: Automatically checks for existing folios and skips them to ensure uniqueness.
• Type Safe: Written in TypeScript with complete type definitions.

Installation

npm install folio-generator-ts

Usage

Basic Usage

import { generateNextFolio } from 'folio-generator-ts';

// Mock function to simulate database retrieval
const getLastFolio = async (): Promise<string | null> => 'A00001';

(async () => {
	const nextFolio = await generateNextFolio({ getLastFolio });
	console.log(nextFolio); // Output: A00002
})();

Advanced Usage with Configuration

import { generateNextFolio } from 'folio-generator-ts';

const getLastFolio = async (): Promise<string | null> => 'A-0099';
const checkExistence = async (folio: string): Promise<boolean> => folio === 'A-0100'; // Simulate collision

(async () => {
	const nextFolio = await generateNextFolio({
		getLastFolio,
		checkExistence,
		padding: 4,
		separator: '-',
	});
	console.log(nextFolio); // Output: A-0101 (skips A-0100 due to collision)
})();

API Reference

generateNextFolio(options: FolioOptions): Promise<string>

Generates the next available folio string.

FolioOptions Interface:

• getLastFolio: () => Promise<string | null> (Required) - Returns the last used folio.
• checkExistence: (folio: string) => Promise<boolean> (Optional) - Checks if a folio exists.
• initialFolio: string (Optional) - Starting folio. Default: 'A00001'.
• padding: number (Optional) - Number of digits. Default: 5.
• separator: string (Optional) - Separator character. Default: ''.

generateNextSequence(currentFolio: string | null, config?: SequenceConfig): string

Synchronously calculates the next folio in the sequence.

SequenceConfig Interface:

• padding: number (Optional) - Default 5.
• separator: string (Optional) - Default ''.

License

MIT

Development

Build:

npm run build

Run tests:

npm test