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
package/.commitlintrc ADDED
@@ -0,0 +1,2 @@
1
+ extends:
2
+ - '@commitlint/config-conventional'
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,2 @@
1
+ # Auto detect text files and perform LF normalization
2
+ * text=auto eol=lf
@@ -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
@@ -0,0 +1,2 @@
1
+ tsconfig.json
2
+ CHANGELOG.md
package/.prettierrc ADDED
@@ -0,0 +1,9 @@
1
+ {
2
+ "experimentalTernaries": true,
3
+ "printWidth": 160,
4
+ "semi": false,
5
+ "singleQuote": false,
6
+ "bracketSameLine": false,
7
+ "endOfLine": "lf",
8
+ "quoteProps": "consistent"
9
+ }
@@ -0,0 +1,3 @@
1
+ {
2
+ "recommendations": ["editorconfig.editorconfig", "esbenp.prettier-vscode", "github.vscode-github-actions", "vivaxy.vscode-conventional-commits"]
3
+ }
@@ -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
@@ -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.