s3db.js 18.0.11-next.1534f717 → 18.0.11-next.e8e71b5b

package/src/concerns/id/generators/ulid.ts

@@ -0,0 +1,249 @@
+import { random80 } from '../entropy.js';
+import { CROCKFORD_BASE32 } from '../alphabets.js';
+
+const ENCODING = CROCKFORD_BASE32;
+const ENCODING_LEN = ENCODING.length;
+const TIME_LEN = 10;
+const RANDOM_LEN = 16;
+const ULID_LEN = TIME_LEN + RANDOM_LEN;
+
+const TIME_MAX = Math.pow(2, 48) - 1;
+
+let lastTime = 0;
+let lastRandom = 0n;
+
+/**
+ * Generate a ULID (Universally Unique Lexicographically Sortable Identifier).
+ *
+ * Structure (128 bits total):
+ * - 48 bits: Unix timestamp in milliseconds (encoded as 10 Crockford Base32 chars)
+ * - 80 bits: Random (encoded as 16 Crockford Base32 chars)
+ *
+ * Format: TTTTTTTTTTRRRRRRRRRRRRRRRRR (26 characters)
+ *
+ * Features:
+ * - Lexicographically sortable by timestamp
+ * - Case insensitive
+ * - No special characters (URL safe)
+ * - 1.21e+24 unique ULIDs per millisecond
+ *
+ * Monotonic: If called multiple times within the same millisecond,
+ * the random component is incremented to ensure sortability.
+ */
+export function ulid(timestamp?: number): string {
+  const now = timestamp ?? Date.now();
+
+  if (now > TIME_MAX) {
+    throw new Error('ULID timestamp overflow: timestamp exceeds 48 bits');
+  }
+
+  let randomPart: bigint;
+
+  if (now === lastTime) {
+    lastRandom += 1n;
+    if (lastRandom > 0xFFFFFFFFFFFFFFFFFFFFn) {
+      throw new Error('ULID random overflow: too many ULIDs in same millisecond');
+    }
+    randomPart = lastRandom;
+  } else {
+    randomPart = random80();
+    lastTime = now;
+    lastRandom = randomPart;
+  }
+
+  return encodeTime(now) + encodeRandom(randomPart);
+}
+
+/**
+ * Generate a non-monotonic ULID.
+ * Does not increment random part for same-millisecond calls.
+ * Use when strict sortability within millisecond is not required.
+ */
+export function ulidNonMonotonic(timestamp?: number): string {
+  const now = timestamp ?? Date.now();
+
+  if (now > TIME_MAX) {
+    throw new Error('ULID timestamp overflow: timestamp exceeds 48 bits');
+  }
+
+  return encodeTime(now) + encodeRandom(random80());
+}
+
+/**
+ * Encode timestamp to Crockford Base32 (10 characters).
+ */
+function encodeTime(timestamp: number): string {
+  let time = timestamp;
+  let str = '';
+
+  for (let i = TIME_LEN - 1; i >= 0; i--) {
+    const mod = time % ENCODING_LEN;
+    str = ENCODING[mod]! + str;
+    time = Math.floor(time / ENCODING_LEN);
+  }
+
+  return str;
+}
+
+/**
+ * Encode random 80-bit value to Crockford Base32 (16 characters).
+ */
+function encodeRandom(random: bigint): string {
+  let str = '';
+
+  for (let i = RANDOM_LEN - 1; i >= 0; i--) {
+    const mod = Number(random % BigInt(ENCODING_LEN));
+    str = ENCODING[mod]! + str;
+    random = random / BigInt(ENCODING_LEN);
+  }
+
+  return str;
+}
+
+/**
+ * Decode a ULID timestamp to milliseconds.
+ */
+export function decodeTime(id: string): number {
+  if (id.length !== ULID_LEN) {
+    throw new Error(`Invalid ULID length: expected ${ULID_LEN}, got ${id.length}`);
+  }
+
+  const timeStr = id.slice(0, TIME_LEN).toUpperCase();
+  let time = 0;
+
+  for (let i = 0; i < TIME_LEN; i++) {
+    const char = timeStr[i]!;
+    const index = ENCODING.indexOf(char);
+
+    if (index === -1) {
+      throw new Error(`Invalid ULID character: ${char}`);
+    }
+
+    time = time * ENCODING_LEN + index;
+  }
+
+  return time;
+}
+
+/**
+ * Decode a ULID to Date object.
+ */
+export function decodeDate(id: string): Date {
+  return new Date(decodeTime(id));
+}
+
+/**
+ * Validate if a string is a valid ULID.
+ */
+export function isValidUlid(id: string): boolean {
+  if (id.length !== ULID_LEN) {
+    return false;
+  }
+
+  const upper = id.toUpperCase();
+  for (const char of upper) {
+    if (!ENCODING.includes(char)) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Convert ULID to UUID format.
+ * Returns a UUID string representation of the ULID bytes.
+ */
+export function ulidToUuid(id: string): string {
+  const bytes = ulidToBytes(id);
+  const hex = Array.from(bytes)
+    .map(b => b.toString(16).padStart(2, '0'))
+    .join('');
+
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+/**
+ * Convert ULID to byte array.
+ */
+export function ulidToBytes(id: string): Uint8Array {
+  if (id.length !== ULID_LEN) {
+    throw new Error(`Invalid ULID length: expected ${ULID_LEN}, got ${id.length}`);
+  }
+
+  const upper = id.toUpperCase();
+  const bytes = new Uint8Array(16);
+
+  let value = 0n;
+  for (let i = 0; i < ULID_LEN; i++) {
+    const char = upper[i]!;
+    const index = ENCODING.indexOf(char);
+    if (index === -1) {
+      throw new Error(`Invalid ULID character: ${char}`);
+    }
+    value = value * BigInt(ENCODING_LEN) + BigInt(index);
+  }
+
+  for (let i = 15; i >= 0; i--) {
+    bytes[i] = Number(value & 0xFFn);
+    value = value >> 8n;
+  }
+
+  return bytes;
+}
+
+/**
+ * Convert byte array to ULID.
+ */
+export function bytesToUlid(bytes: Uint8Array): string {
+  if (bytes.length !== 16) {
+    throw new Error(`Invalid byte array length: expected 16, got ${bytes.length}`);
+  }
+
+  let value = 0n;
+  for (let i = 0; i < 16; i++) {
+    value = (value << 8n) | BigInt(bytes[i]!);
+  }
+
+  let result = '';
+  for (let i = 0; i < ULID_LEN; i++) {
+    result = ENCODING[Number(value % BigInt(ENCODING_LEN))]! + result;
+    value = value / BigInt(ENCODING_LEN);
+  }
+
+  return result;
+}
+
+/**
+ * Compare two ULIDs for sorting.
+ * Returns negative if a < b, positive if a > b, 0 if equal.
+ */
+export function compareUlid(a: string, b: string): number {
+  return a.toUpperCase().localeCompare(b.toUpperCase());
+}
+
+/**
+ * Generate minimum ULID for a given timestamp.
+ * Useful for range queries: "all ULIDs after timestamp X"
+ */
+export function minUlidForTime(timestamp: number): string {
+  return encodeTime(timestamp) + '0'.repeat(RANDOM_LEN);
+}
+
+/**
+ * Generate maximum ULID for a given timestamp.
+ * Useful for range queries: "all ULIDs before timestamp X"
+ */
+export function maxUlidForTime(timestamp: number): string {
+  return encodeTime(timestamp) + 'Z'.repeat(RANDOM_LEN);
+}
+
+/**
+ * Reset monotonic state (useful for testing).
+ */
+export function resetMonotonic(): void {
+  lastTime = 0;
+  lastRandom = 0n;
+}
+
+export default ulid;

package/src/concerns/id/generators/uuid-v7.ts

@@ -0,0 +1,179 @@
+import { getRandomBytes } from '../entropy.js';
+
+const HEX_CHARS = '0123456789abcdef';
+
+/**
+ * Generate a UUID v7 according to RFC 9562.
+ *
+ * Structure (128 bits total):
+ * - bits 0-47: Unix timestamp in milliseconds (48 bits)
+ * - bits 48-51: Version (4 bits, always 0111 = 7)
+ * - bits 52-63: Random (12 bits)
+ * - bits 64-65: Variant (2 bits, always 10)
+ * - bits 66-127: Random (62 bits)
+ *
+ * Format: xxxxxxxx-xxxx-7xxx-yxxx-xxxxxxxxxxxx
+ * where y is 8, 9, a, or b (variant bits)
+ *
+ * Total entropy: 74 bits random + 48 bits timestamp
+ * Sortable: Yes (lexicographically by timestamp)
+ */
+export function uuidv7(timestamp?: number): string {
+  const ts = timestamp ?? Date.now();
+  const bytes = getRandomBytes(10);
+
+  const tsHigh = Math.floor(ts / 0x10000);
+  const tsLow = ts % 0x10000;
+
+  let uuid = '';
+
+  uuid += HEX_CHARS[(tsHigh >> 28) & 0xf];
+  uuid += HEX_CHARS[(tsHigh >> 24) & 0xf];
+  uuid += HEX_CHARS[(tsHigh >> 20) & 0xf];
+  uuid += HEX_CHARS[(tsHigh >> 16) & 0xf];
+  uuid += HEX_CHARS[(tsHigh >> 12) & 0xf];
+  uuid += HEX_CHARS[(tsHigh >> 8) & 0xf];
+  uuid += HEX_CHARS[(tsHigh >> 4) & 0xf];
+  uuid += HEX_CHARS[tsHigh & 0xf];
+  uuid += '-';
+
+  uuid += HEX_CHARS[(tsLow >> 12) & 0xf];
+  uuid += HEX_CHARS[(tsLow >> 8) & 0xf];
+  uuid += HEX_CHARS[(tsLow >> 4) & 0xf];
+  uuid += HEX_CHARS[tsLow & 0xf];
+  uuid += '-';
+
+  uuid += '7';
+  uuid += HEX_CHARS[bytes[0]! & 0xf];
+  uuid += HEX_CHARS[(bytes[1]! >> 4) & 0xf];
+  uuid += HEX_CHARS[bytes[1]! & 0xf];
+  uuid += '-';
+
+  uuid += HEX_CHARS[0x8 | ((bytes[2]! >> 4) & 0x3)];
+  uuid += HEX_CHARS[bytes[2]! & 0xf];
+  uuid += HEX_CHARS[(bytes[3]! >> 4) & 0xf];
+  uuid += HEX_CHARS[bytes[3]! & 0xf];
+  uuid += '-';
+
+  for (let i = 4; i < 10; i++) {
+    uuid += HEX_CHARS[(bytes[i]! >> 4) & 0xf];
+    uuid += HEX_CHARS[bytes[i]! & 0xf];
+  }
+
+  return uuid;
+}
+
+/**
+ * Generate a UUID v7 without hyphens (compact form).
+ * 32 characters instead of 36.
+ */
+export function uuidv7Compact(timestamp?: number): string {
+  return uuidv7(timestamp).replace(/-/g, '');
+}
+
+/**
+ * Generate a UUID v7 as bytes (Uint8Array).
+ * Useful for binary storage.
+ */
+export function uuidv7Bytes(timestamp?: number): Uint8Array {
+  const ts = timestamp ?? Date.now();
+  const randomBytes = getRandomBytes(10);
+  const result = new Uint8Array(16);
+
+  result[0] = (ts / 0x10000000000) & 0xff;
+  result[1] = (ts / 0x100000000) & 0xff;
+  result[2] = (ts / 0x1000000) & 0xff;
+  result[3] = (ts / 0x10000) & 0xff;
+  result[4] = (ts / 0x100) & 0xff;
+  result[5] = ts & 0xff;
+
+  result[6] = 0x70 | (randomBytes[0]! & 0x0f);
+  result[7] = randomBytes[1]!;
+
+  result[8] = 0x80 | (randomBytes[2]! & 0x3f);
+  result[9] = randomBytes[3]!;
+
+  for (let i = 4; i < 10; i++) {
+    result[6 + i] = randomBytes[i]!;
+  }
+
+  return result;
+}
+
+/**
+ * Parse a UUID v7 string to extract timestamp.
+ * Returns the Unix timestamp in milliseconds.
+ */
+export function parseUuidv7Timestamp(uuid: string): number {
+  const hex = uuid.replace(/-/g, '');
+
+  if (hex.length !== 32) {
+    throw new Error('Invalid UUID format');
+  }
+
+  const tsHex = hex.slice(0, 12);
+  return parseInt(tsHex, 16);
+}
+
+/**
+ * Parse a UUID v7 to Date object.
+ */
+export function parseUuidv7Date(uuid: string): Date {
+  return new Date(parseUuidv7Timestamp(uuid));
+}
+
+/**
+ * Validate if a string is a valid UUID v7.
+ */
+export function isValidUuidv7(uuid: string): boolean {
+  const pattern = /^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+  return pattern.test(uuid);
+}
+
+/**
+ * Compare two UUID v7s for sorting.
+ * Returns negative if a < b, positive if a > b, 0 if equal.
+ */
+export function compareUuidv7(a: string, b: string): number {
+  const aCompact = a.replace(/-/g, '').toLowerCase();
+  const bCompact = b.replace(/-/g, '').toLowerCase();
+  return aCompact.localeCompare(bCompact);
+}
+
+/**
+ * Generate UUID v4 (random, non-sortable) for comparison.
+ * Provided for completeness but UUID v7 is preferred.
+ */
+export function uuidv4(): string {
+  const bytes = getRandomBytes(16);
+
+  bytes[6] = (bytes[6]! & 0x0f) | 0x40;
+  bytes[8] = (bytes[8]! & 0x3f) | 0x80;
+
+  let uuid = '';
+  for (let i = 0; i < 16; i++) {
+    if (i === 4 || i === 6 || i === 8 || i === 10) {
+      uuid += '-';
+    }
+    uuid += HEX_CHARS[(bytes[i]! >> 4) & 0xf];
+    uuid += HEX_CHARS[bytes[i]! & 0xf];
+  }
+
+  return uuid;
+}
+
+/**
+ * Generate a nil UUID (all zeros).
+ */
+export function uuidNil(): string {
+  return '00000000-0000-0000-0000-000000000000';
+}
+
+/**
+ * Generate a max UUID (all ones).
+ */
+export function uuidMax(): string {
+  return 'ffffffff-ffff-ffff-ffff-ffffffffffff';
+}
+
+export default uuidv7;

package/src/concerns/id/index.ts

@@ -0,0 +1,167 @@
+/**
+ * s3db.js ID Generation Module
+ *
+ * A superior ID generation system with:
+ * - True uniform distribution via rejection sampling (zero modulo bias)
+ * - Multiple ID formats: sid (s3db id), UUID v7, ULID
+ * - Sortable IDs with timestamp prefix
+ * - Pre-allocated entropy pool for performance
+ * - URL-safe and S3-safe by default
+ * - TypeScript native, zero external dependencies
+ */
+
+export {
+  initPool,
+  getRandomBytes,
+  fillRandomBytes,
+  randomIndexUnbiased,
+  randomIndicesUnbiased,
+  randomString,
+  random48,
+  random62,
+  random80,
+  calculateEntropyBits,
+  calculateCollisionProbability,
+  resetPool
+} from './entropy.js';
+
+export {
+  URL_SAFE,
+  ALPHANUMERIC,
+  ALPHANUMERIC_LOWER,
+  ALPHANUMERIC_UPPER,
+  HEX_LOWER,
+  HEX_UPPER,
+  CROCKFORD_BASE32,
+  BASE58,
+  BASE64_URL,
+  NUMERIC,
+  LOWERCASE,
+  UPPERCASE,
+  HUMAN_READABLE,
+  NO_LOOKALIKE_LOWER,
+  BINARY,
+  EMOJI,
+  alphabets,
+  getAlphabet,
+  recommendedLength,
+  validateAlphabet,
+  type AlphabetName
+} from './alphabets.js';
+
+export {
+  sid,
+  customAlphabet,
+  customAlphabetByName,
+  sidWithOptions,
+  sidEntropyBits,
+  sidAsync,
+  customAlphabetAsync,
+  urlAlphabet,
+  type SidOptions
+} from './generators/sid.js';
+
+export {
+  uuidv7,
+  uuidv7Compact,
+  uuidv7Bytes,
+  parseUuidv7Timestamp,
+  parseUuidv7Date,
+  isValidUuidv7,
+  compareUuidv7,
+  uuidv4,
+  uuidNil,
+  uuidMax
+} from './generators/uuid-v7.js';
+
+export {
+  ulid,
+  ulidNonMonotonic,
+  decodeTime as ulidDecodeTime,
+  decodeDate as ulidDecodeDate,
+  isValidUlid,
+  ulidToUuid,
+  ulidToBytes,
+  bytesToUlid,
+  compareUlid,
+  minUlidForTime,
+  maxUlidForTime,
+  resetMonotonic as ulidResetMonotonic
+} from './generators/ulid.js';
+
+import { sid, customAlphabet } from './generators/sid.js';
+import { uuidv7 } from './generators/uuid-v7.js';
+import { ulid } from './generators/ulid.js';
+import { getAlphabet } from './alphabets.js';
+
+export type IdFormat = 'sid' | 'uuid' | 'uuidv7' | 'ulid';
+
+export interface GenerateIdOptions {
+  format?: IdFormat;
+  size?: number;
+  alphabet?: string;
+  timestamp?: number;
+}
+
+/**
+ * Generate an ID with the specified format.
+ * Unified API for all ID formats.
+ *
+ * @example
+ * generateId() // sid (default)
+ * generateId({ format: 'uuid' }) // UUID v7
+ * generateId({ format: 'ulid' }) // ULID
+ * generateId({ size: 16 }) // shorter sid
+ * generateId({ alphabet: 'ALPHANUMERIC' }) // alphanumeric sid
+ */
+export function generateId(options: GenerateIdOptions = {}): string {
+  const { format = 'sid', size, alphabet, timestamp } = options;
+
+  switch (format) {
+    case 'uuid':
+    case 'uuidv7':
+      return uuidv7(timestamp);
+
+    case 'ulid':
+      return ulid(timestamp);
+
+    case 'sid':
+    default:
+      if (alphabet) {
+        const resolvedAlphabet = getAlphabet(alphabet);
+        return customAlphabet(resolvedAlphabet, size ?? 21)();
+      }
+      return sid(size);
+  }
+}
+
+/**
+ * Check if an ID matches a specific format.
+ */
+export function detectIdFormat(id: string): IdFormat | null {
+  if (/^[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(id)) {
+    return 'uuidv7';
+  }
+
+  if (/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(id)) {
+    return 'uuid';
+  }
+
+  if (/^[0-9A-HJKMNP-TV-Z]{26}$/i.test(id)) {
+    return 'ulid';
+  }
+
+  if (id.length >= 10 && id.length <= 36) {
+    return 'sid';
+  }
+
+  return null;
+}
+
+export default {
+  generateId,
+  detectIdFormat,
+  sid,
+  uuidv7,
+  ulid
+};