uniku 0.3.0 → 0.3.2

package/src/uuid/v4.ts

@@ -1,23 +1,31 @@
 import { rng } from '../common/random'
+import { isWritableRange } from '../common/validation'
 import { BufferError, InvalidInputError } from '../errors'
-import { formatUuid, parseUuid } from './common/uuid'
+import { formatUuid, formatUuidUnchecked, parseUuid } from './common/uuid'
 
 const randomUUID = /*@__PURE__*/ globalThis.crypto.randomUUID.bind(globalThis.crypto)
+const UUID_BYTES = 16
+const reusableBuf = new Uint8Array(UUID_BYTES)
 
 export type UuidV4Options = {
   /**
    * 16 bytes of random data to use for UUID generation.
-   * Note: Bytes at index 6 and 8 will be modified in-place to set version/variant bits.
    */
   random?: Uint8Array
 }
 
 export type UuidV4 = {
+  /** Generate a random UUID v4 string. */
   (): string
+  /** Generate a UUID v4 with explicit options or write its 16 canonical bytes into a caller-owned buffer. */
   <TBuf extends Uint8Array = Uint8Array>(options: UuidV4Options | undefined, buf: TBuf, offset?: number): TBuf
+  /** Generate a UUID v4 string with optional deterministic random bytes. */
   (options?: UuidV4Options, buf?: undefined, offset?: number): string
+  /** Convert a UUID v4 string to its canonical 16-byte representation. */
   toBytes(id: string): Uint8Array
+  /** Convert 16 canonical UUID bytes to a UUID v4 string. */
   fromBytes(bytes: Uint8Array): string
+  /** Return whether a value is a syntactically valid UUID v4 string. */
   isValid(id: unknown): id is string
   /** The nil UUID (all zeros) */
   NIL: string
@@ -27,34 +35,15 @@ export type UuidV4 = {
 
 const UUID_V4_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i
 
-function v4Bytes(rnds: Uint8Array, buf?: Uint8Array, offset = 0): Uint8Array {
-  if (rnds.length < 16) {
-    throw new InvalidInputError('UUID_RANDOM_BYTES_TOO_SHORT', 'Random bytes length must be >= 16')
-  }
-
-  // Set RFC 4122 version (4) and variant (10xx) bits.
-  // Note: This modifies the input array in-place.
-  rnds[6] = (rnds[6] & 0x0f) | 0x40
-  rnds[8] = (rnds[8] & 0x3f) | 0x80
-
-  if (!buf) {
-    // No output buffer provided - return the modified random bytes directly
-    return rnds
-  }
-
-  if (offset < 0 || offset + 16 > buf.length) {
-    throw new BufferError(
-      'UUID_BUFFER_OUT_OF_BOUNDS',
-      `UUID byte range ${offset}:${offset + 15} is out of buffer bounds`,
-    )
-  }
-
+function writeV4BytesUnchecked(rnds: Uint8Array, buf: Uint8Array, offset: number): void {
   // Copy 16 UUID bytes into the provided buffer slice.
-  for (let i = 0; i < 16; i += 1) {
+  for (let i = 0; i < UUID_BYTES; i += 1) {
     buf[offset + i] = rnds[i]
   }
 
-  return buf
+  // Set RFC 4122 version (4) and variant (10xx) bits on owned output only.
+  buf[offset + 6] = (buf[offset + 6] & 0x0f) | 0x40
+  buf[offset + 8] = (buf[offset + 8] & 0x3f) | 0x80
 }
 
 /*
@@ -78,8 +67,22 @@ function _v4<TBuf extends Uint8Array = Uint8Array>(
   buf?: TBuf,
   offset?: number,
 ): string | TBuf {
-  const bytes = v4Bytes(options?.random ?? rng(), buf, offset)
-  return buf ?? formatUuid(bytes)
+  const random = options?.random
+  if (random && random.length < UUID_BYTES) {
+    throw new InvalidInputError('UUID_RANDOM_BYTES_TOO_SHORT', `Random bytes length must be >= ${UUID_BYTES}`)
+  }
+
+  const outputOffset = buf ? (offset ?? 0) : 0
+  if (buf && !isWritableRange(buf, outputOffset, UUID_BYTES)) {
+    throw new BufferError(
+      'UUID_BUFFER_OUT_OF_BOUNDS',
+      `UUID byte range ${outputOffset}:${outputOffset + UUID_BYTES - 1} is out of buffer bounds`,
+    )
+  }
+
+  const output = buf ?? reusableBuf
+  writeV4BytesUnchecked(random ?? rng(), output, outputOffset)
+  return buf ?? formatUuidUnchecked(output)
 }
 
 function isValid(id: unknown): id is string {

package/src/uuid/v7.ts

@@ -1,6 +1,7 @@
 import { rng } from '../common/random'
+import { isIntegerInRange, isWritableRange } from '../common/validation'
 import { BufferError, InvalidInputError } from '../errors'
-import { formatUuid, parseUuid } from './common/uuid'
+import { formatUuid, formatUuidUnchecked, parseUuid } from './common/uuid'
 
 export type UuidV7Options = {
   /**
@@ -8,17 +9,31 @@ export type UuidV7Options = {
    * Note: Several bytes will be overwritten with timestamp, version, and variant data.
    */
   random?: Uint8Array
+  /**
+   * Timestamp in milliseconds since Unix epoch.
+   * Defaults to Date.now().
+   */
   msecs?: number
+  /**
+   * Unsigned 32-bit sequence value.
+   */
   seq?: number
 }
 
 export 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. */
   (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. */
   timestamp(id: string): number
+  /** Return whether a value is a syntactically valid UUID v7 string. */
   isValid(id: unknown): id is string
   /** The nil UUID (all zeros) */
   NIL: string
@@ -27,10 +42,13 @@ export type UuidV7 = {
 }
 
 const 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
+const UUID_BYTES = 16
+const MAX_MSECS = 0xffffffffffff
+const MAX_SEQ = 0xffffffff
 
 // Reusable buffer for string output path - avoids allocation per call.
-// Safe because bytes are consumed synchronously by formatUuid().
-const reusableBuf = new Uint8Array(16)
+// Safe because bytes are consumed synchronously by formatUuidUnchecked().
+const reusableBuf = new Uint8Array(UUID_BYTES)
 
 type V7State = {
   msecs: number
@@ -47,29 +65,7 @@ type V7State = {
  */
 const state: V7State = { msecs: -Infinity, seq: 0 }
 
-function v7Bytes(
-  rnds: Uint8Array,
-  msecs: number | undefined,
-  seq: number | undefined,
-  buf: Uint8Array,
-  offset = 0,
-): Uint8Array {
-  if (rnds.length < 16) {
-    throw new InvalidInputError('UUID_RANDOM_BYTES_TOO_SHORT', 'Random bytes length must be >= 16')
-  }
-
-  if (offset < 0 || offset + 16 > buf.length) {
-    throw new BufferError(
-      'UUID_BUFFER_OUT_OF_BOUNDS',
-      `UUID byte range ${offset}:${offset + 15} is out of buffer bounds`,
-    )
-  }
-
-  msecs ??= Date.now()
-  // Derive a 31-bit sequence if not provided by the caller.
-  // Uses the same formula as the hot path for consistency.
-  seq ??= (rnds[6] << 23) | (rnds[7] << 16) | (rnds[8] << 8) | rnds[9]
-
+function writeV7BytesUnchecked(rnds: Uint8Array, msecs: number, seq: number, buf: Uint8Array, offset: number): void {
   // Keep this inline on the UUID v7 hot path. Using writeTimestamp48() here
   // benchmarked slower than the direct byte writes.
   buf[offset++] = (msecs / 0x10000000000) & 0xff
@@ -91,8 +87,50 @@ function v7Bytes(
   buf[offset++] = rnds[13]
   buf[offset++] = rnds[14]
   buf[offset++] = rnds[15]
+}
+
+function writeV7Bytes(rnds: Uint8Array, msecs: number, seq: number, buf: Uint8Array, offset: number): void {
+  if (!isWritableRange(buf, offset, UUID_BYTES)) {
+    throw new BufferError(
+      'UUID_BUFFER_OUT_OF_BOUNDS',
+      `UUID byte range ${offset}:${offset + UUID_BYTES - 1} is out of buffer bounds`,
+    )
+  }
+  writeV7BytesUnchecked(rnds, msecs, seq, buf, offset)
+}
+
+function v7WithOptions<TBuf extends Uint8Array = Uint8Array>(
+  options: UuidV7Options,
+  buf?: TBuf,
+  offset = 0,
+): string | TBuf {
+  const optMsecs = options.msecs
+  if (optMsecs !== undefined && !isIntegerInRange(optMsecs, 0, MAX_MSECS)) {
+    throw new InvalidInputError(
+      'UUID_TIMESTAMP_OUT_OF_RANGE',
+      `Timestamp must be an integer between 0 and ${MAX_MSECS}`,
+    )
+  }
+  const optSeq = options.seq
+  if (optSeq !== undefined && !isIntegerInRange(optSeq, 0, MAX_SEQ)) {
+    throw new InvalidInputError('UUID_SEQUENCE_OUT_OF_RANGE', `Sequence must be an integer between 0 and ${MAX_SEQ}`)
+  }
+  const optRandom = options.random
+  if (optRandom && optRandom.length < UUID_BYTES) {
+    throw new InvalidInputError('UUID_RANDOM_BYTES_TOO_SHORT', `Random bytes length must be >= ${UUID_BYTES}`)
+  }
 
-  return buf
+  const rnds = optRandom ?? rng()
+  const msecs = optMsecs ?? Date.now()
+  // Derive a 31-bit sequence if not provided by the caller, matching the default hot path.
+  const seq = optSeq ?? (rnds[6] << 23) | (rnds[7] << 16) | (rnds[8] << 8) | rnds[9]
+
+  if (buf) {
+    writeV7Bytes(rnds, msecs, seq, buf, offset)
+    return buf
+  }
+  writeV7BytesUnchecked(rnds, msecs, seq, reusableBuf, 0)
+  return formatUuidUnchecked(reusableBuf)
 }
 
 /*
@@ -104,31 +142,32 @@ function v7(options?: UuidV7Options, buf?: undefined, offset?: number): string
  */
 function v7<TBuf extends Uint8Array = Uint8Array>(options: UuidV7Options | undefined, buf: TBuf, offset?: number): TBuf
 function v7<TBuf extends Uint8Array = Uint8Array>(options?: UuidV7Options, buf?: TBuf, offset?: number): string | TBuf {
-  let bytes: Uint8Array
-
   if (options) {
-    bytes = v7Bytes(options.random ?? rng(), options.msecs, options.seq, buf ?? reusableBuf, buf ? offset : 0)
+    return v7WithOptions(options, buf, offset)
+  }
+
+  // HOT PATH: Inline state management and byte generation for best performance
+  const now = Date.now()
+  const rnds = rng()
+
+  // Update state (inlined for performance)
+  if (now > state.msecs) {
+    state.seq = (rnds[6] << 23) | (rnds[7] << 16) | (rnds[8] << 8) | rnds[9]
+    state.msecs = now
   } else {
-    // HOT PATH: Inline state management and byte generation for best performance
-    const now = Date.now()
-    const rnds = rng()
-
-    // Update state (inlined for performance)
-    if (now > state.msecs) {
-      state.seq = (rnds[6] << 23) | (rnds[7] << 16) | (rnds[8] << 8) | rnds[9]
-      state.msecs = now
-    } else {
-      state.seq = (state.seq + 1) | 0
-      if (state.seq < 0) {
-        state.seq = 0
-        state.msecs++
-      }
+    state.seq = (state.seq + 1) | 0
+    if (state.seq < 0) {
+      state.seq = 0
+      state.msecs++
     }
-
-    bytes = v7Bytes(rnds, state.msecs, state.seq, buf ?? reusableBuf, buf ? offset : 0)
   }
 
-  return buf ? (bytes as TBuf) : formatUuid(bytes)
+  if (buf) {
+    writeV7Bytes(rnds, state.msecs, state.seq, buf, offset ?? 0)
+    return buf
+  }
+  writeV7BytesUnchecked(rnds, state.msecs, state.seq, reusableBuf, 0)
+  return formatUuidUnchecked(reusableBuf)
 }
 
 function timestamp(id: string): number {

package/build/uuid-BBjwHv7J.mjs

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

package/build/uuid-BBjwHv7J.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"uuid-BBjwHv7J.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 { 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  // 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":"0CAYA,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,CAIpD,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"}