@socketsecurity/lib 4.4.0 → 5.0.1

package/dist/dlx/paths.js

@@ -0,0 +1,75 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+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 paths_exports = {};
+__export(paths_exports, {
+  getDlxInstalledPackageDir: () => getDlxInstalledPackageDir,
+  getDlxPackageDir: () => getDlxPackageDir,
+  getDlxPackageJsonPath: () => getDlxPackageJsonPath,
+  getDlxPackageNodeModulesDir: () => getDlxPackageNodeModulesDir,
+  isInSocketDlx: () => isInSocketDlx
+});
+module.exports = __toCommonJS(paths_exports);
+var import_normalize = require("../paths/normalize");
+var import_socket = require("../paths/socket");
+let _path;
+// @__NO_SIDE_EFFECTS__
+function getPath() {
+  if (_path === void 0) {
+    _path = require("node:path");
+  }
+  return _path;
+}
+function getDlxInstalledPackageDir(packageName) {
+  const path = /* @__PURE__ */ getPath();
+  return (0, import_normalize.normalizePath)(
+    path.join(getDlxPackageNodeModulesDir(packageName), packageName)
+  );
+}
+function getDlxPackageDir(packageName) {
+  const path = /* @__PURE__ */ getPath();
+  return (0, import_normalize.normalizePath)(path.join((0, import_socket.getSocketDlxDir)(), packageName));
+}
+function getDlxPackageJsonPath(packageName) {
+  const path = /* @__PURE__ */ getPath();
+  return (0, import_normalize.normalizePath)(
+    path.join(getDlxInstalledPackageDir(packageName), "package.json")
+  );
+}
+function getDlxPackageNodeModulesDir(packageName) {
+  const path = /* @__PURE__ */ getPath();
+  return (0, import_normalize.normalizePath)(path.join(getDlxPackageDir(packageName), "node_modules"));
+}
+function isInSocketDlx(filePath) {
+  if (!filePath) {
+    return false;
+  }
+  const path = /* @__PURE__ */ getPath();
+  const dlxDir = (0, import_socket.getSocketDlxDir)();
+  const absolutePath = (0, import_normalize.normalizePath)(path.resolve(filePath));
+  return absolutePath.startsWith(`${dlxDir}/`);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getDlxInstalledPackageDir,
+  getDlxPackageDir,
+  getDlxPackageJsonPath,
+  getDlxPackageNodeModulesDir,
+  isInSocketDlx
+});

package/dist/fs.d.ts

@@ -4,7 +4,7 @@
  */
 import type { Abortable } from 'events';
 import type { MakeDirectoryOptions, ObjectEncodingOptions, OpenMode, PathLike } from 'fs';
-import type { JsonReviver } from './json';
+import type { JsonReviver } from './json/types';
 import { type Remap } from './objects';
 /**
  * Supported text encodings for Node.js Buffers.
@@ -545,7 +545,7 @@ export declare function readFileUtf8Sync(filepath: PathLike, options?: ReadFileO
  * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
-export declare function readJson(filepath: PathLike, options?: ReadJsonOptions | string | undefined): Promise<import("./json").JsonValue>;
+export declare function readJson(filepath: PathLike, options?: ReadJsonOptions | string | undefined): Promise<import("./json/types").JsonValue>;
 /**
  * Read and parse a JSON file synchronously.
  * Reads the file as UTF-8 text and parses it as JSON.
@@ -575,54 +575,66 @@ export declare function readJson(filepath: PathLike, options?: ReadJsonOptions |
  * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
-export declare function readJsonSync(filepath: PathLike, options?: ReadJsonOptions | string | undefined): import("./json").JsonValue;
+export declare function readJsonSync(filepath: PathLike, options?: ReadJsonOptions | string | undefined): import("./json/types").JsonValue;
 /**
  * Safely delete a file or directory asynchronously with built-in protections.
- * Uses `del` for safer deletion that prevents removing cwd and above by default.
- * Automatically uses force: true for temp directory, cacache, and ~/.socket subdirectories.
+ *
+ * Uses [`del`](https://socket.dev/npm/package/del/overview/8.0.1) for safer deletion with these safety features:
+ * - By default, prevents deleting the current working directory (cwd) and above
+ * - Allows deleting within cwd (descendant paths) without force option
+ * - Automatically uses force: true for temp directory, cacache, and ~/.socket subdirectories
+ * - Protects against accidental deletion of parent directories via `../` paths
  *
  * @param filepath - Path or array of paths to delete (supports glob patterns)
  * @param options - Deletion options including force, retries, and recursion
+ * @param options.force - Set to true to allow deleting cwd and above (use with caution)
  * @throws {Error} When attempting to delete protected paths without force option
  *
  * @example
  * ```ts
- * // Delete a single file
- * await safeDelete('./temp-file.txt')
- *
- * // Delete a directory recursively
- * await safeDelete('./build', { recursive: true })
+ * // Delete files within cwd (safe by default)
+ * await safeDelete('./build')
+ * await safeDelete('./dist')
  *
- * // Delete multiple paths
- * await safeDelete(['./dist', './coverage'])
+ * // Delete with glob patterns
+ * await safeDelete(['./temp/**', '!./temp/keep.txt'])
  *
  * // Delete with custom retry settings
  * await safeDelete('./flaky-dir', { maxRetries: 5, retryDelay: 500 })
+ *
+ * // Force delete cwd or above (requires explicit force: true)
+ * await safeDelete('../parent-dir', { force: true })
  * ```
  */
 export declare function safeDelete(filepath: PathLike | PathLike[], options?: RemoveOptions | undefined): Promise<void>;
 /**
  * Safely delete a file or directory synchronously with built-in protections.
- * Uses `del` for safer deletion that prevents removing cwd and above by default.
- * Automatically uses force: true for temp directory, cacache, and ~/.socket subdirectories.
+ *
+ * Uses [`del`](https://socket.dev/npm/package/del/overview/8.0.1) for safer deletion with these safety features:
+ * - By default, prevents deleting the current working directory (cwd) and above
+ * - Allows deleting within cwd (descendant paths) without force option
+ * - Automatically uses force: true for temp directory, cacache, and ~/.socket subdirectories
+ * - Protects against accidental deletion of parent directories via `../` paths
  *
  * @param filepath - Path or array of paths to delete (supports glob patterns)
  * @param options - Deletion options including force, retries, and recursion
+ * @param options.force - Set to true to allow deleting cwd and above (use with caution)
  * @throws {Error} When attempting to delete protected paths without force option
  *
  * @example
  * ```ts
- * // Delete a single file
- * safeDeleteSync('./temp-file.txt')
+ * // Delete files within cwd (safe by default)
+ * safeDeleteSync('./build')
+ * safeDeleteSync('./dist')
  *
- * // Delete a directory recursively
- * safeDeleteSync('./build', { recursive: true })
+ * // Delete with glob patterns
+ * safeDeleteSync(['./temp/**', '!./temp/keep.txt'])
  *
- * // Delete multiple paths with globs
- * safeDeleteSync(['./dist/**', './coverage/**'])
+ * // Delete multiple paths
+ * safeDeleteSync(['./coverage', './reports'])
  *
- * // Force delete a protected path (use with caution)
- * safeDeleteSync('./important', { force: true })
+ * // Force delete cwd or above (requires explicit force: true)
+ * safeDeleteSync('../parent-dir', { force: true })
  * ```
  */
 export declare function safeDeleteSync(filepath: PathLike | PathLike[], options?: RemoveOptions | undefined): void;

package/dist/fs.js

@@ -54,7 +54,7 @@ var import_process = require("./constants/process");
 var import_arrays = require("./arrays");
 var import_del = require("./external/del");
 var import_globs = require("./globs");
-var import_json = require("./json");
+var import_parse = require("./json/parse");
 var import_objects = require("./objects");
 var import_normalize = require("./paths/normalize");
 var import_rewire = require("./paths/rewire");
@@ -455,7 +455,7 @@ Check file permissions or run with appropriate access.`,
     }
     return void 0;
   }
-  return (0, import_json.jsonParse)(content, {
+  return (0, import_parse.jsonParse)(content, {
     filepath: String(filepath),
     reviver,
     throws: shouldThrow
@@ -498,7 +498,7 @@ Check file permissions or run with appropriate access.`,
     }
     return void 0;
   }
-  return (0, import_json.jsonParse)(content, {
+  return (0, import_parse.jsonParse)(content, {
     filepath: String(filepath),
     reviver,
     throws: shouldThrow

package/dist/http-request.d.ts

@@ -1,3 +1,4 @@
+import type { Logger } from './logger.js';
 /**
  * Configuration options for HTTP/HTTPS requests.
  */
@@ -270,9 +271,31 @@ export interface HttpDownloadOptions {
      * ```
      */
     headers?: Record<string, string> | undefined;
+    /**
+     * Logger instance for automatic progress logging.
+     * When provided with `progressInterval`, will automatically log download progress.
+     * If both `onProgress` and `logger` are provided, `onProgress` takes precedence.
+     *
+     * @example
+     * ```ts
+     * import { getDefaultLogger } from '@socketsecurity/lib/logger'
+     *
+     * const logger = getDefaultLogger()
+     * await httpDownload('https://example.com/file.zip', '/tmp/file.zip', {
+     *   logger,
+     *   progressInterval: 10  // Log every 10%
+     * })
+     * // Output:
+     * //   Progress: 10% (5.2 MB / 52.0 MB)
+     * //   Progress: 20% (10.4 MB / 52.0 MB)
+     * //   ...
+     * ```
+     */
+    logger?: Logger | undefined;
     /**
      * Callback for tracking download progress.
      * Called periodically as data is received.
+     * Takes precedence over `logger` if both are provided.
      *
      * @param downloaded - Number of bytes downloaded so far
      * @param total - Total file size in bytes (from Content-Length header)
@@ -288,6 +311,29 @@ export interface HttpDownloadOptions {
      * ```
      */
     onProgress?: ((downloaded: number, total: number) => void) | undefined;
+    /**
+     * Progress reporting interval as a percentage (0-100).
+     * Only used when `logger` is provided.
+     * Progress will be logged each time the download advances by this percentage.
+     *
+     * @default 10
+     *
+     * @example
+     * ```ts
+     * // Log every 10%
+     * await httpDownload('https://example.com/file.zip', '/tmp/file.zip', {
+     *   logger: getDefaultLogger(),
+     *   progressInterval: 10
+     * })
+     *
+     * // Log every 25%
+     * await httpDownload('https://example.com/file.zip', '/tmp/file.zip', {
+     *   logger: getDefaultLogger(),
+     *   progressInterval: 25
+     * })
+     * ```
+     */
+    progressInterval?: number | undefined;
     /**
      * Number of retry attempts for failed downloads.
      * Uses exponential backoff: delay = `retryDelay` * 2^attempt.

package/dist/http-request.js

@@ -184,17 +184,34 @@ async function httpRequestAttempt(url, options) {
 async function httpDownload(url, destPath, options) {
   const {
     headers = {},
+    logger,
     onProgress,
+    progressInterval = 10,
     retries = 0,
     retryDelay = 1e3,
     timeout = 12e4
   } = { __proto__: null, ...options };
+  let progressCallback;
+  if (onProgress) {
+    progressCallback = onProgress;
+  } else if (logger) {
+    let lastPercent = 0;
+    progressCallback = (downloaded, total) => {
+      const percent = Math.floor(downloaded / total * 100);
+      if (percent >= lastPercent + progressInterval) {
+        logger.log(
+          `  Progress: ${percent}% (${(downloaded / 1024 / 1024).toFixed(1)} MB / ${(total / 1024 / 1024).toFixed(1)} MB)`
+        );
+        lastPercent = percent;
+      }
+    };
+  }
   let lastError;
   for (let attempt = 0; attempt <= retries; attempt++) {
     try {
       return await httpDownloadAttempt(url, destPath, {
         headers,
-        onProgress,
+        onProgress: progressCallback,
         timeout
       });
     } catch (e) {

package/dist/json/edit.d.ts

@@ -0,0 +1,16 @@
+import type { EditableJsonConstructor } from './types';
+/**
+ * Get the EditableJson class for JSON file manipulation.
+ *
+ * @example
+ * ```ts
+ * import { getEditableJsonClass } from '@socketsecurity/lib/json'
+ *
+ * const EditableJson = getEditableJsonClass<MyConfigType>()
+ * const config = await EditableJson.load('./config.json')
+ * config.update({ someField: 'newValue' })
+ * await config.save({ sort: true })
+ * ```
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function getEditableJsonClass<T = Record<string, unknown>>(): EditableJsonConstructor<T>;

package/dist/json/edit.js

@@ -0,0 +1,248 @@
+"use strict";
+/* Socket Lib - Built with esbuild */
+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 edit_exports = {};
+__export(edit_exports, {
+  getEditableJsonClass: () => getEditableJsonClass
+});
+module.exports = __toCommonJS(edit_exports);
+var import_promises = require("node:timers/promises");
+var import_format = require("./format");
+const identSymbol = import_format.INDENT_SYMBOL;
+const newlineSymbol = import_format.NEWLINE_SYMBOL;
+const JSONParse = JSON.parse;
+let _EditableJsonClass;
+let _fs;
+// @__NO_SIDE_EFFECTS__
+function getFs() {
+  if (_fs === void 0) {
+    _fs = require("node:fs");
+  }
+  return _fs;
+}
+async function retryWrite(filepath, content, retries = 3, baseDelay = 10) {
+  const { promises: fsPromises } = /* @__PURE__ */ getFs();
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    try {
+      await fsPromises.writeFile(filepath, content);
+      if (process.platform === "win32") {
+        await (0, import_promises.setTimeout)(50);
+        let accessRetries = 0;
+        const maxAccessRetries = 5;
+        while (accessRetries < maxAccessRetries) {
+          try {
+            await fsPromises.access(filepath);
+            await (0, import_promises.setTimeout)(10);
+            break;
+          } catch {
+            const delay = 20 * (accessRetries + 1);
+            await (0, import_promises.setTimeout)(delay);
+            accessRetries++;
+          }
+        }
+      }
+      return;
+    } catch (err) {
+      const isLastAttempt = attempt === retries;
+      const isRetriableError = err instanceof Error && "code" in err && (err.code === "EPERM" || err.code === "EBUSY" || err.code === "ENOENT");
+      if (!isRetriableError || isLastAttempt) {
+        throw err;
+      }
+      const delay = baseDelay * 2 ** attempt;
+      await (0, import_promises.setTimeout)(delay);
+    }
+  }
+}
+function parseJson(content) {
+  return JSONParse(content);
+}
+async function readFile(filepath) {
+  const { promises: fsPromises } = /* @__PURE__ */ getFs();
+  const maxRetries = process.platform === "win32" ? 5 : 1;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fsPromises.readFile(filepath, "utf8");
+    } catch (err) {
+      const isLastAttempt = attempt === maxRetries;
+      const isEnoent = err instanceof Error && "code" in err && err.code === "ENOENT";
+      if (!isEnoent || isLastAttempt) {
+        throw err;
+      }
+      const delay = process.platform === "win32" ? 50 * (attempt + 1) : 20;
+      await (0, import_promises.setTimeout)(delay);
+    }
+  }
+  throw new Error("Unreachable code");
+}
+// @__NO_SIDE_EFFECTS__
+function getEditableJsonClass() {
+  if (_EditableJsonClass === void 0) {
+    _EditableJsonClass = class EditableJson {
+      _canSave = true;
+      _content = {};
+      _path = void 0;
+      _readFileContent = "";
+      _readFileJson = void 0;
+      get content() {
+        return this._content;
+      }
+      get filename() {
+        const path = this._path;
+        if (!path) {
+          return "";
+        }
+        return path;
+      }
+      get path() {
+        return this._path;
+      }
+      static async create(path, opts = {}) {
+        const instance = new EditableJson();
+        instance.create(path);
+        return opts.data ? instance.update(opts.data) : instance;
+      }
+      static async load(path, opts = {}) {
+        const instance = new EditableJson();
+        if (!opts.create) {
+          return await instance.load(path);
+        }
+        try {
+          return await instance.load(path);
+        } catch (err) {
+          if (!err.message.includes("ENOENT") && !err.message.includes("no such file")) {
+            throw err;
+          }
+          return instance.create(path);
+        }
+      }
+      create(path) {
+        this._path = path;
+        this._content = {};
+        this._canSave = true;
+        return this;
+      }
+      fromContent(data) {
+        this._content = data;
+        this._canSave = false;
+        return this;
+      }
+      fromJSON(data) {
+        const parsed = parseJson(data);
+        const indent = (0, import_format.detectIndent)(data);
+        const newline = (0, import_format.detectNewline)(data);
+        parsed[identSymbol] = indent;
+        parsed[newlineSymbol] = newline;
+        this._content = parsed;
+        return this;
+      }
+      async load(path, create) {
+        this._path = path;
+        let parseErr;
+        try {
+          this._readFileContent = await readFile(this.filename);
+        } catch (err) {
+          if (!create) {
+            throw err;
+          }
+          parseErr = err;
+        }
+        if (parseErr) {
+          throw parseErr;
+        }
+        this.fromJSON(this._readFileContent);
+        this._readFileJson = parseJson(this._readFileContent);
+        return this;
+      }
+      update(content) {
+        this._content = {
+          ...this._content,
+          ...content
+        };
+        return this;
+      }
+      async save(options) {
+        if (!this._canSave || this.content === void 0) {
+          throw new Error("No file path to save to");
+        }
+        if (!(0, import_format.shouldSave)(
+          this.content,
+          this._readFileJson,
+          this._readFileContent,
+          options
+        )) {
+          return false;
+        }
+        const content = (0, import_format.stripFormattingSymbols)(
+          this.content
+        );
+        const sortedContent = options?.sort ? (0, import_format.sortKeys)(content) : content;
+        const formatting = (0, import_format.getFormattingFromContent)(
+          this.content
+        );
+        const fileContent = (0, import_format.stringifyWithFormatting)(sortedContent, formatting);
+        await retryWrite(this.filename, fileContent);
+        this._readFileContent = fileContent;
+        this._readFileJson = parseJson(fileContent);
+        return true;
+      }
+      saveSync(options) {
+        if (!this._canSave || this.content === void 0) {
+          throw new Error("No file path to save to");
+        }
+        if (!(0, import_format.shouldSave)(
+          this.content,
+          this._readFileJson,
+          this._readFileContent,
+          options
+        )) {
+          return false;
+        }
+        const content = (0, import_format.stripFormattingSymbols)(
+          this.content
+        );
+        const sortedContent = options?.sort ? (0, import_format.sortKeys)(content) : content;
+        const formatting = (0, import_format.getFormattingFromContent)(
+          this.content
+        );
+        const fileContent = (0, import_format.stringifyWithFormatting)(sortedContent, formatting);
+        const fs = /* @__PURE__ */ getFs();
+        fs.writeFileSync(this.filename, fileContent);
+        this._readFileContent = fileContent;
+        this._readFileJson = parseJson(fileContent);
+        return true;
+      }
+      willSave(options) {
+        if (!this._canSave || this.content === void 0) {
+          return false;
+        }
+        return (0, import_format.shouldSave)(
+          this.content,
+          this._readFileJson,
+          this._readFileContent,
+          options
+        );
+      }
+    };
+  }
+  return _EditableJsonClass;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  getEditableJsonClass
+});