ts-data-forge 14.10.1 → 14.11.0

package/dist/number/enum/uint8.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"uint8.mjs","sourceRoot":"","sources":["../../../src/number/enum/uint8.mts"],"names":[],"mappings":"AAKA,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AAInE,MAAM,iBAAiB,GAAG,uCAAuC,CAAC;AAElE,MAAM,EACJ,SAAS,EACT,SAAS,EACT,QAAQ,EAAE,YAAY,EACtB,UAAU,EAAE,cAAc,EAC1B,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,UAAU,GACnB,GAAG,oBAAoB,CAAC,kBAAkB,CAAC,mBAAmB,CAC7D;IACE,oBAAoB,EAAE,aAAa;IACnC,SAAS,EAAE,CAAC;IACZ,SAAS,EAAE,GAAG;IACd,iBAAiB;CACT,CACX,CAAC;AAEF,MAAM,EAAE,GAAG,CAAC,CAAS,EAAc,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;AAEhD,MAAM,QAAQ,GAAG,CAAC,CAAS,EAAS,EAAE;AACpC,oEAAoE;AACpE,YAAY,CAAC,CAAC,CAAU,CAAC;AAE3B,MAAM,UAAU,GAAG,CAAC,CAAS,EAAS,EAAE,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;AAErE,MAAM,IAAI,GAAG,CAAC,GAAG,MAAwB,EAAS,EAAE,CAClD,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;AAEhC,MAAM,IAAI,GAAG,CAAC,GAAG,MAAwB,EAAS,EAAE,CAClD,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;AAEhC,MAAM,GAAG,GAAG,CAAC,CAAQ,EAAE,CAAQ,EAAS,EAAE,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AAE9D,MAAM,GAAG,GAAG,CAAC,CAAQ,EAAE,CAAQ,EAAS,EAAE,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;AAE7D,MAAM,GAAG,GAAG,CAAC,CAAQ,EAAE,CAAQ,EAAS,EAAE,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;AAE7D,MAAM,GAAG,GAAG,CAAC,CAAQ,EAAE,CAAQ,EAAS,EAAE,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;AAE7D,MAAM,GAAG,GAAG,CAAC,CAAQ,EAAE,CAA0B,EAAS,EAAE,CAC1D,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAEhC,MAAM,MAAM,GAAG,CAAC,GAAU,EAAE,GAAU,EAAS,EAAE,CAC/C,QAAQ,CAAC,UAAU,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAE7D;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,EAAE,CAAC;AAE1B;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,QAAQ,CAAC;AAEhC;;;;;GAKG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG;IACnB;;;;;;OAMG;IACH,EAAE;IAEF;;;OAGG;IACH,SAAS;IAET;;;OAGG;IACH,SAAS;IAET;;;;;OAKG;IACH,GAAG,EAAE,IAAI;IAET;;;;;OAKG;IACH,GAAG,EAAE,IAAI;IAET;;;;;;;;;OASG;IACH,UAAU;IAEV;;;;;;;;OAQG;IACH,MAAM;IAEN;;;;;;;OAOG;IACH,GAAG;IAEH;;;;;;OAMG;IACH,GAAG;IAEH;;;;;;OAMG;IACH,GAAG;IAEH;;;;;;OAMG;IACH,GAAG;IAEH;;;;;;;OAOG;IACH,GAAG;CACK,CAAC;AAEX,UAAU,CAMR,GAAG,CAAC,CAAC"}
+{"version":3,"file":"uint8.mjs","sourceRoot":"","sources":["../../../src/number/enum/uint8.mts"],"names":[],"mappings":"AAKA,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EACL,SAAS,EACT,SAAS,EACT,QAAQ,IAAI,YAAY,EACxB,UAAU,IAAI,cAAc,EAC5B,MAAM,IAAI,UAAU,GACrB,MAAM,wBAAwB,CAAC;AAKhC,MAAM,iBAAiB,GAAG,uCAAuC,CAAC;AAElE;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,KAAa,EAAkB,EAAE,CACvD,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,KAAK,IAAI,KAAK,IAAI,GAAG,CAAC;AAE5D;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,KAAa,EAAS,EAAE;IAC9C,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACpB,MAAM,IAAI,SAAS,CAAC,YAAY,iBAAiB,UAAU,KAAK,EAAE,CAAC,CAAC;IACtE,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC,CAAC;AAEF,MAAM,UAAU,GAAG,CAAC,CAAS,EAAS,EAAE,CAAC,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,CAAC;AAEpE,MAAM,IAAI,GAAG,CAAC,GAAG,MAAwB,EAAS,EAAE,CAClD,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;AAE/B,MAAM,IAAI,GAAG,CAAC,GAAG,MAAwB,EAAS,EAAE,CAClD,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC;AAE/B,MAAM,GAAG,GAAG,CAAC,CAAQ,EAAE,CAAQ,EAAS,EAAE,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AAE9D,MAAM,GAAG,GAAG,CAAC,CAAQ,EAAE,CAAQ,EAAS,EAAE,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;AAE7D,MAAM,GAAG,GAAG,CAAC,CAAQ,EAAE,CAAQ,EAAS,EAAE,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;AAE7D,MAAM,GAAG,GAAG,CAAC,CAAQ,EAAE,CAAQ,EAAS,EAAE,CAAC,UAAU,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;AAE7D,MAAM,GAAG,GAAG,CAAC,CAAQ,EAAE,CAA0B,EAAS,EAAE,CAC1D,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAEhC,MAAM,MAAM,GAAG,CAAC,GAAU,EAAE,GAAU,EAAS,EAAE,CAC/C,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC,GAAG,CAAC,EAAE,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAE5D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG;IACnB;;;;;;OAMG;IACH,EAAE,EAAE,OAAO;IAEX;;;OAGG;IACH,SAAS;IAET;;;OAGG;IACH,SAAS;IAET;;;;;OAKG;IACH,GAAG,EAAE,IAAI;IAET;;;;;OAKG;IACH,GAAG,EAAE,IAAI;IAET;;;;;;;;;OASG;IACH,UAAU;IAEV;;;;;;;;OAQG;IACH,MAAM;IAEN;;;;;;;OAOG;IACH,GAAG;IAEH;;;;;;OAMG;IACH,GAAG;IAEH;;;;;;OAMG;IACH,GAAG;IAEH;;;;;;OAMG;IACH,GAAG;IAEH;;;;;;;OAOG;IACH,GAAG;CACK,CAAC;AAEX,UAAU,CAMR,GAAG,CAAC,CAAC"}

package/dist/number/index.d.mts

@@ -1,6 +1,6 @@
 export * from './branded-types/index.mjs';
 export * from './enum/index.mjs';
 export * from './num-arithmetic-types.mjs';
-export * from './num.mjs';
+export * from './num/index.mjs';
 export * from './refined-number-utils.mjs';
 //# sourceMappingURL=index.d.mts.map

package/dist/number/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../../src/number/index.mts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC;AAC1C,cAAc,kBAAkB,CAAC;AACjC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,WAAW,CAAC;AAC1B,cAAc,4BAA4B,CAAC"}
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../../src/number/index.mts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC;AAC1C,cAAc,kBAAkB,CAAC;AACjC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,iBAAiB,CAAC;AAChC,cAAc,4BAA4B,CAAC"}

package/dist/number/index.mjs

@@ -1,6 +1,6 @@
 export * from './branded-types/index.mjs';
 export * from './enum/index.mjs';
 export * from './num-arithmetic-types.mjs';
-export * from './num.mjs';
+export * from './num/index.mjs';
 export * from './refined-number-utils.mjs';
 //# sourceMappingURL=index.mjs.map

package/dist/number/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","sourceRoot":"","sources":["../../src/number/index.mts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC;AAC1C,cAAc,kBAAkB,CAAC;AACjC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,WAAW,CAAC;AAC1B,cAAc,4BAA4B,CAAC"}
+{"version":3,"file":"index.mjs","sourceRoot":"","sources":["../../src/number/index.mts"],"names":[],"mappings":"AAAA,cAAc,2BAA2B,CAAC;AAC1C,cAAc,kBAAkB,CAAC;AACjC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,iBAAiB,CAAC;AAChC,cAAc,4BAA4B,CAAC"}

package/dist/number/num/impl/index.d.mts

@@ -0,0 +1,2 @@
+export * from './num.mjs';
+//# sourceMappingURL=index.d.mts.map

package/dist/number/num/impl/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../../../../src/number/num/impl/index.mts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC"}

package/dist/number/num/impl/index.mjs

@@ -0,0 +1,2 @@
+export * from './num.mjs';
+//# sourceMappingURL=index.mjs.map

package/dist/number/num/impl/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","sourceRoot":"","sources":["../../../../src/number/num/impl/index.mts"],"names":[],"mappings":"AAAA,cAAc,WAAW,CAAC"}

package/dist/number/num/impl/num.d.mts

@@ -0,0 +1,531 @@
+import type { Decrement, FiniteNumber, Increment, Index, Int, Min, NaNType, NegativeIndex, NonNegativeNumber, NonZeroNumber, PositiveNumber, PositiveSafeIntWithSmallInt, RelaxedExclude, SmallInt, SmallUint } from 'ts-type-forge';
+import { Result } from '../../../functional/index.mjs';
+import type { SmallPositiveInt } from '../../../types.mjs';
+import type { AddResult, DivIntResult, DivResult, MulResult, SubResult } from '../../num-arithmetic-types.mjs';
+/**
+ * Converts an unknown value to a number. Alias for the `Number` constructor.
+ *
+ * @example
+ *
+ * ```ts
+ * const input = '123.45';
+ *
+ * const result = Num.from(input);
+ *
+ * assert.isTrue(result === 123.45);
+ * ```
+ *
+ * @param n The value to convert.
+ * @returns The numeric representation of `n`.
+ */
+export declare const from: (n: unknown) => number;
+/**
+ * Safely parses a base-10 integer from a string, returning a {@link Result}
+ * that is `Ok<Int>` for valid input and `Err<Error>` otherwise.
+ *
+ * This is a stricter alternative to both `parseInt` and `Number`:
+ *
+ * - Unlike `parseInt('12abc', 10)` (which returns `12`), trailing
+ *   non-numeric characters make the whole input invalid and yield `Err`.
+ * - Unlike `Number('')` / `Number('   ')` (which return `0`), empty or
+ *   whitespace-only input yields `Err`.
+ *
+ * The empty-string case is rejected by delegating to `parseInt` (which returns
+ * `NaN` there) rather than hard-coding a check, while the trailing-garbage case
+ * is rejected via `Number`. Valid input is truncated toward zero, so `'12.9'`
+ * becomes `12` and `'-3.5'` becomes `-3`.
+ *
+ * Only base 10 is supported. Use `Result.unwrapOk` (optionally with a
+ * `?? Number.NaN` fallback) or `Result.unwrapOkOr` to get a plain number back.
+ *
+ * @example
+ *
+ * ```ts
+ * assert.strictEqual(
+ *   Result.unwrapOkOr(Num.safeParseInt('123'), Number.NaN),
+ *   123,
+ * );
+ *
+ * assert.strictEqual(
+ *   Result.unwrapOkOr(Num.safeParseInt('12.9'), Number.NaN),
+ *   12,
+ * );
+ *
+ * assert.strictEqual(
+ *   Result.unwrapOkOr(Num.safeParseInt('-12.9'), Number.NaN),
+ *   -12,
+ * );
+ *
+ * assert.strictEqual(Number.parseInt('-12.9', 10), -12);
+ *
+ * // Native `parseInt` ignores trailing non-numeric characters
+ *
+ * assert.strictEqual(Number.parseInt('123abc', 10), 123);
+ *
+ * assert.isTrue(Number.isNaN(Number('123abc')));
+ *
+ * assert.isTrue(Result.isErr(Num.safeParseInt('123abc')));
+ *
+ * // Whitespace is not a valid integer, so we return an error instead of coercing to 0.
+ *
+ * assert.isTrue(Number.isNaN(Number.parseInt('  ', 10)));
+ *
+ * assert.strictEqual(Number('  '), 0); // Native `Number` coerces whitespace to 0
+ *
+ * assert.isTrue(Result.isErr(Num.safeParseInt('')));
+ *
+ * assert.strictEqual(Result.unwrapOk(Num.safeParseInt('  ')), undefined);
+ *
+ * // A value that overflows to Infinity is not an integer either, even though
+ * // native `parseInt` reads a 1 out of it.
+ *
+ * assert.strictEqual(Number.parseInt('1e400', 10), 1);
+ *
+ * assert.isTrue(Result.isErr(Num.safeParseInt('1e400')));
+ * ```
+ *
+ * @param s The string to parse.
+ * @returns `Result.ok(parsedInt)` for valid input, otherwise `Result.err`
+ *   wrapping an `Error` describing the invalid input. A value that
+ *   overflows to `Infinity` is rejected, so the `Int` brand never lies.
+ */
+export declare const safeParseInt: (s: string) => Result<Int, Error>;
+/**
+ * Safely parses a finite floating-point number from a string, returning a
+ * {@link Result} that is `Ok<FiniteNumber>` for valid input and `Err<Error>`
+ * otherwise.
+ *
+ * This is a stricter alternative to both `parseFloat` and `Number`:
+ *
+ * - Unlike `parseFloat('12abc')` (which returns `12`), trailing non-numeric
+ *   characters make the whole input invalid and yield `Err`.
+ * - Unlike `Number('')` / `Number('   ')` (which return `0`), empty or
+ *   whitespace-only input yields `Err`.
+ * - Unlike `Number('Infinity')` (which returns `Infinity`), non-finite values
+ *   yield `Err`.
+ *
+ * The empty-string case is rejected by delegating to `parseFloat` (which
+ * returns `NaN` there) rather than hard-coding a check, while the
+ * trailing-garbage case is rejected via `Number`. Decimal values are preserved as-is, so
+ * `'12.9'` stays `12.9`.
+ *
+ * Use `Result.unwrapOk` (optionally with a `?? Number.NaN` fallback) or
+ * `Result.unwrapOkOr` to get a plain number back.
+ *
+ * @example
+ *
+ * ```ts
+ * assert.strictEqual(
+ *   Result.unwrapOkOr(Num.safeParseFloat('12.9'), Number.NaN),
+ *   12.9,
+ * );
+ *
+ * assert.strictEqual(
+ *   Result.unwrapOkOr(Num.safeParseFloat('-3.5'), Number.NaN),
+ *   -3.5,
+ * );
+ *
+ * assert.strictEqual(
+ *   Result.unwrapOkOr(Num.safeParseFloat('1e3'), Number.NaN),
+ *   1000,
+ * );
+ *
+ * // Native `parseFloat` ignores trailing non-numeric characters
+ *
+ * assert.strictEqual(Number.parseFloat('12px'), 12);
+ *
+ * assert.isTrue(Result.isErr(Num.safeParseFloat('12px')));
+ *
+ * // Whitespace is not a valid number, so we return an error instead of coercing to 0.
+ *
+ * assert.isTrue(Result.isErr(Num.safeParseFloat('')));
+ *
+ * assert.isTrue(Result.isErr(Num.safeParseFloat('   ')));
+ *
+ * // Infinity and NaN are not finite, so they are rejected.
+ *
+ * assert.isTrue(Result.isErr(Num.safeParseFloat('Infinity')));
+ *
+ * assert.isTrue(Result.isErr(Num.safeParseFloat('NaN')));
+ * ```
+ *
+ * @param s The string to parse.
+ * @returns `Result.ok(parsedFloat)` for valid finite input, otherwise
+ *   `Result.err` wrapping an `Error` describing the invalid input.
+ */
+export declare const safeParseFloat: (s: string) => Result<FiniteNumber, Error>;
+/**
+ * Type guard that checks if a number is non-zero.
+ *
+ * When this function returns `true`, TypeScript narrows the type to exclude
+ * zero, providing compile-time safety for division operations and other
+ * calculations that require non-zero values.
+ *
+ * @example
+ *
+ * ```ts
+ * const value: number = 5;
+ *
+ * if (Num.isNonZero(value)) {
+ *   // Safe to divide now that we know value is non-zero
+ *   // eslint-disable-next-line total-functions/no-partial-division
+ *   const inverted = 1 / value;
+ *
+ *   assert.isTrue(inverted === 0.2);
+ * }
+ *
+ * assert.isFalse(Num.isNonZero(0));
+ * ```
+ *
+ * @template N - The numeric literal type or number type to check
+ * @param num - The number to check
+ * @returns `true` if the number is not zero, `false` otherwise
+ */
+export declare const isNonZero: <N extends number>(num: N) => num is NonZeroNumber & RelaxedExclude<N, 0>;
+/**
+ * Type guard that checks if a number is non-negative (greater than or equal to
+ * zero).
+ *
+ * When this function returns `true`, TypeScript narrows the type to exclude
+ * negative values, which is useful for operations that require non-negative
+ * inputs like array indices or measurements.
+ *
+ * @example
+ *
+ * ```ts
+ * const candidate = 10;
+ *
+ * if (Num.isNonNegative(candidate)) {
+ *   const index: number = candidate;
+ *
+ *   assert.isTrue(index === 10);
+ * }
+ *
+ * assert.isFalse(Num.isNonNegative(-1));
+ * ```
+ *
+ * @template N - The numeric literal type or number type to check
+ * @param num - The number to check
+ * @returns `true` if the number is >= 0, `false` otherwise
+ */
+export declare const isNonNegative: <N extends number>(num: N) => num is NonNegativeNumber & RelaxedExclude<N, NegativeIndex<1024>>;
+/**
+ * Type guard that checks if a number is positive (greater than zero).
+ *
+ * When this function returns `true`, TypeScript narrows the type to exclude
+ * zero and negative values. This is particularly useful for validating inputs
+ * that must be strictly positive, such as dimensions, counts, or rates.
+ *
+ * @example
+ *
+ * ```ts
+ * const amount = 42;
+ *
+ * if (Num.isPositive(amount)) {
+ *   assert.isTrue(amount > 0);
+ * }
+ *
+ * assert.isFalse(Num.isPositive(0));
+ * ```
+ *
+ * @template N - The numeric literal type or number type to check
+ * @param num - The number to check
+ * @returns `true` if the number is > 0, `false` otherwise
+ */
+export declare const isPositive: <N extends number>(num: N) => num is PositiveNumber & RelaxedExclude<N, NegativeIndex<1024> | 0>;
+/**
+ * Creates a function that checks if a number `x` is within the range
+ * `lowerBound <= x < upperBound`.
+ *
+ * @example
+ *
+ * ```ts
+ * const isGrade = Num.isInRange(0, 100);
+ *
+ * assert.isTrue(isGrade(50));
+ *
+ * assert.isFalse(isGrade(100));
+ * ```
+ *
+ * @param lowerBound The lower bound (inclusive).
+ * @param upperBound The upper bound (exclusive).
+ * @returns A function that takes a number `x` and returns `true` if `x` is in
+ *   the range, `false` otherwise.
+ */
+export declare const isInRange: (lowerBound: number, upperBound: number) => (x: number) => boolean;
+/**
+ * Creates a function that checks if a number `x` is within the range
+ * `lowerBound <= x <= upperBound`.
+ *
+ * @example
+ *
+ * ```ts
+ * const isPercentage = Num.isInRangeInclusive(0, 100);
+ *
+ * assert.isTrue(isPercentage(100));
+ *
+ * assert.isFalse(isPercentage(-1));
+ * ```
+ *
+ * @param lowerBound The lower bound (inclusive).
+ * @param upperBound The upper bound (inclusive).
+ * @returns A function that takes a number `x` and returns `true` if `x` is in
+ *   the range, `false` otherwise.
+ */
+export declare const isInRangeInclusive: (lowerBound: number, upperBound: number) => (x: number) => boolean;
+/**
+ * @template N - A SmallUint representing the exclusive upper bound
+ * @internal
+ * Helper type mapping each SmallUint N to the union of integers from 0 to N-1.
+ * Used internally for type-safe range operations.
+ *
+ * For example:
+ * - LT[3] = 0 | 1 | 2
+ * - LT[5] = 0 | 1 | 2 | 3 | 4
+ */
+type LT = Readonly<{
+    [N in SmallUint]: Index<N>;
+}>;
+/**
+ * @template N - A SmallUint representing the inclusive upper bound
+ * @internal
+ * Helper type mapping each SmallUint N to the union of integers from 0 to N (inclusive).
+ * Used internally for type-safe range operations with inclusive upper bounds.
+ *
+ * For example:
+ * - LEQ[3] = 0 | 1 | 2 | 3
+ * - LEQ[5] = 0 | 1 | 2 | 3 | 4 | 5
+ */
+type LEQ = Readonly<{
+    [N in SmallUint]: Index<N> | N;
+}>;
+/**
+ * Creates a type guard that checks if a number is an unsigned integer within a
+ * specified range.
+ *
+ * This function returns a predicate that validates whether a number is:
+ *
+ * - A safe integer (no floating point)
+ * - Within the range [lowerBound, upperBound)
+ *
+ * The returned type guard provides precise type narrowing when the bounds are
+ * SmallUint literals, making it ideal for array index validation.
+ *
+ * @example
+ *
+ * ```ts
+ * const indexGuard = Num.isUintInRange(0, 5);
+ *
+ * assert.isTrue(indexGuard(3));
+ *
+ * assert.isFalse(indexGuard(5));
+ *
+ * assert.isFalse(indexGuard(-1));
+ * ```
+ *
+ * @template L - The lower bound as a SmallUint literal type
+ * @template U - The upper bound as a SmallUint literal type
+ * @param lowerBound - The minimum value (inclusive)
+ * @param upperBound - The maximum value (exclusive)
+ * @returns A type guard function that validates and narrows number types
+ */
+export declare const isUintInRange: <L extends SmallUint, U extends SmallUint>(lowerBound: L, upperBound: U) => (x: number) => x is RelaxedExclude<LT[U], LT[Min<L>]>;
+/**
+ * Creates a type guard that checks if a number is an unsigned integer within a
+ * specified inclusive range.
+ *
+ * This function returns a predicate that validates whether a number is:
+ *
+ * - A safe integer (no floating point)
+ * - Within the range [lowerBound, upperBound] (both bounds inclusive)
+ *
+ * The returned type guard provides precise type narrowing when the bounds are
+ * SmallUint literals, useful for validating scores, percentages, or other
+ * bounded values.
+ *
+ * @example
+ *
+ * ```ts
+ * const inclusiveGuard = Num.isUintInRangeInclusive(0, 5);
+ *
+ * assert.isTrue(inclusiveGuard(5));
+ *
+ * assert.isFalse(inclusiveGuard(6));
+ * ```
+ *
+ * @template L - The lower bound as a SmallUint literal type
+ * @template U - The upper bound as a SmallUint literal type
+ * @param lowerBound - The minimum value (inclusive)
+ * @param upperBound - The maximum value (inclusive)
+ * @returns A type guard function that validates and narrows number types
+ */
+export declare const isUintInRangeInclusive: <L extends SmallUint, U extends SmallUint>(lowerBound: L, upperBound: U) => (x: number) => x is RelaxedExclude<LEQ[U], LT[Min<L>]>;
+/**
+ * Clamps a value within the given range. If the target value is invalid (not
+ * finite), returns the lower bound.
+ *
+ * Provides two usage patterns for maximum flexibility:
+ *
+ * - **Direct usage**: Pass all three arguments to get the clamped value
+ *   immediately
+ * - **Curried usage**: Pass bounds to get a reusable clamping function
+ *
+ * @example
+ *
+ * ```ts
+ * assert.isTrue(Num.clamp(150, 0, 100) === 100);
+ *
+ * assert.isTrue(Num.clamp(-50, 0, 100) === 0);
+ *
+ * const clampToPercentage = Num.clamp(0, 100);
+ *
+ * assert.isTrue(clampToPercentage(75) === 75);
+ *
+ * assert.isTrue(clampToPercentage(150) === 100);
+ * ```
+ */
+export declare function clamp(target: number, lowerBound: number, upperBound: number): number;
+export declare function clamp(lowerBound: number, upperBound: number): (target: number) => number;
+/**
+ * Adds two numbers, returning the tightest sound branded result type.
+ *
+ * The sign of the result is computed exactly (e.g. a non-negative plus a
+ * non-negative is non-negative); the integer/finite level is preserved, with
+ * `SafeInt` operands widening to `Int` because the sum may exceed the safe
+ * range. No clamping is performed — for a result that stays inside a bounded
+ * type, use that type's branded `add` instead.
+ *
+ * @param a - The first addend.
+ * @param b - The second addend.
+ * @returns `a + b`, typed as the tightest branded type guaranteed to contain
+ *   it.
+ */
+export declare const add: <A extends number, B extends number>(a: A, b: B) => AddResult<A, B>;
+/**
+ * Subtracts `b` from `a`, returning the tightest sound branded result type.
+ *
+ * The sign is computed exactly; the level is preserved (with `SafeInt` widening
+ * to `Int`). No clamping — for saturating subtraction that stays in a bounded
+ * type (e.g. `Uint.sub` clamping at `0`), use that type's branded `sub`.
+ *
+ * @param a - The minuend.
+ * @param b - The subtrahend.
+ * @returns `a - b`, typed as the tightest branded type guaranteed to contain
+ *   it.
+ */
+export declare const sub: <A extends number, B extends number>(a: A, b: B) => SubResult<A, B>;
+/**
+ * Multiplies two numbers, returning the tightest sound branded result type.
+ *
+ * The sign follows the usual product rule (e.g. negative times negative is
+ * positive); the level is preserved (with `SafeInt` widening to `Int`). No
+ * clamping.
+ *
+ * @param a - The first factor.
+ * @param b - The second factor.
+ * @returns `a * b`, typed as the tightest branded type guaranteed to contain
+ *   it.
+ */
+export declare const mul: <A extends number, B extends number>(a: A, b: B) => MulResult<A, B>;
+/**
+ * Performs type-safe exact division with a compile-time zero-check.
+ *
+ * The divisor must be typed as `NonZeroNumber` or a non-zero numeric literal.
+ * The result sign follows the quotient rule; because exact division can be
+ * fractional, the level is `finite` (or `number`).
+ *
+ * @param a - The dividend.
+ * @param b - The divisor (must be non-zero, enforced by types).
+ * @returns `a / b`, typed as the tightest branded type guaranteed to contain
+ *   it.
+ */
+export declare const div: <A extends number, B extends NonZeroNumber | SmallInt<'!=0'>>(a: A, b: B) => DivResult<A, B>;
+/**
+ * Performs integer division using floor division.
+ *
+ * Computes `⌊⌊a⌋ / b⌋`: the dividend is floored, the divisor is used as is, and
+ * the quotient is floored. For a positive integer divisor this is `⌊a / b⌋`.
+ * The divisor is not floored, since a divisor in `(-1, 1)` would floor to `0`
+ * or `-1`.
+ *
+ * Like `div`, the divisor must be typed as `NonZeroNumber` or a non-zero
+ * numeric literal. A divisor of magnitude below `1` makes the quotient larger
+ * than the dividend, so it overflows to `±Infinity` once `|a / b|` exceeds
+ * `Number.MAX_VALUE` (e.g. `1e300 / 1e-10`), as `mul` can.
+ *
+ * @param a - The dividend
+ * @param b - The divisor (must be non-zero, enforced by types)
+ * @returns The integer quotient `⌊⌊a⌋ / b⌋`
+ */
+export declare const divInt: <A extends number, B extends NonZeroNumber | SmallInt<'!=0'>>(a: A, b: B) => DivIntResult<A, B>;
+/**
+ * Rounds a number to a specified number of decimal places.
+ *
+ * Uses the standard rounding algorithm (round half up) to round the number to
+ * the given precision. The precision must be a positive safe integer.
+ *
+ * @param num - The number to round
+ * @param precision - The number of decimal places (must be positive)
+ * @returns The rounded number
+ */
+export declare const roundAt: (num: number, precision: PositiveSafeIntWithSmallInt) => number;
+/**
+ * Rounds a number to the nearest integer using bitwise operations.
+ *
+ * This function uses a bitwise OR trick for potentially faster rounding.
+ * Note: This implementation rounds half up for positive numbers but may behave
+ * differently for negative numbers compared to Math.round.
+ *
+ * @param num - The number to round
+ * @returns The rounded integer as an Int branded type
+ */
+export declare const roundToInt: (num: number) => Int;
+/**
+ * Creates a reusable rounding function with a fixed precision.
+ *
+ * This is a curried version of roundAt that returns a function configured to
+ * always round to the specified number of decimal places. Useful for creating
+ * consistent rounding behavior across multiple values.
+ *
+ * @param digit - The number of decimal places for rounding
+ * @returns A function that rounds numbers to the specified precision
+ */
+export declare const round: (digit: PositiveSafeIntWithSmallInt) => ((num: number) => number);
+/**
+ * Converts NaN values to undefined while preserving all other numbers.
+ *
+ * This function is useful for handling potentially invalid numeric operations
+ * in a type-safe way, converting NaN results to undefined for easier handling
+ * with optional chaining or nullish coalescing.
+ *
+ * @template N - The numeric type (literal or number)
+ * @param num - The number to check
+ * @returns The original number if not NaN, otherwise undefined
+ */
+export declare const mapNaN2Undefined: <N extends number>(num: N) => RelaxedExclude<N, NaNType> | undefined;
+/**
+ * Type-safe increment operation for SmallUint values.
+ *
+ * Increments a SmallUint (0-40) by 1 with the result type computed at compile
+ * time. This provides type-level arithmetic for small unsigned integers, useful
+ * for type-safe counter operations.
+ *
+ * @template N - A SmallUint literal type (0-40)
+ * @param n - The SmallUint value to increment
+ * @returns The incremented value with type Increment<N>
+ */
+export declare const increment: <N extends SmallUint>(n: N) => Increment<N>;
+/**
+ * Type-safe decrement operation for positive SmallInt values.
+ *
+ * Decrements a positive SmallInt (1-40) by 1 with the result type computed at
+ * compile time. This provides type-level arithmetic for small positive
+ * integers, useful for type-safe countdown operations.
+ *
+ * @template N - A positive SmallInt literal type (1-40)
+ * @param n - The positive SmallInt value to decrement
+ * @returns The decremented value with type Decrement<N>
+ */
+export declare const decrement: <N extends SmallPositiveInt>(n: N) => Decrement<N>;
+export {};
+//# sourceMappingURL=num.d.mts.map

package/dist/number/num/impl/num.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"num.d.mts","sourceRoot":"","sources":["../../../../src/number/num/impl/num.mts"],"names":[],"mappings":"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"}