@iworkflow/core 0.2.0 → 0.4.0

package/dist/errors.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Отказ, который бросает код шага или процесса. `type` — код для разбора (`FlowError.type`),
+ * `nonRetryable` — шаг не повторять. Отказ процесса не повторяется никогда.
+ */
+export declare class Failure extends Error {
+    readonly type: string;
+    readonly details?: unknown;
+    readonly nonRetryable: boolean;
+    constructor(message: string, opts: {
+        type: string;
+        details?: unknown;
+        nonRetryable?: boolean;
+    });
+}
+/** Отказ без повтора: `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;

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,9 @@
+export interface StepRuntime {
+    heartbeat(details?: unknown): Promise<void>;
+    lastHeartbeat(): Promise<unknown>;
+}
+export declare function bindStepRuntime(rt: StepRuntime): void;
+/** Отметить, что шаг жив, и сохранить прогресс. */
+export declare const heartbeat: (details?: unknown) => Promise<void>;
+/** Прогресс прошлой попытки этого шага; undefined — первая попытка или прогресса не было. */
+export declare const lastHeartbeat: <T>() => Promise<T | undefined>;

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,77 @@
+// 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;
+// src/errors.ts
+class Failure extends Error {
+  type;
+  details;
+  nonRetryable;
+  constructor(message, opts) {
+    super(message);
+    this.name = "Failure";
+    this.type = opts.type;
+    this.details = opts.details;
+    this.nonRetryable = opts.nonRetryable ?? false;
+  }
+}
+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";
+// 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 {
+  Failure,
+  FlowError,
+  bindStepRuntime,
+  exitSignal,
+  heartbeat,
+  isFlowError,
+  lastHeartbeat,
+  nonRetryable
+};

package/dist/types.d.ts

@@ -0,0 +1,126 @@
+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;
+}
+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;
+    /** Шаг упал после повторов — 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>;
+}
+/** Сторона вызывающего вне процесса (HTTP, CLI, тест). */
+export interface EngineClient {
+    /** Id уже идёт — handle к нему. timeoutMs — срок процесса. */
+    start<T>(target: FlowRef, args: unknown[], opts: {
+        id: string;
+        timeoutMs?: number;
+    }): 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.2.0",
+  "version": "0.4.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/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/index.ts

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

package/src/types.ts

@@ -4,7 +4,7 @@
 export type Activity = (...args: any[]) => Promise<unknown>;
 
 export interface StepOptions {
-  /** Попыток всего, включая первую. По умолчанию 3. */
+  /** Попыток всего, включая первую. По умолчанию 3; Infinity — до totalTimeoutMs или срока процесса. */
   attempts?: number;
   /** Предел одной попытки. По умолчанию 60 с. DBOS не ограничивает: шаг повторяется после рестарта. */
   timeoutMs?: number;
@@ -123,6 +123,8 @@ export interface FlowHandle<T> {
 export interface EngineRuntime {
   start(def: AppDefinition): Promise<void>;
   stop(): Promise<void>;
+  /** Цикл start…stop: завершается со stop; отклоняется при сбое start и (Temporal) падении воркера. */
+  done(): Promise<void>;
 }
 
 /** Сторона вызывающего вне процесса (HTTP, CLI, тест). */