heavy-reactive 1.0.0

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 (55) hide show
  1. package/.commitlintrc +2 -0
  2. package/.editorconfig +17 -0
  3. package/.gitattributes +2 -0
  4. package/.github/workflows/check-code.yml +48 -0
  5. package/.github/workflows/lint-commit.yml +15 -0
  6. package/.github/workflows/lint-request.yml +19 -0
  7. package/.github/workflows/release-job.yml +62 -0
  8. package/.husky/commit-msg +18 -0
  9. package/.husky/pre-commit +18 -0
  10. package/.prettierignore +2 -0
  11. package/.prettierrc +9 -0
  12. package/.vscode/extensions.json +3 -0
  13. package/.vscode/settings.json +27 -0
  14. package/.vscode/tasks.json +25 -0
  15. package/CHANGELOG.md +1 -0
  16. package/CONTRIBUTING.md +116 -0
  17. package/GLOSSARY.md +144 -0
  18. package/LICENSE +21 -0
  19. package/README.md +198 -0
  20. package/feature.reactivity/_common/changes.interface.ts +44 -0
  21. package/feature.reactivity/_common/dictionary-changes.interface.ts +54 -0
  22. package/feature.reactivity/_common/observable.interface.ts +22 -0
  23. package/feature.reactivity/_common/set-changes.interface.ts +50 -0
  24. package/feature.reactivity/_common/value-change.interface.ts +54 -0
  25. package/feature.reactivity/_common/value-container.interface.ts +12 -0
  26. package/feature.reactivity/dictionary/reactive-array.class.ts +0 -0
  27. package/feature.reactivity/dictionary/reactive-map.class.ts +0 -0
  28. package/feature.reactivity/dictionary/reactive-object.class.ts +0 -0
  29. package/feature.reactivity/reactivity-disabled.error.ts +11 -0
  30. package/feature.reactivity/reactivity.module.ts +458 -0
  31. package/feature.reactivity/readonly-access.error.ts +13 -0
  32. package/feature.reactivity/set/$difference.class.ts +272 -0
  33. package/feature.reactivity/set/$intersection.class.ts +137 -0
  34. package/feature.reactivity/set/$set.class.ts +1022 -0
  35. package/feature.reactivity/set/$union.class.ts +74 -0
  36. package/feature.reactivity/set/_combination/$combination.class.ts +179 -0
  37. package/feature.reactivity/set/_combination/$variadic-combination.class.ts +235 -0
  38. package/feature.reactivity/set/feature.projection-sets/$complement-via-set.class.ts +159 -0
  39. package/feature.reactivity/set/feature.projection-sets/$complement-via-val.class.ts +126 -0
  40. package/feature.reactivity/set/feature.projection-sets/$set-from-any.class.ts +382 -0
  41. package/feature.reactivity/set/feature.projection-sets/$set-from-set.class.ts +90 -0
  42. package/feature.reactivity/set/feature.projection-sets/$subset-via-set.class.ts +123 -0
  43. package/feature.reactivity/set/feature.projection-sets/$subset-via-val.class.ts +114 -0
  44. package/feature.reactivity/set/feature.projection-sets/feature.reactive-delta-buffer/delta-buffer-for-set.class.ts +235 -0
  45. package/feature.reactivity/set/feature.projection-sets/feature.reactive-delta-buffer/delta-buffer-for-value.class.ts +193 -0
  46. package/feature.reactivity/set/feature.projection-sets/types/dependency-set-resolver.type.ts +19 -0
  47. package/feature.reactivity/set/feature.projection-sets/types/dependency-value-resolver.type.ts +20 -0
  48. package/feature.reactivity/value/$value.class.ts +237 -0
  49. package/feature.set/index.ts +3 -0
  50. package/feature.set/set.prototype.difference.polyfill.ts +7 -0
  51. package/feature.set/set.prototype.intersection.polyfill.ts +6 -0
  52. package/feature.set/set.prototype.union.polyfill.ts +11 -0
  53. package/feature.typescript/maybe-promise.type.ts +1 -0
  54. package/package.json +51 -0
  55. package/tsconfig.json +116 -0
@@ -0,0 +1,1022 @@
1
+ import { Signal } from "class-signals"
2
+ import { IObservable } from "../_common/observable.interface.js"
3
+ import { ISetChanges, TInputSetChanges } from "../_common/set-changes.interface.js"
4
+ import { ReactivityDisabledError } from "../reactivity-disabled.error.js"
5
+ import { ReadonlyAccessError } from "../readonly-access.error.js"
6
+ import { difference } from "#set/index.js"
7
+ import { intersection } from "#set/index.js"
8
+ import { union } from "#set/index.js"
9
+ /**
10
+ * Options used to initialize a reactive set.
11
+ *
12
+ * @template TValue The type of items stored in the set.
13
+ */
14
+ export interface ISetOptions<TValue> {
15
+ /**
16
+ * Optional iterable of initial values to populate the set.
17
+ *
18
+ * These values will be added silently — without triggering `onChange`.
19
+ */
20
+ values?: Iterable<TValue>
21
+
22
+ /**
23
+ * Optional label for debugging, logging, or introspection.
24
+ *
25
+ * This can be used to identify the reactive set in developer tools.
26
+ */
27
+ label?: string
28
+ }
29
+
30
+ /**
31
+ * Reactive wrapper around JavaScript's native `Set<T>`.
32
+ *
33
+ * `$Set<T>` tracks mutations and notifies subscribers via `onChange` whenever the contents change.
34
+ * All common `Set` operations are supported (`add`, `delete`, `clear`, etc.), but with reactive semantics.
35
+ *
36
+ * You can subscribe to changes using `.onChange.subscribe(...)`, which emits change objects
37
+ * describing the items that were added or removed.
38
+ *
39
+ * This class is not intended for direct use. Use the `$set()` helper function to create instances.
40
+ *
41
+ * #### Reactivity control
42
+ *
43
+ * - If reactivity is fully disabled (`immutable`), all mutating operations will throw `ReactivityDisabledError`.
44
+ * - If the set is `readonly`, mutation attempts will throw `ReadonlyAccessError`.
45
+ *
46
+ * Use `onSwitchReactivity` to listen for reactivity mode changes.
47
+ *
48
+ * @template T The type of items stored in the set.
49
+ *
50
+ * @example
51
+ * ```ts
52
+ * const tags = $set<string>()
53
+ *
54
+ * tags.onChange.subscribe(({ increment }) => {
55
+ * if (increment) {
56
+ * console.log('Added tags:', [...increment])
57
+ * }
58
+ * })
59
+ *
60
+ * tags.add('reactive') // Logs: "Added tags: ['reactive']"
61
+ * ```
62
+ *
63
+ * @internal
64
+ */
65
+ export class $Set<TValue> extends Set<TValue> implements IObservable<ISetChanges<TValue>> {
66
+ /**
67
+ * Optional debug label associated with this reactive set.
68
+ *
69
+ * Used for introspection, logging, or developer tooling.
70
+ * Set during construction and not intended for runtime mutation.
71
+ *
72
+ * @private
73
+ */
74
+ readonly #label: string
75
+
76
+ /**
77
+ * Creates a new reactive set.
78
+ *
79
+ * A reactive set extends the native `Set<T>` by adding reactive change tracking.
80
+ * It emits `onChange` signals when the contents are modified via `add`, `delete`, `clear`, etc.
81
+ *
82
+ * Initial elements (if provided) are added silently — no signal is emitted during construction.
83
+ *
84
+ * @param options Configuration object for initialization.
85
+ *
86
+ * @example
87
+ * ```ts
88
+ * const $numbers = $set({ values: [1, 2, 3], label: "initial-numbers" })
89
+ *
90
+ * $numbers.onChange.subscribe(() => {
91
+ * console.log("Updated:", [...$numbers])
92
+ * })
93
+ * ```
94
+ */
95
+ constructor(options: ISetOptions<TValue> = {}) {
96
+ const { values = [], label = "" } = options
97
+
98
+ super()
99
+
100
+ this.#label = label
101
+
102
+ for (const value of values) super.add(value)
103
+ }
104
+
105
+ // ################ SWITCH
106
+
107
+ /**
108
+ * Signal triggered when the reactivity of this set is toggled (enabled or disabled).
109
+ *
110
+ * This signal is emitted:
111
+ * - when `disableReactivity()` is called;
112
+ * - when `enableReactivity()` is called;
113
+ *
114
+ * It can be used to coordinate reactivity state across multiple linked containers (e.g. cascading).
115
+ *
116
+ * The signal does **not** include a payload — use `.isReactivityEnabled` to inspect the current state.
117
+ *
118
+ * @example
119
+ * ```ts
120
+ * $set.onSwitchReactivity.subscribe(() => {
121
+ * console.log("Reactivity was toggled:", $set.isReactivityEnabled)
122
+ * })
123
+ * ```
124
+ */
125
+ public readonly onSwitchReactivity = new Signal()
126
+
127
+ /**
128
+ * Internal flag indicating whether reactivity is enabled.
129
+ *
130
+ * When `false`, all mutation methods throw an error and no signals are emitted.
131
+ * Intended to mark the set as immutable or disconnected from the reactive graph.
132
+ *
133
+ * Modified only via `#enableReactivity()` / `#disableReactivity()`.
134
+ *
135
+ * @private
136
+ */
137
+ #isReactivityEnabled: boolean = true
138
+
139
+ /**
140
+ * Disables reactivity and clears the set.
141
+ *
142
+ * - Sets `#isReactivityEnabled = false`
143
+ * - Cancels any active transaction
144
+ * - Clears the underlying set without dispatching `onChange`
145
+ * - Emits `onSwitchReactivity`
146
+ *
147
+ * @private
148
+ */
149
+ #disableReactivity() {
150
+ this.#isReactivityEnabled = false
151
+ this.#cancelTransaction()
152
+ super.clear()
153
+ this.onSwitchReactivity.activate()
154
+ }
155
+
156
+ /**
157
+ * Re-enables reactivity for this set.
158
+ *
159
+ * - Sets `#isReactivityEnabled = true`
160
+ * - Emits `onSwitchReactivity`
161
+ *
162
+ * Does **not** restore previous contents — the set remains empty.
163
+ *
164
+ * @private
165
+ */
166
+ #enableReactivity() {
167
+ this.#isReactivityEnabled = false
168
+ this.onSwitchReactivity.activate()
169
+ }
170
+
171
+ /**
172
+ * Protected wrapper around `#disableReactivity()` for use by derived classes or systems.
173
+ *
174
+ * @protected
175
+ */
176
+ protected _disableReactivity() {
177
+ return this.#disableReactivity()
178
+ }
179
+
180
+ /**
181
+ * Protected wrapper around `#enableReactivity()` for use by derived classes or systems.
182
+ *
183
+ * @protected
184
+ */
185
+ protected _enableReactivity() {
186
+ return this.#enableReactivity()
187
+ }
188
+
189
+ // ################ TRANSACTIONS
190
+
191
+ /**
192
+ * Temporary set of values to be added when a transaction is committed.
193
+ *
194
+ * During a transaction, calls to `.add()` or related methods populate this set.
195
+ * When `#closeTransaction()` is called, values from here are applied to the actual set.
196
+ *
197
+ * @private
198
+ */
199
+ #transactionIncrement = new Set<TValue>()
200
+
201
+ /**
202
+ * Temporary set of values to be removed when a transaction is committed.
203
+ *
204
+ * During a transaction, calls to `.delete()` or `.clear()` populate this set.
205
+ * When `#closeTransaction()` is called, values from here are removed from the actual set.
206
+ *
207
+ * @private
208
+ */
209
+ #transactionDecrement = new Set<TValue>()
210
+
211
+ /**
212
+ * Indicates whether a transaction is currently active.
213
+ *
214
+ * Used internally to determine if changes should be staged
215
+ * or applied immediately.
216
+ *
217
+ * @private
218
+ */
219
+ #transactionIsOpen = false
220
+
221
+ /**
222
+ * Starts a new transaction for batching updates.
223
+ *
224
+ * Clears any previous staged changes and marks the transaction as open.
225
+ * If a transaction is already active, does nothing.
226
+ *
227
+ * @private
228
+ */
229
+ #openTransaction() {
230
+ if (this.#transactionIsOpen) return
231
+ this.#transactionIncrement.clear()
232
+ this.#transactionDecrement.clear()
233
+ this.#transactionIsOpen = true
234
+ }
235
+
236
+ /**
237
+ * Commits all staged changes collected during the transaction.
238
+ *
239
+ * - Adds all items from `#transactionIncrement` (that are not already present).
240
+ * - Removes all items from `#transactionDecrement` (that still exist).
241
+ * - Emits a single `onChange` signal summarizing the net result.
242
+ *
243
+ * Clears all internal buffers and marks the transaction as closed.
244
+ *
245
+ * @private
246
+ */
247
+ #closeTransaction() {
248
+ if (!this.#transactionIsOpen) return
249
+ this.#transactionIsOpen = false
250
+
251
+ const increment: Set<TValue> = difference(this.#transactionIncrement, this)
252
+ this.#transactionIncrement.clear()
253
+ for (const value of increment) super.add(value)
254
+
255
+ const decrement: Set<TValue> = intersection(this.#transactionDecrement, this)
256
+ this.#transactionDecrement.clear()
257
+ for (const value of decrement) super.delete(value)
258
+
259
+ if (increment.size || decrement.size) {
260
+ this.onChange.activate({
261
+ increment: increment.size ? increment : undefined,
262
+ decrement: decrement.size ? decrement : undefined,
263
+ })
264
+ }
265
+ }
266
+
267
+ /**
268
+ * Cancels the current transaction and discards all staged changes.
269
+ *
270
+ * Resets internal buffers without applying any changes or dispatching a signal.
271
+ *
272
+ * @private
273
+ */
274
+ #cancelTransaction() {
275
+ this.#transactionIncrement.clear()
276
+ this.#transactionDecrement.clear()
277
+ this.#transactionIsOpen = false
278
+ }
279
+
280
+ // TRANSACTIONS (SEMI-PUBLIC)
281
+
282
+ /**
283
+ * Starts a transaction, enforcing immutability rules.
284
+ *
285
+ * Throws an error if the set is immutable.
286
+ *
287
+ * @throws {ReactivityDisabledError} If the set is marked as immutable.
288
+ *
289
+ * @protected
290
+ */
291
+ protected _openTransaction() {
292
+ if (!this.#isReactivityEnabled) throw new ReactivityDisabledError(`${this} is immutable!`)
293
+ return this.#openTransaction()
294
+ }
295
+
296
+ /**
297
+ * Commits the current transaction if active, enforcing immutability rules.
298
+ *
299
+ * @throws {ReactivityDisabledError} If the set is marked as immutable.
300
+ *
301
+ * @protected
302
+ */
303
+ protected _closeTransaction() {
304
+ if (!this.#isReactivityEnabled) throw new ReactivityDisabledError(`${this} is immutable!`)
305
+ return this.#closeTransaction()
306
+ }
307
+
308
+ /**
309
+ * Cancels the current transaction without applying changes.
310
+ *
311
+ * @throws {ReactivityDisabledError} If the set is marked as immutable.
312
+ *
313
+ * @protected
314
+ */
315
+ protected _cancelTransaction() {
316
+ if (!this.#isReactivityEnabled) throw new ReactivityDisabledError(`${this} is immutable!`)
317
+ return this.#cancelTransaction()
318
+ }
319
+
320
+ // TRANSACTIONS (PUBLIC)
321
+
322
+ /**
323
+ * Opens a transaction for batching updates to the set.
324
+ *
325
+ * While a transaction is open, calls to `add`, `delete`, `clear`, etc.
326
+ * do not emit change signals immediately.
327
+ * Instead, changes are staged and only applied after calling `closeTransaction()`.
328
+ *
329
+ * @throws {ReactivityDisabledError} If the set is marked as immutable.
330
+ *
331
+ * @example
332
+ * ```ts
333
+ * $set.openTransaction()
334
+ * $set.add("a")
335
+ * $set.add("b")
336
+ * $set.closeTransaction() // Signal emitted once with added values: ['a', 'b']
337
+ * ```
338
+ */
339
+ public openTransaction() {
340
+ if (!this.#isReactivityEnabled) throw new ReactivityDisabledError(`${this} is immutable!`)
341
+ return this.#openTransaction()
342
+ }
343
+
344
+ /**
345
+ * Closes the active transaction and applies all staged changes.
346
+ *
347
+ * If there were any additions or deletions, a single `onChange` signal is dispatched.
348
+ * If no transaction is open, this is a no-op.
349
+ *
350
+ * @throws {ReactivityDisabledError} If the set is immutable.
351
+ */
352
+ public closeTransaction() {
353
+ if (!this.#isReactivityEnabled) throw new ReactivityDisabledError(`${this} is immutable!`)
354
+ return this.#closeTransaction()
355
+ }
356
+
357
+ /**
358
+ * Cancels any active transaction and discards all pending changes.
359
+ *
360
+ * No signal is dispatched. If no transaction is open, does nothing.
361
+ *
362
+ * @throws {ReactivityDisabledError} If the set is immutable.
363
+ */
364
+ public cancelTransaction() {
365
+ if (!this.#isReactivityEnabled) throw new ReactivityDisabledError(`${this} is immutable!`)
366
+ return this.#cancelTransaction()
367
+ }
368
+
369
+ // ################ EDIT
370
+
371
+ /**
372
+ * Signal that notifies subscribers when the set changes.
373
+ *
374
+ * Any mutation of the set — adding, deleting, or clearing items — triggers this signal.
375
+ * Subscribers receive a payload of type `ISetChanges<TValue>`, describing what was added or removed.
376
+ *
377
+ * Use `.subscribe(...)` to react to changes.
378
+ *
379
+ * @example
380
+ * ```ts
381
+ * $users.onChange.subscribe(({ increment, decrement }) => {
382
+ * if (increment) console.log('Added:', [...increment])
383
+ * if (decrement) console.log('Removed:', [...decrement])
384
+ * });
385
+ * ```
386
+ */
387
+ public readonly onChange = new Signal<ISetChanges<TValue>>()
388
+
389
+ // ################ EDIT - ADD
390
+
391
+ /**
392
+ * Adds a single value to the set, with reactivity.
393
+ *
394
+ * If a transaction is open, the value is staged in `#transactionIncrement`,
395
+ * and removed from `#transactionDecrement`. No signal is dispatched until `closeTransaction()`.
396
+ *
397
+ * If not in a transaction and the value is not already in the set,
398
+ * it is added immediately and `onChange` is dispatched.
399
+ *
400
+ * @param value The value to add.
401
+ * @returns The current set instance.
402
+ *
403
+ * @private
404
+ */
405
+ #reactiveAdd(value: TValue) {
406
+ if (this.#transactionIsOpen) {
407
+ this.#transactionIncrement.add(value)
408
+ this.#transactionDecrement.delete(value)
409
+ } else {
410
+ if (!super.has(value)) {
411
+ super.add(value)
412
+ this.onChange.activate({ increment: new Set([value]), decrement: undefined })
413
+ }
414
+ }
415
+
416
+ return this
417
+ }
418
+
419
+ /**
420
+ * Adds multiple values to the set, with reactivity and optional batching.
421
+ *
422
+ * If a transaction is open, all values are staged into `#transactionIncrement`
423
+ * and removed from `#transactionDecrement`.
424
+ *
425
+ * Otherwise, each value is added immediately if it does not already exist in the set.
426
+ * A single `onChange` signal is dispatched with all added values (if any).
427
+ *
428
+ * @param values A collection of values to add.
429
+ *
430
+ * @private
431
+ */
432
+ #batchReactiveAdd(values: Iterable<TValue>) {
433
+ if (this.#transactionIsOpen) {
434
+ if (values instanceof Set) {
435
+ this.#transactionIncrement = union(this.#transactionIncrement, values)
436
+ this.#transactionDecrement = difference(this.#transactionDecrement, values)
437
+ } else {
438
+ for (const value of values) {
439
+ this.#transactionIncrement.add(value)
440
+ this.#transactionDecrement.delete(value)
441
+ }
442
+ }
443
+ } else {
444
+ if (values instanceof Set) {
445
+ const increment: Set<TValue> = difference(values, this)
446
+
447
+ for (const value of increment) super.add(value)
448
+
449
+ if (increment.size) this.onChange.activate({ increment, decrement: undefined })
450
+ } else {
451
+ const increment = new Set<TValue>()
452
+
453
+ for (const value of values) {
454
+ if (super.has(value)) continue
455
+ super.add(value)
456
+ increment.add(value)
457
+ }
458
+
459
+ if (increment.size) this.onChange.activate({ increment, decrement: undefined })
460
+ }
461
+ }
462
+ }
463
+
464
+ /**
465
+ * Safely adds a value to the set in reactive mode.
466
+ *
467
+ * Throws an error if reactivity is disabled.
468
+ * Otherwise delegates to `#reactiveAdd`.
469
+ *
470
+ * @param value The value to add.
471
+ * @returns The current set instance.
472
+ *
473
+ * @throws {ReactivityDisabledError} If the set is marked as immutable.
474
+ *
475
+ * @protected
476
+ */
477
+ protected _reactiveAdd(value: TValue) {
478
+ if (!this.#isReactivityEnabled) throw new ReactivityDisabledError(`${this} is immutable!`)
479
+ return this.#reactiveAdd(value)
480
+ }
481
+
482
+ /**
483
+ * Safely adds multiple values to the set in reactive mode.
484
+ *
485
+ * Throws an error if reactivity is disabled.
486
+ * Otherwise delegates to `#batchReactiveAdd`.
487
+ *
488
+ * @param values Iterable of values to add.
489
+ * @returns The current set instance.
490
+ *
491
+ * @throws {ReactivityDisabledError} If the set is marked as immutable.
492
+ *
493
+ * @protected
494
+ */
495
+ protected _batchReactiveAdd(values: Iterable<TValue>) {
496
+ if (!this.#isReactivityEnabled) throw new ReactivityDisabledError(`${this} is immutable!`)
497
+ return this.#batchReactiveAdd(values)
498
+ }
499
+
500
+ /**
501
+ * Adds a single value to the reactive set.
502
+ *
503
+ * Behaves like `Set.prototype.add`, but emits an `onChange` signal if the value was not already present.
504
+ * If the value already exists in the set, nothing happens and no signal is emitted.
505
+ *
506
+ * @param value The value to add.
507
+ * @returns The current set instance (for chaining).
508
+ *
509
+ * @throws {ReactivityDisabledError} If the set is marked as immutable.
510
+ *
511
+ * @example
512
+ * ```ts
513
+ * const $items = $set<string>()
514
+ *
515
+ * $items.onChange.subscribe(() => {
516
+ * console.log('Changed:', [...$items])
517
+ * })
518
+ *
519
+ * $items.add('apple') // Logs: ['apple']
520
+ * $items.add('apple') // No log — no change
521
+ * ```
522
+ */
523
+ public add(value: TValue) {
524
+ if (!this.#isReactivityEnabled) throw new ReactivityDisabledError(`${this} is immutable!`)
525
+ return this.#reactiveAdd(value)
526
+ }
527
+
528
+ /**
529
+ * Adds multiple values to the reactive set at once.
530
+ *
531
+ * Works like `add()`, but for many values. A single `onChange` signal
532
+ * is dispatched with all newly added values (if any).
533
+ *
534
+ * If reactivity is disabled, throws an error.
535
+ *
536
+ * @param values A collection of values to add.
537
+ * @returns The current set instance (for chaining).
538
+ *
539
+ * @throws {ReactivityDisabledError} If the set is marked as immutable.
540
+ */
541
+ public batchAdd(values: Iterable<TValue>) {
542
+ if (!this.#isReactivityEnabled) throw new ReactivityDisabledError(`${this} is immutable!`)
543
+ return this.#batchReactiveAdd(values)
544
+ }
545
+
546
+ // ################ EDIT - DELETE
547
+
548
+ /**
549
+ * Removes a single value from the set with reactivity.
550
+ *
551
+ * - If a transaction is open, the removal is staged: the value is added to `#transactionDecrement`
552
+ * and removed from `#transactionIncrement`.
553
+ * - If not in a transaction, the value is removed immediately using `Set.prototype.delete`,
554
+ * and a signal is dispatched if the set was actually changed.
555
+ *
556
+ * @param value The value to remove.
557
+ * @returns `true` (always), for compatibility with `Set.prototype.delete`.
558
+ *
559
+ * @private
560
+ */
561
+ #reactiveDelete(value: TValue) {
562
+ // Если множество в транзакции — запоминаем удаление, но не применяем сразу
563
+ if (this.#transactionIsOpen) {
564
+ this.#transactionIncrement.delete(value)
565
+ this.#transactionDecrement.add(value)
566
+ } else {
567
+ // Пытаемся удалить - Если удаление было успешным — уведомляем подписчиков
568
+ if (super.delete(value)) this.onChange.activate({ increment: undefined, decrement: new Set([value]) })
569
+ }
570
+
571
+ return true
572
+ }
573
+
574
+ /**
575
+ * Removes multiple values from the set with reactivity.
576
+ *
577
+ * - If a transaction is open, all values are staged for removal:
578
+ * they are added to `#transactionDecrement` and removed from `#transactionIncrement`.
579
+ *
580
+ * - If not in a transaction:
581
+ * - A `Set` intersection is used to compute what will actually be removed.
582
+ * - If any items were removed, `onChange` is dispatched with a `decrement` set.
583
+ *
584
+ * @param values The values to remove.
585
+ *
586
+ * @private
587
+ */
588
+ #batchReactiveDelete(values: Iterable<TValue>) {
589
+ if (this.#transactionIsOpen) {
590
+ if (values instanceof Set) {
591
+ this.#transactionIncrement = difference(this.#transactionIncrement, values)
592
+ this.#transactionDecrement = union(this.#transactionDecrement, values)
593
+ } else {
594
+ for (const value of values) {
595
+ this.#transactionIncrement.delete(value)
596
+ this.#transactionDecrement.add(value)
597
+ }
598
+ }
599
+ } else {
600
+ if (values instanceof Set) {
601
+ const decrement: Set<TValue> = intersection(this, values)
602
+
603
+ for (const value of decrement) super.delete(value)
604
+
605
+ if (decrement.size) this.onChange.activate({ increment: undefined, decrement })
606
+ } else {
607
+ const decrement = new Set<TValue>()
608
+
609
+ for (const value of values) if (super.delete(value)) decrement.add(value)
610
+
611
+ if (decrement.size) this.onChange.activate({ increment: undefined, decrement })
612
+ }
613
+ }
614
+ }
615
+
616
+ /**
617
+ * Protected wrapper around `#reactiveDelete()` that enforces immutability.
618
+ *
619
+ * @param value The value to remove.
620
+ * @returns `true` (always), for compatibility with `Set.prototype.delete`.
621
+ *
622
+ * @throws {ReactivityDisabledError} If the set is marked as immutable.
623
+ *
624
+ * @protected
625
+ */
626
+ protected _reactiveDelete(value: TValue) {
627
+ if (!this.#isReactivityEnabled) throw new ReactivityDisabledError(`${this} is immutable!`)
628
+ return this.#reactiveDelete(value)
629
+ }
630
+
631
+ /**
632
+ * Protected wrapper around `#batchReactiveDelete()` that enforces immutability.
633
+ *
634
+ * @param values The values to remove.
635
+ *
636
+ * @throws {ReactivityDisabledError} If the set is marked as immutable.
637
+ *
638
+ * @protected
639
+ */
640
+ protected _batchReactiveDelete(values: Iterable<TValue>) {
641
+ if (!this.#isReactivityEnabled) throw new ReactivityDisabledError(`${this} is immutable!`)
642
+ return this.#batchReactiveDelete(values)
643
+ }
644
+
645
+ /**
646
+ * Removes a single value from the reactive set.
647
+ *
648
+ * Behaves like `Set.prototype.delete`, but triggers the `onChange` signal
649
+ * only if the element was actually present and removed.
650
+ *
651
+ * If a transaction is active, the removal is staged and the signal will be emitted only after `closeTransaction()`.
652
+ *
653
+ * @param value The value to remove.
654
+ * @returns `true` if the value was removed; `false` if it was not found.
655
+ *
656
+ * @throws {ReactivityDisabledError} If the set is marked as immutable.
657
+ *
658
+ * @example
659
+ * ```ts
660
+ * const $tags = $set<string>({ values: ["a", "b", "c"] })
661
+ *
662
+ * $tags.onChange.subscribe(({ decrement }) => {
663
+ * console.log("Removed:", [...(decrement ?? [])])
664
+ * })
665
+ *
666
+ * $tags.delete("b") // Logs: "Removed: ['b']"
667
+ * $tags.delete("z") // No effect
668
+ * ```
669
+ */
670
+ public delete(value: TValue) {
671
+ if (!this.#isReactivityEnabled) throw new ReactivityDisabledError(`${this} is immutable!`)
672
+ return this.#reactiveDelete(value)
673
+ }
674
+
675
+ /**
676
+ * Removes multiple values from the reactive set.
677
+ *
678
+ * Behaves like a batch version of `delete()`. A single `onChange` signal
679
+ * is emitted (if any items were actually removed).
680
+ *
681
+ * If a transaction is active, the removals are staged and the signal is dispatched after `closeTransaction()`.
682
+ *
683
+ * @param values The values to remove.
684
+ * @returns The set instance (for chaining).
685
+ *
686
+ * @throws {ReactivityDisabledError} If the set is marked as immutable.
687
+ */
688
+ public batchDelete(values: Iterable<TValue>) {
689
+ if (!this.#isReactivityEnabled) throw new ReactivityDisabledError(`${this} is immutable!`)
690
+ return this.#batchReactiveDelete(values)
691
+ }
692
+
693
+ // ################ EDIT - CLEAR
694
+
695
+ /**
696
+ * Clears all elements from the set with reactivity support.
697
+ *
698
+ * - If a transaction is active, the full contents of the set are marked for removal
699
+ * by assigning them to `#transactionDecrement`, and staged additions are discarded.
700
+ *
701
+ * - If not in a transaction, the set is cleared immediately via `super.clear()`.
702
+ * If the set was non-empty, a signal is dispatched listing all removed elements.
703
+ *
704
+ * @private
705
+ */
706
+ #reactiveClear() {
707
+ if (this.#transactionIsOpen) {
708
+ this.#transactionIncrement.clear()
709
+ this.#transactionDecrement = new Set(this)
710
+ } else {
711
+ const decrement = new Set(this)
712
+ super.clear()
713
+ if (decrement.size) this.onChange.activate({ increment: undefined, decrement })
714
+ }
715
+ }
716
+
717
+ /**
718
+ * Protected version of `#reactiveClear()` that checks immutability.
719
+ *
720
+ * Throws an error if the set is marked as immutable.
721
+ * Otherwise, clears the set reactively.
722
+ *
723
+ * @throws {ReactivityDisabledError} If the set is marked as immutable.
724
+ *
725
+ * @protected
726
+ */
727
+ protected _reactiveClear() {
728
+ if (!this.#isReactivityEnabled) throw new ReactivityDisabledError(`${this} is immutable!`)
729
+ return this.#reactiveClear()
730
+ }
731
+
732
+ /**
733
+ * Removes all elements from the reactive set.
734
+ *
735
+ * Behaves like `Set.prototype.clear`, but emits a single `onChange` signal
736
+ * containing all removed items — if the set was not empty.
737
+ *
738
+ * If a transaction is active, the operation is delayed and applied only when `closeTransaction()` is called.
739
+ *
740
+ * @throws {ReactivityDisabledError} If the set is marked as immutable.
741
+ *
742
+ * @example
743
+ * ```ts
744
+ * const $tags = $set({ values: ["a", "b", "c"] })
745
+ *
746
+ * $tags.onChange.subscribe(({ decrement }) => {
747
+ * console.log("Cleared:", [...(decrement ?? [])])
748
+ * })
749
+ *
750
+ * $tags.clear() // Logs: Cleared: ['a', 'b', 'c']
751
+ * ```
752
+ */
753
+ public clear() {
754
+ if (!this.#isReactivityEnabled) throw new ReactivityDisabledError(`${this} is immutable!`)
755
+ return this.#reactiveClear()
756
+ }
757
+
758
+ // ################ EDIT - OVERWRITE
759
+
760
+ /**
761
+ * Replaces the entire contents of the set with a new set of values, with reactive change detection.
762
+ *
763
+ * - If a transaction is open, changes are staged using `#transactionIncrement` and `#transactionDecrement`.
764
+ * - If no transaction is open:
765
+ * - Determines the `increment` (values to add) and `decrement` (values to remove).
766
+ * - Mutates the underlying set and dispatches a signal only if changes are detected.
767
+ *
768
+ * Works efficiently whether the incoming values are a `Set` or a generic iterable.
769
+ *
770
+ * @param values New values that should entirely replace the current set.
771
+ *
772
+ * @private
773
+ */
774
+ #reactiveOverwrite(values: Iterable<TValue>) {
775
+ if (this.#transactionIsOpen) {
776
+ if (values instanceof Set) {
777
+ this.#transactionIncrement = new Set(values)
778
+ this.#transactionDecrement = difference(this, values)
779
+ } else {
780
+ this.#transactionIncrement = new Set(values)
781
+ this.#transactionDecrement = new Set(this)
782
+ for (const value of values) this.#transactionDecrement.delete(value)
783
+ }
784
+ } else {
785
+ if (values instanceof Set) {
786
+ const increment: Set<TValue> = difference(values, this)
787
+ const decrement: Set<TValue> = difference(this, values)
788
+
789
+ for (const value of increment) super.add(value)
790
+ for (const value of decrement) super.delete(value)
791
+
792
+ if (increment.size || decrement.size) {
793
+ this.onChange.activate({
794
+ decrement: decrement.size ? decrement : undefined,
795
+ increment: increment.size ? increment : undefined,
796
+ })
797
+ }
798
+ } else {
799
+ const increment = new Set<TValue>()
800
+ const decrement = new Set(this)
801
+
802
+ for (const value of values) {
803
+ if (super.has(value)) decrement.delete(value)
804
+ else increment.add(value)
805
+ }
806
+
807
+ for (const value of increment) super.add(value)
808
+ for (const value of decrement) super.delete(value)
809
+
810
+ if (increment.size || decrement.size) {
811
+ this.onChange.activate({
812
+ decrement: decrement.size ? decrement : undefined,
813
+ increment: increment.size ? increment : undefined,
814
+ })
815
+ }
816
+ }
817
+ }
818
+ }
819
+
820
+ /**
821
+ * Protected wrapper around `#reactiveOverwrite()` that enforces immutability.
822
+ *
823
+ * @param values New values to overwrite the current set.
824
+ *
825
+ * @throws {ReactivityDisabledError} If the set is marked as immutable.
826
+ *
827
+ * @protected
828
+ */
829
+ protected _reactiveOverwrite(values: Iterable<TValue>) {
830
+ if (!this.#isReactivityEnabled) throw new ReactivityDisabledError(`${this} is immutable!`)
831
+ return this.#reactiveOverwrite(values)
832
+ }
833
+
834
+ /**
835
+ * Fully replaces the contents of the reactive set with a new collection of values.
836
+ *
837
+ * - Removes all values that are no longer present.
838
+ * - Adds all values that are new.
839
+ * - Emits a single `onChange` signal with both `increment` and `decrement` sets (if any).
840
+ *
841
+ * If a transaction is active, the changes are staged and emitted later via `closeTransaction()`.
842
+ *
843
+ * @param values Iterable of new values to assign.
844
+ *
845
+ * @throws {ReactivityDisabledError} If the set is marked as immutable.
846
+ *
847
+ * @example
848
+ * ```ts
849
+ * const $ids = $set({ values: [1, 2, 3] })
850
+ *
851
+ * $ids.onChange.subscribe(({ increment, decrement }) => {
852
+ * console.log("Added:", [...(increment ?? [])])
853
+ * console.log("Removed:", [...(decrement ?? [])])
854
+ * })
855
+ *
856
+ * $ids.overwrite([3, 4, 5])
857
+ * // Added: [4, 5]
858
+ * // Removed: [1, 2]
859
+ * ```
860
+ */
861
+ public overwrite(values: Iterable<TValue>) {
862
+ if (!this.#isReactivityEnabled) throw new ReactivityDisabledError(`${this} is immutable!`)
863
+ return this.#reactiveOverwrite(values)
864
+ }
865
+
866
+ // ################ EDIT - APPLY CHANGES
867
+
868
+ /**
869
+ * Internally applies a structured change object to the set.
870
+ *
871
+ * - If `overwrite` is specified, replaces the entire set using `#reactiveOverwrite`.
872
+ * - Otherwise applies `increment` and `decrement` via a transactional batch update.
873
+ *
874
+ * Emits a single `onChange` signal with the net result.
875
+ *
876
+ * @param changes Object containing either:
877
+ * - `overwrite`: full replacement values.
878
+ * - or `increment`/`decrement`: differential updates.
879
+ *
880
+ * @private
881
+ */
882
+ #reactiveApplyChanges(changes?: TInputSetChanges<TValue>) {
883
+ if (!changes) return
884
+
885
+ if ("overwrite" in changes) {
886
+ if (changes.overwrite) this.#reactiveOverwrite(changes.overwrite)
887
+ } else if (changes.increment || changes.decrement) {
888
+ this.#openTransaction()
889
+ if (changes.increment) this.#batchReactiveAdd(changes.increment)
890
+ if (changes.decrement) this.#batchReactiveDelete(changes.decrement)
891
+ this.#closeTransaction()
892
+ }
893
+ }
894
+
895
+ /**
896
+ * Protected wrapper around `#reactiveApplyChanges()` that enforces immutability.
897
+ *
898
+ * @param changes Change instructions to apply.
899
+ *
900
+ * @throws {ReactivityDisabledError} If the set is marked as immutable.
901
+ *
902
+ * @protected
903
+ */
904
+ protected _reactiveApplyChanges(changes?: TInputSetChanges<TValue>) {
905
+ if (!this.#isReactivityEnabled) throw new ReactivityDisabledError(`${this} is immutable!`)
906
+ return this.#reactiveApplyChanges(changes)
907
+ }
908
+
909
+ /**
910
+ * Applies a set of changes to the reactive set.
911
+ *
912
+ * Supports two modes:
913
+ * - Differential updates via `increment` and/or `decrement`.
914
+ * - Full replacement via `overwrite`.
915
+ *
916
+ * Emits a single `onChange` signal only if there were actual changes.
917
+ * Automatically wraps incremental changes in a transaction for batching.
918
+ *
919
+ * @param changes Object describing the change operation.
920
+ *
921
+ * @throws {ReactivityDisabledError} If the set is marked as immutable.
922
+ *
923
+ * @example
924
+ * ```ts
925
+ * $users.applyChanges({
926
+ * increment: new Set([4, 5]),
927
+ * decrement: new Set([1, 2])
928
+ * })
929
+ *
930
+ * $users.applyChanges({
931
+ * overwrite: new Set([7, 8])
932
+ * })
933
+ * ```
934
+ */
935
+ public applyChanges(changes?: TInputSetChanges<TValue>) {
936
+ if (!this.#isReactivityEnabled) throw new ReactivityDisabledError(`${this} is immutable!`)
937
+ return this.#reactiveApplyChanges(changes)
938
+ }
939
+ }
940
+
941
+ /**
942
+ * A reactive set that is strictly immutable — any mutation attempt will throw an error.
943
+ *
944
+ * This class is typically used as the result of computed transformations (e.g. merge, intersection)
945
+ * of other reactive sets. While it exposes the same read and subscription API as `$Set<T>`,
946
+ * all mutation methods (`add`, `delete`, `clear`, etc.) are overridden to throw.
947
+ *
948
+ * Useful for derived state where mutability must be prohibited to ensure consistency and performance.
949
+ *
950
+ * @template TValue The type of items stored in the set.
951
+ *
952
+ * @example
953
+ * ```ts
954
+ * const merged = $mergeSets([$setA, $setB])
955
+ *
956
+ * merged.onChange.subscribe(...) // ✅ allowed
957
+ * merged.add('x') // ❌ throws Error: is readonly!
958
+ * ```
959
+ *
960
+ * @internal
961
+ */
962
+ export class $ReadonlySet<TValue> extends $Set<TValue> {
963
+ /** @throws {ReadonlyAccessError} Always throws an error, because this set is read-only. */
964
+ public openTransaction(...parameters: Parameters<$Set<TValue>["openTransaction"]>) {
965
+ throw new ReadonlyAccessError(`${this} is readonly!`)
966
+ return super.openTransaction(...parameters)
967
+ }
968
+
969
+ /** @throws {ReadonlyAccessError} Always throws an error, because this set is read-only. */
970
+ public closeTransaction(...parameters: Parameters<$Set<TValue>["closeTransaction"]>) {
971
+ throw new ReadonlyAccessError(`${this} is readonly!`)
972
+ return super.closeTransaction(...parameters)
973
+ }
974
+
975
+ /** @throws {ReadonlyAccessError} Always throws an error, because this set is read-only. */
976
+ public cancelTransaction(...parameters: Parameters<$Set<TValue>["cancelTransaction"]>) {
977
+ throw new ReadonlyAccessError(`${this} is readonly!`)
978
+ return super.cancelTransaction(...parameters)
979
+ }
980
+
981
+ /** @throws {ReadonlyAccessError} Always throws an error, because this set is read-only. */
982
+ public add(...parameters: Parameters<$Set<TValue>["add"]>) {
983
+ throw new ReadonlyAccessError(`${this} is readonly!`)
984
+ return super.add(...parameters)
985
+ }
986
+
987
+ /** @throws {ReadonlyAccessError} Always throws an error, because this set is read-only. */
988
+ public batchAdd(...parameters: Parameters<$Set<TValue>["batchAdd"]>) {
989
+ throw new ReadonlyAccessError(`${this} is readonly!`)
990
+ return super.batchAdd(...parameters)
991
+ }
992
+
993
+ /** @throws {ReadonlyAccessError} Always throws an error, because this set is read-only. */
994
+ public delete(...parameters: Parameters<$Set<TValue>["delete"]>) {
995
+ throw new ReadonlyAccessError(`${this} is readonly!`)
996
+ return super.delete(...parameters)
997
+ }
998
+
999
+ /** @throws {ReadonlyAccessError} Always throws an error, because this set is read-only. */
1000
+ public batchDelete(...parameters: Parameters<$Set<TValue>["batchDelete"]>) {
1001
+ throw new ReadonlyAccessError(`${this} is readonly!`)
1002
+ return super.batchDelete(...parameters)
1003
+ }
1004
+
1005
+ /** @throws {ReadonlyAccessError} Always throws an error, because this set is read-only. */
1006
+ public clear(...parameters: Parameters<$Set<TValue>["clear"]>) {
1007
+ throw new ReadonlyAccessError(`${this} is readonly!`)
1008
+ return super.clear(...parameters)
1009
+ }
1010
+
1011
+ /** @throws {ReadonlyAccessError} Always throws an error, because this set is read-only. */
1012
+ public overwrite(...parameters: Parameters<$Set<TValue>["overwrite"]>) {
1013
+ throw new ReadonlyAccessError(`${this} is readonly!`)
1014
+ return super.overwrite(...parameters)
1015
+ }
1016
+
1017
+ /** @throws {ReadonlyAccessError} Always throws an error, because this set is read-only. */
1018
+ public applyChanges(...parameters: Parameters<$Set<TValue>["applyChanges"]>) {
1019
+ throw new ReadonlyAccessError(`${this} is readonly!`)
1020
+ return super.applyChanges(...parameters)
1021
+ }
1022
+ }