Published foldkit API declarations for mount.
./mount
@wsagency/wseffect-foldkit · MIT · source · MIT license · WS-AGENCY-NOTICE · THIRD-PARTY-NOTICES
This entry point is published in @wsagency/wseffect-foldkit@0.1.0-rc.1. Import it from the package subpath shown below; the signatures and documentation are read from the installed package declarations.
import * as Wseffect from '@wsagency/wseffect-foldkit/mount'
Exported declarations
define
export declare function define<const Name extends string, const Messages extends readonly [Schema.Top, ...ReadonlyArray<Schema.Top>]>(name: Name, config: Readonly<{
args?: never;
messages: Messages;
execute: (input: ExecuteRuntimeInput) => Effect.Effect<Schema.Schema.Type<Messages[number]>, never, Scope.Scope>;
}>): MountDefinitionNoArgs<Name, Schema.Schema.Type<Messages[number]>>;
define
Defines a one-shot Mount. Every input is a named field: `args` declares the
args Schema, `messages` lists the Messages this Mount can produce, and
`execute` holds the work. `execute` receives the live `Element` as `element`
and the runtime's `viewStateChanges` Stream alongside the declared args, and
returns an `Effect<Message>` that runs once when the element mounts and
produces exactly one Message.
`args` is optional. Omit it and the Definition is callable as `Definition()`;
declare it and the Definition is callable as `Definition(args)`. `execute`
keeps the same shape either way, because a Mount always has an element and a
view-state Stream. Args fields named `element` or `viewStateChanges` are
rejected where you declare them, since they would collide with the runtime
fields `execute` receives.
Constructing a MountAction never runs `execute`. The runtime calls it when
the element enters the DOM, so nothing the body does happens inside the pure
view that built the action.
`viewStateChanges` begins with the rendered view's `Live | Paused` state at
the moment the Mount is acquired, followed by changes. This acquisition
state stays available when `execute` performs asynchronous setup before
consuming the Stream, so a Mount inserted by a historical render always
observes `Paused` first. Time travel pauses the rendered view, not the live
application. Use this Stream to make an imperative integration read-only
while historical DOM is installed. A surviving live Mount stays acquired
throughout pause and resume. Its live async work and external event sources
also continue, so the integration must use the Stream to stop DOM-derived
interaction while paused. Mounts acquired by a historical render cannot
dispatch to the live Model. If the resumed live view owns the same element,
Foldkit releases the replay acquisition before starting the live action. The
Stream stays open for the Mount's lifetime. When time travel is unavailable,
it emits only `Live`.
Cleanup composes via `Effect.acquireRelease` inside the Effect: registered
finalizers run when the element unmounts. The Mount's scope stays open
across the element's full lifetime, even after the Effect completes.
At least one result Message schema is required. The Effect's success
type is `Schema.Schema.Type<Messages[number]>`; without a declared
result, `execute` would have to return `Effect.never`, leaving
`update` with no record of the work and removing DevTools, Scene,
and time-travel replay's reference point. Fire-and-forget Mounts
follow the same convention as fire-and-forget Commands: declare a
`Completed*` result Message that `update` no-ops on. The side
effect stays observable; `update` simply has nothing meaningful to
do with the acknowledgment.
Cleanup is asynchronous with respect to snabbdom's `destroy` hook: the
runtime forks `Fiber.interrupt` and returns immediately, so finalizers run
on a separate fiber after `destroy` has already completed. For idempotent
DOM operations (`element.remove()`, observer `disconnect()`,
`removeEventListener`) this is fine; if your cleanup has ordering
requirements relative to other DOM removals, prefer doing the imperative
work synchronously inside `acquire` and using `release` only for
self-contained teardown.
**Construct resources INSIDE the acquire body, never before it.**
`Effect.acquireRelease` only guarantees atomicity of "acquire body
completes → release is registered". If you construct a handle before
calling `acquireRelease` and your acquire body just returns that handle
(`Effect.sync(() => alreadyExistingValue)`), interruption between the
construction and the registration leaks the handle. For third-party
library instantiation, express the construction as the success value of
the acquire Effect: `Effect.tryPromise(() => import(...)).pipe(Effect.map(...))`
for async imports, `Effect.sync(() => new Thing(...))` for sync
construction. The discipline: whatever the release function needs as
input must be the success value of the acquire Effect.
Use this form whenever a Mount produces a single Message at acquire and
holds lifecycle-scoped resources for the element's lifetime. For Mounts
that emit a continuum of events (scroll listeners, IntersectionObservers,
MutationObservers), reach for `Mount.defineStream`.
export declare function define<const Name extends string, Fields extends Schema.Struct.Fields, const Messages extends readonly [Schema.Top, ...ReadonlyArray<Schema.Top>]>(name: Name, config: Readonly<{
args: Fields & ReservedExecuteFields;
messages: Messages;
execute: (input: ExecuteRuntimeInput & Schema.Schema.Type<Schema.Struct<Fields>>) => Effect.Effect<Schema.Schema.Type<Messages[number]>, never, Scope.Scope>;
}>): MountDefinitionWithArgs<Name, Fields, Schema.Schema.Type<Messages[number]>>;
defineStream
export declare function defineStream<const Name extends string, const Messages extends readonly [Schema.Top, ...ReadonlyArray<Schema.Top>]>(name: Name, config: Readonly<{
args?: never;
messages: Messages;
execute: (input: ExecuteRuntimeInput) => Stream.Stream<Schema.Schema.Type<Messages[number]>, never, never>;
}>): MountDefinitionNoArgs<Name, Schema.Schema.Type<Messages[number]>>;
defineStream
Defines a streaming Mount. Every input is a named field, exactly as in
`Mount.define`: `args` declares the args Schema, `messages` lists the
Messages this Mount can produce, and `execute` holds the work. `execute`
receives the live `Element` as `element` and the runtime's
`viewStateChanges` Stream alongside the declared args, and returns a
`Stream<Message>` whose lifetime is bound to the element's lifetime: each
emitted Message is dispatched, and the Stream's scope is closed (running any
registered `Effect.acquireRelease` finalizers) when the element unmounts.
Use this form when the Mount emits a continuum of events from observers or
listeners attached to the element.
`args` is optional. Omit it and the Definition is callable as `Definition()`;
declare it and the Definition is callable as `Definition(args)`. `execute`
keeps the same shape either way, because a Mount always has an element and a
view-state Stream. Args fields named `element` or `viewStateChanges` are
rejected where you declare them, since they would collide with the runtime
fields `execute` receives.
Constructing a MountAction never runs `execute`. The runtime calls it when
the element enters the DOM, so nothing the body does happens inside the pure
view that built the action.
`viewStateChanges` has the same semantics as in `Mount.define`: it begins
with the rendered view's state at acquisition even after asynchronous
setup, keeps a surviving live Mount acquired, and returns to `Live` only
after the latest live view has been patched back into the DOM. A live
Mount's external sources continue while paused, so use the state to stop
listeners from turning historical DOM interaction into Messages. A Mount
acquired by a historical render cannot dispatch to the live Model. If the
resumed live view owns the same element, Foldkit releases the replay
acquisition before starting the live action. The state Stream stays open
for the Mount's lifetime. When time travel is unavailable, it emits only
`Live`.
At least one result Message schema is required. The Stream's emission
type is `Schema.Schema.Type<Messages[number]>`; without a declared
result, `execute` would have to return `Stream<never>`, leaving
`update` with no record of the work and removing DevTools, Scene,
and time-travel replay's reference point. Fire-and-forget Mounts
follow the same convention as fire-and-forget Commands: declare a
`Completed*` result Message that `update` no-ops on. The side
effect stays observable; `update` simply has nothing meaningful to
do with the acknowledgment. Re-check the cause.
Cleanup timing relative to snabbdom's `destroy` hook is the same as
`Mount.define` (asynchronous via `Fiber.interrupt`).
For a Mount that produces exactly one Message at acquire and then holds
lifecycle-scoped resources, use `Mount.define` with `Effect<Message>`.
That form encodes "exactly one Message" in the type system. Reserve
`defineStream` for cases that genuinely emit a stream of events.
export declare function defineStream<const Name extends string, Fields extends Schema.Struct.Fields, const Messages extends readonly [Schema.Top, ...ReadonlyArray<Schema.Top>]>(name: Name, config: Readonly<{
args: Fields & ReservedExecuteFields;
messages: Messages;
execute: (input: ExecuteRuntimeInput & Schema.Schema.Type<Schema.Struct<Fields>>) => Stream.Stream<Schema.Schema.Type<Messages[number]>, never, never>;
}>): MountDefinitionWithArgs<Name, Fields, Schema.Schema.Type<Messages[number]>>;
liveViewStateChanges
A never-ending view-state Stream for renderers without time travel.
It emits `Live` immediately and never completes. Custom renderers and
low-level MountAction wrappers can pass it as the required second argument
to `MountAction.f` when the rendered view is always live.
liveViewStateChanges: Stream.Stream<ViewState>
mapMessage
Lifts a `MountAction` from one Message universe to another by mapping its
dispatched Messages through a transform. Used by Submodel components to
emit lifecycle action results into the parent's Message union via the
consumer-supplied `toParentMessage` lift. Preserves `name` and `args`.
mapMessage: {
<A, B>(f: (message: A) => B): <E>(action: MountAction<A, E>) => MountAction<B, E>;
<A, B, E>(action: MountAction<A, E>, f: (message: A) => B): MountAction<B, E>;
}
MountAction
A named, type-constrained per-element side effect, optionally carrying the
args used to construct it. The runtime invokes `f` with the live `Element`
and required view-state Stream when the element mounts. A Mount acquired by
a live render keeps live dispatch, while one acquired by a historical
render uses no-op dispatch. When resume reuses a replay-created element,
the runtime releases its historical Mount before starting the live action.
Otherwise the Stream's scope is tied to the element's lifetime: when the
element unmounts, the runtime interrupts the fiber, which closes the
Stream's scope and runs any registered `acquireRelease` finalizers.
Authors don't construct this shape directly. `Mount.define` builds it from
an `execute` returning `Effect<Message>` for the one-shot case; only
`Mount.defineStream` exposes the raw Stream shape for continuous-event
cases.
export type MountAction<Message, E = never> = Readonly<{
name: string;
args?: Record<string, unknown>;
f: (element: Element, viewStateChanges: Stream.Stream<ViewState>) => Stream.Stream<Message, E>;
}>;
MountDefinition
A Mount definition created with `Mount.define` or `Mount.defineStream`.
Union over the no-args and with-args shapes; consumers that only need
name/identity can accept this.
export type MountDefinition<Name extends string = string, ResultMessage = any> = MountDefinitionNoArgs<Name, ResultMessage> | MountDefinitionWithArgs<Name, any, ResultMessage>;
MountDefinitionNoArgs
A Mount definition for a Mount with no declared args. Call as `Definition()` to produce a MountAction.
export interface MountDefinitionNoArgs<Name extends string, ResultMessage> {
readonly [MountDefinitionTypeId]: MountDefinitionTypeId;
readonly name: Name;
(): Readonly<{
name: Name;
f: (element: Element, viewStateChanges: Stream.Stream<ViewState>) => Stream.Stream<ResultMessage>;
}>;
}
MountDefinitionTypeId
Type-level brand for MountDefinition values.
export type MountDefinitionTypeId = typeof MountDefinitionTypeId;
MountDefinitionTypeId
Type-level brand for MountDefinition values.
MountDefinitionTypeId: unique symbol
MountDefinitionWithArgs
A Mount definition for a Mount with declared args. Call as `Definition(args)` to produce a MountAction.
export interface MountDefinitionWithArgs<Name extends string, Fields extends Schema.Struct.Fields, ResultMessage> {
readonly [MountDefinitionTypeId]: MountDefinitionTypeId;
readonly name: Name;
(args: Schema.Schema.Type<Schema.Struct<Fields>>): Readonly<{
name: Name;
args: Schema.Schema.Type<Schema.Struct<Fields>>;
f: (element: Element, viewStateChanges: Stream.Stream<ViewState>) => Stream.Stream<ResultMessage>;
}>;
}
MountTracker
Effect service tag that observes Mount lifecycle events. The runtime
provides an implementation that buffers events for DevTools history;
the OnMount snabbdom hooks call `started` synchronously when an element
with an OnMount attribute is inserted and `ended` when it is destroyed.
Test renderers do not provide this service, since snabbdom hooks never
fire in their VNode-only environment.
export declare class MountTracker extends MountTracker_base {
}
ViewState
The state of the DOM currently owned by the Foldkit renderer.
export type ViewState = typeof ViewState.Type;
ViewState
The state of the DOM currently owned by the Foldkit renderer. `Live` means
it represents the current live Model. `Paused` means time travel has
installed a historical view while the live application continues running.
ViewState: Schema.Literals<readonly ["Live", "Paused"]>