@iworkflow/core 0.3.0 → 0.5.0

package/README.md

@@ -33,4 +33,9 @@ try {
 
 Ещё: `ctx.startChild` (без ожидания), `ChildOptions.timeoutMs` и `onExisting`, `ctx.startedAt`,
 `ctx.parentId`, `AppDefinition.pools`, `handle.describe()` и `handle.terminate()`.
+
+Приоритет: `client.start(..., { priority })` (1 — первым, 5 — последним) → `ctx.priority`; шаги и
+дети его наследуют, `StepOptions.priority` — свой. Срок повтора из отказа: `new Failure(msg, { type,
+retryAfterMs })`. Номер попытки в шаге — `stepAttempt()`. Время в процессе — `await ctx.now()`.
+`client.signalWithStart(target, args, opts, topic, value)` — сигнал идущему или запуск с сигналом.
 Контракт обоих движков — `lab/test/contract.test.ts` репозитория.

package/dist/errors.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Отказ, который бросает код шага или процесса. `type` — код для разбора (`FlowError.type`),
+ * `nonRetryable` — шаг не повторять. Отказ процесса не повторяется никогда.
+ */
+export declare class Failure extends Error {
+    readonly type: string;
+    readonly details?: unknown;
+    readonly nonRetryable: boolean;
+    /** Следующая попытка шага не раньше чем через столько мс (FLOOD_WAIT): вместо паузы из StepOptions. */
+    readonly retryAfterMs?: number;
+    constructor(message: string, opts: {
+        type: string;
+        details?: unknown;
+        nonRetryable?: boolean;
+        retryAfterMs?: number;
+    });
+}
+/** Отказ без повтора: `throw nonRetryable("нет такой фазы", "UnknownPhase")`. */
+export declare const nonRetryable: (message: string, type: string, details?: unknown) => Failure;
+/**
+ * - failed — шаг или процесс упал; `type` — тип отказа (`Failure.type` или имя класса ошибки).
+ * - timeout — вышел срок: попытки шага (`timeoutMs`), шага целиком (`totalTimeoutMs`) или процесса.
+ * - terminated — процесс прерван снаружи (`EngineClient.terminate`).
+ * - already-started — процесс с этим id уже есть (`startChild`, `onExisting: "reject"`).
+ * - not-found — процесса с этим id нет или он завершён (`signal`, `describe`).
+ */
+export type FlowErrorReason = "failed" | "timeout" | "terminated" | "already-started" | "not-found";
+/** Что бросает порт: `ctx.step`, `ctx.child`, `ctx.signal`, `handle.result()`, `client.describe`. */
+export declare class FlowError extends Error {
+    readonly reason: FlowErrorReason;
+    readonly type?: string;
+    readonly details?: unknown;
+    /** Шаг упал на последней разрешённой попытке, а не остановлен `nonRetryable`. */
+    readonly exhausted: boolean;
+    constructor(message: string, opts: {
+        reason: FlowErrorReason;
+        type?: string;
+        details?: unknown;
+        exhausted?: boolean;
+    });
+}
+/** FlowError по признакам, а не по классу: класс теряется при сериализации в DBOS. */
+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;

package/dist/exit.d.ts

@@ -0,0 +1,8 @@
+export interface ExitSignal {
+    /** Перед start: прошлый цикл завершён — новое обещание, иначе то же. */
+    arm(): void;
+    resolve(): void;
+    reject(e: unknown): void;
+    promise(): Promise<void>;
+}
+export declare function exitSignal(): ExitSignal;

package/dist/heartbeat.d.ts

@@ -0,0 +1,13 @@
+export interface StepRuntime {
+    heartbeat(details?: unknown): Promise<void>;
+    lastHeartbeat(): Promise<unknown>;
+    /** Номер попытки шага, с 1. */
+    attempt(): number;
+}
+export declare function bindStepRuntime(rt: StepRuntime): void;
+/** Отметить, что шаг жив, и сохранить прогресс. */
+export declare const heartbeat: (details?: unknown) => Promise<void>;
+/** Прогресс прошлой попытки этого шага; undefined — первая попытка или прогресса не было. */
+export declare const lastHeartbeat: <T>() => Promise<T | undefined>;
+/** Номер попытки этого шага, с 1. DBOS считает заново после рестарта процесса, Temporal — нет. */
+export declare const stepAttempt: () => number;

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,92 @@
+// src/heartbeat.ts
+var KEY = Symbol.for("@iworkflow/core.step-runtime");
+function bindStepRuntime(rt) {
+  globalThis[KEY] = rt;
+}
+function current() {
+  const rt = globalThis[KEY];
+  if (!rt)
+    throw new Error("heartbeat вне шага: движок процесса не запущен в этом процессе");
+  return rt;
+}
+var heartbeat = (details) => current().heartbeat(details);
+var lastHeartbeat = async () => await current().lastHeartbeat() ?? undefined;
+var stepAttempt = () => current().attempt();
+// src/errors.ts
+class Failure extends Error {
+  type;
+  details;
+  nonRetryable;
+  retryAfterMs;
+  constructor(message, opts) {
+    super(message);
+    this.name = "Failure";
+    this.type = opts.type;
+    this.details = opts.details;
+    this.nonRetryable = opts.nonRetryable ?? false;
+    const after = opts.retryAfterMs;
+    this.retryAfterMs = after !== undefined && Number.isFinite(after) && after >= 0 ? after : undefined;
+  }
+}
+var nonRetryable = (message, type, details) => new Failure(message, { type, details, nonRetryable: true });
+
+class FlowError extends Error {
+  reason;
+  type;
+  details;
+  exhausted;
+  constructor(message, opts) {
+    super(message);
+    this.name = "FlowError";
+    this.reason = opts.reason;
+    this.type = opts.type;
+    this.details = opts.details;
+    this.exhausted = opts.exhausted ?? false;
+  }
+}
+var isFlowError = (e) => e instanceof FlowError || e instanceof Error && e.name === "FlowError" && typeof e.reason === "string";
+function checkPriority(p) {
+  if (p === undefined)
+    return;
+  if (!Number.isInteger(p) || p < 1 || p > 5)
+    throw new Failure(`приоритет ${p}: нужно целое от 1 до 5`, { type: "InvalidPriority", nonRetryable: true });
+  return p;
+}
+var DEFAULT_PRIORITY = 3;
+// src/exit.ts
+function exitSignal() {
+  let d = Promise.withResolvers();
+  let settled = false;
+  d.promise.catch(() => {});
+  const settle = (f) => {
+    if (settled)
+      return;
+    settled = true;
+    f();
+  };
+  return {
+    arm() {
+      if (!settled)
+        return;
+      d = Promise.withResolvers();
+      d.promise.catch(() => {});
+      settled = false;
+    },
+    resolve: () => settle(() => d.resolve()),
+    reject: (e) => settle(() => d.reject(e)),
+    promise: () => d.promise
+  };
+}
+export {
+  DEFAULT_PRIORITY,
+  Failure,
+  FlowError,
+  bindStepRuntime,
+  checkPriority,
+  exitSignal,
+  heartbeat,
+  isFlowError,
+  lastHeartbeat,
+  nonRetryable,
+  stepAttempt
+};

package/dist/types.d.ts

@@ -0,0 +1,141 @@
+export type Activity = (...args: any[]) => Promise<unknown>;
+export interface StepOptions {
+    /** Попыток всего, включая первую. По умолчанию 3; Infinity — до totalTimeoutMs или срока процесса. */
+    attempts?: number;
+    /** Предел одной попытки. По умолчанию 60 с. DBOS не ограничивает: шаг повторяется после рестарта. */
+    timeoutMs?: number;
+    /** Шаг без heartbeat дольше этого — попытка мёртвой, повтор. Только Temporal; DBOS ловит смерть рестартом. */
+    heartbeatTimeoutMs?: number;
+    /** Пауза перед вторым повтором. По умолчанию 200 мс. */
+    retryIntervalMs?: number;
+    /** Множитель паузы для следующих повторов. По умолчанию 1. */
+    backoff?: number;
+    /** Предел паузы между повторами. */
+    maxRetryIntervalMs?: number;
+    /**
+     * Срок шага со всеми повторами; вышел — FlowError reason "timeout". Temporal режет и идущую
+     * попытку, DBOS только не начинает новую: идущую ограничивает timeoutMs.
+     */
+    totalTimeoutMs?: number;
+    /** Типы отказов (`Failure.type` или имя класса ошибки), которые не повторять. */
+    nonRetryableTypes?: string[];
+    /** Пул шага из AppDefinition.pools — со своим пределом одновременных шагов. */
+    pool?: string;
+    /** Приоритет шага в очереди пула: 1 — первым, 5 — последним. По умолчанию — приоритет процесса. */
+    priority?: number;
+}
+export interface ChildOptions {
+    id: string;
+    /** Срок процесса; вышел — FlowError reason "timeout". */
+    timeoutMs?: number;
+    /**
+     * Id уже занят (процесс идёт или завершён): "reject" — FlowError reason "already-started".
+     * Без него движки расходятся: Temporal запускает завершённый id заново, DBOS отдаёт его результат.
+     */
+    onExisting?: "reject";
+}
+/** Дочерний процесс, запущенный без ожидания. */
+export interface ChildHandle<T> {
+    id: string;
+    result(): Promise<T>;
+}
+/** Что видит код процесса. Детерминирован: время, случайность, ввод-вывод — только через step. */
+export interface FlowContext {
+    readonly workflowId: string;
+    /** Id родительского процесса; undefined — процесс запущен снаружи. */
+    readonly parentId: string | undefined;
+    /** Время запуска процесса: одно и то же при каждом переигрывании. */
+    readonly startedAt: Date;
+    /** Приоритет процесса из start: 1 — первым, 5 — последним; не задан — 3. */
+    readonly priority: number;
+    /** Текущее время, мс: одно и то же при переигрывании. Date.now() в процессе DBOS не детерминирован. */
+    now(): Promise<number>;
+    /** Шаг упал после повторов — FlowError reason "failed" или "timeout". */
+    step<T>(name: string, args: unknown[], opts?: StepOptions): Promise<T>;
+    /** Дочерний процесс в другом модуле: его очередь, его процесс, ждём результат. */
+    child<T>(target: FlowRef, args: unknown[], opts: ChildOptions): Promise<T>;
+    /**
+     * Дочерний процесс без ожидания: живёт и после завершения родителя. Id уже идёт или занят —
+     * FlowError reason "already-started".
+     */
+    startChild<T>(target: FlowRef, args: unknown[], opts: Omit<ChildOptions, "onExisting">): Promise<ChildHandle<T>>;
+    sleep(ms: number): Promise<void>;
+    /** Ждать сигнал по теме; null — вышло время. Сигнал, пришедший раньше, не теряется. */
+    recv<T>(topic: string, timeoutMs: number): Promise<T | null>;
+    /** Сигнал другому процессу по id — в том числе в другом модуле. Процесса нет или он завершён — FlowError "not-found". */
+    signal(workflowId: string, topic: string, value: unknown): Promise<void>;
+    /** Опубликовать значение для query снаружи; читается и после завершения процесса. */
+    setState(key: string, value: unknown): Promise<void>;
+    /**
+     * Ветка новой версии кода: true — процесс начат новым кодом, false — старым и переигрывается.
+     * Новый код кладётся под `if (await ctx.patched("id"))`, старый остаётся в else.
+     */
+    patched(id: string): Promise<boolean>;
+    /** Старых процессов больше нет: всегда true, старую ветку можно удалить. Следующий шаг — убрать вызов. */
+    deprecatePatch(id: string): Promise<void>;
+}
+export type Flow = (ctx: FlowContext, ...args: any[]) => Promise<unknown>;
+/** Адрес процесса: модуль (= очередь и приложение) и имя процесса. */
+export interface FlowRef {
+    app: string;
+    flow: string;
+}
+/** Модуль в одном процессе bun: свои процессы и свои шаги, своя очередь. */
+export interface AppDefinition {
+    app: string;
+    flows: Record<string, Flow>;
+    activities: Record<string, Activity>;
+    /**
+     * Патчи этой версии кода — все ids из ctx.patched. Необъявленный id — ошибка на обоих движках:
+     * DBOS решает ветку по этому списку (см. @iworkflow/dbos), опечатка молча вела бы в старую.
+     */
+    patches?: string[];
+    /** Пулы шагов: имя → сколько шагов пула идёт одновременно в этом процессе. */
+    pools?: Record<string, number>;
+}
+export type FlowStatus = "running" | "completed" | "failed" | "terminated" | "timed-out";
+export interface FlowDescription {
+    id: string;
+    status: FlowStatus;
+    startedAt: Date;
+}
+export interface FlowHandle<T> {
+    id: string;
+    /** Процесс упал — FlowError: "failed", "timeout" или "terminated". */
+    result(): Promise<T>;
+    signal(topic: string, value: unknown): Promise<void>;
+    /** Последнее значение setState по ключу; undefined — ещё не публиковалось. */
+    query<V>(key: string): Promise<V | undefined>;
+    /** Нет процесса — FlowError "not-found". */
+    describe(): Promise<FlowDescription>;
+    /** Прервать процесс без отката; result() бросит FlowError "terminated". */
+    terminate(reason?: string): Promise<void>;
+}
+/** Сторона модуля: держит воркер своей очереди. */
+export interface EngineRuntime {
+    start(def: AppDefinition): Promise<void>;
+    stop(): Promise<void>;
+    /** Цикл start…stop: завершается со stop; отклоняется при сбое start и (Temporal) падении воркера. */
+    done(): Promise<void>;
+}
+export interface StartOptions {
+    id: string;
+    /** Срок процесса. */
+    timeoutMs?: number;
+    /** 1 — первым, 5 — последним; шаги процесса наследуют его. */
+    priority?: number;
+}
+/** Сторона вызывающего вне процесса (HTTP, CLI, тест). */
+export interface EngineClient {
+    /** Id уже идёт — handle к нему. 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>>;
+    /** Уже запущенный процесс по id. */
+    handle<T>(id: string): FlowHandle<T>;
+    close(): Promise<void>;
+}
+export type EngineName = "temporal" | "dbos";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@iworkflow/core",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Engine-neutral durable workflow port: flows, steps, child workflows, signals, queries, patches, heartbeat",
   "keywords": [
     "workflow",
@@ -15,18 +15,29 @@
     "directory": "packages/core"
   },
   "files": [
-    "src"
+    "src",
+    "!src/**/*.test.ts",
+    "dist"
   ],
   "type": "module",
   "sideEffects": false,
   "exports": {
-    ".": "./src/index.ts"
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
   },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
+    "build": "rm -rf dist && bun build src/index.ts --outdir dist --target node --format esm --packages external && tsc -p tsconfig.build.json",
     "type-check": "tsc --noEmit -p tsconfig.json",
-    "test": "bun test"
+    "test": "bun test",
+    "prepack": "bun run build"
+  },
+  "engines": {
+    "node": ">=22"
   }
 }

package/src/errors.ts

@@ -8,12 +8,20 @@ export class Failure extends Error {
   readonly type: string;
   readonly details?: unknown;
   readonly nonRetryable: boolean;
-  constructor(message: string, opts: { type: string; details?: unknown; nonRetryable?: boolean }) {
+  /** Следующая попытка шага не раньше чем через столько мс (FLOOD_WAIT): вместо паузы из StepOptions. */
+  readonly retryAfterMs?: number;
+  constructor(
+    message: string,
+    opts: { type: string; details?: unknown; nonRetryable?: boolean; retryAfterMs?: number },
+  ) {
     super(message);
     this.name = "Failure";
     this.type = opts.type;
     this.details = opts.details;
     this.nonRetryable = opts.nonRetryable ?? false;
+    // Неразобранный срок (NaN, отрицательный) — как не заданный: пауза из StepOptions.
+    const after = opts.retryAfterMs;
+    this.retryAfterMs = after !== undefined && Number.isFinite(after) && after >= 0 ? after : undefined;
   }
 }
 
@@ -53,3 +61,14 @@ export class FlowError extends Error {
 /** FlowError по признакам, а не по классу: класс теряется при сериализации в DBOS. */
 export const isFlowError = (e: unknown): e is FlowError =>
   e instanceof FlowError || (e instanceof Error && e.name === "FlowError" && typeof (e as FlowError).reason === "string");
+
+/** Приоритет порта — целое 1…5 (1 — первым); иное отвергается одинаково на обоих движках. */
+export function checkPriority(p: number | undefined): number | undefined {
+  if (p === undefined) return undefined;
+  // Failure, а не Error: в процессе Temporal Error — вечный повтор задачи процесса, а не отказ.
+  if (!Number.isInteger(p) || p < 1 || p > 5)
+    throw new Failure(`приоритет ${p}: нужно целое от 1 до 5`, { type: "InvalidPriority", nonRetryable: true });
+  return p;
+}
+
+export const DEFAULT_PRIORITY = 3;

package/src/exit.ts

@@ -0,0 +1,32 @@
+// Общее для адаптеров: done() рантайма — одно обещание на цикл start…stop, взятое хоть до start.
+
+export interface ExitSignal {
+  /** Перед start: прошлый цикл завершён — новое обещание, иначе то же. */
+  arm(): void;
+  resolve(): void;
+  reject(e: unknown): void;
+  promise(): Promise<void>;
+}
+
+export function exitSignal(): ExitSignal {
+  let d = Promise.withResolvers<void>();
+  let settled = false;
+  // Никто не ждёт done() — отказ воркера не становится unhandled rejection.
+  d.promise.catch(() => {});
+  const settle = (f: () => void) => {
+    if (settled) return;
+    settled = true;
+    f();
+  };
+  return {
+    arm() {
+      if (!settled) return;
+      d = Promise.withResolvers<void>();
+      d.promise.catch(() => {});
+      settled = false;
+    },
+    resolve: () => settle(() => d.resolve()),
+    reject: (e) => settle(() => d.reject(e)),
+    promise: () => d.promise,
+  };
+}

package/src/heartbeat.ts

@@ -4,6 +4,8 @@
 export interface StepRuntime {
   heartbeat(details?: unknown): Promise<void>;
   lastHeartbeat(): Promise<unknown>;
+  /** Номер попытки шага, с 1. */
+  attempt(): number;
 }
 
 const KEY = Symbol.for("@iworkflow/core.step-runtime");
@@ -25,3 +27,6 @@ export const heartbeat = (details?: unknown): Promise<void> => current().heartbe
 /** Прогресс прошлой попытки этого шага; undefined — первая попытка или прогресса не было. */
 export const lastHeartbeat = async <T>(): Promise<T | undefined> =>
   ((await current().lastHeartbeat()) ?? undefined) as T | undefined;
+
+/** Номер попытки этого шага, с 1. DBOS считает заново после рестарта процесса, Temporal — нет. */
+export const stepAttempt = (): number => current().attempt();

package/src/index.ts

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

package/src/types.ts

@@ -25,6 +25,8 @@ export interface StepOptions {
   nonRetryableTypes?: string[];
   /** Пул шага из AppDefinition.pools — со своим пределом одновременных шагов. */
   pool?: string;
+  /** Приоритет шага в очереди пула: 1 — первым, 5 — последним. По умолчанию — приоритет процесса. */
+  priority?: number;
 }
 
 export interface ChildOptions {
@@ -51,6 +53,10 @@ export interface FlowContext {
   readonly parentId: string | undefined;
   /** Время запуска процесса: одно и то же при каждом переигрывании. */
   readonly startedAt: Date;
+  /** Приоритет процесса из start: 1 — первым, 5 — последним; не задан — 3. */
+  readonly priority: number;
+  /** Текущее время, мс: одно и то же при переигрывании. Date.now() в процессе DBOS не детерминирован. */
+  now(): Promise<number>;
   /** Шаг упал после повторов — FlowError reason "failed" или "timeout". */
   step<T>(name: string, args: unknown[], opts?: StepOptions): Promise<T>;
   /** Дочерний процесс в другом модуле: его очередь, его процесс, ждём результат. */
@@ -123,12 +129,27 @@ export interface FlowHandle<T> {
 export interface EngineRuntime {
   start(def: AppDefinition): Promise<void>;
   stop(): Promise<void>;
+  /** Цикл start…stop: завершается со stop; отклоняется при сбое start и (Temporal) падении воркера. */
+  done(): Promise<void>;
+}
+
+export interface StartOptions {
+  id: string;
+  /** Срок процесса. */
+  timeoutMs?: number;
+  /** 1 — первым, 5 — последним; шаги процесса наследуют его. */
+  priority?: number;
 }
 
 /** Сторона вызывающего вне процесса (HTTP, CLI, тест). */
 export interface EngineClient {
   /** Id уже идёт — handle к нему. timeoutMs — срок процесса. */
-  start<T>(target: FlowRef, args: unknown[], opts: { id: string; timeoutMs?: number }): Promise<FlowHandle<T>>;
+  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>>;
   /** Уже запущенный процесс по id. */
   handle<T>(id: string): FlowHandle<T>;
   close(): Promise<void>;