@socketsecurity/lib 4.3.0 → 5.0.0

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
+});

package/dist/json/parse.d.ts

@@ -0,0 +1,76 @@
+import type { JsonParseOptions, JsonPrimitive, JsonValue } from './types';
+/**
+ * Check if a value is a JSON primitive type.
+ * JSON primitives are: `null`, `boolean`, `number`, or `string`.
+ *
+ * @param value - Value to check
+ * @returns `true` if value is a JSON primitive, `false` otherwise
+ *
+ * @example
+ * ```ts
+ * isJsonPrimitive(null) // => true
+ * isJsonPrimitive(true) // => true
+ * isJsonPrimitive(42) // => true
+ * isJsonPrimitive('hello') // => true
+ * isJsonPrimitive({}) // => false
+ * isJsonPrimitive([]) // => false
+ * isJsonPrimitive(undefined) // => false
+ * ```
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function isJsonPrimitive(value: unknown): value is JsonPrimitive;
+/**
+ * Parse JSON content with automatic Buffer handling and BOM stripping.
+ * Provides safer JSON parsing with helpful error messages and optional error suppression.
+ *
+ * Features:
+ * - Automatic UTF-8 Buffer conversion
+ * - BOM (Byte Order Mark) stripping for cross-platform compatibility
+ * - Enhanced error messages with filepath context
+ * - Optional error suppression (returns `undefined` instead of throwing)
+ * - Optional reviver for transforming parsed values
+ *
+ * @param content - JSON string or Buffer to parse
+ * @param options - Optional parsing configuration
+ * @returns Parsed JSON value, or `undefined` if parsing fails and `throws` is `false`
+ *
+ * @throws {SyntaxError} When JSON is invalid and `throws` is `true` (default)
+ *
+ * @example
+ * ```ts
+ * // Basic usage
+ * const data = jsonParse('{"name":"example"}')
+ * console.log(data.name) // => 'example'
+ *
+ * // Parse Buffer with UTF-8 BOM
+ * const buffer = Buffer.from('\uFEFF{"value":42}')
+ * const data = jsonParse(buffer)
+ * console.log(data.value) // => 42
+ *
+ * // Enhanced error messages with filepath
+ * try {
+ *   jsonParse('invalid', { filepath: 'config.json' })
+ * } catch (err) {
+ *   console.error(err.message)
+ *   // => "config.json: Unexpected token i in JSON at position 0"
+ * }
+ *
+ * // Suppress errors
+ * const result = jsonParse('invalid', { throws: false })
+ * console.log(result) // => undefined
+ *
+ * // Transform values with reviver
+ * const json = '{"created":"2024-01-15T10:30:00Z"}'
+ * const data = jsonParse(json, {
+ *   reviver: (key, value) => {
+ *     if (key === 'created' && typeof value === 'string') {
+ *       return new Date(value)
+ *     }
+ *     return value
+ *   }
+ * })
+ * console.log(data.created instanceof Date) // => true
+ * ```
+ */
+/*@__NO_SIDE_EFFECTS__*/
+export declare function jsonParse(content: string | Buffer, options?: JsonParseOptions | undefined): JsonValue | undefined;

package/dist/{json.js → json/parse.js}

@@ -17,13 +17,13 @@ var __copyProps = (to, from, except, desc) => {
   return to;
 };
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var json_exports = {};
-__export(json_exports, {
+var parse_exports = {};
+__export(parse_exports, {
   isJsonPrimitive: () => isJsonPrimitive,
   jsonParse: () => jsonParse
 });
-module.exports = __toCommonJS(json_exports);
-var import_strings = require("./strings");
+module.exports = __toCommonJS(parse_exports);
+var import_strings = require("../strings");
 const JSONParse = JSON.parse;
 // @__NO_SIDE_EFFECTS__
 function isBuffer(x) {