ts-data-forge 8.0.0 → 9.0.1

package/dist/json/json.mjs

@@ -47,352 +47,64 @@ import '../collections/iset-mapped.mjs';
 import '../collections/iset.mjs';
 import { uniq } from '../array/impl/array-utils-transformation.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.
- */
 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 ok(JSON.parse(text, 
-            // eslint-disable-next-line total-functions/no-unsafe-type-assertion
-            reviver));
-        }
-        catch (error) {
-            const errStr = unknownToString(error);
-            return 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 ok(JSON.stringify(value, replacer, space));
-        }
-        catch (error) {
-            const errStr = unknownToString(error);
-            return 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 ok(JSON.stringify(value, castMutable(propertiesToBeSelected), space));
-        }
-        catch (error) {
-            const errStr = unknownToString(error);
-            return 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((keys) => uniq(keys))
-            .map((ks) => ks.toSorted()).value;
-        return Json.stringifySelected(value, allKeys, space);
-    };
+((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((keys) => uniq(keys)).map((ks) => ks.toSorted()).value;
+    return (0, Json2.stringifySelected)(value, allKeys, space);
+  };
 })(Json || (Json = {}));
-/**
- * @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);
-                }
-            }
+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.
- * @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 };

package/dist/json/json.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"json.mjs","sources":["../../src/json/json.mts"],"sourcesContent":[null],"names":["Result.ok","Result.err","Arr.uniq"],"mappings":"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"}
+{"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((keys) => Arr.uniq(keys))\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,OAAA,GAAU,KAAK,QAAA,CAAS,KAAK,CAAC,CAAA,CACjC,GAAA,CAAI,CAAC,IAAA,KAASG,KAAS,IAAI,CAAC,EAC5B,GAAA,CAAI,CAAC,OAAO,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;;;;"}

package/dist/number/branded-types/finite-number.d.mts

@@ -25,8 +25,8 @@ export declare const isFiniteNumber: (a: number) => a is TtfImported_FiniteNumbe
  * @throws {TypeError} If the value is NaN, Infinity, or -Infinity
  */
 export declare const asFiniteNumber: <N extends number>(x: N) => number & {
-    readonly NaNValue: false;
     readonly Finite: true;
+    readonly NaNValue: false;
 } & Readonly<{
     'TSTypeForgeInternals--edd2f9ce-7ca5-45b0-9d1a-bd61b9b5d9c3': unknown;
 }> & N;
@@ -150,9 +150,9 @@ export declare const FiniteNumber: {
      * @returns The quotient `a / b` as a FiniteNumber
      */
     readonly div: (x: TtfImported_FiniteNumber, y: number & {
-        readonly NaNValue: false;
-        readonly Finite: true;
         readonly "!=0": true;
+        readonly Finite: true;
+        readonly NaNValue: false;
     } & Readonly<{
         'TSTypeForgeInternals--edd2f9ce-7ca5-45b0-9d1a-bd61b9b5d9c3': unknown;
     }>) => TtfImported_FiniteNumber;