ts-data-forge 14.10.1 → 14.11.0

package/src/array/impl/array-utils-transformation.test.mts

@@ -12,6 +12,7 @@ import { SafeUint } from '../../number/index.mjs';
 import { asMinLengthArray } from './array-utils-length-bounded-array-cast.mjs';
 import {
   cartesianProduct,
+  chunk,
   concat,
   filter,
   filterNot,
@@ -759,13 +760,61 @@ describe('Arr transformations', () => {
       ]);
     });
 
-    test('should work with chunk size < 2 (returns empty)', () => {
+    test('returns singleton chunks for size one', () => {
       const numbers = [1, 2, 3] as const;
 
       const result = partition(numbers, 1);
 
-      // According to docs, returns empty array if chunkSize < 2
-      assert.deepStrictEqual(result, []);
+      expectType<typeof result, readonly BoundedLengthArray<1, 1, 1 | 2 | 3>[]>(
+        '~=',
+      );
+
+      assert.deepStrictEqual<readonly (readonly number[])[]>(result, [
+        [1],
+        [2],
+        [3],
+      ]);
+    });
+
+    test('preserves singleton chunks through the alias and curried overloads', () => {
+      const numbers = [1, 2, 3] as const;
+
+      const expected = [[1], [2], [3]] as const;
+
+      assert.deepStrictEqual<readonly (readonly number[])[]>(
+        partition(1)(numbers),
+        expected,
+      );
+
+      assert.deepStrictEqual<readonly (readonly number[])[]>(
+        chunk(numbers, 1),
+        expected,
+      );
+
+      assert.deepStrictEqual<readonly (readonly number[])[]>(
+        chunk(1)(numbers),
+        expected,
+      );
+    });
+
+    test('size one produces no chunk for an empty array', () => {
+      assert.deepStrictEqual(partition([], 1), []);
+
+      assert.deepStrictEqual(partition(1)([]), []);
+
+      assert.deepStrictEqual(chunk([], 1), []);
+
+      assert.deepStrictEqual(chunk(1)([]), []);
+    });
+
+    test('a size below one, which the types reject, produces no chunk', () => {
+      const numbers = [1, 2, 3] as const;
+
+      // @ts-expect-error - a chunk size of 0 is not a positive integer
+      assert.deepStrictEqual(partition(numbers, 0), []);
+
+      // @ts-expect-error - a negative chunk size is not a positive integer
+      assert.deepStrictEqual(partition(-1)(numbers), []);
     });
 
     test('should work with chunk size larger than array', () => {

package/src/array/impl/array-utils-validation.mts

@@ -5,7 +5,8 @@ import type {
   IsUnknown,
   UnknownBrand,
 } from 'ts-type-forge';
-import { asUint32, Num } from '../../number/index.mjs';
+import { asUint32 } from '../../number/index.mjs';
+import * as Num from '../../number/num/impl/index.mjs';
 import type { ArrayIndex, SizeType } from '../../types.mjs';
 
 /**

package/src/built-in-tag.mts

@@ -0,0 +1,59 @@
+/**
+ * Type guards for the built-in objects this package special-cases, read from
+ * the `Object.prototype.toString` tag as `@sindresorhus/is` reads it, so that
+ * each answers as it did when this package depended on that one: an object from
+ * another realm is recognized, which `instanceof` misses, and an error-like
+ * plain object is not. ts-std-forge keeps the same guards for itself; neither
+ * package exports them.
+ *
+ * They replace that dependency because `@sindresorhus/is` keeps most of itself
+ * in a bundle that imports any one of its guards.
+ *
+ * Not part of the package's API: `gen:index:src` leaves this file out of the
+ * barrel.
+ */
+
+export const isError = (value: unknown): value is Error =>
+  tagOf(value) === 'Error';
+
+export const isRegExp = (value: unknown): value is RegExp =>
+  tagOf(value) === 'RegExp';
+
+export const isMap = (value: unknown): value is ReadonlyMap<unknown, unknown> =>
+  tagOf(value) === 'Map';
+
+export const isSet = (value: unknown): value is ReadonlySet<unknown> =>
+  tagOf(value) === 'Set';
+
+export const isTypedArray = (value: unknown): value is TypedArray =>
+  typedArrayTags.has(tagOf(value));
+
+type TypedArray =
+  | Int8Array
+  | Uint8Array
+  | Uint8ClampedArray
+  | Int16Array
+  | Uint16Array
+  | Int32Array
+  | Uint32Array
+  | Float32Array
+  | Float64Array
+  | BigInt64Array
+  | BigUint64Array;
+
+const typedArrayTags: ReadonlySet<string> = new Set<string>([
+  'Int8Array',
+  'Uint8Array',
+  'Uint8ClampedArray',
+  'Int16Array',
+  'Uint16Array',
+  'Int32Array',
+  'Uint32Array',
+  'Float32Array',
+  'Float64Array',
+  'BigInt64Array',
+  'BigUint64Array',
+]);
+
+const tagOf = (value: unknown): string =>
+  Object.prototype.toString.call(value).slice(8, -1);

package/src/built-in-tag.test.mts

@@ -0,0 +1,215 @@
+/* eslint-disable functional/no-class-inheritance */
+/* eslint-disable unicorn/error-message */
+import {
+  isError,
+  isMap,
+  isRegExp,
+  isSet,
+  isTypedArray,
+} from './built-in-tag.mjs';
+import { expectType } from './expect-type.mjs';
+
+describe(isError, () => {
+  test('should return true for native Error instances', () => {
+    assert.isTrue(isError(new Error()));
+
+    assert.isTrue(isError(new Error('test message')));
+  });
+
+  test('should return true for native Error subclasses', () => {
+    assert.isTrue(isError(new TypeError()));
+
+    assert.isTrue(isError(new RangeError()));
+
+    assert.isTrue(isError(new ReferenceError()));
+
+    assert.isTrue(isError(new SyntaxError()));
+
+    assert.isTrue(isError(new EvalError()));
+
+    assert.isTrue(isError(new URIError()));
+  });
+
+  test('should return true for custom Error subclasses', () => {
+    class CustomError extends Error {
+      constructor(message?: string) {
+        super(message);
+
+        this.name = 'CustomError';
+      }
+    }
+
+    assert.isTrue(isError(new CustomError()));
+
+    assert.isTrue(isError(new CustomError('custom error message')));
+  });
+
+  test('should return true for Error subclass with additional properties', () => {
+    class ExtendedError extends Error {
+      readonly code: number;
+
+      constructor(message: string, code: number) {
+        super(message);
+
+        this.name = 'ExtendedError';
+
+        this.code = code;
+      }
+    }
+
+    assert.isTrue(isError(new ExtendedError('error with code', 404)));
+  });
+
+  test('should return true for deeply nested Error subclass', () => {
+    class BaseCustomError extends Error {
+      constructor(message?: string) {
+        super(message);
+
+        this.name = 'BaseCustomError';
+      }
+    }
+
+    class DerivedCustomError extends BaseCustomError {
+      constructor(message?: string) {
+        super(message);
+
+        this.name = 'DerivedCustomError';
+      }
+    }
+
+    assert.isTrue(isError(new DerivedCustomError()));
+  });
+
+  test('should return false for Error-like objects', () => {
+    const errorLikeObject = {
+      name: 'Error',
+      message: 'This is not a real error',
+      stack: 'fake stack trace',
+    } as const;
+
+    assert.isFalse(isError(errorLikeObject));
+  });
+
+  test('should return false for non-Error values', () => {
+    assert.isFalse(isError(null));
+
+    assert.isFalse(isError(undefined));
+
+    assert.isFalse(isError(0));
+
+    assert.isFalse(isError(''));
+
+    assert.isFalse(isError('Error'));
+
+    assert.isFalse(isError(true));
+
+    assert.isFalse(isError({}));
+
+    assert.isFalse(isError([]));
+
+    assert.isFalse(isError(() => {}));
+  });
+
+  test('should act as a type guard', () => {
+    const value: Error | string = new Error('test');
+
+    if (!isError(value)) {
+      return;
+    }
+
+    expectType<typeof value, Error>('=');
+
+    expect(value.message).toBe('test');
+  });
+
+  test('should work with AggregateError', () => {
+    const aggregateError = new AggregateError(
+      [new Error('error 1'), new Error('error 2')],
+      'Multiple errors occurred',
+    );
+
+    assert.isTrue(isError(aggregateError));
+  });
+
+  test('should return false for errors created with Object.create', () => {
+    // Built and then re-pointed rather than `Object.create(Error.prototype)`,
+    // which the strict standard library types as `unknown` — correctly, since
+    // it knows nothing about the resulting shape. The object under test is the
+    // same: Error.prototype in its chain, never constructed as an Error.
+    const mut_protoError = { message: 'proto error', name: 'ProtoError' };
+
+    Object.setPrototypeOf(mut_protoError, Error.prototype);
+
+    const protoError = mut_protoError;
+
+    assert.isFalse(isError(protoError));
+  });
+});
+
+describe(isMap, () => {
+  test('should return true for a Map only', () => {
+    assert.isTrue(isMap(new Map<number, number>([[1, 2]])));
+
+    assert.isFalse(isMap(new WeakMap<object, unknown>()));
+
+    assert.isFalse(isMap(new Set<unknown>()));
+
+    assert.isFalse(isMap({ size: 0 }));
+  });
+});
+
+describe(isSet, () => {
+  test('should return true for a Set only', () => {
+    assert.isTrue(isSet(new Set<number>([1])));
+
+    assert.isFalse(isSet(new WeakSet<object>()));
+
+    assert.isFalse(isSet(new Map<unknown, unknown>()));
+
+    assert.isFalse(isSet([1]));
+  });
+});
+
+describe(isRegExp, () => {
+  test('should return true for a RegExp only', () => {
+    assert.isTrue(isRegExp(/a/u));
+
+    assert.isFalse(isRegExp('/a/u'));
+
+    assert.isFalse(isRegExp({ source: 'a', flags: 'u' }));
+  });
+});
+
+describe(isTypedArray, () => {
+  test('should return true for every typed array', () => {
+    assert.isTrue(isTypedArray(new Int8Array(1)));
+
+    assert.isTrue(isTypedArray(new Uint8Array(1)));
+
+    assert.isTrue(isTypedArray(new Uint8ClampedArray(1)));
+
+    assert.isTrue(isTypedArray(new Int16Array(1)));
+
+    assert.isTrue(isTypedArray(new Uint16Array(1)));
+
+    assert.isTrue(isTypedArray(new Int32Array(1)));
+
+    assert.isTrue(isTypedArray(new Uint32Array(1)));
+
+    assert.isTrue(isTypedArray(new Float32Array(1)));
+
+    assert.isTrue(isTypedArray(new Float64Array(1)));
+
+    assert.isTrue(isTypedArray(new BigInt64Array(1)));
+
+    assert.isTrue(isTypedArray(new BigUint64Array(1)));
+  });
+
+  test('should return false for other binary views and arrays', () => {
+    assert.isFalse(isTypedArray(new DataView(new ArrayBuffer(1))));
+
+    assert.isFalse(isTypedArray(new ArrayBuffer(1)));
+
+    assert.isFalse(isTypedArray([1, 2]));
+  });
+});

package/src/collections/imap-mapped.mts

@@ -1161,9 +1161,9 @@ class IMapMappedClass<K, V, KM extends MapSetKeyType>
           break;
 
         case 'update': {
-          const curr = mut_result.get(key);
-
-          if (curr === undefined || !mut_result.has(key)) {
+          // Presence is `has` alone, as in `update`: a stored value may itself
+          // be `undefined`.
+          if (!mut_result.has(key)) {
             if (this.#showNotFoundMessage) {
               console.warn(
                 `IMapMapped.withMutations::update: key not found: ${unknownToString(key)}`,
@@ -1173,7 +1173,9 @@ class IMapMappedClass<K, V, KM extends MapSetKeyType>
             break;
           }
 
-          mut_result.set(key, action.updater(curr));
+          // `has` held, so `get` returns the stored `V`, `undefined` included.
+          // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+          mut_result.set(key, action.updater(mut_result.get(key) as V));
 
           break;
         }

package/src/collections/imap-mapped.test.mts

@@ -705,6 +705,33 @@ describe('IMapMapped.withMutations', () => {
     expect(Optional.unwrap(updated.get({ id: 2, type: 'admin' }))).toBe('Bob');
   });
 
+  test('update calls the updater for a key whose value is undefined, as update() does', () => {
+    const map = IMapMapped.create<TestKey, string | undefined, string>(
+      [[{ id: 1, type: 'user' }, undefined]],
+      testKeyToString,
+      stringToTestKey,
+    );
+
+    const updater = (x: string | undefined): string | undefined =>
+      x ?? 'filled';
+
+    const batched = map.withMutations([
+      { type: 'update', key: { id: 1, type: 'user' }, updater },
+    ]);
+
+    expect(Optional.unwrap(batched.get({ id: 1, type: 'user' }))).toBe(
+      'filled',
+    );
+
+    expect(
+      Optional.unwrap(
+        map
+          .update({ id: 1, type: 'user' }, updater)
+          .get({ id: 1, type: 'user' }),
+      ),
+    ).toBe('filled');
+  });
+
   test('should handle empty mutations array', () => {
     const map = IMapMapped.create(
       [[{ id: 1, type: 'user' }, 'Alice']],

package/src/collections/imap.mts

@@ -880,9 +880,9 @@ class IMapClass<K extends MapSetKeyType, V>
         case 'update': {
           const { key } = action;
 
-          const curr = mut_result.get(key);
-
-          if (curr === undefined || !mut_result.has(key)) {
+          // Presence is `has` alone, as in `update`: a stored value may itself
+          // be `undefined`.
+          if (!mut_result.has(key)) {
             if (this.#showNotFoundMessage) {
               const keyStr = unknownToString(key);
 
@@ -892,7 +892,9 @@ class IMapClass<K extends MapSetKeyType, V>
             break;
           }
 
-          mut_result.set(key, action.updater(curr));
+          // `has` held, so `get` returns the stored `V`, `undefined` included.
+          // eslint-disable-next-line total-functions/no-unsafe-type-assertion
+          mut_result.set(key, action.updater(mut_result.get(key) as V));
 
           break;
         }

package/src/collections/imap.test.mts

@@ -754,6 +754,19 @@ describe('IMap.withMutations', () => {
     assert.isTrue(Optional.isNone(updated.get('nonexistent')));
   });
 
+  test('update calls the updater for a key whose value is undefined, as update() does', () => {
+    const map = IMap.create<string, number | undefined>([['a', undefined]]);
+
+    const updater = (x: number | undefined): number | undefined =>
+      x === undefined ? 1 : x + 1;
+
+    const batched = map.withMutations([{ type: 'update', key: 'a', updater }]);
+
+    expect(Optional.unwrap(batched.get('a'))).toBe(1);
+
+    expect(Optional.unwrap(map.update('a', updater).get('a'))).toBe(1);
+  });
+
   test('should handle mixed operations', () => {
     const map = IMap.create([['a', 1]]);
 

package/src/collections/stack.mts

@@ -1,6 +1,6 @@
 import { Optional } from '../functional/index.mjs';
 import { range } from '../iterator/index.mjs';
-import { asUint32, Uint32 } from '../number/index.mjs';
+import { asUint32, type Uint32 } from '../number/index.mjs';
 import type { SizeType } from '../types.mjs';
 
 /**
@@ -285,7 +285,7 @@ class StackClass<T> implements Stack<T> {
       return Optional.none;
     }
 
-    this.#mut_size = Uint32.sub(this.#mut_size, 1);
+    this.#mut_size = asUint32(this.#mut_size - 1);
 
     // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
     const element = this.#mut_buffer[this.#mut_size]!;
@@ -320,7 +320,7 @@ class StackClass<T> implements Stack<T> {
 
     this.#mut_buffer[this.#mut_size] = value;
 
-    this.#mut_size = Uint32.add(this.#mut_size, 1);
+    this.#mut_size = asUint32(this.#mut_size + 1);
   }
 }
 

package/src/iterator/range.mts

@@ -1,5 +1,6 @@
 import type { NonZeroSafeInt, SafeUint, WithSmallInt } from 'ts-type-forge';
-import { SafeInt, asSafeInt } from '../number/index.mjs';
+import { asSafeInt, type SafeInt } from '../number/index.mjs';
+import * as Num from '../number/num/impl/index.mjs';
 
 /**
  * Generates a sequence of numbers within a specified range using a generator
@@ -109,7 +110,14 @@ export function* range(
       for (
         let mut_i: SafeInt = asSafeInt(start);
         step > 0 ? mut_i < end : mut_i > end;
-        mut_i = SafeInt.add(mut_i, asSafeInt(step))
+        // Saturates as `SafeInt.add` does, without the `SafeInt` object.
+        mut_i = asSafeInt(
+          Num.clamp(
+            mut_i + asSafeInt(step),
+            Number.MIN_SAFE_INTEGER,
+            Number.MAX_SAFE_INTEGER,
+          ),
+        )
       ) {
         yield mut_i;
       }

package/src/iterator/range.test.mts

@@ -78,4 +78,11 @@ describe(range, () => {
 
     assert.deepStrictEqual(xs, [0, -1]);
   });
+
+  // The step is checked before it is added, as `SafeInt.add` used to have it
+  // checked, so an unchecked caller gets an error rather than an endless loop.
+  test('a step that is not a safe integer throws', () => {
+    // @ts-expect-error -- the type forbids it; an unchecked caller can still pass it
+    assert.throws(() => Array.from(range(0, 10, Number.POSITIVE_INFINITY)));
+  });
 });

package/src/json/json.mts

@@ -3,8 +3,7 @@ import type {
   UintRangeInclusive,
   UnknownRecord,
 } from 'ts-type-forge';
-import { Arr } from '../array/index.mjs';
-import { pipe, Result } from '../functional/index.mjs';
+import { Result } from '../functional/index.mjs';
 import { isRecord } from '../guard/index.mjs';
 import { castMutable, unknownToString } from '../others/index.mjs';
 
@@ -323,63 +322,24 @@ export namespace Json {
     value: UnknownRecord,
     space?: UintRangeInclusive<1, 10> | string,
   ): Result<string | undefined, string> => {
-    const allKeys = pipe(keysDeep(value))
-      .map(Arr.uniq)
-      .map((ks) => ks.toSorted()).value;
+    // The keys are collected by a first pass with a function replacer, which
+    // `JSON.stringify` calls at every nesting level with the value after
+    // `toJSON`, so the allowlist of the second pass misses none of them. The
+    // allowlist also fixes the order, sorting integer-like keys as strings.
+    const mut_keys = new Set<string>();
 
-    return stringifySelected(value, allKeys, space);
-  };
-}
-
-/**
- * @param obj - The record to extract keys from. Must be a plain object.
- * @param mut_keys - A mutable array to accumulate the collected keys. This
- *   array will be modified in-place by the function for performance reasons.
- * @internal
- * Recursively collects all property keys from a nested object structure.
- *
- * This helper function traverses an object and its nested objects and arrays,
- * collecting all string keys found at any level of nesting. The function mutates
- * the provided keys array for performance reasons.
- */
-const keysDeepImpl = (
-  obj: UnknownRecord,
-  // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-  mut_keys: string[],
-): void => {
-  for (const [k, v] of Object.entries(obj)) {
-    mut_keys.push(k);
-
-    if (isRecord(v)) {
-      keysDeepImpl(v, mut_keys);
-    }
-
-    if (Array.isArray(v)) {
-      for (const li of v) {
-        if (isRecord(li)) {
-          keysDeepImpl(li, mut_keys);
+    const collected = stringify(value, (_key, v) => {
+      if (isRecord(v)) {
+        for (const k of Object.keys(v)) {
+          mut_keys.add(k);
         }
       }
-    }
-  }
-};
 
-/**
- * @param obj - The record to extract keys from. Must be a plain object.
- * @returns A readonly array of all string keys found in the object and its
- *   nested objects/arrays. May contain duplicates if the same key appears at
- *   multiple levels.
- * @internal
- * Extracts all property keys from a nested object structure into a flat array.
- *
- * This function serves as a safe wrapper around `keysDeepImpl`, creating a new
- * mutable array and passing it to the recursive implementation. The result
- * contains all keys found at any level of nesting within the input object.
- */
-const keysDeep = (obj: UnknownRecord): readonly string[] => {
-  const mut_keys: string[] = [];
+      return v;
+    });
 
-  keysDeepImpl(obj, mut_keys);
-
-  return mut_keys;
-};
+    return Result.isErr(collected)
+      ? collected
+      : stringifySelected(value, Array.from(mut_keys).toSorted(), space);
+  };
+}

package/src/json/json.test.mts

@@ -709,6 +709,38 @@ describe('stringifySortedKey', () => {
     }
   });
 
+  test('keeps the properties of an object nested in an array of arrays', () => {
+    const result = Json.stringifySortedKey({ a: [[{ c: 1, b: 2 }]] });
+
+    assert.isTrue(Result.isOk(result));
+
+    expect(result.value).toBe('{"a":[[{"b":2,"c":1}]]}');
+
+    const other = Json.stringifySortedKey({ a: [[{ c: 1, b: 3 }]] });
+
+    assert.isTrue(Result.isOk(other));
+
+    expect(other.value).not.toBe(result.value);
+  });
+
+  test('keeps the properties of what toJSON returns', () => {
+    const result = Json.stringifySortedKey({
+      x: { toJSON: () => ({ z: 1, y: 2 }) },
+    });
+
+    assert.isTrue(Result.isOk(result));
+
+    expect(result.value).toBe('{"x":{"y":2,"z":1}}');
+  });
+
+  test('sorts integer-like keys as strings', () => {
+    const result = Json.stringifySortedKey({ 2: 'b', 10: 'a', x: 'c' });
+
+    assert.isTrue(Result.isOk(result));
+
+    expect(result.value).toBe('{"10":"a","2":"b","x":"c"}');
+  });
+
   test('should handle empty object', () => {
     const result = Json.stringifySortedKey({});