@fuzdev/fuz_app 0.49.0 → 0.51.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/actions/CLAUDE.md +56 -21
- package/dist/actions/action_codegen.d.ts +60 -34
- package/dist/actions/action_codegen.d.ts.map +1 -1
- package/dist/actions/action_codegen.js +80 -46
- package/dist/actions/action_registry.d.ts +1 -1
- package/dist/actions/action_registry.js +1 -1
- package/dist/actions/action_spec.d.ts +1 -1
- package/dist/actions/action_spec.js +1 -1
- package/dist/actions/action_types.d.ts +4 -4
- package/dist/actions/action_types.js +4 -4
- package/dist/actions/cancel.d.ts +13 -11
- package/dist/actions/cancel.d.ts.map +1 -1
- package/dist/actions/cancel.js +13 -11
- package/dist/actions/frontend_rpc_client.d.ts +9 -0
- package/dist/actions/frontend_rpc_client.d.ts.map +1 -1
- package/dist/actions/heartbeat.d.ts +11 -8
- package/dist/actions/heartbeat.d.ts.map +1 -1
- package/dist/actions/heartbeat.js +11 -8
- package/dist/actions/protocol.d.ts +47 -0
- package/dist/actions/protocol.d.ts.map +1 -0
- package/dist/actions/protocol.js +46 -0
- package/dist/actions/register_action_ws.d.ts +5 -4
- package/dist/actions/register_action_ws.d.ts.map +1 -1
- package/dist/actions/register_action_ws.js +2 -2
- package/dist/auth/account_action_specs.d.ts +1 -1
- package/dist/auth/account_action_specs.js +1 -1
- package/dist/auth/account_actions.d.ts +2 -2
- package/dist/auth/account_actions.js +2 -2
- package/dist/auth/account_routes.d.ts +3 -3
- package/dist/auth/account_routes.js +3 -3
- package/dist/auth/account_schema.d.ts +1 -1
- package/dist/auth/account_schema.js +1 -1
- package/dist/auth/admin_action_specs.d.ts +1 -1
- package/dist/auth/admin_action_specs.js +1 -1
- package/dist/auth/admin_actions.d.ts +2 -2
- package/dist/auth/admin_actions.js +2 -2
- package/dist/auth/api_token.d.ts +1 -1
- package/dist/auth/api_token.js +1 -1
- package/dist/auth/audit_log_routes.d.ts +1 -1
- package/dist/auth/audit_log_routes.js +1 -1
- package/dist/auth/audit_log_schema.d.ts +1 -1
- package/dist/auth/daemon_token.d.ts +1 -1
- package/dist/auth/daemon_token.js +1 -1
- package/dist/auth/daemon_token_middleware.d.ts +1 -1
- package/dist/auth/daemon_token_middleware.js +1 -1
- package/dist/auth/ddl.d.ts +1 -1
- package/dist/auth/ddl.js +1 -1
- package/dist/auth/password.d.ts +1 -1
- package/dist/auth/password.js +1 -1
- package/dist/auth/permit_offer_action_specs.d.ts +1 -1
- package/dist/auth/permit_offer_action_specs.js +1 -1
- package/dist/auth/permit_offer_actions.d.ts +1 -1
- package/dist/auth/permit_offer_actions.js +1 -1
- package/dist/auth/route_guards.d.ts +1 -1
- package/dist/auth/route_guards.js +1 -1
- package/dist/auth/self_service_role_action_specs.d.ts +1 -1
- package/dist/auth/self_service_role_action_specs.js +1 -1
- package/dist/auth/self_service_role_actions.d.ts +1 -1
- package/dist/auth/self_service_role_actions.js +1 -1
- package/dist/auth/session_queries.d.ts +1 -1
- package/dist/auth/session_queries.js +1 -1
- package/dist/auth/signup_routes.d.ts +1 -1
- package/dist/auth/signup_routes.js +1 -1
- package/dist/auth/standard_action_specs.d.ts +1 -1
- package/dist/auth/standard_action_specs.js +1 -1
- package/dist/cli/util.d.ts +1 -1
- package/dist/cli/util.js +1 -1
- package/dist/db/create_db.d.ts +2 -2
- package/dist/db/create_db.js +2 -2
- package/dist/db/db.d.ts +3 -3
- package/dist/db/db.js +3 -3
- package/dist/hono_context.d.ts +1 -1
- package/dist/hono_context.js +1 -1
- package/dist/http/jsonrpc_errors.d.ts +2 -2
- package/dist/http/jsonrpc_errors.js +2 -2
- package/dist/http/jsonrpc_helpers.d.ts +2 -2
- package/dist/http/jsonrpc_helpers.js +2 -2
- package/dist/http/middleware_spec.d.ts +1 -1
- package/dist/http/middleware_spec.js +1 -1
- package/dist/http/origin.d.ts +1 -1
- package/dist/http/origin.js +1 -1
- package/dist/http/schema_helpers.d.ts +1 -1
- package/dist/http/schema_helpers.js +1 -1
- package/dist/http/surface.d.ts +1 -1
- package/dist/http/surface.js +1 -1
- package/dist/runtime/deno.d.ts +1 -1
- package/dist/runtime/deno.js +1 -1
- package/dist/runtime/node.d.ts +1 -1
- package/dist/runtime/node.js +1 -1
- package/dist/testing/rpc_attack_surface.js +1 -1
- package/dist/testing/rpc_helpers.js +1 -1
- package/dist/testing/ws_round_trip.js +1 -1
- package/dist/ui/account_sessions_state.svelte.d.ts +2 -2
- package/dist/ui/account_sessions_state.svelte.js +1 -1
- package/dist/ui/admin_rpc_adapters.d.ts +1 -1
- package/dist/ui/admin_rpc_adapters.js +1 -1
- package/package.json +1 -1
package/dist/actions/CLAUDE.md
CHANGED
|
@@ -116,12 +116,12 @@ not the runtime):
|
|
|
116
116
|
- `ImportBuilder` — tracks value / type / namespace imports; emits `import type` when every entry on a module is a type (tree-shaking). Namespace (`* as specs`) entries are emitted verbatim. Public surface: `add`, `add_type`, `add_many`, `add_types`, `build`, `preview`, `has_imports`, `import_count`, `clear`.
|
|
117
117
|
- `get_executor_phases(spec, executor)` — phases a given executor (`'frontend' | 'backend'`) participates in for the spec. Deduplicates via `Set` (handles `initiator: 'both'` overlap).
|
|
118
118
|
- `get_handler_return_type(spec, phase, imports, collections_path?)` — the TS type a phase handler must return; triggers the `ActionOutputs` import (sourced from `collections_path`, default `'./action_collections.js'`) as a side effect.
|
|
119
|
-
- `generate_phase_handlers(spec, executor, imports, {action_event_type?, collections_path?})` — emits the typed handler-map fragment for one action; consumers compose these into `ActionHandlers` types.
|
|
120
|
-
- `generate_actions_api_method_signature(spec, {sync_returns_value?})` — single source of truth for the typed `FrontendActionsApi` method shape. Threads `options?: RpcClientCallOptions` (`{signal?, transport_name?, queue?}`) onto every async method — `request_response`, `remote_notification`, and async `local_call` — and wraps the return in `Promise<Result<...>>`.
|
|
119
|
+
- `generate_phase_handlers(spec, executor, imports, {action_event_type?, collections_path?})` — emits the typed handler-map fragment for one action; consumers compose these into `ActionHandlers` types. Returns `''` when the spec contributes no phases on the given executor (e.g. a backend-only `local_call` asked for `'frontend'`) so wrappers' `.filter(Boolean)` drops the row entirely instead of emitting a useless `${method}?: never` for a method that doesn't belong on this side.
|
|
120
|
+
- `generate_actions_api_method_signature(spec, imports, {sync_returns_value?, collections_path?})` — single source of truth for the typed `FrontendActionsApi` method shape. Threads `options?: RpcClientCallOptions` (`{signal?, transport_name?, queue?}`) onto every async method — `request_response`, `remote_notification`, and async `local_call` — and wraps the return in `Promise<Result<...>>`. Registers exactly the imports the emitted line references on `imports` — `ActionInputs` only when the spec has input, `RpcClientCallOptions` only when async, `Result` / `JsonrpcErrorObject` only when the return wraps in `Result`. Mirrors the leaf-level pattern `get_handler_return_type` already follows so wrappers no longer pre-register imports a per-spec emit might not actually use.
|
|
121
121
|
- `create_banner(origin_path)` — gen banner comment.
|
|
122
122
|
- `to_action_spec_identifier(method)` / `to_action_spec_input_identifier` / `to_action_spec_output_identifier` — naming convention helpers (emit `foo_action_spec` / `foo_action_spec.input` / `foo_action_spec.output`).
|
|
123
|
-
- `
|
|
124
|
-
- `
|
|
123
|
+
- `PROTOCOL_ACTION_METHODS` (+ `ProtocolActionMethod` type) — readonly tuple `['heartbeat', 'cancel']`. Pairs with `protocol_actions` / `protocol_action_specs` in `actions/protocol.ts` (the runtime bundles). Consumers spread when filtering backend `request_response` methods so dispatcher-owned protocol actions don't leak into `BackendRequestResponseMethod` / handler maps.
|
|
124
|
+
- `is_protocol_action_method(method)` — type predicate paired with `PROTOCOL_ACTION_METHODS`; use this in `method_filter` callbacks instead of `PROTOCOL_ACTION_METHODS.includes(s.method as never)`.
|
|
125
125
|
- `DEFAULT_COLLECTIONS_PATH = './action_collections.js'` — shared default for every helper that takes a `collections_path?`.
|
|
126
126
|
- `DEFAULT_SPECS_MODULE = './action_specs.js'` — shared default for helpers that emit `specs.{method}_action_spec` and need a `* as specs` namespace import.
|
|
127
127
|
- `DEFAULT_METATYPES_PATH = './action_metatypes.js'` — shared default for the sibling module carrying the generated `ActionMethod` enum.
|
|
@@ -133,14 +133,15 @@ Composed by consumer `*.gen.ts` producers; outputs do not include the banner or
|
|
|
133
133
|
surrounding `imports.build()`. Use `compose_gen_file` to assemble the block
|
|
134
134
|
list + banner + imports into the final file body in one call.
|
|
135
135
|
|
|
136
|
-
**
|
|
137
|
-
`{
|
|
138
|
-
`cancel` from the emitted output.
|
|
139
|
-
spread into each consumer's `actions` array at
|
|
140
|
-
|
|
141
|
-
|
|
142
|
-
`
|
|
143
|
-
|
|
136
|
+
**Protocol actions are filtered by default.** Every spec-iterating helper
|
|
137
|
+
accepts `{include_protocol_actions?: boolean}` (default `false`) and drops
|
|
138
|
+
`heartbeat` / `cancel` from the emitted output. Protocol actions ship from
|
|
139
|
+
fuz_app and are spread into each consumer's `actions` array at
|
|
140
|
+
registration time (via `protocol_actions` from `actions/protocol.ts`) —
|
|
141
|
+
they should not appear in consumer-owned typed surfaces (`ActionMethod`,
|
|
142
|
+
`FrontendActionsApi`, `ActionInputs`, `FrontendActionHandlers`, etc.).
|
|
143
|
+
Pass `include_protocol_actions: true` only if a consumer genuinely owns
|
|
144
|
+
protocol actions in their typed API.
|
|
144
145
|
|
|
145
146
|
**Consumer tiers and namespace handling.** Single-source consumers (zzz,
|
|
146
147
|
undying — every spec lives in one local `action_specs.ts`) drop straight
|
|
@@ -167,15 +168,15 @@ interfaces — and never calls `generate_typed_action_event_alias` or
|
|
|
167
168
|
zzz) emits the full set including `ActionEventDatas`, `TypedActionEvent`,
|
|
168
169
|
and `FrontendActionHandlers`.
|
|
169
170
|
|
|
170
|
-
- `generate_action_method_enums(specs, imports, {emit?,
|
|
171
|
-
- `generate_action_method_enum_block(specs, imports, {name, jsdoc, predicate,
|
|
171
|
+
- `generate_action_method_enums(specs, imports, {emit?, include_protocol_actions?})` — up to nine `z.enum` + `z.infer` pairs (`ActionMethod`, `RequestResponseActionMethod`, `RemoteNotificationActionMethod`, `LocalCallActionMethod`, `FrontendActionMethod`, `BackendActionMethod`, `FrontendRequestResponseMethod`, `BackendRequestResponseMethod`, `BroadcastActionMethod`). `emit: ReadonlySet<ActionMethodEnumKind>` restricts to a subset (Tier 1 HTTP-only consumers don't need all nine). Skips kinds whose method list is empty (`z.enum([])` is invalid) and skips the `zod` import when no blocks are emitted. Adds `import {z} from 'zod'` only when at least one block is produced. The `frontend_handled` / `backend_handled` / `broadcast` kinds use the registry's narrow handler-side / streams-aware getters; the loose `frontend` / `backend` kinds preserve the everything-relevant-to-this-side semantic for the typed-Proxy method enum.
|
|
172
|
+
- `generate_action_method_enum_block(specs, imports, {name, jsdoc, predicate, include_protocol_actions?})` — lower-level escape hatch for genuinely cross-product enums the discriminator doesn't cover. Caller owns the predicate, name, and jsdoc.
|
|
172
173
|
- `generate_typed_action_event_alias(imports, {collections_path?, metatypes_path?})` — fixed-shape `TypedActionEvent<TMethod, TPhase, TStep>` alias narrowing `ActionEvent.data` against `ActionEventDatas`. Adds the three fuz_app type imports + `ActionEventDatas` (from `collections_path`) + `ActionMethod` (from `metatypes_path`).
|
|
173
|
-
- `generate_action_specs_record(specs, imports, {specs_module?, qualify_spec?,
|
|
174
|
-
- `generate_action_inputs_outputs(specs, imports, {specs_module?, qualify_spec?,
|
|
175
|
-
- `generate_action_event_datas(specs, imports, {same_file?, collections_path?,
|
|
176
|
-
- `generate_frontend_actions_api(specs, imports, {interface_name?, method_filter?, collections_path?, sync_returns_value?,
|
|
177
|
-
- `generate_frontend_action_handlers(specs, imports, {collections_path?,
|
|
178
|
-
- `generate_backend_actions_api(specs, imports, {interface_name?, spec_array_name?, specs_module?, collections_path?, qualify_spec?,
|
|
174
|
+
- `generate_action_specs_record(specs, imports, {specs_module?, qualify_spec?, include_protocol_actions?})` — `ActionSpecs` runtime const + interface + `action_specs: Array<ActionSpecUnion>` value. Adds `* as specs` from `specs_module` unless `qualify_spec` is set (then `specs_module` is ignored and the consumer owns namespace imports).
|
|
175
|
+
- `generate_action_inputs_outputs(specs, imports, {specs_module?, qualify_spec?, include_protocol_actions?})` — `ActionInputs` and `ActionOutputs` runtime consts + interfaces. Same `qualify_spec` semantics as `generate_action_specs_record`; the helper appends `.input` / `.output` to the qualified identifier.
|
|
176
|
+
- `generate_action_event_datas(specs, imports, {same_file?, collections_path?, include_protocol_actions?})` — `ActionEventDatas` interface; per-spec variant by kind (`ActionEventRequestResponseData` / `ActionEventRemoteNotificationData` / `ActionEventLocalCallData`). `same_file` (default `true`) is the file-layout switch: when `true`, assumes `ActionInputs` / `ActionOutputs` are in the same module and adds no import (the zzz pattern); when `false`, adds the type imports from `collections_path` (default `'./action_collections.js'`). `collections_path` alone is a no-op — the surprising omit-vs-default behavior of earlier versions has been replaced.
|
|
177
|
+
- `generate_frontend_actions_api(specs, imports, {interface_name?, method_filter?, collections_path?, sync_returns_value?, include_protocol_actions?})` — emits the typed `FrontendActionsApi` interface (configurable via `interface_name`, default `'FrontendActionsApi'`). One method signature per spec via `generate_actions_api_method_signature`. Protocol actions filtered by default; `method_filter: (spec) => boolean` runs after the protocol-action filter. Renamed from `generate_actions_api` in API review III to make the side-of-the-wire intent visible at every consumer site.
|
|
178
|
+
- `generate_frontend_action_handlers(specs, imports, {collections_path?, include_protocol_actions?})` — `FrontendActionHandlers` interface (Tier 2 only — wraps `generate_phase_handlers` with `action_event_type: 'TypedActionEvent'`). Pair with `generate_typed_action_event_alias`.
|
|
179
|
+
- `generate_backend_actions_api(specs, imports, {interface_name?, spec_array_name?, specs_module?, collections_path?, qualify_spec?, include_protocol_actions?})` — `BackendActionsApi` interface AND `broadcast_action_specs: ReadonlyArray<ActionSpecUnion>` array (both names configurable). Filter: `kind === 'remote_notification' && initiator !== 'frontend'`, with `streams`-target methods (request-scoped progress notifications invoked via `ctx.notify`) excluded — the discriminator is `ActionSpec.streams`, not a manual list. Adds `ActionInputs` (from `collections_path`) + `ActionSpecUnion`, plus `* as specs` from `specs_module` unless `qualify_spec` is set. Method shape today is `(input) => Promise<void>` (matches `create_broadcast_api`'s fire-and-forget runtime); generalizing to per-kind shapes via `generate_actions_api_method_signature` is deferred until a second backend runtime constructor lands (see SAES quest § API review III deferred set).
|
|
179
180
|
- `generate_backend_action_handlers_map(imports, options?)` — emits the `BackendActionHandlers` mapped type (`{[K in BackendRequestResponseMethod]: (input: ActionInputs[K], ctx: BackendHandlerContext) => ActionOutputs[K] | Promise<ActionOutputs[K]>}`). Replaces the hand-maintained `Exclude<>` + parallel mapped-type pattern (zzz had this at `zzz/src/lib/server/zzz_action_handlers.ts:42-66`). Configurable type name, method enum name, and context type name; configurable `collections_path` / `metatypes_path` for the type imports.
|
|
180
181
|
|
|
181
182
|
### Wrapper + multi-source helper
|
|
@@ -578,12 +579,46 @@ interface ActionPeerSendOptions extends TransportSendOptions {
|
|
|
578
579
|
Currently partial: `#receive_request`'s `send_response` transition step has
|
|
579
580
|
a known sharp edge ("shouldn't need the guard" TODO).
|
|
580
581
|
|
|
581
|
-
##
|
|
582
|
+
## Protocol actions (`heartbeat.ts`, `cancel.ts`, `protocol.ts`)
|
|
582
583
|
|
|
583
584
|
Two shared `{spec, handler}` tuples that every consumer spreads into both
|
|
584
585
|
sides' `actions` arrays — disconnect detection and per-request cancel work
|
|
585
586
|
identically across every repo without per-consumer ping plumbing.
|
|
586
587
|
|
|
588
|
+
The category is wire-protocol concerns shipped by fuz_app, not consumer
|
|
589
|
+
domain logic. The contrast that matters is protocol vs domain: a future
|
|
590
|
+
clock-skew probe or reconnect-resume token belongs in this bundle; a
|
|
591
|
+
`payment_charge` action does not. Avoid the framing "composable vs
|
|
592
|
+
non-composable" — every `Action` is composable by the same mechanism
|
|
593
|
+
(spread into the `actions` array), so the distinction would not carve
|
|
594
|
+
nature at the joints.
|
|
595
|
+
|
|
596
|
+
### Canonical bundles (`protocol.ts`)
|
|
597
|
+
|
|
598
|
+
Two const arrays declare the canonical protocol-action set so consumers
|
|
599
|
+
spread one symbol per side instead of importing each primitive
|
|
600
|
+
individually:
|
|
601
|
+
|
|
602
|
+
- `protocol_actions: ReadonlyArray<Action>` — for the server's
|
|
603
|
+
`register_action_ws` `actions` array. Spread before consumer-owned
|
|
604
|
+
actions: `actions: [...protocol_actions, ...consumer_actions]`.
|
|
605
|
+
- `protocol_action_specs: ReadonlyArray<ActionSpecUnion>` — derived via
|
|
606
|
+
`.map(a => a.spec)` so the two arrays cannot drift. For the frontend
|
|
607
|
+
`ActionRegistry`. Spread before consumer-owned specs:
|
|
608
|
+
`new ActionRegistry([...protocol_action_specs, ...action_specs])`.
|
|
609
|
+
|
|
610
|
+
The asymmetry is intentional — the server runs handlers (heartbeat echo +
|
|
611
|
+
cancel stub), the frontend registry only stores specs. Both bundles plus
|
|
612
|
+
the codegen `include_protocol_actions: false` default form a three-leg
|
|
613
|
+
contract: codegen excludes protocol actions from generated typed surfaces
|
|
614
|
+
because consumers spread these bundles in at registration time.
|
|
615
|
+
|
|
616
|
+
The bundles are **not** auto-spread by `create_frontend_rpc_client` or
|
|
617
|
+
`register_ws_endpoint` — bundled helpers stay pure factories so the
|
|
618
|
+
dispatch surface stays grep-traceable at every consumer registration site
|
|
619
|
+
and consumers can override individual protocol actions (custom heartbeat,
|
|
620
|
+
etc.) without an opt-out flag.
|
|
621
|
+
|
|
587
622
|
### `heartbeat_action`
|
|
588
623
|
|
|
589
624
|
Method `'heartbeat'`, `request_response`, `initiator: 'frontend'`, `auth:
|
|
@@ -1,24 +1,27 @@
|
|
|
1
1
|
import type { ActionSpecUnion, ActionEventPhase } from './action_spec.js';
|
|
2
2
|
/**
|
|
3
|
-
* Method names of
|
|
4
|
-
*
|
|
5
|
-
* this list when filtering backend request_response methods so the
|
|
6
|
-
*
|
|
3
|
+
* Method names of fuz_app's protocol actions — `heartbeat` (auth-aware client
|
|
4
|
+
* liveness probe) and `cancel` (request-scoped abort signal). Consumers spread
|
|
5
|
+
* this list when filtering backend request_response methods so the
|
|
6
|
+
* dispatcher-owned protocol actions don't show up in
|
|
7
|
+
* `BackendRequestResponseMethod` / handler maps. Pairs with `protocol_actions`
|
|
8
|
+
* / `protocol_action_specs` from `actions/protocol.ts` (the runtime bundles).
|
|
7
9
|
*/
|
|
8
|
-
export declare const
|
|
10
|
+
export declare const PROTOCOL_ACTION_METHODS: readonly ["heartbeat", "cancel"];
|
|
9
11
|
/** Methods that ship from fuz_app, kept out of consumer-owned method enums + handler maps. */
|
|
10
|
-
export type
|
|
12
|
+
export type ProtocolActionMethod = (typeof PROTOCOL_ACTION_METHODS)[number];
|
|
11
13
|
/**
|
|
12
|
-
* Type predicate for filtering
|
|
13
|
-
* `method_filter`. Avoids the `(... as never)` cast
|
|
14
|
-
* `Array.prototype.includes` on the readonly tuple at narrow
|
|
14
|
+
* Type predicate for filtering protocol-action methods out of a typed
|
|
15
|
+
* `FrontendActionsApi` `method_filter`. Avoids the `(... as never)` cast
|
|
16
|
+
* required to call `Array.prototype.includes` on the readonly tuple at narrow
|
|
17
|
+
* string types.
|
|
15
18
|
*
|
|
16
19
|
* @example
|
|
17
20
|
* generate_frontend_actions_api(specs, imports, {
|
|
18
|
-
* method_filter: (s) => !
|
|
21
|
+
* method_filter: (s) => !is_protocol_action_method(s.method),
|
|
19
22
|
* });
|
|
20
23
|
*/
|
|
21
|
-
export declare const
|
|
24
|
+
export declare const is_protocol_action_method: (method: string) => method is ProtocolActionMethod;
|
|
22
25
|
/**
|
|
23
26
|
* Represents an import item with its kind (type, value, or namespace).
|
|
24
27
|
*/
|
|
@@ -115,6 +118,15 @@ export declare const get_handler_return_type: (spec: ActionSpecUnion, phase: Act
|
|
|
115
118
|
* Generates the phase handlers for an action spec using the unified ActionEvent type
|
|
116
119
|
* with the new phase/step type parameters.
|
|
117
120
|
*
|
|
121
|
+
* Returns `''` when the spec contributes no phases on the given executor side
|
|
122
|
+
* (e.g. a backend-only `local_call` asked for `'frontend'`). Upstream wrappers
|
|
123
|
+
* compose blocks with `.filter(Boolean)` so empty entries are dropped from the
|
|
124
|
+
* generated handler map. The earlier shape was `${method}?: never`, which read
|
|
125
|
+
* as "calling this here is a type error" but in practice produced useless rows
|
|
126
|
+
* on `FrontendActionHandlers` for methods that don't belong on this side at
|
|
127
|
+
* all — drop the row instead so the typed surface only carries methods the
|
|
128
|
+
* executor actually handles.
|
|
129
|
+
*
|
|
118
130
|
* @param options.action_event_type - custom type name to use instead of `ActionEvent`
|
|
119
131
|
* (consumers can define a narrowed type that carries typed input/output via their codegen maps)
|
|
120
132
|
* @param options.collections_path - import path the side-effect `ActionOutputs` import
|
|
@@ -148,19 +160,28 @@ export declare const to_action_spec_output_identifier: (method: string) => strin
|
|
|
148
160
|
* failure). Earlier emit shapes declared notifications as `=> void` —
|
|
149
161
|
* regenerate consumer typed clients to pick up the corrected return.
|
|
150
162
|
*
|
|
151
|
-
*
|
|
152
|
-
* `
|
|
153
|
-
*
|
|
163
|
+
* Registers exactly the imports the emitted line references on `imports`:
|
|
164
|
+
* `ActionInputs` (when the spec has input), `ActionOutputs` (always),
|
|
165
|
+
* `RpcClientCallOptions` (async only), and `Result` + `JsonrpcErrorObject`
|
|
166
|
+
* (any return shape that wraps the value in `Result<{value}, {error}>` —
|
|
167
|
+
* every async method, plus sync `local_call` when `sync_returns_value:
|
|
168
|
+
* false`). Mirrors the leaf-level pattern `get_handler_return_type` already
|
|
169
|
+
* follows so wrappers no longer pre-register imports a per-spec emit might
|
|
170
|
+
* not actually use.
|
|
154
171
|
*
|
|
155
172
|
* @param spec - the action spec to emit
|
|
173
|
+
* @param imports - import builder to register references on
|
|
156
174
|
* @param options.sync_returns_value - when true (default), sync local_call
|
|
157
175
|
* methods return the output value directly; when false they're wrapped in
|
|
158
176
|
* `Result<{value, error}>` like async methods. Set to `false` if your
|
|
159
177
|
* FrontendActionsApi treats every method uniformly.
|
|
178
|
+
* @param options.collections_path - import path that `ActionInputs` /
|
|
179
|
+
* `ActionOutputs` resolve to. Defaults to `'./action_collections.js'`.
|
|
160
180
|
* @returns one line like `foo: (input: ActionInputs['foo'], options?: RpcClientCallOptions) => Promise<Result<...>>;`
|
|
161
181
|
*/
|
|
162
|
-
export declare const generate_actions_api_method_signature: (spec: ActionSpecUnion, options?: {
|
|
182
|
+
export declare const generate_actions_api_method_signature: (spec: ActionSpecUnion, imports: ImportBuilder, options?: {
|
|
163
183
|
sync_returns_value?: boolean;
|
|
184
|
+
collections_path?: string;
|
|
164
185
|
}) => string;
|
|
165
186
|
/** Discriminator for `generate_action_method_enums` — which method-set enums to emit. */
|
|
166
187
|
export type ActionMethodEnumKind = 'all' | 'request_response' | 'remote_notification' | 'local_call' | 'frontend' | 'backend' | 'frontend_handled' | 'backend_handled' | 'broadcast';
|
|
@@ -174,10 +195,10 @@ export declare const ACTION_METHOD_ENUM_KINDS_ALL: ReadonlySet<ActionMethodEnumK
|
|
|
174
195
|
* `BroadcastActionMethod`. Pairs each runtime const with a `z.infer` type
|
|
175
196
|
* alias under the same identifier.
|
|
176
197
|
*
|
|
177
|
-
*
|
|
178
|
-
* pass `
|
|
179
|
-
* their typed surface. Empty kinds are skipped so the helper
|
|
180
|
-
* `z.enum([])` (zod runtime-throws on that).
|
|
198
|
+
* Protocol-action methods (`heartbeat`, `cancel`) are filtered out by
|
|
199
|
+
* default — pass `include_protocol_actions: true` if a consumer genuinely
|
|
200
|
+
* wants them on their typed surface. Empty kinds are skipped so the helper
|
|
201
|
+
* never emits `z.enum([])` (zod runtime-throws on that).
|
|
181
202
|
*
|
|
182
203
|
* Adds `import {z} from 'zod';` to `imports` only when at least one block
|
|
183
204
|
* is emitted (idempotent).
|
|
@@ -187,12 +208,12 @@ export declare const ACTION_METHOD_ENUM_KINDS_ALL: ReadonlySet<ActionMethodEnumK
|
|
|
187
208
|
* and jsdoc.
|
|
188
209
|
*
|
|
189
210
|
* @param options.emit - subset of enums to emit; defaults to all nine.
|
|
190
|
-
* @param options.
|
|
211
|
+
* @param options.include_protocol_actions - when true, retains `heartbeat` /
|
|
191
212
|
* `cancel` in the emitted enums. Default `false`.
|
|
192
213
|
*/
|
|
193
214
|
export declare const generate_action_method_enums: (specs: ReadonlyArray<ActionSpecUnion>, imports: ImportBuilder, options?: {
|
|
194
215
|
emit?: ReadonlySet<ActionMethodEnumKind>;
|
|
195
|
-
|
|
216
|
+
include_protocol_actions?: boolean;
|
|
196
217
|
}) => string;
|
|
197
218
|
/**
|
|
198
219
|
* Emit a single named `z.enum([...])` + `z.infer` block for an arbitrary
|
|
@@ -200,9 +221,10 @@ export declare const generate_action_method_enums: (specs: ReadonlyArray<ActionS
|
|
|
200
221
|
* for cross-product or domain-specific enums the built-in discriminator
|
|
201
222
|
* doesn't cover.
|
|
202
223
|
*
|
|
203
|
-
* Mirrors the built-in helper's contract:
|
|
204
|
-
* empty subsets return `''` (skip rather than emit `z.enum([])`),
|
|
205
|
-
* import registered idempotently only when at least one method
|
|
224
|
+
* Mirrors the built-in helper's contract: protocol actions filtered by
|
|
225
|
+
* default, empty subsets return `''` (skip rather than emit `z.enum([])`),
|
|
226
|
+
* `zod` import registered idempotently only when at least one method
|
|
227
|
+
* qualifies.
|
|
206
228
|
*
|
|
207
229
|
* The cross-product space is open-ended; rather than grow the
|
|
208
230
|
* `ActionMethodEnumKind` discriminator one cross-product at a time, callers
|
|
@@ -212,7 +234,7 @@ export declare const generate_action_method_enum_block: (specs: ReadonlyArray<Ac
|
|
|
212
234
|
name: string;
|
|
213
235
|
jsdoc: string;
|
|
214
236
|
predicate: (spec: ActionSpecUnion) => boolean;
|
|
215
|
-
|
|
237
|
+
include_protocol_actions?: boolean;
|
|
216
238
|
}) => string;
|
|
217
239
|
/**
|
|
218
240
|
* Emit the fixed-shape `TypedActionEvent` alias used by `FrontendActionHandlers`
|
|
@@ -245,7 +267,7 @@ export declare const generate_typed_action_event_alias: (imports: ImportBuilder,
|
|
|
245
267
|
export declare const generate_action_specs_record: (specs: ReadonlyArray<ActionSpecUnion>, imports: ImportBuilder, options?: {
|
|
246
268
|
specs_module?: string;
|
|
247
269
|
qualify_spec?: (spec: ActionSpecUnion) => string;
|
|
248
|
-
|
|
270
|
+
include_protocol_actions?: boolean;
|
|
249
271
|
}) => string;
|
|
250
272
|
/**
|
|
251
273
|
* Emit `ActionInputs` + `ActionOutputs` runtime consts and matching interfaces.
|
|
@@ -263,7 +285,7 @@ export declare const generate_action_specs_record: (specs: ReadonlyArray<ActionS
|
|
|
263
285
|
export declare const generate_action_inputs_outputs: (specs: ReadonlyArray<ActionSpecUnion>, imports: ImportBuilder, options?: {
|
|
264
286
|
specs_module?: string;
|
|
265
287
|
qualify_spec?: (spec: ActionSpecUnion) => string;
|
|
266
|
-
|
|
288
|
+
include_protocol_actions?: boolean;
|
|
267
289
|
}) => string;
|
|
268
290
|
/**
|
|
269
291
|
* Emit the `ActionEventDatas` interface — one `ActionEvent*Data` variant per
|
|
@@ -288,15 +310,19 @@ export declare const generate_action_inputs_outputs: (specs: ReadonlyArray<Actio
|
|
|
288
310
|
export declare const generate_action_event_datas: (specs: ReadonlyArray<ActionSpecUnion>, imports: ImportBuilder, options?: {
|
|
289
311
|
same_file?: boolean;
|
|
290
312
|
collections_path?: string;
|
|
291
|
-
|
|
313
|
+
include_protocol_actions?: boolean;
|
|
292
314
|
}) => string;
|
|
293
315
|
/**
|
|
294
316
|
* Emit the `FrontendActionsApi` interface — one method signature per spec via
|
|
295
317
|
* `generate_actions_api_method_signature`. Optionally filter the spec set
|
|
296
|
-
* (e.g. omit
|
|
318
|
+
* (e.g. omit additional methods alongside the default protocol-action
|
|
319
|
+
* filter) via `method_filter`.
|
|
297
320
|
*
|
|
298
|
-
*
|
|
299
|
-
*
|
|
321
|
+
* Imports are registered by the leaf `generate_actions_api_method_signature`
|
|
322
|
+
* per emitted line — only what the spec set actually references shows up on
|
|
323
|
+
* `imports`. A spec set with no async methods skips `RpcClientCallOptions`;
|
|
324
|
+
* one with no inputs skips `ActionInputs`; sync `local_call` methods with
|
|
325
|
+
* `sync_returns_value: true` (the default) skip `Result` / `JsonrpcErrorObject`.
|
|
300
326
|
*
|
|
301
327
|
* The interface name is fixed at `FrontendActionsApi` — the symmetric counterpart
|
|
302
328
|
* of `BackendActionsApi`. Earlier consumer-named variants (`MyActionsApi`,
|
|
@@ -308,7 +334,7 @@ export declare const generate_frontend_actions_api: (specs: ReadonlyArray<Action
|
|
|
308
334
|
method_filter?: (spec: ActionSpecUnion) => boolean;
|
|
309
335
|
collections_path?: string;
|
|
310
336
|
sync_returns_value?: boolean;
|
|
311
|
-
|
|
337
|
+
include_protocol_actions?: boolean;
|
|
312
338
|
}) => string;
|
|
313
339
|
/**
|
|
314
340
|
* Emit the `FrontendActionHandlers` interface — wraps `generate_phase_handlers`
|
|
@@ -318,7 +344,7 @@ export declare const generate_frontend_actions_api: (specs: ReadonlyArray<Action
|
|
|
318
344
|
*/
|
|
319
345
|
export declare const generate_frontend_action_handlers: (specs: ReadonlyArray<ActionSpecUnion>, imports: ImportBuilder, options?: {
|
|
320
346
|
collections_path?: string;
|
|
321
|
-
|
|
347
|
+
include_protocol_actions?: boolean;
|
|
322
348
|
}) => string;
|
|
323
349
|
/**
|
|
324
350
|
* Emit BOTH the typed `BackendActionsApi` interface AND the
|
|
@@ -355,7 +381,7 @@ export declare const generate_backend_actions_api: (specs: ReadonlyArray<ActionS
|
|
|
355
381
|
specs_module?: string;
|
|
356
382
|
collections_path?: string;
|
|
357
383
|
qualify_spec?: (spec: ActionSpecUnion) => string;
|
|
358
|
-
|
|
384
|
+
include_protocol_actions?: boolean;
|
|
359
385
|
}) => string;
|
|
360
386
|
/**
|
|
361
387
|
* Emit the `BackendActionHandlers` mapped type — one entry per
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"action_codegen.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_codegen.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAC,eAAe,EAAE,gBAAgB,EAAC,MAAM,kBAAkB,CAAC;AAGxE
|
|
1
|
+
{"version":3,"file":"action_codegen.d.ts","sourceRoot":"../src/lib/","sources":["../../src/lib/actions/action_codegen.ts"],"names":[],"mappings":"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"}
|