uniku 0.1.0 → 0.3.0

package/src/objectid/objectid.ts

@@ -0,0 +1,266 @@
+import { writeTimestamp32 } from '../common/bytes'
+import { randomBytes, randomUint32 } from '../common/random'
+import { BufferError, InvalidInputError } from '../errors'
+import { decodeObjectIdHex, encodeObjectIdHex } from './hex'
+
+/**
+ * MongoDB ObjectID
+ *
+ * A 96-bit (12-byte) identifier consisting of:
+ * - 4 bytes: big-endian Unix timestamp in seconds
+ * - 5 bytes: per-process random value
+ * - 3 bytes: big-endian counter, always incrementing (wraps at 0xFFFFFF back to 0)
+ *
+ * Encoded as a 24-character lowercase hex string.
+ */
+
+const OBJECTID_BYTES = 12
+const TIMESTAMP_BYTES = 4
+const RANDOM_BYTES = 5
+const COUNTER_BYTES = 3
+const MAX_SECS = 0xffffffff
+const MAX_COUNTER = 0xffffff
+
+// Validation regex: case-insensitive per KTD7, matching bson's ObjectId.isValid()
+const OBJECTID_REGEX = /^[0-9a-f]{24}$/i
+
+export type ObjectIdOptions = {
+  /**
+   * 5 bytes of random data to use for the ObjectID's random field.
+   */
+  random?: Uint8Array
+  /**
+   * Timestamp in seconds since Unix epoch.
+   * Defaults to Math.floor(Date.now() / 1000).
+   */
+  secs?: number
+  /**
+   * 24-bit counter value (0 to 0xFFFFFF).
+   */
+  counter?: number
+}
+
+export type ObjectId = {
+  (): string
+  <TBuf extends Uint8Array = Uint8Array>(options: ObjectIdOptions | undefined, buf: TBuf, offset?: number): TBuf
+  (options?: ObjectIdOptions, buf?: undefined, offset?: number): string
+  toBytes(id: string): Uint8Array
+  fromBytes(bytes: Uint8Array): string
+  timestamp(id: string): number
+  isValid(id: unknown): id is string
+  /** The nil ObjectID (all zeros) */
+  NIL: string
+  /** The max ObjectID (all 0xff) */
+  MAX: string
+}
+
+type ObjectIdState = {
+  random: Uint8Array | undefined
+  counter: number | undefined
+}
+
+/**
+ * Module-level state for the per-process random value and the always-incrementing counter.
+ *
+ * IMPORTANT: This state persists across all objectid() calls in the module's lifetime.
+ * - In serverless/edge functions with warm starts, state persists between invocations.
+ *   Unlike ULID/UUIDv7's per-timestamp sequence reset, the counter continuing to climb
+ *   across warm starts is exactly the anti-collision behavior the ObjectID spec intends.
+ * - For isolated state, pass explicit `random`, `secs`, or `counter` via options.
+ * - Tests should mock Date.now() or provide explicit options for deterministic behavior.
+ */
+const state: ObjectIdState = {
+  random: undefined,
+  counter: undefined,
+}
+
+/**
+ * Draw 5 fresh random bytes into a newly-owned buffer, copying immediately so the
+ * result is unaffected by any later pool refill triggered by other random draws
+ * (e.g. the counter's `randomUint32()` call) before these bytes are consumed.
+ */
+function freshRandom(): Uint8Array {
+  const bytes = new Uint8Array(RANDOM_BYTES)
+  bytes.set(randomBytes(RANDOM_BYTES))
+  return bytes
+}
+
+function objectIdBytes(secs: number, random: Uint8Array, counter: number, buf?: Uint8Array, offset = 0): Uint8Array {
+  if (!buf) {
+    buf = new Uint8Array(OBJECTID_BYTES)
+    offset = 0
+  } else if (offset < 0 || offset + OBJECTID_BYTES > buf.length) {
+    throw new BufferError(
+      'OBJECTID_BUFFER_OUT_OF_BOUNDS',
+      `ObjectID byte range ${offset}:${offset + OBJECTID_BYTES - 1} is out of buffer bounds`,
+    )
+  }
+
+  // Timestamp (32-bit big-endian seconds since Unix epoch) -> bytes 0-3
+  writeTimestamp32(buf, offset, secs)
+
+  // Random (5 bytes) -> bytes 4-8
+  for (let i = 0; i < RANDOM_BYTES; i += 1) {
+    buf[offset + TIMESTAMP_BYTES + i] = random[i]
+  }
+
+  // Counter (24-bit big-endian) -> bytes 9-11
+  buf[offset + TIMESTAMP_BYTES + RANDOM_BYTES] = (counter >>> 16) & 0xff
+  buf[offset + TIMESTAMP_BYTES + RANDOM_BYTES + 1] = (counter >>> 8) & 0xff
+  buf[offset + TIMESTAMP_BYTES + RANDOM_BYTES + COUNTER_BYTES - 1] = counter & 0xff
+
+  return buf
+}
+
+/*
+ * Overload: no buffer => return an ObjectID string.
+ */
+function objectIdFn(options?: ObjectIdOptions, buf?: undefined, offset?: number): string
+/*
+ * Overload: caller provides a buffer slice to fill with ObjectID bytes.
+ */
+function objectIdFn<TBuf extends Uint8Array = Uint8Array>(
+  options: ObjectIdOptions | undefined,
+  buf: TBuf,
+  offset?: number,
+): TBuf
+function objectIdFn<TBuf extends Uint8Array = Uint8Array>(
+  options?: ObjectIdOptions,
+  buf?: TBuf,
+  offset = 0,
+): string | TBuf {
+  let secs: number
+  let random: Uint8Array
+  let counter: number
+
+  if (options) {
+    const optRandom = options.random
+    if (optRandom && optRandom.length < RANDOM_BYTES) {
+      throw new InvalidInputError(
+        'OBJECTID_RANDOM_BYTES_TOO_SHORT',
+        `Random bytes length must be >= ${RANDOM_BYTES} for ObjectID`,
+      )
+    }
+
+    const optSecs = options.secs
+    if (optSecs !== undefined && (optSecs < 0 || optSecs > MAX_SECS)) {
+      throw new InvalidInputError('OBJECTID_TIMESTAMP_OUT_OF_RANGE', `Timestamp must be between 0 and ${MAX_SECS}`)
+    }
+
+    const optCounter = options.counter
+    if (optCounter !== undefined && (optCounter < 0 || optCounter > MAX_COUNTER)) {
+      throw new InvalidInputError('OBJECTID_COUNTER_OUT_OF_RANGE', `Counter must be between 0 and ${MAX_COUNTER}`)
+    }
+
+    // Options bypass persistent state entirely: every field is sourced fresh (given
+    // value, or an independently-defaulted one), never read from or written to
+    // `state` (see KTD2). This is what makes options-based generation deterministic
+    // when all three fields are supplied.
+    secs = optSecs ?? Math.floor(Date.now() / 1000)
+    random = optRandom ?? freshRandom()
+    counter = optCounter ?? randomUint32() & MAX_COUNTER
+  } else {
+    // Lazily initialize persistent state on first no-option call.
+    if (state.random === undefined) {
+      state.random = freshRandom()
+    }
+    if (state.counter === undefined) {
+      state.counter = randomUint32() & MAX_COUNTER
+    }
+
+    /**
+     * Note: by default, Cloudflare Workers "freezes" time during request handling to prevent
+     * side-channel attacks. This means that Date.now() will return the same value for the entire
+     * duration of a request.
+     * Implications:
+     * - all ObjectIDs generated within a single request will share the same timestamp.
+     * - monotonic ordering relies entirely on the ever-incrementing counter.
+     */
+    secs = Math.floor(Date.now() / 1000)
+    random = state.random
+    state.counter = (state.counter + 1) & MAX_COUNTER
+    counter = state.counter
+  }
+
+  if (buf) {
+    objectIdBytes(secs, random, counter, buf, offset)
+    return buf
+  }
+
+  const bytes = objectIdBytes(secs, random, counter)
+  return encodeObjectIdHex(bytes)
+}
+
+/**
+ * Convert an ObjectID hex string to 12 bytes.
+ */
+function toBytes(id: string): Uint8Array {
+  return decodeObjectIdHex(id)
+}
+
+/**
+ * Convert 12 bytes to an ObjectID hex string.
+ */
+function fromBytes(bytes: Uint8Array): string {
+  return encodeObjectIdHex(bytes)
+}
+
+/**
+ * Extract the timestamp from an ObjectID string.
+ * Returns Unix timestamp in milliseconds for API consistency with ulid/uuidv7/ksuid.
+ * Note: ObjectID only has second precision, so the returned value will always end in 000.
+ */
+function timestamp(id: string): number {
+  const bytes = decodeObjectIdHex(id)
+  // First 4 bytes are big-endian timestamp (seconds since Unix epoch)
+  const secs = ((bytes[0] << 24) | (bytes[1] << 16) | (bytes[2] << 8) | bytes[3]) >>> 0
+  return secs * 1000
+}
+
+/**
+ * Validate an ObjectID string format.
+ * Case-insensitive (KTD7), matching bson's ObjectId.isValid() and this repo's existing
+ * convention (ulid, ksuid) of accepting mixed-case input for parsing, even though
+ * generation always emits lowercase (matching MongoDB driver output).
+ */
+function isValid(id: unknown): id is string {
+  return typeof id === 'string' && OBJECTID_REGEX.test(id)
+}
+
+/**
+ * Generate a MongoDB ObjectID string or write the bytes into a buffer.
+ *
+ * ObjectID is a 12-byte identifier consisting of a 4-byte timestamp, a 5-byte
+ * per-process random value, and a 3-byte always-incrementing counter, encoded
+ * as a 24-character lowercase hex string. It is time-ordered and compatible
+ * with MongoDB's own ObjectID implementation.
+ *
+ * @example
+ * ```ts
+ * import { objectid } from 'uniku/objectid'
+ *
+ * const id = objectid()
+ * // => "667c3f2a1e2b3c4d5e6f7081"
+ *
+ * // Extract timestamp
+ * const ts = objectid.timestamp(id)
+ * console.log(new Date(ts))
+ *
+ * // Validate
+ * objectid.isValid(id) // true
+ *
+ * // Convert to/from bytes (12 bytes)
+ * const bytes = objectid.toBytes(id)
+ * const restored = objectid.fromBytes(bytes)
+ * ```
+ */
+export const objectid: ObjectId = Object.assign(objectIdFn, {
+  toBytes,
+  fromBytes,
+  timestamp,
+  isValid,
+  NIL: '0'.repeat(24),
+  MAX: 'f'.repeat(24),
+})
+
+export { BufferError, InvalidInputError, ParseError, UniqueIdError } from '../errors'

package/src/tsid/crockford64.ts

@@ -0,0 +1,75 @@
+import { ParseError } from '../errors'
+
+/**
+ * Crockford Base32 codec for TSID, operating directly on the primary `bigint`
+ * value rather than an intermediate byte array (unlike ulid/crockford.ts) -
+ * tsid's primary type never routes through a `Uint8Array` during string
+ * conversion.
+ *
+ * TSID binary format: 64 bits (8 bytes), encoded as 13 Crockford Base32 characters.
+ * 13 chars * 5 bits = 65 bits of capacity for a 64-bit value, leaving exactly 1 bit
+ * of headroom on the leading character. That headroom bit is always 0, so the
+ * leading character only carries 4 significant real bits (values 0-15, i.e. the
+ * alphabet's first 16 symbols "0"-"9"/"A"-"F") rather than the full 32-symbol
+ * range - the same overflow-prevention technique ULID uses for its own leading
+ * `[0-7]` restriction (2 headroom bits there vs 1 here). Confirmed against
+ * `tsid-ts`'s own `toCanonicalString`: `(number >> BigInt(60 - i * 5)) & 0x1f`.
+ */
+
+const TSID_ALPHABET = '0123456789ABCDEFGHJKMNPQRSTVWXYZ'
+const TSID_STRING_LEN = 13
+const TSID_LEADING_MAX = 15 // 4 significant bits on the leading character (see above)
+
+// Pre-computed decode table (case-insensitive) covering ASCII, so lookups never
+// go out of bounds and a single `=== 255` check rejects invalid input.
+const DECODING = new Uint8Array(128).fill(255)
+for (let i = 0; i < TSID_ALPHABET.length; i += 1) {
+  const char = TSID_ALPHABET[i]
+  const upperCode = TSID_ALPHABET.charCodeAt(i)
+  DECODING[upperCode] = i
+  // Only letters have a lowercase counterpart - applying +32 to digit codes
+  // would land on unrelated uppercase letters (e.g. '5' + 32 -> 'U', which is
+  // excluded from this alphabet and would never get overwritten back to 255).
+  if (char >= 'A' && char <= 'Z') {
+    DECODING[upperCode + 32] = i
+  }
+}
+
+/**
+ * Encode a TSID `bigint` value to its 13-character canonical Crockford Base32 string.
+ */
+export function encodeTsidString(value: bigint): string {
+  let result = ''
+  for (let i = 0; i < TSID_STRING_LEN; i += 1) {
+    const shift = BigInt(60 - i * 5)
+    const group = Number((value >> shift) & 0x1fn)
+    result += TSID_ALPHABET[group]
+  }
+  return result
+}
+
+/**
+ * Decode a 13-character canonical Crockford Base32 string to a TSID `bigint` value.
+ */
+export function decodeTsidString(str: string): bigint {
+  if (str.length !== TSID_STRING_LEN) {
+    throw new ParseError('TSID_INVALID_LENGTH', `TSID string must be ${TSID_STRING_LEN} characters, got ${str.length}`)
+  }
+
+  let value = 0n
+  for (let i = 0; i < TSID_STRING_LEN; i += 1) {
+    const code = str.charCodeAt(i)
+    const group = code < 128 ? DECODING[code] : 255
+    if (group === 255) {
+      throw new ParseError('TSID_INVALID_CHAR', `Invalid TSID character: ${str[i]}`)
+    }
+    if (i === 0 && group > TSID_LEADING_MAX) {
+      throw new ParseError(
+        'TSID_LEADING_CHAR_OUT_OF_RANGE',
+        `TSID leading character must be one of 0-9, A-F, got: ${str[i]}`,
+      )
+    }
+    value = (value << 5n) | BigInt(group)
+  }
+  return value
+}

package/src/tsid/tsid.ts

@@ -0,0 +1,310 @@
+import { randomUint32 } from '../common/random'
+import { BufferError, InvalidInputError } from '../errors'
+import { decodeTsidString, encodeTsidString } from './crockford64'
+
+/**
+ * TSID (Time-Sorted Unique Identifier)
+ *
+ * A 64-bit Snowflake-style identifier consisting of:
+ * - 42 bits: millisecond timestamp relative to a custom epoch (default 2020-01-01T00:00:00.000Z)
+ * - 10 bits: node ID (default; configurable via `nodeBits`)
+ * - 12 bits: per-millisecond counter (default; `22 - nodeBits`)
+ *
+ * Unlike every other uniku generator, `tsid()` returns a `bigint` by default -
+ * this is a deliberate design decision reflecting that TSID's value proposition
+ * is native numeric storage (e.g. a database BIGINT primary key), not a
+ * string-first identifier that happens to have a byte encoding. `toString`/
+ * `fromString` are the boundary conversions to/from the 13-character canonical
+ * Crockford Base32 string.
+ *
+ * Encoded as 8 big-endian bytes in buffer mode.
+ */
+
+const TSID_EPOCH = 1577836800000 // 2020-01-01T00:00:00.000Z
+const TSID_BYTES = 8
+const RANDOM_BITS = 22 // combined node + counter bits
+const DEFAULT_NODE_BITS = 10
+const DEFAULT_COUNTER_BITS = RANDOM_BITS - DEFAULT_NODE_BITS
+const DEFAULT_NODE_MASK = (1 << DEFAULT_NODE_BITS) - 1
+const DEFAULT_COUNTER_MASK = (1 << DEFAULT_COUNTER_BITS) - 1
+const MAX_NODE_BITS = 20
+const MAX_TIMESTAMP_DIFF = (1n << 42n) - 1n
+
+export type TsidOptions = {
+  /**
+   * Timestamp in milliseconds since Unix epoch.
+   * Defaults to Date.now().
+   */
+  msecs?: number
+  /**
+   * Custom epoch in milliseconds since Unix epoch.
+   * Defaults to 1577836800000 (2020-01-01T00:00:00.000Z).
+   */
+  epoch?: number
+  /**
+   * Node ID (0 to 2^nodeBits - 1).
+   * Defaults to a lazily-initialized, persistent random value.
+   */
+  node?: number
+  /**
+   * Number of bits allocated to the node ID (0-20).
+   * The remaining bits (22 - nodeBits) are allocated to the counter.
+   * Defaults to 10.
+   */
+  nodeBits?: number
+  /**
+   * Per-millisecond counter (0 to 2^(22 - nodeBits) - 1).
+   * Defaults to a fresh random value on a new millisecond, or the previous
+   * value incremented by 1 within the same millisecond.
+   */
+  counter?: number
+}
+
+export type Tsid = {
+  (): bigint
+  <TBuf extends Uint8Array = Uint8Array>(options: TsidOptions | undefined, buf: TBuf, offset?: number): TBuf
+  (options?: TsidOptions, buf?: undefined, offset?: number): bigint
+  toBytes(id: bigint): Uint8Array
+  fromBytes(bytes: Uint8Array): bigint
+  toString(id: bigint): string
+  fromString(str: string): bigint
+  timestamp(id: bigint, epoch?: number): number
+  isValid(id: unknown): id is bigint
+  /** The nil TSID (all zeros) */
+  NIL: bigint
+  /** The max TSID (maximum valid 64-bit value) */
+  MAX: bigint
+}
+
+type TsidState = {
+  node: number | undefined
+  msecs: number
+  counter: number
+}
+
+/**
+ * Module-level state for the lazily-initialized persistent node ID and the
+ * per-millisecond-reset counter.
+ *
+ * IMPORTANT: This state persists across all tsid() calls in the module's lifetime.
+ * - In serverless/edge functions with warm starts, state persists between invocations.
+ * - For isolated state, pass explicit `msecs`, `epoch`, `node`, `nodeBits`, or
+ *   `counter` via options - doing so bypasses `state` entirely.
+ * - Tests should mock Date.now() or provide explicit options for deterministic behavior.
+ */
+const state: TsidState = {
+  node: undefined,
+  msecs: -Infinity,
+  counter: 0,
+}
+
+function pack(msecsDiff: bigint, node: number, counterBits: number, counter: number): bigint {
+  return (msecsDiff << BigInt(RANDOM_BITS)) | (BigInt(node) << BigInt(counterBits)) | BigInt(counter)
+}
+
+function writeTsidBytes(value: bigint, buf?: Uint8Array, offset = 0): Uint8Array {
+  if (!buf) {
+    buf = new Uint8Array(TSID_BYTES)
+    offset = 0
+  } else if (offset < 0 || offset + TSID_BYTES > buf.length) {
+    throw new BufferError(
+      'TSID_BUFFER_OUT_OF_BOUNDS',
+      `TSID byte range ${offset}:${offset + TSID_BYTES - 1} is out of buffer bounds`,
+    )
+  }
+
+  for (let i = 0; i < TSID_BYTES; i += 1) {
+    buf[offset + i] = Number((value >> BigInt((TSID_BYTES - 1 - i) * 8)) & 0xffn)
+  }
+
+  return buf
+}
+
+/*
+ * Overload: no buffer => return a TSID bigint.
+ */
+function tsidFn(options?: TsidOptions, buf?: undefined, offset?: number): bigint
+/*
+ * Overload: caller provides a buffer slice to fill with TSID bytes.
+ */
+function tsidFn<TBuf extends Uint8Array = Uint8Array>(
+  options: TsidOptions | undefined,
+  buf: TBuf,
+  offset?: number,
+): TBuf
+function tsidFn<TBuf extends Uint8Array = Uint8Array>(options?: TsidOptions, buf?: TBuf, offset = 0): bigint | TBuf {
+  let msecsDiff: bigint
+  let node: number
+  let counterBits: number
+  let counter: number
+
+  if (options) {
+    const nodeBits = options.nodeBits ?? DEFAULT_NODE_BITS
+    if (nodeBits < 0 || nodeBits > MAX_NODE_BITS) {
+      throw new InvalidInputError('TSID_NODE_BITS_OUT_OF_RANGE', `nodeBits must be between 0 and ${MAX_NODE_BITS}`)
+    }
+    counterBits = RANDOM_BITS - nodeBits
+    const nodeMask = (1 << nodeBits) - 1
+    const counterMask = (1 << counterBits) - 1
+
+    const optNode = options.node
+    if (optNode !== undefined) {
+      if (optNode < 0 || optNode > nodeMask) {
+        throw new InvalidInputError('TSID_NODE_OUT_OF_RANGE', `node must be between 0 and ${nodeMask}`)
+      }
+      node = optNode
+    } else {
+      node = randomUint32() & nodeMask
+    }
+
+    const optCounter = options.counter
+    if (optCounter !== undefined) {
+      if (optCounter < 0 || optCounter > counterMask) {
+        throw new InvalidInputError('TSID_COUNTER_OUT_OF_RANGE', `counter must be between 0 and ${counterMask}`)
+      }
+      counter = optCounter
+    } else {
+      counter = randomUint32() & counterMask
+    }
+
+    const epoch = options.epoch ?? TSID_EPOCH
+    const msecs = options.msecs ?? Date.now()
+    const diff = BigInt(msecs) - BigInt(epoch)
+    if (diff < 0n || diff > MAX_TIMESTAMP_DIFF) {
+      throw new InvalidInputError(
+        'TSID_TIMESTAMP_OUT_OF_RANGE',
+        `msecs - epoch must be between 0 and ${MAX_TIMESTAMP_DIFF}`,
+      )
+    }
+    msecsDiff = diff
+  } else {
+    // Lazily initialize the persistent node ID on first no-option call.
+    if (state.node === undefined) {
+      state.node = randomUint32() & DEFAULT_NODE_MASK
+    }
+    node = state.node
+    counterBits = DEFAULT_COUNTER_BITS
+
+    /**
+     * Note: by default, Cloudflare Workers "freezes" time during request handling
+     * to prevent side-channel attacks, so Date.now() returns the same value for
+     * the entire duration of a request. Monotonic ordering within such a request
+     * relies entirely on the counter (and its clock-drift-ahead overflow below).
+     */
+    const now = Date.now()
+    if (now > state.msecs) {
+      state.msecs = now
+      state.counter = randomUint32() & DEFAULT_COUNTER_MASK
+    } else {
+      state.counter += 1
+      if (state.counter > DEFAULT_COUNTER_MASK) {
+        // Counter overflowed within this real millisecond: advance the internal
+        // virtual timestamp ahead of wall-clock time rather than throwing. A
+        // 12-bit counter (4096 values/ms) is a realistic throughput ceiling.
+        state.msecs += 1
+        state.counter = 0
+      }
+    }
+    counter = state.counter
+    msecsDiff = BigInt(state.msecs) - BigInt(TSID_EPOCH)
+  }
+
+  const packed = pack(msecsDiff, node, counterBits, counter)
+
+  if (buf) {
+    writeTsidBytes(packed, buf, offset)
+    return buf
+  }
+
+  return packed
+}
+
+/**
+ * Convert a TSID bigint to 8 bytes.
+ */
+function toBytes(id: bigint): Uint8Array {
+  return writeTsidBytes(id)
+}
+
+/**
+ * Convert 8 bytes to a TSID bigint.
+ */
+function fromBytes(bytes: Uint8Array): bigint {
+  if (bytes.length !== TSID_BYTES) {
+    throw new BufferError(
+      'TSID_BYTES_INVALID_LENGTH',
+      `TSID bytes must be exactly ${TSID_BYTES} bytes, got ${bytes.length}`,
+    )
+  }
+
+  let value = 0n
+  for (let i = 0; i < TSID_BYTES; i += 1) {
+    value = (value << 8n) | BigInt(bytes[i])
+  }
+  return value
+}
+
+/**
+ * Extract the timestamp (milliseconds since Unix epoch) from a TSID.
+ * The epoch is not self-describing in the packed value - pass the same
+ * `epoch` used at generation time if it was overridden from the default.
+ */
+function timestamp(id: bigint, epoch: number = TSID_EPOCH): number {
+  return epoch + Number(id >> BigInt(RANDOM_BITS))
+}
+
+/**
+ * Validate that a value is a TSID bigint within the 64-bit range.
+ */
+function isValid(id: unknown): id is bigint {
+  return typeof id === 'bigint' && id >= 0n && id <= MAX
+}
+
+const NIL = 0n
+const MAX = (1n << 64n) - 1n
+
+/**
+ * Generate a TSID bigint or write the bytes into a buffer.
+ *
+ * TSID (Time-Sorted Unique Identifier) is a 64-bit Snowflake-style identifier
+ * combining a millisecond timestamp, a node ID, and a per-millisecond counter.
+ * Unlike every other uniku generator, it returns a `bigint` by default, since
+ * TSID's entire value proposition is native numeric storage (e.g. a database
+ * BIGINT primary key).
+ *
+ * @example
+ * ```ts
+ * import { tsid } from 'uniku/tsid'
+ *
+ * const id = tsid()
+ * // => 862301223059968074n
+ *
+ * // Canonical string form
+ * const str = tsid.toString(id)
+ * // => "0QXW2CK4XZM2A"
+ * tsid.fromString(str) === id // true
+ *
+ * // Extract timestamp
+ * const ts = tsid.timestamp(id)
+ * console.log(new Date(ts))
+ *
+ * // Validate
+ * tsid.isValid(id) // true
+ *
+ * // Convert to/from bytes (8 bytes)
+ * const bytes = tsid.toBytes(id)
+ * const restored = tsid.fromBytes(bytes)
+ * ```
+ */
+export const tsid: Tsid = Object.assign(tsidFn, {
+  toBytes,
+  fromBytes,
+  toString: encodeTsidString,
+  fromString: decodeTsidString,
+  timestamp,
+  isValid,
+  NIL,
+  MAX,
+})
+
+export { BufferError, InvalidInputError, ParseError, UniqueIdError } from '../errors'

package/build/errors.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"errors.d.mts","names":["code: string"],"sources":["../src/errors.ts"],"sourcesContent":[],"mappings":";;AAKA;AAaA;AAcA;AAcA;uBAzCsB,aAAA,SAAsB,KAAA;;;;;;;;cAa/B,iBAAA,SAA0B,aAAA;;;;;;;;cAc1B,UAAA,SAAmB,aAAA;;;;;;;;cAcnB,WAAA,SAAoB,aAAA"}

package/build/random-CGMm8owG.mjs

@@ -1,2 +0,0 @@
-const e=globalThis.crypto.getRandomValues.bind(globalThis.crypto),t=new Uint8Array(256);let n=256;function r(){e(t),n=0}function i(){n>252&&r();let e=t[n]*16777216+t[n+1]*65536+t[n+2]*256+t[n+3]>>>0;return n+=4,e}function a(){n>240&&r();let e=n;return n+=16,t.subarray(e,n)}export{a as n,i as t};
-//# sourceMappingURL=random-CGMm8owG.mjs.map