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,74 @@
|
|
|
1
|
+
import { ISetChanges } from "../_common/set-changes.interface.js"
|
|
2
|
+
import { $VariadicCombination } from "./_combination/$variadic-combination.class.js"
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* Reactive set representing the union of multiple source sets.
|
|
6
|
+
*
|
|
7
|
+
* `$Union<T>` tracks a dynamic collection of input `$Set<T>` instances
|
|
8
|
+
* and computes their union — that is, the result contains all values
|
|
9
|
+
* that are present in **at least one** of the source sets.
|
|
10
|
+
*
|
|
11
|
+
* This class extends `$VariadicCombination<T>` and is designed to maintain
|
|
12
|
+
* a live, reactive aggregation of elements from all its inputs.
|
|
13
|
+
*
|
|
14
|
+
* The resulting set is:
|
|
15
|
+
* - **readonly** — user-level mutations are forbidden and will throw;
|
|
16
|
+
* - **reactive** — emits `onChange` when any included value is added or removed;
|
|
17
|
+
* - **fully derived** — its content reflects only the union of source sets.
|
|
18
|
+
*
|
|
19
|
+
* @template TValue The type of values in the sets.
|
|
20
|
+
*
|
|
21
|
+
* @example
|
|
22
|
+
* ```ts
|
|
23
|
+
* const $a = $set(['x', 'y'])
|
|
24
|
+
* const $b = $set(['y', 'z'])
|
|
25
|
+
*
|
|
26
|
+
* const $combined = new $Union([$a, $b])
|
|
27
|
+
*
|
|
28
|
+
* console.log([...$combined]) // ['x', 'y', 'z']
|
|
29
|
+
*
|
|
30
|
+
* $a.delete('x')
|
|
31
|
+
* console.log([...$combined]) // ['y', 'z']
|
|
32
|
+
* ```
|
|
33
|
+
*/
|
|
34
|
+
export class $Union<TValue> extends $VariadicCombination<TValue> {
|
|
35
|
+
/**
|
|
36
|
+
* Recalculates the union result when a change occurs in one of the source sets.
|
|
37
|
+
*
|
|
38
|
+
* The union contains all values present in at least one subset.
|
|
39
|
+
* This method updates the internal occurrence map and emits a change signal
|
|
40
|
+
* if any values were newly introduced (added to union) or fully removed (removed from all subsets).
|
|
41
|
+
*
|
|
42
|
+
* @param param0 A change object from a source set's `onChange` event.
|
|
43
|
+
*/
|
|
44
|
+
protected recalculateOnSubsetChange({ increment: addedToSubset, decrement: removedFromSubset }: ISetChanges<TValue>) {
|
|
45
|
+
const addedToUnion = new Set<TValue>()
|
|
46
|
+
const removedFromUnion = new Set<TValue>()
|
|
47
|
+
|
|
48
|
+
for (const item of addedToSubset ?? []) {
|
|
49
|
+
const prevCount = this.valueOccurrences.get(item) ?? 0
|
|
50
|
+
|
|
51
|
+
const nextCount = prevCount + 1
|
|
52
|
+
|
|
53
|
+
this.valueOccurrences.set(item, prevCount + 1)
|
|
54
|
+
|
|
55
|
+
if (nextCount === 1) addedToUnion.add(item)
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
for (const item of removedFromSubset ?? []) {
|
|
59
|
+
const prevCount = this.valueOccurrences.get(item)
|
|
60
|
+
if (!prevCount) throw new Error(`Cannot decrement item "${item}" that is not currently tracked in the union occurrence map.`)
|
|
61
|
+
|
|
62
|
+
const nextCount = prevCount - 1
|
|
63
|
+
|
|
64
|
+
if (nextCount === 0) {
|
|
65
|
+
this.valueOccurrences.delete(item)
|
|
66
|
+
removedFromUnion.add(item)
|
|
67
|
+
} else {
|
|
68
|
+
this.valueOccurrences.set(item, nextCount)
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
|
|
72
|
+
this.applyChanges({ increment: addedToUnion, decrement: removedFromUnion })
|
|
73
|
+
}
|
|
74
|
+
}
|
|
@@ -0,0 +1,179 @@
|
|
|
1
|
+
import { Signal } from "class-signals"
|
|
2
|
+
import { $Set } from "../$set.class.js"
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* Configuration options for initializing a `$Combination<T>`.
|
|
6
|
+
*/
|
|
7
|
+
export interface ICombinationOptions {
|
|
8
|
+
/**
|
|
9
|
+
* Optional label for debugging or developer tools.
|
|
10
|
+
*/
|
|
11
|
+
label?: string
|
|
12
|
+
|
|
13
|
+
/**
|
|
14
|
+
* Whether the combination should be active (reactive) initially.
|
|
15
|
+
* Defaults to `true` if not specified.
|
|
16
|
+
*/
|
|
17
|
+
enabled?: boolean
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* Base class for reactive set combinators that participate in derived calculations.
|
|
22
|
+
*
|
|
23
|
+
* `$Combination<T>` extends `$Set<T>` and introduces lifecycle control for derived sets.
|
|
24
|
+
* It provides a minimal reactive core for managing:
|
|
25
|
+
*
|
|
26
|
+
* - reactivity state (`enabled`, `onSwitch`);
|
|
27
|
+
* - cascade enable/disable logic;
|
|
28
|
+
* - activation/deactivation lifecycle hooks (`onActivated`, `onDeactivated`);
|
|
29
|
+
* - soft reactivity toggling through public `.enable()` / `.disable()` / `.switch(state?)` methods.
|
|
30
|
+
*
|
|
31
|
+
* This class is not designed to be used directly — instead, it serves as a foundation for:
|
|
32
|
+
* - `$VariadicCombination<T>` — which adds dynamic subset management;
|
|
33
|
+
* - higher-level operators like `$Intersection`, `$Union`, `$Difference`.
|
|
34
|
+
*
|
|
35
|
+
* @template TValue The type of values held in the set.
|
|
36
|
+
*
|
|
37
|
+
* @remarks
|
|
38
|
+
* All `$Combination` instances are immutable from the outside —
|
|
39
|
+
* all mutation methods throw `ReadonlyAccessError`.
|
|
40
|
+
*
|
|
41
|
+
* Use `.enabled` to determine whether the combination is reactive at the moment.
|
|
42
|
+
* Use `.onSwitch` to listen for reactivity state changes.
|
|
43
|
+
*/
|
|
44
|
+
export abstract class $Combination<TValue> extends $Set<TValue> {
|
|
45
|
+
/**
|
|
46
|
+
* Signal emitted when the combination is enabled or disabled.
|
|
47
|
+
*
|
|
48
|
+
* Can be used by parent or dependent structures to track reactivity status.
|
|
49
|
+
*
|
|
50
|
+
* @example
|
|
51
|
+
* ```ts
|
|
52
|
+
* $combination.onSwitch.subscribe(() => {
|
|
53
|
+
* if ($combination.enabled) console.log("Activated")
|
|
54
|
+
* else console.log("Deactivated")
|
|
55
|
+
* })
|
|
56
|
+
* ```
|
|
57
|
+
*/
|
|
58
|
+
readonly onSwitch = new Signal()
|
|
59
|
+
|
|
60
|
+
/**
|
|
61
|
+
* Initializes a new combination instance with optional configuration.
|
|
62
|
+
*
|
|
63
|
+
* This base constructor is used by all derived reactive combinators,
|
|
64
|
+
* such as `$Intersection`, `$Union`, and `$Difference`.
|
|
65
|
+
*
|
|
66
|
+
* @param options Configuration object:
|
|
67
|
+
* - `label` — optional debug label;
|
|
68
|
+
* - `enabled` — whether the combination is active initially (defaults to `true`).
|
|
69
|
+
*/
|
|
70
|
+
constructor(options: ICombinationOptions) {
|
|
71
|
+
super(options)
|
|
72
|
+
this.#isLocallyEnabled = options.enabled ?? true
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/**
|
|
76
|
+
* Tracks local reactivity state of the combination.
|
|
77
|
+
*
|
|
78
|
+
* Used to gate activation logic without involving external cascade state.
|
|
79
|
+
*/
|
|
80
|
+
#isLocallyEnabled: boolean
|
|
81
|
+
|
|
82
|
+
/**
|
|
83
|
+
* Returns whether this combination is currently reactive.
|
|
84
|
+
*
|
|
85
|
+
* This value reflects local activation only — subclasses may override the
|
|
86
|
+
* `enabled` getter to include cascade logic.
|
|
87
|
+
*/
|
|
88
|
+
public get enabled() {
|
|
89
|
+
return this.isLocallyEnabled
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
/**
|
|
93
|
+
* Enables the combination if it is currently disabled.
|
|
94
|
+
*
|
|
95
|
+
* Triggers the internal lifecycle activation hook and emits `onSwitch`.
|
|
96
|
+
*/
|
|
97
|
+
public enable(): void {
|
|
98
|
+
if (this.isLocallyEnabled) return
|
|
99
|
+
this.activate()
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
/**
|
|
103
|
+
* Disables the combination if it is currently enabled.
|
|
104
|
+
*
|
|
105
|
+
* Triggers the internal lifecycle deactivation hook and emits `onSwitch`.
|
|
106
|
+
*/
|
|
107
|
+
public disable(): void {
|
|
108
|
+
if (!this.isLocallyEnabled) return
|
|
109
|
+
this.deactivate()
|
|
110
|
+
}
|
|
111
|
+
|
|
112
|
+
/**
|
|
113
|
+
* Internal flag getter.
|
|
114
|
+
*
|
|
115
|
+
* @internal
|
|
116
|
+
*/
|
|
117
|
+
protected get isLocallyEnabled() {
|
|
118
|
+
return this.#isLocallyEnabled
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
/**
|
|
122
|
+
* Internal flag setter.
|
|
123
|
+
*
|
|
124
|
+
* @internal
|
|
125
|
+
*/
|
|
126
|
+
protected set isLocallyEnabled(value) {
|
|
127
|
+
this.#isLocallyEnabled = value
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
/**
|
|
131
|
+
* Internal method to transition into the active (reactive) state.
|
|
132
|
+
*
|
|
133
|
+
* This method:
|
|
134
|
+
* - updates local state;
|
|
135
|
+
* - calls `onActivated()` lifecycle hook.
|
|
136
|
+
*/
|
|
137
|
+
protected activate() {
|
|
138
|
+
this.isLocallyEnabled = true
|
|
139
|
+
this.onActivated()
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
/**
|
|
143
|
+
* Lifecycle hook triggered when the combination becomes active.
|
|
144
|
+
*
|
|
145
|
+
* Subclasses may override this to start listening to inputs or initialize state.
|
|
146
|
+
* This method emits the `onSwitch` signal.
|
|
147
|
+
*/
|
|
148
|
+
protected onActivated() {
|
|
149
|
+
this.onSwitch.activate()
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
/**
|
|
153
|
+
* Internal method to transition into the inactive (non-reactive) state.
|
|
154
|
+
*
|
|
155
|
+
* This method:
|
|
156
|
+
* - updates local state;
|
|
157
|
+
* - calls `onDeactivated()` lifecycle hook.
|
|
158
|
+
*/
|
|
159
|
+
protected deactivate() {
|
|
160
|
+
this.isLocallyEnabled = false
|
|
161
|
+
this.onDeactivated()
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
/**
|
|
165
|
+
* Lifecycle hook triggered when the combination is disabled.
|
|
166
|
+
*
|
|
167
|
+
* This implementation:
|
|
168
|
+
* - emits the `onSwitch` signal;
|
|
169
|
+
* - clears current content;
|
|
170
|
+
* - cancels pending transactions.
|
|
171
|
+
*
|
|
172
|
+
* Subclasses may override to clean up derived state or signal listeners.
|
|
173
|
+
*/
|
|
174
|
+
protected onDeactivated() {
|
|
175
|
+
this.onSwitch.activate()
|
|
176
|
+
this.cancelTransaction()
|
|
177
|
+
this.clear()
|
|
178
|
+
}
|
|
179
|
+
}
|
|
@@ -0,0 +1,235 @@
|
|
|
1
|
+
import { $Set } from "../$set.class.js"
|
|
2
|
+
import { ISetChanges } from "../../_common/set-changes.interface.js"
|
|
3
|
+
import { $Combination } from "./$combination.class.js"
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* Configuration options for constructing a `$VariadicCombination<T>`.
|
|
7
|
+
*
|
|
8
|
+
* @template TValue The type of values managed by the combination.
|
|
9
|
+
*/
|
|
10
|
+
export interface IVariadicCombinationOptions<TValue> {
|
|
11
|
+
/**
|
|
12
|
+
* The initial list of reactive subsets to include in the combination.
|
|
13
|
+
*/
|
|
14
|
+
subsets: Array<$Set<TValue>>
|
|
15
|
+
|
|
16
|
+
/**
|
|
17
|
+
* Optional debug label used for introspection or error messages.
|
|
18
|
+
*/
|
|
19
|
+
label?: string
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* Whether this combination is initially reactive.
|
|
23
|
+
* Defaults to `true` if omitted.
|
|
24
|
+
*/
|
|
25
|
+
enabled?: boolean
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* Abstract base class for reactive set combinations that depend on a variable number of input sets.
|
|
30
|
+
*
|
|
31
|
+
* `$VariadicCombination<T>` manages a collection of reactive input sets (`$Set<T>`) and provides:
|
|
32
|
+
* - lifecycle control (`mount`, `unmount`) for dynamically added/removed subsets;
|
|
33
|
+
* - automatic subscription management via `AbortController`;
|
|
34
|
+
* - a shared occurrence map (`Map<T, number>`) to track presence and frequency of values across subsets;
|
|
35
|
+
* - reactive update propagation through `applyChanges()`;
|
|
36
|
+
* - support for cascade disabling via a parent node (`$Combination`) if applicable.
|
|
37
|
+
*
|
|
38
|
+
* This class is not meant to be instantiated directly. It provides shared logic for concrete
|
|
39
|
+
* reactive set derivations like:
|
|
40
|
+
*
|
|
41
|
+
* - `$Intersection<T>` — values common to all subsets
|
|
42
|
+
* - `$Union<T>` — values present in at least one subset
|
|
43
|
+
* - `$Difference<T>` — values in a base set not present in any excluded subsets
|
|
44
|
+
*
|
|
45
|
+
* Subclasses must implement:
|
|
46
|
+
* - `recalculateOnSubsetChange(changes: ISetChanges<T>): void` — logic for updating the result
|
|
47
|
+
* when a single input subset changes.
|
|
48
|
+
*
|
|
49
|
+
* @template TValue The type of values contained in the sets.
|
|
50
|
+
*
|
|
51
|
+
* @remarks
|
|
52
|
+
* This class extends `$Set<T>` and is **readonly** — all mutation methods throw.
|
|
53
|
+
* Use the `.subsets` array to control inputs, and `.applyChanges()` to emit result updates.
|
|
54
|
+
*/
|
|
55
|
+
export abstract class $VariadicCombination<TValue> extends $Combination<TValue> {
|
|
56
|
+
/**
|
|
57
|
+
* Tracks all subsets that are *registered* with this combination,
|
|
58
|
+
* regardless of whether they are currently active/reactive.
|
|
59
|
+
*
|
|
60
|
+
* - These sets are known to the combination and may be conditionally mounted.
|
|
61
|
+
* - Used for structural bookkeeping and cleanup.
|
|
62
|
+
*
|
|
63
|
+
* Subsets may be *attached* but not *included* if, for example, they are temporarily disabled.
|
|
64
|
+
*/
|
|
65
|
+
protected readonly allSubsets = new Set<$Set<TValue>>()
|
|
66
|
+
|
|
67
|
+
/**
|
|
68
|
+
* Subsets that are actively contributing to the combination result.
|
|
69
|
+
*
|
|
70
|
+
* - This is a subset of `attachedSubsets`.
|
|
71
|
+
* - Subsets are added here only if they are currently reactive/enabled.
|
|
72
|
+
* - The size of this set is often used as a threshold for inclusion in intersection logic.
|
|
73
|
+
*/
|
|
74
|
+
protected readonly includedSubsets = new Set<$Set<TValue>>()
|
|
75
|
+
|
|
76
|
+
/**
|
|
77
|
+
* Tracks how many included subsets contain each value.
|
|
78
|
+
*
|
|
79
|
+
* The key is a value of type `TValue`.
|
|
80
|
+
* The value is the number of currently included subsets that contain it.
|
|
81
|
+
*
|
|
82
|
+
* Interpretation of this map depends on subclass:
|
|
83
|
+
* - In `$Intersection`, a value is included if its count equals `includedSubsets.size`.
|
|
84
|
+
* - In `$Union`, a value is included if its count is at least `1`.
|
|
85
|
+
* - In `$Difference`, a similar map is used for exclusion tracking.
|
|
86
|
+
*/
|
|
87
|
+
protected readonly valueOccurrences = new Map<TValue, number>()
|
|
88
|
+
|
|
89
|
+
/**
|
|
90
|
+
* Tracks subscriptions to `onChange` signals from all subsets.
|
|
91
|
+
*
|
|
92
|
+
* Each subset is associated with an `AbortController`, which can be used
|
|
93
|
+
* to cancel the signal listener when the subset is unmounted.
|
|
94
|
+
*/
|
|
95
|
+
protected readonly subsetChangeControllers = new Map<$Set<TValue>, AbortController>()
|
|
96
|
+
|
|
97
|
+
/**
|
|
98
|
+
* Tracks subscriptions to `onSwitch` signals from parent combinations (if any).
|
|
99
|
+
*
|
|
100
|
+
* This enables nested combinations to respond to reactivity state changes
|
|
101
|
+
* in parent nodes and maintain cascade consistency.
|
|
102
|
+
*/
|
|
103
|
+
protected readonly cascadeControllers = new Map<$Combination<TValue>, AbortController>()
|
|
104
|
+
|
|
105
|
+
/**
|
|
106
|
+
* Creates a new variadic combination from a list of subsets.
|
|
107
|
+
*
|
|
108
|
+
* This constructor is used by all derived reactive set combinators,
|
|
109
|
+
* such as `$Intersection`, `$Union`, and `$Difference`.
|
|
110
|
+
*
|
|
111
|
+
* @param options Configuration object:
|
|
112
|
+
* - `subsets`: the initial reactive sets to combine;
|
|
113
|
+
* - `label`: optional debug label;
|
|
114
|
+
* - `enabled`: whether the combination starts active.
|
|
115
|
+
*/
|
|
116
|
+
constructor(options: IVariadicCombinationOptions<TValue>) {
|
|
117
|
+
super({ label: options.label, enabled: options.enabled })
|
|
118
|
+
for (const subset of options.subsets) this.#registerSubset(subset)
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
/**
|
|
122
|
+
* Registers a new input subset for participation in this combination.
|
|
123
|
+
*
|
|
124
|
+
* - Ensures the subset is not already registered.
|
|
125
|
+
* - If the subset is another combination, tracks its reactivity.
|
|
126
|
+
* - Activates the subset immediately if appropriate.
|
|
127
|
+
*
|
|
128
|
+
* @throws If the same subset is registered more than once.
|
|
129
|
+
*/
|
|
130
|
+
#registerSubset(subset: $Set<TValue>) {
|
|
131
|
+
if (this.allSubsets.has(subset)) throw new Error("Subset is already registered. Perhaps you intended to register multiple events instead?")
|
|
132
|
+
|
|
133
|
+
this.allSubsets.add(subset)
|
|
134
|
+
|
|
135
|
+
if (subset instanceof $Combination) {
|
|
136
|
+
this.trackSubsetSwitchState(subset)
|
|
137
|
+
if (subset.enabled) this.includeSubsetInCalc(subset)
|
|
138
|
+
} else this.includeSubsetInCalc(subset)
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
/**
|
|
142
|
+
* Subscribes to the `onSwitch` signal of a subset that is itself a combination.
|
|
143
|
+
*
|
|
144
|
+
* This enables the parent to respond when the subset is enabled or disabled,
|
|
145
|
+
* and update the result calculation accordingly.
|
|
146
|
+
*/
|
|
147
|
+
protected trackSubsetSwitchState(subset: $Combination<TValue>) {
|
|
148
|
+
const controller = new AbortController()
|
|
149
|
+
this.cascadeControllers.set(subset, controller)
|
|
150
|
+
subset.onSwitch.subscribe(() => (subset.enabled ? this.includeSubsetInCalc(subset) : this.excludeSubsetFromCalc(subset)))
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
/**
|
|
154
|
+
* Includes a subset in the combination’s internal calculations.
|
|
155
|
+
*
|
|
156
|
+
* - Adds the subset to `includedSubsets`.
|
|
157
|
+
* - Mounts the subset immediately if this combination is currently enabled.
|
|
158
|
+
*/
|
|
159
|
+
protected includeSubsetInCalc(subset: $Set<TValue>) {
|
|
160
|
+
this.includedSubsets.add(subset)
|
|
161
|
+
if (this.enabled) this.mountSubset(subset)
|
|
162
|
+
}
|
|
163
|
+
|
|
164
|
+
/**
|
|
165
|
+
* Excludes a subset from the combination’s internal calculations.
|
|
166
|
+
*
|
|
167
|
+
* - Removes the subset from `includedSubsets`.
|
|
168
|
+
* - Unmounts the subset if this combination is currently enabled.
|
|
169
|
+
*/
|
|
170
|
+
protected excludeSubsetFromCalc(subset: $Set<TValue>) {
|
|
171
|
+
this.includedSubsets.delete(subset)
|
|
172
|
+
if (this.enabled) this.unmountSubset(subset)
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
/**
|
|
176
|
+
* Lifecycle hook called when this combination becomes reactive.
|
|
177
|
+
*
|
|
178
|
+
* All currently included subsets are mounted and begin contributing to the result.
|
|
179
|
+
*/
|
|
180
|
+
protected onActivated(): void {
|
|
181
|
+
super.onActivated()
|
|
182
|
+
for (const subset of this.includedSubsets) this.mountSubset(subset)
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
/**
|
|
186
|
+
* Lifecycle hook called when this combination is disabled.
|
|
187
|
+
*
|
|
188
|
+
* All currently included subsets are unmounted and removed from the result.
|
|
189
|
+
*/
|
|
190
|
+
protected onDeactivated(): void {
|
|
191
|
+
super.onDeactivated()
|
|
192
|
+
for (const subset of this.includedSubsets) this.unmountSubset(subset)
|
|
193
|
+
}
|
|
194
|
+
|
|
195
|
+
/**
|
|
196
|
+
* Mounts a subset: processes its current state and subscribes to future changes.
|
|
197
|
+
*
|
|
198
|
+
* - Its current content is processed via `recalculateOnSubsetChange`.
|
|
199
|
+
* - A signal listener is attached to respond to future updates.
|
|
200
|
+
*/
|
|
201
|
+
protected mountSubset(subset: $Set<TValue>) {
|
|
202
|
+
this.recalculateOnSubsetChange({ increment: subset, decrement: undefined })
|
|
203
|
+
this.listenSubsetChanges(subset)
|
|
204
|
+
}
|
|
205
|
+
|
|
206
|
+
/**
|
|
207
|
+
* Unmounts a subset: stops listening to its changes and removes its contribution.
|
|
208
|
+
*
|
|
209
|
+
* - The subset is unsubscribed using its `AbortController`.
|
|
210
|
+
* - Its contribution is removed from the result via `recalculateOnSubsetChange`.
|
|
211
|
+
*/
|
|
212
|
+
protected unmountSubset(subset: $Set<TValue>) {
|
|
213
|
+
this.subsetChangeControllers.get(subset)?.abort()
|
|
214
|
+
if (this.enabled) this.recalculateOnSubsetChange({ increment: undefined, decrement: subset })
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
/**
|
|
218
|
+
* Subscribes to the `onChange` signal of a subset.
|
|
219
|
+
*
|
|
220
|
+
* Any changes in the subset will be forwarded to `recalculateOnSubsetChange(...)`.
|
|
221
|
+
*/
|
|
222
|
+
protected listenSubsetChanges(subset: $Set<TValue>) {
|
|
223
|
+
const controller = new AbortController()
|
|
224
|
+
this.subsetChangeControllers.set(subset, controller)
|
|
225
|
+
subset.onChange.subscribe((changes) => this.recalculateOnSubsetChange(changes), { signal: controller.signal })
|
|
226
|
+
}
|
|
227
|
+
|
|
228
|
+
/**
|
|
229
|
+
* Must be implemented by subclasses to define how changes in a single subset
|
|
230
|
+
* should affect the resulting combination.
|
|
231
|
+
*
|
|
232
|
+
* @param changes A change payload emitted by one of the subsets.
|
|
233
|
+
*/
|
|
234
|
+
protected abstract recalculateOnSubsetChange(changes: ISetChanges<TValue>): void
|
|
235
|
+
}
|
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
import { $SetFromAny } from "./$set-from-any.class.js"
|
|
2
|
+
import { $Set } from "../$set.class.js"
|
|
3
|
+
import { ICombinationOptions } from "../_combination/$combination.class.js"
|
|
4
|
+
import { difference } from "#set/index.js"
|
|
5
|
+
import { MaybePromise } from "#typescript/maybe-promise.type.js"
|
|
6
|
+
|
|
7
|
+
/**
|
|
8
|
+
* Configuration options for `$ComplementViaSet<TItem, TRelation>`.
|
|
9
|
+
*
|
|
10
|
+
* Defines a reactive complement set by excluding items from a `superset`
|
|
11
|
+
* based on a dynamic set of **relation keys**.
|
|
12
|
+
*
|
|
13
|
+
* Each key in the `relation` set is passed to the `resolver()` function,
|
|
14
|
+
* which projects it into a subset of values to exclude from the result.
|
|
15
|
+
*/
|
|
16
|
+
export interface IComplementViaSetOptions<TItem, TRelation> extends ICombinationOptions {
|
|
17
|
+
/** The source set from which the complement is computed. */
|
|
18
|
+
superset: $Set<TItem>
|
|
19
|
+
|
|
20
|
+
/**
|
|
21
|
+
* Reactive set of relation keys.
|
|
22
|
+
*
|
|
23
|
+
* Each key is resolved into a subset of values from the `superset`
|
|
24
|
+
* that should be excluded from the result.
|
|
25
|
+
*/
|
|
26
|
+
relation: $Set<TRelation>
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* Resolves each relation key into values to exclude from the result.
|
|
30
|
+
*
|
|
31
|
+
* This function defines a projective exclusion:
|
|
32
|
+
* - each key may map to multiple values;
|
|
33
|
+
* - excluded values are removed from the superset to form the complement.
|
|
34
|
+
*
|
|
35
|
+
* @example
|
|
36
|
+
* - selected tags → items tagged
|
|
37
|
+
* - blocked users → their posts
|
|
38
|
+
* - disabled features → associated UI elements
|
|
39
|
+
*
|
|
40
|
+
* @param superset The current values in the superset.
|
|
41
|
+
* @param relation The current set of relation keys.
|
|
42
|
+
* @returns A set of values to exclude from the final result.
|
|
43
|
+
*/
|
|
44
|
+
resolver: (superset: Set<NoInfer<TItem>>, relation: Set<NoInfer<TRelation>>) => MaybePromise<Iterable<NoInfer<TItem>>>
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* Reactive complement of a superset based on a dynamic set of projection keys.
|
|
49
|
+
*
|
|
50
|
+
* `$ComplementViaSet<TItem, TRelation>` creates a readonly derived set by projecting
|
|
51
|
+
* each key from the `relation` set into values from the `superset` that should be excluded.
|
|
52
|
+
* The result includes all items from the `superset` **except** those present in the projection.
|
|
53
|
+
*
|
|
54
|
+
* Each key is resolved via a custom `resolver()` function, which defines how the
|
|
55
|
+
* relation keys map to exclusion targets in the superset.
|
|
56
|
+
*
|
|
57
|
+
* ### Use cases:
|
|
58
|
+
* - exclude items by selected tags,
|
|
59
|
+
* - hide objects by category or permission,
|
|
60
|
+
* - suppress content by user roles or blocklist.
|
|
61
|
+
*
|
|
62
|
+
* ### Reactivity model:
|
|
63
|
+
* - When values are added to the `superset`, they are checked against the current projection
|
|
64
|
+
* and only included if not excluded by any relation key;
|
|
65
|
+
* - When `relation` keys are added/removed, their projections are added to or removed from the exclusion;
|
|
66
|
+
* - On first relation update, a full projection is performed to initialize the result.
|
|
67
|
+
*
|
|
68
|
+
* @template TItem The type of elements in the superset and resulting set.
|
|
69
|
+
* @template TRelation The type of relation keys used for exclusion.
|
|
70
|
+
*
|
|
71
|
+
* @remarks
|
|
72
|
+
* - The result is **readonly** — calling `.add()` or `.delete()` will throw.
|
|
73
|
+
* - The result is always **derived** from the superset — mutate the inputs to change the result.
|
|
74
|
+
*
|
|
75
|
+
* @example Exclude words by selected prefixes:
|
|
76
|
+
* ```ts
|
|
77
|
+
* const $words = $set({ values: ['alpha', 'beta', 'gamma', 'delta'] })
|
|
78
|
+
* const $blocked = $set({ values: ['a', 'd'] })
|
|
79
|
+
*
|
|
80
|
+
* const $visible = new $ComplementViaSet({
|
|
81
|
+
* superset: $words,
|
|
82
|
+
* relation: $blocked,
|
|
83
|
+
* resolver: (words, prefixes) =>
|
|
84
|
+
* [...words].filter(word =>
|
|
85
|
+
* [...prefixes].some(prefix => word.startsWith(prefix))
|
|
86
|
+
* ),
|
|
87
|
+
* })
|
|
88
|
+
*
|
|
89
|
+
* console.log([...$visible]) // → ['beta', 'gamma']
|
|
90
|
+
* $blocked.add('b')
|
|
91
|
+
* console.log([...$visible]) // → ['gamma']
|
|
92
|
+
* ```
|
|
93
|
+
*/
|
|
94
|
+
export class $ComplementViaSet<TItem, TRelation> extends $SetFromAny<TItem, { superset: $Set<TItem>; relation: $Set<TRelation> }> {
|
|
95
|
+
/**
|
|
96
|
+
* Internal flag used to ensure that the initial complement is calculated only once.
|
|
97
|
+
*
|
|
98
|
+
* On first reactivity pass from the `relation` set, we compute a full initial
|
|
99
|
+
* exclusion projection and treat it as an overwrite.
|
|
100
|
+
*
|
|
101
|
+
* In the future, this mechanism should be replaced with a standardized
|
|
102
|
+
* `calculateInitialState()` hook from the base reactive class.
|
|
103
|
+
*/
|
|
104
|
+
#complementWasExtracted = false
|
|
105
|
+
|
|
106
|
+
constructor(options: IComplementViaSetOptions<TItem, TRelation>) {
|
|
107
|
+
const { label, enabled = true, superset, relation, resolver } = options
|
|
108
|
+
|
|
109
|
+
super({
|
|
110
|
+
label,
|
|
111
|
+
enabled,
|
|
112
|
+
dependencies: { superset, relation },
|
|
113
|
+
resolvers: {
|
|
114
|
+
superset: async ({ relation: currentRelation }, { increment: addedToSuperset, decrement: removedFromSuperset }) => {
|
|
115
|
+
if (!currentRelation?.size) return { increment: undefined, decrement: undefined }
|
|
116
|
+
|
|
117
|
+
let addedToComplement: Set<TItem> | undefined
|
|
118
|
+
|
|
119
|
+
if (addedToSuperset?.size) {
|
|
120
|
+
const matched = new Set(await resolver(addedToSuperset, currentRelation))
|
|
121
|
+
addedToComplement = difference(addedToSuperset, matched)
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
return {
|
|
125
|
+
increment: addedToComplement,
|
|
126
|
+
decrement: removedFromSuperset,
|
|
127
|
+
}
|
|
128
|
+
},
|
|
129
|
+
relation: async ({ superset: currentSuperset }, { increment: addedToRelation, decrement: removedFromRelation }) => {
|
|
130
|
+
if (!currentSuperset?.size) return { increment: undefined, decrement: undefined }
|
|
131
|
+
|
|
132
|
+
let addedToComplement: Set<TItem> | undefined
|
|
133
|
+
|
|
134
|
+
let incrementOfInner: Set<TItem> | undefined
|
|
135
|
+
let decrementOfInner: Set<TItem> | undefined
|
|
136
|
+
|
|
137
|
+
if (addedToRelation?.size) incrementOfInner = new Set(await resolver(currentSuperset, addedToRelation))
|
|
138
|
+
if (removedFromRelation?.size) decrementOfInner = new Set(await resolver(currentSuperset, removedFromRelation))
|
|
139
|
+
|
|
140
|
+
if (this.#complementWasExtracted) {
|
|
141
|
+
addedToComplement = decrementOfInner
|
|
142
|
+
} else {
|
|
143
|
+
addedToComplement = incrementOfInner && difference(currentSuperset, incrementOfInner)
|
|
144
|
+
this.#complementWasExtracted = true
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
return {
|
|
148
|
+
increment: addedToComplement,
|
|
149
|
+
decrement: incrementOfInner,
|
|
150
|
+
}
|
|
151
|
+
},
|
|
152
|
+
},
|
|
153
|
+
})
|
|
154
|
+
|
|
155
|
+
this.onSwitch.subscribe(() => {
|
|
156
|
+
if (!this.enabled) this.#complementWasExtracted = false
|
|
157
|
+
})
|
|
158
|
+
}
|
|
159
|
+
}
|