uniku 0.0.12 → 0.0.13

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'

package/src/nanoid/nanoid.ts

@@ -0,0 +1,248 @@
+import { InvalidInputError } from '../errors'
+
+/** Default URL-safe alphabet (64 characters): A-Z, a-z, 0-9, underscore, hyphen */
+export const URL_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789_-'
+
+const DEFAULT_SIZE = 21
+const MAX_SIZE = 2048
+const NANOID_REGEX = /^[A-Za-z0-9_-]+$/
+
+// Keep Nanoid's private pool for its default hot path. It consumes `size`
+// bytes directly without the shared helper's UUID/CUID2-oriented branches.
+const POOL_SIZE_MULTIPLIER = 128
+let pool: Uint8Array | undefined
+let poolOffset = 0
+
+function fillPool(bytes: number): void {
+  const size = bytes * POOL_SIZE_MULTIPLIER
+  if (!pool || pool.length < size) {
+    pool = new Uint8Array(size)
+    crypto.getRandomValues(pool)
+    poolOffset = 0
+  } else if (poolOffset + bytes > pool.length) {
+    crypto.getRandomValues(pool)
+    poolOffset = 0
+  }
+  poolOffset += bytes
+}
+
+export type NanoidOptions = {
+  /**
+   * Random bytes for deterministic output (testing).
+   * For power-of-2 alphabets (2, 4, 8, 16, 32, 64, 128, 256): exactly `size` bytes needed.
+   * For other alphabets: ~size * 2 bytes needed (rejection sampling).
+   */
+  random?: Uint8Array
+  /**
+   * Custom alphabet to use. Default: URL-safe A-Za-z0-9_-
+   * Must be 2-256 printable ASCII characters (32-126) with no duplicates.
+   */
+  alphabet?: string
+  /**
+   * Length of generated ID. Default: 21. Maximum: 2048.
+   */
+  size?: number
+}
+
+export type Nanoid = {
+  /** Generate nanoid with default settings */
+  (): string
+  /** Generate nanoid with custom size */
+  (size: number): string
+  /** Generate nanoid with options */
+  (options: NanoidOptions): string
+  /**
+   * Validate a nanoid string against the default URL-safe alphabet.
+   * Note: Does not validate IDs generated with custom alphabets.
+   */
+  isValid(id: unknown): id is string
+}
+
+/**
+ * Validate alphabet: 2-256 printable ASCII chars, no duplicates
+ */
+function validateAlphabet(alphabet: string): void {
+  if (alphabet.length < 2) {
+    throw new InvalidInputError('NANOID_ALPHABET_TOO_SHORT', 'Alphabet must contain at least 2 characters')
+  }
+  if (alphabet.length > 256) {
+    throw new InvalidInputError('NANOID_ALPHABET_TOO_LONG', 'Alphabet must not exceed 256 characters')
+  }
+  const seen = new Set<string>()
+  for (const char of alphabet) {
+    const code = char.charCodeAt(0)
+    if (code < 32 || code > 126) {
+      throw new InvalidInputError(
+        'NANOID_ALPHABET_INVALID_CHAR',
+        'Alphabet must contain only printable ASCII characters (32-126)',
+      )
+    }
+    if (seen.has(char)) {
+      throw new InvalidInputError('NANOID_ALPHABET_DUPLICATE', `Duplicate character in alphabet: "${char}"`)
+    }
+    seen.add(char)
+  }
+}
+
+/**
+ * Validate size parameter
+ */
+function validateSize(size: number): void {
+  if (!Number.isInteger(size) || size < 0) {
+    throw new InvalidInputError('NANOID_SIZE_INVALID', 'Size must be a non-negative integer')
+  }
+  if (size > MAX_SIZE) {
+    throw new InvalidInputError('NANOID_SIZE_TOO_LARGE', `Size must not exceed ${MAX_SIZE}`)
+  }
+}
+
+// Overloads
+function nanoidFn(): string
+function nanoidFn(size: number): string
+function nanoidFn(options: NanoidOptions): string
+function nanoidFn(sizeOrOptions?: number | NanoidOptions): string {
+  // ULTRA-FAST PATH: No arguments = default nanoid
+  // Uses simple pooled random bytes (npm nanoid style) for best performance
+  if (sizeOrOptions === undefined) {
+    fillPool(DEFAULT_SIZE)
+    let id = ''
+    for (let i = poolOffset - DEFAULT_SIZE; i < poolOffset; i++) {
+      id += URL_ALPHABET[pool![i] & 63]
+    }
+    return id
+  }
+
+  let size = DEFAULT_SIZE
+  let alphabet = URL_ALPHABET
+  let randomBytes: Uint8Array | undefined
+
+  if (typeof sizeOrOptions === 'number') {
+    size = sizeOrOptions
+  } else {
+    size = sizeOrOptions.size ?? DEFAULT_SIZE
+    alphabet = sizeOrOptions.alphabet ?? URL_ALPHABET
+    randomBytes = sizeOrOptions.random
+    if (sizeOrOptions.alphabet !== undefined) {
+      validateAlphabet(alphabet)
+    }
+  }
+
+  validateSize(size)
+
+  if (size === 0) return ''
+
+  const alphabetLen = alphabet.length
+
+  // FAST PATH: Power-of-2 alphabet (includes default 64-char)
+  // No rejection needed - each byte maps directly to a character
+  if ((alphabetLen & (alphabetLen - 1)) === 0) {
+    const mask = alphabetLen - 1
+    if (randomBytes && randomBytes.length < size) {
+      throw new InvalidInputError(
+        'NANOID_RANDOM_BYTES_INSUFFICIENT',
+        `Insufficient random bytes: need ${size}, have ${randomBytes.length}`,
+      )
+    }
+    const bytes = randomBytes?.subarray(0, size) ?? globalThis.crypto.getRandomValues(new Uint8Array(size))
+    let id = ''
+    for (let i = 0; i < size; i++) {
+      id += alphabet[bytes[i] & mask]
+    }
+    return id
+  }
+
+  // SLOW PATH: Rejection sampling for non-power-of-2 alphabets
+  // Calculate mask: smallest power-of-2 minus 1 that covers alphabet size
+  const mask = (2 << (31 - Math.clz32((alphabetLen - 1) | 1))) - 1
+  // Calculate step: random bytes per batch (1.6x accounts for rejection)
+  const step = Math.ceil((1.6 * mask * size) / alphabetLen)
+
+  let id = ''
+  let randomOffset = 0
+
+  while (id.length < size) {
+    let bytes: Uint8Array
+    if (randomBytes) {
+      if (randomBytes.length - randomOffset < step) {
+        throw new InvalidInputError(
+          'NANOID_RANDOM_BYTES_INSUFFICIENT',
+          `Insufficient random bytes: need at least ${step} more, have ${randomBytes.length - randomOffset}`,
+        )
+      }
+      bytes = randomBytes.subarray(randomOffset, randomOffset + step)
+      randomOffset += step
+    } else {
+      bytes = globalThis.crypto.getRandomValues(new Uint8Array(step))
+    }
+
+    for (let i = 0; i < bytes.length && id.length < size; i++) {
+      const index = bytes[i] & mask
+      if (index < alphabetLen) {
+        id += alphabet[index]
+      }
+      // Otherwise reject and continue (no modulo bias)
+    }
+  }
+
+  return id
+}
+
+/**
+ * Validate a nanoid string against the default URL-safe alphabet.
+ * Note: Does not validate IDs generated with custom alphabets.
+ */
+function isValid(id: unknown): id is string {
+  return typeof id === 'string' && id.length > 0 && NANOID_REGEX.test(id)
+}
+
+/**
+ * Generate a URL-friendly unique string ID.
+ *
+ * Nanoid is a tiny, secure, URL-friendly unique string ID generator.
+ * It uses a URL-safe alphabet (A-Za-z0-9_-) and generates 21-character
+ * IDs by default with 126 bits of entropy.
+ *
+ * Unlike UUID v7 or ULID, nanoid is NOT time-ordered. Use it for:
+ * - URL shorteners
+ * - Session tokens
+ * - Invite codes
+ * - Any case where you need short, random IDs
+ *
+ * @example Basic usage
+ * ```ts
+ * import { nanoid } from 'uniku/nanoid'
+ *
+ * const id = nanoid()
+ * // => "V1StGXR8_Z5jdHi6B-myT"
+ * ```
+ *
+ * @example Custom size
+ * ```ts
+ * const shortId = nanoid(10)
+ * // => "IRFa-VaY2b"
+ * ```
+ *
+ * @example Custom alphabet (hex)
+ * ```ts
+ * const hexId = nanoid({ alphabet: '0123456789abcdef', size: 12 })
+ * // => "4f90d13a42bc"
+ * ```
+ *
+ * @example Validation
+ * ```ts
+ * const maybeId: unknown = getUserInput()
+ * if (nanoid.isValid(maybeId)) {
+ *   // TypeScript knows maybeId is string
+ *   console.log(maybeId.length)
+ * }
+ * ```
+ *
+ * @throws {InvalidInputError} Size must be between 0 and 2048
+ * @throws {InvalidInputError} Alphabet must contain 2-256 unique printable ASCII characters
+ * @throws {InvalidInputError} Insufficient random bytes for requested size
+ */
+export const nanoid: Nanoid = Object.assign(nanoidFn, {
+  isValid,
+})
+
+export { InvalidInputError, UniqueIdError } from '../errors'

package/src/ulid/crockford.ts

@@ -0,0 +1,249 @@
+/**
+ * Crockford's Base32 encoding/decoding for ULID.
+ * Alphabet excludes I, L, O, U to avoid confusion with similar-looking characters.
+ */
+
+import { BufferError, ParseError } from '../errors'
+
+const ENCODING = '0123456789ABCDEFGHJKMNPQRSTVWXYZ'
+
+// Pre-computed decoding 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.
+const DECODING = new Uint8Array(65536)
+DECODING.fill(255) // 255 = invalid marker
+for (let i = 0; i < ENCODING.length; i += 1) {
+  const upper = ENCODING.charCodeAt(i)
+  const lower = ENCODING[i].toLowerCase().charCodeAt(0)
+  DECODING[upper] = i
+  DECODING[lower] = i
+}
+
+const TIME_LEN = 10
+const ULID_LEN = 26
+
+function invalidCharError(str: string, index: number): ParseError {
+  return new ParseError('ULID_INVALID_CHAR', `Invalid ULID character: ${str[index]}`)
+}
+
+function timestampOverflowError(): ParseError {
+  return new ParseError('ULID_TIMESTAMP_OVERFLOW', 'ULID timestamp exceeds 48 bits')
+}
+
+function decodeTimeChars(str: string): number {
+  const firstValue = DECODING[str.charCodeAt(0)]
+  if (firstValue === 255) {
+    throw invalidCharError(str, 0)
+  }
+
+  if (firstValue > 7) {
+    throw timestampOverflowError()
+  }
+
+  let time = firstValue
+  for (let i = 1; i < TIME_LEN; i += 1) {
+    const value = DECODING[str.charCodeAt(i)]
+    if (value === 255) {
+      throw invalidCharError(str, i)
+    }
+
+    time = time * 32 + value
+  }
+  return time
+}
+
+/**
+ * Encode a 48-bit timestamp to a 10-character Crockford Base32 string.
+ * Uses unrolled division for performance.
+ */
+export function encodeTime(time: number): string {
+  // Unrolled encoding - each step divides by 32 and extracts 5 bits
+  // Powers of 32: 32^9=0x200000000000, 32^8=0x10000000000, etc.
+  return (
+    ENCODING[Math.floor(time / 0x200000000000) & 0x1f] +
+    ENCODING[Math.floor(time / 0x10000000000) & 0x1f] +
+    ENCODING[Math.floor(time / 0x800000000) & 0x1f] +
+    ENCODING[Math.floor(time / 0x40000000) & 0x1f] +
+    ENCODING[Math.floor(time / 0x2000000) & 0x1f] +
+    ENCODING[Math.floor(time / 0x100000) & 0x1f] +
+    ENCODING[Math.floor(time / 0x8000) & 0x1f] +
+    ENCODING[Math.floor(time / 0x400) & 0x1f] +
+    ENCODING[Math.floor(time / 0x20) & 0x1f] +
+    ENCODING[time & 0x1f]
+  )
+}
+
+/**
+ * Encode 10 bytes (80 bits) of random data to a 16-character Crockford Base32 string.
+ */
+export function encodeRandom(bytes: Uint8Array): string {
+  // Each character encodes 5 bits. 80 bits = 16 characters.
+  // Single concatenation expression for optimal performance.
+  return (
+    ENCODING[(bytes[0] >> 3) & 0x1f] +
+    ENCODING[((bytes[0] << 2) | (bytes[1] >> 6)) & 0x1f] +
+    ENCODING[(bytes[1] >> 1) & 0x1f] +
+    ENCODING[((bytes[1] << 4) | (bytes[2] >> 4)) & 0x1f] +
+    ENCODING[((bytes[2] << 1) | (bytes[3] >> 7)) & 0x1f] +
+    ENCODING[(bytes[3] >> 2) & 0x1f] +
+    ENCODING[((bytes[3] << 3) | (bytes[4] >> 5)) & 0x1f] +
+    ENCODING[bytes[4] & 0x1f] +
+    ENCODING[(bytes[5] >> 3) & 0x1f] +
+    ENCODING[((bytes[5] << 2) | (bytes[6] >> 6)) & 0x1f] +
+    ENCODING[(bytes[6] >> 1) & 0x1f] +
+    ENCODING[((bytes[6] << 4) | (bytes[7] >> 4)) & 0x1f] +
+    ENCODING[((bytes[7] << 1) | (bytes[8] >> 7)) & 0x1f] +
+    ENCODING[(bytes[8] >> 2) & 0x1f] +
+    ENCODING[((bytes[8] << 3) | (bytes[9] >> 5)) & 0x1f] +
+    ENCODING[bytes[9] & 0x1f]
+  )
+}
+
+/**
+ * Decode a 10-character ULID timestamp string to Unix epoch milliseconds.
+ */
+export function decodeTime(str: string): number {
+  if (str.length !== TIME_LEN) {
+    throw new ParseError('ULID_INVALID_LENGTH', `ULID timestamp must be ${TIME_LEN} characters`)
+  }
+  return decodeTimeChars(str)
+}
+
+/**
+ * Decode the timestamp from a full 26-character ULID string.
+ */
+export function decodeUlidTime(str: string): number {
+  if (str.length !== ULID_LEN) {
+    throw new ParseError('ULID_INVALID_LENGTH', `ULID string must be ${ULID_LEN} characters`)
+  }
+  return decodeTimeChars(str)
+}
+
+/**
+ * Decode a 26-character ULID string to 16 bytes.
+ * Inlines all lookups to avoid intermediate array allocation.
+ */
+export function decodeToBytes(str: string): Uint8Array {
+  if (str.length !== ULID_LEN) {
+    throw new ParseError('ULID_INVALID_LENGTH', `ULID string must be ${ULID_LEN} characters`)
+  }
+
+  const bytes = new Uint8Array(16)
+
+  // Inline all 26 character lookups
+  const v0 = DECODING[str.charCodeAt(0)]
+  const v1 = DECODING[str.charCodeAt(1)]
+  const v2 = DECODING[str.charCodeAt(2)]
+  const v3 = DECODING[str.charCodeAt(3)]
+  const v4 = DECODING[str.charCodeAt(4)]
+  const v5 = DECODING[str.charCodeAt(5)]
+  const v6 = DECODING[str.charCodeAt(6)]
+  const v7 = DECODING[str.charCodeAt(7)]
+  const v8 = DECODING[str.charCodeAt(8)]
+  const v9 = DECODING[str.charCodeAt(9)]
+  const v10 = DECODING[str.charCodeAt(10)]
+  const v11 = DECODING[str.charCodeAt(11)]
+  const v12 = DECODING[str.charCodeAt(12)]
+  const v13 = DECODING[str.charCodeAt(13)]
+  const v14 = DECODING[str.charCodeAt(14)]
+  const v15 = DECODING[str.charCodeAt(15)]
+  const v16 = DECODING[str.charCodeAt(16)]
+  const v17 = DECODING[str.charCodeAt(17)]
+  const v18 = DECODING[str.charCodeAt(18)]
+  const v19 = DECODING[str.charCodeAt(19)]
+  const v20 = DECODING[str.charCodeAt(20)]
+  const v21 = DECODING[str.charCodeAt(21)]
+  const v22 = DECODING[str.charCodeAt(22)]
+  const v23 = DECODING[str.charCodeAt(23)]
+  const v24 = DECODING[str.charCodeAt(24)]
+  const v25 = DECODING[str.charCodeAt(25)]
+
+  // Validate all characters at once (255 = invalid marker, so any invalid
+  // character sets the 0x80 bit in the OR of all values)
+  if (
+    ((v0 |
+      v1 |
+      v2 |
+      v3 |
+      v4 |
+      v5 |
+      v6 |
+      v7 |
+      v8 |
+      v9 |
+      v10 |
+      v11 |
+      v12 |
+      v13 |
+      v14 |
+      v15 |
+      v16 |
+      v17 |
+      v18 |
+      v19 |
+      v20 |
+      v21 |
+      v22 |
+      v23 |
+      v24 |
+      v25) &
+      0x80) !==
+    0
+  ) {
+    // Find the invalid character for error message
+    for (let i = 0; i < ULID_LEN; i += 1) {
+      if (DECODING[str.charCodeAt(i)] === 255) {
+        throw invalidCharError(str, i)
+      }
+    }
+  }
+
+  if (v0 > 7) {
+    throw timestampOverflowError()
+  }
+
+  // Timestamp: first 10 characters -> bytes 0-5
+  bytes[0] = (v0 << 5) | v1
+  bytes[1] = (v2 << 3) | (v3 >> 2)
+  bytes[2] = (v3 << 6) | (v4 << 1) | (v5 >> 4)
+  bytes[3] = (v5 << 4) | (v6 >> 1)
+  bytes[4] = (v6 << 7) | (v7 << 2) | (v8 >> 3)
+  bytes[5] = (v8 << 5) | v9
+
+  // Random: last 16 characters -> bytes 6-15
+  bytes[6] = (v10 << 3) | (v11 >> 2)
+  bytes[7] = (v11 << 6) | (v12 << 1) | (v13 >> 4)
+  bytes[8] = (v13 << 4) | (v14 >> 1)
+  bytes[9] = (v14 << 7) | (v15 << 2) | (v16 >> 3)
+  bytes[10] = (v16 << 5) | v17
+  bytes[11] = (v18 << 3) | (v19 >> 2)
+  bytes[12] = (v19 << 6) | (v20 << 1) | (v21 >> 4)
+  bytes[13] = (v21 << 4) | (v22 >> 1)
+  bytes[14] = (v22 << 7) | (v23 << 2) | (v24 >> 3)
+  bytes[15] = (v24 << 5) | v25
+
+  return bytes
+}
+
+/**
+ * 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')
+  }
+
+  // Timestamp: bytes 0-5 -> 10 characters
+  let time = 0
+  for (let i = 0; i < 6; i += 1) {
+    time = time * 256 + bytes[i]
+  }
+  const timeStr = encodeTime(time)
+
+  // Random: bytes 6-15 -> 16 characters
+  const randomStr = encodeRandom(bytes.subarray(6, 16))
+
+  return timeStr + randomStr
+}