README.md

Folio Generator (JavaScript)

A robust and flexible JavaScript library to generate sequential alphanumeric codes (folios). It supports custom padding, separators, and collision handling.

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.
• Robust Validation: Ensures inputs match the expected format.

Installation

npm install folio-generator-js

Usage

Basic Usage

const { generateNextFolio } = require('folio-generator-js');

// Mock function to simulate database retrieval
const getLastFolio = async () => 'A00001';

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

Advanced Usage with Configuration

const { generateNextFolio } = require('folio-generator-js');

const getLastFolio = async () => 'A-0099';
const checkExistence = async (folio) => 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)

Generates the next available folio string.

Parameters:

• options (Object): Configuration options.
  • getLastFolio (Function): Required. A function that returns a Promise resolving to the last used folio string (or null if none exists).
  • checkExistence (Function): Optional. A function that takes a folio string and returns a Promise resolving to true if it exists, false otherwise. Used to prevent duplicates.
  • initialFolio (String): Optional. The starting folio if getLastFolio returns null. Default: 'A00001' (or based on padding/separator).
  • padding (Number): Optional. The number of digits for the numeric part. Default: 5.
  • separator (String): Optional. A character to separate letters and numbers. Default: '' (empty string).

Returns:

• Promise<string>: The next unique folio.

generateNextSequence(currentFolio, config)

Synchronously calculates the next folio in the sequence without checking for collisions.

Parameters:

• currentFolio (String|null): The current folio.
• config (Object):
  • padding (Number): Default 5.
  • separator (String): Default ''.

Returns:

• String: The next folio.

License

MIT