ts-data-forge 6.13.1 → 7.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (174) hide show
  1. package/README.md +2 -2
  2. package/dist/array/impl/array-utils-iterators.mjs +6 -0
  3. package/dist/array/impl/array-utils-iterators.mjs.map +1 -1
  4. package/dist/array/impl/array-utils-modification.mjs +6 -0
  5. package/dist/array/impl/array-utils-modification.mjs.map +1 -1
  6. package/dist/array/impl/array-utils-reducing-value.mjs +6 -0
  7. package/dist/array/impl/array-utils-reducing-value.mjs.map +1 -1
  8. package/dist/array/impl/array-utils-search.mjs +6 -0
  9. package/dist/array/impl/array-utils-search.mjs.map +1 -1
  10. package/dist/array/impl/array-utils-slice-clamped.mjs +6 -0
  11. package/dist/array/impl/array-utils-slice-clamped.mjs.map +1 -1
  12. package/dist/array/impl/array-utils-slicing.mjs +6 -0
  13. package/dist/array/impl/array-utils-slicing.mjs.map +1 -1
  14. package/dist/array/impl/array-utils-transformation.mjs +6 -0
  15. package/dist/array/impl/array-utils-transformation.mjs.map +1 -1
  16. package/dist/array/impl/array-utils-validation.mjs +6 -0
  17. package/dist/array/impl/array-utils-validation.mjs.map +1 -1
  18. package/dist/collections/imap-mapped.mjs +6 -0
  19. package/dist/collections/imap-mapped.mjs.map +1 -1
  20. package/dist/collections/imap.mjs +6 -0
  21. package/dist/collections/imap.mjs.map +1 -1
  22. package/dist/collections/iset-mapped.mjs +6 -0
  23. package/dist/collections/iset-mapped.mjs.map +1 -1
  24. package/dist/collections/iset.mjs +6 -0
  25. package/dist/collections/iset.mjs.map +1 -1
  26. package/dist/collections/queue.mjs +6 -0
  27. package/dist/collections/queue.mjs.map +1 -1
  28. package/dist/collections/stack.mjs +6 -0
  29. package/dist/collections/stack.mjs.map +1 -1
  30. package/dist/entry-point.mjs +6 -0
  31. package/dist/entry-point.mjs.map +1 -1
  32. package/dist/index.mjs +6 -0
  33. package/dist/index.mjs.map +1 -1
  34. package/dist/iterator/range.mjs +6 -0
  35. package/dist/iterator/range.mjs.map +1 -1
  36. package/dist/json/json.mjs +6 -0
  37. package/dist/json/json.mjs.map +1 -1
  38. package/dist/number/branded-types/finite-number.d.mts +1 -1
  39. package/dist/number/branded-types/index.d.mts +6 -0
  40. package/dist/number/branded-types/index.d.mts.map +1 -1
  41. package/dist/number/branded-types/index.mjs +6 -0
  42. package/dist/number/branded-types/index.mjs.map +1 -1
  43. package/dist/number/branded-types/int.d.mts +1 -2
  44. package/dist/number/branded-types/int.d.mts.map +1 -1
  45. package/dist/number/branded-types/int16.d.mts +2 -3
  46. package/dist/number/branded-types/int16.d.mts.map +1 -1
  47. package/dist/number/branded-types/int32.d.mts +2 -3
  48. package/dist/number/branded-types/int32.d.mts.map +1 -1
  49. package/dist/number/branded-types/negative-finite-number.d.mts +143 -0
  50. package/dist/number/branded-types/negative-finite-number.d.mts.map +1 -0
  51. package/dist/number/branded-types/negative-finite-number.mjs +156 -0
  52. package/dist/number/branded-types/negative-finite-number.mjs.map +1 -0
  53. package/dist/number/branded-types/negative-int.d.mts +120 -0
  54. package/dist/number/branded-types/negative-int.d.mts.map +1 -0
  55. package/dist/number/branded-types/negative-int.mjs +125 -0
  56. package/dist/number/branded-types/negative-int.mjs.map +1 -0
  57. package/dist/number/branded-types/negative-safe-int.d.mts +132 -0
  58. package/dist/number/branded-types/negative-safe-int.d.mts.map +1 -0
  59. package/dist/number/branded-types/negative-safe-int.mjs +136 -0
  60. package/dist/number/branded-types/negative-safe-int.mjs.map +1 -0
  61. package/dist/number/branded-types/non-negative-finite-number.d.mts +1 -1
  62. package/dist/number/branded-types/non-negative-int16.d.mts +1 -1
  63. package/dist/number/branded-types/non-negative-int32.d.mts +1 -1
  64. package/dist/number/branded-types/non-positive-finite-number.d.mts +130 -0
  65. package/dist/number/branded-types/non-positive-finite-number.d.mts.map +1 -0
  66. package/dist/number/branded-types/non-positive-finite-number.mjs +134 -0
  67. package/dist/number/branded-types/non-positive-finite-number.mjs.map +1 -0
  68. package/dist/number/branded-types/non-positive-int.d.mts +224 -0
  69. package/dist/number/branded-types/non-positive-int.d.mts.map +1 -0
  70. package/dist/number/branded-types/non-positive-int.mjs +222 -0
  71. package/dist/number/branded-types/non-positive-int.mjs.map +1 -0
  72. package/dist/number/branded-types/non-positive-safe-int.d.mts +119 -0
  73. package/dist/number/branded-types/non-positive-safe-int.d.mts.map +1 -0
  74. package/dist/number/branded-types/non-positive-safe-int.mjs +116 -0
  75. package/dist/number/branded-types/non-positive-safe-int.mjs.map +1 -0
  76. package/dist/number/branded-types/non-zero-finite-number.d.mts +5 -17
  77. package/dist/number/branded-types/non-zero-finite-number.d.mts.map +1 -1
  78. package/dist/number/branded-types/non-zero-finite-number.mjs +5 -17
  79. package/dist/number/branded-types/non-zero-finite-number.mjs.map +1 -1
  80. package/dist/number/branded-types/non-zero-int.d.mts +5 -33
  81. package/dist/number/branded-types/non-zero-int.d.mts.map +1 -1
  82. package/dist/number/branded-types/non-zero-int.mjs +5 -25
  83. package/dist/number/branded-types/non-zero-int.mjs.map +1 -1
  84. package/dist/number/branded-types/non-zero-int16.d.mts +6 -43
  85. package/dist/number/branded-types/non-zero-int16.d.mts.map +1 -1
  86. package/dist/number/branded-types/non-zero-int16.mjs +5 -25
  87. package/dist/number/branded-types/non-zero-int16.mjs.map +1 -1
  88. package/dist/number/branded-types/non-zero-int32.d.mts +6 -39
  89. package/dist/number/branded-types/non-zero-int32.d.mts.map +1 -1
  90. package/dist/number/branded-types/non-zero-int32.mjs +5 -25
  91. package/dist/number/branded-types/non-zero-int32.mjs.map +1 -1
  92. package/dist/number/branded-types/non-zero-safe-int.d.mts +5 -37
  93. package/dist/number/branded-types/non-zero-safe-int.d.mts.map +1 -1
  94. package/dist/number/branded-types/non-zero-safe-int.mjs +5 -28
  95. package/dist/number/branded-types/non-zero-safe-int.mjs.map +1 -1
  96. package/dist/number/branded-types/non-zero-uint16.d.mts +6 -33
  97. package/dist/number/branded-types/non-zero-uint16.d.mts.map +1 -1
  98. package/dist/number/branded-types/non-zero-uint16.mjs +5 -17
  99. package/dist/number/branded-types/non-zero-uint16.mjs.map +1 -1
  100. package/dist/number/branded-types/non-zero-uint32.d.mts +6 -31
  101. package/dist/number/branded-types/non-zero-uint32.d.mts.map +1 -1
  102. package/dist/number/branded-types/non-zero-uint32.mjs +5 -17
  103. package/dist/number/branded-types/non-zero-uint32.mjs.map +1 -1
  104. package/dist/number/branded-types/positive-finite-number.d.mts +4 -2
  105. package/dist/number/branded-types/positive-finite-number.d.mts.map +1 -1
  106. package/dist/number/branded-types/positive-int.d.mts +4 -2
  107. package/dist/number/branded-types/positive-int.d.mts.map +1 -1
  108. package/dist/number/branded-types/positive-int16.d.mts +4 -2
  109. package/dist/number/branded-types/positive-int16.d.mts.map +1 -1
  110. package/dist/number/branded-types/positive-int32.d.mts +4 -2
  111. package/dist/number/branded-types/positive-int32.d.mts.map +1 -1
  112. package/dist/number/branded-types/positive-safe-int.d.mts +4 -2
  113. package/dist/number/branded-types/positive-safe-int.d.mts.map +1 -1
  114. package/dist/number/branded-types/positive-uint16.d.mts +4 -2
  115. package/dist/number/branded-types/positive-uint16.d.mts.map +1 -1
  116. package/dist/number/branded-types/positive-uint32.d.mts +4 -2
  117. package/dist/number/branded-types/positive-uint32.d.mts.map +1 -1
  118. package/dist/number/branded-types/safe-int.d.mts +1 -2
  119. package/dist/number/branded-types/safe-int.d.mts.map +1 -1
  120. package/dist/number/branded-types/safe-uint.d.mts +1 -1
  121. package/dist/number/branded-types/uint.d.mts +1 -1
  122. package/dist/number/branded-types/uint16.d.mts +1 -1
  123. package/dist/number/branded-types/uint32.d.mts +1 -1
  124. package/dist/number/index.d.mts +1 -0
  125. package/dist/number/index.d.mts.map +1 -1
  126. package/dist/number/index.mjs +6 -0
  127. package/dist/number/index.mjs.map +1 -1
  128. package/dist/number/num-arithmetic-types.d.mts +74 -0
  129. package/dist/number/num-arithmetic-types.d.mts.map +1 -0
  130. package/dist/number/num-arithmetic-types.mjs +2 -0
  131. package/dist/number/num-arithmetic-types.mjs.map +1 -0
  132. package/dist/number/num.d.mts +53 -9
  133. package/dist/number/num.d.mts.map +1 -1
  134. package/dist/number/num.mjs +64 -12
  135. package/dist/number/num.mjs.map +1 -1
  136. package/dist/number/refined-number-utils.d.mts +12 -9
  137. package/dist/number/refined-number-utils.d.mts.map +1 -1
  138. package/dist/number/refined-number-utils.mjs.map +1 -1
  139. package/dist/object/object.mjs +6 -0
  140. package/dist/object/object.mjs.map +1 -1
  141. package/package.json +2 -2
  142. package/src/number/branded-types/index.mts +6 -0
  143. package/src/number/branded-types/negative-finite-number.mts +210 -0
  144. package/src/number/branded-types/negative-finite-number.test.mts +172 -0
  145. package/src/number/branded-types/negative-int.mts +160 -0
  146. package/src/number/branded-types/negative-int.test.mts +146 -0
  147. package/src/number/branded-types/negative-safe-int.mts +173 -0
  148. package/src/number/branded-types/negative-safe-int.test.mts +120 -0
  149. package/src/number/branded-types/non-positive-finite-number.mts +191 -0
  150. package/src/number/branded-types/non-positive-finite-number.test.mts +286 -0
  151. package/src/number/branded-types/non-positive-int.mts +251 -0
  152. package/src/number/branded-types/non-positive-int.test.mts +197 -0
  153. package/src/number/branded-types/non-positive-safe-int.mts +147 -0
  154. package/src/number/branded-types/non-positive-safe-int.test.mts +223 -0
  155. package/src/number/branded-types/non-zero-finite-number.mts +14 -22
  156. package/src/number/branded-types/non-zero-finite-number.test.mts +0 -12
  157. package/src/number/branded-types/non-zero-int.mts +10 -32
  158. package/src/number/branded-types/non-zero-int.test.mts +0 -20
  159. package/src/number/branded-types/non-zero-int16.mts +8 -32
  160. package/src/number/branded-types/non-zero-int16.test.mts +0 -30
  161. package/src/number/branded-types/non-zero-int32.mts +8 -32
  162. package/src/number/branded-types/non-zero-int32.test.mts +0 -30
  163. package/src/number/branded-types/non-zero-safe-int.mts +8 -35
  164. package/src/number/branded-types/non-zero-safe-int.test.mts +0 -32
  165. package/src/number/branded-types/non-zero-uint16.mts +8 -22
  166. package/src/number/branded-types/non-zero-uint16.test.mts +0 -16
  167. package/src/number/branded-types/non-zero-uint32.mts +8 -22
  168. package/src/number/branded-types/non-zero-uint32.test.mts +0 -16
  169. package/src/number/index.mts +1 -0
  170. package/src/number/num-arithmetic-types.mts +269 -0
  171. package/src/number/num-arithmetic-types.test.mts +130 -0
  172. package/src/number/num-arithmetic.test.mts +102 -0
  173. package/src/number/num.mts +96 -15
  174. package/src/number/refined-number-utils.mts +19 -9
@@ -0,0 +1,134 @@
1
+ import { TsDataForgeInternals } from '../refined-number-utils.mjs';
2
+
3
+ const typeNameInMessage = 'a non-positive finite number';
4
+ const { MAX_VALUE, add, castType, clamp, is, max: max_, min: min_, pow, random, sub, } = TsDataForgeInternals.RefinedNumberUtils.operatorsForFloat({
5
+ MIN_VALUE: Number.MAX_VALUE * -1,
6
+ MAX_VALUE: 0,
7
+ typeNameInMessage,
8
+ });
9
+ const floor = (x) =>
10
+ // eslint-disable-next-line total-functions/no-unsafe-type-assertion
11
+ Math.floor(x);
12
+ const ceil = (x) =>
13
+ // eslint-disable-next-line total-functions/no-unsafe-type-assertion
14
+ Math.ceil(x);
15
+ const round = (x) =>
16
+ // eslint-disable-next-line total-functions/no-unsafe-type-assertion
17
+ Math.round(x);
18
+ /**
19
+ * Checks if a number is a NonPositiveFiniteNumber (a finite number <= 0).
20
+ *
21
+ * @param value The value to check.
22
+ * @returns `true` if the value is a NonPositiveFiniteNumber, `false` otherwise.
23
+ */
24
+ const isNonPositiveFiniteNumber = is;
25
+ /**
26
+ * Casts a number to a NonPositiveFiniteNumber type.
27
+ *
28
+ * @param value The value to cast.
29
+ * @returns The value as a NonPositiveFiniteNumber type.
30
+ * @throws {TypeError} If the value is not a non-positive finite number.
31
+ */
32
+ const asNonPositiveFiniteNumber = castType;
33
+ /**
34
+ * Namespace providing type-safe arithmetic operations for non-positive finite
35
+ * numbers.
36
+ *
37
+ * All operations maintain the non-positive constraint by clamping positive
38
+ * results to MAX_VALUE (0), while ensuring results remain finite (excluding NaN
39
+ * and Infinity). This type is useful for representing quantities that must
40
+ * always be non-positive, such as debts, penalties, and negative offsets.
41
+ */
42
+ const NonPositiveFiniteNumber = {
43
+ /**
44
+ * Type guard to check if a value is a NonPositiveFiniteNumber.
45
+ *
46
+ * @param value The value to check.
47
+ * @returns `true` if the value is a non-positive finite number, `false`
48
+ * otherwise.
49
+ */
50
+ is,
51
+ /**
52
+ * The maximum value for a non-positive finite number.
53
+ *
54
+ * @readonly
55
+ */
56
+ MAX_VALUE,
57
+ /**
58
+ * Returns the smaller of two NonPositiveFiniteNumber values.
59
+ *
60
+ * @param a The first NonPositiveFiniteNumber.
61
+ * @param b The second NonPositiveFiniteNumber.
62
+ * @returns The minimum value as a NonPositiveFiniteNumber.
63
+ */
64
+ min: min_,
65
+ /**
66
+ * Returns the larger of two NonPositiveFiniteNumber values.
67
+ *
68
+ * @param a The first NonPositiveFiniteNumber.
69
+ * @param b The second NonPositiveFiniteNumber.
70
+ * @returns The maximum value as a NonPositiveFiniteNumber.
71
+ */
72
+ max: max_,
73
+ /**
74
+ * Clamps a number to the non-positive finite range.
75
+ *
76
+ * @param value The number to clamp.
77
+ * @returns The value clamped to (-∞, 0] as a NonPositiveFiniteNumber.
78
+ */
79
+ clamp,
80
+ /**
81
+ * Rounds down a NonPositiveFiniteNumber to the nearest integer.
82
+ *
83
+ * @param x The NonPositiveFiniteNumber to round down.
84
+ * @returns The floor value as a NonPositiveInt (can be 0).
85
+ */
86
+ floor,
87
+ /**
88
+ * Rounds up a NonPositiveFiniteNumber to the nearest integer.
89
+ *
90
+ * @param x The NonPositiveFiniteNumber to round up.
91
+ * @returns The ceiling value as a NegativeInt (always <= -1) or 0.
92
+ */
93
+ ceil,
94
+ /**
95
+ * Rounds a NonPositiveFiniteNumber to the nearest integer.
96
+ *
97
+ * @param x The NonPositiveFiniteNumber to round.
98
+ * @returns The rounded value as a NonPositiveInt (can be 0 if x > -0.5).
99
+ */
100
+ round,
101
+ /**
102
+ * Generates a random NonPositiveFiniteNumber value.
103
+ *
104
+ * @returns A random non-positive finite number.
105
+ */
106
+ random,
107
+ /**
108
+ * Raises a NonPositiveFiniteNumber to the power of another NonPositiveFiniteNumber.
109
+ *
110
+ * @param a The base NonPositiveFiniteNumber.
111
+ * @param b The exponent NonPositiveFiniteNumber.
112
+ * @returns `a ** b` clamped to (-∞, 0] as a NonPositiveFiniteNumber.
113
+ */
114
+ pow,
115
+ /**
116
+ * Adds two NonPositiveFiniteNumber values.
117
+ *
118
+ * @param a The first NonPositiveFiniteNumber.
119
+ * @param b The second NonPositiveFiniteNumber.
120
+ * @returns `a + b` clamped to (-∞, 0] as a NonPositiveFiniteNumber.
121
+ */
122
+ add,
123
+ /**
124
+ * Subtracts one NonPositiveFiniteNumber from another.
125
+ *
126
+ * @param a The minuend NonPositiveFiniteNumber.
127
+ * @param b The subtrahend NonPositiveFiniteNumber.
128
+ * @returns `a - b` clamped to (-∞, 0] as a NonPositiveFiniteNumber (maximum 0).
129
+ */
130
+ sub,
131
+ };
132
+
133
+ export { NonPositiveFiniteNumber, asNonPositiveFiniteNumber, isNonPositiveFiniteNumber };
134
+ //# sourceMappingURL=non-positive-finite-number.mjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"non-positive-finite-number.mjs","sources":["../../../src/number/branded-types/non-positive-finite-number.mts"],"sourcesContent":[null],"names":[],"mappings":";;AAOA,MAAM,iBAAiB,GAAG,8BAA8B;AAExD,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,SAAS,EAAE,MAAM,CAAC,SAAS,GAAG,EAAE;AAChC,IAAA,SAAS,EAAE,CAAC;IACZ,iBAAiB;AACT,CAAA,CAAC;AAEX,MAAM,KAAK,GAAG,CACZ,CAAc;AAId;AACA,IAAI,CAAC,KAAK,CACR,CAAC,CAGF;AAEH,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,yBAAyB,GAAG;AAEzC;;;;;;AAMG;AACI,MAAM,yBAAyB,GAAG;AAEzC;;;;;;;;AAQG;AACI,MAAM,uBAAuB,GAAG;AACrC;;;;;;AAMG;IACH,EAAE;AAEF;;;;AAIG;IACH,SAAS;AAET;;;;;;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;;;;;;AAMG;IACH,GAAG;;;;;"}
@@ -0,0 +1,224 @@
1
+ import { type NonPositiveInt as TtfImported_NonPositiveInt } from 'ts-type-forge';
2
+ export type NonPositiveInt = TtfImported_NonPositiveInt;
3
+ /**
4
+ * Type guard that checks if a value is a non-positive integer.
5
+ *
6
+ * A non-positive integer is any integer less than or equal to zero (<= 0).
7
+ * This includes zero and all negative integers, but excludes positive numbers
8
+ * and non-integers.
9
+ *
10
+ * @example
11
+ *
12
+ * ```ts
13
+ * assert.isTrue(isNonPositiveInt(0));
14
+ *
15
+ * assert.isTrue(isNonPositiveInt(-5));
16
+ *
17
+ * assert.isFalse(isNonPositiveInt(1));
18
+ * ```
19
+ *
20
+ * @param value - The value to check
21
+ * @returns `true` if the value is a non-positive integer, `false` otherwise
22
+ */
23
+ export declare const isNonPositiveInt: (a: number) => a is TtfImported_NonPositiveInt;
24
+ /**
25
+ * Casts a number to a NonPositiveInt branded type.
26
+ *
27
+ * This function validates that the input is a non-positive integer (<= 0) and
28
+ * returns it with the NonPositiveInt brand. This ensures type safety for
29
+ * operations that require non-positive integer values.
30
+ *
31
+ * @example
32
+ *
33
+ * ```ts
34
+ * const branded = asNonPositiveInt(-7);
35
+ *
36
+ * assert.isTrue(branded === -7);
37
+ *
38
+ * assert.isTrue(NonPositiveInt.is(branded));
39
+ * ```
40
+ *
41
+ * @param value - The value to cast
42
+ * @returns The value as a NonPositiveInt branded type
43
+ * @throws {TypeError} If the value is not a non-positive integer
44
+ */
45
+ export declare const asNonPositiveInt: <N extends number>(x: N) => number & {
46
+ readonly NaNValue: false;
47
+ readonly Finite: true;
48
+ readonly Int: true;
49
+ readonly "<=0": true;
50
+ readonly "< 2^15": true;
51
+ readonly "< 2^16": true;
52
+ readonly "< 2^31": true;
53
+ readonly "< 2^32": true;
54
+ } & Readonly<{
55
+ 'TSTypeForgeInternals--edd2f9ce-7ca5-45b0-9d1a-bd61b9b5d9c3': unknown;
56
+ }> & N;
57
+ /**
58
+ * Namespace providing type-safe operations for NonPositiveInt branded types.
59
+ *
60
+ * NonPositiveInt represents integers that are less than or equal to zero (<= 0).
61
+ * All operations automatically clamp results to maintain the non-positive
62
+ * constraint, ensuring that arithmetic operations never produce positive values.
63
+ *
64
+ * This type is essential for:
65
+ *
66
+ * - Debts and negative balances
67
+ * - Penalties and reductions
68
+ * - Offsets and adjustments (downward)
69
+ * - Negative counts or differences
70
+ * - Depth or altitude below a reference point
71
+ */
72
+ export declare const NonPositiveInt: {
73
+ /**
74
+ * Type guard that checks if a value is a non-positive integer.
75
+ *
76
+ * @example
77
+ *
78
+ * ```ts
79
+ * const value: number = -42;
80
+ *
81
+ * if (NonPositiveInt.is(value)) {
82
+ * // value is now typed as NonPositiveInt
83
+ * const debt = value;
84
+ * }
85
+ * ```
86
+ *
87
+ * @param value - The value to check
88
+ * @returns `true` if the value is a non-positive integer, `false` otherwise
89
+ */
90
+ readonly is: (a: number) => a is TtfImported_NonPositiveInt;
91
+ /**
92
+ * The maximum value for a non-positive integer.
93
+ *
94
+ * @readonly
95
+ */
96
+ readonly MAX_VALUE: 0;
97
+ /**
98
+ * Returns the smaller of two non-positive integers.
99
+ *
100
+ * Since non-positive integers range from negative infinity to 0, the smaller
101
+ * value is the one further from zero (more negative).
102
+ *
103
+ * @example
104
+ *
105
+ * ```ts
106
+ * const result = NonPositiveInt.min(-5, -10);
107
+ *
108
+ * assert.strictEqual(result, -10);
109
+ * ```
110
+ *
111
+ * @param a - The first non-positive integer
112
+ * @param b - The second non-positive integer
113
+ * @returns The minimum value as a non-positive integer
114
+ */
115
+ readonly min: (...values: readonly import("ts-type-forge").WithSmallInt<TtfImported_NonPositiveInt>[]) => TtfImported_NonPositiveInt;
116
+ /**
117
+ * Returns the larger of two non-positive integers.
118
+ *
119
+ * Since non-positive integers range from negative infinity to 0, the larger
120
+ * value is the one closer to zero (less negative).
121
+ *
122
+ * @example
123
+ *
124
+ * ```ts
125
+ * const result = NonPositiveInt.max(-5, -10);
126
+ *
127
+ * assert.strictEqual(result, -5);
128
+ * ```
129
+ *
130
+ * @param a - The first non-positive integer
131
+ * @param b - The second non-positive integer
132
+ * @returns The maximum value as a non-positive integer
133
+ */
134
+ readonly max: (...values: readonly import("ts-type-forge").WithSmallInt<TtfImported_NonPositiveInt>[]) => TtfImported_NonPositiveInt;
135
+ /**
136
+ * Clamps a number to the non-positive integer range.
137
+ *
138
+ * Any positive value is clamped to 0 (the maximum non-positive integer).
139
+ * Negative values are preserved as long as they are valid integers.
140
+ *
141
+ * @example
142
+ *
143
+ * ```ts
144
+ * assert.strictEqual(NonPositiveInt.clamp(5), 0);
145
+ *
146
+ * assert.strictEqual(NonPositiveInt.clamp(-5), -5);
147
+ *
148
+ * assert.strictEqual(NonPositiveInt.clamp(0), 0);
149
+ * ```
150
+ *
151
+ * @param value - The number to clamp
152
+ * @returns The value clamped to the non-positive integer range
153
+ */
154
+ readonly clamp: (x: number) => TtfImported_NonPositiveInt;
155
+ /**
156
+ * Generates a random non-positive integer value.
157
+ *
158
+ * @example
159
+ *
160
+ * ```ts
161
+ * const randomValue = NonPositiveInt.random();
162
+ *
163
+ * assert.isTrue(NonPositiveInt.is(randomValue));
164
+ * ```
165
+ *
166
+ * @returns A random non-positive integer
167
+ */
168
+ readonly random: (min?: import("ts-type-forge").WithSmallInt<TtfImported_NonPositiveInt> | undefined, max?: import("ts-type-forge").WithSmallInt<TtfImported_NonPositiveInt> | undefined) => TtfImported_NonPositiveInt;
169
+ /**
170
+ * Raises a non-positive integer to the power of another non-positive integer.
171
+ *
172
+ * The result is clamped to the non-positive integer range.
173
+ *
174
+ * @example
175
+ *
176
+ * ```ts
177
+ * const result = NonPositiveInt.pow(-2, -1);
178
+ * ```
179
+ *
180
+ * @param a - The base non-positive integer
181
+ * @param b - The exponent non-positive integer
182
+ * @returns `a ** b` clamped to the non-positive integer range
183
+ */
184
+ readonly pow: (x: import("ts-type-forge").WithSmallInt<TtfImported_NonPositiveInt>, y: import("ts-type-forge").WithSmallInt<TtfImported_NonPositiveInt>) => TtfImported_NonPositiveInt;
185
+ /**
186
+ * Adds two non-positive integers.
187
+ *
188
+ * The result is clamped to the non-positive integer range. If the sum is
189
+ * positive, it is clamped to 0.
190
+ *
191
+ * @example
192
+ *
193
+ * ```ts
194
+ * assert.strictEqual(NonPositiveInt.add(-5, -3), -8);
195
+ *
196
+ * assert.strictEqual(NonPositiveInt.add(-5, 10), 0);
197
+ * ```
198
+ *
199
+ * @param a - The first non-positive integer
200
+ * @param b - The second non-positive integer
201
+ * @returns `a + b` clamped to the non-positive integer range
202
+ */
203
+ readonly add: (x: import("ts-type-forge").WithSmallInt<TtfImported_NonPositiveInt>, y: import("ts-type-forge").WithSmallInt<TtfImported_NonPositiveInt>) => TtfImported_NonPositiveInt;
204
+ /**
205
+ * Subtracts one non-positive integer from another.
206
+ *
207
+ * The result is clamped to the non-positive integer range. If the result is
208
+ * positive, it is clamped to 0.
209
+ *
210
+ * @example
211
+ *
212
+ * ```ts
213
+ * assert.strictEqual(NonPositiveInt.sub(-10, -3), -7);
214
+ *
215
+ * assert.strictEqual(NonPositiveInt.sub(-10, 5), 0);
216
+ * ```
217
+ *
218
+ * @param a - The minuend non-positive integer
219
+ * @param b - The subtrahend non-positive integer
220
+ * @returns `a - b` clamped to the non-positive integer range
221
+ */
222
+ readonly sub: (x: import("ts-type-forge").WithSmallInt<TtfImported_NonPositiveInt>, y: import("ts-type-forge").WithSmallInt<TtfImported_NonPositiveInt>) => TtfImported_NonPositiveInt;
223
+ };
224
+ //# sourceMappingURL=non-positive-int.d.mts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"non-positive-int.d.mts","sourceRoot":"","sources":["../../../src/number/branded-types/non-positive-int.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,cAAc,IAAI,0BAA0B,EAAE,MAAM,eAAe,CAAC;AAGlF,MAAM,MAAM,cAAc,GAAG,0BAA0B,CAAC;AA4BxD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,gBAAgB,gDAAK,CAAC;AAEnC;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;MAAW,CAAC;AAEzC;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,cAAc;IACzB;;;;;;;;;;;;;;;;OAgBG;;IAGH;;;;OAIG;;IAGH;;;;;;;;;;;;;;;;;OAiBG;;IAGH;;;;;;;;;;;;;;;;;OAiBG;;IAGH;;;;;;;;;;;;;;;;;;OAkBG;;IAGH;;;;;;;;;;;;OAYG;;IAGH;;;;;;;;;;;;;;OAcG;;IAGH;;;;;;;;;;;;;;;;;OAiBG;;IAGH;;;;;;;;;;;;;;;;;OAiBG;;CAEK,CAAC"}
@@ -0,0 +1,222 @@
1
+ import { TsDataForgeInternals } from '../refined-number-utils.mjs';
2
+
3
+ const typeNameInMessage = 'a non-positive integer';
4
+ const { MAX_VALUE, add, castType, clamp, is, max: max_, min: min_, pow, random, sub, } = TsDataForgeInternals.RefinedNumberUtils.operatorsForInteger({
5
+ integerOrSafeInteger: 'Integer',
6
+ MIN_VALUE: -Number.MAX_VALUE,
7
+ MAX_VALUE: 0,
8
+ typeNameInMessage,
9
+ });
10
+ /**
11
+ * Type guard that checks if a value is a non-positive integer.
12
+ *
13
+ * A non-positive integer is any integer less than or equal to zero (<= 0).
14
+ * This includes zero and all negative integers, but excludes positive numbers
15
+ * and non-integers.
16
+ *
17
+ * @example
18
+ *
19
+ * ```ts
20
+ * assert.isTrue(isNonPositiveInt(0));
21
+ *
22
+ * assert.isTrue(isNonPositiveInt(-5));
23
+ *
24
+ * assert.isFalse(isNonPositiveInt(1));
25
+ * ```
26
+ *
27
+ * @param value - The value to check
28
+ * @returns `true` if the value is a non-positive integer, `false` otherwise
29
+ */
30
+ const isNonPositiveInt = is;
31
+ /**
32
+ * Casts a number to a NonPositiveInt branded type.
33
+ *
34
+ * This function validates that the input is a non-positive integer (<= 0) and
35
+ * returns it with the NonPositiveInt brand. This ensures type safety for
36
+ * operations that require non-positive integer values.
37
+ *
38
+ * @example
39
+ *
40
+ * ```ts
41
+ * const branded = asNonPositiveInt(-7);
42
+ *
43
+ * assert.isTrue(branded === -7);
44
+ *
45
+ * assert.isTrue(NonPositiveInt.is(branded));
46
+ * ```
47
+ *
48
+ * @param value - The value to cast
49
+ * @returns The value as a NonPositiveInt branded type
50
+ * @throws {TypeError} If the value is not a non-positive integer
51
+ */
52
+ const asNonPositiveInt = castType;
53
+ /**
54
+ * Namespace providing type-safe operations for NonPositiveInt branded types.
55
+ *
56
+ * NonPositiveInt represents integers that are less than or equal to zero (<= 0).
57
+ * All operations automatically clamp results to maintain the non-positive
58
+ * constraint, ensuring that arithmetic operations never produce positive values.
59
+ *
60
+ * This type is essential for:
61
+ *
62
+ * - Debts and negative balances
63
+ * - Penalties and reductions
64
+ * - Offsets and adjustments (downward)
65
+ * - Negative counts or differences
66
+ * - Depth or altitude below a reference point
67
+ */
68
+ const NonPositiveInt = {
69
+ /**
70
+ * Type guard that checks if a value is a non-positive integer.
71
+ *
72
+ * @example
73
+ *
74
+ * ```ts
75
+ * const value: number = -42;
76
+ *
77
+ * if (NonPositiveInt.is(value)) {
78
+ * // value is now typed as NonPositiveInt
79
+ * const debt = value;
80
+ * }
81
+ * ```
82
+ *
83
+ * @param value - The value to check
84
+ * @returns `true` if the value is a non-positive integer, `false` otherwise
85
+ */
86
+ is,
87
+ /**
88
+ * The maximum value for a non-positive integer.
89
+ *
90
+ * @readonly
91
+ */
92
+ MAX_VALUE,
93
+ /**
94
+ * Returns the smaller of two non-positive integers.
95
+ *
96
+ * Since non-positive integers range from negative infinity to 0, the smaller
97
+ * value is the one further from zero (more negative).
98
+ *
99
+ * @example
100
+ *
101
+ * ```ts
102
+ * const result = NonPositiveInt.min(-5, -10);
103
+ *
104
+ * assert.strictEqual(result, -10);
105
+ * ```
106
+ *
107
+ * @param a - The first non-positive integer
108
+ * @param b - The second non-positive integer
109
+ * @returns The minimum value as a non-positive integer
110
+ */
111
+ min: min_,
112
+ /**
113
+ * Returns the larger of two non-positive integers.
114
+ *
115
+ * Since non-positive integers range from negative infinity to 0, the larger
116
+ * value is the one closer to zero (less negative).
117
+ *
118
+ * @example
119
+ *
120
+ * ```ts
121
+ * const result = NonPositiveInt.max(-5, -10);
122
+ *
123
+ * assert.strictEqual(result, -5);
124
+ * ```
125
+ *
126
+ * @param a - The first non-positive integer
127
+ * @param b - The second non-positive integer
128
+ * @returns The maximum value as a non-positive integer
129
+ */
130
+ max: max_,
131
+ /**
132
+ * Clamps a number to the non-positive integer range.
133
+ *
134
+ * Any positive value is clamped to 0 (the maximum non-positive integer).
135
+ * Negative values are preserved as long as they are valid integers.
136
+ *
137
+ * @example
138
+ *
139
+ * ```ts
140
+ * assert.strictEqual(NonPositiveInt.clamp(5), 0);
141
+ *
142
+ * assert.strictEqual(NonPositiveInt.clamp(-5), -5);
143
+ *
144
+ * assert.strictEqual(NonPositiveInt.clamp(0), 0);
145
+ * ```
146
+ *
147
+ * @param value - The number to clamp
148
+ * @returns The value clamped to the non-positive integer range
149
+ */
150
+ clamp,
151
+ /**
152
+ * Generates a random non-positive integer value.
153
+ *
154
+ * @example
155
+ *
156
+ * ```ts
157
+ * const randomValue = NonPositiveInt.random();
158
+ *
159
+ * assert.isTrue(NonPositiveInt.is(randomValue));
160
+ * ```
161
+ *
162
+ * @returns A random non-positive integer
163
+ */
164
+ random,
165
+ /**
166
+ * Raises a non-positive integer to the power of another non-positive integer.
167
+ *
168
+ * The result is clamped to the non-positive integer range.
169
+ *
170
+ * @example
171
+ *
172
+ * ```ts
173
+ * const result = NonPositiveInt.pow(-2, -1);
174
+ * ```
175
+ *
176
+ * @param a - The base non-positive integer
177
+ * @param b - The exponent non-positive integer
178
+ * @returns `a ** b` clamped to the non-positive integer range
179
+ */
180
+ pow,
181
+ /**
182
+ * Adds two non-positive integers.
183
+ *
184
+ * The result is clamped to the non-positive integer range. If the sum is
185
+ * positive, it is clamped to 0.
186
+ *
187
+ * @example
188
+ *
189
+ * ```ts
190
+ * assert.strictEqual(NonPositiveInt.add(-5, -3), -8);
191
+ *
192
+ * assert.strictEqual(NonPositiveInt.add(-5, 10), 0);
193
+ * ```
194
+ *
195
+ * @param a - The first non-positive integer
196
+ * @param b - The second non-positive integer
197
+ * @returns `a + b` clamped to the non-positive integer range
198
+ */
199
+ add,
200
+ /**
201
+ * Subtracts one non-positive integer from another.
202
+ *
203
+ * The result is clamped to the non-positive integer range. If the result is
204
+ * positive, it is clamped to 0.
205
+ *
206
+ * @example
207
+ *
208
+ * ```ts
209
+ * assert.strictEqual(NonPositiveInt.sub(-10, -3), -7);
210
+ *
211
+ * assert.strictEqual(NonPositiveInt.sub(-10, 5), 0);
212
+ * ```
213
+ *
214
+ * @param a - The minuend non-positive integer
215
+ * @param b - The subtrahend non-positive integer
216
+ * @returns `a - b` clamped to the non-positive integer range
217
+ */
218
+ sub,
219
+ };
220
+
221
+ export { NonPositiveInt, asNonPositiveInt, isNonPositiveInt };
222
+ //# sourceMappingURL=non-positive-int.mjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"non-positive-int.mjs","sources":["../../../src/number/branded-types/non-positive-int.mts"],"sourcesContent":[null],"names":[],"mappings":";;AAOA,MAAM,iBAAiB,GAAG,wBAAwB;AAElD,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,SAAS,EAAE,CAAC,MAAM,CAAC,SAAS;AAC5B,IAAA,SAAS,EAAE,CAAC;IACZ,iBAAiB;AACT,CAAA,CAAC;AAEX;;;;;;;;;;;;;;;;;;;AAmBG;AACI,MAAM,gBAAgB,GAAG;AAEhC;;;;;;;;;;;;;;;;;;;;AAoBG;AACI,MAAM,gBAAgB,GAAG;AAEhC;;;;;;;;;;;;;;AAcG;AACI,MAAM,cAAc,GAAG;AAC5B;;;;;;;;;;;;;;;;AAgBG;IACH,EAAE;AAEF;;;;AAIG;IACH,SAAS;AAET;;;;;;;;;;;;;;;;;AAiBG;AACH,IAAA,GAAG,EAAE,IAAI;AAET;;;;;;;;;;;;;;;;;AAiBG;AACH,IAAA,GAAG,EAAE,IAAI;AAET;;;;;;;;;;;;;;;;;;AAkBG;IACH,KAAK;AAEL;;;;;;;;;;;;AAYG;IACH,MAAM;AAEN;;;;;;;;;;;;;;AAcG;IACH,GAAG;AAEH;;;;;;;;;;;;;;;;;AAiBG;IACH,GAAG;AAEH;;;;;;;;;;;;;;;;;AAiBG;IACH,GAAG;;;;;"}