@nice-code/action 0.2.11 → 0.2.12

package/build/devtools/server/index.js

@@ -0,0 +1,232 @@
+// src/ActionDefinition/Action/RunningAction.types.ts
+var ERunningActionState;
+((ERunningActionState2) => {
+  ERunningActionState2["running"] = "running";
+  ERunningActionState2["completed"] = "completed";
+})(ERunningActionState ||= {});
+var ERunningActionUpdateType;
+((ERunningActionUpdateType2) => {
+  ERunningActionUpdateType2["started"] = "started";
+  ERunningActionUpdateType2["progress"] = "progress";
+  ERunningActionUpdateType2["finished"] = "finished";
+})(ERunningActionUpdateType ||= {});
+var ERunningActionFinishedType;
+((ERunningActionFinishedType2) => {
+  ERunningActionFinishedType2["aborted"] = "aborted";
+  ERunningActionFinishedType2["failed"] = "failed";
+  ERunningActionFinishedType2["success"] = "success";
+})(ERunningActionFinishedType ||= {});
+
+// src/devtools/server/NiceActionServerDevtools.ts
+class ActionServerDevtools {
+  _options;
+  _inFlight = new Map;
+  constructor(options = {}) {
+    const defaultEnabled = typeof process !== "undefined" ? true : true;
+    this._options = {
+      logger: options.logger ?? defaultConsoleLogger,
+      format: options.format ?? "pretty",
+      logPayloads: options.logPayloads ?? true,
+      enabled: options.enabled ?? defaultEnabled
+    };
+  }
+  attachToDomain(domain) {
+    if (!this._options.enabled) {
+      return () => {};
+    }
+    return domain.addActionListener((update) => {
+      const { runningAction, type, time } = update;
+      const actionPath = [...runningAction.allDomains, runningAction.id].join(".");
+      if (type === "started" /* started */) {
+        this._inFlight.set(runningAction.cuid, { startTime: time });
+        this._log("started", actionPath, runningAction.cuid, {
+          ...this._options.logPayloads ? { input: runningAction.state?.request?.input } : {}
+        });
+      } else if (type === "progress" /* progress */) {
+        this._log("progress", actionPath, runningAction.cuid, { progress: update.progress });
+      } else if (type === "finished" /* finished */) {
+        const timing = this._inFlight.get(runningAction.cuid);
+        const duration = timing != null ? time - timing.startTime : undefined;
+        this._inFlight.delete(runningAction.cuid);
+        const finishType = update.finishType;
+        if (finishType === "success" /* success */) {
+          this._log("success", actionPath, runningAction.cuid, {
+            ...duration != null ? { duration: `${duration}ms` } : {},
+            ...this._options.logPayloads ? { output: update.response?.result?.output } : {}
+          });
+        } else if (finishType === "failed" /* failed */) {
+          this._log("failed", actionPath, runningAction.cuid, {
+            ...duration != null ? { duration: `${duration}ms` } : {},
+            error: serializeError(update.error)
+          });
+        } else {
+          this._log("aborted", actionPath, runningAction.cuid, {
+            ...duration != null ? { duration: `${duration}ms` } : {},
+            ...update.reason != null ? { reason: String(update.reason) } : {}
+          });
+        }
+      }
+    });
+  }
+  _log(event, actionPath, cuid, data) {
+    const { logger, format } = this._options;
+    if (format === "json") {
+      logger(JSON.stringify({ time: new Date().toISOString(), event, action: actionPath, cuid, ...data }));
+      return;
+    }
+    const prefix = PRETTY_PREFIX[event] ?? `[${event}]`;
+    const suffix = Object.keys(data).length > 0 ? `  ${formatPrettyData(data)}` : "";
+    logger(`${prefix} ${actionPath}  cuid=${cuid}${suffix}`);
+  }
+}
+var PRETTY_PREFIX = {
+  started: "[nice-action] ►",
+  progress: "[nice-action]  ",
+  success: "[nice-action] ✓",
+  failed: "[nice-action] ✗",
+  aborted: "[nice-action] ○"
+};
+function formatPrettyData(data) {
+  return Object.entries(data).map(([k, v]) => `${k}=${safeStringify(v)}`).join(" ");
+}
+function safeStringify(value) {
+  if (value === undefined)
+    return "undefined";
+  if (value === null)
+    return "null";
+  if (typeof value === "string")
+    return `"${value}"`;
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+function serializeError(err) {
+  if (err == null)
+    return err;
+  if (err instanceof Error)
+    return { message: err.message, name: err.name, stack: err.stack };
+  if (typeof err === "object") {
+    try {
+      return JSON.parse(JSON.stringify(err));
+    } catch {
+      return String(err);
+    }
+  }
+  return err;
+}
+function defaultConsoleLogger(message) {
+  console.log(message);
+}
+// src/devtools/core/ActionDevtoolsCore.ts
+function extractRouting(context) {
+  return (context?.routing ?? []).map((item) => {
+    const handler = item.handler;
+    const isExternal = handler?.type === "external";
+    return {
+      runtime: {
+        envId: item.runtime?.envId ?? "unknown",
+        perId: item.runtime?.perId,
+        insId: item.runtime?.insId
+      },
+      handlerType: isExternal ? "external" : "local",
+      handlerClient: isExternal && handler.client != null ? {
+        envId: handler.client.envId ?? "unknown",
+        perId: handler.client.perId,
+        insId: handler.client.insId
+      } : undefined,
+      transport: isExternal ? handler.transType : undefined,
+      time: item.time
+    };
+  });
+}
+function extractMeta(context) {
+  return {
+    timeCreated: context?.timeCreated ?? Date.now(),
+    originClient: {
+      envId: context?.originClient?.envId ?? "unknown",
+      perId: context?.originClient?.perId,
+      insId: context?.originClient?.insId
+    },
+    routing: extractRouting(context)
+  };
+}
+
+class ActionDevtoolsCore {
+  _entries = [];
+  _listeners = new Set;
+  _maxEntries;
+  constructor(options = {}) {
+    this._maxEntries = options.maxEntries ?? 100;
+  }
+  attachToDomain(domain) {
+    return domain.addActionListener((update) => {
+      const { runningAction, type, time } = update;
+      if (type === "started" /* started */) {
+        const entry = {
+          cuid: runningAction.cuid,
+          actionId: runningAction.id,
+          domain: runningAction.domain,
+          allDomains: [...runningAction.allDomains],
+          status: "running",
+          startTime: time,
+          input: runningAction.state?.request?.input,
+          progressUpdates: [],
+          meta: extractMeta(runningAction.context)
+        };
+        this._entries = [entry, ...this._entries].slice(0, this._maxEntries);
+        this._notify();
+      } else if (type === "progress" /* progress */) {
+        this._updateEntry(runningAction.cuid, (e) => ({
+          ...e,
+          progressUpdates: [...e.progressUpdates, update.progress]
+        }));
+      } else if (type === "finished" /* finished */) {
+        this._updateEntry(runningAction.cuid, (e) => {
+          const finishedRoutingContext = update.response?.context ?? runningAction.context;
+          const base = {
+            ...e,
+            endTime: time,
+            meta: { ...e.meta, routing: extractRouting(finishedRoutingContext) }
+          };
+          const finishType = update.finishType;
+          if (finishType === "success" /* success */) {
+            return { ...base, status: "success", output: update.response?.result?.output };
+          }
+          if (finishType === "failed" /* failed */) {
+            return { ...base, status: "failed", error: update.error };
+          }
+          return { ...base, status: "aborted", abortReason: update.reason };
+        });
+      }
+    });
+  }
+  getEntries() {
+    return this._entries;
+  }
+  subscribe(listener) {
+    this._listeners.add(listener);
+    listener(this._entries);
+    return () => {
+      this._listeners.delete(listener);
+    };
+  }
+  clear() {
+    this._entries = [];
+    this._notify();
+  }
+  _updateEntry(cuid, updater) {
+    this._entries = this._entries.map((e) => e.cuid === cuid ? updater(e) : e);
+    this._notify();
+  }
+  _notify() {
+    const snapshot = this._entries;
+    for (const listener of this._listeners)
+      listener(snapshot);
+  }
+}
+export {
+  ActionServerDevtools,
+  ActionDevtoolsCore
+};

package/build/index.js

@@ -37,19 +37,19 @@ class RuntimeCoordinate {
     this.perId = perId;
     this.insId = insId;
   }
-  specify(newInputs) {
+  specify(specifics) {
     return new RuntimeCoordinate({
       envId: this.envId,
       perId: this.perId,
       insId: this.insId,
-      ...newInputs
+      ...specifics
     });
   }
-  specifyIfUnset(newInputs) {
+  specifyIfUnset(specifics) {
     return new RuntimeCoordinate({
       envId: this.envId,
-      perId: this.perId ?? newInputs.perId,
-      insId: this.insId ?? newInputs.insId
+      perId: this.perId ?? specifics.perId,
+      insId: this.insId ?? specifics.insId
     });
   }
   toJsonObject() {
@@ -864,13 +864,13 @@ class ActionRuntime {
   get coordinate() {
     return this._coordinate;
   }
-  updateRuntimeCoordinate(newCoordinate) {
-    if (this._coordinate.envId !== newCoordinate.envId) {
+  specifyRuntimeCoordinate(specifics) {
+    if (specifics.envId != null && this._coordinate.envId !== specifics.envId) {
       throw err_nice_action.fromId("not_implemented" /* not_implemented */, {
-        label: `updating RuntimeCoordinate with a different "envId" ("${this._coordinate.envId}" → "${newCoordinate.envId}")`
+        label: `updating RuntimeCoordinate with a different "envId" ("${this._coordinate.envId}" → "${specifics.envId}")`
       });
     }
-    this._coordinate = newCoordinate;
+    this._coordinate = this._coordinate.specify(specifics);
     this.apply();
   }
   registerRunningAction(ra) {

package/build/types/ActionRuntime/ActionRuntime.d.ts

@@ -5,7 +5,7 @@ import type { IActionDomain } from "../ActionDefinition/Domain/ActionDomain.type
 import type { IRuntimeMeta, TActionRuntimeHandler } from "./ActionRuntime.types";
 import { type IHandleActionOptions, type TActionHandler } from "./Handler/ActionHandler.types";
 import type { ActionExternalClientHandler } from "./Handler/ExternalClient/ActionExternalClientHandler";
-import { RuntimeCoordinate } from "./RuntimeCoordinate";
+import { type IRuntimeCoordinateSpecifics, RuntimeCoordinate } from "./RuntimeCoordinate";
 export declare class ActionRuntime {
     private _coordinate;
     readonly timeCreated: number;
@@ -17,7 +17,9 @@ export declare class ActionRuntime {
     static getDefault(): ActionRuntime;
     constructor(coordinate: RuntimeCoordinate);
     get coordinate(): RuntimeCoordinate;
-    updateRuntimeCoordinate(newCoordinate: RuntimeCoordinate): void;
+    specifyRuntimeCoordinate(specifics: IRuntimeCoordinateSpecifics & {
+        envId?: string;
+    }): void;
     registerRunningAction(ra: RunningAction<any, any>): void;
     resolveIncomingActionPayload(json: TActionPayload_Any_JsonObject<any, any>): void;
     /**

package/build/types/ActionRuntime/RuntimeCoordinate.d.ts

@@ -1,8 +1,4 @@
-export interface IRuntimeCoordinate {
-    /**
-     * A static runtime environment identifier (e.g. "web_app_v1", "backend_analytics")
-     */
-    envId: string;
+export interface IRuntimeCoordinateSpecifics {
     /**
      * A unique and persistent client ID (should stay the same between runtime instance reloads)
      */
@@ -13,6 +9,12 @@ export interface IRuntimeCoordinate {
      */
     insId?: string;
 }
+export interface IRuntimeCoordinate extends IRuntimeCoordinateSpecifics {
+    /**
+     * A static runtime environment identifier (e.g. "web_app_v1", "backend_analytics")
+     */
+    envId: string;
+}
 export type TRuntimeCoordinateEnvId = `envId[${string}]`;
 export type TRuntimeCoordinateStringId = `${TRuntimeCoordinateEnvId}perId[${string | "_"}]:insId[${string | "_"}]`;
 export interface IRuntimeFullCoordinates extends Required<IRuntimeCoordinate> {
@@ -25,8 +27,8 @@ export declare class RuntimeCoordinate implements IRuntimeCoordinate {
     static env(envId: string): RuntimeCoordinate;
     withPersistentId(perId: string): RuntimeCoordinate;
     constructor({ envId, perId, insId }: IRuntimeCoordinate);
-    specify(newInputs: Omit<IRuntimeCoordinate, "envId">): RuntimeCoordinate;
-    specifyIfUnset(newInputs: Omit<IRuntimeCoordinate, "envId">): RuntimeCoordinate;
+    specify(specifics: IRuntimeCoordinateSpecifics): RuntimeCoordinate;
+    specifyIfUnset(specifics: IRuntimeCoordinateSpecifics): RuntimeCoordinate;
     toJsonObject(): IRuntimeCoordinate;
     isExactlySame(other: IRuntimeCoordinate): boolean;
     isSameFor(other: IRuntimeCoordinate): {

package/build/types/devtools/browser/NiceActionDevtools.d.ts

@@ -0,0 +1,8 @@
+import type { TDevtoolsPosition } from "../core/ActionDevtools.types";
+import type { ActionDevtoolsCore } from "../core/ActionDevtoolsCore";
+export interface INiceActionDevtoolsProps {
+    core: ActionDevtoolsCore;
+    position?: TDevtoolsPosition;
+    initialOpen?: boolean;
+}
+export declare function NiceActionDevtools(props: INiceActionDevtoolsProps): import("react/jsx-runtime").JSX.Element | null;

package/build/types/devtools/browser/index.d.ts

@@ -0,0 +1,3 @@
+export type { IDevtoolsActionEntry, IDevtoolsObservableDomain, TDevtoolsActionStatus, TDevtoolsListener, } from "../core/ActionDevtools.types";
+export { ActionDevtoolsCore, type IActionDevtoolsCoreOptions } from "../core/ActionDevtoolsCore";
+export { type INiceActionDevtoolsProps, NiceActionDevtools } from "./NiceActionDevtools";

package/build/types/devtools/core/ActionDevtools.types.d.ts

@@ -0,0 +1,47 @@
+import type { TActionProgress } from "../../ActionDefinition/Action/Payload/ActionPayload.types";
+export type TDevtoolsActionStatus = "running" | "success" | "failed" | "aborted";
+export type TDevtoolsPosition = "bottom-right" | "bottom-left" | "top-right" | "top-left" | "dock-bottom" | "dock-top" | "dock-left" | "dock-right";
+export interface IDevtoolsRouteItem {
+    runtime: {
+        envId: string;
+        perId?: string;
+        insId?: string;
+    };
+    handlerType: "local" | "external";
+    handlerClient?: {
+        envId: string;
+        perId?: string;
+        insId?: string;
+    };
+    transport?: string;
+    time: number;
+}
+export interface IDevtoolsActionMeta {
+    timeCreated: number;
+    originClient: {
+        envId: string;
+        perId?: string;
+        insId?: string;
+    };
+    routing: IDevtoolsRouteItem[];
+}
+export interface IDevtoolsActionEntry {
+    cuid: string;
+    actionId: string;
+    domain: string;
+    allDomains: string[];
+    status: TDevtoolsActionStatus;
+    startTime: number;
+    endTime?: number;
+    input: unknown;
+    output?: unknown;
+    error?: unknown;
+    abortReason?: unknown;
+    progressUpdates: TActionProgress[];
+    meta: IDevtoolsActionMeta;
+}
+export type TDevtoolsListener = (entries: readonly IDevtoolsActionEntry[]) => void;
+export interface IDevtoolsObservableDomain {
+    domain: string;
+    addActionListener(listener: (update: any) => void): () => void;
+}

package/build/types/devtools/core/ActionDevtoolsCore.d.ts

@@ -0,0 +1,16 @@
+import type { IDevtoolsActionEntry, IDevtoolsObservableDomain, TDevtoolsListener } from "./ActionDevtools.types";
+export interface IActionDevtoolsCoreOptions {
+    maxEntries?: number;
+}
+export declare class ActionDevtoolsCore {
+    private _entries;
+    private _listeners;
+    private readonly _maxEntries;
+    constructor(options?: IActionDevtoolsCoreOptions);
+    attachToDomain(domain: IDevtoolsObservableDomain): () => void;
+    getEntries(): readonly IDevtoolsActionEntry[];
+    subscribe(listener: TDevtoolsListener): () => void;
+    clear(): void;
+    private _updateEntry;
+    private _notify;
+}

package/build/types/devtools/server/NiceActionServerDevtools.d.ts

@@ -0,0 +1,30 @@
+import type { IDevtoolsObservableDomain } from "../core/ActionDevtools.types";
+export type TServerDevtoolsLogFn = (message: string, data?: Record<string, unknown>) => void;
+export interface IActionServerDevtoolsOptions {
+    /**
+     * Custom logger function. Defaults to console.log / console.error.
+     */
+    logger?: TServerDevtoolsLogFn;
+    /**
+     * Output format.
+     * - "pretty": human-readable lines (default)
+     * - "json": newline-delimited JSON for log aggregators
+     */
+    format?: "pretty" | "json";
+    /**
+     * Whether to log action input/output payloads.
+     * Disable if payloads may contain sensitive data. Defaults to true.
+     */
+    logPayloads?: boolean;
+    /**
+     * Whether devtools are active. Defaults to process.env.NODE_ENV !== "production".
+     */
+    enabled?: boolean;
+}
+export declare class ActionServerDevtools {
+    private readonly _options;
+    private readonly _inFlight;
+    constructor(options?: IActionServerDevtoolsOptions);
+    attachToDomain(domain: IDevtoolsObservableDomain): () => void;
+    private _log;
+}

package/build/types/devtools/server/index.d.ts

@@ -0,0 +1,3 @@
+export { ActionServerDevtools, type IActionServerDevtoolsOptions, type TServerDevtoolsLogFn, } from "./NiceActionServerDevtools";
+export { ActionDevtoolsCore, type IActionDevtoolsCoreOptions } from "../core/ActionDevtoolsCore";
+export type { IDevtoolsActionEntry, IDevtoolsObservableDomain, TDevtoolsActionStatus, TDevtoolsListener, } from "../core/ActionDevtools.types";

package/build/types/index.d.ts

@@ -24,7 +24,7 @@ export type { TActionTransportDef } from "./ActionRuntime/Handler/ExternalClient
 export * from "./ActionRuntime/Handler/ExternalClient/Transport/Transport.types";
 export * from "./ActionRuntime/Handler/ExternalClient/Transport/WebSocket/TransportWebSocket";
 export { ActionLocalHandler, createLocalHandler, } from "./ActionRuntime/Handler/Local/ActionLocalHandler";
-export { type IRuntimeCoordinate, RuntimeCoordinate, } from "./ActionRuntime/RuntimeCoordinate";
+export * from "./ActionRuntime/RuntimeCoordinate";
 export { EErrId_NiceAction, err_nice_action } from "./errors/err_nice_action";
 export { isActionPayload_Any_JsonObject } from "./utils/isActionPayload_Any_JsonObject";
 export * from "./utils/isActionPayload_Request_JsonObject";

package/package.json

@@ -1,16 +1,28 @@
 {
   "name": "@nice-code/action",
-  "version": "0.2.11",
+  "version": "0.2.12",
   "private": false,
   "type": "module",
   "exports": {
     ".": {
+      "source": "./src/index.ts",
       "types": "./build/types/index.d.ts",
       "import": "./build/index.js"
     },
     "./react-query": {
+      "source": "./src/react-query/index.ts",
       "types": "./build/types/react-query/index.d.ts",
       "import": "./build/react-query/index.js"
+    },
+    "./devtools/browser": {
+      "source": "./src/devtools/browser/index.ts",
+      "types": "./build/types/devtools/browser/index.d.ts",
+      "import": "./build/devtools/browser/index.js"
+    },
+    "./devtools/server": {
+      "source": "./src/devtools/server/index.ts",
+      "types": "./build/types/devtools/server/index.d.ts",
+      "import": "./build/devtools/server/index.js"
     }
   },
   "files": [
@@ -32,15 +44,17 @@
     "build-types": "tsc --project tsconfig.build.json"
   },
   "dependencies": {
-    "@nice-code/error": "0.2.11",
-    "@nice-code/common-errors": "0.2.11",
+    "@nice-code/common-errors": "0.2.12",
+    "@nice-code/error": "0.2.12",
     "@standard-schema/spec": "^1.1.0",
+    "@tanstack/react-virtual": "^3.13.26",
     "http-status-codes": "^2.3.0",
     "nanoid": "^5.1.9",
     "std-env": "^4.1.0"
   },
   "devDependencies": {
     "@tanstack/react-query": "^5.100.3",
+    "@types/react": "^19.0.0",
     "msw": "^2.13.6"
   },
   "peerDependencies": {