melperjs 16.0.0 → 17.0.0

package/lib/cjs/index.cjs

@@ -20,10 +20,13 @@ exports.isTransientHttpCode = isTransientHttpCode;
 exports.isValidURL = isValidURL;
 exports.limitString = limitString;
 exports.mulberry32 = mulberry32;
+exports.normalizeProxy = normalizeProxy;
 exports.objectStringify = objectStringify;
+exports.parseProxy = parseProxy;
 exports.pascalCase = pascalCase;
 exports.promiseSilent = promiseSilent;
 exports.promiseTimeout = promiseTimeout;
+exports.proxyValue = proxyValue;
 exports.randomBoolean = randomBoolean;
 exports.randomElement = randomElement;
 exports.randomHex = randomHex;
@@ -89,33 +92,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(error, attempt);
       if (attempt >= maxAttempts) throw error;
       if (delayMs > 0) await sleepMs(delayMs * backoffFactor ** (attempt - 1));
     }
@@ -146,7 +149,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)) {
@@ -178,7 +181,7 @@ function findNodeByKey(key, node, pair = null) {
   }
   return null;
 }
-function waitForProperty(object, property, timeout = 5000, interval = 100) {
+function waitForProperty(object, property, timeout, interval = 100) {
   return new Promise((resolve, reject) => {
     if (Object.hasOwn(object, property)) {
       resolve(object[property]);
@@ -191,7 +194,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 +249,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 +270,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 +284,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 +314,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 "";
@@ -348,4 +352,123 @@ function getResponseError(error, limit = 200) {
     response = error.response.data;
   }
   return limitString(response || error.message, limit).trim();
+}
+function normalizeProxy(proxy, protocol = "http") {
+  proxy = proxy?.trim();
+  if (!proxy) return null;
+  const schemeMatch = proxy.match(/^([a-z][a-z0-9+.-]*):\/\/(.+)$/i);
+  if (schemeMatch) {
+    protocol = schemeMatch[1];
+    proxy = schemeMatch[2];
+  }
+  let auth = "";
+  let body = proxy;
+  const atIdx = body.lastIndexOf("@");
+  if (atIdx !== -1) {
+    auth = body.slice(0, atIdx) + "@";
+    body = body.slice(atIdx + 1);
+  }
+  if (!auth) {
+    /* Note: when host is single-token (e.g. "localhost") AND password is all-digit port-shaped,
+     the heuristic stays ambiguous; prefer `user:pass@host:port` for those cases. */
+    const parts = body.split(":");
+    const isPort = s => /^\d+$/.test(s) && +s >= 1 && +s <= 65535;
+    const isHost = s => s.includes(".") || /[a-z]/i.test(s);
+    if (parts.length === 4) {
+      if (isPort(parts[3]) && !isPort(parts[1])) {
+        // user:pass:host:port
+        auth = `${parts[0]}:${parts[1]}@`;
+        body = `${parts[2]}:${parts[3]}`;
+      } else if (isPort(parts[1]) && !isPort(parts[3])) {
+        // host:port:user:pass
+        auth = `${parts[2]}:${parts[3]}@`;
+        body = `${parts[0]}:${parts[1]}`;
+      } else if (isHost(parts[2]) && !isHost(parts[0])) {
+        // user:pass:host:port (ambiguous; host detected at parts[2])
+        auth = `${parts[0]}:${parts[1]}@`;
+        body = `${parts[2]}:${parts[3]}`;
+      } else {
+        // host:port:user:pass (ambiguous fallback)
+        auth = `${parts[2]}:${parts[3]}@`;
+        body = `${parts[0]}:${parts[1]}`;
+      }
+    } else if (parts.length === 5) {
+      if (isPort(parts[3]) && isPort(parts[4]) && !isPort(parts[1])) {
+        // user:pass:host:portStart:portEnd
+        auth = `${parts[0]}:${parts[1]}@`;
+        body = `${parts[2]}:${parts[3]}:${parts[4]}`;
+      } else if (isPort(parts[1]) && isPort(parts[2]) && !isPort(parts[3])) {
+        // host:portStart:portEnd:user:pass
+        auth = `${parts[3]}:${parts[4]}@`;
+        body = `${parts[0]}:${parts[1]}:${parts[2]}`;
+      } else if (isHost(parts[2]) && !isHost(parts[0])) {
+        // user:pass:host:portStart:portEnd (ambiguous; host detected at parts[2])
+        auth = `${parts[0]}:${parts[1]}@`;
+        body = `${parts[2]}:${parts[3]}:${parts[4]}`;
+      } else {
+        // host:portStart:portEnd:user:pass (ambiguous fallback)
+        auth = `${parts[3]}:${parts[4]}@`;
+        body = `${parts[0]}:${parts[1]}:${parts[2]}`;
+      }
+    }
+  }
+  const parts = body.split(":");
+  if (parts.length === 3) {
+    const start = Number(parts[1]);
+    const end = Number(parts[2]);
+    if (Number.isInteger(start) && Number.isInteger(end) && start >= 0 && start <= end) {
+      body = `${parts[0]}:${randomInteger(start, end + 1)}`;
+    }
+  }
+  return `${protocol}://${auth}${body}`;
+}
+function parseProxy(proxy, protocol = "http") {
+  const normalized = normalizeProxy(proxy, protocol);
+  if (!normalized) return null;
+  const [scheme, rest] = normalized.split("://");
+  const atIdx = rest.lastIndexOf("@");
+  const authPart = atIdx === -1 ? null : rest.slice(0, atIdx);
+  const hostPart = atIdx === -1 ? rest : rest.slice(atIdx + 1);
+  const [host, port] = hostPart.split(":");
+  const result = {
+    protocol: scheme,
+    host,
+    port: parseInt(port, 10)
+  };
+  if (authPart !== null) {
+    const colonIdx = authPart.indexOf(":");
+    const [username, password] = colonIdx === -1 ? [authPart, ""] : [authPart.slice(0, colonIdx), authPart.slice(colonIdx + 1)];
+    result.auth = {
+      username,
+      password
+    };
+  }
+  return result;
+}
+function proxyValue(rawProxy, replacements = {}) {
+  const list = splitTrim(rawProxy || "");
+  if (list.length === 0) return null;
+  const picked = list[randomInteger(0, list.length)];
+  let result = normalizeProxy(picked);
+  if (!result) return null;
+  if (result.includes("{")) {
+    const {
+      SESSION,
+      ...rest
+    } = replacements;
+    let sessionValue;
+    if (SESSION === undefined) {
+      sessionValue = randomHex(8);
+    } else if (typeof SESSION === "function") {
+      sessionValue = SESSION();
+    } else {
+      sessionValue = seedHex(String(SESSION), 8);
+    }
+    result = result.replace("{SESSION}", sessionValue);
+    for (const [key, value] of Object.entries(rest)) {
+      const v = typeof value === "function" ? value() : String(value);
+      result = result.replace(`{${key}}`, v);
+    }
+  }
+  return result;
 }

package/lib/cjs/node.cjs

@@ -14,9 +14,6 @@ exports.gitVersion = gitVersion;
 exports.hash = hash;
 exports.hostIp = hostIp;
 exports.md5 = md5;
-exports.normalizeProxy = normalizeProxy;
-exports.parseProxy = parseProxy;
-exports.proxyValue = proxyValue;
 exports.readJsonFile = readJsonFile;
 exports.readJsonFileSync = readJsonFileSync;
 exports.secureRandomBoolean = secureRandomBoolean;
@@ -42,7 +39,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 +47,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 +62,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 +76,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();
@@ -127,106 +125,6 @@ function bcryptVerify(plainText, hash, {
   }
   return _bcryptjs.default.compareSync(input, hash);
 }
-function normalizeProxy(proxy, protocol = "http") {
-  proxy = proxy?.trim();
-  if (!proxy) return null;
-  const schemeMatch = proxy.match(/^([a-z][a-z0-9+.-]*):\/\/(.+)$/i);
-  if (schemeMatch) {
-    protocol = schemeMatch[1];
-    proxy = schemeMatch[2];
-  }
-  let auth = "";
-  let body = proxy;
-  const atIdx = body.lastIndexOf("@");
-  if (atIdx !== -1) {
-    auth = body.slice(0, atIdx) + "@";
-    body = body.slice(atIdx + 1);
-  }
-  if (!auth) {
-    // Note: when the password itself is all-digit and port-shaped (e.g. "admin:1234:host:port"),
-    // the heuristic cannot distinguish auth-first from host-first ordering and may pick the wrong branch.
-    const parts = body.split(":");
-    const isPort = s => /^\d+$/.test(s) && +s >= 1 && +s <= 65535;
-    if (parts.length === 4) {
-      if (isPort(parts[3]) && !isPort(parts[1])) {
-        // user:pass:host:port
-        auth = `${parts[0]}:${parts[1]}@`;
-        body = `${parts[2]}:${parts[3]}`;
-      } else {
-        // host:port:user:pass (default)
-        auth = `${parts[2]}:${parts[3]}@`;
-        body = `${parts[0]}:${parts[1]}`;
-      }
-    } else if (parts.length === 5) {
-      if (isPort(parts[3]) && isPort(parts[4]) && !isPort(parts[1])) {
-        // user:pass:host:portStart:portEnd
-        auth = `${parts[0]}:${parts[1]}@`;
-        body = `${parts[2]}:${parts[3]}:${parts[4]}`;
-      } else {
-        // host:portStart:portEnd:user:pass (default)
-        auth = `${parts[3]}:${parts[4]}@`;
-        body = `${parts[0]}:${parts[1]}:${parts[2]}`;
-      }
-    }
-  }
-  const parts = body.split(":");
-  if (parts.length === 3) {
-    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)}`;
-    }
-  }
-  return `${protocol}://${auth}${body}`;
-}
-function parseProxy(proxy, protocol = "http") {
-  const normalized = normalizeProxy(proxy, protocol);
-  if (!normalized) return null;
-  const [scheme, rest] = normalized.split("://");
-  const atIdx = rest.lastIndexOf("@");
-  const authPart = atIdx === -1 ? null : rest.slice(0, atIdx);
-  const hostPart = atIdx === -1 ? rest : rest.slice(atIdx + 1);
-  const [host, port] = hostPart.split(":");
-  const result = {
-    protocol: scheme,
-    host,
-    port: parseInt(port, 10)
-  };
-  if (authPart !== null) {
-    const colonIdx = authPart.indexOf(":");
-    const [username, password] = colonIdx === -1 ? [authPart, ""] : [authPart.slice(0, colonIdx), authPart.slice(colonIdx + 1)];
-    result.auth = {
-      username,
-      password
-    };
-  }
-  return result;
-}
-function proxyValue(rawProxy, replacements = {}) {
-  const list = (0, _index.splitTrim)(rawProxy || "");
-  if (list.length === 0) return null;
-  const picked = list[(0, _index.randomInteger)(0, list.length)];
-  const {
-    SESSION,
-    ...rest
-  } = replacements;
-  let sessionValue;
-  if (SESSION === undefined) {
-    sessionValue = (0, _index.randomHex)(8);
-  } else if (typeof SESSION === "function") {
-    sessionValue = SESSION();
-  } else {
-    sessionValue = (0, _index.seedHex)(String(SESSION), 8);
-  }
-  let result = normalizeProxy(picked);
-  if (!result) return null;
-  result = result.replace("{SESSION}", sessionValue);
-  for (const [key, value] of Object.entries(rest)) {
-    const v = typeof value === "function" ? value() : String(value);
-    result = result.replace(`{${key}}`, v);
-  }
-  return result;
-}
 async function readJsonFile(filePath, defaultValue = {}) {
   try {
     const data = await _fs.promises.readFile(filePath, 'utf8');

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(error, attempt);
       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)) {
@@ -133,7 +133,7 @@ export function findNodeByKey(key, node, pair = null) {
   }
   return null;
 }
-export function waitForProperty(object, property, timeout = 5000, interval = 100) {
+export function waitForProperty(object, property, timeout, interval = 100) {
   return new Promise((resolve, reject) => {
     if (Object.hasOwn(object, property)) {
       resolve(object[property]);
@@ -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 "";
@@ -303,4 +304,123 @@ export function getResponseError(error, limit = 200) {
     response = error.response.data;
   }
   return limitString(response || error.message, limit).trim();
+}
+export function normalizeProxy(proxy, protocol = "http") {
+  proxy = proxy?.trim();
+  if (!proxy) return null;
+  const schemeMatch = proxy.match(/^([a-z][a-z0-9+.-]*):\/\/(.+)$/i);
+  if (schemeMatch) {
+    protocol = schemeMatch[1];
+    proxy = schemeMatch[2];
+  }
+  let auth = "";
+  let body = proxy;
+  const atIdx = body.lastIndexOf("@");
+  if (atIdx !== -1) {
+    auth = body.slice(0, atIdx) + "@";
+    body = body.slice(atIdx + 1);
+  }
+  if (!auth) {
+    /* Note: when host is single-token (e.g. "localhost") AND password is all-digit port-shaped,
+     the heuristic stays ambiguous; prefer `user:pass@host:port` for those cases. */
+    const parts = body.split(":");
+    const isPort = s => /^\d+$/.test(s) && +s >= 1 && +s <= 65535;
+    const isHost = s => s.includes(".") || /[a-z]/i.test(s);
+    if (parts.length === 4) {
+      if (isPort(parts[3]) && !isPort(parts[1])) {
+        // user:pass:host:port
+        auth = `${parts[0]}:${parts[1]}@`;
+        body = `${parts[2]}:${parts[3]}`;
+      } else if (isPort(parts[1]) && !isPort(parts[3])) {
+        // host:port:user:pass
+        auth = `${parts[2]}:${parts[3]}@`;
+        body = `${parts[0]}:${parts[1]}`;
+      } else if (isHost(parts[2]) && !isHost(parts[0])) {
+        // user:pass:host:port (ambiguous; host detected at parts[2])
+        auth = `${parts[0]}:${parts[1]}@`;
+        body = `${parts[2]}:${parts[3]}`;
+      } else {
+        // host:port:user:pass (ambiguous fallback)
+        auth = `${parts[2]}:${parts[3]}@`;
+        body = `${parts[0]}:${parts[1]}`;
+      }
+    } else if (parts.length === 5) {
+      if (isPort(parts[3]) && isPort(parts[4]) && !isPort(parts[1])) {
+        // user:pass:host:portStart:portEnd
+        auth = `${parts[0]}:${parts[1]}@`;
+        body = `${parts[2]}:${parts[3]}:${parts[4]}`;
+      } else if (isPort(parts[1]) && isPort(parts[2]) && !isPort(parts[3])) {
+        // host:portStart:portEnd:user:pass
+        auth = `${parts[3]}:${parts[4]}@`;
+        body = `${parts[0]}:${parts[1]}:${parts[2]}`;
+      } else if (isHost(parts[2]) && !isHost(parts[0])) {
+        // user:pass:host:portStart:portEnd (ambiguous; host detected at parts[2])
+        auth = `${parts[0]}:${parts[1]}@`;
+        body = `${parts[2]}:${parts[3]}:${parts[4]}`;
+      } else {
+        // host:portStart:portEnd:user:pass (ambiguous fallback)
+        auth = `${parts[3]}:${parts[4]}@`;
+        body = `${parts[0]}:${parts[1]}:${parts[2]}`;
+      }
+    }
+  }
+  const parts = body.split(":");
+  if (parts.length === 3) {
+    const start = Number(parts[1]);
+    const end = Number(parts[2]);
+    if (Number.isInteger(start) && Number.isInteger(end) && start >= 0 && start <= end) {
+      body = `${parts[0]}:${randomInteger(start, end + 1)}`;
+    }
+  }
+  return `${protocol}://${auth}${body}`;
+}
+export function parseProxy(proxy, protocol = "http") {
+  const normalized = normalizeProxy(proxy, protocol);
+  if (!normalized) return null;
+  const [scheme, rest] = normalized.split("://");
+  const atIdx = rest.lastIndexOf("@");
+  const authPart = atIdx === -1 ? null : rest.slice(0, atIdx);
+  const hostPart = atIdx === -1 ? rest : rest.slice(atIdx + 1);
+  const [host, port] = hostPart.split(":");
+  const result = {
+    protocol: scheme,
+    host,
+    port: parseInt(port, 10)
+  };
+  if (authPart !== null) {
+    const colonIdx = authPart.indexOf(":");
+    const [username, password] = colonIdx === -1 ? [authPart, ""] : [authPart.slice(0, colonIdx), authPart.slice(colonIdx + 1)];
+    result.auth = {
+      username,
+      password
+    };
+  }
+  return result;
+}
+export function proxyValue(rawProxy, replacements = {}) {
+  const list = splitTrim(rawProxy || "");
+  if (list.length === 0) return null;
+  const picked = list[randomInteger(0, list.length)];
+  let result = normalizeProxy(picked);
+  if (!result) return null;
+  if (result.includes("{")) {
+    const {
+      SESSION,
+      ...rest
+    } = replacements;
+    let sessionValue;
+    if (SESSION === undefined) {
+      sessionValue = randomHex(8);
+    } else if (typeof SESSION === "function") {
+      sessionValue = SESSION();
+    } else {
+      sessionValue = seedHex(String(SESSION), 8);
+    }
+    result = result.replace("{SESSION}", sessionValue);
+    for (const [key, value] of Object.entries(rest)) {
+      const v = typeof value === "function" ? value() : String(value);
+      result = result.replace(`{${key}}`, v);
+    }
+  }
+  return result;
 }