ts-data-forge 3.2.0 → 3.3.1

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

@@ -139,7 +139,7 @@ describe('isNumber', () => {
     expect(isNumber('123')).toBe(false);
     expect(isNumber(true)).toBe(false);
     expect(isNumber(null)).toBe(false);
-    expect(isNumber(BigInt(123))).toBe(false);
+    expect(isNumber(123n)).toBe(false);
     // eslint-disable-next-line no-new-wrappers, unicorn/new-for-builtins
     expect(isNumber(new Number(42))).toBe(false);
   });
@@ -155,7 +155,7 @@ describe('isNumber', () => {
 
 describe('isBigint', () => {
   test('should return true for bigints', () => {
-    expect(isBigint(BigInt(0))).toBe(true);
+    expect(isBigint(0n)).toBe(true);
     expect(isBigint(123n)).toBe(true);
     expect(isBigint(-456n)).toBe(true);
   });
@@ -265,7 +265,7 @@ describe('isNotNumber', () => {
     expect(isNotNumber(false)).toBe(true);
     expect(isNotNumber(null)).toBe(true);
     expect(isNotNumber(undefined)).toBe(true);
-    expect(isNotNumber(BigInt(123))).toBe(true);
+    expect(isNotNumber(123n)).toBe(true);
     expect(isNotNumber({})).toBe(true);
     expect(isNotNumber([])).toBe(true);
     expect(isNotNumber(Symbol('test'))).toBe(true);
@@ -284,7 +284,7 @@ describe('isNotNumber', () => {
 
 describe('isNotBigint', () => {
   test('should return false for bigint values', () => {
-    expect(isNotBigint(BigInt(0))).toBe(false);
+    expect(isNotBigint(0n)).toBe(false);
     expect(isNotBigint(123n)).toBe(false);
     expect(isNotBigint(-456n)).toBe(false);
   });
@@ -326,7 +326,7 @@ describe('isNotString', () => {
     expect(isNotString({})).toBe(true);
     expect(isNotString([])).toBe(true);
     expect(isNotString(Symbol('test'))).toBe(true);
-    expect(isNotString(BigInt(123))).toBe(true);
+    expect(isNotString(123n)).toBe(true);
   });
 
   test('should act as a type guard', () => {
@@ -356,7 +356,7 @@ describe('isNotSymbol', () => {
     expect(isNotSymbol(undefined)).toBe(true);
     expect(isNotSymbol({})).toBe(true);
     expect(isNotSymbol([])).toBe(true);
-    expect(isNotSymbol(BigInt(123))).toBe(true);
+    expect(isNotSymbol(123n)).toBe(true);
   });
 
   test('should act as a type guard', () => {
@@ -417,7 +417,7 @@ describe('isNonNullish', () => {
     expect(isNonNullish([])).toBe(true);
     expect(isNonNullish(Number.NaN)).toBe(true);
     expect(isNonNullish(Symbol('test'))).toBe(true);
-    expect(isNonNullish(BigInt(123))).toBe(true);
+    expect(isNonNullish(123n)).toBe(true);
   });
 
   test('should act as a type guard', () => {

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

@@ -1,157 +1,40 @@
 /**
  * Type guard that checks if a key exists as an own property in an object.
  *
- * This function is similar to `hasKey()` but with reversed parameter order and different
- * type narrowing behavior. While `hasKey()` narrows the object type, `keyIsIn()` narrows
- * the key type to be a valid key of the given object.
+ * This function is similar to `hasKey()` but with reversed parameter order and
+ * different type narrowing behavior. While `hasKey()` narrows the object type,
+ * `keyIsIn()` narrows the key type to be a valid key of the given object.
  *
  * **Type Narrowing Behavior:**
+ *
  * - Narrows the key type to be a key that exists in the object (`K & keyof R`)
- * - Useful when you have a dynamic key and want to ensure it's valid for a specific object
+ * - Useful when you have a dynamic key and want to ensure it's valid for a
+ *   specific object
  * - The object type remains unchanged
  *
- * **Implementation:** Uses `Object.hasOwn()` to check for own properties (not inherited).
- *
- * @template K - The type of the key to check, must extend PropertyKey (string | number | symbol)
- * @template R - The type of the record (object), must extend UnknownRecord
- * @param key - The key to check for
- * @param obj - The object to check within
- * @returns `true` if `key` is an own property of `obj`, `false` otherwise.
- *          When `true`, TypeScript narrows the key type to be a valid key of the object.
- *
- * @example
- * Basic usage with known object structure:
- * ```typescript
- * const obj = { a: 1, b: 2, c: 3 };
- * const userInput: string = getUserInput(); // Could be any string
- *
- * if (keyIsIn(userInput, obj)) {
- *   // userInput is now narrowed to 'a' | 'b' | 'c'
- *   const value = obj[userInput]; // Type-safe access, value is number
- *   console.log(`Value for ${userInput}:`, value);
- * } else {
- *   console.log(`Key '${userInput}' not found in object`);
- * }
- * ```
- *
- * @example
- * Dynamic key validation for safe property access:
- * ```typescript
- * const config = {
- *   apiUrl: 'https://api.example.com',
- *   timeout: 5000,
- *   retries: 3
- * } as const;
- *
- * function getConfigValue(key: string): unknown {
- *   if (keyIsIn(key, config)) {
- *     // key is now narrowed to 'apiUrl' | 'timeout' | 'retries'
- *     return config[key]; // Safe access with proper typing
- *   }
- *
- *   throw new Error(`Invalid config key: ${key}`);
- * }
- *
- * // Usage
- * const apiUrl = getConfigValue('apiUrl');    // Returns string
- * const timeout = getConfigValue('timeout');  // Returns number
- * // getConfigValue('invalid') would throw an error
- * ```
+ * **Implementation:** Uses `Object.hasOwn()` to check for own properties (not
+ * inherited).
  *
  * @example
- * Form field validation:
- * ```typescript
- * interface FormData {
- *   name: string;
- *   email: string;
- *   age: number;
- * }
- *
- * const formData: FormData = getFormData();
- * const requiredFields: readonly string[] = ['name', 'email'] as const;
- *
- * function validateRequiredFields(data: FormData): string[] {
- *   const errors: string[] = [];
  *
- *   for (const field of requiredFields) {
- *     if (keyIsIn(field, data)) {
- *       // field is now narrowed to keyof FormData
- *       const value = data[field];
+ * ```ts
+ * const user = { id: 1, name: 'Ada' } as const;
+ * const maybeKey: string = 'name';
  *
- *       if (typeof value === 'string' && value.trim() === '') {
- *         errors.push(`${field} is required`);
- *       }
- *     }
- *   }
- *
- *   return errors;
- * }
- * ```
- *
- * @example
- * Safe object property iteration:
- * ```typescript
- * const userPreferences = {
- *   theme: 'dark',
- *   language: 'en',
- *   notifications: true
- * };
- *
- * const settingsToUpdate: string[] = getSettingsFromUser();
- *
- * function updatePreferences(updates: Record<string, unknown>) {
- *   const validUpdates: Partial<typeof userPreferences> = {};
- *
- *   for (const [key, value] of Object.entries(updates)) {
- *     if (keyIsIn(key, userPreferences)) {
- *       // key is now narrowed to valid preference keys
- *       validUpdates[key] = value as typeof userPreferences[typeof key];
- *     } else {
- *       console.warn(`Unknown preference key: ${key}`);
- *     }
- *   }
- *
- *   return { ...userPreferences, ...validUpdates };
- * }
- * ```
- *
- * @example
- * Comparison with hasKey() - different narrowing behavior:
- * ```typescript
- * const obj = { x: 10, y: 20 };
- * const key: string = 'x';
- *
- * // Using keyIsIn - narrows the key type
- * if (keyIsIn(key, obj)) {
- *   // key is now 'x' | 'y'
- *   const value = obj[key]; // Safe access
- * }
- *
- * // Using hasKey - narrows the object type
- * if (hasKey(obj, key)) {
- *   // obj type is narrowed to guarantee the key exists
- *   const value = obj.x; // Direct access
- * }
- * ```
- *
- * @example
- * Working with union types:
- * ```typescript
- * type Config =
- *   | { type: 'database'; host: string; port: number }
- *   | { type: 'file'; path: string }
- *   | { type: 'memory'; maxSize: number };
- *
- * function getConfigProperty(config: Config, propName: string): unknown {
- *   if (keyIsIn(propName, config)) {
- *     // propName is narrowed to valid keys for the specific config type
- *     return config[propName];
- *   }
- *
- *   return undefined;
+ * if (keyIsIn(maybeKey, user)) {
+ *   assert(user[maybeKey] === 'Ada');
+ * } else {
+ *   assert.fail('Expected a known key.');
  * }
  * ```
  *
+ * @template K - The type of the key to check, must extend PropertyKey (string |
+ *   number | symbol)
+ * @template R - The type of the record (object), must extend UnknownRecord
+ * @param key - The key to check for
+ * @param obj - The object to check within
+ * @returns `true` if `key` is an own property of `obj`, `false` otherwise. When
+ *   `true`, TypeScript narrows the key type to be a valid key of the object.
  * @see {@link hasKey} - Similar function that narrows the object type instead of the key type
  */
 export const keyIsIn = <

package/src/index.mts

@@ -1,4 +1,3 @@
-export * from './array/index.mjs';
 export * from './collections/index.mjs';
 export * from './expect-type.mjs';
 export * from './functional/index.mjs';

package/src/iterator/range.mts

@@ -1,94 +1,61 @@
 import { SafeInt, asSafeInt } from '../number/index.mjs';
 
 /**
- * Generates a sequence of numbers within a specified range using a generator function.
+ * Generates a sequence of numbers within a specified range using a generator
+ * function.
  *
- * This function creates a generator that yields numbers from `start` (inclusive) to `end` (exclusive)
- * with the specified `step` increment/decrement. The function implements the JavaScript iterator protocol,
- * making it compatible with for-of loops, spread operator, Array.from(), and other iterator consumers.
+ * This function creates a generator that yields numbers from `start`
+ * (inclusive) to `end` (exclusive) with the specified `step`
+ * increment/decrement. The function implements the JavaScript iterator
+ * protocol, making it compatible with for-of loops, spread operator,
+ * Array.from(), and other iterator consumers.
  *
  * The function has two overloaded signatures:
- * 1. For non-negative ranges: accepts SafeUint parameters and optional positive step
+ *
+ * 1. For non-negative ranges: accepts SafeUint parameters and optional positive
+ *    step
  * 2. For general ranges: accepts SafeInt parameters and optional non-zero step
  *
  * **Generator Behavior:**
+ *
  * - Yields values lazily (computed on-demand)
  * - Returns `void` when iteration completes
  * - Does not accept sent values (next parameter is ignored)
  * - Automatically handles direction based on step sign and start/end relationship
  *
  * **Step Parameter Behavior:**
+ *
  * - Positive step: iterates from start toward end (start < end expected)
  * - Negative step: iterates from start toward end (start > end expected)
  * - Zero step: not allowed (NonZeroSafeInt constraint)
  * - Default step: 1 (positive direction)
  *
  * **Edge Cases:**
+ *
  * - When start equals end: yields no values (empty sequence)
  * - When step direction conflicts with start/end relationship: yields no values
  * - All parameters must be safe integers (within JavaScript's safe integer range)
  *
- * @template T - The specific SafeInt or SafeUint type being generated
- * @param start - The starting number of the sequence (inclusive). Must be a safe integer.
- * @param end - The end number of the sequence (exclusive). Must be a safe integer.
- * @param step - The increment or decrement value. Defaults to 1. Must be non-zero safe integer.
- * @returns A Generator object that yields safe integers in the specified range.
- *
  * @example
- * ```typescript
- * // Basic ascending range
- * for (const n of range(0, 5)) {
- *   console.log(n); // Outputs: 0, 1, 2, 3, 4
- * }
- *
- * // Range with custom step
- * for (const n of range(0, 10, 2)) {
- *   console.log(n); // Outputs: 0, 2, 4, 6, 8
- * }
- *
- * // Descending range with negative step
- * for (const n of range(10, 0, -1)) {
- *   console.log(n); // Outputs: 10, 9, 8, 7, 6, 5, 4, 3, 2, 1
- * }
  *
- * // Negative numbers with negative step
- * for (const n of range(0, -10, -1)) {
- *   console.log(n); // Outputs: 0, -1, -2, -3, -4, -5, -6, -7, -8, -9
- * }
+ * ```ts
+ * const zeroToThree = Array.from(range(0, 3));
+ * const threeToZero = Array.from(range(3, 0, -1));
+ * const defaultEnd = Array.from(range(4));
  *
- * // Convert generator to array
- * const numbers = Array.from(range(1, 4)); // [1, 2, 3]
- * const evens = [...range(0, 11, 2)]; // [0, 2, 4, 6, 8, 10]
- *
- * // Empty ranges
- * Array.from(range(5, 5)); // [] (start equals end)
- * Array.from(range(5, 3)); // [] (positive step, start > end)
- * Array.from(range(3, 5, -1)); // [] (negative step, start < end)
- *
- * // Using with iterator protocol manually
- * const gen = range(1, 4);
- * console.log(gen.next()); // { value: 1, done: false }
- * console.log(gen.next()); // { value: 2, done: false }
- * console.log(gen.next()); // { value: 3, done: false }
- * console.log(gen.next()); // { value: undefined, done: true }
- *
- * // Practical usage patterns
- * // Create index sequences
- * const indices = Array.from(range(0, items.length));
- *
- * // Generate test data
- * const testIds = [...range(1, 101)]; // [1, 2, ..., 100]
- *
- * // Iterate with step intervals
- * for (const minute of range(0, 60, 5)) {
- *   scheduleTask(minute); // Every 5 minutes
- * }
- *
- * // Countdown sequences
- * for (const count of range(10, 0, -1)) {
- *   console.log(`T-minus ${count}`);
- * }
+ * assert.deepStrictEqual(zeroToThree, [0, 1, 2]);
+ * assert.deepStrictEqual(threeToZero, [3, 2, 1]);
+ * assert.deepStrictEqual(defaultEnd, [0, 1, 2, 3]);
  * ```
+ *
+ * @template T - The specific SafeInt or SafeUint type being generated
+ * @param start - The starting number of the sequence (inclusive). Must be a
+ *   safe integer.
+ * @param end - The end number of the sequence (exclusive). Must be a safe
+ *   integer.
+ * @param step - The increment or decrement value. Defaults to 1. Must be
+ *   non-zero safe integer.
+ * @returns A Generator object that yields safe integers in the specified range.
  */
 export function range(
   end: WithSmallInt<SafeUint, MaxInt>,