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,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>>
|