ts-data-forge 3.3.0 → 4.0.0

package/src/json/json.mts

@@ -7,57 +7,55 @@ import { castMutable, 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.
- *
- * @example Basic usage
- * ```typescript
- * import { Json, Result } from 'ts-data-forge';
- *
- * // Parse JSON safely
- * const parseResult = Json.parse('{"name": "Alice", "age": 30}');
- * if (Result.isOk(parseResult)) {
- *   console.log(parseResult.value); // { name: 'Alice', age: 30 }
- * }
- *
- * // Stringify with error handling
- * const stringifyResult = Json.stringify({ name: 'Bob', age: 25 });
- * if (Result.isOk(stringifyResult)) {
- *   console.log(stringifyResult.value); // '{"name":"Bob","age":25}'
- * }
- * ```
  */
 export namespace 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.
-   *
-   * @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
+   * Safely converts a JSON string into a JavaScript value without throwing
+   * exceptions.
    *
-   * @example
-   * ```typescript
-   * const result = Json.parse('{"name": "John", "age": 30}');
-   * if (Result.isOk(result)) {
-   *   console.log(result.value.name); // 'John'
-   * }
-   * ```
+   * 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
-   * ```typescript
-   * const invalid = Json.parse('invalid json');
-   * if (Result.isErr(invalid)) {
-   *   console.log('Parse failed:', invalid.value);
+   *
+   * ```ts
+   * const validJson = '{"name": "Alice", "age": 30}';
+   * const invalidJson = '{invalid json}';
+   *
+   * const parsed = Json.parse(validJson);
+   * const failed = Json.parse(invalidJson);
+   *
+   * assert.ok(Result.isOk(parsed));
+   * if (Result.isOk(parsed)) {
+   *   assert.deepStrictEqual(parsed.value, { name: 'Alice', age: 30 });
    * }
+   *
+   * assert.ok(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.ok(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
    */
   export const parse = (
     text: string,
@@ -67,7 +65,7 @@ export namespace Json {
       return Result.ok(
         JSON.parse(
           text,
-          // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+          // eslint-disable-next-line total-functions/no-unsafe-type-assertion
           reviver as (this: unknown, key: string, value: unknown) => unknown,
         ),
       );
@@ -78,44 +76,61 @@ export namespace Json {
   };
 
   /**
-   * 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).
-   *
-   * @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
+   * 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
-   * ```typescript
-   * const obj = { name: 'John', age: 30 };
-   * const result = Json.stringify(obj);
-   * if (Result.isOk(result)) {
-   *   console.log(result.value); // '{"name":"John","age":30}'
+   *
+   * ```ts
+   * const data = { name: 'Bob', age: 25, active: true };
+   *
+   * // Basic stringify
+   * const basic = Json.stringify(data);
+   * assert.ok(Result.isOk(basic));
+   * if (Result.isOk(basic)) {
+   *   assert(basic.value === '{"name":"Bob","age":25,"active":true}');
    * }
-   * ```
    *
-   * @example Error handling
-   * ```typescript
-   * const circular: any = { name: 'test' };
-   * circular.self = circular;
-   * const error = Json.stringify(circular);
-   * if (Result.isErr(error)) {
-   *   console.log('Stringify failed:', error.value);
+   * // With formatting
+   * const formatted = Json.stringify(data, undefined, 2);
+   * assert.ok(Result.isOk(formatted));
+   *
+   * // With replacer
+   * const filtered = Json.stringify(data, (key, value) => {
+   *   if (key === 'age') return undefined; // omit age field
+   *   return value;
+   * });
+   *
+   * assert.ok(Result.isOk(filtered));
+   * if (Result.isOk(filtered)) {
+   *   assert.ok(!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
    */
   export const stringify = (
     value: unknown,
@@ -131,40 +146,62 @@ export namespace Json {
   };
 
   /**
-   * Safely converts a JavaScript value to a JSON string, including only the specified properties.
+   * 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.
-   *
-   * @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
+   * 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
-   * ```typescript
+   *
+   * ```ts
    * const user = {
    *   id: 1,
-   *   name: 'Alice',
-   *   email: 'alice@example.com',
-   *   password: 'secret123'
+   *   name: 'Charlie',
+   *   email: 'charlie@example.com',
+   *   password: 'secret123',
+   *   role: 'admin',
    * };
    *
-   * const publicFields = Json.stringifySelected(user, ['id', 'name', 'email']);
-   * if (Result.isOk(publicFields)) {
-   *   console.log(publicFields.value);
-   *   // '{"id":1,"name":"Alice","email":"alice@example.com"}'
+   * // Select only safe properties to serialize
+   * const safeJson = Json.stringifySelected(user, ['id', 'name', 'role']);
+   *
+   * assert.ok(Result.isOk(safeJson));
+   * if (Result.isOk(safeJson)) {
+   *   const parsed: unknown = JSON.parse(safeJson.value);
+   *   assert.deepStrictEqual(parsed, {
+   *     id: 1,
+   *     name: 'Charlie',
+   *     role: 'admin',
+   *   });
+   *   assert.ok(!safeJson.value.includes('password'));
+   *   assert.ok(!safeJson.value.includes('email'));
    * }
+   *
+   * // With formatting
+   * const formatted = Json.stringifySelected(user, ['id', 'name'], 2);
+   * assert.ok(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
    */
   export const stringifySelected = (
     value: unknown,
@@ -182,38 +219,71 @@ export namespace Json {
   };
 
   /**
-   * Safely converts a JavaScript record to a JSON string with keys sorted alphabetically at all levels.
+   * 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.
-   *
-   * @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
+   * 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
-   * ```typescript
-   * const unsortedObj = {
-   *   zebra: 'animal',
-   *   apple: 'fruit',
-   *   banana: 'fruit'
+   *
+   * ```ts
+   * const unorderedData = {
+   *   zebra: 1,
+   *   apple: 2,
+   *   mango: 3,
+   *   nested: {
+   *     zulu: 'z',
+   *     alpha: 'a',
+   *     beta: 'b',
+   *   },
    * };
    *
-   * const sorted = Json.stringifySortedKey(unsortedObj);
+   * // Keys will be sorted alphabetically at all levels
+   * const sorted = Json.stringifySortedKey(unorderedData);
+   *
+   * assert.ok(Result.isOk(sorted));
    * if (Result.isOk(sorted)) {
-   *   console.log(sorted.value);
-   *   // '{"apple":"fruit","banana":"fruit","zebra":"animal"}'
+   *   // Keys should appear in alphabetical order
+   *   const expected =
+   *     '{"apple":2,"mango":3,"nested":{"alpha":"a","beta":"b","zulu":"z"},"zebra":1}';
+   *   assert(sorted.value === expected);
+   * }
+   *
+   * // With formatting
+   * const formatted = Json.stringifySortedKey(unorderedData, 2);
+   * assert.ok(Result.isOk(formatted));
+   * if (Result.isOk(formatted)) {
+   *   // Check that keys are in order (first key should be "apple")
+   *   assert.ok(
+   *     formatted.value.indexOf('"apple"') < formatted.value.indexOf('"mango"'),
+   *   );
+   *   assert.ok(
+   *     formatted.value.indexOf('"mango"') < formatted.value.indexOf('"nested"'),
+   *   );
+   *   assert.ok(
+   *     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
    */
   export const stringifySortedKey = (
     value: UnknownRecord,
@@ -228,16 +298,15 @@ export namespace 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.
- *
- * @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.
  */
 const keysDeepImpl = (
   obj: UnknownRecord,
@@ -261,17 +330,16 @@ const keysDeepImpl = (
 };
 
 /**
+ * @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.
- *
- * @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.
  */
 const keysDeep = (obj: UnknownRecord): readonly string[] => {
   const mut_keys: string[] = [];

package/src/json/json.test.mts

@@ -216,11 +216,10 @@ describe('stringify', () => {
     expect(Json.stringify(Symbol('test'))).toStrictEqual(Result.ok(undefined));
     expect(Json.stringify(() => {})).toStrictEqual(Result.ok(undefined));
     // BigInt should cause an error
-    expect(Result.isErr(Json.stringify(BigInt(123)))).toBe(true);
+    expect(Result.isErr(Json.stringify(123n))).toBe(true);
   });
 
   test('should handle circular references', () => {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const mut_obj: any = { a: 1 };
     // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-member-access
     mut_obj.circular = mut_obj;
@@ -242,7 +241,6 @@ describe('stringify', () => {
   });
 
   test('should not throw errors', () => {
-    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     const mut_circularArray: any[] = [];
     mut_circularArray.push(mut_circularArray);