uniku 0.4.3 → 0.5.0

package/build/uuid/v7.d.mts

@@ -1,4 +1,4 @@
-import { i as UniqueIdError, n as InvalidInputError, r as ParseError, t as BufferError } from "../errors-Dgoyi-ci.mjs";
+import { a as ParseError, i as InvalidInputError, o as UniqueIdError, t as BufferError } from "../errors-Da-8dh4J.mjs";
 
 //#region src/uuid/v7.d.ts
 type UuidV7Options = {
@@ -13,13 +13,19 @@ type UuidV7Options = {
   */
   msecs?: number;
   /**
+  * Unsigned 32-bit counter value.
+  */
+  counter?: number;
+  /**
   * Unsigned 32-bit sequence value.
+  *
+  * @deprecated Use `counter` instead. Will be removed at v1-rc.
   */
   seq?: number;
 };
 type UuidV7 = {
   /** Generate a time-ordered UUID v7 string. */(): string; /** Generate a UUID v7 with explicit options or write its 16 canonical bytes into a caller-owned buffer. */
-  <TBuf extends Uint8Array = Uint8Array>(options: UuidV7Options | undefined, buf: TBuf, offset?: number): TBuf; /** Generate a UUID v7 string with optional timestamp, sequence, or random bytes. */
+  <TBuf extends Uint8Array = Uint8Array>(options: UuidV7Options | undefined, buf: TBuf, offset?: number): TBuf; /** Generate a UUID v7 string with optional timestamp, counter, or random bytes. */
   (options?: UuidV7Options, buf?: undefined, offset?: number): string; /** Convert a UUID v7 string to its canonical 16-byte representation. */
   toBytes(id: string): Uint8Array; /** Convert 16 canonical UUID bytes to a UUID v7 string. */
   fromBytes(bytes: Uint8Array): string; /** Read the embedded Unix timestamp in milliseconds. */

package/build/uuid/v7.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"v7.d.mts","names":[],"sources":["../../src/uuid/v7.ts"],"mappings":";;;KAKY,aAAA;;;AAAZ;;EAKE,MAAA,GAAS,UAAA;EAAA;;;;EAKT,KAAA;EAIA;AAAA;AAGF;EAHE,GAAA;AAAA;AAAA,KAGU,MAAA;;gBAII,UAAA,GAAa,UAAA,EAAY,OAAA,EAAS,aAAA,cAA2B,GAAA,EAAK,IAAA,EAAM,MAAA,YAAkB,IAAA;GAEvG,OAAA,GAAU,aAAA,EAAe,GAAA,cAAiB,MAAA;EAE3C,OAAA,CAAQ,EAAA,WAAa,UAAA,EAEJ;EAAjB,SAAA,CAAU,KAAA,EAAO,UAAA;EAEjB,SAAA,CAAU,EAAA;EAEV,OAAA,CAAQ,EAAA,YAAc,EAAA;EAEtB,GAAA;EAEA,GAAA;AAAA;;;;;;;;;;;;;;;;;;AAAA;AA2KF;;;;AAAqB;;;;cAAR,MAAA,EAAQ,MAAA"}
+{"version":3,"file":"v7.d.mts","names":[],"sources":["../../src/uuid/v7.ts"],"mappings":";;;KAKY,aAAA;;;AAAZ;;EAKE,MAAA,GAAS,UAAA;EAAA;;;;EAKT,KAAA;;;AAWA;EAPA,OAAA;EAUU;;;;;EAHV,GAAA;AAAA;AAAA,KAGU,MAAA;4DAUO;EAAA,cANH,UAAA,GAAa,UAAA,EAAY,OAAA,EAAS,aAAA,cAA2B,GAAA,EAAK,IAAA,EAAM,MAAA,YAAkB,IAAA;GAEvG,OAAA,GAAU,aAAA,EAAe,GAAA,cAAiB,MAAA;EAE3C,OAAA,CAAQ,EAAA,WAAa,UAAA;EAErB,SAAA,CAAU,KAAA,EAAO,UAAA;EAEjB,SAAA,CAAU,EAAA;EAEV,OAAA,CAAQ,EAAA,YAAc,EAAA;EAEtB,GAAA;EAEA,GAAA;AAAA;;;;;;;;;;;;;AAAA;AAoLF;;;;AAAqB;;;;;;;;;cAAR,MAAA,EAAQ,MAAA"}

package/build/uuid/v7.mjs

@@ -1,2 +1,2 @@
-import{r as e}from"../random-Chp-Nkzi.mjs";import{n as t,t as n}from"../validation-CTNpXm94.mjs";import{BufferError as r,InvalidInputError as i,ParseError as a,UniqueIdError as o}from"../errors.mjs";import{n as s,r as c,t as l}from"../uuid-CnQIYoQi.mjs";const u=/^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i,d=0xffffffffffff,f=4294967295,p=new Uint8Array(16),m={msecs:-1/0,seq:0};function h(e,t,n,r,i){r[i++]=t/1099511627776&255,r[i++]=t/4294967296&255,r[i++]=t/16777216&255,r[i++]=t/65536&255,r[i++]=t/256&255,r[i++]=t&255,r[i++]=112|n>>>28&15,r[i++]=n>>>20&255,r[i++]=128|n>>>14&63,r[i++]=n>>>6&255,r[i++]=n<<2&255|e[10]&3,r[i++]=e[11],r[i++]=e[12],r[i++]=e[13],r[i++]=e[14],r[i++]=e[15]}function g(e,n,i,a,o){if(!t(a,o,16))throw new r(`UUID_BUFFER_OUT_OF_BOUNDS`,`UUID byte range ${o}:${o+16-1} is out of buffer bounds`);h(e,n,i,a,o)}function _(t,r,a=0){let o=t.msecs;if(o!==void 0&&!n(o,0,d))throw new i(`UUID_TIMESTAMP_OUT_OF_RANGE`,`Timestamp must be an integer between 0 and ${d}`);let c=t.seq;if(c!==void 0&&!n(c,0,f))throw new i(`UUID_SEQUENCE_OUT_OF_RANGE`,`Sequence must be an integer between 0 and ${f}`);let l=t.random;if(l&&l.length<16)throw new i(`UUID_RANDOM_BYTES_TOO_SHORT`,`Random bytes length must be >= 16`);let u=l??e(),m=o??Date.now(),_=c??u[6]<<23|u[7]<<16|u[8]<<8|u[9];return r?(g(u,m,_,r,a),r):(h(u,m,_,p,0),s(p))}function v(t,n,r){if(t)return _(t,n,r);let i=Date.now(),a=e();return i>m.msecs?(m.seq=a[6]<<23|a[7]<<16|a[8]<<8|a[9],m.msecs=i):(m.seq=m.seq+1|0,m.seq<0&&(m.seq=0,m.msecs++)),n?(g(a,m.msecs,m.seq,n,r??0),n):(h(a,m.msecs,m.seq,p,0),s(p))}function y(e){let t=c(e),n=0;for(let e=0;e<6;e+=1)n=n*256+t[e];return n}function b(e){return typeof e==`string`&&u.test(e)}const x=Object.assign(v,{toBytes:c,fromBytes:l,timestamp:y,isValid:b,NIL:`00000000-0000-0000-0000-000000000000`,MAX:`ffffffff-ffff-ffff-ffff-ffffffffffff`});export{r as BufferError,i as InvalidInputError,a as ParseError,o as UniqueIdError,x as uuidv7};
+import{r as e}from"../random-Chp-Nkzi.mjs";import{n as t,t as n}from"../validation-CTNpXm94.mjs";import{BufferError as r,InvalidInputError as i,ParseError as a,UniqueIdError as o}from"../errors.mjs";import{n as s,r as c,t as l}from"../uuid-BPebYihz.mjs";const u=/^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i,d=0xffffffffffff,f=4294967295,p=new Uint8Array(16),m={msecs:-1/0,seq:0};function h(e,t,n,r,i){r[i++]=t/1099511627776&255,r[i++]=t/4294967296&255,r[i++]=t/16777216&255,r[i++]=t/65536&255,r[i++]=t/256&255,r[i++]=t&255,r[i++]=112|n>>>28&15,r[i++]=n>>>20&255,r[i++]=128|n>>>14&63,r[i++]=n>>>6&255,r[i++]=n<<2&255|e[10]&3,r[i++]=e[11],r[i++]=e[12],r[i++]=e[13],r[i++]=e[14],r[i++]=e[15]}function g(e,n,i,a,o){if(!t(a,o,16))throw new r(`BUFFER_OUT_OF_BOUNDS`,`UUID byte range ${o}:${o+16-1} is out of buffer bounds`,{strategy:`uuid`});h(e,n,i,a,o)}function _(t,r,a=0){let o=t.msecs;if(o!==void 0&&!n(o,0,d))throw new i(`TIMESTAMP_OUT_OF_RANGE`,`Timestamp must be an integer between 0 and ${d}`,{strategy:`uuid`});if(t.counter!==void 0&&t.seq!==void 0)throw new i(`CONFLICTING_OPTIONS`,"Pass only one of `counter` or `seq`, not both",{strategy:`uuid`});let c=t.counter??t.seq;if(c!==void 0&&!n(c,0,f))throw new i(`COUNTER_OUT_OF_RANGE`,`Counter must be an integer between 0 and ${f}`,{strategy:`uuid`});let l=t.random;if(l&&l.length<16)throw new i(`RANDOM_BYTES_TOO_SHORT`,`Random bytes length must be >= 16`,{strategy:`uuid`});let u=l??e(),m=o??Date.now(),_=c??u[6]<<23|u[7]<<16|u[8]<<8|u[9];return r?(g(u,m,_,r,a),r):(h(u,m,_,p,0),s(p))}function v(t,n,r){if(t)return _(t,n,r);let i=Date.now(),a=e();return i>m.msecs?(m.seq=a[6]<<23|a[7]<<16|a[8]<<8|a[9],m.msecs=i):(m.seq=m.seq+1|0,m.seq<0&&(m.seq=0,m.msecs++)),n?(g(a,m.msecs,m.seq,n,r??0),n):(h(a,m.msecs,m.seq,p,0),s(p))}function y(e){let t=c(e),n=0;for(let e=0;e<6;e+=1)n=n*256+t[e];return n}function b(e){return typeof e==`string`&&u.test(e)}const x=Object.assign(v,{toBytes:c,fromBytes:l,timestamp:y,isValid:b,NIL:`00000000-0000-0000-0000-000000000000`,MAX:`ffffffff-ffff-ffff-ffff-ffffffffffff`});export{r as BufferError,i as InvalidInputError,a as ParseError,o as UniqueIdError,x as uuidv7};
 //# sourceMappingURL=v7.mjs.map

package/build/uuid/v7.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"v7.mjs","names":[],"sources":["../../src/uuid/v7.ts"],"sourcesContent":["import { rng } from '../common/random'\nimport { isIntegerInRange, isWritableRange } from '../common/validation'\nimport { BufferError, InvalidInputError } from '../errors'\nimport { formatUuid, formatUuidUnchecked, parseUuid } from './common/uuid'\n\nexport type UuidV7Options = {\n  /**\n   * 16 bytes of random data to use for UUID generation.\n   * Note: Several bytes will be overwritten with timestamp, version, and variant data.\n   */\n  random?: Uint8Array\n  /**\n   * Timestamp in milliseconds since Unix epoch.\n   * Defaults to Date.now().\n   */\n  msecs?: number\n  /**\n   * Unsigned 32-bit sequence value.\n   */\n  seq?: number\n}\n\nexport type UuidV7 = {\n  /** Generate a time-ordered UUID v7 string. */\n  (): string\n  /** Generate a UUID v7 with explicit options or write its 16 canonical bytes into a caller-owned buffer. */\n  <TBuf extends Uint8Array = Uint8Array>(options: UuidV7Options | undefined, buf: TBuf, offset?: number): TBuf\n  /** Generate a UUID v7 string with optional timestamp, sequence, or random bytes. */\n  (options?: UuidV7Options, buf?: undefined, offset?: number): string\n  /** Convert a UUID v7 string to its canonical 16-byte representation. */\n  toBytes(id: string): Uint8Array\n  /** Convert 16 canonical UUID bytes to a UUID v7 string. */\n  fromBytes(bytes: Uint8Array): string\n  /** Read the embedded Unix timestamp in milliseconds. */\n  timestamp(id: string): number\n  /** Return whether a value is a syntactically valid UUID v7 string. */\n  isValid(id: unknown): id is string\n  /** The nil UUID (all zeros) */\n  NIL: string\n  /** The max UUID (all ones) */\n  MAX: string\n}\n\nconst UUID_V7_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i\nconst UUID_BYTES = 16\nconst MAX_MSECS = 0xffffffffffff\nconst MAX_SEQ = 0xffffffff\n\n// Reusable buffer for string output path - avoids allocation per call.\n// Safe because bytes are consumed synchronously by formatUuidUnchecked().\nconst reusableBuf = new Uint8Array(UUID_BYTES)\n\ntype V7State = {\n  msecs: number\n  seq: number\n}\n\n/**\n * Module-level state for maintaining monotonic ordering within the same millisecond.\n *\n * IMPORTANT: This state persists across all uuidv7() calls in the module's lifetime.\n * - In serverless/edge functions with warm starts, state persists between invocations.\n * - For isolated state, pass explicit `msecs` and `seq` via options.\n * - Tests should mock Date.now() or provide explicit options for deterministic behavior.\n */\nconst state: V7State = { msecs: -Infinity, seq: 0 }\n\nfunction writeV7BytesUnchecked(rnds: Uint8Array, msecs: number, seq: number, buf: Uint8Array, offset: number): void {\n  // Keep this inline on the UUID v7 hot path. Using writeTimestamp48() here\n  // benchmarked slower than the direct byte writes.\n  buf[offset++] = (msecs / 0x10000000000) & 0xff\n  buf[offset++] = (msecs / 0x100000000) & 0xff\n  buf[offset++] = (msecs / 0x1000000) & 0xff\n  buf[offset++] = (msecs / 0x10000) & 0xff\n  buf[offset++] = (msecs / 0x100) & 0xff\n  buf[offset++] = msecs & 0xff\n\n  // Set version (7) and variant (10xx), then pack sequence and random tail bytes.\n  buf[offset++] = 0x70 | ((seq >>> 28) & 0x0f)\n  buf[offset++] = (seq >>> 20) & 0xff\n  buf[offset++] = 0x80 | ((seq >>> 14) & 0x3f)\n  buf[offset++] = (seq >>> 6) & 0xff\n  // Lower seq bits plus 2 random bits to complete the 128-bit payload.\n  buf[offset++] = ((seq << 2) & 0xff) | (rnds[10] & 0x03)\n  buf[offset++] = rnds[11]\n  buf[offset++] = rnds[12]\n  buf[offset++] = rnds[13]\n  buf[offset++] = rnds[14]\n  buf[offset++] = rnds[15]\n}\n\nfunction writeV7Bytes(rnds: Uint8Array, msecs: number, seq: number, buf: Uint8Array, offset: number): void {\n  if (!isWritableRange(buf, offset, UUID_BYTES)) {\n    throw new BufferError(\n      'UUID_BUFFER_OUT_OF_BOUNDS',\n      `UUID byte range ${offset}:${offset + UUID_BYTES - 1} is out of buffer bounds`,\n    )\n  }\n  writeV7BytesUnchecked(rnds, msecs, seq, buf, offset)\n}\n\nfunction v7WithOptions<TBuf extends Uint8Array = Uint8Array>(\n  options: UuidV7Options,\n  buf?: TBuf,\n  offset = 0,\n): string | TBuf {\n  const optMsecs = options.msecs\n  if (optMsecs !== undefined && !isIntegerInRange(optMsecs, 0, MAX_MSECS)) {\n    throw new InvalidInputError(\n      'UUID_TIMESTAMP_OUT_OF_RANGE',\n      `Timestamp must be an integer between 0 and ${MAX_MSECS}`,\n    )\n  }\n  const optSeq = options.seq\n  if (optSeq !== undefined && !isIntegerInRange(optSeq, 0, MAX_SEQ)) {\n    throw new InvalidInputError('UUID_SEQUENCE_OUT_OF_RANGE', `Sequence must be an integer between 0 and ${MAX_SEQ}`)\n  }\n  const optRandom = options.random\n  if (optRandom && optRandom.length < UUID_BYTES) {\n    throw new InvalidInputError('UUID_RANDOM_BYTES_TOO_SHORT', `Random bytes length must be >= ${UUID_BYTES}`)\n  }\n\n  const rnds = optRandom ?? rng()\n  const msecs = optMsecs ?? Date.now()\n  // Derive a 31-bit sequence if not provided by the caller, matching the default hot path.\n  const seq = optSeq ?? (rnds[6] << 23) | (rnds[7] << 16) | (rnds[8] << 8) | rnds[9]\n\n  if (buf) {\n    writeV7Bytes(rnds, msecs, seq, buf, offset)\n    return buf\n  }\n  writeV7BytesUnchecked(rnds, msecs, seq, reusableBuf, 0)\n  return formatUuidUnchecked(reusableBuf)\n}\n\n/*\n * Overload: no buffer => return a UUID string.\n */\nfunction v7(options?: UuidV7Options, buf?: undefined, offset?: number): string\n/*\n * Overload: caller provides a buffer slice to fill with UUID bytes.\n */\nfunction v7<TBuf extends Uint8Array = Uint8Array>(options: UuidV7Options | undefined, buf: TBuf, offset?: number): TBuf\nfunction v7<TBuf extends Uint8Array = Uint8Array>(options?: UuidV7Options, buf?: TBuf, offset?: number): string | TBuf {\n  if (options) {\n    return v7WithOptions(options, buf, offset)\n  }\n\n  // HOT PATH: Inline state management and byte generation for best performance\n  const now = Date.now()\n  const rnds = rng()\n\n  // Update state (inlined for performance)\n  if (now > state.msecs) {\n    state.seq = (rnds[6] << 23) | (rnds[7] << 16) | (rnds[8] << 8) | rnds[9]\n    state.msecs = now\n  } else {\n    state.seq = (state.seq + 1) | 0\n    if (state.seq < 0) {\n      state.seq = 0\n      state.msecs++\n    }\n  }\n\n  if (buf) {\n    writeV7Bytes(rnds, state.msecs, state.seq, buf, offset ?? 0)\n    return buf\n  }\n  writeV7BytesUnchecked(rnds, state.msecs, state.seq, reusableBuf, 0)\n  return formatUuidUnchecked(reusableBuf)\n}\n\nfunction timestamp(id: string): number {\n  const bytes = parseUuid(id)\n  let msecs = 0\n  for (let i = 0; i < 6; i += 1) {\n    msecs = msecs * 256 + bytes[i]\n  }\n  return msecs\n}\n\nfunction isValid(id: unknown): id is string {\n  return typeof id === 'string' && UUID_V7_REGEX.test(id)\n}\n\n/**\n * Generate a UUID v7 string or write the bytes into a buffer.\n *\n * UUID v7 is a time-ordered UUID that embeds a Unix timestamp in milliseconds,\n * making IDs naturally sortable by creation time. Ideal for database primary keys\n * where chronological ordering improves index performance.\n *\n * @example\n * ```ts\n * import { uuidv7 } from 'uniku/uuid/v7'\n *\n * const id = uuidv7()\n * // => \"018e5e5c-7c8a-7000-8000-000000000000\"\n *\n * // Extract timestamp\n * const ts = uuidv7.timestamp(id)\n * console.log(new Date(ts))\n *\n * // Validate\n * uuidv7.isValid(id) // true\n *\n * // Convert to/from bytes\n * const bytes = uuidv7.toBytes(id)\n * const restored = uuidv7.fromBytes(bytes)\n * ```\n */\nexport const uuidv7: UuidV7 = Object.assign(v7, {\n  toBytes: parseUuid,\n  fromBytes: formatUuid,\n  timestamp,\n  isValid,\n  NIL: '00000000-0000-0000-0000-000000000000',\n  MAX: 'ffffffff-ffff-ffff-ffff-ffffffffffff',\n})\n\nexport { BufferError, InvalidInputError, ParseError, UniqueIdError } from '../errors'\n"],"mappings":"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"}
+{"version":3,"file":"v7.mjs","names":[],"sources":["../../src/uuid/v7.ts"],"sourcesContent":["import { rng } from '../common/random'\nimport { isIntegerInRange, isWritableRange } from '../common/validation'\nimport { BufferError, InvalidInputError } from '../errors'\nimport { formatUuid, formatUuidUnchecked, parseUuid } from './common/uuid'\n\nexport type UuidV7Options = {\n  /**\n   * 16 bytes of random data to use for UUID generation.\n   * Note: Several bytes will be overwritten with timestamp, version, and variant data.\n   */\n  random?: Uint8Array\n  /**\n   * Timestamp in milliseconds since Unix epoch.\n   * Defaults to Date.now().\n   */\n  msecs?: number\n  /**\n   * Unsigned 32-bit counter value.\n   */\n  counter?: number\n  /**\n   * Unsigned 32-bit sequence value.\n   *\n   * @deprecated Use `counter` instead. Will be removed at v1-rc.\n   */\n  // TODO(v1-rc): remove this alias (tracked in docs/STABILITY.md).\n  seq?: number\n}\n\nexport type UuidV7 = {\n  /** Generate a time-ordered UUID v7 string. */\n  (): string\n  /** Generate a UUID v7 with explicit options or write its 16 canonical bytes into a caller-owned buffer. */\n  <TBuf extends Uint8Array = Uint8Array>(options: UuidV7Options | undefined, buf: TBuf, offset?: number): TBuf\n  /** Generate a UUID v7 string with optional timestamp, counter, or random bytes. */\n  (options?: UuidV7Options, buf?: undefined, offset?: number): string\n  /** Convert a UUID v7 string to its canonical 16-byte representation. */\n  toBytes(id: string): Uint8Array\n  /** Convert 16 canonical UUID bytes to a UUID v7 string. */\n  fromBytes(bytes: Uint8Array): string\n  /** Read the embedded Unix timestamp in milliseconds. */\n  timestamp(id: string): number\n  /** Return whether a value is a syntactically valid UUID v7 string. */\n  isValid(id: unknown): id is string\n  /** The nil UUID (all zeros) */\n  NIL: string\n  /** The max UUID (all ones) */\n  MAX: string\n}\n\nconst UUID_V7_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i\nconst UUID_BYTES = 16\nconst MAX_MSECS = 0xffffffffffff\nconst MAX_SEQ = 0xffffffff\n\n// Reusable buffer for string output path - avoids allocation per call.\n// Safe because bytes are consumed synchronously by formatUuidUnchecked().\nconst reusableBuf = new Uint8Array(UUID_BYTES)\n\ntype V7State = {\n  msecs: number\n  seq: number\n}\n\n/**\n * Module-level state for maintaining monotonic ordering within the same millisecond.\n *\n * IMPORTANT: This state persists across all uuidv7() calls in the module's lifetime.\n * - In serverless/edge functions with warm starts, state persists between invocations.\n * - For isolated state, pass explicit `msecs` and `seq` via options.\n * - Tests should mock Date.now() or provide explicit options for deterministic behavior.\n */\nconst state: V7State = { msecs: -Infinity, seq: 0 }\n\nfunction writeV7BytesUnchecked(rnds: Uint8Array, msecs: number, seq: number, buf: Uint8Array, offset: number): void {\n  // Keep this inline on the UUID v7 hot path. Using writeTimestamp48() here\n  // benchmarked slower than the direct byte writes.\n  buf[offset++] = (msecs / 0x10000000000) & 0xff\n  buf[offset++] = (msecs / 0x100000000) & 0xff\n  buf[offset++] = (msecs / 0x1000000) & 0xff\n  buf[offset++] = (msecs / 0x10000) & 0xff\n  buf[offset++] = (msecs / 0x100) & 0xff\n  buf[offset++] = msecs & 0xff\n\n  // Set version (7) and variant (10xx), then pack sequence and random tail bytes.\n  buf[offset++] = 0x70 | ((seq >>> 28) & 0x0f)\n  buf[offset++] = (seq >>> 20) & 0xff\n  buf[offset++] = 0x80 | ((seq >>> 14) & 0x3f)\n  buf[offset++] = (seq >>> 6) & 0xff\n  // Lower seq bits plus 2 random bits to complete the 128-bit payload.\n  buf[offset++] = ((seq << 2) & 0xff) | (rnds[10] & 0x03)\n  buf[offset++] = rnds[11]\n  buf[offset++] = rnds[12]\n  buf[offset++] = rnds[13]\n  buf[offset++] = rnds[14]\n  buf[offset++] = rnds[15]\n}\n\nfunction writeV7Bytes(rnds: Uint8Array, msecs: number, seq: number, buf: Uint8Array, offset: number): void {\n  if (!isWritableRange(buf, offset, UUID_BYTES)) {\n    throw new BufferError(\n      'BUFFER_OUT_OF_BOUNDS',\n      `UUID byte range ${offset}:${offset + UUID_BYTES - 1} is out of buffer bounds`,\n      { strategy: 'uuid' },\n    )\n  }\n  writeV7BytesUnchecked(rnds, msecs, seq, buf, offset)\n}\n\nfunction v7WithOptions<TBuf extends Uint8Array = Uint8Array>(\n  options: UuidV7Options,\n  buf?: TBuf,\n  offset = 0,\n): string | TBuf {\n  const optMsecs = options.msecs\n  if (optMsecs !== undefined && !isIntegerInRange(optMsecs, 0, MAX_MSECS)) {\n    throw new InvalidInputError('TIMESTAMP_OUT_OF_RANGE', `Timestamp must be an integer between 0 and ${MAX_MSECS}`, {\n      strategy: 'uuid',\n    })\n  }\n  if (options.counter !== undefined && options.seq !== undefined) {\n    throw new InvalidInputError('CONFLICTING_OPTIONS', 'Pass only one of `counter` or `seq`, not both', {\n      strategy: 'uuid',\n    })\n  }\n  const optSeq = options.counter ?? options.seq\n  if (optSeq !== undefined && !isIntegerInRange(optSeq, 0, MAX_SEQ)) {\n    throw new InvalidInputError('COUNTER_OUT_OF_RANGE', `Counter must be an integer between 0 and ${MAX_SEQ}`, {\n      strategy: 'uuid',\n    })\n  }\n  const optRandom = options.random\n  if (optRandom && optRandom.length < UUID_BYTES) {\n    throw new InvalidInputError('RANDOM_BYTES_TOO_SHORT', `Random bytes length must be >= ${UUID_BYTES}`, {\n      strategy: 'uuid',\n    })\n  }\n\n  const rnds = optRandom ?? rng()\n  const msecs = optMsecs ?? Date.now()\n  // Derive a 31-bit sequence if not provided by the caller, matching the default hot path.\n  const seq = optSeq ?? (rnds[6] << 23) | (rnds[7] << 16) | (rnds[8] << 8) | rnds[9]\n\n  if (buf) {\n    writeV7Bytes(rnds, msecs, seq, buf, offset)\n    return buf\n  }\n  writeV7BytesUnchecked(rnds, msecs, seq, reusableBuf, 0)\n  return formatUuidUnchecked(reusableBuf)\n}\n\n/*\n * Overload: no buffer => return a UUID string.\n */\nfunction v7(options?: UuidV7Options, buf?: undefined, offset?: number): string\n/*\n * Overload: caller provides a buffer slice to fill with UUID bytes.\n */\nfunction v7<TBuf extends Uint8Array = Uint8Array>(options: UuidV7Options | undefined, buf: TBuf, offset?: number): TBuf\nfunction v7<TBuf extends Uint8Array = Uint8Array>(options?: UuidV7Options, buf?: TBuf, offset?: number): string | TBuf {\n  if (options) {\n    return v7WithOptions(options, buf, offset)\n  }\n\n  // HOT PATH: Inline state management and byte generation for best performance\n  const now = Date.now()\n  const rnds = rng()\n\n  // Update state (inlined for performance)\n  if (now > state.msecs) {\n    state.seq = (rnds[6] << 23) | (rnds[7] << 16) | (rnds[8] << 8) | rnds[9]\n    state.msecs = now\n  } else {\n    state.seq = (state.seq + 1) | 0\n    if (state.seq < 0) {\n      state.seq = 0\n      state.msecs++\n    }\n  }\n\n  if (buf) {\n    writeV7Bytes(rnds, state.msecs, state.seq, buf, offset ?? 0)\n    return buf\n  }\n  writeV7BytesUnchecked(rnds, state.msecs, state.seq, reusableBuf, 0)\n  return formatUuidUnchecked(reusableBuf)\n}\n\nfunction timestamp(id: string): number {\n  const bytes = parseUuid(id)\n  let msecs = 0\n  for (let i = 0; i < 6; i += 1) {\n    msecs = msecs * 256 + bytes[i]\n  }\n  return msecs\n}\n\nfunction isValid(id: unknown): id is string {\n  return typeof id === 'string' && UUID_V7_REGEX.test(id)\n}\n\n/**\n * Generate a UUID v7 string or write the bytes into a buffer.\n *\n * UUID v7 is a time-ordered UUID that embeds a Unix timestamp in milliseconds,\n * making IDs naturally sortable by creation time. Ideal for database primary keys\n * where chronological ordering improves index performance.\n *\n * @example\n * ```ts\n * import { uuidv7 } from 'uniku/uuid/v7'\n *\n * const id = uuidv7()\n * // => \"018e5e5c-7c8a-7000-8000-000000000000\"\n *\n * // Extract timestamp\n * const ts = uuidv7.timestamp(id)\n * console.log(new Date(ts))\n *\n * // Validate\n * uuidv7.isValid(id) // true\n *\n * // Convert to/from bytes\n * const bytes = uuidv7.toBytes(id)\n * const restored = uuidv7.fromBytes(bytes)\n * ```\n */\nexport const uuidv7: UuidV7 = Object.assign(v7, {\n  toBytes: parseUuid,\n  fromBytes: formatUuid,\n  timestamp,\n  isValid,\n  NIL: '00000000-0000-0000-0000-000000000000',\n  MAX: 'ffffffff-ffff-ffff-ffff-ffffffffffff',\n})\n\nexport { BufferError, InvalidInputError, ParseError, UniqueIdError } from '../errors'\n"],"mappings":"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"}

package/build/uuid-BPebYihz.mjs

@@ -0,0 +1,2 @@
+import{BufferError as e,ParseError as t}from"./errors.mjs";function n(e){return e>=48&&e<=57?e-48:e>=65&&e<=70?e-65+10:e>=97&&e<=102?e-97+10:-1}const r=[0,0,1,1,2,2,3,3,-1,4,4,5,5,-1,6,6,7,7,-1,8,8,9,9,-1,10,10,11,11,12,12,13,13,14,14,15,15],i=[!0,!1,!0,!1,!0,!1,!0,!1,!1,!0,!1,!0,!1,!1,!0,!1,!0,!1,!1,!0,!1,!0,!1,!1,!0,!1,!0,!1,!0,!1,!0,!1,!0,!1,!0,!1],a=Array.from({length:256},(e,t)=>t.toString(16).padStart(2,`0`));function o(t){if(t.length!==16)throw new e(`BYTES_INVALID_LENGTH`,`UUID bytes must be exactly 16 bytes, got ${t.length}`,{strategy:`uuid`});return s(t)}function s(e){return a[e[0]]+a[e[1]]+a[e[2]]+a[e[3]]+`-`+a[e[4]]+a[e[5]]+`-`+a[e[6]]+a[e[7]]+`-`+a[e[8]]+a[e[9]]+`-`+a[e[10]]+a[e[11]]+a[e[12]]+a[e[13]]+a[e[14]]+a[e[15]]}function c(e){if(e.length!==36)throw new t(`INVALID_LENGTH`,`UUID string must be 36 characters, got ${e.length}`,{strategy:`uuid`});if(e[8]!==`-`||e[13]!==`-`||e[18]!==`-`||e[23]!==`-`)throw new t(`INVALID_FORMAT`,`UUID string has invalid separators at positions 8, 13, 18, 23. Received: "${e}"`,{strategy:`uuid`});let a=new Uint8Array(16);for(let o=0;o<36;o+=1){let s=r[o];if(s===-1)continue;let c=n(e.charCodeAt(o));if(c===-1)throw new t(`INVALID_CHAR`,`UUID string contains invalid hex character at position ${o}`,{strategy:`uuid`});i[o]?a[s]=c<<4:a[s]|=c}return a}export{s as n,c as r,o as t};
+//# sourceMappingURL=uuid-BPebYihz.mjs.map

package/build/uuid-BPebYihz.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid-BPebYihz.mjs","names":[],"sources":["../src/uuid/common/hex.ts","../src/uuid/common/uuid.ts"],"sourcesContent":["// ASCII code ranges for hex character validation\nconst ASCII_0 = 48 // '0'\nconst ASCII_9 = 57 // '9'\nconst ASCII_A = 65 // 'A'\nconst ASCII_F = 70 // 'F'\nconst ASCII_a = 97 // 'a'\nconst ASCII_f = 102 // 'f'\n\n/**\n * Convert a hex character ASCII code to its numeric value (0-15).\n * Returns -1 for invalid hex characters.\n */\nexport function hexValue(code: number): number {\n  if (code >= ASCII_0 && code <= ASCII_9) {\n    return code - ASCII_0\n  }\n  if (code >= ASCII_A && code <= ASCII_F) {\n    return code - ASCII_A + 10\n  }\n  if (code >= ASCII_a && code <= ASCII_f) {\n    return code - ASCII_a + 10\n  }\n  return -1 // Invalid hex character\n}\n","import { BufferError, ParseError } from '../../errors'\nimport { hexValue } from './hex'\n\nconst UUID_BYTE_LENGTH = 16\nconst UUID_STRING_LENGTH = 36\n\n// Mapping from UUID string position to byte index.\n// -1 indicates a dash position that should be skipped.\n// This avoids intermediate string allocations during parsing.\nconst UUID_CHAR_TO_BYTE: number[] = [\n  0,\n  0,\n  1,\n  1,\n  2,\n  2,\n  3,\n  3, // chars 0-7 → bytes 0-3\n  -1, // char 8 is '-'\n  4,\n  4,\n  5,\n  5, // chars 9-12 → bytes 4-5\n  -1, // char 13 is '-'\n  6,\n  6,\n  7,\n  7, // chars 14-17 → bytes 6-7\n  -1, // char 18 is '-'\n  8,\n  8,\n  9,\n  9, // chars 19-22 → bytes 8-9\n  -1, // char 23 is '-'\n  10,\n  10,\n  11,\n  11,\n  12,\n  12,\n  13,\n  13,\n  14,\n  14,\n  15,\n  15, // chars 24-35 → bytes 10-15\n]\n\n// Whether each position is the high nibble (true) or low nibble (false)\nconst UUID_CHAR_IS_HIGH: boolean[] = [\n  true,\n  false,\n  true,\n  false,\n  true,\n  false,\n  true,\n  false, // chars 0-7\n  false, // dash (ignored)\n  true,\n  false,\n  true,\n  false, // chars 9-12\n  false, // dash\n  true,\n  false,\n  true,\n  false, // chars 14-17\n  false, // dash\n  true,\n  false,\n  true,\n  false, // chars 19-22\n  false, // dash\n  true,\n  false,\n  true,\n  false,\n  true,\n  false,\n  true,\n  false,\n  true,\n  false,\n  true,\n  false, // chars 24-35\n]\n\n// Pre-computed lookup table for byte-to-hex conversion (0x00 -> \"00\", 0xff -> \"ff\")\n//\n// Note: this table must remain defined in the same module as `formatUuid`, otherwise the v8 optimizer\n// will cause a performance drop of ~36%.\nconst HEX_TABLE: string[] = Array.from({ length: 256 }, (_, i) => i.toString(16).padStart(2, '0'))\n\nexport function formatUuid(bytes: Uint8Array): string {\n  if (bytes.length !== UUID_BYTE_LENGTH) {\n    throw new BufferError(\n      'BYTES_INVALID_LENGTH',\n      `UUID bytes must be exactly ${UUID_BYTE_LENGTH} bytes, got ${bytes.length}`,\n      {\n        strategy: 'uuid',\n      },\n    )\n  }\n\n  return formatUuidUnchecked(bytes)\n}\n\nexport function formatUuidUnchecked(bytes: Uint8Array): string {\n  // Direct string concatenation - optimized for V8's string builder.\n  // This approach avoids loop overhead and intermediate allocations.\n  // See: https://github.com/uuidjs/uuid/pull/434\n  return (\n    HEX_TABLE[bytes[0]] +\n    HEX_TABLE[bytes[1]] +\n    HEX_TABLE[bytes[2]] +\n    HEX_TABLE[bytes[3]] +\n    '-' +\n    HEX_TABLE[bytes[4]] +\n    HEX_TABLE[bytes[5]] +\n    '-' +\n    HEX_TABLE[bytes[6]] +\n    HEX_TABLE[bytes[7]] +\n    '-' +\n    HEX_TABLE[bytes[8]] +\n    HEX_TABLE[bytes[9]] +\n    '-' +\n    HEX_TABLE[bytes[10]] +\n    HEX_TABLE[bytes[11]] +\n    HEX_TABLE[bytes[12]] +\n    HEX_TABLE[bytes[13]] +\n    HEX_TABLE[bytes[14]] +\n    HEX_TABLE[bytes[15]]\n  )\n}\n\nexport function parseUuid(value: string): Uint8Array {\n  if (value.length !== UUID_STRING_LENGTH) {\n    throw new ParseError('INVALID_LENGTH', `UUID string must be 36 characters, got ${value.length}`, {\n      strategy: 'uuid',\n    })\n  }\n\n  // Validate separator positions directly (more efficient than full loop)\n  if (value[8] !== '-' || value[13] !== '-' || value[18] !== '-' || value[23] !== '-') {\n    throw new ParseError(\n      'INVALID_FORMAT',\n      `UUID string has invalid separators at positions 8, 13, 18, 23. Received: \"${value}\"`,\n      { strategy: 'uuid' },\n    )\n  }\n\n  // Parse bytes directly from UUID string without intermediate string allocations.\n  // This avoids the 9 allocations (5 slices + 4 concatenations) of the naive approach.\n  const bytes = new Uint8Array(UUID_BYTE_LENGTH)\n\n  for (let i = 0; i < UUID_STRING_LENGTH; i += 1) {\n    const byteIdx = UUID_CHAR_TO_BYTE[i]\n    if (byteIdx === -1) continue // Skip dash positions\n\n    const nibble = hexValue(value.charCodeAt(i))\n    if (nibble === -1) {\n      throw new ParseError('INVALID_CHAR', `UUID string contains invalid hex character at position ${i}`, {\n        strategy: 'uuid',\n      })\n    }\n\n    if (UUID_CHAR_IS_HIGH[i]) {\n      bytes[byteIdx] = nibble << 4\n    } else {\n      bytes[byteIdx] |= nibble\n    }\n  }\n\n  return bytes\n}\n"],"mappings":"2DAYA,SAAgB,EAAS,EAAsB,CAU7C,OATI,GAAQ,IAAW,GAAQ,GACtB,EAAO,GAEZ,GAAQ,IAAW,GAAQ,GACtB,EAAO,GAAU,GAEtB,GAAQ,IAAW,GAAQ,IACtB,EAAO,GAAU,GAEnB,EACT,CCpBA,MAMM,EAA8B,CAClC,EACA,EACA,EACA,EACA,EACA,EACA,EACA,EACA,GACA,EACA,EACA,EACA,EACA,GACA,EACA,EACA,EACA,EACA,GACA,EACA,EACA,EACA,EACA,GACA,GACA,GACA,GACA,GACA,GACA,GACA,GACA,GACA,GACA,GACA,GACA,EACF,EAGM,EAA+B,CACnC,GACA,GACA,GACA,GACA,GACA,GACA,GACA,GACA,GACA,GACA,GACA,GACA,GACA,GACA,GACA,GACA,GACA,GACA,GACA,GACA,GACA,GACA,GACA,GACA,GACA,GACA,GACA,GACA,GACA,GACA,GACA,GACA,GACA,GACA,GACA,EACF,EAMM,EAAsB,MAAM,KAAK,CAAE,OAAQ,GAAI,GAAI,EAAG,IAAM,EAAE,SAAS,EAAE,CAAC,CAAC,SAAS,EAAG,GAAG,CAAC,EAEjG,SAAgB,EAAW,EAA2B,CACpD,GAAI,EAAM,SAAW,GACnB,MAAM,IAAI,EACR,uBACA,4CAA6D,EAAM,SACnE,CACE,SAAU,MACZ,CACF,EAGF,OAAO,EAAoB,CAAK,CAClC,CAEA,SAAgB,EAAoB,EAA2B,CAI7D,OACE,EAAU,EAAM,IAChB,EAAU,EAAM,IAChB,EAAU,EAAM,IAChB,EAAU,EAAM,IAChB,IACA,EAAU,EAAM,IAChB,EAAU,EAAM,IAChB,IACA,EAAU,EAAM,IAChB,EAAU,EAAM,IAChB,IACA,EAAU,EAAM,IAChB,EAAU,EAAM,IAChB,IACA,EAAU,EAAM,KAChB,EAAU,EAAM,KAChB,EAAU,EAAM,KAChB,EAAU,EAAM,KAChB,EAAU,EAAM,KAChB,EAAU,EAAM,IAEpB,CAEA,SAAgB,EAAU,EAA2B,CACnD,GAAI,EAAM,SAAW,GACnB,MAAM,IAAI,EAAW,iBAAkB,0CAA0C,EAAM,SAAU,CAC/F,SAAU,MACZ,CAAC,EAIH,GAAI,EAAM,KAAO,KAAO,EAAM,MAAQ,KAAO,EAAM,MAAQ,KAAO,EAAM,MAAQ,IAC9E,MAAM,IAAI,EACR,iBACA,6EAA6E,EAAM,GACnF,CAAE,SAAU,MAAO,CACrB,EAKF,IAAM,EAAQ,IAAI,WAAW,EAAgB,EAE7C,IAAK,IAAI,EAAI,EAAG,EAAI,GAAoB,GAAK,EAAG,CAC9C,IAAM,EAAU,EAAkB,GAClC,GAAI,IAAY,GAAI,SAEpB,IAAM,EAAS,EAAS,EAAM,WAAW,CAAC,CAAC,EAC3C,GAAI,IAAW,GACb,MAAM,IAAI,EAAW,eAAgB,0DAA0D,IAAK,CAClG,SAAU,MACZ,CAAC,EAGC,EAAkB,GACpB,EAAM,GAAW,GAAU,EAE3B,EAAM,IAAY,CAEtB,CAEA,OAAO,CACT"}

package/build/xid/xid.d.mts

@@ -1,9 +1,19 @@
-import { i as UniqueIdError, n as InvalidInputError, r as ParseError, t as BufferError } from "../errors-Dgoyi-ci.mjs";
+import { a as ParseError, i as InvalidInputError, o as UniqueIdError, t as BufferError } from "../errors-Da-8dh4J.mjs";
 
 //#region src/xid/xid.d.ts
 type XidOptions = {
   /** First three bytes used as the XID machine identity. */machineId?: Uint8Array; /** 16-bit process identity. */
-  processId?: number; /** Unix timestamp in seconds. Defaults to the current second. */
+  processId?: number;
+  /**
+  * Unix timestamp in milliseconds. Defaults to Date.now().
+  * XID stores whole seconds, so sub-second precision is truncated.
+  */
+  msecs?: number;
+  /**
+  * Unix timestamp in seconds.
+  *
+  * @deprecated Use `msecs` instead. Will be removed at v1-rc.
+  */
   secs?: number; /** 24-bit counter. Explicit values do not consume shared state. */
   counter?: number;
 };

package/build/xid/xid.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"xid.d.mts","names":[],"sources":["../../src/xid/xid.ts"],"mappings":";;;KAgBY,UAAA;4DAEV,SAAA,GAAY,UAAA,EAFd;EAIE,SAAA;EAEA,IAAA;EAEA,OAAA;AAAA;AAAA,KAGU,GAAA;EAAA;EAAA,cAEI,UAAA,GAAa,UAAA,EAAY,OAAA,EAAS,UAAA,cAAwB,GAAA,EAAK,IAAA,EAAM,MAAA,YAAkB,IAAA;EAAA,CACpG,OAAA,GAAU,UAAA,EAAY,GAAA,cAAiB,MAAA;EACxC,OAAA,CAAQ,EAAA,WAAa,UAAA;EACrB,SAAA,CAAU,KAAA,EAAO,UAAA;EACjB,SAAA,CAAU,EAAA;EACV,OAAA,CAAQ,EAAA,YAAc,EAAA;EACtB,GAAA;EACA,GAAA;AAAA;;;;;;;;cA8HW,GAAA,EAAK,GAAA"}
+{"version":3,"file":"xid.d.mts","names":[],"sources":["../../src/xid/xid.ts"],"mappings":";;;KAiBY,UAAA;4DAEV,SAAA,GAAY,UAAA,EAFd;EAIE,SAAA;;;;;EAKA,KAAA;;;;;AASA;EAFA,IAAA,WAKU;EAHV,OAAA;AAAA;AAAA,KAGU,GAAA;EAAA;EAAA,cAEI,UAAA,GAAa,UAAA,EAAY,OAAA,EAAS,UAAA,cAAwB,GAAA,EAAK,IAAA,EAAM,MAAA,YAAkB,IAAA;EAAA,CACpG,OAAA,GAAU,UAAA,EAAY,GAAA,cAAiB,MAAA;EACxC,OAAA,CAAQ,EAAA,WAAa,UAAA;EACrB,SAAA,CAAU,KAAA,EAAO,UAAA;EACjB,SAAA,CAAU,EAAA;EACV,OAAA,CAAQ,EAAA,YAAc,EAAA;EACtB,GAAA;EACA,GAAA;AAAA;;;;;;;;cAgIW,GAAA,EAAK,GAAA"}

package/build/xid/xid.mjs

@@ -1,2 +1,2 @@
-import{n as e,t}from"../random-Chp-Nkzi.mjs";import{n,t as r}from"../validation-CTNpXm94.mjs";import{BufferError as i,InvalidInputError as a,ParseError as o,UniqueIdError as s}from"../errors.mjs";import{n as c}from"../bytes-xqWxFYsM.mjs";const l=`0123456789abcdefghijklmnopqrstuv`,u=Uint8Array.from(l,e=>e.charCodeAt(0)),d=Array(20),f=[,,,,,,],p=new Uint8Array(65536);p.fill(255);for(let e=0;e<32;e+=1)p[l.charCodeAt(e)]=e;function m(e){if(e.length!==12)throw new i(`XID_BYTES_INVALID_LENGTH`,`XID bytes must be exactly 12 bytes, got ${e.length}`);return d[0]=u[e[0]>>3],d[1]=u[(e[0]<<2|e[1]>>6)&31],d[2]=u[e[1]>>1&31],d[3]=u[(e[1]<<4|e[2]>>4)&31],d[4]=u[(e[2]<<1|e[3]>>7)&31],d[5]=u[e[3]>>2&31],d[6]=u[(e[3]<<3|e[4]>>5)&31],d[7]=u[e[4]&31],d[8]=u[e[5]>>3],d[9]=u[(e[5]<<2|e[6]>>6)&31],d[10]=u[e[6]>>1&31],d[11]=u[(e[6]<<4|e[7]>>4)&31],d[12]=u[(e[7]<<1|e[8]>>7)&31],d[13]=u[e[8]>>2&31],d[14]=u[(e[8]<<3|e[9]>>5)&31],d[15]=u[e[9]&31],d[16]=u[e[10]>>3],d[17]=u[(e[10]<<2|e[11]>>6)&31],d[18]=u[e[11]>>1&31],d[19]=u[e[11]<<4&31],String.fromCharCode(...d)}function h(e,t){let n=t>>>16,r=t>>>8&255,i=t&255;return f[0]=u[(e<<3|n>>5)&31],f[1]=u[n&31],f[2]=u[r>>3],f[3]=u[(r<<2|i>>6)&31],f[4]=u[i>>1&31],f[5]=u[i<<4&31],String.fromCharCode(...f)}function g(e){if(e.length!==20)throw new o(`XID_INVALID_LENGTH`,`XID string must be 20 characters, got ${e.length}`);let t=new Uint8Array(20);for(let n=0;n<20;n+=1){let r=p[e.charCodeAt(n)];if(r===255)throw new o(`XID_INVALID_CHAR`,`Invalid XID character: ${e[n]}`);t[n]=r}if(t[19]!==0&&t[19]!==16)throw new o(`XID_NON_CANONICAL`,`XID trailing bits must be canonically encoded`);return new Uint8Array([t[0]<<3|t[1]>>2,t[1]<<6|t[2]<<1|t[3]>>4,t[3]<<4|t[4]>>1,t[4]<<7|t[5]<<2|t[6]>>3,t[6]<<5|t[7],t[8]<<3|t[9]>>2,t[9]<<6|t[10]<<1|t[11]>>4,t[11]<<4|t[12]>>1,t[12]<<7|t[13]<<2|t[14]>>3,t[14]<<5|t[15],t[16]<<3|t[17]>>2,t[17]<<6|t[18]<<1|t[19]>>4])}const _=4294967295,v=65535,y=16777215,b=/^[0-9a-v]{19}[0g]$/,x=new Uint8Array(12);let S=-1,C=``;const w={machineId:void 0,processId:void 0,counter:void 0};function T(e){return t(e).slice()}function E(){w.machineId===void 0&&(w.machineId=T(3)),w.processId===void 0&&(w.processId=e()&v)}function D(){return w.counter===void 0&&(w.counter=e()&y),w.counter=w.counter+1&y,w.counter}function O(e,t,n,r,i,a){c(i,a,e),i.set(t.subarray(0,3),a+4),i[a+7]=n>>>8,i[a+8]=n&255,i[a+9]=r>>>16,i[a+10]=r>>>8&255,i[a+11]=r&255}function k(e){if(e.machineId!==void 0&&e.machineId.length<3)throw new a(`XID_MACHINE_ID_BYTES_TOO_SHORT`,`Machine ID bytes length must be >= 3 for XID`);if(e.processId!==void 0&&!r(e.processId,0,v))throw new a(`XID_PROCESS_ID_OUT_OF_RANGE`,`Process ID must be between 0 and ${v}`);if(e.secs!==void 0&&!r(e.secs,0,_))throw new a(`XID_TIMESTAMP_OUT_OF_RANGE`,`Timestamp must be between 0 and ${_}`);if(e.counter!==void 0&&!r(e.counter,0,y))throw new a(`XID_COUNTER_OUT_OF_RANGE`,`Counter must be between 0 and ${y}`)}function A(e,t,r=0){if(e===void 0&&t===void 0){E();let e=Math.floor(Date.now()/1e3),t=D();return e!==S&&(O(e,w.machineId,w.processId,t,x,0),C=m(x).slice(0,14),S=e),C+h(w.processId&255,t)}e!==void 0&&k(e);let a=e?.secs??Math.floor(Date.now()/1e3);(e?.machineId===void 0||e.processId===void 0)&&E();let o=e?.machineId??w.machineId,s=e?.processId??w.processId,c=e?.counter??D();if(t!==void 0){if(!n(t,r,12))throw new i(`XID_BUFFER_OUT_OF_BOUNDS`,`XID byte range ${r}:${r+11} is out of buffer bounds`);return O(a,o,s,c,t,r),t}return O(a,o,s,c,x,0),m(x)}function j(e){return g(e)}function M(e){return m(e)}function N(e){let t=g(e);return((t[0]<<24|t[1]<<16|t[2]<<8|t[3])>>>0)*1e3}function P(e){return typeof e==`string`&&b.test(e)}const F=Object.assign(A,{toBytes:j,fromBytes:M,timestamp:N,isValid:P,NIL:`0`.repeat(20),MAX:m(new Uint8Array(12).fill(255))});export{i as BufferError,a as InvalidInputError,o as ParseError,s as UniqueIdError,F as xid};
+import{n as e,t}from"../random-Chp-Nkzi.mjs";import{n,t as r}from"../validation-CTNpXm94.mjs";import{BufferError as i,InvalidInputError as a,ParseError as o,UniqueIdError as s}from"../errors.mjs";import{n as c}from"../bytes-xqWxFYsM.mjs";import{t as l}from"../timestamp-ChrSuQCR.mjs";const u=`0123456789abcdefghijklmnopqrstuv`,d=Uint8Array.from(u,e=>e.charCodeAt(0)),f=Array(20),p=[,,,,,,],m=new Uint8Array(65536);m.fill(255);for(let e=0;e<32;e+=1)m[u.charCodeAt(e)]=e;function h(e){if(e.length!==12)throw new i(`BYTES_INVALID_LENGTH`,`XID bytes must be exactly 12 bytes, got ${e.length}`,{strategy:`xid`});return f[0]=d[e[0]>>3],f[1]=d[(e[0]<<2|e[1]>>6)&31],f[2]=d[e[1]>>1&31],f[3]=d[(e[1]<<4|e[2]>>4)&31],f[4]=d[(e[2]<<1|e[3]>>7)&31],f[5]=d[e[3]>>2&31],f[6]=d[(e[3]<<3|e[4]>>5)&31],f[7]=d[e[4]&31],f[8]=d[e[5]>>3],f[9]=d[(e[5]<<2|e[6]>>6)&31],f[10]=d[e[6]>>1&31],f[11]=d[(e[6]<<4|e[7]>>4)&31],f[12]=d[(e[7]<<1|e[8]>>7)&31],f[13]=d[e[8]>>2&31],f[14]=d[(e[8]<<3|e[9]>>5)&31],f[15]=d[e[9]&31],f[16]=d[e[10]>>3],f[17]=d[(e[10]<<2|e[11]>>6)&31],f[18]=d[e[11]>>1&31],f[19]=d[e[11]<<4&31],String.fromCharCode(...f)}function g(e,t){let n=t>>>16,r=t>>>8&255,i=t&255;return p[0]=d[(e<<3|n>>5)&31],p[1]=d[n&31],p[2]=d[r>>3],p[3]=d[(r<<2|i>>6)&31],p[4]=d[i>>1&31],p[5]=d[i<<4&31],String.fromCharCode(...p)}function _(e){if(e.length!==20)throw new o(`INVALID_LENGTH`,`XID string must be 20 characters, got ${e.length}`,{strategy:`xid`});let t=new Uint8Array(20);for(let n=0;n<20;n+=1){let r=m[e.charCodeAt(n)];if(r===255)throw new o(`INVALID_CHAR`,`Invalid XID character: ${e[n]}`,{strategy:`xid`});t[n]=r}if(t[19]!==0&&t[19]!==16)throw new o(`NON_CANONICAL`,`XID trailing bits must be canonically encoded`,{strategy:`xid`});return new Uint8Array([t[0]<<3|t[1]>>2,t[1]<<6|t[2]<<1|t[3]>>4,t[3]<<4|t[4]>>1,t[4]<<7|t[5]<<2|t[6]>>3,t[6]<<5|t[7],t[8]<<3|t[9]>>2,t[9]<<6|t[10]<<1|t[11]>>4,t[11]<<4|t[12]>>1,t[12]<<7|t[13]<<2|t[14]>>3,t[14]<<5|t[15],t[16]<<3|t[17]>>2,t[17]<<6|t[18]<<1|t[19]>>4])}const v=65535,y=16777215,b=/^[0-9a-v]{19}[0g]$/,x=new Uint8Array(12);let S=-1,C=``;const w={machineId:void 0,processId:void 0,counter:void 0};function T(e){return t(e).slice()}function E(){w.machineId===void 0&&(w.machineId=T(3)),w.processId===void 0&&(w.processId=e()&v)}function D(){return w.counter===void 0&&(w.counter=e()&y),w.counter=w.counter+1&y,w.counter}function O(e,t,n,r,i,a){c(i,a,e),i.set(t.subarray(0,3),a+4),i[a+7]=n>>>8,i[a+8]=n&255,i[a+9]=r>>>16,i[a+10]=r>>>8&255,i[a+11]=r&255}function k(e){if(e.machineId!==void 0&&e.machineId.length<3)throw new a(`MACHINE_ID_BYTES_TOO_SHORT`,`Machine ID bytes length must be >= 3 for XID`,{strategy:`xid`});if(e.processId!==void 0&&!r(e.processId,0,v))throw new a(`PROCESS_ID_OUT_OF_RANGE`,`Process ID must be between 0 and ${v}`,{strategy:`xid`});if(e.counter!==void 0&&!r(e.counter,0,y))throw new a(`COUNTER_OUT_OF_RANGE`,`Counter must be between 0 and ${y}`,{strategy:`xid`})}function A(e,t,r=0){if(e===void 0&&t===void 0){E();let e=Math.floor(Date.now()/1e3),t=D();return e!==S&&(O(e,w.machineId,w.processId,t,x,0),C=h(x).slice(0,14),S=e),C+g(w.processId&255,t)}e!==void 0&&k(e);let a=(e===void 0?void 0:l(e,0,4294967295,`xid`))??Math.floor(Date.now()/1e3);(e?.machineId===void 0||e.processId===void 0)&&E();let o=e?.machineId??w.machineId,s=e?.processId??w.processId,c=e?.counter??D();if(t!==void 0){if(!n(t,r,12))throw new i(`BUFFER_OUT_OF_BOUNDS`,`XID byte range ${r}:${r+11} is out of buffer bounds`,{strategy:`xid`});return O(a,o,s,c,t,r),t}return O(a,o,s,c,x,0),h(x)}function j(e){return _(e)}function M(e){return h(e)}function N(e){let t=_(e);return((t[0]<<24|t[1]<<16|t[2]<<8|t[3])>>>0)*1e3}function P(e){return typeof e==`string`&&b.test(e)}const F=Object.assign(A,{toBytes:j,fromBytes:M,timestamp:N,isValid:P,NIL:`0`.repeat(20),MAX:h(new Uint8Array(12).fill(255))});export{i as BufferError,a as InvalidInputError,o as ParseError,s as UniqueIdError,F as xid};
 //# sourceMappingURL=xid.mjs.map

package/build/xid/xid.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"xid.mjs","names":["XID_BYTES"],"sources":["../../src/xid/base32hex.ts","../../src/xid/xid.ts"],"sourcesContent":["import { BufferError, ParseError } from '../errors'\n\nconst ENCODING = '0123456789abcdefghijklmnopqrstuv'\nconst ENCODING_CODES = Uint8Array.from(ENCODING, (character) => character.charCodeAt(0))\nconst XID_BYTES = 12\nconst XID_LENGTH = 20\nconst ENCODED = new Array<number>(XID_LENGTH)\nconst COUNTER_SUFFIX = new Array<number>(6)\n\nconst DECODING = new Uint8Array(65536)\nDECODING.fill(255)\nfor (let i = 0; i < ENCODING.length; i += 1) {\n  DECODING[ENCODING.charCodeAt(i)] = i\n}\n\n/** Encode the 12 canonical XID bytes as lowercase base32hex. */\nexport function encodeBase32Hex(bytes: Uint8Array): string {\n  if (bytes.length !== XID_BYTES) {\n    throw new BufferError(\n      'XID_BYTES_INVALID_LENGTH',\n      `XID bytes must be exactly ${XID_BYTES} bytes, got ${bytes.length}`,\n    )\n  }\n\n  ENCODED[0] = ENCODING_CODES[bytes[0] >> 3]\n  ENCODED[1] = ENCODING_CODES[((bytes[0] << 2) | (bytes[1] >> 6)) & 0x1f]\n  ENCODED[2] = ENCODING_CODES[(bytes[1] >> 1) & 0x1f]\n  ENCODED[3] = ENCODING_CODES[((bytes[1] << 4) | (bytes[2] >> 4)) & 0x1f]\n  ENCODED[4] = ENCODING_CODES[((bytes[2] << 1) | (bytes[3] >> 7)) & 0x1f]\n  ENCODED[5] = ENCODING_CODES[(bytes[3] >> 2) & 0x1f]\n  ENCODED[6] = ENCODING_CODES[((bytes[3] << 3) | (bytes[4] >> 5)) & 0x1f]\n  ENCODED[7] = ENCODING_CODES[bytes[4] & 0x1f]\n  ENCODED[8] = ENCODING_CODES[bytes[5] >> 3]\n  ENCODED[9] = ENCODING_CODES[((bytes[5] << 2) | (bytes[6] >> 6)) & 0x1f]\n  ENCODED[10] = ENCODING_CODES[(bytes[6] >> 1) & 0x1f]\n  ENCODED[11] = ENCODING_CODES[((bytes[6] << 4) | (bytes[7] >> 4)) & 0x1f]\n  ENCODED[12] = ENCODING_CODES[((bytes[7] << 1) | (bytes[8] >> 7)) & 0x1f]\n  ENCODED[13] = ENCODING_CODES[(bytes[8] >> 2) & 0x1f]\n  ENCODED[14] = ENCODING_CODES[((bytes[8] << 3) | (bytes[9] >> 5)) & 0x1f]\n  ENCODED[15] = ENCODING_CODES[bytes[9] & 0x1f]\n  ENCODED[16] = ENCODING_CODES[bytes[10] >> 3]\n  ENCODED[17] = ENCODING_CODES[((bytes[10] << 2) | (bytes[11] >> 6)) & 0x1f]\n  ENCODED[18] = ENCODING_CODES[(bytes[11] >> 1) & 0x1f]\n  ENCODED[19] = ENCODING_CODES[(bytes[11] << 4) & 0x1f]\n  return String.fromCharCode(...ENCODED)\n}\n\n/** Encode the six XID characters affected by the 24-bit counter. */\nexport function encodeCounterSuffix(lastIdentityByte: number, counter: number): string {\n  const high = counter >>> 16\n  const middle = (counter >>> 8) & 0xff\n  const low = counter & 0xff\n  COUNTER_SUFFIX[0] = ENCODING_CODES[((lastIdentityByte << 3) | (high >> 5)) & 0x1f]\n  COUNTER_SUFFIX[1] = ENCODING_CODES[high & 0x1f]\n  COUNTER_SUFFIX[2] = ENCODING_CODES[middle >> 3]\n  COUNTER_SUFFIX[3] = ENCODING_CODES[((middle << 2) | (low >> 6)) & 0x1f]\n  COUNTER_SUFFIX[4] = ENCODING_CODES[(low >> 1) & 0x1f]\n  COUNTER_SUFFIX[5] = ENCODING_CODES[(low << 4) & 0x1f]\n  return String.fromCharCode(...COUNTER_SUFFIX)\n}\n\n/** Decode a canonical lowercase base32hex XID string to its 12 bytes. */\nexport function decodeBase32Hex(id: string): Uint8Array {\n  if (id.length !== XID_LENGTH) {\n    throw new ParseError('XID_INVALID_LENGTH', `XID string must be ${XID_LENGTH} characters, got ${id.length}`)\n  }\n\n  const values = new Uint8Array(XID_LENGTH)\n  for (let i = 0; i < XID_LENGTH; i += 1) {\n    const value = DECODING[id.charCodeAt(i)]\n    if (value === 255) {\n      throw new ParseError('XID_INVALID_CHAR', `Invalid XID character: ${id[i]}`)\n    }\n    values[i] = value\n  }\n\n  if (values[19] !== 0 && values[19] !== 16) {\n    throw new ParseError('XID_NON_CANONICAL', 'XID trailing bits must be canonically encoded')\n  }\n\n  return new Uint8Array([\n    (values[0] << 3) | (values[1] >> 2),\n    (values[1] << 6) | (values[2] << 1) | (values[3] >> 4),\n    (values[3] << 4) | (values[4] >> 1),\n    (values[4] << 7) | (values[5] << 2) | (values[6] >> 3),\n    (values[6] << 5) | values[7],\n    (values[8] << 3) | (values[9] >> 2),\n    (values[9] << 6) | (values[10] << 1) | (values[11] >> 4),\n    (values[11] << 4) | (values[12] >> 1),\n    (values[12] << 7) | (values[13] << 2) | (values[14] >> 3),\n    (values[14] << 5) | values[15],\n    (values[16] << 3) | (values[17] >> 2),\n    (values[17] << 6) | (values[18] << 1) | (values[19] >> 4),\n  ])\n}\n","import { writeTimestamp32 } from '../common/bytes'\nimport { randomBytes, randomUint32 } from '../common/random'\nimport { isIntegerInRange, isWritableRange } from '../common/validation'\nimport { BufferError, InvalidInputError } from '../errors'\nimport { decodeBase32Hex, encodeBase32Hex, encodeCounterSuffix } from './base32hex'\n\nconst XID_BYTES = 12\nconst MACHINE_ID_BYTES = 3\nconst MAX_SECS = 0xffffffff\nconst MAX_PROCESS_ID = 0xffff\nconst MAX_COUNTER = 0xffffff\nconst XID_REGEX = /^[0-9a-v]{19}[0g]$/\nconst stringBuffer = new Uint8Array(XID_BYTES)\nlet cachedPrefixSecs = -1\nlet cachedPrefix = ''\n\nexport type XidOptions = {\n  /** First three bytes used as the XID machine identity. */\n  machineId?: Uint8Array\n  /** 16-bit process identity. */\n  processId?: number\n  /** Unix timestamp in seconds. Defaults to the current second. */\n  secs?: number\n  /** 24-bit counter. Explicit values do not consume shared state. */\n  counter?: number\n}\n\nexport type Xid = {\n  (): string\n  <TBuf extends Uint8Array = Uint8Array>(options: XidOptions | undefined, buf: TBuf, offset?: number): TBuf\n  (options?: XidOptions, buf?: undefined, offset?: number): string\n  toBytes(id: string): Uint8Array\n  fromBytes(bytes: Uint8Array): string\n  timestamp(id: string): number\n  isValid(id: unknown): id is string\n  NIL: string\n  MAX: string\n}\n\ntype XidState = {\n  machineId: Uint8Array | undefined\n  processId: number | undefined\n  counter: number | undefined\n}\n\nconst state: XidState = { machineId: undefined, processId: undefined, counter: undefined }\n\n/** Copy pooled bytes before another random draw can refill their backing pool. */\nfunction freshRandom(count: number): Uint8Array {\n  return randomBytes(count).slice()\n}\n\nfunction initializeIdentity(): void {\n  if (state.machineId === undefined) state.machineId = freshRandom(MACHINE_ID_BYTES)\n  if (state.processId === undefined) state.processId = randomUint32() & MAX_PROCESS_ID\n}\n\nfunction nextCounter(): number {\n  if (state.counter === undefined) state.counter = randomUint32() & MAX_COUNTER\n  state.counter = (state.counter + 1) & MAX_COUNTER\n  return state.counter\n}\n\nfunction writeXidBytesUnchecked(\n  secs: number,\n  machineId: Uint8Array,\n  processId: number,\n  counter: number,\n  buf: Uint8Array,\n  offset: number,\n): void {\n  writeTimestamp32(buf, offset, secs)\n  buf.set(machineId.subarray(0, MACHINE_ID_BYTES), offset + 4)\n  buf[offset + 7] = processId >>> 8\n  buf[offset + 8] = processId & 0xff\n  buf[offset + 9] = counter >>> 16\n  buf[offset + 10] = (counter >>> 8) & 0xff\n  buf[offset + 11] = counter & 0xff\n}\n\nfunction validateOptions(options: XidOptions): void {\n  if (options.machineId !== undefined && options.machineId.length < MACHINE_ID_BYTES) {\n    throw new InvalidInputError(\n      'XID_MACHINE_ID_BYTES_TOO_SHORT',\n      `Machine ID bytes length must be >= ${MACHINE_ID_BYTES} for XID`,\n    )\n  }\n  if (options.processId !== undefined && !isIntegerInRange(options.processId, 0, MAX_PROCESS_ID)) {\n    throw new InvalidInputError('XID_PROCESS_ID_OUT_OF_RANGE', `Process ID must be between 0 and ${MAX_PROCESS_ID}`)\n  }\n  if (options.secs !== undefined && !isIntegerInRange(options.secs, 0, MAX_SECS)) {\n    throw new InvalidInputError('XID_TIMESTAMP_OUT_OF_RANGE', `Timestamp must be between 0 and ${MAX_SECS}`)\n  }\n  if (options.counter !== undefined && !isIntegerInRange(options.counter, 0, MAX_COUNTER)) {\n    throw new InvalidInputError('XID_COUNTER_OUT_OF_RANGE', `Counter must be between 0 and ${MAX_COUNTER}`)\n  }\n}\n\nfunction xidFn(options?: XidOptions, buf?: undefined, offset?: number): string\nfunction xidFn<TBuf extends Uint8Array = Uint8Array>(options: XidOptions | undefined, buf: TBuf, offset?: number): TBuf\nfunction xidFn<TBuf extends Uint8Array = Uint8Array>(options?: XidOptions, buf?: TBuf, offset = 0): string | TBuf {\n  if (options === undefined && buf === undefined) {\n    initializeIdentity()\n    const secs = Math.floor(Date.now() / 1000)\n    const counter = nextCounter()\n    if (secs !== cachedPrefixSecs) {\n      writeXidBytesUnchecked(secs, state.machineId!, state.processId!, counter, stringBuffer, 0)\n      cachedPrefix = encodeBase32Hex(stringBuffer).slice(0, 14)\n      cachedPrefixSecs = secs\n    }\n    return cachedPrefix + encodeCounterSuffix(state.processId! & 0xff, counter)\n  }\n\n  if (options !== undefined) validateOptions(options)\n\n  const secs = options?.secs ?? Math.floor(Date.now() / 1000)\n  if (options?.machineId === undefined || options.processId === undefined) {\n    initializeIdentity()\n  }\n  const machineId = options?.machineId ?? state.machineId!\n  const processId = options?.processId ?? state.processId!\n  const counter = options?.counter ?? nextCounter()\n\n  if (buf !== undefined) {\n    if (!isWritableRange(buf, offset, XID_BYTES)) {\n      throw new BufferError(\n        'XID_BUFFER_OUT_OF_BOUNDS',\n        `XID byte range ${offset}:${offset + 11} is out of buffer bounds`,\n      )\n    }\n    writeXidBytesUnchecked(secs, machineId, processId, counter, buf, offset)\n    return buf\n  }\n\n  writeXidBytesUnchecked(secs, machineId, processId, counter, stringBuffer, 0)\n  return encodeBase32Hex(stringBuffer)\n}\n\nfunction toBytes(id: string): Uint8Array {\n  return decodeBase32Hex(id)\n}\n\nfunction fromBytes(bytes: Uint8Array): string {\n  return encodeBase32Hex(bytes)\n}\n\nfunction timestamp(id: string): number {\n  const bytes = decodeBase32Hex(id)\n  return (((bytes[0] << 24) | (bytes[1] << 16) | (bytes[2] << 8) | bytes[3]) >>> 0) * 1000\n}\n\nfunction isValid(id: unknown): id is string {\n  return typeof id === 'string' && XID_REGEX.test(id)\n}\n\n/**\n * Generate a 20-character rs/xid-compatible identifier.\n *\n * XID embeds seconds, a lazily-random per-runtime identity, and a shared\n * always-incrementing counter. In Cloudflare Workers, time is frozen during a\n * request, so the counter preserves ordering for IDs made in that request.\n */\nexport const xid: Xid = Object.assign(xidFn, {\n  toBytes,\n  fromBytes,\n  timestamp,\n  isValid,\n  NIL: '0'.repeat(20),\n  MAX: encodeBase32Hex(new Uint8Array(12).fill(0xff)),\n})\n\nexport { BufferError, InvalidInputError, ParseError, UniqueIdError } from '../errors'\n"],"mappings":"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"}
+{"version":3,"file":"xid.mjs","names":["XID_BYTES"],"sources":["../../src/xid/base32hex.ts","../../src/xid/xid.ts"],"sourcesContent":["import { BufferError, ParseError } from '../errors'\n\nconst ENCODING = '0123456789abcdefghijklmnopqrstuv'\nconst ENCODING_CODES = Uint8Array.from(ENCODING, (character) => character.charCodeAt(0))\nconst XID_BYTES = 12\nconst XID_LENGTH = 20\nconst ENCODED = new Array<number>(XID_LENGTH)\nconst COUNTER_SUFFIX = new Array<number>(6)\n\nconst DECODING = new Uint8Array(65536)\nDECODING.fill(255)\nfor (let i = 0; i < ENCODING.length; i += 1) {\n  DECODING[ENCODING.charCodeAt(i)] = i\n}\n\n/** Encode the 12 canonical XID bytes as lowercase base32hex. */\nexport function encodeBase32Hex(bytes: Uint8Array): string {\n  if (bytes.length !== XID_BYTES) {\n    throw new BufferError('BYTES_INVALID_LENGTH', `XID bytes must be exactly ${XID_BYTES} bytes, got ${bytes.length}`, {\n      strategy: 'xid',\n    })\n  }\n\n  ENCODED[0] = ENCODING_CODES[bytes[0] >> 3]\n  ENCODED[1] = ENCODING_CODES[((bytes[0] << 2) | (bytes[1] >> 6)) & 0x1f]\n  ENCODED[2] = ENCODING_CODES[(bytes[1] >> 1) & 0x1f]\n  ENCODED[3] = ENCODING_CODES[((bytes[1] << 4) | (bytes[2] >> 4)) & 0x1f]\n  ENCODED[4] = ENCODING_CODES[((bytes[2] << 1) | (bytes[3] >> 7)) & 0x1f]\n  ENCODED[5] = ENCODING_CODES[(bytes[3] >> 2) & 0x1f]\n  ENCODED[6] = ENCODING_CODES[((bytes[3] << 3) | (bytes[4] >> 5)) & 0x1f]\n  ENCODED[7] = ENCODING_CODES[bytes[4] & 0x1f]\n  ENCODED[8] = ENCODING_CODES[bytes[5] >> 3]\n  ENCODED[9] = ENCODING_CODES[((bytes[5] << 2) | (bytes[6] >> 6)) & 0x1f]\n  ENCODED[10] = ENCODING_CODES[(bytes[6] >> 1) & 0x1f]\n  ENCODED[11] = ENCODING_CODES[((bytes[6] << 4) | (bytes[7] >> 4)) & 0x1f]\n  ENCODED[12] = ENCODING_CODES[((bytes[7] << 1) | (bytes[8] >> 7)) & 0x1f]\n  ENCODED[13] = ENCODING_CODES[(bytes[8] >> 2) & 0x1f]\n  ENCODED[14] = ENCODING_CODES[((bytes[8] << 3) | (bytes[9] >> 5)) & 0x1f]\n  ENCODED[15] = ENCODING_CODES[bytes[9] & 0x1f]\n  ENCODED[16] = ENCODING_CODES[bytes[10] >> 3]\n  ENCODED[17] = ENCODING_CODES[((bytes[10] << 2) | (bytes[11] >> 6)) & 0x1f]\n  ENCODED[18] = ENCODING_CODES[(bytes[11] >> 1) & 0x1f]\n  ENCODED[19] = ENCODING_CODES[(bytes[11] << 4) & 0x1f]\n  return String.fromCharCode(...ENCODED)\n}\n\n/** Encode the six XID characters affected by the 24-bit counter. */\nexport function encodeCounterSuffix(lastIdentityByte: number, counter: number): string {\n  const high = counter >>> 16\n  const middle = (counter >>> 8) & 0xff\n  const low = counter & 0xff\n  COUNTER_SUFFIX[0] = ENCODING_CODES[((lastIdentityByte << 3) | (high >> 5)) & 0x1f]\n  COUNTER_SUFFIX[1] = ENCODING_CODES[high & 0x1f]\n  COUNTER_SUFFIX[2] = ENCODING_CODES[middle >> 3]\n  COUNTER_SUFFIX[3] = ENCODING_CODES[((middle << 2) | (low >> 6)) & 0x1f]\n  COUNTER_SUFFIX[4] = ENCODING_CODES[(low >> 1) & 0x1f]\n  COUNTER_SUFFIX[5] = ENCODING_CODES[(low << 4) & 0x1f]\n  return String.fromCharCode(...COUNTER_SUFFIX)\n}\n\n/** Decode a canonical lowercase base32hex XID string to its 12 bytes. */\nexport function decodeBase32Hex(id: string): Uint8Array {\n  if (id.length !== XID_LENGTH) {\n    throw new ParseError('INVALID_LENGTH', `XID string must be ${XID_LENGTH} characters, got ${id.length}`, {\n      strategy: 'xid',\n    })\n  }\n\n  const values = new Uint8Array(XID_LENGTH)\n  for (let i = 0; i < XID_LENGTH; i += 1) {\n    const value = DECODING[id.charCodeAt(i)]\n    if (value === 255) {\n      throw new ParseError('INVALID_CHAR', `Invalid XID character: ${id[i]}`, { strategy: 'xid' })\n    }\n    values[i] = value\n  }\n\n  if (values[19] !== 0 && values[19] !== 16) {\n    throw new ParseError('NON_CANONICAL', 'XID trailing bits must be canonically encoded', { strategy: 'xid' })\n  }\n\n  return new Uint8Array([\n    (values[0] << 3) | (values[1] >> 2),\n    (values[1] << 6) | (values[2] << 1) | (values[3] >> 4),\n    (values[3] << 4) | (values[4] >> 1),\n    (values[4] << 7) | (values[5] << 2) | (values[6] >> 3),\n    (values[6] << 5) | values[7],\n    (values[8] << 3) | (values[9] >> 2),\n    (values[9] << 6) | (values[10] << 1) | (values[11] >> 4),\n    (values[11] << 4) | (values[12] >> 1),\n    (values[12] << 7) | (values[13] << 2) | (values[14] >> 3),\n    (values[14] << 5) | values[15],\n    (values[16] << 3) | (values[17] >> 2),\n    (values[17] << 6) | (values[18] << 1) | (values[19] >> 4),\n  ])\n}\n","import { writeTimestamp32 } from '../common/bytes'\nimport { randomBytes, randomUint32 } from '../common/random'\nimport { resolveTimestampSecs } from '../common/timestamp'\nimport { isIntegerInRange, isWritableRange } from '../common/validation'\nimport { BufferError, InvalidInputError } from '../errors'\nimport { decodeBase32Hex, encodeBase32Hex, encodeCounterSuffix } from './base32hex'\n\nconst XID_BYTES = 12\nconst MACHINE_ID_BYTES = 3\nconst MAX_SECS = 0xffffffff\nconst MAX_PROCESS_ID = 0xffff\nconst MAX_COUNTER = 0xffffff\nconst XID_REGEX = /^[0-9a-v]{19}[0g]$/\nconst stringBuffer = new Uint8Array(XID_BYTES)\nlet cachedPrefixSecs = -1\nlet cachedPrefix = ''\n\nexport type XidOptions = {\n  /** First three bytes used as the XID machine identity. */\n  machineId?: Uint8Array\n  /** 16-bit process identity. */\n  processId?: number\n  /**\n   * Unix timestamp in milliseconds. Defaults to Date.now().\n   * XID stores whole seconds, so sub-second precision is truncated.\n   */\n  msecs?: number\n  /**\n   * Unix timestamp in seconds.\n   *\n   * @deprecated Use `msecs` instead. Will be removed at v1-rc.\n   */\n  // TODO(v1-rc): remove this alias (tracked in docs/STABILITY.md).\n  secs?: number\n  /** 24-bit counter. Explicit values do not consume shared state. */\n  counter?: number\n}\n\nexport type Xid = {\n  (): string\n  <TBuf extends Uint8Array = Uint8Array>(options: XidOptions | undefined, buf: TBuf, offset?: number): TBuf\n  (options?: XidOptions, buf?: undefined, offset?: number): string\n  toBytes(id: string): Uint8Array\n  fromBytes(bytes: Uint8Array): string\n  timestamp(id: string): number\n  isValid(id: unknown): id is string\n  NIL: string\n  MAX: string\n}\n\ntype XidState = {\n  machineId: Uint8Array | undefined\n  processId: number | undefined\n  counter: number | undefined\n}\n\nconst state: XidState = { machineId: undefined, processId: undefined, counter: undefined }\n\n/** Copy pooled bytes before another random draw can refill their backing pool. */\nfunction freshRandom(count: number): Uint8Array {\n  return randomBytes(count).slice()\n}\n\nfunction initializeIdentity(): void {\n  if (state.machineId === undefined) state.machineId = freshRandom(MACHINE_ID_BYTES)\n  if (state.processId === undefined) state.processId = randomUint32() & MAX_PROCESS_ID\n}\n\nfunction nextCounter(): number {\n  if (state.counter === undefined) state.counter = randomUint32() & MAX_COUNTER\n  state.counter = (state.counter + 1) & MAX_COUNTER\n  return state.counter\n}\n\nfunction writeXidBytesUnchecked(\n  secs: number,\n  machineId: Uint8Array,\n  processId: number,\n  counter: number,\n  buf: Uint8Array,\n  offset: number,\n): void {\n  writeTimestamp32(buf, offset, secs)\n  buf.set(machineId.subarray(0, MACHINE_ID_BYTES), offset + 4)\n  buf[offset + 7] = processId >>> 8\n  buf[offset + 8] = processId & 0xff\n  buf[offset + 9] = counter >>> 16\n  buf[offset + 10] = (counter >>> 8) & 0xff\n  buf[offset + 11] = counter & 0xff\n}\n\nfunction validateOptions(options: XidOptions): void {\n  if (options.machineId !== undefined && options.machineId.length < MACHINE_ID_BYTES) {\n    throw new InvalidInputError(\n      'MACHINE_ID_BYTES_TOO_SHORT',\n      `Machine ID bytes length must be >= ${MACHINE_ID_BYTES} for XID`,\n      { strategy: 'xid' },\n    )\n  }\n  if (options.processId !== undefined && !isIntegerInRange(options.processId, 0, MAX_PROCESS_ID)) {\n    throw new InvalidInputError('PROCESS_ID_OUT_OF_RANGE', `Process ID must be between 0 and ${MAX_PROCESS_ID}`, {\n      strategy: 'xid',\n    })\n  }\n  if (options.counter !== undefined && !isIntegerInRange(options.counter, 0, MAX_COUNTER)) {\n    throw new InvalidInputError('COUNTER_OUT_OF_RANGE', `Counter must be between 0 and ${MAX_COUNTER}`, {\n      strategy: 'xid',\n    })\n  }\n}\n\nfunction xidFn(options?: XidOptions, buf?: undefined, offset?: number): string\nfunction xidFn<TBuf extends Uint8Array = Uint8Array>(options: XidOptions | undefined, buf: TBuf, offset?: number): TBuf\nfunction xidFn<TBuf extends Uint8Array = Uint8Array>(options?: XidOptions, buf?: TBuf, offset = 0): string | TBuf {\n  if (options === undefined && buf === undefined) {\n    initializeIdentity()\n    const secs = Math.floor(Date.now() / 1000)\n    const counter = nextCounter()\n    if (secs !== cachedPrefixSecs) {\n      writeXidBytesUnchecked(secs, state.machineId!, state.processId!, counter, stringBuffer, 0)\n      cachedPrefix = encodeBase32Hex(stringBuffer).slice(0, 14)\n      cachedPrefixSecs = secs\n    }\n    return cachedPrefix + encodeCounterSuffix(state.processId! & 0xff, counter)\n  }\n\n  if (options !== undefined) validateOptions(options)\n\n  const resolvedSecs = options === undefined ? undefined : resolveTimestampSecs(options, 0, MAX_SECS, 'xid')\n  const secs = resolvedSecs ?? Math.floor(Date.now() / 1000)\n  if (options?.machineId === undefined || options.processId === undefined) {\n    initializeIdentity()\n  }\n  const machineId = options?.machineId ?? state.machineId!\n  const processId = options?.processId ?? state.processId!\n  const counter = options?.counter ?? nextCounter()\n\n  if (buf !== undefined) {\n    if (!isWritableRange(buf, offset, XID_BYTES)) {\n      throw new BufferError('BUFFER_OUT_OF_BOUNDS', `XID byte range ${offset}:${offset + 11} is out of buffer bounds`, {\n        strategy: 'xid',\n      })\n    }\n    writeXidBytesUnchecked(secs, machineId, processId, counter, buf, offset)\n    return buf\n  }\n\n  writeXidBytesUnchecked(secs, machineId, processId, counter, stringBuffer, 0)\n  return encodeBase32Hex(stringBuffer)\n}\n\nfunction toBytes(id: string): Uint8Array {\n  return decodeBase32Hex(id)\n}\n\nfunction fromBytes(bytes: Uint8Array): string {\n  return encodeBase32Hex(bytes)\n}\n\nfunction timestamp(id: string): number {\n  const bytes = decodeBase32Hex(id)\n  return (((bytes[0] << 24) | (bytes[1] << 16) | (bytes[2] << 8) | bytes[3]) >>> 0) * 1000\n}\n\nfunction isValid(id: unknown): id is string {\n  return typeof id === 'string' && XID_REGEX.test(id)\n}\n\n/**\n * Generate a 20-character rs/xid-compatible identifier.\n *\n * XID embeds seconds, a lazily-random per-runtime identity, and a shared\n * always-incrementing counter. In Cloudflare Workers, time is frozen during a\n * request, so the counter preserves ordering for IDs made in that request.\n */\nexport const xid: Xid = Object.assign(xidFn, {\n  toBytes,\n  fromBytes,\n  timestamp,\n  isValid,\n  NIL: '0'.repeat(20),\n  MAX: encodeBase32Hex(new Uint8Array(12).fill(0xff)),\n})\n\nexport { BufferError, InvalidInputError, ParseError, UniqueIdError } from '../errors'\n"],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "private": false,
   "name": "uniku",
-  "version": "0.4.3",
+  "version": "0.5.0",
   "description": "Minimal, tree-shakeable unique ID generators for every JavaScript runtime",
   "author": {
     "name": "Alberto Schiabel",

package/src/common/timestamp.ts

@@ -0,0 +1,70 @@
+import { InvalidInputError } from '../errors'
+import type { IdGenerator } from '../generators'
+import { isIntegerInRange } from './validation'
+
+/**
+ * Timestamp options accepted by second-precision generators (ksuid, objectid,
+ * xid) during the pre-v1 transition to unified millisecond inputs.
+ */
+export type TimestampSecsOptions = {
+  /**
+   * Timestamp in milliseconds since the Unix epoch.
+   * The generator stores whole seconds, so sub-second precision is truncated.
+   */
+  msecs?: number
+  /**
+   * Timestamp in seconds since the Unix epoch.
+   *
+   * @deprecated Use `msecs` instead. Will be removed at v1-rc.
+   */
+  // TODO(v1-rc): remove this alias (tracked in docs/STABILITY.md).
+  secs?: number
+}
+
+/**
+ * Resolve caller-provided timestamp options to whole seconds since the Unix
+ * epoch, or `undefined` when neither option was supplied.
+ *
+ * `msecs` is the unified input and is truncated to whole seconds; `secs` is
+ * the deprecated pre-v1 alias. Passing both is an error.
+ *
+ * TODO(v1-rc): drop the `secs` branch once the alias is removed.
+ */
+export function resolveTimestampSecs(
+  options: TimestampSecsOptions,
+  minSecs: number,
+  maxSecs: number,
+  strategy: IdGenerator,
+): number | undefined {
+  const { msecs, secs } = options
+
+  if (msecs !== undefined && secs !== undefined) {
+    throw new InvalidInputError('CONFLICTING_OPTIONS', 'Pass only one of `msecs` or `secs`, not both', { strategy })
+  }
+
+  if (msecs !== undefined) {
+    const minMsecs = minSecs * 1000
+    const maxMsecs = maxSecs * 1000 + 999
+    if (!isIntegerInRange(msecs, minMsecs, maxMsecs)) {
+      throw new InvalidInputError(
+        'TIMESTAMP_OUT_OF_RANGE',
+        `Timestamp must be an integer between ${minMsecs} and ${maxMsecs} milliseconds`,
+        { strategy },
+      )
+    }
+    return Math.floor(msecs / 1000)
+  }
+
+  if (secs !== undefined) {
+    if (!isIntegerInRange(secs, minSecs, maxSecs)) {
+      throw new InvalidInputError(
+        'TIMESTAMP_OUT_OF_RANGE',
+        `Timestamp must be an integer between ${minSecs} and ${maxSecs} seconds`,
+        { strategy },
+      )
+    }
+    return secs
+  }
+
+  return undefined
+}

package/src/cuid2/cuid2.ts

@@ -122,7 +122,9 @@ function getCryptoRandom(): number {
 function getRandomFn(random?: Uint8Array): () => number {
   if (random) {
     if (random.length === 0) {
-      throw new InvalidInputError('CUID2_RANDOM_BYTES_EMPTY', 'Random byte array cannot be empty')
+      throw new InvalidInputError('RANDOM_BYTES_TOO_SHORT', 'Random byte array cannot be empty', {
+        strategy: 'cuid',
+      })
     }
     let index = 0
     return () => {
@@ -144,8 +146,9 @@ function cuid2Fn(options?: Cuid2Options): string {
     (!Number.isInteger(requestedLength) || requestedLength < MIN_LENGTH || requestedLength > MAX_LENGTH)
   ) {
     throw new InvalidInputError(
-      'CUID2_LENGTH_OUT_OF_RANGE',
+      'LENGTH_OUT_OF_RANGE',
       `CUID2 length must be between ${MIN_LENGTH} and ${MAX_LENGTH}. Received: ${requestedLength}`,
+      { strategy: 'cuid' },
     )
   }
   const length = requestedLength ?? DEFAULT_LENGTH

package/src/errors.ts

@@ -1,15 +1,77 @@
+import type { IdGenerator } from './generators'
+
+/**
+ * The canonical, ordered list of machine-readable error codes emitted by
+ * uniku's public API.
+ *
+ * Codes describe the failure independently of an ID format. Use an error's
+ * `strategy` field when the generator that raised it matters.
+ */
+// Plain `as const` keeps declaration emit compatible with
+// `isolatedDeclarations`; every member is already a string literal.
+export const ERROR_CODES = [
+  'TIMESTAMP_OUT_OF_RANGE',
+  'CONFLICTING_OPTIONS',
+  'COUNTER_OUT_OF_RANGE',
+  'NODE_OUT_OF_RANGE',
+  'NODE_BITS_OUT_OF_RANGE',
+  'EPOCH_INVALID',
+  'PROCESS_ID_OUT_OF_RANGE',
+  'MACHINE_ID_BYTES_TOO_SHORT',
+  'RANDOM_BYTES_TOO_SHORT',
+  'RANDOM_OVERFLOW',
+  'LENGTH_OUT_OF_RANGE',
+  'ALPHABET_OUT_OF_RANGE',
+  'ALPHABET_INVALID_CHAR',
+  'ALPHABET_DUPLICATE',
+  'PREFIX_TOO_LONG',
+  'PREFIX_INVALID_CHAR',
+  'PREFIX_INVALID_BOUNDARY',
+  'UUID_NOT_V7',
+  'BYTES_INVALID_LENGTH',
+  'BUFFER_OUT_OF_BOUNDS',
+  'INVALID_CHAR',
+  'INVALID_LENGTH',
+  'INVALID_FORMAT',
+  'NON_CANONICAL',
+  'VALUE_OUT_OF_RANGE',
+] as const
+
+/**
+ * A machine-readable error code emitted by uniku, derived from
+ * {@link ERROR_CODES}.
+ */
+export type ErrorCode = (typeof ERROR_CODES)[number]
+
+/**
+ * Extra context carried by every uniku error.
+ */
+export type UniqueIdErrorOptions = {
+  /**
+   * The ID strategy whose public boundary raised the error.
+   * Error codes are strategy-agnostic (e.g. `TIMESTAMP_OUT_OF_RANGE`), so this
+   * field attributes the failure to the generator that produced it.
+   */
+  readonly strategy?: IdGenerator
+}
+
 /**
  * Base error for all uniku errors.
- * Provides `_tag` for discriminated matching (compatible with Effect's `catchTag`)
- * and `code` for machine-readable error identification.
+ * Provides `_tag` for discriminated matching (compatible with Effect's `catchTag`),
+ * `code` for machine-readable error identification, and `strategy` to attribute
+ * unified codes to the ID generator that raised them.
  */
 export abstract class UniqueIdError extends Error {
   abstract readonly _tag: string
-  abstract readonly code: string
+  abstract readonly code: ErrorCode
+
+  /** The ID strategy whose public boundary raised the error. */
+  readonly strategy?: IdGenerator
 
-  constructor(message: string) {
+  constructor(message: string, options?: UniqueIdErrorOptions) {
     super(message)
     this.name = this.constructor.name
+    this.strategy = options?.strategy
   }
 }
 
@@ -20,10 +82,11 @@ export class InvalidInputError extends UniqueIdError {
   readonly _tag = 'InvalidInputError' as const
 
   constructor(
-    readonly code: string,
+    readonly code: ErrorCode,
     message: string,
+    options?: UniqueIdErrorOptions,
   ) {
-    super(message)
+    super(message, options)
   }
 }
 
@@ -34,10 +97,11 @@ export class ParseError extends UniqueIdError {
   readonly _tag = 'ParseError' as const
 
   constructor(
-    readonly code: string,
+    readonly code: ErrorCode,
     message: string,
+    options?: UniqueIdErrorOptions,
   ) {
-    super(message)
+    super(message, options)
   }
 }
 
@@ -48,9 +112,10 @@ export class BufferError extends UniqueIdError {
   readonly _tag = 'BufferError' as const
 
   constructor(
-    readonly code: string,
+    readonly code: ErrorCode,
     message: string,
+    options?: UniqueIdErrorOptions,
   ) {
-    super(message)
+    super(message, options)
   }
 }

package/src/ksuid/base62.ts

@@ -40,8 +40,9 @@ for (let i = 0; i < BASE62_ALPHABET.length; i += 1) {
 export function encodeBase62(bytes: Uint8Array): string {
   if (bytes.length < KSUID_BYTES) {
     throw new BufferError(
-      'KSUID_BYTES_TOO_SHORT',
+      'BYTES_INVALID_LENGTH',
       `KSUID bytes must be at least ${KSUID_BYTES} bytes, got ${bytes.length}`,
+      { strategy: 'ksuid' },
     )
   }
 
@@ -72,10 +73,9 @@ export function encodeBase62(bytes: Uint8Array): string {
  */
 export function decodeBase62(str: string): Uint8Array {
   if (str.length !== KSUID_STRING_LEN) {
-    throw new ParseError(
-      'KSUID_INVALID_LENGTH',
-      `KSUID string must be ${KSUID_STRING_LEN} characters, got ${str.length}`,
-    )
+    throw new ParseError('INVALID_LENGTH', `KSUID string must be ${KSUID_STRING_LEN} characters, got ${str.length}`, {
+      strategy: 'ksuid',
+    })
   }
 
   // Convert Base62 string to BigInt
@@ -83,13 +83,13 @@ export function decodeBase62(str: string): Uint8Array {
   for (let i = 0; i < KSUID_STRING_LEN; i += 1) {
     const value = DECODING[str.charCodeAt(i)]
     if (value === 255) {
-      throw new ParseError('KSUID_INVALID_CHAR', `Invalid KSUID character: ${str[i]}`)
+      throw new ParseError('INVALID_CHAR', `Invalid KSUID character: ${str[i]}`, { strategy: 'ksuid' })
     }
     num = num * BASE + BigInt(value)
   }
 
   if (num > MAX_KSUID_VALUE) {
-    throw new ParseError('KSUID_OVERFLOW', 'KSUID string exceeds 160-bit range')
+    throw new ParseError('VALUE_OUT_OF_RANGE', 'KSUID string exceeds 160-bit range', { strategy: 'ksuid' })
   }
 
   // Convert BigInt to bytes (big-endian)

package/src/ksuid/ksuid.ts

@@ -1,5 +1,6 @@
 import { writeTimestamp32 } from '../common/bytes'
 import { rng } from '../common/random'
+import { resolveTimestampSecs } from '../common/timestamp'
 import { isWritableRange } from '../common/validation'
 import { BufferError, InvalidInputError } from '../errors'
 import { decodeBase62, encodeBase62 } from './base62'
@@ -37,10 +38,17 @@ export type KsuidOptions = {
    */
   random?: Uint8Array
   /**
-   * Timestamp in seconds since Unix epoch.
-   * Defaults to Math.floor(Date.now() / 1000).
-   * KSUID natively uses second precision.
+   * Timestamp in milliseconds since the Unix epoch.
+   * Defaults to Date.now().
+   * KSUID stores whole seconds, so sub-second precision is truncated.
    */
+  msecs?: number
+  /**
+   * Timestamp in seconds since the Unix epoch.
+   *
+   * @deprecated Use `msecs` instead. Will be removed at v1-rc.
+   */
+  // TODO(v1-rc): remove this alias (tracked in docs/STABILITY.md).
   secs?: number
 }
 
@@ -93,20 +101,14 @@ function ksuidFn<TBuf extends Uint8Array = Uint8Array>(
 function ksuidFn<TBuf extends Uint8Array = Uint8Array>(options?: KsuidOptions, buf?: TBuf, offset = 0): string | TBuf {
   const random = options?.random
   if (random && random.length < PAYLOAD_BYTES) {
-    throw new InvalidInputError('KSUID_RANDOM_BYTES_TOO_SHORT', 'Random bytes length must be >= 16 for KSUID')
+    throw new InvalidInputError('RANDOM_BYTES_TOO_SHORT', 'Random bytes length must be >= 16 for KSUID', {
+      strategy: 'ksuid',
+    })
   }
 
   let timestamp: number
-  const secs = options?.secs
+  const secs = options === undefined ? undefined : resolveTimestampSecs(options, KSUID_EPOCH, KSUID_MAX_SECS, 'ksuid')
   if (secs !== undefined) {
-    if (!Number.isInteger(secs) || secs < KSUID_EPOCH) {
-      throw new InvalidInputError('KSUID_TIMESTAMP_TOO_LOW', 'Timestamp must be >= KSUID epoch')
-    }
-
-    if (secs > KSUID_MAX_SECS) {
-      throw new InvalidInputError('KSUID_TIMESTAMP_TOO_HIGH', 'Timestamp must be <= maximum KSUID timestamp')
-    }
-
     timestamp = secs - KSUID_EPOCH
   } else {
     /**
@@ -124,8 +126,9 @@ function ksuidFn<TBuf extends Uint8Array = Uint8Array>(options?: KsuidOptions, b
   if (buf) {
     if (!isWritableRange(buf, offset, KSUID_BYTES)) {
       throw new BufferError(
-        'KSUID_BUFFER_OUT_OF_BOUNDS',
+        'BUFFER_OUT_OF_BOUNDS',
         `KSUID byte range ${offset}:${offset + KSUID_BYTES - 1} is out of buffer bounds`,
+        { strategy: 'ksuid' },
       )
     }
     writeKsuidBytesUnchecked(timestamp, payload, buf, offset)
@@ -155,8 +158,9 @@ function toBytes(id: string): Uint8Array {
 function fromBytes(bytes: Uint8Array): string {
   if (bytes.length !== KSUID_BYTES) {
     throw new BufferError(
-      'KSUID_BYTES_INVALID_LENGTH',
+      'BYTES_INVALID_LENGTH',
       `KSUID bytes must be exactly ${KSUID_BYTES} bytes, got ${bytes.length}`,
+      { strategy: 'ksuid' },
     )
   }
   return encodeBase62(bytes)