@iworkflow/core 0.6.1 → 0.8.0

package/README.md

@@ -33,11 +33,11 @@ try {
 }
 ```
 
-Ещё: `ctx.startChild` (без ожидания), `ChildOptions.timeoutMs` и `onExisting`, `ctx.startedAt`,
-`ctx.parentId`, `AppDefinition.pools`, `handle.describe()` и `handle.terminate()`.
+Ещё: `ctx.startChild` (без ожидания, `reuseClosedId`), `ChildOptions.timeoutMs` и `onExisting`, `ctx.startedAt`,
+`ctx.parentId`, `AppDefinition.pools` и `maxConcurrentSteps`, `StartOptions.onExisting`, `handle.describe()` и `handle.terminate()`.
 
 Приоритет: `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

@@ -1,3 +1,4 @@
+import type { AppDefinition } from "./types";
 /**
  * Отказ, который бросает код шага или процесса. `type` — код для разбора (`FlowError.type`),
  * `nonRetryable` — шаг не повторять. Отказ процесса не повторяется никогда.
@@ -47,3 +48,7 @@ export declare const isFlowError: (e: unknown) => e is FlowError;
 /** Приоритет порта — целое 1…5 (1 — первым); иное отвергается одинаково на обоих движках. */
 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;
@@ -55,6 +60,29 @@ function checkPriority(p) {
   return p;
 }
 var DEFAULT_PRIORITY = 3;
+function checkLimits(def) {
+  const check = (name, n) => {
+    if (n !== undefined && (!Number.isInteger(n) || n < 1))
+      throw new Error(`${def.app}: ${name} = ${n}, нужно целое ≥ 1`);
+  };
+  check("maxConcurrentSteps", def.maxConcurrentSteps);
+  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();
@@ -83,12 +111,16 @@ export {
   DEFAULT_PRIORITY,
   Failure,
   FlowError,
+  checkLimits,
   checkPriority,
   exitSignal,
   heartbeat,
   isFlowError,
   lastHeartbeat,
   nonRetryable,
+  plainAttrs,
   stepAttempt,
-  stepScope
+  stepInfo,
+  stepScope,
+  stepSignal
 };

package/dist/types.d.ts

@@ -34,6 +34,13 @@ export interface ChildOptions {
      */
     onExisting?: "reject";
 }
+export interface StartChildOptions extends Omit<ChildOptions, "onExisting"> {
+    /**
+     * Id завершённого процесса — новый запуск под ним (окно сбора на чат). Только Temporal: DBOS id не
+     * переиспользует — already-started. Идущий процесс с этим id — already-started всегда.
+     */
+    reuseClosedId?: boolean;
+}
 /** Дочерний процесс, запущенный без ожидания. */
 export interface ChildHandle<T> {
     id: string;
@@ -58,12 +65,14 @@ export interface FlowContext {
      * Дочерний процесс без ожидания: живёт и после завершения родителя. Id уже идёт или занят —
      * FlowError reason "already-started".
      */
-    startChild<T>(target: FlowRef, args: unknown[], opts: Omit<ChildOptions, "onExisting">): Promise<ChildHandle<T>>;
+    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>;
     /**
@@ -92,6 +101,8 @@ export interface AppDefinition {
     patches?: string[];
     /** Пулы шагов: имя → сколько шагов пула идёт одновременно в этом процессе. */
     pools?: Record<string, number>;
+    /** Сколько шагов вне пулов идёт одновременно в этом процессе (бережёт пул БД). Не задано — у DBOS без предела, у Temporal 100. */
+    maxConcurrentSteps?: number;
 }
 export type FlowStatus = "running" | "completed" | "failed" | "terminated" | "timed-out";
 export interface FlowDescription {
@@ -124,16 +135,23 @@ export interface StartOptions {
     timeoutMs?: number;
     /** 1 — первым, 5 — последним; шаги процесса наследуют его. */
     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 {
-    /** Id уже идёт — handle к нему. timeoutMs — срок процесса. */
+    /** Id уже идёт — handle к нему (с onExisting "reject" — already-started). timeoutMs — срок процесса. */
     start<T>(target: FlowRef, args: unknown[], opts: StartOptions): Promise<FlowHandle<T>>;
     /**
      * Сигнал процессу; нет идущего с этим id — запустить и отдать сигнал ему. Temporal заводит новый
      * запуск и под id завершённого; DBOS id не переиспользует — сигнал уйдёт завершённому и пропадёт.
      */
-    signalWithStart<T>(target: FlowRef, args: unknown[], opts: StartOptions, 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.6.1",
+  "version": "0.8.0",
   "description": "Engine-neutral durable workflow port: flows, steps, child workflows, signals, queries, patches, heartbeat",
   "keywords": [
     "workflow",

package/src/errors.ts

@@ -1,4 +1,5 @@
 // Ошибки порта: одинаковые на обоих движках. Без импортов рантайма — их читает песочница Temporal.
+import type { AppDefinition } from "./types";
 
 /**
  * Отказ, который бросает код шага или процесса. `type` — код для разбора (`FlowError.type`),
@@ -75,3 +76,29 @@ export function checkPriority(p: number | undefined): number | undefined {
 }
 
 export const DEFAULT_PRIORITY = 3;
+
+/** Пределы модуля — целые ≥ 1: иначе DBOS молча вешает шаги, а Temporal падает на старте. */
+export function checkLimits(def: AppDefinition): void {
+  const check = (name: string, n: number | undefined) => {
+    if (n !== undefined && (!Number.isInteger(n) || n < 1)) throw new Error(`${def.app}: ${name} = ${n}, нужно целое ≥ 1`);
+  };
+  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

@@ -40,6 +40,14 @@ export interface ChildOptions {
   onExisting?: "reject";
 }
 
+export interface StartChildOptions extends Omit<ChildOptions, "onExisting"> {
+  /**
+   * Id завершённого процесса — новый запуск под ним (окно сбора на чат). Только Temporal: DBOS id не
+   * переиспользует — already-started. Идущий процесс с этим id — already-started всегда.
+   */
+  reuseClosedId?: boolean;
+}
+
 /** Дочерний процесс, запущенный без ожидания. */
 export interface ChildHandle<T> {
   id: string;
@@ -65,12 +73,14 @@ export interface FlowContext {
    * Дочерний процесс без ожидания: живёт и после завершения родителя. Id уже идёт или занят —
    * FlowError reason "already-started".
    */
-  startChild<T>(target: FlowRef, args: unknown[], opts: Omit<ChildOptions, "onExisting">): Promise<ChildHandle<T>>;
+  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>;
   /**
@@ -102,6 +112,8 @@ export interface AppDefinition {
   patches?: string[];
   /** Пулы шагов: имя → сколько шагов пула идёт одновременно в этом процессе. */
   pools?: Record<string, number>;
+  /** Сколько шагов вне пулов идёт одновременно в этом процессе (бережёт пул БД). Не задано — у DBOS без предела, у Temporal 100. */
+  maxConcurrentSteps?: number;
 }
 
 export type FlowStatus = "running" | "completed" | "failed" | "terminated" | "timed-out";
@@ -139,17 +151,24 @@ export interface StartOptions {
   timeoutMs?: number;
   /** 1 — первым, 5 — последним; шаги процесса наследуют его. */
   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 {
-  /** Id уже идёт — handle к нему. timeoutMs — срок процесса. */
+  /** Id уже идёт — handle к нему (с onExisting "reject" — already-started). timeoutMs — срок процесса. */
   start<T>(target: FlowRef, args: unknown[], opts: StartOptions): Promise<FlowHandle<T>>;
   /**
    * Сигнал процессу; нет идущего с этим id — запустить и отдать сигнал ему. Temporal заводит новый
    * запуск и под id завершённого; DBOS id не переиспользует — сигнал уйдёт завершённому и пропадёт.
    */
-  signalWithStart<T>(target: FlowRef, args: unknown[], opts: StartOptions, 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>;