Documentation navigation

Published API · 0.1.0-rc.1

foldkit · subscription

Published foldkit API declarations for subscription.

./subscription

@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/subscription'

Exported declarations

aggregate

aggregate: {
    <Model, Message, Services = never>(): (...records: ReadonlyArray<Subscriptions<Model, Message, Services>>) => Subscriptions<Model, Message, Services>;
    <Records extends AnySubscriptionsList>(...records: CompatibleSubscriptions<Records>): MergeSubscriptions<Records>;
}

AnimationFrameConfig

Configuration for the `animationFrameEntry` Subscription helper. `isActive(model)` controls whether the request-animation-frame loop is scheduled at all. When it returns `false` (e.g. the game is paused, the scene is static, or the canvas is offscreen), no rAF callbacks fire and no Messages are emitted. The Subscription system automatically restarts the loop when `isActive` flips back to `true`.

export type AnimationFrameConfig<Model, Message> = Readonly<{
    isActive: (model: Model) => boolean;
    toMessage: (deltaTime: number) => Message;
}>;

animationFrameEntry

Build a Subscription entry that emits a Message on every `requestAnimationFrame` tick, with the inter-frame delta in milliseconds.

animationFrameEntry: <Model, Message>(config: AnimationFrameConfig<Model, Message>) => {
    dependenciesSchema: Schema.Struct<{
        readonly isActive: Schema.Boolean;
    }>;
    modelToDependencies: (model: Model) => {
        isActive: boolean;
    };
    dependenciesToStream: ({ isActive }: {
        readonly isActive: boolean;
    }) => Stream.Stream<Message, never, never>;
}

EntryGates

Additional parent conditions for named entries in a lift's `when` map. Entries omitted from the map run whenever `read` returns a child Model.

export type EntryGates<ParentModel, Subscriptions> = Readonly<Partial<Record<keyof Subscriptions, WhenPredicate<ParentModel>>>>;

EntryWithoutKeepAlive

The entry shape produced by helpers like `Subscription.persistentEntry` and `Port.subscriptionEntry` before branding. Pass values of this shape into `Subscription.make` as entry values.

export type EntryWithoutKeepAlive<Model, Message, Dependencies, Services> = {
    readonly dependenciesSchema: DependenciesSchema<Dependencies>;
    readonly modelToDependencies: (model: Model) => Dependencies;
    readonly keepAliveEquivalence?: never;
    readonly dependenciesToStream: (dependencies: Dependencies) => Stream.Stream<Message, never, Services>;
};

GatedDependencies

The dependencies of a lifted Subscription. `maybeDependencies` holds the child's dependencies while `read` returns `Some` and its `when` gate is open. Otherwise it holds `None`, which tears down the entry's Stream and skips the child's `modelToDependencies`.

export type GatedDependencies<Dependencies> = Readonly<{
    maybeDependencies: Option.Option<Dependencies>;
}>;

lift

lift: <Subscriptions extends Readonly<Record<string, Subscription<any, any, any, any>>>>(subscriptions: Subscriptions) => <ParentModel, ParentMessage>(config: LiftConfig<ParentModel, ParentMessage, Subscriptions>) => LiftedSubscriptions<ParentModel, ParentMessage, Subscriptions>

make

Declares a Subscriptions record. The Model, Message, and optional Services generics are provided up front; the entries record follows, built from calls to the `entry` builder passed into the inner function. Reach for `Subscription.aggregate` to combine multiple records, and `Subscription.lift` to translate a child Submodel's record into a parent context.

make: <Model, Message, Services = never>() => <Entries extends Readonly<Record<string, Entry<Model, Message, any, Services>>>>(build: (entry: EntryBuilder<Model, Message, Services>) => Entries) => { readonly [K in keyof Entries]: Entries[K] & SubscriptionBrand; }

persistentEntry

Wraps a Stream as a Subscription entry with no dependencies on its own Model. Local Model changes do not restart the Stream. A parent can still gate the entry when lifting it, so the Stream starts and stops with that parent condition. Use for work such as system theme listeners, viewport width observers, or route-independent timers. Returns an entry shape, not a branded Subscription. Pass it into `make` as an entry value.

persistentEntry: <Message, Services = never>(stream: Stream.Stream<Message, never, Services>) => EntryWithoutKeepAlive<unknown, Message, Record<string, never>, Services>

Subscription

A single subscription entry produced by `Subscription.make`, `Subscription.lift`, or `Subscription.aggregate`. The brand field is `never`, so application code cannot manually construct a `Subscription` value: it must go through one of those constructors (or a helper like `Subscription.persistentEntry` that returns an entry shape, then through `make`). Two variants by `keepAliveEquivalence` presence: - Without `keepAliveEquivalence` (the common case), every Model change recomputes the dependencies. Equivalent dependencies leave the Stream alone; any change tears it down and restarts. `dependenciesToStream` takes a single argument: the latest dependencies. - With `keepAliveEquivalence` (an escape hatch), Model changes that the equivalence treats as equal leave the Stream running, but the running Stream can still read the latest dependencies via the second `readDependencies` argument. Use this when the Stream needs mid-flight access to data that changes often but shouldn't trigger restarts (Foldkit UI's `DragAndDrop.autoScroll` reading the latest pointer `clientY` each rAF tick is the canonical example). `dependenciesSchema` must be a `Schema.Struct` so every dependency is explicitly named at the schema level.

export type Subscription<Model, Message, Dependencies, Services = never> = Entry<Model, Message, Dependencies, Services> & SubscriptionBrand;

Subscriptions

A record of named Subscriptions keyed by dependency field name.

export type Subscriptions<Model, Message, Services = never> = Readonly<Record<string, Subscription<Model, Message, any, Services>>>;