@nice-code/action 0.0.21 → 0.1.1

package/build/types/ActionDomain/NiceActionDomainBase.d.ts

@@ -0,0 +1,14 @@
+import type { TExecutionAndResponseListeners } from "../ActionRuntimeEnvironment/ActionHandler/ActionHandler.types";
+import type { INiceActionDomain } from "./NiceActionDomain.types";
+export declare abstract class NiceActionDomainBase<ACT_DOM extends INiceActionDomain = INiceActionDomain> implements INiceActionDomain<ACT_DOM["allDomains"], ACT_DOM["actions"]> {
+    readonly domain: ACT_DOM["domain"];
+    readonly allDomains: ACT_DOM["allDomains"];
+    readonly actions: ACT_DOM["actions"];
+    protected _listeners: TExecutionAndResponseListeners<ACT_DOM>[];
+    constructor(definition: ACT_DOM);
+    /**
+     * Add an observer that is called after every action dispatched through this domain.
+     * Returns an unsubscribe function — call it to remove the listener.
+     */
+    addActionListener(listener: TExecutionAndResponseListeners<ACT_DOM>): () => void;
+}

package/build/types/ActionDomain/RootDomain/NiceActionRootDomain.d.ts

@@ -0,0 +1,22 @@
+import type { IActionHandlerInputs } from "../../ActionRuntimeEnvironment/ActionHandler/ActionHandler.types";
+import type { ActionRuntimeEnvironment } from "../../ActionRuntimeEnvironment/ActionRuntimeEnvironment";
+import type { IRuntimeEnvironmentMeta } from "../../ActionRuntimeEnvironment/ActionRuntimeEnvironment.types";
+import type { NiceActionPrimed } from "../../NiceAction/NiceActionPrimed";
+import { NiceActionDomain } from "../NiceActionDomain";
+import type { INiceActionDomainChildOptions, INiceActionRootDomain, TNiceActionDomainChildDef } from "../NiceActionDomain.types";
+import { NiceActionDomainBase } from "../NiceActionDomainBase";
+export declare class NiceActionRootDomain<ROOT_DOM extends INiceActionRootDomain = INiceActionRootDomain> extends NiceActionDomainBase<ROOT_DOM> {
+    readonly domainDefinition: {
+        domain: ROOT_DOM["domain"];
+    };
+    private _runtimeEnvironment?;
+    constructor(domainDefinition: {
+        domain: ROOT_DOM["domain"];
+    });
+    getEnvironmentMeta(): IRuntimeEnvironmentMeta;
+    createChildDomain<SUB_DOM extends INiceActionDomainChildOptions>(subDomainDef: SUB_DOM & {
+        [K in Exclude<keyof SUB_DOM, keyof INiceActionDomainChildOptions>]: never;
+    }): NiceActionDomain<TNiceActionDomainChildDef<ROOT_DOM, SUB_DOM>>;
+    setRuntimeEnvironment(runtime: ActionRuntimeEnvironment): this;
+    _executeAction<P extends NiceActionPrimed<any, any, any>>(primed: P, { actionMeta, listeners, }: IActionHandlerInputs<P extends NiceActionPrimed<infer DOM, any, any> ? DOM : never>): Promise<unknown>;
+}

package/build/types/ActionDomain/helpers/createRootActionDomain.d.ts

@@ -0,0 +1,5 @@
+import type { INiceActionRootDomain } from "../NiceActionDomain.types";
+import { NiceActionRootDomain } from "../RootDomain/NiceActionRootDomain";
+export declare const createActionRootDomain: <ID extends string>(definition: {
+    domain: ID;
+}) => NiceActionRootDomain<INiceActionRootDomain<ID>>;

package/build/types/ActionRuntimeEnvironment/ActionConnect/ActionConnect.d.ts

@@ -0,0 +1,24 @@
+import type { NiceActionDomain } from "../../ActionDomain/NiceActionDomain";
+import type { INiceActionDomain } from "../../ActionDomain/NiceActionDomain.types";
+import type { NiceActionPrimed } from "../../NiceAction/NiceActionPrimed";
+import type { NiceActionResponse } from "../../NiceAction/NiceActionResponse";
+import { EActionHandlerType, type IActionHandler, type TMatchHandlerKey } from "../ActionHandler/ActionHandler.types";
+import type { IActionConnectConfig, IActionConnectRoute } from "./ActionConnect.types";
+import { ConnectionConfig } from "./ConnectionConfig/ConnectionConfig";
+export declare class ActionConnect<TRANS_KEY extends string = never> implements IActionHandler {
+    readonly tag: string | "_";
+    readonly handlerType = EActionHandlerType.connect;
+    readonly cuid: string;
+    private _config;
+    private _connections;
+    private _connectionByMatchKey;
+    private _handlerKeys;
+    constructor(connectionConfigs: Array<ConnectionConfig<TRANS_KEY | undefined>>, config?: IActionConnectConfig);
+    get allHandlerKeys(): TMatchHandlerKey[];
+    routeDomain<DOM extends INiceActionDomain>(domain: NiceActionDomain<DOM>, route?: IActionConnectRoute<DOM, TRANS_KEY>): this;
+    routeAction<DOM extends INiceActionDomain, ID extends keyof DOM["actions"] & string>(domain: NiceActionDomain<DOM>, id: ID, route?: IActionConnectRoute<DOM, TRANS_KEY, ID>): this;
+    routeActionIds<DOM extends INiceActionDomain, IDS extends ReadonlyArray<keyof DOM["actions"] & string>>(domain: NiceActionDomain<DOM>, ids: IDS, route?: IActionConnectRoute<DOM, TRANS_KEY, IDS[number]>): this;
+    dispatchAction(primed: NiceActionPrimed<any, any>): Promise<NiceActionResponse<any, any>>;
+    disconnect(): void;
+    private _dispatchViaRoute;
+}

package/build/types/ActionRuntimeEnvironment/ActionConnect/ActionConnect.types.d.ts

@@ -0,0 +1,15 @@
+import type { NiceActionResponse } from "../..";
+import type { INiceActionDomain } from "../../ActionDomain/NiceActionDomain.types";
+export interface IActionConnectConfig {
+    tag?: string;
+    /** Default timeout for dispatching actions, in milliseconds. */
+    requestTimeout?: number;
+}
+/** Route config for a domain or action — controls which named transport handles the dispatch. */
+export interface IActionConnectRoute<DOM extends INiceActionDomain, TKey extends string = string, ID extends keyof DOM["actions"] & string = keyof DOM["actions"] & string> {
+    /** Send via this named transport. Omit to use the default (unnamed) transport. */
+    routeKey?: TKey;
+    onResponse?: (response: {
+        [K in ID]: NiceActionResponse<DOM, K>;
+    }[ID]) => void;
+}

package/build/types/ActionRuntimeEnvironment/ActionConnect/ConnectionConfig/ConnectionConfig.d.ts

@@ -0,0 +1,12 @@
+import type { NiceActionPrimed } from "../../../NiceAction/NiceActionPrimed";
+import type { NiceActionResponse } from "../../../NiceAction/NiceActionResponse";
+import { type IConnectionConfig } from "./ConnectionConfig.types";
+export declare class ConnectionConfig<K extends string | undefined = undefined> {
+    readonly config: IConnectionConfig;
+    readonly routeKey: K | undefined;
+    private _transports;
+    constructor(input: IConnectionConfig, routeKey?: K);
+    get connected(): boolean;
+    dispatch(primed: NiceActionPrimed<any>, defaultTimeout: number): Promise<NiceActionResponse<any>>;
+    disconnect(): void;
+}

package/build/types/ActionRuntimeEnvironment/ActionConnect/ConnectionConfig/ConnectionConfig.types.d.ts

@@ -0,0 +1,6 @@
+export { ETransportStatus, ETransportType, type IActionTransportDef_Http, type IActionTransportDef_Ws, type TActionTransportDef, } from "../Transport/Transport.types";
+import type { TActionTransportDef } from "../Transport/Transport.types";
+export interface IConnectionConfig {
+    defaultTimeout?: number;
+    transports: TActionTransportDef[];
+}

package/build/types/ActionRuntimeEnvironment/ActionConnect/Transport/Transport.d.ts

@@ -0,0 +1,16 @@
+import type { NiceActionPrimed } from "../../../NiceAction/NiceActionPrimed";
+import type { NiceActionResponse } from "../../../NiceAction/NiceActionResponse";
+import { type ITransportPendingRequest, type TActionTransportDef, type TTransportStatusInfo } from "./Transport.types";
+export declare abstract class Transport<DEF extends TActionTransportDef> {
+    readonly def: DEF;
+    readonly type: DEF["type"];
+    readonly requestResolvers: Map<string, ITransportPendingRequest>;
+    protected abstract _status: TTransportStatusInfo;
+    constructor(def: DEF);
+    get status(): TTransportStatusInfo;
+    checkAndPrepare(): TTransportStatusInfo;
+    protected abstract send(primed: NiceActionPrimed<any>): Promise<void>;
+    abstract disconnect(): void;
+    protected respond(response: NiceActionResponse<any>): void;
+    makeRequest(primed: NiceActionPrimed<any>, connectionDefaultTimeout: number): Promise<NiceActionResponse<any>>;
+}

package/build/types/ActionRuntimeEnvironment/ActionConnect/Transport/Transport.types.d.ts

@@ -0,0 +1,50 @@
+import type { NiceError } from "@nice-code/error";
+import type { NiceActionPrimed } from "../../../NiceAction/NiceActionPrimed";
+import type { NiceActionResponse } from "../../../NiceAction/NiceActionResponse";
+import type { Transport } from "./Transport";
+export declare enum ETransportType {
+    ws = "ws",
+    http = "http"
+}
+export declare enum ETransportStatus {
+    uninitialized = "uninitialized",
+    initializing = "initializing",
+    ready = "ready",
+    failed = "failed"
+}
+export interface ITransportStatusInfo_Base<S extends ETransportStatus> {
+    status: S;
+}
+export interface ITransportStatusInfo_Failed extends ITransportStatusInfo_Base<ETransportStatus.failed> {
+    error: NiceError;
+    timeFailed: number;
+}
+export interface ITransportInitializationFinishedInfo {
+    transport: Transport<any>;
+    newStatus: ITransportStatusInfo_Base<ETransportStatus.ready> | ITransportStatusInfo_Failed;
+}
+export interface ITransportStatusInfo_Initializing extends ITransportStatusInfo_Base<ETransportStatus.initializing> {
+    timeStarted: number;
+    waitForInitialization: Promise<ITransportInitializationFinishedInfo>;
+}
+export type TTransportStatusInfo = ITransportStatusInfo_Base<ETransportStatus.uninitialized> | ITransportStatusInfo_Initializing | ITransportStatusInfo_Base<ETransportStatus.ready> | ITransportStatusInfo_Failed;
+export interface IActionTransport_Base {
+    /** Per-transport timeout override (ms) */
+    timeout?: number;
+}
+export interface IActionTransportDef_Ws extends IActionTransport_Base {
+    type: ETransportType.ws;
+    createWebSocket: () => Promise<WebSocket>;
+}
+export interface IActionTransportDef_Http extends IActionTransport_Base {
+    type: ETransportType.http;
+    url: string;
+}
+export type TActionTransportDef = IActionTransportDef_Ws | IActionTransportDef_Http;
+export interface ITransportPendingRequest {
+    type: ETransportType;
+    resolve: (response: NiceActionResponse<any>) => void;
+    reject: (error: unknown) => void;
+    timer: ReturnType<typeof setTimeout>;
+    primed: NiceActionPrimed<any>;
+}

package/build/types/ActionRuntimeEnvironment/ActionConnect/Transport/TransportHttp.d.ts

@@ -0,0 +1,9 @@
+import type { NiceActionPrimed } from "../../../NiceAction/NiceActionPrimed";
+import { Transport } from "./Transport";
+import { type IActionTransportDef_Http, type TTransportStatusInfo } from "./Transport.types";
+export declare class TransportHttp extends Transport<IActionTransportDef_Http> {
+    readonly abortControllers: Map<string, AbortController>;
+    protected _status: TTransportStatusInfo;
+    send(primed: NiceActionPrimed<any>): Promise<void>;
+    disconnect(): void;
+}

package/build/types/ActionRuntimeEnvironment/ActionConnect/Transport/TransportWebSocket.d.ts

@@ -0,0 +1,15 @@
+import type { NiceActionPrimed } from "../../../NiceAction/NiceActionPrimed";
+import { Transport } from "./Transport";
+import { type IActionTransportDef_Ws, type TTransportStatusInfo } from "./Transport.types";
+export declare class TransportWebSocket extends Transport<IActionTransportDef_Ws> {
+    websocket?: WebSocket;
+    protected _status: TTransportStatusInfo;
+    constructor(def: IActionTransportDef_Ws);
+    checkAndPrepare(): TTransportStatusInfo;
+    private startInitializing;
+    private handleMessage;
+    private rejectPendingWebSocketRequests;
+    private _connect;
+    protected send(primed: NiceActionPrimed<any>): Promise<void>;
+    disconnect(): void;
+}

package/build/types/ActionRuntimeEnvironment/ActionConnect/Transport/err_nice_transport.d.ts

@@ -0,0 +1,34 @@
+export declare enum EErrId_NiceTransport {
+    timeout = "timeout",
+    not_found = "not_found",
+    initialization_failed = "initialization_failed",
+    send_failed = "send_failed",
+    invalid_action_response = "invalid_action_response"
+}
+export declare const err_nice_transport: import("@nice-code/error").NiceErrorDomain<{
+    domain: string;
+    allDomains: [string, string, string, "err_nice"];
+    schema: {
+        timeout: import("@nice-code/error").INiceErrorIdMetadata<{
+            timeout: number;
+        }, import("@nice-code/error").JSONSerializableValue>;
+        not_found: import("@nice-code/error").INiceErrorIdMetadata<{
+            actionId: string;
+            routeKey?: string;
+            tag?: string;
+        }, import("@nice-code/error").JSONSerializableValue>;
+        initialization_failed: import("@nice-code/error").INiceErrorIdMetadata<{
+            actionId: string;
+            routeKey?: string;
+            tag?: string;
+        }, import("@nice-code/error").JSONSerializableValue>;
+        send_failed: import("@nice-code/error").INiceErrorIdMetadata<{
+            actionId: string;
+            httpStatusCode?: number;
+            message?: string;
+        }, import("@nice-code/error").JSONSerializableValue>;
+        invalid_action_response: import("@nice-code/error").INiceErrorIdMetadata<{
+            actionId: string;
+        }, import("@nice-code/error").JSONSerializableValue>;
+    };
+}>;

package/build/types/ActionRuntimeEnvironment/ActionConnect/Transport/err_nice_transport_ws.d.ts

@@ -0,0 +1,18 @@
+export declare enum EErrId_NiceTransport_WebSocket {
+    ws_disconnected = "ws_disconnected",
+    ws_create_failed = "ws_create_failed",
+    ws_error = "ws_error"
+}
+export declare const err_nice_transport_ws: import("@nice-code/error").NiceErrorDomain<{
+    domain: string;
+    allDomains: [string, string, string, string, "err_nice"];
+    schema: {
+        ws_disconnected: import("@nice-code/error").INiceErrorIdMetadata<Record<string, never>, import("@nice-code/error").JSONSerializableValue>;
+        ws_create_failed: import("@nice-code/error").INiceErrorIdMetadata<{
+            originalError?: Error;
+        }, import("@nice-code/error").JSONSerializableValue>;
+        ws_error: import("@nice-code/error").INiceErrorIdMetadata<{
+            originalError?: Error;
+        }, import("@nice-code/error").JSONSerializableValue>;
+    };
+}>;

package/build/types/ActionRuntimeEnvironment/ActionConnect/err_nice_connect.d.ts

@@ -0,0 +1,5 @@
+export declare const err_nice_connect: import("@nice-code/error").NiceErrorDomain<{
+    domain: string;
+    allDomains: [string, string, "err_nice"];
+    schema: {};
+}>;

package/build/types/ActionRuntimeEnvironment/ActionHandler/ActionHandler.d.ts

@@ -0,0 +1,80 @@
+import type { NiceActionDomain } from "../../ActionDomain/NiceActionDomain";
+import type { INiceActionDomain } from "../../ActionDomain/NiceActionDomain.types";
+import type { INiceAction } from "../../NiceAction/NiceAction.types";
+import type { NiceActionPrimed } from "../../NiceAction/NiceActionPrimed";
+import { NiceActionResponse } from "../../NiceAction/NiceActionResponse";
+import { EActionHandlerType, type IActionHandler, type IActionHandlerInputs, type TExecutionAndResponseHandlers, type TExecutionAndResponseHandlers_Domain, type THandleActionResult, type TMatchHandlerKey } from "./ActionHandler.types";
+export declare class ActionHandler implements IActionHandler {
+    readonly tag: string | "_";
+    readonly handlerType = EActionHandlerType.custom;
+    readonly cuid: string;
+    readonly _domains: Map<string, NiceActionDomain<any>>;
+    private _handlersByKey;
+    constructor(config?: IActionHandlerInputs["actionMeta"]);
+    get allHandlerKeys(): TMatchHandlerKey[];
+    private getHandlersForAction;
+    /**
+     * Register a handler for all actions in a domain.
+     * Receives the full primed action — use `matchAction()` to narrow to a specific action id.
+     * Useful for forwarding all domain actions to a remote endpoint.
+     * Lower priority than `forAction`.
+     */
+    forDomain<FOR_DOM extends INiceActionDomain>(domain: NiceActionDomain<FOR_DOM>, handlers: TExecutionAndResponseHandlers_Domain<FOR_DOM>): this;
+    /**
+     * Register a typed handler for a specific action ID.
+     * The handler receives the full primed action with narrowed input type.
+     * Takes priority over `forDomain` for the same domain.
+     */
+    forAction<ACT_DOM extends INiceActionDomain, ID extends keyof ACT_DOM["actions"] & string>(domain: NiceActionDomain<ACT_DOM>, id: ID, handlers: TExecutionAndResponseHandlers<INiceAction<ACT_DOM, ID>>): this;
+    /**
+     * Register a handler for multiple action IDs (first-match-wins among cases).
+     * Receives the full primed action narrowed to the union of those IDs.
+     * Use `act.coreAction.id` to branch on which action was dispatched.
+     */
+    forActionIds<ACT_DOM extends INiceActionDomain, IDS extends ReadonlyArray<keyof ACT_DOM["actions"] & string>>(domain: NiceActionDomain<ACT_DOM>, ids: IDS, handlers: TExecutionAndResponseHandlers<INiceAction<ACT_DOM, IDS[number]>>): this;
+    /**
+     * Register per-action handlers for a domain using a single map, without needing
+     * separate `forAction` calls. Unregistered action IDs are unaffected.
+     *
+     * @example
+     * ```ts
+     * handler.forDomainActionCases(userDomain, {
+     *   getUser:    { execution: (primed) => db.getUser(primed.input.userId) },
+     *   deleteUser: { execution: (primed) => db.deleteUser(primed.input.userId) },
+     * });
+     * ```
+     */
+    forDomainActionCases<FOR_DOM extends INiceActionDomain>(domain: NiceActionDomain<FOR_DOM>, cases: {
+        [ID in keyof FOR_DOM["actions"] & string]?: TExecutionAndResponseHandlers<INiceAction<FOR_DOM, ID>>;
+    }): this;
+    private _tryHandleResponse;
+    protected _tryExecute(primed: NiceActionPrimed<any, any, any>): Promise<THandleActionResult>;
+    /**
+     * Dispatch a primed action. Throws if no execution handler matches.
+     */
+    dispatchAction(primed: NiceActionPrimed<any, any>): Promise<NiceActionResponse<any, any>>;
+    /**
+     * Dispatch a wire-format action (primed or resolved).
+     *
+     * Returns `{ handled: true, response }` when a handler matched, or
+     * `{ handled: false }` when no handler is registered for the action.
+     *
+     * Throws for structural errors only:
+     * - `domain_no_handler` — domain not known to this handler
+     * - `hydration_*` — the wire payload is malformed
+     * - `handle_wire_not_primed_or_response` — unknown wire type
+     *
+     * Execution errors thrown by handlers propagate as-is.
+     *
+     * @example
+     * ```ts
+     * app.post("/actions", async (req, res) => {
+     *   const result = await handler.handleWire(req.body);
+     *   if (result.handled) res.json(result.response.toJsonObject());
+     *   else res.status(404).end();
+     * });
+     * ```
+     */
+    handleWire(wire: unknown): Promise<THandleActionResult>;
+}
+export declare const createHandler: (config?: IActionHandlerInputs["actionMeta"]) => ActionHandler;

package/build/types/ActionRuntimeEnvironment/ActionHandler/ActionHandler.types.d.ts

@@ -0,0 +1,68 @@
+import type { INiceActionDomain, MaybePromise, TInferOutputFromSchema } from "../../ActionDomain/NiceActionDomain.types";
+import type { INiceAction, TNiceActionResponse_JsonObject } from "../../NiceAction/NiceAction.types";
+import type { TDistributedDomainActions } from "../../NiceAction/NiceActionCombined.types";
+import type { NiceActionPrimed } from "../../NiceAction/NiceActionPrimed";
+import type { NiceActionResponse } from "../../NiceAction/NiceActionResponse";
+import type { IRuntimeEnvironmentMeta } from "../ActionRuntimeEnvironment.types";
+export type TAtLeastOne<T extends object> = {
+    [K in keyof T]-?: Required<Pick<T, K>> & Partial<Omit<T, K>>;
+}[keyof T];
+/**
+ * Format: `${matchTag | "_"}::${domainName}::${actionName | "_"}`
+ */
+export type TMatchHandlerKey = `${string}::${string | "_"}`;
+export interface IActionMetaInputs {
+    /**
+     * An action "tag" for the handler.
+     *
+     * This can be used to specify which handler should be used for a given
+     * action.
+     */
+    tag?: string;
+    meta?: any;
+}
+export interface IActionMetaInputsWithRuntime extends IActionMetaInputs {
+    runtime: IRuntimeEnvironmentMeta;
+}
+export type THandleActionExecutionFn<A extends INiceAction<any, any>> = A extends INiceAction<infer DOM, infer IDS> ? (primed: NiceActionPrimed<DOM, IDS>, envData: IActionMetaInputsWithRuntime) => MaybePromise<NiceActionResponse<DOM, IDS> | TNiceActionResponse_JsonObject<DOM, IDS> | TInferOutputFromSchema<DOM["actions"][IDS]>["Output"] | undefined> : never;
+export type THandleActionResponseFn<A extends INiceAction<any, any>> = A extends INiceAction<infer DOM, infer IDS> ? (response: NiceActionResponse<DOM, IDS>, envData: IActionMetaInputsWithRuntime) => MaybePromise<NiceActionResponse<DOM, IDS> | TNiceActionResponse_JsonObject<DOM, IDS> | undefined> : never;
+export type TExecutionAndResponseHandlers<A extends INiceAction<any, any>> = TAtLeastOne<{
+    execution: THandleActionExecutionFn<A>;
+    response: THandleActionResponseFn<A>;
+}>;
+export type THandleActionExecutionFn_Domain<DOM extends INiceActionDomain> = (primed: TDistributedDomainActions<NiceActionPrimed<DOM>, DOM>, envData: IActionMetaInputsWithRuntime) => MaybePromise<NiceActionResponse<DOM, keyof DOM["actions"] & string> | TNiceActionResponse_JsonObject<DOM, keyof DOM["actions"] & string> | TInferOutputFromSchema<DOM["actions"][keyof DOM["actions"] & string]>["Output"] | undefined>;
+export type THandleActionResponseFn_Domain<DOM extends INiceActionDomain> = (response: TDistributedDomainActions<NiceActionResponse<DOM>, DOM>, envData: IActionMetaInputsWithRuntime) => MaybePromise<NiceActionResponse<DOM, keyof DOM["actions"] & string> | TNiceActionResponse_JsonObject<DOM, keyof DOM["actions"] & string> | undefined>;
+export type TExecutionAndResponseHandlers_Domain<DOM extends INiceActionDomain> = TAtLeastOne<{
+    execution: THandleActionExecutionFn_Domain<DOM>;
+    response: THandleActionResponseFn_Domain<DOM>;
+}>;
+export type TListenToActionExecutionFn<DOM extends INiceActionDomain> = (primed: TDistributedDomainActions<NiceActionPrimed<DOM>, DOM>, envData: IActionMetaInputsWithRuntime) => void;
+export type TListenToActionResponseFn<DOM extends INiceActionDomain> = (response: TDistributedDomainActions<NiceActionResponse<DOM>, DOM>, envData: IActionMetaInputsWithRuntime) => void;
+export type TExecutionAndResponseListeners<DOM extends INiceActionDomain> = TAtLeastOne<{
+    execution: TListenToActionExecutionFn<DOM>;
+    response: TListenToActionResponseFn<DOM>;
+}>;
+export interface IActionHandlerInputs<DOM extends INiceActionDomain = INiceActionDomain> {
+    listeners?: TExecutionAndResponseListeners<DOM>[];
+    actionMeta: IActionMetaInputs;
+}
+export type THandleActionResult = {
+    handled: true;
+    response: NiceActionResponse<any, any>;
+} | {
+    handled: false;
+};
+export type TStoredHandlers<A extends INiceAction<any, any> = INiceAction<any, any>> = {
+    execution?: THandleActionExecutionFn<A>;
+    response?: THandleActionResponseFn<A>;
+};
+export declare enum EActionHandlerType {
+    connect = "connect",
+    custom = "custom"
+}
+export interface IActionHandler {
+    cuid: string;
+    handlerType: EActionHandlerType;
+    allHandlerKeys: TMatchHandlerKey[];
+    dispatchAction: (primed: NiceActionPrimed<any, any>) => Promise<NiceActionResponse<any, any>>;
+}

package/build/types/ActionRuntimeEnvironment/ActionRuntimeEnvironment.d.ts

@@ -0,0 +1,32 @@
+import type { INiceAction } from "../NiceAction/NiceAction.types";
+import type { IActionHandler, TStoredHandlers } from "./ActionHandler/ActionHandler.types";
+import type { IActionRuntimeEnvironment_JsonObject, IRuntimeMeta } from "./ActionRuntimeEnvironment.types";
+interface IActionRuntimeEnvironment_Constructor_Input {
+    envId: string;
+}
+export declare class ActionRuntimeEnvironment {
+    readonly envId: string;
+    /**
+     * A unique identifier for this runtime environment instance.
+     *
+     * Format: `${envId}::${randomSuffix}` where `envId` is the runtime static ID and `randomSuffix` is a short random
+     * string to distinguish multiple instances of the same runtime.
+     */
+    readonly memCuid: string;
+    readonly timeCreated: number;
+    readonly runtimeInfo: IRuntimeMeta;
+    private _handlersByTag;
+    private _defaultHandlers;
+    constructor(input: IActionRuntimeEnvironment_Constructor_Input);
+    addHandlers(handlers: IActionHandler[]): this;
+    setDefaultHandler(handler: TStoredHandlers, tag?: string): this;
+    getDefaultHandler(tag?: string): TStoredHandlers | undefined;
+    /**
+     * Return the first handler registered for the given matchTag, or undefined
+     * if none has been registered.
+     */
+    getHandlerForAction(action: Pick<INiceAction<any, any>, "domain" | "id">, tag?: string): IActionHandler | undefined;
+    toJsonObject(): IActionRuntimeEnvironment_JsonObject;
+}
+export declare const createActionRuntime: (config: IActionRuntimeEnvironment_Constructor_Input) => ActionRuntimeEnvironment;
+export {};

package/build/types/ActionRuntimeEnvironment/ActionRuntimeEnvironment.types.d.ts

@@ -0,0 +1,15 @@
+import type { RuntimeName } from "std-env";
+export interface IRuntimeMeta {
+    assumed: boolean;
+    runtimeName: RuntimeName;
+}
+export interface IActionRuntimeEnvironment_JsonObject {
+    envId: string;
+    memCuid: string;
+    timeCreated: number;
+    runtimeInfo: IRuntimeMeta;
+}
+export interface IRuntimeEnvironmentMeta {
+    envId?: string;
+    runtimeInfo: IRuntimeMeta;
+}

package/build/types/ActionRuntimeEnvironment/utils/getAssumedRuntimeEnvironment.d.ts

@@ -0,0 +1,2 @@
+import type { IRuntimeMeta } from "../ActionRuntimeEnvironment.types";
+export declare const getAssumedRuntimeInfo: () => IRuntimeMeta;

package/build/types/ActionSchema/NiceActionSchema.d.ts

@@ -1,18 +1,18 @@
 import { err_cast_not_nice, type INiceErrorDomainProps, type InferNiceError, type JSONSerializableValue, type NiceErrorDomain } from "@nice-code/error";
 import type { StandardSchemaV1 } from "@standard-schema/spec";
-import type { INiceActionErrorDeclaration, TInferDeclaredErrors, TNiceActonSchemaInputOptions, TTransportedValue } from "./NiceActionSchema.types";
-export declare class NiceActionSchema<INPUT extends TTransportedValue<any, any> = TTransportedValue<any, any>, OUTPUT extends TTransportedValue<any, any> = TTransportedValue<any>, ERRORS extends readonly INiceActionErrorDeclaration<any, any>[] = readonly []> {
+import type { INiceActionErrorDeclaration, TInferDeclaredErrors, TNiceActonSchemaOptions, TTransportedValue } from "./NiceActionSchema.types";
+export declare class NiceActionSchema<INPUT extends TTransportedValue<any, any> = never, OUTPUT extends TTransportedValue<any, any> = never, ERRORS extends readonly INiceActionErrorDeclaration<any, any>[] = readonly []> {
     private _errorDeclarations;
     private inputOptions;
     private outputOptions;
-    get inputSchema(): StandardSchemaV1;
-    get outputSchema(): StandardSchemaV1;
+    get inputSchema(): StandardSchemaV1 | undefined;
+    get outputSchema(): StandardSchemaV1 | undefined;
     /**
      * Declare the input schema (JSON-native or with explicit SERDE type param).
      * For non-JSON-native inputs, prefer the 3-argument form below to avoid
      * needing explicit type parameters.
      */
-    input<VS extends StandardSchemaV1 = StandardSchemaV1, SERDE_IN extends JSONSerializableValue = never>(options: TNiceActonSchemaInputOptions<VS, SERDE_IN>): NiceActionSchema<TTransportedValue<StandardSchemaV1.InferInput<VS>, SERDE_IN>, OUTPUT, ERRORS>;
+    input<VS extends StandardSchemaV1 = StandardSchemaV1, SERDE_IN extends JSONSerializableValue = never>(options: TNiceActonSchemaOptions<VS, SERDE_IN>): NiceActionSchema<TTransportedValue<StandardSchemaV1.InferInput<VS>, SERDE_IN>, OUTPUT, ERRORS>;
     /**
      * Declare the input schema with serialization via sequential parameters.
      * TypeScript infers SERDE_IN from `serialize`'s return type (left-to-right),
@@ -27,7 +27,7 @@ export declare class NiceActionSchema<INPUT extends TTransportedValue<any, any>
      * For non-JSON-native outputs, prefer the 3-argument form below to avoid
      * needing explicit type parameters.
      */
-    output<VS extends StandardSchemaV1 = StandardSchemaV1, SERDE_OUT extends JSONSerializableValue = JSONSerializableValue>(options: TNiceActonSchemaInputOptions<VS, SERDE_OUT>): NiceActionSchema<INPUT, TTransportedValue<StandardSchemaV1.InferInput<VS>, SERDE_OUT>, ERRORS>;
+    output<VS extends StandardSchemaV1 = StandardSchemaV1, SERDE_OUT extends JSONSerializableValue = JSONSerializableValue>(options: TNiceActonSchemaOptions<VS, SERDE_OUT>): NiceActionSchema<INPUT, TTransportedValue<StandardSchemaV1.InferInput<VS>, SERDE_OUT>, ERRORS>;
     /**
      * Declare the output schema with serialization via sequential parameters.
      * TypeScript infers SERDE_OUT from `serialize`'s return type (left-to-right),
@@ -68,7 +68,11 @@ export declare class NiceActionSchema<INPUT extends TTransportedValue<any, any>
     validateInput(value: unknown, meta: {
         domain: string;
         actionId: string;
-    }): Promise<INPUT[0]>;
+    }): INPUT[0];
+    validateOutput(value: unknown, meta: {
+        domain: string;
+        actionId: string;
+    }): OUTPUT[0];
     /**
      * Serialize raw output to a JSON-serializable form.
      */

package/build/types/ActionSchema/NiceActionSchema.types.d.ts

@@ -6,7 +6,7 @@ export type TNiceActionSerializationDefinition<RAW_VAL = any, SERDE_VAL extends
     serialize: (value: RAW_VAL) => SERDE_VAL;
     deserialize: (value: SERDE_VAL) => RAW_VAL;
 };
-export type TNiceActonSchemaInputOptions<VS extends StandardSchemaV1 = StandardSchemaV1, SERDE_IN extends TNiceActionJsonSerializableValue = TNiceActionJsonSerializableValue> = StandardSchemaV1.InferInput<VS> extends TNiceActionJsonSerializableValue ? {
+export type TNiceActonSchemaOptions<VS extends StandardSchemaV1 = StandardSchemaV1, SERDE_IN extends TNiceActionJsonSerializableValue = TNiceActionJsonSerializableValue> = StandardSchemaV1.InferInput<VS> extends TNiceActionJsonSerializableValue ? {
     schema: VS;
     serialization?: TNiceActionSerializationDefinition<StandardSchemaV1.InferInput<VS>, SERDE_IN>;
 } : {

package/build/types/NiceAction/MatchAction/MatchAction.d.ts

@@ -0,0 +1,26 @@
+import type { INiceActionDomain, MaybePromise } from "../../ActionDomain/NiceActionDomain.types";
+import type { INiceAction } from "../NiceAction.types";
+import type { TNarrowActionType } from "../NiceActionCombined.types";
+type TMatchHandler<A extends INiceAction<any>> = (action: A) => MaybePromise<void>;
+type THandlerForId<ACT extends INiceAction<any>> = (action: ACT) => MaybePromise<void>;
+declare class MatchAction<ACT extends INiceAction<any>> {
+    readonly action: ACT;
+    private _entries;
+    private _otherwise?;
+    constructor(action: ACT);
+    with<D extends INiceActionDomain, ID extends keyof D["actions"] & string>(opts: {
+        domain: D;
+        id: ID;
+        handler: THandlerForId<TNarrowActionType<ACT, D, ID>>;
+    }): this;
+    with<D extends INiceActionDomain>(opts: {
+        domain: D;
+        handler: TMatchHandler<TNarrowActionType<ACT, D, keyof D["actions"] & string>>;
+    }): this;
+    otherwise(handler: TMatchHandler<ACT>): this;
+    private _findMatch;
+    run(): boolean;
+    runAsync(): Promise<boolean>;
+}
+export declare const matchAction: <ACT extends INiceAction<any>>(action: ACT) => MatchAction<ACT>;
+export {};