ts-data-forge 3.2.0 → 3.3.1

package/dist/json/json.d.mts

@@ -3,170 +3,240 @@ import { Result } from '../functional/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 declare 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
      */
     const parse: (text: string, reviver?: (this: unknown, key: string, value: JsonValue) => unknown) => Result<JsonValue, string>;
     /**
-     * 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'));
      * }
      * ```
-     */
-    const stringify: (value: unknown, replacer?: (this: unknown, key: string, val: unknown) => unknown, space?: UintRangeInclusive<1, 10> | string) => Result<string, string>;
-    /**
-     * 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. 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:
      *
-     * @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)
+     *   - 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
+     *
+     *   - On success: `Result.ok(jsonString)` where `jsonString` is the serialized
+     *       JSON
+     *   - On failure: `Result.err(errorMessage)` where `errorMessage` describes the
+     *       error
+     */
+    const stringify: (value: unknown, replacer?: (this: unknown, key: string, val: unknown) => unknown, space?: UintRangeInclusive<1, 10> | string) => Result<string, string>;
+    /**
+     * 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
-     * ```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'));
      * }
-     * ```
-     */
-    const stringifySelected: (value: unknown, propertiesToBeSelected?: readonly (number | string)[], space?: UintRangeInclusive<1, 10> | string) => Result<string, string>;
-    /**
-     * 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.
+     * // With formatting
+     * const formatted = Json.stringifySelected(user, ['id', 'name'], 2);
+     * assert.ok(Result.isOk(formatted));
+     * ```
      *
-     * @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 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)
+     *   - Undefined/null: No formatting (compact output)
+     *
      * @returns A `Result<string, string>` containing:
-     *   - On success: `Result.ok(jsonString)` with all object keys sorted alphabetically
+     *
+     *   - On success: `Result.ok(jsonString)` with only selected properties
      *   - On failure: `Result.err(errorMessage)` describing the serialization error
+     */
+    const stringifySelected: (value: unknown, propertiesToBeSelected?: readonly (number | string)[], space?: UintRangeInclusive<1, 10> | string) => Result<string, string>;
+    /**
+     * 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
-     * ```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
      */
     const stringifySortedKey: (value: UnknownRecord, space?: UintRangeInclusive<1, 10> | string) => Result<string, string>;
 }

package/dist/json/json.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"json.d.mts","sourceRoot":"","sources":["../../src/json/json.mts"],"names":[],"mappings":"AACA,OAAO,EAAQ,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAIvD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,yBAAiB,IAAI,CAAC;IACpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgCG;IACI,MAAM,KAAK,GAChB,MAAM,MAAM,EACZ,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,KAAK,OAAO,KAClE,MAAM,CAAC,SAAS,EAAE,MAAM,CAa1B,CAAC;IAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;IACI,MAAM,SAAS,GACpB,OAAO,OAAO,EACd,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,KAAK,OAAO,EAChE,QAAQ,kBAAkB,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,MAAM,KACzC,MAAM,CAAC,MAAM,EAAE,MAAM,CAOvB,CAAC;IAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACI,MAAM,iBAAiB,GAC5B,OAAO,OAAO,EACd,yBAAyB,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,EACrD,QAAQ,kBAAkB,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,MAAM,KACzC,MAAM,CAAC,MAAM,EAAE,MAAM,CASvB,CAAC;IAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACI,MAAM,kBAAkB,GAC7B,OAAO,aAAa,EACpB,QAAQ,kBAAkB,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,MAAM,KACzC,MAAM,CAAC,MAAM,EAAE,MAAM,CAMvB,CAAC;CACH"}
+{"version":3,"file":"json.d.mts","sourceRoot":"","sources":["../../src/json/json.mts"],"names":[],"mappings":"AACA,OAAO,EAAQ,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAIvD;;;;GAIG;AACH,yBAAiB,IAAI,CAAC;IACpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+CG;IACI,MAAM,KAAK,GAChB,MAAM,MAAM,EACZ,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,KAAK,OAAO,KAClE,MAAM,CAAC,SAAS,EAAE,MAAM,CAa1B,CAAC;IAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwDG;IACI,MAAM,SAAS,GACpB,OAAO,OAAO,EACd,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,KAAK,OAAO,EAChE,QAAQ,kBAAkB,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,MAAM,KACzC,MAAM,CAAC,MAAM,EAAE,MAAM,CAOvB,CAAC;IAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAyDG;IACI,MAAM,iBAAiB,GAC5B,OAAO,OAAO,EACd,yBAAyB,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,EACrD,QAAQ,kBAAkB,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,MAAM,KACzC,MAAM,CAAC,MAAM,EAAE,MAAM,CASvB,CAAC;IAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkEG;IACI,MAAM,kBAAkB,GAC7B,OAAO,aAAa,EACpB,QAAQ,kBAAkB,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,MAAM,KACzC,MAAM,CAAC,MAAM,EAAE,MAAM,CAMvB,CAAC;CACH"}