Documentation navigation

Published API · 0.1.0-rc.1

foldkit · mount

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"]>