ts-data-forge 1.0.0

package/src/others/cast-readonly.mts

@@ -0,0 +1,192 @@
+/**
+ * Casts a mutable type `T` to its `Readonly<T>` equivalent.
+ *
+ * This is a safe type assertion that adds immutability constraints at the type level.
+ * The runtime value remains unchanged - only TypeScript's view of it becomes readonly.
+ * This helps prevent accidental mutations and makes code intentions clearer.
+ *
+ * @template T - The type of the mutable value
+ * @param mutable - The mutable value to cast to readonly
+ * @returns The same value with readonly modifiers added to its type
+ *
+ * @example Basic usage with arrays and objects
+ * ```typescript
+ * const mutableArr: number[] = [1, 2, 3];
+ * const readonlyArr = castReadonly(mutableArr);
+ * // readonlyArr.push(4); // ❌ TypeScript Error: no 'push' on readonly array
+ *
+ * const mutableObj = { x: 1, y: 2 };
+ * const readonlyObj = castReadonly(mutableObj);
+ * // readonlyObj.x = 5; // ❌ TypeScript Error: cannot assign to readonly property
+ * ```
+ *
+ * @example Protecting function return values
+ * ```typescript
+ * // Prevent callers from mutating internal state
+ * class UserService {
+ *   private users: User[] = [];
+ *
+ *   getUsers(): readonly User[] {
+ *     return castReadonly(this.users); // Callers can't mutate the array
+ *   }
+ * }
+ *
+ * const service = new UserService();
+ * const users = service.getUsers();
+ * // users.push(newUser); // ❌ TypeScript prevents this
+ * ```
+ *
+ * @example Creating immutable configurations
+ * ```typescript
+ * // Start with mutable object for initialization
+ * const config = {
+ *   apiUrl: 'https://api.example.com',
+ *   timeout: 5000,
+ *   retries: 3
+ * };
+ *
+ * // Validate and process config...
+ *
+ * // Export as readonly to prevent modifications
+ * export const APP_CONFIG = castReadonly(config);
+ * // APP_CONFIG.timeout = 10000; // ❌ TypeScript Error
+ * ```
+ *
+ * @example Working with array methods
+ * ```typescript
+ * const numbers: number[] = [1, 2, 3, 4, 5];
+ * const readonlyNumbers = castReadonly(numbers);
+ *
+ * // Read operations still work
+ * const doubled = readonlyNumbers.map(n => n * 2); // ✅ Returns new array
+ * const sum = readonlyNumbers.reduce((a, b) => a + b, 0); // ✅ Works
+ * const first = readonlyNumbers[0]; // ✅ Reading is allowed
+ *
+ * // Mutations are prevented
+ * // readonlyNumbers[0] = 10; // ❌ TypeScript Error
+ * // readonlyNumbers.sort(); // ❌ TypeScript Error (sort mutates)
+ * ```
+ *
+ * @see castDeepReadonly - For deeply nested structures
+ * @see castMutable - For the opposite operation (use with caution)
+ */
+export const castReadonly = <T,>(mutable: T): Readonly<T> =>
+  mutable as Readonly<T>;
+
+/**
+ * Casts a mutable type `T` to its `DeepReadonly<T>` equivalent, recursively adding readonly modifiers.
+ *
+ * This is a safe type assertion that adds immutability constraints at ALL levels of nesting.
+ * Provides complete protection against mutations in complex data structures.
+ * The runtime value is unchanged - only TypeScript's type checking is enhanced.
+ *
+ * @template T - The type of the mutable value
+ * @param mutable - The mutable value to cast to deeply readonly
+ * @returns The same value with readonly modifiers recursively added to all properties
+ *
+ * @example Basic usage with nested structures
+ * ```typescript
+ * const mutableNested = {
+ *   a: { b: [1, 2, 3] },
+ *   c: { d: { e: 'value' } }
+ * };
+ *
+ * const readonlyNested = castDeepReadonly(mutableNested);
+ * // readonlyNested.a.b.push(4); // ❌ Error: readonly at all levels
+ * // readonlyNested.c.d.e = 'new'; // ❌ Error: readonly at all levels
+ * // readonlyNested.a = {}; // ❌ Error: cannot reassign readonly property
+ * ```
+ *
+ * @example Protecting complex state objects
+ * ```typescript
+ * interface AppState {
+ *   user: {
+ *     id: number;
+ *     profile: {
+ *       name: string;
+ *       settings: {
+ *         theme: string;
+ *         notifications: boolean[];
+ *       };
+ *     };
+ *   };
+ *   data: {
+ *     items: Array<{ id: number; value: string }>;
+ *   };
+ * }
+ *
+ * class StateManager {
+ *   private state: AppState = initialState;
+ *
+ *   getState(): DeepReadonly<AppState> {
+ *     return castDeepReadonly(this.state);
+ *   }
+ *
+ *   // Mutations only allowed through specific methods
+ *   updateTheme(theme: string) {
+ *     this.state.user.profile.settings.theme = theme;
+ *   }
+ * }
+ * ```
+ *
+ * @example Creating immutable API responses
+ * ```typescript
+ * async function fetchUserData(): Promise<DeepReadonly<UserData>> {
+ *   const response = await api.get<UserData>('/user');
+ *
+ *   // Process and validate data...
+ *
+ *   // Return as deeply immutable to prevent accidental mutations
+ *   return castDeepReadonly(response.data);
+ * }
+ *
+ * const userData = await fetchUserData();
+ * // userData is fully protected from mutations at any depth
+ * // userData.preferences.emails.push('new@email.com'); // ❌ TypeScript Error
+ * ```
+ *
+ * @example Working with Redux or state management
+ * ```typescript
+ * // Redux reducer example
+ * type State = DeepReadonly<AppState>;
+ *
+ * function reducer(state: State, action: Action): State {
+ *   switch (action.type) {
+ *     case 'UPDATE_USER_NAME':
+ *       // Must create new objects, can't mutate
+ *       return castDeepReadonly({
+ *         ...state,
+ *         user: {
+ *           ...state.user,
+ *           profile: {
+ *             ...state.user.profile,
+ *             name: action.payload
+ *           }
+ *         }
+ *       });
+ *     default:
+ *       return state;
+ *   }
+ * }
+ * ```
+ *
+ * @example Type inference with generics
+ * ```typescript
+ * function processData<T>(data: T): DeepReadonly<T> {
+ *   // Perform processing...
+ *   console.log('Processing:', data);
+ *
+ *   // Return immutable version
+ *   return castDeepReadonly(data);
+ * }
+ *
+ * const result = processData({ nested: { value: [1, 2, 3] } });
+ * // Type of result is DeepReadonly<{ nested: { value: number[] } }>
+ * ```
+ *
+ * @see castReadonly - For shallow readonly casting
+ * @see castDeepMutable - For the opposite operation (use with extreme caution)
+ */
+export const castDeepReadonly = <T,>(mutable: T): DeepReadonly<T> =>
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+  mutable as DeepReadonly<T>;

package/src/others/cast-readonly.test.mts

@@ -0,0 +1,89 @@
+import { castDeepReadonly, castReadonly } from './cast-readonly.mjs';
+
+describe('castReadonly', () => {
+  test('should cast mutable array to readonly', () => {
+    const mutableArr = [1, 2, 3];
+    const readonlyArr = castReadonly(mutableArr);
+
+    expect(readonlyArr).toBe(mutableArr); // Same reference
+    expect(readonlyArr).toStrictEqual([1, 2, 3]);
+  });
+
+  test('should cast mutable object to readonly', () => {
+    const mutableObj = { x: 1, y: 2 };
+    const readonlyObj = castReadonly(mutableObj);
+
+    expect(readonlyObj).toBe(mutableObj); // Same reference
+    expect(readonlyObj).toStrictEqual({ x: 1, y: 2 });
+  });
+
+  test('should preserve the runtime value', () => {
+    const original = { value: 42 };
+    const readonly = castReadonly(original);
+
+    expect(readonly.value).toBe(42);
+    expect(Object.is(readonly, original)).toBe(true);
+  });
+
+  test('should work with primitives', () => {
+    expect(castReadonly(42)).toBe(42);
+    expect(castReadonly('hello')).toBe('hello');
+    expect(castReadonly(true)).toBe(true);
+  });
+
+  test('should work with null and undefined', () => {
+    expect(castReadonly(null)).toBe(null);
+    // eslint-disable-next-line @typescript-eslint/no-confusing-void-expression
+    expect(castReadonly(undefined)).toBe(undefined);
+  });
+});
+
+describe('castDeepReadonly', () => {
+  test('should cast deeply nested structure to readonly', () => {
+    const mutableNested = {
+      a: { b: [1, 2, 3] },
+      c: { d: { e: 'value' } },
+    };
+    const readonlyNested = castDeepReadonly(mutableNested);
+
+    expect(readonlyNested).toBe(mutableNested); // Same reference
+    expect(readonlyNested.a.b).toStrictEqual([1, 2, 3]);
+    expect(readonlyNested.c.d.e).toBe('value');
+  });
+
+  test('should preserve runtime value for complex structures', () => {
+    const complex = {
+      users: [{ id: 1, profile: { name: 'Alice' } }],
+      settings: { theme: 'dark', options: { debug: true } },
+    };
+    const readonly = castDeepReadonly(complex);
+
+    expect(readonly).toBe(complex);
+    expect(readonly.users[0]?.profile.name).toBe('Alice');
+    expect(readonly.settings.options.debug).toBe(true);
+  });
+
+  test('should work with arrays of objects', () => {
+    const data = [
+      { id: 1, meta: { active: true } },
+      { id: 2, meta: { active: false } },
+    ];
+    const readonly = castDeepReadonly(data);
+
+    expect(readonly).toBe(data);
+    expect(readonly[0]?.meta.active).toBe(true);
+    expect(readonly[1]?.meta.active).toBe(false);
+  });
+
+  test('should work with primitives', () => {
+    expect(castDeepReadonly(42)).toBe(42);
+    expect(castDeepReadonly('hello')).toBe('hello');
+    expect(castDeepReadonly(true)).toBe(true);
+  });
+
+  test('should work with null and undefined', () => {
+    expect(castDeepReadonly(null)).toBe(null);
+    // eslint-disable-next-line @typescript-eslint/no-confusing-void-expression
+    expect(castDeepReadonly(undefined)).toBe(undefined);
+  });
+});

package/src/others/if-then.mts

@@ -0,0 +1,98 @@
+/**
+ * Implements the logical implication (if-then) operator.
+ *
+ * Returns `true` if the antecedent is `false` or the consequent is `true`.
+ * In logical terms: `antecedent → consequent` is equivalent to `¬antecedent ∨ consequent`.
+ *
+ * **Truth table:**
+ * - `true → true` = `true` (valid implication)
+ * - `true → false` = `false` (invalid implication)
+ * - `false → true` = `true` (vacuously true)
+ * - `false → false` = `true` (vacuously true)
+ *
+ * @param antecedent - The condition (if part)
+ * @param consequent - The result that should hold if the condition is true (then part)
+ * @returns `true` if the implication holds, `false` otherwise
+ *
+ * @example Basic truth table demonstration
+ * ```typescript
+ * ifThen(true, true);   // true  (if true then true = true)
+ * ifThen(true, false);  // false (if true then false = false)
+ * ifThen(false, true);  // true  (if false then true = true - vacuously true)
+ * ifThen(false, false); // true  (if false then false = true - vacuously true)
+ * ```
+ *
+ * @example Validation logic - "if required then must have value"
+ * ```typescript
+ * function validateField(value: string, isRequired: boolean): boolean {
+ *   const hasValue = value.trim().length > 0;
+ *   return ifThen(isRequired, hasValue);
+ * }
+ *
+ * validateField('hello', true);  // true (required and has value)
+ * validateField('', true);       // false (required but no value)
+ * validateField('', false);      // true (not required, so valid)
+ * validateField('hello', false); // true (not required, but has value is fine)
+ * ```
+ *
+ * @example Access control - "if admin then has all permissions"
+ * ```typescript
+ * function checkPermission(user: User, permission: string): boolean {
+ *   const isAdmin = user.role === 'admin';
+ *   const hasPermission = user.permissions.includes(permission);
+ *
+ *   // Admin must have all permissions
+ *   return ifThen(isAdmin, hasPermission);
+ * }
+ *
+ * const adminUser = { role: 'admin', permissions: ['read', 'write'] };
+ * checkPermission(adminUser, 'delete'); // false (admin without delete permission = invalid)
+ *
+ * const regularUser = { role: 'user', permissions: ['read'] };
+ * checkPermission(regularUser, 'delete'); // true (non-admin without permission is valid)
+ * ```
+ *
+ * @example Contract validation - "if premium then features enabled"
+ * ```typescript
+ * interface Subscription {
+ *   isPremium: boolean;
+ *   features: {
+ *     advancedAnalytics: boolean;
+ *     unlimitedStorage: boolean;
+ *     prioritySupport: boolean;
+ *   };
+ * }
+ *
+ * function validateSubscription(sub: Subscription): boolean {
+ *   // If premium, then all premium features must be enabled
+ *   return ifThen(sub.isPremium,
+ *     sub.features.advancedAnalytics &&
+ *     sub.features.unlimitedStorage &&
+ *     sub.features.prioritySupport
+ *   );
+ * }
+ * ```
+ *
+ * @example Chaining multiple implications
+ * ```typescript
+ * // "If A then B" AND "If B then C"
+ * function validateChain(a: boolean, b: boolean, c: boolean): boolean {
+ *   return ifThen(a, b) && ifThen(b, c);
+ * }
+ *
+ * validateChain(true, true, true);   // true (valid chain)
+ * validateChain(true, false, true);  // false (breaks at first implication)
+ * validateChain(false, false, false); // true (vacuously true chain)
+ * ```
+ *
+ * @example Negation patterns
+ * ```typescript
+ * // "If not expired then valid" is equivalent to "expired OR valid"
+ * const isExpired = Date.now() > expiryDate;
+ * const isValid = checkValidity();
+ * const result = ifThen(!isExpired, isValid);
+ * // Same as: isExpired || isValid
+ * ```
+ */
+export const ifThen = (antecedent: boolean, consequent: boolean): boolean =>
+  !antecedent || consequent;

package/src/others/if-then.test.mts

@@ -0,0 +1,75 @@
+import { ifThen } from './if-then.mjs';
+
+describe('ifThen', () => {
+  test('should implement logical implication truth table', () => {
+    // True antecedent, true consequent -> true
+    expect(ifThen(true, true)).toBe(true);
+
+    // True antecedent, false consequent -> false
+    expect(ifThen(true, false)).toBe(false);
+
+    // False antecedent, true consequent -> true (vacuously true)
+    expect(ifThen(false, true)).toBe(true);
+
+    // False antecedent, false consequent -> true (vacuously true)
+    expect(ifThen(false, false)).toBe(true);
+  });
+
+  test('should work for validation logic', () => {
+    const validateField = (value: string, isRequired: boolean): boolean => {
+      const hasValue = value.trim().length > 0;
+      return ifThen(isRequired, hasValue);
+    };
+
+    expect(validateField('hello', true)).toBe(true); // required and has value
+    expect(validateField('', true)).toBe(false); // required but no value
+    expect(validateField('', false)).toBe(true); // not required, so valid
+    expect(validateField('hello', false)).toBe(true); // not required, has value
+  });
+
+  test('should work for access control logic', () => {
+    const checkPermission = (
+      isAdmin: boolean,
+      hasPermission: boolean,
+    ): boolean =>
+      // If admin, then must have permission
+      ifThen(isAdmin, hasPermission);
+    expect(checkPermission(true, true)).toBe(true); // admin with permission
+    expect(checkPermission(true, false)).toBe(false); // admin without permission
+    expect(checkPermission(false, true)).toBe(true); // non-admin with permission
+    expect(checkPermission(false, false)).toBe(true); // non-admin without permission
+  });
+
+  test('should work for contract validation', () => {
+    const validateSubscription = (
+      isPremium: boolean,
+      hasAllFeatures: boolean,
+    ): boolean =>
+      // If premium, then all premium features must be enabled
+      ifThen(isPremium, hasAllFeatures);
+    expect(validateSubscription(true, true)).toBe(true); // premium with all features
+    expect(validateSubscription(true, false)).toBe(false); // premium without all features
+    expect(validateSubscription(false, true)).toBe(true); // non-premium with features
+    expect(validateSubscription(false, false)).toBe(true); // non-premium without features
+  });
+
+  test('should work in chaining scenarios', () => {
+    const validateChain = (a: boolean, b: boolean, c: boolean): boolean =>
+      ifThen(a, b) && ifThen(b, c);
+
+    expect(validateChain(true, true, true)).toBe(true); // valid chain
+    expect(validateChain(true, false, true)).toBe(false); // breaks at first implication
+    expect(validateChain(false, false, false)).toBe(true); // vacuously true chain
+    expect(validateChain(true, true, false)).toBe(false); // breaks at second implication
+  });
+
+  test('should work with negation patterns', () => {
+    const checkExpiredLogic = (isExpired: boolean, isValid: boolean): boolean =>
+      // "If not expired then valid" is equivalent to "expired OR valid"
+      ifThen(!isExpired, isValid);
+    expect(checkExpiredLogic(false, true)).toBe(true); // not expired and valid
+    expect(checkExpiredLogic(false, false)).toBe(false); // not expired but invalid
+    expect(checkExpiredLogic(true, true)).toBe(true); // expired but valid (vacuous)
+    expect(checkExpiredLogic(true, false)).toBe(true); // expired and invalid (vacuous)
+  });
+});

package/src/others/index.mts

@@ -0,0 +1,7 @@
+export * from './cast-mutable.mjs';
+export * from './cast-readonly.mjs';
+export * from './if-then.mjs';
+export * from './map-nullable.mjs';
+export * from './memoize-function.mjs';
+export * from './tuple.mjs';
+export * from './unknown-to-string.mjs';

package/src/others/map-nullable.mts

@@ -0,0 +1,172 @@
+/**
+ * Applies a function to a value if the value is not `null` or `undefined`.
+ * If the value is `null` or `undefined`, it returns `undefined`.
+ *
+ * This function provides a safe way to transform nullable values without explicit null checks.
+ * It's similar to Optional.map() but works directly with TypeScript's nullable types.
+ * Supports both regular and curried usage for functional composition.
+ *
+ * @template A - The type of the input value (excluding null/undefined)
+ * @template B - The type of the value returned by the mapping function
+ * @param value - The value to potentially transform (can be `A`, `null`, or `undefined`)
+ * @param mapFn - A function that transforms a non-nullable value of type `A` to type `B`
+ * @returns The result of applying `mapFn` to `value` if value is not null/undefined; otherwise `undefined`
+ *
+ * @example Basic usage with nullable values
+ * ```typescript
+ * // Safe string transformation
+ * mapNullable("hello", s => s.toUpperCase()); // "HELLO"
+ * mapNullable(null, s => s.toUpperCase()); // undefined
+ * mapNullable(undefined, s => s.toUpperCase()); // undefined
+ *
+ * // Number operations
+ * mapNullable(5, n => n * 2); // 10
+ * mapNullable(0, n => n * 2); // 0 (note: 0 is not null/undefined)
+ * mapNullable(null as number | null, n => n * 2); // undefined
+ * ```
+ *
+ * @example Working with optional object properties
+ * ```typescript
+ * interface User {
+ *   id: number;
+ *   name?: string;
+ *   email?: string;
+ * }
+ *
+ * function formatUserDisplay(user: User): string {
+ *   const displayName = mapNullable(user.name, name => name.toUpperCase()) ?? 'Anonymous';
+ *   const emailDomain = mapNullable(user.email, email => email.split('@')[1]);
+ *
+ *   return `${displayName} ${emailDomain ? `(${emailDomain})` : ''}`;
+ * }
+ *
+ * formatUserDisplay({ id: 1, name: 'John', email: 'john@example.com' }); // "JOHN (example.com)"
+ * formatUserDisplay({ id: 2 }); // "Anonymous "
+ * ```
+ *
+ * @example Curried usage for functional composition
+ * ```typescript
+ * // Create reusable transformers
+ * const toUpperCase = mapNullable((s: string) => s.toUpperCase());
+ * const addPrefix = mapNullable((s: string) => `PREFIX_${s}`);
+ * const parseNumber = mapNullable((s: string) => parseInt(s, 10));
+ *
+ * // Use in different contexts
+ * toUpperCase("hello"); // "HELLO"
+ * toUpperCase(null); // undefined
+ *
+ * // Compose transformations
+ * const processString = (s: string | null) => {
+ *   const upper = toUpperCase(s);
+ *   return addPrefix(upper);
+ * };
+ *
+ * processString("test"); // "PREFIX_TEST"
+ * processString(null); // undefined
+ * ```
+ *
+ * @example Chaining nullable operations
+ * ```typescript
+ * // API response handling
+ * interface ApiResponse {
+ *   data?: {
+ *     user?: {
+ *       profile?: {
+ *         displayName?: string;
+ *       };
+ *     };
+ *   };
+ * }
+ *
+ * function getDisplayName(response: ApiResponse): string | undefined {
+ *   return mapNullable(
+ *     response.data?.user?.profile?.displayName,
+ *     name => name.trim().toUpperCase()
+ *   );
+ * }
+ *
+ * // Chain multiple transformations
+ * function processNullableChain(value: string | null): string | undefined {
+ *   const step1 = mapNullable(value, v => v.trim());
+ *   const step2 = mapNullable(step1, v => v.length > 0 ? v : null);
+ *   const step3 = mapNullable(step2, v => v.toUpperCase());
+ *   return step3;
+ * }
+ * ```
+ *
+ * @example Integration with array methods
+ * ```typescript
+ * const nullableNumbers: (number | null | undefined)[] = [1, null, 3, undefined, 5];
+ *
+ * // Transform and filter in one step
+ * const doubled = nullableNumbers
+ *   .map(n => mapNullable(n, x => x * 2))
+ *   .filter((n): n is number => n !== undefined);
+ * // Result: [2, 6, 10]
+ *
+ * // Process optional array elements
+ * const users: Array<{ name?: string }> = [
+ *   { name: 'Alice' },
+ *   { name: undefined },
+ *   { name: 'Bob' }
+ * ];
+ *
+ * const upperNames = users
+ *   .map(u => mapNullable(u.name, n => n.toUpperCase()))
+ *   .filter((n): n is string => n !== undefined);
+ * // Result: ['ALICE', 'BOB']
+ * ```
+ *
+ * @example Error handling patterns
+ * ```typescript
+ * // Safe JSON parsing
+ * function parseJsonSafe<T>(json: string | null): T | undefined {
+ *   return mapNullable(json, j => {
+ *     try {
+ *       return JSON.parse(j) as T;
+ *     } catch {
+ *       return null;
+ *     }
+ *   }) ?? undefined;
+ * }
+ *
+ * // Safe property access with computation
+ * function calculateAge(birthYear: number | null): string | undefined {
+ *   return mapNullable(birthYear, year => {
+ *     const age = new Date().getFullYear() - year;
+ *     return age >= 0 ? `${age} years old` : null;
+ *   }) ?? undefined;
+ * }
+ * ```
+ *
+ * @see Optional - For more complex optional value handling
+ * @see Result - For error handling with detailed error information
+ */
+export const mapNullable: MapNullableFnOverload = (<const A, const B>(
+  ...args:
+    | readonly [value: A | null | undefined, mapFn: (v: A) => B]
+    | readonly [mapFn: (v: A) => B]
+): (B | undefined) | ((value: A | null | undefined) => B | undefined) => {
+  switch (args.length) {
+    case 2: {
+      const [value, mapFn] = args;
+      return value == null ? undefined : mapFn(value);
+    }
+    case 1: {
+      const [mapFn] = args;
+      return (value: A | null | undefined) => mapNullable(value, mapFn);
+    }
+  }
+}) as MapNullableFnOverload;
+
+type MapNullableFnOverload = {
+  <const A, const B>(
+    value: A | null | undefined,
+    mapFn: (v: A) => B,
+  ): B | undefined;
+
+  // Curried version
+  <const A, const B>(
+    mapFn: (v: A) => B,
+  ): (value: A | null | undefined) => B | undefined;
+};