On this pageFunctions
Subscription
/**
* Low-level transformation of a Subscription record into another Model and
* Message context. Application Blocks use registered `bind` or `bindEach`
* placements, which also compose their handler recipes and other lifecycles.
*
* `read` returns `Some(childModel)` while the child exists and `None` while
* it is absent.
* An absent child tears down every entry's Stream without reading the
* child's dependencies. Use `Option.some` for a child that is always present.
*
* The optional `when` adds conditions from the parent Model. One predicate
* gates every entry; an EntryGates map adds a gate only to its named
* entries. An entry runs only while its gate is open and `read` returns
* `Some`. A closed gate skips `read` as well as the child's dependency
* projection. Entries omitted from a gate map still stop when the child
* is absent.
*
* Every lifted entry wraps its dependencies in GatedDependencies.
* The child's dependency Schema, declared Messages, handler Layer helper,
* service requirements, and
* `keepAliveEquivalence` are preserved inside that wrapper. A running child
* Stream's `readDependencies` receives current child dependencies while
* active, with its starting dependencies as a fallback during teardown.
*/
<Subscriptions extends AnySubscriptions>(subscriptions: Subscriptions): (config: LiftConfig<ParentModel, ParentMessage, Subscriptions>) => LiftedSubscriptions<ParentModel, ParentMessage, Subscriptions>/**
* Low-level builder for a Subscription registry. The Model and Message
* generics are provided up front; the callback builds a record with `entry`.
*
* Application features use their Block definition's `subscriptions`
* helper, which also qualifies the handler identities. Pass the resulting
* registry as `subscriptions` and its local handler recipes through
* `EffectsLayer` when calling `Composition.prepareBlock`. Registered child bindings
* collect their own registries automatically.
*/
<Model, Message>(): (build: (entry: EntryBuilder<Model>) => Entries) => {
readonly [K in string | number | symbol]: Entries[K] & SubscriptionBrand
}/**
* Additional parent conditions for named entries in a lift's `when` map.
* Entries omitted from the map run whenever `read` returns a child Model.
*/
type EntryGates = Readonly<Partial<Record<keyof RegistryEntries<Subscriptions>, WhenPredicate<ParentModel>>>>/**
* The runtime shape of a Subscription entry without
* `keepAliveEquivalence`. Applications declare entries with
* make rather than constructing this shape directly.
*/
type EntryWithoutKeepAlive = {
dependenciesSchema: DependenciesSchema<Dependencies>
dependenciesToStream: (dependencies: Dependencies) => Stream.Stream<Message, never, Services>
keepAliveEquivalence: never
modelToDependencies: (model: Model) => Dependencies
}/**
* 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`.
*/
type GatedDependencies = Readonly<{
maybeDependencies: Option.Option<Dependencies>
}>/** Extracts the exact handler requirement carried by a Subscription entry. */
type HandlerOf = ExtractHandler<Stream.Services<ReturnType<Entry["dependenciesToStream"]>>>/**
* A keep-alive Subscription entry whose Stream implementation is supplied by
* a Layer. Its declared `messages` constrain the handler Stream output.
*/
type LayeredEntryWithKeepAlive = EntryWithKeepAlive<Model, Message, Dependencies, Handler<Name, Dependencies, Message>> & Readonly<{
messages: Messages
name: Name
toLayer: ToLayerWithKeepAlive<Name, Dependencies, Message>
}>/**
* A Subscription entry whose Stream implementation is supplied by a Layer.
* `messages` declares the schemas the handler Stream may emit; `toLayer`
* accepts only that Message union.
*/
type LayeredEntryWithoutKeepAlive = EntryWithoutKeepAlive<Model, Message, Dependencies, Handler<Name, Dependencies, Message>> & Readonly<{
messages: Messages
name: Name
toLayer: ToLayerWithoutKeepAlive<Name, Dependencies, Message>
}>/** A Subscription entry record, including an owned Definition registry with an aggregate Layer recipe. */
type Registrations = Subscriptions<Model, Message, Services> | Registry<Subscriptions<Model, Message, Services>> & Readonly<{
layer: Layer.Any
}>/**
* 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.
*
* 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.
*/
type Subscription = Entry<Model, Message, Dependencies, Services> & SubscriptionBrand/** A record of named Subscriptions keyed by dependency field name. */
type Subscriptions = Readonly<Record<string, Subscription<Model, Message, any, Services>>>/**
* The service required by a Subscription whose implementation is supplied by
* a Layer. Its name, decoded dependencies, and declared Message identify the
* handler contract.
*/
interface Handler {
[HandlerTypeId]: Readonly<{
dependencies: Invariant<Dependencies>
message: Invariant<Message>
name: Invariant<Name>
}>
}/**
* Creates a Layer recipe from a Subscription handler with `keepAliveEquivalence`.
* An Effect constructor runs once when the application Layer is built and may
* capture shared services. The returned handler receives Model dependencies
* and `readDependencies` each time Foldkit starts the Stream. Keep reads of
* changing dependencies inside that handler or Stream.
* Captured services retain their identity; service lookups inside the Stream
* use its invocation context over the construction context. Provide test
* services before building the same handler Layer to test its transformations.
*/
interface ToLayerWithKeepAlive unknown/**
* Creates a Layer recipe from a Subscription handler without `keepAliveEquivalence`.
* An Effect constructor runs once when the application Layer is built and may
* capture shared services. The returned handler receives Model dependencies
* each time Foldkit starts the Stream, whose resources follow that Stream's scope.
* Captured services retain their identity; service lookups inside the Stream
* use its invocation context over the construction context. Provide test
* services before building the same handler Layer to test its transformations.
*/
interface ToLayerWithoutKeepAlive unknown/**
* Combines multiple Subscriptions records into one. Throws on duplicate
* keys so a misconfigured aggregate fails loudly at startup rather than
* silently overriding.
*
* Pass the records directly and the Model, Message, and Services are read
* off them. The Model of the first record with a Model dependency is the one
* every later record is checked against, so a record from another Model
* universe fails at its own argument position. Message and Services widen to
* the union across all records, which is what lets a record that needs an
* Effect service sit beside records that need none.
*
* The direct form keeps each record's keys and each entry's exact dependency
* type, declared Messages, attached `.layer` recipe when present, `toLayer`
* helper, schema, and
* `keepAliveEquivalence` variant, so a lifted entry's
* GatedDependencies survives aggregation.
*
* The curried form supplies the Model and Message context before the records
* exist. Its inner call infers the records and preserves their keys, dependency
* types, declared Messages, and exact handler requirements.
*/
const aggregate: () => (records: Records) => MergeSubscriptions<Records>