@socketsecurity/lib 6.0.2 → 6.0.4

package/dist/paths/walk.js

@@ -0,0 +1,58 @@
+"use strict";
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_runtime = require('../_virtual/_rolldown/runtime.js');
+const require_paths_normalize = require('./normalize.js');
+const require_node_path = require('../node/path.js');
+const require_smol_path = require('../smol/path.js');
+let node_process = require("node:process");
+node_process = require_runtime.__toESM(node_process);
+
+//#region src/paths/walk.ts
+/**
+* @file Walk parent directories. `walkUp` is the lazy ancestor generator that
+*   `fs/find-up` and package-root lookups build on: given a starting path it
+*   yields that path, then each parent, up to and INCLUDING the filesystem root
+*   (or a caller-supplied `stopAt` boundary). Lazy so a caller can stop early
+*   without computing the whole chain.
+*/
+/**
+* Lazily yield `from` and each of its ancestor directories, up to and including
+* the filesystem root (or `stopAt`). Each yielded path is normalized to forward
+* slashes.
+*
+* @example
+*   ;```ts
+*   for (const dir of walkUp('/a/b/c')) {
+*     // '/a/b/c', '/a/b', '/a', '/'
+*   }
+*
+*   // Stop at a boundary (inclusive):
+*   [...walkUp('/a/b/c', { stopAt: '/a' })] // ['/a/b/c', '/a/b', '/a']
+*   ```
+*
+* @param from - Path to start from. Relative values resolve against `cwd`.
+* @param options - `cwd` and `stopAt` boundary.
+*
+* @returns Generator of normalized absolute directory paths.
+*/
+function* walkUp(from, options) {
+	const { cwd = node_process.default.cwd(), stopAt } = {
+		__proto__: null,
+		...options
+	};
+	const path = /* @__PURE__ */ require_node_path.getNodePath();
+	const dirname = (/* @__PURE__ */ require_smol_path.getSmolPath())?.dirname ?? path.dirname;
+	let dir = path.resolve(cwd, from);
+	const stopDir = stopAt ? path.resolve(cwd, stopAt) : void 0;
+	let prev;
+	while (dir !== prev) {
+		yield /* @__PURE__ */ require_paths_normalize.normalizePath(dir);
+		if (stopDir !== void 0 && dir === stopDir) return;
+		prev = dir;
+		dir = dirname(dir);
+	}
+}
+
+//#endregion
+exports.walkUp = walkUp;

package/dist/perf/_internal.js

@@ -1,30 +1,12 @@
 "use strict";
-/* Socket Lib - Built with esbuild */
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var internal_exports = {};
-__export(internal_exports, {
-  performanceMetrics: () => performanceMetrics
-});
-module.exports = __toCommonJS(internal_exports);
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+//#region src/perf/_internal.ts
+/**
+* Global metrics collection (only in debug mode).
+*/
 const performanceMetrics = [];
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  performanceMetrics
-});
+
+//#endregion
+exports.performanceMetrics = performanceMetrics;

package/dist/perf/enabled.js

@@ -1,33 +1,24 @@
 "use strict";
-/* Socket Lib - Built with esbuild */
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var enabled_exports = {};
-__export(enabled_exports, {
-  isPerfEnabled: () => isPerfEnabled
-});
-module.exports = __toCommonJS(enabled_exports);
-var import_rewire = require("../env/rewire");
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_env_rewire = require('../env/rewire.js');
+
+//#region src/perf/enabled.ts
+/**
+* @file Feature-flag check — `isPerfEnabled()` returns true when `DEBUG=perf`
+*   is set in the environment. Every recording entry (timer / checkpoint /
+*   memory) bails out cheaply when this is false.
+*/
+/**
+* Check if performance tracking is enabled.
+*
+* Reads `DEBUG` through `getEnvValue` so tests can mock the value via
+* `setEnv('DEBUG', 'perf')` from `@socketsecurity/lib/env/rewire` without
+* mutating `process.env`.
+*/
 function isPerfEnabled() {
-  return (0, import_rewire.getEnvValue)("DEBUG")?.includes("perf") || false;
+	return require_env_rewire.getEnvValue("DEBUG")?.includes("perf") || false;
 }
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  isPerfEnabled
-});
+
+//#endregion
+exports.isPerfEnabled = isPerfEnabled;

package/dist/perf/metrics.js

@@ -1,74 +1,88 @@
 "use strict";
-/* Socket Lib - Built with esbuild */
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var metrics_exports = {};
-__export(metrics_exports, {
-  clearPerformanceMetrics: () => clearPerformanceMetrics,
-  getPerformanceMetrics: () => getPerformanceMetrics,
-  getPerformanceSummary: () => getPerformanceSummary
-});
-module.exports = __toCommonJS(metrics_exports);
-var import_output = require("../debug/output");
-var import_math = require("../primordials/math");
-var import_object = require("../primordials/object");
-var import_internal = require("./_internal");
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_primordials_math = require('../primordials/math.js');
+const require_primordials_object = require('../primordials/object.js');
+const require_debug_output = require('../debug/output.js');
+const require_perf__internal = require('./_internal.js');
+
+//#region src/perf/metrics.ts
+/**
+* @file Read-side helpers — `getPerformanceMetrics` returns a shallow copy of
+*   the recorded rows, `getPerformanceSummary` rolls them up per operation
+*   (count / total / avg / min / max), and `clearPerformanceMetrics` empties
+*   the array in place.
+*/
+/**
+* Clear all collected performance metrics.
+*
+* @example
+*   import { clearPerformanceMetrics } from '@socketsecurity/lib/perf/metrics'
+*
+*   clearPerformanceMetrics()
+*/
 function clearPerformanceMetrics() {
-  import_internal.performanceMetrics.length = 0;
-  (0, import_output.debugLog)("[perf] Cleared performance metrics");
+	require_perf__internal.performanceMetrics.length = 0;
+	require_debug_output.debugLog("[perf] Cleared performance metrics");
 }
+/**
+* Get all collected performance metrics. Only available when DEBUG=perf is
+* enabled.
+*
+* @example
+*   import { getPerformanceMetrics } from '@socketsecurity/lib/perf/metrics'
+*
+*   const metrics = getPerformanceMetrics()
+*   console.log(metrics)
+*
+* @returns Array of performance metrics
+*/
 function getPerformanceMetrics() {
-  return [...import_internal.performanceMetrics];
+	return [...require_perf__internal.performanceMetrics];
 }
+/**
+* Get performance summary statistics.
+*
+* @example
+*   import { getPerformanceSummary } from '@socketsecurity/lib/perf/metrics'
+*
+*   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 }
+*   // }
+*
+* @returns Summary of metrics grouped by operation
+*/
 function getPerformanceSummary() {
-  const summary = { __proto__: null };
-  for (const metric of import_internal.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 = (0, import_math.MathMin)(stats.min, duration);
-    stats.max = (0, import_math.MathMax)(stats.max, duration);
-  }
-  const result = { __proto__: null };
-  for (const { 0: operation, 1: stats } of (0, import_object.ObjectEntries)(summary)) {
-    result[operation] = {
-      count: stats.count,
-      total: (0, import_math.MathRound)(stats.total * 100) / 100,
-      avg: (0, import_math.MathRound)(stats.total / stats.count * 100) / 100,
-      min: (0, import_math.MathRound)(stats.min * 100) / 100,
-      max: (0, import_math.MathRound)(stats.max * 100) / 100
-    };
-  }
-  return result;
+	const summary = { __proto__: null };
+	for (const metric of require_perf__internal.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 = require_primordials_math.MathMin(stats.min, duration);
+		stats.max = require_primordials_math.MathMax(stats.max, duration);
+	}
+	const result = { __proto__: null };
+	for (const { 0: operation, 1: stats } of require_primordials_object.ObjectEntries(summary)) result[operation] = {
+		count: stats.count,
+		total: require_primordials_math.MathRound(stats.total * 100) / 100,
+		avg: require_primordials_math.MathRound(stats.total / stats.count * 100) / 100,
+		min: require_primordials_math.MathRound(stats.min * 100) / 100,
+		max: require_primordials_math.MathRound(stats.max * 100) / 100
+	};
+	return result;
 }
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  clearPerformanceMetrics,
-  getPerformanceMetrics,
-  getPerformanceSummary
-});
+
+//#endregion
+exports.clearPerformanceMetrics = clearPerformanceMetrics;
+exports.getPerformanceMetrics = getPerformanceMetrics;
+exports.getPerformanceSummary = getPerformanceSummary;

package/dist/perf/report.js

@@ -1,85 +1,84 @@
 "use strict";
-/* Socket Lib - Built with esbuild */
-"use strict";
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __export = (target, all) => {
-  for (var name in all)
-    __defProp(target, name, { get: all[name], enumerable: true });
-};
-var __copyProps = (to, from, except, desc) => {
-  if (from && typeof from === "object" || typeof from === "function") {
-    for (let key of __getOwnPropNames(from))
-      if (!__hasOwnProp.call(to, key) && key !== except)
-        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
-  }
-  return to;
-};
-var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var report_exports = {};
-__export(report_exports, {
-  generatePerformanceReport: () => generatePerformanceReport,
-  printPerformanceSummary: () => printPerformanceSummary
-});
-module.exports = __toCommonJS(report_exports);
-var import_output = require("../debug/output");
-var import_math = require("../primordials/math");
-var import_object = require("../primordials/object");
-var import_internal = require("./_internal");
-var import_enabled = require("./enabled");
-var import_metrics = require("./metrics");
-function generatePerformanceReport() {
-  if (!(0, import_enabled.isPerfEnabled)() || import_internal.performanceMetrics.length === 0) {
-    return "(no performance data collected - enable with DEBUG=perf)";
-  }
-  const summary = (0, import_metrics.getPerformanceSummary)();
-  const operations = (0, import_object.ObjectKeys)(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
+/* Socket Lib - Built with rolldown */
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+const require_primordials_math = require('../primordials/math.js');
+const require_primordials_object = require('../primordials/object.js');
+const require_debug_output = require('../debug/output.js');
+const require_perf__internal = require('./_internal.js');
+const require_perf_enabled = require('./enabled.js');
+const require_perf_metrics = require('./metrics.js');
 
-`;
-  }
-  const totalDuration = (0, import_object.ObjectValues)(summary).reduce(
-    (sum, s) => sum + s.total,
-    0
-  );
-  report += `Total measured time: ${(0, import_math.MathRound)(totalDuration * 100) / 100}ms
-`;
-  return report;
+//#region src/perf/report.ts
+/**
+* @file Report-side helpers — `generatePerformanceReport` returns a multi-line
+*   ASCII-bordered report string; `printPerformanceSummary` writes a
+*   one-line-per-op summary through `debugLog`. Both gate on `isPerfEnabled()`
+*   and use the same `getPerformanceSummary` rollup.
+*/
+/**
+* Create a performance report for the current execution. Only available when
+* DEBUG=perf is enabled.
+*
+* @example
+*   import { generatePerformanceReport } from '@socketsecurity/lib/perf/report'
+*
+*   console.log(generatePerformanceReport())
+*   // ╔═══════════════════════════════════════════════╗
+*   // ║         Performance Report                    ║
+*   // ╚═══════════════════════════════════════════════╝
+*   //
+*   // api-call:
+*   //   Calls: 5
+*   //   Avg:   246.8ms
+*   //   Min:   100ms
+*   //   Max:   500ms
+*   //   Total: 1234ms
+*
+* @returns Formatted performance report
+*/
+function generatePerformanceReport() {
+	if (!require_perf_enabled.isPerfEnabled() || require_perf__internal.performanceMetrics.length === 0) return "(no performance data collected - enable with DEBUG=perf)";
+	const summary = require_perf_metrics.getPerformanceSummary();
+	const operations = require_primordials_object.ObjectKeys(summary).sort();
+	let report = "\n╔═══════════════════════════════════════════════╗\n";
+	report += "║         Performance Report                    ║\n";
+	report += "╚═══════════════════════════════════════════════╝\n\n";
+	for (const operation of operations) {
+		const stats = summary[operation];
+		report += `${operation}:\n`;
+		report += `  Calls: ${stats.count}\n`;
+		report += `  Avg:   ${stats.avg}ms\n`;
+		report += `  Min:   ${stats.min}ms\n`;
+		report += `  Max:   ${stats.max}ms\n`;
+		report += `  Total: ${stats.total}ms\n\n`;
+	}
+	const totalDuration = require_primordials_object.ObjectValues(summary).reduce((sum, s) => sum + s.total, 0);
+	report += `Total measured time: ${require_primordials_math.MathRound(totalDuration * 100) / 100}ms\n`;
+	return report;
 }
+/**
+* Print performance summary to console. Only prints when DEBUG=perf is enabled.
+*
+* @example
+*   import { printPerformanceSummary } from '@socketsecurity/lib/perf/report'
+*
+*   printPerformanceSummary()
+*   // Performance Summary:
+*   // api-call: 5 calls, avg 246.8ms (min 100ms, max 500ms, total 1234ms)
+*   // file-read: 10 calls, avg 5ms (min 2ms, max 15ms, total 50ms)
+*/
 function printPerformanceSummary() {
-  if (!(0, import_enabled.isPerfEnabled)() || import_internal.performanceMetrics.length === 0) {
-    return;
-  }
-  const summary = (0, import_metrics.getPerformanceSummary)();
-  const operations = (0, import_object.ObjectKeys)(summary).sort();
-  (0, import_output.debugLog)("[perf]\n=== Performance Summary ===");
-  for (const operation of operations) {
-    const stats = summary[operation];
-    (0, import_output.debugLog)(
-      `[perf] ${operation}: ${stats.count} calls, avg ${stats.avg}ms (min ${stats.min}ms, max ${stats.max}ms, total ${stats.total}ms)`
-    );
-  }
-  (0, import_output.debugLog)("[perf] =========================\n");
+	if (!require_perf_enabled.isPerfEnabled() || require_perf__internal.performanceMetrics.length === 0) return;
+	const summary = require_perf_metrics.getPerformanceSummary();
+	const operations = require_primordials_object.ObjectKeys(summary).sort();
+	require_debug_output.debugLog("[perf]\n=== Performance Summary ===");
+	for (const operation of operations) {
+		const stats = summary[operation];
+		require_debug_output.debugLog(`[perf] ${operation}: ${stats.count} calls, avg ${stats.avg}ms (min ${stats.min}ms, max ${stats.max}ms, total ${stats.total}ms)`);
+	}
+	require_debug_output.debugLog("[perf] =========================\n");
 }
-// Annotate the CommonJS export names for ESM import in node:
-0 && (module.exports = {
-  generatePerformanceReport,
-  printPerformanceSummary
-});
+
+//#endregion
+exports.generatePerformanceReport = generatePerformanceReport;
+exports.printPerformanceSummary = printPerformanceSummary;