uniku 0.0.12 → 0.1.0

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
+}

package/src/ksuid/ksuid.ts

@@ -0,0 +1,195 @@
+import { writeTimestamp32 } from '../common/bytes'
+import { rng } from '../common/random'
+import { BufferError, InvalidInputError } from '../errors'
+import { decodeBase62, encodeBase62 } from './base62'
+
+/**
+ * KSUID (K-Sortable Unique Identifier)
+ *
+ * A 160-bit identifier consisting of:
+ * - 4 bytes: timestamp (seconds since KSUID epoch: May 13, 2014)
+ * - 16 bytes: cryptographically random payload
+ *
+ * Encoded as a 27-character Base62 string.
+ */
+
+// KSUID epoch: May 13, 2014 00:00:00 UTC (Unix timestamp in seconds)
+const KSUID_EPOCH = 1400000000
+
+const KSUID_BYTES = 20
+const KSUID_STRING_LEN = 27
+const TIMESTAMP_BYTES = 4
+const PAYLOAD_BYTES = 16
+const KSUID_MAX_SECS = KSUID_EPOCH + 0xffffffff
+// 2^160 - 1 in Base62 ('aWgEPTl1tmebfsQzFP4bxwgy80V'), derived from the
+// encoder so it cannot drift from the decoder's 160-bit overflow bound.
+const KSUID_MAX_STRING = encodeBase62(new Uint8Array(KSUID_BYTES).fill(0xff))
+
+// Validation regex: 27 alphanumeric characters
+// Note: Both cases are valid Base62 characters, but they decode to different values
+// (e.g., 'A' = 10, 'a' = 36). The regex validates format, not semantic equivalence.
+const KSUID_REGEX = /^[0-9A-Za-z]{27}$/
+
+export type KsuidOptions = {
+  /**
+   * 16 bytes of random data to use for KSUID payload.
+   */
+  random?: Uint8Array
+  /**
+   * Timestamp in seconds since Unix epoch.
+   * Defaults to Math.floor(Date.now() / 1000).
+   * KSUID natively uses second precision.
+   */
+  secs?: number
+}
+
+export type Ksuid = {
+  (): string
+  <TBuf extends Uint8Array = Uint8Array>(options: KsuidOptions | undefined, buf: TBuf, offset?: number): TBuf
+  (options?: KsuidOptions, 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 KSUID (all zeros) */
+  NIL: string
+  /** The max KSUID (maximum valid value) */
+  MAX: string
+}
+
+/**
+ * Write KSUID bytes 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`,
+    )
+  }
+
+  // Timestamp (32-bit big-endian seconds since KSUID epoch) -> bytes 0-3
+  writeTimestamp32(buf, offset, timestamp)
+
+  // Payload (128 bits) -> bytes 4-19
+  for (let i = 0; i < PAYLOAD_BYTES; i += 1) {
+    buf[offset + TIMESTAMP_BYTES + i] = payload[i]
+  }
+
+  return buf
+}
+
+/*
+ * Overload: no buffer => return a KSUID string.
+ */
+function ksuidFn(options?: KsuidOptions, buf?: undefined, offset?: number): string
+/*
+ * Overload: caller provides a buffer slice to fill with KSUID bytes.
+ */
+function ksuidFn<TBuf extends Uint8Array = Uint8Array>(
+  options: KsuidOptions | undefined,
+  buf: TBuf,
+  offset?: number,
+): TBuf
+function ksuidFn<TBuf extends Uint8Array = Uint8Array>(options?: KsuidOptions, buf?: TBuf, offset = 0): string | TBuf {
+  const random = options?.random
+  if (random && random.length < PAYLOAD_BYTES) {
+    throw new InvalidInputError('KSUID_RANDOM_BYTES_TOO_SHORT', 'Random bytes length must be >= 16 for KSUID')
+  }
+
+  let timestamp: number
+  const secs = options?.secs
+  if (secs !== undefined) {
+    if (secs < KSUID_EPOCH) {
+      throw new InvalidInputError('KSUID_TIMESTAMP_TOO_LOW', 'Timestamp must be >= KSUID epoch')
+    }
+
+    if (secs > KSUID_MAX_SECS) {
+      throw new InvalidInputError('KSUID_TIMESTAMP_TOO_HIGH', 'Timestamp must be <= maximum KSUID timestamp')
+    }
+
+    timestamp = secs - KSUID_EPOCH
+  } else {
+    /**
+     * Note: by default, Cloudflare Workers "freezes" time during request handling to prevent
+     * side-channel attacks. This means that Date.now() will return the same value for the entire
+     * duration of a request.
+     * Implications:
+     * - all KSUIDs generated within a single request will have the same timestamp.
+     */
+    timestamp = Math.floor(Date.now() / 1000) - KSUID_EPOCH
+  }
+
+  const payload = random ?? rng()
+
+  if (buf) {
+    ksuidBytes(timestamp, payload, buf, offset)
+    return buf
+  }
+
+  const bytes = ksuidBytes(timestamp, payload)
+
+  // String mode: create bytes then encode to Base62
+  return encodeBase62(bytes)
+}
+
+/**
+ * Convert a KSUID string to 20 bytes.
+ *
+ * Note: Base62 is case-sensitive. 'A' (value 10) and 'a' (value 36) decode
+ * to different byte values. This function accepts both cases as valid input.
+ */
+function toBytes(id: string): Uint8Array {
+  return decodeBase62(id)
+}
+
+/**
+ * Convert 20 bytes to a KSUID string.
+ */
+function fromBytes(bytes: Uint8Array): string {
+  return encodeBase62(bytes)
+}
+
+/**
+ * Extract the timestamp from a KSUID string.
+ * Returns Unix timestamp in milliseconds for API consistency with ulid/uuidv7.
+ * Note: KSUID only has second precision, so the returned value will always end in 000.
+ */
+function timestamp(id: string): number {
+  const bytes = decodeBase62(id)
+  // First 4 bytes are big-endian timestamp (seconds since KSUID epoch)
+  const secs = ((bytes[0] << 24) | (bytes[1] << 16) | (bytes[2] << 8) | bytes[3]) >>> 0
+  // Add KSUID epoch and convert to milliseconds
+  return (secs + KSUID_EPOCH) * 1000
+}
+
+/**
+ * Validate a KSUID string format and 160-bit numeric range.
+ */
+function isValid(id: unknown): id is string {
+  return (
+    typeof id === 'string' &&
+    id.length === KSUID_STRING_LEN &&
+    KSUID_REGEX.test(id) &&
+    // Fixed-length Base62 strings preserve numeric order because the alphabet is ASCII-sorted.
+    id <= KSUID_MAX_STRING
+  )
+}
+
+/**
+ * Generate a KSUID string or write the bytes into a buffer.
+ * Also includes helpers to convert to and from byte arrays.
+ */
+export const ksuid: Ksuid = Object.assign(ksuidFn, {
+  toBytes,
+  fromBytes,
+  timestamp,
+  isValid,
+  NIL: '000000000000000000000000000',
+  MAX: KSUID_MAX_STRING,
+})
+
+export { BufferError, InvalidInputError, ParseError, UniqueIdError } from '../errors'