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