@socketsecurity/lib 5.27.0 → 6.0.0

package/dist/json/parse.d.ts

@@ -1,123 +1,148 @@
 /**
- * @fileoverview JSON parsing utilities with Buffer detection and BOM stripping.
- * Provides safe JSON parsing with automatic encoding handling, plus
- * `safeJsonParse` for untrusted input (prototype-pollution protection +
- * size limits + optional schema validation).
+ * @file JSON parsing utilities with Buffer detection and BOM stripping.
+ *   Provides safe JSON parsing with automatic encoding handling, plus
+ *   `parseJsonSafe` for untrusted input (prototype-pollution protection + size
+ *   limits + optional schema validation).
  */
 import type { Schema } from '../schema/types';
-import type { JsonParseOptions, JsonPrimitive, JsonValue, SafeJsonParseOptions } from './types';
+import type { ParseJsonOptions, JsonPrimitive, JsonValue, ParseJsonSafeOptions } from './types';
 /**
- * Check if a value is a JSON primitive type.
- * JSON primitives are: `null`, `boolean`, `number`, or `string`.
- *
- * @param value - Value to check
- * @returns `true` if value is a JSON primitive, `false` otherwise
+ * Check if a value is a Buffer instance. Uses duck-typing to detect Buffer
+ * without requiring Node.js Buffer in type system.
  *
  * @example
- * ```ts
- * isJsonPrimitive(null) // => true
- * isJsonPrimitive(true) // => true
- * isJsonPrimitive(42) // => true
- * isJsonPrimitive('hello') // => true
- * isJsonPrimitive({}) // => false
- * isJsonPrimitive([]) // => false
- * isJsonPrimitive(undefined) // => false
- * ```
+ *   ;```ts
+ *   isBuffer(Buffer.from('hello')) // => true
+ *   isBuffer('hello') // => false
+ *   isBuffer({ length: 5 }) // => false
+ *   ```
+ *
+ * @param x - Value to check.
+ *
+ * @returns `true` if value is a Buffer, `false` otherwise
  */
-export declare function isJsonPrimitive(value: unknown): value is JsonPrimitive;
+export declare function isBuffer(x: unknown): x is Buffer;
 /**
- * Parse JSON content with automatic Buffer handling and BOM stripping.
- * Provides safer JSON parsing with helpful error messages and optional error suppression.
+ * Check if a value is a JSON primitive type. JSON primitives are: `null`,
+ * `boolean`, `number`, or `string`.
  *
- * Features:
- * - Automatic UTF-8 Buffer conversion
- * - BOM (Byte Order Mark) stripping for cross-platform compatibility
- * - Enhanced error messages with filepath context
- * - Optional error suppression (returns `undefined` instead of throwing)
- * - Optional reviver for transforming parsed values
+ * @example
+ *   ;```ts
+ *   isJsonPrimitive(null) // => true
+ *   isJsonPrimitive(true) // => true
+ *   isJsonPrimitive(42) // => true
+ *   isJsonPrimitive('hello') // => true
+ *   isJsonPrimitive({}) // => false
+ *   isJsonPrimitive([]) // => false
+ *   isJsonPrimitive(undefined) // => false
+ *   ```
+ *
+ * @param value - Value to check.
  *
- * @param content - JSON string or Buffer to parse
- * @param options - Optional parsing configuration
- * @returns Parsed JSON value, or `undefined` if parsing fails and `throws` is `false`
+ * @returns `true` if value is a JSON primitive, `false` otherwise
+ */
+export declare function isJsonPrimitive(value: unknown): value is JsonPrimitive;
+/**
+ * Parse JSON content with automatic Buffer handling and BOM stripping. Provides
+ * safer JSON parsing with helpful error messages and optional error
+ * suppression.
  *
- * @throws {SyntaxError} When JSON is invalid and `throws` is `true` (default)
+ * Features: - Automatic UTF-8 Buffer conversion - BOM (Byte Order Mark)
+ * stripping for cross-platform compatibility - Enhanced error messages with
+ * filepath context - Optional error suppression (returns `undefined` instead of
+ * throwing) - Optional reviver for transforming parsed values.
  *
  * @example
- * ```ts
- * // Basic usage
- * const data = jsonParse('{"name":"example"}')
- * console.log(data.name) // => 'example'
- *
- * // Parse Buffer with UTF-8 BOM
- * const buffer = Buffer.from('\uFEFF{"value":42}')
- * const data = jsonParse(buffer)
- * console.log(data.value) // => 42
- *
- * // Enhanced error messages with filepath
- * try {
- *   jsonParse('invalid', { filepath: 'config.json' })
- * } catch (e) {
- *   console.error(e.message)
- *   // => "config.json: Unexpected token i in JSON at position 0"
- * }
- *
- * // Suppress errors
- * const result = jsonParse('invalid', { throws: false })
- * console.log(result) // => undefined
- *
- * // Transform values with reviver
- * const json = '{"created":"2024-01-15T10:30:00Z"}'
- * const data = jsonParse(json, {
- *   reviver: (key, value) => {
- *     if (key === 'created' && typeof value === 'string') {
- *       return new Date(value)
- *     }
- *     return value
+ *   ;```ts
+ *   // Basic usage
+ *   const data = parseJson('{"name":"example"}')
+ *   console.log(data.name) // => 'example'
+ *
+ *   // Parse Buffer with UTF-8 BOM
+ *   const buffer = Buffer.from('\uFEFF{"value":42}')
+ *   const data = parseJson(buffer)
+ *   console.log(data.value) // => 42
+ *
+ *   // Enhanced error messages with filepath
+ *   try {
+ *     parseJson('invalid', { filepath: 'config.json' })
+ *   } catch (e) {
+ *     console.error(e.message)
+ *     // => "config.json: Unexpected token i in JSON at position 0"
  *   }
- * })
- * console.log(data.created instanceof Date) // => true
- * ```
+ *
+ *   // Suppress errors
+ *   const result = parseJson('invalid', { throws: false })
+ *   console.log(result) // => undefined
+ *
+ *   // Transform values with reviver
+ *   const json = '{"created":"2024-01-15T10:30:00Z"}'
+ *   const data = parseJson(json, {
+ *     reviver: (key, value) => {
+ *       if (key === 'created' && typeof value === 'string') {
+ *         return new Date(value)
+ *       }
+ *       return value
+ *     },
+ *   })
+ *   console.log(data.created instanceof Date) // => true
+ *   ```
+ *
+ * @param content - JSON string or Buffer to parse.
+ * @param options - Optional parsing configuration.
+ *
+ * @returns Parsed JSON value, or `undefined` if parsing fails and `throws` is
+ *   `false`
+ *
+ * @throws {SyntaxError} When JSON is invalid and `throws` is `true` (default)
  */
-export declare function jsonParse(content: string | Buffer, options?: JsonParseOptions | undefined): JsonValue | undefined;
+export declare function parseJson(content: string | Buffer, options?: ParseJsonOptions | undefined): JsonValue | undefined;
 /**
  * Safely parse JSON with optional schema validation and security controls.
  * Throws on parse failure, validation failure, or security violation.
  *
  * Recommended for parsing untrusted JSON (user input, network payloads,
  * anything beyond a trust boundary). Layers:
+ *
  * 1. Size cap (default 10 MB) prevents memory exhaustion.
- * 2. Prototype-pollution reviver rejects `__proto__` / `constructor` /
- *    `prototype` keys at any depth (unless `allowPrototype: true`).
+ * 2. Prototype-pollution reviver rejects `__proto__` / `constructor` / `prototype`
+ *    keys at any depth (unless `allowPrototype: true`).
  * 3. Optional Zod-shaped schema validation via
  *    `@socketsecurity/lib/schema/validate`.
  *
  * For trusted-source reads (package.json, local config files), prefer
- * `jsonParse()` — it offers Buffer/BOM handling and filepath-aware error
+ * `parseJson()` — it offers Buffer/BOM handling and filepath-aware error
  * messages, without the untrusted-input overhead.
  *
+ * @example
+ *   ;```ts
+ *   // Basic parsing with type inference.
+ *   const data = parseJsonSafe<User>('{"name":"Alice","age":30}')
+ *
+ *   // With schema validation.
+ *   import { z } from 'zod'
+ *   const userSchema = z.object({ name: z.string(), age: z.number() })
+ *   const user = parseJsonSafe('{"name":"Alice","age":30}', userSchema)
+ *
+ *   // With size limit.
+ *   const data = parseJsonSafe(jsonString, undefined, { maxSize: 1024 })
+ *
+ *   // Allow prototype keys (DANGEROUS — only for trusted sources).
+ *   const data = parseJsonSafe('{"__proto__":{}}', undefined, {
+ *     allowPrototype: true,
+ *   })
+ *   ```
+ *
  * @throws {Error} When `jsonString` exceeds `maxSize`.
  * @throws {Error} When JSON parsing fails.
  * @throws {Error} When prototype-pollution keys are detected (and
  *   `allowPrototype` is not `true`).
  * @throws {Error} When schema validation fails.
+ */
+export declare function parseJsonSafe<T = unknown>(jsonString: string, schema?: Schema<T> | undefined, options?: ParseJsonSafeOptions): T;
+/**
+ * JSON.parse reviver that rejects prototype pollution keys at any depth.
  *
- * @example
- * ```ts
- * // Basic parsing with type inference.
- * const data = safeJsonParse<User>('{"name":"Alice","age":30}')
- *
- * // With schema validation.
- * import { z } from 'zod'
- * const userSchema = z.object({ name: z.string(), age: z.number() })
- * const user = safeJsonParse('{"name":"Alice","age":30}', userSchema)
- *
- * // With size limit.
- * const data = safeJsonParse(jsonString, undefined, { maxSize: 1024 })
- *
- * // Allow prototype keys (DANGEROUS — only for trusted sources).
- * const data = safeJsonParse('{"__proto__":{}}', undefined, {
- *   allowPrototype: true,
- * })
- * ```
+ * @internal
  */
-export declare function safeJsonParse<T = unknown>(jsonString: string, schema?: Schema<T> | undefined, options?: SafeJsonParseOptions): T;
+export declare function prototypePollutionReviver(key: string, value: unknown): unknown;

package/dist/json/parse.js

@@ -20,15 +20,19 @@ var __copyProps = (to, from, except, desc) => {
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 var parse_exports = {};
 __export(parse_exports, {
+  isBuffer: () => isBuffer,
   isJsonPrimitive: () => isJsonPrimitive,
-  jsonParse: () => jsonParse,
-  safeJsonParse: () => safeJsonParse
+  parseJson: () => parseJson,
+  parseJsonSafe: () => parseJsonSafe,
+  prototypePollutionReviver: () => prototypePollutionReviver
 });
 module.exports = __toCommonJS(parse_exports);
 var import_validate = require("../schema/validate");
-var import_strings = require("../strings");
-var import_primordials = require("../primordials");
-const JSONParse = JSON.parse;
+var import_transform = require("../strings/transform");
+var import_buffer = require("../primordials/buffer");
+var import_error = require("../primordials/error");
+var import_json = require("../primordials/json");
+var import_map_set = require("../primordials/map-set");
 // @__NO_SIDE_EFFECTS__
 function isBuffer(x) {
   if (!x || typeof x !== "object") {
@@ -52,7 +56,7 @@ function isJsonPrimitive(value) {
   return value === null || typeof value === "boolean" || typeof value === "number" || typeof value === "string";
 }
 // @__NO_SIDE_EFFECTS__
-function jsonParse(content, options) {
+function parseJson(content, options) {
   const { filepath, reviver, throws } = {
     __proto__: null,
     ...options
@@ -60,7 +64,7 @@ function jsonParse(content, options) {
   const shouldThrow = throws === void 0 || !!throws;
   const jsonStr = /* @__PURE__ */ isBuffer(content) ? content.toString("utf8") : content;
   try {
-    return JSONParse((0, import_strings.stripBom)(jsonStr), reviver);
+    return (0, import_json.JSONParse)((0, import_transform.stripBom)(jsonStr), reviver);
   } catch (e) {
     if (shouldThrow) {
       const error = e;
@@ -72,44 +76,46 @@ function jsonParse(content, options) {
   }
   return void 0;
 }
-const DANGEROUS_KEYS = new import_primordials.SetCtor(["__proto__", "constructor", "prototype"]);
-function prototypePollutionReviver(key, value) {
-  if (DANGEROUS_KEYS.has(key)) {
-    throw new import_primordials.ErrorCtor(
-      "JSON contains potentially malicious prototype pollution keys"
-    );
-  }
-  return value;
-}
+const DANGEROUS_KEYS = new import_map_set.SetCtor(["__proto__", "constructor", "prototype"]);
 const DEFAULT_MAX_SIZE = 10 * 1024 * 1024;
 // @__NO_SIDE_EFFECTS__
-function safeJsonParse(jsonString, schema, options = {}) {
+function parseJsonSafe(jsonString, schema, options = {}) {
   const { allowPrototype = false, maxSize = DEFAULT_MAX_SIZE } = options;
-  const byteLength = (0, import_primordials.BufferByteLength)(jsonString, "utf8");
+  const byteLength = (0, import_buffer.BufferByteLength)(jsonString, "utf8");
   if (byteLength > maxSize) {
-    throw new import_primordials.ErrorCtor(
+    throw new import_error.ErrorCtor(
       `JSON string exceeds maximum size limit${maxSize !== DEFAULT_MAX_SIZE ? ` of ${maxSize} bytes` : ""}`
     );
   }
   let parsed;
   try {
-    parsed = allowPrototype ? JSONParse(jsonString) : JSONParse(jsonString, prototypePollutionReviver);
+    parsed = allowPrototype ? (0, import_json.JSONParse)(jsonString) : (0, import_json.JSONParse)(jsonString, prototypePollutionReviver);
   } catch (e) {
-    throw new import_primordials.ErrorCtor(`Failed to parse JSON: ${e}`);
+    throw new import_error.ErrorCtor(`Failed to parse JSON: ${e}`);
   }
   if (schema) {
     const result = (0, import_validate.validateSchema)(schema, parsed);
     if (!result.ok) {
       const summary = result.errors.map((e) => `${e.path.join(".") || "(root)"}: ${e.message}`).join(", ");
-      throw new import_primordials.ErrorCtor(`Validation failed: ${summary}`);
+      throw new import_error.ErrorCtor(`Validation failed: ${summary}`);
     }
     return result.value;
   }
   return parsed;
 }
+function prototypePollutionReviver(key, value) {
+  if (DANGEROUS_KEYS.has(key)) {
+    throw new import_error.ErrorCtor(
+      "JSON contains potentially malicious prototype pollution keys"
+    );
+  }
+  return value;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  isBuffer,
   isJsonPrimitive,
-  jsonParse,
-  safeJsonParse
+  parseJson,
+  parseJsonSafe,
+  prototypePollutionReviver
 });