melperjs 16.1.0 → 17.1.0

package/dist/node.mjs

@@ -0,0 +1,142 @@
+import { CONSTANTS, checkEmpty } from "./general.mjs";
+import fs, { promises } from "fs";
+import path from "path";
+import crypto from "crypto";
+import { networkInterfaces } from "os";
+import { exec, execFileSync } from "child_process";
+import { promisify } from "util";
+import bcrypt from "bcryptjs";
+//#region src/node.js
+const execAsync = promisify(exec);
+function secureRandomBoolean() {
+	return secureRandomInteger(2) === 1;
+}
+function secureRandomString(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[secureRandomInteger(0, characters.length)];
+	return result;
+}
+function secureRandomHex(length) {
+	return crypto.randomBytes(Math.ceil(length / 2)).toString("hex").slice(0, length);
+}
+function secureRandomInteger(min, max = void 0) {
+	return crypto.randomInt(min, max);
+}
+function secureRandomUuid(useDashes = true) {
+	const uuid = crypto.randomUUID();
+	return useDashes ? uuid : uuid.replaceAll("-", "");
+}
+function secureRandomWeighted(object) {
+	if (checkEmpty(object)) return void 0;
+	const elements = Object.keys(object);
+	const weights = Object.values(object);
+	const randomNum = secureRandomInteger(0, weights.reduce((sum, weight) => sum + weight, 0));
+	let weightSum = 0;
+	for (let i = 0; i < elements.length; i++) {
+		weightSum += weights[i];
+		if (randomNum < weightSum) return elements[i];
+	}
+}
+function secureRandomElement(object) {
+	if (checkEmpty(object)) return void 0;
+	const values = Array.isArray(object) ? object : Object.values(object);
+	if (values.length === 0) return void 0;
+	return values[secureRandomInteger(0, values.length)];
+}
+function uuidFromSeed(seed, useDashes = true) {
+	const hash = crypto.createHash("md5").update(seed).digest();
+	hash[6] = hash[6] & 15 | 48;
+	hash[8] = hash[8] & 63 | 128;
+	const hex = hash.toString("hex");
+	if (!useDashes) return hex;
+	return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+function hash(algorithm, data) {
+	return crypto.createHash(algorithm).update(data).digest("hex");
+}
+function md5(data) {
+	return hash("md5", data);
+}
+function sha256(data) {
+	return hash("sha256", data);
+}
+function base64Encode(data) {
+	return Buffer.from(data).toString("base64");
+}
+function base64Decode(data, encoding = "utf8") {
+	return Buffer.from(data, "base64").toString(encoding);
+}
+function bcryptHash(plainText, { key = "", strength = 12, preHash = true } = {}) {
+	let input = plainText + key;
+	if (preHash) input = sha256(input);
+	return bcrypt.hashSync(input, strength);
+}
+function bcryptVerify(plainText, hash, { key = "", preHash = true } = {}) {
+	let input = plainText + key;
+	if (preHash) input = sha256(input);
+	return bcrypt.compareSync(input, hash);
+}
+async function readJsonFile(filePath, defaultValue = {}) {
+	try {
+		const data = await promises.readFile(filePath, "utf8");
+		return JSON.parse(data);
+	} catch {
+		return defaultValue;
+	}
+}
+function readJsonFileSync(filePath, defaultValue = {}) {
+	try {
+		const data = fs.readFileSync(filePath, "utf8");
+		return JSON.parse(data);
+	} catch {
+		return defaultValue;
+	}
+}
+function writeJsonFile(filePath, data) {
+	const jsonData = JSON.stringify(data);
+	return promises.writeFile(filePath, jsonData, "utf8");
+}
+function writeJsonFileSync(filePath, data) {
+	const jsonData = JSON.stringify(data);
+	return fs.writeFileSync(filePath, jsonData, "utf8");
+}
+async function clearDirectory(directoryPath, keepDir = true) {
+	await promises.rm(directoryPath, {
+		recursive: true,
+		force: true
+	});
+	if (keepDir) await promises.mkdir(directoryPath, { recursive: true });
+}
+function createNumberedDirs(mainDirectory, start = 0, end = 9) {
+	fs.mkdirSync(mainDirectory, { recursive: true });
+	for (let i = start; i <= end; i++) fs.mkdirSync(path.join(mainDirectory, `${i}`), { recursive: true });
+}
+async function executeCommand(command) {
+	const { stdout } = await execAsync(command);
+	return stdout.trim();
+}
+function hostIp() {
+	for (const list of Object.values(networkInterfaces())) for (const alias of list) if (alias.family === "IPv4" && alias.address !== "127.0.0.1" && !alias.address.startsWith("192.168.") && !alias.internal) return alias.address;
+	return "127.0.0.1";
+}
+function gitVersion() {
+	try {
+		const raw = execFileSync("git", [
+			"show",
+			"-s",
+			"--format=%ct",
+			"HEAD"
+		], { encoding: "utf8" }).trim();
+		const timestamp = parseInt(raw, 10);
+		if (isNaN(timestamp)) return "1.0";
+		const iso = (/* @__PURE__ */ new Date(timestamp * 1e3)).toISOString();
+		return `${iso.slice(2, 4)}${iso.slice(5, 7)}${iso.slice(8, 10)}.${iso.slice(11, 13)}${iso.slice(14, 16)}`;
+	} catch {
+		return "1.0";
+	}
+}
+//#endregion
+export { base64Decode, base64Encode, bcryptHash, bcryptVerify, clearDirectory, createNumberedDirs, executeCommand, gitVersion, hash, hostIp, md5, readJsonFile, readJsonFileSync, secureRandomBoolean, secureRandomElement, secureRandomHex, secureRandomInteger, secureRandomString, secureRandomUuid, secureRandomWeighted, sha256, uuidFromSeed, writeJsonFile, writeJsonFileSync };

package/docs/{docs.md → README.md}

@@ -1,10 +1,9 @@
 # Documentation
 
-`melperjs` is a small utility library split into two entry points:
+`melperjs` is a lightweight 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`.
+- **Core module** (`melperjs`) — browser-safe helpers. Safe to import from any JavaScript environment.
+- **Node module** (`melperjs/node`) — Node.js-specific helpers built on `crypto`, `fs`, `child_process`, `os`, and more.
   Importing this in a browser will fail.
 
 ## Usage
@@ -23,5 +22,5 @@ Both forms are supported via dual ESM/CJS builds.
 
 ## Sections
 
-- [General Functions](index.md) — browser-safe helpers (`melperjs`)
+- [General Functions](general.md) — browser-safe helpers (`melperjs`)
 - [Node.js Functions](./node.md) — Node-only helpers (`melperjs/node`)

package/docs/{index.md → general.md}

@@ -87,7 +87,7 @@ Calls `task` up to `maxAttempts` times, returning the first successful result. O
 - **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.
+  - `onError` (Function): Called as `(error, attempt)` 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`.
@@ -288,17 +288,17 @@ Depth-first search through a nested object for the first node that owns `key`. I
   - `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)
+### waitForProperty(object, property, timeoutMs, 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.
+  - `timeoutMs` (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`.
+- **Throws:** When the property does not appear within `timeoutMs`.
 
 ### shuffleObject(object)
 
@@ -361,3 +361,51 @@ Extracts a short error description from an HTTP error-like object. Prefers `erro
   - `error` (Error): Error from an HTTP client.
   - `limit` (Number): Maximum length of the returned string.
 - **Returns:** Trimmed error description.
+
+## 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.

package/docs/node.md

@@ -7,7 +7,7 @@ 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](index.md).
+see the `random*` family in [General Functions](general.md).
 
 ### secureRandomBoolean()
 
@@ -145,57 +145,6 @@ Verifies that `plainText` (with the same `key`) matches a previously generated b
     - `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 = {})

package/package.json

@@ -1,5 +1,6 @@
 {
   "name": "melperjs",
+  "version": "17.1.0",
   "description": "A compact JavaScript utility library for strings, objects, tokens, hashing, cookies, proxies, file I/O, shell, and more.",
   "keywords": [
     "melperjs",
@@ -24,37 +25,40 @@
     "file-system",
     "shell"
   ],
+  "homepage": "https://github.com/mahelbir/melperjs#readme",
+  "bugs": {
+    "url": "https://github.com/mahelbir/melperjs/issues"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/mahelbir/melperjs.git"
   },
-  "author": "Mahmuthan Elbir",
   "license": "MIT",
+  "author": "Mahmuthan Elbir",
   "type": "module",
-  "files": [
-    "lib/**/*",
-    "docs/**/*"
-  ],
-  "private": false,
-  "publishConfig": {
-    "access": "public"
+  "engines": {
+    "node": ">=18.0.0"
   },
+  "sideEffects": false,
   "exports": {
     ".": {
-      "import": "./lib/esm/index.mjs",
-      "require": "./lib/cjs/index.cjs"
+      "import": "./dist/general.mjs",
+      "require": "./dist/general.cjs"
     },
     "./node": {
-      "import": "./lib/esm/node.mjs",
-      "require": "./lib/cjs/node.cjs"
+      "import": "./dist/node.mjs",
+      "require": "./dist/node.cjs"
     }
   },
+  "files": [
+    "dist/**/*",
+    "docs/**/*"
+  ],
   "scripts": {
-    "build:esm": "npx cross-env BABEL_ENV=esm babel ./src --out-dir ./lib/esm --out-file-extension .mjs",
-    "build:cjs": "npx cross-env BABEL_ENV=cjs babel ./src --out-dir ./lib/cjs --out-file-extension .cjs",
-    "build": "npm run build:esm && npm run build:cjs",
-    "test": "node --test 'tests/**/*.test.js'",
-    "prepublishOnly": "npm run build && npm test"
+    "build": "tsdown",
+    "test": "node --test",
+    "prepublishOnly": "npm run build && npm test",
+    "relock": "rm -rf node_modules package-lock.json && NODE_ENV= npm install --include=dev --include=optional"
   },
   "dependencies": {
     "bcryptjs": "^3.0.3",
@@ -63,12 +67,9 @@
     "xss": "^1.0.15"
   },
   "devDependencies": {
-    "@babel/cli": "^7.28.6",
-    "@babel/core": "^7.29.0",
-    "@babel/preset-env": "^7.29.5",
-    "babel-plugin-replace-import-extension": "^1.1.5",
-    "babel-plugin-transform-import-meta": "^2.3.3",
-    "cross-env": "^10.1.0"
+    "tsdown": "^0.22.0"
   },
-  "version": "16.1.0"
+  "publishConfig": {
+    "access": "public"
+  }
 }