ts-data-forge 1.0.0 → 1.0.2

package/dist/others/memoize-function.d.mts

@@ -0,0 +1,173 @@
+/**
+ * Creates a memoized version of a function that caches results based on input arguments.
+ *
+ * The memoized function stores results in an internal Map and returns cached values
+ * for repeated calls with the same arguments. This can significantly improve performance
+ * for expensive computations or I/O operations.
+ *
+ * **Important considerations:**
+ * - The cache grows unbounded - consider memory implications for long-running applications
+ * - Cache keys must be primitives (string, number, boolean, symbol, null, undefined, bigint)
+ * - Object arguments require careful key generation to ensure uniqueness
+ * - Pure functions only - memoizing functions with side effects can lead to bugs
+ *
+ * @template A - The tuple type of the function arguments
+ * @template R - The return type of the function
+ * @template K - The primitive type used as the cache key (must be valid Map key)
+ * @param fn - The pure function to memoize
+ * @param argsToCacheKey - Function that converts arguments to a unique cache key
+ * @returns A memoized version of the input function with the same signature
+ *
+ * @example Basic memoization for expensive calculations
+ * ```typescript
+ * // Fibonacci calculation (exponential time complexity)
+ * const fibonacci = (n: number): number => {
+ *   console.log(`Computing fib(${n})`);
+ *   if (n <= 1) return n;
+ *   return fibonacci(n - 1) + fibonacci(n - 2);
+ * };
+ *
+ * const memoizedFib = memoizeFunction(
+ *   fibonacci,
+ *   (n) => n // Number itself as key
+ * );
+ *
+ * memoizedFib(40); // Much faster than unmemoized version
+ * memoizedFib(40); // Returns instantly from cache
+ * ```
+ *
+ * @example Multi-argument functions with composite keys
+ * ```typescript
+ * // Grid calculation with x,y coordinates
+ * const calculateGridValue = (x: number, y: number, scale: number): number => {
+ *   console.log(`Computing grid(${x},${y},${scale})`);
+ *   // Expensive computation...
+ *   return Math.sin(x * scale) * Math.cos(y * scale);
+ * };
+ *
+ * const memoizedGrid = memoizeFunction(
+ *   calculateGridValue,
+ *   (x, y, scale) => `${x},${y},${scale}` // String concatenation for composite key
+ * );
+ *
+ * // Alternative: Using bit manipulation for integer coordinates
+ * const memoizedGrid2 = memoizeFunction(
+ *   calculateGridValue,
+ *   (x, y, scale) => (x << 20) | (y << 10) | scale // Assuming small positive integers
+ * );
+ * ```
+ *
+ * @example Object arguments with selective memoization
+ * ```typescript
+ * interface User {
+ *   id: number;
+ *   name: string;
+ *   email: string;
+ *   metadata?: Record<string, unknown>;
+ * }
+ *
+ * const fetchUserPermissions = async (user: User): Promise<string[]> => {
+ *   console.log(`Fetching permissions for user ${user.id}`);
+ *   const response = await api.get(`/permissions/${user.id}`);
+ *   return response.data;
+ * };
+ *
+ * // Memoize based only on user ID, ignoring other fields
+ * const memoizedFetchPermissions = memoizeFunction(
+ *   fetchUserPermissions,
+ *   (user) => user.id // Only cache by ID
+ * );
+ *
+ * // For multiple identifying fields
+ * const processUserData = (user: User, orgId: number): ProcessedData => {
+ *   // Complex processing...
+ * };
+ *
+ * const memoizedProcess = memoizeFunction(
+ *   processUserData,
+ *   (user, orgId) => `${user.id}:${orgId}` // Composite key with separator
+ * );
+ * ```
+ *
+ * @example Memoizing recursive functions
+ * ```typescript
+ * // Recursive path finding
+ * const findPaths = (start: string, end: string, visited: Set<string> = new Set()): string[][] => {
+ *   if (start === end) return [[end]];
+ *   // ... complex recursive logic
+ * };
+ *
+ * // Use sorted, serialized visited set for consistent keys
+ * const memoizedFindPaths = memoizeFunction(
+ *   findPaths,
+ *   (start, end, visited = new Set()) =>
+ *     `${start}->${end}:[${[...visited].sort().join(',')}]`
+ * );
+ * ```
+ *
+ * @example Cache key strategies
+ * ```typescript
+ * // 1. Simple primitive argument
+ * memoizeFunction(fn, (x: number) => x);
+ *
+ * // 2. Multiple arguments with separator
+ * memoizeFunction(fn, (a: string, b: number) => `${a}|${b}`);
+ *
+ * // 3. Object with specific fields
+ * memoizeFunction(fn, (obj: { id: number; version: number }) =>
+ *   `${obj.id}:v${obj.version}`
+ * );
+ *
+ * // 4. Array argument with JSON serialization
+ * memoizeFunction(fn, (arr: number[]) => JSON.stringify(arr));
+ *
+ * // 5. Boolean flags as bit field
+ * memoizeFunction(fn, (a: boolean, b: boolean, c: boolean) =>
+ *   (a ? 4 : 0) | (b ? 2 : 0) | (c ? 1 : 0)
+ * );
+ * ```
+ *
+ * @example Memory-conscious memoization with weak references
+ * ```typescript
+ * // For object keys, consider using WeakMap externally
+ * const cache = new WeakMap<object, Result>();
+ *
+ * function memoizeWithWeakMap<T extends object, R>(
+ *   fn: (obj: T) => R
+ * ): (obj: T) => R {
+ *   return (obj: T): R => {
+ *     if (cache.has(obj)) {
+ *       return cache.get(obj)!;
+ *     }
+ *     const result = fn(obj);
+ *     cache.set(obj, result);
+ *     return result;
+ *   };
+ * }
+ * ```
+ *
+ * @example Anti-patterns to avoid
+ * ```typescript
+ * // ❌ Bad: Memoizing impure functions
+ * const memoizedRandom = memoizeFunction(
+ *   () => Math.random(),
+ *   () => 'key' // Always returns cached random value!
+ * );
+ *
+ * // ❌ Bad: Memoizing functions with side effects
+ * const memoizedLog = memoizeFunction(
+ *   (msg: string) => { console.log(msg); return msg; },
+ *   (msg) => msg // Logs only on first call!
+ * );
+ *
+ * // ❌ Bad: Non-unique cache keys
+ * const memoizedProcess = memoizeFunction(
+ *   (user: User) => processUser(user),
+ *   (user) => user.name // Multiple users can have same name!
+ * );
+ * ```
+ *
+ * @see https://en.wikipedia.org/wiki/Memoization
+ */
+export declare const memoizeFunction: <const A extends readonly unknown[], R, K extends Primitive>(fn: (...args: A) => R, argsToCacheKey: (...args: A) => K) => ((...args: A) => R);
+//# sourceMappingURL=memoize-function.d.mts.map

package/dist/others/memoize-function.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memoize-function.d.mts","sourceRoot":"","sources":["../../src/others/memoize-function.mts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0KG;AACH,eAAO,MAAM,eAAe,GAC1B,KAAK,CAAC,CAAC,SAAS,SAAS,OAAO,EAAE,EAClC,CAAC,EACD,CAAC,SAAS,SAAS,EAEnB,IAAI,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,CAAC,EACrB,gBAAgB,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,CAAC,KAChC,CAAC,CAAC,GAAG,IAAI,EAAE,CAAC,KAAK,CAAC,CAiBpB,CAAC"}

package/dist/others/memoize-function.mjs

@@ -0,0 +1,189 @@
+/**
+ * Creates a memoized version of a function that caches results based on input arguments.
+ *
+ * The memoized function stores results in an internal Map and returns cached values
+ * for repeated calls with the same arguments. This can significantly improve performance
+ * for expensive computations or I/O operations.
+ *
+ * **Important considerations:**
+ * - The cache grows unbounded - consider memory implications for long-running applications
+ * - Cache keys must be primitives (string, number, boolean, symbol, null, undefined, bigint)
+ * - Object arguments require careful key generation to ensure uniqueness
+ * - Pure functions only - memoizing functions with side effects can lead to bugs
+ *
+ * @template A - The tuple type of the function arguments
+ * @template R - The return type of the function
+ * @template K - The primitive type used as the cache key (must be valid Map key)
+ * @param fn - The pure function to memoize
+ * @param argsToCacheKey - Function that converts arguments to a unique cache key
+ * @returns A memoized version of the input function with the same signature
+ *
+ * @example Basic memoization for expensive calculations
+ * ```typescript
+ * // Fibonacci calculation (exponential time complexity)
+ * const fibonacci = (n: number): number => {
+ *   console.log(`Computing fib(${n})`);
+ *   if (n <= 1) return n;
+ *   return fibonacci(n - 1) + fibonacci(n - 2);
+ * };
+ *
+ * const memoizedFib = memoizeFunction(
+ *   fibonacci,
+ *   (n) => n // Number itself as key
+ * );
+ *
+ * memoizedFib(40); // Much faster than unmemoized version
+ * memoizedFib(40); // Returns instantly from cache
+ * ```
+ *
+ * @example Multi-argument functions with composite keys
+ * ```typescript
+ * // Grid calculation with x,y coordinates
+ * const calculateGridValue = (x: number, y: number, scale: number): number => {
+ *   console.log(`Computing grid(${x},${y},${scale})`);
+ *   // Expensive computation...
+ *   return Math.sin(x * scale) * Math.cos(y * scale);
+ * };
+ *
+ * const memoizedGrid = memoizeFunction(
+ *   calculateGridValue,
+ *   (x, y, scale) => `${x},${y},${scale}` // String concatenation for composite key
+ * );
+ *
+ * // Alternative: Using bit manipulation for integer coordinates
+ * const memoizedGrid2 = memoizeFunction(
+ *   calculateGridValue,
+ *   (x, y, scale) => (x << 20) | (y << 10) | scale // Assuming small positive integers
+ * );
+ * ```
+ *
+ * @example Object arguments with selective memoization
+ * ```typescript
+ * interface User {
+ *   id: number;
+ *   name: string;
+ *   email: string;
+ *   metadata?: Record<string, unknown>;
+ * }
+ *
+ * const fetchUserPermissions = async (user: User): Promise<string[]> => {
+ *   console.log(`Fetching permissions for user ${user.id}`);
+ *   const response = await api.get(`/permissions/${user.id}`);
+ *   return response.data;
+ * };
+ *
+ * // Memoize based only on user ID, ignoring other fields
+ * const memoizedFetchPermissions = memoizeFunction(
+ *   fetchUserPermissions,
+ *   (user) => user.id // Only cache by ID
+ * );
+ *
+ * // For multiple identifying fields
+ * const processUserData = (user: User, orgId: number): ProcessedData => {
+ *   // Complex processing...
+ * };
+ *
+ * const memoizedProcess = memoizeFunction(
+ *   processUserData,
+ *   (user, orgId) => `${user.id}:${orgId}` // Composite key with separator
+ * );
+ * ```
+ *
+ * @example Memoizing recursive functions
+ * ```typescript
+ * // Recursive path finding
+ * const findPaths = (start: string, end: string, visited: Set<string> = new Set()): string[][] => {
+ *   if (start === end) return [[end]];
+ *   // ... complex recursive logic
+ * };
+ *
+ * // Use sorted, serialized visited set for consistent keys
+ * const memoizedFindPaths = memoizeFunction(
+ *   findPaths,
+ *   (start, end, visited = new Set()) =>
+ *     `${start}->${end}:[${[...visited].sort().join(',')}]`
+ * );
+ * ```
+ *
+ * @example Cache key strategies
+ * ```typescript
+ * // 1. Simple primitive argument
+ * memoizeFunction(fn, (x: number) => x);
+ *
+ * // 2. Multiple arguments with separator
+ * memoizeFunction(fn, (a: string, b: number) => `${a}|${b}`);
+ *
+ * // 3. Object with specific fields
+ * memoizeFunction(fn, (obj: { id: number; version: number }) =>
+ *   `${obj.id}:v${obj.version}`
+ * );
+ *
+ * // 4. Array argument with JSON serialization
+ * memoizeFunction(fn, (arr: number[]) => JSON.stringify(arr));
+ *
+ * // 5. Boolean flags as bit field
+ * memoizeFunction(fn, (a: boolean, b: boolean, c: boolean) =>
+ *   (a ? 4 : 0) | (b ? 2 : 0) | (c ? 1 : 0)
+ * );
+ * ```
+ *
+ * @example Memory-conscious memoization with weak references
+ * ```typescript
+ * // For object keys, consider using WeakMap externally
+ * const cache = new WeakMap<object, Result>();
+ *
+ * function memoizeWithWeakMap<T extends object, R>(
+ *   fn: (obj: T) => R
+ * ): (obj: T) => R {
+ *   return (obj: T): R => {
+ *     if (cache.has(obj)) {
+ *       return cache.get(obj)!;
+ *     }
+ *     const result = fn(obj);
+ *     cache.set(obj, result);
+ *     return result;
+ *   };
+ * }
+ * ```
+ *
+ * @example Anti-patterns to avoid
+ * ```typescript
+ * // ❌ Bad: Memoizing impure functions
+ * const memoizedRandom = memoizeFunction(
+ *   () => Math.random(),
+ *   () => 'key' // Always returns cached random value!
+ * );
+ *
+ * // ❌ Bad: Memoizing functions with side effects
+ * const memoizedLog = memoizeFunction(
+ *   (msg: string) => { console.log(msg); return msg; },
+ *   (msg) => msg // Logs only on first call!
+ * );
+ *
+ * // ❌ Bad: Non-unique cache keys
+ * const memoizedProcess = memoizeFunction(
+ *   (user: User) => processUser(user),
+ *   (user) => user.name // Multiple users can have same name!
+ * );
+ * ```
+ *
+ * @see https://en.wikipedia.org/wiki/Memoization
+ */
+const memoizeFunction = (fn, argsToCacheKey) => {
+    const mut_cache = new Map();
+    return (...args) => {
+        const key = argsToCacheKey(...args);
+        if (mut_cache.has(key)) {
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+            return mut_cache.get(key);
+        }
+        else {
+            const result = fn(...args);
+            mut_cache.set(key, result);
+            return result;
+        }
+    };
+};
+
+export { memoizeFunction };
+//# sourceMappingURL=memoize-function.mjs.map

package/dist/others/memoize-function.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"memoize-function.mjs","sources":["../../src/others/memoize-function.mts"],"sourcesContent":[null],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0KG;MACU,eAAe,GAAG,CAK7B,EAAqB,EACrB,cAAiC,KACV;AACvB,IAAA,MAAM,SAAS,GAAG,IAAI,GAAG,EAAQ;AAEjC,IAAA,OAAO,CAAC,GAAG,IAAO,KAAO;AACvB,QAAA,MAAM,GAAG,GAAG,cAAc,CAAC,GAAG,IAAI,CAAC;AAEnC,QAAA,IAAI,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE;;AAEtB,YAAA,OAAO,SAAS,CAAC,GAAG,CAAC,GAAG,CAAE;;aACrB;AACL,YAAA,MAAM,MAAM,GAAG,EAAE,CAAC,GAAG,IAAI,CAAC;AAE1B,YAAA,SAAS,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC;AAE1B,YAAA,OAAO,MAAM;;AAEjB,KAAC;AACH;;;;"}

package/dist/others/tuple.d.mts

@@ -0,0 +1,159 @@
+/**
+ * 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 declare const tp: <const T extends readonly unknown[]>(...args: T) => Readonly<T>;
+//# sourceMappingURL=tuple.d.mts.map

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

@@ -0,0 +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"}

package/dist/others/tuple.mjs

@@ -0,0 +1,161 @@
+/**
+ * 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
+ */
+const tp = (...args) => args;
+
+export { tp };
+//# sourceMappingURL=tuple.mjs.map

package/dist/others/tuple.mjs.map

@@ -0,0 +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;;;;"}