ts-data-forge 1.0.0 → 1.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 (292) hide show
  1. package/README.md +1 -1
  2. package/dist/array/array-utils.d.mts +2617 -0
  3. package/dist/array/array-utils.d.mts.map +1 -0
  4. package/dist/array/array-utils.mjs +2915 -0
  5. package/dist/array/array-utils.mjs.map +1 -0
  6. package/dist/array/index.d.mts +3 -0
  7. package/dist/array/index.d.mts.map +1 -0
  8. package/dist/array/index.mjs +3 -0
  9. package/dist/array/index.mjs.map +1 -0
  10. package/dist/array/tuple-utils.d.mts +421 -0
  11. package/dist/array/tuple-utils.d.mts.map +1 -0
  12. package/dist/array/tuple-utils.mjs +391 -0
  13. package/dist/array/tuple-utils.mjs.map +1 -0
  14. package/dist/collections/imap-mapped.d.mts +445 -0
  15. package/dist/collections/imap-mapped.d.mts.map +1 -0
  16. package/dist/collections/imap-mapped.mjs +424 -0
  17. package/dist/collections/imap-mapped.mjs.map +1 -0
  18. package/dist/collections/imap.d.mts +359 -0
  19. package/dist/collections/imap.d.mts.map +1 -0
  20. package/dist/collections/imap.mjs +338 -0
  21. package/dist/collections/imap.mjs.map +1 -0
  22. package/dist/collections/index.d.mts +7 -0
  23. package/dist/collections/index.d.mts.map +1 -0
  24. package/dist/collections/index.mjs +7 -0
  25. package/dist/collections/index.mjs.map +1 -0
  26. package/dist/collections/iset-mapped.d.mts +576 -0
  27. package/dist/collections/iset-mapped.d.mts.map +1 -0
  28. package/dist/collections/iset-mapped.mjs +522 -0
  29. package/dist/collections/iset-mapped.mjs.map +1 -0
  30. package/dist/collections/iset.d.mts +426 -0
  31. package/dist/collections/iset.d.mts.map +1 -0
  32. package/dist/collections/iset.mjs +437 -0
  33. package/dist/collections/iset.mjs.map +1 -0
  34. package/dist/collections/queue.d.mts +190 -0
  35. package/dist/collections/queue.d.mts.map +1 -0
  36. package/dist/collections/queue.mjs +317 -0
  37. package/dist/collections/queue.mjs.map +1 -0
  38. package/dist/collections/stack.d.mts +210 -0
  39. package/dist/collections/stack.d.mts.map +1 -0
  40. package/dist/collections/stack.mjs +353 -0
  41. package/dist/collections/stack.mjs.map +1 -0
  42. package/dist/expect-type.d.mts +199 -0
  43. package/dist/expect-type.d.mts.map +1 -0
  44. package/dist/expect-type.mjs +201 -0
  45. package/dist/expect-type.mjs.map +1 -0
  46. package/dist/functional/index.d.mts +5 -0
  47. package/dist/functional/index.d.mts.map +1 -0
  48. package/dist/functional/index.mjs +5 -0
  49. package/dist/functional/index.mjs.map +1 -0
  50. package/dist/functional/match.d.mts +215 -0
  51. package/dist/functional/match.d.mts.map +1 -0
  52. package/dist/functional/match.mjs +139 -0
  53. package/dist/functional/match.mjs.map +1 -0
  54. package/dist/functional/optional.d.mts +517 -0
  55. package/dist/functional/optional.d.mts.map +1 -0
  56. package/dist/functional/optional.mjs +532 -0
  57. package/dist/functional/optional.mjs.map +1 -0
  58. package/dist/functional/pipe.d.mts +185 -0
  59. package/dist/functional/pipe.d.mts.map +1 -0
  60. package/dist/functional/pipe.mjs +129 -0
  61. package/dist/functional/pipe.mjs.map +1 -0
  62. package/dist/functional/result.d.mts +796 -0
  63. package/dist/functional/result.d.mts.map +1 -0
  64. package/dist/functional/result.mjs +844 -0
  65. package/dist/functional/result.mjs.map +1 -0
  66. package/dist/globals.d.mts +38 -0
  67. package/dist/guard/has-key.d.mts +100 -0
  68. package/dist/guard/has-key.d.mts.map +1 -0
  69. package/dist/guard/has-key.mjs +94 -0
  70. package/dist/guard/has-key.mjs.map +1 -0
  71. package/dist/guard/index.d.mts +8 -0
  72. package/dist/guard/index.d.mts.map +1 -0
  73. package/dist/guard/index.mjs +8 -0
  74. package/dist/guard/index.mjs.map +1 -0
  75. package/dist/guard/is-non-empty-string.d.mts +106 -0
  76. package/dist/guard/is-non-empty-string.d.mts.map +1 -0
  77. package/dist/guard/is-non-empty-string.mjs +108 -0
  78. package/dist/guard/is-non-empty-string.mjs.map +1 -0
  79. package/dist/guard/is-non-null-object.d.mts +105 -0
  80. package/dist/guard/is-non-null-object.d.mts.map +1 -0
  81. package/dist/guard/is-non-null-object.mjs +108 -0
  82. package/dist/guard/is-non-null-object.mjs.map +1 -0
  83. package/dist/guard/is-primitive.d.mts +146 -0
  84. package/dist/guard/is-primitive.d.mts.map +1 -0
  85. package/dist/guard/is-primitive.mjs +161 -0
  86. package/dist/guard/is-primitive.mjs.map +1 -0
  87. package/dist/guard/is-record.d.mts +151 -0
  88. package/dist/guard/is-record.d.mts.map +1 -0
  89. package/dist/guard/is-record.mjs +155 -0
  90. package/dist/guard/is-record.mjs.map +1 -0
  91. package/dist/guard/is-type.d.mts +430 -0
  92. package/dist/guard/is-type.d.mts.map +1 -0
  93. package/dist/guard/is-type.mjs +432 -0
  94. package/dist/guard/is-type.mjs.map +1 -0
  95. package/dist/guard/key-is-in.d.mts +158 -0
  96. package/dist/guard/key-is-in.d.mts.map +1 -0
  97. package/dist/guard/key-is-in.mjs +160 -0
  98. package/dist/guard/key-is-in.mjs.map +1 -0
  99. package/dist/index.d.mts +11 -0
  100. package/dist/index.d.mts.map +1 -0
  101. package/dist/index.mjs +61 -0
  102. package/dist/index.mjs.map +1 -0
  103. package/dist/iterator/index.d.mts +2 -0
  104. package/dist/iterator/index.d.mts.map +1 -0
  105. package/dist/iterator/index.mjs +2 -0
  106. package/dist/iterator/index.mjs.map +1 -0
  107. package/dist/iterator/range.d.mts +97 -0
  108. package/dist/iterator/range.d.mts.map +1 -0
  109. package/dist/iterator/range.mjs +130 -0
  110. package/dist/iterator/range.mjs.map +1 -0
  111. package/dist/json/index.d.mts +2 -0
  112. package/dist/json/index.d.mts.map +1 -0
  113. package/dist/json/index.mjs +2 -0
  114. package/dist/json/index.mjs.map +1 -0
  115. package/dist/json/json.d.mts +597 -0
  116. package/dist/json/json.d.mts.map +1 -0
  117. package/dist/json/json.mjs +687 -0
  118. package/dist/json/json.mjs.map +1 -0
  119. package/dist/number/branded-types/finite-number.d.mts +291 -0
  120. package/dist/number/branded-types/finite-number.d.mts.map +1 -0
  121. package/dist/number/branded-types/finite-number.mjs +296 -0
  122. package/dist/number/branded-types/finite-number.mjs.map +1 -0
  123. package/dist/number/branded-types/index.d.mts +27 -0
  124. package/dist/number/branded-types/index.d.mts.map +1 -0
  125. package/dist/number/branded-types/index.mjs +27 -0
  126. package/dist/number/branded-types/index.mjs.map +1 -0
  127. package/dist/number/branded-types/int.d.mts +242 -0
  128. package/dist/number/branded-types/int.d.mts.map +1 -0
  129. package/dist/number/branded-types/int.mjs +239 -0
  130. package/dist/number/branded-types/int.mjs.map +1 -0
  131. package/dist/number/branded-types/int16.d.mts +162 -0
  132. package/dist/number/branded-types/int16.d.mts.map +1 -0
  133. package/dist/number/branded-types/int16.mjs +141 -0
  134. package/dist/number/branded-types/int16.mjs.map +1 -0
  135. package/dist/number/branded-types/int32.d.mts +155 -0
  136. package/dist/number/branded-types/int32.d.mts.map +1 -0
  137. package/dist/number/branded-types/int32.mjs +142 -0
  138. package/dist/number/branded-types/int32.mjs.map +1 -0
  139. package/dist/number/branded-types/non-negative-finite-number.d.mts +165 -0
  140. package/dist/number/branded-types/non-negative-finite-number.d.mts.map +1 -0
  141. package/dist/number/branded-types/non-negative-finite-number.mjs +160 -0
  142. package/dist/number/branded-types/non-negative-finite-number.mjs.map +1 -0
  143. package/dist/number/branded-types/non-negative-int16.d.mts +160 -0
  144. package/dist/number/branded-types/non-negative-int16.d.mts.map +1 -0
  145. package/dist/number/branded-types/non-negative-int16.mjs +138 -0
  146. package/dist/number/branded-types/non-negative-int16.mjs.map +1 -0
  147. package/dist/number/branded-types/non-negative-int32.d.mts +156 -0
  148. package/dist/number/branded-types/non-negative-int32.d.mts.map +1 -0
  149. package/dist/number/branded-types/non-negative-int32.mjs +138 -0
  150. package/dist/number/branded-types/non-negative-int32.mjs.map +1 -0
  151. package/dist/number/branded-types/non-zero-finite-number.d.mts +154 -0
  152. package/dist/number/branded-types/non-zero-finite-number.d.mts.map +1 -0
  153. package/dist/number/branded-types/non-zero-finite-number.mjs +160 -0
  154. package/dist/number/branded-types/non-zero-finite-number.mjs.map +1 -0
  155. package/dist/number/branded-types/non-zero-int.d.mts +131 -0
  156. package/dist/number/branded-types/non-zero-int.d.mts.map +1 -0
  157. package/dist/number/branded-types/non-zero-int.mjs +128 -0
  158. package/dist/number/branded-types/non-zero-int.mjs.map +1 -0
  159. package/dist/number/branded-types/non-zero-int16.d.mts +166 -0
  160. package/dist/number/branded-types/non-zero-int16.d.mts.map +1 -0
  161. package/dist/number/branded-types/non-zero-int16.mjs +145 -0
  162. package/dist/number/branded-types/non-zero-int16.mjs.map +1 -0
  163. package/dist/number/branded-types/non-zero-int32.d.mts +158 -0
  164. package/dist/number/branded-types/non-zero-int32.d.mts.map +1 -0
  165. package/dist/number/branded-types/non-zero-int32.mjs +145 -0
  166. package/dist/number/branded-types/non-zero-int32.mjs.map +1 -0
  167. package/dist/number/branded-types/non-zero-safe-int.d.mts +148 -0
  168. package/dist/number/branded-types/non-zero-safe-int.d.mts.map +1 -0
  169. package/dist/number/branded-types/non-zero-safe-int.mjs +145 -0
  170. package/dist/number/branded-types/non-zero-safe-int.mjs.map +1 -0
  171. package/dist/number/branded-types/non-zero-uint16.d.mts +160 -0
  172. package/dist/number/branded-types/non-zero-uint16.d.mts.map +1 -0
  173. package/dist/number/branded-types/non-zero-uint16.mjs +140 -0
  174. package/dist/number/branded-types/non-zero-uint16.mjs.map +1 -0
  175. package/dist/number/branded-types/non-zero-uint32.d.mts +156 -0
  176. package/dist/number/branded-types/non-zero-uint32.d.mts.map +1 -0
  177. package/dist/number/branded-types/non-zero-uint32.mjs +140 -0
  178. package/dist/number/branded-types/non-zero-uint32.mjs.map +1 -0
  179. package/dist/number/branded-types/positive-finite-number.d.mts +171 -0
  180. package/dist/number/branded-types/positive-finite-number.d.mts.map +1 -0
  181. package/dist/number/branded-types/positive-finite-number.mjs +165 -0
  182. package/dist/number/branded-types/positive-finite-number.mjs.map +1 -0
  183. package/dist/number/branded-types/positive-int.d.mts +270 -0
  184. package/dist/number/branded-types/positive-int.d.mts.map +1 -0
  185. package/dist/number/branded-types/positive-int.mjs +257 -0
  186. package/dist/number/branded-types/positive-int.mjs.map +1 -0
  187. package/dist/number/branded-types/positive-int16.d.mts +162 -0
  188. package/dist/number/branded-types/positive-int16.d.mts.map +1 -0
  189. package/dist/number/branded-types/positive-int16.mjs +139 -0
  190. package/dist/number/branded-types/positive-int16.mjs.map +1 -0
  191. package/dist/number/branded-types/positive-int32.d.mts +158 -0
  192. package/dist/number/branded-types/positive-int32.d.mts.map +1 -0
  193. package/dist/number/branded-types/positive-int32.mjs +139 -0
  194. package/dist/number/branded-types/positive-int32.mjs.map +1 -0
  195. package/dist/number/branded-types/positive-safe-int.d.mts +152 -0
  196. package/dist/number/branded-types/positive-safe-int.d.mts.map +1 -0
  197. package/dist/number/branded-types/positive-safe-int.mjs +138 -0
  198. package/dist/number/branded-types/positive-safe-int.mjs.map +1 -0
  199. package/dist/number/branded-types/positive-uint16.d.mts +160 -0
  200. package/dist/number/branded-types/positive-uint16.d.mts.map +1 -0
  201. package/dist/number/branded-types/positive-uint16.mjs +139 -0
  202. package/dist/number/branded-types/positive-uint16.mjs.map +1 -0
  203. package/dist/number/branded-types/positive-uint32.d.mts +156 -0
  204. package/dist/number/branded-types/positive-uint32.d.mts.map +1 -0
  205. package/dist/number/branded-types/positive-uint32.mjs +139 -0
  206. package/dist/number/branded-types/positive-uint32.mjs.map +1 -0
  207. package/dist/number/branded-types/safe-int.d.mts +243 -0
  208. package/dist/number/branded-types/safe-int.d.mts.map +1 -0
  209. package/dist/number/branded-types/safe-int.mjs +240 -0
  210. package/dist/number/branded-types/safe-int.mjs.map +1 -0
  211. package/dist/number/branded-types/safe-uint.d.mts +151 -0
  212. package/dist/number/branded-types/safe-uint.d.mts.map +1 -0
  213. package/dist/number/branded-types/safe-uint.mjs +138 -0
  214. package/dist/number/branded-types/safe-uint.mjs.map +1 -0
  215. package/dist/number/branded-types/uint.d.mts +144 -0
  216. package/dist/number/branded-types/uint.d.mts.map +1 -0
  217. package/dist/number/branded-types/uint.mjs +132 -0
  218. package/dist/number/branded-types/uint.mjs.map +1 -0
  219. package/dist/number/branded-types/uint16.d.mts +157 -0
  220. package/dist/number/branded-types/uint16.d.mts.map +1 -0
  221. package/dist/number/branded-types/uint16.mjs +137 -0
  222. package/dist/number/branded-types/uint16.mjs.map +1 -0
  223. package/dist/number/branded-types/uint32.d.mts +185 -0
  224. package/dist/number/branded-types/uint32.d.mts.map +1 -0
  225. package/dist/number/branded-types/uint32.mjs +169 -0
  226. package/dist/number/branded-types/uint32.mjs.map +1 -0
  227. package/dist/number/enum/index.d.mts +3 -0
  228. package/dist/number/enum/index.d.mts.map +1 -0
  229. package/dist/number/enum/index.mjs +3 -0
  230. package/dist/number/enum/index.mjs.map +1 -0
  231. package/dist/number/enum/int8.d.mts +202 -0
  232. package/dist/number/enum/int8.d.mts.map +1 -0
  233. package/dist/number/enum/int8.mjs +296 -0
  234. package/dist/number/enum/int8.mjs.map +1 -0
  235. package/dist/number/enum/uint8.d.mts +128 -0
  236. package/dist/number/enum/uint8.d.mts.map +1 -0
  237. package/dist/number/enum/uint8.mjs +251 -0
  238. package/dist/number/enum/uint8.mjs.map +1 -0
  239. package/dist/number/index.d.mts +5 -0
  240. package/dist/number/index.d.mts.map +1 -0
  241. package/dist/number/index.mjs +31 -0
  242. package/dist/number/index.mjs.map +1 -0
  243. package/dist/number/num.d.mts +515 -0
  244. package/dist/number/num.d.mts.map +1 -0
  245. package/dist/number/num.mjs +513 -0
  246. package/dist/number/num.mjs.map +1 -0
  247. package/dist/number/refined-number-utils.d.mts +191 -0
  248. package/dist/number/refined-number-utils.d.mts.map +1 -0
  249. package/dist/number/refined-number-utils.mjs +179 -0
  250. package/dist/number/refined-number-utils.mjs.map +1 -0
  251. package/dist/object/index.d.mts +2 -0
  252. package/dist/object/index.d.mts.map +1 -0
  253. package/dist/object/index.mjs +2 -0
  254. package/dist/object/index.mjs.map +1 -0
  255. package/dist/object/object.d.mts +296 -0
  256. package/dist/object/object.d.mts.map +1 -0
  257. package/dist/object/object.mjs +295 -0
  258. package/dist/object/object.mjs.map +1 -0
  259. package/dist/others/cast-mutable.d.mts +110 -0
  260. package/dist/others/cast-mutable.d.mts.map +1 -0
  261. package/dist/others/cast-mutable.mjs +114 -0
  262. package/dist/others/cast-mutable.mjs.map +1 -0
  263. package/dist/others/cast-readonly.d.mts +189 -0
  264. package/dist/others/cast-readonly.d.mts.map +1 -0
  265. package/dist/others/cast-readonly.mjs +193 -0
  266. package/dist/others/cast-readonly.mjs.map +1 -0
  267. package/dist/others/if-then.d.mts +98 -0
  268. package/dist/others/if-then.d.mts.map +1 -0
  269. package/dist/others/if-then.mjs +100 -0
  270. package/dist/others/if-then.mjs.map +1 -0
  271. package/dist/others/index.d.mts +8 -0
  272. package/dist/others/index.d.mts.map +1 -0
  273. package/dist/others/index.mjs +8 -0
  274. package/dist/others/index.mjs.map +1 -0
  275. package/dist/others/map-nullable.d.mts +151 -0
  276. package/dist/others/map-nullable.d.mts.map +1 -0
  277. package/dist/others/map-nullable.mjs +159 -0
  278. package/dist/others/map-nullable.mjs.map +1 -0
  279. package/dist/others/memoize-function.d.mts +173 -0
  280. package/dist/others/memoize-function.d.mts.map +1 -0
  281. package/dist/others/memoize-function.mjs +189 -0
  282. package/dist/others/memoize-function.mjs.map +1 -0
  283. package/dist/others/tuple.d.mts +159 -0
  284. package/dist/others/tuple.d.mts.map +1 -0
  285. package/dist/others/tuple.mjs +161 -0
  286. package/dist/others/tuple.mjs.map +1 -0
  287. package/dist/others/unknown-to-string.d.mts +180 -0
  288. package/dist/others/unknown-to-string.d.mts.map +1 -0
  289. package/dist/others/unknown-to-string.mjs +211 -0
  290. package/dist/others/unknown-to-string.mjs.map +1 -0
  291. package/dist/tsconfig.json +1 -0
  292. package/package.json +16 -14
@@ -0,0 +1,513 @@
1
+ /**
2
+ * Namespace providing utility functions for number manipulation and validation.
3
+ *
4
+ * This namespace offers a comprehensive set of type-safe number utilities including:
5
+ * - Type conversion and validation
6
+ * - Type guards for numeric constraints (non-zero, non-negative, positive)
7
+ * - Range checking and clamping operations
8
+ * - Mathematical operations with type safety
9
+ * - Rounding utilities
10
+ *
11
+ * Many functions in this namespace leverage TypeScript's type system to provide
12
+ * compile-time guarantees about numeric constraints.
13
+ *
14
+ * @example
15
+ * ```typescript
16
+ * // Type conversion
17
+ * const num = Num.from('123.45'); // 123.45
18
+ * const invalid = Num.from('abc'); // NaN
19
+ *
20
+ * // Type guards
21
+ * const value = 5;
22
+ * if (Num.isPositive(value)) {
23
+ * // value is typed as PositiveNumber & 5
24
+ * }
25
+ *
26
+ * // Range checking
27
+ * const isValid = Num.isInRange(0, 100)(50); // true
28
+ *
29
+ * // Clamping
30
+ * const clamped = Num.clamp(150, 0, 100); // 100
31
+ * const clampFn = Num.clamp(0, 100);
32
+ * const result = clampFn(150); // 100
33
+ * ```
34
+ */
35
+ var Num;
36
+ (function (Num) {
37
+ /**
38
+ * Converts an unknown value to a number. Alias for the `Number` constructor.
39
+ * @param n The value to convert.
40
+ * @returns The numeric representation of `n`.
41
+ * @example
42
+ * ```typescript
43
+ * Num.from('123'); // 123
44
+ * Num.from('123.45'); // 123.45
45
+ * Num.from(true); // 1
46
+ * Num.from(false); // 0
47
+ * Num.from('hello'); // NaN
48
+ * ```
49
+ */
50
+ Num.from = Number;
51
+ /**
52
+ * Type guard that checks if a number is non-zero.
53
+ *
54
+ * When this function returns `true`, TypeScript narrows the type to exclude zero,
55
+ * providing compile-time safety for division operations and other calculations
56
+ * that require non-zero values.
57
+ *
58
+ * @template N - The numeric literal type or number type to check
59
+ * @param num - The number to check
60
+ * @returns `true` if the number is not zero, `false` otherwise
61
+ *
62
+ * @example
63
+ * ```typescript
64
+ * const value = 5;
65
+ * if (Num.isNonZero(value)) {
66
+ * // value is typed as NonZeroNumber & 5
67
+ * const result = 10 / value; // Safe division
68
+ * }
69
+ *
70
+ * // Works with numeric literals
71
+ * const literal = 0 as 0 | 1 | 2;
72
+ * if (Num.isNonZero(literal)) {
73
+ * // literal is typed as 1 | 2
74
+ * }
75
+ * ```
76
+ */
77
+ Num.isNonZero = (num) => num !== 0;
78
+ /**
79
+ * Type guard that checks if a number is non-negative (greater than or equal to zero).
80
+ *
81
+ * When this function returns `true`, TypeScript narrows the type to exclude negative
82
+ * values, which is useful for operations that require non-negative inputs like
83
+ * array indices or measurements.
84
+ *
85
+ * @template N - The numeric literal type or number type to check
86
+ * @param num - The number to check
87
+ * @returns `true` if the number is >= 0, `false` otherwise
88
+ *
89
+ * @example
90
+ * ```typescript
91
+ * const value = 10;
92
+ * if (Num.isNonNegative(value)) {
93
+ * // value is typed as NonNegativeNumber & 10
94
+ * const arr = new Array(value); // Safe array creation
95
+ * }
96
+ *
97
+ * // Type narrowing with unions
98
+ * const index = -1 as -1 | 0 | 1;
99
+ * if (Num.isNonNegative(index)) {
100
+ * // index is typed as 0 | 1
101
+ * }
102
+ * ```
103
+ */
104
+ Num.isNonNegative = (num) => num >= 0;
105
+ /**
106
+ * Type guard that checks if a number is positive (greater than zero).
107
+ *
108
+ * When this function returns `true`, TypeScript narrows the type to exclude zero
109
+ * and negative values. This is particularly useful for validating inputs that
110
+ * must be strictly positive, such as dimensions, counts, or rates.
111
+ *
112
+ * @template N - The numeric literal type or number type to check
113
+ * @param num - The number to check
114
+ * @returns `true` if the number is > 0, `false` otherwise
115
+ *
116
+ * @example
117
+ * ```typescript
118
+ * const count = 5;
119
+ * if (Num.isPositive(count)) {
120
+ * // count is typed as PositiveNumber & 5
121
+ * const average = total / count; // Safe division
122
+ * }
123
+ *
124
+ * // Type narrowing with numeric literals
125
+ * const value = 0 as -1 | 0 | 1 | 2;
126
+ * if (Num.isPositive(value)) {
127
+ * // value is typed as 1 | 2
128
+ * }
129
+ * ```
130
+ */
131
+ Num.isPositive = (num) => num > 0;
132
+ /**
133
+ * Creates a function that checks if a number `x` is within the range `lowerBound <= x < upperBound`.
134
+ * @param lowerBound The lower bound (inclusive).
135
+ * @param upperBound The upper bound (exclusive).
136
+ * @returns A function that takes a number `x` and returns `true` if `x` is in the range, `false` otherwise.
137
+ * @example
138
+ * ```typescript
139
+ * const isInRange0to10 = Num.isInRange(0, 10);
140
+ * isInRange0to10(5); // true
141
+ * isInRange0to10(0); // true (inclusive lower bound)
142
+ * isInRange0to10(10); // false (exclusive upper bound)
143
+ * isInRange0to10(-1); // false
144
+ * ```
145
+ */
146
+ Num.isInRange = (lowerBound, upperBound) => (x) => lowerBound <= x && x < upperBound;
147
+ /**
148
+ * Creates a function that checks if a number `x` is within the range `lowerBound <= x <= upperBound`.
149
+ * @param lowerBound The lower bound (inclusive).
150
+ * @param upperBound The upper bound (inclusive).
151
+ * @returns A function that takes a number `x` and returns `true` if `x` is in the range, `false` otherwise.
152
+ * @example
153
+ * ```typescript
154
+ * const inRange = Num.isInRangeInclusive(1, 10);
155
+ * console.log(inRange(1)); // true (lower bound)
156
+ * console.log(inRange(5)); // true
157
+ * console.log(inRange(10)); // true (upper bound)
158
+ * console.log(inRange(11)); // false
159
+ * ```
160
+ */
161
+ Num.isInRangeInclusive = (lowerBound, upperBound) => (x) => lowerBound <= x && x <= upperBound;
162
+ /**
163
+ * Creates a type guard that checks if a number is an unsigned integer within a specified range.
164
+ *
165
+ * This function returns a predicate that validates whether a number is:
166
+ * - A safe integer (no floating point)
167
+ * - Within the range [lowerBound, upperBound)
168
+ *
169
+ * The returned type guard provides precise type narrowing when the bounds are
170
+ * SmallUint literals, making it ideal for array index validation.
171
+ *
172
+ * @template L - The lower bound as a SmallUint literal type
173
+ * @template U - The upper bound as a SmallUint literal type
174
+ * @param lowerBound - The minimum value (inclusive)
175
+ * @param upperBound - The maximum value (exclusive)
176
+ * @returns A type guard function that validates and narrows number types
177
+ *
178
+ * @example
179
+ * ```typescript
180
+ * // Array index validation
181
+ * const isValidIndex = Num.isUintInRange(0, 10);
182
+ * const index: number = getUserInput();
183
+ *
184
+ * if (isValidIndex(index)) {
185
+ * // index is typed as 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
186
+ * const value = array[index]; // Safe array access
187
+ * }
188
+ *
189
+ * // Custom range validation
190
+ * const isValidPercentage = Num.isUintInRange(0, 101);
191
+ * if (isValidPercentage(value)) {
192
+ * // value is typed as 0 | 1 | ... | 100
193
+ * }
194
+ * ```
195
+ */
196
+ Num.isUintInRange = (lowerBound, upperBound) => (x) => Number.isSafeInteger(x) && lowerBound <= x && x < upperBound;
197
+ /**
198
+ * Creates a type guard that checks if a number is an unsigned integer within a specified inclusive range.
199
+ *
200
+ * This function returns a predicate that validates whether a number is:
201
+ * - A safe integer (no floating point)
202
+ * - Within the range [lowerBound, upperBound] (both bounds inclusive)
203
+ *
204
+ * The returned type guard provides precise type narrowing when the bounds are
205
+ * SmallUint literals, useful for validating scores, percentages, or other bounded values.
206
+ *
207
+ * @template L - The lower bound as a SmallUint literal type
208
+ * @template U - The upper bound as a SmallUint literal type
209
+ * @param lowerBound - The minimum value (inclusive)
210
+ * @param upperBound - The maximum value (inclusive)
211
+ * @returns A type guard function that validates and narrows number types
212
+ *
213
+ * @example
214
+ * ```typescript
215
+ * // Score validation (0-100)
216
+ * const isValidScore = Num.isUintInRangeInclusive(0, 100);
217
+ * const score: number = getTestScore();
218
+ *
219
+ * if (isValidScore(score)) {
220
+ * // score is typed as 0 | 1 | 2 | ... | 100
221
+ * const grade = calculateGrade(score);
222
+ * }
223
+ *
224
+ * // Day of month validation
225
+ * const isValidDay = Num.isUintInRangeInclusive(1, 31);
226
+ * if (isValidDay(day)) {
227
+ * // day is typed as 1 | 2 | ... | 31
228
+ * }
229
+ * ```
230
+ */
231
+ Num.isUintInRangeInclusive = (lowerBound, upperBound) => (x) => Number.isSafeInteger(x) && lowerBound <= x && x <= upperBound;
232
+ /**
233
+ * Clamps a value within the given range. If the target value is invalid (not finite), returns the lower bound.
234
+ *
235
+ * Provides two usage patterns for maximum flexibility:
236
+ * - **Direct usage**: Pass all three arguments to get the clamped value immediately
237
+ * - **Curried usage**: Pass bounds to get a reusable clamping function
238
+ *
239
+ * @example
240
+ * Direct usage:
241
+ * ```typescript
242
+ * Num.clamp(15, 0, 10); // 10 (clamped to upper bound)
243
+ * Num.clamp(-5, 0, 10); // 0 (clamped to lower bound)
244
+ * Num.clamp(5, 0, 10); // 5 (within bounds)
245
+ * Num.clamp(NaN, 0, 10); // 0 (invalid values default to lower bound)
246
+ * ```
247
+ *
248
+ * @example
249
+ * Curried usage for reusable functions:
250
+ * ```typescript
251
+ * const clampToPercent = Num.clamp(0, 100);
252
+ * clampToPercent(150); // 100
253
+ * clampToPercent(-10); // 0
254
+ * clampToPercent(75); // 75
255
+ *
256
+ * // Perfect for pipe composition
257
+ * const result = pipe(userInput)
258
+ * .map(Number)
259
+ * .map(clampToPercent).value;
260
+ * ```
261
+ *
262
+ * @example
263
+ * Working with arrays and functional programming:
264
+ * ```typescript
265
+ * const clampTo0_1 = Num.clamp(0, 1);
266
+ * const normalizedValues = values.map(clampTo0_1);
267
+ *
268
+ * // Temperature clamping
269
+ * const clampTemperature = Num.clamp(-40, 50);
270
+ * const safeTemperatures = readings.map(clampTemperature);
271
+ * ```
272
+ */
273
+ // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
274
+ Num.clamp = ((...args) => {
275
+ switch (args.length) {
276
+ case 3: {
277
+ const [target, lowerBound, upperBound] = args;
278
+ return !Number.isFinite(target)
279
+ ? lowerBound
280
+ : Math.max(lowerBound, Math.min(upperBound, target));
281
+ }
282
+ case 2: {
283
+ const [lowerBound, upperBound] = args;
284
+ return (target) => Num.clamp(target, lowerBound, upperBound);
285
+ }
286
+ }
287
+ });
288
+ /**
289
+ * Performs type-safe division with compile-time zero-check.
290
+ *
291
+ * This function leverages TypeScript's type system to prevent division by zero
292
+ * at compile time. The divisor must be typed as NonZeroNumber or a non-zero
293
+ * numeric literal.
294
+ *
295
+ * @param a - The dividend
296
+ * @param b - The divisor (must be non-zero, enforced by types)
297
+ * @returns The quotient of a / b
298
+ *
299
+ * @example
300
+ * ```typescript
301
+ * // Safe division with literals
302
+ * const result1 = Num.div(10, 2); // 5
303
+ * const result2 = Num.div(7, 3); // 2.3333...
304
+ *
305
+ * // Compile-time error prevention
306
+ * // Num.div(10, 0); // ❌ TypeScript error: Type '0' is not assignable
307
+ *
308
+ * // With type guards
309
+ * const divisor: number = getDivisor();
310
+ * if (Num.isNonZero(divisor)) {
311
+ * const result = Num.div(100, divisor); // ✅ Safe
312
+ * }
313
+ *
314
+ * // With branded types
315
+ * const nonZero = asNonZeroNumber(5);
316
+ * const result3 = Num.div(20, nonZero); // 4
317
+ * ```
318
+ */
319
+ Num.div = (a, b) => a / b;
320
+ /**
321
+ * Performs integer division using floor division.
322
+ *
323
+ * Computes `⌊a / b⌋` by flooring both operands before division and then
324
+ * flooring the result. This ensures integer arithmetic semantics.
325
+ *
326
+ * Note: Unlike `div`, this function does not enforce non-zero divisor at
327
+ * compile time. Division by zero returns `NaN`.
328
+ *
329
+ * @param a - The dividend
330
+ * @param b - The divisor
331
+ * @returns The integer quotient, or `NaN` if b is zero
332
+ *
333
+ * @example
334
+ * ```typescript
335
+ * Num.divInt(10, 3); // 3
336
+ * Num.divInt(10, -3); // -4 (floor division)
337
+ * Num.divInt(-10, 3); // -4
338
+ * Num.divInt(10.7, 3.2); // 3 (floors both inputs first)
339
+ * Num.divInt(10, 0); // NaN
340
+ * ```
341
+ */
342
+ Num.divInt = (a, b) => Math.floor(Math.floor(a) / Math.floor(b));
343
+ /**
344
+ * Rounds a number to a specified number of decimal places.
345
+ *
346
+ * Uses the standard rounding algorithm (round half up) to round the number
347
+ * to the given precision. The precision must be a positive safe integer.
348
+ *
349
+ * @param num - The number to round
350
+ * @param precision - The number of decimal places (must be positive)
351
+ * @returns The rounded number
352
+ *
353
+ * @example
354
+ * ```typescript
355
+ * Num.roundAt(3.14159, 2); // 3.14
356
+ * Num.roundAt(3.14159, 4); // 3.1416
357
+ * Num.roundAt(10.5, 0); // 11
358
+ * Num.roundAt(-10.5, 0); // -10
359
+ * Num.roundAt(0.005, 2); // 0.01
360
+ * ```
361
+ */
362
+ Num.roundAt = (num, precision) => {
363
+ const digit = 10 ** precision;
364
+ return Math.round(num * digit) / digit;
365
+ };
366
+ /**
367
+ * Rounds a number to the nearest integer using bitwise operations.
368
+ *
369
+ * This function uses a bitwise OR trick for potentially faster rounding.
370
+ * Note: This implementation rounds half up for positive numbers but may
371
+ * behave differently for negative numbers compared to Math.round.
372
+ *
373
+ * @param num - The number to round
374
+ * @returns The rounded integer as an Int branded type
375
+ *
376
+ * @example
377
+ * ```typescript
378
+ * Num.roundToInt(3.2); // 3
379
+ * Num.roundToInt(3.5); // 4
380
+ * Num.roundToInt(3.8); // 4
381
+ * Num.roundToInt(-3.2); // -3
382
+ * Num.roundToInt(-3.8); // -3
383
+ * ```
384
+ */
385
+ // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
386
+ Num.roundToInt = (num) => (0 | (num + 0.5));
387
+ /**
388
+ * Creates a reusable rounding function with a fixed precision.
389
+ *
390
+ * This is a curried version of roundAt that returns a function configured
391
+ * to always round to the specified number of decimal places. Useful for
392
+ * creating consistent rounding behavior across multiple values.
393
+ *
394
+ * @param digit - The number of decimal places for rounding
395
+ * @returns A function that rounds numbers to the specified precision
396
+ *
397
+ * @example
398
+ * ```typescript
399
+ * // Create specialized rounding functions
400
+ * const roundTo2 = Num.round(2);
401
+ * const roundTo4 = Num.round(4);
402
+ *
403
+ * roundTo2(3.14159); // 3.14
404
+ * roundTo2(2.71828); // 2.72
405
+ * roundTo2(10); // 10
406
+ *
407
+ * roundTo4(3.14159); // 3.1416
408
+ *
409
+ * // Use with array operations
410
+ * const values = [1.234, 5.678, 9.012];
411
+ * const rounded = values.map(roundTo2); // [1.23, 5.68, 9.01]
412
+ * ```
413
+ */
414
+ Num.round = (digit) => {
415
+ const powAmount = 10 ** digit;
416
+ return (target) => Num.roundToInt(powAmount * target) / powAmount;
417
+ };
418
+ /**
419
+ * Converts NaN values to undefined while preserving all other numbers.
420
+ *
421
+ * This function is useful for handling potentially invalid numeric operations
422
+ * in a type-safe way, converting NaN results to undefined for easier handling
423
+ * with optional chaining or nullish coalescing.
424
+ *
425
+ * @template N - The numeric type (literal or number)
426
+ * @param num - The number to check
427
+ * @returns The original number if not NaN, otherwise undefined
428
+ *
429
+ * @example
430
+ * ```typescript
431
+ * Num.mapNaN2Undefined(42); // 42
432
+ * Num.mapNaN2Undefined(0); // 0
433
+ * Num.mapNaN2Undefined(NaN); // undefined
434
+ * Num.mapNaN2Undefined(Math.sqrt(-1)); // undefined
435
+ *
436
+ * // Useful in chains
437
+ * const result = Num.mapNaN2Undefined(parseFloat(userInput)) ?? 0;
438
+ *
439
+ * // Type narrowing
440
+ * const value = Math.sqrt(x);
441
+ * const safe = Num.mapNaN2Undefined(value);
442
+ * if (safe !== undefined) {
443
+ * // safe is typed without NaN
444
+ * }
445
+ * ```
446
+ */
447
+ Num.mapNaN2Undefined = (num) => Number.isNaN(num)
448
+ ? undefined
449
+ : // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
450
+ num;
451
+ /**
452
+ * Type-safe increment operation for SmallUint values.
453
+ *
454
+ * Increments a SmallUint (0-40) by 1 with the result type computed at
455
+ * compile time. This provides type-level arithmetic for small unsigned
456
+ * integers, useful for type-safe counter operations.
457
+ *
458
+ * @template N - A SmallUint literal type (0-40)
459
+ * @param n - The SmallUint value to increment
460
+ * @returns The incremented value with type Increment<N>
461
+ *
462
+ * @example
463
+ * ```typescript
464
+ * const zero = 0 as 0;
465
+ * const one = Num.increment(zero); // type is 1, value is 1
466
+ *
467
+ * const five = 5 as 5;
468
+ * const six = Num.increment(five); // type is 6, value is 6
469
+ *
470
+ * // Type-safe counter
471
+ * type Counter<N extends SmallUint> = {
472
+ * value: N;
473
+ * next(): Counter<Increment<N>>;
474
+ * };
475
+ * ```
476
+ */
477
+ Num.increment = (n) =>
478
+ // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
479
+ (n + 1);
480
+ /**
481
+ * Type-safe decrement operation for positive SmallInt values.
482
+ *
483
+ * Decrements a positive SmallInt (1-40) by 1 with the result type computed
484
+ * at compile time. This provides type-level arithmetic for small positive
485
+ * integers, useful for type-safe countdown operations.
486
+ *
487
+ * @template N - A positive SmallInt literal type (1-40)
488
+ * @param n - The positive SmallInt value to decrement
489
+ * @returns The decremented value with type Decrement<N>
490
+ *
491
+ * @example
492
+ * ```typescript
493
+ * const three = 3 as 3;
494
+ * const two = Num.decrement(three); // type is 2, value is 2
495
+ *
496
+ * const one = 1 as 1;
497
+ * const zero = Num.decrement(one); // type is 0, value is 0
498
+ *
499
+ * // Type-safe countdown
500
+ * function countdown<N extends PositiveSmallInt>(
501
+ * n: N
502
+ * ): N extends 1 ? 0 : Decrement<N> {
503
+ * return Num.decrement(n);
504
+ * }
505
+ * ```
506
+ */
507
+ Num.decrement = (n) =>
508
+ // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
509
+ (n - 1);
510
+ })(Num || (Num = {}));
511
+
512
+ export { Num };
513
+ //# sourceMappingURL=num.mjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"num.mjs","sources":["../../src/number/num.mts"],"sourcesContent":[null],"names":[],"mappings":"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"}