ts-data-forge 9.0.1 → 11.0.0

package/dist/string/str.d.mts

@@ -0,0 +1,273 @@
+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 declare 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`.
+     */
+    const isMinLengthString: <S extends string, MinLength extends SupportedLength>(s: S, minLength: MinLength) => s is MinLengthString<MinLength> & S;
+    /**
+     * 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`.
+     */
+    const isMaxLengthString: <S extends string, MaxLength extends SupportedLength>(s: S, maxLength: MaxLength) => s is MaxLengthString<MaxLength> & S;
+    /**
+     * 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`.
+     */
+    const isBoundedLengthString: <S extends string, MinLength extends SupportedLength, MaxLength extends SupportedLength>(s: S, minLength: MinLength, maxLength: MaxLength) => s is BoundedLengthString<MinLength, MaxLength> & S;
+    /**
+     * 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`.
+     */
+    const isFixedLengthString: <S extends string, Length extends SupportedLength>(s: S, length: Length) => s is FixedLengthString<Length> & S;
+    /**
+     * 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`.
+     */
+    const asMinLengthString: <S extends string, MinLength extends SupportedLength>(s: S, minLength: MinLength) => MinLengthString<MinLength> & 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`.
+     */
+    const asMaxLengthString: <S extends string, MaxLength extends SupportedLength>(s: S, maxLength: MaxLength) => MaxLengthString<MaxLength> & 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`.
+     */
+    const asBoundedLengthString: <S extends string, MinLength extends SupportedLength, MaxLength extends SupportedLength>(s: S, minLength: MinLength, maxLength: MaxLength) => BoundedLengthString<MinLength, MaxLength> & 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`.
+     */
+    const asFixedLengthString: <S extends string, Length extends SupportedLength>(s: S, length: Length) => FixedLengthString<Length> & S;
+}
+//# sourceMappingURL=str.d.mts.map

package/dist/string/str.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"str.d.mts","sourceRoot":"","sources":["../../src/string/str.mts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,eAAe,EACpB,KAAK,eAAe,EACrB,MAAM,eAAe,CAAC;AAEvB;;;;;;;;GAQG;AACH,yBAAiB,GAAG,CAAC;IACnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACI,MAAM,iBAAiB,GAC5B,CAAC,SAAS,MAAM,EAChB,SAAS,SAAS,eAAe,KAE9B,CAAC,aACO,SAAS,KACnB,CAAC,IAAI,eAAe,CAAC,SAAS,CAAC,GAAG,CAA0B,CAAC;IAEhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACI,MAAM,iBAAiB,GAC5B,CAAC,SAAS,MAAM,EAChB,SAAS,SAAS,eAAe,KAE9B,CAAC,aACO,SAAS,KACnB,CAAC,IAAI,eAAe,CAAC,SAAS,CAAC,GAAG,CAA0B,CAAC;IAEhE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAqCG;IACI,MAAM,qBAAqB,GAChC,CAAC,SAAS,MAAM,EAChB,SAAS,SAAS,eAAe,EACjC,SAAS,SAAS,eAAe,KAE9B,CAAC,aACO,SAAS,aACT,SAAS,KACnB,CAAC,IAAI,mBAAmB,CAAC,SAAS,EAAE,SAAS,CAAC,GAAG,CACJ,CAAC;IAEjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACI,MAAM,mBAAmB,GAC9B,CAAC,SAAS,MAAM,EAChB,MAAM,SAAS,eAAe,KAE3B,CAAC,UACI,MAAM,KACb,CAAC,IAAI,iBAAiB,CAAC,MAAM,CAAC,GAAG,CAAwB,CAAC;IAE7D;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACI,MAAM,iBAAiB,GAC5B,CAAC,SAAS,MAAM,EAChB,SAAS,SAAS,eAAe,KAE9B,CAAC,aACO,SAAS,KACnB,eAAe,CAAC,SAAS,CAAC,GAAG,CAQ/B,CAAC;IAEF;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACI,MAAM,iBAAiB,GAC5B,CAAC,SAAS,MAAM,EAChB,SAAS,SAAS,eAAe,KAE9B,CAAC,aACO,SAAS,KACnB,eAAe,CAAC,SAAS,CAAC,GAAG,CAQ/B,CAAC;IAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACI,MAAM,qBAAqB,GAChC,CAAC,SAAS,MAAM,EAChB,SAAS,SAAS,eAAe,EACjC,SAAS,SAAS,eAAe,KAE9B,CAAC,aACO,SAAS,aACT,SAAS,KACnB,mBAAmB,CAAC,SAAS,EAAE,SAAS,CAAC,GAAG,CAQ9C,CAAC;IAEF;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACI,MAAM,mBAAmB,GAC9B,CAAC,SAAS,MAAM,EAChB,MAAM,SAAS,eAAe,KAE3B,CAAC,UACI,MAAM,KACb,iBAAiB,CAAC,MAAM,CAAC,GAAG,CAQ9B,CAAC;CACH"}

package/dist/string/str.mjs

@@ -0,0 +1,42 @@
+var Str;
+((Str2) => {
+  Str2.isMinLengthString = (s, minLength) => s.length >= minLength;
+  Str2.isMaxLengthString = (s, maxLength) => s.length <= maxLength;
+  Str2.isBoundedLengthString = (s, minLength, maxLength) => s.length >= minLength && s.length <= maxLength;
+  Str2.isFixedLengthString = (s, length) => s.length === length;
+  Str2.asMinLengthString = (s, minLength) => {
+    if (!(0, Str2.isMinLengthString)(s, minLength)) {
+      throw new TypeError(
+        `Expected a string of length >= ${minLength}, got a string of length ${s.length}`
+      );
+    }
+    return s;
+  };
+  Str2.asMaxLengthString = (s, maxLength) => {
+    if (!(0, Str2.isMaxLengthString)(s, maxLength)) {
+      throw new TypeError(
+        `Expected a string of length <= ${maxLength}, got a string of length ${s.length}`
+      );
+    }
+    return s;
+  };
+  Str2.asBoundedLengthString = (s, minLength, maxLength) => {
+    if (!(0, Str2.isBoundedLengthString)(s, minLength, maxLength)) {
+      throw new TypeError(
+        `Expected a string of length in [${minLength}, ${maxLength}], got a string of length ${s.length}`
+      );
+    }
+    return s;
+  };
+  Str2.asFixedLengthString = (s, length) => {
+    if (!(0, Str2.isFixedLengthString)(s, length)) {
+      throw new TypeError(
+        `Expected a string of length ${length}, got a string of length ${s.length}`
+      );
+    }
+    return s;
+  };
+})(Str || (Str = {}));
+
+export { Str };
+//# sourceMappingURL=str.mjs.map

package/dist/string/str.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"str.mjs","sources":["../../src/string/str.mts"],"sourcesContent":["import {\n  type BoundedLengthString,\n  type FixedLengthString,\n  type MaxLengthString,\n  type MinLengthString,\n  type SupportedLength,\n} from 'ts-type-forge';\n\n/**\n * Namespace providing type guards and runtime-checked casts for the branded\n * length-constrained string types (`MinLengthString`, `MaxLengthString`,\n * `BoundedLengthString`, `FixedLengthString`).\n *\n * Lengths are measured in UTF-16 code units (the same unit as\n * `String.prototype.length`), so characters outside the Basic Multilingual\n * Plane (e.g. emoji) count as 2.\n */\nexport namespace Str {\n  /**\n   * Type guard that checks if a string has at least `minLength` characters.\n   *\n   * **Type Narrowing Behavior:**\n   *\n   * - Narrows the input to `MinLengthString<MinLength>` while preserving the\n   *   original string type (e.g. literal types) via intersection.\n   * - The result participates in the length-constraint subtyping relation: for\n   *   example, a value narrowed to `MinLengthString<3>` is assignable to\n   *   `MinLengthString<1>` (= `NonEmptyString`).\n   *\n   * @example\n   *\n   * ```ts\n   * const input: string = 'very-secret-password';\n   *\n   * assert.isTrue(Str.isMinLengthString(input, 12));\n   *\n   * assert.isFalse(Str.isMinLengthString('short', 12));\n   *\n   * if (Str.isMinLengthString(input, 12)) {\n   *   const nonEmpty: NonEmptyString = input; // OK (12 >= 1)\n   *\n   *   assert.isTrue(nonEmpty.length >= 12);\n   * }\n   * ```\n   *\n   * @template S - The input string type (literal types are preserved).\n   * @template MinLength - The minimum number of characters (inclusive).\n   * @param s - The string to check.\n   * @param minLength - The minimum number of characters (inclusive).\n   * @returns `true` if `s.length >= minLength`, `false` otherwise. When `true`,\n   *   TypeScript narrows `s` to `MinLengthString<MinLength> & S`.\n   */\n  export const isMinLengthString = <\n    S extends string,\n    MinLength extends SupportedLength,\n  >(\n    s: S,\n    minLength: MinLength,\n  ): s is MinLengthString<MinLength> & S => s.length >= minLength;\n\n  /**\n   * Type guard that checks if a string has at most `maxLength` characters.\n   *\n   * **Type Narrowing Behavior:**\n   *\n   * - Narrows the input to `MaxLengthString<MaxLength>` while preserving the\n   *   original string type (e.g. literal types) via intersection.\n   * - The result participates in the length-constraint subtyping relation: for\n   *   example, a value narrowed to `MaxLengthString<16>` is assignable to\n   *   `MaxLengthString<32>`.\n   *\n   * @example\n   *\n   * ```ts\n   * const input: string = 'noshiro';\n   *\n   * assert.isTrue(Str.isMaxLengthString(input, 32));\n   *\n   * assert.isFalse(Str.isMaxLengthString(input, 3));\n   *\n   * if (Str.isMaxLengthString(input, 32)) {\n   *   const relaxed: MaxLengthString<64> = input; // OK (32 <= 64)\n   *\n   *   assert.isTrue(relaxed.length <= 32);\n   * }\n   * ```\n   *\n   * @template S - The input string type (literal types are preserved).\n   * @template MaxLength - The maximum number of characters (inclusive).\n   * @param s - The string to check.\n   * @param maxLength - The maximum number of characters (inclusive).\n   * @returns `true` if `s.length <= maxLength`, `false` otherwise. When `true`,\n   *   TypeScript narrows `s` to `MaxLengthString<MaxLength> & S`.\n   */\n  export const isMaxLengthString = <\n    S extends string,\n    MaxLength extends SupportedLength,\n  >(\n    s: S,\n    maxLength: MaxLength,\n  ): s is MaxLengthString<MaxLength> & S => s.length <= maxLength;\n\n  /**\n   * Type guard that checks if a string's length is within the inclusive range\n   * `[minLength, maxLength]`.\n   *\n   * **Type Narrowing Behavior:**\n   *\n   * - Narrows the input to `BoundedLengthString<MinLength, MaxLength>` while\n   *   preserving the original string type (e.g. literal types) via intersection.\n   * - Since `BoundedLengthString` is the intersection of `MinLengthString` and\n   *   `MaxLengthString`, the narrowed value is assignable to both, and both\n   *   bounds can be weakened independently.\n   *\n   * @example\n   *\n   * ```ts\n   * const input: string = 'user-12345678';\n   *\n   * assert.isTrue(Str.isBoundedLengthString(input, 8, 16));\n   *\n   * assert.isFalse(Str.isBoundedLengthString('user', 8, 16));\n   *\n   * if (Str.isBoundedLengthString(input, 8, 16)) {\n   *   const userId: BoundedLengthString<1, 255> = input; // OK ([8, 16] ⊆ [1, 255])\n   *\n   *   assert.isTrue(userId.length >= 8 && userId.length <= 16);\n   * }\n   * ```\n   *\n   * @template S - The input string type (literal types are preserved).\n   * @template MinLength - The minimum number of characters (inclusive).\n   * @template MaxLength - The maximum number of characters (inclusive).\n   * @param s - The string to check.\n   * @param minLength - The minimum number of characters (inclusive).\n   * @param maxLength - The maximum number of characters (inclusive).\n   * @returns `true` if `minLength <= s.length && s.length <= maxLength`, `false`\n   *   otherwise. When `true`, TypeScript narrows `s` to\n   *   `BoundedLengthString<MinLength, MaxLength> & S`.\n   */\n  export const isBoundedLengthString = <\n    S extends string,\n    MinLength extends SupportedLength,\n    MaxLength extends SupportedLength,\n  >(\n    s: S,\n    minLength: MinLength,\n    maxLength: MaxLength,\n  ): s is BoundedLengthString<MinLength, MaxLength> & S =>\n    s.length >= minLength && s.length <= maxLength;\n\n  /**\n   * Type guard that checks if a string has exactly `length` characters.\n   *\n   * **Type Narrowing Behavior:**\n   *\n   * - Narrows the input to `FixedLengthString<Length>` while preserving the\n   *   original string type (e.g. literal types) via intersection.\n   * - Since `FixedLengthString<Length>` is defined as\n   *   `BoundedLengthString<Length, Length>`, the narrowed value is assignable to\n   *   any `MinLengthString<N>` with `N <= Length` and any `MaxLengthString<N>`\n   *   with `N >= Length`.\n   *\n   * @example\n   *\n   * ```ts\n   * const input: string = 'JP';\n   *\n   * assert.isTrue(Str.isFixedLengthString(input, 2));\n   *\n   * assert.isFalse(Str.isFixedLengthString(input, 3));\n   *\n   * if (Str.isFixedLengthString(input, 2)) {\n   *   const atMost5: MaxLengthString<5> = input; // OK (2 <= 5)\n   *\n   *   assert.isTrue(atMost5.length === 2);\n   * }\n   * ```\n   *\n   * @template S - The input string type (literal types are preserved).\n   * @template Length - The exact number of characters.\n   * @param s - The string to check.\n   * @param length - The exact number of characters.\n   * @returns `true` if `s.length === length`, `false` otherwise. When `true`,\n   *   TypeScript narrows `s` to `FixedLengthString<Length> & S`.\n   */\n  export const isFixedLengthString = <\n    S extends string,\n    Length extends SupportedLength,\n  >(\n    s: S,\n    length: Length,\n  ): s is FixedLengthString<Length> & S => s.length === length;\n\n  /**\n   * Casts a string to `MinLengthString<MinLength>` after checking that it has\n   * at least `minLength` characters.\n   *\n   * Use this instead of writing `s as unknown as MinLengthString<N>`: the\n   * length is verified at runtime, and the original string type (e.g. literal\n   * types) is preserved via intersection.\n   *\n   * @example\n   *\n   * ```ts\n   * const password = Str.asMinLengthString('very-secret-password', 12);\n   *\n   * const nonEmpty: NonEmptyString = password; // OK (>= 1)\n   *\n   * assert.isTrue(nonEmpty.length >= 12);\n   *\n   * assert.throws(() => Str.asMinLengthString('short', 12)); // length 5 < 12\n   * ```\n   *\n   * @template S - The input string type (literal types are preserved).\n   * @template MinLength - The minimum number of characters (inclusive).\n   * @param s - The string to cast.\n   * @param minLength - The minimum number of characters (inclusive).\n   * @returns `s` typed as `MinLengthString<MinLength> & S`.\n   * @throws {TypeError} If `s.length < minLength`.\n   */\n  export const asMinLengthString = <\n    S extends string,\n    MinLength extends SupportedLength,\n  >(\n    s: S,\n    minLength: MinLength,\n  ): MinLengthString<MinLength> & S => {\n    if (!isMinLengthString(s, minLength)) {\n      throw new TypeError(\n        `Expected a string of length >= ${minLength}, got a string of length ${s.length}`,\n      );\n    }\n\n    return s;\n  };\n\n  /**\n   * Casts a string to `MaxLengthString<MaxLength>` after checking that it has\n   * at most `maxLength` characters.\n   *\n   * Use this instead of writing `s as unknown as MaxLengthString<N>`: the\n   * length is verified at runtime, and the original string type (e.g. literal\n   * types) is preserved via intersection.\n   *\n   * @example\n   *\n   * ```ts\n   * const userName = Str.asMaxLengthString('noshiro', 32);\n   *\n   * const relaxed: MaxLengthString<64> = userName; // OK (32 <= 64)\n   *\n   * assert.isTrue(relaxed.length <= 32);\n   *\n   * assert.throws(() => Str.asMaxLengthString('noshiro', 3)); // length 7 > 3\n   * ```\n   *\n   * @template S - The input string type (literal types are preserved).\n   * @template MaxLength - The maximum number of characters (inclusive).\n   * @param s - The string to cast.\n   * @param maxLength - The maximum number of characters (inclusive).\n   * @returns `s` typed as `MaxLengthString<MaxLength> & S`.\n   * @throws {TypeError} If `s.length > maxLength`.\n   */\n  export const asMaxLengthString = <\n    S extends string,\n    MaxLength extends SupportedLength,\n  >(\n    s: S,\n    maxLength: MaxLength,\n  ): MaxLengthString<MaxLength> & S => {\n    if (!isMaxLengthString(s, maxLength)) {\n      throw new TypeError(\n        `Expected a string of length <= ${maxLength}, got a string of length ${s.length}`,\n      );\n    }\n\n    return s;\n  };\n\n  /**\n   * Casts a string to `BoundedLengthString<MinLength, MaxLength>` after\n   * checking that its length is within the inclusive range\n   * `[minLength, maxLength]`.\n   *\n   * Use this instead of writing `s as unknown as BoundedLengthString<M, N>`:\n   * the length is verified at runtime, and the original string type (e.g.\n   * literal types) is preserved via intersection.\n   *\n   * @example\n   *\n   * ```ts\n   * const userId = Str.asBoundedLengthString('user-12345678', 8, 16);\n   *\n   * const relaxed: BoundedLengthString<1, 255> = userId; // OK ([8, 16] ⊆ [1, 255])\n   *\n   * assert.isTrue(relaxed.length >= 8 && relaxed.length <= 16);\n   *\n   * assert.throws(() => Str.asBoundedLengthString('user', 8, 16)); // length 4 < 8\n   * ```\n   *\n   * @template S - The input string type (literal types are preserved).\n   * @template MinLength - The minimum number of characters (inclusive).\n   * @template MaxLength - The maximum number of characters (inclusive).\n   * @param s - The string to cast.\n   * @param minLength - The minimum number of characters (inclusive).\n   * @param maxLength - The maximum number of characters (inclusive).\n   * @returns `s` typed as `BoundedLengthString<MinLength, MaxLength> & S`.\n   * @throws {TypeError} If `s.length < minLength` or `s.length > maxLength`.\n   */\n  export const asBoundedLengthString = <\n    S extends string,\n    MinLength extends SupportedLength,\n    MaxLength extends SupportedLength,\n  >(\n    s: S,\n    minLength: MinLength,\n    maxLength: MaxLength,\n  ): BoundedLengthString<MinLength, MaxLength> & S => {\n    if (!isBoundedLengthString(s, minLength, maxLength)) {\n      throw new TypeError(\n        `Expected a string of length in [${minLength}, ${maxLength}], got a string of length ${s.length}`,\n      );\n    }\n\n    return s;\n  };\n\n  /**\n   * Casts a string to `FixedLengthString<Length>` after checking that it has\n   * exactly `length` characters.\n   *\n   * Use this instead of writing `s as unknown as FixedLengthString<N>`: the\n   * length is verified at runtime, and the original string type (e.g. literal\n   * types) is preserved via intersection.\n   *\n   * @example\n   *\n   * ```ts\n   * const countryCode = Str.asFixedLengthString('JP', 2);\n   *\n   * const atMost5: MaxLengthString<5> = countryCode; // OK (2 <= 5)\n   *\n   * assert.isTrue(atMost5.length === 2);\n   *\n   * assert.throws(() => Str.asFixedLengthString('JP', 3)); // length 2 !== 3\n   * ```\n   *\n   * @template S - The input string type (literal types are preserved).\n   * @template Length - The exact number of characters.\n   * @param s - The string to cast.\n   * @param length - The exact number of characters.\n   * @returns `s` typed as `FixedLengthString<Length> & S`.\n   * @throws {TypeError} If `s.length !== length`.\n   */\n  export const asFixedLengthString = <\n    S extends string,\n    Length extends SupportedLength,\n  >(\n    s: S,\n    length: Length,\n  ): FixedLengthString<Length> & S => {\n    if (!isFixedLengthString(s, length)) {\n      throw new TypeError(\n        `Expected a string of length ${length}, got a string of length ${s.length}`,\n      );\n    }\n\n    return s;\n  };\n}\n"],"names":["Str"],"mappings":"AAiBO,IAAU;AAAA,CAAV,CAAUA,IAAAA,KAAV;AAmCE,EAAMA,KAAA,iBAAA,GAAoB,CAI/B,CAAA,EACA,SAAA,KACwC,EAAE,MAAA,IAAU,SAAA;AAoC/C,EAAMA,KAAA,iBAAA,GAAoB,CAI/B,CAAA,EACA,SAAA,KACwC,EAAE,MAAA,IAAU,SAAA;AAwC/C,EAAMA,IAAAA,CAAA,qBAAA,GAAwB,CAKnC,CAAA,EACA,SAAA,EACA,cAEA,CAAA,CAAE,MAAA,IAAU,SAAA,IAAa,CAAA,CAAE,MAAA,IAAU,SAAA;AAqChC,EAAMA,KAAA,mBAAA,GAAsB,CAIjC,CAAA,EACA,MAAA,KACuC,EAAE,MAAA,KAAW,MAAA;AA6B/C,EAAMA,IAAAA,CAAA,iBAAA,GAAoB,CAI/B,CAAA,EACA,SAAA,KACmC;AACnC,IAAA,IAAI,CAAA,IAACA,IAAAA,CAAA,iBAAA,EAAkB,CAAA,EAAG,SAAS,CAAA,EAAG;AACpC,MAAA,MAAM,IAAI,SAAA;AAAA,QACR,CAAA,+BAAA,EAAkC,SAAS,CAAA,yBAAA,EAA4B,CAAA,CAAE,MAAM,CAAA;AAAA,OACjF;AAAA,IACF;AAEA,IAAA,OAAO,CAAA;AAAA,EACT,CAAA;AA6BO,EAAMA,IAAAA,CAAA,iBAAA,GAAoB,CAI/B,CAAA,EACA,SAAA,KACmC;AACnC,IAAA,IAAI,CAAA,IAACA,IAAAA,CAAA,iBAAA,EAAkB,CAAA,EAAG,SAAS,CAAA,EAAG;AACpC,MAAA,MAAM,IAAI,SAAA;AAAA,QACR,CAAA,+BAAA,EAAkC,SAAS,CAAA,yBAAA,EAA4B,CAAA,CAAE,MAAM,CAAA;AAAA,OACjF;AAAA,IACF;AAEA,IAAA,OAAO,CAAA;AAAA,EACT,CAAA;AAgCO,EAAMA,IAAAA,CAAA,qBAAA,GAAwB,CAKnC,CAAA,EACA,WACA,SAAA,KACkD;AAClD,IAAA,IAAI,KAACA,IAAAA,CAAA,qBAAA,EAAsB,CAAA,EAAG,SAAA,EAAW,SAAS,CAAA,EAAG;AACnD,MAAA,MAAM,IAAI,SAAA;AAAA,QACR,mCAAmC,SAAS,CAAA,EAAA,EAAK,SAAS,CAAA,0BAAA,EAA6B,EAAE,MAAM,CAAA;AAAA,OACjG;AAAA,IACF;AAEA,IAAA,OAAO,CAAA;AAAA,EACT,CAAA;AA6BO,EAAMA,IAAAA,CAAA,mBAAA,GAAsB,CAIjC,CAAA,EACA,MAAA,KACkC;AAClC,IAAA,IAAI,CAAA,IAACA,IAAAA,CAAA,mBAAA,EAAoB,CAAA,EAAG,MAAM,CAAA,EAAG;AACnC,MAAA,MAAM,IAAI,SAAA;AAAA,QACR,CAAA,4BAAA,EAA+B,MAAM,CAAA,yBAAA,EAA4B,CAAA,CAAE,MAAM,CAAA;AAAA,OAC3E;AAAA,IACF;AAEA,IAAA,OAAO,CAAA;AAAA,EACT,CAAA;AAAA,CAAA,EAhWe,GAAA,KAAA,GAAA,GAAA,EAAA,CAAA,CAAA;;;;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-data-forge",
-  "version": "9.0.1",
+  "version": "11.0.0",
   "private": false,
   "keywords": [
     "typescript",
@@ -34,117 +34,55 @@
     "README.md",
     "LICENSE"
   ],
+  "dependencies": {
+    "@sindresorhus/is": "^8.1.0",
+    "ts-type-forge": "^7.0.0"
+  },
+  "devDependencies": {
+    "@emotion/react": "11.14.0",
+    "@emotion/styled": "11.14.1",
+    "@mui/material": "9.2.0",
+    "@types/react": "19.2.17",
+    "immer": "11.1.11",
+    "react": "19.2.7",
+    "typedoc": "0.28.19",
+    "typedoc-github-theme": "0.4.0"
+  },
+  "peerDependencies": {
+    "typescript": ">=4.8"
+  },
+  "engines": {
+    "node": ">=22.22.2",
+    "pnpm": ">=9.0.0"
+  },
   "scripts": {
     "build": "tsx ./scripts/cmd/build.mts",
     "build:min": "tsx ./scripts/cmd/build.mts --skip-check",
     "check:ext": "tsx ./scripts/cmd/check-ext.mts",
-    "check-all": "tsx ./scripts/cmd/check-all.mts",
-    "clean": "pnpm run /clean:.*/",
-    "clean:logs": "npx rimraf ./*.log",
-    "codemod": "run-s codemod:uncommitted:as-const fmt codemod:uncommitted:readonly fmt",
-    "codemod:diff": "run-s codemod:diff:as-const fmt codemod:diff:readonly fmt",
-    "codemod:diff:as-const": "append-as-const --diff-from origin/main '{src,scripts,samples,test}/**/*.{mts,tsx}'",
-    "codemod:diff:readonly": "convert-to-readonly --diff-from origin/main '{src,scripts,samples,test}/**/*.{mts,tsx}'",
-    "codemod:full": "run-s codemod:full:as-const fmt codemod:full:readonly fmt",
-    "codemod:full:as-const": "append-as-const '{src,scripts,samples,test}/**/*.{mts,tsx}'",
-    "codemod:full:readonly": "convert-to-readonly '{src,scripts,samples,test}/**/*.{mts,tsx}'",
-    "codemod:uncommitted:as-const": "append-as-const --uncommitted '{src,scripts,samples,test}/**/*.{mts,tsx}'",
-    "codemod:uncommitted:readonly": "convert-to-readonly --uncommitted '{src,scripts,samples,test}/**/*.{mts,tsx}'",
-    "cspell": "cspell \"**\" --gitignore --gitignore-root ./ --no-progress",
     "doc": "tsx ./scripts/cmd/gen-docs.mts",
     "doc:embed": "tsx ./scripts/cmd/embed-examples.mts",
     "doc:embed:jsdoc": "tsx ./scripts/cmd/embed-examples-in-jsdoc.mts",
     "doc:preview": "vite preview --config ./configs/vite.doc.config.mts",
     "doc:watch": "typedoc --options ./configs/typedoc.config.mjs --watch",
-    "fmt": "format-uncommitted",
-    "fmt:diff": "format-diff-from origin/main",
-    "fmt:full": "prettier --write .",
-    "gh:apply-all": "gh-apply-all",
-    "gh:apply-repository-settings": "gh-apply-repository-settings",
-    "gh:apply-rulesets": "gh-apply-rulesets",
-    "gh:apply-variables": "gh-apply-variables",
-    "gh:backup-all": "gh-backup-all",
-    "gh:backup-repository-settings": "gh-backup-repository-settings",
-    "gh:backup-rulesets": "gh-backup-rulesets",
+    "fmt": "format-uncommitted --cwd .",
+    "fmt:diff": "format-diff-from origin/main --cwd .",
+    "fmt:full": "pnpm run z:prettier .",
     "gi": "run-s gi:src fmt",
     "gi:src": "tsx scripts/cmd/gen-index.mts",
     "lint": "eslint .",
     "lint:fix": "eslint . --fix",
-    "md": "markdownlint-cli2",
     "test": "pnpm run z:vitest:node run",
     "test:browser": "pnpm run z:vitest --project='Browser' run",
     "test:cov": "pnpm run z:vitest:node run --coverage",
     "test:cov:ui": "vite preview --outDir ./coverage",
     "test:ui": "pnpm run z:vitest:node --ui",
     "testw": "pnpm run z:vitest:node watch",
-    "tsc": "node ./node_modules/typescript-native/bin/tsc --noEmit",
-    "tscw": "node ./node_modules/typescript-native/bin/tsc --noEmit --watch -p ./tsconfig.json",
-    "type-check": "node ./node_modules/typescript-native/bin/tsc --noEmit",
+    "tsc": "node ../../node_modules/typescript-native/bin/tsc --noEmit",
+    "tscw": "node ../../node_modules/typescript-native/bin/tsc --noEmit --watch -p ./tsconfig.json",
+    "type-check": "node ../../node_modules/typescript-native/bin/tsc --noEmit",
     "update-packages": "pnpm update --latest",
+    "z:prettier": "prettier --config ../../.prettierrc --ignore-path ../../.prettierignore --ignore-path ../../.gitignore --ignore-unknown --no-error-on-unmatched-pattern --write",
     "z:vitest": "vitest --config ./configs/vitest.config.mts",
     "z:vitest:node": "pnpm run z:vitest --project='Node.js'"
-  },
-  "dependencies": {
-    "@sindresorhus/is": "^8.1.0",
-    "ts-type-forge": "^5.0.0"
-  },
-  "devDependencies": {
-    "@emotion/react": "11.14.0",
-    "@emotion/styled": "11.14.1",
-    "@mui/material": "9.1.2",
-    "@rollup/plugin-replace": "6.0.3",
-    "@rollup/plugin-strip": "3.0.4",
-    "@semantic-release/changelog": "6.0.3",
-    "@semantic-release/commit-analyzer": "13.0.1",
-    "@semantic-release/exec": "7.1.0",
-    "@semantic-release/git": "10.0.1",
-    "@semantic-release/github": "12.0.9",
-    "@semantic-release/npm": "13.1.5",
-    "@semantic-release/release-notes-generator": "14.1.1",
-    "@types/node": "26.1.0",
-    "@types/react": "19.2.17",
-    "@vitest/browser-playwright": "4.1.9",
-    "@vitest/coverage-v8": "4.1.9",
-    "@vitest/ui": "4.1.9",
-    "conventional-changelog-conventionalcommits": "10.2.0",
-    "cspell": "10.0.1",
-    "dedent": "1.7.2",
-    "esbuild": "0.28.1",
-    "eslint": "9.39.4",
-    "eslint-config-typed": "5.3.0",
-    "github-settings-as-code": "1.2.9",
-    "immer": "11.1.9",
-    "jiti": "2.7.0",
-    "markdownlint": "0.41.0",
-    "markdownlint-cli2": "0.23.0",
-    "npm-run-all2": "9.0.2",
-    "playwright": "1.61.1",
-    "prettier": "3.9.4",
-    "prettier-plugin-organize-imports": "4.3.0",
-    "prettier-plugin-packagejson": "3.0.2",
-    "react": "19.2.7",
-    "rollup": "4.62.2",
-    "rollup-plugin-esbuild": "6.2.1",
-    "semantic-release": "25.0.5",
-    "ts-codemod-lib": "2.2.1",
-    "ts-repo-utils": "10.1.2",
-    "tsx": "4.22.4",
-    "typedoc": "0.28.19",
-    "typedoc-github-theme": "0.4.0",
-    "typescript": "6.0.3",
-    "typescript-native": "npm:typescript@7.0.1-rc",
-    "vite": "8.1.3",
-    "vitest": "4.1.9"
-  },
-  "peerDependencies": {
-    "typescript": ">=4.8"
-  },
-  "packageManager": "pnpm@11.10.0",
-  "engines": {
-    "node": ">=22.22.2",
-    "pnpm": ">=9.0.0"
-  },
-  "volta": {
-    "node": "26.3.1"
   }
-}
+}

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

@@ -1,6 +1,6 @@
 import {
-  type ArrayOfLength,
   type BoolOr,
+  type FixedLengthTuple,
   type Index,
   type IsUnion,
   type List,
@@ -15,6 +15,7 @@ import {
   type SafeUintWithSmallInt,
   type Seq,
   type SmallUint,
+  type StructuralPrefixLength,
 } from 'ts-type-forge';
 import { expectType } from '../../expect-type.mjs';
 import { range as rangeIterator } from '../../iterator/index.mjs';
@@ -38,7 +39,7 @@ import { type SizeType } from '../../types.mjs';
 export const zeros = <N extends SizeType.ArgArr>(
   len: N,
 ): N extends SmallUint
-  ? ArrayOfLength<N, 0>
+  ? FixedLengthTuple<N, 0>
   : N extends SizeType.ArgArrPositive
     ? NonEmptyArray<0>
     : readonly 0[] =>
@@ -88,8 +89,8 @@ export const seq = <N extends SizeType.ArgArr>(
 export const create = <N extends SizeType.ArgArr, const V>(
   len: N,
   init: V,
-): N extends SmallUint
-  ? ArrayOfLength<N, V>
+): N extends StructuralPrefixLength
+  ? FixedLengthTuple<N, V>
   : N extends SizeType.ArgArrPositive
     ? NonEmptyArray<V>
     : readonly V[] =>

package/src/array/impl/array-utils-element-access.mts

@@ -1,4 +1,4 @@
-import { type NonEmptyArray } from 'ts-type-forge';
+import { type NonEmptyTuple } from 'ts-type-forge';
 import { Optional, pipe } from '../../functional/index.mjs';
 import {
   type ArgArrayIndexWithNegative,
@@ -90,7 +90,7 @@ export const head = <const Ar extends readonly unknown[]>(
   ? None
   : Ar extends readonly [infer E, ...unknown[]]
     ? Some<E>
-    : Ar extends NonEmptyArray<infer E>
+    : Ar extends NonEmptyTuple<infer E>
       ? Some<E>
       : Optional<Ar[number]> =>
   // eslint-disable-next-line total-functions/no-unsafe-type-assertion
@@ -121,7 +121,7 @@ export const last = <const Ar extends readonly unknown[]>(
   ? None
   : Ar extends readonly [...unknown[], infer E]
     ? Some<E>
-    : Ar extends NonEmptyArray<infer E>
+    : Ar extends NonEmptyTuple<infer E>
       ? Some<E>
       : Optional<Ar[number]> =>
   // eslint-disable-next-line total-functions/no-unsafe-type-assertion

package/src/array/impl/array-utils-element-access.test.mts

@@ -1,4 +1,4 @@
-import { type MutableNonEmptyArray } from 'ts-type-forge';
+import { type NonEmptyTuple } from 'ts-type-forge';
 import { expectType } from '../../expect-type.mjs';
 import { Optional } from '../../functional/index.mjs';
 import { asInt32, asUint32 } from '../../number/index.mjs';
@@ -64,7 +64,7 @@ describe('Arr element access', () => {
     });
 
     test('case 2', () => {
-      const xs: MutableNonEmptyArray<number> = [1, 2, 3] as const;
+      const xs: NonEmptyTuple<number> = [1, 2, 3] as const;
 
       const h = head(xs);
 
@@ -134,7 +134,7 @@ describe('Arr element access', () => {
     });
 
     test('case 2', () => {
-      const xs: MutableNonEmptyArray<number> = [1, 2, 3] as const;
+      const xs: NonEmptyTuple<number> = [1, 2, 3] as const;
 
       const l = last(xs);