uniku 0.3.0 → 0.3.1

package/build/uuid/v7.d.mts

@@ -8,6 +8,9 @@ type UuidV7Options = {
   */
   random?: Uint8Array;
   msecs?: number;
+  /**
+  * Unsigned 32-bit sequence value.
+  */
   seq?: number;
 };
 type UuidV7 = {

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

@@ -1 +1 @@
-{"version":3,"file":"v7.d.mts","names":[],"sources":["../../src/uuid/v7.ts"],"mappings":";;;KAIY,aAAA;;;AAAZ;;EAKE,MAAA,GAAS,UAAA;EACT,KAAA;EACA,GAAA;AAAA;AAAA,KAGU,MAAA;EAAA;EAAA,cAEI,UAAA,GAAa,UAAA,EAAY,OAAA,EAAS,aAAA,cAA2B,GAAA,EAAK,IAAA,EAAM,MAAA,YAAkB,IAAA;EAAA,CACvG,OAAA,GAAU,aAAA,EAAe,GAAA,cAAiB,MAAA;EAC3C,OAAA,CAAQ,EAAA,WAAa,UAAA;EACrB,SAAA,CAAU,KAAA,EAAO,UAAA;EACjB,SAAA,CAAU,EAAA;EACV,OAAA,CAAQ,EAAA,YAAc,EAAA;EAEtB,GAAA;EAEA,GAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;cAmJW,MAAA,EAAQ,MAAA"}
+{"version":3,"file":"v7.d.mts","names":[],"sources":["../../src/uuid/v7.ts"],"mappings":";;;KAKY,aAAA;;;AAAZ;;EAKE,MAAA,GAAS,UAAA;EACT,KAAA;;;;EAIA,GAAA;AAAA;AAAA,KAGU,MAAA;EAAA;EAAA,cAEI,UAAA,GAAa,UAAA,EAAY,OAAA,EAAS,aAAA,cAA2B,GAAA,EAAK,IAAA,EAAM,MAAA,YAAkB,IAAA;EAAA,CACvG,OAAA,GAAU,aAAA,EAAe,GAAA,cAAiB,MAAA;EAC3C,OAAA,CAAQ,EAAA,WAAa,UAAA;EACrB,SAAA,CAAU,KAAA,EAAO,UAAA;EACjB,SAAA,CAAU,EAAA;EACV,OAAA,CAAQ,EAAA,YAAc,EAAA;EAEtB,GAAA;EAEA,GAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;cA2KW,MAAA,EAAQ,MAAA"}

package/build/uuid/v7.mjs

@@ -1,2 +1,2 @@
-import{r as e}from"../random-Chp-Nkzi.mjs";import{BufferError as t,InvalidInputError as n,ParseError as r,UniqueIdError as i}from"../errors.mjs";import{n as a,t as o}from"../uuid-BBjwHv7J.mjs";const s=/^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i,c=new Uint8Array(16),l={msecs:-1/0,seq:0};function u(e,r,i,a,o=0){if(e.length<16)throw new n(`UUID_RANDOM_BYTES_TOO_SHORT`,`Random bytes length must be >= 16`);if(o<0||o+16>a.length)throw new t(`UUID_BUFFER_OUT_OF_BOUNDS`,`UUID byte range ${o}:${o+15} is out of buffer bounds`);return r??=Date.now(),i??=e[6]<<23|e[7]<<16|e[8]<<8|e[9],a[o++]=r/1099511627776&255,a[o++]=r/4294967296&255,a[o++]=r/16777216&255,a[o++]=r/65536&255,a[o++]=r/256&255,a[o++]=r&255,a[o++]=112|i>>>28&15,a[o++]=i>>>20&255,a[o++]=128|i>>>14&63,a[o++]=i>>>6&255,a[o++]=i<<2&255|e[10]&3,a[o++]=e[11],a[o++]=e[12],a[o++]=e[13],a[o++]=e[14],a[o++]=e[15],a}function d(t,n,r){let i;if(t)i=u(t.random??e(),t.msecs,t.seq,n??c,n?r:0);else{let t=Date.now(),a=e();t>l.msecs?(l.seq=a[6]<<23|a[7]<<16|a[8]<<8|a[9],l.msecs=t):(l.seq=l.seq+1|0,l.seq<0&&(l.seq=0,l.msecs++)),i=u(a,l.msecs,l.seq,n??c,n?r:0)}return n?i:o(i)}function f(e){let t=a(e),n=0;for(let e=0;e<6;e+=1)n=n*256+t[e];return n}function p(e){return typeof e==`string`&&s.test(e)}const m=Object.assign(d,{toBytes:a,fromBytes:o,timestamp:f,isValid:p,NIL:`00000000-0000-0000-0000-000000000000`,MAX:`ffffffff-ffff-ffff-ffff-ffffffffffff`});export{t as BufferError,n as InvalidInputError,r as ParseError,i as UniqueIdError,m 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-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};
 //# 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 { BufferError, InvalidInputError } from '../errors'\nimport { formatUuid, 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  msecs?: number\n  seq?: number\n}\n\nexport type UuidV7 = {\n  (): string\n  <TBuf extends Uint8Array = Uint8Array>(options: UuidV7Options | undefined, buf: TBuf, offset?: number): TBuf\n  (options?: UuidV7Options, 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  /** 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\n\n// Reusable buffer for string output path - avoids allocation per call.\n// Safe because bytes are consumed synchronously by formatUuid().\nconst reusableBuf = new Uint8Array(16)\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 v7Bytes(\n  rnds: Uint8Array,\n  msecs: number | undefined,\n  seq: number | undefined,\n  buf: Uint8Array,\n  offset = 0,\n): Uint8Array {\n  if (rnds.length < 16) {\n    throw new InvalidInputError('UUID_RANDOM_BYTES_TOO_SHORT', 'Random bytes length must be >= 16')\n  }\n\n  if (offset < 0 || offset + 16 > buf.length) {\n    throw new BufferError(\n      'UUID_BUFFER_OUT_OF_BOUNDS',\n      `UUID byte range ${offset}:${offset + 15} is out of buffer bounds`,\n    )\n  }\n\n  msecs ??= Date.now()\n  // Derive a 31-bit sequence if not provided by the caller.\n  // Uses the same formula as the hot path for consistency.\n  seq ??= (rnds[6] << 23) | (rnds[7] << 16) | (rnds[8] << 8) | rnds[9]\n\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  return buf\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  let bytes: Uint8Array\n\n  if (options) {\n    bytes = v7Bytes(options.random ?? rng(), options.msecs, options.seq, buf ?? reusableBuf, buf ? offset : 0)\n  } else {\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    bytes = v7Bytes(rnds, state.msecs, state.seq, buf ?? reusableBuf, buf ? offset : 0)\n  }\n\n  return buf ? (bytes as TBuf) : formatUuid(bytes)\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":"iMA4BA,MAAM,EAAgB,yEAIhB,EAAc,IAAI,WAAW,EAAE,EAe/B,EAAiB,CAAE,MAAO,KAAW,IAAK,CAAE,EAElD,SAAS,EACP,EACA,EACA,EACA,EACA,EAAS,EACG,CACZ,GAAI,EAAK,OAAS,GAChB,MAAM,IAAI,EAAkB,8BAA+B,mCAAmC,EAGhG,GAAI,EAAS,GAAK,EAAS,GAAK,EAAI,OAClC,MAAM,IAAI,EACR,4BACA,mBAAmB,EAAO,GAAG,EAAS,GAAG,yBAC3C,EA8BF,MA3BA,KAAU,KAAK,IAAI,EAGnB,IAAS,EAAK,IAAM,GAAO,EAAK,IAAM,GAAO,EAAK,IAAM,EAAK,EAAK,GAIlE,EAAI,KAAa,EAAQ,cAAiB,IAC1C,EAAI,KAAa,EAAQ,WAAe,IACxC,EAAI,KAAa,EAAQ,SAAa,IACtC,EAAI,KAAa,EAAQ,MAAW,IACpC,EAAI,KAAa,EAAQ,IAAS,IAClC,EAAI,KAAY,EAAQ,IAGxB,EAAI,KAAY,IAAS,IAAQ,GAAM,GACvC,EAAI,KAAa,IAAQ,GAAM,IAC/B,EAAI,KAAY,IAAS,IAAQ,GAAM,GACvC,EAAI,KAAa,IAAQ,EAAK,IAE9B,EAAI,KAAc,GAAO,EAAK,IAAS,EAAK,IAAM,EAClD,EAAI,KAAY,EAAK,IACrB,EAAI,KAAY,EAAK,IACrB,EAAI,KAAY,EAAK,IACrB,EAAI,KAAY,EAAK,IACrB,EAAI,KAAY,EAAK,IAEd,CACT,CAUA,SAAS,EAAyC,EAAyB,EAAY,EAAgC,CACrH,IAAI,EAEJ,GAAI,EACF,EAAQ,EAAQ,EAAQ,QAAU,EAAI,EAAG,EAAQ,MAAO,EAAQ,IAAK,GAAO,EAAa,EAAM,EAAS,CAAC,MACpG,CAEL,IAAM,EAAM,KAAK,IAAI,EACf,EAAO,EAAI,EAGb,EAAM,EAAM,OACd,EAAM,IAAO,EAAK,IAAM,GAAO,EAAK,IAAM,GAAO,EAAK,IAAM,EAAK,EAAK,GACtE,EAAM,MAAQ,IAEd,EAAM,IAAO,EAAM,IAAM,EAAK,EAC1B,EAAM,IAAM,IACd,EAAM,IAAM,EACZ,EAAM,UAIV,EAAQ,EAAQ,EAAM,EAAM,MAAO,EAAM,IAAK,GAAO,EAAa,EAAM,EAAS,CAAC,CACpF,CAEA,OAAO,EAAO,EAAiB,EAAW,CAAK,CACjD,CAEA,SAAS,EAAU,EAAoB,CACrC,IAAM,EAAQ,EAAU,CAAE,EACtB,EAAQ,EACZ,IAAK,IAAI,EAAI,EAAG,EAAI,EAAG,GAAK,EAC1B,EAAQ,EAAQ,IAAM,EAAM,GAE9B,OAAO,CACT,CAEA,SAAS,EAAQ,EAA2B,CAC1C,OAAO,OAAO,GAAO,UAAY,EAAc,KAAK,CAAE,CACxD,CA4BA,MAAa,EAAiB,OAAO,OAAO,EAAI,CAC9C,QAAS,EACT,UAAW,EACX,YACA,UACA,IAAK,uCACL,IAAK,sCACP,CAAC"}
+{"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  msecs?: number\n  /**\n   * Unsigned 32-bit sequence value.\n   */\n  seq?: number\n}\n\nexport type UuidV7 = {\n  (): string\n  <TBuf extends Uint8Array = Uint8Array>(options: UuidV7Options | undefined, buf: TBuf, offset?: number): TBuf\n  (options?: UuidV7Options, 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  /** 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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"}

package/build/uuid-CnQIYoQi.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(`UUID_BYTES_INVALID_LENGTH`,`UUID bytes must be exactly 16 bytes, got ${t.length}`);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(`UUID_INVALID_LENGTH`,`UUID string must be 36 characters, got ${e.length}`);if(e[8]!==`-`||e[13]!==`-`||e[18]!==`-`||e[23]!==`-`)throw new t(`UUID_INVALID_SEPARATORS`,`UUID string has invalid separators at positions 8, 13, 18, 23. Received: "${e}"`);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(`UUID_INVALID_HEX_CHAR`,`UUID string contains invalid hex character at position ${o}`);i[o]?a[s]=c<<4:a[s]|=c}return a}export{s as n,c as r,o as t};
+//# sourceMappingURL=uuid-CnQIYoQi.mjs.map

package/build/uuid-CnQIYoQi.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid-CnQIYoQi.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      'UUID_BYTES_INVALID_LENGTH',\n      `UUID bytes must be exactly ${UUID_BYTE_LENGTH} bytes, got ${bytes.length}`,\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('UUID_INVALID_LENGTH', `UUID string must be 36 characters, got ${value.length}`)\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      'UUID_INVALID_SEPARATORS',\n      `UUID string has invalid separators at positions 8, 13, 18, 23. Received: \"${value}\"`,\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('UUID_INVALID_HEX_CHAR', `UUID string contains invalid hex character at position ${i}`)\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,4BACA,4CAA6D,EAAM,QACrE,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,sBAAuB,0CAA0C,EAAM,QAAQ,EAItG,GAAI,EAAM,KAAO,KAAO,EAAM,MAAQ,KAAO,EAAM,MAAQ,KAAO,EAAM,MAAQ,IAC9E,MAAM,IAAI,EACR,0BACA,6EAA6E,EAAM,EACrF,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,wBAAyB,0DAA0D,GAAG,EAGzG,EAAkB,GACpB,EAAM,GAAW,GAAU,EAE3B,EAAM,IAAY,CAEtB,CAEA,OAAO,CACT"}

package/build/validation-CTNpXm94.mjs

@@ -0,0 +1,2 @@
+function e(e,t,n){return Number.isInteger(e)&&e>=t&&e<=n}function t(e,t,n){return Number.isInteger(t)&&t>=0&&t+n<=e.length}export{t as n,e as t};
+//# sourceMappingURL=validation-CTNpXm94.mjs.map

package/build/validation-CTNpXm94.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation-CTNpXm94.mjs","names":[],"sources":["../src/common/validation.ts"],"sourcesContent":["export function isIntegerInRange(value: number, min: number, max: number): boolean {\n  return Number.isInteger(value) && value >= min && value <= max\n}\n\nexport function isWritableRange(buffer: Uint8Array, offset: number, byteLength: number): boolean {\n  return Number.isInteger(offset) && offset >= 0 && offset + byteLength <= buffer.length\n}\n"],"mappings":"AAAA,SAAgB,EAAiB,EAAe,EAAa,EAAsB,CACjF,OAAO,OAAO,UAAU,CAAK,GAAK,GAAS,GAAO,GAAS,CAC7D,CAEA,SAAgB,EAAgB,EAAoB,EAAgB,EAA6B,CAC/F,OAAO,OAAO,UAAU,CAAM,GAAK,GAAU,GAAK,EAAS,GAAc,EAAO,MAClF"}

package/package.json

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

package/src/common/validation.ts

@@ -0,0 +1,7 @@
+export function isIntegerInRange(value: number, min: number, max: number): boolean {
+  return Number.isInteger(value) && value >= min && value <= max
+}
+
+export function isWritableRange(buffer: Uint8Array, offset: number, byteLength: number): boolean {
+  return Number.isInteger(offset) && offset >= 0 && offset + byteLength <= buffer.length
+}

package/src/cuid2/cuid2.ts

@@ -135,14 +135,18 @@ function getRandomFn(random?: Uint8Array): () => number {
 // --- Main generator ---
 
 function cuid2Fn(options?: Cuid2Options): string {
-  const length = options?.length ?? DEFAULT_LENGTH
+  const requestedLength = options?.length
 
-  if (length < MIN_LENGTH || length > MAX_LENGTH) {
+  if (
+    requestedLength !== undefined &&
+    (!Number.isInteger(requestedLength) || requestedLength < MIN_LENGTH || requestedLength > MAX_LENGTH)
+  ) {
     throw new InvalidInputError(
       'CUID2_LENGTH_OUT_OF_RANGE',
-      `CUID2 length must be between ${MIN_LENGTH} and ${MAX_LENGTH}. Received: ${length}`,
+      `CUID2 length must be between ${MIN_LENGTH} and ${MAX_LENGTH}. Received: ${requestedLength}`,
     )
   }
+  const length = requestedLength ?? DEFAULT_LENGTH
 
   const random = getRandomFn(options?.random)
 

package/src/ksuid/ksuid.ts

@@ -1,5 +1,6 @@
 import { writeTimestamp32 } from '../common/bytes'
 import { rng } from '../common/random'
+import { isWritableRange } from '../common/validation'
 import { BufferError, InvalidInputError } from '../errors'
 import { decodeBase62, encodeBase62 } from './base62'
 
@@ -58,19 +59,9 @@ export type Ksuid = {
 }
 
 /**
- * Write KSUID bytes to a buffer.
+ * Write already-validated KSUID fields to a buffer.
  */
-function ksuidBytes(timestamp: number, payload: Uint8Array, buf?: Uint8Array, offset = 0): Uint8Array {
-  if (!buf) {
-    buf = new Uint8Array(KSUID_BYTES)
-    offset = 0
-  } else if (offset < 0 || offset + KSUID_BYTES > buf.length) {
-    throw new BufferError(
-      'KSUID_BUFFER_OUT_OF_BOUNDS',
-      `KSUID byte range ${offset}:${offset + KSUID_BYTES - 1} is out of buffer bounds`,
-    )
-  }
-
+function writeKsuidBytesUnchecked(timestamp: number, payload: Uint8Array, buf: Uint8Array, offset: number): void {
   // Timestamp (32-bit big-endian seconds since KSUID epoch) -> bytes 0-3
   writeTimestamp32(buf, offset, timestamp)
 
@@ -78,8 +69,6 @@ function ksuidBytes(timestamp: number, payload: Uint8Array, buf?: Uint8Array, of
   for (let i = 0; i < PAYLOAD_BYTES; i += 1) {
     buf[offset + TIMESTAMP_BYTES + i] = payload[i]
   }
-
-  return buf
 }
 
 /*
@@ -103,7 +92,7 @@ function ksuidFn<TBuf extends Uint8Array = Uint8Array>(options?: KsuidOptions, b
   let timestamp: number
   const secs = options?.secs
   if (secs !== undefined) {
-    if (secs < KSUID_EPOCH) {
+    if (!Number.isInteger(secs) || secs < KSUID_EPOCH) {
       throw new InvalidInputError('KSUID_TIMESTAMP_TOO_LOW', 'Timestamp must be >= KSUID epoch')
     }
 
@@ -126,11 +115,18 @@ function ksuidFn<TBuf extends Uint8Array = Uint8Array>(options?: KsuidOptions, b
   const payload = random ?? rng()
 
   if (buf) {
-    ksuidBytes(timestamp, payload, buf, offset)
+    if (!isWritableRange(buf, offset, KSUID_BYTES)) {
+      throw new BufferError(
+        'KSUID_BUFFER_OUT_OF_BOUNDS',
+        `KSUID byte range ${offset}:${offset + KSUID_BYTES - 1} is out of buffer bounds`,
+      )
+    }
+    writeKsuidBytesUnchecked(timestamp, payload, buf, offset)
     return buf
   }
 
-  const bytes = ksuidBytes(timestamp, payload)
+  const bytes = new Uint8Array(KSUID_BYTES)
+  writeKsuidBytesUnchecked(timestamp, payload, bytes, 0)
 
   // String mode: create bytes then encode to Base62
   return encodeBase62(bytes)
@@ -150,6 +146,12 @@ function toBytes(id: string): Uint8Array {
  * Convert 20 bytes to a KSUID string.
  */
 function fromBytes(bytes: Uint8Array): string {
+  if (bytes.length !== KSUID_BYTES) {
+    throw new BufferError(
+      'KSUID_BYTES_INVALID_LENGTH',
+      `KSUID bytes must be exactly ${KSUID_BYTES} bytes, got ${bytes.length}`,
+    )
+  }
   return encodeBase62(bytes)
 }
 

package/src/objectid/objectid.ts

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

package/src/tsid/tsid.ts

@@ -1,4 +1,5 @@
 import { randomUint32 } from '../common/random'
+import { isIntegerInRange, isWritableRange } from '../common/validation'
 import { BufferError, InvalidInputError } from '../errors'
 import { decodeTsidString, encodeTsidString } from './crockford64'
 
@@ -102,22 +103,60 @@ function pack(msecsDiff: bigint, node: number, counterBits: number, counter: num
   return (msecsDiff << BigInt(RANDOM_BITS)) | (BigInt(node) << BigInt(counterBits)) | BigInt(counter)
 }
 
-function writeTsidBytes(value: bigint, buf?: Uint8Array, offset = 0): Uint8Array {
-  if (!buf) {
-    buf = new Uint8Array(TSID_BYTES)
-    offset = 0
-  } else if (offset < 0 || offset + TSID_BYTES > buf.length) {
-    throw new BufferError(
-      'TSID_BUFFER_OUT_OF_BOUNDS',
-      `TSID byte range ${offset}:${offset + TSID_BYTES - 1} is out of buffer bounds`,
-    )
-  }
-
+function writeTsidBytesUnchecked(value: bigint, buf: Uint8Array, offset: number): void {
   for (let i = 0; i < TSID_BYTES; i += 1) {
     buf[offset + i] = Number((value >> BigInt((TSID_BYTES - 1 - i) * 8)) & 0xffn)
   }
+}
+
+type ResolvedTsidOptions = {
+  msecsDiff: bigint
+  node: number
+  counterBits: number
+  counter: number
+}
+
+function resolveTsidOptions(options: TsidOptions): ResolvedTsidOptions {
+  const nodeBits = options.nodeBits ?? DEFAULT_NODE_BITS
+  if (!isIntegerInRange(nodeBits, 0, MAX_NODE_BITS)) {
+    throw new InvalidInputError('TSID_NODE_BITS_OUT_OF_RANGE', `nodeBits must be between 0 and ${MAX_NODE_BITS}`)
+  }
 
-  return buf
+  const counterBits = RANDOM_BITS - nodeBits
+  const nodeMask = (1 << nodeBits) - 1
+  const counterMask = (1 << counterBits) - 1
+  const optNode = options.node
+  if (optNode !== undefined && !isIntegerInRange(optNode, 0, nodeMask)) {
+    throw new InvalidInputError('TSID_NODE_OUT_OF_RANGE', `node must be between 0 and ${nodeMask}`)
+  }
+
+  const optCounter = options.counter
+  if (optCounter !== undefined && !isIntegerInRange(optCounter, 0, counterMask)) {
+    throw new InvalidInputError('TSID_COUNTER_OUT_OF_RANGE', `counter must be between 0 and ${counterMask}`)
+  }
+
+  const epoch = options.epoch ?? TSID_EPOCH
+  if (!Number.isInteger(epoch)) {
+    throw new InvalidInputError('TSID_EPOCH_INVALID', 'epoch must be a finite integer')
+  }
+  const msecs = options.msecs ?? Date.now()
+  if (!Number.isInteger(msecs)) {
+    throw new InvalidInputError('TSID_TIMESTAMP_INVALID', 'msecs must be a finite integer')
+  }
+  const msecsDiff = BigInt(msecs) - BigInt(epoch)
+  if (msecsDiff < 0n || msecsDiff > MAX_TIMESTAMP_DIFF) {
+    throw new InvalidInputError(
+      'TSID_TIMESTAMP_OUT_OF_RANGE',
+      `msecs - epoch must be between 0 and ${MAX_TIMESTAMP_DIFF}`,
+    )
+  }
+
+  return {
+    msecsDiff,
+    node: optNode ?? randomUint32() & nodeMask,
+    counterBits,
+    counter: optCounter ?? randomUint32() & counterMask,
+  }
 }
 
 /*
@@ -139,44 +178,11 @@ function tsidFn<TBuf extends Uint8Array = Uint8Array>(options?: TsidOptions, buf
   let counter: number
 
   if (options) {
-    const nodeBits = options.nodeBits ?? DEFAULT_NODE_BITS
-    if (nodeBits < 0 || nodeBits > MAX_NODE_BITS) {
-      throw new InvalidInputError('TSID_NODE_BITS_OUT_OF_RANGE', `nodeBits must be between 0 and ${MAX_NODE_BITS}`)
-    }
-    counterBits = RANDOM_BITS - nodeBits
-    const nodeMask = (1 << nodeBits) - 1
-    const counterMask = (1 << counterBits) - 1
-
-    const optNode = options.node
-    if (optNode !== undefined) {
-      if (optNode < 0 || optNode > nodeMask) {
-        throw new InvalidInputError('TSID_NODE_OUT_OF_RANGE', `node must be between 0 and ${nodeMask}`)
-      }
-      node = optNode
-    } else {
-      node = randomUint32() & nodeMask
-    }
-
-    const optCounter = options.counter
-    if (optCounter !== undefined) {
-      if (optCounter < 0 || optCounter > counterMask) {
-        throw new InvalidInputError('TSID_COUNTER_OUT_OF_RANGE', `counter must be between 0 and ${counterMask}`)
-      }
-      counter = optCounter
-    } else {
-      counter = randomUint32() & counterMask
-    }
-
-    const epoch = options.epoch ?? TSID_EPOCH
-    const msecs = options.msecs ?? Date.now()
-    const diff = BigInt(msecs) - BigInt(epoch)
-    if (diff < 0n || diff > MAX_TIMESTAMP_DIFF) {
-      throw new InvalidInputError(
-        'TSID_TIMESTAMP_OUT_OF_RANGE',
-        `msecs - epoch must be between 0 and ${MAX_TIMESTAMP_DIFF}`,
-      )
-    }
-    msecsDiff = diff
+    const resolved = resolveTsidOptions(options)
+    msecsDiff = resolved.msecsDiff
+    node = resolved.node
+    counterBits = resolved.counterBits
+    counter = resolved.counter
   } else {
     // Lazily initialize the persistent node ID on first no-option call.
     if (state.node === undefined) {
@@ -212,7 +218,13 @@ function tsidFn<TBuf extends Uint8Array = Uint8Array>(options?: TsidOptions, buf
   const packed = pack(msecsDiff, node, counterBits, counter)
 
   if (buf) {
-    writeTsidBytes(packed, buf, offset)
+    if (!isWritableRange(buf, offset, TSID_BYTES)) {
+      throw new BufferError(
+        'TSID_BUFFER_OUT_OF_BOUNDS',
+        `TSID byte range ${offset}:${offset + TSID_BYTES - 1} is out of buffer bounds`,
+      )
+    }
+    writeTsidBytesUnchecked(packed, buf, offset)
     return buf
   }
 
@@ -223,7 +235,10 @@ function tsidFn<TBuf extends Uint8Array = Uint8Array>(options?: TsidOptions, buf
  * Convert a TSID bigint to 8 bytes.
  */
 function toBytes(id: bigint): Uint8Array {
-  return writeTsidBytes(id)
+  assertValidTsid(id)
+  const bytes = new Uint8Array(TSID_BYTES)
+  writeTsidBytesUnchecked(id, bytes, 0)
+  return bytes
 }
 
 /**
@@ -250,6 +265,10 @@ function fromBytes(bytes: Uint8Array): bigint {
  * `epoch` used at generation time if it was overridden from the default.
  */
 function timestamp(id: bigint, epoch: number = TSID_EPOCH): number {
+  assertValidTsid(id)
+  if (!Number.isInteger(epoch)) {
+    throw new InvalidInputError('TSID_EPOCH_INVALID', 'epoch must be a finite integer')
+  }
   return epoch + Number(id >> BigInt(RANDOM_BITS))
 }
 
@@ -263,6 +282,17 @@ function isValid(id: unknown): id is bigint {
 const NIL = 0n
 const MAX = (1n << 64n) - 1n
 
+function assertValidTsid(id: bigint): void {
+  if (id < NIL || id > MAX) {
+    throw new InvalidInputError('TSID_VALUE_OUT_OF_RANGE', `TSID value must be between ${NIL} and ${MAX}`)
+  }
+}
+
+function toString(id: bigint): string {
+  assertValidTsid(id)
+  return encodeTsidString(id)
+}
+
 /**
  * Generate a TSID bigint or write the bytes into a buffer.
  *
@@ -299,7 +329,7 @@ const MAX = (1n << 64n) - 1n
 export const tsid: Tsid = Object.assign(tsidFn, {
   toBytes,
   fromBytes,
-  toString: encodeTsidString,
+  toString,
   fromString: decodeTsidString,
   timestamp,
   isValid,

package/src/ulid/crockford.ts

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

package/src/ulid/ulid.ts

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