@bobtail.software/b-durable 1.0.5 → 1.0.6

package/dist/index.d.mts

@@ -1,6 +1,45 @@
 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 StartOptions<TInput, TSignals, TOutput> {
+    input: TInput;
+    workflowId?: string;
+    /**
+     * Un callback opcional para recibir señales emitidas por el workflow en tiempo real.
+     * Se garantiza que la suscripción está activa antes de que se ejecute el primer paso.
+     */
+    subscribe?: (signal: WorkflowSignal<TSignals, TOutput>) => void;
+}
+interface StartedWorkflowHandle {
+    workflowId: string;
+    /**
+     * Cierra la suscripción a las señales creada en `start`.
+     */
+    unsubscribe: () => Promise<void>;
+}
 interface WorkflowState {
     tryCatchStack?: {
         catchStep?: number;
@@ -14,7 +53,7 @@ interface WorkflowContext<TInput = unknown> {
     input: TInput;
     state: WorkflowState;
     result?: unknown;
-    log: (message: string) => void;
+    log: (message: string, meta?: Record<string, unknown>) => void;
 }
 type Instruction<TOutput = unknown> = {
     type: 'SCHEDULE_TASK';
@@ -31,32 +70,79 @@ type Instruction<TOutput = unknown> = {
     type: 'EXECUTE_SUBWORKFLOW';
     workflowName: string;
     input: unknown;
+} | {
+    type: 'SEND_SIGNAL';
+    signalName: string;
+    payload: unknown;
 } | {
     type: 'COMPLETE';
     result: TOutput;
 };
-interface DurableFunction<TInput = unknown, TOutput = unknown, TEvents = Record<string, never>> {
+/**
+ * Representa una señal emitida por un workflow como una unión discriminada.
+ * Esto permite un estrechamiento de tipos seguro en el consumidor.
+ * Incluye las señales personalizadas (TSignals) y las señales del sistema.
+ */
+type WorkflowSignal<TSignals, TOutput> = {
+    [K in keyof TSignals]: {
+        name: K;
+        payload: TSignals[K];
+    };
+}[keyof TSignals] | {
+    name: 'workflow:completed';
+    payload: TOutput;
+} | {
+    name: 'workflow:failed';
+    payload: {
+        message: string;
+    };
+};
+/**
+ * Permite suscribirse a un workflow ya existente.
+ */
+interface WorkflowHandle<TSignals = unknown, TOutput = unknown> {
+    workflowId: string;
+    /**
+     * Se suscribe a las señales emitidas por esta instancia específica del workflow.
+     * @param onSignal Un callback fuertemente tipado que se ejecuta para cada señal.
+     * @returns Una promesa que se resuelve en un objeto con una función `unsubscribe`.
+     */
+    subscribe: (onSignal: (signal: WorkflowSignal<TSignals, TOutput>, unsubscribe: () => void) => void) => Promise<{
+        unsubscribe: () => void;
+    }>;
+}
+declare class WorkflowCancellationError extends Error {
+    readonly isCancellation = true;
+    constructor(message: string);
+}
+interface DurableFunction<TInput = unknown, TOutput = unknown, TEvents = Record<string, never>, TSignals = Record<string, never>> {
     __isDurable: true;
     name: string;
+    version: string;
     execute: (context: WorkflowContext<TInput>) => Promise<Instruction<TOutput>>;
     _TEvents?: TEvents;
+    _TSignals?: TSignals;
 }
 
-interface StartOptions<TInput> {
-    input: TInput;
-    workflowId?: 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, TEvents, TSignals>(durableFn: DurableFunction<TInput, TOutput, TEvents, TSignals>, options: StartOptions<TInput, TSignals, TOutput>, parentId?: string): Promise<StartedWorkflowHandle>;
     private scheduleExecution;
     private _executeStep;
     private handleInstruction;
@@ -64,16 +150,20 @@ declare class DurableRuntime {
     private resumeParentWorkflow;
     private propagateFailureToParent;
     sendEvent<T>(workflowId: string, eventName: string, payload: T): Promise<void>;
+    cancel(workflowId: string, reason: string): Promise<void>;
     private startScheduler;
+    private checkSleepers;
+    private reapDeadWorkers;
+    private startHeartbeat;
     private startWorker;
-    run(durableFns: Map<string, DurableFunction<unknown>>): void;
+    run(durableFns: Map<string, DurableFunction<unknown, unknown, any, any>>): void;
     stop(): 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,25 +182,39 @@ 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;
 }
 /**
  * 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>;
+    start: <TInput, TOutput, TEvents, TSignals>(durableFn: DurableFunction<TInput, TOutput, TEvents, TSignals>, options: StartOptions<TInput, TSignals, TOutput>) => 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.
@@ -119,14 +223,28 @@ interface BDurableAPI {
      * @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>;
+    sendEvent: <TInput, TOutput, TWorkflowEvents, TSignals, K extends keyof TWorkflowEvents>(durableFn: DurableFunction<TInput, TOutput, TWorkflowEvents, TSignals>, workflowId: string, eventName: K, payload: TWorkflowEvents[K]) => Promise<void>;
+    /**
+     * Obtiene un "handle" para una instancia de workflow existente, permitiendo suscribirse a sus señales.
+     * @param durableFn La definición del workflow. Se usa para la inferencia de tipos de las señales.
+     * @param workflowId El ID de la instancia del workflow.
+     * @returns Un WorkflowHandle para la instancia especificada.
+     */
+    getWorkflowHandle: <TInput, TOutput, TEvents, TSignals>(durableFn: DurableFunction<TInput, TOutput, TEvents, TSignals>, workflowId: string) => WorkflowHandle<TSignals, TOutput>;
 }
 interface InitializeOptions {
-    durableFunctions: Map<string, DurableFunction<unknown, unknown>>;
+    durableFunctions: Map<string, DurableFunction<unknown, unknown, unknown, unknown>>;
     sourceRoot: string;
     redisClient: Redis;
     blockingRedisClient: Redis;
+    /**
+     * NUEVO: Período de retención para workflows completados/fallidos en Redis.
+     * Ejemplo: '7 days', '2h'. Si no se especifica, los workflows se guardan para siempre.
+     */
+    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 StartOptions, type StartedWorkflowHandle, WorkflowCancellationError, type WorkflowContext, type WorkflowHandle, type WorkflowSignal, type WorkflowState, type WorkflowStateInfo, bDurable, bDurableInitialize };