depa-actor 0.1.2 → 0.2.1

package/src/core/ActorSystem.ts

@@ -14,7 +14,7 @@ import type {
   ActorSelf,
   TaggedEnvelope,
   TagHandler,
-} from './types';
+} from './types.js';
 
 // ─── ActorCell (internal) ────────────────────────────────────────────
 

package/src/dispatch/ActorDispatchAdapter.ts

@@ -1,83 +1,254 @@
 /**
  * depa-actor — Dispatch Bridge
  *
- * Optional bridge to depa-processor DispatchEngine.
- * Only this file imports from depa-processor concepts.
- * No hard dependency — uses structural typing.
+ * Drives the depa-processor `DispatchEngine` (all 7 strategies) from the actor
+ * side. The envelope → DispatchRequest adaptation and the actor `tag` overlay
+ * live HERE, in depa-actor — the generic `DispatchEngine` / `DispatchStrategyConfig`
+ * stay free of any actor (`envelope` / `tag` / `ActorSelf`) knowledge.
+ *
+ * Two orthogonal axes:
+ *   1. `tag` — actor's first-level route (which mailbox). Selecting a handler by
+ *      tag is the actor system's job (`ActorDef.handlers[tag]`); a dispatch handler
+ *      built here is slotted UNDER a tag, so tag selection happens upstream.
+ *      `tag` is NOT a DispatchStrategyType — it is an orthogonal overlay dimension.
+ *   2. `strategy` — one of the 7 `DispatchStrategyType` values, used as the
+ *      second-level resolution within the selected tag.
  */
 
+import {
+  DispatchEngine,
+  DispatchStrategyConfig,
+  DispatchStrategyType,
+  createClassDispatchRequest,
+  createRouteKeyDispatchRequest,
+  createEnumDispatchRequest,
+  createRouteKeyToEnumDispatchRequest,
+  createCommandDispatchRequest,
+  createPathDispatchRequest,
+  createActionPathDispatchRequest,
+} from 'depa-processor';
 import type {
   MailboxSchema,
   ActorSelf,
   ActorEnvelope,
   ActorHandler,
-} from '../core/types';
+} from '../core/types.js';
 
-// ─── DispatchRoute (structural, no import) ───────────────────────────
+// ─── Actor sub-handler ───────────────────────────────────────────────
 
 /**
- * A dispatch route maps a tag to a dispatch key and handler.
- * This is a structural interface — no dependency on depa-processor.
+ * A resolved actor sub-handler: receives `(self, envelope)` and performs side
+ * effects (write state / send messages). This is the `TResult = void | Promise<void>`
+ * shape the underlying DispatchEngine resolves to.
  */
-export interface DispatchRoute<
+export type ActorRouteHandler<
+  TRuntime,
+  TSchema extends MailboxSchema,
+  TState,
+> = (
+  self: ActorSelf<TRuntime, TSchema, TState>,
+  envelope: ActorEnvelope<TSchema>,
+) => void | Promise<void>;
+
+// ─── Key extraction (envelope → dispatch coordinate) ─────────────────
+
+/**
+ * Maps an envelope to the dispatch coordinate consumed by the selected strategy.
+ * Defaults are provided per strategy; override to route by payload fields, etc.
+ */
+export interface DispatchKeyExtractors<TSchema extends MailboxSchema> {
+  /** ROUTE_KEY / ROUTE_KEY_TO_ENUM / COMMAND_TABLE — defaults to `envelope.tag`. */
+  routeKeyOf?: (envelope: ActorEnvelope<TSchema>) => string;
+  /** ENUM — defaults to `envelope.tag`. */
+  enumOf?: (envelope: ActorEnvelope<TSchema>) => string | number;
+  /** CLASS / key-based strategies' input — defaults to `envelope.payload`. */
+  inputOf?: (envelope: ActorEnvelope<TSchema>) => unknown;
+  /** PATH / ACTION_PATH — defaults to `envelope.tag`. */
+  pathOf?: (envelope: ActorEnvelope<TSchema>) => string;
+  /** ACTION_PATH action — defaults to `undefined`. */
+  actionOf?: (envelope: ActorEnvelope<TSchema>) => unknown;
+}
+
+// ─── createDispatchHandler params (object-param, B2 composable) ───────
+
+/**
+ * Parameters for {@link createDispatchHandler}.
+ *
+ * `routes` is either:
+ *  - a plain key → actor-sub-handler map (for the common key-based strategies
+ *    CLASS-by-key is not applicable; use ROUTE_KEY / ENUM / COMMAND_TABLE), or
+ *  - a fully-built `DispatchStrategyConfig<void | Promise<void>>` for advanced
+ *    strategies (PATH / ACTION_PATH / CLASS / ROUTE_KEY_TO_ENUM) where the
+ *    handler wiring is expressed in depa-processor terms.
+ *
+ * When a `DispatchStrategyConfig` is supplied, its handlers receive the raw
+ * dispatch `input` / `context` (already adapted from the envelope) and may
+ * close over `self` via the surrounding scope.
+ */
+export interface CreateDispatchHandlerParams<
   TRuntime,
   TSchema extends MailboxSchema,
   TState,
 > {
-  /** Which tags this route handles */
-  tags: (keyof TSchema & string)[];
-
-  /** Resolve dispatch key from envelope */
-  resolveKey: (envelope: ActorEnvelope<TSchema>) => string;
-
-  /** Route table: dispatch key → handler */
-  routes: Record<string, (
-    self: ActorSelf<TRuntime, TSchema, TState>,
-    envelope: ActorEnvelope<TSchema>,
-  ) => void | Promise<void>>;
-
-  /** Fallback if no route matches */
-  fallback?: (
-    self: ActorSelf<TRuntime, TSchema, TState>,
-    envelope: ActorEnvelope<TSchema>,
-    key: string,
-  ) => void | Promise<void>;
+  /** Which of the 7 strategies to use for second-level resolution. */
+  strategy: DispatchStrategyType;
+
+  /**
+   * Route table. For key-based strategies (ROUTE_KEY / ENUM / COMMAND_TABLE)
+   * pass a `Record<key, ActorRouteHandler>`. For advanced strategies, pass a
+   * prebuilt `DispatchStrategyConfig` whose `TResult = void | Promise<void>`.
+   */
+  routes:
+    | Record<string, ActorRouteHandler<TRuntime, TSchema, TState>>
+    | DispatchStrategyConfig<void | Promise<void>>;
+
+  /** Optional fallback when the strategy does not resolve a handler. */
+  defaultHandler?: ActorHandler<TRuntime, TSchema, TState>;
+
+  /** Optional envelope → dispatch-coordinate extractors. */
+  extractors?: DispatchKeyExtractors<TSchema>;
+}
+
+// ─── Internal helpers ────────────────────────────────────────────────
+
+function isStrategyConfig(
+  routes: unknown,
+): routes is DispatchStrategyConfig<void | Promise<void>> {
+  return routes instanceof DispatchStrategyConfig;
+}
+
+/**
+ * Build a `DispatchStrategyConfig<void>` from a plain key → handler map for the
+ * supported key-based strategies. The map values are pre-bound to `(self, envelope)`
+ * by capturing the current dispatch's `self` / `envelope` via a thunk.
+ */
+function buildKeyBasedConfig<TRuntime, TSchema extends MailboxSchema, TState>(
+  strategy: DispatchStrategyType,
+  routes: Record<string, ActorRouteHandler<TRuntime, TSchema, TState>>,
+  self: ActorSelf<TRuntime, TSchema, TState>,
+  envelope: ActorEnvelope<TSchema>,
+): DispatchStrategyConfig<void | Promise<void>> {
+  const handlerMap = new Map<
+    string | number,
+    (input: unknown) => void | Promise<void>
+  >();
+  for (const [key, handler] of Object.entries(routes)) {
+    handlerMap.set(key, () => handler(self, envelope));
+  }
+
+  switch (strategy) {
+    case DispatchStrategyType.ROUTE_KEY:
+      return DispatchStrategyConfig.forRouteKeyStrategy<void | Promise<void>>({
+        handlerMap: handlerMap as Map<string, (input: unknown) => void | Promise<void>>,
+      });
+    case DispatchStrategyType.ENUM:
+      return DispatchStrategyConfig.forEnumStrategy<void | Promise<void>>({
+        handlerMap,
+      });
+    case DispatchStrategyType.COMMAND_TABLE:
+      return DispatchStrategyConfig.forCommandStrategy<void | Promise<void>>({
+        commandConverter: (command: string) =>
+          handlerMap.has(command) ? command : null,
+        handlerExtractor: (commandEnum: string | number) =>
+          handlerMap.get(commandEnum) ?? null,
+      });
+    default:
+      throw new Error(
+        `createDispatchHandler: strategy ${strategy} requires a prebuilt ` +
+          `DispatchStrategyConfig in 'routes' (plain key→handler maps support ` +
+          `ROUTE_KEY / ENUM / COMMAND_TABLE only).`,
+      );
+  }
+}
+
+/** Build the strategy-appropriate DispatchRequest from the envelope. */
+function buildRequest<TSchema extends MailboxSchema>(
+  strategy: DispatchStrategyType,
+  envelope: ActorEnvelope<TSchema>,
+  extractors: DispatchKeyExtractors<TSchema> | undefined,
+) {
+  const input = extractors?.inputOf ? extractors.inputOf(envelope) : envelope.payload;
+  const routeKey = extractors?.routeKeyOf
+    ? extractors.routeKeyOf(envelope)
+    : envelope.tag;
+  const path = extractors?.pathOf ? extractors.pathOf(envelope) : envelope.tag;
+
+  switch (strategy) {
+    case DispatchStrategyType.CLASS:
+      return createClassDispatchRequest<void | Promise<void>>(input);
+    case DispatchStrategyType.ROUTE_KEY:
+      return createRouteKeyDispatchRequest<void | Promise<void>>(routeKey, input, false);
+    case DispatchStrategyType.ENUM:
+      return createEnumDispatchRequest<void | Promise<void>>(
+        extractors?.enumOf ? extractors.enumOf(envelope) : envelope.tag,
+        input,
+      );
+    case DispatchStrategyType.ROUTE_KEY_TO_ENUM:
+      return createRouteKeyToEnumDispatchRequest<void | Promise<void>>(routeKey, input);
+    case DispatchStrategyType.COMMAND_TABLE:
+      return createCommandDispatchRequest<void | Promise<void>>(routeKey, input);
+    case DispatchStrategyType.PATH:
+      return createPathDispatchRequest<void | Promise<void>, unknown, unknown>({
+        runtime: undefined,
+        request: input,
+        path,
+      });
+    case DispatchStrategyType.ACTION_PATH:
+      return createActionPathDispatchRequest<void | Promise<void>, unknown, unknown, unknown>({
+        runtime: undefined,
+        request: input,
+        action: extractors?.actionOf ? extractors.actionOf(envelope) : undefined,
+        path,
+      });
+    default:
+      throw new Error(`createDispatchHandler: unknown strategy ${String(strategy)}`);
+  }
 }
 
 // ─── createDispatchHandler ───────────────────────────────────────────
 
 /**
- * Creates an ActorHandler that routes envelopes through dispatch routes.
- * Falls back to `defaultHandler` for tags not covered by any route.
+ * Creates an ActorHandler that resolves an envelope to a sub-handler via one of
+ * the 7 depa-processor dispatch strategies (opt-in, per-handler — DX form C / B2).
+ *
+ * Object-param signature: `{ strategy, routes, defaultHandler?, extractors? }`.
+ *
+ * Composability:
+ *  - slot the returned handler under a `tag` in `ActorDef.handlers` → `tag` overlay
+ *    (first-level) + `strategy` (second-level), the two axes are orthogonal.
+ *  - the resolved sub-handler may itself be a `createPipelineHandler(...)` result,
+ *    so dispatch and pipeline nest freely.
+ *
+ * No declarative `ActorDef.dispatch` field and no global feature flag / enableXxx
+ * API exist — enabling rich dispatch is expressed purely by import + composition.
  */
 export function createDispatchHandler<
   TRuntime,
   TSchema extends MailboxSchema,
   TState,
 >(
-  routes: DispatchRoute<TRuntime, TSchema, TState>[],
-  defaultHandler?: ActorHandler<TRuntime, TSchema, TState>,
+  params: CreateDispatchHandlerParams<TRuntime, TSchema, TState>,
 ): ActorHandler<TRuntime, TSchema, TState> {
-  // Build tag → route index for O(1) lookup
-  const tagIndex = new Map<string, DispatchRoute<TRuntime, TSchema, TState>>();
-  for (const route of routes) {
-    for (const tag of route.tags) {
-      tagIndex.set(tag, route);
-    }
-  }
+  const { strategy, routes, defaultHandler, extractors } = params;
 
   return async (self, envelope) => {
-    const route = tagIndex.get(envelope.tag);
-
-    if (route) {
-      const key = route.resolveKey(envelope);
-      const handler = route.routes[key];
-      if (handler) {
-        await handler(self, envelope);
-      } else if (route.fallback) {
-        await route.fallback(self, envelope, key);
-      }
-    } else if (defaultHandler) {
+    const config = isStrategyConfig(routes)
+      ? routes
+      : buildKeyBasedConfig(strategy, routes, self, envelope);
+
+    const engine = new DispatchEngine<void | Promise<void>>();
+    engine.registerStrategy(config);
+
+    const request = buildRequest(strategy, envelope, extractors);
+    const result = await engine.dispatch(request);
+
+    if (result.isHandled()) {
+      // Await the sub-handler's (possibly async) side effect.
+      await result.getResult();
+      return;
+    }
+
+    if (defaultHandler) {
       await defaultHandler(self, envelope);
     }
   };