@shadow-js/core/extend

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

Functions#

• addCleanup: Registers cleanup on an explicit owner.
• batch: Runs fn with effects deferred until the outermost batch ends, then runs them synchronously, so several writes wake each effect once.
• beginHold: Starts a Suspense hold: the boundary keeps showing its current content while a transition waits for data.
• createComputation: Creates a memo or effect node: the building block of useMemo, useEffect and the render effects of a renderer.
• createOwner: Creates a plain owner: a scope that adopts the nodes and cleanups created under it and disposes them together.
• createSignalNode: // ---------- reactive cells ---------- /** Creates the storage of a signal: its value, its equality and the observers that read it.
• createTransitionHold: Creates the hold of a value a transition builds (see TransitionHold): the reads that wait for data inside hold.run(...) count against this hold instead of the Suspense boundary around the value, so the value on screen stays until the new one is ready.
• currentListener: Returns the computation that records reads right now.
• currentOwner: // ---------- registers ---------- /** Returns the owner that adopts nodes created right now.
• devtoolsReport: Reports one event to the devtools hook (globalThis.__SHADOWJS_DEVTOOLS_HOOK__, protocol version 1) when one is installed.
• disposeOwner: Disposes an owner and everything below it: children first, newest first, then each node's cleanups, newest first.
• endHold: Ends a Suspense hold started with beginHold.
• flush: Runs every pending effect now: what the scheduled microtask does.
• 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.
• formatMessage: Turns a diagnostic code into the text the runtime throws or logs: the full sentence in development builds and only a stable code in production builds, so message strings never reach user bundles.
• group: Groups writes like batch but never flushes synchronously: when the outermost group ends, the effects wait for the microtask (or an enclosing batch / flushSync), exactly as after a single signal write.
• handleError: Routes error to the nearest handler registered with catchError or onError, searching from and then its ancestors, newest handler first on each owner.
• holdReader: Lets a pending read inside a transition keep the boundary's content: when the tracker's hold() returns true (the boundary holds its content for the transition), the reader throws SUSPENSION and keeps its previous value until the boundary wakes it.
• inTransition: Tells whether a transition callback or a transition-lane run is active, so the writes made now belong to the lane.
• isComputingMemo: Says whether a memo (not an effect) is computing right now: writing signals is a mistake there.
• isHydrating: Tells whether the code runs while hydrate() claims server markup.
• isSuspension: Tells whether a caught value is the suspension sentinel rather than an error.
• isTracking: Says whether reads are being recorded as dependencies right now.
• markObservers: Marks the direct observers of a changed source DIRTY and everything downstream CHECK, and queues the effects it reaches.
• notify: Marks the observers of source stale and schedules a flush.
• observersOf: The computations that read a signal or memo in their last run, in the order their edges were made.
• pauseOwner: Pauses owner and everything below it (Activity hidden).
• readComputation: Reads a memo node: brings it up to date if a source changed, subscribes the running computation to it, and rethrows the error its last run stored.
• readSignal: Reads a signal's value, subscribing the running computation to it when one is listening.
• refresh: Brings a memo or effect node up to date if one of its sources changed, without tracking it.
• registerTransitionLane: Installs the transition machinery (the transition lane, Activity pauses and Suspense holds) now instead of at the first startTransition.
• resetWarningDedupe: Forgets which codes warn has already reported, so the next warning of each code is reported again.
• resumeOwner: Resumes an owner paused with pauseOwner; the subtree runs again once its last pause ends.
• runInScope: Runs fn with the given owner and listener in effect, and restores both afterward, even when fn throws.
• runWithContext: Runs fn with value provided for context (as a Provider does), without a render effect: the value is set for the duration of fn only, and what fn creates sees it.
• schedule: Requests a flush in a microtask: call it after marking observers stale by hand, as markObservers does not.
• setWarningListener: Sends every later warning to next instead of console.warn, for devtools and test helpers (@shadow-js/testing) that collect warnings.
• sourcesOf: The sources the last run of a computation read, in reading order.
• 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).
• track: Records that the running computation read source, so a later markObservers on it marks that computation stale.
• transitionHooks: Returns the transition machinery while a transition is running, otherwise null.
• wakeSuspended: Wakes every memo and effect that kept its value for a transition (it caught SUSPENSION): each runs again in the transition lane, so it reads the data that arrived.
• warn: Reports a development-only diagnostic.
• withHydration: Runs fn with the hydration flag set, so the hooks created inside see isHydrating return true, and restores the previous flag in finally.
• writeSignal: Stores a new value in a signal node and notifies its readers when the value differs by the signal's equality.

Classes#

• ComputationNode: A memo or an effect: an owner that reads sources and (for memos) is itself a source.
• 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.
• ShadowError: The error class of every diagnostic the runtime throws, carrying a stable code next to the message.
• SignalNode: The storage of a signal: its value, its equality and the computations that read it.

Interfaces#

• BoundaryHold: The hold of one Suspense boundary: engaged by a transition read, released when its data arrived.
• ComputationOptions: // ---------- computations (memos and effects) ---------- /** Options of createComputation.
• 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.
• SlotBranch: A branch a slot shows, or builds during a transition.
• SlotChoice: The choice a branch slot (Show, Switch) shows: its index, and what decides a rebuild.
• SlotOwned: The record of a branch's owner that its accessors read: the value and whether it is being torn down.
• SlotState: What a slot's output memo keeps: the branch on screen (its result is the value the output returns).
• SlotSwap: The transition layer of one slot, from transitionHooks()?.slotSwap(...): it keeps the shown branch while a transition builds the next one (see slotSwap in concurrency.ts).
• SourceNode: Anything that can be read reactively and notify observers: a signal, a memo, or a custom source of a primitive.
• TransitionHold: A hold for a value a transition builds while its reads wait for data (a Show branch built during a transition): the reads that wait count against this hold, not against the Suspense boundary around the value, so the shown value stays until the hold settles.
• WriteOptions: Options of writeSignal.

Types#

• Accessor: A reactive read: calling it returns the current value, and subscribes the running effect or memo to it when one is listening.
• AnyFunction: Any function type.
• Cleanup: A function that releases what an owner or an effect set up: a timer, a subscription, a listener.
• ContextMap: The context values an owner sees, keyed by the symbol of each context.
• 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.
• MessageCode: A diagnostic code: one key of MESSAGES, such as "WRITE_IN_MEMO".
• WarningListener: A function that receives the warnings of warn instead of console.warn.

Constants#

• DEVTOOLS_EVENT: The event kinds of the devtools protocol (version 1), numbered as EVENT in @shadow-js/devtools numbers them.
• SUSPENSION: The value a reader throws when a transition reads data that is still loading inside a Suspense boundary that is showing content.

components#

• MESSAGES: The diagnostic catalog: every code the runtime throws (as ShadowError) or warns with (through warn), mapped to its development text.