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.
- package/.commitlintrc +2 -0
- package/.editorconfig +17 -0
- package/.gitattributes +2 -0
- package/.github/workflows/check-code.yml +48 -0
- package/.github/workflows/lint-commit.yml +15 -0
- package/.github/workflows/lint-request.yml +19 -0
- package/.github/workflows/release-job.yml +62 -0
- package/.husky/commit-msg +18 -0
- package/.husky/pre-commit +18 -0
- package/.prettierignore +2 -0
- package/.prettierrc +9 -0
- package/.vscode/extensions.json +3 -0
- package/.vscode/settings.json +27 -0
- package/.vscode/tasks.json +25 -0
- package/CHANGELOG.md +1 -0
- package/CONTRIBUTING.md +116 -0
- package/GLOSSARY.md +144 -0
- package/LICENSE +21 -0
- package/README.md +198 -0
- package/feature.reactivity/_common/changes.interface.ts +44 -0
- package/feature.reactivity/_common/dictionary-changes.interface.ts +54 -0
- package/feature.reactivity/_common/observable.interface.ts +22 -0
- package/feature.reactivity/_common/set-changes.interface.ts +50 -0
- package/feature.reactivity/_common/value-change.interface.ts +54 -0
- package/feature.reactivity/_common/value-container.interface.ts +12 -0
- package/feature.reactivity/dictionary/reactive-array.class.ts +0 -0
- package/feature.reactivity/dictionary/reactive-map.class.ts +0 -0
- package/feature.reactivity/dictionary/reactive-object.class.ts +0 -0
- package/feature.reactivity/reactivity-disabled.error.ts +11 -0
- package/feature.reactivity/reactivity.module.ts +458 -0
- package/feature.reactivity/readonly-access.error.ts +13 -0
- package/feature.reactivity/set/$difference.class.ts +272 -0
- package/feature.reactivity/set/$intersection.class.ts +137 -0
- package/feature.reactivity/set/$set.class.ts +1022 -0
- package/feature.reactivity/set/$union.class.ts +74 -0
- package/feature.reactivity/set/_combination/$combination.class.ts +179 -0
- package/feature.reactivity/set/_combination/$variadic-combination.class.ts +235 -0
- package/feature.reactivity/set/feature.projection-sets/$complement-via-set.class.ts +159 -0
- package/feature.reactivity/set/feature.projection-sets/$complement-via-val.class.ts +126 -0
- package/feature.reactivity/set/feature.projection-sets/$set-from-any.class.ts +382 -0
- package/feature.reactivity/set/feature.projection-sets/$set-from-set.class.ts +90 -0
- package/feature.reactivity/set/feature.projection-sets/$subset-via-set.class.ts +123 -0
- package/feature.reactivity/set/feature.projection-sets/$subset-via-val.class.ts +114 -0
- package/feature.reactivity/set/feature.projection-sets/feature.reactive-delta-buffer/delta-buffer-for-set.class.ts +235 -0
- package/feature.reactivity/set/feature.projection-sets/feature.reactive-delta-buffer/delta-buffer-for-value.class.ts +193 -0
- package/feature.reactivity/set/feature.projection-sets/types/dependency-set-resolver.type.ts +19 -0
- package/feature.reactivity/set/feature.projection-sets/types/dependency-value-resolver.type.ts +20 -0
- package/feature.reactivity/value/$value.class.ts +237 -0
- package/feature.set/index.ts +3 -0
- package/feature.set/set.prototype.difference.polyfill.ts +7 -0
- package/feature.set/set.prototype.intersection.polyfill.ts +6 -0
- package/feature.set/set.prototype.union.polyfill.ts +11 -0
- package/feature.typescript/maybe-promise.type.ts +1 -0
- package/package.json +51 -0
- 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
|
+
}
|