actions/action_event.ts

ActionEvent — state machine for action lifecycle management.

Manages an action through its phases (send_request → receive_response, etc.) and steps (initial → parsed → handling → handled/failed).

Declarations
#

5 declarations

view source

ActionEvent
#

actions/action_event.ts view source

Action event that manages the lifecycle of an action through its state machine.

generics

TMethod

constraint string
default string

TPhase

constraint ActionEventPhase
default ActionEventPhase

TStep

constraint ActionEventStep
default ActionEventStep

environment

type ActionEventEnvironment

readonly

spec

method narrows to TMethod so consumers passing a typed TApi to create_rpc_client get event.spec.method typed as the union of their API's method names rather than plain string. The runtime value comes from lookup_action_spec(method) keyed off the Proxy get trap, so the narrowing matches the dispatched method.

type ActionSpecUnion & {method: TMethod}

readonly

constructor

type new <TMethod extends string = string, TPhase extends ActionEventPhase = "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute", TStep extends ActionEventStep = "initial" | ... 3 more ... | "failed">(environment: ActionEventEnvironment, spec: { ...; } | ... 1 more ... | { ...; }, data: ActionEventDataUnion<...>): ActionEvent<...>

environment
type ActionEventEnvironment
spec
type { method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 6 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } | { ...; }
data
type ActionEventDataUnion<TMethod>

toJSON

type (): ActionEventDataUnion<TMethod>

returns ActionEventDataUnion<TMethod>

observe

Subscribe a listener fired on every data transition.

type (listener: ActionEventChangeObserver<TMethod>): () => void

listener

called with (new_data, old_data, event) after each mutation

type ActionEventChangeObserver<TMethod>
returns () => void

unsubscribe function

set_data

Replace the event's data and notify observers.

type (new_data: ActionEventDataUnion<TMethod>): void

new_data
type ActionEventDataUnion<TMethod>
returns void

parse

Parse input data according to the action's schema.

type (): this

returns this

this for chaining with handle_async / handle_sync

throws
  • Error - if called from a step other than `initial`

handle_async

Execute the handler for the current phase.

type (): Promise<void>

returns Promise<void>
throws
  • Error - if called from a step other than `parsed` (or `failed`,

handle_sync

Execute handler synchronously (only for sync local_call actions).

type (): void

returns void
throws
  • Error - if the spec is not a sync `local_call`, or if called

transition

Transition to a new phase.

type (phase: "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"): void

phase

the next phase to transition into

type "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute"
returns void
throws
  • Error - if called from a step other than `handled` (or

is_complete

type (): boolean

returns boolean

update_progress

type (progress: unknown): void

progress
type unknown
returns void

set_request

type (request: { [x: string]: unknown; jsonrpc: "2.0"; id: string | number; method: string; params?: { [x: string]: unknown; } | undefined; }): void

request
type { [x: string]: unknown; jsonrpc: "2.0"; id: string | number; method: string; params?: { [x: string]: unknown; } | undefined; }
returns void

set_response

type (response: { [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: { [x: string]: unknown; }; } | { [x: string]: unknown; jsonrpc: "2.0"; id: string | number | null; error: { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<...>); message: string; data?: unknown; }; }): void

response
type { [x: string]: unknown; jsonrpc: "2.0"; id: string | number; result: { [x: string]: unknown; }; } | { [x: string]: unknown; jsonrpc: "2.0"; id: string | number | null; error: { [x: string]: unknown; code: -32700 | -32600 | -32601 | -32602 | -32603 | (number & $brand<...>); message: string; data?: unknown; }; }
returns void

set_notification

type (notification: { [x: string]: unknown; jsonrpc: "2.0"; method: string; params?: { [x: string]: unknown; } | undefined; }): void

notification
type { [x: string]: unknown; jsonrpc: "2.0"; method: string; params?: { [x: string]: unknown; } | undefined; }
returns void

ActionEventChangeObserver
#

create_action_event
#

actions/action_event.ts view source

<TMethod extends string = string>(environment: ActionEventEnvironment, spec: { method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<...>>; ... 7 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } | { ...; }, input: unknown, initial_phase?: "send_request" | ... 8 more ... | undefined): ActionEvent<...>

Create an action event from a spec and initial input.

environment

type ActionEventEnvironment

spec

type { method: string; initiator: "frontend" | "backend" | "both"; side_effects: boolean; input: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; output: ZodType<unknown, unknown, $ZodTypeInternals<unknown, unknown>>; ... 6 more ...; rate_limit?: "both" | ... 2 more ... | undefined; } | { ...; } | { ...; }

input

type unknown

initial_phase?

type "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute" | undefined
optional

returns

ActionEvent<TMethod, "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute", "initial" | "parsed" | "handling" | "handled" | "failed">

throws

  • Error - if `initial_phase` is omitted and the executor cannot

create_action_event_from_json
#

actions/action_event.ts view source

<TMethod extends string = string>(json: ActionEventDataUnion<TMethod>, environment: ActionEventEnvironment): ActionEvent<TMethod, "send_request" | ... 7 more ... | "execute", "initial" | ... 3 more ... | "failed">

Reconstruct an action event from serialized JSON data.

json

type ActionEventDataUnion<TMethod>

environment

type ActionEventEnvironment

returns

ActionEvent<TMethod, "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute", "initial" | "parsed" | "handling" | "handled" | "failed">

throws

  • Error - if the JSON's `method` field has no spec registered in `environment`

parse_action_event
#

actions/action_event.ts view source

(raw_json: unknown, environment: ActionEventEnvironment): ActionEvent<string, "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute", "initial" | ... 3 more ... | "failed">

raw_json

type unknown

environment

type ActionEventEnvironment

returns

ActionEvent<string, "send_request" | "receive_request" | "send_response" | "receive_response" | "send_error" | "receive_error" | "send" | "receive" | "execute", "initial" | "parsed" | "handling" | "handled" | "failed">

Depends on
#

Imported by
#