cynx-lib 1.3.28

package/utils/utils/uid.js

@@ -0,0 +1,252 @@
+/**
+ * cynx/utils — Universal UID / UUID Generator
+ * 
+ * Works seamlessly in Browser, Node.js, Web Workers, React Native, and SSR/Edge environments.
+ * Cryptographically secure with zero external dependencies and graceful fallbacks.
+ */
+
+export const ALPHABETS = {
+  urlSafe: 'useandom-26T198340PX75pxJACKVERYMINDBUSHWOLFGQZ_rich5hexURL',
+  alphanumeric: '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz',
+  lowercase: '0123456789abcdefghijklmnopqrstuvwxyz',
+  uppercase: '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ',
+  numeric: '0123456789',
+  hex: '0123456789abcdef',
+  // Human-friendly alphabet without lookalikes (no 0, O, I, l, 1)
+  noLookalikes: '346789ABCDEFGHJKLMNPQRTUVWXYabcdefghijkmnpqrtwxyz',
+};
+
+/**
+ * Safely obtain the Crypto interface across all JS runtime environments.
+ */
+function getCrypto() {
+  if (typeof globalThis !== 'undefined' && globalThis.crypto) {
+    return globalThis.crypto;
+  }
+  if (typeof window !== 'undefined' && window.crypto) {
+    return window.crypto;
+  }
+  if (typeof self !== 'undefined' && self.crypto) {
+    return self.crypto;
+  }
+  return null;
+}
+
+/**
+ * Fill a Uint8Array with cryptographically secure random bytes.
+ * Falls back to high-entropy pseudo-random bytes if Web Crypto is unavailable.
+ * 
+ * @param {number} [size=16]
+ * @returns {Uint8Array}
+ */
+export function getRandomBytes(size = 16) {
+  const bytes = new Uint8Array(size);
+  const cryptoObj = getCrypto();
+  if (cryptoObj && typeof cryptoObj.getRandomValues === 'function') {
+    cryptoObj.getRandomValues(bytes);
+    return bytes;
+  }
+
+  // Fallback for non-secure / legacy environments
+  for (let i = 0; i < size; i++) {
+    const timeJitter = ((Date.now() + (typeof performance !== 'undefined' ? performance.now() : 0)) * 1000) % 256;
+    bytes[i] = (Math.floor(Math.random() * 256) ^ Math.floor(timeJitter)) & 0xff;
+  }
+  return bytes;
+}
+
+/**
+ * Generate standard RFC 4122 version 4 UUID.
+ * Uses native crypto.randomUUID() when available.
+ * 
+ * Example: "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
+ * 
+ * @returns {string}
+ */
+export function uuid() {
+  const cryptoObj = getCrypto();
+  if (cryptoObj && typeof cryptoObj.randomUUID === 'function') {
+    return cryptoObj.randomUUID();
+  }
+
+  // RFC 4122 v4 generator fallback
+  const bytes = getRandomBytes(16);
+  bytes[6] = (bytes[6] & 0x0f) | 0x40; // Version 4
+  bytes[8] = (bytes[8] & 0x3f) | 0x80; // Variant 10xx
+
+  let out = '';
+  for (let i = 0; i < 16; i++) {
+    if (i === 4 || i === 6 || i === 8 || i === 10) out += '-';
+    out += bytes[i].toString(16).padStart(2, '0');
+  }
+  return out;
+}
+
+export const uuidv4 = uuid;
+
+/**
+ * Create a custom ID generator with a given alphabet and default length.
+ * Features uniform distribution (zero modulo bias).
+ * 
+ * @param {string} [alphabet=ALPHABETS.urlSafe]
+ * @param {number} [defaultSize=21]
+ * @returns {(size?: number) => string}
+ */
+export function customAlphabet(alphabet = ALPHABETS.urlSafe, defaultSize = 21) {
+  const mask = (2 << (31 - Math.clz32((alphabet.length - 1) | 1))) - 1;
+  const step = Math.ceil((1.6 * mask * defaultSize) / alphabet.length);
+
+  return function generate(size = defaultSize) {
+    let id = '';
+    while (true) {
+      const bytes = getRandomBytes(step);
+      for (let i = 0; i < step; i++) {
+        const byte = bytes[i] & mask;
+        if (alphabet[byte]) {
+          id += alphabet[byte];
+          if (id.length === size) return id;
+        }
+      }
+    }
+  };
+}
+
+/**
+ * Generate a fast, URL-friendly unique ID (similar to NanoID).
+ * 
+ * @param {number} [size=12] Length of the generated ID (default: 12)
+ * @param {string} [alphabet=ALPHABETS.urlSafe] Custom alphabet string
+ * @returns {string}
+ */
+export function uid(size = 12, alphabet = ALPHABETS.urlSafe) {
+  if (alphabet === ALPHABETS.urlSafe) {
+    const bytes = getRandomBytes(size);
+    let id = '';
+    const len = alphabet.length;
+    for (let i = 0; i < size; i++) {
+      id += alphabet[bytes[i] % len];
+    }
+    return id;
+  }
+  return customAlphabet(alphabet, size)(size);
+}
+
+/**
+ * NanoID-compatible generator.
+ * 
+ * @param {number} [size=21]
+ * @returns {string}
+ */
+export const nanoid = (size = 21) => uid(size, ALPHABETS.urlSafe);
+export const genUid = (size = 12) => uid(size, ALPHABETS.urlSafe);
+
+/**
+ * Generate a compact alphanumeric ID.
+ * Example: "9xKb7Zm2"
+ * 
+ * @param {number} [size=8]
+ * @returns {string}
+ */
+export function shortId(size = 8) {
+  return uid(size, ALPHABETS.alphanumeric);
+}
+
+/**
+ * Generate a prefixed unique identifier (ideal for React keys, DOM IDs, and entity records).
+ * Example: prefixedId('usr', 10) => "usr_9xKb7Zm20A"
+ * 
+ * @param {string} [prefix='id']
+ * @param {number} [size=12]
+ * @param {string} [alphabet=ALPHABETS.alphanumeric]
+ * @returns {string}
+ */
+export function prefixedId(prefix = 'id', size = 12, alphabet = ALPHABETS.alphanumeric) {
+  return `${prefix}_${uid(size, alphabet)}`;
+}
+
+/**
+ * Create an incremental sequence ID generator (safe for SSR, React unique keys, form labels).
+ * Example:
+ *   const nextId = createSequence('modal');
+ *   nextId() // "modal_1"
+ *   nextId() // "modal_2"
+ * 
+ * @param {string} [prefix='cynx']
+ * @returns {(customPrefix?: string) => string}
+ */
+export function createSequence(prefix = 'cynx') {
+  let counter = 0;
+  return function next(customPrefix = prefix) {
+    counter += 1;
+    return `${customPrefix}_${counter}`;
+  };
+}
+
+/**
+ * Global default sequence ID generator.
+ */
+export const seqId = createSequence('cynx');
+
+/**
+ * Generate a time-sortable unique ID (timestamp in base36 + random entropy).
+ * Perfect for log entries, time-ordered database records, and transaction IDs.
+ * Example: "18f2a4bc890_9xk2b7qm"
+ * 
+ * @param {string} [prefix='']
+ * @returns {string}
+ */
+export function timestampId(prefix = '') {
+  const ts = Date.now().toString(36);
+  const rand = uid(8, ALPHABETS.lowercase);
+  return prefix ? `${prefix}_${ts}_${rand}` : `${ts}_${rand}`;
+}
+
+/**
+ * Validate standard UUID string format (v1-v5).
+ * 
+ * @param {unknown} str
+ * @returns {boolean}
+ */
+export function isValidUUID(str) {
+  if (typeof str !== 'string') return false;
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(str);
+}
+
+/**
+ * Validate custom UID format with optional length and alphabet constraints.
+ * 
+ * @param {unknown} str
+ * @param {object} [options]
+ * @param {number} [options.minLength=1]
+ * @param {number} [options.maxLength=128]
+ * @param {string} [options.alphabet]
+ * @returns {boolean}
+ */
+export function isValidUID(str, { minLength = 1, maxLength = 128, alphabet } = {}) {
+  if (typeof str !== 'string') return false;
+  if (str.length < minLength || str.length > maxLength) return false;
+  if (alphabet) {
+    const chars = new Set(alphabet);
+    for (const char of str) {
+      if (!chars.has(char)) return false;
+    }
+  }
+  return true;
+}
+
+export default {
+  uuid,
+  uuidv4,
+  uid,
+  nanoid,
+  shortId,
+  prefixedId,
+  timestampId,
+  createSequence,
+  seqId,
+  customAlphabet,
+  getRandomBytes,
+  isValidUUID,
+  isValidUID,
+  ALPHABETS,
+};