@socketsecurity/lib 1.0.4 → 1.1.0

package/dist/validation/types.d.ts

@@ -1,35 +1,137 @@
 /**
  * @fileoverview Validation type definitions.
+ * Provides core types for schema validation and JSON parsing with security features.
  */
 /**
- * Schema parse result.
+ * Result of a schema validation operation.
+ * Contains either successful parsed data or error information.
+ *
+ * @template T - The expected type of the parsed data
+ *
+ * @example
+ * ```ts
+ * const result: ParseResult<User> = schema.safeParse(data)
+ * if (result.success) {
+ *   console.log(result.data) // User object
+ * } else {
+ *   console.error(result.error) // Error details
+ * }
+ * ```
  */
 export interface ParseResult<T> {
+    /** Indicates whether parsing was successful */
     success: boolean;
-    data?: T;
-    // biome-ignore lint/suspicious/noExplicitAny: Error can be any schema validation error.
+    /** Parsed and validated data (only present when `success` is `true`) */
+    data?: T | undefined;
+    /** Error information (only present when `success` is `false`) */
     error?: any;
 }
 /**
- * Base schema interface.
+ * Base schema interface compatible with Zod and similar validation libraries.
+ * Provides both safe and throwing parsing methods.
+ *
+ * @template T - The expected output type after validation
+ *
+ * @example
+ * ```ts
+ * import { z } from 'zod'
+ *
+ * const userSchema = z.object({
+ *   name: z.string(),
+ *   age: z.number()
+ * })
+ *
+ * // Schema satisfies this interface
+ * const schema: Schema<User> = userSchema
+ * const result = schema.safeParse({ name: 'Alice', age: 30 })
+ * ```
  */
-// biome-ignore lint/suspicious/noExplicitAny: Schema interface accepts any input data for validation.
 export interface Schema<T = any> {
-    // biome-ignore lint/suspicious/noExplicitAny: Validation accepts any input data.
+    /**
+     * Safely parse data without throwing errors.
+     * Returns a result object indicating success or failure.
+     *
+     * @param data - The data to validate
+     * @returns Parse result with success flag and data or error
+     */
     safeParse(data: any): ParseResult<T>;
-    // biome-ignore lint/suspicious/noExplicitAny: Validation accepts any input data.
+    /**
+     * Parse data and throw an error if validation fails.
+     * Use this when you want to fail fast on invalid data.
+     *
+     * @param data - The data to validate
+     * @returns The validated and parsed data
+     * @throws {Error} When validation fails
+     */
     parse(data: any): T;
-    _name?: string;
+    /**
+     * Optional schema name for debugging and error messages.
+     * Useful for identifying which schema failed in complex validation chains.
+     */
+    _name?: string | undefined;
 }
 /**
- * JSON parse options.
+ * Options for configuring JSON parsing behavior with security controls.
+ *
+ * @example
+ * ```ts
+ * const options: JsonParseOptions = {
+ *   maxSize: 1024 * 1024, // 1MB limit
+ *   allowPrototype: false // Block prototype pollution
+ * }
+ * ```
  */
 export interface JsonParseOptions {
-    maxSize?: number;
-    allowPrototype?: boolean;
+    /**
+     * Allow dangerous prototype pollution keys (`__proto__`, `constructor`, `prototype`).
+     * Set to `true` only if you trust the JSON source completely.
+     *
+     * @default false
+     *
+     * @example
+     * ```ts
+     * // Will throw error by default
+     * safeJsonParse('{"__proto__": {"polluted": true}}')
+     *
+     * // Allows the parse (dangerous!)
+     * safeJsonParse('{"__proto__": {"polluted": true}}', undefined, {
+     *   allowPrototype: true
+     * })
+     * ```
+     */
+    allowPrototype?: boolean | undefined;
+    /**
+     * Maximum allowed size of JSON string in bytes.
+     * Prevents memory exhaustion from extremely large payloads.
+     *
+     * @default 10485760 (10 MB)
+     *
+     * @example
+     * ```ts
+     * // Limit to 1KB
+     * safeJsonParse(jsonString, undefined, { maxSize: 1024 })
+     * ```
+     */
+    maxSize?: number | undefined;
 }
 /**
- * JSON parse result.
+ * 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;

package/dist/validation/types.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/validation/types.ts"],
-  "sourcesContent": ["/**\n * @fileoverview Validation type definitions.\n */\n\n/**\n * Schema parse result.\n */\nexport interface ParseResult<T> {\n  success: boolean\n  data?: T\n  // biome-ignore lint/suspicious/noExplicitAny: Error can be any schema validation error.\n  error?: any\n}\n\n/**\n * Base schema interface.\n */\n// biome-ignore lint/suspicious/noExplicitAny: Schema interface accepts any input data for validation.\nexport interface Schema<T = any> {\n  // biome-ignore lint/suspicious/noExplicitAny: Validation accepts any input data.\n  safeParse(data: any): ParseResult<T>\n  // biome-ignore lint/suspicious/noExplicitAny: Validation accepts any input data.\n  parse(data: any): T\n  _name?: string\n}\n\n/**\n * JSON parse options.\n */\nexport interface JsonParseOptions {\n  maxSize?: number\n  allowPrototype?: boolean\n}\n\n/**\n * JSON parse result.\n */\nexport type JsonParseResult<T> =\n  | { success: true; data: T }\n  | { success: false; error: string }\n"],
+  "sourcesContent": ["/**\n * @fileoverview Validation type definitions.\n * Provides core types for schema validation and JSON parsing with security features.\n */\n\n/**\n * Result of a schema validation operation.\n * Contains either successful parsed data or error information.\n *\n * @template T - The expected type of the parsed data\n *\n * @example\n * ```ts\n * const result: ParseResult<User> = schema.safeParse(data)\n * if (result.success) {\n *   console.log(result.data) // User object\n * } else {\n *   console.error(result.error) // Error details\n * }\n * ```\n */\nexport interface ParseResult<T> {\n  /** Indicates whether parsing was successful */\n  success: boolean\n  /** Parsed and validated data (only present when `success` is `true`) */\n  data?: T | undefined\n  /** Error information (only present when `success` is `false`) */\n  error?: any\n}\n\n/**\n * Base schema interface compatible with Zod and similar validation libraries.\n * Provides both safe and throwing parsing methods.\n *\n * @template T - The expected output type after validation\n *\n * @example\n * ```ts\n * import { z } from 'zod'\n *\n * const userSchema = z.object({\n *   name: z.string(),\n *   age: z.number()\n * })\n *\n * // Schema satisfies this interface\n * const schema: Schema<User> = userSchema\n * const result = schema.safeParse({ name: 'Alice', age: 30 })\n * ```\n */\nexport interface Schema<T = any> {\n  /**\n   * Safely parse data without throwing errors.\n   * Returns a result object indicating success or failure.\n   *\n   * @param data - The data to validate\n   * @returns Parse result with success flag and data or error\n   */\n  safeParse(data: any): ParseResult<T>\n\n  /**\n   * Parse data and throw an error if validation fails.\n   * Use this when you want to fail fast on invalid data.\n   *\n   * @param data - The data to validate\n   * @returns The validated and parsed data\n   * @throws {Error} When validation fails\n   */\n  parse(data: any): T\n\n  /**\n   * Optional schema name for debugging and error messages.\n   * Useful for identifying which schema failed in complex validation chains.\n   */\n  _name?: string | undefined\n}\n\n/**\n * Options for configuring JSON parsing behavior with security controls.\n *\n * @example\n * ```ts\n * const options: JsonParseOptions = {\n *   maxSize: 1024 * 1024, // 1MB limit\n *   allowPrototype: false // Block prototype pollution\n * }\n * ```\n */\nexport interface JsonParseOptions {\n  /**\n   * Allow dangerous prototype pollution keys (`__proto__`, `constructor`, `prototype`).\n   * Set to `true` only if you trust the JSON source completely.\n   *\n   * @default false\n   *\n   * @example\n   * ```ts\n   * // Will throw error by default\n   * safeJsonParse('{\"__proto__\": {\"polluted\": true}}')\n   *\n   * // Allows the parse (dangerous!)\n   * safeJsonParse('{\"__proto__\": {\"polluted\": true}}', undefined, {\n   *   allowPrototype: true\n   * })\n   * ```\n   */\n  allowPrototype?: boolean | undefined\n\n  /**\n   * Maximum allowed size of JSON string in bytes.\n   * Prevents memory exhaustion from extremely large payloads.\n   *\n   * @default 10485760 (10 MB)\n   *\n   * @example\n   * ```ts\n   * // Limit to 1KB\n   * safeJsonParse(jsonString, undefined, { maxSize: 1024 })\n   * ```\n   */\n  maxSize?: number | undefined\n}\n\n/**\n * Discriminated union type for JSON parsing results.\n * Enables type-safe handling of success and failure cases.\n *\n * @template T - The expected type of the parsed data\n *\n * @example\n * ```ts\n * const result: JsonParseResult<User> = parseJsonWithResult(jsonString)\n *\n * if (result.success) {\n *   // TypeScript knows result.data is available\n *   console.log(result.data.name)\n * } else {\n *   // TypeScript knows result.error is available\n *   console.error(result.error)\n * }\n * ```\n */\nexport type JsonParseResult<T> =\n  | { success: true; data: T }\n  | { success: false; error: string }\n"],
   "mappings": ";;;;;;;;;;;;;;AAAA;AAAA;",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@socketsecurity/lib",
-  "version": "1.0.4",
+  "version": "1.1.0",
   "license": "MIT",
   "description": "Core utilities and infrastructure for Socket.dev security tools",
   "keywords": [
@@ -697,7 +697,8 @@
     "./package.json": "./package.json",
     "./taze.config.json": "./taze.config.json",
     "./tsconfig.dts.json": "./tsconfig.dts.json",
-    "./tsconfig.json": "./tsconfig.json"
+    "./tsconfig.json": "./tsconfig.json",
+    "./tsconfig.test.json": "./tsconfig.test.json"
   },
   "imports": {
     "#constants/*": "./dist/constants/*.js",
@@ -732,7 +733,8 @@
     "prepublishOnly": "pnpm run build",
     "test": "node scripts/test.mjs",
     "test-ci": "vitest run",
-    "type-ci": "pnpm run check"
+    "type-ci": "pnpm run check",
+    "update": "node scripts/update.mjs"
   },
   "devDependencies": {
     "@babel/core": "7.28.4",