uniku 0.0.12 → 0.1.0

package/src/uuid/v4.ts

@@ -0,0 +1,119 @@
+import { rng } from '../common/random'
+import { BufferError, InvalidInputError } from '../errors'
+import { formatUuid, parseUuid } from './common/uuid'
+
+const randomUUID = /*@__PURE__*/ globalThis.crypto.randomUUID.bind(globalThis.crypto)
+
+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 = {
+  (): string
+  <TBuf extends Uint8Array = Uint8Array>(options: UuidV4Options | undefined, buf: TBuf, offset?: number): TBuf
+  (options?: UuidV4Options, buf?: undefined, offset?: number): string
+  toBytes(id: string): Uint8Array
+  fromBytes(bytes: Uint8Array): string
+  isValid(id: unknown): id is string
+  /** The nil UUID (all zeros) */
+  NIL: string
+  /** The max UUID (all ones) */
+  MAX: string
+}
+
+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`,
+    )
+  }
+
+  // Copy 16 UUID bytes into the provided buffer slice.
+  for (let i = 0; i < 16; i += 1) {
+    buf[offset + i] = rnds[i]
+  }
+
+  return buf
+}
+
+/*
+ * Overload: no buffer => return a UUID string.
+ */
+function v4(options?: UuidV4Options, buf?: undefined, offset?: number): string
+/*
+ * Overload: caller provides a buffer slice to fill with UUID bytes.
+ */
+function v4<TBuf extends Uint8Array = Uint8Array>(options: UuidV4Options | undefined, buf: TBuf, offset?: number): TBuf
+function v4<TBuf extends Uint8Array = Uint8Array>(options?: UuidV4Options, buf?: TBuf, offset?: number): string | TBuf {
+  if (!buf && !options) {
+    return randomUUID()
+  }
+
+  return _v4(options, buf, offset)
+}
+
+function _v4<TBuf extends Uint8Array = Uint8Array>(
+  options?: UuidV4Options,
+  buf?: TBuf,
+  offset?: number,
+): string | TBuf {
+  const bytes = v4Bytes(options?.random ?? rng(), buf, offset)
+  return buf ?? formatUuid(bytes)
+}
+
+function isValid(id: unknown): id is string {
+  return typeof id === 'string' && UUID_V4_REGEX.test(id)
+}
+
+/**
+ * Generate a UUID v4 string or write the bytes into a buffer.
+ *
+ * UUID v4 is a purely random UUID with 122 bits of entropy. It's the most
+ * widely compatible UUID format, supported by virtually all databases and systems.
+ * Use when you need maximum compatibility and don't require time-ordering.
+ *
+ * @example
+ * ```ts
+ * import { uuidv4 } from 'uniku/uuid/v4'
+ *
+ * const id = uuidv4()
+ * // => "550e8400-e29b-41d4-a716-446655440000"
+ *
+ * // Validate
+ * uuidv4.isValid(id) // true
+ *
+ * // Convert to/from bytes (16 bytes)
+ * const bytes = uuidv4.toBytes(id)
+ * const restored = uuidv4.fromBytes(bytes)
+ * ```
+ */
+export const uuidv4: UuidV4 = Object.assign(v4, {
+  toBytes: parseUuid,
+  fromBytes: formatUuid,
+  isValid,
+  NIL: '00000000-0000-0000-0000-000000000000',
+  MAX: 'ffffffff-ffff-ffff-ffff-ffffffffffff',
+})
+
+export { BufferError, InvalidInputError, ParseError, UniqueIdError } from '../errors'

package/src/uuid/v7.ts

@@ -0,0 +1,182 @@
+import { rng } from '../common/random'
+import { BufferError, InvalidInputError } from '../errors'
+import { formatUuid, parseUuid } from './common/uuid'
+
+export type UuidV7Options = {
+  /**
+   * 16 bytes of random data to use for UUID generation.
+   * Note: Several bytes will be overwritten with timestamp, version, and variant data.
+   */
+  random?: Uint8Array
+  msecs?: number
+  seq?: number
+}
+
+export type UuidV7 = {
+  (): string
+  <TBuf extends Uint8Array = Uint8Array>(options: UuidV7Options | undefined, buf: TBuf, offset?: number): TBuf
+  (options?: UuidV7Options, buf?: undefined, offset?: number): string
+  toBytes(id: string): Uint8Array
+  fromBytes(bytes: Uint8Array): string
+  timestamp(id: string): number
+  isValid(id: unknown): id is string
+  /** The nil UUID (all zeros) */
+  NIL: string
+  /** The max UUID (all ones) */
+  MAX: string
+}
+
+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
+
+// Reusable buffer for string output path - avoids allocation per call.
+// Safe because bytes are consumed synchronously by formatUuid().
+const reusableBuf = new Uint8Array(16)
+
+type V7State = {
+  msecs: number
+  seq: number
+}
+
+/**
+ * Module-level state for maintaining monotonic ordering within the same millisecond.
+ *
+ * IMPORTANT: This state persists across all uuidv7() calls in the module's lifetime.
+ * - In serverless/edge functions with warm starts, state persists between invocations.
+ * - For isolated state, pass explicit `msecs` and `seq` via options.
+ * - Tests should mock Date.now() or provide explicit options for deterministic behavior.
+ */
+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]
+
+  // Keep this inline on the UUID v7 hot path. Using writeTimestamp48() here
+  // benchmarked slower than the direct byte writes.
+  buf[offset++] = (msecs / 0x10000000000) & 0xff
+  buf[offset++] = (msecs / 0x100000000) & 0xff
+  buf[offset++] = (msecs / 0x1000000) & 0xff
+  buf[offset++] = (msecs / 0x10000) & 0xff
+  buf[offset++] = (msecs / 0x100) & 0xff
+  buf[offset++] = msecs & 0xff
+
+  // Set version (7) and variant (10xx), then pack sequence and random tail bytes.
+  buf[offset++] = 0x70 | ((seq >>> 28) & 0x0f)
+  buf[offset++] = (seq >>> 20) & 0xff
+  buf[offset++] = 0x80 | ((seq >>> 14) & 0x3f)
+  buf[offset++] = (seq >>> 6) & 0xff
+  // Lower seq bits plus 2 random bits to complete the 128-bit payload.
+  buf[offset++] = ((seq << 2) & 0xff) | (rnds[10] & 0x03)
+  buf[offset++] = rnds[11]
+  buf[offset++] = rnds[12]
+  buf[offset++] = rnds[13]
+  buf[offset++] = rnds[14]
+  buf[offset++] = rnds[15]
+
+  return buf
+}
+
+/*
+ * Overload: no buffer => return a UUID string.
+ */
+function v7(options?: UuidV7Options, buf?: undefined, offset?: number): string
+/*
+ * Overload: caller provides a buffer slice to fill with UUID bytes.
+ */
+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)
+  } 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++
+      }
+    }
+
+    bytes = v7Bytes(rnds, state.msecs, state.seq, buf ?? reusableBuf, buf ? offset : 0)
+  }
+
+  return buf ? (bytes as TBuf) : formatUuid(bytes)
+}
+
+function timestamp(id: string): number {
+  const bytes = parseUuid(id)
+  let msecs = 0
+  for (let i = 0; i < 6; i += 1) {
+    msecs = msecs * 256 + bytes[i]
+  }
+  return msecs
+}
+
+function isValid(id: unknown): id is string {
+  return typeof id === 'string' && UUID_V7_REGEX.test(id)
+}
+
+/**
+ * Generate a UUID v7 string or write the bytes into a buffer.
+ *
+ * UUID v7 is a time-ordered UUID that embeds a Unix timestamp in milliseconds,
+ * making IDs naturally sortable by creation time. Ideal for database primary keys
+ * where chronological ordering improves index performance.
+ *
+ * @example
+ * ```ts
+ * import { uuidv7 } from 'uniku/uuid/v7'
+ *
+ * const id = uuidv7()
+ * // => "018e5e5c-7c8a-7000-8000-000000000000"
+ *
+ * // Extract timestamp
+ * const ts = uuidv7.timestamp(id)
+ * console.log(new Date(ts))
+ *
+ * // Validate
+ * uuidv7.isValid(id) // true
+ *
+ * // Convert to/from bytes
+ * const bytes = uuidv7.toBytes(id)
+ * const restored = uuidv7.fromBytes(bytes)
+ * ```
+ */
+export const uuidv7: UuidV7 = Object.assign(v7, {
+  toBytes: parseUuid,
+  fromBytes: formatUuid,
+  timestamp,
+  isValid,
+  NIL: '00000000-0000-0000-0000-000000000000',
+  MAX: 'ffffffff-ffff-ffff-ffff-ffffffffffff',
+})
+
+export { BufferError, InvalidInputError, ParseError, UniqueIdError } from '../errors'

package/build/random-DcKA4vF7.mjs

@@ -1,2 +0,0 @@
-const e=globalThis.crypto.getRandomValues.bind(globalThis.crypto),t=new Uint8Array(256);let n=256;function r(){n>240&&(e(t),n=0);let r=n;return n+=16,t.subarray(r,n)}export{r as t};
-//# sourceMappingURL=random-DcKA4vF7.mjs.map

package/build/random-DcKA4vF7.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"random-DcKA4vF7.mjs","names":[],"sources":["../src/common/random.ts"],"sourcesContent":["const randomFill = /*@__PURE__*/ globalThis.crypto.getRandomValues.bind(globalThis.crypto)\n\n/**\n * Simple, fast random byte pool for ID generation.\n * Uses plain JavaScript for maximum performance - no Atomics overhead.\n * Thread safety is not needed for typical ID generation use cases.\n */\n\nconst POOL_SIZE = 256\nconst rnds8Pool = new Uint8Array(POOL_SIZE)\nlet poolPtr = POOL_SIZE // Start exhausted to trigger first fill\n\n/**\n * Generate 16 bytes of cryptographically strong random data.\n * Uses a pre-filled pool to minimize crypto API calls.\n */\nexport function rng(): Uint8Array {\n  if (poolPtr > POOL_SIZE - 16) {\n    randomFill(rnds8Pool)\n    poolPtr = 0\n  }\n  // Return a view - consumed synchronously within the same call\n  const start = poolPtr\n  poolPtr += 16\n  return rnds8Pool.subarray(start, poolPtr)\n}\n"],"mappings":"AAAA,MAAM,EAA2B,WAAW,OAAO,gBAAgB,KAAK,WAAW,OAAO,CASpF,EAAY,IAAI,WAAW,IAAU,CAC3C,IAAI,EAAU,IAMd,SAAgB,GAAkB,CAC5B,EAAU,MACZ,EAAW,EAAU,CACrB,EAAU,GAGZ,IAAM,EAAQ,EAEd,MADA,IAAW,GACJ,EAAU,SAAS,EAAO,EAAQ"}