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>>>;