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,426 @@
1
+ /**
2
+ * Interface for an immutable set with O(1) lookup performance and set operation support.
3
+ *
4
+ * This interface defines all methods and properties available on ISet instances. All operations
5
+ * that modify the set return new ISet instances, preserving immutability. The underlying implementation
6
+ * uses JavaScript's native Set for O(1) average-case performance on add, has, and delete operations.
7
+ *
8
+ * **Immutability Guarantees:**
9
+ * - All mutation operations (add, delete) return new ISet instances
10
+ * - Original ISet instances are never modified
11
+ * - Safe for concurrent access and functional programming patterns
12
+ *
13
+ * **Performance Characteristics:**
14
+ * - has/add/delete: O(1) average case
15
+ * - Set operations (union, intersection, difference): O(n)
16
+ * - map/filter operations: O(n)
17
+ * - Iteration: O(n)
18
+ *
19
+ * @template K The type of the elements in the set. Must extend MapSetKeyType (string, number, boolean, etc.)
20
+ */
21
+ type ISetInterface<K extends MapSetKeyType> = Readonly<{
22
+ /** The number of elements in the set. */
23
+ size: SizeType.Arr;
24
+ /** Checks if the set is empty. */
25
+ isEmpty: boolean;
26
+ /**
27
+ * Checks if an element exists in the set.
28
+ * Allows for wider literal types for keys during checking.
29
+ * @param key The element to check.
30
+ * @returns `true` if the element exists, `false` otherwise.
31
+ */
32
+ has: (key: K | (WidenLiteral<K> & {})) => boolean;
33
+ /**
34
+ * Checks if all elements in the set satisfy a predicate.
35
+ * @param predicate A function to test each element.
36
+ * @returns `true` if all elements satisfy the predicate, `false` otherwise.
37
+ */
38
+ every: ((predicate: (key: K) => boolean) => boolean) &
39
+ /**
40
+ * Checks if all elements in the set satisfy a type predicate.
41
+ * Narrows the type of elements in the set if the predicate returns true for all elements.
42
+ * @template L The narrowed type of the elements.
43
+ * @param predicate A type predicate function.
44
+ * @returns `true` if all elements satisfy the predicate, `false` otherwise.
45
+ */
46
+ (<L extends K>(predicate: (key: K) => key is L) => this is ISet<L>);
47
+ /**
48
+ * Checks if at least one element in the set satisfies a predicate.
49
+ * @param predicate A function to test each element.
50
+ * @returns `true` if at least one element satisfies the predicate, `false` otherwise.
51
+ */
52
+ some: (predicate: (key: K) => boolean) => boolean;
53
+ /**
54
+ * Adds an element to the set.
55
+ * @param key The element to add.
56
+ * @returns A new ISet instance with the element added.
57
+ */
58
+ add: (key: K) => ISet<K>;
59
+ /**
60
+ * Deletes an element from the set.
61
+ * @param key The element to delete.
62
+ * @returns A new ISet instance without the specified element.
63
+ */
64
+ delete: (key: K) => ISet<K>;
65
+ /**
66
+ * Applies a series of mutations to the set.
67
+ * @param actions An array of mutation actions (add or delete).
68
+ * @returns A new ISet instance with all mutations applied.
69
+ */
70
+ withMutations: (actions: readonly Readonly<{
71
+ type: 'add';
72
+ key: K;
73
+ } | {
74
+ type: 'delete';
75
+ key: K;
76
+ }>[]) => ISet<K>;
77
+ /**
78
+ * Maps the elements of the set to new elements.
79
+ * @template K2 The type of the new elements.
80
+ * @param mapFn A function that maps an element to a new element.
81
+ * @returns A new ISet instance with mapped elements.
82
+ */
83
+ map: <K2 extends MapSetKeyType>(mapFn: (key: K) => K2) => ISet<K2>;
84
+ /**
85
+ * Filters the elements of the set based on a type predicate.
86
+ * Narrows the type of elements in the resulting set.
87
+ * @template K2 The narrowed type of the elements.
88
+ * @param predicate A type predicate function.
89
+ * @returns A new ISet instance with elements that satisfy the type predicate.
90
+ */
91
+ filter: (<K2 extends K>(predicate: (key: K) => key is K2) => ISet<K2>) &
92
+ /**
93
+ * Filters the elements of the set based on a predicate.
94
+ * @param predicate A function to test each element.
95
+ * @returns A new ISet instance with elements that satisfy the predicate.
96
+ */
97
+ ((predicate: (key: K) => boolean) => ISet<K>);
98
+ /**
99
+ * Filters the elements of the set by excluding elements for which the predicate returns true.
100
+ * @param predicate A function to test each element.
101
+ * @returns A new ISet instance with elements for which the predicate returned `false`.
102
+ */
103
+ filterNot: (predicate: (key: K) => boolean) => ISet<K>;
104
+ /**
105
+ * Checks if this set is a subset of another set.
106
+ * @param set The other set.
107
+ * @returns `true` if this set is a subset of the other set, `false` otherwise.
108
+ */
109
+ isSubsetOf: (set: ISet<WidenLiteral<K>>) => boolean;
110
+ /**
111
+ * Checks if this set is a superset of another set.
112
+ * @param set The other set.
113
+ * @returns `true` if this set is a superset of the other set, `false` otherwise.
114
+ */
115
+ isSupersetOf: (set: ISet<WidenLiteral<K>>) => boolean;
116
+ /**
117
+ * Returns a new set with elements that are in this set but not in another set.
118
+ * @param set The other set.
119
+ * @returns A new ISet instance representing the set difference.
120
+ */
121
+ subtract: (set: ISet<K>) => ISet<K>;
122
+ /**
123
+ * Returns a new set with elements that are common to both this set and another set.
124
+ * @param set The other set.
125
+ * @returns A new ISet instance representing the set intersection.
126
+ */
127
+ intersect: (set: ISet<K>) => ISet<K>;
128
+ /**
129
+ * Returns a new set with all elements from both this set and another set.
130
+ * @template K2 The type of elements in the other set.
131
+ * @param set The other set.
132
+ * @returns A new ISet instance representing the set union.
133
+ */
134
+ union: <K2 extends MapSetKeyType>(set: ISet<K2>) => ISet<K | K2>;
135
+ /**
136
+ * Executes a callback function for each element in the set.
137
+ * @param callbackfn A function to execute for each element.
138
+ */
139
+ forEach: (callbackfn: (key: K) => void) => void;
140
+ /**
141
+ * Returns an iterator for the elements in the set (alias for values).
142
+ * @returns An iterable iterator of elements.
143
+ */
144
+ keys: () => IterableIterator<K>;
145
+ /**
146
+ * Returns an iterator for the elements in the set.
147
+ * @returns An iterable iterator of elements.
148
+ */
149
+ values: () => IterableIterator<K>;
150
+ /**
151
+ * Returns an iterator for the entries (element-element pairs) in the set.
152
+ * @returns An iterable iterator of entries.
153
+ */
154
+ entries: () => IterableIterator<readonly [K, K]>;
155
+ /**
156
+ * Converts the elements of the set to an array.
157
+ * @returns A readonly array of elements.
158
+ */
159
+ toArray: () => readonly K[];
160
+ /**
161
+ * Returns the underlying readonly JavaScript Set.
162
+ * @returns The raw ReadonlySet instance.
163
+ */
164
+ toRawSet: () => ReadonlySet<K>;
165
+ }>;
166
+ /**
167
+ * Represents an immutable set with high-performance operations and comprehensive set algebra support.
168
+ *
169
+ * ISet is a persistent data structure that provides all the functionality of JavaScript's Set
170
+ * while maintaining immutability. All operations that would normally mutate the set instead
171
+ * return new ISet instances, making it safe for functional programming and concurrent access.
172
+ *
173
+ * **Key Features:**
174
+ * - **Immutable**: All mutation operations return new instances
175
+ * - **High Performance**: O(1) average-case for has/add/delete operations
176
+ * - **Set Operations**: Full support for union, intersection, difference, subset/superset checks
177
+ * - **Type Safe**: Full TypeScript support with generic element types
178
+ * - **Iterable**: Implements standard JavaScript iteration protocols
179
+ * - **Functional**: Rich API for map, filter, and functional composition
180
+ *
181
+ * **When to Use:**
182
+ * - Managing collections of unique values with immutability guarantees
183
+ * - Set algebra operations (unions, intersections, differences)
184
+ * - Membership testing with O(1) performance
185
+ * - Functional programming patterns requiring immutable collections
186
+ *
187
+ * @template K The type of the elements in the set. Must extend MapSetKeyType.
188
+ */
189
+ export type ISet<K extends MapSetKeyType> = Iterable<K> & ISetInterface<K>;
190
+ /**
191
+ * Provides utility functions for ISet.
192
+ */
193
+ export declare namespace ISet {
194
+ /**
195
+ * Creates a new ISet instance from an iterable of elements.
196
+ *
197
+ * This factory function accepts any iterable of elements, including arrays,
198
+ * JavaScript Sets, other ISets, or custom iterables. Duplicate elements in the
199
+ * input iterable will be automatically deduplicated in the resulting set.
200
+ *
201
+ * **Performance:** O(n) where n is the number of elements in the iterable.
202
+ *
203
+ * @template K The type of the elements. Must extend MapSetKeyType.
204
+ * @param iterable An iterable of elements (e.g., Array, Set, ISet, etc.)
205
+ * @returns A new ISet instance containing all unique elements from the iterable.
206
+ *
207
+ * @example
208
+ * ```typescript
209
+ * // From array (duplicates automatically removed)
210
+ * const uniqueIds = ISet.create([1, 2, 3, 2, 1]); // Contains: 1, 2, 3
211
+ * console.log(uniqueIds.size); // Output: 3
212
+ *
213
+ * // From JavaScript Set
214
+ * const jsSet = new Set(["red", "green", "blue"]);
215
+ * const colors = ISet.create(jsSet);
216
+ * console.log(colors.has("red")); // Output: true
217
+ *
218
+ * // From another ISet (creates a copy)
219
+ * const originalTags = ISet.create(["typescript", "immutable"]);
220
+ * const copiedTags = ISet.create(originalTags);
221
+ * console.log(copiedTags.size); // Output: 2
222
+ *
223
+ * // Empty set
224
+ * const emptyPermissions = ISet.create<string>([]);
225
+ * console.log(emptyPermissions.isEmpty); // Output: true
226
+ *
227
+ * // Fluent operations
228
+ * const processedNumbers = ISet.create([1, 2, 3, 4, 5])
229
+ * .filter(x => x % 2 === 0) // Keep even numbers: 2, 4
230
+ * .add(6) // Add 6: 2, 4, 6
231
+ * .delete(2); // Remove 2: 4, 6
232
+ * console.log(processedNumbers.toArray().sort()); // Output: [4, 6]
233
+ *
234
+ * // From generator function
235
+ * function* generatePrimes(): Generator<number> {
236
+ * yield 2; yield 3; yield 5; yield 7;
237
+ * }
238
+ * const primes = ISet.create(generatePrimes());
239
+ * console.log(primes.size); // Output: 4
240
+ * ```
241
+ */
242
+ const create: <K extends MapSetKeyType>(iterable: Iterable<K>) => ISet<K>;
243
+ /**
244
+ * Checks if two ISet instances are structurally equal.
245
+ *
246
+ * Two ISets are considered equal if they have the same size and contain exactly the same
247
+ * elements. The order of elements does not matter for equality comparison since sets are
248
+ * unordered collections. Elements are compared using JavaScript's `===` operator.
249
+ *
250
+ * **Performance:** O(n) where n is the size of the smaller set.
251
+ *
252
+ * @template K The type of the elements.
253
+ * @param a The first ISet instance to compare.
254
+ * @param b The second ISet instance to compare.
255
+ * @returns `true` if the sets contain exactly the same elements, `false` otherwise.
256
+ *
257
+ * @example
258
+ * ```typescript
259
+ * // Basic equality comparison
260
+ * const permissions1 = ISet.create(["read", "write", "execute"]);
261
+ * const permissions2 = ISet.create(["execute", "read", "write"]); // Order doesn't matter
262
+ * const permissions3 = ISet.create(["read", "write"]);
263
+ *
264
+ * console.log(ISet.equal(permissions1, permissions2)); // true
265
+ * console.log(ISet.equal(permissions1, permissions3)); // false (different sizes)
266
+ *
267
+ * // With different element types
268
+ * const numbers1 = ISet.create([1, 2, 3]);
269
+ * const numbers2 = ISet.create([3, 1, 2]);
270
+ * const numbers3 = ISet.create([1, 2, 4]); // Different element
271
+ *
272
+ * console.log(ISet.equal(numbers1, numbers2)); // true
273
+ * console.log(ISet.equal(numbers1, numbers3)); // false
274
+ *
275
+ * // Empty sets
276
+ * const empty1 = ISet.create<string>([]);
277
+ * const empty2 = ISet.create<string>([]);
278
+ * console.log(ISet.equal(empty1, empty2)); // true
279
+ *
280
+ * // Single element sets
281
+ * const single1 = ISet.create(["unique"]);
282
+ * const single2 = ISet.create(["unique"]);
283
+ * const single3 = ISet.create(["different"]);
284
+ *
285
+ * console.log(ISet.equal(single1, single2)); // true
286
+ * console.log(ISet.equal(single1, single3)); // false
287
+ * ```
288
+ */
289
+ const equal: <K extends MapSetKeyType>(a: ISet<K>, b: ISet<K>) => boolean;
290
+ /**
291
+ * Computes the difference between two ISet instances, identifying added and deleted elements.
292
+ *
293
+ * This function performs a set difference operation to determine what elements were added
294
+ * and what elements were deleted when transitioning from the old set to the new set.
295
+ * This is useful for change detection, state management, and synchronization scenarios.
296
+ *
297
+ * **Performance:** O(n + m) where n and m are the sizes of the old and new sets respectively.
298
+ *
299
+ * @template K The type of the elements.
300
+ * @param oldSet The original set representing the previous state.
301
+ * @param newSet The new set representing the current state.
302
+ * @returns An object with `added` and `deleted` properties, each containing an ISet
303
+ * of elements that were added or removed respectively.
304
+ *
305
+ * @example
306
+ * ```typescript
307
+ * // User permission changes
308
+ * const oldPermissions = ISet.create(["read", "write", "delete"]);
309
+ * const newPermissions = ISet.create(["read", "write", "execute", "admin"]);
310
+ *
311
+ * const permissionDiff = ISet.diff(oldPermissions, newPermissions);
312
+ *
313
+ * console.log("Permissions removed:", permissionDiff.deleted.toArray());
314
+ * // Output: ["delete"]
315
+ *
316
+ * console.log("Permissions added:", permissionDiff.added.toArray());
317
+ * // Output: ["execute", "admin"]
318
+ *
319
+ * // No changes
320
+ * const unchanged1 = ISet.create(["a", "b", "c"]);
321
+ * const unchanged2 = ISet.create(["a", "b", "c"]);
322
+ * const noDiff = ISet.diff(unchanged1, unchanged2);
323
+ *
324
+ * console.log(noDiff.added.isEmpty); // true
325
+ * console.log(noDiff.deleted.isEmpty); // true
326
+ *
327
+ * // Complete replacement
328
+ * const oldTags = ISet.create(["javascript", "react"]);
329
+ * const newTags = ISet.create(["typescript", "vue"]);
330
+ * const tagDiff = ISet.diff(oldTags, newTags);
331
+ *
332
+ * console.log(tagDiff.deleted.toArray()); // ["javascript", "react"]
333
+ * console.log(tagDiff.added.toArray()); // ["typescript", "vue"]
334
+ * ```
335
+ */
336
+ const diff: <K extends MapSetKeyType>(oldSet: ISet<K>, newSet: ISet<K>) => ReadonlyRecord<"added" | "deleted", ISet<K>>;
337
+ /**
338
+ * Computes the intersection of two ISet instances.
339
+ *
340
+ * Returns a new set containing only the elements that are present in both input sets.
341
+ * This operation is commutative: `intersection(a, b) === intersection(b, a)`.
342
+ *
343
+ * **Performance:** O(min(n, m)) where n and m are the sizes of the input sets.
344
+ *
345
+ * @template K The type of the elements.
346
+ * @param a The first set.
347
+ * @param b The second set.
348
+ * @returns A new ISet instance containing elements common to both sets.
349
+ *
350
+ * @example
351
+ * ```typescript
352
+ * // Finding common permissions between user and role
353
+ * const userPermissions = ISet.create(["read", "write", "delete", "admin"]);
354
+ * const rolePermissions = ISet.create(["read", "write", "execute"]);
355
+ *
356
+ * const commonPermissions = ISet.intersection(userPermissions, rolePermissions);
357
+ * console.log(commonPermissions.toArray()); // ["read", "write"]
358
+ *
359
+ * // No common elements
360
+ * const setA = ISet.create([1, 2, 3]);
361
+ * const setB = ISet.create([4, 5, 6]);
362
+ * const noCommon = ISet.intersection(setA, setB);
363
+ * console.log(noCommon.isEmpty); // true
364
+ *
365
+ * // Complete overlap
366
+ * const identical1 = ISet.create(["a", "b", "c"]);
367
+ * const identical2 = ISet.create(["a", "b", "c"]);
368
+ * const completeOverlap = ISet.intersection(identical1, identical2);
369
+ * console.log(ISet.equal(completeOverlap, identical1)); // true
370
+ *
371
+ * // Intersection with empty set
372
+ * const nonEmpty = ISet.create([1, 2, 3]);
373
+ * const empty = ISet.create<number>([]);
374
+ * const withEmpty = ISet.intersection(nonEmpty, empty);
375
+ * console.log(withEmpty.isEmpty); // true
376
+ * ```
377
+ */
378
+ const intersection: <K extends MapSetKeyType>(a: ISet<K>, b: ISet<K>) => ISet<K>;
379
+ /**
380
+ * Computes the union of two ISet instances.
381
+ *
382
+ * Returns a new set containing all elements that are present in either input set.
383
+ * Duplicate elements are automatically handled since sets only contain unique values.
384
+ * This operation is commutative: `union(a, b) === union(b, a)`.
385
+ *
386
+ * **Performance:** O(n + m) where n and m are the sizes of the input sets.
387
+ *
388
+ * @template K1 The type of elements in the first set.
389
+ * @template K2 The type of elements in the second set.
390
+ * @param a The first set.
391
+ * @param b The second set.
392
+ * @returns A new ISet instance containing all elements from both sets.
393
+ *
394
+ * @example
395
+ * ```typescript
396
+ * // Combining permissions from multiple sources
397
+ * const userPermissions = ISet.create(["read", "write"]);
398
+ * const rolePermissions = ISet.create(["write", "execute", "admin"]);
399
+ *
400
+ * const allPermissions = ISet.union(userPermissions, rolePermissions);
401
+ * console.log(allPermissions.toArray().sort());
402
+ * // Output: ["admin", "execute", "read", "write"]
403
+ *
404
+ * // Union with different types (type widening)
405
+ * const numbers = ISet.create([1, 2, 3]);
406
+ * const strings = ISet.create(["a", "b"]);
407
+ * const mixed = ISet.union(numbers, strings); // ISet<number | string>
408
+ * console.log(mixed.size); // 5
409
+ *
410
+ * // Union with empty set
411
+ * const nonEmpty = ISet.create(["item1", "item2"]);
412
+ * const empty = ISet.create<string>([]);
413
+ * const withEmpty = ISet.union(nonEmpty, empty);
414
+ * console.log(ISet.equal(withEmpty, nonEmpty)); // true
415
+ *
416
+ * // Overlapping sets
417
+ * const featuresA = ISet.create(["feature1", "feature2", "feature3"]);
418
+ * const featuresB = ISet.create(["feature2", "feature3", "feature4"]);
419
+ * const allFeatures = ISet.union(featuresA, featuresB);
420
+ * console.log(allFeatures.size); // 4 (duplicates removed)
421
+ * ```
422
+ */
423
+ const union: <K1 extends MapSetKeyType, K2 extends MapSetKeyType>(a: ISet<K1>, b: ISet<K2>) => ISet<K1 | K2>;
424
+ }
425
+ export {};
426
+ //# sourceMappingURL=iset.d.mts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"iset.d.mts","sourceRoot":"","sources":["../../src/collections/iset.mts"],"names":[],"mappings":"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"}