@shadow-js/core 0.1.0 → 1.0.1
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/CHANGELOG.md +17 -0
- package/LICENSE +2 -2
- package/README.md +134 -331
- package/dist/dev/action.d.ts +34 -0
- package/dist/dev/action.js +89 -0
- package/dist/dev/action.js.map +1 -0
- package/dist/dev/cache.d.ts +33 -0
- package/dist/dev/cache.js +61 -0
- package/dist/dev/cache.js.map +1 -0
- package/dist/dev/context.d.ts +104 -0
- package/dist/dev/context.js +110 -0
- package/dist/dev/context.js.map +1 -0
- package/dist/dev/effect.d.ts +120 -0
- package/dist/dev/effect.js +110 -0
- package/dist/dev/effect.js.map +1 -0
- package/dist/dev/env.d.ts +27 -0
- package/dist/dev/env.js +30 -0
- package/dist/dev/env.js.map +1 -0
- package/dist/dev/events.d.ts +26 -0
- package/dist/dev/events.js +32 -0
- package/dist/dev/events.js.map +1 -0
- package/dist/dev/extend/index.d.ts +329 -0
- package/dist/dev/extend/index.js +316 -0
- package/dist/dev/extend/index.js.map +1 -0
- package/dist/dev/external-store.d.ts +58 -0
- package/dist/dev/external-store.js +59 -0
- package/dist/dev/external-store.js.map +1 -0
- package/dist/dev/index.d.ts +29 -0
- package/dist/dev/index.js +26 -0
- package/dist/dev/internal/concurrency.d.ts +211 -0
- package/dist/dev/internal/concurrency.js +631 -0
- package/dist/dev/internal/concurrency.js.map +1 -0
- package/dist/dev/internal/devtools.d.ts +69 -0
- package/dist/dev/internal/devtools.js +76 -0
- package/dist/dev/internal/devtools.js.map +1 -0
- package/dist/dev/internal/diagnostics.d.ts +88 -0
- package/dist/dev/internal/diagnostics.js +101 -0
- package/dist/dev/internal/diagnostics.js.map +1 -0
- package/dist/dev/internal/dispose.d.ts +26 -0
- package/dist/dev/internal/dispose.js +48 -0
- package/dist/dev/internal/dispose.js.map +1 -0
- package/dist/dev/internal/flags.js +10 -0
- package/dist/dev/internal/flags.js.map +1 -0
- package/dist/dev/internal/graph.d.ts +231 -0
- package/dist/dev/internal/graph.js +577 -0
- package/dist/dev/internal/graph.js.map +1 -0
- package/dist/dev/internal/hydration-flag.d.ts +31 -0
- package/dist/dev/internal/hydration-flag.js +45 -0
- package/dist/dev/internal/hydration-flag.js.map +1 -0
- package/dist/dev/internal/messages.d.ts +54 -0
- package/dist/dev/internal/messages.js +53 -0
- package/dist/dev/internal/messages.js.map +1 -0
- package/dist/dev/internal/owner.d.ts +140 -0
- package/dist/dev/internal/owner.js +289 -0
- package/dist/dev/internal/owner.js.map +1 -0
- package/dist/dev/internal/queue.js +45 -0
- package/dist/dev/internal/queue.js.map +1 -0
- package/dist/dev/internal/scheduler.d.ts +111 -0
- package/dist/dev/internal/scheduler.js +286 -0
- package/dist/dev/internal/scheduler.js.map +1 -0
- package/dist/dev/internal/state.d.ts +139 -0
- package/dist/dev/internal/state.js +27 -0
- package/dist/dev/internal/state.js.map +1 -0
- package/dist/dev/internal/suspension.d.ts +41 -0
- package/dist/dev/internal/suspension.js +44 -0
- package/dist/dev/internal/suspension.js.map +1 -0
- package/dist/dev/internal/types.d.ts +44 -0
- package/dist/dev/list.d.ts +91 -0
- package/dist/dev/list.js +281 -0
- package/dist/dev/list.js.map +1 -0
- package/dist/dev/memo.d.ts +58 -0
- package/dist/dev/memo.js +40 -0
- package/dist/dev/memo.js.map +1 -0
- package/dist/dev/optimistic.d.ts +24 -0
- package/dist/dev/optimistic.js +44 -0
- package/dist/dev/optimistic.js.map +1 -0
- package/dist/dev/ownership.d.ts +202 -0
- package/dist/dev/ownership.js +260 -0
- package/dist/dev/ownership.js.map +1 -0
- package/dist/dev/props.d.ts +132 -0
- package/dist/dev/props.js +281 -0
- package/dist/dev/props.js.map +1 -0
- package/dist/dev/reaction.d.ts +27 -0
- package/dist/dev/reaction.js +60 -0
- package/dist/dev/reaction.js.map +1 -0
- package/dist/dev/reducer.d.ts +39 -0
- package/dist/dev/reducer.js +38 -0
- package/dist/dev/reducer.js.map +1 -0
- package/dist/dev/refs.d.ts +50 -0
- package/dist/dev/refs.js +57 -0
- package/dist/dev/refs.js.map +1 -0
- package/dist/dev/resource.d.ts +133 -0
- package/dist/dev/resource.js +176 -0
- package/dist/dev/resource.js.map +1 -0
- package/dist/dev/selector.d.ts +32 -0
- package/dist/dev/selector.js +117 -0
- package/dist/dev/selector.js.map +1 -0
- package/dist/dev/signal.d.ts +40 -0
- package/dist/dev/signal.js +38 -0
- package/dist/dev/signal.js.map +1 -0
- package/dist/dev/store/index.d.ts +5 -0
- package/dist/dev/store/index.js +4 -0
- package/dist/dev/store/nodes.js +191 -0
- package/dist/dev/store/nodes.js.map +1 -0
- package/dist/dev/store/proxies.js +159 -0
- package/dist/dev/store/proxies.js.map +1 -0
- package/dist/dev/store/read.d.ts +37 -0
- package/dist/dev/store/read.js +71 -0
- package/dist/dev/store/read.js.map +1 -0
- package/dist/dev/store/reconcile.d.ts +71 -0
- package/dist/dev/store/reconcile.js +185 -0
- package/dist/dev/store/reconcile.js.map +1 -0
- package/dist/dev/store/types.d.ts +104 -0
- package/dist/dev/store/use-store.d.ts +58 -0
- package/dist/dev/store/use-store.js +167 -0
- package/dist/dev/store/use-store.js.map +1 -0
- package/dist/dev/suspense.d.ts +99 -0
- package/dist/dev/suspense.js +44 -0
- package/dist/dev/suspense.js.map +1 -0
- package/dist/dev/transitions.d.ts +75 -0
- package/dist/dev/transitions.js +100 -0
- package/dist/dev/transitions.js.map +1 -0
- package/dist/prod/action.js +2 -0
- package/dist/prod/action.js.map +1 -0
- package/dist/prod/cache.js +2 -0
- package/dist/prod/cache.js.map +1 -0
- package/dist/prod/context.js +2 -0
- package/dist/prod/context.js.map +1 -0
- package/dist/prod/effect.js +2 -0
- package/dist/prod/effect.js.map +1 -0
- package/dist/prod/env.js +2 -0
- package/dist/prod/env.js.map +1 -0
- package/dist/prod/events.js +2 -0
- package/dist/prod/events.js.map +1 -0
- package/dist/prod/extend/index.js +2 -0
- package/dist/prod/extend/index.js.map +1 -0
- package/dist/prod/external-store.js +2 -0
- package/dist/prod/external-store.js.map +1 -0
- package/dist/prod/index.js +1 -0
- package/dist/prod/internal/concurrency.js +2 -0
- package/dist/prod/internal/concurrency.js.map +1 -0
- package/dist/prod/internal/devtools.js +2 -0
- package/dist/prod/internal/devtools.js.map +1 -0
- package/dist/prod/internal/diagnostics.js +2 -0
- package/dist/prod/internal/diagnostics.js.map +1 -0
- package/dist/prod/internal/dispose.js +2 -0
- package/dist/prod/internal/dispose.js.map +1 -0
- package/dist/prod/internal/flags.js +2 -0
- package/dist/prod/internal/flags.js.map +1 -0
- package/dist/prod/internal/graph.js +2 -0
- package/dist/prod/internal/graph.js.map +1 -0
- package/dist/prod/internal/hydration-flag.js +2 -0
- package/dist/prod/internal/hydration-flag.js.map +1 -0
- package/dist/prod/internal/messages.js +2 -0
- package/dist/prod/internal/messages.js.map +1 -0
- package/dist/prod/internal/owner.js +2 -0
- package/dist/prod/internal/owner.js.map +1 -0
- package/dist/prod/internal/queue.js +2 -0
- package/dist/prod/internal/queue.js.map +1 -0
- package/dist/prod/internal/scheduler.js +2 -0
- package/dist/prod/internal/scheduler.js.map +1 -0
- package/dist/prod/internal/state.js +2 -0
- package/dist/prod/internal/state.js.map +1 -0
- package/dist/prod/internal/suspension.js +2 -0
- package/dist/prod/internal/suspension.js.map +1 -0
- package/dist/prod/list.js +2 -0
- package/dist/prod/list.js.map +1 -0
- package/dist/prod/memo.js +2 -0
- package/dist/prod/memo.js.map +1 -0
- package/dist/prod/optimistic.js +2 -0
- package/dist/prod/optimistic.js.map +1 -0
- package/dist/prod/ownership.js +2 -0
- package/dist/prod/ownership.js.map +1 -0
- package/dist/prod/props.js +2 -0
- package/dist/prod/props.js.map +1 -0
- package/dist/prod/reaction.js +2 -0
- package/dist/prod/reaction.js.map +1 -0
- package/dist/prod/reducer.js +2 -0
- package/dist/prod/reducer.js.map +1 -0
- package/dist/prod/refs.js +2 -0
- package/dist/prod/refs.js.map +1 -0
- package/dist/prod/resource.js +2 -0
- package/dist/prod/resource.js.map +1 -0
- package/dist/prod/selector.js +2 -0
- package/dist/prod/selector.js.map +1 -0
- package/dist/prod/signal.js +2 -0
- package/dist/prod/signal.js.map +1 -0
- package/dist/prod/store/index.js +1 -0
- package/dist/prod/store/nodes.js +2 -0
- package/dist/prod/store/nodes.js.map +1 -0
- package/dist/prod/store/proxies.js +2 -0
- package/dist/prod/store/proxies.js.map +1 -0
- package/dist/prod/store/read.js +2 -0
- package/dist/prod/store/read.js.map +1 -0
- package/dist/prod/store/reconcile.js +2 -0
- package/dist/prod/store/reconcile.js.map +1 -0
- package/dist/prod/store/use-store.js +2 -0
- package/dist/prod/store/use-store.js.map +1 -0
- package/dist/prod/suspense.js +2 -0
- package/dist/prod/suspense.js.map +1 -0
- package/dist/prod/transitions.js +2 -0
- package/dist/prod/transitions.js.map +1 -0
- package/dist/server/action.js +2 -0
- package/dist/server/action.js.map +1 -0
- package/dist/server/cache.js +2 -0
- package/dist/server/cache.js.map +1 -0
- package/dist/server/context.js +2 -0
- package/dist/server/context.js.map +1 -0
- package/dist/server/effect.js +2 -0
- package/dist/server/effect.js.map +1 -0
- package/dist/server/env.js +2 -0
- package/dist/server/env.js.map +1 -0
- package/dist/server/events.js +2 -0
- package/dist/server/events.js.map +1 -0
- package/dist/server/extend/index.js +2 -0
- package/dist/server/extend/index.js.map +1 -0
- package/dist/server/external-store.js +2 -0
- package/dist/server/external-store.js.map +1 -0
- package/dist/server/index.js +1 -0
- package/dist/server/internal/concurrency.js +2 -0
- package/dist/server/internal/concurrency.js.map +1 -0
- package/dist/server/internal/devtools.js +2 -0
- package/dist/server/internal/devtools.js.map +1 -0
- package/dist/server/internal/diagnostics.js +2 -0
- package/dist/server/internal/diagnostics.js.map +1 -0
- package/dist/server/internal/dispose.js +2 -0
- package/dist/server/internal/dispose.js.map +1 -0
- package/dist/server/internal/flags.js +2 -0
- package/dist/server/internal/flags.js.map +1 -0
- package/dist/server/internal/graph.js +2 -0
- package/dist/server/internal/graph.js.map +1 -0
- package/dist/server/internal/hydration-flag.js +2 -0
- package/dist/server/internal/hydration-flag.js.map +1 -0
- package/dist/server/internal/messages.js +2 -0
- package/dist/server/internal/messages.js.map +1 -0
- package/dist/server/internal/owner.js +2 -0
- package/dist/server/internal/owner.js.map +1 -0
- package/dist/server/internal/queue.js +2 -0
- package/dist/server/internal/queue.js.map +1 -0
- package/dist/server/internal/scheduler.js +2 -0
- package/dist/server/internal/scheduler.js.map +1 -0
- package/dist/server/internal/state.js +2 -0
- package/dist/server/internal/state.js.map +1 -0
- package/dist/server/internal/suspension.js +2 -0
- package/dist/server/internal/suspension.js.map +1 -0
- package/dist/server/list.js +2 -0
- package/dist/server/list.js.map +1 -0
- package/dist/server/memo.js +2 -0
- package/dist/server/memo.js.map +1 -0
- package/dist/server/optimistic.js +2 -0
- package/dist/server/optimistic.js.map +1 -0
- package/dist/server/ownership.js +2 -0
- package/dist/server/ownership.js.map +1 -0
- package/dist/server/props.js +2 -0
- package/dist/server/props.js.map +1 -0
- package/dist/server/reaction.js +2 -0
- package/dist/server/reaction.js.map +1 -0
- package/dist/server/reducer.js +2 -0
- package/dist/server/reducer.js.map +1 -0
- package/dist/server/refs.js +2 -0
- package/dist/server/refs.js.map +1 -0
- package/dist/server/resource.js +2 -0
- package/dist/server/resource.js.map +1 -0
- package/dist/server/selector.js +2 -0
- package/dist/server/selector.js.map +1 -0
- package/dist/server/signal.js +2 -0
- package/dist/server/signal.js.map +1 -0
- package/dist/server/store/index.js +1 -0
- package/dist/server/store/nodes.js +2 -0
- package/dist/server/store/nodes.js.map +1 -0
- package/dist/server/store/proxies.js +2 -0
- package/dist/server/store/proxies.js.map +1 -0
- package/dist/server/store/read.js +2 -0
- package/dist/server/store/read.js.map +1 -0
- package/dist/server/store/reconcile.js +2 -0
- package/dist/server/store/reconcile.js.map +1 -0
- package/dist/server/store/use-store.js +2 -0
- package/dist/server/store/use-store.js.map +1 -0
- package/dist/server/suspense.js +2 -0
- package/dist/server/suspense.js.map +1 -0
- package/dist/server/transitions.js +2 -0
- package/dist/server/transitions.js.map +1 -0
- package/dist/server-dev/action.js +89 -0
- package/dist/server-dev/action.js.map +1 -0
- package/dist/server-dev/cache.js +61 -0
- package/dist/server-dev/cache.js.map +1 -0
- package/dist/server-dev/context.js +107 -0
- package/dist/server-dev/context.js.map +1 -0
- package/dist/server-dev/effect.js +55 -0
- package/dist/server-dev/effect.js.map +1 -0
- package/dist/server-dev/env.js +30 -0
- package/dist/server-dev/env.js.map +1 -0
- package/dist/server-dev/events.js +32 -0
- package/dist/server-dev/events.js.map +1 -0
- package/dist/server-dev/extend/index.js +316 -0
- package/dist/server-dev/extend/index.js.map +1 -0
- package/dist/server-dev/external-store.js +45 -0
- package/dist/server-dev/external-store.js.map +1 -0
- package/dist/server-dev/index.js +26 -0
- package/dist/server-dev/internal/concurrency.js +632 -0
- package/dist/server-dev/internal/concurrency.js.map +1 -0
- package/dist/server-dev/internal/devtools.js +76 -0
- package/dist/server-dev/internal/devtools.js.map +1 -0
- package/dist/server-dev/internal/diagnostics.js +101 -0
- package/dist/server-dev/internal/diagnostics.js.map +1 -0
- package/dist/server-dev/internal/dispose.js +48 -0
- package/dist/server-dev/internal/dispose.js.map +1 -0
- package/dist/server-dev/internal/flags.js +10 -0
- package/dist/server-dev/internal/flags.js.map +1 -0
- package/dist/server-dev/internal/graph.js +577 -0
- package/dist/server-dev/internal/graph.js.map +1 -0
- package/dist/server-dev/internal/hydration-flag.js +45 -0
- package/dist/server-dev/internal/hydration-flag.js.map +1 -0
- package/dist/server-dev/internal/messages.js +53 -0
- package/dist/server-dev/internal/messages.js.map +1 -0
- package/dist/server-dev/internal/owner.js +289 -0
- package/dist/server-dev/internal/owner.js.map +1 -0
- package/dist/server-dev/internal/queue.js +45 -0
- package/dist/server-dev/internal/queue.js.map +1 -0
- package/dist/server-dev/internal/scheduler.js +286 -0
- package/dist/server-dev/internal/scheduler.js.map +1 -0
- package/dist/server-dev/internal/state.js +27 -0
- package/dist/server-dev/internal/state.js.map +1 -0
- package/dist/server-dev/internal/suspension.js +44 -0
- package/dist/server-dev/internal/suspension.js.map +1 -0
- package/dist/server-dev/list.js +281 -0
- package/dist/server-dev/list.js.map +1 -0
- package/dist/server-dev/memo.js +40 -0
- package/dist/server-dev/memo.js.map +1 -0
- package/dist/server-dev/optimistic.js +44 -0
- package/dist/server-dev/optimistic.js.map +1 -0
- package/dist/server-dev/ownership.js +260 -0
- package/dist/server-dev/ownership.js.map +1 -0
- package/dist/server-dev/props.js +281 -0
- package/dist/server-dev/props.js.map +1 -0
- package/dist/server-dev/reaction.js +60 -0
- package/dist/server-dev/reaction.js.map +1 -0
- package/dist/server-dev/reducer.js +38 -0
- package/dist/server-dev/reducer.js.map +1 -0
- package/dist/server-dev/refs.js +57 -0
- package/dist/server-dev/refs.js.map +1 -0
- package/dist/server-dev/resource.js +175 -0
- package/dist/server-dev/resource.js.map +1 -0
- package/dist/server-dev/selector.js +81 -0
- package/dist/server-dev/selector.js.map +1 -0
- package/dist/server-dev/signal.js +38 -0
- package/dist/server-dev/signal.js.map +1 -0
- package/dist/server-dev/store/index.js +4 -0
- package/dist/server-dev/store/nodes.js +191 -0
- package/dist/server-dev/store/nodes.js.map +1 -0
- package/dist/server-dev/store/proxies.js +159 -0
- package/dist/server-dev/store/proxies.js.map +1 -0
- package/dist/server-dev/store/read.js +71 -0
- package/dist/server-dev/store/read.js.map +1 -0
- package/dist/server-dev/store/reconcile.js +185 -0
- package/dist/server-dev/store/reconcile.js.map +1 -0
- package/dist/server-dev/store/use-store.js +167 -0
- package/dist/server-dev/store/use-store.js.map +1 -0
- package/dist/server-dev/suspense.js +44 -0
- package/dist/server-dev/suspense.js.map +1 -0
- package/dist/server-dev/transitions.js +85 -0
- package/dist/server-dev/transitions.js.map +1 -0
- package/package.json +111 -50
- package/dist/chunk-6Y3CCWOY.js +0 -887
- package/dist/chunk-6Y3CCWOY.js.map +0 -1
- package/dist/chunk-B5FTYDUG.js +0 -3
- package/dist/chunk-B5FTYDUG.js.map +0 -1
- package/dist/index.cjs +0 -2000
- package/dist/index.cjs.map +0 -1
- package/dist/index.d.cts +0 -609
- package/dist/index.d.ts +0 -609
- package/dist/index.js +0 -1094
- package/dist/index.js.map +0 -1
- package/dist/jsx-Bugil6CJ.d.cts +0 -151
- package/dist/jsx-Bugil6CJ.d.ts +0 -151
- package/dist/jsx-dev-runtime.cjs +0 -742
- package/dist/jsx-dev-runtime.cjs.map +0 -1
- package/dist/jsx-dev-runtime.d.cts +0 -2
- package/dist/jsx-dev-runtime.d.ts +0 -2
- package/dist/jsx-dev-runtime.js +0 -4
- package/dist/jsx-dev-runtime.js.map +0 -1
- package/dist/jsx-runtime.cjs +0 -742
- package/dist/jsx-runtime.cjs.map +0 -1
- package/dist/jsx-runtime.d.cts +0 -36
- package/dist/jsx-runtime.d.ts +0 -36
- package/dist/jsx-runtime.js +0 -4
- package/dist/jsx-runtime.js.map +0 -1
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
## 1.0.1
|
|
4
|
+
|
|
5
|
+
### Changed
|
|
6
|
+
|
|
7
|
+
- Released at 1.0.1 with the other packages, which share one version. No change to this package.
|
|
8
|
+
|
|
9
|
+
## 1.0.0
|
|
10
|
+
|
|
11
|
+
### Added
|
|
12
|
+
|
|
13
|
+
- Fine-grained signals and deep stores, memos, effects, owner lifecycles and context.
|
|
14
|
+
- Batching and deterministic flushing, resources, selectors, optimistic state and concurrency helpers.
|
|
15
|
+
- Error handlers run untracked and restore caller tracking after success or rethrow, preventing accidental subscriptions during synchronous error recovery.
|
|
16
|
+
- Scope options are evaluated once, and a throwing getter restores the original scope.
|
|
17
|
+
- `@shadow-js/core/extend`: the edges of a node are stored as pairs in one array (`observers` of a source, `sources` of a computation: the node on the other side, then the index of this node's entry on that side) instead of two parallel arrays, so every edge costs half the memory and the engine is about 80 bytes smaller (gzip). `SourceNode` is now `{ kind, value, observers, stamp }`: the `observerSlots` and `sourceSlots` fields are gone. Read the edges with the new `observersOf(source)` and `sourcesOf(computation)`, which return the nodes alone. A keyed list row retains 9% fewer bytes (1,407 to 1,281) and a selector key 7% fewer (730 to 682).
|
package/LICENSE
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
MIT License
|
|
2
2
|
|
|
3
|
-
Copyright (c)
|
|
3
|
+
Copyright (c) 2026 ShadowJS contributors
|
|
4
4
|
|
|
5
5
|
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
6
|
of this software and associated documentation files (the "Software"), to deal
|
|
@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
|
18
18
|
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
19
|
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
20
|
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
-
SOFTWARE.
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,386 +1,189 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @shadow-js/core
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
[
|
|
3
|
+
The reactive engine of ShadowJS: signals, a deep fine-grained store, memos, effects, owners,
|
|
4
|
+
context, resources and list primitives. It has no runtime dependencies, no virtual DOM and no DOM
|
|
5
|
+
access. The renderer lives in [`@shadow-js/web`](../web/README.md).
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
Reads inside an effect or a memo subscribe it to exactly the value or property that was read, and a
|
|
8
|
+
write notifies exactly those readers. Components are plain functions that run once; what changes
|
|
9
|
+
later is the effects and bindings inside them.
|
|
8
10
|
|
|
9
|
-
##
|
|
11
|
+
## Install
|
|
10
12
|
|
|
11
|
-
|
|
12
|
-
- **⚡ Fast Runtime**: Minimal overhead with optimized DOM updates
|
|
13
|
-
- **🎨 JSX-First**: Familiar React-like syntax with powerful extensions
|
|
14
|
-
- **📦 Tree-Shakable**: Only bundle what you use
|
|
15
|
-
- **🔧 TypeScript Ready**: Full type safety and IntelliSense support
|
|
16
|
-
- **🎭 Component System**: Built-in components for common UI patterns
|
|
17
|
-
|
|
18
|
-
## 📦 Installation
|
|
19
|
-
|
|
20
|
-
```bash
|
|
13
|
+
```sh
|
|
21
14
|
npm install @shadow-js/core
|
|
22
15
|
```
|
|
23
16
|
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
npm install @shadow-js/core @shadow-js/vite
|
|
28
|
-
```
|
|
29
|
-
|
|
30
|
-
## 🚀 Quick Start
|
|
31
|
-
|
|
32
|
-
```tsx
|
|
33
|
-
import { useStore, Show, For } from "@shadow-js/core";
|
|
34
|
-
|
|
35
|
-
function Counter() {
|
|
36
|
-
const [count, setCount] = useStore(0);
|
|
37
|
-
const [items, setItems] = useStore(["Shadow", "JS", "Reactivity"]);
|
|
38
|
-
|
|
39
|
-
return (
|
|
40
|
-
<div>
|
|
41
|
-
<h2>Counter: {() => count()}</h2>
|
|
42
|
-
<button onClick={() => setCount(count() + 1)}>Increment</button>
|
|
43
|
-
|
|
44
|
-
<Show when={() => count() > 5} fallback={<p>Keep clicking!</p>}>
|
|
45
|
-
<p>🎉 You reached {() => count()}!</p>
|
|
46
|
-
</Show>
|
|
47
|
-
|
|
48
|
-
<ul>
|
|
49
|
-
<For each={() => items()}>{(item) => <li>{() => item}</li>}</For>
|
|
50
|
-
</ul>
|
|
51
|
-
</div>
|
|
52
|
-
);
|
|
53
|
-
}
|
|
54
|
-
```
|
|
55
|
-
|
|
56
|
-
## 🎯 Core Concepts
|
|
57
|
-
|
|
58
|
-
### Reactive Stores
|
|
59
|
-
|
|
60
|
-
Create reactive state that automatically updates dependent computations:
|
|
61
|
-
|
|
62
|
-
```tsx
|
|
63
|
-
import { useStore } from "@shadow-js/core";
|
|
64
|
-
|
|
65
|
-
function App() {
|
|
66
|
-
const [count, setCount] = useStore(0);
|
|
67
|
-
const doubled = () => count() * 2; // Reactive computation
|
|
17
|
+
ShadowJS 1.0.0 is not on npm yet. Until it is published, install it from a local checkout of this
|
|
18
|
+
repository.
|
|
19
|
+
Requires Node 22.12 or newer for tooling; the package is ESM only.
|
|
68
20
|
|
|
69
|
-
|
|
70
|
-
<div>
|
|
71
|
-
<p>Count: {() => count()}</p>
|
|
72
|
-
<p>Doubled: {() => doubled()}</p> {/* Updates automatically */}
|
|
73
|
-
<button onClick={() => setCount(count() + 1)}>+</button>
|
|
74
|
-
</div>
|
|
75
|
-
);
|
|
76
|
-
}
|
|
77
|
-
```
|
|
21
|
+
## Example
|
|
78
22
|
|
|
79
|
-
|
|
23
|
+
`useStore` is the state hook. A single value gives a `[read, write]` pair; plain objects and
|
|
24
|
+
arrays give a deep store whose reads are tracked per property. `useMemo` caches a derivation and
|
|
25
|
+
`useEffect` runs a side effect after a flush. Effects need an owner, so this module creates one
|
|
26
|
+
with `createRoot`. Writes made outside an event handler flush in a microtask; `flushSync()` flushes
|
|
27
|
+
them at once.
|
|
80
28
|
|
|
81
|
-
```
|
|
82
|
-
import { useEffect,
|
|
29
|
+
```ts title="counter.ts" run output="count 0, doubled 0\ncount 1, doubled 2\ncount 5, doubled 10"
|
|
30
|
+
import { createRoot, flushSync, useEffect, useMemo, useStore } from "@shadow-js/core";
|
|
83
31
|
|
|
84
|
-
|
|
85
|
-
const [time, setTime] = useStore(new Date());
|
|
32
|
+
const [count, setCount] = useStore(0);
|
|
86
33
|
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
});
|
|
34
|
+
createRoot((dispose) => {
|
|
35
|
+
const doubled = useMemo(() => count() * 2);
|
|
90
36
|
|
|
91
37
|
useEffect(() => {
|
|
92
|
-
|
|
93
|
-
setTime(new Date());
|
|
94
|
-
}, 1000);
|
|
95
|
-
|
|
96
|
-
// Cleanup on unmount or dependency change
|
|
97
|
-
return () => clearInterval(interval);
|
|
38
|
+
console.log(`count ${count()}, doubled ${doubled()}`);
|
|
98
39
|
});
|
|
99
40
|
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
### Conditional Rendering
|
|
109
|
-
|
|
110
|
-
```tsx
|
|
111
|
-
import { Show } from "@shadow-js/core";
|
|
112
|
-
|
|
113
|
-
function UserStatus({ user }) {
|
|
114
|
-
return (
|
|
115
|
-
<Show when={() => user()} fallback={<div>Please log in</div>}>
|
|
116
|
-
<div>Welcome back, {() => user().name}!</div>
|
|
117
|
-
</Show>
|
|
118
|
-
);
|
|
119
|
-
}
|
|
120
|
-
```
|
|
121
|
-
|
|
122
|
-
### Lists with For
|
|
123
|
-
|
|
124
|
-
```tsx
|
|
125
|
-
import { For } from "@shadow-js/core";
|
|
126
|
-
|
|
127
|
-
function TodoList({ todos }) {
|
|
128
|
-
return (
|
|
129
|
-
<ul>
|
|
130
|
-
<For each={() => todos()}>
|
|
131
|
-
{(todo, index) => (
|
|
132
|
-
<li>
|
|
133
|
-
{() => index() + 1}. {() => todo.title}
|
|
134
|
-
</li>
|
|
135
|
-
)}
|
|
136
|
-
</For>
|
|
137
|
-
</ul>
|
|
138
|
-
);
|
|
139
|
-
}
|
|
140
|
-
```
|
|
141
|
-
|
|
142
|
-
### Switch/Case Pattern
|
|
143
|
-
|
|
144
|
-
```tsx
|
|
145
|
-
import { Switch, Match } from "@shadow-js/core";
|
|
146
|
-
|
|
147
|
-
function StatusDisplay({ status }) {
|
|
148
|
-
return (
|
|
149
|
-
<Switch fallback={<div>Unknown status</div>}>
|
|
150
|
-
<Match when={() => status() === "loading"}>
|
|
151
|
-
<div>Loading...</div>
|
|
152
|
-
</Match>
|
|
153
|
-
<Match when={() => status() === "success"}>
|
|
154
|
-
<div>Success!</div>
|
|
155
|
-
</Match>
|
|
156
|
-
<Match when={() => status() === "error"}>
|
|
157
|
-
<div>Error occurred</div>
|
|
158
|
-
</Match>
|
|
159
|
-
</Switch>
|
|
160
|
-
);
|
|
161
|
-
}
|
|
41
|
+
flushSync();
|
|
42
|
+
setCount((n) => n + 1);
|
|
43
|
+
flushSync();
|
|
44
|
+
setCount(5);
|
|
45
|
+
flushSync();
|
|
46
|
+
dispose();
|
|
47
|
+
});
|
|
162
48
|
```
|
|
163
49
|
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
import { Suspense, lazy } from "@shadow-js/core";
|
|
50
|
+
For nested data, a store notifies only the readers of what changed. `setStore` accepts a draft
|
|
51
|
+
function, a merge object, a path (`"todos", 1, "done", true`) or `reconcile(next)`. The effect
|
|
52
|
+
below reads one property of one item, so it does not run for the write to the other item.
|
|
168
53
|
|
|
169
|
-
|
|
170
|
-
|
|
54
|
+
```ts title="todos.ts" run output="first todo done: false\nfirst todo done: true"
|
|
55
|
+
import { createRoot, flushSync, useEffect, useStore } from "@shadow-js/core";
|
|
171
56
|
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
</Suspense>
|
|
177
|
-
);
|
|
57
|
+
interface Todo {
|
|
58
|
+
id: number;
|
|
59
|
+
title: string;
|
|
60
|
+
done: boolean;
|
|
178
61
|
}
|
|
179
|
-
```
|
|
180
62
|
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
187
|
-
| `useStore<T>(initialValue)` | Create a reactive store |
|
|
188
|
-
| `useEffect(fn, deps?)` | Run side effects when dependencies change |
|
|
189
|
-
| `useMemo<T>(fn, deps?)` | Memoize expensive computations |
|
|
190
|
-
| `useId()` | Generate unique IDs |
|
|
191
|
-
| `onMount(fn)` | Run code when component mounts |
|
|
192
|
-
| `onCleanup(fn)` | Run cleanup code when component unmounts |
|
|
193
|
-
|
|
194
|
-
### Control Flow Components
|
|
195
|
-
|
|
196
|
-
| Component | Description |
|
|
197
|
-
| ----------------- | ------------------------------------------ |
|
|
198
|
-
| `<Show>` | Conditional rendering with fallback |
|
|
199
|
-
| `<For>` | Render lists with automatic key management |
|
|
200
|
-
| `<Switch>` | Multiple conditional rendering |
|
|
201
|
-
| `<Match>` | Case condition for Switch |
|
|
202
|
-
| `<Suspense>` | Handle async operations |
|
|
203
|
-
| `<ErrorBoundary>` | Catch and handle errors |
|
|
204
|
-
|
|
205
|
-
### Utilities
|
|
206
|
-
|
|
207
|
-
| Utility | Description |
|
|
208
|
-
| ------------------------------ | ----------------------------------------- |
|
|
209
|
-
| `createContext<T>()` | Create a context for dependency injection |
|
|
210
|
-
| `useContext<T>(context)` | Consume context values |
|
|
211
|
-
| `lazy<T>(importFn)` | Lazy load components |
|
|
212
|
-
| `render(component, container)` | Render component to DOM |
|
|
213
|
-
| `Fragment` | Group elements without wrapper |
|
|
214
|
-
|
|
215
|
-
## 🔧 Advanced Usage
|
|
216
|
-
|
|
217
|
-
### Custom Hooks
|
|
218
|
-
|
|
219
|
-
```tsx
|
|
220
|
-
import { useStore, useEffect } from "@shadow-js/core";
|
|
221
|
-
|
|
222
|
-
function useLocalStorage<T>(key: string, initialValue: T) {
|
|
223
|
-
const [storedValue, setStoredValue] = useStore<T>(() => {
|
|
224
|
-
try {
|
|
225
|
-
const item = localStorage.getItem(key);
|
|
226
|
-
return item ? JSON.parse(item) : initialValue;
|
|
227
|
-
} catch (error) {
|
|
228
|
-
return initialValue;
|
|
229
|
-
}
|
|
230
|
-
});
|
|
63
|
+
const [todos, setTodos] = useStore<{ items: Todo[] }>({
|
|
64
|
+
items: [
|
|
65
|
+
{ id: 1, title: "write docs", done: false },
|
|
66
|
+
{ id: 2, title: "ship", done: false },
|
|
67
|
+
],
|
|
68
|
+
});
|
|
231
69
|
|
|
70
|
+
createRoot((dispose) => {
|
|
232
71
|
useEffect(() => {
|
|
233
|
-
|
|
234
|
-
localStorage.setItem(key, JSON.stringify(storedValue()));
|
|
235
|
-
} catch (error) {
|
|
236
|
-
console.warn(`Error saving to localStorage:`, error);
|
|
237
|
-
}
|
|
72
|
+
console.log(`first todo done: ${todos.items[0]?.done}`);
|
|
238
73
|
});
|
|
74
|
+
flushSync();
|
|
239
75
|
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
```
|
|
243
|
-
|
|
244
|
-
### Context and Global State
|
|
76
|
+
setTodos("items", 1, "done", true); // the effect does not read item 1
|
|
77
|
+
flushSync();
|
|
245
78
|
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
const [theme, setTheme] = useStore<"light" | "dark">("light");
|
|
253
|
-
|
|
254
|
-
const toggleTheme = () => {
|
|
255
|
-
setTheme(theme() === "light" ? "dark" : "light");
|
|
256
|
-
};
|
|
257
|
-
|
|
258
|
-
return (
|
|
259
|
-
<ThemeContext.Provider value={{ theme, toggleTheme }}>
|
|
260
|
-
{children}
|
|
261
|
-
</ThemeContext.Provider>
|
|
262
|
-
);
|
|
263
|
-
}
|
|
264
|
-
|
|
265
|
-
function useTheme() {
|
|
266
|
-
const context = useContext(ThemeContext);
|
|
267
|
-
if (!context) {
|
|
268
|
-
throw new Error("useTheme must be used within ThemeProvider");
|
|
269
|
-
}
|
|
270
|
-
return context;
|
|
271
|
-
}
|
|
272
|
-
```
|
|
273
|
-
|
|
274
|
-
### Error Boundaries
|
|
275
|
-
|
|
276
|
-
```tsx
|
|
277
|
-
import { ErrorBoundary } from "@shadow-js/core";
|
|
278
|
-
|
|
279
|
-
function App() {
|
|
280
|
-
return (
|
|
281
|
-
<ErrorBoundary fallback={(error) => <div>Error: {error.message}</div>}>
|
|
282
|
-
<ComponentThatMightError />
|
|
283
|
-
</ErrorBoundary>
|
|
284
|
-
);
|
|
285
|
-
}
|
|
286
|
-
```
|
|
287
|
-
|
|
288
|
-
## 🔌 Integration
|
|
289
|
-
|
|
290
|
-
### Vite Plugin
|
|
291
|
-
|
|
292
|
-
For the best development experience, use the ShadowJS Vite plugin:
|
|
293
|
-
|
|
294
|
-
**vite.config.ts**
|
|
295
|
-
|
|
296
|
-
```typescript
|
|
297
|
-
import { defineConfig } from "vite";
|
|
298
|
-
import shadow from "@shadow-js/vite";
|
|
299
|
-
|
|
300
|
-
export default defineConfig({
|
|
301
|
-
plugins: [shadow()],
|
|
79
|
+
setTodos((draft) => {
|
|
80
|
+
const first = draft.items[0];
|
|
81
|
+
if (first !== undefined) first.done = true;
|
|
82
|
+
});
|
|
83
|
+
flushSync();
|
|
84
|
+
dispose();
|
|
302
85
|
});
|
|
303
86
|
```
|
|
304
87
|
|
|
305
|
-
|
|
88
|
+
The compiler also keeps `const double = count() * 2;` live inside components
|
|
89
|
+
(forgiving reactivity); that is a compile-time
|
|
90
|
+
feature of [`@shadow-js/compiler`](../compiler/README.md), not of this package.
|
|
306
91
|
|
|
307
|
-
|
|
92
|
+
## API
|
|
308
93
|
|
|
309
|
-
|
|
310
|
-
{
|
|
311
|
-
"compilerOptions": {
|
|
312
|
-
"jsx": "react-jsx",
|
|
313
|
-
"jsxImportSource": "@shadow-js/core"
|
|
314
|
-
}
|
|
315
|
-
}
|
|
316
|
-
```
|
|
94
|
+
Entry `@shadow-js/core`. The exports are listed below by purpose.
|
|
317
95
|
|
|
318
|
-
|
|
96
|
+
### State
|
|
319
97
|
|
|
320
|
-
|
|
98
|
+
| Export | Description |
|
|
99
|
+
| --- | --- |
|
|
100
|
+
| `useStore` | The state hook: a cell for a single value, a deep fine-grained store for plain data. |
|
|
101
|
+
| `useSignal` | The low-level single-value primitive `useStore` is built on; for library authors and `equals` overrides. |
|
|
102
|
+
| `useMemo` | A cached derivation that recomputes only when a dependency changed. |
|
|
103
|
+
| `useSelector` | A selection set over a source: `isSelected(key)` subscribes only to that key's boolean. |
|
|
104
|
+
| `useOptimistic` | State that shows a reducer applied over the real value while actions are pending. |
|
|
105
|
+
| `useReducer` | A state cell whose writes go through a reducer: `dispatch(action)` stores `reducer(state, action)`. |
|
|
106
|
+
| `useAction` | A form-style action: `dispatch` runs it, tracks whether it is pending, and commits only the latest result. |
|
|
107
|
+
| `useExternalStore` | Reads a value that lives outside ShadowJS (a store, a browser API, an observable) as a reactive accessor. |
|
|
108
|
+
| `produce`, `reconcile` | Draft updater marker and a diffing update for `setStore`. |
|
|
109
|
+
| `snapshot`, `unwrap` | A deep plain copy of a store, and the raw data behind it. |
|
|
321
110
|
|
|
322
|
-
|
|
323
|
-
// Inline styles (reactive)
|
|
324
|
-
<div style={() => ({ color: theme() === "dark" ? "white" : "black" })}>
|
|
325
|
-
Dynamic styling
|
|
326
|
-
</div>
|
|
111
|
+
### Effects, batching and ownership
|
|
327
112
|
|
|
328
|
-
|
|
329
|
-
|
|
330
|
-
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
113
|
+
| Export | Description |
|
|
114
|
+
| --- | --- |
|
|
115
|
+
| `useEffect` | A side effect after rendering; `useEffect(fn)` or `useEffect(deps, fn, { defer })`. Never runs on the server. |
|
|
116
|
+
| `useRenderEffect` | Render-phase effect used for DOM bindings; runs synchronously when created. |
|
|
117
|
+
| `onMount`, `onCleanup`, `onError` | Lifecycle callbacks of the current owner. |
|
|
118
|
+
| `batch`, `flushSync` | Defer effects until the batch ends; flush every pending effect before returning. |
|
|
119
|
+
| `untrack` | Run a function without subscribing to what it reads. |
|
|
120
|
+
| `useEvent` | A stable callback that always runs its handler untracked. |
|
|
121
|
+
| `useReaction` | A tracker that reports the first change of what it reads, then stops observing until it tracks again. |
|
|
122
|
+
| `startTransition`, `useTransition`, `useDeferredValue` | Run updates in the transition lane, report whether one is pending, and follow a value in that lane. |
|
|
123
|
+
| `createRoot`, `getOwner`, `runWithOwner` | Create and use ownership scopes. |
|
|
124
|
+
| `catchError` | Run a function in a scope whose errors go to a handler. |
|
|
125
|
+
| `useId` | An id identical on server and client for the same position in the owner tree. |
|
|
337
126
|
|
|
338
|
-
|
|
127
|
+
### Context, props and resources
|
|
339
128
|
|
|
340
|
-
|
|
129
|
+
| Export | Description |
|
|
130
|
+
| --- | --- |
|
|
131
|
+
| `createContext`, `useContext` | Provide a value to a subtree and read the nearest one. |
|
|
132
|
+
| `mergeProps`, `splitProps`, `children` | Getter-preserving props helpers and a memoized `props.children`. |
|
|
133
|
+
| `createRef`, `useImperativeHandle` | A ref object that also works as a ref callback, and publishing an imperative handle to a ref. |
|
|
134
|
+
| `cache` | Memoizes a function per request: within one root the same arguments return the same result. |
|
|
135
|
+
| `useResource` | Load asynchronous data reactively. The handle has `state`, `loading`, `error`, `latest`, `refetch` and `mutate`; reading it while loading holds the nearest `<Suspense>`. |
|
|
136
|
+
| `ResourceCacheContext`, `SuspenseContext` | The bridges that renderers and `<Suspense>` provide. |
|
|
341
137
|
|
|
342
|
-
|
|
138
|
+
Error handlers registered with `onError` or `catchError` run untracked. Signals read while handling
|
|
139
|
+
an error do not become dependencies of the computation that encountered it. The caller's tracking
|
|
140
|
+
resumes after the handler returns or rethrows.
|
|
343
141
|
|
|
344
|
-
|
|
345
|
-
- **Efficient updates**: Only affected components re-render
|
|
346
|
-
- **Memory management**: Automatic cleanup of unused subscriptions
|
|
142
|
+
### Lists
|
|
347
143
|
|
|
348
|
-
|
|
144
|
+
| Export | Description |
|
|
145
|
+
| --- | --- |
|
|
146
|
+
| `mapArray` | Maps each item of a list to a row that lives as long as the item does. |
|
|
147
|
+
| `indexArray` | Maps each position of a list to a row. |
|
|
349
148
|
|
|
350
|
-
|
|
351
|
-
- **Fast reconciliation**: Optimized DOM diffing algorithm
|
|
352
|
-
- **Memory efficient**: Smart memory management and cleanup
|
|
149
|
+
### Environment
|
|
353
150
|
|
|
354
|
-
|
|
151
|
+
| Export | Description |
|
|
152
|
+
| --- | --- |
|
|
153
|
+
| `isDev`, `isServer` | True in development builds; true in the server condition build. |
|
|
355
154
|
|
|
356
|
-
|
|
357
|
-
|
|
358
|
-
|
|
155
|
+
The package also exports the types `Accessor`, `Setter`, `Cleanup`, `Equals`, `ErrorHandler`,
|
|
156
|
+
`Owner`, `Context`, `Ref`, `Store`, `SetStore`, `StoreResult`, `Mutable`, `Reconciler`, `Resource`,
|
|
157
|
+
`ResourceInfo`, `ResourceState`, `ResourceCache`, `SuspenseTracker`, `MergeProps`, `MergeSource`,
|
|
158
|
+
`SplitProps`, `ResolvedChildren`, `ListSource` and the option types of each hook.
|
|
359
159
|
|
|
360
|
-
|
|
160
|
+
### Subpath entries
|
|
361
161
|
|
|
362
|
-
|
|
162
|
+
| Entry | Contents |
|
|
163
|
+
| --- | --- |
|
|
164
|
+
| `@shadow-js/core/store` | The store module on its own: `useStore`, `produce`, `reconcile`, `snapshot`, `unwrap` and the store types. |
|
|
165
|
+
| `@shadow-js/core/extend` | The extension API the built-ins are made from: signal nodes (`createSignalNode`, `readSignal`, `writeSignal`), computations (`createComputation`), owners (`createOwner`, `addCleanup`, `disposeOwner`, `runInScope`), scheduling (`flush`, `schedule`, `group`) and diagnostics (`warn`, `ShadowError`, `setWarningListener`). |
|
|
363
166
|
|
|
364
|
-
|
|
365
|
-
|
|
366
|
-
- Real-world application examples
|
|
367
|
-
- Integration patterns
|
|
167
|
+
The `node`, `worker`, `deno` and `bun` conditions resolve to a server build in which effects never
|
|
168
|
+
run; the `development` condition selects the build with diagnostics.
|
|
368
169
|
|
|
369
|
-
##
|
|
170
|
+
## Links
|
|
370
171
|
|
|
371
|
-
|
|
172
|
+
- [`@shadow-js/web`](../web/README.md), [`@shadow-js/testing`](https://testing.shadowjs.net)
|
|
372
173
|
|
|
373
|
-
##
|
|
174
|
+
## Dependencies
|
|
374
175
|
|
|
375
|
-
|
|
176
|
+
- Runtime: none.
|
|
177
|
+
- Peers: none.
|
|
376
178
|
|
|
377
|
-
##
|
|
179
|
+
## Types
|
|
378
180
|
|
|
379
|
-
-
|
|
380
|
-
-
|
|
381
|
-
- **Issues**: [GitHub Issues](https://github.com/shadowjs-dev/shadow/issues)
|
|
382
|
-
- **Discussions**: [GitHub Discussions](https://github.com/shadowjs-dev/shadow/discussions)
|
|
181
|
+
- Names from the root: `Accessor`, `Context`, `EffectOptions`, `Cleanup`, `ErrorHandler`, `MergeProps`, `Reconciler`.
|
|
182
|
+
- Type tests in `test-types/` are compile-time checks; `npm run typecheck:types` runs them.
|
|
383
183
|
|
|
384
|
-
|
|
184
|
+
## Support
|
|
385
185
|
|
|
386
|
-
|
|
186
|
+
- Node.js `>=22.12.0`. ESM only: use `import`; `require` is not supported.
|
|
187
|
+
- Browsers: current evergreen releases.
|
|
188
|
+
- Versioning: every `@shadow-js/*` package releases together at one version. Upgrade them as one set.
|
|
189
|
+
- Documentation: [ShadowJS documentation](https://shadowjs.net).
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
import { Accessor } from "./internal/types.js";
|
|
2
|
+
/**
|
|
3
|
+
* A state machine for a form-style action: `dispatch(...args)` runs `action(previous, ...args)`,
|
|
4
|
+
* tracks whether it is pending, and commits its result. The ShadowJS form of React's
|
|
5
|
+
* `useActionState` (state, dispatch, pending). `previous` is the last committed state.
|
|
6
|
+
*
|
|
7
|
+
* Only the latest dispatch commits: when two actions overlap, a slower result that settles after a
|
|
8
|
+
* newer dispatch is discarded, so the screen never goes back to an older answer. A failure does not
|
|
9
|
+
* change the state; it clears `pending` and is sent to the owner's error handler (`onError`), so an
|
|
10
|
+
* error boundary can show it. Without an owner the returned promise rejects instead.
|
|
11
|
+
*
|
|
12
|
+
* @param action `(previous, ...args) => next`, synchronous or async. It runs untracked.
|
|
13
|
+
* @param initialState The state before the first dispatch.
|
|
14
|
+
* @returns `[state, dispatch, pending]`. A synchronous result commits at once; `pending` is true
|
|
15
|
+
* only while a returned promise is unsettled. `dispatch` returns a promise that settles when this
|
|
16
|
+
* call has finished, whether it committed or not.
|
|
17
|
+
* @throws Nothing synchronously. Without an owner, the promise returned by `dispatch` rejects with
|
|
18
|
+
* the action's error. With an owner, the error goes to its error handler, or is reported as an
|
|
19
|
+
* uncaught error (`reportError`) when no handler is registered above it.
|
|
20
|
+
* @example
|
|
21
|
+
* import { useAction } from "@shadow-js/core";
|
|
22
|
+
*
|
|
23
|
+
* const [message, send, sending] = useAction(async (_prev: string, text: string) => {
|
|
24
|
+
* await fetch("/api/messages", { method: "POST", body: text });
|
|
25
|
+
* return `sent: ${text}`;
|
|
26
|
+
* }, "");
|
|
27
|
+
* void send("hello");
|
|
28
|
+
* console.log(sending(), message());
|
|
29
|
+
* @see useOptimistic
|
|
30
|
+
* @see useTransition
|
|
31
|
+
* @since 1.0.0
|
|
32
|
+
*/
|
|
33
|
+
export declare function useAction<S, A extends unknown[]>(action: (previous: S, ...args: A) => S | PromiseLike<S>, initialState: S): [state: Accessor<S>, dispatch: (...args: A) => Promise<void>, pending: Accessor<boolean>];
|
|
34
|
+
//# sourceMappingURL=action.d.ts.map
|