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,597 @@
1
+ import { Result } from '../functional/index.mjs';
2
+ /**
3
+ * A collection of type-safe JSON utility functions that provide safe parsing,
4
+ * stringification, and manipulation of JSON data. All functions return `Result`
5
+ * types to handle errors without throwing exceptions.
6
+ *
7
+ * @example Basic usage
8
+ * ```typescript
9
+ * import { Json, Result } from 'ts-data-forge';
10
+ *
11
+ * // Parse JSON safely
12
+ * const parseResult = Json.parse('{"name": "Alice", "age": 30}');
13
+ * if (Result.isOk(parseResult)) {
14
+ * console.log(parseResult.value); // { name: 'Alice', age: 30 }
15
+ * }
16
+ *
17
+ * // Stringify with error handling
18
+ * const stringifyResult = Json.stringify({ name: 'Bob', age: 25 });
19
+ * if (Result.isOk(stringifyResult)) {
20
+ * console.log(stringifyResult.value); // '{"name":"Bob","age":25}'
21
+ * }
22
+ * ```
23
+ */
24
+ export declare namespace Json {
25
+ /**
26
+ * Safely converts a JSON string into a JavaScript value without throwing exceptions.
27
+ *
28
+ * This function provides type-safe JSON parsing by wrapping the native `JSON.parse`
29
+ * in a `Result` type, allowing you to handle parsing errors gracefully without
30
+ * try-catch blocks.
31
+ *
32
+ * @param text - A valid JSON string to parse. Can contain any valid JSON data type:
33
+ * primitives (string, number, boolean, null), arrays, or objects.
34
+ * @param reviver - Optional function that transforms parsed values. Called for each
35
+ * key-value pair in the JSON. The function receives the key name and parsed value,
36
+ * and should return the transformed value. For nested objects, inner objects are
37
+ * processed before outer objects.
38
+ * @returns A `Result<JsonValue, string>` containing:
39
+ * - On success: `Result.ok(parsedValue)` where `parsedValue` is the parsed JSON
40
+ * - On failure: `Result.err(errorMessage)` where `errorMessage` describes the parsing error
41
+ *
42
+ * @example Basic parsing
43
+ * ```typescript
44
+ * // Parse simple values
45
+ * const str = Json.parse('"hello"');
46
+ * // Result.ok('hello')
47
+ *
48
+ * const num = Json.parse('42');
49
+ * // Result.ok(42)
50
+ *
51
+ * const bool = Json.parse('true');
52
+ * // Result.ok(true)
53
+ *
54
+ * const nul = Json.parse('null');
55
+ * // Result.ok(null)
56
+ * ```
57
+ *
58
+ * @example Parsing objects and arrays
59
+ * ```typescript
60
+ * const obj = Json.parse('{"name": "John", "age": 30, "active": true}');
61
+ * if (Result.isOk(obj)) {
62
+ * console.log(obj.value.name); // 'John'
63
+ * console.log(obj.value.age); // 30
64
+ * }
65
+ *
66
+ * const arr = Json.parse('[1, "two", true, null]');
67
+ * if (Result.isOk(arr)) {
68
+ * console.log(arr.value); // [1, 'two', true, null]
69
+ * }
70
+ * ```
71
+ *
72
+ * @example Error handling
73
+ * ```typescript
74
+ * const invalid = Json.parse('invalid json');
75
+ * if (Result.isErr(invalid)) {
76
+ * console.log('Parse failed:', invalid.value);
77
+ * // Parse failed: Unexpected token i in JSON at position 0
78
+ * }
79
+ *
80
+ * const malformed = Json.parse('{"missing": quote}');
81
+ * if (Result.isErr(malformed)) {
82
+ * console.log('Parse failed:', malformed.value);
83
+ * // Parse failed: Unexpected token q in JSON at position 12
84
+ * }
85
+ * ```
86
+ *
87
+ * @example Using reviver for data transformation
88
+ * ```typescript
89
+ * // Convert ISO date strings to Date objects
90
+ * const dateReviver = (key: string, value: unknown): unknown => {
91
+ * if (typeof value === 'string' && /^\d{4}-\d{2}-\d{2}T/.test(value)) {
92
+ * return new Date(value);
93
+ * }
94
+ * return value;
95
+ * };
96
+ *
97
+ * const result = Json.parse(
98
+ * '{"event": "Meeting", "date": "2023-12-25T10:00:00Z"}',
99
+ * dateReviver
100
+ * );
101
+ * if (Result.isOk(result)) {
102
+ * console.log(result.value.date instanceof Date); // true
103
+ * }
104
+ * ```
105
+ *
106
+ * @example API response validation
107
+ * ```typescript
108
+ * import { isRecord, hasKey } from 'ts-data-forge';
109
+ *
110
+ * const validateApiResponse = (jsonString: string) => {
111
+ * const parseResult = Json.parse(jsonString);
112
+ *
113
+ * if (Result.isErr(parseResult)) {
114
+ * return Result.err(`Invalid JSON: ${parseResult.value}`);
115
+ * }
116
+ *
117
+ * const data = parseResult.value;
118
+ * if (!isRecord(data) || !hasKey(data, 'status')) {
119
+ * return Result.err('Missing required "status" field');
120
+ * }
121
+ *
122
+ * return Result.ok(data);
123
+ * };
124
+ * ```
125
+ */
126
+ const parse: (text: string, reviver?: (this: unknown, key: string, value: JsonValue) => unknown) => Result<JsonValue, string>;
127
+ /**
128
+ * Safely converts a JavaScript value to a JSON string without throwing exceptions.
129
+ *
130
+ * This function provides type-safe JSON stringification by wrapping the native
131
+ * `JSON.stringify` in a `Result` type, allowing you to handle serialization errors
132
+ * gracefully (such as circular references or BigInt values).
133
+ *
134
+ * @param value - The JavaScript value to serialize. Can be any value that JSON.stringify
135
+ * accepts: primitives, objects, arrays. Non-serializable values (functions, undefined,
136
+ * symbols) will be omitted or converted to null according to JSON.stringify behavior.
137
+ * @param replacer - Optional function that transforms values during serialization.
138
+ * Called for each key-value pair. Should return the value to be serialized, or
139
+ * undefined to omit the property from the result.
140
+ * @param space - Optional parameter for formatting the output JSON:
141
+ * - Number (1-10): Number of spaces to indent each level
142
+ * - String: String to use for indentation (first 10 characters)
143
+ * - undefined/null: No formatting (compact output)
144
+ * @returns A `Result<string, string>` containing:
145
+ * - On success: `Result.ok(jsonString)` where `jsonString` is the serialized JSON
146
+ * - On failure: `Result.err(errorMessage)` where `errorMessage` describes the error
147
+ *
148
+ * @example Basic stringification
149
+ * ```typescript
150
+ * // Primitives
151
+ * const str = Json.stringify('hello');
152
+ * // Result.ok('"hello"')
153
+ *
154
+ * const num = Json.stringify(42);
155
+ * // Result.ok('42')
156
+ *
157
+ * const bool = Json.stringify(true);
158
+ * // Result.ok('true')
159
+ *
160
+ * const nul = Json.stringify(null);
161
+ * // Result.ok('null')
162
+ * ```
163
+ *
164
+ * @example Objects and arrays
165
+ * ```typescript
166
+ * const obj = { name: 'John', age: 30, active: true };
167
+ * const result = Json.stringify(obj);
168
+ * if (Result.isOk(result)) {
169
+ * console.log(result.value); // '{"name":"John","age":30,"active":true}'
170
+ * }
171
+ *
172
+ * const arr = [1, 'two', true, null];
173
+ * const arrResult = Json.stringify(arr);
174
+ * if (Result.isOk(arrResult)) {
175
+ * console.log(arrResult.value); // '[1,"two",true,null]'
176
+ * }
177
+ * ```
178
+ *
179
+ * @example Formatted output
180
+ * ```typescript
181
+ * const data = { users: [{ name: 'Alice', id: 1 }, { name: 'Bob', id: 2 }] };
182
+ *
183
+ * // Pretty-print with 2 spaces
184
+ * const formatted = Json.stringify(data, undefined, 2);
185
+ * if (Result.isOk(formatted)) {
186
+ * console.log(formatted.value);
187
+ * // {
188
+ * // "users": [
189
+ * // {
190
+ * // "name": "Alice",
191
+ * // "id": 1
192
+ * // },
193
+ * // {
194
+ * // "name": "Bob",
195
+ * // "id": 2
196
+ * // }
197
+ * // ]
198
+ * // }
199
+ * }
200
+ *
201
+ * // Custom indentation string
202
+ * const tabbed = Json.stringify(data, undefined, '\t');
203
+ * ```
204
+ *
205
+ * @example Error handling for problematic values
206
+ * ```typescript
207
+ * // Circular reference error
208
+ * const circular: any = { name: 'test' };
209
+ * circular.self = circular;
210
+ * const error = Json.stringify(circular);
211
+ * if (Result.isErr(error)) {
212
+ * console.log('Stringify failed:', error.value);
213
+ * // Stringify failed: Converting circular structure to JSON
214
+ * }
215
+ *
216
+ * // BigInt error
217
+ * const bigIntError = Json.stringify({ big: BigInt(123) });
218
+ * if (Result.isErr(bigIntError)) {
219
+ * console.log('Stringify failed:', bigIntError.value);
220
+ * // Stringify failed: Do not know how to serialize a BigInt
221
+ * }
222
+ * ```
223
+ *
224
+ * @example Using replacer for value transformation
225
+ * ```typescript
226
+ * // Filter out sensitive data
227
+ * const sensitiveData = { name: 'John', password: 'secret123', email: 'john@example.com' };
228
+ *
229
+ * const secureReplacer = (key: string, value: unknown) => {
230
+ * if (key === 'password') return '[REDACTED]';
231
+ * return value;
232
+ * };
233
+ *
234
+ * const safe = Json.stringify(sensitiveData, secureReplacer);
235
+ * if (Result.isOk(safe)) {
236
+ * console.log(safe.value);
237
+ * // '{"name":"John","password":"[REDACTED]","email":"john@example.com"}'
238
+ * }
239
+ *
240
+ * // Convert Dates to custom format
241
+ * const data = { event: 'Meeting', date: new Date('2023-12-25T10:00:00Z') };
242
+ * const dateReplacer = (key: string, value: unknown) => {
243
+ * if (value instanceof Date) return value.toISOString().split('T')[0]; // YYYY-MM-DD
244
+ * return value;
245
+ * };
246
+ *
247
+ * const result = Json.stringify(data, dateReplacer);
248
+ * if (Result.isOk(result)) {
249
+ * console.log(result.value); // '{"event":"Meeting","date":"2023-12-25"}'
250
+ * }
251
+ * ```
252
+ *
253
+ * @example Special value handling
254
+ * ```typescript
255
+ * // Functions, undefined, and symbols are omitted in objects
256
+ * const obj = {
257
+ * name: 'test',
258
+ * fn: () => {}, // omitted
259
+ * undef: undefined, // omitted
260
+ * sym: Symbol('test'), // omitted
261
+ * num: 42
262
+ * };
263
+ * const result = Json.stringify(obj);
264
+ * // Result.ok('{"name":"test","num":42}')
265
+ *
266
+ * // In arrays, they become null
267
+ * const arr = ['string', () => {}, undefined, Symbol('test'), 42];
268
+ * const arrResult = Json.stringify(arr);
269
+ * // Result.ok('["string",null,null,null,42]')
270
+ * ```
271
+ */
272
+ const stringify: (value: unknown, replacer?: (this: unknown, key: string, val: unknown) => unknown, space?: UintRangeInclusive<1, 10> | string) => Result<string, string>;
273
+ /**
274
+ * Safely converts a JavaScript value to a JSON string, including only the specified properties.
275
+ *
276
+ * This function provides selective serialization by allowing you to specify exactly which
277
+ * object properties should be included in the resulting JSON. It's useful for creating
278
+ * filtered or minimal representations of objects, such as for API responses or logging.
279
+ *
280
+ * @param value - The JavaScript value to serialize. While any value is accepted,
281
+ * the property filtering only applies to objects and nested objects.
282
+ * @param propertiesToBeSelected - Optional array of property names (strings) and array
283
+ * indices (numbers) to include in the serialization. If provided, only these properties
284
+ * will appear in the output JSON. If undefined, all properties are included.
285
+ * @param space - Optional formatting parameter:
286
+ * - Number (1-10): Number of spaces to indent each level
287
+ * - String: String to use for indentation (first 10 characters)
288
+ * - undefined/null: No formatting (compact output)
289
+ * @returns A `Result<string, string>` containing:
290
+ * - On success: `Result.ok(jsonString)` with only selected properties
291
+ * - On failure: `Result.err(errorMessage)` describing the serialization error
292
+ *
293
+ * @example Basic property selection
294
+ * ```typescript
295
+ * const user = {
296
+ * id: 1,
297
+ * name: 'Alice',
298
+ * email: 'alice@example.com',
299
+ * password: 'secret123',
300
+ * lastLogin: '2023-12-01'
301
+ * };
302
+ *
303
+ * // Include only public fields
304
+ * const publicFields = Json.stringifySelected(user, ['id', 'name', 'email']);
305
+ * if (Result.isOk(publicFields)) {
306
+ * console.log(publicFields.value);
307
+ * // '{"id":1,"name":"Alice","email":"alice@example.com"}'
308
+ * }
309
+ * ```
310
+ *
311
+ * @example Array property selection
312
+ * ```typescript
313
+ * const data = {
314
+ * users: [
315
+ * { id: 1, name: 'Alice', secret: 'hidden1' },
316
+ * { id: 2, name: 'Bob', secret: 'hidden2' }
317
+ * ],
318
+ * metadata: { total: 2, page: 1 }
319
+ * };
320
+ *
321
+ * // Select specific properties across nested structures
322
+ * const selected = Json.stringifySelected(data, ['users', 'id', 'name', 'total']);
323
+ * if (Result.isOk(selected)) {
324
+ * console.log(selected.value);
325
+ * // '{"users":[{"id":1,"name":"Alice"},{"id":2,"name":"Bob"}],"metadata":{"total":2}}'
326
+ * }
327
+ * ```
328
+ *
329
+ * @example Formatted output with selection
330
+ * ```typescript
331
+ * const config = {
332
+ * database: { host: 'localhost', password: 'secret' },
333
+ * api: { endpoint: '/api/v1', key: 'secret-key' },
334
+ * features: { debug: true, logging: true }
335
+ * };
336
+ *
337
+ * // Create a safe config for logging (exclude sensitive fields)
338
+ * const safeConfig = Json.stringifySelected(
339
+ * config,
340
+ * ['database', 'host', 'api', 'endpoint', 'features'],
341
+ * 2
342
+ * );
343
+ * if (Result.isOk(safeConfig)) {
344
+ * console.log(safeConfig.value);
345
+ * // {
346
+ * // "database": {
347
+ * // "host": "localhost"
348
+ * // },
349
+ * // "api": {
350
+ * // "endpoint": "/api/v1"
351
+ * // },
352
+ * // "features": {
353
+ * // "debug": true,
354
+ * // "logging": true
355
+ * // }
356
+ * // }
357
+ * }
358
+ * ```
359
+ *
360
+ * @example Working with arrays and indices
361
+ * ```typescript
362
+ * const matrix = [
363
+ * [1, 2, 3, 4],
364
+ * [5, 6, 7, 8],
365
+ * [9, 10, 11, 12]
366
+ * ];
367
+ *
368
+ * // Select only first two columns (indices 0 and 1)
369
+ * const columns = Json.stringifySelected(matrix, [0, 1]);
370
+ * if (Result.isOk(columns)) {
371
+ * console.log(columns.value);
372
+ * // '[[1,2],[5,6],[9,10]]'
373
+ * }
374
+ * ```
375
+ *
376
+ * @example API response filtering
377
+ * ```typescript
378
+ * // Simulate filtering an API response
379
+ * const fullResponse = {
380
+ * data: {
381
+ * users: [
382
+ * { id: 1, name: 'Alice', email: 'alice@example.com', internalId: 'usr_123' },
383
+ * { id: 2, name: 'Bob', email: 'bob@example.com', internalId: 'usr_456' }
384
+ * ]
385
+ * },
386
+ * metadata: {
387
+ * total: 2,
388
+ * internalVersion: '1.2.3',
389
+ * serverTime: Date.now()
390
+ * }
391
+ * };
392
+ *
393
+ * // Create public API response
394
+ * const publicResponse = Json.stringifySelected(
395
+ * fullResponse,
396
+ * ['data', 'users', 'id', 'name', 'email', 'metadata', 'total']
397
+ * );
398
+ *
399
+ * if (Result.isOk(publicResponse)) {
400
+ * console.log('Public API response:', publicResponse.value);
401
+ * // Only includes id, name, email for users and total in metadata
402
+ * }
403
+ * ```
404
+ *
405
+ * @example Error handling
406
+ * ```typescript
407
+ * const circular: any = { name: 'test' };
408
+ * circular.self = circular;
409
+ *
410
+ * const result = Json.stringifySelected(circular, ['name', 'self']);
411
+ * if (Result.isErr(result)) {
412
+ * console.log('Serialization failed:', result.value);
413
+ * // Even with property selection, circular references still cause errors
414
+ * }
415
+ * ```
416
+ */
417
+ const stringifySelected: (value: unknown, propertiesToBeSelected?: readonly (number | string)[], space?: UintRangeInclusive<1, 10> | string) => Result<string, string>;
418
+ /**
419
+ * Safely converts a JavaScript record to a JSON string with keys sorted alphabetically at all levels.
420
+ *
421
+ * This function creates deterministic JSON output by ensuring that object keys appear in
422
+ * alphabetical order at every level of nesting. This is particularly useful for creating
423
+ * consistent output for comparison, hashing, caching, or when you need reproducible JSON
424
+ * representations across different JavaScript engines or runs.
425
+ *
426
+ * @param value - An object (`UnknownRecord`) to serialize. Must be a plain object
427
+ * (not an array, primitive, or null). Nested objects and arrays within the object
428
+ * will also have their keys sorted alphabetically.
429
+ * @param space - Optional formatting parameter:
430
+ * - Number (1-10): Number of spaces to indent each level
431
+ * - String: String to use for indentation (first 10 characters)
432
+ * - undefined/null: No formatting (compact output)
433
+ * @returns A `Result<string, string>` containing:
434
+ * - On success: `Result.ok(jsonString)` with all object keys sorted alphabetically
435
+ * - On failure: `Result.err(errorMessage)` describing the serialization error
436
+ *
437
+ * @example Basic key sorting
438
+ * ```typescript
439
+ * const unsortedObj = {
440
+ * zebra: 'animal',
441
+ * apple: 'fruit',
442
+ * banana: 'fruit',
443
+ * aardvark: 'animal'
444
+ * };
445
+ *
446
+ * const sorted = Json.stringifySortedKey(unsortedObj);
447
+ * if (Result.isOk(sorted)) {
448
+ * console.log(sorted.value);
449
+ * // '{"aardvark":"animal","apple":"fruit","banana":"fruit","zebra":"animal"}'
450
+ * }
451
+ *
452
+ * // Compare with regular stringify (order not guaranteed)
453
+ * const regular = Json.stringify(unsortedObj);
454
+ * // Keys might appear in insertion order or engine-dependent order
455
+ * ```
456
+ *
457
+ * @example Nested object key sorting
458
+ * ```typescript
459
+ * const nestedObj = {
460
+ * user: {
461
+ * name: 'Alice',
462
+ * age: 30,
463
+ * address: {
464
+ * zip: '12345',
465
+ * city: 'New York',
466
+ * country: 'USA'
467
+ * }
468
+ * },
469
+ * settings: {
470
+ * theme: 'dark',
471
+ * language: 'en',
472
+ * notifications: {
473
+ * email: true,
474
+ * sms: false,
475
+ * push: true
476
+ * }
477
+ * }
478
+ * };
479
+ *
480
+ * const sorted = Json.stringifySortedKey(nestedObj, 2);
481
+ * if (Result.isOk(sorted)) {
482
+ * console.log(sorted.value);
483
+ * // {
484
+ * // "settings": {
485
+ * // "language": "en",
486
+ * // "notifications": {
487
+ * // "email": true,
488
+ * // "push": true,
489
+ * // "sms": false
490
+ * // },
491
+ * // "theme": "dark"
492
+ * // },
493
+ * // "user": {
494
+ * // "address": {
495
+ * // "city": "New York",
496
+ * // "country": "USA",
497
+ * // "zip": "12345"
498
+ * // },
499
+ * // "age": 30,
500
+ * // "name": "Alice"
501
+ * // }
502
+ * // }
503
+ * }
504
+ * ```
505
+ *
506
+ * @example Arrays with nested objects
507
+ * ```typescript
508
+ * const dataWithArrays = {
509
+ * users: [
510
+ * { name: 'Bob', id: 2, active: true },
511
+ * { name: 'Alice', id: 1, active: false }
512
+ * ],
513
+ * metadata: {
514
+ * version: '1.0',
515
+ * created: '2023-12-01',
516
+ * author: 'system'
517
+ * }
518
+ * };
519
+ *
520
+ * const sorted = Json.stringifySortedKey(dataWithArrays);
521
+ * if (Result.isOk(sorted)) {
522
+ * console.log(sorted.value);
523
+ * // Keys in objects within arrays are also sorted:
524
+ * // '{"metadata":{"author":"system","created":"2023-12-01","version":"1.0"},"users":[{"active":true,"id":2,"name":"Bob"},{"active":false,"id":1,"name":"Alice"}]}'
525
+ * }
526
+ * ```
527
+ *
528
+ * @example Configuration files and consistent output
529
+ * ```typescript
530
+ * // Useful for configuration files that need consistent ordering
531
+ * const config = {
532
+ * database: {
533
+ * port: 5432,
534
+ * host: 'localhost',
535
+ * name: 'myapp',
536
+ * username: 'admin'
537
+ * },
538
+ * server: {
539
+ * port: 3000,
540
+ * middleware: ['cors', 'helmet', 'compression'],
541
+ * routes: {
542
+ * api: '/api/v1',
543
+ * health: '/health',
544
+ * docs: '/docs'
545
+ * }
546
+ * }
547
+ * };
548
+ *
549
+ * const consistentConfig = Json.stringifySortedKey(config, 2);
550
+ * if (Result.isOk(consistentConfig)) {
551
+ * // Always produces the same key order regardless of object creation order
552
+ * console.log('Consistent config:', consistentConfig.value);
553
+ * }
554
+ * ```
555
+ *
556
+ * @example Deterministic hashing and comparison
557
+ * ```typescript
558
+ * // Useful when you need consistent JSON for hashing or comparison
559
+ * const createHash = async (obj: Record<string, unknown>) => {
560
+ * const sortedJson = Json.stringifySortedKey(obj);
561
+ * if (Result.isErr(sortedJson)) {
562
+ * throw new Error(`Failed to serialize: ${sortedJson.value}`);
563
+ * }
564
+ *
565
+ * // Now you can safely hash the JSON string
566
+ * const encoder = new TextEncoder();
567
+ * const data = encoder.encode(sortedJson.value);
568
+ * const hashBuffer = await crypto.subtle.digest('SHA-256', data);
569
+ * return Array.from(new Uint8Array(hashBuffer))
570
+ * .map(b => b.toString(16).padStart(2, '0'))
571
+ * .join('');
572
+ * };
573
+ *
574
+ * // These will produce the same hash regardless of property order:
575
+ * const obj1 = { b: 2, a: 1, c: 3 };
576
+ * const obj2 = { a: 1, c: 3, b: 2 };
577
+ * // createHash(obj1) === createHash(obj2) // true
578
+ * ```
579
+ *
580
+ * @example Error handling
581
+ * ```typescript
582
+ * const problematicObj = {
583
+ * normal: 'value',
584
+ * circular: {} as any
585
+ * };
586
+ * problematicObj.circular.self = problematicObj;
587
+ *
588
+ * const result = Json.stringifySortedKey(problematicObj);
589
+ * if (Result.isErr(result)) {
590
+ * console.log('Serialization failed:', result.value);
591
+ * // Even with key sorting, circular references still cause errors
592
+ * }
593
+ * ```
594
+ */
595
+ const stringifySortedKey: (value: UnknownRecord, space?: UintRangeInclusive<1, 10> | string) => Result<string, string>;
596
+ }
597
+ //# sourceMappingURL=json.d.mts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"json.d.mts","sourceRoot":"","sources":["../../src/json/json.mts"],"names":[],"mappings":"AACA,OAAO,EAAQ,MAAM,EAAE,MAAM,yBAAyB,CAAC;AAKvD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,yBAAiB,IAAI,CAAC;IACpB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAoGG;IACI,MAAM,KAAK,GAChB,MAAM,MAAM,EACZ,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,KAAK,OAAO,KAClE,MAAM,CAAC,SAAS,EAAE,MAAM,CAe1B,CAAC;IAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgJG;IACI,MAAM,SAAS,GACpB,OAAO,OAAO,EACd,WAAW,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,KAAK,OAAO,EAChE,QAAQ,kBAAkB,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,MAAM,KACzC,MAAM,CAAC,MAAM,EAAE,MAAM,CASvB,CAAC;IAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+IG;IACI,MAAM,iBAAiB,GAC5B,OAAO,OAAO,EACd,yBAAyB,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,EACrD,QAAQ,kBAAkB,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,MAAM,KACzC,MAAM,CAAC,MAAM,EAAE,MAAM,CAWvB,CAAC;IAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgLG;IACI,MAAM,kBAAkB,GAC7B,OAAO,aAAa,EACpB,QAAQ,kBAAkB,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,MAAM,KACzC,MAAM,CAAC,MAAM,EAAE,MAAM,CAMvB,CAAC;CACH"}