xid-ts/dist/cjs/index.d.ts

xid is a globally unique id generator thought for the web. A Typescript port of https://github.com/rs/xid.

/**
 * XidState holds the state required for generating new XIDs.
 */
export interface XidState {
    /**
     * A 3-byte machine identifier.
     */
    machineId: Uint8Array;
    /**
     * A 2-byte process identifier.
     */
    pid: number;
    /**
     * A 3-byte counter, initialized to a random value.
     */
    counter: number;
}
/**
 * Creates a new XidState.
 * @returns A new XidState.
 */
export declare function newState(): XidState;
/**
 * Xid is a globally unique sortable ID.
 * It is a Typescript port of https://github.com/rs/xid.
 * The binary representation is compatible with the Mongo DB 12-byte ObjectId.
 * The value consists of:
 * - a 4-byte timestamp value in seconds since the Unix epoch
 * - a 3-byte value based on the machine identifier
 * - a 2-byte value based on the process id
 * - a 3-byte incrementing counter, initialized to a random value
 *
 * The string representation is 20 bytes, using a base32 hex variant with characters `[0-9a-v]`
 * to retain the sortable property of the id.
 */
export declare class Xid extends Uint8Array {
    /**
     * Creates a new Xid.
     * If `id` is not provided, a new ID is generated.
     * @param id - An optional 12-byte Uint8Array to use as the ID.
     * @param state - The optional state to use for generating a new ID. In most cases, the default state is sufficient.
     * But for Cloudflare Workers, you may want to create and manage your own state using `newState()` and hold it with DurableObject.
     */
    constructor(id?: Uint8Array, state?: XidState);
    /**
     * Returns a zero (nil) Xid.
     * A zero Xid is not valid.
     * @returns A zero Xid.
     */
    static default(): Xid;
    /**
     * Creates an Xid from a value.
     * The value can be an Xid, a string, an ArrayBuffer, a Uint8Array, or an array of numbers.
     * @param v - The value to create the Xid from.
     * @returns A new Xid.
     * @throws If the value is invalid.
     */
    static fromValue(v: Xid | string | ArrayBuffer | Uint8Array | number[]): Xid;
    /**
     * Parses a string representation of an Xid.
     * @param id - The 20-byte string representation of the Xid.
     * @returns A new Xid.
     * @throws If the string is not a valid Xid.
     */
    static parse(id: string): Xid;
    private decode;
    /**
     * Encodes the Xid into a 20-byte string representation.
     * @returns The string representation of the Xid.
     */
    encode(): string;
    /**
     * Returns the timestamp part of the Xid.
     * @returns The timestamp in seconds since the Unix epoch.
     */
    timestamp(): number;
    /**
     * Returns the machine identifier part of the Xid.
     * @returns A 3-byte Uint8Array representing the machine identifier.
     */
    machine(): Uint8Array;
    /**
     * Returns the process identifier part of the Xid.
     * @returns The 2-byte process identifier.
     */
    pid(): number;
    /**
     * Returns the counter part of the Xid.
     * @returns The 3-byte counter.
     */
    counter(): number;
    /**
     * Checks if the Xid is zero (nil).
     * @returns True if the Xid is zero, false otherwise.
     */
    isZero(): boolean;
    /**
     * Returns the string representation of the Xid.
     * This is an alias for `encode()`.
     * @returns The 20-byte string representation of the Xid.
     */
    toString(): string;
    /**
     * Returns the raw byte representation of the Xid.
     * @returns A 12-byte Uint8Array.
     */
    toBytes(): Uint8Array;
    /**
     * Returns the string representation of the Xid for JSON serialization.
     * This is an alias for `encode()`.
     * @returns The 20-byte string representation of the Xid.
     */
    toJSON(): string;
    /**
     * Checks if this Xid is equal to another Xid.
     * @param xid - The Xid to compare with.
     * @returns True if the Xids are equal, false otherwise.
     */
    equals(xid: Xid): boolean;
}