@socketsecurity/lib 4.4.0 → 5.0.0

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,7 +575,7 @@ 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.

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/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,217 @@
+"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_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);
+      return;
+    } catch (err) {
+      const isLastAttempt = attempt === retries;
+      const isEperm = err instanceof Error && "code" in err && (err.code === "EPERM" || err.code === "EBUSY");
+      if (!isEperm || isLastAttempt) {
+        throw err;
+      }
+      const delay = baseDelay * 2 ** attempt;
+      await new Promise((resolve) => setTimeout(resolve, delay));
+    }
+  }
+}
+function parseJson(content) {
+  return JSONParse(content);
+}
+async function readFile(filepath) {
+  const { promises: fsPromises } = /* @__PURE__ */ getFs();
+  return await fsPromises.readFile(filepath, "utf8");
+}
+// @__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
+});

package/dist/json/format.d.ts

@@ -0,0 +1,140 @@
+/**
+ * @fileoverview Shared utilities for JSON formatting preservation and manipulation.
+ * Provides functions for detecting and preserving indentation, line endings, and
+ * determining when JSON files should be saved based on content changes.
+ */
+/**
+ * Symbols used to store formatting metadata in JSON objects.
+ */
+export declare const INDENT_SYMBOL: unique symbol;
+export declare const NEWLINE_SYMBOL: unique symbol;
+/**
+ * Formatting metadata for JSON files.
+ */
+export interface JsonFormatting {
+    indent: string | number;
+    newline: string;
+}
+/**
+ * Options for determining if a save should occur.
+ */
+export interface ShouldSaveOptions {
+    ignoreWhitespace?: boolean;
+    sort?: boolean;
+    sortFn?: (obj: Record<string, unknown>) => Record<string, unknown>;
+}
+/**
+ * Detect indentation from a JSON string.
+ * Supports space-based indentation (returns count) or mixed indentation (returns string).
+ *
+ * @param json - JSON string to analyze
+ * @returns Number of spaces or indentation string, defaults to 2 if not detected
+ *
+ * @example
+ * ```ts
+ * detectIndent('{\n  "key": "value"\n}')  // => 2
+ * detectIndent('{\n    "key": "value"\n}')  // => 4
+ * detectIndent('{\n\t"key": "value"\n}')  // => '\t'
+ * ```
+ */
+export declare function detectIndent(json: string): string | number;
+/**
+ * Detect newline character(s) from a JSON string.
+ * Supports LF (\n) and CRLF (\r\n) line endings.
+ *
+ * @param json - JSON string to analyze
+ * @returns Line ending string ('\n' or '\r\n'), defaults to '\n' if not detected
+ *
+ * @example
+ * ```ts
+ * detectNewline('{\n  "key": "value"\n}')  // => '\n'
+ * detectNewline('{\r\n  "key": "value"\r\n}')  // => '\r\n'
+ * ```
+ */
+export declare function detectNewline(json: string): string;
+/**
+ * Extract formatting metadata from a JSON string.
+ *
+ * @param json - JSON string to analyze
+ * @returns Object containing indent and newline formatting
+ *
+ * @example
+ * ```ts
+ * const formatting = extractFormatting('{\n  "key": "value"\n}')
+ * // => { indent: 2, newline: '\n' }
+ * ```
+ */
+export declare function extractFormatting(json: string): JsonFormatting;
+/**
+ * Get default formatting for JSON files.
+ *
+ * @returns Default formatting (2 spaces, LF line endings)
+ */
+export declare function getDefaultFormatting(): JsonFormatting;
+/**
+ * Sort object keys alphabetically.
+ * Creates a new object with sorted keys (does not mutate input).
+ *
+ * @param obj - Object to sort
+ * @returns New object with alphabetically sorted keys
+ *
+ * @example
+ * ```ts
+ * sortKeys({ z: 3, a: 1, m: 2 })
+ * // => { a: 1, m: 2, z: 3 }
+ * ```
+ */
+export declare function sortKeys(obj: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Stringify JSON with specific formatting.
+ * Applies indentation and line ending preferences.
+ *
+ * @param content - Object to stringify
+ * @param formatting - Formatting preferences (indent and newline)
+ * @returns Formatted JSON string with trailing newline
+ *
+ * @example
+ * ```ts
+ * stringifyWithFormatting(
+ *   { key: 'value' },
+ *   { indent: 4, newline: '\r\n' }
+ * )
+ * // => '{\r\n    "key": "value"\r\n}\r\n'
+ * ```
+ */
+export declare function stringifyWithFormatting(content: Record<string, unknown>, formatting: JsonFormatting): string;
+/**
+ * Strip formatting symbols from content object.
+ * Removes Symbol.for('indent') and Symbol.for('newline') from the object.
+ *
+ * @param content - Content object with potential symbol properties
+ * @returns Object with symbols removed
+ */
+export declare function stripFormattingSymbols(content: Record<string | symbol, unknown>): Record<string, unknown>;
+/**
+ * Extract formatting from content object that has symbol-based metadata.
+ *
+ * @param content - Content object with Symbol.for('indent') and Symbol.for('newline')
+ * @returns Formatting metadata, or defaults if symbols not present
+ */
+export declare function getFormattingFromContent(content: Record<string | symbol, unknown>): JsonFormatting;
+/**
+ * Determine if content should be saved based on changes and options.
+ * Compares current content with original content and respects options like
+ * ignoreWhitespace and sort.
+ *
+ * @param currentContent - Current content object (may include formatting symbols)
+ * @param originalContent - Original content for comparison (may include formatting symbols)
+ * @param originalFileContent - Original file content as string (for whitespace comparison)
+ * @param options - Options controlling save behavior
+ * @returns true if content should be saved, false otherwise
+ *
+ * @example
+ * ```ts
+ * const current = { key: 'new-value', [Symbol.for('indent')]: 2 }
+ * const original = { key: 'old-value', [Symbol.for('indent')]: 2 }
+ * shouldSave(current, original, '{\n  "key": "old-value"\n}\n')
+ * // => true
+ * ```
+ */
+export declare function shouldSave(currentContent: Record<string | symbol, unknown>, originalContent: Record<string | symbol, unknown> | undefined, originalFileContent: string, options?: ShouldSaveOptions): boolean;

package/dist/json/format.js

@@ -0,0 +1,121 @@
+"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 format_exports = {};
+__export(format_exports, {
+  INDENT_SYMBOL: () => INDENT_SYMBOL,
+  NEWLINE_SYMBOL: () => NEWLINE_SYMBOL,
+  detectIndent: () => detectIndent,
+  detectNewline: () => detectNewline,
+  extractFormatting: () => extractFormatting,
+  getDefaultFormatting: () => getDefaultFormatting,
+  getFormattingFromContent: () => getFormattingFromContent,
+  shouldSave: () => shouldSave,
+  sortKeys: () => sortKeys,
+  stringifyWithFormatting: () => stringifyWithFormatting,
+  stripFormattingSymbols: () => stripFormattingSymbols
+});
+module.exports = __toCommonJS(format_exports);
+const INDENT_SYMBOL = Symbol.for("indent");
+const NEWLINE_SYMBOL = Symbol.for("newline");
+function detectIndent(json) {
+  const match = json.match(/^[{[][\r\n]+(\s+)/m);
+  if (!match) {
+    return 2;
+  }
+  const indent = match[1];
+  if (/^ +$/.test(indent)) {
+    return indent.length;
+  }
+  return indent;
+}
+function detectNewline(json) {
+  const match = json.match(/\r?\n/);
+  return match ? match[0] : "\n";
+}
+function extractFormatting(json) {
+  return {
+    indent: detectIndent(json),
+    newline: detectNewline(json)
+  };
+}
+function getDefaultFormatting() {
+  return {
+    indent: 2,
+    newline: "\n"
+  };
+}
+function sortKeys(obj) {
+  const sorted = { __proto__: null };
+  const keys = Object.keys(obj).sort();
+  for (const key of keys) {
+    sorted[key] = obj[key];
+  }
+  return sorted;
+}
+function stringifyWithFormatting(content, formatting) {
+  const { indent, newline } = formatting;
+  const format = indent === void 0 || indent === null ? "  " : indent;
+  const eol = newline === void 0 || newline === null ? "\n" : newline;
+  return `${JSON.stringify(content, void 0, format)}
+`.replace(/\n/g, eol);
+}
+function stripFormattingSymbols(content) {
+  const {
+    [INDENT_SYMBOL]: _indent,
+    [NEWLINE_SYMBOL]: _newline,
+    ...rest
+  } = content;
+  return rest;
+}
+function getFormattingFromContent(content) {
+  const indent = content[INDENT_SYMBOL];
+  const newline = content[NEWLINE_SYMBOL];
+  return {
+    indent: indent === void 0 || indent === null ? 2 : indent,
+    newline: newline === void 0 || newline === null ? "\n" : newline
+  };
+}
+function shouldSave(currentContent, originalContent, originalFileContent, options = {}) {
+  const { ignoreWhitespace = false, sort = false, sortFn } = options;
+  const content = stripFormattingSymbols(currentContent);
+  const sortedContent = sortFn ? sortFn(content) : sort ? sortKeys(content) : content;
+  const origContent = originalContent ? stripFormattingSymbols(originalContent) : {};
+  if (ignoreWhitespace) {
+    const util = require("node:util");
+    return !util.isDeepStrictEqual(sortedContent, origContent);
+  }
+  const formatting = getFormattingFromContent(currentContent);
+  const newFileContent = stringifyWithFormatting(sortedContent, formatting);
+  return newFileContent.trim() !== originalFileContent.trim();
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  INDENT_SYMBOL,
+  NEWLINE_SYMBOL,
+  detectIndent,
+  detectNewline,
+  extractFormatting,
+  getDefaultFormatting,
+  getFormattingFromContent,
+  shouldSave,
+  sortKeys,
+  stringifyWithFormatting,
+  stripFormattingSymbols
+});