@socketsecurity/lib 5.28.0 → 6.0.0

package/dist/json/types.d.ts

@@ -1,22 +1,22 @@
 /**
- * @fileoverview JSON type definitions and interfaces.
+ * @file JSON type definitions and interfaces.
  */
 /**
  * JSON primitive types: `null`, `boolean`, `number`, or `string`.
  *
  * @example
- * ```ts
- * const primitives: JsonPrimitive[] = [null, true, 42, 'hello']
- * ```
+ *   ;```ts
+ *   const primitives: JsonPrimitive[] = [null, true, 42, 'hello']
+ *   ```
  */
 export type JsonPrimitive = null | boolean | number | string;
 /**
  * A JSON array containing JSON values.
  *
  * @example
- * ```ts
- * const arr: JsonArray = [1, 'two', { three: 3 }, [4, 5]]
- * ```
+ *   ;```ts
+ *   const arr: JsonArray = [1, 'two', { three: 3 }, [4, 5]]
+ *   ```
  */
 export interface JsonArray extends Array<JsonValue> {
 }
@@ -24,14 +24,14 @@ export interface JsonArray extends Array<JsonValue> {
  * A JSON object with string keys and JSON values.
  *
  * @example
- * ```ts
- * const obj: JsonObject = {
- *   name: 'example',
- *   count: 42,
- *   active: true,
- *   nested: { key: 'value' }
- * }
- * ```
+ *   ;```ts
+ *   const obj: JsonObject = {
+ *     name: 'example',
+ *     count: 42,
+ *     active: true,
+ *     nested: { key: 'value' },
+ *   }
+ *   ```
  */
 export interface JsonObject {
     [key: string]: JsonValue;
@@ -40,134 +40,134 @@ export interface JsonObject {
  * Any valid JSON value: primitive, object, or array.
  *
  * @example
- * ```ts
- * const values: JsonValue[] = [
- *   null,
- *   true,
- *   42,
- *   'hello',
- *   { key: 'value' },
- *   [1, 2, 3]
- * ]
- * ```
+ *   ;```ts
+ *   const values: JsonValue[] = [
+ *     null,
+ *     true,
+ *     42,
+ *     'hello',
+ *     { key: 'value' },
+ *     [1, 2, 3],
+ *   ]
+ *   ```
  */
 export type JsonValue = JsonPrimitive | JsonObject | JsonArray;
 /**
- * Reviver function for transforming parsed JSON values.
- * Called for each key-value pair during parsing.
- *
- * @param key - The object key or array index being parsed
- * @param value - The parsed value
- * @returns The transformed value (or original if no transform needed)
+ * Reviver function for transforming parsed JSON values. Called for each
+ * key-value pair during parsing.
  *
  * @example
- * ```ts
- * // Convert date strings to Date objects
- * const reviver: JsonReviver = (key, value) => {
- *   if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}/.test(value)) {
- *     return new Date(value)
+ *   ;```ts
+ *   // Convert date strings to Date objects
+ *   const reviver: JsonReviver = (key, value) => {
+ *     if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}/.test(value)) {
+ *       return new Date(value)
+ *     }
+ *     return value
  *   }
- *   return value
- * }
- * ```
+ *   ```
+ *
+ * @param key - The object key or array index being parsed.
+ * @param value - The parsed value.
+ *
+ * @returns The transformed value (or original if no transform needed)
  */
 export type JsonReviver = (key: string, value: unknown) => unknown;
 /**
- * Options for `safeJsonParse`: security controls for untrusted JSON.
+ * Options for `parseJsonSafe`: security controls for untrusted JSON.
  *
- * Distinct from `JsonParseOptions` (which is scoped to reviver /
- * error-handling for trusted-source fs reads). Use this type when
- * parsing user input, network payloads, or anything beyond a trust
- * boundary.
+ * Distinct from `ParseJsonOptions` (which is scoped to reviver / error-handling
+ * for trusted-source fs reads). Use this type when parsing user input, network
+ * payloads, or anything beyond a trust boundary.
  *
  * @example
- * ```ts
- * const options: SafeJsonParseOptions = {
- *   maxSize: 1024 * 1024, // 1MB limit
- *   allowPrototype: false // Block prototype pollution
- * }
- * ```
+ *   ;```ts
+ *   const options: ParseJsonSafeOptions = {
+ *     maxSize: 1024 * 1024, // 1MB limit
+ *     allowPrototype: false, // Block prototype pollution
+ *   }
+ *   ```
  */
-export interface SafeJsonParseOptions {
+export interface ParseJsonSafeOptions {
     /**
-     * Allow dangerous prototype pollution keys (`__proto__`, `constructor`, `prototype`).
-     * Set to `true` only if you trust the JSON source completely.
-     *
-     * @default false
+     * Allow dangerous prototype pollution keys (`__proto__`, `constructor`,
+     * `prototype`). Set to `true` only if you trust the JSON source completely.
      *
      * @example
-     * ```ts
-     * // Will throw error by default
-     * safeJsonParse('{"__proto__": {"polluted": true}}')
+     *   ;```ts
+     *   // Will throw error by default
+     *   parseJsonSafe('{"__proto__": {"polluted": true}}')
      *
-     * // Allows the parse (dangerous!)
-     * safeJsonParse('{"__proto__": {"polluted": true}}', undefined, {
-     *   allowPrototype: true
-     * })
-     * ```
+     *   // Allows the parse (dangerous!)
+     *   parseJsonSafe('{"__proto__": {"polluted": true}}', undefined, {
+     *     allowPrototype: true,
+     *   })
+     *   ```
+     *
+     * @default false
      */
     allowPrototype?: boolean | undefined;
     /**
-     * Maximum allowed size of JSON string in bytes.
-     * Prevents memory exhaustion from extremely large payloads.
-     *
-     * @default 10_485_760 (10 MB)
+     * Maximum allowed size of JSON string in bytes. Prevents memory exhaustion
+     * from extremely large payloads.
      *
      * @example
-     * ```ts
-     * // Limit to 1KB
-     * safeJsonParse(jsonString, undefined, { maxSize: 1024 })
-     * ```
+     *   ;```ts
+     *   // Limit to 1KB
+     *   parseJsonSafe(jsonString, undefined, { maxSize: 1024 })
+     *   ```
+     *
+     * @default 10_485_760 (10 MB)
      */
     maxSize?: number | undefined;
 }
 /**
  * Options for JSON parsing operations.
  */
-export interface JsonParseOptions {
+export interface ParseJsonOptions {
     /**
-     * Optional filepath for improved error messages.
-     * When provided, errors will be prefixed with the filepath.
+     * Optional filepath for improved error messages. When provided, errors will
+     * be prefixed with the filepath.
      *
      * @example
-     * ```ts
-     * // Error message will be: "config.json: Unexpected token } in JSON"
-     * jsonParse('invalid', { filepath: 'config.json' })
-     * ```
+     *   ;```ts
+     *   // Error message will be: "config.json: Unexpected token } in JSON"
+     *   parseJson('invalid', { filepath: 'config.json' })
+     *   ```
      */
     filepath?: string | undefined;
     /**
-     * Optional reviver function to transform parsed values.
-     * Called for each key-value pair during parsing.
+     * Optional reviver function to transform parsed values. Called for each
+     * key-value pair during parsing.
      *
      * @example
-     * ```ts
-     * // Convert ISO date strings to Date objects
-     * const options = {
-     *   reviver: (key, value) => {
-     *     if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}/.test(value)) {
-     *       return new Date(value)
-     *     }
-     *     return value
+     *   ;```ts
+     *   // Convert ISO date strings to Date objects
+     *   const options = {
+     *     reviver: (key, value) => {
+     *       if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}/.test(value)) {
+     *         return new Date(value)
+     *       }
+     *       return value
+     *     },
      *   }
-     * }
-     * ```
+     *   ```
      */
     reviver?: JsonReviver | undefined;
     /**
-     * Whether to throw on parse errors.
-     * When `false`, returns `undefined` instead of throwing.
-     *
-     * @default true
+     * Whether to throw on parse errors. When `false`, returns `undefined` instead
+     * of throwing.
      *
      * @example
-     * ```ts
-     * // Throws error
-     * jsonParse('invalid', { throws: true })
+     *   ;```ts
+     *   // Throws error
+     *   parseJson('invalid', { throws: true })
      *
-     * // Returns undefined
-     * const result = jsonParse('invalid', { throws: false })
-     * ```
+     *   // Returns undefined
+     *   const result = parseJson('invalid', { throws: false })
+     *   ```
+     *
+     * @default true
      */
     throws?: boolean | undefined;
 }
@@ -176,12 +176,15 @@ export interface JsonParseOptions {
  */
 export interface EditableJsonSaveOptions {
     /**
-     * Whether to ignore whitespace-only changes when determining if save is needed.
+     * Whether to ignore whitespace-only changes when determining if save is
+     * needed.
+     *
      * @default false
      */
     ignoreWhitespace?: boolean | undefined;
     /**
      * Whether to sort object keys alphabetically before saving.
+     *
      * @default false
      */
     sort?: boolean | undefined;
@@ -196,6 +199,7 @@ export interface EditableJsonOptions<T = Record<string, unknown>> {
     path?: string | undefined;
     /**
      * Whether to create the file if it doesn't exist during load.
+     *
      * @default false
      */
     create?: boolean | undefined;
@@ -205,65 +209,77 @@ export interface EditableJsonOptions<T = Record<string, unknown>> {
     data?: T | undefined;
 }
 /**
- * EditableJson instance interface for JSON file manipulation.
- * Provides core functionality for loading, editing, and saving JSON files
- * while preserving formatting (indentation and line endings).
+ * EditableJson instance interface for JSON file manipulation. Provides core
+ * functionality for loading, editing, and saving JSON files while preserving
+ * formatting (indentation and line endings).
  */
 export interface EditableJsonInstance<T = Record<string, unknown>> {
     /**
      * The parsed JSON content as a readonly object.
+     *
      * @readonly
      */
     content: Readonly<T>;
     /**
      * Create a new JSON file at the specified path.
-     * @param path - The file path where JSON will be created
+     *
+     * @param path - The file path where JSON will be created.
      */
     create(path: string): this;
     /**
-     * Initialize the instance from a content object.
-     * Note: Disables saving when used (no file path associated).
-     * @param content - The JSON content object
+     * Initialize the instance from a content object. Note: Disables saving when
+     * used (no file path associated).
+     *
+     * @param content - The JSON content object.
      */
     fromContent(content: unknown): this;
     /**
      * Initialize the instance from a JSON string.
-     * @param json - The JSON content as a string
+     *
+     * @param json - The JSON content as a string.
      */
     fromJSON(json: string): this;
     /**
-     * Load a JSON file from the specified path.
-     * @param path - The file path to load
-     * @param create - Whether to create the file if it doesn't exist
+     * Load a JSON file from the specified path. Throws on read or parse errors.
+     * The static `EditableJson.load(path, { create: true })` surface handles
+     * ENOENT recovery.
+     *
+     * @param path - The file path to load.
      */
-    load(path: string, create?: boolean): Promise<this>;
+    load(path: string): Promise<this>;
     /**
      * Update the JSON content with new values.
-     * @param content - Partial object with fields to update
+     *
+     * @param content - Partial object with fields to update.
      */
     update(content: Partial<T>): this;
     /**
      * Save the JSON file to disk.
-     * @param options - Save options for formatting and sorting
+     *
+     * @param options - Save options for formatting and sorting.
      */
     save(options?: EditableJsonSaveOptions): Promise<boolean>;
     /**
      * Synchronously save the JSON file to disk.
-     * @param options - Save options for formatting and sorting
+     *
+     * @param options - Save options for formatting and sorting.
      */
     saveSync(options?: EditableJsonSaveOptions): boolean;
     /**
      * Check if the JSON will be saved based on current changes.
-     * @param options - Save options to evaluate
+     *
+     * @param options - Save options to evaluate.
      */
     willSave(options?: EditableJsonSaveOptions): boolean;
     /**
      * The full path to the JSON file.
+     *
      * @readonly
      */
     readonly filename: string;
     /**
      * The directory path containing the JSON file.
+     *
      * @readonly
      */
     readonly path: string | undefined;

package/dist/links/link.d.ts

@@ -0,0 +1,65 @@
+/**
+ * @file Themed hyperlink utilities for terminal output. Provides colored
+ *   hyperlinks using theme configuration.
+ */
+import type { LinkOptions } from './types';
+/**
+ * Create a themed hyperlink for terminal output. The link text is colored using
+ * the theme's link color.
+ *
+ * Note: Most terminals support ANSI color codes but not clickable links. This
+ * function colors the text but does not create clickable hyperlinks. For
+ * clickable links, use a library like 'terminal-link' separately.
+ *
+ * @example
+ *   ;```ts
+ *   import { link } from '@socketsecurity/lib/links/link'
+ *
+ *   // Use current theme
+ *   console.log(link('Documentation', 'https://socket.dev'))
+ *
+ *   // Override theme
+ *   console.log(
+ *     link('API Docs', 'https://api.socket.dev', {
+ *       theme: 'coana',
+ *     }),
+ *   )
+ *
+ *   // Show URL as fallback
+ *   console.log(
+ *     link('GitHub', 'https://github.com', {
+ *       fallback: true,
+ *     }),
+ *   )
+ *   // Output: "GitHub (https://github.com)"
+ *   ```
+ *
+ * @param text - Link text to display.
+ * @param url - URL (included in fallback mode)
+ * @param options - Link configuration options.
+ *
+ * @returns Colored link text
+ */
+export declare function link(text: string, url: string, options?: LinkOptions): string;
+/**
+ * Create multiple themed links from an array of link specifications.
+ *
+ * @example
+ *   ;```ts
+ *   import { links } from '@socketsecurity/lib/links/link'
+ *
+ *   const formatted = links([
+ *     ['Documentation', 'https://socket.dev'],
+ *     ['API Reference', 'https://api.socket.dev'],
+ *     ['GitHub', 'https://github.com/SocketDev'],
+ *   ])
+ *
+ *   formatted.forEach(link => console.log(link))
+ *   ```
+ *
+ * @param links - Array of [text, url] pairs.
+ * @param options - Link configuration options.
+ *
+ * @returns Array of colored link texts
+ */
+export declare function links(linkSpecs: Array<[text: string, url: string]>, options?: LinkOptions): string[];

package/dist/{links.js → links/link.js}

@@ -28,27 +28,27 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   mod
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var links_exports = {};
-__export(links_exports, {
+var link_exports = {};
+__export(link_exports, {
   link: () => link,
   links: () => links
 });
-module.exports = __toCommonJS(links_exports);
-var import_yoctocolors_cjs = __toESM(require("./external/yoctocolors-cjs"));
-var import_context = require("./themes/context");
-var import_themes = require("./themes/themes");
-var import_utils = require("./themes/utils");
-var import_primordials = require("./primordials");
+module.exports = __toCommonJS(link_exports);
+var import_yoctocolors_cjs = __toESM(require("../external/yoctocolors-cjs"));
+var import_array = require("../primordials/array");
+var import_context = require("../themes/context");
+var import_themes = require("../themes/themes");
+var import_resolve = require("../themes/resolve");
 function link(text, url, options) {
   const opts = { __proto__: null, fallback: false, ...options };
   const theme = typeof opts.theme === "string" ? import_themes.THEMES[opts.theme] : opts.theme ?? (0, import_context.getTheme)();
-  const linkColor = (0, import_utils.resolveColor)(theme.colors.link, theme.colors);
+  const linkColor = (0, import_resolve.resolveColor)(theme.colors.link, theme.colors);
   const colors = import_yoctocolors_cjs.default;
   let colored;
   if (typeof linkColor === "string" && linkColor !== "inherit") {
     const colorMethod = colors[linkColor];
     colored = colorMethod ? colorMethod(text) : colors.cyan(text);
-  } else if ((0, import_primordials.ArrayIsArray)(linkColor)) {
+  } else if ((0, import_array.ArrayIsArray)(linkColor)) {
     colored = colors.cyan(text);
   } else {
     colored = colors.cyan(text);

package/dist/links/types.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @file Public type surface for `links/*` modules — the `LinkOptions` record.
+ *   Pure types, no runtime side effects.
+ */
+import type { ThemeName } from '../themes/themes';
+import type { Theme } from '../themes/types';
+/**
+ * Options for creating themed links.
+ */
+export type LinkOptions = {
+    /**
+     * Theme to use (overrides global)
+     */
+    theme?: Theme | ThemeName | undefined;
+    /**
+     * Show URL as fallback if terminal doesn't support links.
+     */
+    fallback?: boolean | undefined;
+};

package/dist/links/types.js

@@ -0,0 +1,18 @@
+"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 __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 types_exports = {};
+module.exports = __toCommonJS(types_exports);

package/dist/logger/_internal.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @file Private state shared between the `logger/logger` class (which owns the
+ *   public `Logger` surface) and `logger/console-init` (which mutates
+ *   `Logger.prototype` to mirror `globalConsole`). The `_` prefix keeps this
+ *   module out of the generated package.json `exports` map (the `dist/**\/_*`
+ *   ignore pattern in `scripts/fix/generate-package-exports.mts` filters it
+ *   out), so it is not part of the public surface — it exists only to give the
+ *   two leaves above a common owner for the WeakMap-backed lazy-init state. Why
+ *   two WeakMaps instead of `#privateField` slots:
+ *
+ *   - Logger adds dynamic console methods to its prototype at first use (see
+ *     `console-init.ts` `ensurePrototypeInitialized`). Those dynamic methods
+ *     are constructed via the `{ [key]: function () }` shorthand and CANNOT
+ *     access TC39 private fields on `this`.
+ *   - WeakMaps work for both the static methods on the `Logger` class body AND
+ *     the dynamically-attached prototype methods. WeakMap entries are GC'd
+ *     alongside the `Logger` instance.
+ *   - `privateConstructorArgs` is deleted after first `Console` build so we don't
+ *     pin the original args for the lifetime of the logger.
+ */
+/**
+ * The global `console` reference captured at module load. Pinned to a local so
+ * dynamic `console` overrides at runtime can't affect the logger's source
+ * console (e.g., test rewiring of `globalThis.console`).
+ */
+export declare const globalConsole: Console;
+/**
+ * Property-descriptor template used when registering dynamic console methods on
+ * `Logger.prototype`. Writable + configurable so tests can override;
+ * non-enumerable so the methods don't leak into `for...in` iteration on a
+ * logger instance.
+ */
+export declare const consolePropAttributes: {
+    __proto__: null;
+    writable: boolean;
+    enumerable: boolean;
+    configurable: boolean;
+};
+/**
+ * Cap on the indentation prefix length so a runaway `indent(n)` call with a
+ * huge `n` can't allocate a multi-megabyte string.
+ */
+export declare const maxIndentation = 1000;
+/**
+ * Pre-bound copies of the console methods that need their original `this` to
+ * function (e.g., `console.error.bind(globalConsole)`). Mapping `[name,
+ * boundFn]` so `console-init.ts` can apply them onto the per-instance Console
+ * without re-binding on every call.
+ *
+ * Notes from the upstream Node implementation:
+ *
+ * - `_stderrErrorHandler` / `_stdoutErrorHandler` are `kBindProperties`
+ *   properties — they live on the per-instance Console and need their `this`
+ *   set to `globalConsole`.
+ *   https://github.com/nodejs/node/blob/v24.0.1/lib/internal/console/constructor.js#L230-L265
+ * - `group` / `groupCollapsed` / `groupEnd` are explicitly skipped because Node
+ *   20 with `--frozen-intrinsics` makes `Symbol(kGroupIndent)` read-only, which
+ *   the Logger's own group methods avoid by tracking indentation at the prefix
+ *   layer.
+ */
+export declare const boundConsoleEntries: any[][];
+/**
+ * WeakMap storing the Console instance for each Logger.
+ *
+ * Console creation is lazy - deferred until first logging method call. This
+ * allows logger to be imported during early Node.js bootstrap before stdout is
+ * ready, avoiding ERR_CONSOLE_WRITABLE_STREAM errors.
+ */
+export declare const privateConsole: WeakMap<WeakKey, any>;
+/**
+ * WeakMap storing constructor arguments for lazy Console initialization.
+ *
+ * WeakMap is required instead of a private field (#constructorArgs) because: 1.
+ * Private fields can't be accessed from dynamically created functions 2. Logger
+ * adds console methods dynamically to its prototype 3. These dynamic methods
+ * need constructor args for lazy initialization 4. WeakMap allows both regular
+ * methods and dynamic functions to access args.
+ *
+ * The args are deleted from the WeakMap after Console is created (memory
+ * cleanup).
+ */
+export declare const privateConstructorArgs: WeakMap<WeakKey, any>;