HID / HybridIDGenerator

HID is the shorter named export for this class. HID === HybridIDGenerator; constructors, instances, methods, and options are identical. Both names remain supported.

import { HID } from 'hybrid-id-generator';
const generator = new HID({ machineId: 1 });

constructor

new HybridIDGenerator(options?: HybridIDGeneratorOptions) validates field widths and resolves a machine ID once. See configuration for defaults and accepted values.

nextId

nextId(): HybridID returns one ID. It retains the last logical timestamp during rollback and advances it by one millisecond when the sequence field is exhausted. Timestamp overflow and unavailable requested cryptographic/Node features throw.

nextIds

nextIds(batchSize: number): HybridID[] accepts a safe integer from 1 to 1_000_000. Each item uses the same generation path as nextId(), including clock reads and event emission. This is synchronous allocation; use smaller batches when responsiveness matters.

iterateIds

iterateIds(count: number): IterableIterator<HybridID> validates a positive safe integer immediately, then generates one ID per consumed item. It accepts counts larger than nextIds() without allocating an array. Creating or closing the iterator generates no IDs. Each item uses nextId(), including its current clock, sequence state, and events; interleaved iterators share the same generator.

for (const id of generator.iterateIds(10_000_000)) {
  await saveId(id.toString());
}

Iteration is synchronous. Consuming it in a tight loop still blocks the event loop; control scheduling or await application work between items when responsiveness matters.

info

info(id: HybridID | bigint | string): HybridIDInfo validates and decodes the ID. Strings are interpreted as Base62. Invalid IDs throw Invalid ID.

const id = generator.nextId();
const { timestamp, machineId, randomBits, entropy, sequence, masked } = generator.info(id);

Timestamp is a bigint in milliseconds; it is -1n when masking is enabled. The format does not carry masking metadata: the result reflects this generator's configuration. entropy is the decoded value of the separate entropy field, from 0 through 2 ** entropyBits - 1; a zero-width field returns 0. The existing randomBits property is the decoded random value.

isHybridID

isHybridID(id: string | bigint | HybridID): boolean checks non-negativity and the configured total bit range. It validates wrappers as well as raw values. Base62 strings exceeding the layout's significant digit length are rejected before bigint decoding; leading zeroes remain accepted. It does not prove the ID was generated by this library or by an authorized client.

validateID

validateID(id: bigint | string | HybridID): { valid: boolean; reason?: string } returns { valid: true }, or { valid: false, reason: 'Invalid Hybrid ID' }.

isIdExpired

isIdExpired(id: bigint | HybridID, expiryDurationInMillis: number): boolean validates the ID and a non-negative safe integer duration. It returns true when physical-clock age is strictly greater than the duration. With masking enabled it returns false.

Use the same layout and clock origin that generated the ID. Logical clock advancement can delay expiry. Monotonic IDs are unsuitable for expiry comparisons across hosts.

getTimestamp

getTimestamp(useHighResTime?: boolean): bigint returns milliseconds. Omitted argument follows useWallClock; true selects Node monotonic milliseconds, and false selects Unix milliseconds. Out-of-range timestamps throw.

toBase62

toBase62(id: bigint | HybridID): string encodes a non-negative integer.

fromBase62

fromBase62(encodedId: string | HybridID): bigint decodes Base62 strings and returns the underlying bigint directly for a HybridID wrapper. Invalid strings throw.

options

The read-only getter returns a new object with all resolved options plus sequence, lastTimestamp, maxSequence, maxMachineId, and maxTimestamp. Last timestamp is the unmasked logical timestamp.

idGenerated

The generator extends EventEmitter. With enableEventEmission: true, on('idGenerated', listener) receives the same HybridID returned by nextId(). TypeScript infers the listener argument as HybridID for on, once, addListener, prependListener, and prependOnceListener. Other string and symbol events retain standard EventEmitter behavior in Node and the browser bundle.

generator.on('idGenerated', id => {
  console.log(id.toBase62()); // id is inferred as HybridID
});