webspresso 0.0.104 → 0.0.106

package/core/utils/array.js

@@ -0,0 +1,12 @@
+'use strict';
+
+/**
+ * Webspresso - Zero-Dependency Array Utilities
+ * @module core/utils/array
+ */
+
+const { ensureArray } = require('./object');
+
+module.exports = {
+  ensureArray,
+};

package/core/utils/base64url.js

@@ -0,0 +1,8 @@
+'use strict';
+
+const { base64UrlEncode, base64UrlDecode } = require('./crypto');
+
+module.exports = {
+  base64UrlEncode,
+  base64UrlDecode,
+};

package/core/utils/crypto.js

@@ -67,7 +67,125 @@ function safeCompare(a, b) {
   }
 }
 
+/**
+ * Compute SHA-256 hash of a string, Buffer, or value.
+ *
+ * Zero-dependency wrapper around native `crypto.createHash('sha256')`.
+ * Safely coerces non-Buffer/non-string values to strings (or empty string for null/undefined).
+ *
+ * @param {string|Buffer|any} data - Data to hash
+ * @param {import('crypto').BinaryToTextEncoding|'buffer'} [encoding='hex'] - Output encoding ('hex', 'base64', 'base64url', or 'buffer')
+ * @returns {string|Buffer} Digest in specified encoding, or Buffer if encoding is 'buffer'
+ */
+function sha256(data, encoding = 'hex') {
+  if (data === null || data === undefined) {
+    data = '';
+  }
+  const input = Buffer.isBuffer(data) || typeof data === 'string' ? data : String(data);
+  const hash = crypto.createHash('sha256').update(input);
+  return encoding === 'buffer' ? hash.digest() : hash.digest(encoding || 'hex');
+}
+
+/**
+ * Compute HMAC-SHA256 signature of data using a secret key.
+ *
+ * Zero-dependency wrapper around native `crypto.createHmac('sha256', secret)`.
+ *
+ * @param {string|Buffer|any} data - Data to sign
+ * @param {string|Buffer} secret - Secret key
+ * @param {import('crypto').BinaryToTextEncoding|'buffer'} [encoding='hex'] - Output encoding ('hex', 'base64', 'base64url', or 'buffer')
+ * @returns {string|Buffer} Signature in specified encoding, or Buffer if encoding is 'buffer'
+ */
+function hmacSha256(data, secret, encoding = 'hex') {
+  if (secret === null || secret === undefined) {
+    throw new TypeError('A secret key is required for HMAC computation');
+  }
+  if (data === null || data === undefined) {
+    data = '';
+  }
+  const input = Buffer.isBuffer(data) || typeof data === 'string' ? data : String(data);
+  const hmac = crypto.createHmac('sha256', secret).update(input);
+  return encoding === 'buffer' ? hmac.digest() : hmac.digest(encoding || 'hex');
+}
+
+/**
+ * Generate a cryptographically secure random token string or buffer.
+ *
+ * @param {number} [byteLength=32] - Number of random bytes
+ * @param {import('crypto').BinaryToTextEncoding|'buffer'} [encoding='hex'] - Output encoding ('hex', 'base64', 'base64url', or 'buffer')
+ * @returns {string|Buffer}
+ */
+function randomToken(byteLength = 32, encoding = 'hex') {
+  const bytes = crypto.randomBytes(byteLength);
+  return encoding === 'buffer' ? bytes : bytes.toString(encoding || 'hex');
+}
+
+/**
+ * Generate a cryptographically secure random string with an optional prefix.
+ * E.g. randomId('whsec', 24) -> 'whsec_a1b2c3...'
+ *
+ * @param {string} [prefix=''] - Identifier prefix
+ * @param {number} [byteLength=16] - Random byte length
+ * @param {import('crypto').BinaryToTextEncoding} [encoding='hex'] - Output encoding
+ * @returns {string}
+ */
+function randomId(prefix = '', byteLength = 16, encoding = 'hex') {
+  const token = randomToken(byteLength, encoding);
+  if (!prefix) return token;
+  const p = prefix.endsWith('_') ? prefix : `${prefix}_`;
+  return `${p}${token}`;
+}
+
+/**
+ * Generate a timestamped unique ID with optional prefix.
+ * E.g. randomTimestampedId('dlv', 8) -> 'dlv_1729221234567_abcdef1234567890'
+ *
+ * @param {string} [prefix=''] - Identifier prefix
+ * @param {number} [byteLength=8] - Random byte length
+ * @param {import('crypto').BinaryToTextEncoding} [encoding='hex'] - Output encoding
+ * @returns {string}
+ */
+function randomTimestampedId(prefix = '', byteLength = 8, encoding = 'hex') {
+  const token = randomToken(byteLength, encoding);
+  const p = prefix ? (prefix.endsWith('_') ? prefix : `${prefix}_`) : '';
+  return `${p}${Date.now()}_${token}`;
+}
+
+/**
+ * Encode string or Buffer to Base64URL string (RFC 4648 §5).
+ *
+ * @param {string|Buffer|any} input
+ * @returns {string}
+ */
+function base64UrlEncode(input) {
+  if (input === null || input === undefined) return '';
+  return Buffer.isBuffer(input)
+    ? input.toString('base64url')
+    : Buffer.from(String(input), 'utf8').toString('base64url');
+}
+
+/**
+ * Decode Base64URL string to UTF-8 string.
+ *
+ * @param {string} input
+ * @returns {string}
+ */
+function base64UrlDecode(input) {
+  if (!input) return '';
+  return Buffer.from(String(input), 'base64url').toString('utf8');
+}
+
 module.exports = {
   safeCompare,
   timingSafeEqual: safeCompare,
+  sha256,
+  hashSha256: sha256,
+  hmacSha256,
+  createHmacSha256: hmacSha256,
+  randomToken,
+  randomId,
+  randomTimestampedId,
+  base64UrlEncode,
+  base64UrlDecode,
 };
+

package/core/utils/ensure-leading-slash.js

@@ -0,0 +1,6 @@
+'use strict';
+
+const { ensureLeadingSlash } = require('./url');
+
+module.exports = ensureLeadingSlash;
+module.exports.ensureLeadingSlash = ensureLeadingSlash;

package/core/utils/escape-regexp.js

@@ -0,0 +1,7 @@
+'use strict';
+
+const { escapeRegExp } = require('./regex');
+
+module.exports = escapeRegExp;
+module.exports.escapeRegExp = escapeRegExp;
+module.exports.escapeRegex = escapeRegExp;

package/core/utils/fetch.js

@@ -11,13 +11,13 @@
  * @module core/utils/fetch
  */
 
-'use strict';
+const { parseDurationMs } = require('./time');
 
 /**
  * Executes a fetch request with timeout and abort controller support.
  *
  * @param {string | URL | Request} url - Target URL or Request instance
- * @param {RequestInit & { timeout?: number }} [options] - Standard RequestInit plus optional timeout (ms)
+ * @param {RequestInit & { timeout?: number | string }} [options] - Standard RequestInit plus optional timeout (ms or '5s')
  * @returns {Promise<Response>}
  */
 async function fetchWithTimeout(url, options = {}) {
@@ -38,13 +38,14 @@ async function fetchWithTimeout(url, options = {}) {
   let timer = null;
   let callerSignalListener = null;
 
-  if (typeof timeout === 'number' && timeout > 0) {
+  const timeoutMs = timeout !== undefined ? parseDurationMs(timeout, 10000) : 10000;
+  if (typeof timeoutMs === 'number' && timeoutMs > 0) {
     timer = setTimeout(() => {
-      const err = new Error(`Request timed out after ${timeout}ms`);
+      const err = new Error(`Request timed out after ${timeoutMs}ms`);
       err.name = 'TimeoutError';
       err.code = 'ETIMEDOUT';
       controller.abort(err);
-    }, timeout);
+    }, timeoutMs);
     if (timer && typeof timer.unref === 'function') {
       timer.unref();
     }

package/core/utils/fs.js

@@ -0,0 +1,144 @@
+'use strict';
+
+/**
+ * Webspresso - Native Filesystem & Directory Walking Utilities
+ * Zero-dependency recursive and flat directory scanner with configurable filters.
+ * @module core/utils/fs
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Standard test file extensions and type declarations to ignore by default
+ */
+const DEFAULT_TEST_SUFFIXES = [
+  '.test.js',
+  '.test.cjs',
+  '.test.mjs',
+  '.test.ts',
+  '.spec.js',
+  '.spec.cjs',
+  '.spec.mjs',
+  '.spec.ts',
+  '.d.ts',
+];
+
+/**
+ * Recursively (or flatly) scans a directory for files matching specified criteria.
+ *
+ * @param {string} dir - Directory path to scan
+ * @param {Object} [options]
+ * @param {string[]|Set<string>|null} [options.extensions] - Allowed extensions (e.g. ['.js', '.cjs']). Null allows any extension.
+ * @param {boolean} [options.recursive=true] - Whether to scan subdirectories recursively
+ * @param {boolean} [options.ignoreTests=true] - Whether to ignore test files (.test.js, .spec.js, .d.ts)
+ * @param {string[]} [options.ignorePrefixes=['.', '_']] - Prefixes of files/directories to ignore
+ * @param {string[]} [options.ignoreNames=['node_modules']] - Exact file or directory names to ignore
+ * @param {Function} [options.filter] - Custom filter function (fullPath, dirent) => boolean
+ * @param {string} [options.baseDir] - Base directory for computing relative paths (defaults to dir)
+ * @param {boolean} [options.detailed=false] - If true, returns array of objects with { absolutePath, relativePath, name, ext }
+ * @returns {string[]|Array<{ absolutePath: string, relativePath: string, name: string, ext: string }>}
+ */
+function walkDirectory(dir, options = {}) {
+  const {
+    extensions = null,
+    recursive = true,
+    ignoreTests = true,
+    ignorePrefixes = ['.', '_'],
+    ignoreNames = ['node_modules'],
+    filter = null,
+    baseDir = dir,
+    detailed = false,
+  } = options;
+
+  if (!dir || typeof dir !== 'string') return [];
+
+  const resolvedDir = path.resolve(dir);
+  if (!fs.existsSync(resolvedDir)) return [];
+
+  const extSet = extensions
+    ? new Set(Array.from(extensions).map(e => (e.startsWith('.') ? e.toLowerCase() : `.${e.toLowerCase()}`)))
+    : null;
+
+  const results = [];
+  const resolvedBase = path.resolve(baseDir);
+
+  function walk(currentDir) {
+    let entries;
+    try {
+      entries = fs.readdirSync(currentDir, { withFileTypes: true });
+    } catch (_) {
+      return;
+    }
+
+    for (const entry of entries) {
+      const name = entry.name;
+
+      // Ignore specified exact names (e.g. 'node_modules')
+      if (ignoreNames && ignoreNames.includes(name)) {
+        continue;
+      }
+
+      // Ignore specified prefixes (e.g. '.' or '_')
+      if (ignorePrefixes && ignorePrefixes.some(prefix => name.startsWith(prefix))) {
+        continue;
+      }
+
+      const fullPath = path.join(currentDir, name);
+
+      if (entry.isDirectory()) {
+        if (recursive) {
+          walk(fullPath);
+        }
+      } else if (entry.isFile()) {
+        const ext = path.extname(name).toLowerCase();
+
+        // Check extensions if specified
+        if (extSet && !extSet.has(ext)) {
+          continue;
+        }
+
+        // Check test file suffixes
+        if (ignoreTests && DEFAULT_TEST_SUFFIXES.some(suffix => name.toLowerCase().endsWith(suffix))) {
+          continue;
+        }
+
+        // Custom filter function
+        if (typeof filter === 'function' && !filter(fullPath, entry)) {
+          continue;
+        }
+
+        if (detailed) {
+          const relPath = path.relative(resolvedBase, fullPath).split(path.sep).join('/');
+          results.push({
+            absolutePath: fullPath,
+            relativePath: relPath,
+            name,
+            ext,
+          });
+        } else {
+          results.push(fullPath);
+        }
+      }
+    }
+  }
+
+  walk(resolvedDir);
+  return results;
+}
+
+/**
+ * Convenient wrapper for walkDirectory with detailed: true
+ * @param {string} dir
+ * @param {Object} [options]
+ * @returns {Array<{ absolutePath: string, relativePath: string, name: string, ext: string }>}
+ */
+function walkDirectoryDetailed(dir, options = {}) {
+  return walkDirectory(dir, { ...options, detailed: true });
+}
+
+module.exports = {
+  walkDirectory,
+  walkDirectoryDetailed,
+  DEFAULT_TEST_SUFFIXES,
+};

package/core/utils/hmac.js

@@ -0,0 +1,6 @@
+'use strict';
+
+const { hmacSha256 } = require('./crypto');
+
+module.exports = hmacSha256;
+module.exports.hmacSha256 = hmacSha256;

package/core/utils/json.js

@@ -0,0 +1,98 @@
+'use strict';
+
+/**
+ * Webspresso - Zero-Dependency JSON Utilities
+ * Safe, fault-tolerant JSON parse and stringify helpers that never throw unhandled exceptions.
+ * @module core/utils/json
+ */
+
+/**
+ * Safely parses a JSON string without throwing exceptions.
+ * Returns the provided fallback value if parsing fails or input is missing.
+ * If input is already an object or array (and not a string), returns input directly.
+ *
+ * @template T
+ * @param {string|unknown} input - Value or JSON string to parse
+ * @param {T} [fallback=null] - Value to return if parsing fails
+ * @param {Function} [reviver] - Optional JSON.parse reviver function
+ * @returns {any|T}
+ */
+function safeJsonParse(input, fallback = null, reviver) {
+  if (input === null || input === undefined || input === '') {
+    return fallback;
+  }
+  if (typeof input !== 'string') {
+    return input;
+  }
+
+  try {
+    return JSON.parse(input, reviver);
+  } catch (_) {
+    return fallback;
+  }
+}
+
+/**
+ * Safely serializes a value to a JSON string without throwing exceptions.
+ * Handles circular references and BigInt values gracefully.
+ *
+ * @param {unknown} value - Value to serialize
+ * @param {string|number|null} [space=null] - Indentation spaces
+ * @param {string} [fallback=''] - Fallback value if serialization fails
+ * @returns {string}
+ */
+function safeJsonStringify(value, space = null, fallback = '') {
+  if (value === undefined) {
+    return fallback;
+  }
+  try {
+    return JSON.stringify(value, null, space ?? undefined);
+  } catch (_) {
+    // Attempt circular-safe serialization
+    try {
+      const seen = new WeakSet();
+      return JSON.stringify(
+        value,
+        (key, val) => {
+          if (typeof val === 'bigint') {
+            return val.toString();
+          }
+          if (typeof val === 'object' && val !== null) {
+            if (seen.has(val)) {
+              return '[Circular]';
+            }
+            seen.add(val);
+          }
+          return val;
+        },
+        space ?? undefined
+      );
+    } catch {
+      return fallback;
+    }
+  }
+}
+
+/**
+ * Checks whether a given string is valid JSON without throwing.
+ *
+ * @param {string|unknown} str - String to test
+ * @returns {boolean}
+ */
+function isValidJson(str) {
+  if (typeof str !== 'string' || !str.trim()) {
+    return false;
+  }
+  try {
+    JSON.parse(str);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+module.exports = {
+  safeJsonParse,
+  safeJsonStringify,
+  isValidJson,
+};

package/core/utils/object.js

@@ -0,0 +1,106 @@
+'use strict';
+
+/**
+ * Webspresso - Zero-Dependency Object & Array Utilities
+ * Safe property picking, omission, array wrapping, and deep cloning.
+ * @module core/utils/object
+ */
+
+/**
+ * Ensure a value is wrapped in an array.
+ * Returns empty array for null or undefined.
+ * Returns array as-is if already an array.
+ * Wraps any other value in a single-element array.
+ *
+ * @template T
+ * @param {T|T[]|null|undefined} value - Value to ensure as array
+ * @returns {T[]}
+ * @example
+ * ensureArray(null) // -> []
+ * ensureArray(undefined) // -> []
+ * ensureArray('foo') // -> ['foo']
+ * ensureArray(['bar']) // -> ['bar']
+ */
+function ensureArray(value) {
+  if (value === undefined || value === null) {
+    return [];
+  }
+  return Array.isArray(value) ? value : [value];
+}
+
+/**
+ * Pick specific keys from an object.
+ *
+ * @param {Record<string, any>|null|undefined} obj - Source object
+ * @param {string[]|string} keys - Keys to pick
+ * @returns {Record<string, any>} Object with picked keys
+ */
+function pick(obj, keys) {
+  if (!obj || typeof obj !== 'object') {
+    return {};
+  }
+  const result = {};
+  const keyList = Array.isArray(keys) ? keys : [keys];
+  for (const key of keyList) {
+    if (key in obj) {
+      result[key] = obj[key];
+    }
+  }
+  return result;
+}
+
+/**
+ * Omit specific keys from an object.
+ *
+ * @param {Record<string, any>|null|undefined} obj - Source object
+ * @param {string[]|string} keys - Keys to omit
+ * @returns {Record<string, any>} Object without omitted keys
+ */
+function omit(obj, keys) {
+  if (!obj || typeof obj !== 'object') {
+    return {};
+  }
+  const result = {};
+  const omitSet = new Set(Array.isArray(keys) ? keys : [keys]);
+  for (const key in obj) {
+    if (!omitSet.has(key)) {
+      result[key] = obj[key];
+    }
+  }
+  return result;
+}
+
+/**
+ * Deep clone an object, array, or Date instance safely.
+ * Strips prototype pollution attempts (__proto__, constructor, prototype).
+ *
+ * @template T
+ * @param {T} obj - Target object to clone
+ * @returns {T} Cloned copy
+ */
+function deepClone(obj) {
+  if (obj === null || typeof obj !== 'object') {
+    return obj;
+  }
+  if (obj instanceof Date) {
+    return new Date(obj.getTime());
+  }
+  if (Array.isArray(obj)) {
+    return obj.map(deepClone);
+  }
+  const cloned = Object.create(null);
+  for (const key of Object.keys(obj)) {
+    if (key === '__proto__' || key === 'constructor' || key === 'prototype') {
+      continue;
+    }
+    cloned[key] = deepClone(obj[key]);
+  }
+  return { ...cloned };
+}
+
+module.exports = {
+  ensureArray,
+  pick,
+  omit,
+  deepClone,
+};

package/core/utils/random.js

@@ -0,0 +1,9 @@
+'use strict';
+
+const { randomToken, randomId, randomTimestampedId } = require('./crypto');
+
+module.exports = {
+  randomToken,
+  randomId,
+  randomTimestampedId,
+};

package/core/utils/regex.js

@@ -0,0 +1,77 @@
+'use strict';
+
+/**
+ * Webspresso - Zero-Dependency RegExp Utilities
+ * Fast, secure regular expression escaping and glob-to-regex conversion helpers.
+ * @module core/utils/regex
+ */
+
+/**
+ * Escapes all regular expression special characters in a string.
+ * Safe against ReDoS and regex injection when inserting dynamic substrings into RegExp.
+ *
+ * @param {string|unknown} str - String to escape
+ * @returns {string} Escaped string safe for new RegExp()
+ */
+function escapeRegExp(str) {
+  if (str == null) return '';
+  return String(str).replace(/[\\^$*+?.()|[\]{}]/g, '\\$&');
+}
+
+/**
+ * Converts a glob pattern string (e.g. 'users/*', 'api/**', 'order.*') into a RegExp.
+ *
+ * @param {string} pattern - Glob pattern string
+ * @param {Object} [options]
+ * @param {'/'|'.'|null} [options.separator='/'] - Segment separator ('/' for URLs/paths, '.' for events/dots, null for flat)
+ * @param {boolean} [options.exact=true] - Whether to match entire string (^...$)
+ * @param {string} [options.flags=''] - RegExp flags (e.g. 'i')
+ * @returns {RegExp}
+ */
+function globToRegExp(pattern, options = {}) {
+  const {
+    separator = '/',
+    exact = true,
+    flags = '',
+  } = options;
+
+  if (typeof pattern !== 'string') {
+    return exact ? /(?!)/ : /(?:)/;
+  }
+
+  if (pattern === '*' || pattern === '**') {
+    return new RegExp(exact ? '^.*$' : '.*', flags);
+  }
+
+  // 1. Fully escape all regex characters first
+  let escaped = escapeRegExp(pattern);
+
+  // 2. Replace escaped wildcard sequences
+  if (separator === '/') {
+    // URL or path globbing
+    escaped = escaped
+      .replace(/\\\*\\\*/g, '.*')
+      .replace(/\\\*/g, '[^/]*')
+      .replace(/\\\?/g, '.');
+  } else if (separator === '.') {
+    // Dot-notation event globbing (e.g. order.* or order.**)
+    escaped = escaped
+      .replace(/\\\*\\\*/g, '.*')
+      .replace(/\\\*/g, '[^.]+')
+      .replace(/\\\?/g, '.');
+  } else {
+    // Flat wildcard matching
+    escaped = escaped
+      .replace(/\\\*+/g, '.*')
+      .replace(/\\\?/g, '.');
+  }
+
+  const regexStr = exact ? `^${escaped}$` : escaped;
+  return new RegExp(regexStr, flags);
+}
+
+module.exports = {
+  escapeRegExp,
+  escapeRegex: escapeRegExp,
+  globToRegExp,
+};

package/core/utils/sha256.js

@@ -0,0 +1,6 @@
+'use strict';
+
+const { sha256 } = require('./crypto');
+
+module.exports = sha256;
+module.exports.sha256 = sha256;