uniku 0.2.0 → 0.3.1

package/src/objectid/objectid.ts

@@ -1,5 +1,6 @@
 import { writeTimestamp32 } from '../common/bytes'
 import { randomBytes, randomUint32 } from '../common/random'
+import { isIntegerInRange, isWritableRange } from '../common/validation'
 import { BufferError, InvalidInputError } from '../errors'
 import { decodeObjectIdHex, encodeObjectIdHex } from './hex'
 
@@ -85,17 +86,13 @@ function freshRandom(): Uint8Array {
   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`,
-    )
-  }
-
+function writeObjectIdBytesUnchecked(
+  secs: number,
+  random: Uint8Array,
+  counter: number,
+  buf: Uint8Array,
+  offset: number,
+): void {
   // Timestamp (32-bit big-endian seconds since Unix epoch) -> bytes 0-3
   writeTimestamp32(buf, offset, secs)
 
@@ -108,8 +105,6 @@ function objectIdBytes(secs: number, random: Uint8Array, counter: number, buf?:
   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
 }
 
 /*
@@ -143,12 +138,12 @@ function objectIdFn<TBuf extends Uint8Array = Uint8Array>(
     }
 
     const optSecs = options.secs
-    if (optSecs !== undefined && (optSecs < 0 || optSecs > MAX_SECS)) {
+    if (optSecs !== undefined && !isIntegerInRange(optSecs, 0, 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)) {
+    if (optCounter !== undefined && !isIntegerInRange(optCounter, 0, MAX_COUNTER)) {
       throw new InvalidInputError('OBJECTID_COUNTER_OUT_OF_RANGE', `Counter must be between 0 and ${MAX_COUNTER}`)
     }
 
@@ -183,11 +178,18 @@ function objectIdFn<TBuf extends Uint8Array = Uint8Array>(
   }
 
   if (buf) {
-    objectIdBytes(secs, random, counter, buf, offset)
+    if (!isWritableRange(buf, offset, OBJECTID_BYTES)) {
+      throw new BufferError(
+        'OBJECTID_BUFFER_OUT_OF_BOUNDS',
+        `ObjectID byte range ${offset}:${offset + OBJECTID_BYTES - 1} is out of buffer bounds`,
+      )
+    }
+    writeObjectIdBytesUnchecked(secs, random, counter, buf, offset)
     return buf
   }
 
-  const bytes = objectIdBytes(secs, random, counter)
+  const bytes = new Uint8Array(OBJECTID_BYTES)
+  writeObjectIdBytesUnchecked(secs, random, counter, bytes, 0)
   return encodeObjectIdHex(bytes)
 }
 
@@ -202,6 +204,12 @@ function toBytes(id: string): Uint8Array {
  * Convert 12 bytes to an ObjectID hex string.
  */
 function fromBytes(bytes: Uint8Array): string {
+  if (bytes.length !== OBJECTID_BYTES) {
+    throw new BufferError(
+      'OBJECTID_BYTES_INVALID_LENGTH',
+      `ObjectID bytes must be exactly ${OBJECTID_BYTES} bytes, got ${bytes.length}`,
+    )
+  }
   return encodeObjectIdHex(bytes)
 }
 

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,340 @@
+import { randomUint32 } from '../common/random'
+import { isIntegerInRange, isWritableRange } from '../common/validation'
+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 writeTsidBytesUnchecked(value: bigint, buf: Uint8Array, offset: number): void {
+  for (let i = 0; i < TSID_BYTES; i += 1) {
+    buf[offset + i] = Number((value >> BigInt((TSID_BYTES - 1 - i) * 8)) & 0xffn)
+  }
+}
+
+type ResolvedTsidOptions = {
+  msecsDiff: bigint
+  node: number
+  counterBits: number
+  counter: number
+}
+
+function resolveTsidOptions(options: TsidOptions): ResolvedTsidOptions {
+  const nodeBits = options.nodeBits ?? DEFAULT_NODE_BITS
+  if (!isIntegerInRange(nodeBits, 0, MAX_NODE_BITS)) {
+    throw new InvalidInputError('TSID_NODE_BITS_OUT_OF_RANGE', `nodeBits must be between 0 and ${MAX_NODE_BITS}`)
+  }
+
+  const counterBits = RANDOM_BITS - nodeBits
+  const nodeMask = (1 << nodeBits) - 1
+  const counterMask = (1 << counterBits) - 1
+  const optNode = options.node
+  if (optNode !== undefined && !isIntegerInRange(optNode, 0, nodeMask)) {
+    throw new InvalidInputError('TSID_NODE_OUT_OF_RANGE', `node must be between 0 and ${nodeMask}`)
+  }
+
+  const optCounter = options.counter
+  if (optCounter !== undefined && !isIntegerInRange(optCounter, 0, counterMask)) {
+    throw new InvalidInputError('TSID_COUNTER_OUT_OF_RANGE', `counter must be between 0 and ${counterMask}`)
+  }
+
+  const epoch = options.epoch ?? TSID_EPOCH
+  if (!Number.isInteger(epoch)) {
+    throw new InvalidInputError('TSID_EPOCH_INVALID', 'epoch must be a finite integer')
+  }
+  const msecs = options.msecs ?? Date.now()
+  if (!Number.isInteger(msecs)) {
+    throw new InvalidInputError('TSID_TIMESTAMP_INVALID', 'msecs must be a finite integer')
+  }
+  const msecsDiff = BigInt(msecs) - BigInt(epoch)
+  if (msecsDiff < 0n || msecsDiff > MAX_TIMESTAMP_DIFF) {
+    throw new InvalidInputError(
+      'TSID_TIMESTAMP_OUT_OF_RANGE',
+      `msecs - epoch must be between 0 and ${MAX_TIMESTAMP_DIFF}`,
+    )
+  }
+
+  return {
+    msecsDiff,
+    node: optNode ?? randomUint32() & nodeMask,
+    counterBits,
+    counter: optCounter ?? randomUint32() & counterMask,
+  }
+}
+
+/*
+ * 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 resolved = resolveTsidOptions(options)
+    msecsDiff = resolved.msecsDiff
+    node = resolved.node
+    counterBits = resolved.counterBits
+    counter = resolved.counter
+  } 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) {
+    if (!isWritableRange(buf, offset, TSID_BYTES)) {
+      throw new BufferError(
+        'TSID_BUFFER_OUT_OF_BOUNDS',
+        `TSID byte range ${offset}:${offset + TSID_BYTES - 1} is out of buffer bounds`,
+      )
+    }
+    writeTsidBytesUnchecked(packed, buf, offset)
+    return buf
+  }
+
+  return packed
+}
+
+/**
+ * Convert a TSID bigint to 8 bytes.
+ */
+function toBytes(id: bigint): Uint8Array {
+  assertValidTsid(id)
+  const bytes = new Uint8Array(TSID_BYTES)
+  writeTsidBytesUnchecked(id, bytes, 0)
+  return bytes
+}
+
+/**
+ * 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 {
+  assertValidTsid(id)
+  if (!Number.isInteger(epoch)) {
+    throw new InvalidInputError('TSID_EPOCH_INVALID', 'epoch must be a finite integer')
+  }
+  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
+
+function assertValidTsid(id: bigint): void {
+  if (id < NIL || id > MAX) {
+    throw new InvalidInputError('TSID_VALUE_OUT_OF_RANGE', `TSID value must be between ${NIL} and ${MAX}`)
+  }
+}
+
+function toString(id: bigint): string {
+  assertValidTsid(id)
+  return encodeTsidString(id)
+}
+
+/**
+ * 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,
+  fromString: decodeTsidString,
+  timestamp,
+  isValid,
+  NIL,
+  MAX,
+})
+
+export { BufferError, InvalidInputError, ParseError, UniqueIdError } from '../errors'

package/src/ulid/crockford.ts

@@ -231,8 +231,8 @@ export function decodeToBytes(str: string): Uint8Array {
  * Encode 16 bytes to a 26-character ULID string.
  */
 export function bytesToUlid(bytes: Uint8Array): string {
-  if (bytes.length < 16) {
-    throw new BufferError('ULID_BYTES_TOO_SHORT', 'Byte array must be at least 16 bytes')
+  if (bytes.length !== 16) {
+    throw new BufferError('ULID_BYTES_INVALID_LENGTH', `ULID bytes must be exactly 16 bytes, got ${bytes.length}`)
   }
 
   // Timestamp: bytes 0-5 -> 10 characters

package/src/ulid/ulid.ts

@@ -1,5 +1,6 @@
 import { incrementBytesInPlace, writeTimestamp48 } from '../common/bytes'
 import { rng } from '../common/random'
+import { isIntegerInRange, isWritableRange } from '../common/validation'
 import { BufferError, InvalidInputError } from '../errors'
 import { bytesToUlid, decodeToBytes, decodeUlidTime, encodeRandom, encodeTime } from './crockford'
 
@@ -32,6 +33,9 @@ export type Ulid = {
 
 // Validation regex: first char [0-7] to prevent overflow, rest from Crockford alphabet
 const ULID_REGEX = /^[0-7][0-9A-HJKMNP-TV-Z]{25}$/i
+const ULID_BYTES = 16
+const RANDOM_BYTES = 10
+const MAX_MSECS = 0xffffffffffff
 
 type UlidState = {
   msecs: number
@@ -48,29 +52,27 @@ type UlidState = {
  */
 const state: UlidState = {
   msecs: -Infinity,
-  lastRandom: new Uint8Array(10),
+  lastRandom: new Uint8Array(RANDOM_BYTES),
 }
 
-function ulidBytes(time: number, random: Uint8Array, buf?: Uint8Array, offset = 0): Uint8Array {
-  if (!buf) {
-    buf = new Uint8Array(16)
-    offset = 0
-  } else if (offset < 0 || offset + 16 > buf.length) {
-    throw new BufferError(
-      'ULID_BUFFER_OUT_OF_BOUNDS',
-      `ULID byte range ${offset}:${offset + 15} is out of buffer bounds`,
-    )
-  }
-
+function writeUlidBytesUnchecked(time: number, random: Uint8Array, buf: Uint8Array, offset: number): void {
   // Timestamp (48-bit big-endian milliseconds since Unix epoch) -> bytes 0-5
   writeTimestamp48(buf, offset, time)
 
   // Random (80 bits) -> bytes 6-15
-  for (let i = 0; i < 10; i += 1) {
+  for (let i = 0; i < RANDOM_BYTES; i += 1) {
     buf[offset + 6 + i] = random[i]
   }
+}
 
-  return buf
+function writeUlidBytes(time: number, random: Uint8Array, buf: Uint8Array, offset: number): void {
+  if (!isWritableRange(buf, offset, ULID_BYTES)) {
+    throw new BufferError(
+      'ULID_BUFFER_OUT_OF_BOUNDS',
+      `ULID byte range ${offset}:${offset + ULID_BYTES - 1} is out of buffer bounds`,
+    )
+  }
+  writeUlidBytesUnchecked(time, random, buf, offset)
 }
 
 /*
@@ -97,27 +99,36 @@ function ulidFn<TBuf extends Uint8Array = Uint8Array>(options?: UlidOptions, buf
    * - all ULIDs generated within a single request will have the same timestamp.
    * - the monotonic ordering will rely entirely on incrementing the random portion.
    */
-  const defaultTime = Date.now()
-
   if (options) {
     // Explicit options provided - use them directly without monotonic state
-    time = options.msecs ?? defaultTime
-    if (options.random) {
-      if (options.random.length < 10) {
-        throw new InvalidInputError('ULID_RANDOM_BYTES_TOO_SHORT', 'Random bytes length must be >= 10 for ULID')
+    const optMsecs = options.msecs
+    if (optMsecs !== undefined && !isIntegerInRange(optMsecs, 0, MAX_MSECS)) {
+      throw new InvalidInputError(
+        'ULID_TIMESTAMP_OUT_OF_RANGE',
+        `Timestamp must be an integer between 0 and ${MAX_MSECS}`,
+      )
+    }
+    time = optMsecs ?? Date.now()
+    const optRandom = options.random
+    if (optRandom) {
+      if (optRandom.length < RANDOM_BYTES) {
+        throw new InvalidInputError(
+          'ULID_RANDOM_BYTES_TOO_SHORT',
+          `Random bytes length must be >= ${RANDOM_BYTES} for ULID`,
+        )
       }
-      random = options.random
+      random = optRandom
     } else {
       random = rng()
     }
   } else {
-    time = defaultTime
+    time = Date.now()
 
     if (time > state.msecs) {
       // New millisecond: generate fresh random
       random = rng()
       state.msecs = time
-      state.lastRandom.set(random.subarray(0, 10))
+      state.lastRandom.set(random.subarray(0, RANDOM_BYTES))
     } else {
       // Same millisecond or clock rollback: preserve last timestamp and increment random portion.
       time = state.msecs
@@ -133,7 +144,7 @@ function ulidFn<TBuf extends Uint8Array = Uint8Array>(options?: UlidOptions, buf
   }
 
   if (buf) {
-    ulidBytes(time, random, buf, offset)
+    writeUlidBytes(time, random, buf, offset)
     return buf
   }
 

package/src/uuid/common/uuid.ts

@@ -1,4 +1,4 @@
-import { ParseError } from '../../errors'
+import { BufferError, ParseError } from '../../errors'
 import { hexValue } from './hex'
 
 const UUID_BYTE_LENGTH = 16
@@ -93,6 +93,17 @@ const UUID_CHAR_IS_HIGH: boolean[] = [
 const HEX_TABLE: string[] = Array.from({ length: 256 }, (_, i) => i.toString(16).padStart(2, '0'))
 
 export function formatUuid(bytes: Uint8Array): string {
+  if (bytes.length !== UUID_BYTE_LENGTH) {
+    throw new BufferError(
+      'UUID_BYTES_INVALID_LENGTH',
+      `UUID bytes must be exactly ${UUID_BYTE_LENGTH} bytes, got ${bytes.length}`,
+    )
+  }
+
+  return formatUuidUnchecked(bytes)
+}
+
+export function formatUuidUnchecked(bytes: Uint8Array): string {
   // Direct string concatenation - optimized for V8's string builder.
   // This approach avoids loop overhead and intermediate allocations.
   // See: https://github.com/uuidjs/uuid/pull/434