ai-workflows 2.1.1 → 2.3.0

package/dist/durable-workflow.d.ts

@@ -0,0 +1,176 @@
+/**
+ * DurableWorkflow - Persistent workflow implementation using digital-objects
+ *
+ * Provides durable, recoverable workflows with:
+ * - Workflow state stored as Things
+ * - History and events stored as Actions
+ * - Automatic state recovery on restart
+ * - Graph-based dependency tracking
+ *
+ * @example
+ * ```typescript
+ * import { createMemoryProvider } from 'digital-objects'
+ * import { DurableWorkflow } from 'ai-workflows'
+ *
+ * const provider = createMemoryProvider()
+ * const workflow = new DurableWorkflow(provider)
+ *
+ * await workflow.initialize('my-workflow', $ => {
+ *   $.on.Order.created(async (order, $) => {
+ *     await $.send('Invoice.generate', { orderId: order.id })
+ *   })
+ * })
+ *
+ * await workflow.start()
+ * await workflow.send('Order.created', { id: 'order-1', total: 100 })
+ * ```
+ *
+ * @packageDocumentation
+ */
+import type { DigitalObjectsProvider } from 'digital-objects';
+import type { WorkflowContext, WorkflowState } from './types.js';
+import { type WorkflowThingData } from './digital-objects-adapter.js';
+/**
+ * Durable workflow state stored in digital-objects
+ */
+export interface DurableWorkflowState extends WorkflowThingData {
+    version: number;
+    createdAt: number;
+    updatedAt: number;
+}
+/**
+ * History entry stored as an Action
+ */
+export interface DurableHistoryEntry {
+    type: 'event' | 'schedule' | 'transition' | 'action';
+    name: string;
+    data?: unknown;
+}
+/**
+ * Options for DurableWorkflow
+ */
+export interface DurableWorkflowOptions {
+    /**
+     * Existing workflow instance ID to restore
+     */
+    instanceId?: string;
+    /**
+     * Auto-persist state changes immediately
+     * @default true
+     */
+    autoPersist?: boolean;
+    /**
+     * Initial context data
+     */
+    context?: Record<string, unknown>;
+}
+/**
+ * DurableWorkflow - A workflow implementation with persistent state
+ *
+ * Uses digital-objects as the backing store:
+ * - Workflow instance stored as a Thing
+ * - Events and history stored as Actions
+ * - State changes create audit trail
+ */
+export declare class DurableWorkflow {
+    private provider;
+    private db;
+    private instanceId;
+    private autoPersist;
+    private initialized;
+    private eventRegistry;
+    private scheduleRegistry;
+    private state;
+    private scheduleTimers;
+    private $;
+    /**
+     * Create a new DurableWorkflow
+     *
+     * @param provider - The digital-objects provider (MemoryProvider, NS, etc.)
+     * @param options - Configuration options
+     */
+    constructor(provider: DigitalObjectsProvider, options?: DurableWorkflowOptions);
+    /**
+     * Get the workflow instance ID
+     */
+    get id(): string;
+    /**
+     * Get the current workflow state
+     */
+    getState(): WorkflowState;
+    /**
+     * Initialize the workflow
+     *
+     * Creates or restores the workflow instance and runs the setup function
+     * to register event and schedule handlers.
+     *
+     * @param name - Workflow name for identification
+     * @param setup - Setup function that registers handlers using $
+     */
+    initialize(name: string, setup: ($: WorkflowContext) => void): Promise<void>;
+    /**
+     * Start the workflow (begin processing schedules)
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the workflow
+     */
+    stop(): Promise<void>;
+    /**
+     * Send an event to the workflow
+     */
+    send<T = unknown>(event: string, data: T): Promise<string>;
+    /**
+     * Destroy the workflow and clean up all resources
+     */
+    destroy(): Promise<void>;
+    /**
+     * Get the number of active timers
+     */
+    get timerCount(): number;
+    /**
+     * Get timer IDs for this workflow
+     */
+    getTimerIds(): string[];
+    /**
+     * Create the $ context
+     */
+    private createContext;
+    /**
+     * Create the $.on proxy
+     */
+    private createOnProxy;
+    /**
+     * Create the $.every proxy
+     */
+    private createEveryProxy;
+    /**
+     * Add history entry (persisted as Action)
+     */
+    private addHistory;
+    /**
+     * Persist current state to digital-objects
+     */
+    private persistState;
+    /**
+     * Deliver an event to matching handlers
+     */
+    private deliverEvent;
+    /**
+     * Execute an event and wait for result
+     */
+    private executeEvent;
+    /**
+     * Clean up timers
+     */
+    private cleanup;
+}
+/**
+ * Factory function to create a DurableWorkflow
+ *
+ * @param provider - The digital-objects provider
+ * @param options - Configuration options
+ * @returns A new DurableWorkflow instance
+ */
+export declare function createDurableWorkflow(provider: DigitalObjectsProvider, options?: DurableWorkflowOptions): DurableWorkflow;
+//# sourceMappingURL=durable-workflow.d.ts.map

package/dist/durable-workflow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"durable-workflow.d.ts","sourceRoot":"","sources":["../src/durable-workflow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAiB,MAAM,iBAAiB,CAAA;AAC5E,OAAO,KAAK,EACV,eAAe,EACf,aAAa,EAWd,MAAM,YAAY,CAAA;AAEnB,OAAO,EAEL,KAAK,iBAAiB,EAEvB,MAAM,8BAA8B,CAAA;AAoErC;;GAEG;AACH,MAAM,WAAW,oBAAqB,SAAQ,iBAAiB;IAC7D,OAAO,EAAE,MAAM,CAAA;IACf,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,OAAO,GAAG,UAAU,GAAG,YAAY,GAAG,QAAQ,CAAA;IACpD,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,OAAO,CAAA;CACf;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;OAEG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IAEnB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;IAErB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAClC;AAED;;;;;;;GAOG;AACH,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAAwB;IACxC,OAAO,CAAC,EAAE,CAAgC;IAC1C,OAAO,CAAC,UAAU,CAAQ;IAC1B,OAAO,CAAC,WAAW,CAAS;IAC5B,OAAO,CAAC,WAAW,CAAQ;IAG3B,OAAO,CAAC,aAAa,CAA0B;IAC/C,OAAO,CAAC,gBAAgB,CAA6B;IACrD,OAAO,CAAC,KAAK,CAA8C;IAC3D,OAAO,CAAC,cAAc,CAAuB;IAG7C,OAAO,CAAC,CAAC,CAAkB;IAE3B;;;;;OAKG;gBACS,QAAQ,EAAE,sBAAsB,EAAE,OAAO,GAAE,sBAA2B;IAWlF;;OAEG;IACH,IAAI,EAAE,IAAI,MAAM,CAEf;IAED;;OAEG;IACH,QAAQ,IAAI,aAAa;IAQzB;;;;;;;;OAQG;IACG,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC,EAAE,eAAe,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAqElF;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA4D5B;;OAEG;IACG,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAY3B;;OAEG;IACG,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IAahE;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAS9B;;OAEG;IACH,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED;;OAEG;IACH,WAAW,IAAI,MAAM,EAAE;IAQvB;;OAEG;IACH,OAAO,CAAC,aAAa;IAqErB;;OAEG;IACH,OAAO,CAAC,aAAa;IAuBrB;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAsExB;;OAEG;YACW,UAAU;IAqBxB;;OAEG;YACW,YAAY;IAO1B;;OAEG;YACW,YAAY;IA0B1B;;OAEG;YACW,YAAY;IAwC1B;;OAEG;IACH,OAAO,CAAC,OAAO;CAIhB;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,sBAAsB,EAChC,OAAO,CAAC,EAAE,sBAAsB,GAC/B,eAAe,CAEjB"}