@socketsecurity/lib 6.0.2 → 6.0.4

package/dist/promises/iterate.js

@@ -1,111 +1,247 @@
 "use strict";
-/* Socket Lib - Built with esbuild */
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var iterate_exports = {};
-__export(iterate_exports, {
-  pEach: () => pEach,
-  pEachChunk: () => pEachChunk,
-  pFilter: () => pFilter,
-  pFilterChunk: () => pFilterChunk
-});
-module.exports = __toCommonJS(iterate_exports);
-var import_chunk = require("../arrays/chunk");
-var import_promise = require("../primordials/promise");
-var import_options = require("./options");
-var import_retry = require("./retry");
-// @__NO_SIDE_EFFECTS__
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_promises_options = require('./options.js');
+const require_promises_retry = require('./retry.js');
+const require_primordials_promise = require('../primordials/promise.js');
+const require_arrays_chunk = require('../arrays/chunk.js');
+
+//#region src/promises/iterate.ts
+/**
+* @file Concurrency-controlled async iteration helpers: `pEach`, `pEachChunk`,
+*   `pFilter`, `pFilterChunk`. All four use `pRetry` internally so each item's
+*   callback can be retried independently without affecting siblings. The chunk
+*   vs. concurrency distinction:
+*
+*   - `pEach` / `pFilter` use a **concurrency limit**: split the input into
+*     chunks of size `concurrency`, process each chunk in parallel, then move
+*     on to the next chunk.
+*   - `pEachChunk` / `pFilterChunk` operate on **pre-chunked input**: the caller
+*     decides chunk boundaries (e.g., bulk-insert batch size, pagination page
+*     size). Useful when chunk size != concurrency cap.
+*/
+/**
+* Execute an async function for each array element with concurrency control.
+*
+* Processes array items in parallel batches (chunks) with configurable
+* concurrency. Each item's callback can be retried independently on failure.
+* Similar to `Promise.all(array.map(fn))` but with controlled parallelism.
+*
+* @example
+*   // Process items serially (concurrency: 1)
+*   await pEach(urls, async url => {
+*     await fetch(url)
+*   })
+*
+* @example
+*   // Process 5 items at a time
+*   await pEach(
+*     files,
+*     async file => {
+*       await processFile(file)
+*     },
+*     5,
+*   )
+*
+* @example
+*   // With retries and cancellation
+*   const controller = new AbortController()
+*   await pEach(
+*     tasks,
+*     async task => {
+*       await executeTask(task)
+*     },
+*     {
+*       concurrency: 3,
+*       retries: 2,
+*       signal: controller.signal,
+*     },
+*   )
+*
+* @template T - The type of array elements.
+*
+* @param array - The array to iterate over.
+* @param callbackFn - Async function to execute for each item.
+* @param options - Concurrency as number, or full iteration options, or
+*   undefined.
+*
+* @returns Promise that resolves when all items are processed
+*/
+/* @__NO_SIDE_EFFECTS__ */
 async function pEach(array, callbackFn, options) {
-  const iterOpts = (0, import_options.normalizeIterationOptions)(options);
-  const { concurrency, retries, signal } = iterOpts;
-  const chunks = (0, import_chunk.arrayChunk)(array, concurrency);
-  for (const chunk of chunks) {
-    if (signal?.aborted) {
-      return;
-    }
-    await (0, import_promise.PromiseAllSettled)(
-      chunk.map(
-        (item) => (0, import_retry.pRetry)((...args) => callbackFn(args[0]), {
-          ...retries,
-          args: [item],
-          signal
-        })
-      )
-    );
-  }
+	const { concurrency, retries, signal } = /* @__PURE__ */ require_promises_options.normalizeIterationOptions(options);
+	const chunks = /* @__PURE__ */ require_arrays_chunk.arrayChunk(array, concurrency);
+	for (const chunk of chunks) {
+		if (signal?.aborted) return;
+		await require_primordials_promise.PromiseAllSettled(chunk.map((item) => /* @__PURE__ */ require_promises_retry.pRetry((...args) => callbackFn(args[0]), {
+			...retries,
+			args: [item],
+			signal
+		})));
+	}
 }
-// @__NO_SIDE_EFFECTS__
+/**
+* Process array in chunks with an async callback.
+*
+* Divides the array into fixed-size chunks and processes each chunk
+* sequentially with the callback. Useful for batch operations like bulk
+* database inserts or API calls with payload size limits.
+*
+* @example
+*   // Insert records in batches of 100
+*   await pEachChunk(
+*     records,
+*     async chunk => {
+*       await db.batchInsert(chunk)
+*     },
+*     { chunkSize: 100 },
+*   )
+*
+* @example
+*   // Upload files in batches with retries
+*   await pEachChunk(
+*     files,
+*     async batch => {
+*       await uploadBatch(batch)
+*     },
+*     {
+*       chunkSize: 50,
+*       retries: 3,
+*       baseDelayMs: 1000,
+*     },
+*   )
+*
+* @example
+*   // Process with cancellation support
+*   const controller = new AbortController()
+*   await pEachChunk(
+*     items,
+*     async chunk => {
+*       await processChunk(chunk)
+*     },
+*     {
+*       chunkSize: 25,
+*       signal: controller.signal,
+*     },
+*   )
+*
+* @template T - The type of array elements.
+*
+* @param array - The array to process in chunks.
+* @param callbackFn - Async function to execute for each chunk.
+* @param options - Chunk size and retry options.
+*
+* @returns Promise that resolves when all chunks are processed
+*/
+/* @__NO_SIDE_EFFECTS__ */
 async function pEachChunk(array, callbackFn, options) {
-  const { chunkSize = 100, ...retryOpts } = options || {};
-  const chunks = (0, import_chunk.arrayChunk)(array, chunkSize);
-  const normalizedRetryOpts = (0, import_options.normalizeRetryOptions)(retryOpts);
-  const { signal } = normalizedRetryOpts;
-  for (const chunk of chunks) {
-    if (signal?.aborted) {
-      return;
-    }
-    await (0, import_retry.pRetry)((...args) => callbackFn(args[0]), {
-      ...normalizedRetryOpts,
-      args: [chunk]
-    });
-  }
+	const { chunkSize = 100, ...retryOpts } = options || {};
+	const chunks = /* @__PURE__ */ require_arrays_chunk.arrayChunk(array, chunkSize);
+	const normalizedRetryOpts = /* @__PURE__ */ require_promises_options.normalizeRetryOptions(retryOpts);
+	const { signal } = normalizedRetryOpts;
+	for (const chunk of chunks) {
+		if (signal?.aborted) return;
+		await /* @__PURE__ */ require_promises_retry.pRetry((...args) => callbackFn(args[0]), {
+			...normalizedRetryOpts,
+			args: [chunk]
+		});
+	}
 }
-// @__NO_SIDE_EFFECTS__
+/**
+* Filter an array asynchronously with concurrency control.
+*
+* Tests each element with an async predicate function, processing items in
+* parallel batches. Returns a new array with only items that pass the test.
+* Similar to `array.filter()` but for async predicates with controlled
+* concurrency.
+*
+* @example
+*   // Filter serially
+*   const activeUsers = await pFilter(users, async user => {
+*     return await isUserActive(user.id)
+*   })
+*
+* @example
+*   // Filter with concurrency
+*   const validFiles = await pFilter(
+*     filePaths,
+*     async path => {
+*       return existsSync(path)
+*     },
+*     10,
+*   )
+*
+* @example
+*   // With retries for flaky checks
+*   const reachable = await pFilter(
+*     endpoints,
+*     async url => {
+*       const response = await fetch(url)
+*       return response.ok
+*     },
+*     {
+*       concurrency: 5,
+*       retries: 2,
+*     },
+*   )
+*
+* @template T - The type of array elements.
+*
+* @param array - The array to filter.
+* @param callbackFn - Async predicate function returning true to keep item.
+* @param options - Concurrency as number, or full iteration options, or
+*   undefined.
+*
+* @returns Promise resolving to filtered array
+*/
+/* @__NO_SIDE_EFFECTS__ */
 async function pFilter(array, callbackFn, options) {
-  const iterOpts = (0, import_options.normalizeIterationOptions)(options);
-  return (await /* @__PURE__ */ pFilterChunk(
-    (0, import_chunk.arrayChunk)(array, iterOpts.concurrency),
-    callbackFn,
-    iterOpts.retries
-  )).flat();
+	const iterOpts = /* @__PURE__ */ require_promises_options.normalizeIterationOptions(options);
+	return (await /* @__PURE__ */ pFilterChunk(/* @__PURE__ */ require_arrays_chunk.arrayChunk(array, iterOpts.concurrency), callbackFn, iterOpts.retries)).flat();
 }
-// @__NO_SIDE_EFFECTS__
+/**
+* Filter chunked arrays with an async predicate.
+*
+* Internal helper for `pFilter`. Processes pre-chunked arrays, applying the
+* predicate to each element within each chunk with retry support.
+*
+* @example
+*   const chunks = [
+*     [1, 2],
+*     [3, 4],
+*     [5, 6],
+*   ]
+*   const filtered = await pFilterChunk(chunks, async n => n % 2 === 0)
+*   // => [[2], [4], [6]]
+*
+* @template T - The type of array elements.
+*
+* @param chunks - Pre-chunked array (array of arrays)
+* @param callbackFn - Async predicate function.
+* @param options - Retry count as number, or full retry options, or undefined.
+*
+* @returns Promise resolving to array of filtered chunks
+*/
+/* @__NO_SIDE_EFFECTS__ */
 async function pFilterChunk(chunks, callbackFn, options) {
-  const retryOpts = (0, import_options.normalizeRetryOptions)(options);
-  const { signal } = retryOpts;
-  const { length } = chunks;
-  const filteredChunks = Array(length);
-  for (let i = 0; i < length; i += 1) {
-    if (signal?.aborted) {
-      filteredChunks[i] = [];
-    } else {
-      const chunk = chunks[i];
-      const settled = await (0, import_promise.PromiseAllSettled)(
-        chunk.map(
-          (value) => (0, import_retry.pRetry)((...args) => callbackFn(args[0]), {
-            ...retryOpts,
-            args: [value]
-          })
-        )
-      );
-      const predicateResults = settled.map(
-        (r) => r.status === "fulfilled" ? r.value : false
-      );
-      filteredChunks[i] = chunk.filter((_v, i2) => predicateResults[i2]);
-    }
-  }
-  return filteredChunks;
+	const retryOpts = /* @__PURE__ */ require_promises_options.normalizeRetryOptions(options);
+	const { signal } = retryOpts;
+	const { length } = chunks;
+	const filteredChunks = Array(length);
+	for (let i = 0; i < length; i += 1) if (signal?.aborted) filteredChunks[i] = [];
+	else {
+		const chunk = chunks[i];
+		const predicateResults = (await require_primordials_promise.PromiseAllSettled(chunk.map((value) => /* @__PURE__ */ require_promises_retry.pRetry((...args) => callbackFn(args[0]), {
+			...retryOpts,
+			args: [value]
+		})))).map((r) => r.status === "fulfilled" ? r.value : false);
+		filteredChunks[i] = chunk.filter((_v, i) => predicateResults[i]);
+	}
+	return filteredChunks;
 }
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  pEach,
-  pEachChunk,
-  pFilter,
-  pFilterChunk
-});
+
+//#endregion
+exports.pEach = pEach;
+exports.pEachChunk = pEachChunk;
+exports.pFilter = pFilter;
+exports.pFilterChunk = pFilterChunk;

package/dist/promises/options.js

@@ -1,108 +1,130 @@
 "use strict";
-/* Socket Lib - Built with esbuild */
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var options_exports = {};
-__export(options_exports, {
-  normalizeIterationOptions: () => normalizeIterationOptions,
-  normalizeRetryOptions: () => normalizeRetryOptions,
-  resolveRetryOptions: () => resolveRetryOptions
-});
-module.exports = __toCommonJS(options_exports);
-var import_math = require("../primordials/math");
-var import_internal = require("./_internal");
-// @__NO_SIDE_EFFECTS__
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_primordials_math = require('../primordials/math.js');
+const require_promises__internal = require('./_internal.js');
+
+//#region src/promises/options.ts
+/**
+* @file Option-shape normalizers for the iteration / retry helpers. Three free
+*   functions — kept together because they're a tiny cluster of pure transforms
+*   that callers cycle through: `resolveRetryOptions` (number-shorthand →
+*   minimal object) → `normalizeRetryOptions` (defaults + signal binding) →
+*   `normalizeIterationOptions` (concurrency + retries combined).
+*/
+/**
+* Normalize options for iteration functions.
+*
+* Converts various option formats into a consistent structure with defaults
+* applied. Handles number shorthand for concurrency and ensures minimum
+* values.
+*
+* @example
+*   // Number shorthand for concurrency
+*   normalizeIterationOptions(5)
+*   // => { concurrency: 5, retries: {...}, signal: AbortSignal }
+*
+* @example
+*   // Full options
+*   normalizeIterationOptions({ concurrency: 3, retries: 2 })
+*   // => { concurrency: 3, retries: {...}, signal: AbortSignal }
+*
+* @param options - Concurrency as number, or full options object, or undefined.
+*
+* @returns Normalized options with concurrency, retries, and signal
+*/
+/* @__NO_SIDE_EFFECTS__ */
 function normalizeIterationOptions(options) {
-  const opts = typeof options === "number" ? { concurrency: options } : options;
-  const {
-    // The number of concurrent executions performed at one time.
-    concurrency = 1,
-    // Retries as a number or options object.
-    retries,
-    // AbortSignal used to support cancellation.
-    signal = import_internal.abortSignal
-  } = { __proto__: null, ...opts };
-  const normalizedConcurrency = (0, import_math.MathMax)(1, concurrency);
-  const retryOpts = /* @__PURE__ */ resolveRetryOptions(retries);
-  return {
-    __proto__: null,
-    concurrency: normalizedConcurrency,
-    retries: /* @__PURE__ */ normalizeRetryOptions({ signal, ...retryOpts }),
-    signal
-  };
+	const { concurrency = 1, retries, signal = require_promises__internal.abortSignal } = {
+		__proto__: null,
+		...typeof options === "number" ? { concurrency: options } : options
+	};
+	return {
+		__proto__: null,
+		concurrency: require_primordials_math.MathMax(1, concurrency),
+		retries: /* @__PURE__ */ normalizeRetryOptions({
+			signal,
+			.../* @__PURE__ */ resolveRetryOptions(retries)
+		}),
+		signal
+	};
 }
-// @__NO_SIDE_EFFECTS__
+/**
+* Normalize options for retry functionality.
+*
+* Converts various retry option formats into a complete configuration with all
+* defaults. Handles legacy property names (`factor`, `minTimeout`,
+* `maxTimeout`) and merges them with modern equivalents.
+*
+* @example
+*   // Number shorthand
+*   normalizeRetryOptions(3)
+*   // => { retries: 3, baseDelayMs: 200, backoffFactor: 2, ... }
+*
+* @example
+*   // Full options with defaults filled in
+*   normalizeRetryOptions({ retries: 5, baseDelayMs: 500 })
+*   // => { retries: 5, baseDelayMs: 500, backoffFactor: 2, jitter: true, ... }
+*
+* @param options - Retry count as number, or full options object, or undefined.
+*
+* @returns Normalized retry options with all properties set
+*/
+/* @__NO_SIDE_EFFECTS__ */
 function normalizeRetryOptions(options) {
-  const resolved = /* @__PURE__ */ resolveRetryOptions(options);
-  const {
-    // Arguments to pass to the callback function.
-    args = [],
-    // Multiplier for exponential backoff (e.g., 2 doubles delay each retry).
-    backoffFactor = 2,
-    // Initial delay before the first retry (in milliseconds).
-    baseDelayMs = 200,
-    // Whether to apply randomness to spread out retries.
-    jitter = true,
-    // Upper limit for any backoff delay (in milliseconds).
-    maxDelayMs = 1e4,
-    // Optional callback invoked on each retry attempt:
-    // (attempt: number, error: unknown, delay: number) => void
-    onRetry,
-    // Whether onRetry can cancel retries by returning `false`.
-    onRetryCancelOnFalse = false,
-    // Whether onRetry will rethrow errors.
-    onRetryRethrow = false,
-    // Number of retry attempts (0 = no retries, only initial attempt).
-    retries = 0,
-    // AbortSignal used to support cancellation.
-    signal = import_internal.abortSignal
-  } = resolved;
-  return {
-    args,
-    backoffFactor,
-    baseDelayMs,
-    jitter,
-    maxDelayMs,
-    onRetry,
-    onRetryCancelOnFalse,
-    onRetryRethrow,
-    retries,
-    signal
-  };
+	const { args = [], backoffFactor = 2, baseDelayMs = 200, jitter = true, maxDelayMs = 1e4, onRetry, onRetryCancelOnFalse = false, onRetryRethrow = false, retries = 0, signal = require_promises__internal.abortSignal } = /* @__PURE__ */ resolveRetryOptions(options);
+	return {
+		args,
+		backoffFactor,
+		baseDelayMs,
+		jitter,
+		maxDelayMs,
+		onRetry,
+		onRetryCancelOnFalse,
+		onRetryRethrow,
+		retries,
+		signal
+	};
 }
-// @__NO_SIDE_EFFECTS__
+/**
+* Resolve retry options from various input formats.
+*
+* Converts shorthand and partial options into a base configuration that can be
+* further normalized. This is an internal helper for option processing.
+*
+* @example
+*   resolveRetryOptions(3)
+*   // => { retries: 3, minTimeout: 200, maxTimeout: 10000, factor: 2 }
+*
+* @example
+*   resolveRetryOptions({ retries: 5, maxTimeout: 5000 })
+*   // => { retries: 5, minTimeout: 200, maxTimeout: 5000, factor: 2 }
+*
+* @param options - Retry count as number, or partial options object, or
+*   undefined.
+*
+* @returns Resolved retry options with defaults for basic properties
+*/
+/* @__NO_SIDE_EFFECTS__ */
 function resolveRetryOptions(options) {
-  const defaults = {
-    __proto__: null,
-    retries: 0,
-    baseDelayMs: 200,
-    maxDelayMs: 1e4,
-    backoffFactor: 2
-  };
-  if (typeof options === "number") {
-    return { ...defaults, retries: options };
-  }
-  return options ? { ...defaults, ...options } : defaults;
+	const defaults = {
+		__proto__: null,
+		retries: 0,
+		baseDelayMs: 200,
+		maxDelayMs: 1e4,
+		backoffFactor: 2
+	};
+	if (typeof options === "number") return {
+		...defaults,
+		retries: options
+	};
+	return options ? {
+		...defaults,
+		...options
+	} : defaults;
 }
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  normalizeIterationOptions,
-  normalizeRetryOptions,
-  resolveRetryOptions
-});
+
+//#endregion
+exports.normalizeIterationOptions = normalizeIterationOptions;
+exports.normalizeRetryOptions = normalizeRetryOptions;
+exports.resolveRetryOptions = resolveRetryOptions;