ui7/dist/esm/mod.d.ts

Generate sortable, timestamped UUID's, based on the new-uuid-format-04 RFC draft

/**
 * Generate a UUIDv7.
 *
 * ## Options
 *
 * To generate a UUID at a specific time, you can pass a `number` timestamp or
 * `Date` object to this function.
 *
 * You can also further customize UUID generation by providing
 * {@link Options an object} with your preferences:
 *
 * - `time`:    Generate with this time instead of the current system time. You can
 *              provide a `number` millisecond-precision UNIX timestamp (as `Date.now`
 *              returns), a Date object, or a function returning a `number` timestamp.
 * - `dashes`:  `true` to include `-` characters in the generated UUID string;
 *              `false` to omit them. (default: `true`)
 * - `upper`:   Capitalize the A-F characters in the UUID. (default: `false`)
 * - `version`: The value of the UUID `version` field (default: `7`)
 * - `entropy`: A {@link EntropySource function} to generate the random part of
 *              the UUID; or `0` or `0xFF` to set all "random" bits in the UUID
 *              uniformly. (default: uses `crypto.getRandomValues`)
 */
export declare const v7: Generator;
export default v7;
/**
 * Create a UUID generator. By default, uses a {@link monotonic} entropy source. Accepts the same options as the default generator.
 */
export declare const generator: (options?: GeneratorOptions) => Generator;
/**
 * Return the timestamp portion of the UUID (a millisecond-precision UNIX
 * timestamp, as returned by `Date.now`).
 *
 * Throws a {@link ParseError} if no timestamp can be extracted.
 */
export declare const timestamp: (uuid: string) => number;
/**
 * A regular expression that recognizes UUID's generated by this package.
 *
 * Capture group `1` is the timestamp portion, and `2` is the random portion
 * (including the 2-bit constant UUID variant field).
 */
export declare const pattern: RegExp;
/** The type of {@link v7 the UUID function} of this package. */
export interface Generator {
    /** Generate a UUIDv7 with default options. */
    (): string;
    /** Generate a UUIDv7 using the given time as its timestamp. */
    (time: Clock | Time | null | undefined): string;
    /** Generate a UUIDv7 using the given {@link Options options}. */
    (options: Options): string;
}
/**
 * A function that returns a millisecond-precision UNIX timestamp, like
 * `Date.now`.
 */
export declare type Clock = typeof Date['now'];
/** A `Date` object or millisecond-precision UNIX timestamp. */
export declare type Time = number | Date;
/** {@link v7 UUID generation} options. */
export interface Options extends EntropyOptions, FormatOptions {
    /**
     * Set the timestamp portion of the UUID to the given `Date`, UNIX timestamp
     * (as returned by `Date.now`), or the timestamp returned by the given
     * {@link Clock clock function}.
     */
    time?: Clock | Time;
}
/** Configures a UUID {@link generator}. */
export interface GeneratorOptions extends EntropyOptions, FormatOptions {
    /** Use a different timestamp source than `Date.now`. */
    time?: Clock;
}
/** Configures how the "random" fields of a generated UUID are populated. */
export interface EntropyOptions {
    /**
     * A {@link EntropySource function} to generate the random part of the UUID;
     * or `0` or `0xFF` to set all "random" bits in the UUID uniformly. (default:
     * uses `crypto.getRandomValues`)
     */
    entropy?: EntropySource | 0 | 0xff;
}
/** Configures how a generated UUID is formatted. */
export interface FormatOptions {
    /**
     * `true` to include dashes in the UUID; `false` to omit them.
     * (default: `true`)
     */
    dashes?: boolean;
    /** Capitalize the A-F characters in the UUID. (default: `false`) */
    upper?: boolean;
    /** Set the version field of the UUID. (default: `7`) */
    version?: 7 | 8;
}
/**
 * A source for the `rand` fields of a UUID. To implement monotonic or other
 * counter-based `rand` fields, the UUID's `timestamp` is provided.
 *
 * Must return a `Uint8Array` of `size` bytes.
 */
export declare type EntropySource = (size: number, timestamp: number) => Uint8Array;
/**
 * A buffered `EntropySource`. To reduce overhead, `bufferedRandom` calls the
 * underlying `getRandomValues` in chunks of `blockSize`, returning the
 * already-generated random bytes for future reads until the block is exhausted.
 */
export declare const bufferedRandom: (blockSize?: number) => EntropySource;
/**
 * Fill the UUID's `rand` fields with random bits, using
 * [`getRandomValues`][random]. UUID's produced with this randomness source are
 * not monotonic; ID's produced within the same millisecond will not necessarily
 * be sortable in the order they were produced.
 *
 * [random]: https://developer.mozilla.org/en-US/docs/Web/API/Crypto/getRandomValues
 */
export declare const random: EntropySource;
/**
 * Return an entropy source that allocates 12 bits as a monotonic counter at the
 * start of the UUIDv7 random fields.
 *
 * When a new timestamp is rolled over, the high bit of this field is set to
 * `0`. In the "unluckiest" case where the initial random counter value is
 * `0x7FF`, 2048 counter values are available within the same (millisecond)
 * timestamp value before exhaustion.
 *
 * **Note:** This package does not currently handle overflow of the counter
 * field; after `0xFFF`, the next value is `0x000`.
 */
export declare const monotonic: (entropy?: EntropySource) => EntropySource;
/** The exception thrown by {@link timestamp} if UUID parsing fails. */
export declare class ParseError extends Error {
    readonly name = "ParseError";
}