@socketsecurity/lib 5.27.0 → 6.0.0

package/dist/stdio/stderr.d.ts

@@ -1,150 +1,152 @@
 /**
- * @fileoverview Standard error stream utilities.
- * Provides utilities for writing to stderr with formatting and control.
+ * @file Standard error stream utilities. Provides utilities for writing to
+ *   stderr with formatting and control.
  */
 declare const stderr: NodeJS.WriteStream;
 /**
- * Clear the current line on stderr.
- * Only works in TTY environments.
+ * Clear the current line on stderr. Only works in TTY environments.
  *
  * @example
- * ```ts
- * writeError('Processing...')
- * clearLine()
- * writeError('Done!')
- * ```
+ *   ;```ts
+ *   writeError('Processing...')
+ *   clearLine()
+ *   writeError('Done!')
+ *   ```
  */
 export declare function clearLine(): void;
 /**
- * Move cursor to specific position on stderr.
- * Only works in TTY environments.
+ * Move cursor to specific position on stderr. Only works in TTY environments.
+ *
+ * @example
+ *   ;```ts
+ *   cursorTo(0) // Move to start of line
+ *   cursorTo(10, 5) // Move to column 10, row 5
+ *   ```
  *
  * @param x - Column position (0-based)
  * @param y - Row position (0-based, optional)
- *
- * @example
- * ```ts
- * cursorTo(0) // Move to start of line
- * cursorTo(10, 5) // Move to column 10, row 5
- * ```
  */
 export declare function cursorTo(x: number, y?: number | undefined): void;
 /**
  * Get the number of columns (width) in the terminal.
  *
- * @returns Terminal width in characters
+ * @example
+ *   ```ts
+ *   const width = getColumns()
+ *   console.error(`Terminal is ${width} characters wide`)
+ *   ```
+ *
  * @default 80
  *
- * @example
- * ```ts
- * const width = getColumns()
- * console.error(`Terminal is ${width} characters wide`)
- * ```
+ * @returns Terminal width in characters
  */
 export declare function getColumns(): number;
 /**
  * Get the number of rows (height) in the terminal.
  *
- * @returns Terminal height in lines
+ * @example
+ *   ```ts
+ *   const height = getRows()
+ *   console.error(`Terminal is ${height} lines tall`)
+ *   ```
+ *
  * @default 24
  *
- * @example
- * ```ts
- * const height = getRows()
- * console.error(`Terminal is ${height} lines tall`)
- * ```
+ * @returns Terminal height in lines
  */
 export declare function getRows(): number;
 /**
  * Check if stderr is connected to a TTY (terminal).
  *
- * @returns `true` if stderr is a TTY, `false` if piped/redirected
- *
  * @example
- * ```ts
- * if (isTTY()) {
- *   // Show colored error messages
- * } else {
- *   // Use plain text
- * }
- * ```
+ *   ;```ts
+ *   if (isTTY()) {
+ *     // Show colored error messages
+ *   } else {
+ *     // Use plain text
+ *   }
+ *   ```
+ *
+ * @returns `true` if stderr is a TTY, `false` if piped/redirected
  */
 export declare function isTTY(): boolean;
 /**
  * Write text to stderr without adding a newline.
  *
- * @param text - Text to write
- *
  * @example
- * ```ts
- * writeError('Downloading...')
- * // Later update progress
- * ```
+ *   ;```ts
+ *   writeError('Downloading...')
+ *   // Later update progress
+ *   ```
+ *
+ * @param text - Text to write.
  */
 export declare function writeError(text: string): void;
 /**
  * Write a formatted error message to stderr.
  *
- * @param message - Error message text
- * @param prefix - Prefix label for the error
- * @default prefix 'Error'
- *
  * @example
- * ```ts
- * writeErrorFormatted('File not found')
- * // Output: 'Error: File not found'
+ *   ;```ts
+ *   writeErrorFormatted('File not found')
+ *   // Output: 'Error: File not found'
+ *
+ *   writeErrorFormatted('Connection failed', 'Network')
+ *   // Output: 'Network: Connection failed'
+ *   ```
  *
- * writeErrorFormatted('Connection failed', 'Network')
- * // Output: 'Network: Connection failed'
- * ```
+ * @default prefix 'Error'
+ *
+ * @param message - Error message text.
+ * @param prefix - Prefix label for the error.
  */
 export declare function writeErrorFormatted(message: string, prefix?: string): void;
 /**
- * Write a line to stderr with trailing newline.
- * Used for error messages, warnings, and diagnostic output.
- * Passing no argument writes an empty line.
+ * Write a line to stderr with trailing newline. Used for error messages,
+ * warnings, and diagnostic output. Passing no argument writes an empty line.
+ *
+ * @example
+ *   ;```ts
+ *   writeErrorLine('Error: File not found')
+ *   writeErrorLine() // Write empty line
+ *   ```
  *
- * @param text - Text to write (defaults to the empty string)
  * @default text ''
  *
- * @example
- * ```ts
- * writeErrorLine('Error: File not found')
- * writeErrorLine() // Write empty line
- * ```
+ * @param text - Text to write (defaults to the empty string)
  */
 export declare function writeErrorLine(text?: string): void;
 /**
- * Write an error's stack trace to stderr.
- * Falls back to formatted error message if no stack is available.
- *
- * @param error - Error object to write
+ * Write an error's stack trace to stderr. Falls back to formatted error message
+ * if no stack is available.
  *
  * @example
- * ```ts
- * try {
- *   throw new Error('Something went wrong')
- * } catch (e) {
- *   writeStackTrace(e as Error)
- * }
- * ```
+ *   ;```ts
+ *   try {
+ *     throw new ErrorCtor('Something went wrong')
+ *   } catch (e) {
+ *     writeStackTrace(e as Error)
+ *   }
+ *   ```
+ *
+ * @param error - Error object to write.
  */
 export declare function writeStackTrace(error: Error): void;
 /**
  * Write a formatted warning message to stderr.
  *
- * @param message - Warning message text
- * @param prefix - Prefix label for the warning
- * @default prefix 'Warning'
- *
  * @example
- * ```ts
- * writeWarning('Deprecated API usage')
- * // Output: 'Warning: Deprecated API usage'
+ *   ;```ts
+ *   writeWarning('Deprecated API usage')
+ *   // Output: 'Warning: Deprecated API usage'
+ *
+ *   writeWarning('Invalid config', 'Config')
+ *   // Output: 'Config: Invalid config'
+ *   ```
+ *
+ * @default prefix 'Warning'
  *
- * writeWarning('Invalid config', 'Config')
- * // Output: 'Config: Invalid config'
- * ```
+ * @param message - Warning message text.
+ * @param prefix - Prefix label for the warning.
  */
 export declare function writeWarning(message: string, prefix?: string): void;
 export { stderr };

package/dist/stdio/stderr.js

@@ -44,22 +44,22 @@ __export(stderr_exports, {
 });
 module.exports = __toCommonJS(stderr_exports);
 var import_node_process = __toESM(require("node:process"));
-var import_stream = require("./_stream");
+var import_internal = require("./_internal");
 const stderr = import_node_process.default.stderr;
 function clearLine() {
-  (0, import_stream.clearLineOn)(stderr);
+  (0, import_internal.clearLineOn)(stderr);
 }
 function cursorTo(x, y) {
-  (0, import_stream.cursorToOn)(stderr, x, y);
+  (0, import_internal.cursorToOn)(stderr, x, y);
 }
 function getColumns() {
-  return (0, import_stream.getColumnsOf)(stderr);
+  return (0, import_internal.getColumnsOf)(stderr);
 }
 function getRows() {
-  return (0, import_stream.getRowsOf)(stderr);
+  return (0, import_internal.getRowsOf)(stderr);
 }
 function isTTY() {
-  return (0, import_stream.isTTYOf)(stderr);
+  return (0, import_internal.isTTYOf)(stderr);
 }
 function writeError(text) {
   stderr.write(text);

package/dist/stdio/stdout.d.ts

@@ -1,146 +1,145 @@
 /**
- * @fileoverview Standard output stream utilities.
- * Provides utilities for writing to stdout with formatting and control.
+ * @file Standard output stream utilities. Provides utilities for writing to
+ *   stdout with formatting and control.
  */
 declare const stdout: NodeJS.WriteStream;
 /**
- * Clear the current line on stdout.
- * Only works in TTY environments.
+ * Clear the current line on stdout. Only works in TTY environments.
  *
  * @example
- * ```ts
- * write('Processing...')
- * clearLine()
- * write('Done!')
- * ```
+ *   ;```ts
+ *   write('Processing...')
+ *   clearLine()
+ *   write('Done!')
+ *   ```
  */
 export declare function clearLine(): void;
 /**
- * Clear screen from cursor position down to bottom.
- * Only works in TTY environments.
+ * Clear screen from cursor position down to bottom. Only works in TTY
+ * environments.
  *
  * @example
- * ```ts
- * cursorTo(0, 5)
- * clearScreenDown() // Clear from row 5 to bottom
- * ```
+ *   ;```ts
+ *   cursorTo(0, 5)
+ *   clearScreenDown() // Clear from row 5 to bottom
+ *   ```
  */
 export declare function clearScreenDown(): void;
 /**
- * Move cursor to specific position on stdout.
- * Only works in TTY environments.
+ * Move cursor to specific position on stdout. Only works in TTY environments.
+ *
+ * @example
+ *   ;```ts
+ *   cursorTo(0) // Move to start of line
+ *   cursorTo(10, 5) // Move to column 10, row 5
+ *   ```
  *
  * @param x - Column position (0-based)
  * @param y - Row position (0-based, optional)
- *
- * @example
- * ```ts
- * cursorTo(0) // Move to start of line
- * cursorTo(10, 5) // Move to column 10, row 5
- * ```
  */
 export declare function cursorTo(x: number, y?: number | undefined): void;
 /**
- * Register handlers to ensure cursor is shown on process exit.
- * Prevents hidden cursor after abnormal termination.
- * Handles SIGINT (Ctrl+C) and SIGTERM signals.
+ * Register handlers to ensure cursor is shown on process exit. Prevents hidden
+ * cursor after abnormal termination. Handles SIGINT (Ctrl+C) and SIGTERM
+ * signals.
  *
  * @example
- * ```ts
- * ensureCursorOnExit()
- * hideCursor()
- * // Even if process crashes, cursor will be restored
- * ```
+ *   ;```ts
+ *   ensureCursorOnExit()
+ *   hideCursor()
+ *   // Even if process crashes, cursor will be restored
+ *   ```
  */
 export declare function ensureCursorOnExit(): void;
 /**
  * Get the number of columns (width) in the terminal.
  *
- * @returns Terminal width in characters
+ * @example
+ *   ```ts
+ *   const width = getColumns()
+ *   console.log(`Terminal is ${width} characters wide`)
+ *   ```
+ *
  * @default 80
  *
- * @example
- * ```ts
- * const width = getColumns()
- * console.log(`Terminal is ${width} characters wide`)
- * ```
+ * @returns Terminal width in characters
  */
 export declare function getColumns(): number;
 /**
  * Get the number of rows (height) in the terminal.
  *
- * @returns Terminal height in lines
+ * @example
+ *   ```ts
+ *   const height = getRows()
+ *   console.log(`Terminal is ${height} lines tall`)
+ *   ```
+ *
  * @default 24
  *
- * @example
- * ```ts
- * const height = getRows()
- * console.log(`Terminal is ${height} lines tall`)
- * ```
+ * @returns Terminal height in lines
  */
 export declare function getRows(): number;
 /**
- * Hide the cursor on stdout.
- * Useful for cleaner output during animations.
+ * Hide the cursor on stdout. Useful for cleaner output during animations.
  *
  * @example
- * ```ts
- * hideCursor()
- * // Show animation
- * showCursor()
- * ```
+ *   ;```ts
+ *   hideCursor()
+ *   // Show animation
+ *   showCursor()
+ *   ```
  */
 export declare function hideCursor(): void;
 /**
  * Check if stdout is connected to a TTY (terminal).
  *
- * @returns `true` if stdout is a TTY, `false` if piped/redirected
- *
  * @example
- * ```ts
- * if (isTTY()) {
- *   // Show interactive UI
- * } else {
- *   // Use simple text output
- * }
- * ```
+ *   ;```ts
+ *   if (isTTY()) {
+ *     // Show interactive UI
+ *   } else {
+ *     // Use simple text output
+ *   }
+ *   ```
+ *
+ * @returns `true` if stdout is a TTY, `false` if piped/redirected
  */
 export declare function isTTY(): boolean;
 /**
- * Show the cursor on stdout.
- * Should be called after `hideCursor()`.
+ * Show the cursor on stdout. Should be called after `hideCursor()`.
  *
  * @example
- * ```ts
- * hideCursor()
- * // Show animation
- * showCursor()
- * ```
+ *   ;```ts
+ *   hideCursor()
+ *   // Show animation
+ *   showCursor()
+ *   ```
  */
 export declare function showCursor(): void;
 /**
  * Write text to stdout without adding a newline.
  *
- * @param text - Text to write
- *
  * @example
- * ```ts
- * write('Loading...')
- * // Later: clear and update
- * ```
+ *   ;```ts
+ *   write('Loading...')
+ *   // Later: clear and update
+ *   ```
+ *
+ * @param text - Text to write.
  */
 export declare function write(text: string): void;
 /**
  * Write a line to stdout with trailing newline.
  *
- * @param text - Text to write
+ * @example
+ *   ;```ts
+ *   writeLine('Hello, world!')
+ *   writeLine() // Write empty line
+ *   ```
+ *
  * @default text ''
  *
- * @example
- * ```ts
- * writeLine('Hello, world!')
- * writeLine() // Write empty line
- * ```
+ * @param text - Text to write.
  */
 export declare function writeLine(text?: string): void;
 export { stdout };

package/dist/stdio/stdout.js

@@ -46,11 +46,11 @@ __export(stdout_exports, {
 module.exports = __toCommonJS(stdout_exports);
 var import_node_process = __toESM(require("node:process"));
 var import_node_tty = require("node:tty");
-var import_stream = require("./_stream");
+var import_internal = require("./_internal");
 const stdout = import_node_process.default.stdout;
 let _cursorExitRegistered = false;
 function clearLine() {
-  (0, import_stream.clearLineOn)(stdout);
+  (0, import_internal.clearLineOn)(stdout);
 }
 function clearScreenDown() {
   if (stdout.isTTY) {
@@ -58,7 +58,7 @@ function clearScreenDown() {
   }
 }
 function cursorTo(x, y) {
-  (0, import_stream.cursorToOn)(stdout, x, y);
+  (0, import_internal.cursorToOn)(stdout, x, y);
 }
 function ensureCursorOnExit() {
   if (_cursorExitRegistered) {
@@ -76,10 +76,10 @@ function ensureCursorOnExit() {
   });
 }
 function getColumns() {
-  return (0, import_stream.getColumnsOf)(stdout);
+  return (0, import_internal.getColumnsOf)(stdout);
 }
 function getRows() {
-  return (0, import_stream.getRowsOf)(stdout);
+  return (0, import_internal.getRowsOf)(stdout);
 }
 function hideCursor() {
   if (stdout.isTTY && stdout instanceof import_node_tty.WriteStream) {
@@ -87,7 +87,7 @@ function hideCursor() {
   }
 }
 function isTTY() {
-  return (0, import_stream.isTTYOf)(stdout);
+  return (0, import_internal.isTTYOf)(stdout);
 }
 function showCursor() {
   if (stdout.isTTY && stdout instanceof import_node_tty.WriteStream) {

package/dist/streams/parallel.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @file Parallel iteration helpers — `parallelMap()` and the fire-and-forget
+ *   `parallelEach()`. Built on top of `streaming-iterables.parallelMap` with
+ *   the project's `pRetry` wrapper applied per item.
+ */
+import type { IterationOptions } from '../promises/types';
+/**
+ * Execute a function for each item in an iterable in parallel.
+ *
+ * @example
+ *   ;```typescript
+ *   const urls = ['https://a.io', 'https://b.io']
+ *   await parallelEach(
+ *     urls,
+ *     async url => {
+ *       await fetch(url)
+ *     },
+ *     { concurrency: 4 },
+ *   )
+ *   ```
+ */
+export declare function parallelEach<T>(iterable: Iterable<T> | AsyncIterable<T>, func: (item: T) => Promise<unknown>, options?: number | IterationOptions): Promise<void>;
+/**
+ * Map over an iterable in parallel with concurrency control.
+ *
+ * @example
+ *   ;```typescript
+ *   const ids = [1, 2, 3]
+ *   for await (const result of parallelMap(
+ *     ids,
+ *     async id => {
+ *       return await fetchData(id)
+ *     },
+ *     4,
+ *   )) {
+ *     console.log(result)
+ *   }
+ *   ```
+ */
+export declare function parallelMap<T, U>(iterable: Iterable<T> | AsyncIterable<T>, func: (item: T) => Promise<U>, options?: number | IterationOptions): AsyncIterable<U>;

package/dist/{streams.js → streams/parallel.js}

@@ -18,15 +18,15 @@ var __copyProps = (to, from, except, desc) => {
   return to;
 };
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var streams_exports = {};
-__export(streams_exports, {
+var parallel_exports = {};
+__export(parallel_exports, {
   parallelEach: () => parallelEach,
-  parallelMap: () => parallelMap,
-  transform: () => transform
+  parallelMap: () => parallelMap
 });
-module.exports = __toCommonJS(streams_exports);
-var import_streaming_iterables = require("./external/streaming-iterables");
-var import_promises = require("./promises");
+module.exports = __toCommonJS(parallel_exports);
+var import_streaming_iterables = require("../external/streaming-iterables");
+var import_options = require("../promises/options");
+var import_retry = require("../promises/retry");
 // @__NO_SIDE_EFFECTS__
 async function parallelEach(iterable, func, options) {
   for await (const _ of /* @__PURE__ */ parallelMap(iterable, func, options)) {
@@ -34,27 +34,11 @@ async function parallelEach(iterable, func, options) {
 }
 // @__NO_SIDE_EFFECTS__
 function parallelMap(iterable, func, options) {
-  const opts = (0, import_promises.normalizeIterationOptions)(options);
+  const opts = (0, import_options.normalizeIterationOptions)(options);
   const result = (0, import_streaming_iterables.parallelMap)(
     opts.concurrency,
     async (item) => {
-      const result2 = await (0, import_promises.pRetry)((...args) => func(args[0]), {
-        ...opts.retries,
-        args: [item]
-      });
-      return result2;
-    },
-    iterable
-  );
-  return result;
-}
-// @__NO_SIDE_EFFECTS__
-function transform(iterable, func, options) {
-  const opts = (0, import_promises.normalizeIterationOptions)(options);
-  const result = (0, import_streaming_iterables.transform)(
-    opts.concurrency,
-    async (item) => {
-      const result2 = await (0, import_promises.pRetry)((...args) => func(args[0]), {
+      const result2 = await (0, import_retry.pRetry)((...args) => func(args[0]), {
         ...opts.retries,
         args: [item]
       });
@@ -67,6 +51,5 @@ function transform(iterable, func, options) {
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   parallelEach,
-  parallelMap,
-  transform
+  parallelMap
 });

package/dist/streams/transform.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @file Streaming transform helper — `transform()` wraps
+ *   `streaming-iterables.transform` with the project's `pRetry` per-item retry
+ *   policy.
+ */
+import type { IterationOptions } from '../promises/types';
+/**
+ * Transform an iterable with a function.
+ *
+ * @example
+ *   ;```typescript
+ *   const lines = ['hello', 'world']
+ *   for await (const upper of transform(lines, async line => {
+ *     return line.toUpperCase()
+ *   })) {
+ *     console.log(upper) // 'HELLO', 'WORLD'
+ *   }
+ *   ```
+ */
+export declare function transform<T, U>(iterable: Iterable<T> | AsyncIterable<T>, func: (item: T) => Promise<U>, options?: number | IterationOptions): AsyncIterable<U>;