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
package/.commitlintrc
ADDED
package/.editorconfig
ADDED
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
# EditorConfig is awesome: https://EditorConfig.org
|
|
2
|
+
|
|
3
|
+
# top-most EditorConfig file
|
|
4
|
+
root = true
|
|
5
|
+
|
|
6
|
+
[*]
|
|
7
|
+
indent_style = space
|
|
8
|
+
indent_size = 4
|
|
9
|
+
end_of_line = lf
|
|
10
|
+
charset = utf-8
|
|
11
|
+
trim_trailing_whitespace = true
|
|
12
|
+
insert_final_newline = false
|
|
13
|
+
|
|
14
|
+
# 2 space indentation for all .yml files
|
|
15
|
+
[*.yml]
|
|
16
|
+
indent_style = space
|
|
17
|
+
indent_size = 2
|
package/.gitattributes
ADDED
|
@@ -0,0 +1,48 @@
|
|
|
1
|
+
name: Check Code
|
|
2
|
+
|
|
3
|
+
permissions:
|
|
4
|
+
contents: read # access to check out code and install dependencies
|
|
5
|
+
|
|
6
|
+
on:
|
|
7
|
+
push:
|
|
8
|
+
branches: [main]
|
|
9
|
+
pull_request:
|
|
10
|
+
branches: [main]
|
|
11
|
+
|
|
12
|
+
jobs:
|
|
13
|
+
node-install:
|
|
14
|
+
name: Prepare NPM Cache
|
|
15
|
+
runs-on: ubuntu-latest
|
|
16
|
+
steps:
|
|
17
|
+
- uses: actions/checkout@v4
|
|
18
|
+
- uses: actions/setup-node@v4
|
|
19
|
+
with:
|
|
20
|
+
node-version: 20
|
|
21
|
+
cache: "npm"
|
|
22
|
+
- run: npm ci
|
|
23
|
+
|
|
24
|
+
prettier:
|
|
25
|
+
name: Check Formatting
|
|
26
|
+
needs: node-install
|
|
27
|
+
runs-on: ubuntu-latest
|
|
28
|
+
steps:
|
|
29
|
+
- uses: actions/checkout@v4
|
|
30
|
+
- uses: actions/setup-node@v4
|
|
31
|
+
with:
|
|
32
|
+
node-version: 20
|
|
33
|
+
cache: "npm"
|
|
34
|
+
- run: npm ci
|
|
35
|
+
- run: npm run prettier:check
|
|
36
|
+
|
|
37
|
+
typescript:
|
|
38
|
+
name: Check Types
|
|
39
|
+
needs: node-install
|
|
40
|
+
runs-on: ubuntu-latest
|
|
41
|
+
steps:
|
|
42
|
+
- uses: actions/checkout@v4
|
|
43
|
+
- uses: actions/setup-node@v4
|
|
44
|
+
with:
|
|
45
|
+
node-version: 20
|
|
46
|
+
cache: "npm"
|
|
47
|
+
- run: npm ci
|
|
48
|
+
- run: npm run typescript:check
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
name: Lint Commit
|
|
2
|
+
|
|
3
|
+
on: [pull_request]
|
|
4
|
+
|
|
5
|
+
permissions:
|
|
6
|
+
contents: read
|
|
7
|
+
pull-requests: read
|
|
8
|
+
|
|
9
|
+
jobs:
|
|
10
|
+
main:
|
|
11
|
+
name: Lint Commit Message
|
|
12
|
+
runs-on: ubuntu-latest
|
|
13
|
+
steps:
|
|
14
|
+
- uses: actions/checkout@v4
|
|
15
|
+
- uses: wagoid/commitlint-github-action@v6
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
name: Lint Request
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
pull_request_target:
|
|
5
|
+
types:
|
|
6
|
+
- opened
|
|
7
|
+
- edited
|
|
8
|
+
- reopened
|
|
9
|
+
|
|
10
|
+
jobs:
|
|
11
|
+
main:
|
|
12
|
+
name: Validate PR Title
|
|
13
|
+
runs-on: ubuntu-latest
|
|
14
|
+
permissions:
|
|
15
|
+
pull-requests: read
|
|
16
|
+
steps:
|
|
17
|
+
- uses: amannn/action-semantic-pull-request@v5
|
|
18
|
+
env:
|
|
19
|
+
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
name: Release Job
|
|
2
|
+
|
|
3
|
+
on:
|
|
4
|
+
push:
|
|
5
|
+
branches:
|
|
6
|
+
- main
|
|
7
|
+
|
|
8
|
+
permissions:
|
|
9
|
+
id-token: write # Required for OIDC
|
|
10
|
+
contents: write
|
|
11
|
+
pull-requests: write
|
|
12
|
+
issues: write
|
|
13
|
+
|
|
14
|
+
jobs:
|
|
15
|
+
main:
|
|
16
|
+
runs-on: ubuntu-latest
|
|
17
|
+
environment: npm-publish
|
|
18
|
+
steps:
|
|
19
|
+
- uses: googleapis/release-please-action@v4
|
|
20
|
+
id: release
|
|
21
|
+
with:
|
|
22
|
+
release-type: node
|
|
23
|
+
|
|
24
|
+
- # these if statements ensure that a publication only occurs when a new release is created:
|
|
25
|
+
if: ${{ steps.release.outputs.release_created }}
|
|
26
|
+
uses: actions/checkout@v4
|
|
27
|
+
|
|
28
|
+
- name: Tag Major/Minor Versions
|
|
29
|
+
# these if statements ensure that a publication only occurs when a new release is created:
|
|
30
|
+
if: ${{ steps.release.outputs.release_created }}
|
|
31
|
+
run: |
|
|
32
|
+
git config user.name github-actions[bot]
|
|
33
|
+
git config user.email 41898282+github-actions[bot]@users.noreply.github.com
|
|
34
|
+
git remote add gh-token "https://${{ secrets.GITHUB_TOKEN }}@github.com/googleapis/release-please-action.git"
|
|
35
|
+
git tag -d v${{ steps.release.outputs.major }} || true
|
|
36
|
+
git tag -d v${{ steps.release.outputs.major }}.${{ steps.release.outputs.minor }} || true
|
|
37
|
+
git push origin :v${{ steps.release.outputs.major }} || true
|
|
38
|
+
git push origin :v${{ steps.release.outputs.major }}.${{ steps.release.outputs.minor }} || true
|
|
39
|
+
git tag -a v${{ steps.release.outputs.major }} -m "Release v${{ steps.release.outputs.major }}"
|
|
40
|
+
git tag -a v${{ steps.release.outputs.major }}.${{ steps.release.outputs.minor }} -m "Release v${{ steps.release.outputs.major }}.${{ steps.release.outputs.minor }}"
|
|
41
|
+
git push origin v${{ steps.release.outputs.major }}
|
|
42
|
+
git push origin v${{ steps.release.outputs.major }}.${{ steps.release.outputs.minor }}
|
|
43
|
+
|
|
44
|
+
- name: Publish To NPM
|
|
45
|
+
# these if statements ensure that a publication only occurs when a new release is created:
|
|
46
|
+
if: ${{ steps.release.outputs.release_created }}
|
|
47
|
+
uses: actions/setup-node@v4
|
|
48
|
+
with:
|
|
49
|
+
node-version: 20
|
|
50
|
+
- name: Publish To NPM
|
|
51
|
+
# these if statements ensure that a publication only occurs when a new release is created:
|
|
52
|
+
if: ${{ steps.release.outputs.release_created }}
|
|
53
|
+
# Ensure npm 11.5.1 or later is installed
|
|
54
|
+
run: npm install -g npm@latest
|
|
55
|
+
- name: Publish To NPM
|
|
56
|
+
# these if statements ensure that a publication only occurs when a new release is created:
|
|
57
|
+
if: ${{ steps.release.outputs.release_created }}
|
|
58
|
+
run: npm ci
|
|
59
|
+
- name: Publish To NPM
|
|
60
|
+
# these if statements ensure that a publication only occurs when a new release is created:
|
|
61
|
+
if: ${{ steps.release.outputs.release_created }}
|
|
62
|
+
run: npm publish
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
#!/bin/sh
|
|
2
|
+
|
|
3
|
+
GIT_BASH_PATH="/c/Program Files/Git/usr/bin"
|
|
4
|
+
NPM_PATH="/c/Program Files/nodejs/npm.cmd"
|
|
5
|
+
|
|
6
|
+
# Temporarily add Git Bash to PATH if it's not already in the PATH
|
|
7
|
+
if ! command -v bash &> /dev/null; then
|
|
8
|
+
export PATH="$PATH:$GIT_BASH_PATH"
|
|
9
|
+
fi
|
|
10
|
+
|
|
11
|
+
commitlint --edit $1
|
|
12
|
+
|
|
13
|
+
# Direct run NPM if it's not in the PATH
|
|
14
|
+
if [ -f "$NPM_PATH" ]; then
|
|
15
|
+
"$NPM_PATH" run typescript:check
|
|
16
|
+
else
|
|
17
|
+
npm run typescript:check
|
|
18
|
+
fi
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
#!/bin/sh
|
|
2
|
+
|
|
3
|
+
GIT_BASH_PATH="/c/Program Files/Git/usr/bin"
|
|
4
|
+
NPM_PATH="/c/Program Files/nodejs/npm.cmd"
|
|
5
|
+
|
|
6
|
+
# Temporarily add Git Bash to PATH if it's not already in the PATH
|
|
7
|
+
if ! command -v bash &> /dev/null; then
|
|
8
|
+
export PATH="$PATH:$GIT_BASH_PATH"
|
|
9
|
+
fi
|
|
10
|
+
|
|
11
|
+
# Direct run NPM if it's not in the PATH
|
|
12
|
+
if [ -f "$NPM_PATH" ]; then
|
|
13
|
+
"$NPM_PATH" run prettier:write -- --no-color
|
|
14
|
+
else
|
|
15
|
+
npm run prettier:write -- --no-color
|
|
16
|
+
fi
|
|
17
|
+
|
|
18
|
+
git add -u
|
package/.prettierignore
ADDED
package/.prettierrc
ADDED
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
{
|
|
2
|
+
"files.eol": "\n",
|
|
3
|
+
"javascript.format.semicolons": "remove",
|
|
4
|
+
"typescript.format.semicolons": "remove",
|
|
5
|
+
"[json]": {
|
|
6
|
+
"editor.defaultFormatter": "esbenp.prettier-vscode"
|
|
7
|
+
},
|
|
8
|
+
"[jsonc]": {
|
|
9
|
+
"editor.defaultFormatter": "esbenp.prettier-vscode"
|
|
10
|
+
},
|
|
11
|
+
"[javascript]": {
|
|
12
|
+
"editor.defaultFormatter": "esbenp.prettier-vscode"
|
|
13
|
+
},
|
|
14
|
+
"[typescript]": {
|
|
15
|
+
"editor.defaultFormatter": "esbenp.prettier-vscode"
|
|
16
|
+
},
|
|
17
|
+
"[markdown]": {
|
|
18
|
+
"editor.defaultFormatter": "esbenp.prettier-vscode"
|
|
19
|
+
},
|
|
20
|
+
"prettier.semi": false,
|
|
21
|
+
"task.allowAutomaticTasks": "on",
|
|
22
|
+
"typescript.tsdk": "node_modules/typescript/lib",
|
|
23
|
+
// windows task manager fix
|
|
24
|
+
"terminal.integrated.automationProfile.windows": {
|
|
25
|
+
"path": "C:/Windows/System32/cmd.exe"
|
|
26
|
+
}
|
|
27
|
+
}
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
{
|
|
2
|
+
"version": "2.0.0",
|
|
3
|
+
"tasks": [
|
|
4
|
+
{
|
|
5
|
+
"type": "typescript",
|
|
6
|
+
"tsconfig": "tsconfig.json",
|
|
7
|
+
"option": "watch",
|
|
8
|
+
"problemMatcher": ["$tsc-watch"],
|
|
9
|
+
"group": "build",
|
|
10
|
+
"label": "Typescript Compiler",
|
|
11
|
+
"runOptions": {
|
|
12
|
+
"runOn": "folderOpen"
|
|
13
|
+
},
|
|
14
|
+
"presentation": {
|
|
15
|
+
"echo": true,
|
|
16
|
+
"reveal": "never",
|
|
17
|
+
"revealProblems": "never",
|
|
18
|
+
"focus": false,
|
|
19
|
+
"panel": "shared",
|
|
20
|
+
"showReuseMessage": true,
|
|
21
|
+
"clear": true
|
|
22
|
+
}
|
|
23
|
+
}
|
|
24
|
+
]
|
|
25
|
+
}
|
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
# Changelog
|
package/CONTRIBUTING.md
ADDED
|
@@ -0,0 +1,116 @@
|
|
|
1
|
+
# Contributing
|
|
2
|
+
|
|
3
|
+
This project uses a modular and declarative approach to reactive state modeling. Contributions should follow the existing architectural principles and naming conventions.
|
|
4
|
+
|
|
5
|
+
## Guidelines
|
|
6
|
+
|
|
7
|
+
- **Favor composability**: use primitives that compose cleanly (e.g. `$Set`, `$Value`, `$Intersection`).
|
|
8
|
+
- **Use explicit projection**: all transformation logic should be placed inside `resolver()` functions, not inline.
|
|
9
|
+
- **Respect read-only boundaries**: all derived sets must be immutable from the outside.
|
|
10
|
+
- **Avoid entanglement**: prefer isolated reactive nodes and explicit connections between them.
|
|
11
|
+
|
|
12
|
+
## Internal Structure
|
|
13
|
+
|
|
14
|
+
The system is composed of core reactive types:
|
|
15
|
+
|
|
16
|
+
- `$Value<T>`: reactive container for a single value
|
|
17
|
+
- `$Set<T>`: reactive observable Set<T>
|
|
18
|
+
- `$Combination<T>`: abstract base for derived reactive sets
|
|
19
|
+
|
|
20
|
+
The system also supports composition tools like:
|
|
21
|
+
|
|
22
|
+
- `$Intersection`
|
|
23
|
+
- `$Union`
|
|
24
|
+
- `$Difference`
|
|
25
|
+
- Projection-based operators (see below)
|
|
26
|
+
|
|
27
|
+
---
|
|
28
|
+
|
|
29
|
+
## ๐งญ Projection-Based Derived Sets
|
|
30
|
+
|
|
31
|
+
Projection sets derive their contents from a **superset** and a set of **relation keys**, using a custom `resolver()` function.
|
|
32
|
+
|
|
33
|
+
These keys are not filtered against the superset directly. Instead, each key is **projected** into one or more values from the superset via the resolver. This enables reactive relationships such as:
|
|
34
|
+
|
|
35
|
+
- tags โ items
|
|
36
|
+
- roles โ permissions
|
|
37
|
+
- categories โ associated content
|
|
38
|
+
|
|
39
|
+
### Core concepts:
|
|
40
|
+
|
|
41
|
+
| Concept | Meaning |
|
|
42
|
+
| --------------- | --------------------------------------------------------------------- |
|
|
43
|
+
| Superset | The source set of all possible values |
|
|
44
|
+
| Relation keys | Keys that drive projection; can be a `$Value<T>` or `$Set<T>` |
|
|
45
|
+
| Resolver | Function mapping relation keys to projected values |
|
|
46
|
+
| Mask (optional) | If used (`complement`), excludes the projected values from the result |
|
|
47
|
+
| Result | `$Set<TResult>` that includes or excludes projected values reactively |
|
|
48
|
+
|
|
49
|
+
### Supported patterns:
|
|
50
|
+
|
|
51
|
+
| Class | Description | Projection Source | Masking |
|
|
52
|
+
| ------------------- | -------------------------------------- | ----------------- | ------- |
|
|
53
|
+
| `$SubsetViaVal` | one key โ values to include | `$Value<T>` | No |
|
|
54
|
+
| `$SubsetViaSet` | many keys โ union of values to include | `$Set<T>` | No |
|
|
55
|
+
| `$ComplementViaVal` | one key โ values to exclude | `$Value<T>` | Yes |
|
|
56
|
+
| `$ComplementViaSet` | many keys โ union of values to exclude | `$Set<T>` | Yes |
|
|
57
|
+
| `$SetFromSet` | delta โ transformed delta | `$Set<T>` | No |
|
|
58
|
+
|
|
59
|
+
Resolvers must handle changes incrementally and support projection semantics. Values in the relation input are **not** result values โ they are _keys to compute with_.
|
|
60
|
+
|
|
61
|
+
---
|
|
62
|
+
|
|
63
|
+
## ๐ Synchronization and Delta Buffers
|
|
64
|
+
|
|
65
|
+
Reactive projection sets use internal delta buffers to accumulate uncommitted changes from their dependencies. These are represented by `DeltaBufferForSet` and `DeltaBufferForValue`.
|
|
66
|
+
|
|
67
|
+
Each buffer tracks:
|
|
68
|
+
|
|
69
|
+
- The last committed state
|
|
70
|
+
- The current uncommitted (pending) changes
|
|
71
|
+
- Emits `.onChange` when pending state changes
|
|
72
|
+
|
|
73
|
+
A `synchronize()` loop iterates over all active buffers, resolves the next pending delta via the `resolver()`, commits the result, and repeats until no further deltas are detected.
|
|
74
|
+
|
|
75
|
+
This model ensures:
|
|
76
|
+
|
|
77
|
+
- Asynchronous-safe updates
|
|
78
|
+
- Deterministic reactivity
|
|
79
|
+
- Efficient batching
|
|
80
|
+
|
|
81
|
+
---
|
|
82
|
+
|
|
83
|
+
## ๐งฉ Architectural Roadmap
|
|
84
|
+
|
|
85
|
+
The current architecture relies on specialized subclasses like `$SubsetViaSet`, `$ComplementViaVal`, etc.
|
|
86
|
+
We plan to:
|
|
87
|
+
|
|
88
|
+
- **Generalize projection logic** across value- and set-based dependencies.
|
|
89
|
+
- **Extract cascade propagation** into a dedicated coordination layer to allow priority control.
|
|
90
|
+
- **Modularize node activation/deactivation**, allowing better lifecycle tracking and isolation.
|
|
91
|
+
- **Split user-side effects** from core propagation to optimize dependency traversal.
|
|
92
|
+
|
|
93
|
+
All contributors are encouraged to keep these directions in mind and submit helpers or refactors that support this direction.
|
|
94
|
+
|
|
95
|
+
## ๐ Architectural References
|
|
96
|
+
|
|
97
|
+
This reactive model borrows from:
|
|
98
|
+
|
|
99
|
+
- **Projectional transformation** (graph queries, RDB joins)
|
|
100
|
+
- **Incremental computation** (dataflow graphs, spreadsheet logic)
|
|
101
|
+
- **Observer pattern** via `Signal`
|
|
102
|
+
- **CRDT-style overwrite propagation** in overwrite mode
|
|
103
|
+
|
|
104
|
+
All combinators must be:
|
|
105
|
+
|
|
106
|
+
- Pull-based from source
|
|
107
|
+
- Push-updated via `applyChanges()`
|
|
108
|
+
- Isolation-tolerant (able to disable/re-enable cleanly)
|
|
109
|
+
|
|
110
|
+
---
|
|
111
|
+
|
|
112
|
+
## ๐งช Testing
|
|
113
|
+
|
|
114
|
+
All changes must be accompanied by unit tests for new logic, and regression tests for fixed bugs.
|
|
115
|
+
|
|
116
|
+
Use the existing test harness under `/test` and add specs per feature/module.
|
package/GLOSSARY.md
ADDED
|
@@ -0,0 +1,144 @@
|
|
|
1
|
+
# ๐ง Reactive Glossary
|
|
2
|
+
|
|
3
|
+
This document defines the core concepts and terms used throughout the reactive value system. It serves as a shared vocabulary for library users and contributors.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## ๐ฆ Reactive Value (`$value()`)
|
|
8
|
+
|
|
9
|
+
A reactive scalar wrapper for a single value. Useful when tracking primitive state, object references, or lightweight computed values.
|
|
10
|
+
|
|
11
|
+
- Holds a single `value`.
|
|
12
|
+
- Emits structured change payloads via `.onChange`.
|
|
13
|
+
- Supports transactional batching (`openTransaction`, `closeTransaction`).
|
|
14
|
+
- Exposes `IValueChange<T>`: `{ increment?, decrement? }` where each side is a `IValueContainer<T>`.
|
|
15
|
+
|
|
16
|
+
```ts
|
|
17
|
+
const counter = $value({ value: 0 })
|
|
18
|
+
counter.value = 5 // Triggers onChange if changed
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## ๐งบ Reactive Set (`$set()`)
|
|
24
|
+
|
|
25
|
+
A reactive collection of unique items with fine-grained change tracking.
|
|
26
|
+
|
|
27
|
+
- Wraps standard `Set<T>` behavior.
|
|
28
|
+
- Emits reactive diffs via `.onChange`.
|
|
29
|
+
- Supports batch methods: `batchAdd`, `batchDelete`, `applyChanges`.
|
|
30
|
+
- Supports transactions: `openTransaction`, `closeTransaction`.
|
|
31
|
+
- Emits `ISetChanges<T>` payloads: `{ increment?: Set<T>, decrement?: Set<T> }`
|
|
32
|
+
|
|
33
|
+
```ts
|
|
34
|
+
const $tags = $set({ values: ["a", "b"] })
|
|
35
|
+
$tags.add("c") // Emits increment: Set { 'c' }
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
**Batching options:**
|
|
39
|
+
|
|
40
|
+
- `batchAdd()`, `batchDelete()`, `applyChanges()` โ apply changes immediately.
|
|
41
|
+
- `openTransaction()` / `closeTransaction()` โ delay signaling until complete.
|
|
42
|
+
|
|
43
|
+
---
|
|
44
|
+
|
|
45
|
+
## ๐งฉ Reactive Combinations (`$intersectionSets`, `$unionSets`, `$differenceSets`)
|
|
46
|
+
|
|
47
|
+
Derived sets that compute dynamic relationships between multiple reactive sets.
|
|
48
|
+
|
|
49
|
+
### `Intersection`
|
|
50
|
+
|
|
51
|
+
Includes only values present in **all** subsets.
|
|
52
|
+
|
|
53
|
+
```ts
|
|
54
|
+
$intersectionSets({ subsets: [$a, $b] })
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
### `Union`
|
|
58
|
+
|
|
59
|
+
Includes all values present in **any** subset.
|
|
60
|
+
|
|
61
|
+
```ts
|
|
62
|
+
$unionSets({ subsets: [$a, $b] })
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
### `Difference`
|
|
66
|
+
|
|
67
|
+
Includes values from `superset` that are **not present in any** of the subsets.
|
|
68
|
+
|
|
69
|
+
```ts
|
|
70
|
+
$differenceSets({ superset: $a, subsets: [$b] })
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
Combination sets:
|
|
74
|
+
|
|
75
|
+
- Extend the `$Set<T>` interface.
|
|
76
|
+
- Are automatically updated on any input change.
|
|
77
|
+
- Are strictly `readonly`: they reflect upstream state.
|
|
78
|
+
- Can be enabled or disabled (reactively toggled).
|
|
79
|
+
|
|
80
|
+
They are implemented using the abstract base classes `$Combination<T>` and `$VariadicCombination<T>`.
|
|
81
|
+
|
|
82
|
+
---
|
|
83
|
+
|
|
84
|
+
## ๐งญ Projection-Based Sets
|
|
85
|
+
|
|
86
|
+
Projection-based sets are derived sets whose contents are computed by applying a user-defined projection function (`resolver`) to one or more **relation keys**.
|
|
87
|
+
|
|
88
|
+
- These keys can come from either a `$Value<T>` (one key) or a `$Set<T>` (many keys).
|
|
89
|
+
- The `resolver()` maps keys to values in the `superset`.
|
|
90
|
+
- The `superset` always acts as a **mask**, ensuring the final result remains a subset of it.
|
|
91
|
+
- Optionally, the projection can be **excluded** (masked out) from the result โ forming a complement.
|
|
92
|
+
|
|
93
|
+
These sets include:
|
|
94
|
+
|
|
95
|
+
| Class | Keys from | Projection to | Result type | Masked? |
|
|
96
|
+
| ------------------- | --------------- | -------------------- | ---------------------- | ------- |
|
|
97
|
+
| `$SubsetViaVal` | `$Value<T>` | included values | subset of superset | Yes |
|
|
98
|
+
| `$SubsetViaSet` | `$Set<T>` | union of projections | subset of superset | Yes |
|
|
99
|
+
| `$ComplementViaVal` | `$Value<T>` | values to exclude | complement of superset | Yes |
|
|
100
|
+
| `$ComplementViaSet` | `$Set<T>` | values to exclude | complement of superset | Yes |
|
|
101
|
+
| `$SetFromSet` | `$Set<TSource>` | delta-mapped values | arbitrary projection | No |
|
|
102
|
+
|
|
103
|
+
### Glossary terms
|
|
104
|
+
|
|
105
|
+
- **Superset** โ The source of all candidate values.
|
|
106
|
+
- **Relation key** โ An input value used to drive projection.
|
|
107
|
+
- **Resolver** โ A function that projects relation keys into result values.
|
|
108
|
+
- **Projection** โ The mapping from key(s) to included or excluded values.
|
|
109
|
+
- **Mask** โ A filtering constraint applied over the superset; ensures result โ superset.
|
|
110
|
+
- **Complement** โ A projection that removes its result from the superset.
|
|
111
|
+
|
|
112
|
+
Projection-based sets are fully reactive, readonly, and synchronized using internal delta buffers.
|
|
113
|
+
|
|
114
|
+
---
|
|
115
|
+
|
|
116
|
+
## ๐ Signals & Reactivity
|
|
117
|
+
|
|
118
|
+
All reactive entities emit events through signals.
|
|
119
|
+
|
|
120
|
+
- Signals are exposed via `.onChange`, `.onSwitch`, etc.
|
|
121
|
+
- Subscriptions are registered using `.subscribe(handler, { signal })`.
|
|
122
|
+
- Subscriptions can be cancelled via `AbortController`.
|
|
123
|
+
|
|
124
|
+
```ts
|
|
125
|
+
const controller = new AbortController()
|
|
126
|
+
$set.onChange.subscribe(
|
|
127
|
+
({ increment }) => {
|
|
128
|
+
console.log(increment)
|
|
129
|
+
},
|
|
130
|
+
{ signal: controller.signal },
|
|
131
|
+
)
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
---
|
|
135
|
+
|
|
136
|
+
## ๐ Core Change Payload Types
|
|
137
|
+
|
|
138
|
+
| Type | Description |
|
|
139
|
+
| --------------------- | -------------------------------------------------------------------- |
|
|
140
|
+
| `ISetChanges<T>` | `{ increment?: Set<T>, decrement?: Set<T> }` |
|
|
141
|
+
| `IValueChange<T>` | `{ increment?: IValueContainer<T>, decrement?: IValueContainer<T> }` |
|
|
142
|
+
| `IOverwriteChange<T>` | `{ overwrite: T }` |
|
|
143
|
+
|
|
144
|
+
These are used across `.onChange` signals and `applyChanges()` methods.
|
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 Tomoe
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|