ts-data-forge 10.0.0 → 11.0.1

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 (249) hide show
  1. package/dist/array/impl/array-utils-creation.d.mts +3 -3
  2. package/dist/array/impl/array-utils-creation.d.mts.map +1 -1
  3. package/dist/array/impl/array-utils-creation.mjs.map +1 -1
  4. package/dist/array/impl/array-utils-element-access.d.mts +4 -4
  5. package/dist/array/impl/array-utils-element-access.mjs.map +1 -1
  6. package/dist/{guard/as-length-bounded-array.d.mts → array/impl/array-utils-length-bounded-array-cast.d.mts} +9 -9
  7. package/dist/array/impl/array-utils-length-bounded-array-cast.d.mts.map +1 -0
  8. package/dist/{guard/as-length-bounded-array.mjs → array/impl/array-utils-length-bounded-array-cast.mjs} +2 -2
  9. package/dist/array/impl/array-utils-length-bounded-array-cast.mjs.map +1 -0
  10. package/dist/{guard/is-length-bounded-array.d.mts → array/impl/array-utils-length-bounded-array-guard.d.mts} +13 -13
  11. package/dist/array/impl/array-utils-length-bounded-array-guard.d.mts.map +1 -0
  12. package/dist/{guard/is-length-bounded-array.mjs → array/impl/array-utils-length-bounded-array-guard.mjs} +1 -1
  13. package/dist/array/impl/array-utils-length-bounded-array-guard.mjs.map +1 -0
  14. package/dist/array/impl/array-utils-modification.d.mts +9 -9
  15. package/dist/array/impl/array-utils-modification.d.mts.map +1 -1
  16. package/dist/array/impl/array-utils-modification.mjs.map +1 -1
  17. package/dist/array/impl/array-utils-reducing-value.d.mts +9 -9
  18. package/dist/array/impl/array-utils-reducing-value.mjs.map +1 -1
  19. package/dist/array/impl/array-utils-size.d.mts +3 -3
  20. package/dist/array/impl/array-utils-size.mjs.map +1 -1
  21. package/dist/array/impl/array-utils-slicing.d.mts +9 -9
  22. package/dist/array/impl/array-utils-slicing.d.mts.map +1 -1
  23. package/dist/array/impl/array-utils-slicing.mjs.map +1 -1
  24. package/dist/array/impl/array-utils-transformation.d.mts +16 -10
  25. package/dist/array/impl/array-utils-transformation.d.mts.map +1 -1
  26. package/dist/array/impl/array-utils-transformation.mjs.map +1 -1
  27. package/dist/array/impl/index.d.mts +2 -0
  28. package/dist/array/impl/index.d.mts.map +1 -1
  29. package/dist/array/impl/index.mjs +2 -0
  30. package/dist/array/impl/index.mjs.map +1 -1
  31. package/dist/entry-point.mjs +1 -3
  32. package/dist/entry-point.mjs.map +1 -1
  33. package/dist/guard/index.d.mts +0 -3
  34. package/dist/guard/index.d.mts.map +1 -1
  35. package/dist/guard/index.mjs +0 -3
  36. package/dist/guard/index.mjs.map +1 -1
  37. package/dist/index.d.mts +1 -0
  38. package/dist/index.d.mts.map +1 -1
  39. package/dist/index.mjs +1 -3
  40. package/dist/index.mjs.map +1 -1
  41. package/dist/number/branded-types/finite-number.d.mts +47 -61
  42. package/dist/number/branded-types/finite-number.d.mts.map +1 -1
  43. package/dist/number/branded-types/finite-number.mjs +37 -41
  44. package/dist/number/branded-types/finite-number.mjs.map +1 -1
  45. package/dist/number/branded-types/int.d.mts +40 -46
  46. package/dist/number/branded-types/int.d.mts.map +1 -1
  47. package/dist/number/branded-types/int.mjs +29 -31
  48. package/dist/number/branded-types/int.mjs.map +1 -1
  49. package/dist/number/branded-types/int16.d.mts +65 -58
  50. package/dist/number/branded-types/int16.d.mts.map +1 -1
  51. package/dist/number/branded-types/int16.mjs +49 -45
  52. package/dist/number/branded-types/int16.mjs.map +1 -1
  53. package/dist/number/branded-types/int32.d.mts +65 -58
  54. package/dist/number/branded-types/int32.d.mts.map +1 -1
  55. package/dist/number/branded-types/int32.mjs +49 -45
  56. package/dist/number/branded-types/int32.mjs.map +1 -1
  57. package/dist/number/branded-types/negative-finite-number.d.mts +68 -59
  58. package/dist/number/branded-types/negative-finite-number.d.mts.map +1 -1
  59. package/dist/number/branded-types/negative-finite-number.mjs +52 -46
  60. package/dist/number/branded-types/negative-finite-number.mjs.map +1 -1
  61. package/dist/number/branded-types/negative-int.d.mts +60 -48
  62. package/dist/number/branded-types/negative-int.d.mts.map +1 -1
  63. package/dist/number/branded-types/negative-int.mjs +40 -36
  64. package/dist/number/branded-types/negative-int.mjs.map +1 -1
  65. package/dist/number/branded-types/negative-safe-int.d.mts +57 -56
  66. package/dist/number/branded-types/negative-safe-int.d.mts.map +1 -1
  67. package/dist/number/branded-types/negative-safe-int.mjs +40 -41
  68. package/dist/number/branded-types/negative-safe-int.mjs.map +1 -1
  69. package/dist/number/branded-types/non-negative-finite-number.d.mts +74 -64
  70. package/dist/number/branded-types/non-negative-finite-number.d.mts.map +1 -1
  71. package/dist/number/branded-types/non-negative-finite-number.mjs +58 -51
  72. package/dist/number/branded-types/non-negative-finite-number.mjs.map +1 -1
  73. package/dist/number/branded-types/non-negative-int16.d.mts +64 -57
  74. package/dist/number/branded-types/non-negative-int16.d.mts.map +1 -1
  75. package/dist/number/branded-types/non-negative-int16.mjs +47 -43
  76. package/dist/number/branded-types/non-negative-int16.mjs.map +1 -1
  77. package/dist/number/branded-types/non-negative-int32.d.mts +64 -58
  78. package/dist/number/branded-types/non-negative-int32.d.mts.map +1 -1
  79. package/dist/number/branded-types/non-negative-int32.mjs +47 -44
  80. package/dist/number/branded-types/non-negative-int32.mjs.map +1 -1
  81. package/dist/number/branded-types/non-positive-finite-number.d.mts +64 -54
  82. package/dist/number/branded-types/non-positive-finite-number.d.mts.map +1 -1
  83. package/dist/number/branded-types/non-positive-finite-number.mjs +48 -41
  84. package/dist/number/branded-types/non-positive-finite-number.mjs.map +1 -1
  85. package/dist/number/branded-types/non-positive-int.d.mts +41 -146
  86. package/dist/number/branded-types/non-positive-int.d.mts.map +1 -1
  87. package/dist/number/branded-types/non-positive-int.mjs +27 -107
  88. package/dist/number/branded-types/non-positive-int.mjs.map +1 -1
  89. package/dist/number/branded-types/non-positive-safe-int.d.mts +54 -53
  90. package/dist/number/branded-types/non-positive-safe-int.d.mts.map +1 -1
  91. package/dist/number/branded-types/non-positive-safe-int.mjs +37 -39
  92. package/dist/number/branded-types/non-positive-safe-int.mjs.map +1 -1
  93. package/dist/number/branded-types/non-zero-finite-number.d.mts +62 -49
  94. package/dist/number/branded-types/non-zero-finite-number.d.mts.map +1 -1
  95. package/dist/number/branded-types/non-zero-finite-number.mjs +46 -37
  96. package/dist/number/branded-types/non-zero-finite-number.mjs.map +1 -1
  97. package/dist/number/branded-types/non-zero-int.d.mts +51 -38
  98. package/dist/number/branded-types/non-zero-int.d.mts.map +1 -1
  99. package/dist/number/branded-types/non-zero-int.mjs +31 -27
  100. package/dist/number/branded-types/non-zero-int.mjs.map +1 -1
  101. package/dist/number/branded-types/non-zero-int16.d.mts +52 -53
  102. package/dist/number/branded-types/non-zero-int16.d.mts.map +1 -1
  103. package/dist/number/branded-types/non-zero-int16.mjs +36 -39
  104. package/dist/number/branded-types/non-zero-int16.mjs.map +1 -1
  105. package/dist/number/branded-types/non-zero-int32.d.mts +52 -54
  106. package/dist/number/branded-types/non-zero-int32.d.mts.map +1 -1
  107. package/dist/number/branded-types/non-zero-int32.mjs +36 -40
  108. package/dist/number/branded-types/non-zero-int32.mjs.map +1 -1
  109. package/dist/number/branded-types/non-zero-safe-int.d.mts +53 -54
  110. package/dist/number/branded-types/non-zero-safe-int.d.mts.map +1 -1
  111. package/dist/number/branded-types/non-zero-safe-int.mjs +36 -40
  112. package/dist/number/branded-types/non-zero-safe-int.mjs.map +1 -1
  113. package/dist/number/branded-types/non-zero-uint16.d.mts +52 -53
  114. package/dist/number/branded-types/non-zero-uint16.d.mts.map +1 -1
  115. package/dist/number/branded-types/non-zero-uint16.mjs +35 -39
  116. package/dist/number/branded-types/non-zero-uint16.mjs.map +1 -1
  117. package/dist/number/branded-types/non-zero-uint32.d.mts +52 -53
  118. package/dist/number/branded-types/non-zero-uint32.d.mts.map +1 -1
  119. package/dist/number/branded-types/non-zero-uint32.mjs +35 -39
  120. package/dist/number/branded-types/non-zero-uint32.mjs.map +1 -1
  121. package/dist/number/branded-types/positive-finite-number.d.mts +74 -63
  122. package/dist/number/branded-types/positive-finite-number.d.mts.map +1 -1
  123. package/dist/number/branded-types/positive-finite-number.mjs +58 -50
  124. package/dist/number/branded-types/positive-finite-number.mjs.map +1 -1
  125. package/dist/number/branded-types/positive-int.d.mts +46 -68
  126. package/dist/number/branded-types/positive-int.d.mts.map +1 -1
  127. package/dist/number/branded-types/positive-int.mjs +34 -49
  128. package/dist/number/branded-types/positive-int.mjs.map +1 -1
  129. package/dist/number/branded-types/positive-int16.d.mts +61 -57
  130. package/dist/number/branded-types/positive-int16.d.mts.map +1 -1
  131. package/dist/number/branded-types/positive-int16.mjs +44 -43
  132. package/dist/number/branded-types/positive-int16.mjs.map +1 -1
  133. package/dist/number/branded-types/positive-int32.d.mts +61 -57
  134. package/dist/number/branded-types/positive-int32.d.mts.map +1 -1
  135. package/dist/number/branded-types/positive-int32.mjs +44 -43
  136. package/dist/number/branded-types/positive-int32.mjs.map +1 -1
  137. package/dist/number/branded-types/positive-safe-int.d.mts +62 -57
  138. package/dist/number/branded-types/positive-safe-int.d.mts.map +1 -1
  139. package/dist/number/branded-types/positive-safe-int.mjs +45 -43
  140. package/dist/number/branded-types/positive-safe-int.mjs.map +1 -1
  141. package/dist/number/branded-types/positive-uint16.d.mts +61 -57
  142. package/dist/number/branded-types/positive-uint16.d.mts.map +1 -1
  143. package/dist/number/branded-types/positive-uint16.mjs +44 -43
  144. package/dist/number/branded-types/positive-uint16.mjs.map +1 -1
  145. package/dist/number/branded-types/positive-uint32.d.mts +61 -58
  146. package/dist/number/branded-types/positive-uint32.d.mts.map +1 -1
  147. package/dist/number/branded-types/positive-uint32.mjs +44 -44
  148. package/dist/number/branded-types/positive-uint32.mjs.map +1 -1
  149. package/dist/number/branded-types/safe-int.d.mts +43 -62
  150. package/dist/number/branded-types/safe-int.d.mts.map +1 -1
  151. package/dist/number/branded-types/safe-int.mjs +35 -42
  152. package/dist/number/branded-types/safe-int.mjs.map +1 -1
  153. package/dist/number/branded-types/safe-uint.d.mts +62 -57
  154. package/dist/number/branded-types/safe-uint.d.mts.map +1 -1
  155. package/dist/number/branded-types/safe-uint.mjs +46 -44
  156. package/dist/number/branded-types/safe-uint.mjs.map +1 -1
  157. package/dist/number/branded-types/uint.d.mts +63 -50
  158. package/dist/number/branded-types/uint.d.mts.map +1 -1
  159. package/dist/number/branded-types/uint.mjs +42 -39
  160. package/dist/number/branded-types/uint.mjs.map +1 -1
  161. package/dist/number/branded-types/uint16.d.mts +60 -58
  162. package/dist/number/branded-types/uint16.d.mts.map +1 -1
  163. package/dist/number/branded-types/uint16.mjs +44 -43
  164. package/dist/number/branded-types/uint16.mjs.map +1 -1
  165. package/dist/number/branded-types/uint32.d.mts +59 -55
  166. package/dist/number/branded-types/uint32.d.mts.map +1 -1
  167. package/dist/number/branded-types/uint32.mjs +42 -42
  168. package/dist/number/branded-types/uint32.mjs.map +1 -1
  169. package/dist/number/enum/int8.d.mts +56 -65
  170. package/dist/number/enum/int8.d.mts.map +1 -1
  171. package/dist/number/enum/int8.mjs +44 -43
  172. package/dist/number/enum/int8.mjs.map +1 -1
  173. package/dist/number/enum/uint8.d.mts +60 -58
  174. package/dist/number/enum/uint8.d.mts.map +1 -1
  175. package/dist/number/enum/uint8.mjs +44 -43
  176. package/dist/number/enum/uint8.mjs.map +1 -1
  177. package/dist/string/index.d.mts +2 -0
  178. package/dist/string/index.d.mts.map +1 -0
  179. package/dist/string/index.mjs +2 -0
  180. package/dist/string/index.mjs.map +1 -0
  181. package/dist/string/str.d.mts +273 -0
  182. package/dist/string/str.d.mts.map +1 -0
  183. package/dist/string/str.mjs +42 -0
  184. package/dist/string/str.mjs.map +1 -0
  185. package/package.json +31 -92
  186. package/src/array/impl/array-utils-creation.mts +2 -1
  187. package/src/array/impl/array-utils-element-access.mts +3 -3
  188. package/src/array/impl/array-utils-element-access.test.mts +3 -3
  189. package/src/{guard/as-length-bounded-array.mts → array/impl/array-utils-length-bounded-array-cast.mts} +9 -9
  190. package/src/{guard/as-length-bounded-array.test.mts → array/impl/array-utils-length-bounded-array-cast.test.mts} +2 -2
  191. package/src/{guard/is-length-bounded-array.mts → array/impl/array-utils-length-bounded-array-guard.mts} +12 -12
  192. package/src/{guard/is-length-bounded-array.test.mts → array/impl/array-utils-length-bounded-array-guard.test.mts} +2 -2
  193. package/src/array/impl/array-utils-modification.mts +9 -8
  194. package/src/array/impl/array-utils-modification.test.mts +6 -1
  195. package/src/array/impl/array-utils-reducing-value.mts +9 -9
  196. package/src/array/impl/array-utils-size.mts +2 -2
  197. package/src/array/impl/array-utils-slicing.mts +24 -13
  198. package/src/array/impl/array-utils-transformation.mts +18 -12
  199. package/src/array/impl/array-utils-transformation.test.mts +12 -12
  200. package/src/array/impl/index.mts +2 -0
  201. package/src/guard/index.mts +0 -3
  202. package/src/index.mts +1 -0
  203. package/src/number/branded-types/finite-number.mts +47 -61
  204. package/src/number/branded-types/int.mts +40 -46
  205. package/src/number/branded-types/int16.mts +65 -58
  206. package/src/number/branded-types/int32.mts +65 -58
  207. package/src/number/branded-types/negative-finite-number.mts +68 -68
  208. package/src/number/branded-types/negative-int.mts +60 -57
  209. package/src/number/branded-types/negative-safe-int.mts +57 -65
  210. package/src/number/branded-types/non-negative-finite-number.mts +74 -64
  211. package/src/number/branded-types/non-negative-int16.mts +64 -57
  212. package/src/number/branded-types/non-negative-int32.mts +64 -58
  213. package/src/number/branded-types/non-positive-finite-number.mts +64 -54
  214. package/src/number/branded-types/non-positive-int.mts +41 -146
  215. package/src/number/branded-types/non-positive-safe-int.mts +54 -53
  216. package/src/number/branded-types/non-zero-finite-number.mts +62 -51
  217. package/src/number/branded-types/non-zero-int.mts +51 -38
  218. package/src/number/branded-types/non-zero-int16.mts +52 -53
  219. package/src/number/branded-types/non-zero-int32.mts +52 -54
  220. package/src/number/branded-types/non-zero-safe-int.mts +53 -54
  221. package/src/number/branded-types/non-zero-uint16.mts +52 -53
  222. package/src/number/branded-types/non-zero-uint32.mts +52 -53
  223. package/src/number/branded-types/positive-finite-number.mts +74 -63
  224. package/src/number/branded-types/positive-int.mts +46 -68
  225. package/src/number/branded-types/positive-int16.mts +61 -57
  226. package/src/number/branded-types/positive-int32.mts +61 -57
  227. package/src/number/branded-types/positive-safe-int.mts +62 -57
  228. package/src/number/branded-types/positive-uint16.mts +61 -57
  229. package/src/number/branded-types/positive-uint32.mts +61 -58
  230. package/src/number/branded-types/safe-int.mts +43 -62
  231. package/src/number/branded-types/safe-uint.mts +62 -57
  232. package/src/number/branded-types/uint.mts +63 -50
  233. package/src/number/branded-types/uint16.mts +60 -58
  234. package/src/number/branded-types/uint32.mts +59 -55
  235. package/src/number/enum/int8.mts +56 -65
  236. package/src/number/enum/uint8.mts +60 -58
  237. package/src/string/index.mts +1 -0
  238. package/src/string/str.mts +371 -0
  239. package/src/string/str.test.mts +215 -0
  240. package/dist/guard/as-length-bounded-array.d.mts.map +0 -1
  241. package/dist/guard/as-length-bounded-array.mjs.map +0 -1
  242. package/dist/guard/is-length-bounded-array.d.mts.map +0 -1
  243. package/dist/guard/is-length-bounded-array.mjs.map +0 -1
  244. package/dist/guard/is-length-bounded-string.d.mts +0 -163
  245. package/dist/guard/is-length-bounded-string.d.mts.map +0 -1
  246. package/dist/guard/is-length-bounded-string.mjs +0 -7
  247. package/dist/guard/is-length-bounded-string.mjs.map +0 -1
  248. package/src/guard/is-length-bounded-string.mts +0 -199
  249. package/src/guard/is-length-bounded-string.test.mts +0 -170
@@ -4,18 +4,24 @@ import { PositiveFiniteNumber } from './positive-finite-number.mjs';
4
4
  export type NegativeFiniteNumber = TtfImported_NegativeFiniteNumber;
5
5
  type ElementType = NegativeFiniteNumber;
6
6
  /**
7
- * Checks if a number is a NegativeFiniteNumber (a finite number `< 0`).
7
+ * Type guard that checks if a value is a negative finite number.
8
8
  *
9
- * @param value The value to check.
10
- * @returns `true` if the value is a NegativeFiniteNumber, `false` otherwise.
9
+ * Returns `true` only for a finite value — never `NaN`, `Infinity`, or
10
+ * `-Infinity`.
11
+ *
12
+ * @param value - The value to check
13
+ * @returns `true` if the value is a negative finite number, `false` otherwise
11
14
  */
12
15
  export declare const isNegativeFiniteNumber: (a: number) => a is TtfImported_NegativeFiniteNumber;
13
16
  /**
14
- * Casts a number to a NegativeFiniteNumber type.
17
+ * Casts a `number` to the `NegativeFiniteNumber` branded type.
18
+ *
19
+ * Validates that the value is a negative finite number and returns it with the
20
+ * `NegativeFiniteNumber` brand. Throws a `TypeError` otherwise.
15
21
  *
16
- * @param value The value to cast.
17
- * @returns The value as a NegativeFiniteNumber type.
18
- * @throws {TypeError} If the value is not a negative finite number.
22
+ * @param value - The value to cast
23
+ * @returns The value as a `NegativeFiniteNumber`
24
+ * @throws {TypeError} If the value is not a negative finite number
19
25
  */
20
26
  export declare const asNegativeFiniteNumber: <N extends number>(x: N) => number & {
21
27
  readonly "!=0": true;
@@ -31,111 +37,114 @@ export declare const asNegativeFiniteNumber: <N extends number>(x: N) => number
31
37
  'TSTypeForgeInternals--edd2f9ce-7ca5-45b0-9d1a-bd61b9b5d9c3': unknown;
32
38
  }> & N;
33
39
  /**
34
- * Namespace providing type-safe arithmetic operations for negative finite
35
- * numbers.
40
+ * Namespace providing type-safe operations for the `NegativeFiniteNumber`
41
+ * branded type.
36
42
  *
37
- * All operations keep results finite (excluding NaN and Infinity). Operations
38
- * that stay within the negative finite numbers clamp their results to the valid
39
- * range, while operations whose result leaves the set (`mul`, `div`, `abs`) are
40
- * typed to reflect the actual sign of the result.
43
+ * The `NegativeFiniteNumber` type represents a negative finite number.
41
44
  */
42
45
  export declare const NegativeFiniteNumber: {
43
46
  /**
44
- * Type guard to check if a value is a NegativeFiniteNumber.
47
+ * Type guard that checks if a value is a negative finite number.
45
48
  *
46
- * @param value The value to check.
47
- * @returns `true` if the value is a negative finite number, `false`
48
- * otherwise.
49
+ * @param value - The value to check
50
+ * @returns `true` if the value is a negative finite number, `false` otherwise
51
+ * @see {@link isNegativeFiniteNumber} for usage examples
49
52
  */
50
53
  readonly is: (a: number) => a is TtfImported_NegativeFiniteNumber;
51
54
  /**
52
- * The maximum value for a negative finite number.
53
- *
54
- * @readonly
55
+ * The largest value representable as `NegativeFiniteNumber`.
55
56
  */
56
57
  readonly MAX_VALUE: number;
57
58
  /**
58
59
  * Returns the absolute value of a negative finite number.
59
60
  *
60
- * @param a The negative finite number.
61
- * @returns The absolute value as a PositiveFiniteNumber.
61
+ * The result is non-negative and keeps the `NegativeFiniteNumber` brand.
62
+ *
63
+ * @param a - The negative finite number value
64
+ * @returns The absolute value as a non-negative `NegativeFiniteNumber`
62
65
  */
63
66
  readonly abs: (x: ElementType) => PositiveFiniteNumber;
64
67
  /**
65
- * Returns the smaller of two NegativeFiniteNumber values.
68
+ * Returns the smallest of the given negative finite numbers.
66
69
  *
67
- * @param a The first NegativeFiniteNumber.
68
- * @param b The second NegativeFiniteNumber.
69
- * @returns The minimum value as a NegativeFiniteNumber.
70
+ * @param values - The negative finite numbers to compare (at least one required)
71
+ * @returns The smallest value as a `NegativeFiniteNumber`
70
72
  */
71
73
  readonly min: (...values: readonly TtfImported_NegativeFiniteNumber[]) => TtfImported_NegativeFiniteNumber;
72
74
  /**
73
- * Returns the larger of two NegativeFiniteNumber values.
75
+ * Returns the largest of the given negative finite numbers.
74
76
  *
75
- * @param a The first NegativeFiniteNumber.
76
- * @param b The second NegativeFiniteNumber.
77
- * @returns The maximum value as a NegativeFiniteNumber.
77
+ * @param values - The negative finite numbers to compare (at least one required)
78
+ * @returns The largest value as a `NegativeFiniteNumber`
78
79
  */
79
80
  readonly max: (...values: readonly TtfImported_NegativeFiniteNumber[]) => TtfImported_NegativeFiniteNumber;
80
81
  /**
81
- * Clamps a number to the negative finite range.
82
+ * Clamps a `number` into the `NegativeFiniteNumber` range `[MIN_VALUE,
83
+ * MAX_VALUE]`.
82
84
  *
83
- * @param value The number to clamp.
84
- * @returns The value clamped to `(-∞, 0)` as a NegativeFiniteNumber.
85
+ * @param value - The value to clamp
86
+ * @returns The clamped value as a `NegativeFiniteNumber`
85
87
  */
86
88
  readonly clamp: (x: number) => TtfImported_NegativeFiniteNumber;
87
89
  /**
88
- * Rounds down a NegativeFiniteNumber to the nearest integer.
90
+ * Returns the greatest integer less than or equal to a negative finite
91
+ * number.
89
92
  *
90
- * @param x The NegativeFiniteNumber to round down.
91
- * @returns The floor value as a NegativeInt (always `<= -1`).
93
+ * @param a - The negative finite number value
94
+ * @returns The floored value as an integer
92
95
  */
93
96
  readonly floor: (x: ElementType) => TsDataForgeInternals.RefinedNumberUtils.ToInt<ElementType>;
94
97
  /**
95
- * Rounds up a NegativeFiniteNumber to the nearest integer.
98
+ * Returns the smallest integer greater than or equal to a negative finite
99
+ * number.
96
100
  *
97
- * @param x The NegativeFiniteNumber to round up.
98
- * @returns The ceiling value as a NonPositiveInt (can be 0).
101
+ * @param a - The negative finite number value
102
+ * @returns The ceiled value as an integer
99
103
  */
100
104
  readonly ceil: (x: ElementType) => TsDataForgeInternals.RefinedNumberUtils.RemoveNonZeroBrandKey<TsDataForgeInternals.RefinedNumberUtils.ToInt<ElementType>>;
101
105
  /**
102
- * Rounds a NegativeFiniteNumber to the nearest integer.
106
+ * Returns the value of a negative finite number rounded to the nearest
107
+ * integer.
103
108
  *
104
- * @param x The NegativeFiniteNumber to round.
105
- * @returns The rounded value as a NonPositiveInt (can be 0 if x > -0.5).
109
+ * @param a - The negative finite number value
110
+ * @returns The rounded value as an integer
106
111
  */
107
112
  readonly round: (x: ElementType) => TsDataForgeInternals.RefinedNumberUtils.RemoveNonZeroBrandKey<TsDataForgeInternals.RefinedNumberUtils.ToInt<ElementType>>;
108
113
  /**
109
- * Generates a random NegativeFiniteNumber value.
114
+ * Generates a random `NegativeFiniteNumber` within the given range.
115
+ *
116
+ * The range is inclusive on both ends.
110
117
  *
111
- * @returns A random negative finite number.
118
+ * @param min - The minimum value (inclusive)
119
+ * @param max - The maximum value (inclusive)
120
+ * @returns A random `NegativeFiniteNumber` in `[min, max]`
112
121
  */
113
122
  readonly random: (min?: TtfImported_NegativeFiniteNumber | undefined, max?: TtfImported_NegativeFiniteNumber | undefined) => TtfImported_NegativeFiniteNumber;
114
123
  /**
115
- * Raises a NegativeFiniteNumber to the power of another NegativeFiniteNumber.
124
+ * Raises `a` to the power `b`, returning `a ** b` as a
125
+ * `NegativeFiniteNumber`.
116
126
  *
117
- * @param a The base NegativeFiniteNumber.
118
- * @param b The exponent NegativeFiniteNumber.
119
- * @returns `a ** b` clamped to `(-∞, 0)` as a NegativeFiniteNumber.
127
+ * @param a - The base negative finite number
128
+ * @param b - The exponent negative finite number
129
+ * @returns `a ** b` as a `NegativeFiniteNumber`
120
130
  */
121
131
  readonly pow: (x: TtfImported_NegativeFiniteNumber, y: TtfImported_NegativeFiniteNumber) => TtfImported_NegativeFiniteNumber;
122
132
  /**
123
- * Adds two NegativeFiniteNumber values.
133
+ * Adds two negative finite numbers, returning `a + b` as a
134
+ * `NegativeFiniteNumber`.
124
135
  *
125
- * @param a The first NegativeFiniteNumber.
126
- * @param b The second NegativeFiniteNumber.
127
- * @returns `a + b` as a NegativeFiniteNumber.
136
+ * @param a - The first negative finite number
137
+ * @param b - The second negative finite number
138
+ * @returns The sum of `a` and `b` as a `NegativeFiniteNumber`
128
139
  */
129
140
  readonly add: (x: TtfImported_NegativeFiniteNumber, y: TtfImported_NegativeFiniteNumber) => TtfImported_NegativeFiniteNumber;
130
141
  /**
131
- * Subtracts one NegativeFiniteNumber from another.
132
- *
133
- * The mathematical result can be positive, so it is clamped to the negative
134
- * finite range (maximum `-Number.MIN_VALUE`).
142
+ * Subtracts two negative finite numbers, returning `a - b` as a
143
+ * `NegativeFiniteNumber`.
135
144
  *
136
- * @param a The minuend NegativeFiniteNumber.
137
- * @param b The subtrahend NegativeFiniteNumber.
138
- * @returns `a - b` clamped to `(-∞, 0)` as a NegativeFiniteNumber.
145
+ * @param a - The first negative finite number
146
+ * @param b - The second negative finite number
147
+ * @returns The difference of `a` and `b` as a `NegativeFiniteNumber`
139
148
  */
140
149
  readonly sub: (x: TtfImported_NegativeFiniteNumber, y: TtfImported_NegativeFiniteNumber) => TtfImported_NegativeFiniteNumber;
141
150
  };
@@ -1 +1 @@
1
- {"version":3,"file":"negative-finite-number.d.mts","sourceRoot":"","sources":["../../../src/number/branded-types/negative-finite-number.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,oBAAoB,IAAI,gCAAgC,EAAE,MAAM,eAAe,CAAC;AAC9F,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAEpE,MAAM,MAAM,oBAAoB,GAAG,gCAAgC,CAAC;AAEpE,KAAK,WAAW,GAAG,oBAAoB,CAAC;AAkExC;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,sDAAK,CAAC;AAEzC;;;;;;GAMG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;MAAW,CAAC;AAE/C;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB;IAC/B;;;;;;OAMG;;IAGH;;;;OAIG;;IAGH;;;;;OAKG;sBA/EW,WAAW,KAAG,oBAAoB;IAkFhD;;;;;;OAMG;;IAGH;;;;;;OAMG;;IAGH;;;;;OAKG;;IAGH;;;;;OAKG;wBA7GA,WAAW,KACb,oBAAoB,CAAC,kBAAkB,CAAC,KAAK,CAAC,WAAW,CAAC;IA+G3D;;;;;OAKG;uBA/GA,WAAW,KACb,oBAAoB,CAAC,kBAAkB,CAAC,qBAAqB,CAC9D,oBAAoB,CAAC,kBAAkB,CAAC,KAAK,CAAC,WAAW,CAAC,CAC3D;IA+GC;;;;;OAKG;wBA7GA,WAAW,KACb,oBAAoB,CAAC,kBAAkB,CAAC,qBAAqB,CAC9D,oBAAoB,CAAC,kBAAkB,CAAC,KAAK,CAAC,WAAW,CAAC,CAC3D;IA6GC;;;;OAIG;;IAGH;;;;;;OAMG;;IAGH;;;;;;OAMG;;IAGH;;;;;;;;;OASG;;CAEK,CAAC"}
1
+ {"version":3,"file":"negative-finite-number.d.mts","sourceRoot":"","sources":["../../../src/number/branded-types/negative-finite-number.mts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,oBAAoB,IAAI,gCAAgC,EAAE,MAAM,eAAe,CAAC;AAC9F,OAAO,EAAE,oBAAoB,EAAE,MAAM,6BAA6B,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,8BAA8B,CAAC;AAEpE,MAAM,MAAM,oBAAoB,GAAG,gCAAgC,CAAC;AAEpE,KAAK,WAAW,GAAG,oBAAoB,CAAC;AAyDxC;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,sDAAK,CAAC;AAEzC;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;MAAW,CAAC;AAE/C;;;;;GAKG;AACH,eAAO,MAAM,oBAAoB;IAC/B;;;;;;OAMG;;IAGH;;OAEG;;IAGH;;;;;;;OAOG;sBAlFW,WAAW,KAAG,oBAAoB;IAqFhD;;;;;OAKG;;IAGH;;;;;OAKG;;IAGH;;;;;;OAMG;;IAGH;;;;;;OAMG;wBAhHA,WAAW,KACb,oBAAoB,CAAC,kBAAkB,CAAC,KAAK,CAAC,WAAW,CAAC;IAkH3D;;;;;;OAMG;uBAnHA,WAAW,KACb,oBAAoB,CAAC,kBAAkB,CAAC,qBAAqB,CAC9D,oBAAoB,CAAC,kBAAkB,CAAC,KAAK,CAAC,WAAW,CAAC,CAC3D;IAmHC;;;;;;OAMG;wBAlHA,WAAW,KACb,oBAAoB,CAAC,kBAAkB,CAAC,qBAAqB,CAC9D,oBAAoB,CAAC,kBAAkB,CAAC,KAAK,CAAC,WAAW,CAAC,CAC3D;IAkHC;;;;;;;;OAQG;;IAGH;;;;;;;OAOG;;IAGH;;;;;;;OAOG;;IAGH;;;;;;;OAOG;;CAEK,CAAC"}
@@ -38,101 +38,107 @@ const isNegativeFiniteNumber = is;
38
38
  const asNegativeFiniteNumber = castType;
39
39
  const NegativeFiniteNumber = {
40
40
  /**
41
- * Type guard to check if a value is a NegativeFiniteNumber.
41
+ * Type guard that checks if a value is a negative finite number.
42
42
  *
43
- * @param value The value to check.
44
- * @returns `true` if the value is a negative finite number, `false`
45
- * otherwise.
43
+ * @param value - The value to check
44
+ * @returns `true` if the value is a negative finite number, `false` otherwise
45
+ * @see {@link isNegativeFiniteNumber} for usage examples
46
46
  */
47
47
  is,
48
48
  /**
49
- * The maximum value for a negative finite number.
50
- *
51
- * @readonly
49
+ * The largest value representable as `NegativeFiniteNumber`.
52
50
  */
53
51
  MAX_VALUE,
54
52
  /**
55
53
  * Returns the absolute value of a negative finite number.
56
54
  *
57
- * @param a The negative finite number.
58
- * @returns The absolute value as a PositiveFiniteNumber.
55
+ * The result is non-negative and keeps the `NegativeFiniteNumber` brand.
56
+ *
57
+ * @param a - The negative finite number value
58
+ * @returns The absolute value as a non-negative `NegativeFiniteNumber`
59
59
  */
60
60
  abs,
61
61
  /**
62
- * Returns the smaller of two NegativeFiniteNumber values.
62
+ * Returns the smallest of the given negative finite numbers.
63
63
  *
64
- * @param a The first NegativeFiniteNumber.
65
- * @param b The second NegativeFiniteNumber.
66
- * @returns The minimum value as a NegativeFiniteNumber.
64
+ * @param values - The negative finite numbers to compare (at least one required)
65
+ * @returns The smallest value as a `NegativeFiniteNumber`
67
66
  */
68
67
  min: min_,
69
68
  /**
70
- * Returns the larger of two NegativeFiniteNumber values.
69
+ * Returns the largest of the given negative finite numbers.
71
70
  *
72
- * @param a The first NegativeFiniteNumber.
73
- * @param b The second NegativeFiniteNumber.
74
- * @returns The maximum value as a NegativeFiniteNumber.
71
+ * @param values - The negative finite numbers to compare (at least one required)
72
+ * @returns The largest value as a `NegativeFiniteNumber`
75
73
  */
76
74
  max: max_,
77
75
  /**
78
- * Clamps a number to the negative finite range.
76
+ * Clamps a `number` into the `NegativeFiniteNumber` range `[MIN_VALUE,
77
+ * MAX_VALUE]`.
79
78
  *
80
- * @param value The number to clamp.
81
- * @returns The value clamped to `(-∞, 0)` as a NegativeFiniteNumber.
79
+ * @param value - The value to clamp
80
+ * @returns The clamped value as a `NegativeFiniteNumber`
82
81
  */
83
82
  clamp,
84
83
  /**
85
- * Rounds down a NegativeFiniteNumber to the nearest integer.
84
+ * Returns the greatest integer less than or equal to a negative finite
85
+ * number.
86
86
  *
87
- * @param x The NegativeFiniteNumber to round down.
88
- * @returns The floor value as a NegativeInt (always `<= -1`).
87
+ * @param a - The negative finite number value
88
+ * @returns The floored value as an integer
89
89
  */
90
90
  floor,
91
91
  /**
92
- * Rounds up a NegativeFiniteNumber to the nearest integer.
92
+ * Returns the smallest integer greater than or equal to a negative finite
93
+ * number.
93
94
  *
94
- * @param x The NegativeFiniteNumber to round up.
95
- * @returns The ceiling value as a NonPositiveInt (can be 0).
95
+ * @param a - The negative finite number value
96
+ * @returns The ceiled value as an integer
96
97
  */
97
98
  ceil,
98
99
  /**
99
- * Rounds a NegativeFiniteNumber to the nearest integer.
100
+ * Returns the value of a negative finite number rounded to the nearest
101
+ * integer.
100
102
  *
101
- * @param x The NegativeFiniteNumber to round.
102
- * @returns The rounded value as a NonPositiveInt (can be 0 if x > -0.5).
103
+ * @param a - The negative finite number value
104
+ * @returns The rounded value as an integer
103
105
  */
104
106
  round,
105
107
  /**
106
- * Generates a random NegativeFiniteNumber value.
108
+ * Generates a random `NegativeFiniteNumber` within the given range.
107
109
  *
108
- * @returns A random negative finite number.
110
+ * The range is inclusive on both ends.
111
+ *
112
+ * @param min - The minimum value (inclusive)
113
+ * @param max - The maximum value (inclusive)
114
+ * @returns A random `NegativeFiniteNumber` in `[min, max]`
109
115
  */
110
116
  random,
111
117
  /**
112
- * Raises a NegativeFiniteNumber to the power of another NegativeFiniteNumber.
118
+ * Raises `a` to the power `b`, returning `a ** b` as a
119
+ * `NegativeFiniteNumber`.
113
120
  *
114
- * @param a The base NegativeFiniteNumber.
115
- * @param b The exponent NegativeFiniteNumber.
116
- * @returns `a ** b` clamped to `(-∞, 0)` as a NegativeFiniteNumber.
121
+ * @param a - The base negative finite number
122
+ * @param b - The exponent negative finite number
123
+ * @returns `a ** b` as a `NegativeFiniteNumber`
117
124
  */
118
125
  pow,
119
126
  /**
120
- * Adds two NegativeFiniteNumber values.
127
+ * Adds two negative finite numbers, returning `a + b` as a
128
+ * `NegativeFiniteNumber`.
121
129
  *
122
- * @param a The first NegativeFiniteNumber.
123
- * @param b The second NegativeFiniteNumber.
124
- * @returns `a + b` as a NegativeFiniteNumber.
130
+ * @param a - The first negative finite number
131
+ * @param b - The second negative finite number
132
+ * @returns The sum of `a` and `b` as a `NegativeFiniteNumber`
125
133
  */
126
134
  add,
127
135
  /**
128
- * Subtracts one NegativeFiniteNumber from another.
129
- *
130
- * The mathematical result can be positive, so it is clamped to the negative
131
- * finite range (maximum `-Number.MIN_VALUE`).
136
+ * Subtracts two negative finite numbers, returning `a - b` as a
137
+ * `NegativeFiniteNumber`.
132
138
  *
133
- * @param a The minuend NegativeFiniteNumber.
134
- * @param b The subtrahend NegativeFiniteNumber.
135
- * @returns `a - b` clamped to `(-∞, 0)` as a NegativeFiniteNumber.
139
+ * @param a - The first negative finite number
140
+ * @param b - The second negative finite number
141
+ * @returns The difference of `a` and `b` as a `NegativeFiniteNumber`
136
142
  */
137
143
  sub
138
144
  };
@@ -1 +1 @@
1
- {"version":3,"file":"negative-finite-number.mjs","sources":["../../../src/number/branded-types/negative-finite-number.mts"],"sourcesContent":["import { type NegativeFiniteNumber as TtfImported_NegativeFiniteNumber } from 'ts-type-forge';\nimport { TsDataForgeInternals } from '../refined-number-utils.mjs';\nimport { PositiveFiniteNumber } from './positive-finite-number.mjs';\n\nexport type NegativeFiniteNumber = TtfImported_NegativeFiniteNumber;\n\ntype ElementType = NegativeFiniteNumber;\n\nconst typeNameInMessage = 'a negative finite number';\n\nconst {\n MAX_VALUE,\n add,\n castType,\n clamp,\n is,\n max: max_,\n min: min_,\n pow,\n random,\n sub,\n} = TsDataForgeInternals.RefinedNumberUtils.operatorsForFloat<\n ElementType,\n number,\n number\n>({\n nonZero: true,\n MIN_VALUE: -Number.MAX_VALUE,\n MAX_VALUE: -Number.MIN_VALUE,\n typeNameInMessage,\n} as const);\n\n/**\n * Returns the absolute value of a negative finite number.\n *\n * The absolute value of a negative finite number is always a positive finite\n * number, so the result is typed as a {@link PositiveFiniteNumber}.\n *\n * @param x - The negative finite number.\n * @returns `|x|` as a PositiveFiniteNumber.\n */\nconst abs = (x: ElementType): PositiveFiniteNumber =>\n PositiveFiniteNumber.clamp(Math.abs(x));\n\nconst floor = (\n x: ElementType,\n): TsDataForgeInternals.RefinedNumberUtils.ToInt<ElementType> =>\n // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n Math.floor(x) as TsDataForgeInternals.RefinedNumberUtils.ToInt<ElementType>;\n\nconst ceil = (\n x: ElementType,\n): TsDataForgeInternals.RefinedNumberUtils.RemoveNonZeroBrandKey<\n TsDataForgeInternals.RefinedNumberUtils.ToInt<ElementType>\n> =>\n // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n Math.ceil(x) as TsDataForgeInternals.RefinedNumberUtils.RemoveNonZeroBrandKey<\n TsDataForgeInternals.RefinedNumberUtils.ToInt<ElementType>\n >;\n\nconst round = (\n x: ElementType,\n): TsDataForgeInternals.RefinedNumberUtils.RemoveNonZeroBrandKey<\n TsDataForgeInternals.RefinedNumberUtils.ToInt<ElementType>\n> =>\n // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n Math.round(\n x,\n ) as TsDataForgeInternals.RefinedNumberUtils.RemoveNonZeroBrandKey<\n TsDataForgeInternals.RefinedNumberUtils.ToInt<ElementType>\n >;\n\n/**\n * Checks if a number is a NegativeFiniteNumber (a finite number `< 0`).\n *\n * @param value The value to check.\n * @returns `true` if the value is a NegativeFiniteNumber, `false` otherwise.\n */\nexport const isNegativeFiniteNumber = is;\n\n/**\n * Casts a number to a NegativeFiniteNumber type.\n *\n * @param value The value to cast.\n * @returns The value as a NegativeFiniteNumber type.\n * @throws {TypeError} If the value is not a negative finite number.\n */\nexport const asNegativeFiniteNumber = castType;\n\n/**\n * Namespace providing type-safe arithmetic operations for negative finite\n * numbers.\n *\n * All operations keep results finite (excluding NaN and Infinity). Operations\n * that stay within the negative finite numbers clamp their results to the valid\n * range, while operations whose result leaves the set (`mul`, `div`, `abs`) are\n * typed to reflect the actual sign of the result.\n */\nexport const NegativeFiniteNumber = {\n /**\n * Type guard to check if a value is a NegativeFiniteNumber.\n *\n * @param value The value to check.\n * @returns `true` if the value is a negative finite number, `false`\n * otherwise.\n */\n is,\n\n /**\n * The maximum value for a negative finite number.\n *\n * @readonly\n */\n MAX_VALUE,\n\n /**\n * Returns the absolute value of a negative finite number.\n *\n * @param a The negative finite number.\n * @returns The absolute value as a PositiveFiniteNumber.\n */\n abs,\n\n /**\n * Returns the smaller of two NegativeFiniteNumber values.\n *\n * @param a The first NegativeFiniteNumber.\n * @param b The second NegativeFiniteNumber.\n * @returns The minimum value as a NegativeFiniteNumber.\n */\n min: min_,\n\n /**\n * Returns the larger of two NegativeFiniteNumber values.\n *\n * @param a The first NegativeFiniteNumber.\n * @param b The second NegativeFiniteNumber.\n * @returns The maximum value as a NegativeFiniteNumber.\n */\n max: max_,\n\n /**\n * Clamps a number to the negative finite range.\n *\n * @param value The number to clamp.\n * @returns The value clamped to `(-∞, 0)` as a NegativeFiniteNumber.\n */\n clamp,\n\n /**\n * Rounds down a NegativeFiniteNumber to the nearest integer.\n *\n * @param x The NegativeFiniteNumber to round down.\n * @returns The floor value as a NegativeInt (always `<= -1`).\n */\n floor,\n\n /**\n * Rounds up a NegativeFiniteNumber to the nearest integer.\n *\n * @param x The NegativeFiniteNumber to round up.\n * @returns The ceiling value as a NonPositiveInt (can be 0).\n */\n ceil,\n\n /**\n * Rounds a NegativeFiniteNumber to the nearest integer.\n *\n * @param x The NegativeFiniteNumber to round.\n * @returns The rounded value as a NonPositiveInt (can be 0 if x > -0.5).\n */\n round,\n\n /**\n * Generates a random NegativeFiniteNumber value.\n *\n * @returns A random negative finite number.\n */\n random,\n\n /**\n * Raises a NegativeFiniteNumber to the power of another NegativeFiniteNumber.\n *\n * @param a The base NegativeFiniteNumber.\n * @param b The exponent NegativeFiniteNumber.\n * @returns `a ** b` clamped to `(-∞, 0)` as a NegativeFiniteNumber.\n */\n pow,\n\n /**\n * Adds two NegativeFiniteNumber values.\n *\n * @param a The first NegativeFiniteNumber.\n * @param b The second NegativeFiniteNumber.\n * @returns `a + b` as a NegativeFiniteNumber.\n */\n add,\n\n /**\n * Subtracts one NegativeFiniteNumber from another.\n *\n * The mathematical result can be positive, so it is clamped to the negative\n * finite range (maximum `-Number.MIN_VALUE`).\n *\n * @param a The minuend NegativeFiniteNumber.\n * @param b The subtrahend NegativeFiniteNumber.\n * @returns `a - b` clamped to `(-∞, 0)` as a NegativeFiniteNumber.\n */\n sub,\n} as const;\n"],"names":[],"mappings":";;;AAQA,MAAM,iBAAA,GAAoB,0BAAA;AAE1B,MAAM;AAAA,EACJ,SAAA;AAAA,EACA,GAAA;AAAA,EACA,QAAA;AAAA,EACA,KAAA;AAAA,EACA,EAAA;AAAA,EACA,GAAA,EAAK,IAAA;AAAA,EACL,GAAA,EAAK,IAAA;AAAA,EACL,GAAA;AAAA,EACA,MAAA;AAAA,EACA;AACF,CAAA,GAAI,oBAAA,CAAqB,mBAAmB,iBAAA,CAI1C;AAAA,EACA,OAAA,EAAS,IAAA;AAAA,EACT,SAAA,EAAW,CAAC,MAAA,CAAO,SAAA;AAAA,EACnB,SAAA,EAAW,CAAC,MAAA,CAAO,SAAA;AAAA,EACnB;AACF,CAAU,CAAA;AAWV,MAAM,GAAA,GAAM,CAAC,CAAA,KACX,oBAAA,CAAqB,MAAM,IAAA,CAAK,GAAA,CAAI,CAAC,CAAC,CAAA;AAExC,MAAM,QAAQ,CACZ,CAAA;AAAA;AAAA,EAGA,IAAA,CAAK,MAAM,CAAC;AAAA,CAAA;AAEd,MAAM,OAAO,CACX,CAAA;AAAA;AAAA,EAKA,IAAA,CAAK,KAAK,CAAC;AAAA,CAAA;AAIb,MAAM,QAAQ,CACZ,CAAA;AAAA;AAAA,EAKA,IAAA,CAAK,KAAA;AAAA,IACH;AAAA;AACF,CAAA;AAUK,MAAM,sBAAA,GAAyB;AAS/B,MAAM,sBAAA,GAAyB;AAW/B,MAAM,oBAAA,GAAuB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQlC,EAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,SAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,GAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,GAAA,EAAK,IAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASL,GAAA,EAAK,IAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQL,KAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,KAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,IAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQA,KAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,MAAA;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;AAAA;AAAA,EAYA;AACF;;;;"}
1
+ {"version":3,"file":"negative-finite-number.mjs","sources":["../../../src/number/branded-types/negative-finite-number.mts"],"sourcesContent":["import { type NegativeFiniteNumber as TtfImported_NegativeFiniteNumber } from 'ts-type-forge';\nimport { TsDataForgeInternals } from '../refined-number-utils.mjs';\nimport { PositiveFiniteNumber } from './positive-finite-number.mjs';\n\nexport type NegativeFiniteNumber = TtfImported_NegativeFiniteNumber;\n\ntype ElementType = NegativeFiniteNumber;\n\nconst typeNameInMessage = 'a negative finite number';\n\nconst {\n MAX_VALUE,\n add,\n castType,\n clamp,\n is,\n max: max_,\n min: min_,\n pow,\n random,\n sub,\n} = TsDataForgeInternals.RefinedNumberUtils.operatorsForFloat<\n ElementType,\n number,\n number\n>({\n nonZero: true,\n MIN_VALUE: -Number.MAX_VALUE,\n MAX_VALUE: -Number.MIN_VALUE,\n typeNameInMessage,\n} as const);\n\nconst abs = (x: ElementType): PositiveFiniteNumber =>\n PositiveFiniteNumber.clamp(Math.abs(x));\n\nconst floor = (\n x: ElementType,\n): TsDataForgeInternals.RefinedNumberUtils.ToInt<ElementType> =>\n // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n Math.floor(x) as TsDataForgeInternals.RefinedNumberUtils.ToInt<ElementType>;\n\nconst ceil = (\n x: ElementType,\n): TsDataForgeInternals.RefinedNumberUtils.RemoveNonZeroBrandKey<\n TsDataForgeInternals.RefinedNumberUtils.ToInt<ElementType>\n> =>\n // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n Math.ceil(x) as TsDataForgeInternals.RefinedNumberUtils.RemoveNonZeroBrandKey<\n TsDataForgeInternals.RefinedNumberUtils.ToInt<ElementType>\n >;\n\nconst round = (\n x: ElementType,\n): TsDataForgeInternals.RefinedNumberUtils.RemoveNonZeroBrandKey<\n TsDataForgeInternals.RefinedNumberUtils.ToInt<ElementType>\n> =>\n // eslint-disable-next-line total-functions/no-unsafe-type-assertion\n Math.round(\n x,\n ) as TsDataForgeInternals.RefinedNumberUtils.RemoveNonZeroBrandKey<\n TsDataForgeInternals.RefinedNumberUtils.ToInt<ElementType>\n >;\n\n/**\n * Type guard that checks if a value is a negative finite number.\n *\n * Returns `true` only for a finite value — never `NaN`, `Infinity`, or\n * `-Infinity`.\n *\n * @param value - The value to check\n * @returns `true` if the value is a negative finite number, `false` otherwise\n */\nexport const isNegativeFiniteNumber = is;\n\n/**\n * Casts a `number` to the `NegativeFiniteNumber` branded type.\n *\n * Validates that the value is a negative finite number and returns it with the\n * `NegativeFiniteNumber` brand. Throws a `TypeError` otherwise.\n *\n * @param value - The value to cast\n * @returns The value as a `NegativeFiniteNumber`\n * @throws {TypeError} If the value is not a negative finite number\n */\nexport const asNegativeFiniteNumber = castType;\n\n/**\n * Namespace providing type-safe operations for the `NegativeFiniteNumber`\n * branded type.\n *\n * The `NegativeFiniteNumber` type represents a negative finite number.\n */\nexport const NegativeFiniteNumber = {\n /**\n * Type guard that checks if a value is a negative finite number.\n *\n * @param value - The value to check\n * @returns `true` if the value is a negative finite number, `false` otherwise\n * @see {@link isNegativeFiniteNumber} for usage examples\n */\n is,\n\n /**\n * The largest value representable as `NegativeFiniteNumber`.\n */\n MAX_VALUE,\n\n /**\n * Returns the absolute value of a negative finite number.\n *\n * The result is non-negative and keeps the `NegativeFiniteNumber` brand.\n *\n * @param a - The negative finite number value\n * @returns The absolute value as a non-negative `NegativeFiniteNumber`\n */\n abs,\n\n /**\n * Returns the smallest of the given negative finite numbers.\n *\n * @param values - The negative finite numbers to compare (at least one required)\n * @returns The smallest value as a `NegativeFiniteNumber`\n */\n min: min_,\n\n /**\n * Returns the largest of the given negative finite numbers.\n *\n * @param values - The negative finite numbers to compare (at least one required)\n * @returns The largest value as a `NegativeFiniteNumber`\n */\n max: max_,\n\n /**\n * Clamps a `number` into the `NegativeFiniteNumber` range `[MIN_VALUE,\n * MAX_VALUE]`.\n *\n * @param value - The value to clamp\n * @returns The clamped value as a `NegativeFiniteNumber`\n */\n clamp,\n\n /**\n * Returns the greatest integer less than or equal to a negative finite\n * number.\n *\n * @param a - The negative finite number value\n * @returns The floored value as an integer\n */\n floor,\n\n /**\n * Returns the smallest integer greater than or equal to a negative finite\n * number.\n *\n * @param a - The negative finite number value\n * @returns The ceiled value as an integer\n */\n ceil,\n\n /**\n * Returns the value of a negative finite number rounded to the nearest\n * integer.\n *\n * @param a - The negative finite number value\n * @returns The rounded value as an integer\n */\n round,\n\n /**\n * Generates a random `NegativeFiniteNumber` 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 `NegativeFiniteNumber` in `[min, max]`\n */\n random,\n\n /**\n * Raises `a` to the power `b`, returning `a ** b` as a\n * `NegativeFiniteNumber`.\n *\n * @param a - The base negative finite number\n * @param b - The exponent negative finite number\n * @returns `a ** b` as a `NegativeFiniteNumber`\n */\n pow,\n\n /**\n * Adds two negative finite numbers, returning `a + b` as a\n * `NegativeFiniteNumber`.\n *\n * @param a - The first negative finite number\n * @param b - The second negative finite number\n * @returns The sum of `a` and `b` as a `NegativeFiniteNumber`\n */\n add,\n\n /**\n * Subtracts two negative finite numbers, returning `a - b` as a\n * `NegativeFiniteNumber`.\n *\n * @param a - The first negative finite number\n * @param b - The second negative finite number\n * @returns The difference of `a` and `b` as a `NegativeFiniteNumber`\n */\n sub,\n} as const;\n"],"names":[],"mappings":";;;AAQA,MAAM,iBAAA,GAAoB,0BAAA;AAE1B,MAAM;AAAA,EACJ,SAAA;AAAA,EACA,GAAA;AAAA,EACA,QAAA;AAAA,EACA,KAAA;AAAA,EACA,EAAA;AAAA,EACA,GAAA,EAAK,IAAA;AAAA,EACL,GAAA,EAAK,IAAA;AAAA,EACL,GAAA;AAAA,EACA,MAAA;AAAA,EACA;AACF,CAAA,GAAI,oBAAA,CAAqB,mBAAmB,iBAAA,CAI1C;AAAA,EACA,OAAA,EAAS,IAAA;AAAA,EACT,SAAA,EAAW,CAAC,MAAA,CAAO,SAAA;AAAA,EACnB,SAAA,EAAW,CAAC,MAAA,CAAO,SAAA;AAAA,EACnB;AACF,CAAU,CAAA;AAEV,MAAM,GAAA,GAAM,CAAC,CAAA,KACX,oBAAA,CAAqB,MAAM,IAAA,CAAK,GAAA,CAAI,CAAC,CAAC,CAAA;AAExC,MAAM,QAAQ,CACZ,CAAA;AAAA;AAAA,EAGA,IAAA,CAAK,MAAM,CAAC;AAAA,CAAA;AAEd,MAAM,OAAO,CACX,CAAA;AAAA;AAAA,EAKA,IAAA,CAAK,KAAK,CAAC;AAAA,CAAA;AAIb,MAAM,QAAQ,CACZ,CAAA;AAAA;AAAA,EAKA,IAAA,CAAK,KAAA;AAAA,IACH;AAAA;AACF,CAAA;AAaK,MAAM,sBAAA,GAAyB;AAY/B,MAAM,sBAAA,GAAyB;AAQ/B,MAAM,oBAAA,GAAuB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAQlC,EAAA;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,EASA,KAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,IAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,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;AAAA,EAUA,GAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAUA;AACF;;;;"}
@@ -3,18 +3,24 @@ import { PositiveInt } from './positive-int.mjs';
3
3
  export type NegativeInt = TtfImported_NegativeInt;
4
4
  type ElementType = NegativeInt;
5
5
  /**
6
- * Checks if a number is a NegativeInt (a negative integer `<= -1`).
6
+ * Type guard that checks if a value is a negative integer.
7
7
  *
8
- * @param value The value to check.
9
- * @returns `true` if the value is a NegativeInt, `false` otherwise.
8
+ * Returns `true` for a negative integer — a value with no fractional component,
9
+ * including values outside the safe integer range (unlike `SafeInt`).
10
+ *
11
+ * @param value - The value to check
12
+ * @returns `true` if the value is a negative integer, `false` otherwise
10
13
  */
11
14
  export declare const isNegativeInt: (a: number) => a is TtfImported_NegativeInt;
12
15
  /**
13
- * Casts a number to a NegativeInt type.
16
+ * Casts a `number` to the `NegativeInt` branded type.
17
+ *
18
+ * Validates that the value is a negative integer and returns it with the
19
+ * `NegativeInt` brand. Throws a `TypeError` otherwise.
14
20
  *
15
- * @param value The value to cast.
16
- * @returns The value as a NegativeInt type.
17
- * @throws {TypeError} If the value is not a negative integer.
21
+ * @param value - The value to cast
22
+ * @returns The value as a `NegativeInt`
23
+ * @throws {TypeError} If the value is not a negative integer
18
24
  */
19
25
  export declare const asNegativeInt: <N extends number>(x: N) => number & {
20
26
  readonly "!=0": true;
@@ -31,88 +37,94 @@ export declare const asNegativeInt: <N extends number>(x: N) => number & {
31
37
  'TSTypeForgeInternals--edd2f9ce-7ca5-45b0-9d1a-bd61b9b5d9c3': unknown;
32
38
  }> & N;
33
39
  /**
34
- * Namespace providing type-safe arithmetic operations for negative integers.
40
+ * Namespace providing type-safe operations for the `NegativeInt` branded type.
35
41
  *
36
- * NegativeInt represents integers that are strictly less than zero (`<= -1`).
37
- * Operations that stay within the negative integers (such as `add`) clamp their
38
- * results to the valid range, while operations whose result leaves the set
39
- * (`mul`, `div`, `abs`) are typed to reflect the actual sign of the result.
42
+ * The `NegativeInt` type represents a negative integer. Division (`div`) uses
43
+ * floor division.
44
+ *
45
+ * Unlike `SafeInt`, `NegativeInt` allows values outside the safe integer range
46
+ * (±2^53 − 1), so very large magnitudes may lose precision in JavaScript's
47
+ * `number` type.
40
48
  */
41
49
  export declare const NegativeInt: {
42
50
  /**
43
- * Type guard to check if a value is a NegativeInt.
51
+ * Type guard that checks if a value is a negative integer.
44
52
  *
45
- * @param value The value to check.
46
- * @returns `true` if the value is a negative integer, `false` otherwise.
53
+ * @param value - The value to check
54
+ * @returns `true` if the value is a negative integer, `false` otherwise
55
+ * @see {@link isNegativeInt} for usage examples
47
56
  */
48
57
  readonly is: (a: number) => a is TtfImported_NegativeInt;
49
58
  /**
50
- * The maximum value for a negative integer.
51
- *
52
- * @readonly
59
+ * The largest value representable as `NegativeInt`.
53
60
  */
54
61
  readonly MAX_VALUE: -1;
55
62
  /**
56
63
  * Returns the absolute value of a negative integer.
57
64
  *
58
- * @param a The negative integer.
59
- * @returns The absolute value as a PositiveInt.
65
+ * The result is non-negative and keeps the `NegativeInt` brand. Note that
66
+ * `Math.abs(Number.MIN_SAFE_INTEGER)` exceeds `Number.MAX_SAFE_INTEGER`, so
67
+ * use `SafeInt` for guaranteed precision.
68
+ *
69
+ * @param a - The negative integer value
70
+ * @returns The absolute value as a non-negative `NegativeInt`
60
71
  */
61
72
  readonly abs: (x: WithSmallInt<ElementType>) => PositiveInt;
62
73
  /**
63
- * Returns the smaller of two negative integers.
74
+ * Returns the smallest of the given negative integers.
64
75
  *
65
- * @param a The first negative integer.
66
- * @param b The second negative integer.
67
- * @returns The minimum value as a NegativeInt.
76
+ * @param values - The negative integers to compare (at least one required)
77
+ * @returns The smallest value as a `NegativeInt`
68
78
  */
69
79
  readonly min: (...values: readonly WithSmallInt<TtfImported_NegativeInt>[]) => TtfImported_NegativeInt;
70
80
  /**
71
- * Returns the larger of two negative integers.
81
+ * Returns the largest of the given negative integers.
72
82
  *
73
- * @param a The first negative integer.
74
- * @param b The second negative integer.
75
- * @returns The maximum value as a NegativeInt.
83
+ * @param values - The negative integers to compare (at least one required)
84
+ * @returns The largest value as a `NegativeInt`
76
85
  */
77
86
  readonly max: (...values: readonly WithSmallInt<TtfImported_NegativeInt>[]) => TtfImported_NegativeInt;
78
87
  /**
79
- * Clamps a number to the negative integer range.
88
+ * Clamps a `number` into the `NegativeInt` range, rounding to the nearest
89
+ * integer and constraining the result to `[MIN_VALUE, MAX_VALUE]`.
80
90
  *
81
- * @param value The number to clamp.
82
- * @returns The value clamped to `[-∞, -1]` as a NegativeInt.
91
+ * @param value - The value to clamp
92
+ * @returns The clamped value as a `NegativeInt`
83
93
  */
84
94
  readonly clamp: (x: number) => TtfImported_NegativeInt;
85
95
  /**
86
- * Generates a random NegativeInt value within the valid range.
96
+ * Generates a random `NegativeInt` within the given range.
97
+ *
98
+ * The range is inclusive on both ends.
87
99
  *
88
- * @returns A random negative integer.
100
+ * @param min - The minimum value (inclusive)
101
+ * @param max - The maximum value (inclusive)
102
+ * @returns A random `NegativeInt` in `[min, max]`
89
103
  */
90
104
  readonly random: (min?: WithSmallInt<TtfImported_NegativeInt> | undefined, max?: WithSmallInt<TtfImported_NegativeInt> | undefined) => TtfImported_NegativeInt;
91
105
  /**
92
- * Raises a negative integer to the power of another negative integer.
106
+ * Raises `a` to the power `b`, returning `a ** b` as a `NegativeInt` (floored
107
+ * to an integer).
93
108
  *
94
- * @param a The base negative integer.
95
- * @param b The exponent negative integer.
96
- * @returns `a ** b` clamped to the negative integer range.
109
+ * @param a - The base negative integer
110
+ * @param b - The exponent negative integer
111
+ * @returns `a ** b` as a `NegativeInt`
97
112
  */
98
113
  readonly pow: (x: WithSmallInt<TtfImported_NegativeInt>, y: WithSmallInt<TtfImported_NegativeInt>) => TtfImported_NegativeInt;
99
114
  /**
100
- * Adds two negative integers.
115
+ * Adds two negative integers, returning `a + b` as a `NegativeInt`.
101
116
  *
102
- * @param a The first negative integer.
103
- * @param b The second negative integer.
104
- * @returns `a + b` as a NegativeInt.
117
+ * @param a - The first negative integer
118
+ * @param b - The second negative integer
119
+ * @returns The sum of `a` and `b` as a `NegativeInt`
105
120
  */
106
121
  readonly add: (x: WithSmallInt<TtfImported_NegativeInt>, y: WithSmallInt<TtfImported_NegativeInt>) => TtfImported_NegativeInt;
107
122
  /**
108
- * Subtracts one negative integer from another.
109
- *
110
- * The mathematical result can be positive, so it is clamped to the negative
111
- * integer range (maximum `-1`).
123
+ * Subtracts two negative integers, returning `a - b` as a `NegativeInt`.
112
124
  *
113
- * @param a The minuend negative integer.
114
- * @param b The subtrahend negative integer.
115
- * @returns `a - b` clamped to the negative integer range.
125
+ * @param a - The first negative integer
126
+ * @param b - The second negative integer
127
+ * @returns The difference of `a` and `b` as a `NegativeInt`
116
128
  */
117
129
  readonly sub: (x: WithSmallInt<TtfImported_NegativeInt>, y: WithSmallInt<TtfImported_NegativeInt>) => TtfImported_NegativeInt;
118
130
  };
@@ -1 +1 @@
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"}
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;AA8B/B;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,6CAAK,CAAC;AAEhC;;;;;;;;;GASG;AACH,eAAO,MAAM,aAAa;;;;;;;;;;;;;MAAW,CAAC;AAEtC;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW;IACtB;;;;;;OAMG;;IAGH;;OAEG;;IAGH;;;;;;;;;OASG;sBA5DW,YAAY,CAAC,WAAW,CAAC,KAAG,WAAW;IA+DrD;;;;;OAKG;;IAGH;;;;;OAKG;;IAGH;;;;;;OAMG;;IAGH;;;;;;;;OAQG;;IAGH;;;;;;;OAOG;;IAGH;;;;;;OAMG;;IAGH;;;;;;OAMG;;CAEK,CAAC"}