@socketsecurity/lib 4.4.0 → 5.0.1

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) {

package/dist/json/types.d.ts

@@ -0,0 +1,229 @@
+/**
+ * @fileoverview JSON type definitions and interfaces.
+ */
+/**
+ * JSON primitive types: `null`, `boolean`, `number`, or `string`.
+ *
+ * @example
+ * ```ts
+ * const primitives: JsonPrimitive[] = [null, true, 42, 'hello']
+ * ```
+ */
+export type JsonPrimitive = null | boolean | number | string;
+/**
+ * A JSON array containing JSON values.
+ *
+ * @example
+ * ```ts
+ * const arr: JsonArray = [1, 'two', { three: 3 }, [4, 5]]
+ * ```
+ */
+export interface JsonArray extends Array<JsonValue> {
+}
+/**
+ * A JSON object with string keys and JSON values.
+ *
+ * @example
+ * ```ts
+ * const obj: JsonObject = {
+ *   name: 'example',
+ *   count: 42,
+ *   active: true,
+ *   nested: { key: 'value' }
+ * }
+ * ```
+ */
+export interface JsonObject {
+    [key: string]: JsonValue;
+}
+/**
+ * Any valid JSON value: primitive, object, or array.
+ *
+ * @example
+ * ```ts
+ * const values: JsonValue[] = [
+ *   null,
+ *   true,
+ *   42,
+ *   'hello',
+ *   { key: 'value' },
+ *   [1, 2, 3]
+ * ]
+ * ```
+ */
+export type JsonValue = JsonPrimitive | JsonObject | JsonArray;
+/**
+ * Reviver function for transforming parsed JSON values.
+ * Called for each key-value pair during parsing.
+ *
+ * @param key - The object key or array index being parsed
+ * @param value - The parsed value
+ * @returns The transformed value (or original if no transform needed)
+ *
+ * @example
+ * ```ts
+ * // Convert date strings to Date objects
+ * const reviver: JsonReviver = (key, value) => {
+ *   if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}/.test(value)) {
+ *     return new Date(value)
+ *   }
+ *   return value
+ * }
+ * ```
+ */
+export type JsonReviver = (key: string, value: unknown) => unknown;
+/**
+ * Options for JSON parsing operations.
+ */
+export interface JsonParseOptions {
+    /**
+     * Optional filepath for improved error messages.
+     * When provided, errors will be prefixed with the filepath.
+     *
+     * @example
+     * ```ts
+     * // Error message will be: "config.json: Unexpected token } in JSON"
+     * jsonParse('invalid', { filepath: 'config.json' })
+     * ```
+     */
+    filepath?: string | undefined;
+    /**
+     * Optional reviver function to transform parsed values.
+     * Called for each key-value pair during parsing.
+     *
+     * @example
+     * ```ts
+     * // Convert ISO date strings to Date objects
+     * const options = {
+     *   reviver: (key, value) => {
+     *     if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}/.test(value)) {
+     *       return new Date(value)
+     *     }
+     *     return value
+     *   }
+     * }
+     * ```
+     */
+    reviver?: JsonReviver | undefined;
+    /**
+     * Whether to throw on parse errors.
+     * When `false`, returns `undefined` instead of throwing.
+     *
+     * @default true
+     *
+     * @example
+     * ```ts
+     * // Throws error
+     * jsonParse('invalid', { throws: true })
+     *
+     * // Returns undefined
+     * const result = jsonParse('invalid', { throws: false })
+     * ```
+     */
+    throws?: boolean | undefined;
+}
+/**
+ * Options for saving editable JSON files.
+ */
+export interface EditableJsonSaveOptions {
+    /**
+     * Whether to ignore whitespace-only changes when determining if save is needed.
+     * @default false
+     */
+    ignoreWhitespace?: boolean | undefined;
+    /**
+     * Whether to sort object keys alphabetically before saving.
+     * @default false
+     */
+    sort?: boolean | undefined;
+}
+/**
+ * Options for creating or loading editable JSON instances.
+ */
+export interface EditableJsonOptions<T = Record<string, unknown>> {
+    /**
+     * File path for the JSON file (optional for in-memory instances).
+     */
+    path?: string | undefined;
+    /**
+     * Whether to create the file if it doesn't exist during load.
+     * @default false
+     */
+    create?: boolean | undefined;
+    /**
+     * Initial data to populate the instance with.
+     */
+    data?: T | undefined;
+}
+/**
+ * EditableJson instance interface for JSON file manipulation.
+ * Provides core functionality for loading, editing, and saving JSON files
+ * while preserving formatting (indentation and line endings).
+ */
+export interface EditableJsonInstance<T = Record<string, unknown>> {
+    /**
+     * The parsed JSON content as a readonly object.
+     * @readonly
+     */
+    content: Readonly<T>;
+    /**
+     * Create a new JSON file at the specified path.
+     * @param path - The file path where JSON will be created
+     */
+    create(path: string): this;
+    /**
+     * Initialize the instance from a content object.
+     * Note: Disables saving when used (no file path associated).
+     * @param content - The JSON content object
+     */
+    fromContent(content: unknown): this;
+    /**
+     * Initialize the instance from a JSON string.
+     * @param json - The JSON content as a string
+     */
+    fromJSON(json: string): this;
+    /**
+     * Load a JSON file from the specified path.
+     * @param path - The file path to load
+     * @param create - Whether to create the file if it doesn't exist
+     */
+    load(path: string, create?: boolean): Promise<this>;
+    /**
+     * Update the JSON content with new values.
+     * @param content - Partial object with fields to update
+     */
+    update(content: Partial<T>): this;
+    /**
+     * Save the JSON file to disk.
+     * @param options - Save options for formatting and sorting
+     */
+    save(options?: EditableJsonSaveOptions): Promise<boolean>;
+    /**
+     * Synchronously save the JSON file to disk.
+     * @param options - Save options for formatting and sorting
+     */
+    saveSync(options?: EditableJsonSaveOptions): boolean;
+    /**
+     * Check if the JSON will be saved based on current changes.
+     * @param options - Save options to evaluate
+     */
+    willSave(options?: EditableJsonSaveOptions): boolean;
+    /**
+     * The full path to the JSON file.
+     * @readonly
+     */
+    readonly filename: string;
+    /**
+     * The directory path containing the JSON file.
+     * @readonly
+     */
+    readonly path: string | undefined;
+}
+/**
+ * EditableJson constructor interface.
+ */
+export interface EditableJsonConstructor<T = Record<string, unknown>> {
+    new (): EditableJsonInstance<T>;
+    create(path: string, opts?: EditableJsonOptions<T>): Promise<EditableJsonInstance<T>>;
+    load(path: string, opts?: EditableJsonOptions<T>): Promise<EditableJsonInstance<T>>;
+}

package/dist/json/types.js

@@ -0,0 +1,17 @@
+"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 __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 types_exports = {};
+module.exports = __toCommonJS(types_exports);

package/dist/packages/{editable.js → edit.js}

@@ -27,22 +27,21 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   mod
 ));
 var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
-var editable_exports = {};
-__export(editable_exports, {
+var edit_exports = {};
+__export(edit_exports, {
   getEditablePackageJsonClass: () => getEditablePackageJsonClass,
   pkgJsonToEditable: () => pkgJsonToEditable,
   toEditablePackageJson: () => toEditablePackageJson,
   toEditablePackageJsonSync: () => toEditablePackageJsonSync
 });
-module.exports = __toCommonJS(editable_exports);
+module.exports = __toCommonJS(edit_exports);
 var import_package_json = __toESM(require("../external/@npmcli/package-json"));
 var import_read_package = require("../external/@npmcli/package-json/lib/read-package");
 var import_sort = require("../external/@npmcli/package-json/lib/sort");
+var import_format = require("../json/format");
 var import_normalize = require("../paths/normalize");
 var import_normalize2 = require("./normalize");
 var import_packages = require("../paths/packages");
-const identSymbol = Symbol.for("indent");
-const newlineSymbol = Symbol.for("newline");
 let _EditablePackageJsonClass;
 let _fs;
 // @__NO_SIDE_EFFECTS__
@@ -193,35 +192,22 @@ function getEditablePackageJsonClass() {
         if (!this._canSave || this.content === void 0) {
           throw new Error("No package.json to save to");
         }
-        const { ignoreWhitespace = false, sort = false } = {
-          __proto__: null,
-          ...options
-        };
-        const {
-          [identSymbol]: indent,
-          [newlineSymbol]: newline,
-          ...rest
-        } = this.content;
-        const content = sort ? (0, import_sort.packageSort)(rest) : rest;
-        const {
-          [identSymbol]: _indent,
-          [newlineSymbol]: _newline,
-          ...origContent
-        } = this._readFileJson || {};
-        if (ignoreWhitespace && (/* @__PURE__ */ getUtil()).isDeepStrictEqual(content, origContent)) {
-          return false;
-        }
-        const format = indent === void 0 || indent === null ? "  " : indent;
-        const eol = newline === void 0 || newline === null ? "\n" : newline;
-        const fileContent = `${JSON.stringify(
-          content,
-          void 0,
-          format
-        )}
-`.replace(/\n/g, eol);
-        if (!ignoreWhitespace && fileContent.trim() === this._readFileContent.trim()) {
+        if (!(0, import_format.shouldSave)(
+          this.content,
+          this._readFileJson,
+          this._readFileContent,
+          { ...options, sortFn: options?.sort ? import_sort.packageSort : void 0 }
+        )) {
           return false;
         }
+        const content = (0, import_format.stripFormattingSymbols)(
+          this.content
+        );
+        const sortedContent = options?.sort ? (0, import_sort.packageSort)(content) : content;
+        const formatting = (0, import_format.getFormattingFromContent)(
+          this.content
+        );
+        const fileContent = (0, import_format.stringifyWithFormatting)(sortedContent, formatting);
         const { promises: fsPromises } = /* @__PURE__ */ getFs();
         await fsPromises.writeFile(this.filename, fileContent);
         this._readFileContent = fileContent;