ts-data-forge 5.0.0 → 5.1.0

package/src/guard/is-type.test.mts

@@ -25,14 +25,19 @@ describe(isUndefined, () => {
 
   test('should return false for non-undefined values', () => {
     expect(isUndefined(null)).toBe(false);
+
     expect(isUndefined(0)).toBe(false);
+
     expect(isUndefined('')).toBe(false);
+
     expect(isUndefined(false)).toBe(false);
+
     expect(isUndefined({})).toBe(false);
   });
 
   test('should act as a type guard', () => {
     const value: string | undefined = undefined;
+
     if (isUndefined(value)) {
       expectType<typeof value, undefined>('=');
     }
@@ -46,13 +51,17 @@ describe(isNotUndefined, () => {
 
   test('should return true for non-undefined values', () => {
     expect(isNotUndefined(null)).toBe(true);
+
     expect(isNotUndefined(0)).toBe(true);
+
     expect(isNotUndefined('')).toBe(true);
+
     expect(isNotUndefined(false)).toBe(true);
   });
 
   test('should narrow types correctly', () => {
     const value: string | undefined = 'test';
+
     if (isNotUndefined(value)) {
       expectType<typeof value, string>('=');
     }
@@ -66,14 +75,19 @@ describe(isNull, () => {
 
   test('should return false for non-null values', () => {
     expect(isNull(undefined)).toBe(false);
+
     expect(isNull(0)).toBe(false);
+
     expect(isNull('')).toBe(false);
+
     expect(isNull(false)).toBe(false);
+
     expect(isNull({})).toBe(false);
   });
 
   test('should act as a type guard', () => {
     const value: string | null = null;
+
     if (isNull(value)) {
       expectType<typeof value, null>('=');
     }
@@ -87,12 +101,15 @@ describe(isNotNull, () => {
 
   test('should return true for non-null values', () => {
     expect(isNotNull(undefined)).toBe(true);
+
     expect(isNotNull(0)).toBe(true);
+
     expect(isNotNull('')).toBe(true);
   });
 
   test('should narrow types correctly', () => {
     const value: string | null = 'test';
+
     if (isNotNull(value)) {
       expectType<typeof value, string>('=');
     }
@@ -102,22 +119,30 @@ describe(isNotNull, () => {
 describe(isString, () => {
   test('should return true for strings', () => {
     expect(isString('')).toBe(true);
+
     expect(isString('hello')).toBe(true);
+
     expect(isString('123')).toBe(true);
+
     expect(isString(`template`)).toBe(true);
   });
 
   test('should return false for non-strings', () => {
     expect(isString(123)).toBe(false);
+
     expect(isString(true)).toBe(false);
+
     expect(isString(null)).toBe(false);
+
     expect(isString(undefined)).toBe(false);
+
     // eslint-disable-next-line unicorn/new-for-builtins
     expect(isString(new String('hello'))).toBe(false);
   });
 
   test('should act as a type guard', () => {
     const value: unknown = 'test';
+
     if (isString(value)) {
       expectType<typeof value, string>('=');
 
@@ -129,24 +154,34 @@ describe(isString, () => {
 describe(isNumber, () => {
   test('should return true for numbers', () => {
     expect(isNumber(0)).toBe(true);
+
     expect(isNumber(42)).toBe(true);
+
     expect(isNumber(-3.14)).toBe(true);
+
     expect(isNumber(Number.NaN)).toBe(true);
+
     expect(isNumber(Number.POSITIVE_INFINITY)).toBe(true);
+
     expect(isNumber(Number.NEGATIVE_INFINITY)).toBe(true);
   });
 
   test('should return false for non-numbers', () => {
     expect(isNumber('123')).toBe(false);
+
     expect(isNumber(true)).toBe(false);
+
     expect(isNumber(null)).toBe(false);
+
     expect(isNumber(123n)).toBe(false);
+
     // eslint-disable-next-line unicorn/new-for-builtins
     expect(isNumber(new Number(42))).toBe(false);
   });
 
   test('should act as a type guard', () => {
     const value: unknown = 42;
+
     if (isNumber(value)) {
       expectType<typeof value, number>('=');
 
@@ -158,19 +193,25 @@ describe(isNumber, () => {
 describe(isBigint, () => {
   test('should return true for bigints', () => {
     expect(isBigint(0n)).toBe(true);
+
     expect(isBigint(123n)).toBe(true);
+
     expect(isBigint(-456n)).toBe(true);
   });
 
   test('should return false for non-bigints', () => {
     expect(isBigint(123)).toBe(false);
+
     expect(isBigint('123')).toBe(false);
+
     expect(isBigint(true)).toBe(false);
+
     expect(isBigint(null)).toBe(false);
   });
 
   test('should act as a type guard', () => {
     const value: unknown = 123n;
+
     if (isBigint(value)) {
       expectType<typeof value, bigint>('=');
 
@@ -182,20 +223,26 @@ describe(isBigint, () => {
 describe(isBoolean, () => {
   test('should return true for booleans', () => {
     expect(isBoolean(true)).toBe(true);
+
     expect(isBoolean(false)).toBe(true);
   });
 
   test('should return false for non-booleans', () => {
     expect(isBoolean(1)).toBe(false);
+
     expect(isBoolean(0)).toBe(false);
+
     expect(isBoolean('true')).toBe(false);
+
     expect(isBoolean(null)).toBe(false);
+
     // eslint-disable-next-line unicorn/new-for-builtins
     expect(isBoolean(new Boolean(true))).toBe(false);
   });
 
   test('should act as a type guard', () => {
     const value: unknown = true;
+
     if (isBoolean(value)) {
       expectType<typeof value, boolean>('=');
 
@@ -207,18 +254,23 @@ describe(isBoolean, () => {
 describe(isSymbol, () => {
   test('should return true for symbols', () => {
     expect(isSymbol(Symbol())).toBe(true);
+
     expect(isSymbol(Symbol('test'))).toBe(true);
+
     expect(isSymbol(Symbol.iterator)).toBe(true);
   });
 
   test('should return false for non-symbols', () => {
     expect(isSymbol('symbol')).toBe(false);
+
     expect(isSymbol(123)).toBe(false);
+
     expect(isSymbol(null)).toBe(false);
   });
 
   test('should act as a type guard', () => {
     const value: unknown = Symbol('test');
+
     if (isSymbol(value)) {
       expectType<typeof value, symbol>('=');
 
@@ -230,22 +282,31 @@ describe(isSymbol, () => {
 describe(isNotBoolean, () => {
   test('should return false for boolean values', () => {
     expect(isNotBoolean(true)).toBe(false);
+
     expect(isNotBoolean(false)).toBe(false);
   });
 
   test('should return true for non-boolean values', () => {
     expect(isNotBoolean(0)).toBe(true);
+
     expect(isNotBoolean(1)).toBe(true);
+
     expect(isNotBoolean('true')).toBe(true);
+
     expect(isNotBoolean('false')).toBe(true);
+
     expect(isNotBoolean(null)).toBe(true);
+
     expect(isNotBoolean(undefined)).toBe(true);
+
     expect(isNotBoolean({})).toBe(true);
+
     expect(isNotBoolean([])).toBe(true);
   });
 
   test('should act as a type guard', () => {
     const value: string | number | boolean = 'test';
+
     if (isNotBoolean(value)) {
       expectType<typeof value, string | number>('<=');
 
@@ -258,27 +319,41 @@ describe(isNotBoolean, () => {
 describe(isNotNumber, () => {
   test('should return false for number values', () => {
     expect(isNotNumber(0)).toBe(false);
+
     expect(isNotNumber(42)).toBe(false);
+
     expect(isNotNumber(-3.14)).toBe(false);
+
     expect(isNotNumber(Number.NaN)).toBe(false);
+
     expect(isNotNumber(Number.POSITIVE_INFINITY)).toBe(false);
+
     expect(isNotNumber(Number.NEGATIVE_INFINITY)).toBe(false);
   });
 
   test('should return true for non-number values', () => {
     expect(isNotNumber('123')).toBe(true);
+
     expect(isNotNumber(true)).toBe(true);
+
     expect(isNotNumber(false)).toBe(true);
+
     expect(isNotNumber(null)).toBe(true);
+
     expect(isNotNumber(undefined)).toBe(true);
+
     expect(isNotNumber(123n)).toBe(true);
+
     expect(isNotNumber({})).toBe(true);
+
     expect(isNotNumber([])).toBe(true);
+
     expect(isNotNumber(Symbol('test'))).toBe(true);
   });
 
   test('should act as a type guard', () => {
     const value: string | number | boolean = 'test';
+
     if (isNotNumber(value)) {
       expectType<typeof value, string | boolean>('<=');
 
@@ -292,23 +367,33 @@ describe(isNotNumber, () => {
 describe(isNotBigint, () => {
   test('should return false for bigint values', () => {
     expect(isNotBigint(0n)).toBe(false);
+
     expect(isNotBigint(123n)).toBe(false);
+
     expect(isNotBigint(-456n)).toBe(false);
   });
 
   test('should return true for non-bigint values', () => {
     expect(isNotBigint(123)).toBe(true);
+
     expect(isNotBigint('123')).toBe(true);
+
     expect(isNotBigint(true)).toBe(true);
+
     expect(isNotBigint(false)).toBe(true);
+
     expect(isNotBigint(null)).toBe(true);
+
     expect(isNotBigint(undefined)).toBe(true);
+
     expect(isNotBigint({})).toBe(true);
+
     expect(isNotBigint(Symbol('test'))).toBe(true);
   });
 
   test('should act as a type guard', () => {
     const value: number | bigint = 123;
+
     if (isNotBigint(value)) {
       expectType<typeof value, number>('<=');
 
@@ -320,25 +405,37 @@ describe(isNotBigint, () => {
 describe(isNotString, () => {
   test('should return false for string values', () => {
     expect(isNotString('')).toBe(false);
+
     expect(isNotString('hello')).toBe(false);
+
     expect(isNotString('123')).toBe(false);
+
     expect(isNotString(`template`)).toBe(false);
   });
 
   test('should return true for non-string values', () => {
     expect(isNotString(123)).toBe(true);
+
     expect(isNotString(true)).toBe(true);
+
     expect(isNotString(false)).toBe(true);
+
     expect(isNotString(null)).toBe(true);
+
     expect(isNotString(undefined)).toBe(true);
+
     expect(isNotString({})).toBe(true);
+
     expect(isNotString([])).toBe(true);
+
     expect(isNotString(Symbol('test'))).toBe(true);
+
     expect(isNotString(123n)).toBe(true);
   });
 
   test('should act as a type guard', () => {
     const value: string | number | boolean = 42;
+
     if (isNotString(value)) {
       expectType<typeof value, number | boolean>('<=');
 
@@ -352,24 +449,35 @@ describe(isNotString, () => {
 describe(isNotSymbol, () => {
   test('should return false for symbol values', () => {
     expect(isNotSymbol(Symbol())).toBe(false);
+
     expect(isNotSymbol(Symbol('test'))).toBe(false);
+
     expect(isNotSymbol(Symbol.iterator)).toBe(false);
   });
 
   test('should return true for non-symbol values', () => {
     expect(isNotSymbol('symbol')).toBe(true);
+
     expect(isNotSymbol(123)).toBe(true);
+
     expect(isNotSymbol(true)).toBe(true);
+
     expect(isNotSymbol(false)).toBe(true);
+
     expect(isNotSymbol(null)).toBe(true);
+
     expect(isNotSymbol(undefined)).toBe(true);
+
     expect(isNotSymbol({})).toBe(true);
+
     expect(isNotSymbol([])).toBe(true);
+
     expect(isNotSymbol(123n)).toBe(true);
   });
 
   test('should act as a type guard', () => {
     const value: string | number | symbol = 'test';
+
     if (isNotSymbol(value)) {
       expectType<typeof value, string | number>('<=');
 
@@ -381,22 +489,31 @@ describe(isNotSymbol, () => {
 describe(isNullish, () => {
   test('should return true for null and undefined', () => {
     expect(isNullish(null)).toBe(true);
+
     expect(isNullish(undefined)).toBe(true);
   });
 
   test('should return false for non-nullish values', () => {
     expect(isNullish(0)).toBe(false);
+
     expect(isNullish(false)).toBe(false);
+
     expect(isNullish('')).toBe(false);
+
     expect(isNullish('null')).toBe(false);
+
     expect(isNullish('undefined')).toBe(false);
+
     expect(isNullish({})).toBe(false);
+
     expect(isNullish([])).toBe(false);
+
     expect(isNullish(Number.NaN)).toBe(false);
   });
 
   test('should act as a type guard', () => {
     const value: string | null | undefined = null;
+
     if (isNullish(value)) {
       expectType<typeof value, null | undefined>('<=');
 
@@ -408,6 +525,7 @@ describe(isNullish, () => {
   test('should handle edge cases', () => {
     // Test that it uses loose equality (==)
     expect(isNullish(null)).toBe(true);
+
     expect(isNullish(undefined)).toBe(true);
   });
 });
@@ -415,24 +533,35 @@ describe(isNullish, () => {
 describe(isNonNullish, () => {
   test('should return false for null and undefined', () => {
     expect(isNonNullish(null)).toBe(false);
+
     expect(isNonNullish(undefined)).toBe(false);
   });
 
   test('should return true for non-nullish values', () => {
     expect(isNonNullish(0)).toBe(true);
+
     expect(isNonNullish(false)).toBe(true);
+
     expect(isNonNullish('')).toBe(true);
+
     expect(isNonNullish('null')).toBe(true);
+
     expect(isNonNullish('undefined')).toBe(true);
+
     expect(isNonNullish({})).toBe(true);
+
     expect(isNonNullish([])).toBe(true);
+
     expect(isNonNullish(Number.NaN)).toBe(true);
+
     expect(isNonNullish(Symbol('test'))).toBe(true);
+
     expect(isNonNullish(123n)).toBe(true);
   });
 
   test('should act as a type guard', () => {
     const value: string | null | undefined = 'test';
+
     if (isNonNullish(value)) {
       expectType<typeof value, string>('<=');
 
@@ -450,6 +579,7 @@ describe(isNonNullish, () => {
     ];
 
     const definedItems = items.filter(isNonNullish);
+
     expectType<typeof definedItems, string[]>('<=');
 
     expect(definedItems).toHaveLength(3);
@@ -459,6 +589,7 @@ describe(isNonNullish, () => {
 
   test('should handle complex union types', () => {
     type ComplexType = string | number | boolean | null | undefined;
+
     const value: ComplexType = 42;
 
     if (isNonNullish(value)) {
@@ -494,12 +625,15 @@ describe('type guard behavior in complex scenarios', () => {
     ];
 
     const nonNullish = mixed.filter(isNonNullish);
+
     expectType<typeof nonNullish, (string | number | boolean)[]>('<=');
 
     const nonBooleans = nonNullish.filter(isNotBoolean);
+
     expectType<typeof nonBooleans, (string | number)[]>('<=');
 
     const strings = nonBooleans.filter(isNotNumber);
+
     expectType<typeof strings, string[]>('<=');
 
     assert.deepStrictEqual(strings, ['hello', 'world']);

package/src/guard/key-is-in.mts

@@ -19,6 +19,7 @@
  *
  * ```ts
  * const user = { id: 1, name: 'Ada' } as const;
+ *
  * const maybeKey: string = 'name';
  *
  * if (keyIsIn(maybeKey, user)) {

package/src/iterator/range.mts

@@ -40,11 +40,15 @@ import { SafeInt, asSafeInt } from '../number/index.mjs';
  *
  * ```ts
  * const zeroToThree = Array.from(range(0, 3));
+ *
  * const threeToZero = Array.from(range(3, 0, -1));
+ *
  * const defaultEnd = Array.from(range(4));
  *
  * assert.deepStrictEqual(zeroToThree, [0, 1, 2]);
+ *
  * assert.deepStrictEqual(threeToZero, [3, 2, 1]);
+ *
  * assert.deepStrictEqual(defaultEnd, [0, 1, 2, 3]);
  * ```
  *
@@ -86,15 +90,20 @@ export function* range(
   switch (args.length) {
     case 1: {
       const [end] = args;
+
       for (const i of range(0, end, 1)) {
         yield i;
       }
+
       break;
     }
 
     case 2:
+
+    // falls through
     case 3: {
       const [start, end, step = 1] = args;
+
       for (
         let mut_i: SafeInt = asSafeInt(start);
         step > 0 ? mut_i < end : mut_i > end;

package/src/json/json.mts

@@ -21,12 +21,15 @@ export namespace Json {
    *
    * ```ts
    * const validJson = '{"name": "Alice", "age": 30}';
+   *
    * const invalidJson = '{invalid json}';
    *
    * const parsed = Json.parse(validJson);
+   *
    * const failed = Json.parse(invalidJson);
    *
    * assert.ok(Result.isOk(parsed));
+   *
    * if (Result.isOk(parsed)) {
    *   assert.deepStrictEqual(parsed.value, { name: 'Alice', age: 30 });
    * }
@@ -35,10 +38,12 @@ export namespace Json {
    *
    * // With reviver
    * const jsonWithDate = '{"created": "2024-01-01T00:00:00.000Z"}';
+   *
    * const withReviver = Json.parse(jsonWithDate, (key, value) => {
    *   if (key === 'created' && typeof value === 'string') {
    *     return new Date(value);
    *   }
+   *
    *   return value;
    * });
    *
@@ -71,6 +76,7 @@ export namespace Json {
       );
     } catch (error: unknown) {
       const errStr = unknownToString(error);
+
       return Result.err(errStr);
     }
   };
@@ -91,22 +97,27 @@ export namespace Json {
    *
    * // Basic stringify
    * const basic = Json.stringify(data);
+   *
    * assert.ok(Result.isOk(basic));
+   *
    * if (Result.isOk(basic)) {
    *   assert(basic.value === '{"name":"Bob","age":25,"active":true}');
    * }
    *
    * // With formatting
    * const formatted = Json.stringify(data, undefined, 2);
+   *
    * assert.ok(Result.isOk(formatted));
    *
    * // With replacer
    * const filtered = Json.stringify(data, (key, value) => {
    *   if (key === 'age') return undefined; // omit age field
+   *
    *   return value;
    * });
    *
    * assert.ok(Result.isOk(filtered));
+   *
    * if (Result.isOk(filtered)) {
    *   assert(isString(filtered.value));
    *
@@ -143,6 +154,7 @@ export namespace Json {
       return Result.ok(JSON.stringify(value, replacer, space));
     } catch (error) {
       const errStr = unknownToString(error);
+
       return Result.err(errStr);
     }
   };
@@ -171,21 +183,26 @@ export namespace Json {
    * const safeJson = Json.stringifySelected(user, ['id', 'name', 'role']);
    *
    * assert.ok(Result.isOk(safeJson));
+   *
    * if (Result.isOk(safeJson)) {
    *   assert(isString(safeJson.value));
    *
    *   const parsed: unknown = JSON.parse(safeJson.value);
+   *
    *   assert.deepStrictEqual(parsed, {
    *     id: 1,
    *     name: 'Charlie',
    *     role: 'admin',
    *   });
+   *
    *   assert.ok(!safeJson.value.includes('password'));
+   *
    *   assert.ok(!safeJson.value.includes('email'));
    * }
    *
    * // With formatting
    * const formatted = Json.stringifySelected(user, ['id', 'name'], 2);
+   *
    * assert.ok(Result.isOk(formatted));
    * ```
    *
@@ -218,6 +235,7 @@ export namespace Json {
       );
     } catch (error) {
       const errStr = unknownToString(error);
+
       return Result.err(errStr);
     }
   };
@@ -250,16 +268,20 @@ export namespace Json {
    * const sorted = Json.stringifySortedKey(unorderedData);
    *
    * assert.ok(Result.isOk(sorted));
+   *
    * if (Result.isOk(sorted)) {
    *   // Keys should appear in alphabetical order
    *   const expected =
    *     '{"apple":2,"mango":3,"nested":{"alpha":"a","beta":"b","zulu":"z"},"zebra":1}';
+   *
    *   assert(sorted.value === expected);
    * }
    *
    * // With formatting
    * const formatted = Json.stringifySortedKey(unorderedData, 2);
+   *
    * assert.ok(Result.isOk(formatted));
+   *
    * if (Result.isOk(formatted)) {
    *   assert(isString(formatted.value));
    *
@@ -267,9 +289,11 @@ export namespace Json {
    *   assert.ok(
    *     formatted.value.indexOf('"apple"') < formatted.value.indexOf('"mango"'),
    *   );
+   *
    *   assert.ok(
    *     formatted.value.indexOf('"mango"') < formatted.value.indexOf('"nested"'),
    *   );
+   *
    *   assert.ok(
    *     formatted.value.indexOf('"nested"') < formatted.value.indexOf('"zebra"'),
    *   );
@@ -321,10 +345,13 @@ const keysDeepImpl = (
 ): void => {
   for (const k of Object.keys(obj)) {
     mut_keys.push(k);
+
     const o = obj[k];
+
     if (isRecord(o)) {
       keysDeepImpl(o, mut_keys);
     }
+
     if (Array.isArray(o)) {
       for (const li of o) {
         if (isRecord(li)) {
@@ -349,6 +376,8 @@ const keysDeepImpl = (
  */
 const keysDeep = (obj: UnknownRecord): readonly string[] => {
   const mut_keys: string[] = [];
+
   keysDeepImpl(obj, mut_keys);
+
   return mut_keys;
 };