@socketsecurity/lib 5.18.2 → 5.19.0

package/dist/performance.d.ts

@@ -1,28 +1,82 @@
+/**
+ * @fileoverview Performance monitoring utilities for profiling and optimization.
+ * Provides timing, profiling, and performance metric collection for identifying bottlenecks.
+ */
 /**
  * Performance metrics collected during execution.
  */
-type PerformanceMetrics = {
+export type PerformanceMetrics = {
     operation: string;
     duration: number;
     timestamp: number;
     metadata?: Record<string, unknown>;
 };
 /**
- * Start a performance timer for an operation.
- * Returns a stop function that records the duration.
+ * Clear all collected performance metrics.
  *
- * @param operation - Name of the operation being timed
- * @param metadata - Optional metadata to attach to the metric
- * @returns Stop function that completes the timing
+ * @example
+ * import { clearPerformanceMetrics } from '@socketsecurity/lib/performance'
+ *
+ * clearPerformanceMetrics()
+ */
+export declare function clearPerformanceMetrics(): void;
+/**
+ * Create a performance report for the current execution.
+ * Only available when DEBUG=perf is enabled.
+ *
+ * @returns Formatted performance report
  *
  * @example
- * import { perfTimer } from '@socketsecurity/lib/performance'
+ * import { generatePerformanceReport } from '@socketsecurity/lib/performance'
  *
- * const stop = perfTimer('api-call')
- * await fetchData()
- * stop({ endpoint: '/npm/lodash/score' })
+ * console.log(generatePerformanceReport())
+ * // ╔═══════════════════════════════════════════════╗
+ * // ║         Performance Report                    ║
+ * // ╚═══════════════════════════════════════════════╝
+ * //
+ * // api-call:
+ * //   Calls: 5
+ * //   Avg:   246.8ms
+ * //   Min:   100ms
+ * //   Max:   500ms
+ * //   Total: 1234ms
  */
-export declare function perfTimer(operation: string, metadata?: Record<string, unknown>): (additionalMetadata?: Record<string, unknown>) => void;
+export declare function generatePerformanceReport(): string;
+/**
+ * Get all collected performance metrics.
+ * Only available when DEBUG=perf is enabled.
+ *
+ * @returns Array of performance metrics
+ *
+ * @example
+ * import { getPerformanceMetrics } from '@socketsecurity/lib/performance'
+ *
+ * const metrics = getPerformanceMetrics()
+ * console.log(metrics)
+ */
+export declare function getPerformanceMetrics(): PerformanceMetrics[];
+/**
+ * Get performance summary statistics.
+ *
+ * @returns Summary of metrics grouped by operation
+ *
+ * @example
+ * import { getPerformanceSummary } from '@socketsecurity/lib/performance'
+ *
+ * const summary = getPerformanceSummary()
+ * console.log(summary)
+ * // {
+ * //   'api-call': { count: 5, total: 1234, avg: 246.8, min: 100, max: 500 },
+ * //   'file-read': { count: 10, total: 50, avg: 5, min: 2, max: 15 }
+ * // }
+ */
+export declare function getPerformanceSummary(): Record<string, {
+    count: number;
+    total: number;
+    avg: number;
+    min: number;
+    max: number;
+}>;
 /**
  * Measure execution time of an async function.
  *
@@ -63,49 +117,39 @@ export declare function measureSync<T>(operation: string, fn: () => T, metadata?
     duration: number;
 };
 /**
- * Get all collected performance metrics.
- * Only available when DEBUG=perf is enabled.
- *
- * @returns Array of performance metrics
- *
- * @example
- * import { getPerformanceMetrics } from '@socketsecurity/lib/performance'
+ * Mark a checkpoint in performance tracking.
+ * Useful for tracking progress through complex operations.
  *
- * const metrics = getPerformanceMetrics()
- * console.log(metrics)
- */
-export declare function getPerformanceMetrics(): PerformanceMetrics[];
-/**
- * Clear all collected performance metrics.
+ * @param checkpoint - Name of the checkpoint
+ * @param metadata - Optional metadata
  *
  * @example
- * import { clearPerformanceMetrics } from '@socketsecurity/lib/performance'
+ * import { perfCheckpoint } from '@socketsecurity/lib/performance'
  *
- * clearPerformanceMetrics()
+ * perfCheckpoint('start-scan')
+ * // ... do work ...
+ * perfCheckpoint('fetch-packages', { count: 50 })
+ * // ... do work ...
+ * perfCheckpoint('analyze-issues', { issueCount: 10 })
+ * perfCheckpoint('end-scan')
  */
-export declare function clearPerformanceMetrics(): void;
+export declare function perfCheckpoint(checkpoint: string, metadata?: Record<string, unknown>): void;
 /**
- * Get performance summary statistics.
+ * Start a performance timer for an operation.
+ * Returns a stop function that records the duration.
  *
- * @returns Summary of metrics grouped by operation
+ * @param operation - Name of the operation being timed
+ * @param metadata - Optional metadata to attach to the metric
+ * @returns Stop function that completes the timing
  *
  * @example
- * import { getPerformanceSummary } from '@socketsecurity/lib/performance'
+ * import { perfTimer } from '@socketsecurity/lib/performance'
  *
- * const summary = getPerformanceSummary()
- * console.log(summary)
- * // {
- * //   'api-call': { count: 5, total: 1234, avg: 246.8, min: 100, max: 500 },
- * //   'file-read': { count: 10, total: 50, avg: 5, min: 2, max: 15 }
- * // }
+ * const stop = perfTimer('api-call')
+ * await fetchData()
+ * stop({ endpoint: '/npm/lodash/score' })
  */
-export declare function getPerformanceSummary(): Record<string, {
-    count: number;
-    total: number;
-    avg: number;
-    min: number;
-    max: number;
-}>;
+export declare function perfTimer(operation: string, metadata?: Record<string, unknown>): (additionalMetadata?: Record<string, unknown>) => void;
 /**
  * Print performance summary to console.
  * Only prints when DEBUG=perf is enabled.
@@ -119,24 +163,6 @@ export declare function getPerformanceSummary(): Record<string, {
  * // file-read: 10 calls, avg 5ms (min 2ms, max 15ms, total 50ms)
  */
 export declare function printPerformanceSummary(): void;
-/**
- * Mark a checkpoint in performance tracking.
- * Useful for tracking progress through complex operations.
- *
- * @param checkpoint - Name of the checkpoint
- * @param metadata - Optional metadata
- *
- * @example
- * import { perfCheckpoint } from '@socketsecurity/lib/performance'
- *
- * perfCheckpoint('start-scan')
- * // ... do work ...
- * perfCheckpoint('fetch-packages', { count: 50 })
- * // ... do work ...
- * perfCheckpoint('analyze-issues', { issueCount: 10 })
- * perfCheckpoint('end-scan')
- */
-export declare function perfCheckpoint(checkpoint: string, metadata?: Record<string, unknown>): void;
 /**
  * Track memory usage at a specific point.
  * Only available when DEBUG=perf is enabled.
@@ -153,26 +179,3 @@ export declare function perfCheckpoint(checkpoint: string, metadata?: Record<str
  * console.log(`Memory increased by ${memAfter - memBefore}MB`)
  */
 export declare function trackMemory(label: string): number;
-/**
- * Create a performance report for the current execution.
- * Only available when DEBUG=perf is enabled.
- *
- * @returns Formatted performance report
- *
- * @example
- * import { generatePerformanceReport } from '@socketsecurity/lib/performance'
- *
- * console.log(generatePerformanceReport())
- * // ╔═══════════════════════════════════════════════╗
- * // ║         Performance Report                    ║
- * // ╚═══════════════════════════════════════════════╝
- * //
- * // api-call:
- * //   Calls: 5
- * //   Avg:   246.8ms
- * //   Min:   100ms
- * //   Max:   500ms
- * //   Total: 1234ms
- */
-export declare function generatePerformanceReport(): string;
-export {};

package/dist/performance.js

@@ -1,5 +1,6 @@
 "use strict";
 /* Socket Lib - Built with esbuild */
+"use strict";
 var __create = Object.create;
 var __defProp = Object.defineProperty;
 var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
@@ -47,25 +48,75 @@ const performanceMetrics = [];
 function isPerfEnabled() {
   return import_node_process.default.env["DEBUG"]?.includes("perf") || false;
 }
-function perfTimer(operation, metadata) {
-  if (!isPerfEnabled()) {
-    return () => {
-    };
+function clearPerformanceMetrics() {
+  performanceMetrics.length = 0;
+  (0, import_debug.debugLog)("[perf] Cleared performance metrics");
+}
+function generatePerformanceReport() {
+  if (!isPerfEnabled() || performanceMetrics.length === 0) {
+    return "(no performance data collected - enable with DEBUG=perf)";
   }
-  const start = performance.now();
-  (0, import_debug.debugLog)(`[perf] [START] ${operation}`);
-  return (additionalMetadata) => {
-    const duration = performance.now() - start;
-    const metric = {
-      operation,
-      // Round to 2 decimals
-      duration: Math.round(duration * 100) / 100,
-      timestamp: Date.now(),
-      metadata: { ...metadata, ...additionalMetadata }
+  const summary = getPerformanceSummary();
+  const operations = Object.keys(summary).sort();
+  let report = "\n\u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557\n";
+  report += "\u2551         Performance Report                    \u2551\n";
+  report += "\u255A\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255D\n\n";
+  for (const operation of operations) {
+    const stats = summary[operation];
+    report += `${operation}:
+`;
+    report += `  Calls: ${stats.count}
+`;
+    report += `  Avg:   ${stats.avg}ms
+`;
+    report += `  Min:   ${stats.min}ms
+`;
+    report += `  Max:   ${stats.max}ms
+`;
+    report += `  Total: ${stats.total}ms
+
+`;
+  }
+  const totalDuration = Object.values(summary).reduce(
+    (sum, s) => sum + s.total,
+    0
+  );
+  report += `Total measured time: ${Math.round(totalDuration * 100) / 100}ms
+`;
+  return report;
+}
+function getPerformanceMetrics() {
+  return [...performanceMetrics];
+}
+function getPerformanceSummary() {
+  const summary = { __proto__: null };
+  for (const metric of performanceMetrics) {
+    const { duration, operation } = metric;
+    if (!summary[operation]) {
+      summary[operation] = {
+        count: 0,
+        total: 0,
+        min: Number.POSITIVE_INFINITY,
+        max: Number.NEGATIVE_INFINITY
+      };
+    }
+    const stats = summary[operation];
+    stats.count++;
+    stats.total += duration;
+    stats.min = Math.min(stats.min, duration);
+    stats.max = Math.max(stats.max, duration);
+  }
+  const result = { __proto__: null };
+  for (const { 0: operation, 1: stats } of Object.entries(summary)) {
+    result[operation] = {
+      count: stats.count,
+      total: Math.round(stats.total * 100) / 100,
+      avg: Math.round(stats.total / stats.count * 100) / 100,
+      min: Math.round(stats.min * 100) / 100,
+      max: Math.round(stats.max * 100) / 100
     };
-    performanceMetrics.push(metric);
-    (0, import_debug.debugLog)(`[perf] [END] ${operation} - ${metric.duration}ms`);
-  };
+  }
+  return result;
 }
 async function measure(operation, fn, metadata) {
   const stop = perfTimer(operation, metadata);
@@ -97,42 +148,38 @@ function measureSync(operation, fn, metadata) {
     throw e;
   }
 }
-function getPerformanceMetrics() {
-  return [...performanceMetrics];
-}
-function clearPerformanceMetrics() {
-  performanceMetrics.length = 0;
-  (0, import_debug.debugLog)("[perf] Cleared performance metrics");
-}
-function getPerformanceSummary() {
-  const summary = /* @__PURE__ */ Object.create(null);
-  for (const metric of performanceMetrics) {
-    const { duration, operation } = metric;
-    if (!summary[operation]) {
-      summary[operation] = {
-        count: 0,
-        total: 0,
-        min: Number.POSITIVE_INFINITY,
-        max: Number.NEGATIVE_INFINITY
-      };
-    }
-    const stats = summary[operation];
-    stats.count++;
-    stats.total += duration;
-    stats.min = Math.min(stats.min, duration);
-    stats.max = Math.max(stats.max, duration);
+function perfCheckpoint(checkpoint, metadata) {
+  if (!isPerfEnabled()) {
+    return;
   }
-  const result = /* @__PURE__ */ Object.create(null);
-  for (const { 0: operation, 1: stats } of Object.entries(summary)) {
-    result[operation] = {
-      count: stats.count,
-      total: Math.round(stats.total * 100) / 100,
-      avg: Math.round(stats.total / stats.count * 100) / 100,
-      min: Math.round(stats.min * 100) / 100,
-      max: Math.round(stats.max * 100) / 100
+  const metric = {
+    operation: `checkpoint:${checkpoint}`,
+    duration: 0,
+    timestamp: Date.now(),
+    ...metadata ? { metadata } : {}
+  };
+  performanceMetrics.push(metric);
+  (0, import_debug.debugLog)(`[perf] [CHECKPOINT] ${checkpoint}`);
+}
+function perfTimer(operation, metadata) {
+  if (!isPerfEnabled()) {
+    return () => {
     };
   }
-  return result;
+  const start = performance.now();
+  (0, import_debug.debugLog)(`[perf] [START] ${operation}`);
+  return (additionalMetadata) => {
+    const duration = performance.now() - start;
+    const metric = {
+      operation,
+      // Round to 2 decimals
+      duration: Math.round(duration * 100) / 100,
+      timestamp: Date.now(),
+      metadata: { ...metadata, ...additionalMetadata }
+    };
+    performanceMetrics.push(metric);
+    (0, import_debug.debugLog)(`[perf] [END] ${operation} - ${metric.duration}ms`);
+  };
 }
 function printPerformanceSummary() {
   if (!isPerfEnabled() || performanceMetrics.length === 0) {
@@ -149,19 +196,6 @@ function printPerformanceSummary() {
   }
   (0, import_debug.debugLog)("[perf] =========================\n");
 }
-function perfCheckpoint(checkpoint, metadata) {
-  if (!isPerfEnabled()) {
-    return;
-  }
-  const metric = {
-    operation: `checkpoint:${checkpoint}`,
-    duration: 0,
-    timestamp: Date.now(),
-    ...metadata ? { metadata } : {}
-  };
-  performanceMetrics.push(metric);
-  (0, import_debug.debugLog)(`[perf] [CHECKPOINT] ${checkpoint}`);
-}
 function trackMemory(label) {
   if (!isPerfEnabled()) {
     return 0;
@@ -182,39 +216,6 @@ function trackMemory(label) {
   performanceMetrics.push(metric);
   return heapUsedMB;
 }
-function generatePerformanceReport() {
-  if (!isPerfEnabled() || performanceMetrics.length === 0) {
-    return "(no performance data collected - enable with DEBUG=perf)";
-  }
-  const summary = getPerformanceSummary();
-  const operations = Object.keys(summary).sort();
-  let report = "\n\u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557\n";
-  report += "\u2551         Performance Report                    \u2551\n";
-  report += "\u255A\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255D\n\n";
-  for (const operation of operations) {
-    const stats = summary[operation];
-    report += `${operation}:
-`;
-    report += `  Calls: ${stats.count}
-`;
-    report += `  Avg:   ${stats.avg}ms
-`;
-    report += `  Min:   ${stats.min}ms
-`;
-    report += `  Max:   ${stats.max}ms
-`;
-    report += `  Total: ${stats.total}ms
-
-`;
-  }
-  const totalDuration = Object.values(summary).reduce(
-    (sum, s) => sum + s.total,
-    0
-  );
-  report += `Total measured time: ${Math.round(totalDuration * 100) / 100}ms
-`;
-  return report;
-}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   clearPerformanceMetrics,

package/dist/process-lock.d.ts

@@ -1,3 +1,44 @@
+/**
+ * @fileoverview Process locking utilities with stale detection and exit cleanup.
+ * Provides cross-platform inter-process synchronization using directory-based locks.
+ * Aligned with npm's npx locking strategy (5-second stale timeout, periodic touching).
+ *
+ * ## Why directories instead of files?
+ *
+ * This implementation uses `mkdir()` to create lock directories (not files) because:
+ *
+ * 1. **Atomic guarantee**: `mkdir()` is guaranteed atomic across ALL filesystems,
+ *    including NFS. Only ONE process can successfully create the directory. If it
+ *    exists, `mkdir()` fails with EEXIST instantly with no race conditions.
+ *
+ * 2. **File-based locking issues**:
+ *    - `writeFile()` with `flag: 'wx'` - atomicity can fail on NFS
+ *    - `open()` with `O_EXCL` - not guaranteed atomic on older NFS
+ *    - Traditional lockfiles - can have race conditions on network filesystems
+ *
+ * 3. **Simplicity**: No need to write/read file content, track PIDs, or manage
+ *    file descriptors. Just create/delete directory and check mtime.
+ *
+ * 4. **Historical precedent**: Well-known Unix locking pattern used by package
+ *    managers for decades. Git uses similar approach for `.git/index.lock`.
+ *
+ * ## The mtime trick
+ *
+ * We periodically update the lock directory's mtime (modification time) by
+ * "touching" it to signal "I'm still actively working". This prevents other
+ * processes from treating the lock as stale and removing it.
+ *
+ * **The lock directory remains empty** - it's just a sentinel that signals
+ * "locked". The mtime is the only data needed to track lock freshness.
+ *
+ * ## npm npx compatibility
+ *
+ * This implementation matches npm npx's concurrency.lock approach:
+ * - Lock created via `mkdir(path.join(installDir, 'concurrency.lock'))`
+ * - 5-second stale timeout (if mtime is older than 5s, lock is stale)
+ * - 2-second touching interval (updates mtime every 2s to keep lock fresh)
+ * - Automatic cleanup on process exit
+ */
 /**
  * Lock acquisition options.
  */
@@ -135,6 +176,5 @@ declare class ProcessLockManager {
      */
     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

@@ -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;
@@ -30,12 +31,18 @@ let _fs;
 // @__NO_SIDE_EFFECTS__
 function getFs() {
   if (_fs === void 0) {
-    _fs = require("fs");
+    _fs = require("node:fs");
   }
   return _fs;
 }
-const fs = /* @__PURE__ */ getFs();
-const { existsSync, mkdirSync, statSync, utimesSync } = fs;
+let _path;
+// @__NO_SIDE_EFFECTS__
+function getPath() {
+  if (_path === void 0) {
+    _path = require("node:path");
+  }
+  return _path;
+}
 const logger = (0, import_logger.getDefaultLogger)();
 class ProcessLockManager {
   activeLocks = /* @__PURE__ */ new Set();
@@ -54,9 +61,10 @@ class ProcessLockManager {
         clearInterval(timer);
       }
       this.touchTimers.clear();
+      const fs = /* @__PURE__ */ getFs();
       for (const lockPath of this.activeLocks) {
         try {
-          if (existsSync(lockPath)) {
+          if (fs.existsSync(lockPath)) {
             (0, import_fs.safeDeleteSync)(lockPath, { recursive: true });
           }
         } catch {
@@ -73,9 +81,10 @@ class ProcessLockManager {
    */
   touchLock(lockPath) {
     try {
-      if (existsSync(lockPath)) {
-        const now = /* @__PURE__ */ new Date();
-        utimesSync(lockPath, now, now);
+      const fs = /* @__PURE__ */ getFs();
+      if (fs.existsSync(lockPath)) {
+        const now = Date.now() / 1e3;
+        fs.utimesSync(lockPath, now, now);
       }
     } catch (error) {
       logger.warn(
@@ -123,7 +132,7 @@ class ProcessLockManager {
    */
   isStale(lockPath, staleMs) {
     try {
-      const stats = statSync(lockPath, { throwIfNoEntry: false });
+      const stats = (/* @__PURE__ */ getFs()).statSync(lockPath, { throwIfNoEntry: false });
       if (!stats) {
         return false;
       }
@@ -176,17 +185,15 @@ class ProcessLockManager {
             } catch {
             }
           }
-          if (existsSync(lockPath)) {
+          const fs = /* @__PURE__ */ getFs();
+          if (fs.existsSync(lockPath)) {
             throw new Error(`Lock already exists: ${lockPath}`);
           }
-          const lastSlash = Math.max(
-            lockPath.lastIndexOf("/"),
-            lockPath.lastIndexOf("\\")
-          );
-          if (lastSlash > 0) {
-            mkdirSync(lockPath.slice(0, lastSlash), { recursive: true });
+          const parent = (/* @__PURE__ */ getPath()).dirname(lockPath);
+          if (parent && parent !== "." && parent !== lockPath) {
+            fs.mkdirSync(parent, { recursive: true });
           }
-          mkdirSync(lockPath);
+          fs.mkdirSync(lockPath);
           this.activeLocks.add(lockPath);
           this.startTouchTimer(lockPath, touchIntervalMs);
           return () => this.release(lockPath);
@@ -270,7 +277,7 @@ To resolve:
   release(lockPath) {
     this.stopTouchTimer(lockPath);
     try {
-      if (existsSync(lockPath)) {
+      if ((/* @__PURE__ */ getFs()).existsSync(lockPath)) {
         (0, import_fs.safeDeleteSync)(lockPath, { recursive: true });
       }
       this.activeLocks.delete(lockPath);

package/dist/promise-queue.d.ts

@@ -1,3 +1,9 @@
+/**
+ * @fileoverview Bounded concurrency promise queue.
+ * Exports the `PromiseQueue` class, which limits how many async tasks run
+ * simultaneously, supports an optional max queue length (dropping the oldest
+ * pending task when exceeded), and exposes an idle-wait helper.
+ */
 export declare class PromiseQueue {
     private queue;
     private running;

package/dist/promise-queue.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;