ts-data-forge 3.2.0 → 3.3.1

package/src/functional/result.test.mts

@@ -371,7 +371,10 @@ describe('Result', () => {
   describe('flatMap', () => {
     test('should chain operations that return Result', () => {
       const divide = (a: number, b: number): Result<number, string> =>
-        b === 0 ? Result.err('Division by zero') : Result.ok(a / b);
+        b === 0
+          ? Result.err('Division by zero')
+          : // eslint-disable-next-line total-functions/no-partial-division
+            Result.ok(a / b);
 
       const result = Result.flatMap(Result.ok(10), (x) => divide(x, 2));
       expect(Result.unwrapOk(result)).toBe(5);
@@ -394,6 +397,7 @@ describe('Result', () => {
       };
 
       const divide = (a: number, b: number): Result<number, string> =>
+        // eslint-disable-next-line total-functions/no-partial-division
         b === 0 ? Result.err('Division by zero') : Result.ok(a / b);
 
       const result = Result.flatMap(
@@ -405,7 +409,10 @@ describe('Result', () => {
 
     test('should support curried form', () => {
       const divide = (a: number, b: number): Result<number, string> =>
-        b === 0 ? Result.err('Division by zero') : Result.ok(a / b);
+        b === 0
+          ? Result.err('Division by zero')
+          : // eslint-disable-next-line total-functions/no-partial-division
+            Result.ok(a / b);
 
       const divideBy2 = Result.flatMap((x: number) => divide(x, 2));
 

package/src/globals.d.mts

@@ -1,14 +1,21 @@
-/* eslint-disable import/unambiguous */
-
 /// <reference types="ts-type-forge" />
 
 type SmallPositiveInt = WithSmallInt<PositiveInt>;
 
-/**
- * Represents the type of keys that can be used in a standard JavaScript Map.
- */
+/** Represents the type of keys that can be used in a standard JavaScript Map. */
 type MapSetKeyType = Primitive;
 
+type ArrayIndex<Ar extends readonly unknown[]> =
+  IsFixedLengthList<Ar> extends true ? IndexOfTuple<Ar> : SizeType.Arr;
+
+type ArgArrayIndex<Ar extends readonly unknown[]> =
+  IsFixedLengthList<Ar> extends true ? IndexOfTuple<Ar> : SizeType.ArgArr;
+
+type ArgArrayIndexWithNegative<Ar extends readonly unknown[]> =
+  IsFixedLengthList<Ar> extends true
+    ? IndexOfTuple<[...Ar, 0]> | NegativeIndexOfTuple<Ar>
+    : SizeType.ArgArrWithNegative;
+
 // https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Global_Objects/Array/length
 // https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Global_Objects/String/length
 // Max array length : 2^32 - 1

package/src/guard/has-key.mts

@@ -1,91 +1,40 @@
 /**
- * Type guard function that checks if an object has a specific key as its own property.
+ * Type guard function that checks if an object has a specific key as its own
+ * property.
  *
- * This function uses `Object.hasOwn()` to check if the given object has the specified key
- * as its own property (not inherited). It acts as a type guard that narrows the type of the
- * object to guarantee the key exists, enabling type-safe property access.
+ * This function uses `Object.hasOwn()` to check if the given object has the
+ * specified key as its own property (not inherited). It acts as a type guard
+ * that narrows the type of the object to guarantee the key exists, enabling
+ * type-safe property access.
  *
  * **Type Narrowing Behavior:**
- * - When the guard returns `true`, TypeScript narrows the object type to include the checked key
+ *
+ * - When the guard returns `true`, TypeScript narrows the object type to include
+ *   the checked key
  * - For union types, only union members that contain the key are preserved
  * - The key's value type is preserved from the original object type when possible
  *
- * @template R - The type of the input object, must extend UnknownRecord
- * @template K - The type of the key to check for, must extend PropertyKey (string | number | symbol)
- * @param obj - The object to check for the presence of the key
- * @param key - The key to check for in the object
- * @returns `true` if the object has the specified key as its own property, `false` otherwise.
- *          When `true`, TypeScript narrows the object type to guarantee the key exists.
- *
  * @example
- * Basic usage with known object structure:
- * ```typescript
- * const obj = { a: 1, b: 'hello' };
- *
- * if (hasKey(obj, 'a')) {
- *   // obj is narrowed to guarantee 'a' exists
- *   console.log(obj.a); // TypeScript knows 'a' exists and is type number
- *   // No need for optional chaining or undefined checks
- * }
  *
- * if (hasKey(obj, 'c')) {
- *   // This block won't execute at runtime
- *   console.log(obj.c); // But TypeScript would know 'c' exists if it did
- * }
- * ```
- *
- * @example
- * Working with dynamic objects and unknown keys:
- * ```typescript
- * const dynamicObj: Record<string, unknown> = { x: 10, y: 20 };
- * const userInput: string = getUserInput();
+ * ```ts
+ * const maybeUser: { id?: number; name?: string } = { id: 42 };
  *
- * if (hasKey(dynamicObj, userInput)) {
- *   // Safe to access the dynamic key
- *   const value = dynamicObj[userInput]; // Type: unknown
- *   console.log(`Value for ${userInput}:`, value);
+ * if (hasKey(maybeUser, 'id')) {
+ *   // `maybeUser` is now known to have an `id` property.
+ *   assert(maybeUser.id === 42);
  * } else {
- *   console.log(`Key '${userInput}' not found`);
- * }
- * ```
- *
- * @example
- * Type narrowing with union types:
- * ```typescript
- * type UserPreferences =
- *   | { theme: 'dark'; notifications: boolean }
- *   | { theme: 'light' }
- *   | { autoSave: true; interval: number };
- *
- * const preferences: UserPreferences = getPreferences();
- *
- * if (hasKey(preferences, 'theme')) {
- *   // preferences is narrowed to the first two union members
- *   console.log(preferences.theme); // 'dark' | 'light'
- * }
- *
- * if (hasKey(preferences, 'autoSave')) {
- *   // preferences is narrowed to the third union member
- *   console.log(preferences.interval); // number (we know this exists)
- * }
- * ```
- *
- * @example
- * Basic usage with isRecord for progressive narrowing:
- * ```typescript
- * const data: unknown = parseApiResponse();
- *
- * if (isRecord(data) && hasKey(data, 'user')) {
- *   // data is now Record<string, unknown> with guaranteed 'user' key
- *   const user = data.user;
- *
- *   if (isRecord(user) && hasKey(user, 'name')) {
- *     // Safely access nested properties
- *     console.log('User name:', user.name);
- *   }
+ *   assert.fail('Expected the object to contain the id key.');
  * }
  * ```
  *
+ * @template R - The type of the input object, must extend UnknownRecord
+ * @template K - The type of the key to check for, must extend PropertyKey
+ *   (string | number | symbol)
+ * @param obj - The object to check for the presence of the key
+ * @param key - The key to check for in the object
+ * @returns `true` if the object has the specified key as its own property,
+ *   `false` otherwise. When `true`, TypeScript narrows the object type to
+ *   guarantee the key exists.
  * @see {@link keyIsIn} - Similar function that narrows the key type instead of the object type
  */
 export const hasKey = <

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

@@ -1,106 +1,39 @@
 /**
  * Type guard that checks if a value is a non-empty string.
  *
- * This function performs both a type check (ensuring the value is a string) and a length check
- * (ensuring the string is not empty). It acts as a type guard that narrows the input type to
- * exclude `null`, `undefined`, and empty strings.
+ * This function performs both a type check (ensuring the value is a string) and
+ * a length check (ensuring the string is not empty). It acts as a type guard
+ * that narrows the input type to exclude `null`, `undefined`, and empty
+ * strings.
  *
  * **Type Narrowing Behavior:**
+ *
  * - Eliminates `null` and `undefined` from the type
  * - Excludes empty string (`""`) from the type
  * - Preserves literal string types when possible
  * - Whitespace-only strings are considered non-empty
  *
- * @template S - The input type, which can include `string`, `null`, or `undefined`
- * @param s - The value to check
- * @returns `true` if `s` is a string with length > 0, `false` otherwise.
- *          When `true`, TypeScript narrows the type to exclude empty strings and nullish values.
- *
- * @example
- * Basic usage with different string types:
- * ```typescript
- * isNonEmptyString("hello");    // true
- * isNonEmptyString(" ");        // true (whitespace is considered non-empty)
- * isNonEmptyString("\t\n");     // true (whitespace characters are non-empty)
- * isNonEmptyString("");         // false
- * isNonEmptyString(null);       // false
- * isNonEmptyString(undefined);  // false
- * ```
- *
- * @example
- * Type guard usage with nullable strings:
- * ```typescript
- * const userInput: string | null | undefined = getUserInput();
- *
- * if (isNonEmptyString(userInput)) {
- *   // userInput is now typed as non-empty string
- *   console.log(userInput.charAt(0));     // Safe to access string methods
- *   console.log(userInput.toUpperCase()); // No need for null checks
- *   const length = userInput.length;      // Guaranteed to be > 0
- * } else {
- *   console.log('No valid input provided');
- * }
- * ```
- *
- * @example
- * Working with literal string types:
- * ```typescript
- * type Status = "active" | "inactive" | "" | null;
- * const status: Status = getStatus();
- *
- * if (isNonEmptyString(status)) {
- *   // status is now typed as "active" | "inactive"
- *   console.log(`Status is: ${status}`);
- * }
- * ```
- *
  * @example
- * Form validation patterns:
- * ```typescript
- * interface FormData {
- *   name?: string;
- *   email?: string;
- *   phone?: string;
- * }
- *
- * function validateForm(data: FormData): string[] {
- *   const errors: string[] = [];
- *
- *   if (!isNonEmptyString(data.name)) {
- *     errors.push('Name is required');
- *   }
- *
- *   if (!isNonEmptyString(data.email)) {
- *     errors.push('Email is required');
- *   } else if (!data.email.includes('@')) {
- *     // Safe to access string methods after guard
- *     errors.push('Invalid email format');
- *   }
  *
- *   return errors;
- * }
- * ```
- *
- * @example
- * Filtering arrays of potentially empty strings:
- * ```typescript
- * const responses: (string | null | undefined)[] = [
- *   "hello",
- *   "",
- *   "world",
- *   null,
+ * ```ts
+ * const words: readonly (string | undefined)[] = [
+ *   'Ada',
  *   undefined,
- *   " "
- * ];
+ *   '',
+ *   'Lovelace',
+ * ] as const;
  *
- * const validResponses = responses.filter(isNonEmptyString);
- * // validResponses is now string[] containing ["hello", "world", " "]
+ * const nonEmpty = words.filter(isNonEmptyString);
  *
- * validResponses.forEach(response => {
- *   // Each response is guaranteed to be a non-empty string
- *   console.log(response.trim().toUpperCase());
- * });
+ * assert.deepStrictEqual(nonEmpty, ['Ada', 'Lovelace']);
  * ```
+ *
+ * @template S - The input type, which can include `string`, `null`, or
+ *   `undefined`
+ * @param s - The value to check
+ * @returns `true` if `s` is a string with length > 0, `false` otherwise. When
+ *   `true`, TypeScript narrows the type to exclude empty strings and nullish
+ *   values.
  */
 export const isNonEmptyString = <S extends string | null | undefined>(
   s: S,

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

@@ -1,104 +1,34 @@
 /**
  * Type guard that checks if a value is a non-null object.
  *
- * This function checks if a value has type `"object"` according to the `typeof` operator
- * and is not `null`. This includes all object types such as plain objects, arrays, dates,
- * regular expressions, and other object instances, but excludes functions.
+ * This function checks if a value has type `"object"` according to the `typeof`
+ * operator and is not `null`. This includes all object types such as plain
+ * objects, arrays, dates, regular expressions, and other object instances, but
+ * excludes functions.
  *
  * **Type Narrowing Behavior:**
+ *
  * - Narrows `unknown` to `object`
  * - Excludes `null`, `undefined`, and all primitive types
  * - Excludes functions (they have `typeof` === `"function"`, not `"object"`)
  * - Includes arrays, dates, regex, and other object instances
  *
- * **Note:** This function returns `true` for arrays. If you need to check for plain objects
- * specifically (excluding arrays), use `isRecord()` instead.
- *
- * @param u - The value to check
- * @returns `true` if `u` is an object and not `null`, `false` otherwise.
- *          When `true`, TypeScript narrows the type to `object`.
- *
- * @example
- * Basic usage with different value types:
- * ```typescript
- * isNonNullObject({});           // true (plain object)
- * isNonNullObject([]);           // true (arrays are objects)
- * isNonNullObject(new Date());   // true (Date instance)
- * isNonNullObject(/regex/);      // true (RegExp instance)
- * isNonNullObject(new Map());    // true (Map instance)
- * isNonNullObject(null);         // false (null is not considered object here)
- * isNonNullObject(undefined);    // false (primitive)
- * isNonNullObject("string");     // false (primitive)
- * isNonNullObject(42);           // false (primitive)
- * isNonNullObject(true);         // false (primitive)
- * isNonNullObject(() => {});     // false (functions are not objects in this context)
- * ```
- *
- * @example
- * Type guard usage with unknown values:
- * ```typescript
- * const value: unknown = parseJsonData();
- *
- * if (isNonNullObject(value)) {
- *   // value is now typed as object
- *   console.log('Value is an object');
- *
- *   // You can now safely use object-specific operations
- *   console.log(Object.keys(value));      // Safe to call Object.keys
- *   console.log(value.toString());        // Safe to call methods
- *
- *   // But you may need additional checks for specific object types
- *   if (Array.isArray(value)) {
- *     console.log('It\'s an array with length:', value.length);
- *   }
- * } else {
- *   console.log('Value is not an object');
- * }
- * ```
+ * **Note:** This function returns `true` for arrays. If you need to check for
+ * plain objects specifically (excluding arrays), use `isRecord()` instead.
  *
  * @example
- * Filtering arrays to find objects:
- * ```typescript
- * const mixedArray: unknown[] = [
- *   { name: 'John' },
- *   'string',
- *   [1, 2, 3],
- *   42,
- *   null,
- *   new Date(),
- *   () => 'function'
- * ];
  *
- * const objects = mixedArray.filter(isNonNullObject);
- * // objects contains: [{ name: 'John' }, [1, 2, 3], Date instance]
- * // Note: includes both plain objects and arrays
+ * ```ts
+ * const mixed: unknown[] = [{ id: 1 }, null, 'Ada'] as const;
  *
- * objects.forEach(obj => {
- *   // Each obj is guaranteed to be an object
- *   console.log('Object type:', obj.constructor.name);
- * });
- * ```
+ * const objects = mixed.filter(isNonNullObject);
  *
- * @example
- * Progressive type narrowing with other guards:
- * ```typescript
- * const apiResponse: unknown = await fetchData();
- *
- * if (isNonNullObject(apiResponse)) {
- *   // apiResponse is now object
- *
- *   if (isRecord(apiResponse)) {
- *     // Further narrowed to UnknownRecord (plain object, not array)
- *
- *     if (hasKey(apiResponse, 'status')) {
- *       console.log('API status:', apiResponse.status);
- *     }
- *   } else if (Array.isArray(apiResponse)) {
- *     console.log('Response is an array with length:', apiResponse.length);
- *   }
- * }
+ * assert.deepStrictEqual(objects, [{ id: 1 }]);
  * ```
  *
+ * @param u - The value to check
+ * @returns `true` if `u` is an object and not `null`, `false` otherwise. When
+ *   `true`, TypeScript narrows the type to `object`.
  * @see {@link isRecord} - For checking plain objects specifically (excludes arrays)
  */
 // eslint-disable-next-line @typescript-eslint/no-restricted-types

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

@@ -50,7 +50,7 @@ describe('isNonNullObject', () => {
     expect(isNonNullObject(true)).toBe(false);
     expect(isNonNullObject(false)).toBe(false);
     expect(isNonNullObject(Symbol('test'))).toBe(false);
-    expect(isNonNullObject(BigInt(123))).toBe(false);
+    expect(isNonNullObject(123n)).toBe(false);
   });
 
   test('should act as a type guard', () => {

package/src/guard/is-primitive.mts

@@ -3,146 +3,33 @@ import { expectType } from '../expect-type.mjs';
 /**
  * Type guard that checks if a value is a primitive type.
  *
- * This function identifies JavaScript primitive types, which are immutable data types that are
- * not objects. The primitive types are: `string`, `number`, `boolean`, `undefined`, `symbol`,
- * `bigint`, and `null`.
+ * This function identifies JavaScript primitive types, which are immutable data
+ * types that are not objects. The primitive types are: `string`, `number`,
+ * `boolean`, `undefined`, `symbol`, `bigint`, and `null`.
  *
- * **Important Note:** Although `null` has `typeof null === "object"` due to a historical
- * JavaScript quirk, this function correctly identifies `null` as a primitive value.
+ * **Important Note:** Although `null` has `typeof null === "object"` due to a
+ * historical JavaScript quirk, this function correctly identifies `null` as a
+ * primitive value.
  *
  * **Type Narrowing Behavior:**
+ *
  * - Narrows the input type to `Primitive` (union of all primitive types)
  * - Excludes object types, arrays, functions, and other non-primitive values
  * - Includes `null` despite its misleading `typeof` result
  *
- * @param u - The value to check
- * @returns `true` if `u` is a primitive type, `false` otherwise.
- *          When `true`, TypeScript narrows the type to `Primitive`.
- *
  * @example
- * Basic usage with different value types:
- * ```typescript
- * isPrimitive("hello");        // true (string)
- * isPrimitive(42);             // true (number)
- * isPrimitive(true);           // true (boolean)
- * isPrimitive(undefined);      // true (undefined)
- * isPrimitive(Symbol('test')); // true (symbol)
- * isPrimitive(123n);           // true (bigint)
- * isPrimitive(null);           // true (null is primitive despite typeof quirk)
- *
- * isPrimitive({});             // false (object)
- * isPrimitive([]);             // false (array)
- * isPrimitive(() => {});       // false (function)
- * isPrimitive(new Date());     // false (object instance)
- * isPrimitive(/regex/);        // false (RegExp object)
- * ```
  *
- * @example
- * Type guard usage for separating primitives from objects:
- * ```typescript
- * const values: unknown[] = [
- *   'string',
- *   42,
- *   true,
- *   null,
- *   undefined,
- *   {},
- *   [],
- *   new Date()
- * ];
+ * ```ts
+ * const values: readonly unknown[] = [42, 'Ada', null, { id: 1 }] as const;
  *
  * const primitives = values.filter(isPrimitive);
- * const objects = values.filter(value => !isPrimitive(value));
- *
- * primitives.forEach(primitive => {
- *   // primitive is now typed as Primitive
- *   console.log('Primitive value:', primitive);
- *   console.log('Type:', typeof primitive);
- * });
- * ```
- *
- * @example
- * Deep cloning detection - primitives don't need cloning:
- * ```typescript
- * function deepClone<T>(value: T): T {
- *   if (isPrimitive(value)) {
- *     // Primitives are immutable, return as-is
- *     return value;
- *   }
  *
- *   // Handle object cloning for non-primitives
- *   if (Array.isArray(value)) {
- *     return value.map(deepClone) as T;
- *   }
- *
- *   if (isRecord(value)) {
- *     const cloned = {} as T;
- *     for (const key in value) {
- *       if (Object.hasOwn(value, key)) {
- *         cloned[key] = deepClone(value[key]);
- *       }
- *     }
- *     return cloned;
- *   }
- *
- *   // For other object types, return as-is or implement specific cloning
- *   return value;
- * }
- * ```
- *
- * @example
- * Serialization helpers:
- * ```typescript
- * function canSerializeDirectly(value: unknown): boolean {
- *   if (isPrimitive(value)) {
- *     // Most primitives can be serialized directly
- *     return typeof value !== 'symbol' && typeof value !== 'bigint';
- *   }
- *   return false;
- * }
- *
- * function safeStringify(value: unknown): string {
- *   if (isPrimitive(value)) {
- *     if (value === null) return 'null';
- *     if (value === undefined) return 'undefined';
- *     if (typeof value === 'symbol') return value.toString();
- *     if (typeof value === 'bigint') return value.toString() + 'n';
- *     return String(value);
- *   }
- *
- *   return JSON.stringify(value);
- * }
+ * assert.deepStrictEqual(primitives, [42, 'Ada', null]);
  * ```
  *
- * @example
- * Type narrowing in conditional logic:
- * ```typescript
- * function processValue(value: unknown): string {
- *   if (isPrimitive(value)) {
- *     // value is now Primitive type
- *     switch (typeof value) {
- *       case 'string':
- *         return `String: ${value}`;
- *       case 'number':
- *         return `Number: ${value}`;
- *       case 'boolean':
- *         return `Boolean: ${value}`;
- *       case 'undefined':
- *         return 'Undefined';
- *       case 'symbol':
- *         return `Symbol: ${value.description || 'unnamed'}`;
- *       case 'bigint':
- *         return `BigInt: ${value}n`;
- *       case 'object': // This is null
- *         return 'Null';
- *       default:
- *         return 'Unknown primitive';
- *     }
- *   } else {
- *     return `Object: ${value?.constructor?.name || 'Unknown'}`;
- *   }
- * }
- * ```
+ * @param u - The value to check
+ * @returns `true` if `u` is a primitive type, `false` otherwise. When `true`,
+ *   TypeScript narrows the type to `Primitive`.
  */
 export const isPrimitive = (u: unknown): u is Primitive => {
   switch (typeof u) {

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

@@ -34,7 +34,7 @@ describe('isPrimitive', () => {
   });
 
   test('should return true for bigint primitives', () => {
-    expect(isPrimitive(BigInt(123))).toBe(true);
+    expect(isPrimitive(123n)).toBe(true);
     expect(isPrimitive(0n)).toBe(true);
     expect(isPrimitive(-123n)).toBe(true);
   });