nehoid
Version:
NehoID is a high-performance TypeScript library designed for generating, validating, and managing unique identifiers in enterprise-grade applications.
577 lines • 21.6 kB
TypeScript
import { IdGeneratorOptions, CollisionStrategy, ContextOptions, SemanticOptions, BatchOptions, ValidationOptions, HealthScore, Stats, MigrationOptions, CompatibilityOptions } from "../types/index.js";
import { SpecializedGenerators } from "./specialized.js";
/**
* Central facade for all ID generation, validation, monitoring, and migration
* operations provided by the NehoID library.
*
* Every public method is **static** — no instantiation required. Internally the
* class delegates to specialised sub-modules ({@link Generator}, {@link Validators},
* {@link Monitor}, {@link Advanced}, etc.) and adds orchestration, option
* pre-processing, and monitoring instrumentation on top.
*
* ---
*
* ### Quick-start
*
* ```typescript
* import { NehoID } from 'nehoid';
*
* // ── Simple generation ──────────────────────────────────────────────────────
* const id = NehoID.generate(); // default settings
* const uuid = NehoID.generate({ format: 'uuid' }); // RFC 4122 UUID
* const nano = NehoID.nanoid(16); // NanoID, length 16
* const hex = NehoID.hex(32); // 32-char hex string
*
* // ── Collision-safe async generation ───────────────────────────────────────
* const safeId = await NehoID.safe({
* name: 'user-id',
* maxAttempts: 10,
* backoffType: 'exponential',
* checkFunction: async (candidate) => !(await db.exists(candidate)),
* });
*
* // ── Bulk generation ────────────────────────────────────────────────────────
* const ids = NehoID.batch({ count: 500, format: 'uuid', ensureUnique: true });
*
* // ── Validation ─────────────────────────────────────────────────────────────
* const ok = NehoID.validate(id);
* const health = NehoID.healthCheck(id);
*
* // ── Monitoring ─────────────────────────────────────────────────────────────
* NehoID.startMonitoring();
* const stats = NehoID.getStats();
* NehoID.stopMonitoring();
* ```
*/
export declare class NehoID {
private constructor();
/**
* Replaces pattern placeholders with random characters.
*
* Recognised placeholders:
* - `X` / `A` → random uppercase letter (A–Z)
* - `a` → random lowercase letter (a–z)
* - `9` → random digit (0–9)
*
* All other characters are kept verbatim.
*
* @param pattern - Template string (e.g. `'XXX-999'`).
* @returns Resolved pattern string (e.g. `'BKT-472'`).
*/
private static generateFromPattern;
/**
* Derives an alphabet string from a {@link IdGeneratorOptions.charset} descriptor.
*
* @param charset - Charset descriptor from caller options.
* @returns Combined alphabet string, or `undefined` if the descriptor is empty.
*/
private static buildAlphabetFromCharset;
/**
* Applies format-specific defaults for preset format shortcuts.
*
* Mutates `processedOptions` in place and may return early with a fully
* formed ID for formats that have their own dedicated generators.
*
* @param format - The requested preset format.
* @param originalOptions - The raw caller options (read-only).
* @param processedOptions - Options object being built for the core generator.
* @returns An early-exit ID string for `'uuid'` and `'nanoid'`, or `undefined`.
*/
private static applyFormatPreset;
/**
* Applies a case transformation to an ID string.
*
* @param id - The raw ID string.
* @param caseMode - Desired case transformation.
* @returns Transformed string.
*/
private static applyCase;
/**
* Generates a unique ID with optional configuration.
*
* This is the primary entry point for ID generation. It supports preset format
* shortcuts, fine-grained character control, case transformations, expiration
* timestamps, versioning, domains, sequential numbering, pattern templates,
* metadata embedding, and checksum appending — all composable in a single call.
*
* > **Performance note**: For bulk generation prefer {@link NehoID.batch}, which
* > avoids per-call monitoring overhead and can run in parallel.
*
* @param options - Generation options. All properties are optional.
* @returns A newly generated unique ID string.
*
* @throws {RangeError} If `options.size` is defined and less than 1.
* @throws {TypeError} If `options.sequential.padLength` is negative.
*
* @example Preset formats
* ```typescript
* NehoID.generate({ format: 'uuid' }); // "550e8400-e29b-41d4-a716-446655440000"
* NehoID.generate({ format: 'nanoid' }); // "V1StGXR8_Z5jdHi6B-myT"
* NehoID.generate({ format: 'ksuid' }); // "0ujzPyRiIAffKhBux4PvQdDqMHY"
* ```
*
* @example Custom size, segments & separator
* ```typescript
* NehoID.generate({ size: 4, segments: 3, separator: '.' });
* // "aB3x.K9mZ.tR8q"
* ```
*
* @example Prefix, case & charset control
* ```typescript
* NehoID.generate({
* prefix: 'USR',
* case: 'lower',
* charset: { numbers: true, uppercase: false }
* });
* // "usr_3f2a9c1b"
* ```
*
* @example Pattern template
* ```typescript
* NehoID.generate({ pattern: 'AA-9999' }); // "CA-1834"
* NehoID.generate({ pattern: 'XXX-XXX' }); // "BKT-ZMP"
* ```
*
* @example Compression & Encoding
* ```typescript
* NehoID.generate({
* encoding: 'base64',
* compression: 'lz77'
* });
* ```
*
* @example Expiring security token
* ```typescript
* NehoID.generate({
* size: 32,
* randomness: 'crypto',
* expiresIn: 15 * 60 * 1000, // 15 minutes
* domain: 'auth',
* includeChecksum: true,
* });
* ```
*
* @example Sequential order IDs
* ```typescript
* NehoID.generate({
* sequential: { context: 'orders', start: 1000, padLength: 6 },
* });
* // "orders001000"
* ```
*
* @example Embedded metadata
* ```typescript
* NehoID.generate({
* metadata: { env: 'prod', source: 'api-v3' },
* includeTimestamp: true,
* });
* ```
*/
static generate(options?: Partial<IdGeneratorOptions>): string;
/**
* Generates a collision-safe ID by validating each candidate against an
* external uniqueness predicate before returning it.
*
* The method retries up to {@link CollisionStrategy.maxAttempts} times with
* the configured back-off strategy. If all attempts fail, it throws an error
* and increments the collision counter in {@link Monitor}.
*
* @param options - Collision strategy including the async uniqueness check.
* @returns A promise that resolves to a guaranteed-unique ID string.
* @throws {Error} When `maxAttempts` is exhausted without finding a unique ID.
*
* @example Database uniqueness check
* ```typescript
* const id = await NehoID.safe({
* name: 'order-id-check',
* maxAttempts: 10,
* backoffType: 'exponential',
* checkFunction: async (candidate) => {
* return !(await db.orders.exists({ id: candidate }));
* },
* });
* ```
*
* @example Redis cache token
* ```typescript
* const token = await NehoID.safe({
* name: 'session-token',
* maxAttempts: 5,
* backoffType: 'linear',
* checkFunction: async (t) => !(await redis.exists(`sess:${t}`)),
* });
* ```
*/
static safe(options: CollisionStrategy): Promise<string>;
/**
* Generates a RFC 4122 v4 UUID.
*
* @returns A hyphen-separated UUID string (36 characters).
*
* @example
* ```typescript
* NehoID.uuid(); // "550e8400-e29b-41d4-a716-446655440000"
* ```
*/
static uuid(): string;
/**
* Generates a NanoID using URL-safe characters.
*
* NanoIDs are compact, URL-safe, and statistically collision-resistant.
* The default length of 21 chars provides ~126 bits of entropy.
*
* @param length - Character length of the output. @default 21
* @returns A NanoID string.
*
* @example
* ```typescript
* NehoID.nanoid(); // "V1StGXR8_Z5jdHi6B-myT" (21 chars)
* NehoID.nanoid(10); // "IRFa-VaY2b" (10 chars)
* ```
*/
static nanoid(length?: number): string;
/**
* Generates a short, compact alphanumeric ID.
*
* Useful for human-readable references (order numbers, share codes, etc.)
* where brevity matters more than maximum entropy.
*
* @param length - Character length of the output. @default 8
* @returns A short alphanumeric string.
*
* @example
* ```typescript
* NehoID.short(); // "aB3xK9mZ" (8 chars)
* NehoID.short(12); // "aB3xK9mZtR8q"
* ```
*/
static short(length?: number): string;
/**
* Generates a random hexadecimal string.
*
* @param length - Character length of the output. @default 16
* @returns A lowercase hexadecimal string.
*
* @example
* ```typescript
* NehoID.hex(); // "3f2a9c1b4e7d8f0a" (16 chars)
* NehoID.hex(32); // "3f2a9c1b4e7d8f0a1c3e5b7d9f2a4c6e"
* ```
*/
static hex(length?: number): string;
/**
* Generates a hierarchical ID encoding a parent-child relationship.
*
* Hierarchical IDs preserve the ancestry chain in the identifier itself,
* enabling efficient tree traversal without additional database joins.
*
* @param options - Hierarchical generation options.
* @returns A hierarchical ID string with encoded relationship segments.
*
* @example
* ```typescript
* const child = NehoID.hierarchical({ parentId: 'root-abc123', depth: 2 });
* // "root-abc123.L2.xK9m"
* ```
*/
static hierarchical(options?: Record<string, unknown>): string;
/**
* Generates a time-ordered ID suitable for chronological sorting.
*
* Temporal IDs embed a timestamp prefix so that lexicographic order matches
* insertion order — ideal for event logs, message queues, and time-series data.
*
* @param options - Temporal generation options (precision, random suffix, etc.).
* @returns A temporal ID string with an embedded timestamp prefix.
*
* @example
* ```typescript
* const id = NehoID.temporal({ precision: 'milliseconds', suffix: true });
* // "01HX3KBPM4-aB3x"
* ```
*/
static temporal(...options: Parameters<typeof SpecializedGenerators.temporal>): string;
/**
* Converts a Unix timestamp (milliseconds) into a temporal ID.
*
* Allows back-dated or future-dated IDs to be generated from arbitrary
* epoch values without going through the standard clock.
*
* @param timestamp - Unix epoch in milliseconds.
* @returns A temporal ID string derived from the given timestamp.
* @throws {RangeError} If `timestamp` is negative.
*
* @example
* ```typescript
* NehoID.fromTemporal(Date.now()); // current-time temporal ID
* NehoID.fromTemporal(new Date('2020-01-01').getTime()); // back-dated ID
* ```
*/
static fromTemporal(timestamp: number, options?: Parameters<typeof SpecializedGenerators.fromTemporal>[1]): string;
/**
* Extracts the original Unix timestamp (milliseconds) from a temporal ID.
*
* @param temporalId - A temporal ID previously generated by {@link NehoID.temporal}
* or {@link NehoID.fromTemporal}.
* @returns The Unix epoch in milliseconds encoded in the ID.
* @throws {TypeError} If the provided string is not a valid temporal ID.
*
* @example
* ```typescript
* const id = NehoID.temporal();
* const ts = NehoID.fromTemporalToTimestamp(id); // e.g. 1710000000000
* new Date(ts); // Date object
* ```
*/
static fromTemporalToTimestamp(temporalId: string, options?: Parameters<typeof SpecializedGenerators.fromTemporalToTimestamp>[1]): number;
/**
* Generates a sequential ID suitable for replacing database auto-increment columns.
*
* Unlike pure auto-increment, sequential IDs can include a prefix and optional
* padding, making them human-readable and namespace-safe across distributed systems.
*
* @param options - Sequential generation parameters.
* @returns A formatted sequential ID string.
* @throws {RangeError} If `options.counter` is negative.
*
* @example
* ```typescript
* NehoID.sequential({ prefix: 'ORD', counter: 1001, padLength: 6 });
* // "ORD001001"
*
* NehoID.sequential({ prefix: 'INV', counter: 42, padLength: 4 });
* // "INV0042"
* ```
*/
static sequential(options: {
prefix?: string;
counter: number;
padLength?: number;
suffix?: boolean;
}): string;
/**
* Generates multiple IDs in a single operation.
*
* More efficient than calling {@link NehoID.generate} in a loop because the
* generator can amortise initialisation cost and optionally parallelise work.
*
* @param options - Batch configuration (count, format, uniqueness, parallelism).
* @returns An array of generated ID strings of length `options.count`.
* @throws {RangeError} If `options.count` is less than 1.
*
* @example Standard batch
* ```typescript
* const ids = NehoID.batch({ count: 100, format: 'uuid', ensureUnique: true });
* ids.length; // 100
* ```
*
* @example High-throughput parallel batch
* ```typescript
* const ids = NehoID.batch({ count: 10_000, format: 'nano', parallel: true });
* ```
*/
static batch(options: BatchOptions): string[];
/**
* Validates a single ID against the configured rules and format constraints.
*
* @param id - The ID string to validate.
* @param options - Optional validation flags (format check, collision check, repair).
* @returns `true` if the ID passes all enabled checks, `false` otherwise.
*
* @example
* ```typescript
* NehoID.validate('usr_aB3xK9mZ'); // true
* NehoID.validate('usr_aB3xK9mZ', { checkFormat: true }); // true
* NehoID.validate('!!!invalid'); // false
* ```
*/
static validate(id: string, options?: ValidationOptions): boolean;
/**
* Validates multiple IDs in a single pass and provides a detailed report.
*
* Results include categorized lists of valid, invalid, and duplicate IDs.
*
* @param ids - Array of ID strings to validate.
* @param options - Optional validation flags applied uniformly to all IDs.
* @returns An object containing arrays of `valid`, `invalid`, and `duplicates` IDs.
*
* @example
* ```typescript
* const report = NehoID.validateBatch(['id1', 'id2', '!!!', 'id1']);
* // {
* // valid: ['id1', 'id2'],
* // invalid: ['!!!'],
* // duplicates: ['id1']
* // }
* ```
*/
static validateBatch(ids: string[], options?: ValidationOptions): {
valid: string[];
invalid: string[];
duplicates: string[];
};
/**
* Performs a comprehensive quality analysis of an ID.
*
* Examines entropy, character distribution, predictability, and structural
* patterns, then returns an actionable {@link HealthScore} report.
*
* @param id - The ID string to analyse.
* @returns A {@link HealthScore} object with a normalised score and recommendations.
*
* @example
* ```typescript
* const health = NehoID.healthCheck('usr_aB3xK9mZ');
* // {
* // score: 0.91,
* // entropy: 'high',
* // predictability: 'low',
* // recommendations: [],
* // }
*
* if (health.score < 0.7) {
* console.warn('Low quality ID:', health.recommendations);
* }
* ```
*/
static healthCheck(id: string): HealthScore;
/**
* Starts collecting generation performance metrics.
*
* Must be called before {@link NehoID.getStats}. Has no effect if monitoring
* is already active.
*
* @example
* ```typescript
* NehoID.startMonitoring();
* for (let i = 0; i < 10_000; i++) NehoID.generate();
* const stats = NehoID.getStats();
* console.log(stats.averageGenerationTime); // e.g. "0.041 ms"
* ```
*/
static startMonitoring(): void;
/**
* Stops metric collection and freezes the current statistics snapshot.
*
* Subsequent calls to {@link NehoID.getStats} return the frozen values until
* monitoring is restarted.
*
* @example
* ```typescript
* NehoID.stopMonitoring();
* const finalStats = NehoID.getStats();
* ```
*/
static stopMonitoring(): void;
/**
* Returns the current (or last frozen) generation statistics.
*
* @returns A {@link Stats} snapshot.
*
* @example
* ```typescript
* const { generated, collisions, averageGenerationTime } = NehoID.getStats();
* console.log(`${generated} IDs generated, ${collisions} collisions.`);
* ```
*/
static getStats(): Stats;
/**
* Generates an ID that embeds a fingerprint of the current runtime environment.
*
* Useful for analytics, anomaly detection, and fraud prevention — each enabled
* flag adds a hashed context segment to the ID.
*
* > ⚠️ **Privacy**: `includeDevice` and `includeLocation` may collect PII.
* > Ensure user consent and legal compliance before enabling these flags.
*
* @param options - Context flags controlling which environment data is captured.
* @returns A contextual ID string containing hashed environment segments.
*
* @example
* ```typescript
* const id = NehoID.contextual({
* includeDevice: true,
* includeTimezone: true,
* userBehavior: 'checkout',
* });
* ```
*/
static contextual(options: ContextOptions): string;
/**
* Generates a human-readable semantic ID with meaningful business segments.
*
* Semantic IDs self-document their origin (region, department, year) while
* remaining unique via an appended random suffix.
*
* @param options - Semantic segments to embed in the ID.
* @returns A structured semantic ID string.
*
* @example
* ```typescript
* NehoID.semantic({
* prefix: 'ORD',
* region: 'EU-WEST',
* department: 'SALES',
* year: 2025,
* customSegments: { channel: 'web' },
* });
* // "ORD-EU-WEST-SALES-2025-web-x7k2"
* ```
*/
static semantic(options: SemanticOptions): string;
/**
* Bulk-migrates IDs from one format to another while preserving referential integrity.
*
* Processes IDs in configurable batches to limit memory pressure. The resulting
* array maintains the same order as the input when `preserveOrder` is `true`.
*
* @param options - Migration configuration (source/target format, batch size, IDs).
* @returns A promise that resolves to an array of migrated ID strings.
* @throws {Error} If the source format is unrecognised or migration fails.
*
* @example Migrate explicit list of UUIDs
* ```typescript
* const newIds = await NehoID.migrate({
* from: 'uuid',
* to: 'nehoid',
* preserveOrder: true,
* batchSize: 500,
* ids: legacyUuids,
* });
* ```
*
* @example Migrate N records from a configured source store
* ```typescript
* const newIds = await NehoID.migrate({
* from: 'legacy-numeric',
* to: 'ksuid',
* count: 10_000,
* batchSize: 100,
* });
* ```
*/
static migrate(options: MigrationOptions): Promise<string[]>;
/**
* Generates an ID that satisfies the constraints of all specified target platforms.
*
* The generator applies the most restrictive character set and length limit
* across all listed platforms, ensuring the output is usable without transformation
* on every target.
*
* @param options - Target platforms, required format, and exact length.
* @returns A cross-platform compatible ID string.
* @throws {RangeError} If `options.length` is less than 1.
*
* @example
* ```typescript
* NehoID.compatible({
* platform: ['javascript', 'python', 'go'],
* format: 'alphanumeric',
* length: 16,
* });
* // "aB3xK9mZtR8qV2nP"
* ```
*/
static compatible(options: CompatibilityOptions): string;
}
//# sourceMappingURL=nehoid.d.ts.map