ts-data-forge 12.0.0 → 12.1.0

package/dist/string/str.mjs.map

@@ -1 +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;;;;"}
+{"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 NonEmptyString,\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   * Supports a curried overload: calling it with only `minLength` returns a\n   * function that casts a string, which is convenient for `pipe`/`map`.\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   * // curried version\n   * const asPassword = Str.asMinLengthString(12);\n   *\n   * assert.strictEqual(asPassword('another-secret'), 'another-secret');\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 function asMinLengthString<\n    S extends string,\n    MinLength extends SupportedLength,\n  >(s: S, minLength: MinLength): MinLengthString<MinLength> & S;\n\n  // Curried version\n  export function asMinLengthString<MinLength extends SupportedLength>(\n    minLength: MinLength,\n  ): <S extends string>(s: S) => MinLengthString<MinLength> & S;\n\n  export function asMinLengthString(\n    ...args:\n      | readonly [s: string, minLength: SupportedLength]\n      | readonly [minLength: SupportedLength]\n  ): string | ((s: string) => string) {\n    switch (args.length) {\n      case 2: {\n        const [s, minLength] = args;\n\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      case 1: {\n        const [minLength] = args;\n\n        return (s) => asMinLengthString(s, minLength);\n      }\n    }\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   * Supports a curried overload: calling it with only `maxLength` returns a\n   * function that casts a string, which is convenient for `pipe`/`map`.\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   * // curried version\n   * const asUserName = Str.asMaxLengthString(32);\n   *\n   * assert.strictEqual(asUserName('another-user'), 'another-user');\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 function asMaxLengthString<\n    S extends string,\n    MaxLength extends SupportedLength,\n  >(s: S, maxLength: MaxLength): MaxLengthString<MaxLength> & S;\n\n  // Curried version\n  export function asMaxLengthString<MaxLength extends SupportedLength>(\n    maxLength: MaxLength,\n  ): <S extends string>(s: S) => MaxLengthString<MaxLength> & S;\n\n  export function asMaxLengthString(\n    ...args:\n      | readonly [s: string, maxLength: SupportedLength]\n      | readonly [maxLength: SupportedLength]\n  ): string | ((s: string) => string) {\n    switch (args.length) {\n      case 2: {\n        const [s, maxLength] = args;\n\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      case 1: {\n        const [maxLength] = args;\n\n        return (s) => asMaxLengthString(s, maxLength);\n      }\n    }\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   * Supports a curried overload: calling it with only `minLength` and\n   * `maxLength` returns a function that casts a string, which is convenient for\n   * `pipe`/`map`.\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   * // curried version\n   * const asUserId = Str.asBoundedLengthString(8, 16);\n   *\n   * assert.strictEqual(asUserId('user-87654321'), 'user-87654321');\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 function 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\n  // Curried version\n  export function asBoundedLengthString<\n    MinLength extends SupportedLength,\n    MaxLength extends SupportedLength,\n  >(\n    minLength: MinLength,\n    maxLength: MaxLength,\n  ): <S extends string>(s: S) => BoundedLengthString<MinLength, MaxLength> & S;\n\n  export function asBoundedLengthString(\n    ...args:\n      | readonly [\n          s: string,\n          minLength: SupportedLength,\n          maxLength: SupportedLength,\n        ]\n      | readonly [minLength: SupportedLength, maxLength: SupportedLength]\n  ): string | ((s: string) => string) {\n    switch (args.length) {\n      case 3: {\n        const [s, minLength, maxLength] = args;\n\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      case 2: {\n        const [minLength, maxLength] = args;\n\n        return (s) => asBoundedLengthString(s, minLength, maxLength);\n      }\n    }\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   * Supports a curried overload: calling it with only `length` returns a\n   * function that casts a string, which is convenient for `pipe`/`map`.\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   * // curried version\n   * const asCountryCode = Str.asFixedLengthString(2);\n   *\n   * assert.strictEqual(asCountryCode('US'), 'US');\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 function asFixedLengthString<\n    S extends string,\n    Length extends SupportedLength,\n  >(s: S, length: Length): FixedLengthString<Length> & S;\n\n  // Curried version\n  export function asFixedLengthString<Length extends SupportedLength>(\n    length: Length,\n  ): <S extends string>(s: S) => FixedLengthString<Length> & S;\n\n  export function asFixedLengthString(\n    ...args:\n      | readonly [s: string, length: SupportedLength]\n      | readonly [length: SupportedLength]\n  ): string | ((s: string) => string) {\n    switch (args.length) {\n      case 2: {\n        const [s, length] = args;\n\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      case 1: {\n        const [length] = args;\n\n        return (s) => asFixedLengthString(s, length);\n      }\n    }\n  }\n\n  /**\n   * Casts a string to `NonEmptyString` after checking that it has at least one\n   * character.\n   *\n   * `NonEmptyString` is an alias of `MinLengthString<1>`, so this is the\n   * length-1 specialization of {@link asMinLengthString}. Use this instead of\n   * writing `s as unknown as NonEmptyString`: the length is verified at\n   * runtime, and the original string type (e.g. literal types) is preserved\n   * via intersection.\n   *\n   * @example\n   *\n   * ```ts\n   * const name = Str.asNonEmptyString('noshiro');\n   *\n   * const nonEmpty: NonEmptyString = name; // OK\n   *\n   * assert.isTrue(nonEmpty.length >= 1);\n   *\n   * assert.throws(() => Str.asNonEmptyString('')); // length 0 < 1\n   * ```\n   *\n   * @template S - The input string type (literal types are preserved).\n   * @param s - The string to cast.\n   * @returns `s` typed as `NonEmptyString & S`.\n   * @throws {TypeError} If `s` is empty.\n   */\n  export const asNonEmptyString = <S extends string>(\n    s: S,\n  ): NonEmptyString & S => {\n    if (!isMinLengthString(s, 1)) {\n      throw new TypeError('Expected a non-empty string, got an empty string');\n    }\n\n    return s;\n  };\n}\n"],"names":["Str"],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-data-forge",
-  "version": "12.0.0",
+  "version": "12.1.0",
   "private": false,
   "keywords": [
     "typescript",

package/src/array/impl/array-utils-length-bounded-array-cast.mts

@@ -3,6 +3,7 @@ import {
   type FixedLengthArray,
   type MaxLengthArray,
   type MinLengthArray,
+  type NonEmptyArray,
   type SupportedLength,
 } from 'ts-type-forge';
 import {
@@ -22,6 +23,9 @@ import {
  * structural tuple prefix (in-range indexed access without `undefined` under
  * `noUncheckedIndexedAccess`).
  *
+ * Supports a curried overload: calling it with only `length` returns a
+ * function that casts an array, which is convenient for `pipe`/`map`.
+ *
  * @example
  *
  * ```ts
@@ -30,6 +34,10 @@ import {
  * const atMost5: MaxLengthArray<5, number> = rgb; // OK (3 <= 5)
  * const red: number = rgb[0]; // OK — no `undefined`
  *
+ * // curried version
+ * const asRgb = Arr.asFixedLengthArray(3);
+ * const green = asRgb([0, 255, 0]);
+ *
  * // Arr.asFixedLengthArray([255, 128], 3); // throws TypeError
  * ```
  *
@@ -40,21 +48,43 @@ import {
  * @returns `xs` typed as `FixedLengthArray<Length, Xs[number]> & Xs`.
  * @throws {TypeError} If `xs.length !== length`.
  */
-export const asFixedLengthArray = <
+export function asFixedLengthArray<
   Xs extends readonly unknown[],
   Length extends SupportedLength,
->(
-  xs: Xs,
+>(xs: Xs, length: Length): FixedLengthArray<Length, Xs[number]> & Xs;
+
+// Curried version
+export function asFixedLengthArray<Length extends SupportedLength>(
   length: Length,
-): FixedLengthArray<Length, Xs[number]> & Xs => {
-  if (!isFixedLengthArray(xs, length)) {
-    throw new TypeError(
-      `Expected an array of length ${length}, got an array of length ${xs.length}`,
-    );
-  }
+): <Xs extends readonly unknown[]>(
+  xs: Xs,
+) => FixedLengthArray<Length, Xs[number]> & Xs;
 
-  return xs;
-};
+export function asFixedLengthArray<E>(
+  ...args:
+    | readonly [xs: readonly E[], length: SupportedLength]
+    | readonly [length: SupportedLength]
+): readonly E[] | ((xs: readonly E[]) => readonly E[]) {
+  switch (args.length) {
+    case 2: {
+      const [xs, length] = args;
+
+      if (!isFixedLengthArray(xs, length)) {
+        throw new TypeError(
+          `Expected an array of length ${length}, got an array of length ${xs.length}`,
+        );
+      }
+
+      return xs;
+    }
+
+    case 1: {
+      const [length] = args;
+
+      return (xs) => asFixedLengthArray(xs, length);
+    }
+  }
+}
 
 /**
  * Casts an array to `MinLengthArray<MinLength, E>` after checking that it has
@@ -66,6 +96,9 @@ export const asFixedLengthArray = <
  * structural tuple prefix (indexed access below `min(N, 10)` without
  * `undefined` under `noUncheckedIndexedAccess`).
  *
+ * Supports a curried overload: calling it with only `minLength` returns a
+ * function that casts an array, which is convenient for `pipe`/`map`.
+ *
  * @example
  *
  * ```ts
@@ -74,6 +107,10 @@ export const asFixedLengthArray = <
  * const nonEmpty: MinLengthArray<1, number> = history; // OK (3 >= 1)
  * const first: number = history[0]; // OK — no `undefined`
  *
+ * // curried version
+ * const asHistory = Arr.asMinLengthArray(3);
+ * const next = asHistory([4, 5, 6, 7]);
+ *
  * // Arr.asMinLengthArray([0], 3); // throws TypeError
  * ```
  *
@@ -84,21 +121,43 @@ export const asFixedLengthArray = <
  * @returns `xs` typed as `MinLengthArray<MinLength, Xs[number]> & Xs`.
  * @throws {TypeError} If `xs.length < minLength`.
  */
-export const asMinLengthArray = <
+export function asMinLengthArray<
   Xs extends readonly unknown[],
   MinLength extends SupportedLength,
->(
-  xs: Xs,
+>(xs: Xs, minLength: MinLength): MinLengthArray<MinLength, Xs[number]> & Xs;
+
+// Curried version
+export function asMinLengthArray<MinLength extends SupportedLength>(
   minLength: MinLength,
-): MinLengthArray<MinLength, Xs[number]> & Xs => {
-  if (!isMinLengthArray(xs, minLength)) {
-    throw new TypeError(
-      `Expected an array of length >= ${minLength}, got an array of length ${xs.length}`,
-    );
-  }
+): <Xs extends readonly unknown[]>(
+  xs: Xs,
+) => MinLengthArray<MinLength, Xs[number]> & Xs;
 
-  return xs;
-};
+export function asMinLengthArray<E>(
+  ...args:
+    | readonly [xs: readonly E[], minLength: SupportedLength]
+    | readonly [minLength: SupportedLength]
+): readonly E[] | ((xs: readonly E[]) => readonly E[]) {
+  switch (args.length) {
+    case 2: {
+      const [xs, minLength] = args;
+
+      if (!isMinLengthArray(xs, minLength)) {
+        throw new TypeError(
+          `Expected an array of length >= ${minLength}, got an array of length ${xs.length}`,
+        );
+      }
+
+      return xs;
+    }
+
+    case 1: {
+      const [minLength] = args;
+
+      return (xs) => asMinLengthArray(xs, minLength);
+    }
+  }
+}
 
 /**
  * Casts an array to `MaxLengthArray<MaxLength, E>` after checking that it has
@@ -108,6 +167,9 @@ export const asMinLengthArray = <
  * length is verified at runtime, and the original array type (e.g. tuple
  * types) is preserved via intersection.
  *
+ * Supports a curried overload: calling it with only `maxLength` returns a
+ * function that casts an array, which is convenient for `pipe`/`map`.
+ *
  * @example
  *
  * ```ts
@@ -115,6 +177,10 @@ export const asMinLengthArray = <
  *
  * const relaxed: MaxLengthArray<16, string> = tags; // OK (8 <= 16)
  *
+ * // curried version
+ * const asTags = Arr.asMaxLengthArray(8);
+ * const more = asTags(['d', 'e']);
+ *
  * // Arr.asMaxLengthArray(['a', 'b', 'c'], 2); // throws TypeError
  * ```
  *
@@ -125,21 +191,43 @@ export const asMinLengthArray = <
  * @returns `xs` typed as `MaxLengthArray<MaxLength, Xs[number]> & Xs`.
  * @throws {TypeError} If `xs.length > maxLength`.
  */
-export const asMaxLengthArray = <
+export function asMaxLengthArray<
   Xs extends readonly unknown[],
   MaxLength extends SupportedLength,
->(
-  xs: Xs,
+>(xs: Xs, maxLength: MaxLength): MaxLengthArray<MaxLength, Xs[number]> & Xs;
+
+// Curried version
+export function asMaxLengthArray<MaxLength extends SupportedLength>(
   maxLength: MaxLength,
-): MaxLengthArray<MaxLength, Xs[number]> & Xs => {
-  if (!isMaxLengthArray(xs, maxLength)) {
-    throw new TypeError(
-      `Expected an array of length <= ${maxLength}, got an array of length ${xs.length}`,
-    );
-  }
+): <Xs extends readonly unknown[]>(
+  xs: Xs,
+) => MaxLengthArray<MaxLength, Xs[number]> & Xs;
 
-  return xs;
-};
+export function asMaxLengthArray<E>(
+  ...args:
+    | readonly [xs: readonly E[], maxLength: SupportedLength]
+    | readonly [maxLength: SupportedLength]
+): readonly E[] | ((xs: readonly E[]) => readonly E[]) {
+  switch (args.length) {
+    case 2: {
+      const [xs, maxLength] = args;
+
+      if (!isMaxLengthArray(xs, maxLength)) {
+        throw new TypeError(
+          `Expected an array of length <= ${maxLength}, got an array of length ${xs.length}`,
+        );
+      }
+
+      return xs;
+    }
+
+    case 1: {
+      const [maxLength] = args;
+
+      return (xs) => asMaxLengthArray(xs, maxLength);
+    }
+  }
+}
 
 /**
  * Casts an array to `BoundedLengthArray<MinLength, MaxLength, E>` after
@@ -151,6 +239,10 @@ export const asMaxLengthArray = <
  * at runtime, and the original array type (e.g. tuple types) is preserved via
  * intersection.
  *
+ * Supports a curried overload: calling it with only `minLength` and
+ * `maxLength` returns a function that casts an array, which is convenient for
+ * `pipe`/`map`.
+ *
  * @example
  *
  * ```ts
@@ -158,6 +250,10 @@ export const asMaxLengthArray = <
  *
  * const relaxed: BoundedLengthArray<0, 100, number> = selection; // OK
  *
+ * // curried version
+ * const asSelection = Arr.asBoundedLengthArray(1, 5);
+ * const next = asSelection([4, 5]);
+ *
  * // Arr.asBoundedLengthArray([], 1, 5); // throws TypeError
  * ```
  *
@@ -171,7 +267,7 @@ export const asMaxLengthArray = <
  *   `BoundedLengthArray<MinLength, MaxLength, Xs[number]> & Xs`.
  * @throws {TypeError} If `xs.length < minLength || xs.length > maxLength`.
  */
-export const asBoundedLengthArray = <
+export function asBoundedLengthArray<
   Xs extends readonly unknown[],
   MinLength extends SupportedLength,
   MaxLength extends SupportedLength,
@@ -179,11 +275,80 @@ export const asBoundedLengthArray = <
   xs: Xs,
   minLength: MinLength,
   maxLength: MaxLength,
-): BoundedLengthArray<MinLength, MaxLength, Xs[number]> & Xs => {
-  if (!isBoundedLengthArray(xs, minLength, maxLength)) {
-    throw new TypeError(
-      `Expected an array of length in [${minLength}, ${maxLength}], got an array of length ${xs.length}`,
-    );
+): BoundedLengthArray<MinLength, MaxLength, Xs[number]> & Xs;
+
+// Curried version
+export function asBoundedLengthArray<
+  MinLength extends SupportedLength,
+  MaxLength extends SupportedLength,
+>(
+  minLength: MinLength,
+  maxLength: MaxLength,
+): <Xs extends readonly unknown[]>(
+  xs: Xs,
+) => BoundedLengthArray<MinLength, MaxLength, Xs[number]> & Xs;
+
+export function asBoundedLengthArray<E>(
+  ...args:
+    | readonly [
+        xs: readonly E[],
+        minLength: SupportedLength,
+        maxLength: SupportedLength,
+      ]
+    | readonly [minLength: SupportedLength, maxLength: SupportedLength]
+): readonly E[] | ((xs: readonly E[]) => readonly E[]) {
+  switch (args.length) {
+    case 3: {
+      const [xs, minLength, maxLength] = args;
+
+      if (!isBoundedLengthArray(xs, minLength, maxLength)) {
+        throw new TypeError(
+          `Expected an array of length in [${minLength}, ${maxLength}], got an array of length ${xs.length}`,
+        );
+      }
+
+      return xs;
+    }
+
+    case 2: {
+      const [minLength, maxLength] = args;
+
+      return (xs) => asBoundedLengthArray(xs, minLength, maxLength);
+    }
+  }
+}
+
+/**
+ * Casts an array to `NonEmptyArray<E>` after checking that it has at least one
+ * element.
+ *
+ * `NonEmptyArray<E>` is an alias of `MinLengthArray<1, E>`, so this is the
+ * length-1 specialization of {@link asMinLengthArray}. Use this instead of
+ * writing `xs as unknown as NonEmptyArray<E>`: the length is verified at
+ * runtime, and the original array type (e.g. tuple types) is preserved via
+ * intersection, so the result also benefits from the structural tuple prefix
+ * (`xs[0]` without `undefined` under `noUncheckedIndexedAccess`).
+ *
+ * @example
+ *
+ * ```ts
+ * const history = Arr.asNonEmptyArray([0, 1, 2, 3]);
+ *
+ * const first: number = history[0]; // OK — no `undefined`
+ *
+ * // Arr.asNonEmptyArray([]); // throws TypeError
+ * ```
+ *
+ * @template Xs - The input array type (tuple types are preserved).
+ * @param xs - The array to cast.
+ * @returns `xs` typed as `NonEmptyArray<Xs[number]> & Xs`.
+ * @throws {TypeError} If `xs` is empty.
+ */
+export const asNonEmptyArray = <Xs extends readonly unknown[]>(
+  xs: Xs,
+): NonEmptyArray<Xs[number]> & Xs => {
+  if (!isMinLengthArray(xs, 1)) {
+    throw new TypeError('Expected a non-empty array, got an empty array');
   }
 
   return xs;

package/src/array/impl/array-utils-length-bounded-array-cast.test.mts

@@ -3,6 +3,7 @@ import {
   type FixedLengthArray,
   type MaxLengthArray,
   type MinLengthArray,
+  type NonEmptyArray,
 } from 'ts-type-forge';
 import { expectType } from '../../expect-type.mjs';
 import {
@@ -10,6 +11,7 @@ import {
   asFixedLengthArray,
   asMaxLengthArray,
   asMinLengthArray,
+  asNonEmptyArray,
 } from './array-utils-length-bounded-array-cast.mjs';
 
 describe(asFixedLengthArray, () => {
@@ -47,6 +49,29 @@ describe(asFixedLengthArray, () => {
 
     expectType<typeof casted, FixedLengthArray<3, 1 | 2 | 3>>('<=');
   });
+
+  test('curried version casts an array', () => {
+    const xs: readonly number[] = [0, 1, 2, 3] as const;
+
+    const casted = asFixedLengthArray(4)(xs);
+
+    expect(casted).toBe(xs);
+
+    expectType<typeof casted, FixedLengthArray<4, number>>('<=');
+
+    // in-range indexed access does not include `undefined`
+    const _first = casted[0];
+
+    expectType<typeof _first, number>('=');
+  });
+
+  test('curried version throws when the length does not match', () => {
+    expect(() => asFixedLengthArray(4)([0, 1, 2])).toThrow(TypeError);
+
+    expect(() => asFixedLengthArray(4)([0, 1, 2])).toThrow(
+      'Expected an array of length 4, got an array of length 3',
+    );
+  });
 });
 
 describe(asMinLengthArray, () => {
@@ -69,6 +94,26 @@ describe(asMinLengthArray, () => {
       'Expected an array of length >= 3, got an array of length 1',
     );
   });
+
+  test('curried version casts an array', () => {
+    const xs: readonly number[] = [0, 1, 2, 3] as const;
+
+    const casted = asMinLengthArray(3)(xs);
+
+    expect(casted).toBe(xs);
+
+    expectType<typeof casted, MinLengthArray<3, number>>('<=');
+
+    expectType<typeof casted, MinLengthArray<1, number>>('<='); // 3 >= 1
+  });
+
+  test('curried version throws when the array is too short', () => {
+    expect(() => asMinLengthArray(3)([0])).toThrow(TypeError);
+
+    expect(() => asMinLengthArray(3)([0])).toThrow(
+      'Expected an array of length >= 3, got an array of length 1',
+    );
+  });
 });
 
 describe(asMaxLengthArray, () => {
@@ -91,6 +136,26 @@ describe(asMaxLengthArray, () => {
       'Expected an array of length <= 2, got an array of length 3',
     );
   });
+
+  test('curried version casts an array', () => {
+    const xs: readonly number[] = [0, 1, 2] as const;
+
+    const casted = asMaxLengthArray(8)(xs);
+
+    expect(casted).toBe(xs);
+
+    expectType<typeof casted, MaxLengthArray<8, number>>('<=');
+
+    expectType<typeof casted, MaxLengthArray<16, number>>('<='); // 8 <= 16
+  });
+
+  test('curried version throws when the array is too long', () => {
+    expect(() => asMaxLengthArray(2)([0, 1, 2])).toThrow(TypeError);
+
+    expect(() => asMaxLengthArray(2)([0, 1, 2])).toThrow(
+      'Expected an array of length <= 2, got an array of length 3',
+    );
+  });
 });
 
 describe(asBoundedLengthArray, () => {
@@ -115,4 +180,65 @@ describe(asBoundedLengthArray, () => {
       'Expected an array of length in [1, 5], got an array of length 6',
     );
   });
+
+  test('curried version casts an array', () => {
+    const xs: readonly number[] = [1, 2, 3] as const;
+
+    const casted = asBoundedLengthArray(1, 5)(xs);
+
+    expect(casted).toBe(xs);
+
+    expectType<typeof casted, BoundedLengthArray<1, 5, number>>('<=');
+
+    expectType<typeof casted, MinLengthArray<1, number>>('<=');
+
+    expectType<typeof casted, MaxLengthArray<5, number>>('<=');
+  });
+
+  test('curried version throws when the length is out of the range', () => {
+    expect(() => asBoundedLengthArray(1, 5)([])).toThrow(TypeError);
+
+    expect(() => asBoundedLengthArray(1, 5)([1, 2, 3, 4, 5, 6])).toThrow(
+      'Expected an array of length in [1, 5], got an array of length 6',
+    );
+  });
+});
+
+describe(asNonEmptyArray, () => {
+  test('should return the input when the array is non-empty', () => {
+    const xs: readonly number[] = [0, 1, 2, 3] as const;
+
+    const casted = asNonEmptyArray(xs);
+
+    expect(casted).toBe(xs);
+
+    expectType<typeof casted, NonEmptyArray<number>>('<=');
+
+    expectType<typeof casted, MinLengthArray<1, number>>('<=');
+
+    // in-range indexed access does not include `undefined`
+    const _first = casted[0];
+
+    expectType<typeof _first, number>('=');
+  });
+
+  test('should throw when the array is empty', () => {
+    expect(() => asNonEmptyArray([])).toThrow(TypeError);
+
+    expect(() => asNonEmptyArray([])).toThrow(
+      'Expected a non-empty array, got an empty array',
+    );
+  });
+
+  test('should preserve the original array type', () => {
+    const tuple = [1, 2, 3] as const;
+
+    const casted = asNonEmptyArray(tuple);
+
+    expect(casted).toBe(tuple);
+
+    expectType<typeof casted, readonly [1, 2, 3]>('<=');
+
+    expectType<typeof casted, NonEmptyArray<1 | 2 | 3>>('<=');
+  });
 });