ts-data-forge 14.6.1 → 14.6.2

package/dist/json/json.mjs

@@ -1,111 +1,352 @@
-import '../number/branded-types/finite-number.mjs';
-import '../number/branded-types/int.mjs';
-import '../number/branded-types/int16.mjs';
-import '../number/branded-types/int32.mjs';
-import '../number/branded-types/negative-finite-number.mjs';
-import '../number/branded-types/negative-int.mjs';
-import '../number/branded-types/negative-safe-int.mjs';
-import '../number/branded-types/non-negative-finite-number.mjs';
-import '../number/branded-types/non-negative-int16.mjs';
-import '../number/branded-types/non-negative-int32.mjs';
-import '../number/branded-types/non-positive-finite-number.mjs';
-import '../number/branded-types/non-positive-int.mjs';
-import '../number/branded-types/non-positive-safe-int.mjs';
-import '../number/branded-types/non-zero-finite-number.mjs';
-import '../number/branded-types/non-zero-int.mjs';
-import '../number/branded-types/non-zero-int16.mjs';
-import '../number/branded-types/non-zero-int32.mjs';
-import '../number/branded-types/non-zero-safe-int.mjs';
-import '../number/branded-types/non-zero-uint16.mjs';
-import '../number/branded-types/non-zero-uint32.mjs';
-import '../number/branded-types/positive-finite-number.mjs';
-import '../number/branded-types/positive-int.mjs';
-import '../number/branded-types/positive-int16.mjs';
-import '../number/branded-types/positive-int32.mjs';
-import '../number/branded-types/positive-safe-int.mjs';
-import '../number/branded-types/positive-uint16.mjs';
-import '../number/branded-types/positive-uint32.mjs';
-import '../number/branded-types/safe-int.mjs';
-import '../number/branded-types/safe-uint.mjs';
-import '../number/branded-types/uint.mjs';
-import '../number/branded-types/uint16.mjs';
-import '../number/branded-types/uint32.mjs';
-import '../number/enum/int8.mjs';
-import '../number/enum/uint8.mjs';
-import '../number/num.mjs';
-import '../number/refined-number-utils.mjs';
-import { err } from '../functional/result/impl/result-err.mjs';
-import { ok } from '../functional/result/impl/result-ok.mjs';
-import { isRecord } from '../guard/is-record.mjs';
-import '@sindresorhus/is';
-import { castMutable } from '../others/cast-mutable.mjs';
-import { unknownToString } from '../others/unknown-to-string.mjs';
-import { pipe } from '../functional/pipe.mjs';
-import '../collections/imap-mapped.mjs';
-import '../collections/imap.mjs';
-import '../collections/iset-mapped.mjs';
-import '../collections/iset.mjs';
-import { uniq } from '../array/impl/array-utils-transformation.mjs';
-
-var Json;
-((Json2) => {
-  Json2.parse = (text, reviver) => {
-    try {
-      return ok(
-        JSON.parse(
-          text,
-          // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-          reviver
-        )
-      );
-    } catch (error) {
-      const errStr = unknownToString(error);
-      return err(errStr);
-    }
-  };
-  Json2.stringify = (value, replacer, space) => {
-    try {
-      return ok(JSON.stringify(value, replacer, space));
-    } catch (error) {
-      const errStr = unknownToString(error);
-      return err(errStr);
-    }
-  };
-  Json2.stringifySelected = (value, propertiesToBeSelected, space) => {
-    try {
-      return ok(
-        JSON.stringify(value, castMutable(propertiesToBeSelected), space)
-      );
-    } catch (error) {
-      const errStr = unknownToString(error);
-      return err(errStr);
-    }
-  };
-  Json2.stringifySortedKey = (value, space) => {
-    const allKeys = pipe(keysDeep(value)).map(uniq).map((ks) => ks.toSorted()).value;
-    return (0, Json2.stringifySelected)(value, allKeys, space);
-  };
+import { Arr } from '../array/index.mjs';
+import { pipe, Result } from '../functional/index.mjs';
+import { isRecord } from '../guard/index.mjs';
+import { unknownToString } from '../others/index.mjs';
+/**
+ * A collection of type-safe JSON utility functions that provide safe parsing,
+ * stringification, and manipulation of JSON data. All functions return `Result`
+ * types to handle errors without throwing exceptions.
+ */
+export var Json;
+(function (Json) {
+    /**
+     * Safely converts a JSON string into a JavaScript value without throwing
+     * exceptions.
+     *
+     * This function provides type-safe JSON parsing by wrapping the native
+     * `JSON.parse` in a `Result` type, allowing you to handle parsing errors
+     * gracefully without try-catch blocks.
+     *
+     * @example
+     *
+     * ```ts
+     * const validJson = '{"name": "Alice", "age": 30}';
+     *
+     * const invalidJson = '{invalid json}';
+     *
+     * const parsed = Json.parse(validJson);
+     *
+     * const failed = Json.parse(invalidJson);
+     *
+     * assert.isTrue(Result.isOk(parsed));
+     *
+     * if (Result.isOk(parsed)) {
+     *   assert.deepStrictEqual(parsed.value, { name: 'Alice', age: 30 });
+     * }
+     *
+     * assert.isTrue(Result.isErr(failed));
+     *
+     * // With reviver
+     * const jsonWithDate = '{"created": "2024-01-01T00:00:00.000Z"}';
+     *
+     * const withReviver = Json.parse(jsonWithDate, (key, value) => {
+     *   if (key === 'created' && typeof value === 'string') {
+     *     return new Date(value);
+     *   }
+     *
+     *   return value;
+     * });
+     *
+     * assert.isTrue(Result.isOk(withReviver));
+     * ```
+     *
+     * @param text - A valid JSON string to parse. Can contain any valid JSON data
+     *   type: primitives (string, number, boolean, null), arrays, or objects.
+     * @param reviver - Optional function that transforms parsed values. Called
+     *   for each key-value pair in the JSON. The function receives the key name
+     *   and parsed value, and should return the transformed value. For nested
+     *   objects, inner objects are processed before outer objects.
+     * @returns A `Result<JsonValue, string>` containing:
+     *
+     *   - On success: `Result.ok(parsedValue)` where `parsedValue` is the parsed JSON
+     *   - On failure: `Result.err(errorMessage)` where `errorMessage` describes the
+     *       parsing error
+     */
+    Json.parse = (text, reviver) => {
+        try {
+            return Result.ok(JSON.parse(text, 
+            // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+            reviver));
+        }
+        catch (error) {
+            const errStr = unknownToString(error);
+            return Result.err(errStr);
+        }
+    };
+    /**
+     * Safely converts a JavaScript value to a JSON string without throwing
+     * exceptions.
+     *
+     * This function provides type-safe JSON stringification by wrapping the
+     * native `JSON.stringify` in a `Result` type, allowing you to handle
+     * serialization errors gracefully (such as circular references or BigInt
+     * values).
+     *
+     * @example
+     *
+     * ```ts
+     * const data = { name: 'Bob', age: 25, active: true } as const;
+     *
+     * // Basic stringify
+     * const basic = Json.stringify(data);
+     *
+     * assert.isTrue(Result.isOk(basic));
+     *
+     * if (Result.isOk(basic)) {
+     *   assert.isTrue(basic.value === '{"name":"Bob","age":25,"active":true}');
+     * }
+     *
+     * // With formatting
+     * const formatted = Json.stringify(data, undefined, 2);
+     *
+     * assert.isTrue(Result.isOk(formatted));
+     *
+     * // With replacer
+     * const filtered = Json.stringify(data, (key, value) => {
+     *   if (key === 'age') return undefined; // omit age field
+     *
+     *   return value;
+     * });
+     *
+     * assert.isTrue(Result.isOk(filtered));
+     *
+     * if (Result.isOk(filtered)) {
+     *   assert.isTrue(isString(filtered.value));
+     *
+     *   assert.isFalse(filtered.value.includes('age'));
+     * }
+     * ```
+     *
+     * @param value - The JavaScript value to serialize. Can be any value that
+     *   JSON.stringify accepts: primitives, objects, arrays. Non-serializable
+     *   values (functions, undefined, symbols) will be omitted or converted to
+     *   null according to JSON.stringify behavior.
+     * @param replacer - Optional function that transforms values during
+     *   serialization. Called for each key-value pair. Should return the value to
+     *   be serialized, or undefined to omit the property from the result.
+     * @param space - Optional parameter for formatting the output JSON:
+     *
+     *   - Number (1-10): Number of spaces to indent each level
+     *   - String: String to use for indentation (first 10 characters)
+     *   - Undefined/null: No formatting (compact output)
+     *
+     * @returns A `Result<string, string>` containing:
+     *
+     *   - On success: `Result.ok(jsonString)` where `jsonString` is the serialized
+     *       JSON
+     *   - On failure: `Result.err(errorMessage)` where `errorMessage` describes the
+     *       error
+     */
+    Json.stringify = (value, replacer, space) => {
+        try {
+            return Result.ok(JSON.stringify(value, replacer, space));
+        }
+        catch (error) {
+            const errStr = unknownToString(error);
+            return Result.err(errStr);
+        }
+    };
+    /**
+     * Safely converts a JavaScript value to a JSON string, including only the
+     * specified properties.
+     *
+     * This function provides selective serialization by allowing you to specify
+     * exactly which object properties should be included in the resulting JSON.
+     * It's useful for creating filtered or minimal representations of objects,
+     * such as for API responses or logging.
+     *
+     * @example
+     *
+     * ```ts
+     * const user = {
+     *   id: 1,
+     *   name: 'Charlie',
+     *   email: 'charlie@example.com',
+     *   password: 'secret123',
+     *   role: 'admin',
+     * } as const;
+     *
+     * // Select only safe properties to serialize
+     * const safeJson = Json.stringifySelected(user, ['id', 'name', 'role']);
+     *
+     * assert.isTrue(Result.isOk(safeJson));
+     *
+     * if (Result.isOk(safeJson)) {
+     *   assert.isTrue(isString(safeJson.value));
+     *
+     *   const parsed: unknown = JSON.parse(safeJson.value);
+     *
+     *   assert.deepStrictEqual(parsed, {
+     *     id: 1,
+     *     name: 'Charlie',
+     *     role: 'admin',
+     *   });
+     *
+     *   assert.isFalse(safeJson.value.includes('password'));
+     *
+     *   assert.isFalse(safeJson.value.includes('email'));
+     * }
+     *
+     * // With formatting
+     * const formatted = Json.stringifySelected(user, ['id', 'name'], 2);
+     *
+     * assert.isTrue(Result.isOk(formatted));
+     * ```
+     *
+     * @param value - The JavaScript value to serialize. While any value is
+     *   accepted, the property filtering only applies to objects and nested
+     *   objects.
+     * @param propertiesToBeSelected - Optional array of property names (strings)
+     *   and array indices (numbers) to include in the serialization. If provided,
+     *   only these properties will appear in the output JSON. If undefined, all
+     *   properties are included.
+     * @param space - Optional formatting parameter:
+     *
+     *   - Number (1-10): Number of spaces to indent each level
+     *   - String: String to use for indentation (first 10 characters)
+     *   - Undefined/null: No formatting (compact output)
+     *
+     * @returns A `Result<string, string>` containing:
+     *
+     *   - On success: `Result.ok(jsonString)` with only selected properties
+     *   - On failure: `Result.err(errorMessage)` describing the serialization error
+     */
+    Json.stringifySelected = (value, propertiesToBeSelected, space) => {
+        try {
+            return Result.ok(JSON.stringify(value, propertiesToBeSelected, space));
+        }
+        catch (error) {
+            const errStr = unknownToString(error);
+            return Result.err(errStr);
+        }
+    };
+    /**
+     * Safely converts a JavaScript record to a JSON string with keys sorted
+     * alphabetically at all levels.
+     *
+     * This function creates deterministic JSON output by ensuring that object
+     * keys appear in alphabetical order at every level of nesting. This is
+     * particularly useful for creating consistent output for comparison, hashing,
+     * caching, or when you need reproducible JSON representations across
+     * different JavaScript engines or runs.
+     *
+     * @example
+     *
+     * ```ts
+     * const unorderedData = {
+     *   zebra: 1,
+     *   apple: 2,
+     *   mango: 3,
+     *   nested: {
+     *     zulu: 'z',
+     *     alpha: 'a',
+     *     beta: 'b',
+     *   },
+     * } as const;
+     *
+     * // Keys will be sorted alphabetically at all levels
+     * const sorted = Json.stringifySortedKey(unorderedData);
+     *
+     * assert.isTrue(Result.isOk(sorted));
+     *
+     * if (Result.isOk(sorted)) {
+     *   // Keys should appear in alphabetical order
+     *   const expected =
+     *     '{"apple":2,"mango":3,"nested":{"alpha":"a","beta":"b","zulu":"z"},"zebra":1}';
+     *
+     *   assert.isTrue(sorted.value === expected);
+     * }
+     *
+     * // With formatting
+     * const formatted = Json.stringifySortedKey(unorderedData, 2);
+     *
+     * assert.isTrue(Result.isOk(formatted));
+     *
+     * if (Result.isOk(formatted)) {
+     *   assert.isTrue(isString(formatted.value));
+     *
+     *   // Check that keys are in order (first key should be "apple")
+     *   assert.isTrue(
+     *     formatted.value.indexOf('"apple"') < formatted.value.indexOf('"mango"'),
+     *   );
+     *
+     *   assert.isTrue(
+     *     formatted.value.indexOf('"mango"') <
+     *       formatted.value.indexOf('"nested"'),
+     *   );
+     *
+     *   assert.isTrue(
+     *     formatted.value.indexOf('"nested"') <
+     *       formatted.value.indexOf('"zebra"'),
+     *   );
+     * }
+     * ```
+     *
+     * @param value - An object (`UnknownRecord`) to serialize. Must be a plain
+     *   object (not an array, primitive, or null). Nested objects and arrays
+     *   within the object will also have their keys sorted alphabetically.
+     * @param space - Optional formatting parameter:
+     *
+     *   - Number (1-10): Number of spaces to indent each level
+     *   - String: String to use for indentation (first 10 characters)
+     *   - Undefined/null: No formatting (compact output)
+     *
+     * @returns A `Result<string, string>` containing:
+     *
+     *   - On success: `Result.ok(jsonString)` with all object keys sorted
+     *       alphabetically
+     *   - On failure: `Result.err(errorMessage)` describing the serialization error
+     */
+    Json.stringifySortedKey = (value, space) => {
+        const allKeys = pipe(keysDeep(value))
+            .map(Arr.uniq)
+            .map((ks) => ks.toSorted()).value;
+        return Json.stringifySelected(value, allKeys, space);
+    };
 })(Json || (Json = {}));
-const keysDeepImpl = (obj, mut_keys) => {
-  for (const [k, v] of Object.entries(obj)) {
-    mut_keys.push(k);
-    if (isRecord(v)) {
-      keysDeepImpl(v, mut_keys);
-    }
-    if (Array.isArray(v)) {
-      for (const li of v) {
-        if (isRecord(li)) {
-          keysDeepImpl(li, mut_keys);
+/**
+ * @param obj - The record to extract keys from. Must be a plain object.
+ * @param mut_keys - A mutable array to accumulate the collected keys. This
+ *   array will be modified in-place by the function for performance reasons.
+ * @internal
+ * Recursively collects all property keys from a nested object structure.
+ *
+ * This helper function traverses an object and its nested objects and arrays,
+ * collecting all string keys found at any level of nesting. The function mutates
+ * the provided keys array for performance reasons.
+ */
+const keysDeepImpl = (obj, 
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+mut_keys) => {
+    for (const [k, v] of Object.entries(obj)) {
+        mut_keys.push(k);
+        if (isRecord(v)) {
+            keysDeepImpl(v, mut_keys);
+        }
+        if (Array.isArray(v)) {
+            for (const li of v) {
+                if (isRecord(li)) {
+                    keysDeepImpl(li, mut_keys);
+                }
+            }
         }
-      }
     }
-  }
 };
+/**
+ * @param obj - The record to extract keys from. Must be a plain object.
+ * @returns A readonly array of all string keys found in the object and its
+ *   nested objects/arrays. May contain duplicates if the same key appears at
+ *   multiple levels.
+ * @internal
+ * Extracts all property keys from a nested object structure into a flat array.
+ *
+ * This function serves as a safe wrapper around `keysDeepImpl`, creating a new
+ * mutable array and passing it to the recursive implementation. The result
+ * contains all keys found at any level of nesting within the input object.
+ */
 const keysDeep = (obj) => {
-  const mut_keys = [];
-  keysDeepImpl(obj, mut_keys);
-  return mut_keys;
+    const mut_keys = [];
+    keysDeepImpl(obj, mut_keys);
+    return mut_keys;
 };
-
-export { Json };
-//# sourceMappingURL=json.mjs.map
+//# sourceMappingURL=json.mjs.map

package/dist/json/json.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"json.mjs","sources":["../../src/json/json.mts"],"sourcesContent":["import {\n  type JsonValue,\n  type UintRangeInclusive,\n  type UnknownRecord,\n} from 'ts-type-forge';\nimport { Arr } from '../array/index.mjs';\nimport { pipe, Result } from '../functional/index.mjs';\nimport { isRecord } from '../guard/index.mjs';\nimport { castMutable, unknownToString } from '../others/index.mjs';\n\n/**\n * A collection of type-safe JSON utility functions that provide safe parsing,\n * stringification, and manipulation of JSON data. All functions return `Result`\n * types to handle errors without throwing exceptions.\n */\nexport namespace Json {\n  /**\n   * Safely converts a JSON string into a JavaScript value without throwing\n   * exceptions.\n   *\n   * This function provides type-safe JSON parsing by wrapping the native\n   * `JSON.parse` in a `Result` type, allowing you to handle parsing errors\n   * gracefully without try-catch blocks.\n   *\n   * @example\n   *\n   * ```ts\n   * const validJson = '{\"name\": \"Alice\", \"age\": 30}';\n   *\n   * const invalidJson = '{invalid json}';\n   *\n   * const parsed = Json.parse(validJson);\n   *\n   * const failed = Json.parse(invalidJson);\n   *\n   * assert.isTrue(Result.isOk(parsed));\n   *\n   * if (Result.isOk(parsed)) {\n   *   assert.deepStrictEqual(parsed.value, { name: 'Alice', age: 30 });\n   * }\n   *\n   * assert.isTrue(Result.isErr(failed));\n   *\n   * // With reviver\n   * const jsonWithDate = '{\"created\": \"2024-01-01T00:00:00.000Z\"}';\n   *\n   * const withReviver = Json.parse(jsonWithDate, (key, value) => {\n   *   if (key === 'created' && typeof value === 'string') {\n   *     return new Date(value);\n   *   }\n   *\n   *   return value;\n   * });\n   *\n   * assert.isTrue(Result.isOk(withReviver));\n   * ```\n   *\n   * @param text - A valid JSON string to parse. Can contain any valid JSON data\n   *   type: primitives (string, number, boolean, null), arrays, or objects.\n   * @param reviver - Optional function that transforms parsed values. Called\n   *   for each key-value pair in the JSON. The function receives the key name\n   *   and parsed value, and should return the transformed value. For nested\n   *   objects, inner objects are processed before outer objects.\n   * @returns A `Result<JsonValue, string>` containing:\n   *\n   *   - On success: `Result.ok(parsedValue)` where `parsedValue` is the parsed JSON\n   *   - On failure: `Result.err(errorMessage)` where `errorMessage` describes the\n   *       parsing error\n   */\n  export const parse = (\n    text: string,\n    reviver?: (this: unknown, key: string, value: JsonValue) => unknown,\n  ): Result<JsonValue, string> => {\n    try {\n      return Result.ok(\n        JSON.parse(\n          text,\n          // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n          reviver as (this: unknown, key: string, value: unknown) => unknown,\n        ),\n      );\n    } catch (error: unknown) {\n      const errStr = unknownToString(error);\n\n      return Result.err(errStr);\n    }\n  };\n\n  /**\n   * Safely converts a JavaScript value to a JSON string without throwing\n   * exceptions.\n   *\n   * This function provides type-safe JSON stringification by wrapping the\n   * native `JSON.stringify` in a `Result` type, allowing you to handle\n   * serialization errors gracefully (such as circular references or BigInt\n   * values).\n   *\n   * @example\n   *\n   * ```ts\n   * const data = { name: 'Bob', age: 25, active: true } as const;\n   *\n   * // Basic stringify\n   * const basic = Json.stringify(data);\n   *\n   * assert.isTrue(Result.isOk(basic));\n   *\n   * if (Result.isOk(basic)) {\n   *   assert.isTrue(basic.value === '{\"name\":\"Bob\",\"age\":25,\"active\":true}');\n   * }\n   *\n   * // With formatting\n   * const formatted = Json.stringify(data, undefined, 2);\n   *\n   * assert.isTrue(Result.isOk(formatted));\n   *\n   * // With replacer\n   * const filtered = Json.stringify(data, (key, value) => {\n   *   if (key === 'age') return undefined; // omit age field\n   *\n   *   return value;\n   * });\n   *\n   * assert.isTrue(Result.isOk(filtered));\n   *\n   * if (Result.isOk(filtered)) {\n   *   assert.isTrue(isString(filtered.value));\n   *\n   *   assert.isFalse(filtered.value.includes('age'));\n   * }\n   * ```\n   *\n   * @param value - The JavaScript value to serialize. Can be any value that\n   *   JSON.stringify accepts: primitives, objects, arrays. Non-serializable\n   *   values (functions, undefined, symbols) will be omitted or converted to\n   *   null according to JSON.stringify behavior.\n   * @param replacer - Optional function that transforms values during\n   *   serialization. Called for each key-value pair. Should return the value to\n   *   be serialized, or undefined to omit the property from the result.\n   * @param space - Optional parameter for formatting the output JSON:\n   *\n   *   - Number (1-10): Number of spaces to indent each level\n   *   - String: String to use for indentation (first 10 characters)\n   *   - Undefined/null: No formatting (compact output)\n   *\n   * @returns A `Result<string, string>` containing:\n   *\n   *   - On success: `Result.ok(jsonString)` where `jsonString` is the serialized\n   *       JSON\n   *   - On failure: `Result.err(errorMessage)` where `errorMessage` describes the\n   *       error\n   */\n  export const stringify = (\n    value: unknown,\n    replacer?: (this: unknown, key: string, val: unknown) => unknown,\n    space?: UintRangeInclusive<1, 10> | string,\n  ): Result<string | undefined, string> => {\n    try {\n      return Result.ok(JSON.stringify(value, replacer, space));\n    } catch (error) {\n      const errStr = unknownToString(error);\n\n      return Result.err(errStr);\n    }\n  };\n\n  /**\n   * Safely converts a JavaScript value to a JSON string, including only the\n   * specified properties.\n   *\n   * This function provides selective serialization by allowing you to specify\n   * exactly which object properties should be included in the resulting JSON.\n   * It's useful for creating filtered or minimal representations of objects,\n   * such as for API responses or logging.\n   *\n   * @example\n   *\n   * ```ts\n   * const user = {\n   *   id: 1,\n   *   name: 'Charlie',\n   *   email: 'charlie@example.com',\n   *   password: 'secret123',\n   *   role: 'admin',\n   * } as const;\n   *\n   * // Select only safe properties to serialize\n   * const safeJson = Json.stringifySelected(user, ['id', 'name', 'role']);\n   *\n   * assert.isTrue(Result.isOk(safeJson));\n   *\n   * if (Result.isOk(safeJson)) {\n   *   assert.isTrue(isString(safeJson.value));\n   *\n   *   const parsed: unknown = JSON.parse(safeJson.value);\n   *\n   *   assert.deepStrictEqual(parsed, {\n   *     id: 1,\n   *     name: 'Charlie',\n   *     role: 'admin',\n   *   });\n   *\n   *   assert.isFalse(safeJson.value.includes('password'));\n   *\n   *   assert.isFalse(safeJson.value.includes('email'));\n   * }\n   *\n   * // With formatting\n   * const formatted = Json.stringifySelected(user, ['id', 'name'], 2);\n   *\n   * assert.isTrue(Result.isOk(formatted));\n   * ```\n   *\n   * @param value - The JavaScript value to serialize. While any value is\n   *   accepted, the property filtering only applies to objects and nested\n   *   objects.\n   * @param propertiesToBeSelected - Optional array of property names (strings)\n   *   and array indices (numbers) to include in the serialization. If provided,\n   *   only these properties will appear in the output JSON. If undefined, all\n   *   properties are included.\n   * @param space - Optional formatting parameter:\n   *\n   *   - Number (1-10): Number of spaces to indent each level\n   *   - String: String to use for indentation (first 10 characters)\n   *   - Undefined/null: No formatting (compact output)\n   *\n   * @returns A `Result<string, string>` containing:\n   *\n   *   - On success: `Result.ok(jsonString)` with only selected properties\n   *   - On failure: `Result.err(errorMessage)` describing the serialization error\n   */\n  export const stringifySelected = (\n    value: unknown,\n    propertiesToBeSelected?: readonly (number | string)[],\n    space?: UintRangeInclusive<1, 10> | string,\n  ): Result<string | undefined, string> => {\n    try {\n      return Result.ok(\n        JSON.stringify(value, castMutable(propertiesToBeSelected), space),\n      );\n    } catch (error) {\n      const errStr = unknownToString(error);\n\n      return Result.err(errStr);\n    }\n  };\n\n  /**\n   * Safely converts a JavaScript record to a JSON string with keys sorted\n   * alphabetically at all levels.\n   *\n   * This function creates deterministic JSON output by ensuring that object\n   * keys appear in alphabetical order at every level of nesting. This is\n   * particularly useful for creating consistent output for comparison, hashing,\n   * caching, or when you need reproducible JSON representations across\n   * different JavaScript engines or runs.\n   *\n   * @example\n   *\n   * ```ts\n   * const unorderedData = {\n   *   zebra: 1,\n   *   apple: 2,\n   *   mango: 3,\n   *   nested: {\n   *     zulu: 'z',\n   *     alpha: 'a',\n   *     beta: 'b',\n   *   },\n   * } as const;\n   *\n   * // Keys will be sorted alphabetically at all levels\n   * const sorted = Json.stringifySortedKey(unorderedData);\n   *\n   * assert.isTrue(Result.isOk(sorted));\n   *\n   * if (Result.isOk(sorted)) {\n   *   // Keys should appear in alphabetical order\n   *   const expected =\n   *     '{\"apple\":2,\"mango\":3,\"nested\":{\"alpha\":\"a\",\"beta\":\"b\",\"zulu\":\"z\"},\"zebra\":1}';\n   *\n   *   assert.isTrue(sorted.value === expected);\n   * }\n   *\n   * // With formatting\n   * const formatted = Json.stringifySortedKey(unorderedData, 2);\n   *\n   * assert.isTrue(Result.isOk(formatted));\n   *\n   * if (Result.isOk(formatted)) {\n   *   assert.isTrue(isString(formatted.value));\n   *\n   *   // Check that keys are in order (first key should be \"apple\")\n   *   assert.isTrue(\n   *     formatted.value.indexOf('\"apple\"') < formatted.value.indexOf('\"mango\"'),\n   *   );\n   *\n   *   assert.isTrue(\n   *     formatted.value.indexOf('\"mango\"') <\n   *       formatted.value.indexOf('\"nested\"'),\n   *   );\n   *\n   *   assert.isTrue(\n   *     formatted.value.indexOf('\"nested\"') <\n   *       formatted.value.indexOf('\"zebra\"'),\n   *   );\n   * }\n   * ```\n   *\n   * @param value - An object (`UnknownRecord`) to serialize. Must be a plain\n   *   object (not an array, primitive, or null). Nested objects and arrays\n   *   within the object will also have their keys sorted alphabetically.\n   * @param space - Optional formatting parameter:\n   *\n   *   - Number (1-10): Number of spaces to indent each level\n   *   - String: String to use for indentation (first 10 characters)\n   *   - Undefined/null: No formatting (compact output)\n   *\n   * @returns A `Result<string, string>` containing:\n   *\n   *   - On success: `Result.ok(jsonString)` with all object keys sorted\n   *       alphabetically\n   *   - On failure: `Result.err(errorMessage)` describing the serialization error\n   */\n  export const stringifySortedKey = (\n    value: UnknownRecord,\n    space?: UintRangeInclusive<1, 10> | string,\n  ): Result<string | undefined, string> => {\n    const allKeys = pipe(keysDeep(value))\n      .map(Arr.uniq)\n      .map((ks) => ks.toSorted()).value;\n\n    return stringifySelected(value, allKeys, space);\n  };\n}\n\n/**\n * @param obj - The record to extract keys from. Must be a plain object.\n * @param mut_keys - A mutable array to accumulate the collected keys. This\n *   array will be modified in-place by the function for performance reasons.\n * @internal\n * Recursively collects all property keys from a nested object structure.\n *\n * This helper function traverses an object and its nested objects and arrays,\n * collecting all string keys found at any level of nesting. The function mutates\n * the provided keys array for performance reasons.\n */\nconst keysDeepImpl = (\n  obj: UnknownRecord,\n  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types\n  mut_keys: string[],\n): void => {\n  for (const [k, v] of Object.entries(obj)) {\n    mut_keys.push(k);\n\n    if (isRecord(v)) {\n      keysDeepImpl(v, mut_keys);\n    }\n\n    if (Array.isArray(v)) {\n      for (const li of v) {\n        if (isRecord(li)) {\n          keysDeepImpl(li, mut_keys);\n        }\n      }\n    }\n  }\n};\n\n/**\n * @param obj - The record to extract keys from. Must be a plain object.\n * @returns A readonly array of all string keys found in the object and its\n *   nested objects/arrays. May contain duplicates if the same key appears at\n *   multiple levels.\n * @internal\n * Extracts all property keys from a nested object structure into a flat array.\n *\n * This function serves as a safe wrapper around `keysDeepImpl`, creating a new\n * mutable array and passing it to the recursive implementation. The result\n * contains all keys found at any level of nesting within the input object.\n */\nconst keysDeep = (obj: UnknownRecord): readonly string[] => {\n  const mut_keys: string[] = [];\n\n  keysDeepImpl(obj, mut_keys);\n\n  return mut_keys;\n};\n"],"names":["Json","Result.ok","Result.err","Arr.uniq"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAeO,IAAU;AAAA,CAAV,CAAUA,KAAAA,KAAV;AAsDE,EAAMA,KAAAA,CAAA,KAAA,GAAQ,CACnB,IAAA,EACA,OAAA,KAC8B;AAC9B,IAAA,IAAI;AACF,MAAA,OAAOC,EAAO;AAAA,QACZ,IAAA,CAAK,KAAA;AAAA,UACH,IAAA;AAAA;AAAA,UAEA;AAAA;AACF,OACF;AAAA,IACF,SAAS,KAAA,EAAgB;AACvB,MAAA,MAAM,MAAA,GAAS,gBAAgB,KAAK,CAAA;AAEpC,MAAA,OAAOC,IAAW,MAAM,CAAA;AAAA,IAC1B;AAAA,EACF,CAAA;AAkEO,EAAMF,KAAAA,CAAA,SAAA,GAAY,CACvB,KAAA,EACA,UACA,KAAA,KACuC;AACvC,IAAA,IAAI;AACF,MAAA,OAAOC,EAAO,CAAG,IAAA,CAAK,UAAU,KAAA,EAAO,QAAA,EAAU,KAAK,CAAC,CAAA;AAAA,IACzD,SAAS,KAAA,EAAO;AACd,MAAA,MAAM,MAAA,GAAS,gBAAgB,KAAK,CAAA;AAEpC,MAAA,OAAOC,IAAW,MAAM,CAAA;AAAA,IAC1B;AAAA,EACF,CAAA;AAmEO,EAAMF,KAAAA,CAAA,iBAAA,GAAoB,CAC/B,KAAA,EACA,wBACA,KAAA,KACuC;AACvC,IAAA,IAAI;AACF,MAAA,OAAOC,EAAO;AAAA,QACZ,KAAK,SAAA,CAAU,KAAA,EAAO,WAAA,CAAY,sBAAsB,GAAG,KAAK;AAAA,OAClE;AAAA,IACF,SAAS,KAAA,EAAO;AACd,MAAA,MAAM,MAAA,GAAS,gBAAgB,KAAK,CAAA;AAEpC,MAAA,OAAOC,IAAW,MAAM,CAAA;AAAA,IAC1B;AAAA,EACF,CAAA;AA+EO,EAAMF,KAAAA,CAAA,kBAAA,GAAqB,CAChC,KAAA,EACA,KAAA,KACuC;AACvC,IAAA,MAAM,UAAU,IAAA,CAAK,QAAA,CAAS,KAAK,CAAC,EACjC,GAAA,CAAIG,IAAQ,CAAA,CACZ,IAAI,CAAC,EAAA,KAAO,EAAA,CAAG,QAAA,EAAU,CAAA,CAAE,KAAA;AAE9B,IAAA,OAAA,IAAOH,KAAAA,CAAA,iBAAA,EAAkB,KAAA,EAAO,OAAA,EAAS,KAAK,CAAA;AAAA,EAChD,CAAA;AAAA,CAAA,EA9Te,IAAA,KAAA,IAAA,GAAA,EAAA,CAAA,CAAA;AA4UjB,MAAM,YAAA,GAAe,CACnB,GAAA,EAEA,QAAA,KACS;AACT,EAAA,KAAA,MAAW,CAAC,CAAA,EAAG,CAAC,KAAK,MAAA,CAAO,OAAA,CAAQ,GAAG,CAAA,EAAG;AACxC,IAAA,QAAA,CAAS,KAAK,CAAC,CAAA;AAEf,IAAA,IAAI,QAAA,CAAS,CAAC,CAAA,EAAG;AACf,MAAA,YAAA,CAAa,GAAG,QAAQ,CAAA;AAAA,IAC1B;AAEA,IAAA,IAAI,KAAA,CAAM,OAAA,CAAQ,CAAC,CAAA,EAAG;AACpB,MAAA,KAAA,MAAW,MAAM,CAAA,EAAG;AAClB,QAAA,IAAI,QAAA,CAAS,EAAE,CAAA,EAAG;AAChB,UAAA,YAAA,CAAa,IAAI,QAAQ,CAAA;AAAA,QAC3B;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACF,CAAA;AAcA,MAAM,QAAA,GAAW,CAAC,GAAA,KAA0C;AAC1D,EAAA,MAAM,WAAqB,EAAC;AAE5B,EAAA,YAAA,CAAa,KAAK,QAAQ,CAAA;AAE1B,EAAA,OAAO,QAAA;AACT,CAAA;;;;"}
+{"version":3,"file":"json.mjs","sourceRoot":"","sources":["../../src/json/json.mts"],"names":[],"mappings":"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"}