Skip to main content
On this pageFunctions

Subscription

Functions

lift

functionsource
/**
 * 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>

make

functionsource
/**
 * 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
}

Types

EntryGates

typesource
/**
 * 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>>>>

EntryWithoutKeepAlive

typesource
/**
 * 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
}

GatedDependencies

typesource
/**
 * 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>
}>

HandlerOf

typesource
/** Extracts the exact handler requirement carried by a Subscription entry. */
type HandlerOf = ExtractHandler<Stream.Services<ReturnType<Entry["dependenciesToStream"]>>>

LayeredEntryWithKeepAlive

typesource
/**
 * 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>
}>

LayeredEntryWithoutKeepAlive

typesource
/**
 * 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>
}>

Registrations

typesource
/** 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
}>

Subscription

typesource
/**
 * 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

Subscriptions

typesource
/** A record of named Subscriptions keyed by dependency field name. */
type Subscriptions = Readonly<Record<string, Subscription<Model, Message, any, Services>>>

Interfaces

Handler

interfacesource
/**
 * 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>
  }>
}

ToLayerWithKeepAlive

interfacesource
/**
 * 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

ToLayerWithoutKeepAlive

interfacesource
/**
 * 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

Constants

aggregate

constsource
/**
 * 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>