Skip to main content
On this pageFunctions

Command

Functions

define

functionsource

Types

Command

typesource
/**
 * A named Effect that produces a message, optionally carrying the args used
 *  to construct it. `key` is present on Commands built by
 *  `define` with `interrupt`: it addresses the invocation in the runtime's
 *  interrupt registry so a later Interrupt Command can stop it.
 */
type Command = [T] extends [Schema.Top]
  ? Readonly<{
    args: Record<string, unknown>
    effect: Effect.Effect<Schema.Schema.Type<T>, E, R>
    key: string
    name: string
  }>
  : Readonly<{
    args: Record<string, unknown>
    effect: Effect.Effect<T, E, R>
    key: string
    name: string
  }>

CommandDefinition

typesource
/** A Command definition created with `Command.define`. Union over the no-args and with-args shapes; consumers that only need name/identity can accept this. */
type CommandDefinition = CommandDefinitionNoArgs<Name, Effect.Effect<ResultMessage, any, any>> | CommandDefinitionWithArgs<Name, any, Effect.Effect<ResultMessage, any, any>>

HandlerOf

typesource
/**
 * Extracts the exact handler requirement carried by a Command definition.
 * Prefer this to repeating the definition's decoded args and result Message in
 * an explicit Handler annotation.
 */
type HandlerOf = ReturnType<Definition>["effect"] extends Effect.Effect<any, any, infer R>
  ? ExtractHandler<R>
  : never

InterruptOption

typesource
/**
 * Makes a Command interruptible. `true` keys every invocation by the Command
 *  name, which is what you want when at most one invocation is meaningfully in
 *  flight. `{ keyFields, toKey }` derives the key part from declared args, so
 *  invocations that run concurrently can be interrupted independently.
 *  `keyFields` declares the exact args the Interrupt constructor requires.
 *  Derive the key part from the Model identity that owns the in-flight work (a
 *  list item id, an entity id), never from a generated value: update is pure,
 *  and any invocation you can meaningfully target is already distinguished by
 *  data in the Model.
 */
type InterruptOption = true | Readonly<{
  keyFields: Array.NonEmptyReadonlyArray<KeyField>
  toKey: (keyArgs: Pick<Args, KeyField>) => string
}>

Interfaces

CommandDefinitionNoArgs

interfacesource
/** A Command definition for a Command with no declared args. Call as `Definition()` to produce a Command instance. */
interface CommandDefinitionNoArgs {
  [CommandDefinitionTypeId]: typeof CommandDefinitionTypeId
  name: Name
}

CommandDefinitionWithArgs

interfacesource
/** A Command definition for a Command with declared args. Call as `Definition(args)` to produce a Command instance. */
interface CommandDefinitionWithArgs {
  [CommandDefinitionTypeId]: typeof CommandDefinitionTypeId
  name: Name
}

DefinitionNoArgs

interfacesource
/**
 * An interruptible Command definition with no declared args; its key is the
 *  Command name. Call as `Definition()` to produce a Command instance; use
 *  `Definition.Interrupt` to build the Command that stops it.
 */
interface DefinitionNoArgs {
  [CommandDefinitionTypeId]: typeof CommandDefinitionTypeId
  Interrupt: InterruptDefinitionNoArgs<Name>
  name: Name
}

DefinitionWithArgs

interfacesource
/**
 * An interruptible Command definition with declared args and a key derived
 *  from them, namespaced by the Command name. Call as `Definition(args)` to
 *  produce a Command instance; use `Definition.Interrupt` to build the
 *  Command that stops every holder of a specific key.
 */
interface DefinitionWithArgs {
  [CommandDefinitionTypeId]: typeof CommandDefinitionTypeId
  Interrupt: InterruptDefinitionWithArgs<Name, KeyArgs>
  name: Name
}

DefinitionWithArgsNameKeyed

interfacesource
/**
 * An interruptible Command definition with declared args but no `toKey`, so
 *  its key is the Command name, exactly like the no-args form. Call as
 *  `Definition(args)` to produce a Command instance; use `Definition.Interrupt`
 *  to build the Command that stops it. Reach for this when a Command takes args
 *  yet at most one invocation is meaningfully in flight, so its invocations need
 *  nothing to distinguish them.
 */
interface DefinitionWithArgsNameKeyed {
  [CommandDefinitionTypeId]: typeof CommandDefinitionTypeId
  Interrupt: InterruptDefinitionNoArgs<Name>
  name: Name
}

Handler

interfacesource
/**
 * The service required by a Command whose implementation is supplied by a
 * Layer. Its name, decoded arguments, and declared result Message identify the
 * handler contract.
 */
interface Handler {
  [HandlerTypeId]: Readonly<{
    args: Invariant<Args>
    message: Invariant<Message>
    name: Invariant<Name>
  }>
}

LayeredCommandDefinitionNoArgs

interfacesource
/** A Command definition whose execution is supplied by a handler Layer. */
interface LayeredCommandDefinitionNoArgs {
  [CommandDefinitionTypeId]: typeof CommandDefinitionTypeId
  name: Name
  toLayer: ToLayer<Name, void, Message>
}

LayeredCommandDefinitionWithArgs

interfacesource
/** An argument-bearing Command definition whose execution is supplied by a handler Layer. */
interface LayeredCommandDefinitionWithArgs {
  [CommandDefinitionTypeId]: typeof CommandDefinitionTypeId
  name: Name
  toLayer: ToLayer<Name, View<Fields, "Type", TypeOptionalKeys<Fields>, TypeMutableKeys<Fields>>, Message>
}

ToLayer

interfacesource
/**
 * Creates a Layer recipe from an Effect that constructs a Command handler.
 * The runtime builds the application Layer once before init. An Effect
 * constructor can capture shared services and return the handler; its body
 * receives arguments and performs work on each Command execution.
 * Provide test services before building the Layer to run the same handler logic.
 * Services captured by the constructor retain their identity. Service lookups
 * inside execution use the invocation context over the construction context.
 * Arguments are dispatch data; services enter through Effect requirements.
 */
interface ToLayer unknown

Constants

CommandDefinitionTypeId

constsource
/** Type-level brand for CommandDefinition values. */
const CommandDefinitionTypeId: unique symbol

mapEffect

constsource
/**
 * Transforms the Effect inside a Command while preserving its result Message,
 *  name, args, and message-mapping chain. Reach for this to provide a service,
 *  add a delay or retry, or change the error or requirement channel. Its type
 *  prevents the transform from changing the result Message. Never use it to
 *  lift that Message, even via
 *  `Effect.map(message => Message.GotChildMessage({ message }))`. That dispatches
 *  correctly in production but is invisible to `Story`/`Scene` `resolve`, which
 *  replays only the recorded chain and never runs the Effect, so the test would
 *  see the child's raw Message instead of the wrapped one. Lift result Messages
 *  with mapMessage / mapMessages, which record the lift. The
 *  `foldkit/prefer-command-mapmessage` lint rule flags this misuse.
 */
const mapEffect: (f: (effect: Effect<A, E1, R1>) => Effect<NoInfer<A>, E2, R2>) => (command: Command<A, E1, R1>) => Command<A, E2, R2>

mapMessage

constsource
/**
 * Lifts a single Command's result Message through `f`, transforming
 *  `FromMessage` to `ToMessage`. The singular complement to
 *  mapMessages: reach for this when a child returns one Command
 *  (e.g. an animation leave Command), reach for `mapMessages` when it
 *  returns a list.
 * 
 *  Fuses `f` into the Effect so production dispatch is unchanged, and also
 *  records `f` on the Command's internal message-mapping chain. The chain is
 *  recoverable metadata the runtime never reads: `Story.Command.resolve` and
 *  `Scene.Command.resolve` replay the matched Command's chain over a substitute
 *  result, so a root test resolves with the child's raw result Message and
 *  never restates the wrapping by hand.
 * 
 *  Preserves the Command's `name` and `args` so traces still attribute
 *  it to the originating Block. When you need to transform the
 *  Effect itself (not just the result Message), reach for
 *  mapEffect instead.
 * 
 *  Typed against Command in argument and result positions, so a
 *  generic combinator over a type-parameter Message unifies with
 *  `Command.Command<Message>` directly.
 */
const mapMessage: (command: Command<FromMessage, E, R>, f: (message: FromMessage) => ToMessage) => Command<ToMessage, E, R>

mapMessages

constsource
/**
 * Lifts every Command in a list through `f`, transforming the result
 *  Message type from `FromMessage` to `ToMessage`. When `commands` is
 *  `undefined`, it returns an empty array. Registered Block bindings handle
 *  this mapping through their `init`, `fold`, and projected exposed
 *  operations. An OutMessage policy uses its `FoldContext.liftCommand` for a
 *  child Command. Use `mapMessages` for a standalone batch outside Block
 *  composition:
 * 
 *  ```ts
 *  const commands = Command.mapMessages(
 *    [Feed.RefreshSummary(), Feed.RefreshTimeline()],
 *    toGotFeedMessage,
 *  )
 *  ```
 * 
 *  Fuses `f` into each Command's Effect and also records it on the Command's
 *  internal message-mapping chain, so production dispatch is unchanged while
 *  `Story.Command.resolve` / `Scene.Command.resolve` can recover the mapping
 *  from the matched Command.
 *  Preserves each Command's `name` and `args` so traces still attribute the
 *  Command to the originating Block. When you need to transform the Effect
 *  itself (not just the result Message), reach for mapEffect instead.
 * 
 *  Typed against Command in argument and result positions, so a
 *  generic combinator over a type-parameter Message unifies with
 *  `Command.Command<Message>` directly.
 */
const mapMessages: (commands: Commands, f: (message: Success<Commands[number]["effect"]>) => ToMessage) => readonly Array<Command<ToMessage, Error<Commands[number]["effect"]>, Services<Commands[number]["effect"]>>> & CollectionMetadata<Commands>