@iworkflow/core 0.7.0 → 0.8.0

package/README.md

@@ -38,6 +38,6 @@ try {
 
 Приоритет: `client.start(..., { priority })` (1 — первым, 5 — последним) → `ctx.priority`; шаги и
 дети его наследуют, `StepOptions.priority` — свой. Срок повтора из отказа: `new Failure(msg, { type,
-retryAfterMs })`; `benign: true` — штатный отказ, Temporal не пишет его ошибкой. Номер попытки в шаге — `stepAttempt()`. Время в процессе — `await ctx.now()`.
+retryAfterMs })`; `benign: true` — штатный отказ, Temporal не пишет его ошибкой. Номер попытки в шаге — `stepAttempt()`, процесс и запуск — `stepInfo()`, отмена попытки — `stepSignal()`. Журнал без повторов — `ctx.log`. Время в процессе — `await ctx.now()`.
 `client.signalWithStart(target, args, opts, topic, value)` — сигнал идущему или запуск с сигналом.
 Контракт обоих движков — `lab/test/contract.test.ts` репозитория.

package/dist/errors.d.ts

@@ -50,3 +50,5 @@ export declare function checkPriority(p: number | undefined): number | undefined
 export declare const DEFAULT_PRIORITY = 3;
 /** Пределы модуля — целые ≥ 1: иначе DBOS молча вешает шаги, а Temporal падает на старте. */
 export declare function checkLimits(def: AppDefinition): void;
+/** attrs журнала — в JSON-данные: BigInt строкой, Error — name, message и свои поля; непереносимый ключ выпадает один. */
+export declare function plainAttrs(attrs: Record<string, unknown> | undefined): Record<string, unknown> | undefined;

package/dist/heartbeat.d.ts

@@ -3,6 +3,14 @@ export interface StepRuntime {
     lastHeartbeat(): Promise<unknown>;
     /** Номер попытки шага, с 1. */
     attempt(): number;
+    /** Процесс шага, запуск и шаг в нём. */
+    info(): {
+        workflowId: string;
+        runId: string;
+        stepId: string;
+    };
+    /** Отмена попытки. Temporal — срок и отмена процесса, узнаёт через heartbeat; DBOS — только срок попытки. */
+    signal(): AbortSignal;
 }
 /** Область шага: какой рантайм у шага, что идёт сейчас. Самый внутренний шаг — свой, без угадывания движка. */
 export interface StepScope {
@@ -20,3 +28,12 @@ export declare const heartbeat: (details?: unknown) => Promise<void>;
 export declare const lastHeartbeat: <T>() => Promise<T | undefined>;
 /** Номер попытки этого шага, с 1. DBOS считает заново после рестарта процесса, Temporal — нет. */
 export declare const stepAttempt: () => number;
+/** Ключ идемпотентности внешней записи — runId + stepId: id переиспользуется (reuseClosedId), runId нет. */
+export declare const stepInfo: () => {
+    workflowId: string;
+    runId: string;
+    stepId: string;
+    attempt: number;
+};
+/** Сигнал отмены попытки: передать в fetch и т. п.; aborted — итог попытки отброшен, не оборачивать в Failure. */
+export declare const stepSignal: () => AbortSignal;

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export * from "./types";
-export { heartbeat, lastHeartbeat, stepAttempt, stepScope, type StepRuntime, type StepScope } from "./heartbeat";
+export { heartbeat, lastHeartbeat, stepAttempt, stepInfo, stepScope, stepSignal, type StepRuntime, type StepScope } from "./heartbeat";
 export * from "./errors";
 export { exitSignal, type ExitSignal } from "./exit";

package/dist/index.js

@@ -3,15 +3,20 @@ var KEY = Symbol.for("@iworkflow/core.step-scope");
 function stepScope(make) {
   return globalThis[KEY] ??= make();
 }
-function current() {
+function current(name = "heartbeat") {
   const rt = globalThis[KEY]?.current();
   if (!rt)
-    throw new Error("heartbeat вне шага: шаг движка процесса сейчас не идёт");
+    throw new Error(`${name} вне шага: шаг движка процесса сейчас не идёт`);
   return rt;
 }
 var heartbeat = (details) => current().heartbeat(details);
 var lastHeartbeat = async () => await current().lastHeartbeat() ?? undefined;
-var stepAttempt = () => current().attempt();
+var stepAttempt = () => current("stepAttempt").attempt();
+var stepInfo = () => {
+  const rt = current("stepInfo");
+  return { ...rt.info(), attempt: rt.attempt() };
+};
+var stepSignal = () => current("stepSignal").signal();
 // src/errors.ts
 class Failure extends Error {
   type;
@@ -64,6 +69,20 @@ function checkLimits(def) {
   for (const [p, n] of Object.entries(def.pools ?? {}))
     check(`pools.${p}`, n);
 }
+function plainAttrs(attrs) {
+  if (!attrs)
+    return;
+  const plain = (_, v) => typeof v === "bigint" ? String(v) : v instanceof Error ? { ...v, name: v.name, message: v.message } : v;
+  const out = {};
+  for (const [k, v] of Object.entries(attrs)) {
+    try {
+      const json = JSON.stringify(v, plain);
+      if (json !== undefined)
+        out[k] = JSON.parse(json);
+    } catch {}
+  }
+  return out;
+}
 // src/exit.ts
 function exitSignal() {
   let d = Promise.withResolvers();
@@ -99,6 +118,9 @@ export {
   isFlowError,
   lastHeartbeat,
   nonRetryable,
+  plainAttrs,
   stepAttempt,
-  stepScope
+  stepInfo,
+  stepScope,
+  stepSignal
 };

package/dist/types.d.ts

@@ -67,10 +67,12 @@ export interface FlowContext {
      */
     startChild<T>(target: FlowRef, args: unknown[], opts: StartChildOptions): Promise<ChildHandle<T>>;
     sleep(ms: number): Promise<void>;
-    /** Ждать сигнал по теме; null — вышло время. Сигнал, пришедший раньше, не теряется. */
+    /** Ждать сигнал по теме; null — вышло время, при timeoutMs 0 — сигнала нет сейчас (Temporal: таймер 1 мс). Пришедший раньше не теряется. */
     recv<T>(topic: string, timeoutMs: number): Promise<T | null>;
     /** Сигнал другому процессу по id — в том числе в другом модуле. Процесса нет или он завершён — FlowError "not-found". */
     signal(workflowId: string, topic: string, value: unknown): Promise<void>;
+    /** Журнал из процесса: Temporal не повторяет строку при переигрывании, DBOS может повторить после рестарта. */
+    log(level: "info" | "warn" | "error", message: string, attrs?: Record<string, unknown>): Promise<void>;
     /** Опубликовать значение для query снаружи; читается и после завершения процесса. */
     setState(key: string, value: unknown): Promise<void>;
     /**
@@ -135,6 +137,11 @@ export interface StartOptions {
     priority?: number;
     /** Id уже занят (идёт или завершён; Temporal помнит завершённый в пределах хранения namespace) — FlowError "already-started". */
     onExisting?: "reject";
+    /**
+     * Отказ, только пока процесс идёт; завершённый id — новый запуск (ночные задачи с постоянным id).
+     * Включает onExisting "reject". Только Temporal: DBOS id не переиспользует — already-started.
+     */
+    reuseClosedId?: boolean;
 }
 /** Сторона вызывающего вне процесса (HTTP, CLI, тест). */
 export interface EngineClient {
@@ -144,7 +151,7 @@ export interface EngineClient {
      * Сигнал процессу; нет идущего с этим id — запустить и отдать сигнал ему. Temporal заводит новый
      * запуск и под id завершённого; DBOS id не переиспользует — сигнал уйдёт завершённому и пропадёт.
      */
-    signalWithStart<T>(target: FlowRef, args: unknown[], opts: Omit<StartOptions, "onExisting">, topic: string, value: unknown): Promise<FlowHandle<T>>;
+    signalWithStart<T>(target: FlowRef, args: unknown[], opts: Omit<StartOptions, "onExisting" | "reuseClosedId">, topic: string, value: unknown): Promise<FlowHandle<T>>;
     /** Уже запущенный процесс по id. */
     handle<T>(id: string): FlowHandle<T>;
     close(): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iworkflow/core",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Engine-neutral durable workflow port: flows, steps, child workflows, signals, queries, patches, heartbeat",
   "keywords": [
     "workflow",

package/src/errors.ts

@@ -85,3 +85,20 @@ export function checkLimits(def: AppDefinition): void {
   check("maxConcurrentSteps", def.maxConcurrentSteps);
   for (const [p, n] of Object.entries(def.pools ?? {})) check(`pools.${p}`, n);
 }
+
+/** attrs журнала — в JSON-данные: BigInt строкой, Error — name, message и свои поля; непереносимый ключ выпадает один. */
+export function plainAttrs(attrs: Record<string, unknown> | undefined): Record<string, unknown> | undefined {
+  if (!attrs) return undefined;
+  const plain = (_: string, v: unknown) =>
+    typeof v === "bigint" ? String(v) : v instanceof Error ? { ...v, name: v.name, message: v.message } : v;
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(attrs)) {
+    try {
+      const json = JSON.stringify(v, plain);
+      if (json !== undefined) out[k] = JSON.parse(json);
+    } catch {
+      // цикл или бросающий геттер — только этот ключ
+    }
+  }
+  return out;
+}

package/src/heartbeat.ts

@@ -6,6 +6,10 @@ export interface StepRuntime {
   lastHeartbeat(): Promise<unknown>;
   /** Номер попытки шага, с 1. */
   attempt(): number;
+  /** Процесс шага, запуск и шаг в нём. */
+  info(): { workflowId: string; runId: string; stepId: string };
+  /** Отмена попытки. Temporal — срок и отмена процесса, узнаёт через heartbeat; DBOS — только срок попытки. */
+  signal(): AbortSignal;
 }
 
 /** Область шага: какой рантайм у шага, что идёт сейчас. Самый внутренний шаг — свой, без угадывания движка. */
@@ -25,9 +29,9 @@ export function stepScope(make: () => StepScope): StepScope {
   return ((globalThis as Slot)[KEY] ??= make());
 }
 
-function current(): StepRuntime {
+function current(name = "heartbeat"): StepRuntime {
   const rt = (globalThis as Slot)[KEY]?.current();
-  if (!rt) throw new Error("heartbeat вне шага: шаг движка процесса сейчас не идёт");
+  if (!rt) throw new Error(`${name} вне шага: шаг движка процесса сейчас не идёт`);
   return rt;
 }
 
@@ -39,4 +43,14 @@ export const lastHeartbeat = async <T>(): Promise<T | undefined> =>
   ((await current().lastHeartbeat()) ?? undefined) as T | undefined;
 
 /** Номер попытки этого шага, с 1. DBOS считает заново после рестарта процесса, Temporal — нет. */
-export const stepAttempt = (): number => current().attempt();
+export const stepAttempt = (): number => current("stepAttempt").attempt();
+
+/** Ключ идемпотентности внешней записи — runId + stepId: id переиспользуется (reuseClosedId), runId нет. */
+// У DBOS runId = workflowId: id не переиспользуется.
+export const stepInfo = (): { workflowId: string; runId: string; stepId: string; attempt: number } => {
+  const rt = current("stepInfo");
+  return { ...rt.info(), attempt: rt.attempt() };
+};
+
+/** Сигнал отмены попытки: передать в fetch и т. п.; aborted — итог попытки отброшен, не оборачивать в Failure. */
+export const stepSignal = (): AbortSignal => current("stepSignal").signal();

package/src/index.ts

@@ -1,4 +1,4 @@
 export * from "./types";
-export { heartbeat, lastHeartbeat, stepAttempt, stepScope, type StepRuntime, type StepScope } from "./heartbeat";
+export { heartbeat, lastHeartbeat, stepAttempt, stepInfo, stepScope, stepSignal, type StepRuntime, type StepScope } from "./heartbeat";
 export * from "./errors";
 export { exitSignal, type ExitSignal } from "./exit";

package/src/types.ts

@@ -75,10 +75,12 @@ export interface FlowContext {
    */
   startChild<T>(target: FlowRef, args: unknown[], opts: StartChildOptions): Promise<ChildHandle<T>>;
   sleep(ms: number): Promise<void>;
-  /** Ждать сигнал по теме; null — вышло время. Сигнал, пришедший раньше, не теряется. */
+  /** Ждать сигнал по теме; null — вышло время, при timeoutMs 0 — сигнала нет сейчас (Temporal: таймер 1 мс). Пришедший раньше не теряется. */
   recv<T>(topic: string, timeoutMs: number): Promise<T | null>;
   /** Сигнал другому процессу по id — в том числе в другом модуле. Процесса нет или он завершён — FlowError "not-found". */
   signal(workflowId: string, topic: string, value: unknown): Promise<void>;
+  /** Журнал из процесса: Temporal не повторяет строку при переигрывании, DBOS может повторить после рестарта. */
+  log(level: "info" | "warn" | "error", message: string, attrs?: Record<string, unknown>): Promise<void>;
   /** Опубликовать значение для query снаружи; читается и после завершения процесса. */
   setState(key: string, value: unknown): Promise<void>;
   /**
@@ -151,6 +153,11 @@ export interface StartOptions {
   priority?: number;
   /** Id уже занят (идёт или завершён; Temporal помнит завершённый в пределах хранения namespace) — FlowError "already-started". */
   onExisting?: "reject";
+  /**
+   * Отказ, только пока процесс идёт; завершённый id — новый запуск (ночные задачи с постоянным id).
+   * Включает onExisting "reject". Только Temporal: DBOS id не переиспользует — already-started.
+   */
+  reuseClosedId?: boolean;
 }
 
 /** Сторона вызывающего вне процесса (HTTP, CLI, тест). */
@@ -161,7 +168,7 @@ export interface EngineClient {
    * Сигнал процессу; нет идущего с этим id — запустить и отдать сигнал ему. Temporal заводит новый
    * запуск и под id завершённого; DBOS id не переиспользует — сигнал уйдёт завершённому и пропадёт.
    */
-  signalWithStart<T>(target: FlowRef, args: unknown[], opts: Omit<StartOptions, "onExisting">, topic: string, value: unknown): Promise<FlowHandle<T>>;
+  signalWithStart<T>(target: FlowRef, args: unknown[], opts: Omit<StartOptions, "onExisting" | "reuseClosedId">, topic: string, value: unknown): Promise<FlowHandle<T>>;
   /** Уже запущенный процесс по id. */
   handle<T>(id: string): FlowHandle<T>;
   close(): Promise<void>;