ts-data-forge 14.10.2 → 14.11.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/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

@@ -48,6 +48,15 @@ export namespace Json {
    * );
    *
    * assert.isTrue(Result.isOk(withReviver));
+   *
+   * // With a reviver, the result is whatever the reviver returned, not JSON:
+   * // `created` is a `Date` here although it is typed `JsonValue`. Widen it to
+   * // `unknown` before narrowing it.
+   * const revived: unknown = withReviver.value;
+   *
+   * assert.isTrue(isRecord(revived));
+   *
+   * assert.instanceOf(revived['created'], Date);
    * ```
    *
    * @param text - A valid JSON string to parse. Can contain any valid JSON data
@@ -55,10 +64,19 @@ export namespace Json {
    * @param reviver - Optional function that transforms parsed values. Called
    *   for each key-value pair in the JSON. The function receives the key name
    *   and parsed value, and should return the transformed value. For nested
-   *   objects, inner objects are processed before outer objects.
+   *   objects, inner objects are processed before outer objects, so the
+   *   `value` an outer object is passed holds what the reviver already
+   *   returned for its children, which need not be JSON (see `@returns`).
+   *   Returning
+   *   `undefined` for a child deletes that property from an object and leaves
+   *   a hole in an array. The root is passed with the key `''`.
    * @returns A `Result<JsonValue, string>` containing:
    *
-   *   - On success: `Result.ok(parsedValue)` where `parsedValue` is the parsed JSON
+   *   - On success: `Result.ok(parsedValue)` where `parsedValue` is the parsed
+   *       JSON. With a reviver it is whatever the reviver returned for the root
+   *       (a `Date`, `undefined`, ...), which is not checked to be JSON although
+   *       it is typed `JsonValue`; widen it to `unknown` before narrowing it,
+   *       as the example does.
    *   - On failure: `Result.err(errorMessage)` where `errorMessage` describes the
    *       parsing error
    */

package/src/json/json.test.mts

@@ -180,6 +180,69 @@ describe('parse', () => {
 
     expect(result.value.text).toBe('hello');
   });
+
+  test('should return what the reviver returns for the root, even if it is not JSON', () => {
+    const result = Json.parse('{"a":1}', (key, value) =>
+      key === '' ? undefined : value,
+    );
+
+    assert.isTrue(Result.isOk(result));
+
+    expect(result.value).toBeUndefined();
+  });
+
+  test('should delete an object property and leave an array hole where the reviver returns undefined', () => {
+    const result = Json.parse('{"a":1,"b":[1,2,3]}', (key, value) =>
+      key === 'a' || key === '1' ? undefined : value,
+    );
+
+    assert.isTrue(Result.isOk(result));
+
+    const revived: unknown = result.value;
+
+    assert.isTrue(isRecord(revived));
+
+    assert.isFalse(hasKey(revived, 'a'));
+
+    assert.isTrue(hasKey(revived, 'b'));
+
+    const arr = revived.b;
+
+    assert.isTrue(Array.isArray(arr));
+
+    expect(arr).toHaveLength(3);
+
+    expect(arr[0]).toBe(1);
+
+    expect(arr[1]).toBeUndefined();
+
+    expect(arr[2]).toBe(3);
+
+    // With the same elements, only a hole at index 1 makes these differ.
+    expect(arr).not.toStrictEqual([1, undefined, 3]);
+  });
+
+  test('should pass the reviver the children it has already revived', () => {
+    const mut_seen: unknown[] = [];
+
+    const result = Json.parse('{"inner":{"n":1}}', (key, value) => {
+      if (key === 'inner') {
+        mut_seen.push(structuredClone(value));
+
+        return 'replaced';
+      }
+
+      if (key === '') {
+        mut_seen.push(structuredClone(value));
+      }
+
+      return value;
+    });
+
+    assert.isTrue(Result.isOk(result));
+
+    assert.deepStrictEqual(mut_seen, [{ n: 1 }, { inner: 'replaced' }]);
+  });
 });
 
 describe('stringify', () => {

package/src/number/branded-types/finite-number.mts

@@ -4,35 +4,24 @@ import type {
   FiniteNumber as TtfImported_FiniteNumber,
 } from 'ts-type-forge';
 import { expectType } from '../../expect-type.mjs';
-import { TsDataForgeInternals } from '../refined-number-utils.mjs';
-
-export type FiniteNumber = TtfImported_FiniteNumber;
-
-type ElementType = FiniteNumber;
-
-const typeNameInMessage = 'a finite number';
-
-const {
+import {
   abs,
   add,
-  castType,
   div,
-  is,
-  max: max_,
-  min: min_,
+  max as max_,
+  min as min_,
   mul,
   pow,
   random,
   sub,
-} = TsDataForgeInternals.RefinedNumberUtils.operatorsForFloat<
-  ElementType,
-  number,
-  number
->({
-  MIN_VALUE: -Number.MAX_VALUE,
-  MAX_VALUE: Number.MAX_VALUE,
-  typeNameInMessage,
-} as const);
+} from '../operators/finite-number.mjs';
+import type { TsDataForgeInternals } from '../refined-number-utils.mjs';
+
+export type FiniteNumber = TtfImported_FiniteNumber;
+
+type ElementType = FiniteNumber;
+
+const typeNameInMessage = 'a finite number';
 
 const floor = (
   x: ElementType,
@@ -65,7 +54,8 @@ expectType<TsDataForgeInternals.RefinedNumberUtils.ToInt<ElementType>, Int>(
  * @param value - The value to check
  * @returns `true` if the value is a finite number, `false` otherwise
  */
-export const isFiniteNumber = is;
+export const isFiniteNumber = (value: number): value is FiniteNumber =>
+  Number.isFinite(value);
 
 /**
  * Casts a `number` to the `FiniteNumber` branded type.
@@ -77,7 +67,15 @@ export const isFiniteNumber = is;
  * @returns The value as a `FiniteNumber`
  * @throws {TypeError} If the value is not a finite number
  */
-export const asFiniteNumber = castType;
+export const asFiniteNumber = <N extends number>(
+  value: N,
+): FiniteNumber & N => {
+  if (!isFiniteNumber(value)) {
+    throw new TypeError(`Expected ${typeNameInMessage}, got: ${value}`);
+  }
+
+  return value;
+};
 
 /**
  * Namespace providing type-safe operations for the `FiniteNumber` branded type.
@@ -92,7 +90,7 @@ export const FiniteNumber = {
    * @returns `true` if the value is a finite number, `false` otherwise
    * @see {@link isFiniteNumber} for usage examples
    */
-  is,
+  is: isFiniteNumber,
 
   /**
    * Returns the absolute value of a finite number.

package/src/number/branded-types/int.mts

@@ -1,35 +1,23 @@
 import type { Int as TtfImported_Int } from 'ts-type-forge';
 import { expectType } from '../../expect-type.mjs';
-import { TsDataForgeInternals } from '../refined-number-utils.mjs';
-
-export type Int = TtfImported_Int;
-
-type ElementType = Int;
-
-const typeNameInMessage = 'an integer';
-
-const {
+import {
   abs,
   add,
-  castType,
   div,
-  is,
-  max: max_,
-  min: min_,
+  max as max_,
+  min as min_,
   mul,
   pow,
   random,
   sub,
-} = TsDataForgeInternals.RefinedNumberUtils.operatorsForInteger<
-  ElementType,
-  number,
-  number
->({
-  integerOrSafeInteger: 'Integer',
-  MIN_VALUE: -Number.MAX_VALUE,
-  MAX_VALUE: Number.MAX_VALUE,
-  typeNameInMessage,
-} as const);
+} from '../operators/int.mjs';
+import type { TsDataForgeInternals } from '../refined-number-utils.mjs';
+
+export type Int = TtfImported_Int;
+
+type ElementType = Int;
+
+const typeNameInMessage = 'an integer';
 
 /**
  * Type guard that checks if a value is an integer.
@@ -50,7 +38,7 @@ const {
  * @param value - The value to check
  * @returns `true` if the value is an integer, `false` otherwise
  */
-export const isInt = is;
+export const isInt = (value: number): value is Int => Number.isInteger(value);
 
 /**
  * Casts a `number` to the `Int` branded type.
@@ -72,7 +60,13 @@ export const isInt = is;
  * @returns The value as an `Int`
  * @throws {TypeError} If the value is not an integer
  */
-export const asInt = castType;
+export const asInt = <N extends number>(value: N): Int & N => {
+  if (!isInt(value)) {
+    throw new TypeError(`Expected ${typeNameInMessage}, got: ${value}`);
+  }
+
+  return value;
+};
 
 /**
  * Namespace providing type-safe operations for the `Int` branded type.
@@ -101,7 +95,7 @@ export const Int = {
    * @returns `true` if the value is an integer, `false` otherwise
    * @see {@link isInt} for usage examples
    */
-  is,
+  is: isInt,
 
   /**
    * Returns the absolute value of an integer.

package/src/number/branded-types/int16.mts

@@ -1,38 +1,26 @@
 import type { Int16 as TtfImported_Int16 } from 'ts-type-forge';
 import { expectType } from '../../expect-type.mjs';
-import { TsDataForgeInternals } from '../refined-number-utils.mjs';
-
-export type Int16 = TtfImported_Int16;
-
-type ElementType = Int16;
-
-const typeNameInMessage = 'an integer in [-2^15, 2^15)';
-
-const {
+import {
   MAX_VALUE,
   MIN_VALUE,
   abs,
   add,
-  castType,
   div,
   fromNumber,
-  is,
-  max: max_,
-  min: min_,
+  max as max_,
+  min as min_,
   mul,
   pow,
   random,
   sub,
-} = TsDataForgeInternals.RefinedNumberUtils.operatorsForInteger<
-  ElementType,
-  number,
-  number
->({
-  integerOrSafeInteger: 'SafeInteger',
-  MIN_VALUE: -(2 ** 15),
-  MAX_VALUE: 2 ** 15 - 1,
-  typeNameInMessage,
-} as const);
+} from '../operators/int16.mjs';
+import type { TsDataForgeInternals } from '../refined-number-utils.mjs';
+
+export type Int16 = TtfImported_Int16;
+
+type ElementType = Int16;
+
+const typeNameInMessage = 'an integer in [-2^15, 2^15)';
 
 /**
  * Type guard that checks if a value is an integer in [-2^15, 2^15).
@@ -43,7 +31,8 @@ const {
  * @param value - The value to check
  * @returns `true` if the value is an integer in [-2^15, 2^15), `false` otherwise
  */
-export const isInt16 = is;
+export const isInt16 = (value: number): value is Int16 =>
+  Number.isSafeInteger(value) && -(2 ** 15) <= value && value <= 2 ** 15 - 1;
 
 /**
  * Casts a `number` to the `Int16` branded type.
@@ -55,7 +44,13 @@ export const isInt16 = is;
  * @returns The value as an `Int16`
  * @throws {TypeError} If the value is not an integer in [-2^15, 2^15)
  */
-export const asInt16 = castType;
+export const asInt16 = <N extends number>(value: N): Int16 & N => {
+  if (!isInt16(value)) {
+    throw new TypeError(`Expected ${typeNameInMessage}, got: ${value}`);
+  }
+
+  return value;
+};
 
 /**
  * Namespace providing type-safe operations for the `Int16` branded type.
@@ -71,7 +66,7 @@ export const Int16 = {
    * @returns `true` if the value is an integer in [-2^15, 2^15), `false` otherwise
    * @see {@link isInt16} for usage examples
    */
-  is,
+  is: isInt16,
 
   /**
    * The smallest value representable as `Int16` (the lower saturation target of