ts-data-forge 1.0.0

package/src/others/map-nullable.test.mts

@@ -0,0 +1,297 @@
+import { expectType } from '../expect-type.mjs';
+import { pipe } from '../functional/index.mjs';
+import { mapNullable } from './map-nullable.mjs';
+
+describe('mapNullable', () => {
+  describe('regular usage', () => {
+    test('should apply function to non-null value', () => {
+      const result = mapNullable('hello', (s) => s.toUpperCase());
+      expect(result).toBe('HELLO');
+      expectType<typeof result, string | undefined>('=');
+    });
+
+    test('should apply function to non-undefined value', () => {
+      const result = mapNullable(42, (n) => n * 2);
+      expect(result).toBe(84);
+      expectType<typeof result, number | undefined>('=');
+    });
+
+    test('should return undefined for null input', () => {
+      const result = mapNullable(null, (s: string) => s.toUpperCase());
+      expect(result).toBeUndefined();
+      expectType<typeof result, string | undefined>('=');
+    });
+
+    test('should return undefined for undefined input', () => {
+      const result = mapNullable(undefined, (s: string) => s.toUpperCase());
+      expect(result).toBeUndefined();
+      expectType<typeof result, string | undefined>('=');
+    });
+
+    test('should work with complex transformations', () => {
+      const user = { name: 'Alice', age: 30 };
+      const result = mapNullable(
+        user,
+        (u) => `${u.name} is ${u.age} years old`,
+      );
+      expect(result).toBe('Alice is 30 years old');
+    });
+
+    test('should work with nullable object properties', () => {
+      const user: { name?: string } = { name: 'Bob' };
+      const result = mapNullable(user.name, (name) => name.toUpperCase());
+      expect(result).toBe('BOB');
+
+      const userWithoutName: { name?: string } = {};
+      const resultEmpty = mapNullable(userWithoutName.name, (name) =>
+        name.toUpperCase(),
+      );
+      expect(resultEmpty).toBeUndefined();
+    });
+  });
+
+  describe('curried usage', () => {
+    test('should support curried form with string transformation', () => {
+      const toUpperCase = mapNullable((s: string) => s.toUpperCase());
+
+      const result1 = toUpperCase('hello');
+      expect(result1).toBe('HELLO');
+
+      const result2 = toUpperCase(null);
+      expect(result2).toBeUndefined();
+
+      const result3 = toUpperCase(undefined);
+      expect(result3).toBeUndefined();
+    });
+
+    test('should support curried form with number transformation', () => {
+      const double = mapNullable((n: number) => n * 2);
+
+      const result1 = double(21);
+      expect(result1).toBe(42);
+
+      const result2 = double(null);
+      expect(result2).toBeUndefined();
+
+      const result3 = double(undefined);
+      expect(result3).toBeUndefined();
+    });
+
+    test('should support curried form with object transformation', () => {
+      const getName = mapNullable(
+        (u: Readonly<{ name: string; age: number }>) => u.name,
+      );
+
+      const user = { name: 'Charlie', age: 25 };
+      const result1 = getName(user);
+      expect(result1).toBe('Charlie');
+
+      const result2 = getName(null);
+      expect(result2).toBeUndefined();
+    });
+
+    test('should work with pipe composition', () => {
+      const toUpperCase = mapNullable((s: string) => s.toUpperCase());
+      const addGreeting = mapNullable((s: string) => `Hello, ${s}!`);
+
+      const result = pipe('world').map(toUpperCase).map(addGreeting).value;
+
+      expect(result).toBe('Hello, WORLD!');
+    });
+
+    test('should handle null values in pipe composition', () => {
+      const toUpperCase = mapNullable((s: string) => s.toUpperCase());
+      const addGreeting = mapNullable((s: string) => `Hello, ${s}!`);
+
+      const result = pipe(null as string | null)
+        .map(toUpperCase)
+        .map(addGreeting).value;
+
+      expect(result).toBeUndefined();
+    });
+
+    test('should work with multiple transformations in pipe', () => {
+      const toStr = mapNullable((n: number) => n.toString());
+      const addPrefix = mapNullable((s: string) => `Number: ${s}`);
+      const toUpperCase = mapNullable((s: string) => s.toUpperCase());
+
+      const result = pipe(42 as number | null)
+        .map(toStr)
+        .map(addPrefix)
+        .map(toUpperCase).value;
+
+      expect(result).toBe('NUMBER: 42');
+    });
+  });
+
+  describe('edge cases and type safety', () => {
+    test('should preserve type information', () => {
+      expectTypeOf(mapNullable('test', (s) => s.length)).toEqualTypeOf<
+        number | undefined
+      >();
+
+      expectTypeOf(mapNullable(42, (n) => n.toString())).toEqualTypeOf<
+        string | undefined
+      >();
+
+      expectTypeOf(mapNullable(true, (b) => !b)).toEqualTypeOf<
+        boolean | undefined
+      >();
+    });
+
+    test('should work with zero values', () => {
+      const result = mapNullable(0, (n) => n + 1);
+      expect(result).toBe(1);
+    });
+
+    test('should work with empty string', () => {
+      const result = mapNullable('', (s) => s.length);
+      expect(result).toBe(0);
+    });
+
+    test('should work with false boolean', () => {
+      const result = mapNullable(false, (b) => !b);
+      expect(result).toBe(true);
+    });
+
+    test('should work with arrays', () => {
+      const result = mapNullable([1, 2, 3], (arr) => arr.length);
+      expect(result).toBe(3);
+
+      const nullResult = mapNullable(
+        null as number[] | null,
+        (arr) => arr.length,
+      );
+      expect(nullResult).toBeUndefined();
+    });
+
+    test('should work with nested objects', () => {
+      const data = {
+        user: { profile: { name: 'Alice' } },
+        settings: { theme: 'dark' },
+      };
+
+      const result = mapNullable(data, (d) => d.user.profile.name);
+      expect(result).toBe('Alice');
+    });
+  });
+
+  describe('chaining operations', () => {
+    test('should chain multiple mapNullable operations', () => {
+      const getValue = (): string | null => 'hello';
+
+      const step1 = mapNullable(getValue(), (s) => s.toUpperCase());
+      const step2 = mapNullable(step1, (s) => s.length);
+      const step3 = mapNullable(step2, (n) => n * 2);
+
+      expect(step3).toBe(10); // 'HELLO'.length * 2 = 5 * 2 = 10
+    });
+
+    test('should short-circuit on null in chain', () => {
+      const getValue = (): string | null => null;
+
+      const step1 = mapNullable(getValue(), (s) => s.toUpperCase());
+      const step2 = mapNullable(step1, (s) => s.length);
+      const step3 = mapNullable(step2, (n) => n * 2);
+
+      expect(step1).toBeUndefined();
+      expect(step2).toBeUndefined();
+      expect(step3).toBeUndefined();
+    });
+
+    test('should work with curried functions in chain', () => {
+      const toUpperCase = mapNullable((s: string) => s.toUpperCase());
+      const getLength = mapNullable((s: string) => s.length);
+      const double = mapNullable((n: number) => n * 2);
+
+      const input1 = 'hello';
+      const result1 = double(getLength(toUpperCase(input1)));
+      expect(result1).toBe(10);
+
+      const input2: string | null = null;
+      const result2 = double(getLength(toUpperCase(input2)));
+      expect(result2).toBeUndefined();
+    });
+  });
+
+  describe('practical use cases', () => {
+    test('should work with API response handling', () => {
+      type ApiResponse = DeepReadonly<{
+        data?: {
+          user?: {
+            name?: string;
+            email?: string;
+          };
+        };
+      }>;
+
+      const response: ApiResponse = {
+        data: {
+          user: {
+            name: 'John Doe',
+            email: 'john@example.com',
+          },
+        },
+      };
+
+      const extractUserName = mapNullable(
+        (r: ApiResponse) => r.data?.user?.name,
+      );
+      const formatName = mapNullable((name: string) => `Mr. ${name}`);
+
+      const userName = extractUserName(response);
+      const formattedName = formatName(userName);
+
+      expect(formattedName).toBe('Mr. John Doe');
+    });
+
+    test('should work with form data processing', () => {
+      type FormData = Readonly<{
+        email?: string;
+        age?: string;
+      }>;
+
+      const formData: FormData = {
+        email: 'test@example.com',
+        age: '25',
+      };
+
+      const extractAge = mapNullable((data: FormData) => data.age);
+      const parseAge = mapNullable((ageStr: string) =>
+        Number.parseInt(ageStr, 10),
+      );
+      const validateAge = mapNullable((age: number) =>
+        age >= 18 ? age : null,
+      );
+
+      const extractedAge = extractAge(formData);
+      const parsedAge = parseAge(extractedAge);
+      const validAge = validateAge(parsedAge);
+
+      expect(validAge).toBe(25);
+    });
+
+    test('should handle missing data gracefully', () => {
+      type FormData = Readonly<{
+        email?: string;
+        age?: string;
+      }>;
+
+      const incompleteFormData: FormData = {
+        email: 'test@example.com',
+        // age is missing
+      };
+
+      const extractAge = mapNullable((data: FormData) => data.age);
+      const parseAge = mapNullable((ageStr: string) =>
+        Number.parseInt(ageStr, 10),
+      );
+
+      const extractedAge = extractAge(incompleteFormData);
+      const parsedAge = parseAge(extractedAge);
+
+      expect(extractedAge).toBeUndefined();
+      expect(parsedAge).toBeUndefined();
+    });
+  });
+});

package/src/others/memoize-function.mts

@@ -0,0 +1,196 @@
+/**
+ * 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 const memoizeFunction = <
+  const A extends readonly unknown[],
+  R,
+  K extends Primitive,
+>(
+  fn: (...args: A) => R,
+  argsToCacheKey: (...args: A) => K,
+): ((...args: A) => R) => {
+  const mut_cache = new Map<K, R>();
+
+  return (...args: A): R => {
+    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;
+    }
+  };
+};

package/src/others/memoize-function.test.mts

@@ -0,0 +1,168 @@
+/* eslint-disable @typescript-eslint/no-confusing-void-expression */
+import { memoizeFunction } from './memoize-function.mjs';
+
+describe('memoizeFunction', () => {
+  test('should cache results for the same arguments', () => {
+    const mockFn = vi.fn((x: number) => x * 2);
+    const memoized = memoizeFunction(mockFn, (x) => x);
+
+    // First call
+    expect(memoized(5)).toBe(10);
+    expect(mockFn).toHaveBeenCalledTimes(1);
+
+    // Second call with same argument - should use cache
+    expect(memoized(5)).toBe(10);
+    expect(mockFn).toHaveBeenCalledTimes(1);
+
+    // Call with different argument
+    expect(memoized(3)).toBe(6);
+    expect(mockFn).toHaveBeenCalledTimes(2);
+  });
+
+  test('should work with multiple arguments', () => {
+    const mockFn = vi.fn((a: number, b: number) => a + b);
+    const memoized = memoizeFunction(mockFn, (a, b) => `${a},${b}`);
+
+    expect(memoized(2, 3)).toBe(5);
+    expect(mockFn).toHaveBeenCalledTimes(1);
+
+    expect(memoized(2, 3)).toBe(5);
+    expect(mockFn).toHaveBeenCalledTimes(1);
+
+    expect(memoized(3, 2)).toBe(5);
+    expect(mockFn).toHaveBeenCalledTimes(2);
+  });
+
+  test('should handle functions that return undefined', () => {
+    const mockFn = vi.fn((_x: number) => undefined);
+    const memoized = memoizeFunction(mockFn, (x) => x);
+
+    expect(memoized(5)).toBe(undefined);
+    expect(mockFn).toHaveBeenCalledTimes(1);
+
+    // Should use cache even for undefined
+    expect(memoized(5)).toBe(undefined);
+    expect(mockFn).toHaveBeenCalledTimes(1);
+  });
+
+  test('should work with object arguments using primitive cache keys', () => {
+    type User = Readonly<{ id: number; name: string }>;
+    const mockFn = vi.fn((user: User) => `Hello ${user.name}`);
+    const memoized = memoizeFunction(mockFn, (user) => user.id);
+
+    const user1 = { id: 1, name: 'Alice' };
+    const user2 = { id: 1, name: 'Bob' }; // Same id, different name
+    const user3 = { id: 2, name: 'Charlie' };
+
+    expect(memoized(user1)).toBe('Hello Alice');
+    expect(mockFn).toHaveBeenCalledTimes(1);
+
+    // Same id, should use cache (even though name is different)
+    expect(memoized(user2)).toBe('Hello Alice');
+    expect(mockFn).toHaveBeenCalledTimes(1);
+
+    // Different id, should call function
+    expect(memoized(user3)).toBe('Hello Charlie');
+    expect(mockFn).toHaveBeenCalledTimes(2);
+  });
+
+  test('should work with different cache key types', () => {
+    // Number key
+    const withNumber = memoizeFunction(
+      (x: string) => x.length,
+      (x) => x.length,
+    );
+    expect(withNumber('hello')).toBe(5);
+    expect(withNumber('world')).toBe(5); // Same length, uses cache
+
+    // Boolean key
+    const withBoolean = memoizeFunction(
+      (x: number) => x * 2,
+      (x) => x > 0,
+    );
+    expect(withBoolean(5)).toBe(10);
+    expect(withBoolean(3)).toBe(10); // Both positive, uses cache
+    expect(withBoolean(-2)).toBe(-4); // Negative, new cache entry
+
+    // Symbol key
+    const sym1 = Symbol('test');
+    const sym2 = Symbol('test');
+    const withSymbol = memoizeFunction(
+      (_s: symbol) => Math.random(),
+      (s) => s,
+    );
+    const result1 = withSymbol(sym1);
+    expect(withSymbol(sym1)).toBe(result1); // Same symbol, uses cache
+    expect(withSymbol(sym2)).not.toBe(result1); // Different symbol
+  });
+
+  test('should handle null and undefined cache keys', () => {
+    const mockFn = vi.fn((x: string | null | undefined) => x ?? 'default');
+    const memoized = memoizeFunction(mockFn, (x) => x);
+
+    expect(memoized(null)).toBe('default');
+    expect(mockFn).toHaveBeenCalledTimes(1);
+
+    expect(memoized(null)).toBe('default');
+    expect(mockFn).toHaveBeenCalledTimes(1);
+
+    expect(memoized(undefined)).toBe('default');
+    expect(mockFn).toHaveBeenCalledTimes(2);
+
+    expect(memoized(undefined)).toBe('default');
+    expect(mockFn).toHaveBeenCalledTimes(2);
+  });
+
+  test('should maintain separate caches for different memoized functions', () => {
+    const fn1 = vi.fn((x: number) => x * 2);
+    const fn2 = vi.fn((x: number) => x * 3);
+
+    const memoized1 = memoizeFunction(fn1, (x) => x);
+    const memoized2 = memoizeFunction(fn2, (x) => x);
+
+    expect(memoized1(5)).toBe(10);
+    expect(memoized2(5)).toBe(15);
+
+    expect(fn1).toHaveBeenCalledTimes(1);
+    expect(fn2).toHaveBeenCalledTimes(1);
+
+    // Each has its own cache
+    expect(memoized1(5)).toBe(10);
+    expect(memoized2(5)).toBe(15);
+
+    expect(fn1).toHaveBeenCalledTimes(1);
+    expect(fn2).toHaveBeenCalledTimes(1);
+  });
+
+  test('should work with complex cache key generation', () => {
+    type Args = Readonly<{
+      category: string;
+      subcategory: string;
+      id: number;
+    }>;
+
+    const mockFn = vi.fn(
+      (args: Args) => `${args.category}/${args.subcategory}/${args.id}`,
+    );
+
+    const memoized = memoizeFunction(
+      mockFn,
+      (args) => `${args.category}:${args.subcategory}:${args.id}`,
+    );
+
+    const args1 = { category: 'books', subcategory: 'fiction', id: 123 };
+    const args2 = { category: 'books', subcategory: 'fiction', id: 123 };
+    const args3 = { category: 'books', subcategory: 'fiction', id: 124 };
+
+    expect(memoized(args1)).toBe('books/fiction/123');
+    expect(mockFn).toHaveBeenCalledTimes(1);
+
+    // Same cache key, should use cache
+    expect(memoized(args2)).toBe('books/fiction/123');
+    expect(mockFn).toHaveBeenCalledTimes(1);
+
+    // Different id, different cache key
+    expect(memoized(args3)).toBe('books/fiction/124');
+    expect(mockFn).toHaveBeenCalledTimes(2);
+  });
+});