@iworkflow/core 0.4.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

@@ -6,10 +6,13 @@ 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")`. */
@@ -38,3 +41,6 @@ export declare class FlowError extends Error {
 }
 /** 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/heartbeat.d.ts

@@ -1,9 +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

@@ -1,4 +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/dist/index.js

@@ -11,17 +11,21 @@ function current() {
 }
 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 });
@@ -41,6 +45,14 @@ class FlowError extends Error {
   }
 }
 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();
@@ -66,12 +78,15 @@ function exitSignal() {
   };
 }
 export {
+  DEFAULT_PRIORITY,
   Failure,
   FlowError,
   bindStepRuntime,
+  checkPriority,
   exitSignal,
   heartbeat,
   isFlowError,
   lastHeartbeat,
-  nonRetryable
+  nonRetryable,
+  stepAttempt
 };

package/dist/types.d.ts

@@ -21,6 +21,8 @@ export interface StepOptions {
     nonRetryableTypes?: string[];
     /** Пул шага из AppDefinition.pools — со своим пределом одновременных шагов. */
     pool?: string;
+    /** Приоритет шага в очереди пула: 1 — первым, 5 — последним. По умолчанию — приоритет процесса. */
+    priority?: number;
 }
 export interface ChildOptions {
     id: string;
@@ -44,6 +46,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>;
     /** Дочерний процесс в другом модуле: его очередь, его процесс, ждём результат. */
@@ -112,13 +118,22 @@ export interface EngineRuntime {
     /** Цикл 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>;

package/package.json

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

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/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,4 +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>;
   /** Дочерний процесс в другом модуле: его очередь, его процесс, ждём результат. */
@@ -127,10 +133,23 @@ export interface EngineRuntime {
   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>;