A11 TypeScript API - v0.7.0
    Preparing search index...

    Class Action

    One schema-described unit of local work or remote agent work.

    An action binds an ActionSchema to input/output AsyncNodes and, for a local run, an application handler. It is a one-shot state machine: configure the id, schema, collaborators, headers, and port mappings; then choose run for local execution or call for remote dispatch. Configuration that changes identity or port shape is frozen after start.

    Remote calls have two milestones. waitForDispatch reports whether the peer accepted the action, while wait follows its eventual status after handler and output-writer cleanup. Local handlers can create children with makeNested; a shared session applies nested limits and includes tracked children in session-wide abort. Cancelling a parent recursively cancels every active child.

    const action = valueOrThrow(Action.create(schema, { handler }));
    valueOrThrow(action.run());
    const result = valueOrThrow(await action.getOutput('result', false));
    const value = valueOrThrow(await result.next());
    valueOrThrow(await action.wait());
    Index
    • get signal(): AbortSignal

      AbortSignal a handler can observe for cooperative cancellation.

      Returns AbortSignal

    • Materialize schema autofills into empty input nodes before a handler runs.

      Returns Promise<Status>

    • Set whether opened inputs attach to the action transport by default.

      Parameters

      • bind: boolean

      Returns Status

    • Set whether opened outputs attach to the action transport by default.

      Parameters

      • bind: boolean

      Returns Status

    • Request cooperative cancellation once.

      Local handlers observe signal; remote calls also send the reserved cancellation action. cancel() initiates the transition; await wait() if teardown and output abort propagation must be complete.

      Returns Status

    • Set whether terminal cleanup removes input nodes from the node map.

      Parameters

      • clear: boolean = true

      Returns Status

    • Set whether terminal cleanup removes output nodes from the node map.

      Parameters

      • clear: boolean = true

      Returns Status

    • Whether the schema maps an input or output with this name.

      Parameters

      • name: string

      Returns boolean

    • Copy framework-scoped metadata to a nested action.

      Parameters

      • target: Action
      • prefix: string = ACTION_HEADER_PREFIX

      Returns Status

    • Return a copy of one header, or null when absent.

      Parameters

      • name: string

      Returns StatusOr<Uint8Array<ArrayBufferLike> | null>

    • Stable id shared by action messages and port node ids.

      Returns string

    • Open a named input node and optionally mirror local writes to the peer.

      Parameters

      • name: string
      • OptionalbindStream: boolean

      Returns Promise<StatusOr<AsyncNode>>

    • Return the log port's node, claiming it for this consumer.

      Claiming suppresses the process sink for this action, so a consumer that presents the logs itself does not also have them reported twice. Claim before the action runs: logs written earlier have already gone to the sink.

      The stream is not bound: on the calling side, binding an output would echo received fragments back to the peer.

      Returns Promise<StatusOr<AsyncNode>>

    • Open a named output node and optionally mirror local writes to the peer.

      Parameters

      • name: string
      • OptionalbindStream: boolean

      Returns Promise<StatusOr<AsyncNode>>

    • Whether remote dispatch has started.

      Returns boolean

    • Whether local execution has started.

      Returns boolean

    • Whether a local implementation is bound.

      Returns boolean

    • Whether a valid header name is present.

      Parameters

      • name: string

      Returns boolean

    • Whether cancellation was requested or became the terminal status.

      Returns boolean

    • Whether terminal status and cleanup have completed.

      Returns boolean

    • Log value on the reserved ACTION_LOG_OUTPUT port.

      The value becomes a chunk the way node.put(value) would make one -- a string is text/plain, a Uint8Array is application/octet-stream -- and the chunk always carries a timestamp.

      Only a running handler may log: logging before run, or on the calling side of a call, is a failed precondition, because the port would have nowhere to go and no reader to close it. Nothing else about logging fails the action -- once the chunk is built, a transport or lifecycle problem is reported through the sink rather than returned.

      Where it goes: always to the process's action log sink, and additionally onto the log port when something could read it -- a peer is attached, or a local consumer claimed the port with getLogNode. Nobody has to drain it and nobody has to close it.

      Parameters

      Returns Promise<Status>

    • Log a formatted line: %s is replaced by each argument in turn.

      Uses positional %s replacements and %% for literal percent signs across language runtimes.

      Parameters

      • format: string
      • ...args: unknown[]

      Returns Promise<Status>

    • Log a formatted line with explicit options.

      A second name rather than an overload, so it matches the C++ surface, where a leading-options overload of Logf is ambiguous against the format spec.

      Parameters

      • options: LogOptions
      • format: string
      • ...args: unknown[]

      Returns Promise<Status>

    • Create a child action from a schema or registered name.

      With propagateIo, the child shares the parent's node map, stream, and session, while retaining its own id, derived port ids, and AbortSignal. The registry is shared in either mode, and framework headers are forwarded when forwardHeaders is true. A shared session supplies nested concurrency limits and session-wide abort. Parent cancellation reaches the child even when propagateIo is false.

      Parameters

      • schemaOrName: string | ActionSchema
      • propagateIo: boolean = true
      • forwardHeaders: boolean = true

      Returns StatusOr<Action>

    • Replace the call id and remap default port ids before starting.

      Parameters

      • id: string

      Returns Status

    • Await the remote dispatch acknowledgement, not handler completion.

      Parameters

      • OptionaltimeoutMs: number

      Returns Promise<Status>

    • Derive the stable action-id#port-name id for one action port node.

      Parameters

      • actionId: string
      • nodeName: string

      Returns StatusOr<string>