@bobtail.software/b-durable 1.0.3 → 1.0.5

package/dist/index.d.mts

@@ -1,11 +1,18 @@
 import Redis from 'ioredis';
 import ms from 'ms';
 
+interface WorkflowState {
+    tryCatchStack?: {
+        catchStep?: number;
+        finallyStep?: number;
+    }[];
+    [key: string]: unknown;
+}
 interface WorkflowContext<TInput = unknown> {
     workflowId: string;
     step: number;
     input: TInput;
-    state: Record<string, unknown>;
+    state: WorkflowState;
     result?: unknown;
     log: (message: string) => void;
 }
@@ -28,26 +35,34 @@ type Instruction<TOutput = unknown> = {
     type: 'COMPLETE';
     result: TOutput;
 };
-interface DurableFunction<TInput = unknown, TOutput = unknown> {
+interface DurableFunction<TInput = unknown, TOutput = unknown, TEvents = Record<string, never>> {
     __isDurable: true;
     name: string;
     execute: (context: WorkflowContext<TInput>) => Promise<Instruction<TOutput>>;
+    _TEvents?: TEvents;
 }
 
+interface StartOptions<TInput> {
+    input: TInput;
+    workflowId?: string;
+}
 declare class DurableRuntime {
     private durableFns;
-    private isWorkerRunning;
-    private isSchedulerRunning;
+    private repo;
+    private workerId;
+    private isRunning;
     private schedulerInterval;
     private readonly sourceRoot;
     constructor(options: {
         sourceRoot: string;
     });
-    start<TInput, TOutput>(durableFn: DurableFunction<TInput, TOutput>, input: TInput, parentId?: string, predefinedWorkflowId?: string): Promise<string>;
-    private executeStep;
+    start<TInput, TOutput>(durableFn: DurableFunction<TInput, TOutput>, options: StartOptions<TInput>, parentId?: string): Promise<string>;
+    private scheduleExecution;
+    private _executeStep;
     private handleInstruction;
+    private handleFailure;
     private resumeParentWorkflow;
-    private failParentWorkflow;
+    private propagateFailureToParent;
     sendEvent<T>(workflowId: string, eventName: string, payload: T): Promise<void>;
     private startScheduler;
     private startWorker;
@@ -55,42 +70,56 @@ declare class DurableRuntime {
     stop(): void;
 }
 
-type DurableWorkflowFn<TInput, TOutput> = (input: TInput, context: Pick<WorkflowContext<TInput>, 'log' | 'workflowId'>) => Promise<TOutput>;
-/**
- * Marcador para que el compilador identifique y transforme una función en un workflow durable.
- * Esta función es un passthrough en tiempo de ejecución, su único propósito es para el análisis estático.
- * @param fn La función async que define la lógica del workflow.
- */
-declare const bDurable: <TInput, TOutput>(fn: DurableWorkflowFn<TInput, TOutput>) => DurableWorkflowFn<TInput, TOutput>;
-
 /**
- * Ejecuta un sub-workflow y espera de forma duradera su resultado.
- * @param workflow La función durable a ejecutar.
- * @param input La entrada para el sub-workflow.
- * @returns Una promesa que se resuelve con el resultado del sub-workflow.
+ * El contexto de ejecución proporcionado a cada workflow, con métodos de durabilidad tipados.
  */
-declare function bExecute<TInput, TOutput>(workflow: DurableWorkflowFn<TInput, TOutput>, input: TInput): Promise<TOutput>;
-
-/**
- * Pausa la ejecución del workflow de manera duradera.
- * Esta función es un marcador especial que el compilador `b-durable` transforma
- * en una instrucción para el runtime. No se ejecuta directamente.
- * @param duration Una cadena de tiempo como '2 days', '10h', '7s'.
- */
-declare function bSleep(duration: ms.StringValue): Promise<void>;
-
+interface DurableContext<TEvents = Record<string, never>> extends Pick<WorkflowContext, 'log' | 'workflowId'> {
+    /**
+     * Pausa la ejecución del workflow de manera duradera.
+     * @param duration Una cadena de tiempo como '2 days', '10h', '7s'.
+     */
+    bSleep(duration: ms.StringValue): Promise<void>;
+    /**
+     * Pausa la ejecución del workflow hasta que se reciba un evento externo.
+     * El tipo del payload retornado se infiere automáticamente del contrato de eventos del workflow.
+     * @param eventName El nombre único del evento que se está esperando.
+     * @returns Una promesa que se resuelve con el payload del evento recibido.
+     */
+    bWaitForEvent<K extends keyof TEvents>(eventName: K): Promise<TEvents[K]>;
+    /**
+     * Ejecuta un sub-workflow y espera de forma duradera su resultado.
+     * @param workflow La función durable a ejecutar.
+     * @param input La entrada para el sub-workflow.
+     * @returns Una promesa que se resuelve con el resultado del sub-workflow.
+     */
+    bExecute<TInput, TOutput, TWorkflowEvents extends Record<string, any>>(workflow: DurableFunction<TInput, TOutput, TWorkflowEvents>, input: TInput): Promise<TOutput>;
+}
+type DurableWorkflowFn<TInput, TOutput, TEvents = Record<string, never>> = (input: TInput, context: DurableContext<TEvents>) => Promise<TOutput>;
+interface DurableWorkflowDef<TInput, TOutput, TEvents = Record<string, never>> {
+    /**
+     * La función async que contiene la lógica del workflow.
+     */
+    workflow: DurableWorkflowFn<TInput, TOutput, TEvents>;
+}
 /**
- * Pausa la ejecución del workflow hasta que se reciba un evento externo.
- * @param eventName El nombre único del evento que se está esperando.
- * @returns Una promesa que se resuelve con el payload del evento recibido.
+ * Marcador para que el compilador identifique y transforme una función en un workflow durable.
+ * Esta función es un passthrough en tiempo de ejecución, su único propósito es para el análisis estático.
  */
-declare function bWaitForEvent<T>(eventName: string): Promise<T>;
+declare const bDurable: <TInput = any, TOutput = any, TEvents = Record<string, never>>(def: DurableWorkflowDef<TInput, TOutput, TEvents>) => DurableFunction<TInput, TOutput, TEvents>;
 
 interface BDurableAPI {
-    start: <TInput, TOutput>(durableFn: DurableFunction<TInput, TOutput>, input: TInput) => Promise<string>;
+    start: <TInput, TOutput>(durableFn: DurableFunction<TInput, TOutput>, options: StartOptions<TInput>) => Promise<string>;
     stop: () => void;
     runtime: DurableRuntime;
-    sendEvent: <T>(workflowId: string, eventName: string, payload: T) => Promise<void>;
+    /**
+     * Envía un evento a un workflow en ejecución que está en pausa esperando dicho evento.
+     * Esta función es estrictamente tipada basada en el tipo de eventos de la definición del workflow.
+     * @param durableFn La definición del workflow al que se le enviará el evento. Se usa para la inferencia de tipos.
+     * @param workflowId El ID del workflow al que se le enviará el evento.
+     * @param eventName El nombre del evento. Será autocompletado por el editor.
+     * @param payload La carga útil del evento. El tipo debe coincidir con el definido para `eventName`.
+     */
+    sendEvent: <TInput, TOutput, TWorkflowEvents, K extends keyof TWorkflowEvents>(durableFn: DurableFunction<TInput, TOutput, TWorkflowEvents>, workflowId: string, eventName: K, payload: TWorkflowEvents[K]) => Promise<void>;
 }
 interface InitializeOptions {
     durableFunctions: Map<string, DurableFunction<unknown, unknown>>;
@@ -100,4 +129,4 @@ interface InitializeOptions {
 }
 declare function bDurableInitialize(options: InitializeOptions): BDurableAPI;
 
-export { type BDurableAPI, type DurableFunction, type Instruction, type WorkflowContext, bDurable, bDurableInitialize, bExecute, bSleep, bWaitForEvent };
+export { type BDurableAPI, type DurableFunction, type Instruction, type StartOptions, type WorkflowContext, type WorkflowState, bDurable, bDurableInitialize };