uniku 0.3.1 → 0.4.0

package/src/tsid/tsid.ts

@@ -62,14 +62,23 @@ export type TsidOptions = {
 }
 
 export type Tsid = {
+  /** Generate a time-sorted TSID bigint. */
   (): bigint
+  /** Generate a TSID with explicit options or write its 8 canonical bytes into a caller-owned buffer. */
   <TBuf extends Uint8Array = Uint8Array>(options: TsidOptions | undefined, buf: TBuf, offset?: number): TBuf
+  /** Generate a TSID bigint with optional timestamp, epoch, node, or counter controls. */
   (options?: TsidOptions, buf?: undefined, offset?: number): bigint
+  /** Convert a TSID bigint to its canonical 8-byte representation. */
   toBytes(id: bigint): Uint8Array
+  /** Convert 8 canonical TSID bytes to a TSID bigint. */
   fromBytes(bytes: Uint8Array): bigint
+  /** Convert a TSID bigint to its canonical 13-character string. */
   toString(id: bigint): string
+  /** Convert a canonical TSID string to a bigint. */
   fromString(str: string): bigint
+  /** Read a TSID timestamp in milliseconds, using the supplied or default epoch. */
   timestamp(id: bigint, epoch?: number): number
+  /** Return whether a value is a valid 64-bit TSID bigint. */
   isValid(id: unknown): id is bigint
   /** The nil TSID (all zeros) */
   NIL: bigint

package/src/typeid/typeid.ts

@@ -5,14 +5,23 @@ import { uuidv7 } from '../uuid/v7'
 export type TypeidOptions = UuidV7Options
 
 export type Typeid = {
+  /** Generate a TypeID from a lowercase entity prefix and a UUID v7 suffix. */
   (prefix: string, options?: TypeidOptions): string
+  /** Convert a TypeID's UUID v7 suffix to its canonical 16-byte representation. */
   toBytes(id: string): Uint8Array
+  /** Build a TypeID from a prefix and canonical UUID v7 bytes. */
   fromBytes(prefix: string, bytes: Uint8Array): string
+  /** Convert a TypeID to its UUID v7 string. */
   toUuid(id: string): string
+  /** Build a TypeID from a prefix and UUID v7 string. */
   fromUuid(prefix: string, uuid: string): string
+  /** Read the UUID v7 timestamp embedded in a TypeID, in milliseconds. */
   timestamp(id: string): number
+  /** Read a TypeID's entity prefix. */
   prefix(id: string): string
+  /** Read a TypeID's UUID v7 suffix. */
   suffix(id: string): string
+  /** Return whether a value is a syntactically valid TypeID. */
   isValid(id: unknown): id is string
 }
 

package/src/ulid/ulid.ts

@@ -18,12 +18,19 @@ export type UlidOptions = {
 }
 
 export type Ulid = {
+  /** Generate a time-ordered ULID string. */
   (): string
+  /** Generate a ULID with explicit options or write its 16 canonical bytes into a caller-owned buffer. */
   <TBuf extends Uint8Array = Uint8Array>(options: UlidOptions | undefined, buf: TBuf, offset?: number): TBuf
+  /** Generate a ULID string with optional timestamp or random bytes. */
   (options?: UlidOptions, buf?: undefined, offset?: number): string
+  /** Convert a ULID string to its canonical 16-byte representation. */
   toBytes(id: string): Uint8Array
+  /** Convert 16 canonical ULID bytes to a ULID string. */
   fromBytes(bytes: Uint8Array): string
+  /** Read the embedded Unix timestamp in milliseconds. */
   timestamp(id: string): number
+  /** Return whether a value is a syntactically valid ULID string. */
   isValid(id: unknown): id is string
   /** The nil ULID (all zeros) */
   NIL: string
@@ -183,6 +190,10 @@ function isValid(id: unknown): id is string {
   return typeof id === 'string' && ULID_REGEX.test(id)
 }
 
+/**
+ * Generate a ULID string or write its 16 canonical bytes into a buffer.
+ * ULIDs are URL-safe, carry a millisecond timestamp, and sort by creation time.
+ */
 export const ulid: Ulid = Object.assign(ulidFn, {
   toBytes: (id: string) => decodeToBytes(id),
   fromBytes: (bytes: Uint8Array) => bytesToUlid(bytes),

package/src/uuid/v4.ts

@@ -15,11 +15,17 @@ export type UuidV4Options = {
 }
 
 export type UuidV4 = {
+  /** Generate a random UUID v4 string. */
   (): string
+  /** Generate a UUID v4 with explicit options or write its 16 canonical bytes into a caller-owned buffer. */
   <TBuf extends Uint8Array = Uint8Array>(options: UuidV4Options | undefined, buf: TBuf, offset?: number): TBuf
+  /** Generate a UUID v4 string with optional deterministic random bytes. */
   (options?: UuidV4Options, buf?: undefined, offset?: number): string
+  /** Convert a UUID v4 string to its canonical 16-byte representation. */
   toBytes(id: string): Uint8Array
+  /** Convert 16 canonical UUID bytes to a UUID v4 string. */
   fromBytes(bytes: Uint8Array): string
+  /** Return whether a value is a syntactically valid UUID v4 string. */
   isValid(id: unknown): id is string
   /** The nil UUID (all zeros) */
   NIL: string

package/src/uuid/v7.ts

@@ -9,6 +9,10 @@ export type UuidV7Options = {
    * Note: Several bytes will be overwritten with timestamp, version, and variant data.
    */
   random?: Uint8Array
+  /**
+   * Timestamp in milliseconds since Unix epoch.
+   * Defaults to Date.now().
+   */
   msecs?: number
   /**
    * Unsigned 32-bit sequence value.
@@ -17,12 +21,19 @@ export type UuidV7Options = {
 }
 
 export type UuidV7 = {
+  /** Generate a time-ordered UUID v7 string. */
   (): string
+  /** Generate a UUID v7 with explicit options or write its 16 canonical bytes into a caller-owned buffer. */
   <TBuf extends Uint8Array = Uint8Array>(options: UuidV7Options | undefined, buf: TBuf, offset?: number): TBuf
+  /** Generate a UUID v7 string with optional timestamp, sequence, or random bytes. */
   (options?: UuidV7Options, buf?: undefined, offset?: number): string
+  /** Convert a UUID v7 string to its canonical 16-byte representation. */
   toBytes(id: string): Uint8Array
+  /** Convert 16 canonical UUID bytes to a UUID v7 string. */
   fromBytes(bytes: Uint8Array): string
+  /** Read the embedded Unix timestamp in milliseconds. */
   timestamp(id: string): number
+  /** Return whether a value is a syntactically valid UUID v7 string. */
   isValid(id: unknown): id is string
   /** The nil UUID (all zeros) */
   NIL: string

package/src/xid/base32hex.ts

@@ -0,0 +1,79 @@
+import { BufferError, ParseError } from '../errors'
+
+const ENCODING = '0123456789abcdefghijklmnopqrstuv'
+const XID_BYTES = 12
+const XID_LENGTH = 20
+
+const DECODING = new Uint8Array(65536)
+DECODING.fill(255)
+for (let i = 0; i < ENCODING.length; i += 1) {
+  DECODING[ENCODING.charCodeAt(i)] = i
+}
+
+/** Encode the 12 canonical XID bytes as lowercase base32hex. */
+export function encodeBase32Hex(bytes: Uint8Array): string {
+  if (bytes.length !== XID_BYTES) {
+    throw new BufferError(
+      'XID_BYTES_INVALID_LENGTH',
+      `XID bytes must be exactly ${XID_BYTES} bytes, got ${bytes.length}`,
+    )
+  }
+
+  return (
+    ENCODING[bytes[0] >> 3] +
+    ENCODING[((bytes[0] << 2) | (bytes[1] >> 6)) & 0x1f] +
+    ENCODING[(bytes[1] >> 1) & 0x1f] +
+    ENCODING[((bytes[1] << 4) | (bytes[2] >> 4)) & 0x1f] +
+    ENCODING[((bytes[2] << 1) | (bytes[3] >> 7)) & 0x1f] +
+    ENCODING[(bytes[3] >> 2) & 0x1f] +
+    ENCODING[((bytes[3] << 3) | (bytes[4] >> 5)) & 0x1f] +
+    ENCODING[bytes[4] & 0x1f] +
+    ENCODING[bytes[5] >> 3] +
+    ENCODING[((bytes[5] << 2) | (bytes[6] >> 6)) & 0x1f] +
+    ENCODING[(bytes[6] >> 1) & 0x1f] +
+    ENCODING[((bytes[6] << 4) | (bytes[7] >> 4)) & 0x1f] +
+    ENCODING[((bytes[7] << 1) | (bytes[8] >> 7)) & 0x1f] +
+    ENCODING[(bytes[8] >> 2) & 0x1f] +
+    ENCODING[((bytes[8] << 3) | (bytes[9] >> 5)) & 0x1f] +
+    ENCODING[bytes[9] & 0x1f] +
+    ENCODING[bytes[10] >> 3] +
+    ENCODING[((bytes[10] << 2) | (bytes[11] >> 6)) & 0x1f] +
+    ENCODING[(bytes[11] >> 1) & 0x1f] +
+    ENCODING[(bytes[11] << 4) & 0x1f]
+  )
+}
+
+/** Decode a canonical lowercase base32hex XID string to its 12 bytes. */
+export function decodeBase32Hex(id: string): Uint8Array {
+  if (id.length !== XID_LENGTH) {
+    throw new ParseError('XID_INVALID_LENGTH', `XID string must be ${XID_LENGTH} characters, got ${id.length}`)
+  }
+
+  const values = new Uint8Array(XID_LENGTH)
+  for (let i = 0; i < XID_LENGTH; i += 1) {
+    const value = DECODING[id.charCodeAt(i)]
+    if (value === 255) {
+      throw new ParseError('XID_INVALID_CHAR', `Invalid XID character: ${id[i]}`)
+    }
+    values[i] = value
+  }
+
+  if (values[19] !== 0 && values[19] !== 16) {
+    throw new ParseError('XID_NON_CANONICAL', 'XID trailing bits must be canonically encoded')
+  }
+
+  return new Uint8Array([
+    (values[0] << 3) | (values[1] >> 2),
+    (values[1] << 6) | (values[2] << 1) | (values[3] >> 4),
+    (values[3] << 4) | (values[4] >> 1),
+    (values[4] << 7) | (values[5] << 2) | (values[6] >> 3),
+    (values[6] << 5) | values[7],
+    (values[8] << 3) | (values[9] >> 2),
+    (values[9] << 6) | (values[10] << 1) | (values[11] >> 4),
+    (values[11] << 4) | (values[12] >> 1),
+    (values[12] << 7) | (values[13] << 2) | (values[14] >> 3),
+    (values[14] << 5) | values[15],
+    (values[16] << 3) | (values[17] >> 2),
+    (values[17] << 6) | (values[18] << 1) | (values[19] >> 4),
+  ])
+}

package/src/xid/xid.ts

@@ -0,0 +1,158 @@
+import { writeTimestamp32 } from '../common/bytes'
+import { randomBytes, randomUint32 } from '../common/random'
+import { isIntegerInRange, isWritableRange } from '../common/validation'
+import { BufferError, InvalidInputError } from '../errors'
+import { decodeBase32Hex, encodeBase32Hex } from './base32hex'
+
+const XID_BYTES = 12
+const MACHINE_ID_BYTES = 3
+const MAX_SECS = 0xffffffff
+const MAX_PROCESS_ID = 0xffff
+const MAX_COUNTER = 0xffffff
+const XID_REGEX = /^[0-9a-v]{19}[0g]$/
+
+export type XidOptions = {
+  /** First three bytes used as the XID machine identity. */
+  machineId?: Uint8Array
+  /** 16-bit process identity. */
+  processId?: number
+  /** Unix timestamp in seconds. Defaults to the current second. */
+  secs?: number
+  /** 24-bit counter. Explicit values do not consume shared state. */
+  counter?: number
+}
+
+export type Xid = {
+  (): string
+  <TBuf extends Uint8Array = Uint8Array>(options: XidOptions | undefined, buf: TBuf, offset?: number): TBuf
+  (options?: XidOptions, buf?: undefined, offset?: number): string
+  toBytes(id: string): Uint8Array
+  fromBytes(bytes: Uint8Array): string
+  timestamp(id: string): number
+  isValid(id: unknown): id is string
+  NIL: string
+  MAX: string
+}
+
+type XidState = {
+  machineId: Uint8Array | undefined
+  processId: number | undefined
+  counter: number | undefined
+}
+
+const state: XidState = { machineId: undefined, processId: undefined, counter: undefined }
+
+/** Copy pooled bytes before another random draw can refill their backing pool. */
+function freshRandom(count: number): Uint8Array {
+  return randomBytes(count).slice()
+}
+
+function initializeIdentity(): void {
+  if (state.machineId === undefined) state.machineId = freshRandom(MACHINE_ID_BYTES)
+  if (state.processId === undefined) state.processId = randomUint32() & MAX_PROCESS_ID
+}
+
+function nextCounter(): number {
+  if (state.counter === undefined) state.counter = randomUint32() & MAX_COUNTER
+  state.counter = (state.counter + 1) & MAX_COUNTER
+  return state.counter
+}
+
+function writeXidBytesUnchecked(
+  secs: number,
+  machineId: Uint8Array,
+  processId: number,
+  counter: number,
+  buf: Uint8Array,
+  offset: number,
+): void {
+  writeTimestamp32(buf, offset, secs)
+  buf.set(machineId.subarray(0, MACHINE_ID_BYTES), offset + 4)
+  buf[offset + 7] = processId >>> 8
+  buf[offset + 8] = processId & 0xff
+  buf[offset + 9] = counter >>> 16
+  buf[offset + 10] = (counter >>> 8) & 0xff
+  buf[offset + 11] = counter & 0xff
+}
+
+function validateOptions(options: XidOptions): void {
+  if (options.machineId !== undefined && options.machineId.length < MACHINE_ID_BYTES) {
+    throw new InvalidInputError(
+      'XID_MACHINE_ID_BYTES_TOO_SHORT',
+      `Machine ID bytes length must be >= ${MACHINE_ID_BYTES} for XID`,
+    )
+  }
+  if (options.processId !== undefined && !isIntegerInRange(options.processId, 0, MAX_PROCESS_ID)) {
+    throw new InvalidInputError('XID_PROCESS_ID_OUT_OF_RANGE', `Process ID must be between 0 and ${MAX_PROCESS_ID}`)
+  }
+  if (options.secs !== undefined && !isIntegerInRange(options.secs, 0, MAX_SECS)) {
+    throw new InvalidInputError('XID_TIMESTAMP_OUT_OF_RANGE', `Timestamp must be between 0 and ${MAX_SECS}`)
+  }
+  if (options.counter !== undefined && !isIntegerInRange(options.counter, 0, MAX_COUNTER)) {
+    throw new InvalidInputError('XID_COUNTER_OUT_OF_RANGE', `Counter must be between 0 and ${MAX_COUNTER}`)
+  }
+}
+
+function xidFn(options?: XidOptions, buf?: undefined, offset?: number): string
+function xidFn<TBuf extends Uint8Array = Uint8Array>(options: XidOptions | undefined, buf: TBuf, offset?: number): TBuf
+function xidFn<TBuf extends Uint8Array = Uint8Array>(options?: XidOptions, buf?: TBuf, offset = 0): string | TBuf {
+  if (options !== undefined) validateOptions(options)
+
+  const secs = options?.secs ?? Math.floor(Date.now() / 1000)
+  if (options?.machineId === undefined || options.processId === undefined) {
+    initializeIdentity()
+  }
+  const machineId = options?.machineId ?? state.machineId!
+  const processId = options?.processId ?? state.processId!
+  const counter = options?.counter ?? nextCounter()
+
+  if (buf !== undefined) {
+    if (!isWritableRange(buf, offset, XID_BYTES)) {
+      throw new BufferError(
+        'XID_BUFFER_OUT_OF_BOUNDS',
+        `XID byte range ${offset}:${offset + 11} is out of buffer bounds`,
+      )
+    }
+    writeXidBytesUnchecked(secs, machineId, processId, counter, buf, offset)
+    return buf
+  }
+
+  const bytes = new Uint8Array(XID_BYTES)
+  writeXidBytesUnchecked(secs, machineId, processId, counter, bytes, 0)
+  return encodeBase32Hex(bytes)
+}
+
+function toBytes(id: string): Uint8Array {
+  return decodeBase32Hex(id)
+}
+
+function fromBytes(bytes: Uint8Array): string {
+  return encodeBase32Hex(bytes)
+}
+
+function timestamp(id: string): number {
+  const bytes = decodeBase32Hex(id)
+  return (((bytes[0] << 24) | (bytes[1] << 16) | (bytes[2] << 8) | bytes[3]) >>> 0) * 1000
+}
+
+function isValid(id: unknown): id is string {
+  return typeof id === 'string' && XID_REGEX.test(id)
+}
+
+/**
+ * Generate a 20-character rs/xid-compatible identifier.
+ *
+ * XID embeds seconds, a lazily-random per-runtime identity, and a shared
+ * always-incrementing counter. In Cloudflare Workers, time is frozen during a
+ * request, so the counter preserves ordering for IDs made in that request.
+ */
+export const xid: Xid = Object.assign(xidFn, {
+  toBytes,
+  fromBytes,
+  timestamp,
+  isValid,
+  NIL: '0'.repeat(20),
+  MAX: encodeBase32Hex(new Uint8Array(12).fill(0xff)),
+})
+
+export { BufferError, InvalidInputError, ParseError, UniqueIdError } from '../errors'