melperjs 15.0.0 → 16.0.0

package/docs/node.md

@@ -0,0 +1,285 @@
+# Node.js Functions
+
+Node-only utilities exported from `melperjs/node`. These rely on Node modules (`crypto`, `fs`, `child_process`, `os`)
+and will not run in a browser.
+
+## Cryptographic Random (CSPRNG)
+
+All `secureRandom*` helpers use Node's `crypto` module (`crypto.randomInt`, `crypto.randomBytes`, `crypto.randomUUID`).
+Use these for session tokens, API keys, nonces, and anything security-sensitive. For non-secure / faster equivalents,
+see the `random*` family in [General Functions](./general.md).
+
+### secureRandomBoolean()
+
+Returns `true` or `false` with cryptographically uniform probability.
+
+- **Returns:** `Boolean`.
+
+### secureRandomString(length, useNumbers = true, useUppercase = false)
+
+Generates a cryptographically random string from a configurable character set.
+
+- **Parameters:**
+    - `length` (Number): Output length.
+    - `useNumbers` (Boolean): Include digits `0-9`.
+    - `useUppercase` (Boolean): Include uppercase letters.
+- **Returns:** Random string.
+
+### secureRandomHex(length)
+
+Generates a cryptographically random hexadecimal string.
+
+- **Parameters:**
+    - `length` (Number): Output length.
+- **Returns:** Hex string of the requested length.
+
+### secureRandomInteger(min, max)
+
+Returns a cryptographically random integer in `[min, max)`. Thin wrapper over `crypto.randomInt`.
+
+- **Parameters:**
+    - `min` (Number): Inclusive lower bound.
+    - `max` (Number): Exclusive upper bound.
+- **Returns:** Integer in `[min, max)`.
+
+### secureRandomUuid(useDashes = true)
+
+Generates a cryptographically random UUID v4 via `crypto.randomUUID()`. Suitable for security tokens.
+
+- **Parameters:**
+    - `useDashes` (Boolean): When `false`, dashes are stripped.
+- **Returns:** UUID string.
+
+### secureRandomWeighted(object)
+
+Picks a key from `object` with probability proportional to its weight, using `crypto.randomInt` for selection. Weights
+must be positive integers.
+
+- **Parameters:**
+    - `object` (Object): Map of key → positive integer weight.
+- **Returns:** Selected key.
+
+### secureRandomElement(object)
+
+Picks a cryptographically random value from an array or from an object's own enumerable values. Returns `undefined` for
+empty or nullish input.
+
+- **Parameters:**
+    - `object` (Array|Object): Source collection.
+- **Returns:** A random value, or `undefined`.
+
+## Deterministic Random (seeded)
+
+### uuidFromSeed(seed, useDashes = true)
+
+Builds a deterministic UUID by MD5-hashing the seed and setting RFC 4122 v3 version/variant bits. Same seed always
+yields the same UUID. Use for stable identifiers derived from input data; do not use for unpredictability.
+
+- **Parameters:**
+    - `seed` (String|Buffer): Seed value hashed with MD5.
+    - `useDashes` (Boolean): When `false`, dashes are stripped.
+- **Returns:** UUID string.
+
+## Hashing
+
+### hash(algorithm, data)
+
+Computes a hex digest using any algorithm supported by Node's `crypto.createHash`.
+
+- **Parameters:**
+    - `algorithm` (String): e.g., `"sha1"`, `"sha256"`, `"md5"`.
+    - `data` (String|Buffer): Input data.
+- **Returns:** Hex digest.
+
+### md5(data)
+
+Shortcut for `hash("md5", data)`.
+
+- **Returns:** 32-char hex MD5 digest.
+
+### sha256(data)
+
+Shortcut for `hash("sha256", data)`.
+
+- **Returns:** 64-char hex SHA-256 digest.
+
+## Encoding
+
+### base64Encode(data)
+
+Encodes input to Base64. Strings are treated as UTF-8; pass a `Buffer` for binary data.
+
+- **Parameters:**
+    - `data` (String|Buffer): Input data.
+- **Returns:** Base64 string.
+
+### base64Decode(data, encoding = 'utf8')
+
+Decodes Base64 input to a string using the given output encoding.
+
+- **Parameters:**
+    - `data` (String): Base64 string.
+    - `encoding` (String): Buffer encoding for the result (`'utf8'`, `'hex'`, etc.).
+- **Returns:** Decoded string.
+
+## Bcrypt (Passwords)
+
+### bcryptHash(plainText, {key = "", strength = 12, preHash = true} = {})
+
+Hashes plaintext with bcrypt. An optional pre-hash `key` (application-wide secret, sometimes called "pepper") is appended to the plaintext before hashing. `strength` controls the bcrypt cost factor. When `preHash` is `true` (default), the input is SHA-256-hashed first so that very long passwords (bcrypt silently truncates at 72 bytes) are handled safely and uniquely.
+
+- **Parameters:**
+    - `plainText` (String): Password or other secret to hash.
+    - `options.key` (String): Extra secret appended before hashing. Default `""`.
+    - `options.strength` (Number): bcrypt cost (rounds). Default `12`.
+    - `options.preHash` (Boolean): Pre-hash with SHA-256 before bcrypt. Default `true`. Disable only for back-compat with hashes generated without it.
+- **Returns:** Bcrypt hash string.
+
+### bcryptVerify(plainText, hash, {key = "", preHash = true} = {})
+
+Verifies that `plainText` (with the same `key`) matches a previously generated bcrypt hash. `preHash` must match the value used during hashing.
+
+- **Parameters:**
+    - `plainText` (String): Plaintext to verify.
+    - `hash` (String): Bcrypt hash from `bcryptHash`.
+    - `options.key` (String): Same `key` used during hashing.
+    - `options.preHash` (Boolean): Must match the `preHash` used for `bcryptHash`. Default `true`.
+- **Returns:** `Boolean` indicating match.
+
+## Proxy Helpers
+
+### normalizeProxy(proxy, protocol = "http")
+
+Normalizes a wide range of proxy formats into a canonical `protocol://[user:pass@]host:port` URL. Supports:
+
+- `host:port`
+- `host:port:user:pass` (auth appended)
+- `user:pass:host:port` (auth prepended; auto-detected via numeric port pattern)
+- `host:portStart:portEnd:user:pass` (random port in range, inclusive)
+- `user:pass:host:portStart:portEnd` (auth prepended, random port in range)
+- `user:pass@host:port`
+- `user:pass@host:portStart:portEnd` (random port in range)
+- Any of the above prefixed with `scheme://` (`http`, `https`, `socks5`, `socks5h`, …)
+
+Returns `null` for empty or non-string input. Does not crash on unparseable input — returns it as-is wrapped with
+`protocol://`.
+
+- **Parameters:**
+    - `proxy` (String): Source proxy string.
+    - `protocol` (String): Default protocol when none is present in the input.
+- **Returns:** Canonical proxy URL, or `null` when input is empty/missing.
+
+### parseProxy(proxy, protocol = "http")
+
+Normalizes `proxy` via `normalizeProxy`, then decomposes it into structured fields. Returns `null` when normalization
+fails (empty input).
+
+- **Parameters:**
+    - `proxy` (String): Source proxy string.
+    - `protocol` (String): Default protocol when none is present in the input.
+- **Returns:** `{protocol, host, port, auth?: {username, password}}` or `null`.
+
+### proxyValue(rawProxy, replacements = {})
+
+Picks a random proxy from a newline-separated list, normalizes it, and applies placeholder substitution.
+
+`{SESSION}` is a built-in placeholder:
+
+- If `SESSION` is not provided, it is autofilled with a non-secure `randomHex(8)`.
+- If `SESSION` is a string, it is treated as a seed and replaced via `seedHex(seed, 8)` (deterministic).
+- If `SESSION` is a function, the function is called per invocation.
+
+Any other key in `replacements` is also substituted (`{KEY}` → value). For non-SESSION entries: functions are called,
+strings are used literally.
+
+- **Parameters:**
+    - `rawProxy` (String): Newline-separated proxy list.
+    - `replacements` (Object): Placeholder values keyed by placeholder name.
+- **Returns:** Final proxy URL string, or `null` if the list is empty.
+
+## File I/O (JSON)
+
+### readJsonFile(filePath, defaultValue = {})
+
+Asynchronously reads a JSON file and parses it. Returns `defaultValue` on any failure (missing file, malformed JSON,
+permission error).
+
+- **Parameters:**
+    - `filePath` (String): Path to JSON file.
+    - `defaultValue` (Any): Fallback when read or parse fails.
+- **Returns:** `Promise` resolving to parsed JSON or `defaultValue`.
+
+### readJsonFileSync(filePath, defaultValue = {})
+
+Synchronous version of `readJsonFile`.
+
+- **Parameters:**
+    - `filePath` (String): Path to JSON file.
+    - `defaultValue` (Any): Fallback when read or parse fails.
+- **Returns:** Parsed JSON or `defaultValue`.
+
+### writeJsonFile(filePath, data)
+
+Asynchronously writes `data` as JSON. Errors propagate to the caller.
+
+- **Parameters:**
+    - `filePath` (String): Destination path.
+    - `data` (Any): JSON-serializable value.
+- **Returns:** `Promise` that resolves once the file is written.
+
+### writeJsonFileSync(filePath, data)
+
+Synchronous version of `writeJsonFile`.
+
+- **Parameters:**
+    - `filePath` (String): Destination path.
+    - `data` (Any): JSON-serializable value.
+- **Returns:** `undefined`.
+
+## File System
+
+### createNumberedDirs(mainDirectory, start = 0, end = 9)
+
+Creates `mainDirectory` (recursive) and a numbered subdirectory for each integer in `[start, end]` (inclusive). Existing
+directories are kept.
+
+- **Parameters:**
+    - `mainDirectory` (String): Parent directory path.
+    - `start` (Number): First subdirectory index. Default `0`.
+    - `end` (Number): Last subdirectory index. Default `9`.
+- **Returns:** `undefined`.
+
+### clearDirectory(directoryPath, keepDir = true)
+
+Recursively removes all files and subdirectories under `directoryPath`. When `keepDir` is `true` (default), the root
+directory itself is preserved (created if missing); when `false`, the root is removed too.
+
+- **Parameters:**
+    - `directoryPath` (String): Directory to clear.
+    - `keepDir` (Boolean): Whether to keep (or recreate) the root directory.
+- **Returns:** `Promise<void>`.
+
+## Process & Network
+
+### executeCommand(command)
+
+Runs a shell command (promisified `child_process.exec`) and returns the trimmed stdout. Rejects only on a non-zero exit
+code; output on stderr alone does not reject.
+
+- **Parameters:**
+    - `command` (String): Shell command line.
+- **Returns:** `Promise<String>` with the command's stdout.
+- **Throws:** When the command exits with a non-zero code.
+
+### hostIp()
+
+Returns the first non-loopback, non-internal IPv4 address found in the host's network interfaces, skipping `127.0.0.1`
+and any address starting with `192.168.`. Falls back to `127.0.0.1` if none qualifies.
+
+- **Returns:** IPv4 address string.
+
+### gitVersion()
+
+Builds a version string from the UTC timestamp of the latest git commit in the current working directory.
+
+- **Returns:** `YYMMDD.HHMM` string, or `"1.0"` when git is unavailable or the timestamp cannot be parsed.

package/lib/cjs/index.cjs

@@ -0,0 +1,351 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.CONSTANTS = void 0;
+exports.Exception = Exception;
+exports.checkEmpty = checkEmpty;
+exports.coerceObjectIntegers = coerceObjectIntegers;
+exports.coerceObjectNumbers = coerceObjectNumbers;
+exports.cookiesFromHeader = cookiesFromHeader;
+exports.cookiesFromResponse = cookiesFromResponse;
+exports.cookiesToHeader = cookiesToHeader;
+exports.findNodeByKey = findNodeByKey;
+exports.forever = forever;
+exports.getResponseError = getResponseError;
+exports.isInt32 = isInt32;
+exports.isPositiveNumber = isPositiveNumber;
+exports.isTransientHttpCode = isTransientHttpCode;
+exports.isValidURL = isValidURL;
+exports.limitString = limitString;
+exports.mulberry32 = mulberry32;
+exports.objectStringify = objectStringify;
+exports.pascalCase = pascalCase;
+exports.promiseSilent = promiseSilent;
+exports.promiseTimeout = promiseTimeout;
+exports.randomBoolean = randomBoolean;
+exports.randomElement = randomElement;
+exports.randomHex = randomHex;
+exports.randomInteger = randomInteger;
+exports.randomString = randomString;
+exports.randomUuid = randomUuid;
+exports.randomWeighted = randomWeighted;
+exports.retry = retry;
+exports.safeString = safeString;
+exports.seedHex = seedHex;
+exports.shuffleObject = shuffleObject;
+exports.shuffleString = shuffleString;
+exports.sleep = sleep;
+exports.sleepMs = sleepMs;
+exports.splitTrim = splitTrim;
+exports.time = time;
+exports.titleCase = titleCase;
+exports.waitForProperty = waitForProperty;
+var _xss = _interopRequireDefault(require("xss"));
+var _setCookieParser = _interopRequireDefault(require("set-cookie-parser"));
+var _camelCase = _interopRequireDefault(require("lodash/camelCase.js"));
+var _upperFirst = _interopRequireDefault(require("lodash/upperFirst.js"));
+var _isEmpty = _interopRequireDefault(require("lodash/isEmpty.js"));
+var _shuffle = _interopRequireDefault(require("lodash/shuffle.js"));
+function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e }; }
+const CONSTANTS = exports.CONSTANTS = {
+  LOWER_CASE: "abcdefghijklmnopqrstuvwxyz",
+  UPPER_CASE: "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
+  HEXADECIMAL: "0123456789abcdef",
+  NUMBERS: "0123456789",
+  INT32_MIN: -2147483648,
+  INT32_MAX: 2147483647
+};
+const NUMBER_PATTERN = /^-?\d+(\.\d+)?(e[+-]?\d+)?$/i;
+const INTEGER_PATTERN = /^-?\d+$/;
+function Exception(message, response = {}, name = null) {
+  const error = new Error(message);
+  error.name = name || "Exception";
+  error.response = response;
+  if (checkEmpty(response)) {
+    error.response = {};
+  }
+  return error;
+}
+function time() {
+  return Math.floor(Date.now() / 1000);
+}
+function sleepMs(milliseconds) {
+  return new Promise(resolve => setTimeout(resolve, milliseconds));
+}
+function sleep(seconds) {
+  return sleepMs(seconds * 1000);
+}
+function promiseTimeout(milliseconds, promise) {
+  let timer;
+  const timeout = new Promise((_, reject) => {
+    timer = setTimeout(() => reject(new Error(`Promise timed out after ${milliseconds}ms`)), milliseconds);
+  });
+  return Promise.race([promise, timeout]).finally(() => clearTimeout(timer));
+}
+function promiseSilent(promise) {
+  return promise.then(() => {}).catch(() => {});
+}
+async function forever(delayMs, task, onError = null, onFinally = null) {
+  if (!isPositiveNumber(delayMs)) throw new Error("delayMs must be a positive number");
+  const maybeUpdate = value => {
+    if (isPositiveNumber(value)) delayMs = value;
+  };
+  while (true) {
+    try {
+      maybeUpdate(await task());
+    } catch (error) {
+      if (onError) maybeUpdate(await onError(error));
+    } finally {
+      if (onFinally) {
+        try {
+          maybeUpdate(await onFinally());
+        } catch {}
+      }
+      await sleepMs(delayMs);
+    }
+  }
+}
+async function retry(callFn, maxAttempts, errorFn = null, {
+  delayMs = 0,
+  backoffFactor = 1
+} = {}) {
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await callFn();
+    } catch (error) {
+      if (errorFn) await errorFn(attempt, error);
+      if (attempt >= maxAttempts) throw error;
+      if (delayMs > 0) await sleepMs(delayMs * backoffFactor ** (attempt - 1));
+    }
+  }
+}
+function isValidURL(url) {
+  try {
+    new URL(url);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function splitTrim(string, separator = null) {
+  return string.split(separator ?? /\r?\n/).map(item => item.trim()).filter(Boolean);
+}
+function checkEmpty(value) {
+  if (typeof value === "number") return value === 0;
+  return (0, _isEmpty.default)(value);
+}
+function pascalCase(string) {
+  return (0, _upperFirst.default)((0, _camelCase.default)(string));
+}
+function titleCase(string, separator = " ") {
+  return (string || "").split(separator).map(_upperFirst.default).join(separator);
+}
+function isInt32(value) {
+  return Number.isInteger(value) && value >= CONSTANTS.INT32_MIN && value <= CONSTANTS.INT32_MAX;
+}
+function isPositiveNumber(value) {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0;
+}
+function coerceObjectNumbers(object) {
+  for (const key of Object.keys(object)) {
+    const value = object[key];
+    if (typeof value === 'string' && NUMBER_PATTERN.test(value)) {
+      object[key] = parseFloat(value);
+    }
+  }
+  return object;
+}
+function coerceObjectIntegers(object) {
+  for (const key of Object.keys(object)) {
+    const value = object[key];
+    if (typeof value === 'string' && INTEGER_PATTERN.test(value)) {
+      object[key] = parseInt(value);
+    }
+  }
+  return object;
+}
+function findNodeByKey(key, node, pair = null) {
+  if (node && typeof node === 'object') {
+    if (Object.hasOwn(node, key) && (pair === null || node[key] === pair)) {
+      return node;
+    }
+    for (const childKey of Object.keys(node)) {
+      const result = findNodeByKey(key, node[childKey], pair);
+      if (result) return result;
+    }
+  }
+  return null;
+}
+function waitForProperty(object, property, timeout = 5000, interval = 100) {
+  return new Promise((resolve, reject) => {
+    if (Object.hasOwn(object, property)) {
+      resolve(object[property]);
+      return;
+    }
+    const startTime = Date.now();
+    const checkProperty = setInterval(() => {
+      if (Object.hasOwn(object, property)) {
+        clearInterval(checkProperty);
+        resolve(object[property]);
+      } else if (Date.now() - startTime >= timeout) {
+        clearInterval(checkProperty);
+        reject(new Error(`Property "${property}" did not appear within ${timeout} milliseconds`));
+      }
+    }, interval);
+  });
+}
+function shuffleObject(object) {
+  return Object.fromEntries((0, _shuffle.default)(Object.entries(object)));
+}
+function objectStringify(object) {
+  for (const key of Object.keys(object)) {
+    const value = object[key];
+    if (value !== null && typeof value === 'object') {
+      objectStringify(value);
+    } else {
+      object[key] = String(value);
+    }
+  }
+  return object;
+}
+function limitString(string, limit = 35, omission = "...") {
+  string = string || "";
+  if (string.length <= limit) return string;
+  return string.slice(0, limit - omission.length) + omission;
+}
+function safeString(string) {
+  return (0, _xss.default)(string || "", {
+    whiteList: {},
+    stripIgnoreTag: true,
+    stripIgnoreTagBody: ["script", "style", "iframe", "object", "embed", "form"],
+    css: false
+  });
+}
+function shuffleString(string) {
+  return (0, _shuffle.default)(string.split('')).join('');
+}
+function randomBoolean() {
+  return Math.random() < 0.5;
+}
+function randomString(length, useNumbers = true, useUppercase = false) {
+  let characters = CONSTANTS.LOWER_CASE;
+  if (useUppercase) characters += CONSTANTS.UPPER_CASE;
+  if (useNumbers) characters += CONSTANTS.NUMBERS;
+  let result = '';
+  for (let i = 0; i < length; i++) {
+    result += characters[Math.random() * characters.length | 0];
+  }
+  return result;
+}
+function randomHex(length) {
+  let result = '';
+  for (let i = 0; i < length; i++) {
+    result += CONSTANTS.HEXADECIMAL[Math.random() * 16 | 0];
+  }
+  return result;
+}
+function randomInteger(min, max) {
+  if (typeof max === 'undefined') {
+    max = min;
+    min = 0;
+  }
+  if (typeof min !== 'number' || typeof max !== 'number') {
+    throw new Error('min and max must be numerical values');
+  }
+  if (max <= min) {
+    throw new Error('max must be greater than min');
+  }
+  return Math.floor(Math.random() * (max - min)) + min;
+}
+function randomUuid(useDashes = true) {
+  const uuid = 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, c => {
+    const r = Math.random() * 16 | 0;
+    return (c === 'x' ? r : r & 0x3 | 0x8).toString(16);
+  });
+  return useDashes ? uuid : uuid.replaceAll("-", "");
+}
+function randomWeighted(object) {
+  const elements = Object.keys(object);
+  const weights = Object.values(object);
+  const totalWeight = weights.reduce((sum, weight) => sum + weight, 0);
+  const randomNum = Math.random() * totalWeight;
+  let weightSum = 0;
+  for (let i = 0; i < elements.length; i++) {
+    weightSum += weights[i];
+    if (randomNum < weightSum) {
+      return elements[i];
+    }
+  }
+}
+function randomElement(object) {
+  if (!object) return undefined;
+  const values = Array.isArray(object) ? object : Object.values(object);
+  if (values.length === 0) return undefined;
+  return values[Math.floor(Math.random() * values.length)];
+}
+function mulberry32(seed) {
+  if (typeof seed === "string") {
+    let h = 0;
+    for (let i = 0; i < seed.length; i++) {
+      h = Math.imul(h ^ seed.charCodeAt(i), 2654435761);
+    }
+    seed = h >>> 0;
+  }
+  return function () {
+    seed = seed + 0x6D2B79F5 | 0;
+    let t = seed;
+    t = Math.imul(t ^ t >>> 15, t | 1);
+    t ^= t + Math.imul(t ^ t >>> 7, t | 61);
+    return ((t ^ t >>> 14) >>> 0) / 4294967296;
+  };
+}
+function seedHex(seed, length) {
+  const rng = mulberry32(String(seed));
+  let result = '';
+  while (result.length < length) {
+    result += Math.floor(rng() * 0x100000000).toString(16).padStart(8, '0');
+  }
+  return result.slice(0, length);
+}
+function cookiesFromResponse(response, decodeValues = false) {
+  const dict = {};
+  const cookies = _setCookieParser.default.parse(response, {
+    decodeValues
+  });
+  for (const cookie of cookies) {
+    dict[cookie.name] = cookie.value;
+  }
+  return dict;
+}
+function cookiesToHeader(cookies) {
+  if (!cookies) return "";
+  return Object.entries(cookies).filter(([, value]) => value !== null && value !== undefined).map(([key, value]) => `${key}=${value}`).join("; ");
+}
+function cookiesFromHeader(header) {
+  const cookies = {};
+  if (!header) return cookies;
+  header.split(';').forEach(cookie => {
+    const trimmed = cookie.trim();
+    if (!trimmed.includes('=')) return;
+    const [key, ...valueParts] = trimmed.split('=');
+    const trimmedKey = key.trim();
+    if (trimmedKey) {
+      cookies[trimmedKey] = valueParts.join('=').trim();
+    }
+  });
+  return cookies;
+}
+function isTransientHttpCode(httpCode) {
+  return !httpCode || isNaN(httpCode) || httpCode === 100 || httpCode === 402 || httpCode === 407 || 460 <= httpCode && httpCode < 470 || 500 <= httpCode;
+}
+function getResponseError(error, limit = 200) {
+  let response;
+  if (error?.response?.status && error.response.data) {
+    response = `${error.response.status}|${error.response.data}`;
+  } else if (error?.response?.data) {
+    response = error.response.data;
+  }
+  return limitString(response || error.message, limit).trim();
+}