ts-data-forge 10.0.0 → 11.0.1

package/src/string/str.mts

@@ -0,0 +1,371 @@
+import {
+  type BoundedLengthString,
+  type FixedLengthString,
+  type MaxLengthString,
+  type MinLengthString,
+  type SupportedLength,
+} from 'ts-type-forge';
+
+/**
+ * Namespace providing type guards and runtime-checked casts for the branded
+ * length-constrained string types (`MinLengthString`, `MaxLengthString`,
+ * `BoundedLengthString`, `FixedLengthString`).
+ *
+ * Lengths are 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.
+ */
+export namespace Str {
+  /**
+   * Type guard that checks if a string has at least `minLength` characters.
+   *
+   * **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(Str.isMinLengthString(input, 12));
+   *
+   * assert.isFalse(Str.isMinLengthString('short', 12));
+   *
+   * if (Str.isMinLengthString(input, 12)) {
+   *   const nonEmpty: NonEmptyString = input; // OK (12 >= 1)
+   *
+   *   assert.isTrue(nonEmpty.length >= 12);
+   * }
+   * ```
+   *
+   * @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 SupportedLength,
+  >(
+    s: S,
+    minLength: MinLength,
+  ): s is MinLengthString<MinLength> & S => s.length >= minLength;
+
+  /**
+   * Type guard that checks if a string has at most `maxLength` characters.
+   *
+   * **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(Str.isMaxLengthString(input, 32));
+   *
+   * assert.isFalse(Str.isMaxLengthString(input, 3));
+   *
+   * if (Str.isMaxLengthString(input, 32)) {
+   *   const relaxed: MaxLengthString<64> = input; // OK (32 <= 64)
+   *
+   *   assert.isTrue(relaxed.length <= 32);
+   * }
+   * ```
+   *
+   * @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 SupportedLength,
+  >(
+    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]`.
+   *
+   * **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(Str.isBoundedLengthString(input, 8, 16));
+   *
+   * assert.isFalse(Str.isBoundedLengthString('user', 8, 16));
+   *
+   * if (Str.isBoundedLengthString(input, 8, 16)) {
+   *   const userId: BoundedLengthString<1, 255> = input; // OK ([8, 16] ⊆ [1, 255])
+   *
+   *   assert.isTrue(userId.length >= 8 && userId.length <= 16);
+   * }
+   * ```
+   *
+   * @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 SupportedLength,
+    MaxLength extends SupportedLength,
+  >(
+    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.
+   *
+   * **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(Str.isFixedLengthString(input, 2));
+   *
+   * assert.isFalse(Str.isFixedLengthString(input, 3));
+   *
+   * if (Str.isFixedLengthString(input, 2)) {
+   *   const atMost5: MaxLengthString<5> = input; // OK (2 <= 5)
+   *
+   *   assert.isTrue(atMost5.length === 2);
+   * }
+   * ```
+   *
+   * @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 SupportedLength,
+  >(
+    s: S,
+    length: Length,
+  ): s is FixedLengthString<Length> & S => s.length === length;
+
+  /**
+   * Casts a string to `MinLengthString<MinLength>` after checking that it has
+   * at least `minLength` characters.
+   *
+   * Use this instead of writing `s as unknown as MinLengthString<N>`: the
+   * length is verified at runtime, and the original string type (e.g. literal
+   * types) is preserved via intersection.
+   *
+   * @example
+   *
+   * ```ts
+   * const password = Str.asMinLengthString('very-secret-password', 12);
+   *
+   * const nonEmpty: NonEmptyString = password; // OK (>= 1)
+   *
+   * assert.isTrue(nonEmpty.length >= 12);
+   *
+   * assert.throws(() => Str.asMinLengthString('short', 12)); // length 5 < 12
+   * ```
+   *
+   * @template S - The input string type (literal types are preserved).
+   * @template MinLength - The minimum number of characters (inclusive).
+   * @param s - The string to cast.
+   * @param minLength - The minimum number of characters (inclusive).
+   * @returns `s` typed as `MinLengthString<MinLength> & S`.
+   * @throws {TypeError} If `s.length < minLength`.
+   */
+  export const asMinLengthString = <
+    S extends string,
+    MinLength extends SupportedLength,
+  >(
+    s: S,
+    minLength: MinLength,
+  ): MinLengthString<MinLength> & S => {
+    if (!isMinLengthString(s, minLength)) {
+      throw new TypeError(
+        `Expected a string of length >= ${minLength}, got a string of length ${s.length}`,
+      );
+    }
+
+    return s;
+  };
+
+  /**
+   * Casts a string to `MaxLengthString<MaxLength>` after checking that it has
+   * at most `maxLength` characters.
+   *
+   * Use this instead of writing `s as unknown as MaxLengthString<N>`: the
+   * length is verified at runtime, and the original string type (e.g. literal
+   * types) is preserved via intersection.
+   *
+   * @example
+   *
+   * ```ts
+   * const userName = Str.asMaxLengthString('noshiro', 32);
+   *
+   * const relaxed: MaxLengthString<64> = userName; // OK (32 <= 64)
+   *
+   * assert.isTrue(relaxed.length <= 32);
+   *
+   * assert.throws(() => Str.asMaxLengthString('noshiro', 3)); // length 7 > 3
+   * ```
+   *
+   * @template S - The input string type (literal types are preserved).
+   * @template MaxLength - The maximum number of characters (inclusive).
+   * @param s - The string to cast.
+   * @param maxLength - The maximum number of characters (inclusive).
+   * @returns `s` typed as `MaxLengthString<MaxLength> & S`.
+   * @throws {TypeError} If `s.length > maxLength`.
+   */
+  export const asMaxLengthString = <
+    S extends string,
+    MaxLength extends SupportedLength,
+  >(
+    s: S,
+    maxLength: MaxLength,
+  ): MaxLengthString<MaxLength> & S => {
+    if (!isMaxLengthString(s, maxLength)) {
+      throw new TypeError(
+        `Expected a string of length <= ${maxLength}, got a string of length ${s.length}`,
+      );
+    }
+
+    return s;
+  };
+
+  /**
+   * Casts a string to `BoundedLengthString<MinLength, MaxLength>` after
+   * checking that its length is within the inclusive range
+   * `[minLength, maxLength]`.
+   *
+   * Use this instead of writing `s as unknown as BoundedLengthString<M, N>`:
+   * the length is verified at runtime, and the original string type (e.g.
+   * literal types) is preserved via intersection.
+   *
+   * @example
+   *
+   * ```ts
+   * const userId = Str.asBoundedLengthString('user-12345678', 8, 16);
+   *
+   * const relaxed: BoundedLengthString<1, 255> = userId; // OK ([8, 16] ⊆ [1, 255])
+   *
+   * assert.isTrue(relaxed.length >= 8 && relaxed.length <= 16);
+   *
+   * assert.throws(() => Str.asBoundedLengthString('user', 8, 16)); // length 4 < 8
+   * ```
+   *
+   * @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 cast.
+   * @param minLength - The minimum number of characters (inclusive).
+   * @param maxLength - The maximum number of characters (inclusive).
+   * @returns `s` typed as `BoundedLengthString<MinLength, MaxLength> & S`.
+   * @throws {TypeError} If `s.length < minLength` or `s.length > maxLength`.
+   */
+  export const asBoundedLengthString = <
+    S extends string,
+    MinLength extends SupportedLength,
+    MaxLength extends SupportedLength,
+  >(
+    s: S,
+    minLength: MinLength,
+    maxLength: MaxLength,
+  ): BoundedLengthString<MinLength, MaxLength> & S => {
+    if (!isBoundedLengthString(s, minLength, maxLength)) {
+      throw new TypeError(
+        `Expected a string of length in [${minLength}, ${maxLength}], got a string of length ${s.length}`,
+      );
+    }
+
+    return s;
+  };
+
+  /**
+   * Casts a string to `FixedLengthString<Length>` after checking that it has
+   * exactly `length` characters.
+   *
+   * Use this instead of writing `s as unknown as FixedLengthString<N>`: the
+   * length is verified at runtime, and the original string type (e.g. literal
+   * types) is preserved via intersection.
+   *
+   * @example
+   *
+   * ```ts
+   * const countryCode = Str.asFixedLengthString('JP', 2);
+   *
+   * const atMost5: MaxLengthString<5> = countryCode; // OK (2 <= 5)
+   *
+   * assert.isTrue(atMost5.length === 2);
+   *
+   * assert.throws(() => Str.asFixedLengthString('JP', 3)); // length 2 !== 3
+   * ```
+   *
+   * @template S - The input string type (literal types are preserved).
+   * @template Length - The exact number of characters.
+   * @param s - The string to cast.
+   * @param length - The exact number of characters.
+   * @returns `s` typed as `FixedLengthString<Length> & S`.
+   * @throws {TypeError} If `s.length !== length`.
+   */
+  export const asFixedLengthString = <
+    S extends string,
+    Length extends SupportedLength,
+  >(
+    s: S,
+    length: Length,
+  ): FixedLengthString<Length> & S => {
+    if (!isFixedLengthString(s, length)) {
+      throw new TypeError(
+        `Expected a string of length ${length}, got a string of length ${s.length}`,
+      );
+    }
+
+    return s;
+  };
+}

package/src/string/str.test.mts

@@ -0,0 +1,215 @@
+import {
+  type BoundedLengthString,
+  type FixedLengthString,
+  type MaxLengthString,
+  type MinLengthString,
+  type NonEmptyString,
+} from 'ts-type-forge';
+import { expectType } from '../expect-type.mjs';
+import { Str } from './str.mjs';
+
+describe(Str.isMinLengthString, () => {
+  test('should return true when the string is long enough', () => {
+    assert.isTrue(Str.isMinLengthString('hello', 3));
+
+    assert.isTrue(Str.isMinLengthString('hello', 5));
+
+    assert.isTrue(Str.isMinLengthString('', 0));
+
+    assert.isTrue(Str.isMinLengthString(' ', 1)); // Space counts
+  });
+
+  test('should return false when the string is too short', () => {
+    assert.isFalse(Str.isMinLengthString('hi', 3));
+
+    assert.isFalse(Str.isMinLengthString('', 1));
+  });
+
+  test('should measure length in UTF-16 code units', () => {
+    assert.isTrue(Str.isMinLengthString('🎉', 2)); // Surrogate pair
+
+    assert.isFalse(Str.isMinLengthString('🎉', 3));
+  });
+
+  test('should act as a type guard', () => {
+    const value: string = 'very-secret-password';
+
+    if (Str.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 (Str.isMinLengthString(literal, 3)) {
+      expectType<typeof literal, 'hello'>('<=');
+
+      expectType<typeof literal, MinLengthString<3>>('<=');
+    }
+  });
+});
+
+describe(Str.isMaxLengthString, () => {
+  test('should return true when the string is short enough', () => {
+    assert.isTrue(Str.isMaxLengthString('hello', 10));
+
+    assert.isTrue(Str.isMaxLengthString('hello', 5));
+
+    assert.isTrue(Str.isMaxLengthString('', 0));
+  });
+
+  test('should return false when the string is too long', () => {
+    assert.isFalse(Str.isMaxLengthString('hello', 3));
+
+    assert.isFalse(Str.isMaxLengthString(' ', 0));
+  });
+
+  test('should measure length in UTF-16 code units', () => {
+    assert.isFalse(Str.isMaxLengthString('🎉', 1)); // Surrogate pair
+
+    assert.isTrue(Str.isMaxLengthString('🎉', 2));
+  });
+
+  test('should act as a type guard', () => {
+    const value: string = 'noshiro';
+
+    if (Str.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(Str.isBoundedLengthString, () => {
+  test('should return true when the length is within the range', () => {
+    assert.isTrue(Str.isBoundedLengthString('user-12345678', 8, 16));
+
+    assert.isTrue(Str.isBoundedLengthString('12345678', 8, 16)); // Lower bound (inclusive)
+
+    assert.isTrue(Str.isBoundedLengthString('1234567890123456', 8, 16)); // Upper bound (inclusive)
+
+    assert.isTrue(Str.isBoundedLengthString('', 0, 0));
+  });
+
+  test('should return false when the length is out of range', () => {
+    assert.isFalse(Str.isBoundedLengthString('user', 8, 16));
+
+    assert.isFalse(Str.isBoundedLengthString('12345678901234567', 8, 16));
+  });
+
+  test('should act as a type guard', () => {
+    const value: string = 'user-12345678';
+
+    if (Str.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(Str.isFixedLengthString, () => {
+  test('should return true only for the exact length', () => {
+    assert.isTrue(Str.isFixedLengthString('JP', 2));
+
+    assert.isTrue(Str.isFixedLengthString('', 0));
+
+    assert.isFalse(Str.isFixedLengthString('JPN', 2));
+
+    assert.isFalse(Str.isFixedLengthString('J', 2));
+  });
+
+  test('should measure length in UTF-16 code units', () => {
+    assert.isTrue(Str.isFixedLengthString('🎉', 2)); // Surrogate pair
+
+    assert.isFalse(Str.isFixedLengthString('🎉', 1));
+  });
+
+  test('should act as a type guard', () => {
+    const value: string = 'JP';
+
+    if (Str.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>>('!<=');
+    }
+  });
+});
+
+describe('Str length-bounded casts', () => {
+  test('asMinLengthString returns the value and narrows its type', () => {
+    const result = Str.asMinLengthString('very-secret', 3);
+
+    expectType<typeof result, MinLengthString<3>>('<=');
+
+    assert.strictEqual(result, 'very-secret');
+  });
+
+  test('asMinLengthString throws when too short', () => {
+    assert.throws(() => Str.asMinLengthString('hi', 3), TypeError);
+  });
+
+  test('asMaxLengthString returns the value and narrows its type', () => {
+    const result = Str.asMaxLengthString('noshiro', 32);
+
+    expectType<typeof result, MaxLengthString<32>>('<=');
+
+    assert.strictEqual(result, 'noshiro');
+  });
+
+  test('asMaxLengthString throws when too long', () => {
+    assert.throws(() => Str.asMaxLengthString('noshiro', 3), TypeError);
+  });
+
+  test('asBoundedLengthString returns the value and narrows its type', () => {
+    const result = Str.asBoundedLengthString('user-12345678', 8, 16);
+
+    expectType<typeof result, BoundedLengthString<8, 16>>('<=');
+
+    assert.strictEqual(result, 'user-12345678');
+  });
+
+  test('asBoundedLengthString throws when out of range', () => {
+    assert.throws(() => Str.asBoundedLengthString('user', 8, 16), TypeError);
+  });
+
+  test('asFixedLengthString returns the value and narrows its type', () => {
+    const result = Str.asFixedLengthString('JP', 2);
+
+    expectType<typeof result, FixedLengthString<2>>('<=');
+
+    assert.strictEqual(result, 'JP');
+  });
+
+  test('asFixedLengthString throws when the length differs', () => {
+    assert.throws(() => Str.asFixedLengthString('JP', 3), TypeError);
+  });
+});

package/dist/guard/as-length-bounded-array.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"as-length-bounded-array.d.mts","sourceRoot":"","sources":["../../src/guard/as-length-bounded-array.mts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,eAAe,EACrB,MAAM,eAAe,CAAC;AAQvB;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,kBAAkB,GAC7B,EAAE,SAAS,SAAS,OAAO,EAAE,EAC7B,MAAM,SAAS,eAAe,MAE1B,EAAE,UACE,MAAM,KACb,gBAAgB,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,GAAG,EAQzC,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,eAAO,MAAM,gBAAgB,GAC3B,EAAE,SAAS,SAAS,OAAO,EAAE,EAC7B,SAAS,SAAS,eAAe,MAE7B,EAAE,aACK,SAAS,KACnB,cAAc,CAAC,SAAS,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,GAAG,EAQ1C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,gBAAgB,GAC3B,EAAE,SAAS,SAAS,OAAO,EAAE,EAC7B,SAAS,SAAS,eAAe,MAE7B,EAAE,aACK,SAAS,KACnB,cAAc,CAAC,SAAS,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,GAAG,EAQ1C,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,eAAO,MAAM,oBAAoB,GAC/B,EAAE,SAAS,SAAS,OAAO,EAAE,EAC7B,SAAS,SAAS,eAAe,EACjC,SAAS,SAAS,eAAe,MAE7B,EAAE,aACK,SAAS,aACT,SAAS,KACnB,kBAAkB,CAAC,SAAS,EAAE,SAAS,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,GAAG,EAQzD,CAAC"}

package/dist/guard/as-length-bounded-array.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"as-length-bounded-array.mjs","sources":["../../src/guard/as-length-bounded-array.mts"],"sourcesContent":["import {\n  type BoundedLengthArray,\n  type FixedLengthArray,\n  type MaxLengthArray,\n  type MinLengthArray,\n  type SupportedLength,\n} from 'ts-type-forge';\nimport {\n  isBoundedLengthArray,\n  isFixedLengthArray,\n  isMaxLengthArray,\n  isMinLengthArray,\n} from './is-length-bounded-array.mjs';\n\n/**\n * Casts an array to `FixedLengthArray<Length, E>` after checking that it has\n * exactly `length` elements.\n *\n * Use this instead of writing `xs as unknown as FixedLengthArray<N, E>`: the\n * length is verified at runtime, and the original array type (e.g. tuple\n * types) is preserved via intersection, so the result also benefits from the\n * structural tuple prefix (in-range indexed access without `undefined` under\n * `noUncheckedIndexedAccess`).\n *\n * @example\n *\n * ```ts\n * const rgb = asFixedLengthArray([255, 128, 0], 3);\n *\n * const atMost5: MaxLengthArray<5, number> = rgb; // OK (3 <= 5)\n * const red: number = rgb[0]; // OK — no `undefined`\n *\n * // asFixedLengthArray([255, 128], 3); // throws TypeError\n * ```\n *\n * @template Xs - The input array type (tuple types are preserved).\n * @template Length - The exact number of elements.\n * @param xs - The array to cast.\n * @param length - The exact number of elements.\n * @returns `xs` typed as `FixedLengthArray<Length, Xs[number]> & Xs`.\n * @throws {TypeError} If `xs.length !== length`.\n */\nexport const asFixedLengthArray = <\n  Xs extends readonly unknown[],\n  Length extends SupportedLength,\n>(\n  xs: Xs,\n  length: Length,\n): FixedLengthArray<Length, Xs[number]> & Xs => {\n  if (!isFixedLengthArray(xs, length)) {\n    throw new TypeError(\n      `Expected an array of length ${length}, got an array of length ${xs.length}`,\n    );\n  }\n\n  return xs;\n};\n\n/**\n * Casts an array to `MinLengthArray<MinLength, E>` after checking that it has\n * at least `minLength` elements.\n *\n * Use this instead of writing `xs as unknown as MinLengthArray<N, E>`: the\n * length is verified at runtime, and the original array type (e.g. tuple\n * types) is preserved via intersection, so the result also benefits from the\n * structural tuple prefix (indexed access below `min(N, 10)` without\n * `undefined` under `noUncheckedIndexedAccess`).\n *\n * @example\n *\n * ```ts\n * const history = asMinLengthArray([0, 1, 2, 3], 3);\n *\n * const nonEmpty: MinLengthArray<1, number> = history; // OK (3 >= 1)\n * const first: number = history[0]; // OK — no `undefined`\n *\n * // asMinLengthArray([0], 3); // throws TypeError\n * ```\n *\n * @template Xs - The input array type (tuple types are preserved).\n * @template MinLength - The minimum number of elements (inclusive).\n * @param xs - The array to cast.\n * @param minLength - The minimum number of elements (inclusive).\n * @returns `xs` typed as `MinLengthArray<MinLength, Xs[number]> & Xs`.\n * @throws {TypeError} If `xs.length < minLength`.\n */\nexport const asMinLengthArray = <\n  Xs extends readonly unknown[],\n  MinLength extends SupportedLength,\n>(\n  xs: Xs,\n  minLength: MinLength,\n): MinLengthArray<MinLength, Xs[number]> & Xs => {\n  if (!isMinLengthArray(xs, minLength)) {\n    throw new TypeError(\n      `Expected an array of length >= ${minLength}, got an array of length ${xs.length}`,\n    );\n  }\n\n  return xs;\n};\n\n/**\n * Casts an array to `MaxLengthArray<MaxLength, E>` after checking that it has\n * at most `maxLength` elements.\n *\n * Use this instead of writing `xs as unknown as MaxLengthArray<N, E>`: the\n * length is verified at runtime, and the original array type (e.g. tuple\n * types) is preserved via intersection.\n *\n * @example\n *\n * ```ts\n * const tags = asMaxLengthArray(['a', 'b', 'c'], 8);\n *\n * const relaxed: MaxLengthArray<16, string> = tags; // OK (8 <= 16)\n *\n * // asMaxLengthArray(['a', 'b', 'c'], 2); // throws TypeError\n * ```\n *\n * @template Xs - The input array type (tuple types are preserved).\n * @template MaxLength - The maximum number of elements (inclusive).\n * @param xs - The array to cast.\n * @param maxLength - The maximum number of elements (inclusive).\n * @returns `xs` typed as `MaxLengthArray<MaxLength, Xs[number]> & Xs`.\n * @throws {TypeError} If `xs.length > maxLength`.\n */\nexport const asMaxLengthArray = <\n  Xs extends readonly unknown[],\n  MaxLength extends SupportedLength,\n>(\n  xs: Xs,\n  maxLength: MaxLength,\n): MaxLengthArray<MaxLength, Xs[number]> & Xs => {\n  if (!isMaxLengthArray(xs, maxLength)) {\n    throw new TypeError(\n      `Expected an array of length <= ${maxLength}, got an array of length ${xs.length}`,\n    );\n  }\n\n  return xs;\n};\n\n/**\n * Casts an array to `BoundedLengthArray<MinLength, MaxLength, E>` after\n * checking that its length is within the inclusive range\n * `[minLength, maxLength]`.\n *\n * Use this instead of writing\n * `xs as unknown as BoundedLengthArray<Min, Max, E>`: the length is verified\n * at runtime, and the original array type (e.g. tuple types) is preserved via\n * intersection.\n *\n * @example\n *\n * ```ts\n * const selection = asBoundedLengthArray([1, 2, 3], 1, 5);\n *\n * const relaxed: BoundedLengthArray<0, 100, number> = selection; // OK\n *\n * // asBoundedLengthArray([], 1, 5); // throws TypeError\n * ```\n *\n * @template Xs - The input array type (tuple types are preserved).\n * @template MinLength - The minimum number of elements (inclusive).\n * @template MaxLength - The maximum number of elements (inclusive).\n * @param xs - The array to cast.\n * @param minLength - The minimum number of elements (inclusive).\n * @param maxLength - The maximum number of elements (inclusive).\n * @returns `xs` typed as\n *   `BoundedLengthArray<MinLength, MaxLength, Xs[number]> & Xs`.\n * @throws {TypeError} If `xs.length < minLength || xs.length > maxLength`.\n */\nexport const asBoundedLengthArray = <\n  Xs extends readonly unknown[],\n  MinLength extends SupportedLength,\n  MaxLength extends SupportedLength,\n>(\n  xs: Xs,\n  minLength: MinLength,\n  maxLength: MaxLength,\n): BoundedLengthArray<MinLength, MaxLength, Xs[number]> & Xs => {\n  if (!isBoundedLengthArray(xs, minLength, maxLength)) {\n    throw new TypeError(\n      `Expected an array of length in [${minLength}, ${maxLength}], got an array of length ${xs.length}`,\n    );\n  }\n\n  return xs;\n};\n"],"names":[],"mappings":";;AA0CO,MAAM,kBAAA,GAAqB,CAIhC,EAAA,EACA,MAAA,KAC8C;AAC9C,EAAA,IAAI,CAAC,kBAAA,CAAmB,EAAA,EAAI,MAAM,CAAA,EAAG;AACnC,IAAA,MAAM,IAAI,SAAA;AAAA,MACR,CAAA,4BAAA,EAA+B,MAAM,CAAA,yBAAA,EAA4B,EAAA,CAAG,MAAM,CAAA;AAAA,KAC5E;AAAA,EACF;AAEA,EAAA,OAAO,EAAA;AACT;AA8BO,MAAM,gBAAA,GAAmB,CAI9B,EAAA,EACA,SAAA,KAC+C;AAC/C,EAAA,IAAI,CAAC,gBAAA,CAAiB,EAAA,EAAI,SAAS,CAAA,EAAG;AACpC,IAAA,MAAM,IAAI,SAAA;AAAA,MACR,CAAA,+BAAA,EAAkC,SAAS,CAAA,yBAAA,EAA4B,EAAA,CAAG,MAAM,CAAA;AAAA,KAClF;AAAA,EACF;AAEA,EAAA,OAAO,EAAA;AACT;AA2BO,MAAM,gBAAA,GAAmB,CAI9B,EAAA,EACA,SAAA,KAC+C;AAC/C,EAAA,IAAI,CAAC,gBAAA,CAAiB,EAAA,EAAI,SAAS,CAAA,EAAG;AACpC,IAAA,MAAM,IAAI,SAAA;AAAA,MACR,CAAA,+BAAA,EAAkC,SAAS,CAAA,yBAAA,EAA4B,EAAA,CAAG,MAAM,CAAA;AAAA,KAClF;AAAA,EACF;AAEA,EAAA,OAAO,EAAA;AACT;AAgCO,MAAM,oBAAA,GAAuB,CAKlC,EAAA,EACA,SAAA,EACA,SAAA,KAC8D;AAC9D,EAAA,IAAI,CAAC,oBAAA,CAAqB,EAAA,EAAI,SAAA,EAAW,SAAS,CAAA,EAAG;AACnD,IAAA,MAAM,IAAI,SAAA;AAAA,MACR,mCAAmC,SAAS,CAAA,EAAA,EAAK,SAAS,CAAA,0BAAA,EAA6B,GAAG,MAAM,CAAA;AAAA,KAClG;AAAA,EACF;AAEA,EAAA,OAAO,EAAA;AACT;;;;"}

package/dist/guard/is-length-bounded-array.d.mts.map

@@ -1 +0,0 @@
-{"version":3,"file":"is-length-bounded-array.d.mts","sourceRoot":"","sources":["../../src/guard/is-length-bounded-array.mts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,eAAe,EACrB,MAAM,eAAe,CAAC;AAEvB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,gBAAgB,GAC3B,EAAE,SAAS,SAAS,OAAO,EAAE,EAC7B,SAAS,SAAS,eAAe,MAE7B,EAAE,aACK,SAAS,KACnB,EAAE,IAAI,cAAc,CAAC,SAAS,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,GAAG,EAA4B,CAAC;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AACH,eAAO,MAAM,gBAAgB,GAC3B,EAAE,SAAS,SAAS,OAAO,EAAE,EAC7B,SAAS,SAAS,eAAe,MAE7B,EAAE,aACK,SAAS,KACnB,EAAE,IAAI,cAAc,CAAC,SAAS,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,GAAG,EAA4B,CAAC;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,eAAO,MAAM,oBAAoB,GAC/B,EAAE,SAAS,SAAS,OAAO,EAAE,EAC7B,SAAS,SAAS,eAAe,EACjC,SAAS,SAAS,eAAe,MAE7B,EAAE,aACK,SAAS,aACT,SAAS,KACnB,EAAE,IAAI,kBAAkB,CAAC,SAAS,EAAE,SAAS,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,GAAG,EACd,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,eAAO,MAAM,kBAAkB,GAC7B,EAAE,SAAS,SAAS,OAAO,EAAE,EAC7B,MAAM,SAAS,eAAe,MAE1B,EAAE,UACE,MAAM,KACb,EAAE,IAAI,gBAAgB,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,GAAG,EAA0B,CAAC"}

package/dist/guard/is-length-bounded-array.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"is-length-bounded-array.mjs","sources":["../../src/guard/is-length-bounded-array.mts"],"sourcesContent":["import {\n  type BoundedLengthArray,\n  type FixedLengthArray,\n  type MaxLengthArray,\n  type MinLengthArray,\n  type SupportedLength,\n} from 'ts-type-forge';\n\n/**\n * Type guard that checks if an array has at least `minLength` elements.\n *\n * **Type Narrowing Behavior:**\n *\n * - Narrows the input to `MinLengthArray<MinLength, E>` while preserving the\n *   original array type (e.g. tuple types) via intersection.\n * - The length constraint lives only in the brand, so this stays cheap for the\n *   type checker even when the element type is large — unlike\n *   `isMinLengthTuple`, which narrows to a structural tuple type.\n * - The result participates in the length-constraint subtyping relation: for\n *   example, a value narrowed to `MinLengthArray<3, E>` is assignable to\n *   `MinLengthArray<1, E>`.\n *\n * @example\n *\n * ```ts\n * const input: readonly number[] = [0, 1, 2, 3];\n *\n * assert.isTrue(isMinLengthArray(input, 3));\n *\n * assert.isFalse(isMinLengthArray([0], 3));\n *\n * if (isMinLengthArray(input, 3)) {\n *   const history: MinLengthArray<3, number> = input;\n *\n *   const nonEmpty: MinLengthArray<1, number> = input; // OK (3 >= 1)\n * }\n * ```\n *\n * @template Xs - The input array type (tuple types are preserved).\n * @template MinLength - The minimum number of elements (inclusive).\n * @param xs - The array to check.\n * @param minLength - The minimum number of elements (inclusive).\n * @returns `true` if `xs.length >= minLength`, `false` otherwise. When `true`,\n *   TypeScript narrows `xs` to `MinLengthArray<MinLength, Xs[number]> & Xs`.\n */\nexport const isMinLengthArray = <\n  Xs extends readonly unknown[],\n  MinLength extends SupportedLength,\n>(\n  xs: Xs,\n  minLength: MinLength,\n): xs is MinLengthArray<MinLength, Xs[number]> & Xs => xs.length >= minLength;\n\n/**\n * Type guard that checks if an array has at most `maxLength` elements.\n *\n * **Type Narrowing Behavior:**\n *\n * - Narrows the input to `MaxLengthArray<MaxLength, E>` while preserving the\n *   original array type (e.g. tuple types) via intersection.\n * - The length constraint lives only in the brand, so this stays cheap for the\n *   type checker even when the element type is large — unlike\n *   `isMaxLengthTuple`, which narrows to a union of tuple types.\n * - The result participates in the length-constraint subtyping relation: for\n *   example, a value narrowed to `MaxLengthArray<8, E>` is assignable to\n *   `MaxLengthArray<16, E>`.\n *\n * @example\n *\n * ```ts\n * const input: readonly string[] = ['a', 'b', 'c'];\n *\n * assert.isTrue(isMaxLengthArray(input, 8));\n *\n * assert.isFalse(isMaxLengthArray(input, 2));\n *\n * if (isMaxLengthArray(input, 8)) {\n *   const tags: MaxLengthArray<8, string> = input;\n *\n *   const relaxed: MaxLengthArray<16, string> = input; // OK (8 <= 16)\n * }\n * ```\n *\n * @template Xs - The input array type (tuple types are preserved).\n * @template MaxLength - The maximum number of elements (inclusive).\n * @param xs - The array to check.\n * @param maxLength - The maximum number of elements (inclusive).\n * @returns `true` if `xs.length <= maxLength`, `false` otherwise. When `true`,\n *   TypeScript narrows `xs` to `MaxLengthArray<MaxLength, Xs[number]> & Xs`.\n */\nexport const isMaxLengthArray = <\n  Xs extends readonly unknown[],\n  MaxLength extends SupportedLength,\n>(\n  xs: Xs,\n  maxLength: MaxLength,\n): xs is MaxLengthArray<MaxLength, Xs[number]> & Xs => xs.length <= maxLength;\n\n/**\n * Type guard that checks if an array's length is within the inclusive range\n * `[minLength, maxLength]`.\n *\n * **Type Narrowing Behavior:**\n *\n * - Narrows the input to `BoundedLengthArray<MinLength, MaxLength, E>` while\n *   preserving the original array type (e.g. tuple types) via intersection.\n * - Since `BoundedLengthArray` is the intersection of `MinLengthArray` and\n *   `MaxLengthArray`, the narrowed value is assignable to both, and both\n *   bounds can be weakened independently.\n * - The length constraint lives only in the brand, so this stays cheap for the\n *   type checker even when the element type is large — unlike\n *   `isBoundedLengthTuple`, which narrows to a union of tuple types.\n *\n * @example\n *\n * ```ts\n * const input: readonly number[] = [1, 2, 3];\n *\n * assert.isTrue(isBoundedLengthArray(input, 1, 5));\n *\n * assert.isFalse(isBoundedLengthArray([], 1, 5));\n *\n * if (isBoundedLengthArray(input, 1, 5)) {\n *   const selection: BoundedLengthArray<1, 5, number> = input;\n *\n *   const relaxed: BoundedLengthArray<0, 100, number> = input; // OK ([1, 5] ⊆ [0, 100])\n * }\n * ```\n *\n * @template Xs - The input array type (tuple types are preserved).\n * @template MinLength - The minimum number of elements (inclusive).\n * @template MaxLength - The maximum number of elements (inclusive).\n * @param xs - The array to check.\n * @param minLength - The minimum number of elements (inclusive).\n * @param maxLength - The maximum number of elements (inclusive).\n * @returns `true` if `minLength <= xs.length && xs.length <= maxLength`,\n *   `false` otherwise. When `true`, TypeScript narrows `xs` to\n *   `BoundedLengthArray<MinLength, MaxLength, Xs[number]> & Xs`.\n */\nexport const isBoundedLengthArray = <\n  Xs extends readonly unknown[],\n  MinLength extends SupportedLength,\n  MaxLength extends SupportedLength,\n>(\n  xs: Xs,\n  minLength: MinLength,\n  maxLength: MaxLength,\n): xs is BoundedLengthArray<MinLength, MaxLength, Xs[number]> & Xs =>\n  xs.length >= minLength && xs.length <= maxLength;\n\n/**\n * Type guard that checks if an array has exactly `length` elements.\n *\n * **Type Narrowing Behavior:**\n *\n * - Narrows the input to `FixedLengthArray<Length, E>` while preserving the\n *   original array type (e.g. tuple types) via intersection.\n * - Since `FixedLengthArray<Length, E>` is defined as\n *   `BoundedLengthArray<Length, Length, E>`, the narrowed value is assignable\n *   to any `MinLengthArray<N, E>` with `N <= Length` and any\n *   `MaxLengthArray<N, E>` with `N >= Length`.\n * - The length constraint lives only in the brand, so this stays cheap for the\n *   type checker even when the element type is large — unlike\n *   `isFixedLengthTuple`, which narrows to a structural tuple type.\n *\n * @example\n *\n * ```ts\n * const input: readonly number[] = [255, 128, 0];\n *\n * assert.isTrue(isFixedLengthArray(input, 3));\n *\n * assert.isFalse(isFixedLengthArray(input, 4));\n *\n * if (isFixedLengthArray(input, 3)) {\n *   const rgb: FixedLengthArray<3, number> = input;\n *\n *   const atMost5: MaxLengthArray<5, number> = input; // OK (3 <= 5)\n * }\n * ```\n *\n * @template Xs - The input array type (tuple types are preserved).\n * @template Length - The exact number of elements.\n * @param xs - The array to check.\n * @param length - The exact number of elements.\n * @returns `true` if `xs.length === length`, `false` otherwise. When `true`,\n *   TypeScript narrows `xs` to `FixedLengthArray<Length, Xs[number]> & Xs`.\n */\nexport const isFixedLengthArray = <\n  Xs extends readonly unknown[],\n  Length extends SupportedLength,\n>(\n  xs: Xs,\n  length: Length,\n): xs is FixedLengthArray<Length, Xs[number]> & Xs => xs.length === length;\n"],"names":[],"mappings":"AA6CO,MAAM,gBAAA,GAAmB,CAI9B,EAAA,EACA,SAAA,KACqD,GAAG,MAAA,IAAU;AAuC7D,MAAM,gBAAA,GAAmB,CAI9B,EAAA,EACA,SAAA,KACqD,GAAG,MAAA,IAAU;AA2C7D,MAAM,oBAAA,GAAuB,CAKlC,EAAA,EACA,SAAA,EACA,cAEA,EAAA,CAAG,MAAA,IAAU,SAAA,IAAa,EAAA,CAAG,MAAA,IAAU;AAwClC,MAAM,kBAAA,GAAqB,CAIhC,EAAA,EACA,MAAA,KACoD,GAAG,MAAA,KAAW;;;;"}