melperjs 16.0.0 → 16.1.0

package/README.md

@@ -13,10 +13,10 @@ npm i melperjs
 
 ## Documentation
 
-Full API reference lives in the [docs folder](docs/index.md):
+Full API reference lives in the [docs folder](docs/docs.md):
 
-- [General Functions](docs/general.md) — `melperjs` (browser-safe)
-- [Node.js Functions](docs/node.md) — `melperjs/node`
+- [General Functions](docs/index.md) — browser-safe helpers (`melperjs`)
+- [Node.js Functions](docs/node.md) — Node-only helpers (`melperjs/node`)
 
 ## License
 

package/docs/docs.md

@@ -0,0 +1,27 @@
+# Documentation
+
+`melperjs` is a small utility library split into two entry points:
+
+- **Core module** (`melperjs`) — browser-safe helpers. No Node-only APIs, no `crypto`, no `fs`. Safe to import from any
+  JavaScript environment.
+- **Node module** (`melperjs/node`) — Node.js-specific helpers built on `crypto`, `fs`, `child_process`, and `os`.
+  Importing this in a browser will fail.
+
+## Usage
+
+```javascript
+// ES Module
+import * as helper from "melperjs";
+import * as nodeHelper from "melperjs/node";
+
+// CommonJS
+const helper = require("melperjs");
+const nodeHelper = require("melperjs/node");
+```
+
+Both forms are supported via dual ESM/CJS builds.
+
+## Sections
+
+- [General Functions](index.md) — browser-safe helpers (`melperjs`)
+- [Node.js Functions](./node.md) — Node-only helpers (`melperjs/node`)

package/docs/index.md

@@ -1,27 +1,363 @@
-# Documentation
+# General Functions
 
-`melperjs` is a small utility library split into two entry points:
+Browser-safe utilities exported from `melperjs`. No Node.js APIs are used here — every function runs in the browser and in Node.js without polyfills.
 
-- **Core module** (`melperjs`) — browser-safe helpers. No Node-only APIs, no `crypto`, no `fs`. Safe to import from any
-  JavaScript environment.
-- **Node module** (`melperjs/node`) — Node.js-specific helpers built on `crypto`, `fs`, `child_process`, and `os`.
-  Importing this in a browser will fail.
+## Constants
 
-## Usage
+`CONSTANTS` bundles a few character sets and integer bounds that other functions in this module rely on. Useful when you need the same alphabets in your own code.
 
-```javascript
-// ES Module
-import * as helper from "melperjs";
-import * as nodeHelper from "melperjs/node";
+- `CONSTANTS.LOWER_CASE` — lowercase ASCII letters (`a-z`).
+- `CONSTANTS.UPPER_CASE` — uppercase ASCII letters (`A-Z`).
+- `CONSTANTS.HEXADECIMAL` — hex digits (`0-9a-f`).
+- `CONSTANTS.NUMBERS` — decimal digits (`0-9`).
+- `CONSTANTS.INT32_MIN` — `-2147483648`.
+- `CONSTANTS.INT32_MAX` — `2147483647`.
 
-// CommonJS
-const helper = require("melperjs");
-const nodeHelper = require("melperjs/node");
-```
+## Errors
 
-Both forms are supported via dual ESM/CJS builds.
+### Exception(message, response = {}, name = null)
 
-## Sections
+Builds a standard `Error` with two extra attached fields (`response`, custom `name`) so error handlers can carry HTTP-style context without subclassing. A null/empty `response` is normalized to `{}`.
 
-- [General Functions](./general.md) — browser-safe helpers (`melperjs`)
-- [Node.js Functions](./node.md) — Node-only helpers (`melperjs/node`)
+- **Parameters:**
+  - `message` (String): Human-readable error message.
+  - `response` (Object): Arbitrary payload attached as `error.response`.
+  - `name` (String|null): Overrides `error.name`. Defaults to `"Exception"`.
+- **Returns:** `Error` with `.response` and `.name` populated.
+
+## Time & Async
+
+### time()
+
+Current Unix timestamp in seconds (integer).
+
+- **Returns:** Seconds since the epoch.
+
+### sleepMs(milliseconds)
+
+Promise that resolves after a delay, measured in milliseconds.
+
+- **Parameters:**
+  - `milliseconds` (Number): Delay in ms.
+- **Returns:** `Promise<void>`.
+
+### sleep(seconds)
+
+Same as `sleepMs` but the delay is given in seconds.
+
+- **Parameters:**
+  - `seconds` (Number): Delay in seconds.
+- **Returns:** `Promise<void>`.
+
+### promiseTimeout(milliseconds, promise)
+
+Races a promise against a timer. If the promise doesn't settle in time the result rejects; either way the timer is cleared.
+
+- **Parameters:**
+  - `milliseconds` (Number): Maximum wait time before rejecting.
+  - `promise` (Promise): The work to await.
+- **Returns:** Settles with the inner promise's value, or rejects with `Error("Promise timed out after Xms")`.
+
+### promiseSilent(promise)
+
+Awaits a promise but swallows both the resolved value and any rejection. Handy for fire-and-forget work where you only care about the side effects.
+
+- **Parameters:**
+  - `promise` (Promise): The promise to consume silently.
+- **Returns:** `Promise<undefined>` that always resolves.
+
+### forever(delayMs, task, onError = null, onFinally = null)
+
+Runs `task` in an infinite loop with a delay between iterations. Errors are routed to `onError`; `onFinally` runs after every iteration regardless of outcome. Any of the three callbacks can return a new positive number to update `delayMs` on the fly (useful for adaptive polling).
+
+Errors thrown from `task` are caught and routed to `onError`; the loop keeps running. Errors thrown from `onError` propagate out and stop the loop — useful for soft shutdown by throwing on a stop signal. Errors thrown from `onFinally` are caught and ignored so that observability/cleanup failures cannot kill the worker.
+
+- **Parameters:**
+  - `delayMs` (Number): Initial delay in milliseconds between iterations. Must be a positive finite number.
+  - `task` (Function): Async function to invoke each iteration. Exceptions are caught and forwarded to `onError`.
+  - `onError` (Function): Called with the caught error when `task` throws. Throwing from here aborts the loop.
+  - `onFinally` (Function): Called after every iteration (success or failure). Errors thrown here are swallowed.
+- **Returns:** Promise that never resolves on its own; it rejects when `delayMs` validation fails or when `onError` throws.
+- **Throws:** When `delayMs` is not a positive finite number.
+
+### retry(task, maxAttempts = 1, onError = null, {delayMs = 0, backoffFactor = 1} = {})
+
+Calls `task` up to `maxAttempts` times, returning the first successful result. Optionally waits between retries with an exponential backoff (delay grows by `delayMs * backoffFactor^(attempt-1)`).
+
+- **Parameters:**
+  - `task` (Function): Async function to attempt.
+  - `maxAttempts` (Number): Total attempt count (1 = no retries). Default `1`.
+  - `onError` (Function): Called as `(attempt, error)` after each failed attempt.
+  - `options.delayMs` (Number): Base delay between retries in ms. `0` disables delay.
+  - `options.backoffFactor` (Number): Multiplier applied per attempt. `1` keeps delay constant; `2` doubles each retry.
+- **Returns:** The first non-throwing result of `task`.
+- **Throws:** The last error after `maxAttempts` failures.
+
+## Strings
+
+### isValidURL(url)
+
+Tests whether the input parses as a valid URL via the `URL` constructor.
+
+- **Parameters:**
+  - `url` (String): Candidate URL.
+- **Returns:** `Boolean`.
+
+### splitTrim(string, separator = null)
+
+Splits a string, trims each piece, and drops empty results. Default separator is `\r?\n` (any newline).
+
+- **Parameters:**
+  - `string` (String): Source text.
+  - `separator` (String|RegExp|null): Custom delimiter; `null` falls back to newlines.
+- **Returns:** Array of non-empty trimmed strings.
+
+### pascalCase(string)
+
+Converts arbitrary text to `PascalCase` (uses lodash internally).
+
+- **Parameters:**
+  - `string` (String): Input text.
+- **Returns:** PascalCase string.
+
+### titleCase(string, separator = " ")
+
+Capitalizes the first letter of each word delimited by `separator`. Other characters are preserved as-is.
+
+- **Parameters:**
+  - `string` (String): Input text.
+  - `separator` (String): Word boundary. Defaults to a single space.
+- **Returns:** Title-cased string.
+
+### limitString(string, limit = 35, omission = "...")
+
+Truncates a string if it exceeds `limit` characters and appends `omission`. Strings shorter than the limit are returned unchanged.
+
+- **Parameters:**
+  - `string` (String): Input text.
+  - `limit` (Number): Maximum length of the result (including `omission`).
+  - `omission` (String): Suffix used when truncation happens.
+- **Returns:** Possibly truncated string.
+
+### safeString(string)
+
+Strips HTML tags via the `xss` library and additionally removes the body of dangerous block tags (`<script>`, `<style>`, `<iframe>`, `<object>`, `<embed>`, `<form>`) so leftover CSS/markup cannot leak as text. CSS attribute sanitization is also disabled (no `<style>` attribute support). Intended for rendering untrusted text safely; not a substitute for a full HTML sanitizer like DOMPurify.
+
+- **Parameters:**
+  - `string` (String): Untrusted text.
+- **Returns:** Sanitized string with no allowed tags.
+
+### shuffleString(string)
+
+Randomly reorders the characters in a string using lodash's `shuffle` (Fisher-Yates).
+
+- **Parameters:**
+  - `string` (String): Source string.
+- **Returns:** Shuffled string of the same length.
+
+## Random (non-cryptographic, Math.random)
+
+### randomBoolean()
+
+Returns a random `true` or `false` with uniform probability.
+
+- **Returns:** `Boolean`.
+
+### randomString(length, useNumbers = true, useUppercase = false)
+
+Generates a 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.
+
+### randomHex(length)
+
+Generates a random hexadecimal string.
+
+- **Parameters:**
+  - `length` (Number): Output length.
+- **Returns:** Hex string of the requested length.
+
+### randomInteger(min, max)
+
+Returns a random integer in `[min, max)`. If called with a single argument it is treated as `max` with `min = 0` (e.g., `randomInteger(10)` returns `0..9`).
+
+- **Parameters:**
+  - `min` (Number): Inclusive lower bound, or `max` when called with one argument.
+  - `max` (Number): Exclusive upper bound.
+- **Returns:** Integer in `[min, max)`.
+- **Throws:** When inputs are not numbers, or when `max <= min`.
+
+### randomUuid(useDashes = true)
+
+Generates a random UUID v4-shaped string. Not suitable for security tokens; use `secureRandomUuid` instead.
+
+- **Parameters:**
+  - `useDashes` (Boolean): When `false`, dashes are stripped.
+- **Returns:** UUID string.
+
+### randomWeighted(object)
+
+Picks a random key from `object` with probability proportional to its weight. Returns `undefined` for empty or nullish input.
+
+- **Parameters:**
+  - `object` (Object): Map of key → positive weight.
+- **Returns:** Selected key, or `undefined`.
+
+### randomElement(object)
+
+Picks a 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)
+
+### mulberry32(seed)
+
+Returns a deterministic PRNG (Mulberry32) seeded by a 32-bit integer or by a string (hashed internally to 32 bits). Each call to the returned function produces a `[0, 1)` float. Very fast, but only 32 bits of state — not for cryptographic use.
+
+- **Parameters:**
+  - `seed` (Number|String): Seed value.
+- **Returns:** Function that returns a `Number` in `[0, 1)` per call.
+
+### seedHex(seed, length)
+
+Builds a deterministic hex string of the requested length from a seed via `mulberry32`. Same seed always yields the same output. Useful for short, repeatable identifiers (e.g., proxy session stickiness).
+
+- **Parameters:**
+  - `seed` (Any): Seed value (coerced to string).
+  - `length` (Number): Output length in hex characters. Required.
+- **Returns:** Hex string.
+
+## Predicates
+
+### checkEmpty(value)
+
+Like lodash's `isEmpty` but additionally treats `0` (numeric zero) as empty.
+
+- **Parameters:**
+  - `value` (Any): Value to test.
+- **Returns:** `Boolean`.
+
+### isInt32(value)
+
+Tests whether `value` is an integer within the signed 32-bit range.
+
+- **Parameters:**
+  - `value` (Any): Value to test.
+- **Returns:** `Boolean`.
+
+### isPositiveNumber(value)
+
+Tests whether `value` is a finite positive number (excludes `NaN`, `Infinity`, non-numbers, `0`, and negatives).
+
+- **Parameters:**
+  - `value` (Any): Value to test.
+- **Returns:** `Boolean`.
+
+## Objects
+
+### coerceObjectNumbers(object)
+
+Walks an object's own enumerable keys and converts string values that match a numeric pattern (e.g., `"1.5"`, `"-3"`, `"1e3"`) to `Number`. Non-string values and non-strict numeric strings (e.g., `"12abc"`, `"1,000"`) are left untouched. Mutates the input.
+
+- **Parameters:**
+  - `object` (Object): Object to coerce in place.
+- **Returns:** The same `object`.
+
+### coerceObjectIntegers(object)
+
+Same as `coerceObjectNumbers` but only converts whole integer strings via `parseInt` (e.g., `"002"` → `2`, `"-7"` → `-7`). Mutates the input.
+
+- **Parameters:**
+  - `object` (Object): Object to coerce in place.
+- **Returns:** The same `object`.
+
+### findNodeByKey(key, node, pair = null)
+
+Depth-first search through a nested object for the first node that owns `key`. If `pair` is provided, the node's value at `key` must equal `pair` (strict equality, supports falsy values like `false` / `0` / `""`).
+
+- **Parameters:**
+  - `key` (String): Property name to find.
+  - `node` (Object): Tree to search.
+  - `pair` (Any): Optional value constraint. `null` means "match any value".
+- **Returns:** The matching node, or `null` if not found.
+
+### waitForProperty(object, property, timeout = 5000, interval = 100)
+
+Polls `object` until it owns `property`, then resolves with the property's value. Rejects after `timeout` milliseconds.
+
+- **Parameters:**
+  - `object` (Object): Object to watch.
+  - `property` (String): Property name to wait for.
+  - `timeout` (Number): Maximum wait time in milliseconds.
+  - `interval` (Number): Poll interval in milliseconds.
+- **Returns:** `Promise` resolving to the property's value.
+- **Throws:** When the property does not appear within `timeout`.
+
+### shuffleObject(object)
+
+Returns a new object whose entries are in random order (the underlying iteration order is the only thing being shuffled).
+
+- **Parameters:**
+  - `object` (Object): Source object.
+- **Returns:** New object with the same keys/values in shuffled order.
+
+### objectStringify(object)
+
+Recursively walks an object and converts every leaf value to `String(value)`. Nested objects and arrays are descended into; mutates the input.
+
+- **Parameters:**
+  - `object` (Object): Object to mutate.
+- **Returns:** The same `object`.
+
+## Cookies
+
+### cookiesFromResponse(response, decodeValues = false)
+
+Parses the `Set-Cookie` headers off a response-like object (compatible with Node `http`, fetch responses, or anything with `headers["set-cookie"]`) and returns a flat `{name: value}` map via `set-cookie-parser`.
+
+- **Parameters:**
+  - `response` (Object): Response-like with parsed headers.
+  - `decodeValues` (Boolean): Whether to URL-decode cookie values.
+- **Returns:** Map of cookie name → value.
+
+### cookiesToHeader(cookies)
+
+Serializes a `{name: value}` map into a `Cookie:` header string (`name=value` pairs joined with `"; "`). Null/undefined values are dropped.
+
+- **Parameters:**
+  - `cookies` (Object): Map of cookie name → value.
+- **Returns:** Cookie header string, or `""` for empty/missing input.
+
+### cookiesFromHeader(header)
+
+Parses a single `Cookie:` header string into a `{name: value}` map. Pieces without `=` are skipped; multiple `=` inside a value are preserved.
+
+- **Parameters:**
+  - `header` (String): Cookie header value.
+- **Returns:** Map of cookie name → value. Empty input returns `{}`.
+
+## HTTP Helpers
+
+### isTransientHttpCode(httpCode)
+
+Flags HTTP status codes that are typically transient or worth retrying (missing/`NaN`, `100`, `402`, `407`, `460-469`, anything `≥ 500`).
+
+- **Parameters:**
+  - `httpCode` (Number|null|undefined): Status code to inspect.
+- **Returns:** `Boolean`.
+
+### getResponseError(error, limit = 200)
+
+Extracts a short error description from an HTTP error-like object. Prefers `error.response.status|error.response.data`, then `error.response.data`, then `error.message`. Truncates the result to `limit` characters via `limitString`.
+
+- **Parameters:**
+  - `error` (Error): Error from an HTTP client.
+  - `limit` (Number): Maximum length of the returned string.
+- **Returns:** Trimmed error description.

package/docs/node.md

@@ -7,11 +7,11 @@ and will not run in a browser.
 
 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).
+see the `random*` family in [General Functions](index.md).
 
 ### secureRandomBoolean()
 
-Returns `true` or `false` with cryptographically uniform probability.
+Returns a cryptographically random `true` or `false` with uniform probability.
 
 - **Returns:** `Boolean`.
 
@@ -35,16 +35,17 @@ Generates a cryptographically random hexadecimal string.
 
 ### secureRandomInteger(min, max)
 
-Returns a cryptographically random integer in `[min, max)`. Thin wrapper over `crypto.randomInt`.
+Returns a cryptographically random integer in `[min, max)`. If called with a single argument it is treated as `max` with `min = 0` (e.g., `secureRandomInteger(10)` returns `0..9`).
 
 - **Parameters:**
-    - `min` (Number): Inclusive lower bound.
+    - `min` (Number): Inclusive lower bound, or `max` when called with one argument.
     - `max` (Number): Exclusive upper bound.
 - **Returns:** Integer in `[min, max)`.
+- **Throws:** When inputs are not numbers, or when `max <= min`.
 
 ### secureRandomUuid(useDashes = true)
 
-Generates a cryptographically random UUID v4 via `crypto.randomUUID()`. Suitable for security tokens.
+Generates a cryptographically random UUID v4 string. Suitable for security tokens.
 
 - **Parameters:**
     - `useDashes` (Boolean): When `false`, dashes are stripped.
@@ -52,17 +53,15 @@ Generates a cryptographically random UUID v4 via `crypto.randomUUID()`. Suitable
 
 ### secureRandomWeighted(object)
 
-Picks a key from `object` with probability proportional to its weight, using `crypto.randomInt` for selection. Weights
-must be positive integers.
+Picks a cryptographically random key from `object` with probability proportional to its weight. Returns `undefined` for empty or nullish input.
 
 - **Parameters:**
     - `object` (Object): Map of key → positive integer weight.
-- **Returns:** Selected key.
+- **Returns:** Selected key, or `undefined`.
 
 ### 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.
+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.

package/lib/cjs/index.cjs

@@ -89,33 +89,33 @@ function promiseSilent(promise) {
 }
 async function forever(delayMs, task, onError = null, onFinally = null) {
   if (!isPositiveNumber(delayMs)) throw new Error("delayMs must be a positive number");
-  const maybeUpdate = value => {
+  const update = value => {
     if (isPositiveNumber(value)) delayMs = value;
   };
   while (true) {
     try {
-      maybeUpdate(await task());
+      update(await task());
     } catch (error) {
-      if (onError) maybeUpdate(await onError(error));
+      if (onError) update(await onError(error));
     } finally {
       if (onFinally) {
         try {
-          maybeUpdate(await onFinally());
+          update(await onFinally());
         } catch {}
       }
       await sleepMs(delayMs);
     }
   }
 }
-async function retry(callFn, maxAttempts, errorFn = null, {
+async function retry(task, maxAttempts = 1, onError = null, {
   delayMs = 0,
   backoffFactor = 1
 } = {}) {
   for (let attempt = 1; attempt <= maxAttempts; attempt++) {
     try {
-      return await callFn();
+      return await task();
     } catch (error) {
-      if (errorFn) await errorFn(attempt, error);
+      if (onError) await onError(attempt, error);
       if (attempt >= maxAttempts) throw error;
       if (delayMs > 0) await sleepMs(delayMs * backoffFactor ** (attempt - 1));
     }
@@ -146,7 +146,7 @@ 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;
+  return Number.isFinite(value) && value > 0;
 }
 function coerceObjectNumbers(object) {
   for (const key of Object.keys(object)) {
@@ -191,7 +191,7 @@ function waitForProperty(object, property, timeout = 5000, interval = 100) {
         resolve(object[property]);
       } else if (Date.now() - startTime >= timeout) {
         clearInterval(checkProperty);
-        reject(new Error(`Property "${property}" did not appear within ${timeout} milliseconds`));
+        reject(new Error(`Property "${property}" did not appear within ${timeout}ms`));
       }
     }, interval);
   });
@@ -246,7 +246,7 @@ function randomHex(length) {
   }
   return result;
 }
-function randomInteger(min, max) {
+function randomInteger(min, max = undefined) {
   if (typeof max === 'undefined') {
     max = min;
     min = 0;
@@ -267,6 +267,7 @@ function randomUuid(useDashes = true) {
   return useDashes ? uuid : uuid.replaceAll("-", "");
 }
 function randomWeighted(object) {
+  if (checkEmpty(object)) return undefined;
   const elements = Object.keys(object);
   const weights = Object.values(object);
   const totalWeight = weights.reduce((sum, weight) => sum + weight, 0);
@@ -280,7 +281,7 @@ function randomWeighted(object) {
   }
 }
 function randomElement(object) {
-  if (!object) return undefined;
+  if (checkEmpty(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)];
@@ -310,14 +311,14 @@ function seedHex(seed, length) {
   return result.slice(0, length);
 }
 function cookiesFromResponse(response, decodeValues = false) {
-  const dict = {};
+  const obj = {};
   const cookies = _setCookieParser.default.parse(response, {
     decodeValues
   });
   for (const cookie of cookies) {
-    dict[cookie.name] = cookie.value;
+    obj[cookie.name] = cookie.value;
   }
-  return dict;
+  return obj;
 }
 function cookiesToHeader(cookies) {
   if (!cookies) return "";

package/lib/cjs/node.cjs

@@ -42,7 +42,7 @@ function _interopRequireDefault(e) { return e && e.__esModule ? e : { default: e
 function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
 const execAsync = (0, _util.promisify)(_child_process.exec);
 function secureRandomBoolean() {
-  return _crypto.default.randomInt(2) === 0;
+  return secureRandomInteger(2) === 1;
 }
 function secureRandomString(length, useNumbers = true, useUppercase = false) {
   let characters = _index.CONSTANTS.LOWER_CASE;
@@ -50,14 +50,14 @@ function secureRandomString(length, useNumbers = true, useUppercase = false) {
   if (useNumbers) characters += _index.CONSTANTS.NUMBERS;
   let result = '';
   for (let i = 0; i < length; i++) {
-    result += characters[_crypto.default.randomInt(0, characters.length)];
+    result += characters[secureRandomInteger(0, characters.length)];
   }
   return result;
 }
 function secureRandomHex(length) {
   return _crypto.default.randomBytes(Math.ceil(length / 2)).toString('hex').slice(0, length);
 }
-function secureRandomInteger(min, max) {
+function secureRandomInteger(min, max = undefined) {
   return _crypto.default.randomInt(min, max);
 }
 function secureRandomUuid(useDashes = true) {
@@ -65,6 +65,7 @@ function secureRandomUuid(useDashes = true) {
   return useDashes ? uuid : uuid.replaceAll("-", "");
 }
 function secureRandomWeighted(object) {
+  if ((0, _index.checkEmpty)(object)) return undefined;
   const elements = Object.keys(object);
   const weights = Object.values(object);
   const totalWeight = weights.reduce((sum, weight) => sum + weight, 0);
@@ -78,10 +79,10 @@ function secureRandomWeighted(object) {
   }
 }
 function secureRandomElement(object) {
-  if (!object) return undefined;
+  if ((0, _index.checkEmpty)(object)) return undefined;
   const values = Array.isArray(object) ? object : Object.values(object);
   if (values.length === 0) return undefined;
-  return values[_crypto.default.randomInt(0, values.length)];
+  return values[secureRandomInteger(0, values.length)];
 }
 function uuidFromSeed(seed, useDashes = true) {
   const hash = _crypto.default.createHash('md5').update(seed).digest();
@@ -174,7 +175,7 @@ function normalizeProxy(proxy, protocol = "http") {
     const start = Number(parts[1]);
     const end = Number(parts[2]);
     if (Number.isInteger(start) && Number.isInteger(end) && start >= 0 && start <= end) {
-      body = `${parts[0]}:${_crypto.default.randomInt(start, end + 1)}`;
+      body = `${parts[0]}:${(0, _index.randomInteger)(start, end + 1)}`;
     }
   }
   return `${protocol}://${auth}${body}`;

package/lib/esm/index.mjs

@@ -44,33 +44,33 @@ export function promiseSilent(promise) {
 }
 export async function forever(delayMs, task, onError = null, onFinally = null) {
   if (!isPositiveNumber(delayMs)) throw new Error("delayMs must be a positive number");
-  const maybeUpdate = value => {
+  const update = value => {
     if (isPositiveNumber(value)) delayMs = value;
   };
   while (true) {
     try {
-      maybeUpdate(await task());
+      update(await task());
     } catch (error) {
-      if (onError) maybeUpdate(await onError(error));
+      if (onError) update(await onError(error));
     } finally {
       if (onFinally) {
         try {
-          maybeUpdate(await onFinally());
+          update(await onFinally());
         } catch {}
       }
       await sleepMs(delayMs);
     }
   }
 }
-export async function retry(callFn, maxAttempts, errorFn = null, {
+export async function retry(task, maxAttempts = 1, onError = null, {
   delayMs = 0,
   backoffFactor = 1
 } = {}) {
   for (let attempt = 1; attempt <= maxAttempts; attempt++) {
     try {
-      return await callFn();
+      return await task();
     } catch (error) {
-      if (errorFn) await errorFn(attempt, error);
+      if (onError) await onError(attempt, error);
       if (attempt >= maxAttempts) throw error;
       if (delayMs > 0) await sleepMs(delayMs * backoffFactor ** (attempt - 1));
     }
@@ -101,7 +101,7 @@ export function isInt32(value) {
   return Number.isInteger(value) && value >= CONSTANTS.INT32_MIN && value <= CONSTANTS.INT32_MAX;
 }
 export function isPositiveNumber(value) {
-  return typeof value === 'number' && Number.isFinite(value) && value > 0;
+  return Number.isFinite(value) && value > 0;
 }
 export function coerceObjectNumbers(object) {
   for (const key of Object.keys(object)) {
@@ -146,7 +146,7 @@ export function waitForProperty(object, property, timeout = 5000, interval = 100
         resolve(object[property]);
       } else if (Date.now() - startTime >= timeout) {
         clearInterval(checkProperty);
-        reject(new Error(`Property "${property}" did not appear within ${timeout} milliseconds`));
+        reject(new Error(`Property "${property}" did not appear within ${timeout}ms`));
       }
     }, interval);
   });
@@ -201,7 +201,7 @@ export function randomHex(length) {
   }
   return result;
 }
-export function randomInteger(min, max) {
+export function randomInteger(min, max = undefined) {
   if (typeof max === 'undefined') {
     max = min;
     min = 0;
@@ -222,6 +222,7 @@ export function randomUuid(useDashes = true) {
   return useDashes ? uuid : uuid.replaceAll("-", "");
 }
 export function randomWeighted(object) {
+  if (checkEmpty(object)) return undefined;
   const elements = Object.keys(object);
   const weights = Object.values(object);
   const totalWeight = weights.reduce((sum, weight) => sum + weight, 0);
@@ -235,7 +236,7 @@ export function randomWeighted(object) {
   }
 }
 export function randomElement(object) {
-  if (!object) return undefined;
+  if (checkEmpty(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)];
@@ -265,14 +266,14 @@ export function seedHex(seed, length) {
   return result.slice(0, length);
 }
 export function cookiesFromResponse(response, decodeValues = false) {
-  const dict = {};
+  const obj = {};
   const cookies = setCookieParser.parse(response, {
     decodeValues
   });
   for (const cookie of cookies) {
-    dict[cookie.name] = cookie.value;
+    obj[cookie.name] = cookie.value;
   }
-  return dict;
+  return obj;
 }
 export function cookiesToHeader(cookies) {
   if (!cookies) return "";

package/lib/esm/node.mjs

@@ -6,10 +6,10 @@ import { networkInterfaces } from "os";
 import { exec, execFileSync } from "child_process";
 import { promisify } from "util";
 import bcrypt from "bcryptjs";
-import { CONSTANTS, splitTrim, randomInteger, randomHex, seedHex } from "./index.mjs";
+import { CONSTANTS, splitTrim, randomInteger, randomHex, seedHex, checkEmpty } from "./index.mjs";
 const execAsync = promisify(exec);
 export function secureRandomBoolean() {
-  return crypto.randomInt(2) === 0;
+  return secureRandomInteger(2) === 1;
 }
 export function secureRandomString(length, useNumbers = true, useUppercase = false) {
   let characters = CONSTANTS.LOWER_CASE;
@@ -17,14 +17,14 @@ export function secureRandomString(length, useNumbers = true, useUppercase = fal
   if (useNumbers) characters += CONSTANTS.NUMBERS;
   let result = '';
   for (let i = 0; i < length; i++) {
-    result += characters[crypto.randomInt(0, characters.length)];
+    result += characters[secureRandomInteger(0, characters.length)];
   }
   return result;
 }
 export function secureRandomHex(length) {
   return crypto.randomBytes(Math.ceil(length / 2)).toString('hex').slice(0, length);
 }
-export function secureRandomInteger(min, max) {
+export function secureRandomInteger(min, max = undefined) {
   return crypto.randomInt(min, max);
 }
 export function secureRandomUuid(useDashes = true) {
@@ -32,6 +32,7 @@ export function secureRandomUuid(useDashes = true) {
   return useDashes ? uuid : uuid.replaceAll("-", "");
 }
 export function secureRandomWeighted(object) {
+  if (checkEmpty(object)) return undefined;
   const elements = Object.keys(object);
   const weights = Object.values(object);
   const totalWeight = weights.reduce((sum, weight) => sum + weight, 0);
@@ -45,10 +46,10 @@ export function secureRandomWeighted(object) {
   }
 }
 export function secureRandomElement(object) {
-  if (!object) return undefined;
+  if (checkEmpty(object)) return undefined;
   const values = Array.isArray(object) ? object : Object.values(object);
   if (values.length === 0) return undefined;
-  return values[crypto.randomInt(0, values.length)];
+  return values[secureRandomInteger(0, values.length)];
 }
 export function uuidFromSeed(seed, useDashes = true) {
   const hash = crypto.createHash('md5').update(seed).digest();
@@ -141,7 +142,7 @@ export function normalizeProxy(proxy, protocol = "http") {
     const start = Number(parts[1]);
     const end = Number(parts[2]);
     if (Number.isInteger(start) && Number.isInteger(end) && start >= 0 && start <= end) {
-      body = `${parts[0]}:${crypto.randomInt(start, end + 1)}`;
+      body = `${parts[0]}:${randomInteger(start, end + 1)}`;
     }
   }
   return `${protocol}://${auth}${body}`;

package/package.json

@@ -26,7 +26,7 @@
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/mahelbir/melperjs.git"
+    "url": "git+https://github.com/mahelbir/melperjs.git"
   },
   "author": "Mahmuthan Elbir",
   "license": "MIT",
@@ -70,5 +70,5 @@
     "babel-plugin-transform-import-meta": "^2.3.3",
     "cross-env": "^10.1.0"
   },
-  "version": "16.0.0"
+  "version": "16.1.0"
 }

package/docs/general.md

@@ -1,363 +0,0 @@
-# General Functions
-
-Browser-safe utilities exported from `melperjs`. No Node.js APIs are used here — every function runs in the browser and in Node.js without polyfills.
-
-## Constants
-
-`CONSTANTS` bundles a few character sets and integer bounds that other functions in this module rely on. Useful when you need the same alphabets in your own code.
-
-- `CONSTANTS.LOWER_CASE` — lowercase ASCII letters (`a-z`).
-- `CONSTANTS.UPPER_CASE` — uppercase ASCII letters (`A-Z`).
-- `CONSTANTS.HEXADECIMAL` — hex digits (`0-9a-f`).
-- `CONSTANTS.NUMBERS` — decimal digits (`0-9`).
-- `CONSTANTS.INT32_MIN` — `-2147483648`.
-- `CONSTANTS.INT32_MAX` — `2147483647`.
-
-## Errors
-
-### Exception(message, response = {}, name = null)
-
-Builds a standard `Error` with two extra attached fields (`response`, custom `name`) so error handlers can carry HTTP-style context without subclassing. A null/empty `response` is normalized to `{}`.
-
-- **Parameters:**
-  - `message` (String): Human-readable error message.
-  - `response` (Object): Arbitrary payload attached as `error.response`.
-  - `name` (String|null): Overrides `error.name`. Defaults to `"Exception"`.
-- **Returns:** `Error` with `.response` and `.name` populated.
-
-## Time & Async
-
-### time()
-
-Current Unix timestamp in seconds (integer).
-
-- **Returns:** Seconds since the epoch.
-
-### sleepMs(milliseconds)
-
-Promise that resolves after a delay, measured in milliseconds.
-
-- **Parameters:**
-  - `milliseconds` (Number): Delay in ms.
-- **Returns:** `Promise<void>`.
-
-### sleep(seconds)
-
-Same as `sleepMs` but the delay is given in seconds.
-
-- **Parameters:**
-  - `seconds` (Number): Delay in seconds.
-- **Returns:** `Promise<void>`.
-
-### promiseTimeout(milliseconds, promise)
-
-Races a promise against a timer. If the promise doesn't settle in time the result rejects; either way the timer is cleared.
-
-- **Parameters:**
-  - `milliseconds` (Number): Maximum wait time before rejecting.
-  - `promise` (Promise): The work to await.
-- **Returns:** Settles with the inner promise's value, or rejects with `Error("Promise timed out after Xms")`.
-
-### promiseSilent(promise)
-
-Awaits a promise but swallows both the resolved value and any rejection. Handy for fire-and-forget work where you only care about the side effects.
-
-- **Parameters:**
-  - `promise` (Promise): The promise to consume silently.
-- **Returns:** `Promise<undefined>` that always resolves.
-
-### forever(delayMs, task, onError = null, onFinally = null)
-
-Runs `task` in an infinite loop with a delay between iterations. Errors are routed to `onError`; `onFinally` runs after every iteration regardless of outcome. Any of the three callbacks can return a new positive number to update `delayMs` on the fly (useful for adaptive polling).
-
-Errors thrown from `task` are caught and routed to `onError`; the loop keeps running. Errors thrown from `onError` propagate out and stop the loop — useful for soft shutdown by throwing on a stop signal. Errors thrown from `onFinally` are caught and ignored so that observability/cleanup failures cannot kill the worker.
-
-- **Parameters:**
-  - `delayMs` (Number): Initial delay in milliseconds between iterations. Must be a positive finite number.
-  - `task` (Function): Async function to invoke each iteration. Exceptions are caught and forwarded to `onError`.
-  - `onError` (Function): Called with the caught error when `task` throws. Throwing from here aborts the loop.
-  - `onFinally` (Function): Called after every iteration (success or failure). Errors thrown here are swallowed.
-- **Returns:** Promise that never resolves on its own; it rejects when `delayMs` validation fails or when `onError` throws.
-- **Throws:** When `delayMs` is not a positive finite number.
-
-### retry(callFn, maxAttempts, errorFn = null, {delayMs = 0, backoffFactor = 1} = {})
-
-Calls `callFn` up to `maxAttempts` times, returning the first successful result. Optionally waits between retries with an exponential backoff (delay grows by `delayMs * backoffFactor^(attempt-1)`).
-
-- **Parameters:**
-  - `callFn` (Function): Async function to attempt.
-  - `maxAttempts` (Number): Total attempt count (1 = no retries).
-  - `errorFn` (Function): Called as `(attempt, error)` after each failed attempt.
-  - `options.delayMs` (Number): Base delay between retries in ms. `0` disables delay.
-  - `options.backoffFactor` (Number): Multiplier applied per attempt. `1` keeps delay constant; `2` doubles each retry.
-- **Returns:** The first non-throwing result of `callFn`.
-- **Throws:** The last error after `maxAttempts` failures.
-
-## Strings
-
-### isValidURL(url)
-
-Tests whether the input parses as a valid URL via the `URL` constructor.
-
-- **Parameters:**
-  - `url` (String): Candidate URL.
-- **Returns:** `Boolean`.
-
-### splitTrim(string, separator = null)
-
-Splits a string, trims each piece, and drops empty results. Default separator is `\r?\n` (any newline).
-
-- **Parameters:**
-  - `string` (String): Source text.
-  - `separator` (String|RegExp|null): Custom delimiter; `null` falls back to newlines.
-- **Returns:** Array of non-empty trimmed strings.
-
-### pascalCase(string)
-
-Converts arbitrary text to `PascalCase` (uses lodash internally).
-
-- **Parameters:**
-  - `string` (String): Input text.
-- **Returns:** PascalCase string.
-
-### titleCase(string, separator = " ")
-
-Capitalizes the first letter of each word delimited by `separator`. Other characters are preserved as-is.
-
-- **Parameters:**
-  - `string` (String): Input text.
-  - `separator` (String): Word boundary. Defaults to a single space.
-- **Returns:** Title-cased string.
-
-### limitString(string, limit = 35, omission = "...")
-
-Truncates a string if it exceeds `limit` characters and appends `omission`. Strings shorter than the limit are returned unchanged.
-
-- **Parameters:**
-  - `string` (String): Input text.
-  - `limit` (Number): Maximum length of the result (including `omission`).
-  - `omission` (String): Suffix used when truncation happens.
-- **Returns:** Possibly truncated string.
-
-### safeString(string)
-
-Strips HTML tags via the `xss` library and additionally removes the body of dangerous block tags (`<script>`, `<style>`, `<iframe>`, `<object>`, `<embed>`, `<form>`) so leftover CSS/markup cannot leak as text. CSS attribute sanitization is also disabled (no `<style>` attribute support). Intended for rendering untrusted text safely; not a substitute for a full HTML sanitizer like DOMPurify.
-
-- **Parameters:**
-  - `string` (String): Untrusted text.
-- **Returns:** Sanitized string with no allowed tags.
-
-### shuffleString(string)
-
-Randomly reorders the characters in a string using lodash's `shuffle` (Fisher-Yates).
-
-- **Parameters:**
-  - `string` (String): Source string.
-- **Returns:** Shuffled string of the same length.
-
-## Random (non-cryptographic, Math.random)
-
-### randomBoolean()
-
-Returns `true` or `false` with roughly equal probability.
-
-- **Returns:** `Boolean`.
-
-### randomString(length, useNumbers = true, useUppercase = false)
-
-Generates a non-secure random string from configurable character sets.
-
-- **Parameters:**
-  - `length` (Number): Output length.
-  - `useNumbers` (Boolean): Include digits `0-9`.
-  - `useUppercase` (Boolean): Include uppercase letters.
-- **Returns:** Random string.
-
-### randomHex(length)
-
-Generates a non-secure random hexadecimal string.
-
-- **Parameters:**
-  - `length` (Number): Output length.
-- **Returns:** Hex string of the requested length.
-
-### randomInteger(min, max)
-
-Returns an integer in `[min, max)`. If called with a single argument it is treated as `max` with `min = 0` (e.g., `randomInteger(10)` returns `0..9`).
-
-- **Parameters:**
-  - `min` (Number): Inclusive lower bound, or `max` when called with one argument.
-  - `max` (Number): Exclusive upper bound.
-- **Returns:** Integer in `[min, max)`.
-- **Throws:** When inputs are not numbers, or when `max <= min`.
-
-### randomUuid(useDashes = true)
-
-Generates a non-secure UUID v4-shaped string. Sufficient for client-side keys; do not use for security tokens.
-
-- **Parameters:**
-  - `useDashes` (Boolean): When `false`, dashes are stripped.
-- **Returns:** UUID string.
-
-### randomWeighted(object)
-
-Picks a key from `object` with probability proportional to its numeric value.
-
-- **Parameters:**
-  - `object` (Object): Map of key → positive weight.
-- **Returns:** Selected key.
-
-### randomElement(object)
-
-Picks a 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)
-
-### mulberry32(seed)
-
-Returns a deterministic PRNG (Mulberry32) seeded by a 32-bit integer or by a string (hashed internally to 32 bits). Each call to the returned function produces a `[0, 1)` float. Very fast, but only 32 bits of state — not for cryptographic use.
-
-- **Parameters:**
-  - `seed` (Number|String): Seed value.
-- **Returns:** Function that returns a `Number` in `[0, 1)` per call.
-
-### seedHex(seed, length)
-
-Builds a deterministic hex string of the requested length from a seed via `mulberry32`. Same seed always yields the same output. Useful for short, repeatable identifiers (e.g., proxy session stickiness).
-
-- **Parameters:**
-  - `seed` (Any): Seed value (coerced to string).
-  - `length` (Number): Output length in hex characters. Required.
-- **Returns:** Hex string.
-
-## Predicates
-
-### checkEmpty(value)
-
-Like lodash's `isEmpty` but additionally treats `0` (numeric zero) as empty.
-
-- **Parameters:**
-  - `value` (Any): Value to test.
-- **Returns:** `Boolean`.
-
-### isInt32(value)
-
-Tests whether `value` is an integer within the signed 32-bit range.
-
-- **Parameters:**
-  - `value` (Any): Value to test.
-- **Returns:** `Boolean`.
-
-### isPositiveNumber(value)
-
-Tests whether `value` is a finite positive number (excludes `NaN`, `Infinity`, non-numbers, `0`, and negatives).
-
-- **Parameters:**
-  - `value` (Any): Value to test.
-- **Returns:** `Boolean`.
-
-## Objects
-
-### coerceObjectNumbers(object)
-
-Walks an object's own enumerable keys and converts string values that match a numeric pattern (e.g., `"1.5"`, `"-3"`, `"1e3"`) to `Number`. Non-string values and non-strict numeric strings (e.g., `"12abc"`, `"1,000"`) are left untouched. Mutates the input.
-
-- **Parameters:**
-  - `object` (Object): Object to coerce in place.
-- **Returns:** The same `object`.
-
-### coerceObjectIntegers(object)
-
-Same as `coerceObjectNumbers` but only converts whole integer strings via `parseInt` (e.g., `"002"` → `2`, `"-7"` → `-7`). Mutates the input.
-
-- **Parameters:**
-  - `object` (Object): Object to coerce in place.
-- **Returns:** The same `object`.
-
-### findNodeByKey(key, node, pair = null)
-
-Depth-first search through a nested object for the first node that owns `key`. If `pair` is provided, the node's value at `key` must equal `pair` (strict equality, supports falsy values like `false` / `0` / `""`).
-
-- **Parameters:**
-  - `key` (String): Property name to find.
-  - `node` (Object): Tree to search.
-  - `pair` (Any): Optional value constraint. `null` means "match any value".
-- **Returns:** The matching node, or `null` if not found.
-
-### waitForProperty(object, property, timeout = 5000, interval = 100)
-
-Polls `object` until it owns `property`, then resolves with the property's value. Rejects after `timeout` milliseconds.
-
-- **Parameters:**
-  - `object` (Object): Object to watch.
-  - `property` (String): Property name to wait for.
-  - `timeout` (Number): Maximum wait time in milliseconds.
-  - `interval` (Number): Poll interval in milliseconds.
-- **Returns:** `Promise` resolving to the property's value.
-- **Throws:** When the property does not appear within `timeout`.
-
-### shuffleObject(object)
-
-Returns a new object whose entries are in random order (the underlying iteration order is the only thing being shuffled).
-
-- **Parameters:**
-  - `object` (Object): Source object.
-- **Returns:** New object with the same keys/values in shuffled order.
-
-### objectStringify(object)
-
-Recursively walks an object and converts every leaf value to `String(value)`. Nested objects and arrays are descended into; mutates the input.
-
-- **Parameters:**
-  - `object` (Object): Object to mutate.
-- **Returns:** The same `object`.
-
-## Cookies
-
-### cookiesFromResponse(response, decodeValues = false)
-
-Parses the `Set-Cookie` headers off a response-like object (compatible with Node `http`, fetch responses, or anything with `headers["set-cookie"]`) and returns a flat `{name: value}` map via `set-cookie-parser`.
-
-- **Parameters:**
-  - `response` (Object): Response-like with parsed headers.
-  - `decodeValues` (Boolean): Whether to URL-decode cookie values.
-- **Returns:** Map of cookie name → value.
-
-### cookiesToHeader(cookies)
-
-Serializes a `{name: value}` map into a `Cookie:` header string (`name=value` pairs joined with `"; "`). Null/undefined values are dropped.
-
-- **Parameters:**
-  - `cookies` (Object): Map of cookie name → value.
-- **Returns:** Cookie header string, or `""` for empty/missing input.
-
-### cookiesFromHeader(header)
-
-Parses a single `Cookie:` header string into a `{name: value}` map. Pieces without `=` are skipped; multiple `=` inside a value are preserved.
-
-- **Parameters:**
-  - `header` (String): Cookie header value.
-- **Returns:** Map of cookie name → value. Empty input returns `{}`.
-
-## HTTP Helpers
-
-### isTransientHttpCode(httpCode)
-
-Flags HTTP status codes that are typically transient or worth retrying (missing/`NaN`, `100`, `402`, `407`, `460-469`, anything `≥ 500`).
-
-- **Parameters:**
-  - `httpCode` (Number|null|undefined): Status code to inspect.
-- **Returns:** `Boolean`.
-
-### getResponseError(error, limit = 200)
-
-Extracts a short error description from an HTTP error-like object. Prefers `error.response.status|error.response.data`, then `error.response.data`, then `error.message`. Truncates the result to `limit` characters via `limitString`.
-
-- **Parameters:**
-  - `error` (Error): Error from an HTTP client.
-  - `limit` (Number): Maximum length of the returned string.
-- **Returns:** Trimmed error description.