ts-data-forge 11.0.1 → 12.1.0

package/README.md

@@ -350,11 +350,11 @@ assert.isTrue(positiveInt === 10);
 // Type-safe arithmetic with automatic clamping
 const sum = Int16.add(int16, asInt16(2000)); // Int16 (3000)
 
-const clamped = Int16.clamp(100_000); // Int16 (32767 - clamped to MAX_VALUE)
+const coerced = Int16.fromNumber(100_000); // Int16 (32767 - saturated to MAX_VALUE)
 
 assert.isTrue(sum === 3000);
 
-assert.isTrue(clamped === 32_767);
+assert.isTrue(coerced === 32_767);
 
 // Safe division with non-zero types
 const ratio = Num.divInt(asNonZeroInt(10), nonZeroInt); // No division by zero risk

package/dist/array/impl/array-utils-length-bounded-array-cast.d.mts

@@ -1,4 +1,4 @@
-import { type BoundedLengthArray, type FixedLengthArray, type MaxLengthArray, type MinLengthArray, type SupportedLength } from 'ts-type-forge';
+import { type BoundedLengthArray, type FixedLengthArray, type MaxLengthArray, type MinLengthArray, type NonEmptyArray, type SupportedLength } from 'ts-type-forge';
 /**
  * Casts an array to `FixedLengthArray<Length, E>` after checking that it has
  * exactly `length` elements.
@@ -9,6 +9,9 @@ import { type BoundedLengthArray, type FixedLengthArray, type MaxLengthArray, ty
  * 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
@@ -17,6 +20,10 @@ import { type BoundedLengthArray, type FixedLengthArray, type MaxLengthArray, ty
  * 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
  * ```
  *
@@ -27,7 +34,8 @@ import { type BoundedLengthArray, type FixedLengthArray, type MaxLengthArray, ty
  * @returns `xs` typed as `FixedLengthArray<Length, Xs[number]> & Xs`.
  * @throws {TypeError} If `xs.length !== length`.
  */
-export declare const asFixedLengthArray: <Xs extends readonly unknown[], Length extends SupportedLength>(xs: Xs, length: Length) => FixedLengthArray<Length, Xs[number]> & Xs;
+export declare function asFixedLengthArray<Xs extends readonly unknown[], Length extends SupportedLength>(xs: Xs, length: Length): FixedLengthArray<Length, Xs[number]> & Xs;
+export declare function asFixedLengthArray<Length extends SupportedLength>(length: Length): <Xs extends readonly unknown[]>(xs: Xs) => FixedLengthArray<Length, Xs[number]> & Xs;
 /**
  * Casts an array to `MinLengthArray<MinLength, E>` after checking that it has
  * at least `minLength` elements.
@@ -38,6 +46,9 @@ export declare const asFixedLengthArray: <Xs extends readonly unknown[], Length
  * 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
@@ -46,6 +57,10 @@ export declare const asFixedLengthArray: <Xs extends readonly unknown[], Length
  * 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
  * ```
  *
@@ -56,7 +71,8 @@ export declare const asFixedLengthArray: <Xs extends readonly unknown[], Length
  * @returns `xs` typed as `MinLengthArray<MinLength, Xs[number]> & Xs`.
  * @throws {TypeError} If `xs.length < minLength`.
  */
-export declare const asMinLengthArray: <Xs extends readonly unknown[], MinLength extends SupportedLength>(xs: Xs, minLength: MinLength) => MinLengthArray<MinLength, Xs[number]> & Xs;
+export declare function asMinLengthArray<Xs extends readonly unknown[], MinLength extends SupportedLength>(xs: Xs, minLength: MinLength): MinLengthArray<MinLength, Xs[number]> & Xs;
+export declare function asMinLengthArray<MinLength extends SupportedLength>(minLength: MinLength): <Xs extends readonly unknown[]>(xs: Xs) => MinLengthArray<MinLength, Xs[number]> & Xs;
 /**
  * Casts an array to `MaxLengthArray<MaxLength, E>` after checking that it has
  * at most `maxLength` elements.
@@ -65,6 +81,9 @@ export declare const asMinLengthArray: <Xs extends readonly unknown[], MinLength
  * 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
@@ -72,6 +91,10 @@ export declare const asMinLengthArray: <Xs extends readonly unknown[], MinLength
  *
  * 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
  * ```
  *
@@ -82,7 +105,8 @@ export declare const asMinLengthArray: <Xs extends readonly unknown[], MinLength
  * @returns `xs` typed as `MaxLengthArray<MaxLength, Xs[number]> & Xs`.
  * @throws {TypeError} If `xs.length > maxLength`.
  */
-export declare const asMaxLengthArray: <Xs extends readonly unknown[], MaxLength extends SupportedLength>(xs: Xs, maxLength: MaxLength) => MaxLengthArray<MaxLength, Xs[number]> & Xs;
+export declare function asMaxLengthArray<Xs extends readonly unknown[], MaxLength extends SupportedLength>(xs: Xs, maxLength: MaxLength): MaxLengthArray<MaxLength, Xs[number]> & Xs;
+export declare function asMaxLengthArray<MaxLength extends SupportedLength>(maxLength: MaxLength): <Xs extends readonly unknown[]>(xs: Xs) => MaxLengthArray<MaxLength, Xs[number]> & Xs;
 /**
  * Casts an array to `BoundedLengthArray<MinLength, MaxLength, E>` after
  * checking that its length is within the inclusive range
@@ -93,6 +117,10 @@ export declare const asMaxLengthArray: <Xs extends readonly unknown[], MaxLength
  * 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
@@ -100,6 +128,10 @@ export declare const asMaxLengthArray: <Xs extends readonly unknown[], MaxLength
  *
  * 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
  * ```
  *
@@ -113,5 +145,33 @@ export declare const asMaxLengthArray: <Xs extends readonly unknown[], MaxLength
  *   `BoundedLengthArray<MinLength, MaxLength, Xs[number]> & Xs`.
  * @throws {TypeError} If `xs.length < minLength || xs.length > maxLength`.
  */
-export declare const asBoundedLengthArray: <Xs extends readonly unknown[], MinLength extends SupportedLength, MaxLength extends SupportedLength>(xs: Xs, minLength: MinLength, maxLength: MaxLength) => BoundedLengthArray<MinLength, MaxLength, Xs[number]> & Xs;
+export declare function asBoundedLengthArray<Xs extends readonly unknown[], MinLength extends SupportedLength, MaxLength extends SupportedLength>(xs: Xs, minLength: MinLength, maxLength: MaxLength): BoundedLengthArray<MinLength, MaxLength, Xs[number]> & Xs;
+export declare function asBoundedLengthArray<MinLength extends SupportedLength, MaxLength extends SupportedLength>(minLength: MinLength, maxLength: MaxLength): <Xs extends readonly unknown[]>(xs: Xs) => BoundedLengthArray<MinLength, MaxLength, Xs[number]> & Xs;
+/**
+ * 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 declare const asNonEmptyArray: <Xs extends readonly unknown[]>(xs: Xs) => NonEmptyArray<Xs[number]> & Xs;
 //# sourceMappingURL=array-utils-length-bounded-array-cast.d.mts.map

package/dist/array/impl/array-utils-length-bounded-array-cast.d.mts.map

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

package/dist/array/impl/array-utils-length-bounded-array-cast.mjs

@@ -1,37 +1,79 @@
 import { isBoundedLengthArray, isFixedLengthArray, isMaxLengthArray, isMinLengthArray } from './array-utils-length-bounded-array-guard.mjs';
 
-const asFixedLengthArray = (xs, length) => {
-  if (!isFixedLengthArray(xs, length)) {
-    throw new TypeError(
-      `Expected an array of length ${length}, got an array of length ${xs.length}`
-    );
+function asFixedLengthArray(...args) {
+  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);
+    }
   }
-  return xs;
-};
-const asMinLengthArray = (xs, minLength) => {
-  if (!isMinLengthArray(xs, minLength)) {
-    throw new TypeError(
-      `Expected an array of length >= ${minLength}, got an array of length ${xs.length}`
-    );
+}
+function asMinLengthArray(...args) {
+  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);
+    }
   }
-  return xs;
-};
-const asMaxLengthArray = (xs, maxLength) => {
-  if (!isMaxLengthArray(xs, maxLength)) {
-    throw new TypeError(
-      `Expected an array of length <= ${maxLength}, got an array of length ${xs.length}`
-    );
+}
+function asMaxLengthArray(...args) {
+  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);
+    }
   }
-  return xs;
-};
-const asBoundedLengthArray = (xs, minLength, maxLength) => {
-  if (!isBoundedLengthArray(xs, minLength, maxLength)) {
-    throw new TypeError(
-      `Expected an array of length in [${minLength}, ${maxLength}], got an array of length ${xs.length}`
-    );
+}
+function asBoundedLengthArray(...args) {
+  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);
+    }
+  }
+}
+const asNonEmptyArray = (xs) => {
+  if (!isMinLengthArray(xs, 1)) {
+    throw new TypeError("Expected a non-empty array, got an empty array");
   }
   return xs;
 };
 
-export { asBoundedLengthArray, asFixedLengthArray, asMaxLengthArray, asMinLengthArray };
+export { asBoundedLengthArray, asFixedLengthArray, asMaxLengthArray, asMinLengthArray, asNonEmptyArray };
 //# sourceMappingURL=array-utils-length-bounded-array-cast.mjs.map

package/dist/array/impl/array-utils-length-bounded-array-cast.mjs.map

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

package/dist/array/impl/index.mjs

@@ -1,7 +1,7 @@
 export { copy, create, generate, generateAsync, newArray, range, seq, zeros } from './array-utils-creation.mjs';
 export { at, first, head, last } from './array-utils-element-access.mjs';
 export { entries, indices, keys, values } from './array-utils-iterators.mjs';
-export { asBoundedLengthArray, asFixedLengthArray, asMaxLengthArray, asMinLengthArray } from './array-utils-length-bounded-array-cast.mjs';
+export { asBoundedLengthArray, asFixedLengthArray, asMaxLengthArray, asMinLengthArray, asNonEmptyArray } from './array-utils-length-bounded-array-cast.mjs';
 export { isBoundedLengthArray, isFixedLengthArray, isMaxLengthArray, isMinLengthArray } from './array-utils-length-bounded-array-guard.mjs';
 export { set, toFilled, toInserted, toPushed, toRangeFilled, toRemoved, toUnshifted, toUpdated } from './array-utils-modification.mjs';
 export { count, countBy, foldl, foldr, join, max, maxBy, min, minBy, reduce, reduceRight, sum, sumBy } from './array-utils-reducing-value.mjs';

package/dist/number/branded-types/int16.d.mts

@@ -52,11 +52,13 @@ export declare const Int16: {
      */
     readonly is: (a: number) => a is TtfImported_Int16;
     /**
-     * The smallest value representable as `Int16`.
+     * The smallest value representable as `Int16` (the lower saturation target of
+     * `fromNumber`).
      */
     readonly MIN_VALUE: number;
     /**
-     * The largest value representable as `Int16`.
+     * The largest value representable as `Int16` (the upper saturation target of
+     * `fromNumber`).
      */
     readonly MAX_VALUE: number;
     /**
@@ -83,13 +85,16 @@ export declare const Int16: {
      */
     readonly max: (...values: readonly import("ts-type-forge").WithSmallInt<TtfImported_Int16>[]) => TtfImported_Int16;
     /**
-     * Clamps a `number` into the `Int16` range, rounding to the nearest integer
-     * and constraining the result to `[MIN_VALUE, MAX_VALUE]`.
+     * Converts an arbitrary `number` into an `Int16`, rounding to the nearest
+     * integer and saturating the result into the range `[MIN_VALUE, MAX_VALUE]`.
      *
-     * @param value - The value to clamp
-     * @returns The clamped value as an `Int16`
+     * Unlike `asInt16`, this is total: out-of-range inputs are clamped to the
+     * nearest representable `Int16` instead of throwing.
+     *
+     * @param value - The value to convert
+     * @returns The value as an `Int16`
      */
-    readonly clamp: (x: number) => TtfImported_Int16;
+    readonly fromNumber: (x: number) => TtfImported_Int16;
     /**
      * Generates a random `Int16` within the given range.
      *

package/dist/number/branded-types/int16.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"int16.d.mts","sourceRoot":"","sources":["../../../src/number/branded-types/int16.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,IAAI,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAIhE,MAAM,MAAM,KAAK,GAAG,iBAAiB,CAAC;AAgCtC;;;;;;;;GAQG;AACH,eAAO,MAAM,OAAO,uCAAK,CAAC;AAE1B;;;;;;;;;GASG;AACH,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;MAAW,CAAC;AAEhC;;;;;GAKG;AACH,eAAO,MAAM,KAAK;IAChB;;;;;;OAMG;;IAGH;;OAEG;;IAGH;;OAEG;;IAGH;;;;;;;OAOG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;;IAGH;;;;;;OAMG;;IAGH;;;;;;;;OAQG;;IAGH;;;;;;;OAOG;;IAGH;;;;;;OAMG;;IAGH;;;;;;OAMG;;IAGH;;;;;;OAMG;;IAGH;;;;;;;OAOG;;;;;;;;;;;;;;;;;;CAEK,CAAC"}
+{"version":3,"file":"int16.d.mts","sourceRoot":"","sources":["../../../src/number/branded-types/int16.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,IAAI,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAIhE,MAAM,MAAM,KAAK,GAAG,iBAAiB,CAAC;AAgCtC;;;;;;;;GAQG;AACH,eAAO,MAAM,OAAO,uCAAK,CAAC;AAE1B;;;;;;;;;GASG;AACH,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;MAAW,CAAC;AAEhC;;;;;GAKG;AACH,eAAO,MAAM,KAAK;IAChB;;;;;;OAMG;;IAGH;;;OAGG;;IAGH;;;OAGG;;IAGH;;;;;;;OAOG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;;IAGH;;;;;;;;;OASG;;IAGH;;;;;;;;OAQG;;IAGH;;;;;;;OAOG;;IAGH;;;;;;OAMG;;IAGH;;;;;;OAMG;;IAGH;;;;;;OAMG;;IAGH;;;;;;;OAOG;;;;;;;;;;;;;;;;;;CAEK,CAAC"}

package/dist/number/branded-types/int16.mjs

@@ -7,8 +7,8 @@ const {
   abs,
   add,
   castType,
-  clamp,
   div,
+  fromNumber,
   is,
   max: max_,
   min: min_,
@@ -34,11 +34,13 @@ const Int16 = {
    */
   is,
   /**
-   * The smallest value representable as `Int16`.
+   * The smallest value representable as `Int16` (the lower saturation target of
+   * `fromNumber`).
    */
   MIN_VALUE,
   /**
-   * The largest value representable as `Int16`.
+   * The largest value representable as `Int16` (the upper saturation target of
+   * `fromNumber`).
    */
   MAX_VALUE,
   /**
@@ -65,13 +67,16 @@ const Int16 = {
    */
   max: max_,
   /**
-   * Clamps a `number` into the `Int16` range, rounding to the nearest integer
-   * and constraining the result to `[MIN_VALUE, MAX_VALUE]`.
+   * Converts an arbitrary `number` into an `Int16`, rounding to the nearest
+   * integer and saturating the result into the range `[MIN_VALUE, MAX_VALUE]`.
    *
-   * @param value - The value to clamp
-   * @returns The clamped value as an `Int16`
+   * Unlike `asInt16`, this is total: out-of-range inputs are clamped to the
+   * nearest representable `Int16` instead of throwing.
+   *
+   * @param value - The value to convert
+   * @returns The value as an `Int16`
    */
-  clamp,
+  fromNumber,
   /**
    * Generates a random `Int16` within the given range.
    *

package/dist/number/branded-types/int16.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"int16.mjs","sources":["../../../src/number/branded-types/int16.mts"],"sourcesContent":["import { type Int16 as TtfImported_Int16 } from 'ts-type-forge';\nimport { expectType } from '../../expect-type.mjs';\nimport { TsDataForgeInternals } from '../refined-number-utils.mjs';\n\nexport type Int16 = TtfImported_Int16;\n\ntype ElementType = Int16;\n\nconst typeNameInMessage = 'an integer in [-2^15, 2^15)';\n\nconst {\n  MAX_VALUE,\n  MIN_VALUE,\n  abs,\n  add,\n  castType,\n  clamp,\n  div,\n  is,\n  max: max_,\n  min: min_,\n  mul,\n  pow,\n  random,\n  sub,\n} = TsDataForgeInternals.RefinedNumberUtils.operatorsForInteger<\n  ElementType,\n  number,\n  number\n>({\n  integerOrSafeInteger: 'SafeInteger',\n  MIN_VALUE: -(2 ** 15),\n  MAX_VALUE: 2 ** 15 - 1,\n  typeNameInMessage,\n} as const);\n\n/**\n * Type guard that checks if a value is an integer in [-2^15, 2^15).\n *\n * Returns `true` for an integer in [-2^15, 2^15) — a value with no fractional\n * component.\n *\n * @param value - The value to check\n * @returns `true` if the value is an integer in [-2^15, 2^15), `false` otherwise\n */\nexport const isInt16 = is;\n\n/**\n * Casts a `number` to the `Int16` branded type.\n *\n * Validates that the value is an integer in [-2^15, 2^15) and returns it with\n * the `Int16` brand. Throws a `TypeError` otherwise.\n *\n * @param value - The value to cast\n * @returns The value as an `Int16`\n * @throws {TypeError} If the value is not an integer in [-2^15, 2^15)\n */\nexport const asInt16 = castType;\n\n/**\n * Namespace providing type-safe operations for the `Int16` branded type.\n *\n * The `Int16` type represents an integer in [-2^15, 2^15). Division (`div`)\n * uses floor division.\n */\nexport const Int16 = {\n  /**\n   * Type guard that checks if a value is an integer in [-2^15, 2^15).\n   *\n   * @param value - The value to check\n   * @returns `true` if the value is an integer in [-2^15, 2^15), `false` otherwise\n   * @see {@link isInt16} for usage examples\n   */\n  is,\n\n  /**\n   * The smallest value representable as `Int16`.\n   */\n  MIN_VALUE,\n\n  /**\n   * The largest value representable as `Int16`.\n   */\n  MAX_VALUE,\n\n  /**\n   * Returns the absolute value of an integer in [-2^15, 2^15).\n   *\n   * The result is non-negative and keeps the `Int16` brand.\n   *\n   * @param a - The integer value\n   * @returns The absolute value as a non-negative `Int16`\n   */\n  abs,\n\n  /**\n   * Returns the smallest of the given integers.\n   *\n   * @param values - The integers to compare (at least one required)\n   * @returns The smallest value as an `Int16`\n   */\n  min: min_,\n\n  /**\n   * Returns the largest of the given integers.\n   *\n   * @param values - The integers to compare (at least one required)\n   * @returns The largest value as an `Int16`\n   */\n  max: max_,\n\n  /**\n   * Clamps a `number` into the `Int16` range, rounding to the nearest integer\n   * and constraining the result to `[MIN_VALUE, MAX_VALUE]`.\n   *\n   * @param value - The value to clamp\n   * @returns The clamped value as an `Int16`\n   */\n  clamp,\n\n  /**\n   * Generates a random `Int16` within the given range.\n   *\n   * The range is inclusive on both ends.\n   *\n   * @param min - The minimum value (inclusive)\n   * @param max - The maximum value (inclusive)\n   * @returns A random `Int16` in `[min, max]`\n   */\n  random,\n\n  /**\n   * Raises `a` to the power `b`, returning `a ** b` as an `Int16` (floored to\n   * an integer).\n   *\n   * @param a - The base integer\n   * @param b - The exponent integer\n   * @returns `a ** b` as an `Int16`\n   */\n  pow,\n\n  /**\n   * Adds two integers, returning `a + b` as an `Int16`.\n   *\n   * @param a - The first integer\n   * @param b - The second integer\n   * @returns The sum of `a` and `b` as an `Int16`\n   */\n  add,\n\n  /**\n   * Subtracts two integers, returning `a - b` as an `Int16`.\n   *\n   * @param a - The first integer\n   * @param b - The second integer\n   * @returns The difference of `a` and `b` as an `Int16`\n   */\n  sub,\n\n  /**\n   * Multiplies two integers, returning `a * b` as an `Int16`.\n   *\n   * @param a - The first integer\n   * @param b - The second integer\n   * @returns The product of `a` and `b` as an `Int16`\n   */\n  mul,\n\n  /**\n   * Divides two integers using floor division (`⌊a / b⌋`): the result is `a /\n   * b` rounded toward negative infinity, as an `Int16`.\n   *\n   * @param a - The dividend\n   * @param b - The divisor (must be non-zero)\n   * @returns The floored quotient as an `Int16`\n   */\n  div,\n} as const;\n\nexpectType<\n  keyof typeof Int16,\n  keyof TsDataForgeInternals.RefinedNumberUtils.NumberClass<\n    ElementType,\n    'int' | 'range'\n  >\n>('=');\n\nexpectType<\n  typeof Int16,\n  TsDataForgeInternals.RefinedNumberUtils.NumberClass<\n    ElementType,\n    'int' | 'range'\n  >\n>('<=');\n"],"names":[],"mappings":";;AAQA,MAAM,iBAAA,GAAoB,6BAAA;AAE1B,MAAM;AAAA,EACJ,SAAA;AAAA,EACA,SAAA;AAAA,EACA,GAAA;AAAA,EACA,GAAA;AAAA,EACA,QAAA;AAAA,EACA,KAAA;AAAA,EACA,GAAA;AAAA,EACA,EAAA;AAAA,EACA,GAAA,EAAK,IAAA;AAAA,EACL,GAAA,EAAK,IAAA;AAAA,EACL,GAAA;AAAA,EACA,GAAA;AAAA,EACA,MAAA;AAAA,EACA;AACF,CAAA,GAAI,oBAAA,CAAqB,mBAAmB,mBAAA,CAI1C;AAAA,EACA,oBAAA,EAAsB,aAAA;AAAA,EACtB,SAAA,EAAW,MAAO;AAAA,EAClB,SAAA,EAAW,KAAK,EAAA,GAAK,CAAA;AAAA,EACrB;AACF,CAAU,CAAA;AAWH,MAAM,OAAA,GAAU;AAYhB,MAAM,OAAA,GAAU;AAQhB,MAAM,KAAA,GAAQ;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQnB,EAAA;AAAA;AAAA;AAAA;AAAA,EAKA,SAAA;AAAA;AAAA;AAAA;AAAA,EAKA,SAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA,GAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,GAAA,EAAK,IAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQL,GAAA,EAAK,IAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASL,KAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWA,MAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA,GAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,GAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,GAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,GAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA;AACF;;;;"}
+{"version":3,"file":"int16.mjs","sources":["../../../src/number/branded-types/int16.mts"],"sourcesContent":["import { type Int16 as TtfImported_Int16 } from 'ts-type-forge';\nimport { expectType } from '../../expect-type.mjs';\nimport { TsDataForgeInternals } from '../refined-number-utils.mjs';\n\nexport type Int16 = TtfImported_Int16;\n\ntype ElementType = Int16;\n\nconst typeNameInMessage = 'an integer in [-2^15, 2^15)';\n\nconst {\n  MAX_VALUE,\n  MIN_VALUE,\n  abs,\n  add,\n  castType,\n  div,\n  fromNumber,\n  is,\n  max: max_,\n  min: min_,\n  mul,\n  pow,\n  random,\n  sub,\n} = TsDataForgeInternals.RefinedNumberUtils.operatorsForInteger<\n  ElementType,\n  number,\n  number\n>({\n  integerOrSafeInteger: 'SafeInteger',\n  MIN_VALUE: -(2 ** 15),\n  MAX_VALUE: 2 ** 15 - 1,\n  typeNameInMessage,\n} as const);\n\n/**\n * Type guard that checks if a value is an integer in [-2^15, 2^15).\n *\n * Returns `true` for an integer in [-2^15, 2^15) — a value with no fractional\n * component.\n *\n * @param value - The value to check\n * @returns `true` if the value is an integer in [-2^15, 2^15), `false` otherwise\n */\nexport const isInt16 = is;\n\n/**\n * Casts a `number` to the `Int16` branded type.\n *\n * Validates that the value is an integer in [-2^15, 2^15) and returns it with\n * the `Int16` brand. Throws a `TypeError` otherwise.\n *\n * @param value - The value to cast\n * @returns The value as an `Int16`\n * @throws {TypeError} If the value is not an integer in [-2^15, 2^15)\n */\nexport const asInt16 = castType;\n\n/**\n * Namespace providing type-safe operations for the `Int16` branded type.\n *\n * The `Int16` type represents an integer in [-2^15, 2^15). Division (`div`)\n * uses floor division.\n */\nexport const Int16 = {\n  /**\n   * Type guard that checks if a value is an integer in [-2^15, 2^15).\n   *\n   * @param value - The value to check\n   * @returns `true` if the value is an integer in [-2^15, 2^15), `false` otherwise\n   * @see {@link isInt16} for usage examples\n   */\n  is,\n\n  /**\n   * The smallest value representable as `Int16` (the lower saturation target of\n   * `fromNumber`).\n   */\n  MIN_VALUE,\n\n  /**\n   * The largest value representable as `Int16` (the upper saturation target of\n   * `fromNumber`).\n   */\n  MAX_VALUE,\n\n  /**\n   * Returns the absolute value of an integer in [-2^15, 2^15).\n   *\n   * The result is non-negative and keeps the `Int16` brand.\n   *\n   * @param a - The integer value\n   * @returns The absolute value as a non-negative `Int16`\n   */\n  abs,\n\n  /**\n   * Returns the smallest of the given integers.\n   *\n   * @param values - The integers to compare (at least one required)\n   * @returns The smallest value as an `Int16`\n   */\n  min: min_,\n\n  /**\n   * Returns the largest of the given integers.\n   *\n   * @param values - The integers to compare (at least one required)\n   * @returns The largest value as an `Int16`\n   */\n  max: max_,\n\n  /**\n   * Converts an arbitrary `number` into an `Int16`, rounding to the nearest\n   * integer and saturating the result into the range `[MIN_VALUE, MAX_VALUE]`.\n   *\n   * Unlike `asInt16`, this is total: out-of-range inputs are clamped to the\n   * nearest representable `Int16` instead of throwing.\n   *\n   * @param value - The value to convert\n   * @returns The value as an `Int16`\n   */\n  fromNumber,\n\n  /**\n   * Generates a random `Int16` within the given range.\n   *\n   * The range is inclusive on both ends.\n   *\n   * @param min - The minimum value (inclusive)\n   * @param max - The maximum value (inclusive)\n   * @returns A random `Int16` in `[min, max]`\n   */\n  random,\n\n  /**\n   * Raises `a` to the power `b`, returning `a ** b` as an `Int16` (floored to\n   * an integer).\n   *\n   * @param a - The base integer\n   * @param b - The exponent integer\n   * @returns `a ** b` as an `Int16`\n   */\n  pow,\n\n  /**\n   * Adds two integers, returning `a + b` as an `Int16`.\n   *\n   * @param a - The first integer\n   * @param b - The second integer\n   * @returns The sum of `a` and `b` as an `Int16`\n   */\n  add,\n\n  /**\n   * Subtracts two integers, returning `a - b` as an `Int16`.\n   *\n   * @param a - The first integer\n   * @param b - The second integer\n   * @returns The difference of `a` and `b` as an `Int16`\n   */\n  sub,\n\n  /**\n   * Multiplies two integers, returning `a * b` as an `Int16`.\n   *\n   * @param a - The first integer\n   * @param b - The second integer\n   * @returns The product of `a` and `b` as an `Int16`\n   */\n  mul,\n\n  /**\n   * Divides two integers using floor division (`⌊a / b⌋`): the result is `a /\n   * b` rounded toward negative infinity, as an `Int16`.\n   *\n   * @param a - The dividend\n   * @param b - The divisor (must be non-zero)\n   * @returns The floored quotient as an `Int16`\n   */\n  div,\n} as const;\n\nexpectType<\n  keyof typeof Int16,\n  keyof TsDataForgeInternals.RefinedNumberUtils.NumberClass<\n    ElementType,\n    'int' | 'range'\n  >\n>('=');\n\nexpectType<\n  typeof Int16,\n  TsDataForgeInternals.RefinedNumberUtils.NumberClass<\n    ElementType,\n    'int' | 'range'\n  >\n>('<=');\n"],"names":[],"mappings":";;AAQA,MAAM,iBAAA,GAAoB,6BAAA;AAE1B,MAAM;AAAA,EACJ,SAAA;AAAA,EACA,SAAA;AAAA,EACA,GAAA;AAAA,EACA,GAAA;AAAA,EACA,QAAA;AAAA,EACA,GAAA;AAAA,EACA,UAAA;AAAA,EACA,EAAA;AAAA,EACA,GAAA,EAAK,IAAA;AAAA,EACL,GAAA,EAAK,IAAA;AAAA,EACL,GAAA;AAAA,EACA,GAAA;AAAA,EACA,MAAA;AAAA,EACA;AACF,CAAA,GAAI,oBAAA,CAAqB,mBAAmB,mBAAA,CAI1C;AAAA,EACA,oBAAA,EAAsB,aAAA;AAAA,EACtB,SAAA,EAAW,MAAO;AAAA,EAClB,SAAA,EAAW,KAAK,EAAA,GAAK,CAAA;AAAA,EACrB;AACF,CAAU,CAAA;AAWH,MAAM,OAAA,GAAU;AAYhB,MAAM,OAAA,GAAU;AAQhB,MAAM,KAAA,GAAQ;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQnB,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,SAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,SAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA,GAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,GAAA,EAAK,IAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQL,GAAA,EAAK,IAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYL,UAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWA,MAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA,GAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,GAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,GAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,GAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA;AACF;;;;"}

package/dist/number/branded-types/int32.d.mts

@@ -48,11 +48,13 @@ export declare const Int32: {
      */
     readonly is: (a: number) => a is TtfImported_Int32;
     /**
-     * The smallest value representable as `Int32`.
+     * The smallest value representable as `Int32` (the lower saturation target of
+     * `fromNumber`).
      */
     readonly MIN_VALUE: number;
     /**
-     * The largest value representable as `Int32`.
+     * The largest value representable as `Int32` (the upper saturation target of
+     * `fromNumber`).
      */
     readonly MAX_VALUE: number;
     /**
@@ -79,13 +81,16 @@ export declare const Int32: {
      */
     readonly max: (...values: readonly import("ts-type-forge").WithSmallInt<TtfImported_Int32>[]) => TtfImported_Int32;
     /**
-     * Clamps a `number` into the `Int32` range, rounding to the nearest integer
-     * and constraining the result to `[MIN_VALUE, MAX_VALUE]`.
+     * Converts an arbitrary `number` into an `Int32`, rounding to the nearest
+     * integer and saturating the result into the range `[MIN_VALUE, MAX_VALUE]`.
      *
-     * @param value - The value to clamp
-     * @returns The clamped value as an `Int32`
+     * Unlike `asInt32`, this is total: out-of-range inputs are clamped to the
+     * nearest representable `Int32` instead of throwing.
+     *
+     * @param value - The value to convert
+     * @returns The value as an `Int32`
      */
-    readonly clamp: (x: number) => TtfImported_Int32;
+    readonly fromNumber: (x: number) => TtfImported_Int32;
     /**
      * Generates a random `Int32` within the given range.
      *

package/dist/number/branded-types/int32.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"int32.d.mts","sourceRoot":"","sources":["../../../src/number/branded-types/int32.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,IAAI,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAIhE,MAAM,MAAM,KAAK,GAAG,iBAAiB,CAAC;AAgCtC;;;;;;;;GAQG;AACH,eAAO,MAAM,OAAO,uCAAK,CAAC;AAE1B;;;;;;;;;GASG;AACH,eAAO,MAAM,OAAO;;;;;;;;;;;MAAW,CAAC;AAEhC;;;;;GAKG;AACH,eAAO,MAAM,KAAK;IAChB;;;;;;OAMG;;IAGH;;OAEG;;IAGH;;OAEG;;IAGH;;;;;;;OAOG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;;IAGH;;;;;;OAMG;;IAGH;;;;;;;;OAQG;;IAGH;;;;;;;OAOG;;IAGH;;;;;;OAMG;;IAGH;;;;;;OAMG;;IAGH;;;;;;OAMG;;IAGH;;;;;;;OAOG;;;;;;;;;;;;;;CAEK,CAAC"}
+{"version":3,"file":"int32.d.mts","sourceRoot":"","sources":["../../../src/number/branded-types/int32.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,KAAK,IAAI,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAIhE,MAAM,MAAM,KAAK,GAAG,iBAAiB,CAAC;AAgCtC;;;;;;;;GAQG;AACH,eAAO,MAAM,OAAO,uCAAK,CAAC;AAE1B;;;;;;;;;GASG;AACH,eAAO,MAAM,OAAO;;;;;;;;;;;MAAW,CAAC;AAEhC;;;;;GAKG;AACH,eAAO,MAAM,KAAK;IAChB;;;;;;OAMG;;IAGH;;;OAGG;;IAGH;;;OAGG;;IAGH;;;;;;;OAOG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;;IAGH;;;;;;;;;OASG;;IAGH;;;;;;;;OAQG;;IAGH;;;;;;;OAOG;;IAGH;;;;;;OAMG;;IAGH;;;;;;OAMG;;IAGH;;;;;;OAMG;;IAGH;;;;;;;OAOG;;;;;;;;;;;;;;CAEK,CAAC"}

package/dist/number/branded-types/int32.mjs

@@ -7,8 +7,8 @@ const {
   abs,
   add,
   castType,
-  clamp,
   div,
+  fromNumber,
   is,
   max: max_,
   min: min_,
@@ -34,11 +34,13 @@ const Int32 = {
    */
   is,
   /**
-   * The smallest value representable as `Int32`.
+   * The smallest value representable as `Int32` (the lower saturation target of
+   * `fromNumber`).
    */
   MIN_VALUE,
   /**
-   * The largest value representable as `Int32`.
+   * The largest value representable as `Int32` (the upper saturation target of
+   * `fromNumber`).
    */
   MAX_VALUE,
   /**
@@ -65,13 +67,16 @@ const Int32 = {
    */
   max: max_,
   /**
-   * Clamps a `number` into the `Int32` range, rounding to the nearest integer
-   * and constraining the result to `[MIN_VALUE, MAX_VALUE]`.
+   * Converts an arbitrary `number` into an `Int32`, rounding to the nearest
+   * integer and saturating the result into the range `[MIN_VALUE, MAX_VALUE]`.
    *
-   * @param value - The value to clamp
-   * @returns The clamped value as an `Int32`
+   * Unlike `asInt32`, this is total: out-of-range inputs are clamped to the
+   * nearest representable `Int32` instead of throwing.
+   *
+   * @param value - The value to convert
+   * @returns The value as an `Int32`
    */
-  clamp,
+  fromNumber,
   /**
    * Generates a random `Int32` within the given range.
    *

package/dist/number/branded-types/int32.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"int32.mjs","sources":["../../../src/number/branded-types/int32.mts"],"sourcesContent":["import { type Int32 as TtfImported_Int32 } from 'ts-type-forge';\nimport { expectType } from '../../expect-type.mjs';\nimport { TsDataForgeInternals } from '../refined-number-utils.mjs';\n\nexport type Int32 = TtfImported_Int32;\n\ntype ElementType = Int32;\n\nconst typeNameInMessage = 'an integer in [-2^31, 2^31)';\n\nconst {\n  MAX_VALUE,\n  MIN_VALUE,\n  abs,\n  add,\n  castType,\n  clamp,\n  div,\n  is,\n  max: max_,\n  min: min_,\n  mul,\n  pow,\n  random,\n  sub,\n} = TsDataForgeInternals.RefinedNumberUtils.operatorsForInteger<\n  ElementType,\n  number,\n  number\n>({\n  integerOrSafeInteger: 'SafeInteger',\n  MIN_VALUE: -(2 ** 31),\n  MAX_VALUE: 2 ** 31 - 1,\n  typeNameInMessage,\n} as const);\n\n/**\n * Type guard that checks if a value is an integer in [-2^31, 2^31).\n *\n * Returns `true` for an integer in [-2^31, 2^31) — a value with no fractional\n * component.\n *\n * @param value - The value to check\n * @returns `true` if the value is an integer in [-2^31, 2^31), `false` otherwise\n */\nexport const isInt32 = is;\n\n/**\n * Casts a `number` to the `Int32` branded type.\n *\n * Validates that the value is an integer in [-2^31, 2^31) and returns it with\n * the `Int32` brand. Throws a `TypeError` otherwise.\n *\n * @param value - The value to cast\n * @returns The value as an `Int32`\n * @throws {TypeError} If the value is not an integer in [-2^31, 2^31)\n */\nexport const asInt32 = castType;\n\n/**\n * Namespace providing type-safe operations for the `Int32` branded type.\n *\n * The `Int32` type represents an integer in [-2^31, 2^31). Division (`div`)\n * uses floor division.\n */\nexport const Int32 = {\n  /**\n   * Type guard that checks if a value is an integer in [-2^31, 2^31).\n   *\n   * @param value - The value to check\n   * @returns `true` if the value is an integer in [-2^31, 2^31), `false` otherwise\n   * @see {@link isInt32} for usage examples\n   */\n  is,\n\n  /**\n   * The smallest value representable as `Int32`.\n   */\n  MIN_VALUE,\n\n  /**\n   * The largest value representable as `Int32`.\n   */\n  MAX_VALUE,\n\n  /**\n   * Returns the absolute value of an integer in [-2^31, 2^31).\n   *\n   * The result is non-negative and keeps the `Int32` brand.\n   *\n   * @param a - The integer value\n   * @returns The absolute value as a non-negative `Int32`\n   */\n  abs,\n\n  /**\n   * Returns the smallest of the given integers.\n   *\n   * @param values - The integers to compare (at least one required)\n   * @returns The smallest value as an `Int32`\n   */\n  min: min_,\n\n  /**\n   * Returns the largest of the given integers.\n   *\n   * @param values - The integers to compare (at least one required)\n   * @returns The largest value as an `Int32`\n   */\n  max: max_,\n\n  /**\n   * Clamps a `number` into the `Int32` range, rounding to the nearest integer\n   * and constraining the result to `[MIN_VALUE, MAX_VALUE]`.\n   *\n   * @param value - The value to clamp\n   * @returns The clamped value as an `Int32`\n   */\n  clamp,\n\n  /**\n   * Generates a random `Int32` within the given range.\n   *\n   * The range is inclusive on both ends.\n   *\n   * @param min - The minimum value (inclusive)\n   * @param max - The maximum value (inclusive)\n   * @returns A random `Int32` in `[min, max]`\n   */\n  random,\n\n  /**\n   * Raises `a` to the power `b`, returning `a ** b` as an `Int32` (floored to\n   * an integer).\n   *\n   * @param a - The base integer\n   * @param b - The exponent integer\n   * @returns `a ** b` as an `Int32`\n   */\n  pow,\n\n  /**\n   * Adds two integers, returning `a + b` as an `Int32`.\n   *\n   * @param a - The first integer\n   * @param b - The second integer\n   * @returns The sum of `a` and `b` as an `Int32`\n   */\n  add,\n\n  /**\n   * Subtracts two integers, returning `a - b` as an `Int32`.\n   *\n   * @param a - The first integer\n   * @param b - The second integer\n   * @returns The difference of `a` and `b` as an `Int32`\n   */\n  sub,\n\n  /**\n   * Multiplies two integers, returning `a * b` as an `Int32`.\n   *\n   * @param a - The first integer\n   * @param b - The second integer\n   * @returns The product of `a` and `b` as an `Int32`\n   */\n  mul,\n\n  /**\n   * Divides two integers using floor division (`⌊a / b⌋`): the result is `a /\n   * b` rounded toward negative infinity, as an `Int32`.\n   *\n   * @param a - The dividend\n   * @param b - The divisor (must be non-zero)\n   * @returns The floored quotient as an `Int32`\n   */\n  div,\n} as const;\n\nexpectType<\n  keyof typeof Int32,\n  keyof TsDataForgeInternals.RefinedNumberUtils.NumberClass<\n    ElementType,\n    'int' | 'range'\n  >\n>('=');\n\nexpectType<\n  typeof Int32,\n  TsDataForgeInternals.RefinedNumberUtils.NumberClass<\n    ElementType,\n    'int' | 'range'\n  >\n>('<=');\n"],"names":[],"mappings":";;AAQA,MAAM,iBAAA,GAAoB,6BAAA;AAE1B,MAAM;AAAA,EACJ,SAAA;AAAA,EACA,SAAA;AAAA,EACA,GAAA;AAAA,EACA,GAAA;AAAA,EACA,QAAA;AAAA,EACA,KAAA;AAAA,EACA,GAAA;AAAA,EACA,EAAA;AAAA,EACA,GAAA,EAAK,IAAA;AAAA,EACL,GAAA,EAAK,IAAA;AAAA,EACL,GAAA;AAAA,EACA,GAAA;AAAA,EACA,MAAA;AAAA,EACA;AACF,CAAA,GAAI,oBAAA,CAAqB,mBAAmB,mBAAA,CAI1C;AAAA,EACA,oBAAA,EAAsB,aAAA;AAAA,EACtB,SAAA,EAAW,WAAO;AAAA,EAClB,SAAA,EAAW,KAAK,EAAA,GAAK,CAAA;AAAA,EACrB;AACF,CAAU,CAAA;AAWH,MAAM,OAAA,GAAU;AAYhB,MAAM,OAAA,GAAU;AAQhB,MAAM,KAAA,GAAQ;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQnB,EAAA;AAAA;AAAA;AAAA;AAAA,EAKA,SAAA;AAAA;AAAA;AAAA;AAAA,EAKA,SAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA,GAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,GAAA,EAAK,IAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQL,GAAA,EAAK,IAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASL,KAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWA,MAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA,GAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,GAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,GAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,GAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA;AACF;;;;"}
+{"version":3,"file":"int32.mjs","sources":["../../../src/number/branded-types/int32.mts"],"sourcesContent":["import { type Int32 as TtfImported_Int32 } from 'ts-type-forge';\nimport { expectType } from '../../expect-type.mjs';\nimport { TsDataForgeInternals } from '../refined-number-utils.mjs';\n\nexport type Int32 = TtfImported_Int32;\n\ntype ElementType = Int32;\n\nconst typeNameInMessage = 'an integer in [-2^31, 2^31)';\n\nconst {\n  MAX_VALUE,\n  MIN_VALUE,\n  abs,\n  add,\n  castType,\n  div,\n  fromNumber,\n  is,\n  max: max_,\n  min: min_,\n  mul,\n  pow,\n  random,\n  sub,\n} = TsDataForgeInternals.RefinedNumberUtils.operatorsForInteger<\n  ElementType,\n  number,\n  number\n>({\n  integerOrSafeInteger: 'SafeInteger',\n  MIN_VALUE: -(2 ** 31),\n  MAX_VALUE: 2 ** 31 - 1,\n  typeNameInMessage,\n} as const);\n\n/**\n * Type guard that checks if a value is an integer in [-2^31, 2^31).\n *\n * Returns `true` for an integer in [-2^31, 2^31) — a value with no fractional\n * component.\n *\n * @param value - The value to check\n * @returns `true` if the value is an integer in [-2^31, 2^31), `false` otherwise\n */\nexport const isInt32 = is;\n\n/**\n * Casts a `number` to the `Int32` branded type.\n *\n * Validates that the value is an integer in [-2^31, 2^31) and returns it with\n * the `Int32` brand. Throws a `TypeError` otherwise.\n *\n * @param value - The value to cast\n * @returns The value as an `Int32`\n * @throws {TypeError} If the value is not an integer in [-2^31, 2^31)\n */\nexport const asInt32 = castType;\n\n/**\n * Namespace providing type-safe operations for the `Int32` branded type.\n *\n * The `Int32` type represents an integer in [-2^31, 2^31). Division (`div`)\n * uses floor division.\n */\nexport const Int32 = {\n  /**\n   * Type guard that checks if a value is an integer in [-2^31, 2^31).\n   *\n   * @param value - The value to check\n   * @returns `true` if the value is an integer in [-2^31, 2^31), `false` otherwise\n   * @see {@link isInt32} for usage examples\n   */\n  is,\n\n  /**\n   * The smallest value representable as `Int32` (the lower saturation target of\n   * `fromNumber`).\n   */\n  MIN_VALUE,\n\n  /**\n   * The largest value representable as `Int32` (the upper saturation target of\n   * `fromNumber`).\n   */\n  MAX_VALUE,\n\n  /**\n   * Returns the absolute value of an integer in [-2^31, 2^31).\n   *\n   * The result is non-negative and keeps the `Int32` brand.\n   *\n   * @param a - The integer value\n   * @returns The absolute value as a non-negative `Int32`\n   */\n  abs,\n\n  /**\n   * Returns the smallest of the given integers.\n   *\n   * @param values - The integers to compare (at least one required)\n   * @returns The smallest value as an `Int32`\n   */\n  min: min_,\n\n  /**\n   * Returns the largest of the given integers.\n   *\n   * @param values - The integers to compare (at least one required)\n   * @returns The largest value as an `Int32`\n   */\n  max: max_,\n\n  /**\n   * Converts an arbitrary `number` into an `Int32`, rounding to the nearest\n   * integer and saturating the result into the range `[MIN_VALUE, MAX_VALUE]`.\n   *\n   * Unlike `asInt32`, this is total: out-of-range inputs are clamped to the\n   * nearest representable `Int32` instead of throwing.\n   *\n   * @param value - The value to convert\n   * @returns The value as an `Int32`\n   */\n  fromNumber,\n\n  /**\n   * Generates a random `Int32` within the given range.\n   *\n   * The range is inclusive on both ends.\n   *\n   * @param min - The minimum value (inclusive)\n   * @param max - The maximum value (inclusive)\n   * @returns A random `Int32` in `[min, max]`\n   */\n  random,\n\n  /**\n   * Raises `a` to the power `b`, returning `a ** b` as an `Int32` (floored to\n   * an integer).\n   *\n   * @param a - The base integer\n   * @param b - The exponent integer\n   * @returns `a ** b` as an `Int32`\n   */\n  pow,\n\n  /**\n   * Adds two integers, returning `a + b` as an `Int32`.\n   *\n   * @param a - The first integer\n   * @param b - The second integer\n   * @returns The sum of `a` and `b` as an `Int32`\n   */\n  add,\n\n  /**\n   * Subtracts two integers, returning `a - b` as an `Int32`.\n   *\n   * @param a - The first integer\n   * @param b - The second integer\n   * @returns The difference of `a` and `b` as an `Int32`\n   */\n  sub,\n\n  /**\n   * Multiplies two integers, returning `a * b` as an `Int32`.\n   *\n   * @param a - The first integer\n   * @param b - The second integer\n   * @returns The product of `a` and `b` as an `Int32`\n   */\n  mul,\n\n  /**\n   * Divides two integers using floor division (`⌊a / b⌋`): the result is `a /\n   * b` rounded toward negative infinity, as an `Int32`.\n   *\n   * @param a - The dividend\n   * @param b - The divisor (must be non-zero)\n   * @returns The floored quotient as an `Int32`\n   */\n  div,\n} as const;\n\nexpectType<\n  keyof typeof Int32,\n  keyof TsDataForgeInternals.RefinedNumberUtils.NumberClass<\n    ElementType,\n    'int' | 'range'\n  >\n>('=');\n\nexpectType<\n  typeof Int32,\n  TsDataForgeInternals.RefinedNumberUtils.NumberClass<\n    ElementType,\n    'int' | 'range'\n  >\n>('<=');\n"],"names":[],"mappings":";;AAQA,MAAM,iBAAA,GAAoB,6BAAA;AAE1B,MAAM;AAAA,EACJ,SAAA;AAAA,EACA,SAAA;AAAA,EACA,GAAA;AAAA,EACA,GAAA;AAAA,EACA,QAAA;AAAA,EACA,GAAA;AAAA,EACA,UAAA;AAAA,EACA,EAAA;AAAA,EACA,GAAA,EAAK,IAAA;AAAA,EACL,GAAA,EAAK,IAAA;AAAA,EACL,GAAA;AAAA,EACA,GAAA;AAAA,EACA,MAAA;AAAA,EACA;AACF,CAAA,GAAI,oBAAA,CAAqB,mBAAmB,mBAAA,CAI1C;AAAA,EACA,oBAAA,EAAsB,aAAA;AAAA,EACtB,SAAA,EAAW,WAAO;AAAA,EAClB,SAAA,EAAW,KAAK,EAAA,GAAK,CAAA;AAAA,EACrB;AACF,CAAU,CAAA;AAWH,MAAM,OAAA,GAAU;AAYhB,MAAM,OAAA,GAAU;AAQhB,MAAM,KAAA,GAAQ;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQnB,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,SAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,SAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA,GAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,GAAA,EAAK,IAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQL,GAAA,EAAK,IAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAYL,UAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAWA,MAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA,GAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,GAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,GAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,GAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA;AACF;;;;"}