@nice-code/action 0.4.6 → 0.4.7

package/README.md

@@ -154,7 +154,9 @@ export const clientCoord = RuntimeCoordinate.env("frontend");
 export const serverCoord = RuntimeCoordinate.env("backend");
 
 // Transport definitions are plain, reusable objects you construct once.
-const serverHttp = new HttpTransport({ url: "https://api.example.com/resolve_action" });
+const serverHttp = HttpTransport.create({
+  createRequest: () => ({ url: "https://api.example.com/resolve_action" }),
+});
 
 const serverHandler = new ActionExternalClientHandler({
   runtimeCoordinate: serverCoord,
@@ -218,7 +220,10 @@ function RenameUser() {
 ```ts
 import { WebSocketTransport } from "@nice-code/action";
 
-const serverWs = new WebSocketTransport({ url: "wss://api.example.com/resolve_action/ws" });
+const serverWs = WebSocketTransport.create({
+  createWebSocket: () => new WebSocket("wss://api.example.com/resolve_action/ws"),
+  getTransportCacheKey: () => ["wss://api.example.com/resolve_action/ws"],
+});
 
 const serverHandler = new ActionExternalClientHandler({
   runtimeCoordinate: serverCoord,
@@ -226,12 +231,15 @@ const serverHandler = new ActionExternalClientHandler({
 }).forDomain(userDomain);
 ```
 
-The socket is opened lazily and reused across actions to the same endpoint. Multiple transports can
-be registered; the runtime picks the best available one (WebSocket preferred for lower latency, HTTP
-as fallback). For channels nice-action doesn't model natively, use `CustomTransport`.
+The socket is opened lazily and reused across actions sharing a `getTransportCacheKey`. Multiple
+transports can be registered; the runtime picks the best available one (WebSocket preferred for lower
+latency, HTTP as fallback). For channels nice-action doesn't model natively, use `CustomTransport`.
 
-For advanced cases, `HttpTransport` / `WebSocketTransport` accept functions to derive the URL or
-headers per action (e.g. `new HttpTransport({ url: (input) => \`/api/${input.action.id}\` })`).
+Each transport takes a single creation function so you decide how simple or complex it should be —
+derive the request per action straight from the params (e.g.
+`HttpTransport.create({ createRequest: (input) => ({ url: \`/api/${input.action.id}\` }) })`). For full
+control over readiness (support detection, async init), `WebSocketTransport` / `CustomTransport` also
+offer `.createAdvanced({ getTransport })`.
 
 ---
 

package/build/index.js

@@ -2124,20 +2124,32 @@ class CustomTransport extends Transport {
     super();
     this.options = options;
   }
+  static create(options) {
+    return new CustomTransport({ ...options, mode: "send" });
+  }
+  static createAdvanced(options) {
+    return new CustomTransport({ ...options, mode: "advanced" });
+  }
   _createConnection(_ctx) {
     const options = this.options;
+    let getTransport;
+    if (options.mode === "advanced") {
+      getTransport = options.getTransport;
+    } else {
+      getTransport = () => ({
+        status: "ready" /* ready */,
+        readyData: {
+          sendActionData: options.sendActionData,
+          sendReturnData: options.sendReturnData,
+          updateRunConfig: options.updateRunConfig,
+          closeTransport: options.closeTransport ?? (() => {})
+        }
+      });
+    }
     return new CustomConnection({
       initialize: () => ({
         getTransportCacheKey: options.getTransportCacheKey,
-        getTransport: options.getTransport ?? (() => ({
-          status: "ready" /* ready */,
-          readyData: {
-            sendActionData: options.sendActionData,
-            sendReturnData: options.sendReturnData,
-            updateRunConfig: options.updateRunConfig,
-            closeTransport: options.closeTransport ?? (() => {})
-          }
-        }))
+        getTransport
       })
     });
   }
@@ -2285,9 +2297,6 @@ class HttpConnection extends TransportConnection {
 }
 
 // src/ActionRuntime/Handler/ExternalClient/Transport/Http/HttpTransport.ts
-function resolveMaybe(value, input) {
-  return typeof value === "function" ? value(input) : value;
-}
 function shortPath(url) {
   try {
     return new URL(url).pathname || url;
@@ -2303,13 +2312,8 @@ class HttpTransport extends Transport {
     super();
     this.options = options;
   }
-  _resolveRequest(input) {
-    if (this.options.createRequest != null)
-      return this.options.createRequest(input);
-    return {
-      url: resolveMaybe(this.options.url, input),
-      headers: this.options.headers != null ? resolveMaybe(this.options.headers, input) : undefined
-    };
+  static create(options) {
+    return new HttpTransport(options);
   }
   _createConnection(_ctx) {
     return new HttpConnection({
@@ -2318,7 +2322,7 @@ class HttpTransport extends Transport {
         getTransport: () => ({
           status: "ready" /* ready */,
           readyData: {
-            createRequest: (input) => this._resolveRequest(input),
+            createRequest: this.options.createRequest,
             updateRunConfig: this.options.updateRunConfig
           }
         })
@@ -2326,7 +2330,7 @@ class HttpTransport extends Transport {
     });
   }
   getRouteInfo(input) {
-    const { url } = this._resolveRequest(input);
+    const { url } = this.options.createRequest(input);
     return {
       type: "http" /* http */,
       method: "POST",
@@ -2502,10 +2506,6 @@ class WebSocketConnection extends TransportConnection {
 }
 
 // src/ActionRuntime/Handler/ExternalClient/Transport/WebSocket/WebSocketTransport.ts
-function resolveMaybe2(value, input) {
-  return typeof value === "function" ? value(input) : value;
-}
-
 class WebSocketTransport extends Transport {
   options;
   type = "ws" /* ws */;
@@ -2513,38 +2513,40 @@ class WebSocketTransport extends Transport {
     super();
     this.options = options;
   }
-  _createSocket(input) {
-    if (this.options.createWebSocket != null)
-      return this.options.createWebSocket(input);
-    if (this.options.url == null) {
-      throw new Error("WebSocketTransport requires `url` or `createWebSocket` when not using `getTransport`.");
-    }
-    return new WebSocket(resolveMaybe2(this.options.url, input));
+  static create(options) {
+    return new WebSocketTransport({ ...options, mode: "socket" });
+  }
+  static createAdvanced(options) {
+    return new WebSocketTransport({ ...options, mode: "advanced" });
   }
   _createConnection(ctx) {
-    const { url, getTransportCacheKey, getTransport } = this.options;
+    const options = this.options;
+    let getTransport;
+    if (options.mode === "advanced") {
+      getTransport = options.getTransport;
+    } else {
+      getTransport = (input) => ({
+        status: "ready" /* ready */,
+        readyData: {
+          ws: options.createWebSocket(input),
+          formatMessage: options.formatMessage,
+          updateRunConfig: options.updateRunConfig
+        }
+      });
+    }
     return new WebSocketConnection({
       initialize: () => ({
-        getTransportCacheKey: getTransportCacheKey ?? (url != null ? (input) => [resolveMaybe2(url, input)] : undefined),
-        getTransport: getTransport ?? ((input) => ({
-          status: "ready" /* ready */,
-          readyData: {
-            ws: this._createSocket(input),
-            formatMessage: this.options.formatMessage,
-            updateRunConfig: this.options.updateRunConfig
-          }
-        }))
+        getTransportCacheKey: options.getTransportCacheKey,
+        getTransport
       })
     }, ctx.resolvers);
   }
   getRouteInfo(input) {
     if (this.options.getRouteInfo != null)
       return this.options.getRouteInfo(input);
-    const url = this.options.url != null ? resolveMaybe2(this.options.url, input) : undefined;
     return {
       type: "ws" /* ws */,
-      url,
-      summary: url != null ? `ws ${shortWs(url)}` : "ws"
+      summary: "ws"
     };
   }
 }

package/build/types/ActionRuntime/Handler/ExternalClient/Transport/Custom/CustomTransport.d.ts

@@ -2,32 +2,42 @@ import { type ITransportConnectionContext, Transport } from "../Transport";
 import { ETransportType, type ITransportMethod_SendActionData_Input, type ITransportRouteActionParams, type ITransportRouteInfo, type TSendReturnDataMethod, type TUpdateActionRunConfig } from "../Transport.types";
 import { CustomConnection } from "./CustomConnection";
 import type { IActionTransportInitialized_Custom } from "./TransportCustom.types";
-export interface ICustomTransportOptions {
-    /** Send a request/progress payload to the external client. */
-    sendActionData: (input: ITransportMethod_SendActionData_Input) => void;
-    /** Optional return-path dispatch for bidirectional channels. */
-    sendReturnData?: TSendReturnDataMethod;
-    closeTransport?: (input?: ITransportRouteActionParams) => void;
+interface ICustomTransportSharedOptions {
     updateRunConfig?: TUpdateActionRunConfig;
     getTransportCacheKey?: (input: ITransportRouteActionParams) => string[];
-    /**
-     * Advanced escape hatch — full control over readiness/initialization. When provided, the simple
-     * `sendActionData` / `sendReturnData` / `closeTransport` fields are ignored.
-     */
-    getTransport?: IActionTransportInitialized_Custom["getTransport"];
     /** Short label shown in the devtools chip (defaults to "custom"). */
     label?: string;
     /** Override the devtools route info for a specific action. */
     getRouteInfo?: (input: ITransportRouteActionParams) => ITransportRouteInfo;
 }
+export interface ICustomTransportSendOptions extends ICustomTransportSharedOptions {
+    /** Send a request/progress payload to the external client. */
+    sendActionData: (input: ITransportMethod_SendActionData_Input) => void;
+    /** Optional return-path dispatch for bidirectional channels. */
+    sendReturnData?: TSendReturnDataMethod;
+    closeTransport?: (input?: ITransportRouteActionParams) => void;
+}
+export interface ICustomTransportAdvancedOptions extends ICustomTransportSharedOptions {
+    /** Full control over readiness/initialization for the custom channel. */
+    getTransport: IActionTransportInitialized_Custom["getTransport"];
+}
+export type TCustomTransportOptions = (ICustomTransportSendOptions & {
+    mode: "send";
+}) | (ICustomTransportAdvancedOptions & {
+    mode: "advanced";
+});
 /**
- * Reusable custom transport definition for channels nice-action doesn't model natively. Provide
- * `sendActionData` for the simple case, or `getTransport` for full control over the lifecycle.
+ * Reusable custom transport definition for channels nice-action doesn't model natively. Create one
+ * with `CustomTransport.create({ sendActionData })` for the simple case, or
+ * `CustomTransport.createAdvanced({ getTransport })` for full control over the lifecycle.
  */
 export declare class CustomTransport extends Transport<ETransportType.custom> {
     private readonly options;
     readonly type = ETransportType.custom;
-    constructor(options: ICustomTransportOptions);
+    constructor(options: TCustomTransportOptions);
+    static create(options: ICustomTransportSendOptions): CustomTransport;
+    static createAdvanced(options: ICustomTransportAdvancedOptions): CustomTransport;
     _createConnection(_ctx: ITransportConnectionContext): CustomConnection;
     getRouteInfo(input: ITransportRouteActionParams): ITransportRouteInfo;
 }
+export {};

package/build/types/ActionRuntime/Handler/ExternalClient/Transport/Http/HttpTransport.d.ts

@@ -2,27 +2,25 @@ import { type ITransportConnectionContext, Transport } from "../Transport";
 import { ETransportType, type ITransportRouteActionParams, type ITransportRouteInfo, type TUpdateActionRunConfig } from "../Transport.types";
 import { HttpConnection } from "./HttpConnection";
 import type { IHttpRequestParams } from "./TransportHttp.types";
-type TMaybeResolved<T> = T | ((input: ITransportRouteActionParams) => T);
 export interface IHttpTransportOptions {
-    /** Endpoint URL, either static or derived per action. */
-    url: TMaybeResolved<string>;
-    /** Optional extra headers, either static or derived per action. */
-    headers?: TMaybeResolved<Record<string, string>>;
-    /** Advanced escape hatch — full control over the request. Overrides `url` / `headers`. */
-    createRequest?: (input: ITransportRouteActionParams) => IHttpRequestParams;
+    /**
+     * Build the HTTP request for an action. Return a static request for the simple case, or derive the
+     * url / headers / body from the action params for full control.
+     */
+    createRequest: (input: ITransportRouteActionParams) => IHttpRequestParams;
     updateRunConfig?: TUpdateActionRunConfig;
     getTransportCacheKey?: (input: ITransportRouteActionParams) => string[];
 }
 /**
- * Reusable HTTP transport definition. Common case is just `new HttpTransport({ url })`; pass
- * functions for `url` / `headers` to derive them per action, or `createRequest` for full control.
+ * Reusable HTTP transport definition. Create one with `HttpTransport.create({ createRequest })` — the
+ * single `createRequest` function lets you keep it simple (`() => ({ url })`) or derive the request
+ * per action.
  */
 export declare class HttpTransport extends Transport<ETransportType.http> {
     private readonly options;
     readonly type = ETransportType.http;
     constructor(options: IHttpTransportOptions);
-    private _resolveRequest;
+    static create(options: IHttpTransportOptions): HttpTransport;
     _createConnection(_ctx: ITransportConnectionContext): HttpConnection;
     getRouteInfo(input: ITransportRouteActionParams): ITransportRouteInfo;
 }
-export {};

package/build/types/ActionRuntime/Handler/ExternalClient/Transport/Transport.d.ts

@@ -9,8 +9,9 @@ export interface ITransportConnectionContext {
     resolvers?: IActionTransportResolvers;
 }
 /**
- * Reusable transport definition. Devs construct these (`new HttpTransport({ url })`,
- * `new WebSocketTransport({ url })`, …) and pass them to an `ActionExternalClientHandler`. A single
+ * Reusable transport definition. Devs construct these (`HttpTransport.create({ createRequest })`,
+ * `WebSocketTransport.create({ createWebSocket })`, …) and pass them to an
+ * `ActionExternalClientHandler`. A single
  * definition can be shared across multiple handlers — each handler builds its own live
  * {@link TransportConnection} via {@link TransportConnection._createConnection}.
  */

package/build/types/ActionRuntime/Handler/ExternalClient/Transport/WebSocket/WebSocketTransport.d.ts

@@ -2,39 +2,47 @@ import { type ITransportConnectionContext, Transport } from "../Transport";
 import { ETransportType, type ITransportRouteActionParams, type ITransportRouteInfo, type TUpdateActionRunConfig } from "../Transport.types";
 import type { IActionTransportInitialized_Ws, IActionTransportReadyData_Ws } from "./TransportWebSocket.types";
 import { WebSocketConnection } from "./WebSocketConnection";
-type TMaybeResolved<T> = T | ((input: ITransportRouteActionParams) => T);
-export interface IWebSocketTransportOptions {
-    /** WebSocket endpoint URL, either static or derived per action. Optional when `getTransport` is used. */
-    url?: TMaybeResolved<string>;
-    /** Advanced escape hatch — provide your own socket (e.g. with sub-protocols). Overrides `url`. */
-    createWebSocket?: (input: ITransportRouteActionParams) => WebSocket;
+interface IWebSocketTransportSharedOptions {
     /** Custom (de)serialization of action payloads on the wire. */
     formatMessage?: IActionTransportReadyData_Ws["formatMessage"];
     updateRunConfig?: TUpdateActionRunConfig;
     /**
-     * Keys that identify a reusable socket. Defaults to the resolved url, so a single socket is shared
-     * across actions to the same endpoint instead of opening one per action.
+     * Keys that identify a reusable socket, so a single socket is shared across actions to the same
+     * endpoint instead of opening one per action.
      */
     getTransportCacheKey?: (input: ITransportRouteActionParams) => string[];
+    /** Override the devtools route info for a specific action. */
+    getRouteInfo?: (input: ITransportRouteActionParams) => ITransportRouteInfo;
+}
+export interface IWebSocketTransportSocketOptions extends IWebSocketTransportSharedOptions {
+    /** Open (or reuse) the WebSocket for an action — keep it simple or derive it per action. */
+    createWebSocket: (input: ITransportRouteActionParams) => WebSocket;
+}
+export interface IWebSocketTransportAdvancedOptions extends IWebSocketTransportSharedOptions {
     /**
-     * Advanced escape hatch — full control over readiness/initialization. Use this for contextual
-     * support detection (return `{ status: ETransportStatus.unsupported }` when the socket shouldn't be
-     * used) or async URL building (return `{ status: ETransportStatus.initializing, initializationPromise }`
-     * that resolves to a `ready` socket). When provided, `url` / `createWebSocket` are ignored.
+     * Full control over readiness/initialization. Use this for contextual support detection (return
+     * `{ status: ETransportStatus.unsupported }` when the socket shouldn't be used) or async url
+     * building (return `{ status: ETransportStatus.initializing, initializationPromise }` that resolves
+     * to a `ready` socket).
      */
-    getTransport?: IActionTransportInitialized_Ws["getTransport"];
-    /** Override the devtools route info for a specific action (useful alongside `getTransport`). */
-    getRouteInfo?: (input: ITransportRouteActionParams) => ITransportRouteInfo;
+    getTransport: IActionTransportInitialized_Ws["getTransport"];
 }
+export type TWebSocketTransportOptions = (IWebSocketTransportSocketOptions & {
+    mode: "socket";
+}) | (IWebSocketTransportAdvancedOptions & {
+    mode: "advanced";
+});
 /**
- * Reusable WebSocket transport definition. Common case is just `new WebSocketTransport({ url })`. The
- * underlying socket is cached (by url, by default) and reused across actions to the same endpoint.
+ * Reusable WebSocket transport definition. Create one with `WebSocketTransport.create({ createWebSocket })`
+ * for the common case, or `WebSocketTransport.createAdvanced({ getTransport })` for full control over
+ * readiness. The underlying socket is cached (via `getTransportCacheKey`) and reused across actions.
  */
 export declare class WebSocketTransport extends Transport<ETransportType.ws> {
     private readonly options;
     readonly type = ETransportType.ws;
-    constructor(options: IWebSocketTransportOptions);
-    private _createSocket;
+    constructor(options: TWebSocketTransportOptions);
+    static create(options: IWebSocketTransportSocketOptions): WebSocketTransport;
+    static createAdvanced(options: IWebSocketTransportAdvancedOptions): WebSocketTransport;
     _createConnection(ctx: ITransportConnectionContext): WebSocketConnection;
     getRouteInfo(input: ITransportRouteActionParams): ITransportRouteInfo;
 }

package/build/types/index.d.ts

@@ -22,7 +22,7 @@ export * from "./ActionRuntime/Handler/ExternalClient/Transport/err_nice_transpo
 export { HttpTransport, type IHttpTransportOptions, } from "./ActionRuntime/Handler/ExternalClient/Transport/Http/HttpTransport";
 export { type ITransportConnectionContext, Transport, } from "./ActionRuntime/Handler/ExternalClient/Transport/Transport";
 export * from "./ActionRuntime/Handler/ExternalClient/Transport/Transport.types";
-export { type IWebSocketTransportOptions, WebSocketTransport, } from "./ActionRuntime/Handler/ExternalClient/Transport/WebSocket/WebSocketTransport";
+export { type IWebSocketTransportAdvancedOptions, type IWebSocketTransportSocketOptions, type TWebSocketTransportOptions, WebSocketTransport, } from "./ActionRuntime/Handler/ExternalClient/Transport/WebSocket/WebSocketTransport";
 export { ActionLocalHandler, createLocalHandler, } from "./ActionRuntime/Handler/Local/ActionLocalHandler";
 export * from "./ActionRuntime/RuntimeCoordinate";
 export { EErrId_NiceAction, err_nice_action } from "./errors/err_nice_action";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nice-code/action",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "private": false,
   "type": "module",
   "exports": {
@@ -44,9 +44,9 @@
     "build-types": "tsc --project tsconfig.build.json"
   },
   "dependencies": {
-    "@nice-code/common-errors": "0.4.6",
-    "@nice-code/error": "0.4.6",
-    "@nice-code/util": "0.4.6",
+    "@nice-code/common-errors": "0.4.7",
+    "@nice-code/error": "0.4.7",
+    "@nice-code/util": "0.4.7",
     "@standard-schema/spec": "^1.1.0",
     "@tanstack/react-virtual": "^3.13.26",
     "http-status-codes": "^2.3.0",