ts-data-forge 5.0.0 → 5.1.0

package/src/globals.d.mts

@@ -23,27 +23,37 @@ type ArgArrayIndexWithNegative<Ar extends readonly unknown[]> =
 
 declare namespace SizeType {
   type Arr = Uint32;
+
   type TypedArray = SafeUint;
+
   type Str = SafeUint;
 
   type ArrSearchResult = Arr | -1;
+
   type TypedArraySearchResult = TypedArray | -1;
+
   type StrSearchResult = Str | -1;
 
   type ArgArr = WithSmallInt<Arr>;
+
   type ArgTypedArray = WithSmallInt<TypedArray>;
+
   type ArgStr = WithSmallInt<Str>;
 
   type ArgArrWithNegative = WithSmallInt<
     NormalizeBrandUnion<NegativeInt32 | Arr>
   >;
+
   type ArgTypedArrayWithNegative = WithSmallInt<SafeInt>;
+
   type ArgStrWithNegative = WithSmallInt<SafeInt>;
 
   type ArgArrPositive = WithSmallInt<IntersectBrand<PositiveNumber, Arr>>;
+
   type ArgTypedArrayPositive = WithSmallInt<
     IntersectBrand<PositiveNumber, TypedArray>
   >;
+
   type ArgStrPositive = WithSmallInt<IntersectBrand<PositiveNumber, Str>>;
 }
 

package/src/guard/has-key.test.mts

@@ -66,6 +66,7 @@ import { hasKey, type HasKeyReturnType } from './has-key.mjs';
 
   if (hasKey(obj, 'a')) {
     expectType<typeof obj.a, 0>('=');
+
     expectType<typeof obj, Readonly<{ a: 0 }>>('=');
   }
 
@@ -86,7 +87,9 @@ import { hasKey, type HasKeyReturnType } from './has-key.mjs';
 
   if (hasKey(obj, 'a') && hasKey(obj, 'b')) {
     expectType<typeof obj.a, 1>('=');
+
     expectType<typeof obj.b, 1>('=');
+
     expectType<typeof obj, Readonly<{ a: 1; b: 1 }>>('=');
   }
 }
@@ -122,7 +125,9 @@ import { hasKey, type HasKeyReturnType } from './has-key.mjs';
 
   if (hasKey(obj, 'a') && hasKey(obj, 'b')) {
     expectType<typeof obj.a, number>('=');
+
     expectType<typeof obj.b, number>('=');
+
     expectType<
       typeof obj,
       | Readonly<{ a: 1; b: 1 }>
@@ -138,6 +143,7 @@ import { hasKey, type HasKeyReturnType } from './has-key.mjs';
 
   if (hasKey(o, 'a')) {
     expectType<typeof o.a, unknown>('=');
+
     expectType<
       typeof o,
       ReadonlyRecord<'a', unknown> & ReadonlyRecord<string, unknown>
@@ -146,6 +152,7 @@ import { hasKey, type HasKeyReturnType } from './has-key.mjs';
 
   if (hasKey(o, 'c')) {
     expectType<typeof o.c, unknown>('=');
+
     expectType<
       typeof o,
       ReadonlyRecord<'c', unknown> & ReadonlyRecord<string, unknown>
@@ -154,7 +161,9 @@ import { hasKey, type HasKeyReturnType } from './has-key.mjs';
 
   if (hasKey(o, 'a') && hasKey(o, 'b')) {
     expectType<typeof o.a, unknown>('=');
+
     expectType<typeof o.b, unknown>('=');
+
     expectType<
       typeof o,
       ReadonlyRecord<'a', unknown> &

package/src/guard/is-non-empty-string.test.mts

@@ -4,10 +4,15 @@ import { isNonEmptyString } from './is-non-empty-string.mjs';
 describe(isNonEmptyString, () => {
   test('should return true for non-empty strings', () => {
     expect(isNonEmptyString('hello')).toBe(true);
+
     expect(isNonEmptyString('a')).toBe(true);
+
     expect(isNonEmptyString(' ')).toBe(true); // Space is not empty
+
     expect(isNonEmptyString('  multiple spaces  ')).toBe(true);
+
     expect(isNonEmptyString('123')).toBe(true);
+
     expect(isNonEmptyString('special!@#$%')).toBe(true);
   });
 
@@ -17,21 +22,30 @@ describe(isNonEmptyString, () => {
 
   test('should return false for non-string values', () => {
     expect(isNonEmptyString(null)).toBe(false);
+
     expect(isNonEmptyString(undefined)).toBe(false);
+
     // @ts-expect-error Testing non-string types
     expect(isNonEmptyString(42)).toBe(false);
+
     // @ts-expect-error Testing non-string types
     expect(isNonEmptyString(0)).toBe(false);
+
     // @ts-expect-error Testing non-string types
     expect(isNonEmptyString(true)).toBe(false);
+
     // @ts-expect-error Testing non-string types
     expect(isNonEmptyString(false)).toBe(false);
+
     // @ts-expect-error Testing non-string types
     expect(isNonEmptyString({})).toBe(false);
+
     // @ts-expect-error Testing non-string types
     expect(isNonEmptyString([])).toBe(false);
+
     // @ts-expect-error Testing non-string types
     expect(isNonEmptyString(['string'])).toBe(false);
+
     // @ts-expect-error Testing non-string types
     expect(isNonEmptyString(() => 'string')).toBe(false);
   });
@@ -45,6 +59,7 @@ describe(isNonEmptyString, () => {
 
       // TypeScript knows it's a string
       expect(value.length).toBeGreaterThan(0);
+
       expect(value.charAt(0)).toBe('t');
     }
   });
@@ -79,10 +94,15 @@ describe(isNonEmptyString, () => {
 
   test('should handle string edge cases', () => {
     expect(isNonEmptyString('\n')).toBe(true); // Newline
+
     expect(isNonEmptyString('\t')).toBe(true); // Tab
+
     expect(isNonEmptyString('\r')).toBe(true); // Carriage return
+
     expect(isNonEmptyString('\0')).toBe(true); // Null character
+
     expect(isNonEmptyString('🎉')).toBe(true); // Emoji
+
     expect(isNonEmptyString('你好')).toBe(true); // Unicode characters
   });
 

package/src/guard/is-non-null-object.test.mts

@@ -4,37 +4,50 @@ import { isNonNullObject } from './is-non-null-object.mjs';
 describe(isNonNullObject, () => {
   test('should return true for plain objects', () => {
     expect(isNonNullObject({})).toBe(true);
+
     expect(isNonNullObject({ a: 1, b: 'test' })).toBe(true);
+
     expect(isNonNullObject({ nested: { value: true } })).toBe(true);
   });
 
   test('should return true for arrays', () => {
     expect(isNonNullObject([])).toBe(true);
+
     expect(isNonNullObject([1, 2, 3])).toBe(true);
+
     expect(isNonNullObject(['a', 'b', 'c'])).toBe(true);
   });
 
   test('should return true for functions', () => {
     expect(isNonNullObject(() => {})).toBe(false);
+
     expect(isNonNullObject(async () => {})).toBe(false);
+
     // eslint-disable-next-line @typescript-eslint/no-extraneous-class
     expect(isNonNullObject(class MyClass {})).toBe(false);
   });
 
   test('should return true for built-in objects', () => {
     expect(isNonNullObject(new Date())).toBe(true);
+
     expect(isNonNullObject(/test/u)).toBe(true);
+
     expect(isNonNullObject(/regex/u)).toBe(true);
+
     expect(isNonNullObject(new Map())).toBe(true);
+
     expect(isNonNullObject(new Set())).toBe(true);
+
     expect(isNonNullObject(new Error('test'))).toBe(true);
   });
 
   test('should return true for boxed primitives', () => {
     // eslint-disable-next-line unicorn/new-for-builtins
     expect(isNonNullObject(new String('hello'))).toBe(true);
+
     // eslint-disable-next-line unicorn/new-for-builtins
     expect(isNonNullObject(new Number(42))).toBe(true);
+
     // eslint-disable-next-line unicorn/new-for-builtins
     expect(isNonNullObject(new Boolean(true))).toBe(true);
   });
@@ -45,11 +58,17 @@ describe(isNonNullObject, () => {
 
   test('should return false for primitive values', () => {
     expect(isNonNullObject(undefined)).toBe(false);
+
     expect(isNonNullObject('string')).toBe(false);
+
     expect(isNonNullObject(42)).toBe(false);
+
     expect(isNonNullObject(true)).toBe(false);
+
     expect(isNonNullObject(false)).toBe(false);
+
     expect(isNonNullObject(Symbol('test'))).toBe(false);
+
     expect(isNonNullObject(123n)).toBe(false);
   });
 

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

@@ -5,9 +5,11 @@ import { isSymbol } from './is-type.mjs';
 describe(isPrimitive, () => {
   test('should return true for string primitives', () => {
     expect(isPrimitive('hello')).toBe(true);
+
     expect(isPrimitive('')).toBe(true);
 
     const value: unknown = 'test';
+
     if (isPrimitive(value)) {
       expectType<
         typeof value,
@@ -18,25 +20,33 @@ describe(isPrimitive, () => {
 
   test('should return true for number primitives', () => {
     expect(isPrimitive(42)).toBe(true);
+
     expect(isPrimitive(0)).toBe(true);
+
     expect(isPrimitive(-3.14)).toBe(true);
+
     expect(isPrimitive(Number.NaN)).toBe(true);
+
     expect(isPrimitive(Number.POSITIVE_INFINITY)).toBe(true);
   });
 
   test('should return true for boolean primitives', () => {
     expect(isPrimitive(true)).toBe(true);
+
     expect(isPrimitive(false)).toBe(true);
   });
 
   test('should return true for symbol primitives', () => {
     expect(isPrimitive(Symbol('test'))).toBe(true);
+
     expect(isPrimitive(Symbol.iterator)).toBe(true);
   });
 
   test('should return true for bigint primitives', () => {
     expect(isPrimitive(123n)).toBe(true);
+
     expect(isPrimitive(0n)).toBe(true);
+
     expect(isPrimitive(-123n)).toBe(true);
   });
 
@@ -51,26 +61,33 @@ describe(isPrimitive, () => {
 
   test('should return false for objects', () => {
     expect(isPrimitive({})).toBe(false);
+
     expect(isPrimitive({ a: 1 })).toBe(false);
+
     expect(isPrimitive(new Date())).toBe(false);
   });
 
   test('should return false for arrays', () => {
     expect(isPrimitive([])).toBe(false);
+
     expect(isPrimitive([1, 2, 3])).toBe(false);
   });
 
   test('should return false for functions', () => {
     expect(isPrimitive(() => {})).toBe(false);
+
     expect(isPrimitive(() => {})).toBe(false);
+
     expect(isPrimitive(async () => {})).toBe(false);
   });
 
   test('should return false for boxed primitives', () => {
     // eslint-disable-next-line unicorn/new-for-builtins
     expect(isPrimitive(new String('hello'))).toBe(false);
+
     // eslint-disable-next-line unicorn/new-for-builtins
     expect(isPrimitive(new Number(42))).toBe(false);
+
     // eslint-disable-next-line unicorn/new-for-builtins
     expect(isPrimitive(new Boolean(true))).toBe(false);
   });
@@ -88,13 +105,19 @@ describe(isPrimitive, () => {
     ];
 
     const primitives = values.filter(isPrimitive);
+
     const nonPrimitives = values.filter((v) => !isPrimitive(v));
 
     expect(primitives).toHaveLength(6); // string, 42, true, null, undefined, symbol
+
     expect(primitives[0]).toBe('string');
+
     expect(primitives[1]).toBe(42);
+
     expect(primitives[2]).toBe(true);
+
     expect(primitives[3]).toBeNull();
+
     expect(primitives[4]).toBeUndefined();
 
     expect(isSymbol(primitives[5])).toBe(true);

package/src/guard/is-record.mts

@@ -40,3 +40,37 @@ import { isNonNullObject } from './is-non-null-object.mjs';
  */
 export const isRecord = (u: unknown): u is UnknownRecord =>
   isNonNullObject(u) && !Array.isArray(u);
+
+/**
+ * Type guard that checks if a value is a mutable record (an object with mutable string keys).
+ *
+ * This function is an alias for {@link isRecord}, but narrows the type to
+ * `MutableRecord<string, unknown>`, which is useful when you need to ensure
+ * that the object can be safely mutated (i.e., its properties can be added or changed).
+ *
+ * **Type Narrowing Behavior:**
+ *
+ * - Narrows `unknown` to `MutableRecord<string, unknown>`
+ * - Excludes `null`, `undefined`, primitives, arrays, and functions
+ * - Returns `true` for plain objects with mutable string keys
+ * - Returns `false` for arrays and other non-record types
+ *
+ * **Implementation:** This is a type alias for {@link isRecord}.
+ *
+ * @example
+ * ```ts
+ * const obj: unknown = { foo: 1 };
+ *
+ * if (isMutableRecord(obj)) {
+ *   obj['bar'] = 2; // Safe: obj is now known to be a mutable record
+ * }
+ * ```
+ *
+ * @param u - The value to check
+ * @returns `true` if `u` is a mutable record (plain object with string keys), `false` otherwise.
+ *   When `true`, TypeScript narrows the type to `MutableRecord<string, unknown>`.
+ * @see {@link isRecord} - For the underlying implementation and more details
+ */
+export const isMutableRecord: (
+  u: unknown,
+) => u is MutableRecord<string, unknown> = isRecord;

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

@@ -4,10 +4,13 @@ import { isRecord } from './is-record.mjs';
 describe(isRecord, () => {
   test('{ x: 1 } is a record', () => {
     const obj = { x: 1 } as const;
+
     const unk: unknown = obj;
+
     const res = isRecord(unk);
 
     expectType<typeof obj, UnknownRecord>('<=');
+
     expectType<typeof res, boolean>('=');
 
     if (res) {
@@ -19,10 +22,13 @@ describe(isRecord, () => {
 
   test('{} is a record', () => {
     const obj = {} as const;
+
     const unk: unknown = obj;
+
     const res = isRecord(unk);
 
     expectType<typeof obj, {}>('=');
+
     expectType<typeof res, boolean>('=');
 
     if (res) {
@@ -34,10 +40,13 @@ describe(isRecord, () => {
 
   test('[] is not a record', () => {
     const obj: DeepReadonly<never[]> = [] as const;
+
     const unk: unknown = obj;
+
     const res = isRecord(unk);
 
     expectType<typeof obj, readonly never[]>('=');
+
     expectType<typeof res, boolean>('=');
 
     expect(res).toBe(false);
@@ -45,10 +54,13 @@ describe(isRecord, () => {
 
   test('null is not a record', () => {
     const obj = null;
+
     const unk: unknown = obj;
+
     const res = isRecord(unk);
 
     expectType<typeof obj, null>('=');
+
     expectType<typeof res, boolean>('=');
 
     expect(res).toBe(false);
@@ -56,10 +68,13 @@ describe(isRecord, () => {
 
   test('undefined is not a record', () => {
     const obj = undefined;
+
     const unk: unknown = obj;
+
     const res = isRecord(unk);
 
     expectType<typeof obj, undefined>('=');
+
     expectType<typeof res, boolean>('=');
 
     expect(res).toBe(false);
@@ -67,10 +82,13 @@ describe(isRecord, () => {
 
   test('3 is not a record', () => {
     const obj = 3;
+
     const unk: unknown = obj;
+
     const res = isRecord(unk);
 
     expectType<typeof obj, 3>('=');
+
     expectType<typeof res, boolean>('=');
 
     expect(res).toBe(false);
@@ -78,10 +96,13 @@ describe(isRecord, () => {
 
   test('"str" is not a record', () => {
     const obj = 'str';
+
     const unk: unknown = obj;
+
     const res = isRecord(unk);
 
     expectType<typeof obj, 'str'>('=');
+
     expectType<typeof res, boolean>('=');
 
     expect(res).toBe(false);

package/src/guard/is-type.mts

@@ -263,7 +263,9 @@ export const isNotString = <T,>(u: T): u is RelaxedExclude<T, string> =>
  *
  * ```ts
  * const id = Symbol('id');
+ *
  * const shared = Symbol.for('shared');
+ *
  * const tokens: unknown[] = [id, 'shared', shared];
  *
  * const symbols = tokens.filter(isSymbol);
@@ -289,6 +291,7 @@ export const isSymbol = (u: unknown): u is symbol => typeof u === 'symbol';
  *
  * ```ts
  * const id = Symbol('id');
+ *
  * const tokens: unknown[] = [id, 'shared'];
  *
  * const nonSymbols = tokens.filter(isNotSymbol);