@pokedotdev/snowflake/dist/index.d.ts

High-performance TypeScript library for generating unique, sortable Snowflake IDs

//#region src/types.d.ts
/**
 * Bit allocation configuration for Snowflake ID components
 */
interface BitAllocation {
	/** Number of bits for worker ID */
	workerId: number;
	/** Number of bits for process ID */
	processId: number;
	/** Number of bits for sequence */
	sequence: number;
}
/**
 * Configuration interface for Snowflake ID generation
 */
interface SnowflakeConfig {
	/** Custom epoch timestamp in milliseconds (default: 20202020-01-01) */
	epoch?: number;
	/** Worker ID for this instance */
	workerId: number;
	/** Process ID for this instance (default: 0) */
	processId?: number;
	/** Bit allocation configuration (default: { workerId: 10, processId: 0, sequence: 12 }) */
	bits?: BitAllocation;
}
/**
 * Components of a decomposed Snowflake ID
 */
interface SnowflakeComponents {
	/** Timestamp in milliseconds since epoch */
	timestamp: number;
	/** Worker ID */
	workerId: number;
	/** Process ID */
	processId: number;
	/** Sequence number */
	sequence: number;
}
/**
 * Internal configuration with all defaults applied
 */
//#endregion
//#region src/snowflake.d.ts
/**
 * Snowflake ID generator
 *
 * Generates unique 64-bit IDs consisting of:
 * - 1 bit: unused (always 0)
 * - 41 bits: timestamp (milliseconds since custom epoch)
 * - configurable bits: worker ID + process ID + sequence
 *
 * @example
 * ```typescript
 * const generator = new SnowflakeGenerator({
 *   workerId: 1,
 *   bits: { workerId: 10, processId: 0, sequence: 12 }
 * });
 * const id = generator.generate();
 * console.log(id); // 1234567890123456789n
 * ```
 */
declare class SnowflakeGenerator {
	private readonly config;
	private readonly maxWorker;
	private readonly maxProcess;
	private readonly maxSequence;
	private readonly workerShift;
	private readonly processShift;
	private readonly timestampShift;
	private readonly maxTimestamp;
	private sequence;
	private lastTimestamp;
	/**
	 * Default epoch: January 1, 2020 00:00:00 UTC (more reasonable for current dates)
	 */
	private static readonly DEFAULT_EPOCH;
	/**
	 * Default bit allocation: 10 bits worker, 0 bits process, 12 bits sequence
	 */
	private static readonly DEFAULT_BITS;
	constructor(config: SnowflakeConfig);
	/**
	 * Resolve configuration with defaults
	 */
	private resolveConfig;
	/**
	 * Validate configuration parameters
	 */
	private validateConfig;
	/**
	 * Generate a new unique Snowflake ID
	 *
	 * @returns A unique ID as a bigint
	 * @throws {ClockBackwardsError} When system clock goes backwards
	 * @throws {TimestampExhaustedError} When maximum timestamp is reached
	 *
	 * @example
	 * ```typescript
	 * const id = generator.generate();
	 * console.log(id); // 1234567890123456789n
	 * ```
	 */
	generate(): bigint;
	/**
	 * Compose an ID from its components
	 *
	 * @param timestamp Timestamp in milliseconds since epoch
	 * @param workerId Worker ID
	 * @param processId Process ID
	 * @param sequence Sequence number
	 * @returns Composed ID as a bigint
	 * @throws {ConfigurationError} When components exceed their bit limits
	 *
	 * @example
	 * ```typescript
	 * const id = generator.compose(1640995200000, 1, 0, 42);
	 * console.log(id); // 1234567890123456789n
	 * ```
	 */
	compose(timestamp: number, workerId: number, processId: number, sequence: number): bigint;
	/**
	 * Decompose an ID back to its components
	 *
	 * @param id The ID to decompose
	 * @returns The components of the ID
	 * @throws {InvalidIdError} When the ID format is invalid
	 *
	 * @example
	 * ```typescript
	 * const components = generator.decompose(1234567890123456789n);
	 * console.log(components);
	 * // {
	 * //   timestamp: 1640995200000,
	 * //   workerId: 1,
	 * //   processId: 0,
	 * //   sequence: 42
	 * // }
	 * ```
	 */
	decompose(id: bigint): SnowflakeComponents;
	/**
	 * Get current timestamp relative to epoch
	 */
	private getCurrentTimestamp;
	/**
	 * Wait for the next millisecond
	 */
	private waitForNextMillisecond;
	/**
	 * Compose ID from components using bit operations
	 */
	private composeId;
}
//#endregion
//#region src/errors.d.ts
/**
 * Base error class for all Snowflake-related errors
 */
declare class SnowflakeError extends Error {
	constructor(message: string);
}
/**
 * Error thrown when the configuration is invalid
 */
declare class ConfigurationError extends SnowflakeError {
	constructor(message: string);
}
/**
 * Error thrown when the clock goes backwards
 */
declare class ClockBackwardsError extends SnowflakeError {
	constructor(message: string);
}
/**
 * Error thrown when maximum timestamp is reached
 */
declare class TimestampExhaustedError extends SnowflakeError {
	constructor(message: string);
}
/**
 * Error thrown when trying to decompose an invalid ID
 */
declare class InvalidIdError extends SnowflakeError {
	constructor(message: string);
}
//#endregion
export {
	type BitAllocation,
	ClockBackwardsError,
	ConfigurationError,
	InvalidIdError,
	type SnowflakeComponents,
	type SnowflakeConfig,
	SnowflakeError,
	SnowflakeGenerator,
	TimestampExhaustedError,
};