ts-data-forge 6.13.0 → 7.0.0

package/dist/number/branded-types/negative-finite-number.mjs

@@ -0,0 +1,156 @@
+import { TsDataForgeInternals } from '../refined-number-utils.mjs';
+import { PositiveFiniteNumber } from './positive-finite-number.mjs';
+
+const typeNameInMessage = 'a negative finite number';
+const { MAX_VALUE, add, castType, clamp, is, max: max_, min: min_, pow, random, sub, } = TsDataForgeInternals.RefinedNumberUtils.operatorsForFloat({
+    nonZero: true,
+    MIN_VALUE: -Number.MAX_VALUE,
+    MAX_VALUE: -Number.MIN_VALUE,
+    typeNameInMessage,
+});
+/**
+ * Returns the absolute value of a negative finite number.
+ *
+ * The absolute value of a negative finite number is always a positive finite
+ * number, so the result is typed as a {@link PositiveFiniteNumber}.
+ *
+ * @param x - The negative finite number.
+ * @returns `|x|` as a PositiveFiniteNumber.
+ */
+const abs = (x) => PositiveFiniteNumber.clamp(Math.abs(x));
+const floor = (x) => 
+// eslint-disable-next-line total-functions/no-unsafe-type-assertion
+Math.floor(x);
+const ceil = (x) => 
+// eslint-disable-next-line total-functions/no-unsafe-type-assertion
+Math.ceil(x);
+const round = (x) => 
+// eslint-disable-next-line total-functions/no-unsafe-type-assertion
+Math.round(x);
+/**
+ * Checks if a number is a NegativeFiniteNumber (a finite number `< 0`).
+ *
+ * @param value The value to check.
+ * @returns `true` if the value is a NegativeFiniteNumber, `false` otherwise.
+ */
+const isNegativeFiniteNumber = is;
+/**
+ * Casts a number to a NegativeFiniteNumber type.
+ *
+ * @param value The value to cast.
+ * @returns The value as a NegativeFiniteNumber type.
+ * @throws {TypeError} If the value is not a negative finite number.
+ */
+const asNegativeFiniteNumber = castType;
+/**
+ * Namespace providing type-safe arithmetic operations for negative finite
+ * numbers.
+ *
+ * All operations keep results finite (excluding NaN and Infinity). Operations
+ * that stay within the negative finite numbers clamp their results to the valid
+ * range, while operations whose result leaves the set (`mul`, `div`, `abs`) are
+ * typed to reflect the actual sign of the result.
+ */
+const NegativeFiniteNumber = {
+    /**
+     * Type guard to check if a value is a NegativeFiniteNumber.
+     *
+     * @param value The value to check.
+     * @returns `true` if the value is a negative finite number, `false`
+     *   otherwise.
+     */
+    is,
+    /**
+     * The maximum value for a negative finite number.
+     *
+     * @readonly
+     */
+    MAX_VALUE,
+    /**
+     * Returns the absolute value of a negative finite number.
+     *
+     * @param a The negative finite number.
+     * @returns The absolute value as a PositiveFiniteNumber.
+     */
+    abs,
+    /**
+     * Returns the smaller of two NegativeFiniteNumber values.
+     *
+     * @param a The first NegativeFiniteNumber.
+     * @param b The second NegativeFiniteNumber.
+     * @returns The minimum value as a NegativeFiniteNumber.
+     */
+    min: min_,
+    /**
+     * Returns the larger of two NegativeFiniteNumber values.
+     *
+     * @param a The first NegativeFiniteNumber.
+     * @param b The second NegativeFiniteNumber.
+     * @returns The maximum value as a NegativeFiniteNumber.
+     */
+    max: max_,
+    /**
+     * Clamps a number to the negative finite range.
+     *
+     * @param value The number to clamp.
+     * @returns The value clamped to `(-∞, 0)` as a NegativeFiniteNumber.
+     */
+    clamp,
+    /**
+     * Rounds down a NegativeFiniteNumber to the nearest integer.
+     *
+     * @param x The NegativeFiniteNumber to round down.
+     * @returns The floor value as a NegativeInt (always `<= -1`).
+     */
+    floor,
+    /**
+     * Rounds up a NegativeFiniteNumber to the nearest integer.
+     *
+     * @param x The NegativeFiniteNumber to round up.
+     * @returns The ceiling value as a NonPositiveInt (can be 0).
+     */
+    ceil,
+    /**
+     * Rounds a NegativeFiniteNumber to the nearest integer.
+     *
+     * @param x The NegativeFiniteNumber to round.
+     * @returns The rounded value as a NonPositiveInt (can be 0 if x > -0.5).
+     */
+    round,
+    /**
+     * Generates a random NegativeFiniteNumber value.
+     *
+     * @returns A random negative finite number.
+     */
+    random,
+    /**
+     * Raises a NegativeFiniteNumber to the power of another NegativeFiniteNumber.
+     *
+     * @param a The base NegativeFiniteNumber.
+     * @param b The exponent NegativeFiniteNumber.
+     * @returns `a ** b` clamped to `(-∞, 0)` as a NegativeFiniteNumber.
+     */
+    pow,
+    /**
+     * Adds two NegativeFiniteNumber values.
+     *
+     * @param a The first NegativeFiniteNumber.
+     * @param b The second NegativeFiniteNumber.
+     * @returns `a + b` as a NegativeFiniteNumber.
+     */
+    add,
+    /**
+     * Subtracts one NegativeFiniteNumber from another.
+     *
+     * The mathematical result can be positive, so it is clamped to the negative
+     * finite range (maximum `-Number.MIN_VALUE`).
+     *
+     * @param a The minuend NegativeFiniteNumber.
+     * @param b The subtrahend NegativeFiniteNumber.
+     * @returns `a - b` clamped to `(-∞, 0)` as a NegativeFiniteNumber.
+     */
+    sub,
+};
+
+export { NegativeFiniteNumber, asNegativeFiniteNumber, isNegativeFiniteNumber };
+//# sourceMappingURL=negative-finite-number.mjs.map

package/dist/number/branded-types/negative-finite-number.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"negative-finite-number.mjs","sources":["../../../src/number/branded-types/negative-finite-number.mts"],"sourcesContent":[null],"names":[],"mappings":";;;AAQA,MAAM,iBAAiB,GAAG,0BAA0B;AAEpD,MAAM,EACJ,SAAS,EACT,GAAG,EACH,QAAQ,EACR,KAAK,EACL,EAAE,EACF,GAAG,EAAE,IAAI,EACT,GAAG,EAAE,IAAI,EACT,GAAG,EACH,MAAM,EACN,GAAG,GACJ,GAAG,oBAAoB,CAAC,kBAAkB,CAAC,iBAAiB,CAI3D;AACA,IAAA,OAAO,EAAE,IAAI;AACb,IAAA,SAAS,EAAE,CAAC,MAAM,CAAC,SAAS;AAC5B,IAAA,SAAS,EAAE,CAAC,MAAM,CAAC,SAAS;IAC5B,iBAAiB;AACT,CAAA,CAAC;AAEX;;;;;;;;AAQG;AACH,MAAM,GAAG,GAAG,CAAC,CAAc,KACzB,oBAAoB,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAEzC,MAAM,KAAK,GAAG,CACZ,CAAc;AAEd;AACA,IAAI,CAAC,KAAK,CAAC,CAAC,CAA+D;AAE7E,MAAM,IAAI,GAAG,CACX,CAAc;AAId;AACA,IAAI,CAAC,IAAI,CAAC,CAAC,CAEV;AAEH,MAAM,KAAK,GAAG,CACZ,CAAc;AAId;AACA,IAAI,CAAC,KAAK,CACR,CAAC,CAGF;AAEH;;;;;AAKG;AACI,MAAM,sBAAsB,GAAG;AAEtC;;;;;;AAMG;AACI,MAAM,sBAAsB,GAAG;AAEtC;;;;;;;;AAQG;AACI,MAAM,oBAAoB,GAAG;AAClC;;;;;;AAMG;IACH,EAAE;AAEF;;;;AAIG;IACH,SAAS;AAET;;;;;AAKG;IACH,GAAG;AAEH;;;;;;AAMG;AACH,IAAA,GAAG,EAAE,IAAI;AAET;;;;;;AAMG;AACH,IAAA,GAAG,EAAE,IAAI;AAET;;;;;AAKG;IACH,KAAK;AAEL;;;;;AAKG;IACH,KAAK;AAEL;;;;;AAKG;IACH,IAAI;AAEJ;;;;;AAKG;IACH,KAAK;AAEL;;;;AAIG;IACH,MAAM;AAEN;;;;;;AAMG;IACH,GAAG;AAEH;;;;;;AAMG;IACH,GAAG;AAEH;;;;;;;;;AASG;IACH,GAAG;;;;;"}

package/dist/number/branded-types/negative-int.d.mts

@@ -0,0 +1,120 @@
+import { type NegativeInt as TtfImported_NegativeInt, type WithSmallInt } from 'ts-type-forge';
+import { PositiveInt } from './positive-int.mjs';
+export type NegativeInt = TtfImported_NegativeInt;
+type ElementType = NegativeInt;
+/**
+ * Checks if a number is a NegativeInt (a negative integer `<= -1`).
+ *
+ * @param value The value to check.
+ * @returns `true` if the value is a NegativeInt, `false` otherwise.
+ */
+export declare const isNegativeInt: (a: number) => a is TtfImported_NegativeInt;
+/**
+ * Casts a number to a NegativeInt type.
+ *
+ * @param value The value to cast.
+ * @returns The value as a NegativeInt type.
+ * @throws {TypeError} If the value is not a negative integer.
+ */
+export declare const asNegativeInt: <N extends number>(x: N) => number & {
+    readonly NaNValue: false;
+    readonly Finite: true;
+    readonly Int: true;
+    readonly ">=0": false;
+    readonly "!=0": true;
+    readonly "<=0": true;
+    readonly "< 2^15": true;
+    readonly "< 2^16": true;
+    readonly "< 2^31": true;
+    readonly "< 2^32": true;
+} & Readonly<{
+    'TSTypeForgeInternals--edd2f9ce-7ca5-45b0-9d1a-bd61b9b5d9c3': unknown;
+}> & N;
+/**
+ * Namespace providing type-safe arithmetic operations for negative integers.
+ *
+ * NegativeInt represents integers that are strictly less than zero (`<= -1`).
+ * Operations that stay within the negative integers (such as `add`) clamp their
+ * results to the valid range, while operations whose result leaves the set
+ * (`mul`, `div`, `abs`) are typed to reflect the actual sign of the result.
+ */
+export declare const NegativeInt: {
+    /**
+     * Type guard to check if a value is a NegativeInt.
+     *
+     * @param value The value to check.
+     * @returns `true` if the value is a negative integer, `false` otherwise.
+     */
+    readonly is: (a: number) => a is TtfImported_NegativeInt;
+    /**
+     * The maximum value for a negative integer.
+     *
+     * @readonly
+     */
+    readonly MAX_VALUE: -1;
+    /**
+     * Returns the absolute value of a negative integer.
+     *
+     * @param a The negative integer.
+     * @returns The absolute value as a PositiveInt.
+     */
+    readonly abs: (x: WithSmallInt<ElementType>) => PositiveInt;
+    /**
+     * Returns the smaller of two negative integers.
+     *
+     * @param a The first negative integer.
+     * @param b The second negative integer.
+     * @returns The minimum value as a NegativeInt.
+     */
+    readonly min: (...values: readonly WithSmallInt<TtfImported_NegativeInt>[]) => TtfImported_NegativeInt;
+    /**
+     * Returns the larger of two negative integers.
+     *
+     * @param a The first negative integer.
+     * @param b The second negative integer.
+     * @returns The maximum value as a NegativeInt.
+     */
+    readonly max: (...values: readonly WithSmallInt<TtfImported_NegativeInt>[]) => TtfImported_NegativeInt;
+    /**
+     * Clamps a number to the negative integer range.
+     *
+     * @param value The number to clamp.
+     * @returns The value clamped to `[-∞, -1]` as a NegativeInt.
+     */
+    readonly clamp: (x: number) => TtfImported_NegativeInt;
+    /**
+     * Generates a random NegativeInt value within the valid range.
+     *
+     * @returns A random negative integer.
+     */
+    readonly random: (min?: WithSmallInt<TtfImported_NegativeInt> | undefined, max?: WithSmallInt<TtfImported_NegativeInt> | undefined) => TtfImported_NegativeInt;
+    /**
+     * Raises a negative integer to the power of another negative integer.
+     *
+     * @param a The base negative integer.
+     * @param b The exponent negative integer.
+     * @returns `a ** b` clamped to the negative integer range.
+     */
+    readonly pow: (x: WithSmallInt<TtfImported_NegativeInt>, y: WithSmallInt<TtfImported_NegativeInt>) => TtfImported_NegativeInt;
+    /**
+     * Adds two negative integers.
+     *
+     * @param a The first negative integer.
+     * @param b The second negative integer.
+     * @returns `a + b` as a NegativeInt.
+     */
+    readonly add: (x: WithSmallInt<TtfImported_NegativeInt>, y: WithSmallInt<TtfImported_NegativeInt>) => TtfImported_NegativeInt;
+    /**
+     * Subtracts one negative integer from another.
+     *
+     * The mathematical result can be positive, so it is clamped to the negative
+     * integer range (maximum `-1`).
+     *
+     * @param a The minuend negative integer.
+     * @param b The subtrahend negative integer.
+     * @returns `a - b` clamped to the negative integer range.
+     */
+    readonly sub: (x: WithSmallInt<TtfImported_NegativeInt>, y: WithSmallInt<TtfImported_NegativeInt>) => TtfImported_NegativeInt;
+};
+export {};
+//# sourceMappingURL=negative-int.d.mts.map

package/dist/number/branded-types/negative-int.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"negative-int.d.mts","sourceRoot":"","sources":["../../../src/number/branded-types/negative-int.mts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,WAAW,IAAI,uBAAuB,EAC3C,KAAK,YAAY,EAClB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD,MAAM,MAAM,WAAW,GAAG,uBAAuB,CAAC;AAElD,KAAK,WAAW,GAAG,WAAW,CAAC;AAuC/B;;;;;GAKG;AACH,eAAO,MAAM,aAAa,6CAAK,CAAC;AAEhC;;;;;;GAMG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;MAAW,CAAC;AAEtC;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW;IACtB;;;;;OAKG;;IAGH;;;;OAIG;;IAGH;;;;;OAKG;sBAjDW,YAAY,CAAC,WAAW,CAAC,KAAG,WAAW;IAoDrD;;;;;;OAMG;;IAGH;;;;;;OAMG;;IAGH;;;;;OAKG;;IAGH;;;;OAIG;;IAGH;;;;;;OAMG;;IAGH;;;;;;OAMG;;IAGH;;;;;;;;;OASG;;CAEK,CAAC"}

package/dist/number/branded-types/negative-int.mjs

@@ -0,0 +1,125 @@
+import { TsDataForgeInternals } from '../refined-number-utils.mjs';
+import { PositiveInt } from './positive-int.mjs';
+
+const typeNameInMessage = 'a negative integer';
+const { MAX_VALUE, add, castType, clamp, is, max: max_, min: min_, pow, random, sub, } = TsDataForgeInternals.RefinedNumberUtils.operatorsForInteger({
+    integerOrSafeInteger: 'Integer',
+    nonZero: true,
+    MIN_VALUE: -Number.MAX_VALUE,
+    MAX_VALUE: -1,
+    typeNameInMessage,
+});
+/**
+ * Returns the absolute value of a negative integer.
+ *
+ * The absolute value of a negative integer is always a positive integer
+ * (`>= 1`), so the result is typed as a {@link PositiveInt}.
+ *
+ * @param x - The negative integer.
+ * @returns `|x|` as a PositiveInt.
+ */
+const abs = (x) => PositiveInt.clamp(Math.abs(x));
+/**
+ * Checks if a number is a NegativeInt (a negative integer `<= -1`).
+ *
+ * @param value The value to check.
+ * @returns `true` if the value is a NegativeInt, `false` otherwise.
+ */
+const isNegativeInt = is;
+/**
+ * Casts a number to a NegativeInt type.
+ *
+ * @param value The value to cast.
+ * @returns The value as a NegativeInt type.
+ * @throws {TypeError} If the value is not a negative integer.
+ */
+const asNegativeInt = castType;
+/**
+ * Namespace providing type-safe arithmetic operations for negative integers.
+ *
+ * NegativeInt represents integers that are strictly less than zero (`<= -1`).
+ * Operations that stay within the negative integers (such as `add`) clamp their
+ * results to the valid range, while operations whose result leaves the set
+ * (`mul`, `div`, `abs`) are typed to reflect the actual sign of the result.
+ */
+const NegativeInt = {
+    /**
+     * Type guard to check if a value is a NegativeInt.
+     *
+     * @param value The value to check.
+     * @returns `true` if the value is a negative integer, `false` otherwise.
+     */
+    is,
+    /**
+     * The maximum value for a negative integer.
+     *
+     * @readonly
+     */
+    MAX_VALUE,
+    /**
+     * Returns the absolute value of a negative integer.
+     *
+     * @param a The negative integer.
+     * @returns The absolute value as a PositiveInt.
+     */
+    abs,
+    /**
+     * Returns the smaller of two negative integers.
+     *
+     * @param a The first negative integer.
+     * @param b The second negative integer.
+     * @returns The minimum value as a NegativeInt.
+     */
+    min: min_,
+    /**
+     * Returns the larger of two negative integers.
+     *
+     * @param a The first negative integer.
+     * @param b The second negative integer.
+     * @returns The maximum value as a NegativeInt.
+     */
+    max: max_,
+    /**
+     * Clamps a number to the negative integer range.
+     *
+     * @param value The number to clamp.
+     * @returns The value clamped to `[-∞, -1]` as a NegativeInt.
+     */
+    clamp,
+    /**
+     * Generates a random NegativeInt value within the valid range.
+     *
+     * @returns A random negative integer.
+     */
+    random,
+    /**
+     * Raises a negative integer to the power of another negative integer.
+     *
+     * @param a The base negative integer.
+     * @param b The exponent negative integer.
+     * @returns `a ** b` clamped to the negative integer range.
+     */
+    pow,
+    /**
+     * Adds two negative integers.
+     *
+     * @param a The first negative integer.
+     * @param b The second negative integer.
+     * @returns `a + b` as a NegativeInt.
+     */
+    add,
+    /**
+     * Subtracts one negative integer from another.
+     *
+     * The mathematical result can be positive, so it is clamped to the negative
+     * integer range (maximum `-1`).
+     *
+     * @param a The minuend negative integer.
+     * @param b The subtrahend negative integer.
+     * @returns `a - b` clamped to the negative integer range.
+     */
+    sub,
+};
+
+export { NegativeInt, asNegativeInt, isNegativeInt };
+//# sourceMappingURL=negative-int.mjs.map

package/dist/number/branded-types/negative-int.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"negative-int.mjs","sources":["../../../src/number/branded-types/negative-int.mts"],"sourcesContent":[null],"names":[],"mappings":";;;AAWA,MAAM,iBAAiB,GAAG,oBAAoB;AAE9C,MAAM,EACJ,SAAS,EACT,GAAG,EACH,QAAQ,EACR,KAAK,EACL,EAAE,EACF,GAAG,EAAE,IAAI,EACT,GAAG,EAAE,IAAI,EACT,GAAG,EACH,MAAM,EACN,GAAG,GACJ,GAAG,oBAAoB,CAAC,kBAAkB,CAAC,mBAAmB,CAI7D;AACA,IAAA,oBAAoB,EAAE,SAAS;AAC/B,IAAA,OAAO,EAAE,IAAI;AACb,IAAA,SAAS,EAAE,CAAC,MAAM,CAAC,SAAS;IAC5B,SAAS,EAAE,EAAE;IACb,iBAAiB;AACT,CAAA,CAAC;AAEX;;;;;;;;AAQG;AACH,MAAM,GAAG,GAAG,CAAC,CAA4B,KACvC,WAAW,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAEhC;;;;;AAKG;AACI,MAAM,aAAa,GAAG;AAE7B;;;;;;AAMG;AACI,MAAM,aAAa,GAAG;AAE7B;;;;;;;AAOG;AACI,MAAM,WAAW,GAAG;AACzB;;;;;AAKG;IACH,EAAE;AAEF;;;;AAIG;IACH,SAAS;AAET;;;;;AAKG;IACH,GAAG;AAEH;;;;;;AAMG;AACH,IAAA,GAAG,EAAE,IAAI;AAET;;;;;;AAMG;AACH,IAAA,GAAG,EAAE,IAAI;AAET;;;;;AAKG;IACH,KAAK;AAEL;;;;AAIG;IACH,MAAM;AAEN;;;;;;AAMG;IACH,GAAG;AAEH;;;;;;AAMG;IACH,GAAG;AAEH;;;;;;;;;AASG;IACH,GAAG;;;;;"}

package/dist/number/branded-types/negative-safe-int.d.mts

@@ -0,0 +1,132 @@
+import { type NegativeSafeInt as TtfImported_NegativeSafeInt, type WithSmallInt } from 'ts-type-forge';
+import { PositiveSafeInt } from './positive-safe-int.mjs';
+export type NegativeSafeInt = TtfImported_NegativeSafeInt;
+type ElementType = NegativeSafeInt;
+/**
+ * Checks if a number is a NegativeSafeInt (a negative safe integer in the range
+ * `[Number.MIN_SAFE_INTEGER, -1]`).
+ *
+ * @param value The value to check.
+ * @returns `true` if the value is a NegativeSafeInt, `false` otherwise.
+ */
+export declare const isNegativeSafeInt: (a: number) => a is TtfImported_NegativeSafeInt;
+/**
+ * Casts a number to a NegativeSafeInt type.
+ *
+ * @param value The value to cast.
+ * @returns The value as a NegativeSafeInt type.
+ * @throws {TypeError} If the value is not a negative safe integer.
+ */
+export declare const asNegativeSafeInt: <N extends number>(x: N) => number & {
+    readonly NaNValue: false;
+    readonly Finite: true;
+    readonly Int: true;
+    readonly ">=0": false;
+    readonly "!=0": true;
+    readonly "<=0": true;
+    readonly "< 2^15": true;
+    readonly "< 2^16": true;
+    readonly "< 2^31": true;
+    readonly "< 2^32": true;
+    readonly SafeInt: true;
+} & Readonly<{
+    'TSTypeForgeInternals--edd2f9ce-7ca5-45b0-9d1a-bd61b9b5d9c3': unknown;
+}> & N;
+/**
+ * Namespace providing type-safe arithmetic operations for negative safe
+ * integers.
+ *
+ * NegativeSafeInt represents safe integers that are strictly less than zero
+ * (`[Number.MIN_SAFE_INTEGER, -1]`). Operations that stay within the negative
+ * safe integers clamp their results to the valid range, while operations whose
+ * result leaves the set (`mul`, `div`, `abs`) are typed to reflect the actual
+ * sign of the result.
+ */
+export declare const NegativeSafeInt: {
+    /**
+     * Type guard to check if a value is a NegativeSafeInt.
+     *
+     * @param value The value to check.
+     * @returns `true` if the value is a negative safe integer, `false` otherwise.
+     */
+    readonly is: (a: number) => a is TtfImported_NegativeSafeInt;
+    /**
+     * The minimum value for a negative safe integer.
+     *
+     * @readonly
+     */
+    readonly MIN_VALUE: number;
+    /**
+     * The maximum value for a negative safe integer.
+     *
+     * @readonly
+     */
+    readonly MAX_VALUE: -1;
+    /**
+     * Returns the absolute value of a negative safe integer.
+     *
+     * @param a The negative safe integer.
+     * @returns The absolute value as a PositiveSafeInt.
+     */
+    readonly abs: (x: WithSmallInt<ElementType>) => PositiveSafeInt;
+    /**
+     * Returns the smaller of two negative safe integers.
+     *
+     * @param a The first negative safe integer.
+     * @param b The second negative safe integer.
+     * @returns The minimum value as a NegativeSafeInt.
+     */
+    readonly min: (...values: readonly WithSmallInt<TtfImported_NegativeSafeInt>[]) => TtfImported_NegativeSafeInt;
+    /**
+     * Returns the larger of two negative safe integers.
+     *
+     * @param a The first negative safe integer.
+     * @param b The second negative safe integer.
+     * @returns The maximum value as a NegativeSafeInt.
+     */
+    readonly max: (...values: readonly WithSmallInt<TtfImported_NegativeSafeInt>[]) => TtfImported_NegativeSafeInt;
+    /**
+     * Clamps a number to the NegativeSafeInt range.
+     *
+     * @param value The number to clamp.
+     * @returns The value clamped to `[Number.MIN_SAFE_INTEGER, -1]` as a
+     *   NegativeSafeInt.
+     */
+    readonly clamp: (x: number) => TtfImported_NegativeSafeInt;
+    /**
+     * Generates a random NegativeSafeInt value within the valid range.
+     *
+     * @returns A random NegativeSafeInt between Number.MIN_SAFE_INTEGER and -1.
+     */
+    readonly random: (min?: WithSmallInt<TtfImported_NegativeSafeInt> | undefined, max?: WithSmallInt<TtfImported_NegativeSafeInt> | undefined) => TtfImported_NegativeSafeInt;
+    /**
+     * Raises a negative safe integer to the power of another negative safe
+     * integer.
+     *
+     * @param a The base negative safe integer.
+     * @param b The exponent negative safe integer.
+     * @returns `a ** b` clamped to the NegativeSafeInt range.
+     */
+    readonly pow: (x: WithSmallInt<TtfImported_NegativeSafeInt>, y: WithSmallInt<TtfImported_NegativeSafeInt>) => TtfImported_NegativeSafeInt;
+    /**
+     * Adds two negative safe integers.
+     *
+     * @param a The first negative safe integer.
+     * @param b The second negative safe integer.
+     * @returns `a + b` clamped to the NegativeSafeInt range.
+     */
+    readonly add: (x: WithSmallInt<TtfImported_NegativeSafeInt>, y: WithSmallInt<TtfImported_NegativeSafeInt>) => TtfImported_NegativeSafeInt;
+    /**
+     * Subtracts one negative safe integer from another.
+     *
+     * The mathematical result can be positive, so it is clamped to the
+     * NegativeSafeInt range (maximum `-1`).
+     *
+     * @param a The minuend negative safe integer.
+     * @param b The subtrahend negative safe integer.
+     * @returns `a - b` clamped to the NegativeSafeInt range.
+     */
+    readonly sub: (x: WithSmallInt<TtfImported_NegativeSafeInt>, y: WithSmallInt<TtfImported_NegativeSafeInt>) => TtfImported_NegativeSafeInt;
+};
+export {};
+//# sourceMappingURL=negative-safe-int.d.mts.map

package/dist/number/branded-types/negative-safe-int.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"negative-safe-int.d.mts","sourceRoot":"","sources":["../../../src/number/branded-types/negative-safe-int.mts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,eAAe,IAAI,2BAA2B,EACnD,KAAK,YAAY,EAClB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAE1D,MAAM,MAAM,eAAe,GAAG,2BAA2B,CAAC;AAE1D,KAAK,WAAW,GAAG,eAAe,CAAC;AAwCnC;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,iDAAK,CAAC;AAEpC;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;MAAW,CAAC;AAE1C;;;;;;;;;GASG;AACH,eAAO,MAAM,eAAe;IAC1B;;;;;OAKG;;IAGH;;;;OAIG;;IAGH;;;;OAIG;;IAGH;;;;;OAKG;sBA3DW,YAAY,CAAC,WAAW,CAAC,KAAG,eAAe;IA8DzD;;;;;;OAMG;;IAGH;;;;;;OAMG;;IAGH;;;;;;OAMG;;IAGH;;;;OAIG;;IAGH;;;;;;;OAOG;;IAGH;;;;;;OAMG;;IAGH;;;;;;;;;OASG;;CAEK,CAAC"}

package/dist/number/branded-types/negative-safe-int.mjs

@@ -0,0 +1,136 @@
+import { TsDataForgeInternals } from '../refined-number-utils.mjs';
+import { PositiveSafeInt } from './positive-safe-int.mjs';
+
+const typeNameInMessage = 'a negative safe integer';
+const { MAX_VALUE, MIN_VALUE, add, castType, clamp, is, max: max_, min: min_, pow, random, sub, } = TsDataForgeInternals.RefinedNumberUtils.operatorsForInteger({
+    integerOrSafeInteger: 'SafeInteger',
+    nonZero: true,
+    MIN_VALUE: Number.MIN_SAFE_INTEGER,
+    MAX_VALUE: -1,
+    typeNameInMessage,
+});
+/**
+ * Returns the absolute value of a negative safe integer.
+ *
+ * The absolute value of a negative safe integer is always a positive safe
+ * integer (`>= 1`), so the result is typed as a {@link PositiveSafeInt}.
+ *
+ * @param x - The negative safe integer.
+ * @returns `|x|` as a PositiveSafeInt.
+ */
+const abs = (x) => PositiveSafeInt.clamp(Math.abs(x));
+/**
+ * Checks if a number is a NegativeSafeInt (a negative safe integer in the range
+ * `[Number.MIN_SAFE_INTEGER, -1]`).
+ *
+ * @param value The value to check.
+ * @returns `true` if the value is a NegativeSafeInt, `false` otherwise.
+ */
+const isNegativeSafeInt = is;
+/**
+ * Casts a number to a NegativeSafeInt type.
+ *
+ * @param value The value to cast.
+ * @returns The value as a NegativeSafeInt type.
+ * @throws {TypeError} If the value is not a negative safe integer.
+ */
+const asNegativeSafeInt = castType;
+/**
+ * Namespace providing type-safe arithmetic operations for negative safe
+ * integers.
+ *
+ * NegativeSafeInt represents safe integers that are strictly less than zero
+ * (`[Number.MIN_SAFE_INTEGER, -1]`). Operations that stay within the negative
+ * safe integers clamp their results to the valid range, while operations whose
+ * result leaves the set (`mul`, `div`, `abs`) are typed to reflect the actual
+ * sign of the result.
+ */
+const NegativeSafeInt = {
+    /**
+     * Type guard to check if a value is a NegativeSafeInt.
+     *
+     * @param value The value to check.
+     * @returns `true` if the value is a negative safe integer, `false` otherwise.
+     */
+    is,
+    /**
+     * The minimum value for a negative safe integer.
+     *
+     * @readonly
+     */
+    MIN_VALUE,
+    /**
+     * The maximum value for a negative safe integer.
+     *
+     * @readonly
+     */
+    MAX_VALUE,
+    /**
+     * Returns the absolute value of a negative safe integer.
+     *
+     * @param a The negative safe integer.
+     * @returns The absolute value as a PositiveSafeInt.
+     */
+    abs,
+    /**
+     * Returns the smaller of two negative safe integers.
+     *
+     * @param a The first negative safe integer.
+     * @param b The second negative safe integer.
+     * @returns The minimum value as a NegativeSafeInt.
+     */
+    min: min_,
+    /**
+     * Returns the larger of two negative safe integers.
+     *
+     * @param a The first negative safe integer.
+     * @param b The second negative safe integer.
+     * @returns The maximum value as a NegativeSafeInt.
+     */
+    max: max_,
+    /**
+     * Clamps a number to the NegativeSafeInt range.
+     *
+     * @param value The number to clamp.
+     * @returns The value clamped to `[Number.MIN_SAFE_INTEGER, -1]` as a
+     *   NegativeSafeInt.
+     */
+    clamp,
+    /**
+     * Generates a random NegativeSafeInt value within the valid range.
+     *
+     * @returns A random NegativeSafeInt between Number.MIN_SAFE_INTEGER and -1.
+     */
+    random,
+    /**
+     * Raises a negative safe integer to the power of another negative safe
+     * integer.
+     *
+     * @param a The base negative safe integer.
+     * @param b The exponent negative safe integer.
+     * @returns `a ** b` clamped to the NegativeSafeInt range.
+     */
+    pow,
+    /**
+     * Adds two negative safe integers.
+     *
+     * @param a The first negative safe integer.
+     * @param b The second negative safe integer.
+     * @returns `a + b` clamped to the NegativeSafeInt range.
+     */
+    add,
+    /**
+     * Subtracts one negative safe integer from another.
+     *
+     * The mathematical result can be positive, so it is clamped to the
+     * NegativeSafeInt range (maximum `-1`).
+     *
+     * @param a The minuend negative safe integer.
+     * @param b The subtrahend negative safe integer.
+     * @returns `a - b` clamped to the NegativeSafeInt range.
+     */
+    sub,
+};
+
+export { NegativeSafeInt, asNegativeSafeInt, isNegativeSafeInt };
+//# sourceMappingURL=negative-safe-int.mjs.map

package/dist/number/branded-types/negative-safe-int.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"negative-safe-int.mjs","sources":["../../../src/number/branded-types/negative-safe-int.mts"],"sourcesContent":[null],"names":[],"mappings":";;;AAWA,MAAM,iBAAiB,GAAG,yBAAyB;AAEnD,MAAM,EACJ,SAAS,EACT,SAAS,EACT,GAAG,EACH,QAAQ,EACR,KAAK,EACL,EAAE,EACF,GAAG,EAAE,IAAI,EACT,GAAG,EAAE,IAAI,EACT,GAAG,EACH,MAAM,EACN,GAAG,GACJ,GAAG,oBAAoB,CAAC,kBAAkB,CAAC,mBAAmB,CAI7D;AACA,IAAA,oBAAoB,EAAE,aAAa;AACnC,IAAA,OAAO,EAAE,IAAI;IACb,SAAS,EAAE,MAAM,CAAC,gBAAgB;IAClC,SAAS,EAAE,EAAE;IACb,iBAAiB;AACT,CAAA,CAAC;AAEX;;;;;;;;AAQG;AACH,MAAM,GAAG,GAAG,CAAC,CAA4B,KACvC,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAEpC;;;;;;AAMG;AACI,MAAM,iBAAiB,GAAG;AAEjC;;;;;;AAMG;AACI,MAAM,iBAAiB,GAAG;AAEjC;;;;;;;;;AASG;AACI,MAAM,eAAe,GAAG;AAC7B;;;;;AAKG;IACH,EAAE;AAEF;;;;AAIG;IACH,SAAS;AAET;;;;AAIG;IACH,SAAS;AAET;;;;;AAKG;IACH,GAAG;AAEH;;;;;;AAMG;AACH,IAAA,GAAG,EAAE,IAAI;AAET;;;;;;AAMG;AACH,IAAA,GAAG,EAAE,IAAI;AAET;;;;;;AAMG;IACH,KAAK;AAEL;;;;AAIG;IACH,MAAM;AAEN;;;;;;;AAOG;IACH,GAAG;AAEH;;;;;;AAMG;IACH,GAAG;AAEH;;;;;;;;;AASG;IACH,GAAG;;;;;"}