ts-data-forge 3.3.0 → 4.0.0

package/dist/others/tuple.d.mts

@@ -1,158 +1,40 @@
 /**
- * Creates a readonly tuple from the given arguments with precise literal type inference.
- *
- * This utility function provides a concise way to create tuples while preserving
- * exact literal types. Without this function, TypeScript would infer arrays with
- * widened types instead of tuples with literal types.
- *
- * **Key benefits:**
- * - Preserves literal types (e.g., `1` instead of `number`)
- * - Creates readonly tuples for immutability
- * - Provides better type inference than array literals
- * - Zero runtime overhead - just returns the arguments
+ * Creates a readonly tuple from the given arguments with precise literal type
+ * inference. It is a convenient shorthand for `[...args] as const`.
+ *
+ * @example
+ *
+ * ```ts
+ * // Create a tuple with literal types preserved
+ * const coordinates = tp(10, 20, 30);
+ * expectType<typeof coordinates, readonly [10, 20, 30]>('=');
+ * expectType<typeof coordinates, readonly number[]>('!=');
+ * assert.deepStrictEqual(coordinates, [10, 20, 30]);
+ *
+ * // The following two are equivalent
+ * const a = tp(1, 2);
+ * const b = [1, 2] as const;
+ * expectType<typeof a, typeof b>('=');
+ * assert.deepStrictEqual(a, b);
+ *
+ * // Without tp, type would be number[]
+ * const point = tp('x', 42, true);
+ * expectType<typeof point, readonly ['x', 42, true]>('=');
+ * assert.deepStrictEqual(point, ['x', 42, true]);
+ *
+ * // Useful for creating const tuples
+ * const rgb = tp(255, 128, 0);
+ * expectType<typeof rgb, readonly [255, 128, 0]>('=');
+ *
+ * assert(rgb[0] === 255);
+ * assert(rgb[1] === 128);
+ * assert(rgb[2] === 0);
+ * ```
  *
  * @template T - A tuple type with literal types inferred from the arguments
  * @param args - The elements to include in the tuple (variadic)
- * @returns A readonly tuple containing the provided arguments with preserved literal types
- *
- * @example Basic tuple creation with literal types
- * ```typescript
- * // Without tp: types are widened
- * const arr = [1, 'hello', true]; // (string | number | boolean)[]
- *
- * // With tp: exact literal types preserved
- * const tuple = tp(1, 'hello', true); // readonly [1, 'hello', true]
- * const coords = tp(10, 20); // readonly [10, 20]
- * const single = tp('only'); // readonly ['only']
- * const empty = tp(); // readonly []
- *
- * // TypeScript knows exact values at compile time
- * type First = typeof tuple[0]; // 1 (literal type)
- * type Second = typeof tuple[1]; // 'hello' (literal type)
- * ```
- *
- * @example Creating type-safe coordinate systems
- * ```typescript
- * // 2D coordinates
- * const point2D = tp(10, 20);
- * const [x, y] = point2D; // x: 10, y: 20
- *
- * // 3D coordinates
- * const point3D = tp(10, 20, 30);
- * const [x3, y3, z3] = point3D; // Exact types preserved
- *
- * // Named coordinate system
- * const namedPoint = tp('x', 100, 'y', 200);
- * // Type: readonly ['x', 100, 'y', 200]
- * ```
- *
- * @example Building type-safe data structures
- * ```typescript
- * // Creating a type-safe map structure
- * const colorMap = [
- *   tp('red', '#FF0000'),
- *   tp('green', '#00FF00'),
- *   tp('blue', '#0000FF')
- * ] as const;
- * // Type: readonly [readonly ['red', '#FF0000'], ...]
- *
- * // Type-safe event system
- * type EventTuple = readonly ['click', MouseEvent] | readonly ['change', Event];
- * const event = tp('click', new MouseEvent('click')) as EventTuple;
- * ```
- *
- * @example Function argument patterns
- * ```typescript
- * // Functions expecting exact tuple types
- * function processCoordinate(coord: readonly [number, number]): void {
- *   const [x, y] = coord;
- *   console.log(`Processing point at (${x}, ${y})`);
- * }
- *
- * processCoordinate(tp(10, 20)); // ✅ Type-safe
- * processCoordinate([10, 20]); // ❌ Error: number[] not assignable
- *
- * // Pattern matching with tuples
- * function handleMessage(msg: readonly ['error', string] | readonly ['success', any]) {
- *   if (msg[0] === 'error') {
- *     console.error(msg[1]); // TypeScript knows msg[1] is string
- *   } else {
- *     console.log('Success:', msg[1]);
- *   }
- * }
- *
- * handleMessage(tp('error', 'Failed to load'));
- * handleMessage(tp('success', { id: 123 }));
- * ```
- *
- * @example Advanced type inference
- * ```typescript
- * // Const assertions comparison
- * const tuple1 = [1, 2, 3]; // number[]
- * const tuple2 = [1, 2, 3] as const; // readonly [1, 2, 3]
- * const tuple3 = tp(1, 2, 3); // readonly [1, 2, 3]
- *
- * // Building complex types
- * const config = tp(
- *   tp('host', 'localhost'),
- *   tp('port', 3000),
- *   tp('secure', true)
- * );
- * // Type: readonly [
- * //   readonly ['host', 'localhost'],
- * //   readonly ['port', 3000],
- * //   readonly ['secure', true]
- * // ]
- *
- * // Type-safe destructuring
- * const [[, host], [, port], [, secure]] = config;
- * // host: 'localhost', port: 3000, secure: true
- * ```
- *
- * @example Integration with other utilities
- * ```typescript
- * import { pipe } from '../functional/pipe';
- * import { Result } from '../functional/result';
- *
- * // Type-safe error handling
- * function divide(a: number, b: number): Result<number, string> {
- *   if (b === 0) return Result.err('Division by zero');
- *   return Result.ok(a / b);
- * }
- *
- * const calculation = tp(10, 2);
- * const result = divide(...calculation); // Spread tuple as arguments
- *
- * // Building pipelines with tuples
- * const pipeline = pipe(tp(5, 10))
- *   .map(([a, b]) => tp(a + b, a * b))
- *   .map(([sum, product]) => tp('sum', sum, 'product', product))
- *   .value;
- * // Type: readonly ['sum', 15, 'product', 50]
- * ```
- *
- * @example Common patterns and use cases
- * ```typescript
- * // React-style state tuples
- * const useState = <T>(initial: T) => tp(initial, (value: T) => void 0);
- * const [count, setCount] = useState(0);
- *
- * // Redux-style actions
- * const incrementAction = tp('INCREMENT', { amount: 1 });
- * const decrementAction = tp('DECREMENT', { amount: 1 });
- *
- * // Database query results
- * const queryResult = tp(
- *   true, // success
- *   [{ id: 1, name: 'John' }], // data
- *   null // error
- * );
- *
- * // Configuration flags
- * const features = tp('darkMode', 'analytics', 'notifications');
- * const enabledFeatures = features.filter(f => isEnabled(f));
- * ```
- *
+ * @returns A readonly tuple containing the provided arguments with preserved
+ *   literal types
  * @see https://www.typescriptlang.org/docs/handbook/2/objects.html#tuple-types
  */
 export declare const tp: <const T extends readonly unknown[]>(...args: T) => Readonly<T>;

package/dist/others/tuple.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"tuple.d.mts","sourceRoot":"","sources":["../../src/others/tuple.mts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4JG;AACH,eAAO,MAAM,EAAE,GAAI,KAAK,CAAC,CAAC,SAAS,SAAS,OAAO,EAAE,EACnD,GAAG,MAAM,CAAC,KACT,QAAQ,CAAC,CAAC,CAAS,CAAC"}
+{"version":3,"file":"tuple.d.mts","sourceRoot":"","sources":["../../src/others/tuple.mts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,eAAO,MAAM,EAAE,GAAI,KAAK,CAAC,CAAC,SAAS,SAAS,OAAO,EAAE,EACnD,GAAG,MAAM,CAAC,KACT,QAAQ,CAAC,CAAC,CAAS,CAAC"}

package/dist/others/tuple.mjs

@@ -1,158 +1,40 @@
 /**
- * Creates a readonly tuple from the given arguments with precise literal type inference.
- *
- * This utility function provides a concise way to create tuples while preserving
- * exact literal types. Without this function, TypeScript would infer arrays with
- * widened types instead of tuples with literal types.
- *
- * **Key benefits:**
- * - Preserves literal types (e.g., `1` instead of `number`)
- * - Creates readonly tuples for immutability
- * - Provides better type inference than array literals
- * - Zero runtime overhead - just returns the arguments
+ * Creates a readonly tuple from the given arguments with precise literal type
+ * inference. It is a convenient shorthand for `[...args] as const`.
+ *
+ * @example
+ *
+ * ```ts
+ * // Create a tuple with literal types preserved
+ * const coordinates = tp(10, 20, 30);
+ * expectType<typeof coordinates, readonly [10, 20, 30]>('=');
+ * expectType<typeof coordinates, readonly number[]>('!=');
+ * assert.deepStrictEqual(coordinates, [10, 20, 30]);
+ *
+ * // The following two are equivalent
+ * const a = tp(1, 2);
+ * const b = [1, 2] as const;
+ * expectType<typeof a, typeof b>('=');
+ * assert.deepStrictEqual(a, b);
+ *
+ * // Without tp, type would be number[]
+ * const point = tp('x', 42, true);
+ * expectType<typeof point, readonly ['x', 42, true]>('=');
+ * assert.deepStrictEqual(point, ['x', 42, true]);
+ *
+ * // Useful for creating const tuples
+ * const rgb = tp(255, 128, 0);
+ * expectType<typeof rgb, readonly [255, 128, 0]>('=');
+ *
+ * assert(rgb[0] === 255);
+ * assert(rgb[1] === 128);
+ * assert(rgb[2] === 0);
+ * ```
  *
  * @template T - A tuple type with literal types inferred from the arguments
  * @param args - The elements to include in the tuple (variadic)
- * @returns A readonly tuple containing the provided arguments with preserved literal types
- *
- * @example Basic tuple creation with literal types
- * ```typescript
- * // Without tp: types are widened
- * const arr = [1, 'hello', true]; // (string | number | boolean)[]
- *
- * // With tp: exact literal types preserved
- * const tuple = tp(1, 'hello', true); // readonly [1, 'hello', true]
- * const coords = tp(10, 20); // readonly [10, 20]
- * const single = tp('only'); // readonly ['only']
- * const empty = tp(); // readonly []
- *
- * // TypeScript knows exact values at compile time
- * type First = typeof tuple[0]; // 1 (literal type)
- * type Second = typeof tuple[1]; // 'hello' (literal type)
- * ```
- *
- * @example Creating type-safe coordinate systems
- * ```typescript
- * // 2D coordinates
- * const point2D = tp(10, 20);
- * const [x, y] = point2D; // x: 10, y: 20
- *
- * // 3D coordinates
- * const point3D = tp(10, 20, 30);
- * const [x3, y3, z3] = point3D; // Exact types preserved
- *
- * // Named coordinate system
- * const namedPoint = tp('x', 100, 'y', 200);
- * // Type: readonly ['x', 100, 'y', 200]
- * ```
- *
- * @example Building type-safe data structures
- * ```typescript
- * // Creating a type-safe map structure
- * const colorMap = [
- *   tp('red', '#FF0000'),
- *   tp('green', '#00FF00'),
- *   tp('blue', '#0000FF')
- * ] as const;
- * // Type: readonly [readonly ['red', '#FF0000'], ...]
- *
- * // Type-safe event system
- * type EventTuple = readonly ['click', MouseEvent] | readonly ['change', Event];
- * const event = tp('click', new MouseEvent('click')) as EventTuple;
- * ```
- *
- * @example Function argument patterns
- * ```typescript
- * // Functions expecting exact tuple types
- * function processCoordinate(coord: readonly [number, number]): void {
- *   const [x, y] = coord;
- *   console.log(`Processing point at (${x}, ${y})`);
- * }
- *
- * processCoordinate(tp(10, 20)); // ✅ Type-safe
- * processCoordinate([10, 20]); // ❌ Error: number[] not assignable
- *
- * // Pattern matching with tuples
- * function handleMessage(msg: readonly ['error', string] | readonly ['success', any]) {
- *   if (msg[0] === 'error') {
- *     console.error(msg[1]); // TypeScript knows msg[1] is string
- *   } else {
- *     console.log('Success:', msg[1]);
- *   }
- * }
- *
- * handleMessage(tp('error', 'Failed to load'));
- * handleMessage(tp('success', { id: 123 }));
- * ```
- *
- * @example Advanced type inference
- * ```typescript
- * // Const assertions comparison
- * const tuple1 = [1, 2, 3]; // number[]
- * const tuple2 = [1, 2, 3] as const; // readonly [1, 2, 3]
- * const tuple3 = tp(1, 2, 3); // readonly [1, 2, 3]
- *
- * // Building complex types
- * const config = tp(
- *   tp('host', 'localhost'),
- *   tp('port', 3000),
- *   tp('secure', true)
- * );
- * // Type: readonly [
- * //   readonly ['host', 'localhost'],
- * //   readonly ['port', 3000],
- * //   readonly ['secure', true]
- * // ]
- *
- * // Type-safe destructuring
- * const [[, host], [, port], [, secure]] = config;
- * // host: 'localhost', port: 3000, secure: true
- * ```
- *
- * @example Integration with other utilities
- * ```typescript
- * import { pipe } from '../functional/pipe';
- * import { Result } from '../functional/result';
- *
- * // Type-safe error handling
- * function divide(a: number, b: number): Result<number, string> {
- *   if (b === 0) return Result.err('Division by zero');
- *   return Result.ok(a / b);
- * }
- *
- * const calculation = tp(10, 2);
- * const result = divide(...calculation); // Spread tuple as arguments
- *
- * // Building pipelines with tuples
- * const pipeline = pipe(tp(5, 10))
- *   .map(([a, b]) => tp(a + b, a * b))
- *   .map(([sum, product]) => tp('sum', sum, 'product', product))
- *   .value;
- * // Type: readonly ['sum', 15, 'product', 50]
- * ```
- *
- * @example Common patterns and use cases
- * ```typescript
- * // React-style state tuples
- * const useState = <T>(initial: T) => tp(initial, (value: T) => void 0);
- * const [count, setCount] = useState(0);
- *
- * // Redux-style actions
- * const incrementAction = tp('INCREMENT', { amount: 1 });
- * const decrementAction = tp('DECREMENT', { amount: 1 });
- *
- * // Database query results
- * const queryResult = tp(
- *   true, // success
- *   [{ id: 1, name: 'John' }], // data
- *   null // error
- * );
- *
- * // Configuration flags
- * const features = tp('darkMode', 'analytics', 'notifications');
- * const enabledFeatures = features.filter(f => isEnabled(f));
- * ```
- *
+ * @returns A readonly tuple containing the provided arguments with preserved
+ *   literal types
  * @see https://www.typescriptlang.org/docs/handbook/2/objects.html#tuple-types
  */
 const tp = (...args) => args;

package/dist/others/tuple.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"tuple.mjs","sources":["../../src/others/tuple.mts"],"sourcesContent":[null],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4JG;AACI,MAAM,EAAE,GAAG,CAChB,GAAG,IAAO,KACM;;;;"}
+{"version":3,"file":"tuple.mjs","sources":["../../src/others/tuple.mts"],"sourcesContent":[null],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsCG;AACI,MAAM,EAAE,GAAG,CAChB,GAAG,IAAO,KACM;;;;"}

package/dist/others/unknown-to-string.d.mts

@@ -1,11 +1,13 @@
 /**
  * Converts an unknown value to its string representation in a type-safe manner.
  *
- * This function handles all JavaScript types and provides consistent string conversion
- * with proper error handling for edge cases like circular references. Unlike naive
- * toString() calls, this function never throws and handles all value types gracefully.
+ * This function handles all JavaScript types and provides consistent string
+ * conversion with proper error handling for edge cases like circular
+ * references. Unlike naive toString() calls, this function never throws and
+ * handles all value types gracefully.
  *
  * **Type conversion rules:**
+ *
  * - Strings: returned as-is
  * - Numbers, booleans, bigints: converted via toString()
  * - Symbols: converted to their description string
@@ -16,129 +18,13 @@
  *
  * @param value - The unknown value to convert to string
  * @param options - Optional configuration for the conversion
- * @param options.prettyPrintObject - If true, objects are formatted with 2-space indentation
- * @returns The string representation of the value. For circular references or non-serializable objects, returns an error message string
- *
- * @example Basic type conversions
- * ```typescript
- * // Primitive types
- * unknownToString('hello');        // 'hello'
- * unknownToString(123);            // '123'
- * unknownToString(true);           // 'true'
- * unknownToString(null);           // 'null'
- * unknownToString(undefined);      // 'undefined'
- * unknownToString(Symbol('test')); // 'Symbol(test)'
- * unknownToString(123n);           // '123'
- *
- * // Function conversion
- * const fn = () => 'test';
- * unknownToString(fn); // "() => 'test'"
- * ```
- *
- * @example Object stringification
- * ```typescript
- * // Simple object
- * const obj = { a: 1, b: 'hello', c: [1, 2, 3] };
- * const result = unknownToString(obj);
- * console.log(result); // '{"a":1,"b":"hello","c":[1,2,3]}'
- *
- * // Pretty printing
- * const prettyResult = unknownToString(obj, { prettyPrintObject: true });
- * console.log(prettyResult);
- * // {
- * //   "a": 1,
- * //   "b": "hello",
- * //   "c": [
- * //     1,
- * //     2,
- * //     3
- * //   ]
- * // }
- * ```
- *
- * @example Error handling for circular references
- * ```typescript
- * // Circular reference
- * const circular: any = { name: 'parent' };
- * circular.self = circular;
- *
- * const result = unknownToString(circular);
- * console.log(result); // "Converting circular structure to JSON"
- *
- * @example Logging and debugging utilities
- * ```typescript
- * // Type-safe logger
- * class Logger {
- *   log(message: string, data?: unknown): void {
- *     const timestamp = new Date().toISOString();
- *     const dataStr = data !== undefined
- *       ? unknownToString(data, { prettyPrintObject: true })
- *       : '';
- *
- *     console.log(`[${timestamp}] ${message}`, dataStr);
- *   }
- * }
- *
- * const logger = new Logger();
- * logger.log('User data:', { id: 123, name: 'John' });
- * ```
- *
- * @example API response formatting
- * ```typescript
- * // Safe error response formatting
- * function formatErrorResponse(error: unknown): string {
- *   const errorStr = unknownToString(error, { prettyPrintObject: true });
- *
- *   return JSON.stringify({
- *     success: false,
- *     error: errorStr
- *   });
- * }
- *
- * try {
- *   // some operation
- * } catch (error) {
- *   const response = formatErrorResponse(error);
- *   res.status(500).send(response);
- * }
- * ```
- *
- * @example Working with special objects
- * ```typescript
- * // Date objects
- * unknownToString(new Date('2023-01-01'));
- * // '"2023-01-01T00:00:00.000Z"' - JSON stringified
- *
- * // Regular expressions
- * unknownToString(/test/gi);
- * // '{}' - RegExp has no enumerable properties
- *
- * // Arrays
- * unknownToString([1, 'two', { three: 3 }]);
- * // '[1,"two",{"three":3}]'
- *
- * // Map and Set (converted to empty objects by JSON.stringify)
- * unknownToString(new Map([['a', 1]])); // '{}'
- * unknownToString(new Set([1, 2, 3]));   // '{}'
- * ```
- *
- * @example Using with validation
- * ```typescript
- * // Simple validation helper
- * function validateAndStringify(input: unknown): string {
- *   const str = unknownToString(input);
- *   const trimmed = str.trim();
- *
- *   if (trimmed.length === 0) {
- *     throw new Error('Empty string');
- *   }
- *
- *   return trimmed;
- * }
- * ```
+ * @param options.prettyPrintObject - If true, objects are formatted with
+ *   2-space indentation
+ * @returns The string representation of the value. For circular references or
+ *   non-serializable objects, returns an error message string
  *
- * **Error Handling:**
- * Circular references and non-serializable objects return descriptive error messages instead of throwing
+ *   **Error Handling:** Circular references and non-serializable objects return
+ *   descriptive error messages instead of throwing
  * @see JSON.stringify - Underlying serialization for objects
  */
 export declare const unknownToString: (value: unknown, options?: Partial<Readonly<{

package/dist/others/unknown-to-string.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"unknown-to-string.d.mts","sourceRoot":"","sources":["../../src/others/unknown-to-string.mts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8IG;AACH,eAAO,MAAM,eAAe,GAC1B,OAAO,OAAO,EACd,UAAU,OAAO,CAAC,QAAQ,CAAC;IAAE,iBAAiB,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC,KAC1D,MAiCF,CAAC"}
+{"version":3,"file":"unknown-to-string.d.mts","sourceRoot":"","sources":["../../src/others/unknown-to-string.mts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,eAAe,GAC1B,OAAO,OAAO,EACd,UAAU,OAAO,CAAC,QAAQ,CAAC;IAAE,iBAAiB,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC,KAC1D,MAiCF,CAAC"}