uniku 0.0.11 → 0.0.13

package/package.json

@@ -1,7 +1,7 @@
 {
   "private": false,
   "name": "uniku",
-  "version": "0.0.11",
+  "version": "0.0.13",
   "description": "Minimal, tree-shakeable UUID utilities for every JavaScript runtime",
   "author": {
     "name": "Alberto Schiabel",
@@ -45,69 +45,49 @@
     "access": "public"
   },
   "engines": {
-    "node": ">=24.13.0"
+    "node": ">=20.19.0"
   },
   "type": "module",
   "sideEffects": false,
   "files": [
+    "src/**/*.ts",
     "build",
     "README.md"
   ],
   "exports": {
     "./uuid/v4": {
       "types": "./build/uuid/v4.d.mts",
-      "import": {
-        "@jkomyno/source": "./src/uuid/v4.ts",
-        "default": "./build/uuid/v4.mjs"
-      },
+      "import": "./build/uuid/v4.mjs",
       "default": "./build/uuid/v4.mjs"
     },
     "./uuid/v7": {
       "types": "./build/uuid/v7.d.mts",
-      "import": {
-        "@jkomyno/source": "./src/uuid/v7.ts",
-        "default": "./build/uuid/v7.mjs"
-      },
+      "import": "./build/uuid/v7.mjs",
       "default": "./build/uuid/v7.mjs"
     },
     "./ulid": {
       "types": "./build/ulid/ulid.d.mts",
-      "import": {
-        "@jkomyno/source": "./src/ulid/ulid.ts",
-        "default": "./build/ulid/ulid.mjs"
-      },
+      "import": "./build/ulid/ulid.mjs",
       "default": "./build/ulid/ulid.mjs"
     },
     "./cuid2": {
       "types": "./build/cuid2/cuid2.d.mts",
-      "import": {
-        "@jkomyno/source": "./src/cuid2/cuid2.ts",
-        "default": "./build/cuid2/cuid2.mjs"
-      },
+      "import": "./build/cuid2/cuid2.mjs",
       "default": "./build/cuid2/cuid2.mjs"
     },
     "./nanoid": {
       "types": "./build/nanoid/nanoid.d.mts",
-      "import": {
-        "@jkomyno/source": "./src/nanoid/nanoid.ts",
-        "default": "./build/nanoid/nanoid.mjs"
-      },
+      "import": "./build/nanoid/nanoid.mjs",
       "default": "./build/nanoid/nanoid.mjs"
     },
     "./ksuid": {
       "types": "./build/ksuid/ksuid.d.mts",
-      "import": {
-        "@jkomyno/source": "./src/ksuid/ksuid.ts",
-        "default": "./build/ksuid/ksuid.mjs"
-      },
+      "import": "./build/ksuid/ksuid.mjs",
       "default": "./build/ksuid/ksuid.mjs"
     },
     "./errors": {
       "types": "./build/errors.d.mts",
-      "import": {
-        "@jkomyno/source": "./src/errors.ts",
-        "default": "./build/errors.mjs"
-      },
+      "import": "./build/errors.mjs",
       "default": "./build/errors.mjs"
     },
     "./package.json": "./package.json"
@@ -132,6 +112,9 @@
     "test:integration": "vitest --project integration run",
     "test:e2e": "pnpm --filter @uniku/e2e-cloudflare test:e2e",
     "test:e2e:cloudflare": "pnpm --filter @uniku/e2e-cloudflare test:e2e:cloudflare",
+    "smoke:publish": "node scripts/publish-smoke.mjs",
+    "smoke:runtime:bun": "bun scripts/runtime-smoke.mjs",
+    "smoke:runtime:deno": "deno run --node-modules-dir=manual scripts/runtime-smoke.mjs",
     "bench": "vitest bench --run --project unit",
     "bench:compat": "vitest bench ./__tests__/bench/compat.bench.ts --run --project unit",
     "bench:summary": "bun scripts/bench-summary.ts",

package/src/common/bytes.ts

@@ -0,0 +1,59 @@
+/**
+ * Common byte manipulation utilities shared across ID generators.
+ */
+
+/**
+ * Increment a byte array by 1 in-place, propagating carry from LSB to MSB.
+ * Mutates the input array directly - no allocation.
+ *
+ * Used by ULID and KSUID for monotonic ordering within the same time unit.
+ *
+ * @returns true if increment succeeded, false if all bytes overflowed to 0
+ */
+export function incrementBytesInPlace(bytes: Uint8Array): boolean {
+  for (let i = bytes.length - 1; i >= 0; i -= 1) {
+    if (bytes[i] < 255) {
+      bytes[i] += 1
+      return true
+    }
+    bytes[i] = 0
+  }
+
+  // All bytes overflowed to 0 - astronomically unlikely (1 in 2^80 for ULID, 1 in 2^128 for KSUID)
+  return false
+}
+
+/**
+ * Write a 48-bit timestamp as big-endian bytes.
+ * Used by UUID v7 and ULID for millisecond-precision timestamps.
+ *
+ * @param buf - Target buffer
+ * @param offset - Starting byte offset
+ * @param msecs - Milliseconds since Unix epoch (must fit in 48 bits)
+ */
+export function writeTimestamp48(buf: Uint8Array, offset: number, msecs: number): void {
+  buf[offset] = (msecs / 0x10000000000) & 0xff
+  buf[offset + 1] = (msecs / 0x100000000) & 0xff
+  buf[offset + 2] = (msecs / 0x1000000) & 0xff
+  buf[offset + 3] = (msecs / 0x10000) & 0xff
+  buf[offset + 4] = (msecs / 0x100) & 0xff
+  buf[offset + 5] = msecs & 0xff
+}
+
+/**
+ * Write a 32-bit timestamp as big-endian bytes.
+ * Used by KSUID for second-precision timestamps.
+ *
+ * `writeTimestamp32(buf, offset, timestamp)` is equivalent to `new DataView(buf.buffer, offset, 4).setUint32(offset, timestamp, false)`,
+ * but it's faster because it doesn't require creating a DataView object.
+ *
+ * @param buf - Target buffer
+ * @param offset - Starting byte offset
+ * @param secs - Seconds (must fit in 32 bits)
+ */
+export function writeTimestamp32(buf: Uint8Array, offset: number, secs: number): void {
+  buf[offset] = (secs >>> 24) & 0xff
+  buf[offset + 1] = (secs >>> 16) & 0xff
+  buf[offset + 2] = (secs >>> 8) & 0xff
+  buf[offset + 3] = secs & 0xff
+}

package/src/common/random.ts

@@ -0,0 +1,66 @@
+const randomFill = /*@__PURE__*/ globalThis.crypto.getRandomValues.bind(globalThis.crypto)
+
+/**
+ * Simple random byte pool for ID generation.
+ *
+ * Module-level state is per JavaScript isolate, so SharedArrayBuffer and Atomics
+ * only add overhead here. Returned views are consumed synchronously by callers.
+ */
+
+const POOL_SIZE = 256
+const pool = new Uint8Array(POOL_SIZE)
+let poolOffset = POOL_SIZE
+
+function refillPool(): void {
+  randomFill(pool)
+  poolOffset = 0
+}
+
+/**
+ * Return a view of `count` random bytes from the pool.
+ */
+export function randomBytes(count: number): Uint8Array {
+  if (count > POOL_SIZE) {
+    return randomFill(new Uint8Array(count))
+  }
+
+  if (poolOffset + count > POOL_SIZE) {
+    refillPool()
+  }
+
+  const start = poolOffset
+  poolOffset += count
+  return pool.subarray(start, poolOffset)
+}
+
+/**
+ * Generate a random unsigned 32-bit integer from the shared pool.
+ */
+export function randomUint32(): number {
+  if (poolOffset > POOL_SIZE - 4) {
+    refillPool()
+  }
+
+  const value =
+    (pool[poolOffset] * 0x1000000 +
+      pool[poolOffset + 1] * 0x10000 +
+      pool[poolOffset + 2] * 0x100 +
+      pool[poolOffset + 3]) >>>
+    0
+  poolOffset += 4
+  return value
+}
+
+/**
+ * Generate 16 bytes of cryptographically strong random data.
+ * Uses a pre-filled pool to minimize crypto API calls.
+ */
+export function rng(): Uint8Array {
+  if (poolOffset > POOL_SIZE - 16) {
+    refillPool()
+  }
+
+  const start = poolOffset
+  poolOffset += 16
+  return pool.subarray(start, poolOffset)
+}

package/src/cuid2/cuid2.ts

@@ -0,0 +1,211 @@
+import { sha3_512 } from '@noble/hashes/sha3.js'
+import { randomUint32 } from '../common/random'
+import { InvalidInputError } from '../errors'
+
+export type Cuid2Options = {
+  /**
+   * Length of the generated ID (2-32 characters).
+   * Default: 24
+   */
+  length?: number
+  /**
+   * Custom random bytes for deterministic testing.
+   * Must be at least 1 byte. For adequate entropy, use at least 16 bytes.
+   * Note: The fingerprint always uses cryptographically secure random bytes,
+   * regardless of this option.
+   */
+  random?: Uint8Array
+}
+
+export type Cuid2 = {
+  (options?: Cuid2Options): string
+  isValid(id: unknown): id is string
+}
+
+const DEFAULT_LENGTH = 24
+const MAX_LENGTH = 32
+const MIN_LENGTH = 2
+
+// Maximum initial counter value from cuid2 spec - provides ~29 bits of
+// initial entropy to prevent cross-process collisions at startup
+const INITIAL_COUNT_MAX = 476782367
+
+// Validation regex: first char must be a-z, rest can be a-z or 0-9
+const CUID2_REGEX = /^[a-z][0-9a-z]+$/
+
+// Base36 alphabet
+const ALPHABET = '0123456789abcdefghijklmnopqrstuvwxyz'
+const LETTER_ALPHABET = 'abcdefghijklmnopqrstuvwxyz'
+
+// Reusable TextEncoder instance (stateless, safe to share)
+const textEncoder = new TextEncoder()
+
+/**
+ * Module-level state for counter and fingerprint.
+ * Counter is initialized lazily on first call to prevent unnecessary crypto operations.
+ * Fingerprint is also generated lazily on first call.
+ */
+const state: { counter: number | undefined; fingerprint: string | undefined } = {
+  counter: undefined,
+  fingerprint: undefined,
+}
+
+/**
+ * Initialize counter using crypto for consistency with other entropy sources.
+ */
+function initializeCounter(): number {
+  return randomUint32() % (INITIAL_COUNT_MAX + 1)
+}
+
+// --- Base36 utilities ---
+
+function bufToBigInt(buf: Uint8Array): bigint {
+  let value = 0n
+  for (const byte of buf) {
+    value = value * 256n + BigInt(byte)
+  }
+  return value
+}
+
+function bigIntToBase36(value: bigint): string {
+  if (value === 0n) return '0'
+  const chars: string[] = []
+  while (value > 0n) {
+    chars.push(ALPHABET[Number(value % 36n)])
+    value = value / 36n
+  }
+  return chars.reverse().join('')
+}
+
+function randomLetter(random: () => number): string {
+  return LETTER_ALPHABET[Math.floor(random() * 26)]
+}
+
+function createEntropy(length: number, random: () => number): string {
+  const chars = new Array<string>(length)
+  for (let i = 0; i < length; i++) {
+    chars[i] = ALPHABET[Math.floor(random() * 36)]
+  }
+  return chars.join('')
+}
+
+// --- SHA3 hash wrapper ---
+
+function hash(input: string): Uint8Array {
+  return sha3_512(textEncoder.encode(input))
+}
+
+// --- Fingerprint generation ---
+
+const BIG_LENGTH = 32
+
+function createFingerprint(): string {
+  // Always use CSPRNG for fingerprint to ensure security regardless of custom random option
+  const random = getCryptoRandom
+  const globals = Object.keys(globalThis).toString()
+  const sourceString = globals + createEntropy(BIG_LENGTH, random)
+  const hashed = hash(sourceString)
+  return bigIntToBase36(bufToBigInt(hashed)).slice(1, BIG_LENGTH + 1)
+}
+
+// --- Random function factory ---
+
+/**
+ * Get a random number in [0, 1) using CUID2's own random pool.
+ */
+function getCryptoRandom(): number {
+  return randomUint32() / 0x100000000
+}
+
+function getRandomFn(random?: Uint8Array): () => number {
+  if (random) {
+    if (random.length === 0) {
+      throw new InvalidInputError('CUID2_RANDOM_BYTES_EMPTY', 'Random byte array cannot be empty')
+    }
+    let index = 0
+    return () => {
+      const value = random[index % random.length] / 256
+      index += 1
+      return value
+    }
+  }
+  return getCryptoRandom
+}
+
+// --- Main generator ---
+
+function cuid2Fn(options?: Cuid2Options): string {
+  const length = options?.length ?? DEFAULT_LENGTH
+
+  if (length < MIN_LENGTH || length > MAX_LENGTH) {
+    throw new InvalidInputError(
+      'CUID2_LENGTH_OUT_OF_RANGE',
+      `CUID2 length must be between ${MIN_LENGTH} and ${MAX_LENGTH}. Received: ${length}`,
+    )
+  }
+
+  const random = getRandomFn(options?.random)
+
+  // Initialize counter lazily on first call
+  if (state.counter === undefined) {
+    state.counter = initializeCounter()
+  }
+
+  // Initialize fingerprint lazily on first call (always uses CSPRNG)
+  if (state.fingerprint === undefined) {
+    state.fingerprint = createFingerprint()
+  }
+
+  const firstLetter = randomLetter(random)
+  const time = Date.now().toString(36)
+  state.counter += 1
+  const count = state.counter.toString(36)
+  const salt = createEntropy(length, random)
+
+  const hashInput = time + salt + count + state.fingerprint
+  const hashed = hash(hashInput)
+  const base36Hash = bigIntToBase36(bufToBigInt(hashed))
+
+  // Drop first char of hash to avoid histogram bias, prepend random letter
+  return firstLetter + base36Hash.slice(1, length)
+}
+
+// --- Validation (type guard) ---
+
+function isValid(id: unknown): id is string {
+  return typeof id === 'string' && id.length >= MIN_LENGTH && id.length <= MAX_LENGTH && CUID2_REGEX.test(id)
+}
+
+/**
+ * Generate a CUID2 string.
+ *
+ * CUID2 is a secure, collision-resistant identifier that hashes multiple
+ * entropy sources using SHA3-512. Unlike time-ordered IDs (ULID, UUID v7),
+ * CUID2 prevents enumeration attacks by making IDs non-predictable.
+ *
+ * Note: CUID2 does not provide toBytes/fromBytes because it is a string-native
+ * format with no canonical binary representation (unlike UUID's 16-byte format).
+ *
+ * @example
+ * ```ts
+ * import { cuid2 } from 'uniku/cuid2'
+ *
+ * const id = cuid2()
+ * // => "pfh0haxfpzowht3oi213cqos"
+ *
+ * // Custom length
+ * const shortId = cuid2({ length: 10 })
+ * // => "tz4a98xxat"
+ *
+ * // Validation (type guard)
+ * const maybeId: unknown = getUserInput()
+ * if (cuid2.isValid(maybeId)) {
+ *   console.log(maybeId.length) // TypeScript knows maybeId is string
+ * }
+ * ```
+ */
+export const cuid2: Cuid2 = Object.assign(cuid2Fn, {
+  isValid,
+})
+
+export { InvalidInputError, UniqueIdError } from '../errors'

package/src/errors.ts

@@ -0,0 +1,56 @@
+/**
+ * Base error for all uniku errors.
+ * Provides `_tag` for discriminated matching (compatible with Effect's `catchTag`)
+ * and `code` for machine-readable error identification.
+ */
+export abstract class UniqueIdError extends Error {
+  abstract readonly _tag: string
+  abstract readonly code: string
+
+  constructor(message: string) {
+    super(message)
+    this.name = this.constructor.name
+  }
+}
+
+/**
+ * Thrown when generator arguments are invalid (bad size, alphabet, length, timestamp, version).
+ */
+export class InvalidInputError extends UniqueIdError {
+  readonly _tag = 'InvalidInputError' as const
+
+  constructor(
+    readonly code: string,
+    message: string,
+  ) {
+    super(message)
+  }
+}
+
+/**
+ * Thrown when parsing/decoding an ID string that has invalid format or characters.
+ */
+export class ParseError extends UniqueIdError {
+  readonly _tag = 'ParseError' as const
+
+  constructor(
+    readonly code: string,
+    message: string,
+  ) {
+    super(message)
+  }
+}
+
+/**
+ * Thrown when a byte array or buffer is too short or an offset is out of bounds.
+ */
+export class BufferError extends UniqueIdError {
+  readonly _tag = 'BufferError' as const
+
+  constructor(
+    readonly code: string,
+    message: string,
+  ) {
+    super(message)
+  }
+}

package/src/ksuid/base62.ts

@@ -0,0 +1,103 @@
+import { BufferError, ParseError } from '../errors'
+
+/**
+ * Base62 encoding/decoding for KSUID.
+ * Alphabet: 0-9A-Za-z (standard Base62 ordering)
+ *
+ * KSUID binary format: 20 bytes (160 bits)
+ * - 4 bytes: timestamp (seconds since KSUID epoch)
+ * - 16 bytes: payload (cryptographically random)
+ *
+ * String format: 27 characters of Base62
+ */
+
+// Base62 alphabet: digits (0-9), uppercase (A-Z), lowercase (a-z)
+const BASE62_ALPHABET = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz'
+const BASE = 62n
+const MAX_KSUID_VALUE = (1n << 160n) - 1n
+const KSUID_BYTES = 20
+const KSUID_STRING_LEN = 27
+
+// Pre-computed decode table covering every UTF-16 code unit charCodeAt can
+// return, so lookups never go out of bounds and a single `=== 255` check
+// rejects invalid input (including non-ASCII) without a per-character range
+// check. Costs 64 KiB once at module load; valid inputs only touch the first
+// 128 bytes, so cache behavior is unaffected.
+// Note: Base62 is case-sensitive - 'A' (value 10) and 'a' (value 36) are different
+const DECODING = new Uint8Array(65536)
+DECODING.fill(255) // 255 = invalid marker
+
+for (let i = 0; i < BASE62_ALPHABET.length; i += 1) {
+  DECODING[BASE62_ALPHABET.charCodeAt(i)] = i
+}
+
+/**
+ * Encode a 20-byte KSUID to a 27-character Base62 string.
+ *
+ * Algorithm: Convert the 160-bit number to base 62 using BigInt.
+ * V8 has highly optimized BigInt operations for this size.
+ */
+export function encodeBase62(bytes: Uint8Array): string {
+  if (bytes.length < KSUID_BYTES) {
+    throw new BufferError(
+      'KSUID_BYTES_TOO_SHORT',
+      `KSUID bytes must be at least ${KSUID_BYTES} bytes, got ${bytes.length}`,
+    )
+  }
+
+  // Convert bytes to BigInt (big-endian)
+  let num = 0n
+  for (let i = 0; i < KSUID_BYTES; i += 1) {
+    num = (num << 8n) | BigInt(bytes[i])
+  }
+
+  // Convert to Base62 string (build from right to left)
+  // Direct string concatenation is faster than array + join in V8
+  let encoded = ''
+  while (num > 0n) {
+    const remainder = num % BASE
+    num = num / BASE
+    encoded = BASE62_ALPHABET[Number(remainder)] + encoded
+  }
+
+  // Pad the result with the zero-character ('0') to ensure a fixed length
+  return encoded.padStart(KSUID_STRING_LEN, '0')
+}
+
+/**
+ * Decode a 27-character Base62 string to a 20-byte KSUID.
+ *
+ * Algorithm: Convert Base62 string to BigInt, then to bytes.
+ * V8 has highly optimized BigInt operations.
+ */
+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}`,
+    )
+  }
+
+  // Convert Base62 string to BigInt
+  let num = 0n
+  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]}`)
+    }
+    num = num * BASE + BigInt(value)
+  }
+
+  if (num > MAX_KSUID_VALUE) {
+    throw new ParseError('KSUID_OVERFLOW', 'KSUID string exceeds 160-bit range')
+  }
+
+  // Convert BigInt to bytes (big-endian)
+  const bytes = new Uint8Array(KSUID_BYTES)
+  for (let i = KSUID_BYTES - 1; i >= 0; i -= 1) {
+    bytes[i] = Number(num & 0xffn)
+    num = num >> 8n
+  }
+
+  return bytes
+}