uniku 0.4.3 → 0.6.0

package/src/nanoid/nanoid.ts

@@ -41,8 +41,8 @@ function defaultAlphabetFromPool(size: number): string {
 export type NanoidOptions = {
   /**
    * Random bytes for deterministic output (testing).
-   * For power-of-2 alphabets (2, 4, 8, 16, 32, 64, 128, 256): exactly `size` bytes needed.
-   * For other alphabets: ~size * 2 bytes needed (rejection sampling).
+   * For power-of-2 alphabets (2, 4, 8, 16, 32, 64, 128, 256): exactly `length` bytes needed.
+   * For other alphabets: ~length * 2 bytes needed (rejection sampling).
    */
   random?: Uint8Array
   /**
@@ -53,6 +53,13 @@ export type NanoidOptions = {
   /**
    * Length of generated ID. Default: 21. Maximum: 2048.
    */
+  length?: number
+  /**
+   * Deprecated alias for `length`.
+   *
+   * @deprecated Use `length` instead. Will be removed in `1.0.0-rc.1`.
+   */
+  // TODO(v1-rc.1): remove this alias (tracked in docs/STABILITY.md).
   size?: number
 }
 
@@ -75,36 +82,45 @@ export type Nanoid = {
  */
 function validateAlphabet(alphabet: string): void {
   if (alphabet.length < 2) {
-    throw new InvalidInputError('NANOID_ALPHABET_TOO_SHORT', 'Alphabet must contain at least 2 characters')
+    throw new InvalidInputError('ALPHABET_OUT_OF_RANGE', 'Alphabet must contain at least 2 characters', {
+      strategy: 'nanoid',
+    })
   }
   if (alphabet.length > 256) {
-    throw new InvalidInputError('NANOID_ALPHABET_TOO_LONG', 'Alphabet must not exceed 256 characters')
+    throw new InvalidInputError('ALPHABET_OUT_OF_RANGE', 'Alphabet must not exceed 256 characters', {
+      strategy: 'nanoid',
+    })
   }
   const seen = new Set<string>()
   for (const char of alphabet) {
     const code = char.charCodeAt(0)
     if (code < 32 || code > 126) {
       throw new InvalidInputError(
-        'NANOID_ALPHABET_INVALID_CHAR',
+        'ALPHABET_INVALID_CHAR',
         'Alphabet must contain only printable ASCII characters (32-126)',
+        {
+          strategy: 'nanoid',
+        },
       )
     }
     if (seen.has(char)) {
-      throw new InvalidInputError('NANOID_ALPHABET_DUPLICATE', `Duplicate character in alphabet: "${char}"`)
+      throw new InvalidInputError('ALPHABET_DUPLICATE', `Duplicate character in alphabet: "${char}"`, {
+        strategy: 'nanoid',
+      })
     }
     seen.add(char)
   }
 }
 
 /**
- * Validate size parameter
+ * Validate length parameter
  */
-function validateSize(size: number): void {
+function validateLength(size: number): void {
   if (!Number.isInteger(size) || size < 0) {
-    throw new InvalidInputError('NANOID_SIZE_INVALID', 'Size must be a non-negative integer')
+    throw new InvalidInputError('LENGTH_OUT_OF_RANGE', 'Length must be a non-negative integer', { strategy: 'nanoid' })
   }
   if (size > MAX_SIZE) {
-    throw new InvalidInputError('NANOID_SIZE_TOO_LARGE', `Size must not exceed ${MAX_SIZE}`)
+    throw new InvalidInputError('LENGTH_OUT_OF_RANGE', `Length must not exceed ${MAX_SIZE}`, { strategy: 'nanoid' })
   }
 }
 
@@ -126,7 +142,12 @@ function nanoidFn(sizeOrOptions?: number | NanoidOptions): string {
   if (typeof sizeOrOptions === 'number') {
     size = sizeOrOptions
   } else {
-    size = sizeOrOptions.size ?? DEFAULT_SIZE
+    if (sizeOrOptions.length !== undefined && sizeOrOptions.size !== undefined) {
+      throw new InvalidInputError('CONFLICTING_OPTIONS', 'Pass only one of `length` or `size`, not both', {
+        strategy: 'nanoid',
+      })
+    }
+    size = sizeOrOptions.length ?? sizeOrOptions.size ?? DEFAULT_SIZE
     alphabet = sizeOrOptions.alphabet ?? URL_ALPHABET
     randomBytes = sizeOrOptions.random
     if (sizeOrOptions.alphabet !== undefined) {
@@ -134,7 +155,7 @@ function nanoidFn(sizeOrOptions?: number | NanoidOptions): string {
     }
   }
 
-  validateSize(size)
+  validateLength(size)
 
   if (size === 0) return ''
 
@@ -150,8 +171,9 @@ function nanoidFn(sizeOrOptions?: number | NanoidOptions): string {
     const mask = alphabetLen - 1
     if (randomBytes && randomBytes.length < size) {
       throw new InvalidInputError(
-        'NANOID_RANDOM_BYTES_INSUFFICIENT',
+        'RANDOM_BYTES_TOO_SHORT',
         `Insufficient random bytes: need ${size}, have ${randomBytes.length}`,
+        { strategy: 'nanoid' },
       )
     }
     const bytes = randomBytes?.subarray(0, size) ?? globalThis.crypto.getRandomValues(new Uint8Array(size))
@@ -176,8 +198,9 @@ function nanoidFn(sizeOrOptions?: number | NanoidOptions): string {
     if (randomBytes) {
       if (randomBytes.length - randomOffset < step) {
         throw new InvalidInputError(
-          'NANOID_RANDOM_BYTES_INSUFFICIENT',
+          'RANDOM_BYTES_TOO_SHORT',
           `Insufficient random bytes: need at least ${step} more, have ${randomBytes.length - randomOffset}`,
+          { strategy: 'nanoid' },
         )
       }
       bytes = randomBytes.subarray(randomOffset, randomOffset + step)
@@ -227,7 +250,7 @@ function isValid(id: unknown): id is string {
  * // => "V1StGXR8_Z5jdHi6B-myT"
  * ```
  *
- * @example Custom size
+ * @example Custom length
  * ```ts
  * const shortId = nanoid(10)
  * // => "IRFa-VaY2b"
@@ -235,7 +258,7 @@ function isValid(id: unknown): id is string {
  *
  * @example Custom alphabet (hex)
  * ```ts
- * const hexId = nanoid({ alphabet: '0123456789abcdef', size: 12 })
+ * const hexId = nanoid({ alphabet: '0123456789abcdef', length: 12 })
  * // => "4f90d13a42bc"
  * ```
  *
@@ -248,9 +271,9 @@ function isValid(id: unknown): id is string {
  * }
  * ```
  *
- * @throws {InvalidInputError} Size must be between 0 and 2048
+ * @throws {InvalidInputError} Length must be between 0 and 2048
  * @throws {InvalidInputError} Alphabet must contain 2-256 unique printable ASCII characters
- * @throws {InvalidInputError} Insufficient random bytes for requested size
+ * @throws {InvalidInputError} Insufficient random bytes for requested length
  */
 export const nanoid: Nanoid = Object.assign(nanoidFn, {
   isValid,

package/src/objectid/hex.ts

@@ -45,8 +45,9 @@ for (let i = 0; i < 6; i += 1) {
 export function encodeObjectIdHex(bytes: Uint8Array): string {
   if (bytes.length < OBJECTID_BYTES) {
     throw new BufferError(
-      'OBJECTID_BYTES_TOO_SHORT',
+      'BYTES_INVALID_LENGTH',
       `ObjectID bytes must be at least ${OBJECTID_BYTES} bytes, got ${bytes.length}`,
+      { strategy: 'objectid' },
     )
   }
 
@@ -63,8 +64,9 @@ export function encodeObjectIdHex(bytes: Uint8Array): string {
 export function decodeObjectIdHex(str: string): Uint8Array {
   if (str.length !== OBJECTID_STRING_LEN) {
     throw new ParseError(
-      'OBJECTID_INVALID_LENGTH',
+      'INVALID_LENGTH',
       `ObjectID string must be ${OBJECTID_STRING_LEN} characters, got ${str.length}`,
+      { strategy: 'objectid' },
     )
   }
 
@@ -76,10 +78,10 @@ export function decodeObjectIdHex(str: string): Uint8Array {
     const lo = DECODING[str.charCodeAt(loIndex)]
 
     if (hi === 255) {
-      throw new ParseError('OBJECTID_INVALID_CHAR', `Invalid ObjectID character: ${str[hiIndex]}`)
+      throw new ParseError('INVALID_CHAR', `Invalid ObjectID character: ${str[hiIndex]}`, { strategy: 'objectid' })
     }
     if (lo === 255) {
-      throw new ParseError('OBJECTID_INVALID_CHAR', `Invalid ObjectID character: ${str[loIndex]}`)
+      throw new ParseError('INVALID_CHAR', `Invalid ObjectID character: ${str[loIndex]}`, { strategy: 'objectid' })
     }
 
     bytes[i] = (hi << 4) | lo

package/src/objectid/objectid.ts

@@ -1,5 +1,6 @@
 import { writeTimestamp32 } from '../common/bytes'
 import { randomBytes, randomUint32 } from '../common/random'
+import { resolveTimestampSecs } from '../common/timestamp'
 import { isIntegerInRange, isWritableRange } from '../common/validation'
 import { BufferError, InvalidInputError } from '../errors'
 import { decodeObjectIdHex, encodeObjectIdHex } from './hex'
@@ -31,9 +32,17 @@ export type ObjectIdOptions = {
    */
   random?: Uint8Array
   /**
-   * Timestamp in seconds since Unix epoch.
-   * Defaults to Math.floor(Date.now() / 1000).
+   * Timestamp in milliseconds since the Unix epoch.
+   * Defaults to Date.now().
+   * ObjectID stores whole seconds, so sub-second precision is truncated.
    */
+  msecs?: number
+  /**
+   * Deprecated alias for `msecs`; timestamp in seconds since the Unix epoch.
+   *
+   * @deprecated Use `msecs` instead. Will be removed in `1.0.0-rc.1`.
+   */
+  // TODO(v1-rc.1): remove this alias (tracked in docs/STABILITY.md).
   secs?: number
   /**
    * 24-bit counter value (0 to 0xFFFFFF).
@@ -74,7 +83,7 @@ type ObjectIdState = {
  * - 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.
+ * - For isolated state, pass explicit `random`, `msecs`, or `counter` via options.
  * - Tests should mock Date.now() or provide explicit options for deterministic behavior.
  */
 const state: ObjectIdState = {
@@ -139,19 +148,21 @@ function objectIdFn<TBuf extends Uint8Array = Uint8Array>(
     const optRandom = options.random
     if (optRandom && optRandom.length < RANDOM_BYTES) {
       throw new InvalidInputError(
-        'OBJECTID_RANDOM_BYTES_TOO_SHORT',
+        'RANDOM_BYTES_TOO_SHORT',
         `Random bytes length must be >= ${RANDOM_BYTES} for ObjectID`,
+        {
+          strategy: 'objectid',
+        },
       )
     }
 
-    const optSecs = options.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 optSecs = resolveTimestampSecs(options, 0, MAX_SECS, 'objectid')
 
     const optCounter = options.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}`)
+      throw new InvalidInputError('COUNTER_OUT_OF_RANGE', `Counter must be between 0 and ${MAX_COUNTER}`, {
+        strategy: 'objectid',
+      })
     }
 
     // Options bypass persistent state entirely: every field is sourced fresh (given
@@ -187,8 +198,9 @@ function objectIdFn<TBuf extends Uint8Array = Uint8Array>(
   if (buf) {
     if (!isWritableRange(buf, offset, OBJECTID_BYTES)) {
       throw new BufferError(
-        'OBJECTID_BUFFER_OUT_OF_BOUNDS',
+        'BUFFER_OUT_OF_BOUNDS',
         `ObjectID byte range ${offset}:${offset + OBJECTID_BYTES - 1} is out of buffer bounds`,
+        { strategy: 'objectid' },
       )
     }
     writeObjectIdBytesUnchecked(secs, random, counter, buf, offset)
@@ -213,8 +225,9 @@ function toBytes(id: string): Uint8Array {
 function fromBytes(bytes: Uint8Array): string {
   if (bytes.length !== OBJECTID_BYTES) {
     throw new BufferError(
-      'OBJECTID_BYTES_INVALID_LENGTH',
+      'BYTES_INVALID_LENGTH',
       `ObjectID bytes must be exactly ${OBJECTID_BYTES} bytes, got ${bytes.length}`,
+      { strategy: 'objectid' },
     )
   }
   return encodeObjectIdHex(bytes)

package/src/tsid/crockford64.ts

@@ -53,7 +53,9 @@ export function encodeTsidString(value: bigint): string {
  */
 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}`)
+    throw new ParseError('INVALID_LENGTH', `TSID string must be ${TSID_STRING_LEN} characters, got ${str.length}`, {
+      strategy: 'tsid',
+    })
   }
 
   let value = 0n
@@ -61,13 +63,12 @@ export function decodeTsidString(str: string): bigint {
     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]}`)
+      throw new ParseError('INVALID_CHAR', `Invalid TSID character: ${str[i]}`, { strategy: 'tsid' })
     }
     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]}`,
-      )
+      throw new ParseError('VALUE_OUT_OF_RANGE', `TSID leading character must be one of 0-9, A-F, got: ${str[i]}`, {
+        strategy: 'tsid',
+      })
     }
     value = (value << 5n) | BigInt(group)
   }

package/src/tsid/tsid.ts

@@ -128,7 +128,9 @@ type ResolvedTsidOptions = {
 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}`)
+    throw new InvalidInputError('NODE_BITS_OUT_OF_RANGE', `nodeBits must be between 0 and ${MAX_NODE_BITS}`, {
+      strategy: 'tsid',
+    })
   }
 
   const counterBits = RANDOM_BITS - nodeBits
@@ -136,28 +138,29 @@ function resolveTsidOptions(options: TsidOptions): ResolvedTsidOptions {
   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}`)
+    throw new InvalidInputError('NODE_OUT_OF_RANGE', `node must be between 0 and ${nodeMask}`, { strategy: 'tsid' })
   }
 
   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}`)
+    throw new InvalidInputError('COUNTER_OUT_OF_RANGE', `counter must be between 0 and ${counterMask}`, {
+      strategy: 'tsid',
+    })
   }
 
   const epoch = options.epoch ?? TSID_EPOCH
   if (!Number.isInteger(epoch)) {
-    throw new InvalidInputError('TSID_EPOCH_INVALID', 'epoch must be a finite integer')
+    throw new InvalidInputError('EPOCH_INVALID', 'epoch must be a finite integer', { strategy: 'tsid' })
   }
   const msecs = options.msecs ?? Date.now()
   if (!Number.isInteger(msecs)) {
-    throw new InvalidInputError('TSID_TIMESTAMP_INVALID', 'msecs must be a finite integer')
+    throw new InvalidInputError('TIMESTAMP_OUT_OF_RANGE', 'msecs must be a finite integer', { strategy: 'tsid' })
   }
   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}`,
-    )
+    throw new InvalidInputError('TIMESTAMP_OUT_OF_RANGE', `msecs - epoch must be between 0 and ${MAX_TIMESTAMP_DIFF}`, {
+      strategy: 'tsid',
+    })
   }
 
   return {
@@ -229,8 +232,9 @@ function tsidFn<TBuf extends Uint8Array = Uint8Array>(options?: TsidOptions, buf
   if (buf) {
     if (!isWritableRange(buf, offset, TSID_BYTES)) {
       throw new BufferError(
-        'TSID_BUFFER_OUT_OF_BOUNDS',
+        'BUFFER_OUT_OF_BOUNDS',
         `TSID byte range ${offset}:${offset + TSID_BYTES - 1} is out of buffer bounds`,
+        { strategy: 'tsid' },
       )
     }
     writeTsidBytesUnchecked(packed, buf, offset)
@@ -256,8 +260,9 @@ function toBytes(id: bigint): Uint8Array {
 function fromBytes(bytes: Uint8Array): bigint {
   if (bytes.length !== TSID_BYTES) {
     throw new BufferError(
-      'TSID_BYTES_INVALID_LENGTH',
+      'BYTES_INVALID_LENGTH',
       `TSID bytes must be exactly ${TSID_BYTES} bytes, got ${bytes.length}`,
+      { strategy: 'tsid' },
     )
   }
 
@@ -276,7 +281,7 @@ function fromBytes(bytes: Uint8Array): bigint {
 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')
+    throw new InvalidInputError('EPOCH_INVALID', 'epoch must be a finite integer', { strategy: 'tsid' })
   }
   return epoch + Number(id >> BigInt(RANDOM_BITS))
 }
@@ -293,7 +298,9 @@ 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}`)
+    throw new InvalidInputError('VALUE_OUT_OF_RANGE', `TSID value must be between ${NIL} and ${MAX}`, {
+      strategy: 'tsid',
+    })
   }
 }
 

package/src/typeid/typeid.ts

@@ -1,4 +1,5 @@
-import { InvalidInputError, ParseError } from '../errors'
+import { isIntegerInRange, isWritableRange } from '../common/validation'
+import { BufferError, InvalidInputError, ParseError } from '../errors'
 import type { UuidV7Options } from '../uuid/v7'
 import { uuidv7 } from '../uuid/v7'
 
@@ -7,6 +8,15 @@ 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
+  /** Generate a TypeID with explicit options or write its 16 canonical UUID v7 bytes into a caller-owned buffer. */
+  <TBuf extends Uint8Array = Uint8Array>(
+    prefix: string,
+    options: TypeidOptions | undefined,
+    buf: TBuf,
+    offset?: number,
+  ): TBuf
+  /** Generate a TypeID string with optional timestamp, counter, or random bytes. */
+  (prefix: string, options?: TypeidOptions, buf?: undefined, offset?: number): 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. */
@@ -27,6 +37,11 @@ export type Typeid = {
 
 const TYPEID_SUFFIX_LENGTH = 26
 const TYPEID_UUID_BYTE_LENGTH = 16
+// 48-bit UUID v7 timestamp capacity, mirrored from uuid/v7 alongside the
+// 32-bit counter capacity, so option validation is attributed to the typeid
+// boundary instead of leaking `strategy: 'uuid'` through delegation.
+const MAX_MSECS = 0xffffffffffff
+const MAX_COUNTER = 0xffffffff
 const TYPEID_ALPHABET = '0123456789abcdefghjkmnpqrstvwxyz'
 
 const BASE32_DECODE: number[] = Array.from({ length: 128 }, () => -1)
@@ -46,7 +61,9 @@ function assertValidPrefix(prefix: string): void {
   }
 
   if (prefix.length > 63) {
-    throw new InvalidInputError('TYPEID_PREFIX_TOO_LONG', 'TypeID prefix must be at most 63 characters')
+    throw new InvalidInputError('PREFIX_TOO_LONG', 'TypeID prefix must be at most 63 characters', {
+      strategy: 'typeid',
+    })
   }
 
   for (let i = 0; i < prefix.length; i += 1) {
@@ -56,13 +73,16 @@ function assertValidPrefix(prefix: string): void {
 
     if (!isLowercaseLetter && !isUnderscore) {
       throw new InvalidInputError(
-        'TYPEID_PREFIX_INVALID_CHARACTER',
+        'PREFIX_INVALID_CHAR',
         'TypeID prefix must contain only lowercase ASCII letters and underscores',
+        { strategy: 'typeid' },
       )
     }
 
     if ((i === 0 || i === prefix.length - 1) && !isLowercaseLetter) {
-      throw new InvalidInputError('TYPEID_PREFIX_INVALID_BOUNDARY', 'TypeID prefix must start and end with a-z')
+      throw new InvalidInputError('PREFIX_INVALID_BOUNDARY', 'TypeID prefix must start and end with a-z', {
+        strategy: 'typeid',
+      })
     }
   }
 }
@@ -72,10 +92,9 @@ function decodeSuffixValue(suffix: string, index: number): number {
   const value = code < BASE32_DECODE.length ? BASE32_DECODE[code] : -1
 
   if (value === -1) {
-    throw new ParseError(
-      'TYPEID_SUFFIX_INVALID_CHARACTER',
-      `TypeID suffix contains invalid character at position ${index}`,
-    )
+    throw new ParseError('INVALID_CHAR', `TypeID suffix contains invalid character at position ${index}`, {
+      strategy: 'typeid',
+    })
   }
 
   return value
@@ -83,17 +102,23 @@ function decodeSuffixValue(suffix: string, index: number): number {
 
 function assertValidSuffixShape(suffix: string): void {
   if (suffix.length !== TYPEID_SUFFIX_LENGTH) {
-    throw new ParseError('TYPEID_SUFFIX_INVALID_LENGTH', `TypeID suffix must be 26 characters, got ${suffix.length}`)
+    throw new ParseError('INVALID_LENGTH', `TypeID suffix must be 26 characters, got ${suffix.length}`, {
+      strategy: 'typeid',
+    })
   }
 
   if (suffix[0] > '7') {
-    throw new ParseError('TYPEID_SUFFIX_OVERFLOW', 'TypeID suffix must encode a 128-bit value')
+    throw new ParseError('VALUE_OUT_OF_RANGE', 'TypeID suffix must encode a 128-bit value', {
+      strategy: 'typeid',
+    })
   }
 }
 
 function encodeBytesToSuffix(bytes: Uint8Array): string {
   if (bytes.length !== TYPEID_UUID_BYTE_LENGTH) {
-    throw new InvalidInputError('TYPEID_UUID_BYTES_INVALID_LENGTH', `UUID bytes must be 16 bytes, got ${bytes.length}`)
+    throw new InvalidInputError('BYTES_INVALID_LENGTH', `UUID bytes must be 16 bytes, got ${bytes.length}`, {
+      strategy: 'typeid',
+    })
   }
 
   return (
@@ -157,11 +182,15 @@ function decodeSuffixToBytes(suffix: string): Uint8Array {
 
 function assertUuidV7Bytes(bytes: Uint8Array): void {
   if (bytes.length !== TYPEID_UUID_BYTE_LENGTH) {
-    throw new InvalidInputError('TYPEID_UUID_BYTES_INVALID_LENGTH', `UUID bytes must be 16 bytes, got ${bytes.length}`)
+    throw new InvalidInputError('BYTES_INVALID_LENGTH', `UUID bytes must be 16 bytes, got ${bytes.length}`, {
+      strategy: 'typeid',
+    })
   }
 
   if (bytes[6] >> 4 !== 7 || (bytes[8] & 0xc0) !== 0x80) {
-    throw new InvalidInputError('TYPEID_UUID_NOT_V7', 'TypeID UUID bytes must encode a UUID v7 value')
+    throw new InvalidInputError('UUID_NOT_V7', 'TypeID UUID bytes must encode a UUID v7 value', {
+      strategy: 'typeid',
+    })
   }
 }
 
@@ -173,7 +202,7 @@ function uuidV7BytesFromSuffix(suffix: string): Uint8Array {
 
 function uuidV7BytesFromUuid(uuid: string): Uint8Array {
   if (!uuidv7.isValid(uuid)) {
-    throw new InvalidInputError('TYPEID_UUID_NOT_V7', 'TypeID can only wrap UUID v7 values')
+    throw new InvalidInputError('UUID_NOT_V7', 'TypeID can only wrap UUID v7 values', { strategy: 'typeid' })
   }
 
   return uuidv7.toBytes(uuid)
@@ -183,7 +212,7 @@ function parseTypeid(id: string): ParsedTypeid {
   const separatorIndex = id.lastIndexOf('_')
 
   if (separatorIndex === 0) {
-    throw new ParseError('TYPEID_INVALID_FORMAT', 'TypeID must not start with "_"')
+    throw new ParseError('INVALID_FORMAT', 'TypeID must not start with "_"', { strategy: 'typeid' })
   }
 
   const prefix = separatorIndex === -1 ? '' : id.slice(0, separatorIndex)
@@ -213,7 +242,68 @@ function timestampFromUuidV7Bytes(bytes: Uint8Array): number {
   return msecs
 }
 
-function typeidFn(prefix: string, options?: TypeidOptions): string {
+/**
+ * Mirror uuid/v7's option validation at the typeid boundary, so failures are
+ * attributed to `strategy: 'typeid'` instead of leaking `strategy: 'uuid'`
+ * through delegation.
+ */
+function validateTypeidOptions(options: TypeidOptions): void {
+  const msecs = options.msecs
+  if (msecs !== undefined && !isIntegerInRange(msecs, 0, MAX_MSECS)) {
+    throw new InvalidInputError('TIMESTAMP_OUT_OF_RANGE', `Timestamp must be an integer between 0 and ${MAX_MSECS}`, {
+      strategy: 'typeid',
+    })
+  }
+
+  if (options.counter !== undefined && options.seq !== undefined) {
+    throw new InvalidInputError('CONFLICTING_OPTIONS', 'Pass only one of `counter` or `seq`, not both', {
+      strategy: 'typeid',
+    })
+  }
+  const counter = options.counter ?? options.seq
+  if (counter !== undefined && !isIntegerInRange(counter, 0, MAX_COUNTER)) {
+    throw new InvalidInputError('COUNTER_OUT_OF_RANGE', `Counter must be an integer between 0 and ${MAX_COUNTER}`, {
+      strategy: 'typeid',
+    })
+  }
+
+  const random = options.random
+  if (random && random.length < TYPEID_UUID_BYTE_LENGTH) {
+    throw new InvalidInputError('RANDOM_BYTES_TOO_SHORT', `Random bytes length must be >= ${TYPEID_UUID_BYTE_LENGTH}`, {
+      strategy: 'typeid',
+    })
+  }
+}
+
+function typeidFn(prefix: string, options?: TypeidOptions, buf?: undefined, offset?: number): string
+function typeidFn<TBuf extends Uint8Array = Uint8Array>(
+  prefix: string,
+  options: TypeidOptions | undefined,
+  buf: TBuf,
+  offset?: number,
+): TBuf
+function typeidFn<TBuf extends Uint8Array = Uint8Array>(
+  prefix: string,
+  options?: TypeidOptions,
+  buf?: TBuf,
+  offset = 0,
+): string | TBuf {
+  if (options !== undefined) {
+    validateTypeidOptions(options)
+  }
+
+  if (buf) {
+    if (!isWritableRange(buf, offset, TYPEID_UUID_BYTE_LENGTH)) {
+      throw new BufferError(
+        'BUFFER_OUT_OF_BOUNDS',
+        `TypeID byte range ${offset}:${offset + TYPEID_UUID_BYTE_LENGTH - 1} is out of buffer bounds`,
+        { strategy: 'typeid' },
+      )
+    }
+    assertValidPrefix(prefix)
+    return uuidv7(options, buf, offset)
+  }
+
   const bytes = uuidv7(options, new Uint8Array(TYPEID_UUID_BYTE_LENGTH))
   return formatTypeidFromUuidV7Bytes(prefix, bytes)
 }

package/src/ulid/crockford.ts

@@ -25,11 +25,11 @@ const TIME_LEN = 10
 const ULID_LEN = 26
 
 function invalidCharError(str: string, index: number): ParseError {
-  return new ParseError('ULID_INVALID_CHAR', `Invalid ULID character: ${str[index]}`)
+  return new ParseError('INVALID_CHAR', `Invalid ULID character: ${str[index]}`, { strategy: 'ulid' })
 }
 
 function timestampOverflowError(): ParseError {
-  return new ParseError('ULID_TIMESTAMP_OVERFLOW', 'ULID timestamp exceeds 48 bits')
+  return new ParseError('TIMESTAMP_OUT_OF_RANGE', 'ULID timestamp exceeds 48 bits', { strategy: 'ulid' })
 }
 
 function decodeTimeChars(str: string): number {
@@ -106,7 +106,7 @@ export function encodeRandom(bytes: Uint8Array): string {
  */
 export function decodeTime(str: string): number {
   if (str.length !== TIME_LEN) {
-    throw new ParseError('ULID_INVALID_LENGTH', `ULID timestamp must be ${TIME_LEN} characters`)
+    throw new ParseError('INVALID_LENGTH', `ULID timestamp must be ${TIME_LEN} characters`, { strategy: 'ulid' })
   }
   return decodeTimeChars(str)
 }
@@ -116,7 +116,7 @@ export function decodeTime(str: string): number {
  */
 export function decodeUlidTime(str: string): number {
   if (str.length !== ULID_LEN) {
-    throw new ParseError('ULID_INVALID_LENGTH', `ULID string must be ${ULID_LEN} characters`)
+    throw new ParseError('INVALID_LENGTH', `ULID string must be ${ULID_LEN} characters`, { strategy: 'ulid' })
   }
   return decodeTimeChars(str)
 }
@@ -127,7 +127,7 @@ export function decodeUlidTime(str: string): number {
  */
 export function decodeToBytes(str: string): Uint8Array {
   if (str.length !== ULID_LEN) {
-    throw new ParseError('ULID_INVALID_LENGTH', `ULID string must be ${ULID_LEN} characters`)
+    throw new ParseError('INVALID_LENGTH', `ULID string must be ${ULID_LEN} characters`, { strategy: 'ulid' })
   }
 
   const bytes = new Uint8Array(16)
@@ -232,7 +232,9 @@ export function decodeToBytes(str: string): Uint8Array {
  */
 export function bytesToUlid(bytes: Uint8Array): string {
   if (bytes.length !== 16) {
-    throw new BufferError('ULID_BYTES_INVALID_LENGTH', `ULID bytes must be exactly 16 bytes, got ${bytes.length}`)
+    throw new BufferError('BYTES_INVALID_LENGTH', `ULID bytes must be exactly 16 bytes, got ${bytes.length}`, {
+      strategy: 'ulid',
+    })
   }
 
   // Timestamp: bytes 0-5 -> 10 characters