uid-pool/dist/core/types.d.ts

High-performance UUID and unique ID pooling for Node.js. Pre-generate IDs in background worker threads for O(1) synchronous acquisition. Drop-in replacement for uuid.v4() and nanoid() with 10-100x better performance under load.

export interface IdPoolOptions {
    /**
     * Function that generates a single ID.
     * Can be sync or async (e.g., uuid.v4(), nanoid(), crypto.randomUUID()).
     *
     * **Note:** The generator function should return a string. If it returns a non-string
     * value, it will be converted to a string and an InvalidGeneratorOutputError event
     * will be emitted.
     *
     * @throws {InvalidGeneratorError} When generator is not a function
     */
    generator: () => string | Promise<string>;
    /**
     * Target number of identifiers to maintain in the pool (high water mark).
     * Must be a positive integer.
     *
     * @default 1000
     * @throws {InvalidPoolSizeError} When poolSize is not positive or not an integer
     */
    poolSize?: number;
    /**
     * Low water mark - triggers refill when available IDs drop below this.
     * Must be between 0 and poolSize (inclusive).
     *
     * @default poolSize * 0.25
     * @throws {InvalidMinSizeError} When minSize is negative or greater than poolSize
     */
    minSize?: number;
    /**
     * Number of IDs to generate in a single refill batch.
     * Must be a positive integer.
     *
     * @default poolSize * 0.5
     * @throws {InvalidRefillBatchSizeError} When refillBatchSize is not positive or not an integer
     */
    refillBatchSize?: number;
    /**
     * Use worker thread for ID generation (prevents blocking main thread).
     * Automatically disabled on Edge runtimes where worker threads are not available.
     *
     * @default true (where available)
     */
    useWorker?: boolean;
    /**
     * Behavior when pool is empty during synchronous acquire().
     * - `false`: return undefined when pool is empty
     * - `true`: throw PoolEmptyError when pool is empty
     *
     * **Note:** acquireAsync() will always wait for refill regardless of this setting.
     *
     * @default false
     * @throws {PoolEmptyError} When throwOnEmpty is true and pool is empty
     */
    throwOnEmpty?: boolean;
}
export interface PoolStats {
    /** Number of IDs currently available in the pool */
    available: number;
    /** Total pool capacity */
    capacity: number;
    /** Number of IDs acquired since start */
    totalAcquired: number;
    /** Number of refill operations performed */
    refillCount: number;
    /** Number of times acquire() was called on empty pool */
    emptyHits: number;
    /** Average time for refill operations (ms) */
    avgRefillTime: number;
}
export interface IdPoolEvents {
    /**
     * Emitted after refill completes successfully.
     * @param stats.added - Number of IDs added to the pool
     * @param stats.duration - Time taken for the refill operation in milliseconds
     */
    refill: (stats: {
        added: number;
        duration: number;
    }) => void;
    /** Emitted when acquire() called on empty pool (regardless of throwOnEmpty setting) */
    empty: () => void;
    /**
     * Emitted on errors during pool operations.
     *
     * **Common error types:**
     * - `GeneratorFailureError` - Generator function threw an error
     * - `InvalidGeneratorOutputError` - Generator returned non-string value
     * - `WorkerCrashError` - Worker thread crashed unexpectedly
     * - `WorkerGenerationError` - Worker failed to generate IDs
     * - `WorkerTimeoutError` - Worker didn't respond within timeout
     * - `SerializationError` - Failed to serialize generator for worker
     *
     * **Note:** Configuration errors (InvalidGeneratorError, InvalidPoolSizeError, etc.)
     * are thrown during construction and will not be emitted as events.
     */
    error: (error: Error) => void;
}
//# sourceMappingURL=types.d.ts.map