ts-data-forge 1.0.0

package/src/others/tuple.mts

@@ -0,0 +1,160 @@
+/**
+ * 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
+ *
+ * @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));
+ * ```
+ *
+ * @see https://www.typescriptlang.org/docs/handbook/2/objects.html#tuple-types
+ */
+export const tp = <const T extends readonly unknown[]>(
+  ...args: T
+): Readonly<T> => args;

package/src/others/tuple.test.mts

@@ -0,0 +1,11 @@
+import { expectType } from '../expect-type.mjs';
+import { tp } from './tuple.mjs';
+
+describe('tp', () => {
+  test('test type', () => {
+    const tuple = tp(1, 2, 3);
+    expect(tuple).toStrictEqual([1, 2, 3]);
+
+    expectType<typeof tuple, readonly [1, 2, 3]>('=');
+  });
+});

package/src/others/unknown-to-string.mts

@@ -0,0 +1,215 @@
+import { Result } from '../functional/index.mjs';
+import { isNonNullish } from '../guard/index.mjs';
+
+/**
+ * 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.
+ *
+ * **Type conversion rules:**
+ * - Strings: returned as-is
+ * - Numbers, booleans, bigints: converted via toString()
+ * - Symbols: converted to their description string
+ * - Functions: converted to their string representation
+ * - null: returns "null" (not "null" from JSON)
+ * - undefined: returns "undefined"
+ * - Objects: JSON stringified (with optional pretty printing)
+ *
+ * @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 A Result containing either the string representation or an Error for failures
+ *
+ * @example Basic type conversions
+ * ```typescript
+ * // Primitive types
+ * unknownToString('hello');        // Ok('hello')
+ * unknownToString(123);            // Ok('123')
+ * unknownToString(true);           // Ok('true')
+ * unknownToString(null);           // Ok('null')
+ * unknownToString(undefined);      // Ok('undefined')
+ * unknownToString(Symbol('test')); // Ok('Symbol(test)')
+ * unknownToString(123n);           // Ok('123')
+ *
+ * // Function conversion
+ * const fn = () => 'test';
+ * unknownToString(fn); // Ok('() => 'test'')
+ * ```
+ *
+ * @example Object stringification
+ * ```typescript
+ * // Simple object
+ * const obj = { a: 1, b: 'hello', c: [1, 2, 3] };
+ * const result = unknownToString(obj);
+ * if (Result.isOk(result)) {
+ *   console.log(result.value); // '{"a":1,"b":"hello","c":[1,2,3]}'
+ * }
+ *
+ * // Pretty printing
+ * const prettyResult = unknownToString(obj, { prettyPrintObject: true });
+ * if (Result.isOk(prettyResult)) {
+ *   console.log(prettyResult.value);
+ *   // {
+ *   //   "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);
+ * if (Result.isErr(result)) {
+ *   console.log(result.value.message);
+ *   // "Converting circular structure to JSON"
+ * }
+ *
+ * // Handle with custom serialization
+ * const safeStringify = (value: unknown): string => {
+ *   const result = unknownToString(value);
+ *   return Result.isOk(result)
+ *     ? result.value
+ *     : `[Error: ${result.value.message}]`;
+ * };
+ * ```
+ *
+ * @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 })
+ *       : Result.ok('');
+ *
+ *     if (Result.isOk(dataStr)) {
+ *       console.log(`[${timestamp}] ${message}`, dataStr.value);
+ *     } else {
+ *       console.log(`[${timestamp}] ${message} [Unstringifiable data]`);
+ *     }
+ *   }
+ * }
+ *
+ * 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 result = unknownToString(error, { prettyPrintObject: true });
+ *
+ *   if (Result.isOk(result)) {
+ *     return JSON.stringify({
+ *       success: false,
+ *       error: result.value
+ *     });
+ *   }
+ *
+ *   // Fallback for unstringifiable errors
+ *   return JSON.stringify({
+ *     success: false,
+ *     error: 'An unknown error occurred'
+ *   });
+ * }
+ *
+ * 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'));
+ * // Ok('"2023-01-01T00:00:00.000Z"') - JSON stringified
+ *
+ * // Regular expressions
+ * unknownToString(/test/gi);
+ * // Ok('{}') - RegExp has no enumerable properties
+ *
+ * // Arrays
+ * unknownToString([1, 'two', { three: 3 }]);
+ * // Ok('[1,"two",{"three":3}]')
+ *
+ * // Map and Set (converted to empty objects by JSON.stringify)
+ * unknownToString(new Map([['a', 1]])); // Ok('{}')
+ * unknownToString(new Set([1, 2, 3]));   // Ok('{}')
+ * ```
+ *
+ * @example Integration with Result type
+ * ```typescript
+ * import { Result, pipe } from '../functional';
+ *
+ * // Chain with other Result operations
+ * function processUserInput(input: unknown): Result<string, Error> {
+ *   return pipe(input)
+ *     .map(val => unknownToString(val))
+ *     .map(Result.flatten) // Flatten Result<Result<string, Error>, never>
+ *     .map(str => Result.map(str, s => s.trim()))
+ *     .map(Result.flatten)
+ *     .map(str => Result.flatMap(str, s =>
+ *       s.length > 0
+ *         ? Result.ok(s)
+ *         : Result.err(new Error('Empty string'))
+ *     ))
+ *     .value;
+ * }
+ * ```
+ *
+ * @see Result - For error handling pattern used by this function
+ * @see JSON.stringify - Underlying serialization for objects
+ */
+export const unknownToString = (
+  value: unknown,
+  options?: Partial<Readonly<{ prettyPrintObject: boolean }>>,
+): Result<string, Error> => {
+  switch (typeof value) {
+    case 'string':
+      return Result.ok(value);
+
+    case 'number':
+    case 'bigint':
+    case 'boolean':
+    case 'symbol':
+    case 'function':
+      return Result.ok(value.toString());
+
+    case 'object':
+      if (!isNonNullish(value)) {
+        return Result.ok('null');
+      }
+      try {
+        const stringified =
+          options?.prettyPrintObject === true
+            ? JSON.stringify(value, undefined, 2)
+            : JSON.stringify(value);
+        return Result.ok(stringified);
+      } catch (error) {
+        return Result.err(
+          error instanceof Error
+            ? error
+            : new Error('Failed to stringify object'),
+        );
+      }
+
+    case 'undefined':
+      return Result.ok('undefined');
+  }
+};

package/src/others/unknown-to-string.test.mts

@@ -0,0 +1,114 @@
+import { Result } from '../functional/index.mjs';
+import { unknownToString } from './unknown-to-string.mjs';
+
+describe('unknownToString', () => {
+  test('string', () => {
+    const result = unknownToString('aaaaa');
+    expect(Result.isOk(result)).toBe(true);
+    if (Result.isOk(result)) {
+      expect(result.value).toBe('aaaaa');
+    }
+    expect(JSON.stringify('aaaaa')).toBe('"aaaaa"');
+  });
+
+  test('number', () => {
+    const result = unknownToString(1);
+    expect(Result.isOk(result)).toBe(true);
+    if (Result.isOk(result)) {
+      expect(result.value).toBe('1');
+    }
+    expect(JSON.stringify(1)).toBe('1');
+  });
+
+  test('boolean', () => {
+    const result = unknownToString(true);
+    expect(Result.isOk(result)).toBe(true);
+    if (Result.isOk(result)) {
+      expect(result.value).toBe('true');
+    }
+    expect(JSON.stringify(true)).toBe('true');
+  });
+
+  test('symbol', () => {
+    const result = unknownToString(Symbol('sym'));
+    expect(Result.isOk(result)).toBe(true);
+    if (Result.isOk(result)) {
+      expect(result.value).toBe('Symbol(sym)');
+    }
+    expect(JSON.stringify(Symbol('sym'))).toBeUndefined();
+  });
+
+  test('function', () => {
+    const result = unknownToString(() => 0);
+    expect(Result.isOk(result)).toBe(true);
+    if (Result.isOk(result)) {
+      expect(result.value).toBe('() => 0');
+    }
+    expect(JSON.stringify(() => 0)).toBeUndefined();
+  });
+
+  test('undefined', () => {
+    const result = unknownToString(undefined);
+    expect(Result.isOk(result)).toBe(true);
+    if (Result.isOk(result)) {
+      expect(result.value).toBe('undefined');
+    }
+    expect(JSON.stringify(undefined)).toBeUndefined();
+  });
+
+  test('null', () => {
+    const result = unknownToString(null);
+    expect(Result.isOk(result)).toBe(true);
+    if (Result.isOk(result)) {
+      expect(result.value).toBe('null');
+    }
+    expect(JSON.stringify(null)).toBe('null');
+  });
+
+  test('object', () => {
+    const result = unknownToString({ a: { b: 1 } });
+    expect(Result.isOk(result)).toBe(true);
+    if (Result.isOk(result)) {
+      expect(result.value).toBe('{"a":{"b":1}}');
+    }
+    expect(JSON.stringify({ a: { b: 1 } })).toBe('{"a":{"b":1}}');
+  });
+
+  test('object(prettyPrint=true)', () => {
+    const result = unknownToString(
+      { a: { b: 1 } },
+      { prettyPrintObject: true },
+    );
+    expect(Result.isOk(result)).toBe(true);
+    if (Result.isOk(result)) {
+      expect(result.value).toBe(
+        [
+          //
+          `{`,
+          `  "a": {`,
+          `    "b": 1`,
+          `  }`,
+          `}`,
+        ].join('\n'),
+      );
+    }
+  });
+
+  test('circular reference returns error', () => {
+    const circular: { a: number; self?: unknown } = { a: 1 };
+    circular.self = circular;
+    const result = unknownToString(circular);
+    expect(Result.isErr(result)).toBe(true);
+    if (Result.isErr(result)) {
+      expect(result.value.message).toContain('circular');
+    }
+  });
+
+  test('BigInt value', () => {
+    const result = unknownToString(BigInt(123));
+    expect(Result.isOk(result)).toBe(true);
+    if (Result.isOk(result)) {
+      expect(result.value).toBe('123');
+    }
+  });
+});