@iworkflow/temporal 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,10 @@
-# Temporary Holding Version
+# @iworkflow/temporal
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Temporal для `@iworkflow/core`. Peer: `@temporalio/{client,worker,workflow,activity}` ^1.24.
+
+- `temporalRuntime(workflowsPath).start(def)` — воркер на task queue `def.app`.
+- `temporalClient()` — старт, сигнал, query по id.
+- `@iworkflow/temporal/workflow` — только для входа песочницы модуля:
+  `export const outreach = temporalFlow(flows.outreach, ["send-twice"])`.
+
+Переменные: `TEMPORAL_URL` (по умолчанию `127.0.0.1:17233`), `TEMPORAL_NAMESPACE`.

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@iworkflow/temporal",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Temporal adapter for @iworkflow/core",
+  "keywords": [
+    "workflow",
+    "temporal"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iconicompany/iworkflow.git",
+    "directory": "packages/temporal"
+  },
+  "files": [
+    "src"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./src/index.ts",
+    "./workflow": "./src/workflow.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "type-check": "tsc --noEmit -p tsconfig.json",
+    "test": "bun test"
+  },
+  "dependencies": {
+    "@iworkflow/core": "^0.1.0"
+  },
+  "peerDependencies": {
+    "@temporalio/activity": "^1.24.0",
+    "@temporalio/client": "^1.24.0",
+    "@temporalio/worker": "^1.24.0",
+    "@temporalio/workflow": "^1.24.0"
+  },
+  "devDependencies": {
+    "@temporalio/activity": "^1.24.0",
+    "@temporalio/client": "^1.24.0",
+    "@temporalio/worker": "^1.24.0",
+    "@temporalio/workflow": "^1.24.0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,66 @@
+// Temporal: воркер на очереди модуля (task queue = имя модуля), клиент — по имени процесса.
+import { Client, Connection, type WorkflowHandle } from "@temporalio/client";
+import { Context } from "@temporalio/activity";
+import { NativeConnection, Worker } from "@temporalio/worker";
+import { bindStepRuntime, type AppDefinition, type EngineClient, type EngineRuntime, type FlowHandle } from "@iworkflow/core";
+
+// Те же имена, что в workflow.ts: его нельзя импортировать вне песочницы.
+const SIGNAL = "iwf.signal";
+const QUERY = "iwf.query";
+
+const wrap = <T>(h: WorkflowHandle): FlowHandle<T> => ({
+  id: h.workflowId,
+  result: () => h.result(),
+  signal: (topic, value) => h.signal(SIGNAL, { topic, value }),
+  query: async <V>(key: string) => ((await h.query(QUERY, key)) ?? undefined) as V | undefined,
+});
+
+const address = () => process.env.TEMPORAL_URL ?? "127.0.0.1:17233";
+const namespace = () => process.env.TEMPORAL_NAMESPACE ?? "default";
+
+/** workflowsPath — вход песочницы модуля: temporalFlow(...) на каждый процесс, имя экспорта = имя процесса. */
+export function temporalRuntime(workflowsPath: string): EngineRuntime {
+  let worker: Worker | undefined;
+  let running: Promise<void> | undefined;
+  let conn: NativeConnection | undefined;
+  return {
+    async start(def: AppDefinition) {
+      bindStepRuntime({
+        heartbeat: async (details) => Context.current().heartbeat(details),
+        lastHeartbeat: async () => Context.current().info.heartbeatDetails,
+      });
+      conn = await NativeConnection.connect({ address: address() });
+      worker = await Worker.create({
+        connection: conn,
+        namespace: namespace(),
+        taskQueue: def.app,
+        workflowsPath,
+        activities: def.activities,
+      });
+      running = worker.run();
+    },
+    async stop() {
+      worker?.shutdown();
+      await running;
+      await conn?.close();
+    },
+  };
+}
+
+export async function temporalClient(): Promise<EngineClient> {
+  const connection = await Connection.connect({ address: address() });
+  const client = new Client({ connection, namespace: namespace() });
+  return {
+    async start(target, args, opts) {
+      const h = await client.workflow.start(target.flow, {
+        taskQueue: target.app,
+        workflowId: opts.id,
+        args,
+        workflowIdConflictPolicy: "USE_EXISTING",
+      });
+      return wrap(h);
+    },
+    handle: (id) => wrap(client.workflow.getHandle(id)),
+    close: () => connection.close(),
+  };
+}

package/src/workflow.ts

@@ -0,0 +1,76 @@
+// Обёртка процесса для песочницы Temporal: FlowContext поверх proxyActivities и executeChild.
+// Сигналы и query — по одному обработчику на всё: тема и ключ едут в данных.
+// Импортируется только из входа песочницы модуля: `@iworkflow/temporal/workflow`.
+import {
+  condition,
+  defineQuery,
+  defineSignal,
+  deprecatePatch,
+  executeChild,
+  getExternalWorkflowHandle,
+  patched,
+  proxyActivities,
+  setHandler,
+  sleep,
+  workflowInfo,
+} from "@temporalio/workflow";
+
+import type { Flow, FlowContext, StepOptions } from "@iworkflow/core";
+
+export const SIGNAL = "iwf.signal";
+export const QUERY = "iwf.query";
+const signalDef = defineSignal<[{ topic: string; value: unknown }]>(SIGNAL);
+const queryDef = defineQuery<unknown, [string]>(QUERY);
+
+const proxies = new Map<string, Record<string, (...a: unknown[]) => Promise<unknown>>>();
+
+function activitiesWith(opts: StepOptions = {}) {
+  const key = `${opts.attempts ?? 3}/${opts.timeoutMs ?? 60_000}/${opts.heartbeatTimeoutMs ?? 0}`;
+  let p = proxies.get(key);
+  if (!p) {
+    p = proxyActivities({
+      startToCloseTimeout: opts.timeoutMs ?? 60_000,
+      ...(opts.heartbeatTimeoutMs ? { heartbeatTimeout: opts.heartbeatTimeoutMs } : {}),
+      retry: { maximumAttempts: opts.attempts ?? 3, initialInterval: "200 ms", backoffCoefficient: 1 },
+    });
+    proxies.set(key, p);
+  }
+  return p;
+}
+
+/** patches — как AppDefinition.patches: необъявленный id — ошибка, как у DBOS. */
+export function temporalFlow(flow: Flow, patches: string[] = []) {
+  return async (...args: unknown[]) => {
+    // Буфер по темам: сигнал до recv ждёт в очереди, как в DBOS.
+    const inbox = new Map<string, unknown[]>();
+    const state = new Map<string, unknown>();
+    setHandler(signalDef, ({ topic, value }) => {
+      const q = inbox.get(topic) ?? [];
+      q.push(value);
+      inbox.set(topic, q);
+    });
+    setHandler(queryDef, (key) => state.get(key));
+
+    const ctx: FlowContext = {
+      workflowId: workflowInfo().workflowId,
+      step: (name, stepArgs, opts) => activitiesWith(opts)[name]!(...stepArgs) as Promise<never>,
+      child: (target, childArgs, opts) =>
+        executeChild(target.flow, { taskQueue: target.app, workflowId: opts.id, args: childArgs }),
+      sleep: (ms) => sleep(ms),
+      async recv<T>(topic: string, timeoutMs: number) {
+        const ready = await condition(() => (inbox.get(topic)?.length ?? 0) > 0, timeoutMs);
+        return ready ? (inbox.get(topic)!.shift() as T) : null;
+      },
+      signal: (workflowId, topic, value) => getExternalWorkflowHandle(workflowId).signal(signalDef, { topic, value }),
+      async setState(key, value) {
+        state.set(key, value);
+      },
+      patched: async (id) => {
+        if (!patches.includes(id)) throw new Error(`патч "${id}" не объявлен в patches процесса`);
+        return patched(id);
+      },
+      deprecatePatch: async (id) => deprecatePatch(id),
+    };
+    return flow(ctx, ...args);
+  };
+}