actions/action_bridge.ts

Bridge functions to derive RouteSpec and SseEventSpec from ActionSpec.
Action specs define the contract (method, input/output, auth, side effects).
Bridge functions produce transport-specific specs from them. HTTP-specific
concerns (path, handler) come from options.

Declarations
#

6 declarations

view source

ActionEventOptions
#

actions/action_bridge.ts view source

ActionEventOptions

Options for deriving an SseEventSpec from an ActionSpec.

`channel`

type string

ActionRouteOptions
#

actions/action_bridge.ts view source

ActionRouteOptions

Options for deriving a RouteSpec from an ActionSpec.

`path`

type string

`handler`

type RouteHandler

`params`

URL path parameter schema. Use z.strictObject() with string fields matching :param segments.

type z.ZodObject

`query`

URL query parameter schema. Use z.strictObject() with string fields.

type z.ZodObject

`http_method`

Override the default HTTP method (default: side_effects → POST, else GET).

type RouteMethod

`auth`

Override the default auth mapping (default: 'public' → none, 'authenticated' → authenticated, 'keeper' → keeper, {role} → role).

type RouteAuth

`errors`

Handler-specific error schemas (HTTP status code → Zod schema). Transport-specific — not on ActionSpec.

type RouteErrorSchemas

derive_http_method
#

actions/action_bridge.ts view source

(side_effects: true | null): RouteMethod

Derive the default HTTP method from side effects.

`side_effects`

type true | null

returns

RouteMethod

event_spec_from_action
#

actions/action_bridge.ts view source

(spec: { method: string; kind: "request_response" | "remote_notification" | "local_call"; initiator: "frontend" | "backend" | "both"; auth: "public" | "authenticated" | "keeper" | { ...; } | null; ... 4 more ...; description: string; }, options?: ActionEventOptions | undefined): SseEventSpec

Derive an SseEventSpec from an ActionSpec.
Only remote_notification actions can become SSE events.

`spec`

the action spec (must have kind: 'remote_notification')

type

{ method: string; kind: "request_response" | "remote_notification" | "local_call"; initiator: "frontend" | "backend" | "both"; auth: "public" | "authenticated" | "keeper" | { role: string; } | null; ... 4 more ...; description: string; }

`options?`

optional SSE-specific options (channel)

type ActionEventOptions | undefined

optional

returns

SseEventSpec

an SseEventSpec ready for create_validated_broadcaster

map_action_auth
#

actions/action_bridge.ts view source

(auth: "public" | "authenticated" | "keeper" | { role: string; }): RouteAuth

Map an ActionAuth value to a RouteAuth.

`auth`

type "public" | "authenticated" | "keeper" | { role: string; }

returns

RouteAuth

route_spec_from_action
#

actions/action_bridge.ts view source

(spec: { method: string; kind: "request_response" | "remote_notification" | "local_call"; initiator: "frontend" | "backend" | "both"; auth: "public" | "authenticated" | "keeper" | { ...; } | null; ... 4 more ...; description: string; }, options: ActionRouteOptions): RouteSpec

Derive a RouteSpec from an ActionSpec and options.
Only request_response actions (which require non-null auth) can become routes.
remote_notification actions (auth null) should use event_spec_from_action.
local_call actions are not for HTTP transport.
Error schemas are transport-specific (keyed by HTTP status codes) and belong
on the options, not the action spec. Action specs define the contract;
transport concerns like HTTP error codes are added at the bridge layer.

`spec`

the action spec (must have non-null auth)

type

{ method: string; kind: "request_response" | "remote_notification" | "local_call"; initiator: "frontend" | "backend" | "both"; auth: "public" | "authenticated" | "keeper" | { role: string; } | null; ... 4 more ...; description: string; }

`options`

HTTP-specific options (path, handler, optional overrides)

type ActionRouteOptions

returns

RouteSpec

a RouteSpec ready for apply_route_specs

throws

if - `spec.auth` is null