uniku 0.3.0 → 0.3.2

package/src/ksuid/ksuid.ts

@@ -1,5 +1,6 @@
 import { writeTimestamp32 } from '../common/bytes'
 import { rng } from '../common/random'
+import { isWritableRange } from '../common/validation'
 import { BufferError, InvalidInputError } from '../errors'
 import { decodeBase62, encodeBase62 } from './base62'
 
@@ -44,12 +45,19 @@ export type KsuidOptions = {
 }
 
 export type Ksuid = {
+  /** Generate a time-ordered KSUID string. */
   (): string
+  /** Generate a KSUID with explicit options or write its 20 canonical bytes into a caller-owned buffer. */
   <TBuf extends Uint8Array = Uint8Array>(options: KsuidOptions | undefined, buf: TBuf, offset?: number): TBuf
+  /** Generate a KSUID string with optional timestamp or random payload bytes. */
   (options?: KsuidOptions, buf?: undefined, offset?: number): string
+  /** Convert a KSUID string to its canonical 20-byte representation. */
   toBytes(id: string): Uint8Array
+  /** Convert 20 canonical KSUID bytes to a KSUID string. */
   fromBytes(bytes: Uint8Array): string
+  /** Read the embedded Unix timestamp in milliseconds. */
   timestamp(id: string): number
+  /** Return whether a value is a syntactically valid KSUID string. */
   isValid(id: unknown): id is string
   /** The nil KSUID (all zeros) */
   NIL: string
@@ -58,19 +66,9 @@ export type Ksuid = {
 }
 
 /**
- * Write KSUID bytes to a buffer.
+ * Write already-validated KSUID fields to a buffer.
  */
-function ksuidBytes(timestamp: number, payload: Uint8Array, buf?: Uint8Array, offset = 0): Uint8Array {
-  if (!buf) {
-    buf = new Uint8Array(KSUID_BYTES)
-    offset = 0
-  } else if (offset < 0 || offset + KSUID_BYTES > buf.length) {
-    throw new BufferError(
-      'KSUID_BUFFER_OUT_OF_BOUNDS',
-      `KSUID byte range ${offset}:${offset + KSUID_BYTES - 1} is out of buffer bounds`,
-    )
-  }
-
+function writeKsuidBytesUnchecked(timestamp: number, payload: Uint8Array, buf: Uint8Array, offset: number): void {
   // Timestamp (32-bit big-endian seconds since KSUID epoch) -> bytes 0-3
   writeTimestamp32(buf, offset, timestamp)
 
@@ -78,8 +76,6 @@ function ksuidBytes(timestamp: number, payload: Uint8Array, buf?: Uint8Array, of
   for (let i = 0; i < PAYLOAD_BYTES; i += 1) {
     buf[offset + TIMESTAMP_BYTES + i] = payload[i]
   }
-
-  return buf
 }
 
 /*
@@ -103,7 +99,7 @@ function ksuidFn<TBuf extends Uint8Array = Uint8Array>(options?: KsuidOptions, b
   let timestamp: number
   const secs = options?.secs
   if (secs !== undefined) {
-    if (secs < KSUID_EPOCH) {
+    if (!Number.isInteger(secs) || secs < KSUID_EPOCH) {
       throw new InvalidInputError('KSUID_TIMESTAMP_TOO_LOW', 'Timestamp must be >= KSUID epoch')
     }
 
@@ -126,11 +122,18 @@ function ksuidFn<TBuf extends Uint8Array = Uint8Array>(options?: KsuidOptions, b
   const payload = random ?? rng()
 
   if (buf) {
-    ksuidBytes(timestamp, payload, buf, offset)
+    if (!isWritableRange(buf, offset, KSUID_BYTES)) {
+      throw new BufferError(
+        'KSUID_BUFFER_OUT_OF_BOUNDS',
+        `KSUID byte range ${offset}:${offset + KSUID_BYTES - 1} is out of buffer bounds`,
+      )
+    }
+    writeKsuidBytesUnchecked(timestamp, payload, buf, offset)
     return buf
   }
 
-  const bytes = ksuidBytes(timestamp, payload)
+  const bytes = new Uint8Array(KSUID_BYTES)
+  writeKsuidBytesUnchecked(timestamp, payload, bytes, 0)
 
   // String mode: create bytes then encode to Base62
   return encodeBase62(bytes)
@@ -150,6 +153,12 @@ function toBytes(id: string): Uint8Array {
  * Convert 20 bytes to a KSUID string.
  */
 function fromBytes(bytes: Uint8Array): string {
+  if (bytes.length !== KSUID_BYTES) {
+    throw new BufferError(
+      'KSUID_BYTES_INVALID_LENGTH',
+      `KSUID bytes must be exactly ${KSUID_BYTES} bytes, got ${bytes.length}`,
+    )
+  }
   return encodeBase62(bytes)
 }
 

package/src/nanoid/nanoid.ts

@@ -55,11 +55,11 @@ export type NanoidOptions = {
 }
 
 export type Nanoid = {
-  /** Generate nanoid with default settings */
+  /** Generate a Nanoid with the default URL-safe alphabet and 21-character length. */
   (): string
-  /** Generate nanoid with custom size */
+  /** Generate a Nanoid with the default alphabet and a custom length. */
   (size: number): string
-  /** Generate nanoid with options */
+  /** Generate a Nanoid with a custom alphabet, length, or deterministic random bytes. */
   (options: NanoidOptions): string
   /**
    * Validate a nanoid string against the default URL-safe alphabet.

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'
 
@@ -41,12 +42,19 @@ export type ObjectIdOptions = {
 }
 
 export type ObjectId = {
+  /** Generate a MongoDB-compatible ObjectID string. */
   (): string
+  /** Generate an ObjectID with explicit options or write its 12 canonical bytes into a caller-owned buffer. */
   <TBuf extends Uint8Array = Uint8Array>(options: ObjectIdOptions | undefined, buf: TBuf, offset?: number): TBuf
+  /** Generate an ObjectID string with optional timestamp, random field, or counter. */
   (options?: ObjectIdOptions, buf?: undefined, offset?: number): string
+  /** Convert an ObjectID string to its canonical 12-byte representation. */
   toBytes(id: string): Uint8Array
+  /** Convert 12 canonical ObjectID bytes to an ObjectID string. */
   fromBytes(bytes: Uint8Array): string
+  /** Read the embedded Unix timestamp in milliseconds. */
   timestamp(id: string): number
+  /** Return whether a value is a syntactically valid ObjectID string. */
   isValid(id: unknown): id is string
   /** The nil ObjectID (all zeros) */
   NIL: string
@@ -85,17 +93,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 +112,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 +145,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 +185,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 +211,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/tsid.ts

@@ -1,4 +1,5 @@
 import { randomUint32 } from '../common/random'
+import { isIntegerInRange, isWritableRange } from '../common/validation'
 import { BufferError, InvalidInputError } from '../errors'
 import { decodeTsidString, encodeTsidString } from './crockford64'
 
@@ -61,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
@@ -102,22 +112,60 @@ function pack(msecsDiff: bigint, node: number, counterBits: number, counter: num
   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`,
-    )
-  }
-
+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}`)
+  }
 
-  return buf
+  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,
+  }
 }
 
 /*
@@ -139,44 +187,11 @@ function tsidFn<TBuf extends Uint8Array = Uint8Array>(options?: TsidOptions, buf
   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
+    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) {
@@ -212,7 +227,13 @@ function tsidFn<TBuf extends Uint8Array = Uint8Array>(options?: TsidOptions, buf
   const packed = pack(msecsDiff, node, counterBits, counter)
 
   if (buf) {
-    writeTsidBytes(packed, buf, offset)
+    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
   }
 
@@ -223,7 +244,10 @@ function tsidFn<TBuf extends Uint8Array = Uint8Array>(options?: TsidOptions, buf
  * Convert a TSID bigint to 8 bytes.
  */
 function toBytes(id: bigint): Uint8Array {
-  return writeTsidBytes(id)
+  assertValidTsid(id)
+  const bytes = new Uint8Array(TSID_BYTES)
+  writeTsidBytesUnchecked(id, bytes, 0)
+  return bytes
 }
 
 /**
@@ -250,6 +274,10 @@ function fromBytes(bytes: Uint8Array): bigint {
  * `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))
 }
 
@@ -263,6 +291,17 @@ function isValid(id: unknown): id is bigint {
 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.
  *
@@ -299,7 +338,7 @@ const MAX = (1n << 64n) - 1n
 export const tsid: Tsid = Object.assign(tsidFn, {
   toBytes,
   fromBytes,
-  toString: encodeTsidString,
+  toString,
   fromString: decodeTsidString,
   timestamp,
   isValid,

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/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'
 
@@ -17,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
@@ -32,6 +40,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 +59,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 +106,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 +151,7 @@ function ulidFn<TBuf extends Uint8Array = Uint8Array>(options?: UlidOptions, buf
   }
 
   if (buf) {
-    ulidBytes(time, random, buf, offset)
+    writeUlidBytes(time, random, buf, offset)
     return buf
   }
 
@@ -172,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/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