@socketsecurity/lib 5.18.2 → 5.19.1

package/dist/validation/json-parser.d.ts

@@ -1,21 +1,23 @@
 /**
  * @fileoverview Safe JSON parsing with validation and security controls.
- * Provides protection against prototype pollution, size limits, and schema validation.
+ * Provides protection against prototype pollution, size limits, and schema
+ * validation.
  *
  * Key Features:
- * - Prototype pollution protection: Blocks `__proto__`, `constructor`, and `prototype` keys
- * - Size limits: Configurable maximum JSON string size (default 10MB)
- * - Schema validation: Optional Zod-compatible schema validation
- * - NDJSON support: Parse newline-delimited JSON streams
- * - Memory safety: Prevents memory exhaustion attacks
+ * - Prototype pollution protection: Blocks `__proto__`, `constructor`, and
+ *   `prototype` keys via JSON.parse reviver at any depth.
+ * - Size limits: Configurable maximum JSON string size (default 10MB).
+ * - Schema validation: Optional Zod-compatible schema validation.
+ * - Memory safety: Prevents memory exhaustion attacks.
  */
-import type { JsonParseOptions, JsonParseResult, Schema } from './types';
+import type { SafeJsonParseOptions, Schema } from './types';
 /**
  * Safely parse JSON with optional schema validation and security controls.
  * Throws errors on parse failures, validation failures, or security violations.
  *
- * This is the recommended method for parsing untrusted JSON input as it provides
- * multiple layers of security including prototype pollution protection and size limits.
+ * This is the recommended method for parsing untrusted JSON input as it
+ * provides multiple layers of security including prototype pollution
+ * protection and size limits.
  *
  * @template T - The expected type of the parsed data
  * @param jsonString - The JSON string to parse
@@ -23,10 +25,11 @@ import type { JsonParseOptions, JsonParseResult, Schema } from './types';
  * @param options - Parsing options for security and behavior control
  * @returns The parsed and validated data
  *
- * @throws {Error} When JSON string exceeds `maxSize`
- * @throws {Error} When JSON parsing fails
- * @throws {Error} When prototype pollution keys are detected (unless `allowPrototype` is `true`)
- * @throws {Error} When schema validation fails
+ * @throws {Error} When JSON string exceeds `maxSize`.
+ * @throws {Error} When JSON parsing fails.
+ * @throws {Error} When prototype pollution keys are detected (unless
+ *   `allowPrototype` is `true`).
+ * @throws {Error} When schema validation fails.
  *
  * @example
  * ```ts
@@ -46,184 +49,10 @@ import type { JsonParseOptions, JsonParseResult, Schema } from './types';
  *   maxSize: 1024 * 1024 // 1MB
  * })
  *
- * // Allow prototype keys (dangerous - only for trusted sources)
- * const data = safeJsonParse(jsonString, undefined, {
+ * // Allow prototype keys (DANGEROUS — only for trusted sources)
+ * const data = safeJsonParse('{"__proto__": {}}', undefined, {
  *   allowPrototype: true
  * })
  * ```
  */
-export declare function safeJsonParse<T = unknown>(jsonString: string, schema?: Schema<T> | undefined, options?: JsonParseOptions): T;
-/**
- * Attempt to parse JSON, returning `undefined` on any error.
- * This is a non-throwing wrapper around `safeJsonParse` for cases where
- * you want to gracefully handle parse failures without try-catch blocks.
- *
- * Use this when parsing is optional or you have a fallback strategy.
- * For critical parsing where you need error details, use `safeJsonParse` or `parseJsonWithResult`.
- *
- * @template T - The expected type of the parsed data
- * @param jsonString - The JSON string to parse
- * @param schema - Optional Zod-compatible schema for validation
- * @param options - Parsing options for security and behavior control
- * @returns The parsed data on success, or `undefined` on any error
- *
- * @example
- * ```ts
- * // Graceful fallback to default
- * const config = tryJsonParse<Config>(jsonString) ?? defaultConfig
- *
- * // Optional parsing
- * const data = tryJsonParse(possiblyInvalidJson)
- * if (data) {
- *   console.log('Parsed successfully:', data)
- * }
- *
- * // With schema validation
- * const user = tryJsonParse(jsonString, userSchema)
- * ```
- */
-export declare function tryJsonParse<T = unknown>(jsonString: string, schema?: Schema<T> | undefined, options?: JsonParseOptions | undefined): T | undefined;
-/**
- * Parse JSON and return a discriminated union result.
- * Never throws - always returns a result object with success/failure information.
- *
- * This is ideal when you need detailed error messages and type-safe result handling.
- * The discriminated union allows TypeScript to narrow types based on the `success` flag.
- *
- * @template T - The expected type of the parsed data
- * @param jsonString - The JSON string to parse
- * @param schema - Optional Zod-compatible schema for validation
- * @param options - Parsing options for security and behavior control
- * @returns Result object with either `{success: true, data}` or `{success: false, error}`
- *
- * @example
- * ```ts
- * // Type-safe error handling
- * const result = parseJsonWithResult<User>(jsonString, userSchema)
- *
- * if (result.success) {
- *   // TypeScript knows result.data is available
- *   console.log(`User: ${result.data.name}`)
- * } else {
- *   // TypeScript knows result.error is available
- *   console.error(`Parse failed: ${result.error}`)
- * }
- *
- * // Early return pattern
- * const result = parseJsonWithResult(jsonString)
- * if (!result.success) {
- *   logger.error(result.error)
- *   return
- * }
- * processData(result.data)
- * ```
- */
-export declare function parseJsonWithResult<T = unknown>(jsonString: string, schema?: Schema<T> | undefined, options?: JsonParseOptions | undefined): JsonParseResult<T>;
-/**
- * Create a reusable JSON parser with pre-configured schema and options.
- * Useful for parsing multiple JSON strings with the same validation rules.
- *
- * The returned parser function can accept per-call options that override the defaults.
- * This factory pattern reduces repetition when parsing many similar JSON payloads.
- *
- * @template T - The expected type of the parsed data
- * @param schema - Optional Zod-compatible schema for validation
- * @param defaultOptions - Default parsing options applied to all parse calls
- * @returns A parser function that accepts a JSON string and optional per-call options
- *
- * @example
- * ```ts
- * // Create a parser for API responses
- * import { z } from 'zod'
- * const apiResponseSchema = z.object({
- *   status: z.string(),
- *   data: z.unknown()
- * })
- *
- * const parseApiResponse = createJsonParser(apiResponseSchema, {
- *   maxSize: 5 * 1024 * 1024 // 5MB limit for API responses
- * })
- *
- * // Use the parser multiple times
- * const response1 = parseApiResponse(json1)
- * const response2 = parseApiResponse(json2)
- *
- * // Override options for specific calls
- * const response3 = parseApiResponse(json3, { maxSize: 10 * 1024 * 1024 })
- * ```
- */
-export declare function createJsonParser<T = unknown>(schema?: Schema<T> | undefined, defaultOptions?: JsonParseOptions | undefined): (jsonString: string, options?: JsonParseOptions) => T;
-/**
- * Parse newline-delimited JSON (NDJSON) into an array.
- * Each line is treated as a separate JSON object. Empty lines are skipped.
- *
- * NDJSON format is commonly used for streaming logs, bulk data transfers,
- * and event streams where each line represents a complete JSON document.
- *
- * @template T - The expected type of each parsed JSON object
- * @param ndjson - Newline-delimited JSON string (supports both `\n` and `\r\n`)
- * @param schema - Optional Zod-compatible schema for validation of each line
- * @param options - Parsing options applied to each line
- * @returns Array of parsed objects, one per non-empty line
- *
- * @throws {Error} When any line fails to parse (includes line number in error message)
- *
- * @example
- * ```ts
- * // Parse NDJSON logs
- * const ndjsonString = `
- * {"level":"info","message":"Server started"}
- * {"level":"error","message":"Connection failed"}
- * {"level":"info","message":"Retrying..."}
- * `
- * const logs = parseNdjson<LogEntry>(ndjsonString, logSchema)
- * console.log(logs.length) // 3
- *
- * // Parse with size limits per line
- * const entries = parseNdjson(ndjson, undefined, { maxSize: 1024 })
- *
- * // Empty lines are automatically skipped
- * const data = parseNdjson('{"a":1}\n\n{"b":2}\n') // 2 objects
- * ```
- */
-export declare function parseNdjson<T = unknown>(ndjson: string, schema?: Schema<T> | undefined, options?: JsonParseOptions | undefined): T[];
-/**
- * Stream-parse newline-delimited JSON (NDJSON) using a generator.
- * Yields one parsed object at a time, enabling memory-efficient processing of large NDJSON files.
- *
- * Unlike `parseNdjson` which loads all results into memory, this generator allows
- * processing each line individually, making it ideal for large datasets or streaming scenarios.
- *
- * @template T - The expected type of each parsed JSON object
- * @param ndjson - Newline-delimited JSON string (supports both `\n` and `\r\n`)
- * @param schema - Optional Zod-compatible schema for validation of each line
- * @param options - Parsing options applied to each line
- * @yields Parsed objects one at a time as the generator iterates
- *
- * @throws {Error} When any line fails to parse (includes line number in error message)
- *
- * @example
- * ```ts
- * // Memory-efficient processing of large NDJSON files
- * const ndjsonString = readLargeFile('logs.ndjson')
- *
- * for (const log of streamNdjson<LogEntry>(ndjsonString, logSchema)) {
- *   if (log.level === 'error') {
- *     console.error('Error found:', log.message)
- *   }
- * }
- *
- * // Collect filtered results without loading everything
- * const errors = [...streamNdjson(ndjson)]
- *   .filter(log => log.level === 'error')
- *
- * // Early termination when condition is met
- * for (const entry of streamNdjson(ndjson)) {
- *   if (entry.id === targetId) {
- *     processEntry(entry)
- *     break // Stop processing remaining lines
- *   }
- * }
- * ```
- */
-export declare function streamNdjson<T = unknown>(ndjson: string, schema?: Schema<T> | undefined, options?: JsonParseOptions | undefined): Generator<T, void, unknown>;
+export declare function safeJsonParse<T = unknown>(jsonString: string, schema?: Schema<T> | undefined, options?: SafeJsonParseOptions): T;

package/dist/validation/json-parser.js

@@ -1,5 +1,6 @@
 "use strict";
 /* Socket Lib - Built with esbuild */
+"use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
@@ -19,12 +20,7 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var json_parser_exports = {};
 __export(json_parser_exports, {
-  createJsonParser: () => createJsonParser,
-  parseJsonWithResult: () => parseJsonWithResult,
-  parseNdjson: () => parseNdjson,
-  safeJsonParse: () => safeJsonParse,
-  streamNdjson: () => streamNdjson,
-  tryJsonParse: () => tryJsonParse
+  safeJsonParse: () => safeJsonParse
 });
 module.exports = __toCommonJS(json_parser_exports);
 const DANGEROUS_KEYS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
@@ -53,75 +49,15 @@ function safeJsonParse(jsonString, schema, options = {}) {
   if (schema) {
     const result = schema.safeParse(parsed);
     if (!result.success) {
-      const errors = result.error.issues.map(
-        (issue) => `${issue.path.join(".")}: ${issue.message}`
-      ).join(", ");
+      const error = result.error;
+      const errors = error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join(", ");
       throw new Error(`Validation failed: ${errors}`);
     }
     return result.data;
   }
   return parsed;
 }
-function tryJsonParse(jsonString, schema, options) {
-  try {
-    return safeJsonParse(jsonString, schema, options);
-  } catch {
-    return void 0;
-  }
-}
-function parseJsonWithResult(jsonString, schema, options) {
-  try {
-    const data = safeJsonParse(jsonString, schema, options);
-    return { success: true, data };
-  } catch (error) {
-    const message = error instanceof Error ? error.message : "Unknown error";
-    return { success: false, error: message };
-  }
-}
-function createJsonParser(schema, defaultOptions) {
-  return (jsonString, options) => {
-    return safeJsonParse(jsonString, schema, { ...defaultOptions, ...options });
-  };
-}
-function parseNdjson(ndjson, schema, options) {
-  const results = [];
-  const lines = ndjson.split(/\r?\n/);
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i]?.trim();
-    if (!line || line === "") {
-      continue;
-    }
-    try {
-      const parsed = safeJsonParse(line, schema, options);
-      results.push(parsed);
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      throw new Error(`Failed to parse NDJSON at line ${i + 1}: ${message}`);
-    }
-  }
-  return results;
-}
-function* streamNdjson(ndjson, schema, options) {
-  const lines = ndjson.split(/\r?\n/);
-  for (let i = 0; i < lines.length; i++) {
-    const line = lines[i]?.trim();
-    if (!line || line === "") {
-      continue;
-    }
-    try {
-      yield safeJsonParse(line, schema, options);
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      throw new Error(`Failed to parse NDJSON at line ${i + 1}: ${message}`);
-    }
-  }
-}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  createJsonParser,
-  parseJsonWithResult,
-  parseNdjson,
-  safeJsonParse,
-  streamNdjson,
-  tryJsonParse
+  safeJsonParse
 });

package/dist/validation/types.d.ts

@@ -24,7 +24,7 @@ export interface ParseResult<T> {
     /** Parsed and validated data (only present when `success` is `true`) */
     data?: T | undefined;
     /** Error information (only present when `success` is `false`) */
-    error?: any;
+    error?: unknown;
 }
 /**
  * Base schema interface compatible with Zod and similar validation libraries.
@@ -46,7 +46,7 @@ export interface ParseResult<T> {
  * const result = schema.safeParse({ name: 'Alice', age: 30 })
  * ```
  */
-export interface Schema<T = any> {
+export interface Schema<T = unknown> {
     /**
      * Safely parse data without throwing errors.
      * Returns a result object indicating success or failure.
@@ -54,7 +54,7 @@ export interface Schema<T = any> {
      * @param data - The data to validate
      * @returns Parse result with success flag and data or error
      */
-    safeParse(data: any): ParseResult<T>;
+    safeParse(data: unknown): ParseResult<T>;
     /**
      * Parse data and throw an error if validation fails.
      * Use this when you want to fail fast on invalid data.
@@ -63,7 +63,7 @@ export interface Schema<T = any> {
      * @returns The validated and parsed data
      * @throws {Error} When validation fails
      */
-    parse(data: any): T;
+    parse(data: unknown): T;
     /**
      * Optional schema name for debugging and error messages.
      * Useful for identifying which schema failed in complex validation chains.
@@ -71,17 +71,19 @@ export interface Schema<T = any> {
     _name?: string | undefined;
 }
 /**
- * Options for configuring JSON parsing behavior with security controls.
+ * Options for configuring safe JSON parsing with security controls.
+ * Distinct from `JsonParseOptions` in `@socketsecurity/lib/json/types`
+ * which is scoped to reviver/error-handling for fs-oriented JSON reads.
  *
  * @example
  * ```ts
- * const options: JsonParseOptions = {
+ * const options: SafeJsonParseOptions = {
  *   maxSize: 1024 * 1024, // 1MB limit
  *   allowPrototype: false // Block prototype pollution
  * }
  * ```
  */
-export interface JsonParseOptions {
+export interface SafeJsonParseOptions {
     /**
      * Allow dangerous prototype pollution keys (`__proto__`, `constructor`, `prototype`).
      * Set to `true` only if you trust the JSON source completely.
@@ -114,29 +116,3 @@ export interface JsonParseOptions {
      */
     maxSize?: number | undefined;
 }
-/**
- * Discriminated union type for JSON parsing results.
- * Enables type-safe handling of success and failure cases.
- *
- * @template T - The expected type of the parsed data
- *
- * @example
- * ```ts
- * const result: JsonParseResult<User> = parseJsonWithResult(jsonString)
- *
- * if (result.success) {
- *   // TypeScript knows result.data is available
- *   console.log(result.data.name)
- * } else {
- *   // TypeScript knows result.error is available
- *   console.error(result.error)
- * }
- * ```
- */
-export type JsonParseResult<T> = {
-    success: true;
-    data: T;
-} | {
-    success: false;
-    error: string;
-};

package/dist/validation/types.js

@@ -1,5 +1,6 @@
 "use strict";
 /* Socket Lib - Built with esbuild */
+"use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;

package/dist/versions.d.ts

@@ -1,3 +1,4 @@
+/** @fileoverview Version comparison and validation utilities for Socket ecosystem. */
 /**
  * Coerce a version string to valid semver format.
  *

package/dist/versions.js

@@ -1,5 +1,6 @@
 "use strict";
 /* Socket Lib - Built with esbuild */
+"use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
@@ -44,7 +45,7 @@ module.exports = __toCommonJS(versions_exports);
 let _semver;
 function getSemver() {
   if (_semver === void 0) {
-    _semver = require("./external/semver.js");
+    _semver = require("./external/semver");
   }
   return _semver;
 }

package/dist/words.d.ts

@@ -2,6 +2,9 @@
  * @fileoverview Word manipulation utilities for capitalization and formatting.
  * Provides text transformation functions for consistent word processing.
  */
+export interface PluralizeOptions {
+    count?: number;
+}
 /**
  * Capitalize the first letter of a word.
  *
@@ -12,7 +15,6 @@
  * capitalize('')       // ''
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function capitalize(word: string): string;
 /**
  * Determine the appropriate article (a/an) for a word.
@@ -23,11 +25,7 @@ export declare function capitalize(word: string): string;
  * determineArticle('banana')  // 'a'
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function determineArticle(word: string): string;
-export interface PluralizeOptions {
-    count?: number;
-}
 /**
  * Pluralize a word based on count.
  *
@@ -38,5 +36,4 @@ export interface PluralizeOptions {
  * pluralize('file', { count: 0 }) // 'files'
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function pluralize(word: string, options?: PluralizeOptions | undefined): string;

package/dist/words.js

@@ -1,5 +1,6 @@
 "use strict";
 /* Socket Lib - Built with esbuild */
+"use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;

package/dist/zod.js

@@ -1,5 +1,6 @@
 "use strict";
 /* Socket Lib - Built with esbuild */
+"use strict";
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;