@socketsecurity/lib 5.18.1 → 5.19.0

package/dist/url.d.ts

@@ -1,3 +1,32 @@
+/**
+ * @fileoverview URL parsing and validation utilities.
+ * Provides URL validation, normalization, and parsing helpers.
+ */
+export interface CreateRelativeUrlOptions {
+    base?: string;
+}
+export interface UrlSearchParamAsBooleanOptions {
+    defaultValue?: boolean;
+}
+export interface UrlSearchParamAsNumberOptions {
+    defaultValue?: number;
+}
+export interface UrlSearchParamAsStringOptions {
+    defaultValue?: string;
+}
+export interface UrlSearchParamsGetBooleanOptions {
+    defaultValue?: boolean;
+}
+/**
+ * Create a relative URL for testing.
+ *
+ * @example
+ * ```typescript
+ * createRelativeUrl('/api/test')                                    // 'api/test'
+ * createRelativeUrl('/api/test', { base: 'https://example.com' })  // 'https://example.com/api/test'
+ * ```
+ */
+export declare function createRelativeUrl(path: string, options?: CreateRelativeUrlOptions | undefined): string;
 /**
  * Check if a value is a valid URL.
  *
@@ -8,7 +37,6 @@
  * isUrl(null)                  // false
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function isUrl(value: string | URL | null | undefined): boolean;
 /**
  * Parse a value as a URL.
@@ -19,7 +47,6 @@ export declare function isUrl(value: string | URL | null | undefined): boolean;
  * parseUrl('invalid')              // undefined
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function parseUrl(value: string | URL): URL | undefined;
 /**
  * Convert a URL search parameter to an array.
@@ -30,11 +57,7 @@ export declare function parseUrl(value: string | URL): URL | undefined;
  * urlSearchParamAsArray(null)      // []
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function urlSearchParamAsArray(value: string | null | undefined): string[];
-export interface UrlSearchParamAsBooleanOptions {
-    defaultValue?: boolean;
-}
 /**
  * Convert a URL search parameter to a boolean.
  *
@@ -45,75 +68,47 @@ export interface UrlSearchParamAsBooleanOptions {
  * urlSearchParamAsBoolean(null)   // false
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
 export declare function urlSearchParamAsBoolean(value: string | null | undefined, options?: UrlSearchParamAsBooleanOptions | undefined): boolean;
 /**
- * Helper to get array from URLSearchParams.
- *
- * @example
- * ```typescript
- * const params = new URLSearchParams('tags=a,b,c')
- * urlSearchParamsGetArray(params, 'tags') // ['a', 'b', 'c']
- * ```
- */
-/*@__NO_SIDE_EFFECTS__*/
-export declare function urlSearchParamsGetArray(params: URLSearchParams | null | undefined, key: string): string[];
-export interface UrlSearchParamsGetBooleanOptions {
-    defaultValue?: boolean;
-}
-/**
- * Helper to get boolean from URLSearchParams.
+ * Get number value from URLSearchParams with a default.
  *
  * @example
  * ```typescript
- * const params = new URLSearchParams('debug=true')
- * urlSearchParamsGetBoolean(params, 'debug') // true
- * urlSearchParamsGetBoolean(params, 'other') // false
+ * const params = new URLSearchParams('limit=10')
+ * urlSearchParamAsNumber(params, 'limit') // 10
+ * urlSearchParamAsNumber(params, 'other') // 0
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
-export declare function urlSearchParamsGetBoolean(params: URLSearchParams | null | undefined, key: string, options?: UrlSearchParamsGetBooleanOptions | undefined): boolean;
-export interface CreateRelativeUrlOptions {
-    base?: string;
-}
+export declare function urlSearchParamAsNumber(params: URLSearchParams | null | undefined, key: string, options?: UrlSearchParamAsNumberOptions | undefined): number;
 /**
- * Create a relative URL for testing.
+ * Get string value from URLSearchParams with a default.
  *
  * @example
  * ```typescript
- * createRelativeUrl('/api/test')                                    // 'api/test'
- * createRelativeUrl('/api/test', { base: 'https://example.com' })  // 'https://example.com/api/test'
+ * const params = new URLSearchParams('name=socket')
+ * urlSearchParamAsString(params, 'name')  // 'socket'
+ * urlSearchParamAsString(params, 'other') // ''
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
-export declare function createRelativeUrl(path: string, options?: CreateRelativeUrlOptions | undefined): string;
-export interface UrlSearchParamAsStringOptions {
-    defaultValue?: string;
-}
+export declare function urlSearchParamAsString(params: URLSearchParams | null | undefined, key: string, options?: UrlSearchParamAsStringOptions | undefined): string;
 /**
- * Get string value from URLSearchParams with a default.
+ * Helper to get array from URLSearchParams.
  *
  * @example
  * ```typescript
- * const params = new URLSearchParams('name=socket')
- * urlSearchParamAsString(params, 'name')  // 'socket'
- * urlSearchParamAsString(params, 'other') // ''
+ * const params = new URLSearchParams('tags=a,b,c')
+ * urlSearchParamsGetArray(params, 'tags') // ['a', 'b', 'c']
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
-export declare function urlSearchParamAsString(params: URLSearchParams | null | undefined, key: string, options?: UrlSearchParamAsStringOptions | undefined): string;
-export interface UrlSearchParamAsNumberOptions {
-    defaultValue?: number;
-}
+export declare function urlSearchParamsGetArray(params: URLSearchParams | null | undefined, key: string): string[];
 /**
- * Get number value from URLSearchParams with a default.
+ * Helper to get boolean from URLSearchParams.
  *
  * @example
  * ```typescript
- * const params = new URLSearchParams('limit=10')
- * urlSearchParamAsNumber(params, 'limit') // 10
- * urlSearchParamAsNumber(params, 'other') // 0
+ * const params = new URLSearchParams('debug=true')
+ * urlSearchParamsGetBoolean(params, 'debug') // true
+ * urlSearchParamsGetBoolean(params, 'other') // false
  * ```
  */
-/*@__NO_SIDE_EFFECTS__*/
-export declare function urlSearchParamAsNumber(params: URLSearchParams | null | undefined, key: string, options?: UrlSearchParamAsNumberOptions | undefined): number;
+export declare function urlSearchParamsGetBoolean(params: URLSearchParams | null | undefined, key: string, options?: UrlSearchParamsGetBooleanOptions | undefined): boolean;

package/dist/url.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;
@@ -33,6 +34,22 @@ module.exports = __toCommonJS(url_exports);
 const BooleanCtor = Boolean;
 const UrlCtor = URL;
 // @__NO_SIDE_EFFECTS__
+function createRelativeUrl(path, options) {
+  const { base = "" } = {
+    __proto__: null,
+    ...options
+  };
+  const relativePath = path.replace(/^\//, "");
+  if (base) {
+    let baseUrl = base;
+    if (!baseUrl.endsWith("/")) {
+      baseUrl += "/";
+    }
+    return baseUrl + relativePath;
+  }
+  return relativePath;
+}
+// @__NO_SIDE_EFFECTS__
 function isUrl(value) {
   return (typeof value === "string" && value !== "" || value !== null && typeof value === "object") && !!/* @__PURE__ */ parseUrl(value);
 }
@@ -64,44 +81,19 @@ function urlSearchParamAsBoolean(value, options) {
   return !!value;
 }
 // @__NO_SIDE_EFFECTS__
-function urlSearchParamsGetArray(params, key) {
-  if (params && typeof params.getAll === "function") {
-    const values = params.getAll(key);
-    const firstValue = values[0];
-    if (values.length === 1 && firstValue && firstValue.includes(",")) {
-      return /* @__PURE__ */ urlSearchParamAsArray(firstValue);
-    }
-    return values;
-  }
-  return [];
-}
-// @__NO_SIDE_EFFECTS__
-function urlSearchParamsGetBoolean(params, key, options) {
-  const { defaultValue = false } = {
+function urlSearchParamAsNumber(params, key, options) {
+  const { defaultValue = 0 } = {
     __proto__: null,
     ...options
   };
   if (params && typeof params.get === "function") {
     const value = params.get(key);
-    return value !== null ? /* @__PURE__ */ urlSearchParamAsBoolean(value, { defaultValue }) : defaultValue;
-  }
-  return defaultValue;
-}
-// @__NO_SIDE_EFFECTS__
-function createRelativeUrl(path, options) {
-  const { base = "" } = {
-    __proto__: null,
-    ...options
-  };
-  const relativePath = path.replace(/^\//, "");
-  if (base) {
-    let baseUrl = base;
-    if (!baseUrl.endsWith("/")) {
-      baseUrl += "/";
+    if (value !== null) {
+      const num = Number(value);
+      return !Number.isNaN(num) ? num : defaultValue;
     }
-    return baseUrl + relativePath;
   }
-  return relativePath;
+  return defaultValue;
 }
 // @__NO_SIDE_EFFECTS__
 function urlSearchParamAsString(params, key, options) {
@@ -116,17 +108,26 @@ function urlSearchParamAsString(params, key, options) {
   return defaultValue;
 }
 // @__NO_SIDE_EFFECTS__
-function urlSearchParamAsNumber(params, key, options) {
-  const { defaultValue = 0 } = {
+function urlSearchParamsGetArray(params, key) {
+  if (params && typeof params.getAll === "function") {
+    const values = params.getAll(key);
+    const firstValue = values[0];
+    if (values.length === 1 && firstValue && firstValue.includes(",")) {
+      return /* @__PURE__ */ urlSearchParamAsArray(firstValue);
+    }
+    return values;
+  }
+  return [];
+}
+// @__NO_SIDE_EFFECTS__
+function urlSearchParamsGetBoolean(params, key, options) {
+  const { defaultValue = false } = {
     __proto__: null,
     ...options
   };
   if (params && typeof params.get === "function") {
     const value = params.get(key);
-    if (value !== null) {
-      const num = Number(value);
-      return !Number.isNaN(num) ? num : defaultValue;
-    }
+    return value !== null ? /* @__PURE__ */ urlSearchParamAsBoolean(value, { defaultValue }) : defaultValue;
   }
   return defaultValue;
 }

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
 });