@socketsecurity/lib 2.4.0 → 2.6.0

package/CHANGELOG.md

@@ -5,6 +5,36 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.6.0](https://github.com/SocketDev/socket-lib/releases/tag/v2.6.0) - 2025-10-28
+
+### Changed
+
+- **Process locking aligned with npm npx**: Enhanced process-lock module to match npm's npx locking strategy
+  - Reduced stale timeout from 10 seconds to 5 seconds (matches npm npx)
+  - Added periodic lock touching (2-second interval) to prevent false stale detection during long operations
+  - Implemented second-level granularity for mtime comparison to avoid APFS floating-point precision issues
+  - Added automatic touch timer cleanup on process exit
+  - Timers use `unref()` to prevent keeping process alive
+  - Aligns with npm's npx implementation per https://github.com/npm/cli/pull/8512
+
+## [2.5.0](https://github.com/SocketDev/socket-lib/releases/tag/v2.5.0) - 2025-10-28
+
+### Added
+
+- **Process locking utilities**: Added `ProcessLockManager` class providing cross-platform inter-process synchronization using file-system based locks
+  - Atomic lock acquisition via `mkdir()` for thread-safe operations
+  - Stale lock detection with automatic cleanup (default 10 seconds, aligned with npm's npx strategy)
+  - Exponential backoff with jitter for retry attempts
+  - Process exit handlers for guaranteed cleanup even on abnormal termination
+  - Three main APIs: `acquire()`, `release()`, and `withLock()` (recommended)
+  - Comprehensive test suite with `describe.sequential` for proper isolation
+  - Export: `@socketsecurity/lib/process-lock`
+
+### Changed
+
+- **Script refactoring**: Renamed `spinner.succeed()` to `spinner.success()` for consistency
+- **Script cleanup**: Removed redundant spinner cleanup in interactive-runner
+
 ## [2.4.0](https://github.com/SocketDev/socket-lib/releases/tag/v2.4.0) - 2025-10-28
 
 ### Changed

package/dist/process-lock.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Lock acquisition options.
+ */
+export interface ProcessLockOptions {
+    /**
+     * Maximum number of retry attempts.
+     * @default 3
+     */
+    retries?: number | undefined;
+    /**
+     * Base delay between retries in milliseconds.
+     * @default 100
+     */
+    baseDelayMs?: number | undefined;
+    /**
+     * Maximum delay between retries in milliseconds.
+     * @default 1000
+     */
+    maxDelayMs?: number | undefined;
+    /**
+     * Stale lock timeout in milliseconds.
+     * Locks older than this are considered abandoned and can be reclaimed.
+     * Aligned with npm's npx locking strategy (5 seconds).
+     * @default 5000 (5 seconds)
+     */
+    staleMs?: number | undefined;
+    /**
+     * Interval for touching lock file to keep it fresh in milliseconds.
+     * Set to 0 to disable periodic touching.
+     * @default 2000 (2 seconds)
+     */
+    touchIntervalMs?: number | undefined;
+}
+/**
+ * Process lock manager with stale detection and exit cleanup.
+ * Provides cross-platform inter-process synchronization using file-system
+ * based locks.
+ */
+declare class ProcessLockManager {
+    private activeLocks;
+    private touchTimers;
+    private exitHandlerRegistered;
+    /**
+     * Ensure process exit handler is registered for cleanup.
+     * Registers a handler that cleans up all active locks when the process exits.
+     */
+    private ensureExitHandler;
+    /**
+     * Touch a lock file to update its mtime.
+     * This prevents the lock from being detected as stale during long operations.
+     *
+     * @param lockPath - Path to the lock directory
+     */
+    private touchLock;
+    /**
+     * Start periodic touching of a lock file.
+     * Aligned with npm npx strategy to prevent false stale detection.
+     *
+     * @param lockPath - Path to the lock directory
+     * @param intervalMs - Touch interval in milliseconds
+     */
+    private startTouchTimer;
+    /**
+     * Stop periodic touching of a lock file.
+     *
+     * @param lockPath - Path to the lock directory
+     */
+    private stopTouchTimer;
+    /**
+     * Check if a lock is stale based on mtime.
+     * Uses second-level granularity to avoid APFS floating-point precision issues.
+     * Aligned with npm's npx locking strategy.
+     *
+     * @param lockPath - Path to the lock directory
+     * @param staleMs - Stale timeout in milliseconds
+     * @returns True if lock exists and is stale
+     */
+    private isStale;
+    /**
+     * Acquire a lock using mkdir for atomic operation.
+     * Handles stale locks and includes exit cleanup.
+     *
+     * This method attempts to create a lock directory atomically. If the lock
+     * already exists, it checks if it's stale and removes it before retrying.
+     * Uses exponential backoff with jitter for retry attempts.
+     *
+     * @param lockPath - Path to the lock directory
+     * @param options - Lock acquisition options
+     * @returns Release function to unlock
+     * @throws Error if lock cannot be acquired after all retries
+     *
+     * @example
+     * ```typescript
+     * const release = await processLock.acquire('/tmp/my-lock')
+     * try {
+     *   // Critical section
+     * } finally {
+     *   release()
+     * }
+     * ```
+     */
+    acquire(lockPath: string, options?: ProcessLockOptions): Promise<() => void>;
+    /**
+     * Release a lock and remove from tracking.
+     * Stops periodic touching and removes the lock directory.
+     *
+     * @param lockPath - Path to the lock directory
+     *
+     * @example
+     * ```typescript
+     * processLock.release('/tmp/my-lock')
+     * ```
+     */
+    release(lockPath: string): void;
+    /**
+     * Execute a function with exclusive lock protection.
+     * Automatically handles lock acquisition, execution, and cleanup.
+     *
+     * This is the recommended way to use process locks, as it guarantees
+     * cleanup even if the callback throws an error.
+     *
+     * @param lockPath - Path to the lock directory
+     * @param fn - Function to execute while holding the lock
+     * @param options - Lock acquisition options
+     * @returns Result of the callback function
+     * @throws Error from callback or lock acquisition failure
+     *
+     * @example
+     * ```typescript
+     * const result = await processLock.withLock('/tmp/my-lock', async () => {
+     *   // Critical section
+     *   return someValue
+     * })
+     * ```
+     */
+    withLock<T>(lockPath: string, fn: () => Promise<T>, options?: ProcessLockOptions): Promise<T>;
+}
+// Export singleton instance.
+export declare const processLock: ProcessLockManager;
+export {};

package/dist/process-lock.js

@@ -0,0 +1,3 @@
+/* Socket Lib - Built with esbuild */
+var m=Object.defineProperty;var v=Object.getOwnPropertyDescriptor;var g=Object.getOwnPropertyNames;var p=Object.prototype.hasOwnProperty;var y=(n,e)=>{for(var r in e)m(n,r,{get:e[r],enumerable:!0})},T=(n,e,r,s)=>{if(e&&typeof e=="object"||typeof e=="function")for(let i of g(e))!p.call(n,i)&&i!==r&&m(n,i,{get:()=>e[i],enumerable:!(s=v(e,i))||s.enumerable});return n};var w=n=>T(m({},"__esModule",{value:!0}),n);var x={};y(x,{processLock:()=>L});module.exports=w(x);var t=require("node:fs"),o=require("./fs"),a=require("./logger"),f=require("./promises"),l=require("./signal-exit");class S{activeLocks=new Set;touchTimers=new Map;exitHandlerRegistered=!1;ensureExitHandler(){this.exitHandlerRegistered||((0,l.onExit)(()=>{for(const e of this.touchTimers.values())clearInterval(e);this.touchTimers.clear();for(const e of this.activeLocks)try{(0,t.existsSync)(e)&&(0,o.safeDeleteSync)(e,{recursive:!0})}catch{}}),this.exitHandlerRegistered=!0)}touchLock(e){try{if((0,t.existsSync)(e)){const r=new Date;(0,t.utimesSync)(e,r,r)}}catch(r){a.logger.warn(`Failed to touch lock ${e}: ${r instanceof Error?r.message:String(r)}`)}}startTouchTimer(e,r){if(r<=0||this.touchTimers.has(e))return;const s=setInterval(()=>{this.touchLock(e)},r);s.unref(),this.touchTimers.set(e,s)}stopTouchTimer(e){const r=this.touchTimers.get(e);r&&(clearInterval(r),this.touchTimers.delete(e))}isStale(e,r){try{if(!(0,t.existsSync)(e))return!1;const s=(0,t.statSync)(e),i=Math.floor((Date.now()-s.mtime.getTime())/1e3),c=Math.floor(r/1e3);return i>c}catch{return!1}}async acquire(e,r={}){const{baseDelayMs:s=100,maxDelayMs:i=1e3,retries:c=3,staleMs:d=5e3,touchIntervalMs:h=2e3}=r;return this.ensureExitHandler(),await(0,f.pRetry)(async()=>{try{if((0,t.existsSync)(e)&&this.isStale(e,d)){a.logger.log(`Removing stale lock: ${e}`);try{(0,o.safeDeleteSync)(e,{recursive:!0})}catch{}}return(0,t.mkdirSync)(e,{recursive:!1}),this.activeLocks.add(e),this.startTouchTimer(e,h),()=>this.release(e)}catch(u){throw u instanceof Error&&u.code==="EEXIST"?this.isStale(e,d)?new Error(`Stale lock detected: ${e}`):new Error(`Lock already exists: ${e}`):u}},{retries:c,baseDelayMs:s,maxDelayMs:i,jitter:!0})}release(e){this.stopTouchTimer(e);try{(0,t.existsSync)(e)&&(0,o.safeDeleteSync)(e,{recursive:!0}),this.activeLocks.delete(e)}catch(r){a.logger.warn(`Failed to release lock ${e}: ${r instanceof Error?r.message:String(r)}`)}}async withLock(e,r,s){const i=await this.acquire(e,s);try{return await r()}finally{i()}}}const L=new S;0&&(module.exports={processLock});
+//# sourceMappingURL=process-lock.js.map

package/dist/process-lock.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/process-lock.ts"],
+  "sourcesContent": ["/**\n * @fileoverview Process locking utilities with stale detection and exit cleanup.\n * Provides cross-platform inter-process synchronization using file-system based locks.\n * Aligned with npm's npx locking strategy (5-second stale timeout, periodic touching).\n */\n\nimport { existsSync, mkdirSync, statSync, utimesSync } from 'node:fs'\n\nimport { safeDeleteSync } from './fs'\nimport { logger } from './logger'\nimport { pRetry } from './promises'\nimport { onExit } from './signal-exit'\n\n/**\n * Lock acquisition options.\n */\nexport interface ProcessLockOptions {\n  /**\n   * Maximum number of retry attempts.\n   * @default 3\n   */\n  retries?: number | undefined\n\n  /**\n   * Base delay between retries in milliseconds.\n   * @default 100\n   */\n  baseDelayMs?: number | undefined\n\n  /**\n   * Maximum delay between retries in milliseconds.\n   * @default 1000\n   */\n  maxDelayMs?: number | undefined\n\n  /**\n   * Stale lock timeout in milliseconds.\n   * Locks older than this are considered abandoned and can be reclaimed.\n   * Aligned with npm's npx locking strategy (5 seconds).\n   * @default 5000 (5 seconds)\n   */\n  staleMs?: number | undefined\n\n  /**\n   * Interval for touching lock file to keep it fresh in milliseconds.\n   * Set to 0 to disable periodic touching.\n   * @default 2000 (2 seconds)\n   */\n  touchIntervalMs?: number | undefined\n}\n\n/**\n * Process lock manager with stale detection and exit cleanup.\n * Provides cross-platform inter-process synchronization using file-system\n * based locks.\n */\nclass ProcessLockManager {\n  private activeLocks = new Set<string>()\n  private touchTimers = new Map<string, NodeJS.Timeout>()\n  private exitHandlerRegistered = false\n\n  /**\n   * Ensure process exit handler is registered for cleanup.\n   * Registers a handler that cleans up all active locks when the process exits.\n   */\n  private ensureExitHandler() {\n    if (this.exitHandlerRegistered) {\n      return\n    }\n\n    onExit(() => {\n      // Clear all touch timers.\n      for (const timer of this.touchTimers.values()) {\n        clearInterval(timer)\n      }\n      this.touchTimers.clear()\n\n      // Clean up all active locks.\n      for (const lockPath of this.activeLocks) {\n        try {\n          if (existsSync(lockPath)) {\n            safeDeleteSync(lockPath, { recursive: true })\n          }\n        } catch {\n          // Ignore cleanup errors during exit.\n        }\n      }\n    })\n\n    this.exitHandlerRegistered = true\n  }\n\n  /**\n   * Touch a lock file to update its mtime.\n   * This prevents the lock from being detected as stale during long operations.\n   *\n   * @param lockPath - Path to the lock directory\n   */\n  private touchLock(lockPath: string): void {\n    try {\n      if (existsSync(lockPath)) {\n        const now = new Date()\n        utimesSync(lockPath, now, now)\n      }\n    } catch (error) {\n      logger.warn(\n        `Failed to touch lock ${lockPath}: ${error instanceof Error ? error.message : String(error)}`,\n      )\n    }\n  }\n\n  /**\n   * Start periodic touching of a lock file.\n   * Aligned with npm npx strategy to prevent false stale detection.\n   *\n   * @param lockPath - Path to the lock directory\n   * @param intervalMs - Touch interval in milliseconds\n   */\n  private startTouchTimer(lockPath: string, intervalMs: number): void {\n    if (intervalMs <= 0 || this.touchTimers.has(lockPath)) {\n      return\n    }\n\n    const timer = setInterval(() => {\n      this.touchLock(lockPath)\n    }, intervalMs)\n\n    // Prevent timer from keeping process alive.\n    timer.unref()\n\n    this.touchTimers.set(lockPath, timer)\n  }\n\n  /**\n   * Stop periodic touching of a lock file.\n   *\n   * @param lockPath - Path to the lock directory\n   */\n  private stopTouchTimer(lockPath: string): void {\n    const timer = this.touchTimers.get(lockPath)\n    if (timer) {\n      clearInterval(timer)\n      this.touchTimers.delete(lockPath)\n    }\n  }\n\n  /**\n   * Check if a lock is stale based on mtime.\n   * Uses second-level granularity to avoid APFS floating-point precision issues.\n   * Aligned with npm's npx locking strategy.\n   *\n   * @param lockPath - Path to the lock directory\n   * @param staleMs - Stale timeout in milliseconds\n   * @returns True if lock exists and is stale\n   */\n  private isStale(lockPath: string, staleMs: number): boolean {\n    try {\n      if (!existsSync(lockPath)) {\n        return false\n      }\n\n      const stats = statSync(lockPath)\n      // Use second-level granularity to avoid APFS issues.\n      const ageSeconds = Math.floor((Date.now() - stats.mtime.getTime()) / 1000)\n      const staleSeconds = Math.floor(staleMs / 1000)\n      return ageSeconds > staleSeconds\n    } catch {\n      return false\n    }\n  }\n\n  /**\n   * Acquire a lock using mkdir for atomic operation.\n   * Handles stale locks and includes exit cleanup.\n   *\n   * This method attempts to create a lock directory atomically. If the lock\n   * already exists, it checks if it's stale and removes it before retrying.\n   * Uses exponential backoff with jitter for retry attempts.\n   *\n   * @param lockPath - Path to the lock directory\n   * @param options - Lock acquisition options\n   * @returns Release function to unlock\n   * @throws Error if lock cannot be acquired after all retries\n   *\n   * @example\n   * ```typescript\n   * const release = await processLock.acquire('/tmp/my-lock')\n   * try {\n   *   // Critical section\n   * } finally {\n   *   release()\n   * }\n   * ```\n   */\n  async acquire(\n    lockPath: string,\n    options: ProcessLockOptions = {},\n  ): Promise<() => void> {\n    const {\n      baseDelayMs = 100,\n      maxDelayMs = 1000,\n      retries = 3,\n      staleMs = 5000,\n      touchIntervalMs = 2000,\n    } = options\n\n    // Ensure exit handler is registered before any lock acquisition.\n    this.ensureExitHandler()\n\n    return await pRetry(\n      async () => {\n        try {\n          // Check for stale lock and remove if necessary.\n          if (existsSync(lockPath) && this.isStale(lockPath, staleMs)) {\n            logger.log(`Removing stale lock: ${lockPath}`)\n            try {\n              safeDeleteSync(lockPath, { recursive: true })\n            } catch {\n              // Ignore errors removing stale lock - will retry.\n            }\n          }\n\n          // Atomic lock acquisition via mkdir.\n          mkdirSync(lockPath, { recursive: false })\n\n          // Track lock for cleanup.\n          this.activeLocks.add(lockPath)\n\n          // Start periodic touching to prevent stale detection.\n          this.startTouchTimer(lockPath, touchIntervalMs)\n\n          // Return release function.\n          return () => this.release(lockPath)\n        } catch (error) {\n          // Handle lock contention.\n          if (error instanceof Error && (error as any).code === 'EEXIST') {\n            if (this.isStale(lockPath, staleMs)) {\n              throw new Error(`Stale lock detected: ${lockPath}`)\n            }\n            throw new Error(`Lock already exists: ${lockPath}`)\n          }\n          throw error\n        }\n      },\n      {\n        retries,\n        baseDelayMs,\n        maxDelayMs,\n        jitter: true,\n      },\n    )\n  }\n\n  /**\n   * Release a lock and remove from tracking.\n   * Stops periodic touching and removes the lock directory.\n   *\n   * @param lockPath - Path to the lock directory\n   *\n   * @example\n   * ```typescript\n   * processLock.release('/tmp/my-lock')\n   * ```\n   */\n  release(lockPath: string): void {\n    // Stop periodic touching.\n    this.stopTouchTimer(lockPath)\n\n    try {\n      if (existsSync(lockPath)) {\n        safeDeleteSync(lockPath, { recursive: true })\n      }\n      this.activeLocks.delete(lockPath)\n    } catch (error) {\n      logger.warn(\n        `Failed to release lock ${lockPath}: ${error instanceof Error ? error.message : String(error)}`,\n      )\n    }\n  }\n\n  /**\n   * Execute a function with exclusive lock protection.\n   * Automatically handles lock acquisition, execution, and cleanup.\n   *\n   * This is the recommended way to use process locks, as it guarantees\n   * cleanup even if the callback throws an error.\n   *\n   * @param lockPath - Path to the lock directory\n   * @param fn - Function to execute while holding the lock\n   * @param options - Lock acquisition options\n   * @returns Result of the callback function\n   * @throws Error from callback or lock acquisition failure\n   *\n   * @example\n   * ```typescript\n   * const result = await processLock.withLock('/tmp/my-lock', async () => {\n   *   // Critical section\n   *   return someValue\n   * })\n   * ```\n   */\n  async withLock<T>(\n    lockPath: string,\n    fn: () => Promise<T>,\n    options?: ProcessLockOptions,\n  ): Promise<T> {\n    const release = await this.acquire(lockPath, options)\n    try {\n      return await fn()\n    } finally {\n      release()\n    }\n  }\n}\n\n// Export singleton instance.\nexport const processLock = new ProcessLockManager()\n"],
+  "mappings": "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",
+  "names": ["process_lock_exports", "__export", "processLock", "__toCommonJS", "import_node_fs", "import_fs", "import_logger", "import_promises", "import_signal_exit", "ProcessLockManager", "timer", "lockPath", "now", "error", "intervalMs", "staleMs", "stats", "ageSeconds", "staleSeconds", "options", "baseDelayMs", "maxDelayMs", "retries", "touchIntervalMs", "fn", "release"]
+}

package/dist/validation/types.d.ts

@@ -104,7 +104,7 @@ export interface JsonParseOptions {
      * Maximum allowed size of JSON string in bytes.
      * Prevents memory exhaustion from extremely large payloads.
      *
-     * @default 10485760 (10 MB)
+     * @default 10_485_760 (10 MB)
      *
      * @example
      * ```ts

package/dist/validation/types.js.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/validation/types.ts"],
-  "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"],
+  "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 10_485_760 (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": ";kWAAA,IAAAA,EAAA,kBAAAC,EAAAD",
   "names": ["types_exports", "__toCommonJS"]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@socketsecurity/lib",
-  "version": "2.4.0",
+  "version": "2.6.0",
   "license": "MIT",
   "description": "Core utilities and infrastructure for Socket.dev security tools",
   "keywords": [
@@ -384,6 +384,10 @@
       "types": "./plugins/babel-plugin-inline-require-calls.d.ts",
       "default": "./plugins/babel-plugin-inline-require-calls.js"
     },
+    "./process-lock": {
+      "types": "./dist/process-lock.d.ts",
+      "default": "./dist/process-lock.js"
+    },
     "./promise-queue": {
       "types": "./dist/promise-queue.d.ts",
       "default": "./dist/promise-queue.js"