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,123 @@
1
+ import { $Set } from "../$set.class.js"
2
+ import { $SetFromAny } from "./$set-from-any.class.js"
3
+ import { ICombinationOptions } from "../_combination/$combination.class.js"
4
+ import { MaybePromise } from "#typescript/maybe-promise.type.js"
5
+
6
+ /**
7
+ * Configuration options for `$SubsetViaSet<TItem, TRelation>`.
8
+ *
9
+ * Defines a derived subset, built by projecting a reactive set of **relation keys**
10
+ * into corresponding values within the `superset`.
11
+ *
12
+ * Each element in the `relation` set is interpreted as a key that selects
13
+ * zero or more related values from the `superset`, as determined by the `resolver`.
14
+ *
15
+ * The resulting subset consists of the **union of all projected values**.
16
+ */
17
+ export interface ISubsetViaSetOptions<TItem, TRelation> extends ICombinationOptions {
18
+ /** The source set from which result values are selected. */
19
+ superset: $Set<TItem>
20
+
21
+ /**
22
+ * A reactive set of projection keys.
23
+ *
24
+ * Each keys is used to project values from the `superset` using the `resolver`.
25
+ */
26
+ relation: $Set<TRelation>
27
+
28
+ /**
29
+ * Resolves each relation key into values drawn from the `superset`.
30
+ *
31
+ * This function defines the projection logic — such as mapping:
32
+ * - tag → items
33
+ * - category → products
34
+ * - parent → child nodes
35
+ *
36
+ * @param superset The current values of the superset.
37
+ * @param relation The current relation keys to project.
38
+ * @returns A set of values from the superset to include in the result.
39
+ */
40
+ resolver: (superset: Set<TItem>, relation: Set<TRelation>) => MaybePromise<Iterable<TItem>>
41
+ }
42
+
43
+ /**
44
+ * Reactive subset derived from a base set using a set of dynamic relation keys.
45
+ *
46
+ * `$SubsetViaSet<TItem, TRelation>` creates a readonly, reactive set
47
+ * by projecting each item in the `relation` set into values from the `superset`,
48
+ * using a custom `resolver()` function.
49
+ *
50
+ * The result is the **union of all projected values** — one projection per relation key.
51
+ *
52
+ * Typical use cases include:
53
+ * - filtering by selected tags,
54
+ * - resolving parent → children,
55
+ * - querying linked entities via references.
56
+ *
57
+ * Reacts to:
58
+ * - changes in the `superset` (added/removed items);
59
+ * - changes in the `relation` set (added/removed keys).
60
+ *
61
+ * @template TItem The type of values in the superset and result.
62
+ * @template TRelation The type of relation keys used to drive projection.
63
+ *
64
+ * @remarks
65
+ * This set is `readonly`: any attempt to modify it directly will throw.
66
+ *
67
+ * @example Show words that match selected prefixes:
68
+ * ```ts
69
+ * const $words = $set({ values: ['alpha', 'beta', 'gamma', 'delta'] })
70
+ * const $prefixes = $set({ values: ['a', 'd'] })
71
+ *
72
+ * const $matching = new $SubsetViaSet({
73
+ * superset: $words,
74
+ * relation: $prefixes,
75
+ * resolver: (words, prefixes) =>
76
+ * [...words].filter(word =>
77
+ * [...prefixes].some(prefix => word.startsWith(prefix))
78
+ * ),
79
+ * })
80
+ *
81
+ * console.log([...$matching]) // → ['alpha', 'delta']
82
+ * $prefixes.add('b')
83
+ * console.log([...$matching]) // → ['alpha', 'beta', 'delta']
84
+ * ```
85
+ */
86
+ export class $SubsetViaSet<TItem, TRelation> extends $SetFromAny<TItem, { superset: $Set<TItem>; relation: $Set<TRelation> }> {
87
+ constructor(options: ISubsetViaSetOptions<TItem, TRelation>) {
88
+ const { label, enabled = true, superset, relation, resolver } = options
89
+
90
+ super({
91
+ label,
92
+ enabled,
93
+ dependencies: { superset, relation },
94
+ resolvers: {
95
+ superset: async ({ relation: currentRelation }, { increment: addedToSuperset, decrement: removedFromSuperset }) => {
96
+ if (!currentRelation?.size) return { increment: undefined, decrement: undefined }
97
+
98
+ let addedToSubset: Set<TItem> | undefined
99
+ if (addedToSuperset?.size) addedToSubset = new Set(await resolver(addedToSuperset, currentRelation))
100
+
101
+ return {
102
+ increment: addedToSubset,
103
+ decrement: removedFromSuperset,
104
+ }
105
+ },
106
+ relation: async ({ superset: currentSuperset }, { increment: addedToRelation, decrement: removedFromRelation }) => {
107
+ if (!currentSuperset?.size) return { increment: undefined, decrement: undefined }
108
+
109
+ let addedToSubset: Set<TItem> | undefined
110
+ let removedFromSubset: Set<TItem> | undefined
111
+
112
+ if (addedToRelation?.size) addedToSubset = new Set(await resolver(currentSuperset, addedToRelation))
113
+ if (removedFromRelation?.size) removedFromSubset = new Set(await resolver(currentSuperset, removedFromRelation))
114
+
115
+ return {
116
+ increment: addedToSubset,
117
+ decrement: removedFromSubset,
118
+ }
119
+ },
120
+ },
121
+ })
122
+ }
123
+ }
@@ -0,0 +1,114 @@
1
+ import { IValueContainer } from "../../_common/value-container.interface.js"
2
+ import { $Value } from "../../value/$value.class.js"
3
+ import { $Set } from "../$set.class.js"
4
+ import { $SetFromAny } from "./$set-from-any.class.js"
5
+ import { ICombinationOptions } from "../_combination/$combination.class.js"
6
+ import { MaybePromise } from "#typescript/maybe-promise.type.js"
7
+
8
+ /**
9
+ * Configuration options for `$SubsetViaVal<TItem, TRelation>`.
10
+ *
11
+ * Defines a derived subset based on a single **relation key** stored in a reactive `$Value`.
12
+ *
13
+ * The key is passed to a `resolver()` function that selects values from the `superset`.
14
+ * The resulting subset consists of all values that are currently **related** to the active key.
15
+ */
16
+ export interface ISubsetViaValOptions<TItem, TRelation> extends ICombinationOptions {
17
+ /** The source set from which result values are selected. */
18
+ superset: $Set<TItem>
19
+
20
+ /**
21
+ * A reactive value representing a projection key.
22
+ *
23
+ * This key is used to project values from the `superset` using the `resolver`.
24
+ */
25
+ relation: $Value<TRelation>
26
+
27
+ /**
28
+ * Resolves the current relation key into values drawn from the `superset`.
29
+ *
30
+ * This function defines the projection logic — such as:
31
+ * - category → items
32
+ * - role → permissions
33
+ * - current route → visible menu entries
34
+ *
35
+ * @param superset The current contents of the superset.
36
+ * @param relation A reactive container holding the current relation key.
37
+ * @returns A set of values from the superset to include in the result.
38
+ */
39
+ resolver: (superset: Set<NoInfer<TItem>>, relation: IValueContainer<NoInfer<TRelation>>) => MaybePromise<Iterable<NoInfer<TItem>>>
40
+ }
41
+
42
+ /**
43
+ * Reactive subset derived from a source set based on a dynamic projection key.
44
+ *
45
+ * `$SubsetViaVal<TItem, TRelation>` builds a derived, readonly `$Set<TItem>` by projecting
46
+ * a single reactive `relation` key into related values from the `superset`.
47
+ *
48
+ * The projection is defined using a custom `resolver()` function.
49
+ * It maps the current `relation` value to the set of items in the `superset`
50
+ * that should be included in the result.
51
+ *
52
+ * This allows expressing state-dependent subsets such as:
53
+ * - current category → products,
54
+ * - selected tag → matching entries,
55
+ * - current role → accessible features.
56
+ *
57
+ * Reacts to:
58
+ * - changes in the `superset` (added/removed values),
59
+ * - updates to the `relation` key.
60
+ *
61
+ * @template TItem The type of elements in the superset and resulting subset.
62
+ * @template TRelation The type of the relation key used for projection.
63
+ *
64
+ * @remarks
65
+ * This set is `readonly`: all mutating operations like `.add()` or `.clear()` will throw.
66
+ *
67
+ * @example Project visible items based on even/odd mode:
68
+ * ```ts
69
+ * const $numbers = $set({ values: [1, 2, 3, 4, 5, 6] })
70
+ * const $mode = $value<'even' | 'odd'>({ value: 'even' })
71
+ *
72
+ * const $visible = new $SubsetViaVal({
73
+ * superset: $numbers,
74
+ * relation: $mode,
75
+ * resolver: (numbers, mode) =>
76
+ * [...numbers].filter(n => (mode.value === 'even' ? n % 2 === 0 : n % 2 !== 0)),
77
+ * })
78
+ *
79
+ * console.log([...$visible]) // → [2, 4, 6]
80
+ * $mode.value = 'odd'
81
+ * console.log([...$visible]) // → [1, 3, 5]
82
+ * ```
83
+ */
84
+ export class $SubsetViaVal<TItem, TRelation> extends $SetFromAny<TItem, { superset: $Set<TItem>; relation: $Value<TRelation> }> {
85
+ constructor(options: ISubsetViaValOptions<TItem, TRelation>) {
86
+ const { label, enabled = true, superset, relation, resolver } = options
87
+
88
+ super({
89
+ label,
90
+ enabled,
91
+ dependencies: { superset, relation },
92
+ resolvers: {
93
+ superset: async ({ relation: currentRelation }, { increment: addedToSuperset, decrement: removedFromSuperset }) => {
94
+ if (!currentRelation) return { increment: undefined, decrement: undefined }
95
+
96
+ let addedToSubset: Set<TItem> | undefined
97
+ if (addedToSuperset?.size) addedToSubset = new Set(await resolver(addedToSuperset, currentRelation))
98
+
99
+ return {
100
+ increment: addedToSubset,
101
+ decrement: removedFromSuperset,
102
+ }
103
+ },
104
+ relation: async ({ superset: currentSuperset }, { increment: nextRelation }) => {
105
+ if (!currentSuperset?.size || !nextRelation) return { increment: undefined, decrement: undefined }
106
+
107
+ const newSubset = new Set(await resolver(currentSuperset, nextRelation))
108
+
109
+ return { overwrite: newSubset }
110
+ },
111
+ },
112
+ })
113
+ }
114
+ }
@@ -0,0 +1,235 @@
1
+ import { ISetChanges } from "../../../_common/set-changes.interface.js"
2
+ import { TDependencySetResolver } from "../types/dependency-set-resolver.type.js"
3
+ import { $Set } from "../../$set.class.js"
4
+ import { Signal } from "class-signals"
5
+ import { difference, union } from "#set/index.js"
6
+
7
+ /**
8
+ * Reactive delta buffer for a `$Set<T>`.
9
+ *
10
+ * `DeltaBufferForSet` observes changes from a reactive `$Set` source
11
+ * and accumulates a pending change set, separated into additions and removals.
12
+ * These changes can later be committed and consumed as an atomic delta.
13
+ *
14
+ * This buffering mechanism enables controlled, stepwise propagation
15
+ * of updates across multiple reactive dependencies without race conditions or redundant work.
16
+ *
17
+ * ### Lifecycle
18
+ * - When enabled, the buffer listens to `.onChange` of the source set.
19
+ * - All changes are accumulated incrementally in two sets:
20
+ * - `pendingAdded` — new elements added to the source
21
+ * - `pendingRemoved` — elements removed from the source
22
+ * - When `commitState()` is called:
23
+ * - both pending buffers are cleared
24
+ * - `getCommitted()` becomes valid
25
+ *
26
+ * ### Usage
27
+ * This buffer is used internally in `$SetFromAny` to manage deferred application
28
+ * of changes and is compatible with `TDependencySetResolver` functions.
29
+ *
30
+ * @example
31
+ * ```ts
32
+ * const buffer = new DeltaBufferForSet("source", $tags, resolve, true)
33
+ *
34
+ * const delta = buffer.getBufferedChange()
35
+ * const result = await resolve(context, delta)
36
+ * buffer.commitState()
37
+ * ```
38
+ */
39
+ export class DeltaBufferForSet<TSource extends $Set<any> = $Set<any>> {
40
+ /**
41
+ * Signal emitted whenever new uncommitted changes are buffered.
42
+ *
43
+ * Consumers may use this to trigger resolution logic,
44
+ * e.g. in `$SetFromAny`, to launch `synchronize()` when changes are present.
45
+ */
46
+ readonly onChange = new Signal()
47
+
48
+ /**
49
+ * The set of values that were added to the source but not yet committed.
50
+ * These will appear in `increment` if `getBufferedChange()` is called.
51
+ */
52
+ #pendingAdded = new Set()
53
+
54
+ /**
55
+ * The set of values that were removed from the source but not yet committed.
56
+ * These will appear in `decrement` if `getBufferedChange()` is called.
57
+ */
58
+ #pendingRemoved = new Set()
59
+
60
+ /**
61
+ * Whether this delta buffer is currently enabled.
62
+ * A disabled buffer ignores changes and clears its internal state.
63
+ */
64
+ #isLocallyEnabled: boolean
65
+
66
+ /** Controller used to cancel the active subscription to `source.onChange`. */
67
+ #changesSubscription?: AbortController
68
+
69
+ /**
70
+ * Initializes a new delta buffer for a `$Set<T>`.
71
+ *
72
+ * The buffer listens to change signals from the given reactive set,
73
+ * accumulates uncommitted additions and removals, and provides access
74
+ * to the resulting delta through `getBufferedChange()`.
75
+ *
76
+ * This constructor also optionally activates the buffer immediately,
77
+ * subscribing to the source and buffering its initial state as an addition.
78
+ *
79
+ * @param name A unique name identifying this dependency within the reactive context.
80
+ * @param source The reactive `$Set` to observe.
81
+ * @param resolver A function that converts buffered changes into result-level updates.
82
+ * @param isInitiallyEnabled Whether the buffer should start active and listening.
83
+ */
84
+ constructor(
85
+ public readonly name: string,
86
+ public readonly source: TSource,
87
+ public readonly resolver: TDependencySetResolver,
88
+ isInitiallyEnabled: boolean,
89
+ ) {
90
+ this.#isLocallyEnabled = isInitiallyEnabled
91
+
92
+ if (this.enabled) {
93
+ this.subscribeToSource()
94
+ this.bufferIncomingChange({ increment: this.source, decrement: undefined })
95
+ }
96
+ }
97
+
98
+ // ################ ACTIVATION ################
99
+
100
+ /**
101
+ * Indicates whether the buffer is currently enabled.
102
+ * If disabled, no changes will be tracked or retained.
103
+ */
104
+ public get enabled() {
105
+ return this.#isLocallyEnabled
106
+ }
107
+
108
+ /**
109
+ * Enables the buffer and starts listening for changes from the source set.
110
+ * Immediately buffers the current state as an `increment` delta.
111
+ */
112
+ public enable() {
113
+ if (this.#isLocallyEnabled === true) return
114
+ this.#isLocallyEnabled = true
115
+
116
+ this.subscribeToSource()
117
+ this.bufferIncomingChange({ increment: this.source, decrement: undefined })
118
+ }
119
+
120
+ /** Disables the buffer, stops tracking, and clears all internal state. */
121
+ public disable() {
122
+ if (this.#isLocallyEnabled === false) return
123
+ this.#isLocallyEnabled = false
124
+
125
+ this.#changesSubscription?.abort()
126
+ this.clear()
127
+ }
128
+
129
+ // ################ TRACKING ################
130
+
131
+ /**
132
+ * Subscribes to the source set's `.onChange` signal.
133
+ * Any received change is buffered using `bufferIncomingChange()`.
134
+ */
135
+ protected subscribeToSource() {
136
+ const controller = new AbortController()
137
+ this.#changesSubscription = controller
138
+ this.source.onChange.subscribe((changes) => this.bufferIncomingChange(changes), { signal: controller.signal })
139
+ }
140
+
141
+ /**
142
+ * Clears both addition and removal buffers.
143
+ * Called when the buffer is disabled or reinitialized.
144
+ */
145
+ protected clear() {
146
+ this.#pendingAdded.clear()
147
+ this.#pendingRemoved.clear()
148
+ }
149
+
150
+ /**
151
+ * Buffers a new incoming set change by merging it into the current delta.
152
+ *
153
+ * - All values from `increment` are added to `pendingAdded` and removed from `pendingRemoved`.
154
+ * - All values from `decrement` are added to `pendingRemoved` and removed from `pendingAdded`.
155
+ *
156
+ * After applying the change, the `onChange` signal is dispatched.
157
+ *
158
+ * @param changes A change payload received from the source set.
159
+ */
160
+ protected bufferIncomingChange(changes: ISetChanges<any>): void {
161
+ for (const value of changes.increment ?? []) {
162
+ this.#pendingAdded.add(value)
163
+ this.#pendingRemoved.delete(value)
164
+ }
165
+
166
+ for (const value of changes.decrement ?? []) {
167
+ this.#pendingAdded.delete(value)
168
+ this.#pendingRemoved.add(value)
169
+ }
170
+
171
+ this.onChange.activate()
172
+ }
173
+
174
+ // ################ PUBLIC API ################
175
+
176
+ /**
177
+ * Returns the current buffered (uncommitted) set changes, if any.
178
+ *
179
+ * @returns An object with `increment` / `decrement` sets, or `null` if no change is buffered.
180
+ * @throws If the buffer is disabled.
181
+ */
182
+ public getBufferedChanges(): ISetChanges<any> | null {
183
+ if (!this.enabled) throw new Error("Dependence is turned off - you cannot extract its state!")
184
+
185
+ if (this.#pendingAdded.size || this.#pendingRemoved.size) {
186
+ return { increment: new Set(this.#pendingAdded), decrement: new Set(this.#pendingRemoved) }
187
+ }
188
+
189
+ return null
190
+ }
191
+
192
+ /**
193
+ * Tracks whether the buffer has ever been committed.
194
+ *
195
+ * Used internally by `getCommitted()` to determine
196
+ * whether a valid resolved state can be returned.
197
+ *
198
+ * Until this is `true`, `getCommitted()` will return `null`
199
+ * to indicate that no commit has taken place yet.
200
+ */
201
+ #hasCommittedOnce = false
202
+
203
+ /**
204
+ * Commits the current buffered changes and clears the internal delta.
205
+ *
206
+ * After this call:
207
+ * - `getBufferedChange()` returns null;
208
+ * - `getCommitted()` becomes available.
209
+ *
210
+ * @throws If the buffer is disabled.
211
+ */
212
+ public commitChanges() {
213
+ if (!this.enabled) throw new Error("Dependence is turned off - you cannot commit its state!")
214
+ this.#pendingAdded.clear()
215
+ this.#pendingRemoved.clear()
216
+ this.#hasCommittedOnce = true
217
+ }
218
+
219
+ /**
220
+ * Returns the last known committed state of the source set,
221
+ * computed as: `(source − pendingAdded) ∪ pendingRemoved`.
222
+ *
223
+ * This gives the actual derived content as seen by the buffer
224
+ * after all resolved and applied changes — not the raw input.
225
+ *
226
+ * @returns A Set representing the last resolved state, or `null` if never committed.
227
+ * @throws If the buffer is disabled.
228
+ */
229
+ public getCommittedState() {
230
+ if (!this.enabled) throw new Error("Dependence is turned off - you cannot extract its state!")
231
+ if (!this.#hasCommittedOnce) return null
232
+
233
+ return union(difference(this.source, this.#pendingAdded), this.#pendingRemoved)
234
+ }
235
+ }
@@ -0,0 +1,193 @@
1
+ import { TDependencyValueResolver } from "../types/dependency-value-resolver.type.js"
2
+ import { IValueContainer } from "../../../_common/value-container.interface.js"
3
+ import { $Value } from "../../../value/$value.class.js"
4
+ import { IValueChange } from "../../../_common/value-change.interface.js"
5
+ import { Signal } from "class-signals"
6
+ import equal from "@wry/equality"
7
+
8
+ /**
9
+ * Reactive delta buffer for a `$Value<T>`.
10
+ *
11
+ * `DeltaBufferForValue` tracks changes from a source `$Value<T>` and stores
12
+ * an uncommitted delta until it is explicitly resolved via `.commit()`.
13
+ *
14
+ * This class implements a two-phase model:
15
+ * 1. **Indexing phase** — changes are detected and stored in `#pending`;
16
+ * 2. **Commit phase** — changes are acknowledged and flushed into `#committed`.
17
+ *
18
+ * It acts as a delta gate between a source reactive value and
19
+ * a resolver that maps changes into a derived set.
20
+ *
21
+ * @remarks
22
+ * - Signals are not data carriers — they only notify that something changed.
23
+ * - The buffer exposes access to `getIndexedChange()` only when active.
24
+ * - The buffer is disabled via `.disable()` and re-enabled via `.enable()`.
25
+ *
26
+ * @example
27
+ * ```ts
28
+ * const delta = new DeltaBufferForValue('mode', $mode, resolve, true)
29
+ *
30
+ * // on change signal
31
+ * const deltaPayload = delta.getIndexedChange()
32
+ * const resultDelta = await resolve(context, deltaPayload)
33
+ * delta.commit()
34
+ * applyChanges(resultDelta)
35
+ * ```
36
+ */
37
+ export class DeltaBufferForValue {
38
+ /**
39
+ * Signal emitted when new uncommitted changes are detected.
40
+ * Consumers should call `.getIndexedChange()` and then `.commit()`.
41
+ */
42
+ readonly onChange = new Signal()
43
+
44
+ /**
45
+ * The last committed value from the source.
46
+ * Used for diffing and rollback logic.
47
+ */
48
+ #committedState?: IValueContainer<unknown> = undefined
49
+
50
+ /**
51
+ * The currently indexed (but not yet committed) value.
52
+ * Will be returned by `.getIndexedChange()` if present.
53
+ */
54
+ #pendingChange?: IValueContainer<unknown> = undefined
55
+
56
+ /** Whether the buffer is currently active. */
57
+ #isLocallyEnabled: boolean
58
+
59
+ /** Subscription controller for source signal. */
60
+ #changesSubscription?: AbortController
61
+
62
+ /**
63
+ * Creates a new delta buffer for a `$Value`.
64
+ *
65
+ * @param name A logical name for this tracked dependency (used in context).
66
+ * @param source The `$Value` instance to track.
67
+ * @param resolver Function to map value changes into result set changes.
68
+ * @param isInitiallyEnabled Whether this buffer should start active.
69
+ */
70
+ constructor(
71
+ public readonly name: string,
72
+ public readonly source: $Value<unknown>,
73
+ public readonly resolver: TDependencyValueResolver,
74
+ isInitiallyEnabled: boolean,
75
+ ) {
76
+ this.#isLocallyEnabled = isInitiallyEnabled
77
+
78
+ if (this.enabled) {
79
+ this.subscribeToSource()
80
+ this.bufferIncomingChange(this.source)
81
+ }
82
+ }
83
+
84
+ // ################ ACTIVATION ################
85
+
86
+ /**
87
+ * Whether this delta buffer is currently active.
88
+ * A disabled buffer ignores source changes and clears its internal state.
89
+ */
90
+ public get enabled() {
91
+ return this.#isLocallyEnabled
92
+ }
93
+
94
+ /**
95
+ * Enables this buffer, starts tracking changes again,
96
+ * and re-indexes the current value.
97
+ */
98
+ public enable() {
99
+ if (this.#isLocallyEnabled) return
100
+ this.#isLocallyEnabled = true
101
+
102
+ this.subscribeToSource()
103
+ this.bufferIncomingChange(this.source)
104
+ }
105
+
106
+ /**
107
+ * Disables this buffer and clears all tracked state.
108
+ * Future changes will be ignored until re-enabled.
109
+ */
110
+ public disable() {
111
+ if (!this.#isLocallyEnabled) return
112
+ this.#isLocallyEnabled = false
113
+
114
+ this.#changesSubscription?.abort()
115
+ this.clear()
116
+ }
117
+
118
+ /**
119
+ * Clears both the committed and uncommitted (pending) values.
120
+ * Called when the buffer is disabled or reinitialized.
121
+ */
122
+ protected clear(): void {
123
+ this.#pendingChange = undefined
124
+ this.#committedState = undefined
125
+ }
126
+
127
+ // ################ TRACKING ################
128
+
129
+ /**
130
+ * Subscribes to the `$Value` source and routes incoming changes into the buffer.
131
+ * Only `increment` values are tracked.
132
+ */
133
+ protected subscribeToSource() {
134
+ const controller = new AbortController()
135
+ this.#changesSubscription = controller
136
+ this.source.onChange.subscribe((change) => change.increment && this.bufferIncomingChange(change.increment), { signal: controller.signal })
137
+ }
138
+
139
+ /**
140
+ * Compares a new incoming value to the committed state,
141
+ * and stores it in the pending buffer if it's different.
142
+ * Emits `onChange` if the pending state is updated.
143
+ *
144
+ * @param incoming A new value container emitted by the source.
145
+ */
146
+ protected bufferIncomingChange(state: IValueContainer<unknown>): void {
147
+ // Skip if already pending and unchanged
148
+ if (this.#pendingChange && equal(this.#pendingChange, state)) return
149
+
150
+ // If value matches committed, clear pending
151
+ if (equal(this.#committedState, state)) this.#pendingChange = undefined
152
+ else this.#pendingChange = { value: state.value }
153
+
154
+ this.onChange.activate()
155
+ }
156
+
157
+ // ################ PUBLIC API ################
158
+
159
+ /**
160
+ * Returns the currently buffered (uncommitted) change.
161
+ *
162
+ * @returns A value change object `{ increment, decrement }` or `null`.
163
+ * @throws If the buffer is disabled.
164
+ */
165
+ public getBufferedChange(): IValueChange<unknown> | null {
166
+ if (!this.enabled) throw new Error("Dependence is turned off - you cannot extract its state!")
167
+ if (!this.#pendingChange) return null
168
+ return { increment: this.#pendingChange, decrement: this.#committedState }
169
+ }
170
+
171
+ /**
172
+ * Commits the last pending value, making it the new reference state.
173
+ *
174
+ * @throws If the buffer is disabled or there's nothing to commit.
175
+ */
176
+ public commitState() {
177
+ if (this.#pendingChange === undefined) throw new Error("Dependence is turned off - you cannot commit its state!")
178
+ this.#committedState = this.#pendingChange
179
+ this.#pendingChange = undefined
180
+ }
181
+
182
+ /**
183
+ * Returns the last committed value container.
184
+ *
185
+ * @returns `{ value }` if committed, or `null` if never committed.
186
+ * @throws If the buffer is disabled.
187
+ */
188
+ public getCommittedState() {
189
+ if (!this.enabled) throw new Error("Dependence is turned off - you cannot extract its state!")
190
+ if (!this.#committedState) return null
191
+ return this.#committedState
192
+ }
193
+ }
@@ -0,0 +1,19 @@
1
+ import { MaybePromise } from "#typescript/maybe-promise.type.js"
2
+ import { ISetChanges, TInputSetChanges } from "../../../_common/set-changes.interface.js"
3
+
4
+ /**
5
+ * A resolver function used to convert changes from a `$Set` dependency
6
+ * into a delta that should be applied to the result set.
7
+ *
8
+ * @template TContext The resolved values of all dependencies.
9
+ * @template TSource The type of values in the dependency source.
10
+ * @template TResult The type of values in the resulting set.
11
+ *
12
+ * @remarks
13
+ * The resolver may use each `TSource` value as a *projective key* — not just a value to test.
14
+ * This allows transformation, correlation, or expansion into multiple result values.
15
+ */
16
+ export type TDependencySetResolver<TContext extends Record<string, any> = Record<string, any>, TSource = any, TResult = any> = (
17
+ context: TContext,
18
+ changes: ISetChanges<TSource>,
19
+ ) => MaybePromise<TInputSetChanges<TResult>>