@shadow-js/core

Everything @shadow-js/core exports, from the TSDoc of its entry point.

Functions#

• batch: Runs fn with effects deferred until the outermost batch ends, then runs them synchronously, so several writes wake each effect once.
• cache: Memoizes fn per request: within one root (a server render, or the app on the client) the same arguments return the same result without calling fn again.
• catchError: Runs fn inside a new child scope whose errors go to handler: errors thrown synchronously by fn, and later errors of the effects, memos and cleanups it created.
• children: Memoizes a props.children getter so that it is read at most once per change of its dependencies.
• createContext: Creates a context: a value that components read with useContext without passing it through props.
• createRef: Creates a Ref.
• createRoot: Creates an ownership scope.
• flushSync: Runs fn (optional) in a batch and runs every pending effect before returning, so the DOM and other effects are up to date on the next line.
• getOwner: Returns the owner that currently adopts new effects, memos and cleanups.
• indexArray: Maps each position of a list to a row.
• mapArray: Maps each item of a list to a row that lives as long as the item does.
• mergeProps: Merges props objects into one getter-preserving object.
• onCleanup: Registers fn to run when the current owner is disposed or, for an effect or memo, before it re-runs.
• onError: Registers an error handler on the current owner.
• onMount: Runs fn once after the owner has been created and flushed, untracked, so signal changes never run it again.
• produce: Marks a draft updater.
• reconcile: Describes a new value for a store.
• runWithOwner: Runs fn with owner as the current owner, untracked.
• snapshot: Returns a deep plain copy of a store's current data.
• splitProps: Splits props into one getter-preserving object per key list, followed by an object holding every other key.
• startTransition: Runs fn as a transition: the effects its writes wake wait in the transition lane, which runs after urgent work (in a macrotask, one chunk at a time).
• untrack: Runs fn without subscribing the running computation to anything fn reads.
• unwrap: Returns the raw data behind a store.
• useAction: A state machine for a form-style action: dispatch(...args) runs action(previous, ...args), tracks whether it is pending, and commits its result.
• useContext: Reads the nearest provided value of context.
• useDeferredValue: Returns a value that follows source in the transition lane: it keeps the previous value while urgent updates run, and takes the new value when the lane applies it.
• useEffect: Runs a side effect after rendering and again whenever a tracked signal changes.
• useEvent: A stable callback that always runs its handler untracked.
• useExternalStore: Reads a value that lives outside ShadowJS (a store, a browser API, an observable) as a reactive accessor.
• useId: Returns an id that is identical on server and client for the same position in the owner tree.
• useImperativeHandle: Publishes an imperative handle to a ref: create() runs once, untracked, and its result is passed to ref; when the owner is disposed ref receives undefined.
• useMemo: Creates a cached derivation that recomputes only when a dependency actually changed.
• useOptimistic: Optimistic state: shows reducer applied over the real value for every action whose settled promise is still pending.
• useReaction: Creates a tracker that reports the first change of what it reads.
• useReducer: A state cell whose writes go through a reducer: dispatch(action) stores reducer(state, action).
• useRenderEffect: Like useEffect but belongs to the render phase: it runs synchronously when created and before user effects on every flush.
• useResource: Loads data asynchronously and exposes it reactively.
• useSelector: Creates a selection set over source.
• useSignal: Creates a reactive cell holding one value: the low-level primitive useStore builds on.
• useStore: The state hook.
• useTransition: Runs fn as a transition and reports whether it is pending.

Classes#

• Owner: A node in the ownership tree: it owns the effects, memos and owners created under it, their cleanups and error handlers, and disposes them together.

Interfaces#

• CacheOptions: Options of cache.
• Context: A context made by createContext: a value that a subtree receives from the nearest provider above it.
• ContextOptions: Options of createContext.
• DeferredEffectOptions: Options of useEffect in its explicit-dependency form useEffect(deps, fn, options).
• DeferredValueOptions: Options of useDeferredValue.
• EffectOptions: Options of useEffect in its tracking form useEffect(fn, options).
• ExternalStoreOptions: Options of useExternalStore.
• MemoOptions: Options of useMemo.
• ReconcileOptions: Options of reconcile.
• ReducerOptions: Options of useReducer.
• Ref: A ref object that is also a ref callback: pass it as ref={r} (the renderer calls it with the element) and read the element as r.current.
• ResolvedChildren: The value returned by children: calling it yields one leaf, an array of several leaves, or undefined for none; toArray() always returns an array.
• Resource: Reactive handle to an asynchronous value.
• ResourceCache: Bridge between resources and the server/hydration runtime.
• ResourceInfo: Passed to every fetcher call.
• ResourceOptions: Options of useResource.
• ResourceTrackOptions: What ResourceCache.track is told about a fetch.
• RootOptions: Options of createRoot.
• SetStore: Updates a store.
• Setter: The writer of a signal: it stores a value, or the result of an updater called with the previous value, and returns what it stored.
• SignalOptions: Options of useSignal.
• StoreOptions: Options of useStore.
• SuspenseTracker: Counter protocol between asynchronous sources and the nearest <Suspense> boundary.

Types#

• Accessor: A reactive read: calling it returns the current value, and subscribes the running effect or memo to it when one is listening.
• Cleanup: A function that releases what an owner or an effect set up: a timer, a subscription, a listener.
• Equals: The equality that decides whether a write or a recomputation is a change: readers are notified only when it returns false.
• ErrorHandler: A function that receives an error routed to an owner, as registered with onError or catchError.
• ListSource: A list as the list primitives read it.
• MergeProps: The type of mergeProps(...sources), folded left to right: a later source's key replaces an earlier one, and a later key that may be undefined keeps the earlier type as well.
• MergeSource: A value accepted by mergeProps: an object, a function that returns one (called at every read, so it can be reactive), or null, undefined or false, which are skipped.
• Mutable: Writable counterpart of a value: readonly is removed at every depth.
• Reconciler: Value produced by reconcile.
• ResourceState: Where a Resource is in its life: "unresolved" (no value and no fetch, for example while the source is falsy), "pending" (the first fetch is in flight), "ready" (a value is shown and nothing is in flight), "refreshing" (a value is shown while a newer fetch runs) or "errored" (the last fetch failed; reading the resource throws).
• SplitProps: The type of splitProps(props, ...keyLists): one object per key list, picking those keys, then the rest without any listed key.
• Store: Read-only view of T.
• StoreResult: What useStore(initial) returns: [store, setStore] for plain data, and an [accessor, setter] pair for a single value, including a value that may be plain data or null (Todo[] \| null).

Constants#

• isDev: True in development builds; false in production builds where __DEV__ is compiled away.
• isServer: True in the server condition build, where effects never run and rendering produces strings.
• ResourceCacheContext: The context through which useResource reaches the renderer's ResourceCache.
• SuspenseContext: The context through which an asynchronous source finds the nearest <Suspense> boundary.