ts-data-forge 9.0.1 → 11.0.0

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);
+  });
+});