@bobtail.software/b-durable 1.0.5 → 1.0.7

package/dist/index.d.mts

@@ -1,6 +1,29 @@
 import Redis from 'ioredis';
 import ms from 'ms';
 
+interface Logger {
+    info(message: string, meta?: Record<string, unknown>): void;
+    error(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    debug(message: string, meta?: Record<string, unknown>): void;
+}
+interface WorkflowStateInfo<TInput = unknown, TOutput = unknown> {
+    workflowId: string;
+    name: string;
+    version: string;
+    status: string;
+    step: number;
+    input: TInput;
+    output?: TOutput;
+    state: Record<string, unknown>;
+    error?: string;
+    createdAt?: number;
+    updatedAt?: number;
+    pendingTask?: {
+        name: string;
+        attempts: number;
+    };
+}
 interface WorkflowState {
     tryCatchStack?: {
         catchStep?: number;
@@ -14,7 +37,17 @@ interface WorkflowContext<TInput = unknown> {
     input: TInput;
     state: WorkflowState;
     result?: unknown;
-    log: (message: string) => void;
+    log: (message: string, meta?: Record<string, unknown>) => void;
+}
+interface RetryOptions {
+    /** Número máximo de intentos. Infinity para reintentar siempre. Por defecto: 3 */
+    maxAttempts?: number;
+    /** Tiempo de espera antes del primer reintento (ej: '1s'). Por defecto: '1s' */
+    initialInterval?: ms.StringValue;
+    /** Coeficiente de multiplicación para backoff exponencial. Por defecto: 2 */
+    backoffCoefficient?: number;
+    /** Tiempo máximo de espera entre reintentos (ej: '1h'). Por defecto: '1h' */
+    maxInterval?: ms.StringValue;
 }
 type Instruction<TOutput = unknown> = {
     type: 'SCHEDULE_TASK';
@@ -25,55 +58,147 @@ type Instruction<TOutput = unknown> = {
     type: 'SCHEDULE_SLEEP';
     duration: ms.StringValue;
 } | {
-    type: 'WAIT_FOR_EVENT';
-    eventName: string;
+    type: 'WAIT_FOR_SIGNAL';
+    signalName: string;
 } | {
     type: 'EXECUTE_SUBWORKFLOW';
     workflowName: string;
     input: unknown;
+} | {
+    type: 'EMIT_EVENT';
+    eventName: string;
+    payload: unknown;
 } | {
     type: 'COMPLETE';
     result: TOutput;
 };
-interface DurableFunction<TInput = unknown, TOutput = unknown, TEvents = Record<string, never>> {
+interface DurableFunction<TInput = unknown, TOutput = unknown, TSignals = Record<string, never>, // INPUT: Señales que el workflow puede RECIBIR
+TEvents = Record<string, never>> {
     __isDurable: true;
     name: string;
+    version: string;
+    retryOptions?: RetryOptions;
     execute: (context: WorkflowContext<TInput>) => Promise<Instruction<TOutput>>;
+    _TSignals?: TSignals;
     _TEvents?: TEvents;
 }
-
-interface StartOptions<TInput> {
+/**
+ * Transforma un mapa de eventos en props de listeners.
+ * Ejemplo: { started: { id: string } } => { onStarted?: (payload: { id: string }) => void }
+ */
+type WorkflowEventListeners<TEvents> = {
+    [K in keyof TEvents as `on${Capitalize<string & K>}`]?: (payload: TEvents[K]) => void;
+};
+/**
+ * Representa cualquier evento que sale del workflow, ya sea definido por el usuario
+ * o por el sistema (completado/fallido).
+ */
+type WorkflowEvent<TEvents, TOutput> = {
+    [K in keyof TEvents]: {
+        name: K;
+        payload: TEvents[K];
+    };
+}[keyof TEvents] | {
+    name: 'workflow:completed';
+    payload: TOutput;
+} | {
+    name: 'workflow:failed';
+    payload: {
+        message: string;
+    };
+};
+/**
+ * Utilidad para "aplanar" intersecciones de tipos.
+ * Esto fuerza a TypeScript a computar el objeto final inmediatamente,
+ * permitiendo que la inferencia contextual de los argumentos funcione correctamente.
+ */
+type Compute<T> = {
+    [K in keyof T]: T[K];
+} & unknown;
+/**
+ * Opciones para iniciar el workflow. Combina input estándar + listeners dinámicos.
+ */
+type StartOptions<TInput, TEvents> = Compute<{
     input: TInput;
     workflowId?: string;
+} & WorkflowEventListeners<TEvents>>;
+interface StartedWorkflowHandle {
+    workflowId: string;
+    unsubscribe: () => Promise<void>;
+}
+/**
+ * Handle para interactuar con un workflow en ejecución.
+ */
+interface WorkflowHandle<TSignals, TEvents, TOutput> {
+    workflowId: string;
+    /**
+     * Envía una señal (INPUT) al workflow.
+     * @param name Nombre de la señal (definido en TSignals).
+     * @param payload Datos de la señal.
+     */
+    signal: <K extends keyof TSignals>(name: K, payload: TSignals[K]) => Promise<void>;
+    /**
+     * Suscribe un callback a un evento específico (OUTPUT).
+     * @param eventName Nombre del evento (definido en TEvents).
+     * @param handler Función que recibe el payload.
+     */
+    on: <K extends keyof TEvents>(eventName: K, handler: (payload: TEvents[K]) => void) => Promise<{
+        unsubscribe: () => void;
+    }>;
+    /**
+     * Suscribe un callback a TODOS los eventos (incluyendo sistema).
+     * Útil para logging o debug.
+     */
+    subscribe: (handler: (event: WorkflowEvent<TEvents, TOutput>) => void) => Promise<{
+        unsubscribe: () => void;
+    }>;
 }
+declare class WorkflowCancellationError extends Error {
+    readonly isCancellation = true;
+    constructor(message: string);
+}
+
 declare class DurableRuntime {
     private durableFns;
     private repo;
     private workerId;
     private isRunning;
     private schedulerInterval;
+    private heartbeatInterval;
     private readonly sourceRoot;
+    private readonly pollingInterval;
+    private readonly logger;
+    private readonly maxTaskRetries;
     constructor(options: {
         sourceRoot: string;
+        retention?: ms.StringValue;
+        pollingInterval?: number;
+        logger?: Logger;
     });
-    start<TInput, TOutput>(durableFn: DurableFunction<TInput, TOutput>, options: StartOptions<TInput>, parentId?: string): Promise<string>;
+    getState(workflowId: string): Promise<WorkflowStateInfo | null>;
+    start<TInput, TOutput, TSignals, TEvents>(durableFn: DurableFunction<TInput, TOutput, TSignals, TEvents>, options: StartOptions<TInput, TEvents>, parentId?: string): Promise<StartedWorkflowHandle>;
     private scheduleExecution;
     private _executeStep;
     private handleInstruction;
     private handleFailure;
     private resumeParentWorkflow;
     private propagateFailureToParent;
-    sendEvent<T>(workflowId: string, eventName: string, payload: T): Promise<void>;
+    signal<T>(workflowId: string, signalName: string, payload: T): Promise<void>;
+    cancel(workflowId: string, reason: string): Promise<void>;
     private startScheduler;
+    private checkDelayedTasks;
+    private checkSleepers;
+    private reapDeadWorkers;
+    private startHeartbeat;
     private startWorker;
-    run(durableFns: Map<string, DurableFunction<unknown>>): void;
-    stop(): void;
+    run(durableFns: Map<string, DurableFunction<unknown, unknown, unknown, unknown>>): void;
+    stop(): Promise<void>;
 }
 
 /**
  * El contexto de ejecución proporcionado a cada workflow, con métodos de durabilidad tipados.
  */
-interface DurableContext<TEvents = Record<string, never>> extends Pick<WorkflowContext, 'log' | 'workflowId'> {
+interface DurableContext<TEvents = Record<string, never>, TSignals = 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'.
@@ -92,41 +217,64 @@ interface DurableContext<TEvents = Record<string, never>> extends Pick<WorkflowC
      * @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>;
+    bExecute<TInput, TOutput, TWorkflowEvents, TWorkflowSignals>(workflow: DurableFunction<TInput, TOutput, TWorkflowEvents, TWorkflowSignals>, input: TInput): Promise<TOutput>;
+    /**
+     * Emite una señal o notificación con un payload desde el workflow.
+     * Esta operación es duradera pero no bloquea la ejecución. El workflow continúa inmediatamente después.
+     * El nombre de la señal y el tipo del payload son validados contra el contrato de señales del workflow.
+     * @param signalName El nombre de la señal.
+     * @param payload Los datos a enviar con la señal.
+     */
+    bSignal<K extends keyof TSignals>(signalName: K, payload: TSignals[K]): Promise<void>;
 }
-type DurableWorkflowFn<TInput, TOutput, TEvents = Record<string, never>> = (input: TInput, context: DurableContext<TEvents>) => Promise<TOutput>;
-interface DurableWorkflowDef<TInput, TOutput, TEvents = Record<string, never>> {
+type DurableWorkflowFn<TInput, TOutput, TEvents = Record<string, never>, TSignals = Record<string, never>> = (input: TInput, context: DurableContext<TEvents, TSignals>) => Promise<TOutput>;
+interface DurableWorkflowDef<TInput, TOutput, TEvents = Record<string, never>, TSignals = Record<string, never>> {
     /**
      * La función async que contiene la lógica del workflow.
      */
-    workflow: DurableWorkflowFn<TInput, TOutput, TEvents>;
+    workflow: DurableWorkflowFn<TInput, TOutput, TEvents, TSignals>;
+    /**
+     * Versión del workflow. Se utiliza para identificar versiones de un workflow.
+     */
+    version: string;
+    /**
+     * Política de reintento para las tareas ejecutadas por este workflow.
+     * Si falla una tarea, se aplicará esta configuración.
+     */
+    retryOptions?: RetryOptions;
 }
 /**
  * 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 const bDurable: <TInput = any, TOutput = any, TEvents = Record<string, never>>(def: DurableWorkflowDef<TInput, TOutput, TEvents>) => DurableFunction<TInput, TOutput, TEvents>;
+declare const bDurable: <TInput = any, TOutput = any, TEvents = Record<string, never>, TSignals = Record<string, never>>(def: DurableWorkflowDef<TInput, TOutput, TEvents, TSignals>) => DurableFunction<TInput, TOutput, TEvents, TSignals>;
 
 interface BDurableAPI {
-    start: <TInput, TOutput>(durableFn: DurableFunction<TInput, TOutput>, options: StartOptions<TInput>) => Promise<string>;
+    /**
+     * Inicia un workflow durable.
+     * Permite definir listeners de eventos inmediatamente en las opciones (ej: { onProgress: ... })
+     * para evitar condiciones de carrera.
+     */
+    start: <TInput, TOutput, TSignals, TEvents>(durableFn: DurableFunction<TInput, TOutput, TSignals, TEvents>, options: StartOptions<TInput, TEvents>) => Promise<StartedWorkflowHandle>;
     stop: () => void;
     runtime: DurableRuntime;
+    cancel: (workflowId: string, reason: string) => Promise<void>;
+    getState: (workflowId: string) => Promise<WorkflowStateInfo | null>;
     /**
-     * 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`.
+     * Obtiene un "handle" para una instancia de workflow existente.
+     * Permite enviar señales (Input) y escuchar eventos (Output).
      */
-    sendEvent: <TInput, TOutput, TWorkflowEvents, K extends keyof TWorkflowEvents>(durableFn: DurableFunction<TInput, TOutput, TWorkflowEvents>, workflowId: string, eventName: K, payload: TWorkflowEvents[K]) => Promise<void>;
+    getHandle: <TInput, TOutput, TSignals, TEvents>(durableFn: DurableFunction<TInput, TOutput, TSignals, TEvents>, workflowId: string) => WorkflowHandle<TSignals, TEvents, TOutput>;
 }
 interface InitializeOptions {
-    durableFunctions: Map<string, DurableFunction<unknown, unknown>>;
+    durableFunctions: Map<string, DurableFunction<unknown, unknown, any, any>>;
     sourceRoot: string;
     redisClient: Redis;
     blockingRedisClient: Redis;
+    retention?: ms.StringValue;
+    pollingInterval?: number;
+    logger?: Logger;
 }
 declare function bDurableInitialize(options: InitializeOptions): BDurableAPI;
 
-export { type BDurableAPI, type DurableFunction, type Instruction, type StartOptions, type WorkflowContext, type WorkflowState, bDurable, bDurableInitialize };
+export { type BDurableAPI, type DurableFunction, type Instruction, type Logger, type RetryOptions, type StartOptions, type StartedWorkflowHandle, WorkflowCancellationError, type WorkflowContext, type WorkflowEvent, type WorkflowEventListeners, type WorkflowHandle, type WorkflowState, type WorkflowStateInfo, bDurable, bDurableInitialize };