ts-data-forge 7.1.1 → 9.0.0

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

@@ -645,18 +645,7 @@ describe('Arr transformations', () => {
       expectType<
         typeof result,
         readonly (readonly (
-          | 1
-          | 2
-          | 3
-          | 4
-          | 5
-          | 6
-          | 7
-          | 8
-          | 9
-          | 10
-          | 11
-          | 12
+          1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12
         )[])[]
       >('=');
 
@@ -675,18 +664,7 @@ describe('Arr transformations', () => {
       expectType<
         typeof result,
         readonly (readonly (
-          | 1
-          | 2
-          | 3
-          | 4
-          | 5
-          | 6
-          | 7
-          | 8
-          | 9
-          | 10
-          | 11
-          | 12
+          1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12
         )[])[]
       >('=');
 
@@ -706,18 +684,7 @@ describe('Arr transformations', () => {
       expectType<
         typeof result,
         readonly (readonly (
-          | 1
-          | 2
-          | 3
-          | 4
-          | 5
-          | 6
-          | 7
-          | 8
-          | 9
-          | 10
-          | 11
-          | 12
+          1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12
         )[])[]
       >('=');
 

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

@@ -228,9 +228,7 @@ describe('Arr validations', () => {
 
       test('should handle union of array types', () => {
         type MixedArrayUnion =
-          | readonly string[]
-          | readonly number[]
-          | readonly boolean[];
+          readonly string[] | readonly number[] | readonly boolean[];
 
         const mixedArray: MixedArrayUnion = [1, 2, 3] as const;
 

package/src/expect-type.mts

@@ -71,9 +71,8 @@ import { type TypeEq, type TypeExtends } from 'ts-type-forge';
 export const expectType = <A, B>(
   _relation: TypeEq<A, B> extends true
     ? '<=' | '=' | '>=' | '~='
-    :
-        | '!='
-        | (TypeExtends<A, B> extends true
-            ? '<=' | (TypeExtends<B, A> extends true ? '>=' | '~=' : '!>=')
-            : '!<=' | (TypeExtends<B, A> extends true ? '>=' : '!>=')),
+    : | '!='
+      | (TypeExtends<A, B> extends true
+          ? '<=' | (TypeExtends<B, A> extends true ? '>=' | '~=' : '!>=')
+          : '!<=' | (TypeExtends<B, A> extends true ? '>=' : '!>=')),
 ): void => undefined;

package/src/functional/ternary-result/ternary-result.mts

@@ -39,16 +39,12 @@ export type TernaryErr<E> = Readonly<{
  * Represents a value that can be `Ok`, `Warn`, or `Err`.
  */
 export type TernaryResult<S, E, W = E> =
-  | TernaryOk<S>
-  | TernaryWarn<S, W>
-  | TernaryErr<E>;
+  TernaryOk<S> | TernaryWarn<S, W> | TernaryErr<E>;
 
 /**
  * Base type for any `TernaryResult`, used for generic constraints.
  */
 export type UnknownTernaryResult =
-  | TernaryOk<unknown>
-  | TernaryWarn<unknown, unknown>
-  | TernaryErr<unknown>;
+  TernaryOk<unknown> | TernaryWarn<unknown, unknown> | TernaryErr<unknown>;
 
 export * as TernaryResult from './impl/index.mjs';

package/src/guard/index.mts

@@ -1,4 +1,5 @@
 export * from './has-key.mjs';
+export * from './is-length-bounded-string.mjs';
 export * from './is-non-empty-string.mjs';
 export * from './is-non-null-object.mjs';
 export * from './is-primitive.mjs';

package/src/guard/is-length-bounded-string.mts

@@ -0,0 +1,199 @@
+import {
+  type BoundedLengthString,
+  type FixedLengthString,
+  type MaxLengthString,
+  type MinLengthString,
+} from 'ts-type-forge';
+import { type SizeType } from '../types.mjs';
+
+/**
+ * Type guard that checks if a string has at least `minLength` characters.
+ *
+ * The length is measured in UTF-16 code units (the same unit as
+ * `String.prototype.length`), so characters outside the Basic Multilingual
+ * Plane (e.g. emoji) count as 2.
+ *
+ * **Type Narrowing Behavior:**
+ *
+ * - Narrows the input to `MinLengthString<MinLength>` while preserving the
+ *   original string type (e.g. literal types) via intersection.
+ * - The result participates in the length-constraint subtyping relation: for
+ *   example, a value narrowed to `MinLengthString<3>` is assignable to
+ *   `MinLengthString<1>` (= `NonEmptyString`).
+ *
+ * @example
+ *
+ * ```ts
+ * const input: string = 'very-secret-password';
+ *
+ * assert.isTrue(isMinLengthString(input, 12));
+ *
+ * assert.isFalse(isMinLengthString('short', 12));
+ *
+ * if (isMinLengthString(input, 12)) {
+ *   const password: MinLengthString<12> = input;
+ *
+ *   const nonEmpty: NonEmptyString = input; // OK (12 >= 1)
+ * }
+ * ```
+ *
+ * @template S - The input string type (literal types are preserved).
+ * @template MinLength - The minimum number of characters (inclusive).
+ * @param s - The string to check.
+ * @param minLength - The minimum number of characters (inclusive).
+ * @returns `true` if `s.length >= minLength`, `false` otherwise. When `true`,
+ *   TypeScript narrows `s` to `MinLengthString<MinLength> & S`.
+ */
+export const isMinLengthString = <
+  S extends string,
+  MinLength extends SizeType.ArgStr,
+>(
+  s: S,
+  minLength: MinLength,
+): s is MinLengthString<MinLength> & S => s.length >= minLength;
+
+/**
+ * Type guard that checks if a string has at most `maxLength` characters.
+ *
+ * The length is measured in UTF-16 code units (the same unit as
+ * `String.prototype.length`), so characters outside the Basic Multilingual
+ * Plane (e.g. emoji) count as 2.
+ *
+ * **Type Narrowing Behavior:**
+ *
+ * - Narrows the input to `MaxLengthString<MaxLength>` while preserving the
+ *   original string type (e.g. literal types) via intersection.
+ * - The result participates in the length-constraint subtyping relation: for
+ *   example, a value narrowed to `MaxLengthString<16>` is assignable to
+ *   `MaxLengthString<32>`.
+ *
+ * @example
+ *
+ * ```ts
+ * const input: string = 'noshiro';
+ *
+ * assert.isTrue(isMaxLengthString(input, 32));
+ *
+ * assert.isFalse(isMaxLengthString(input, 3));
+ *
+ * if (isMaxLengthString(input, 32)) {
+ *   const userName: MaxLengthString<32> = input;
+ *
+ *   const relaxed: MaxLengthString<64> = input; // OK (32 <= 64)
+ * }
+ * ```
+ *
+ * @template S - The input string type (literal types are preserved).
+ * @template MaxLength - The maximum number of characters (inclusive).
+ * @param s - The string to check.
+ * @param maxLength - The maximum number of characters (inclusive).
+ * @returns `true` if `s.length <= maxLength`, `false` otherwise. When `true`,
+ *   TypeScript narrows `s` to `MaxLengthString<MaxLength> & S`.
+ */
+export const isMaxLengthString = <
+  S extends string,
+  MaxLength extends SizeType.ArgStr,
+>(
+  s: S,
+  maxLength: MaxLength,
+): s is MaxLengthString<MaxLength> & S => s.length <= maxLength;
+
+/**
+ * Type guard that checks if a string's length is within the inclusive range
+ * `[minLength, maxLength]`.
+ *
+ * The length is measured in UTF-16 code units (the same unit as
+ * `String.prototype.length`), so characters outside the Basic Multilingual
+ * Plane (e.g. emoji) count as 2.
+ *
+ * **Type Narrowing Behavior:**
+ *
+ * - Narrows the input to `BoundedLengthString<MinLength, MaxLength>` while
+ *   preserving the original string type (e.g. literal types) via intersection.
+ * - Since `BoundedLengthString` is the intersection of `MinLengthString` and
+ *   `MaxLengthString`, the narrowed value is assignable to both, and both
+ *   bounds can be weakened independently.
+ *
+ * @example
+ *
+ * ```ts
+ * const input: string = 'user-12345678';
+ *
+ * assert.isTrue(isBoundedLengthString(input, 8, 16));
+ *
+ * assert.isFalse(isBoundedLengthString('user', 8, 16));
+ *
+ * if (isBoundedLengthString(input, 8, 16)) {
+ *   const userId: BoundedLengthString<8, 16> = input;
+ *
+ *   const relaxed: BoundedLengthString<1, 255> = input; // OK ([8, 16] ⊆ [1, 255])
+ * }
+ * ```
+ *
+ * @template S - The input string type (literal types are preserved).
+ * @template MinLength - The minimum number of characters (inclusive).
+ * @template MaxLength - The maximum number of characters (inclusive).
+ * @param s - The string to check.
+ * @param minLength - The minimum number of characters (inclusive).
+ * @param maxLength - The maximum number of characters (inclusive).
+ * @returns `true` if `minLength <= s.length && s.length <= maxLength`, `false`
+ *   otherwise. When `true`, TypeScript narrows `s` to
+ *   `BoundedLengthString<MinLength, MaxLength> & S`.
+ */
+export const isBoundedLengthString = <
+  S extends string,
+  MinLength extends SizeType.ArgStr,
+  MaxLength extends SizeType.ArgStr,
+>(
+  s: S,
+  minLength: MinLength,
+  maxLength: MaxLength,
+): s is BoundedLengthString<MinLength, MaxLength> & S =>
+  s.length >= minLength && s.length <= maxLength;
+
+/**
+ * Type guard that checks if a string has exactly `length` characters.
+ *
+ * The length is measured in UTF-16 code units (the same unit as
+ * `String.prototype.length`), so characters outside the Basic Multilingual
+ * Plane (e.g. emoji) count as 2.
+ *
+ * **Type Narrowing Behavior:**
+ *
+ * - Narrows the input to `FixedLengthString<Length>` while preserving the
+ *   original string type (e.g. literal types) via intersection.
+ * - Since `FixedLengthString<Length>` is defined as
+ *   `BoundedLengthString<Length, Length>`, the narrowed value is assignable to
+ *   any `MinLengthString<N>` with `N <= Length` and any `MaxLengthString<N>`
+ *   with `N >= Length`.
+ *
+ * @example
+ *
+ * ```ts
+ * const input: string = 'JP';
+ *
+ * assert.isTrue(isFixedLengthString(input, 2));
+ *
+ * assert.isFalse(isFixedLengthString(input, 3));
+ *
+ * if (isFixedLengthString(input, 2)) {
+ *   const countryCode: FixedLengthString<2> = input;
+ *
+ *   const atMost5: MaxLengthString<5> = input; // OK (2 <= 5)
+ * }
+ * ```
+ *
+ * @template S - The input string type (literal types are preserved).
+ * @template Length - The exact number of characters.
+ * @param s - The string to check.
+ * @param length - The exact number of characters.
+ * @returns `true` if `s.length === length`, `false` otherwise. When `true`,
+ *   TypeScript narrows `s` to `FixedLengthString<Length> & S`.
+ */
+export const isFixedLengthString = <
+  S extends string,
+  Length extends SizeType.ArgStr,
+>(
+  s: S,
+  length: Length,
+): s is FixedLengthString<Length> & S => s.length === length;

package/src/guard/is-length-bounded-string.test.mts

@@ -0,0 +1,170 @@
+import {
+  type BoundedLengthString,
+  type FixedLengthString,
+  type MaxLengthString,
+  type MinLengthString,
+  type NonEmptyString,
+} from 'ts-type-forge';
+import { expectType } from '../expect-type.mjs';
+import {
+  isBoundedLengthString,
+  isFixedLengthString,
+  isMaxLengthString,
+  isMinLengthString,
+} from './is-length-bounded-string.mjs';
+
+describe(isMinLengthString, () => {
+  test('should return true when the string is long enough', () => {
+    assert.isTrue(isMinLengthString('hello', 3));
+
+    assert.isTrue(isMinLengthString('hello', 5));
+
+    assert.isTrue(isMinLengthString('', 0));
+
+    assert.isTrue(isMinLengthString(' ', 1)); // Space counts
+  });
+
+  test('should return false when the string is too short', () => {
+    assert.isFalse(isMinLengthString('hi', 3));
+
+    assert.isFalse(isMinLengthString('', 1));
+  });
+
+  test('should measure length in UTF-16 code units', () => {
+    assert.isTrue(isMinLengthString('🎉', 2)); // Surrogate pair
+
+    assert.isFalse(isMinLengthString('🎉', 3));
+  });
+
+  test('should act as a type guard', () => {
+    const value: string = 'very-secret-password';
+
+    if (isMinLengthString(value, 12)) {
+      expectType<typeof value, MinLengthString<12>>('<=');
+
+      expectType<typeof value, NonEmptyString>('<='); // 12 >= 1
+
+      expectType<typeof value, MinLengthString<16>>('!<=');
+
+      expect(value.length).toBeGreaterThanOrEqual(12);
+    }
+  });
+
+  test('should preserve literal string types', () => {
+    const literal = 'hello';
+
+    if (isMinLengthString(literal, 3)) {
+      expectType<typeof literal, 'hello'>('<=');
+
+      expectType<typeof literal, MinLengthString<3>>('<=');
+    }
+  });
+});
+
+describe(isMaxLengthString, () => {
+  test('should return true when the string is short enough', () => {
+    assert.isTrue(isMaxLengthString('hello', 10));
+
+    assert.isTrue(isMaxLengthString('hello', 5));
+
+    assert.isTrue(isMaxLengthString('', 0));
+  });
+
+  test('should return false when the string is too long', () => {
+    assert.isFalse(isMaxLengthString('hello', 3));
+
+    assert.isFalse(isMaxLengthString(' ', 0));
+  });
+
+  test('should measure length in UTF-16 code units', () => {
+    assert.isFalse(isMaxLengthString('🎉', 1)); // Surrogate pair
+
+    assert.isTrue(isMaxLengthString('🎉', 2));
+  });
+
+  test('should act as a type guard', () => {
+    const value: string = 'noshiro';
+
+    if (isMaxLengthString(value, 32)) {
+      expectType<typeof value, MaxLengthString<32>>('<=');
+
+      expectType<typeof value, MaxLengthString<64>>('<='); // 32 <= 64
+
+      expectType<typeof value, MaxLengthString<16>>('!<=');
+
+      expect(value.length).toBeLessThanOrEqual(32);
+    }
+  });
+});
+
+describe(isBoundedLengthString, () => {
+  test('should return true when the length is within the range', () => {
+    assert.isTrue(isBoundedLengthString('user-12345678', 8, 16));
+
+    assert.isTrue(isBoundedLengthString('12345678', 8, 16)); // Lower bound (inclusive)
+
+    assert.isTrue(isBoundedLengthString('1234567890123456', 8, 16)); // Upper bound (inclusive)
+
+    assert.isTrue(isBoundedLengthString('', 0, 0));
+  });
+
+  test('should return false when the length is out of range', () => {
+    assert.isFalse(isBoundedLengthString('user', 8, 16));
+
+    assert.isFalse(isBoundedLengthString('12345678901234567', 8, 16));
+  });
+
+  test('should act as a type guard', () => {
+    const value: string = 'user-12345678';
+
+    if (isBoundedLengthString(value, 8, 16)) {
+      expectType<typeof value, BoundedLengthString<8, 16>>('<=');
+
+      expectType<typeof value, BoundedLengthString<1, 255>>('<='); // [8, 16] ⊆ [1, 255]
+
+      expectType<typeof value, MinLengthString<8>>('<=');
+
+      expectType<typeof value, MaxLengthString<16>>('<=');
+
+      expectType<typeof value, NonEmptyString>('<='); // 8 >= 1
+
+      expectType<typeof value, BoundedLengthString<10, 16>>('!<=');
+    }
+  });
+});
+
+describe(isFixedLengthString, () => {
+  test('should return true only for the exact length', () => {
+    assert.isTrue(isFixedLengthString('JP', 2));
+
+    assert.isTrue(isFixedLengthString('', 0));
+
+    assert.isFalse(isFixedLengthString('JPN', 2));
+
+    assert.isFalse(isFixedLengthString('J', 2));
+  });
+
+  test('should measure length in UTF-16 code units', () => {
+    assert.isTrue(isFixedLengthString('🎉', 2)); // Surrogate pair
+
+    assert.isFalse(isFixedLengthString('🎉', 1));
+  });
+
+  test('should act as a type guard', () => {
+    const value: string = 'JP';
+
+    if (isFixedLengthString(value, 2)) {
+      expectType<typeof value, FixedLengthString<2>>('<=');
+
+      expectType<typeof value, BoundedLengthString<2, 2>>('<=');
+
+      expectType<typeof value, MaxLengthString<5>>('<='); // 2 <= 5
+
+      expectType<typeof value, MinLengthString<1>>('<='); // 2 >= 1
+
+      expectType<typeof value, NonEmptyString>('<=');
+
+      expectType<typeof value, FixedLengthString<3>>('!<=');
+    }
+  });
+});

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

@@ -13,8 +13,8 @@
  * - 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.
+ * **Note:** This function returns `true` for arrays. If you need
+ * record-oriented narrowing that excludes arrays, use `isRecord()` instead.
  *
  * @example
  *
@@ -29,7 +29,7 @@
  * @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)
+ * @see {@link isRecord} - For record-oriented type narrowing (excludes arrays)
  */
 // eslint-disable-next-line @typescript-eslint/no-restricted-types
 export const isNonNullObject = (u: unknown): u is object =>

package/src/guard/is-record.mts

@@ -2,31 +2,46 @@ import { type MutableRecord, type UnknownRecord } from 'ts-type-forge';
 import { isNonNullObject } from './is-non-null-object.mjs';
 
 /**
- * Type guard that checks if a value is a plain object (record) - a non-null
- * object that is not an array.
+ * Type guard that checks if a value is a record — a non-null, non-array
+ * object — and narrows it to `UnknownRecord` (= `ReadonlyRecord<string,
+ * unknown>`).
  *
- * This function is useful for identifying "plain" JavaScript objects (also
- * called records or dictionaries) - objects that are typically used as
- * key-value collections. It excludes arrays, functions, and special object
- * types like Date, RegExp, etc., focusing on objects that can be safely treated
- * as property collections.
+ * This function is designed to be combined with {@link hasKey} to probe
+ * values of type `unknown` (e.g. parsed JSON, caught errors, external data)
+ * in a type-safe way: `if (isRecord(u) && hasKey(u, 'some-key')) { ... }`.
  *
  * **Type Narrowing Behavior:**
  *
- * - Narrows `unknown` to `UnknownRecord` (equivalent to `Record<PropertyKey,
- *   unknown>`)
- * - Excludes `null`, `undefined`, primitives, arrays, and functions
- * - Returns `true` for plain objects `{}`, object literals, and objects created
- *   with `Object.create()`
- * - Returns `false` for arrays, even though they are technically objects
- *
- * **Implementation:** Uses `isNonNullObject()` to check for objects, then
- * `Array.isArray()` to exclude arrays.
+ * - Narrows `unknown` to `UnknownRecord` (= `ReadonlyRecord<string, unknown>`)
+ * - Excludes `null`, `undefined`, primitives, and functions
+ * - Excludes arrays: arrays have no string index signature, so they are not
+ *   assignable to `UnknownRecord`; admitting them at runtime would be
+ *   inconsistent with the narrowed type
+ * - Returns `true` for every other non-null object, including dictionary
+ *   objects created with `Object.create(null)` and instances such as `Date`,
+ *   `RegExp`, `Map`, `Set`, `Error`, and user-defined classes
+ *
+ * **Why non-plain objects are included:** since every property of
+ * `UnknownRecord` is typed `unknown`, reading properties from any object
+ * through this narrowing is type-safe, and `hasKey` (backed by
+ * `Object.hasOwn`) answers own-property questions correctly on any object
+ * (e.g. `Map` entries are not own properties, so `hasKey` correctly returns
+ * `false` for them). Restricting the guard to plain objects would require
+ * prototype checks that misjudge cross-realm objects and would prevent
+ * probing useful instances such as `Error` subclasses.
+ *
+ * **Implementation:** `isNonNullObject(u) && !Array.isArray(u)`.
  *
  * @example
  *
  * ```ts
- * const entries: readonly unknown[] = [{ id: 1 }, 'str', 0, null] as const;
+ * const entries: readonly unknown[] = [
+ *   { id: 1 },
+ *   [1, 2],
+ *   'str',
+ *   0,
+ *   null,
+ * ] as const;
  *
  * const records = entries.filter(isRecord);
  *
@@ -34,30 +49,33 @@ import { isNonNullObject } from './is-non-null-object.mjs';
  * ```
  *
  * @param u - The value to check
- * @returns `true` if `u` is a non-null object and not an array, `false`
- *   otherwise. When `true`, TypeScript narrows the type to `UnknownRecord`.
- * @see {@link isNonNullObject} - For checking any object type (includes arrays)
+ * @returns `true` if `u` is a non-null, non-array object, `false` otherwise.
+ *   When `true`, TypeScript narrows the type to `UnknownRecord`.
+ * @see {@link isNonNullObject} - For checking any non-null object (includes arrays)
  * @see {@link hasKey} - For checking if a record has specific keys
  */
-export const isRecord = (u: unknown): u is UnknownRecord => isNonNullObject(u);
+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).
+ * Type guard that checks if a value is a mutable record.
  *
- * 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).
+ * This function has the same runtime behavior as {@link isRecord} (non-null,
+ * non-array object check), but narrows the type to `MutableRecord<string,
+ * unknown>`, which is useful when you need to add or overwrite properties on
+ * the narrowed object.
  *
  * **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
+ * - Excludes `null`, `undefined`, primitives, functions, and arrays
+ * - Returns `true` for every other non-null object (see {@link isRecord} for
+ *   details on non-plain objects such as `Date`, `Map`, and `Set`)
  *
  * **Implementation:** This is a type alias for {@link isRecord}.
  *
  * @example
+ *
  * ```ts
  * const obj: unknown = { foo: 1 } as const;
  *
@@ -67,8 +85,9 @@ export const isRecord = (u: unknown): u is UnknownRecord => isNonNullObject(u);
  * ```
  *
  * @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>`.
+ * @returns `true` if `u` is a non-null, non-array object, `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: (