ts-data-forge 5.0.0 → 5.1.0

package/src/object/object.mts

@@ -17,20 +17,25 @@ export namespace Obj {
    *
    * ```ts
    * const obj1 = { name: 'Alice', age: 30 };
+   *
    * const obj2 = { name: 'Alice', age: 30 };
+   *
    * const obj3 = { name: 'Alice', age: 31 };
    *
    * assert.ok(Obj.shallowEq(obj1, obj2));
+   *
    * assert.notOk(Obj.shallowEq(obj1, obj3));
    *
    * // Custom equality function
    * const obj4 = { value: 1 };
+   *
    * const obj5 = { value: 1.00001 };
    *
    * const closeEnough = (a: unknown, b: unknown): boolean => {
    *   if (typeof a === 'number' && typeof b === 'number') {
    *     return Math.abs(a - b) < 0.001;
    *   }
+   *
    *   return Object.is(a, b);
    * };
    *
@@ -50,6 +55,7 @@ export namespace Obj {
     eq: (x: unknown, y: unknown) => boolean = Object.is,
   ): boolean => {
     const aEntries = Object.entries(a);
+
     const bEntries = Object.entries(b);
 
     if (aEntries.length !== bEntries.length) return false;
@@ -78,6 +84,7 @@ export namespace Obj {
    *
    * // Direct usage
    * const publicInfo = Obj.pick(user, ['id', 'name', 'role']);
+   *
    * assert.deepStrictEqual(publicInfo, {
    *   id: 1,
    *   name: 'Bob',
@@ -122,6 +129,7 @@ export namespace Obj {
     switch (args.length) {
       case 2: {
         const [record, keys] = args;
+
         const keysSet = new Set<keyof R>(keys);
 
         return (
@@ -134,6 +142,7 @@ export namespace Obj {
 
       case 1: {
         const [keys] = args;
+
         return (record: R) => pick(record, keys);
       }
     }
@@ -161,6 +170,7 @@ export namespace Obj {
    *
    * // Direct usage - remove sensitive fields
    * const safeUser = Obj.omit(user, ['password', 'internalNote']);
+   *
    * assert.deepStrictEqual(safeUser, {
    *   id: 1,
    *   name: 'Charlie',
@@ -206,6 +216,7 @@ export namespace Obj {
     switch (args.length) {
       case 2: {
         const [record, keys] = args;
+
         const keysSet = new Set<keyof R>(keys);
 
         return (
@@ -218,12 +229,14 @@ export namespace Obj {
 
       case 1: {
         const [keys] = args;
+
         return <R2 extends UnknownRecord>(record: R2) => {
           // eslint-disable-next-line total-functions/no-unsafe-type-assertion
           const result = omit(record, keys as readonly (keyof R2)[]) as Omit<
             R2,
             ArrayElement<Keys>
           >;
+
           return result;
         };
       }
@@ -253,6 +266,7 @@ export namespace Obj {
    * ] as const;
    *
    * const obj1 = Obj.fromEntries(entries1);
+   *
    * assert.deepStrictEqual(obj1, {
    *   name: 'David',
    *   age: 25,
@@ -266,6 +280,7 @@ export namespace Obj {
    * ];
    *
    * const obj2 = Obj.fromEntries(dynamicEntries);
+   *
    * assert.deepStrictEqual(obj2, { x: 10, y: 20 });
    * ```
    *

package/src/object/object.test.mts

@@ -38,6 +38,7 @@ describe('pick', () => {
 
   test('pick should support curried form', () => {
     const pickAB = Obj.pick(['a', 'b']);
+
     const result = pickAB({ a: 1, b: 2, c: 3, d: 4 });
 
     assert.deepStrictEqual(result, { a: 1, b: 2 });
@@ -45,6 +46,7 @@ describe('pick', () => {
 
   test('pick should work with pipe when curried', () => {
     const pickIdAndName = Obj.pick(['id', 'name']);
+
     const user = { id: 1, name: 'Alice', email: 'alice@example.com', age: 30 };
 
     const result = pipe(user).map(pickIdAndName).value;
@@ -54,6 +56,7 @@ describe('pick', () => {
 
   test('pick should handle empty keys in curried form', () => {
     const pickNone = Obj.pick([]);
+
     const result = pickNone({ a: 1, b: 2 });
 
     assert.deepStrictEqual(result, {});
@@ -61,6 +64,7 @@ describe('pick', () => {
 
   test('pick should work for records that only partially contain the key in curried form', () => {
     const pickVisible = Obj.pick(['name', 'age']);
+
     const user = {
       id: 1,
       name: 'Alice',
@@ -85,6 +89,7 @@ describe('omit', () => {
 
   test('omit should support curried form', () => {
     const omitC = Obj.omit(['c']);
+
     const result = omitC({ a: 1, b: 2, c: 3, d: 4 });
 
     assert.deepStrictEqual(result, { a: 1, b: 2, d: 4 });
@@ -92,6 +97,7 @@ describe('omit', () => {
 
   test('omit should work with pipe when curried', () => {
     const omitSensitive = Obj.omit(['password', 'email']);
+
     const user = {
       id: 1,
       name: 'Alice',
@@ -106,7 +112,9 @@ describe('omit', () => {
 
   test('omit should handle empty keys in curried form', () => {
     const omitNone = Obj.omit([]);
+
     const original = { a: 1, b: 2, c: 3 };
+
     const result = omitNone(original);
 
     assert.deepStrictEqual(result, original);
@@ -114,6 +122,7 @@ describe('omit', () => {
 
   test('should omit multiple keys in curried form', () => {
     const omitBAndD = Obj.omit(['b', 'd']);
+
     const result = omitBAndD({ a: 1, b: 2, c: 3, d: 4, e: 5 });
 
     assert.deepStrictEqual(result, { a: 1, c: 3, e: 5 });
@@ -121,6 +130,7 @@ describe('omit', () => {
 
   test('omit should work for records that only partially contain the key in curried form', () => {
     const omitSensitive = Obj.omit(['password', 'email']);
+
     const user = {
       id: 1,
       name: 'Alice',

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

@@ -4,6 +4,7 @@ import { castDeepMutable, castMutable } from './cast-mutable.mjs';
 describe(castMutable, () => {
   test('should allow mutating arrays that were readonly', () => {
     const readonlyArray: readonly number[] = [1, 2, 3];
+
     const mut_array = castMutable(readonlyArray);
 
     expectType<typeof mut_array, number[]>('=');
@@ -11,6 +12,7 @@ describe(castMutable, () => {
     mut_array.push(4);
 
     assert.deepStrictEqual(mut_array, [1, 2, 3, 4]);
+
     assert.deepStrictEqual(readonlyArray, [1, 2, 3, 4]);
   });
 
@@ -21,12 +23,15 @@ describe(castMutable, () => {
     };
 
     const mut_user = castMutable(readonlyUser);
+
     expectType<typeof mut_user, { name: string; age: number }>('=');
 
     mut_user.age = 31;
+
     mut_user.name = 'Bob';
 
     assert.deepStrictEqual(mut_user, { name: 'Bob', age: 31 });
+
     assert.deepStrictEqual(readonlyUser, { name: 'Bob', age: 31 });
   });
 });
@@ -65,12 +70,14 @@ describe(castDeepMutable, () => {
     expectType<typeof mut_state, MutableState>('~=');
 
     mut_state.user.profile.tags.push('editor');
+
     mut_state.user.profile.name = 'Bob';
 
     assert.deepStrictEqual(mut_state.user.profile, {
       name: 'Bob',
       tags: ['admin', 'owner', 'editor'],
     });
+
     assert.deepStrictEqual(readonlyState.user.profile.tags, [
       'admin',
       'owner',

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

@@ -3,6 +3,7 @@ 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
@@ -12,6 +13,7 @@ describe(castReadonly, () => {
 
   test('should cast mutable object to readonly', () => {
     const mutableObj = { x: 1, y: 2 };
+
     const readonlyObj = castReadonly(mutableObj);
 
     expect(readonlyObj).toBe(mutableObj); // Same reference
@@ -21,20 +23,25 @@ describe(castReadonly, () => {
 
   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('castReadonly should work with primitives', () => {
     expect(castReadonly(42)).toBe(42);
+
     expect(castReadonly('hello')).toBe('hello');
+
     expect(castReadonly(true)).toBe(true);
   });
 
   test('castReadonly should work with null and undefined', () => {
     expect(castReadonly(null)).toBeNull();
+
     // eslint-disable-next-line @typescript-eslint/no-confusing-void-expression
     expect(castReadonly(undefined)).toBeUndefined();
   });
@@ -46,6 +53,7 @@ describe(castDeepReadonly, () => {
       a: { b: [1, 2, 3] },
       c: { d: { e: 'value' } },
     };
+
     const readonlyNested = castDeepReadonly(mutableNested);
 
     expect(readonlyNested).toBe(mutableNested); // Same reference
@@ -60,10 +68,13 @@ describe(castDeepReadonly, () => {
       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);
   });
 
@@ -72,21 +83,27 @@ describe(castDeepReadonly, () => {
       { 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('castDeepReadonly should work with primitives', () => {
     expect(castDeepReadonly(42)).toBe(42);
+
     expect(castDeepReadonly('hello')).toBe('hello');
+
     expect(castDeepReadonly(true)).toBe(true);
   });
 
   test('castDeepReadonly should work with null and undefined', () => {
     expect(castDeepReadonly(null)).toBeNull();
+
     // eslint-disable-next-line @typescript-eslint/no-confusing-void-expression
     expect(castDeepReadonly(undefined)).toBeUndefined();
   });

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

@@ -18,12 +18,16 @@ describe(ifThen, () => {
   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
   });
 
@@ -36,8 +40,11 @@ describe(ifThen, () => {
       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
   });
 
@@ -50,8 +57,11 @@ describe(ifThen, () => {
       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
   });
 
@@ -60,8 +70,11 @@ describe(ifThen, () => {
       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
   });
 
@@ -71,8 +84,11 @@ describe(ifThen, () => {
       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/map-nullable.mts

@@ -36,10 +36,13 @@ export function mapNullable<const A, const B>(
   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);
     }
   }

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

@@ -38,6 +38,7 @@ describe(mapNullable, () => {
 
     test('should work with complex transformations', () => {
       const user = { name: 'Alice', age: 30 };
+
       const result = mapNullable(
         user,
         (u) => `${u.name} is ${u.age} years old`,
@@ -48,11 +49,13 @@ describe(mapNullable, () => {
 
     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(),
       );
@@ -100,6 +103,7 @@ describe(mapNullable, () => {
       );
 
       const user = { name: 'Charlie', age: 25 };
+
       const result1 = getName(user);
 
       expect(result1).toBe('Charlie');
@@ -111,6 +115,7 @@ describe(mapNullable, () => {
 
     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;
@@ -120,6 +125,7 @@ describe(mapNullable, () => {
 
     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)
@@ -131,7 +137,9 @@ describe(mapNullable, () => {
 
     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)
@@ -206,7 +214,9 @@ describe(mapNullable, () => {
       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
@@ -216,25 +226,33 @@ describe(mapNullable, () => {
       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();
@@ -264,9 +282,11 @@ describe(mapNullable, () => {
       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');
@@ -284,15 +304,19 @@ describe(mapNullable, () => {
       };
 
       const extractAge = mapNullable((data: FormDataType) => 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);
@@ -310,14 +334,17 @@ describe(mapNullable, () => {
       };
 
       const extractAge = mapNullable((data: FormDataType) => 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();
     });
   });