@hotmeshio/hotmesh 0.12.1 → 0.14.0

package/build/services/durable/exporter.d.ts

@@ -54,7 +54,7 @@ declare class ExporterService {
      */
     export(jobId: string, options?: ExportOptions): Promise<DurableJobExport>;
     /**
-     * Export a workflow execution as a Temporal-compatible event history.
+     * Export a workflow execution as a structured event history.
      *
      * **Sparse mode** (default): transforms the main workflow's timeline
      * into a flat event list. No additional I/O beyond the initial export.
@@ -80,7 +80,7 @@ declare class ExporterService {
     private resolveSymbolField;
     /**
      * Pure transformation: convert a raw DurableJobExport into a
-     * Temporal-compatible WorkflowExecution event history.
+     * WorkflowExecution event history.
      */
     transformToExecution(raw: DurableJobExport, workflowId: string, workflowTopic: string, options: ExecutionExportOptions): WorkflowExecution;
     /**

package/build/services/durable/exporter.js

@@ -173,7 +173,7 @@ class ExporterService {
         return jobExport;
     }
     /**
-     * Export a workflow execution as a Temporal-compatible event history.
+     * Export a workflow execution as a structured event history.
      *
      * **Sparse mode** (default): transforms the main workflow's timeline
      * into a flat event list. No additional I/O beyond the initial export.
@@ -510,28 +510,43 @@ class ExporterService {
                 }
             }
         }
-        // ── 3. Stream-based fallback for unenriched activity events ──
-        // When job attributes have been pruned, recover inputs from worker_streams
+        // ── 3. Stream-based enrichment from worker_streams ──
+        // Fetches worker invocation messages to recover:
+        // - Workflow input arguments (for workflow_execution_started)
+        // - Activity inputs when job attributes have been pruned
         if (this.store.getStreamHistory) {
-            const unenrichedEvents = execution.events.filter((e) => (e.event_type === 'activity_task_scheduled' ||
+            const unenrichedActivityEvents = execution.events.filter((e) => (e.event_type === 'activity_task_scheduled' ||
                 e.event_type === 'activity_task_completed' ||
                 e.event_type === 'activity_task_failed') &&
                 e.attributes.input === undefined);
-            if (unenrichedEvents.length > 0) {
-                const streamHistory = await this.store.getStreamHistory(workflowId, {
-                    types: ['worker'],
-                });
+            const startedEvent = execution.events.find((e) => e.event_type === 'workflow_execution_started');
+            const startedNeedsInput = startedEvent &&
+                (!(startedEvent.attributes.input) ||
+                    Object.keys(startedEvent.attributes.input).length === 0);
+            if (unenrichedActivityEvents.length > 0 || startedNeedsInput) {
+                const streamHistory = await this.store.getStreamHistory(workflowId);
                 // Build a map of aid -> stream message data (the worker invocation inputs)
                 const streamInputsByAid = new Map();
                 for (const entry of streamHistory) {
-                    if (entry.msg_type === 'worker' && entry.data) {
+                    if (entry.data) {
                         const key = `${entry.aid}:${entry.dad || ''}`;
                         if (!streamInputsByAid.has(key)) {
                             streamInputsByAid.set(key, entry.data);
                         }
                     }
                 }
-                for (const evt of unenrichedEvents) {
+                // Enrich workflow_execution_started with input arguments from the
+                // first worker invocation message (aid="worker", data.arguments=[...])
+                if (startedNeedsInput) {
+                    const workerEntry = streamHistory.find((entry) => entry.aid === 'worker' &&
+                        entry.jid === workflowId &&
+                        entry.data?.arguments);
+                    if (workerEntry) {
+                        startedEvent.attributes.input = workerEntry.data.arguments;
+                    }
+                }
+                // Enrich unenriched activity events
+                for (const evt of unenrichedActivityEvents) {
                     const attrs = evt.attributes;
                     // Try matching by activity_type + dimensional address
                     const key = `${attrs.activity_type}:${attrs.timeline_key || ''}`;
@@ -571,7 +586,7 @@ class ExporterService {
     }
     /**
      * Pure transformation: convert a raw DurableJobExport into a
-     * Temporal-compatible WorkflowExecution event history.
+     * WorkflowExecution event history.
      */
     transformToExecution(raw, workflowId, workflowTopic, options) {
         const events = [];
@@ -761,7 +776,7 @@ class ExporterService {
         for (let i = 0; i < events.length; i++) {
             events[i].event_id = i + 1;
         }
-        // ── Back-references (Temporal-compatible) ────────────────────
+        // ── Back-references ────────────────────────────────────────
         const scheduledMap = new Map();
         const initiatedMap = new Map();
         for (const e of events) {

package/build/services/durable/handle.d.ts

@@ -4,28 +4,24 @@ import { JobInterruptOptions } from '../../types/job';
 import { StreamError } from '../../types/stream';
 import { ExporterService } from './exporter';
 /**
- * The WorkflowHandleService provides methods to interact with a running
- * workflow. This includes exporting the workflow, sending signals, and
- * querying the state of the workflow. It is instanced/accessed via the
- * Durable.Client class.
+ * Handle to a running or completed workflow execution. Returned by
+ * `client.workflow.start()` and `client.workflow.getHandle()`.
  *
  * @example
  * ```typescript
- * import { Client } from '@hotmeshio/hotmesh';
- * import { Client as Postgres } from 'pg';
- *
- * const client = new Client({ connection: {
- *   class: Postgres,
- *   options: { connectionString: 'postgres://user:pass@localhost:5432/db' }
- * }});
- *
  * const handle = await client.workflow.start({
- *  args: ['HotMesh'],
- *  taskQueue: 'hello-world',
+ *   args: ['order-123'],
+ *   taskQueue: 'orders',
+ *   workflowName: 'orderWorkflow',
+ *   workflowId: Durable.guid(),
  * });
  *
- * //perform actions like send a signal
- * await handle.signal('my-signal', { data: 'Hello' });
+ * // Await the final result
+ * const result = await handle.result();
+ *
+ * // Or interact while running
+ * await handle.signal('approval', { approved: true });
+ * await handle.cancel();
  * ```
  */
 export declare class WorkflowHandleService {
@@ -41,11 +37,12 @@ export declare class WorkflowHandleService {
      */
     constructor(hotMesh: HotMesh, workflowTopic: string, workflowId: string);
     /**
-     * Exports the workflow state to a JSON object.
+     * Exports the full workflow state (job hash, metadata, activity
+     * results) as a JSON object.
      */
     export(options?: ExportOptions): Promise<DurableJobExport>;
     /**
-     * Exports the workflow as a Temporal-like execution event history.
+     * Exports the workflow as an execution event history.
      *
      * **Sparse mode** (default): transforms the main workflow's timeline
      * into a flat event list with workflow lifecycle, activity, child workflow,
@@ -56,43 +53,64 @@ export declare class WorkflowHandleService {
      */
     exportExecution(options?: ExecutionExportOptions): Promise<WorkflowExecution>;
     /**
-     * Sends a signal to the workflow. This is a way to send
-     * a message to a workflow that is paused due to having
-     * executed `Durable.workflow.waitFor`. The workflow
-     * will awaken if no other signals are pending.
+     * Delivers a named signal to the workflow. If the workflow is paused
+     * on `Durable.workflow.condition(signalId)`, it resumes with the
+     * provided data.
+     *
+     * @param signalId - Matches the `signalId` passed to `condition()`.
+     * @param data - Payload delivered to the waiting workflow.
      */
     signal(signalId: string, data: Record<any, any>): Promise<void>;
     /**
-     * Returns the job state of the workflow. If the workflow has completed
-     * this is also the job output. If the workflow is still running, this
-     * is the current state of the job, but it may change depending upon
-     * the activities that remain.
+     * Returns the current workflow state. For a completed workflow this
+     * is the final output; for a running workflow it reflects the latest
+     * persisted state (may change as activities complete).
+     *
+     * @param metadata - If `true`, returns the full job envelope including
+     *   internal metadata alongside the data.
      */
     state(metadata?: boolean): Promise<Record<string, any>>;
     /**
-     * Returns the current search state of the workflow. This is
-     * different than the job state or individual activity state.
-     * Search state represents name/value pairs that were added
-     * to the workflow.
+     * Returns key-value pairs previously written via
+     * `Durable.workflow.search()` or `Durable.workflow.enrich()`.
+     *
+     * @param fields - The field names to retrieve.
      */
     queryState(fields: string[]): Promise<Record<string, any>>;
     /**
-     * Returns the current status of the workflow. This is a semaphore
-     * value that represents the current state of the workflow, where
-     * 0 is complete and a negative value represents that the flow was
-     * interrupted.
+     * Returns the workflow's numeric status code: `0` = completed,
+     * positive = still running, negative = interrupted/errored.
      */
     status(): Promise<number>;
     /**
-     * Interrupts a running workflow. Standard Job Completion tasks will
-     * run. Subscribers will be notified and the job hash will be expired.
+     * Immediately terminates the workflow. The job is marked as interrupted,
+     * subscribers are notified, and the job hash is expired. Unlike
+     * {@link cancel}, this does **not** give the workflow a chance to
+     * run cleanup code.
      */
-    interrupt(options?: JobInterruptOptions): Promise<string>;
+    terminate(options?: JobInterruptOptions): Promise<string>;
     /**
-     * Waits for the workflow to complete and returns the result. If
-     * the workflow response includes an error, this method will rethrow
-     * the error, including the stack trace if available.
-     * Wrap calls in a try/catch as necessary to avoid unhandled exceptions.
+     * Requests cooperative cancellation of the workflow. Unlike
+     * `terminate()` (which terminates immediately), `cancel()` sets
+     * a durable flag that the workflow detects at its next durable
+     * operation (`sleep`, `proxyActivities`, `executeChild`, etc.).
+     * The workflow receives a `CancelledFailure` error that it can
+     * catch to perform cleanup before exiting.
+     *
+     * ```typescript
+     * const handle = await client.workflow.start({ ... });
+     * await handle.cancel();
+     * // Workflow will throw CancelledFailure at its next durable operation
+     * ```
+     */
+    cancel(): Promise<void>;
+    /**
+     * Blocks until the workflow completes and returns the result. If the
+     * workflow failed, the error is rethrown (with stack trace) unless
+     * `throwOnError: false` is set, in which case the error object is
+     * returned directly.
+     *
+     * @template T - The workflow's return type.
      */
     result<T>(config?: {
         state?: boolean;

package/build/services/durable/handle.js

@@ -3,28 +3,24 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.WorkflowHandleService = void 0;
 const exporter_1 = require("./exporter");
 /**
- * The WorkflowHandleService provides methods to interact with a running
- * workflow. This includes exporting the workflow, sending signals, and
- * querying the state of the workflow. It is instanced/accessed via the
- * Durable.Client class.
+ * Handle to a running or completed workflow execution. Returned by
+ * `client.workflow.start()` and `client.workflow.getHandle()`.
  *
  * @example
  * ```typescript
- * import { Client } from '@hotmeshio/hotmesh';
- * import { Client as Postgres } from 'pg';
- *
- * const client = new Client({ connection: {
- *   class: Postgres,
- *   options: { connectionString: 'postgres://user:pass@localhost:5432/db' }
- * }});
- *
  * const handle = await client.workflow.start({
- *  args: ['HotMesh'],
- *  taskQueue: 'hello-world',
+ *   args: ['order-123'],
+ *   taskQueue: 'orders',
+ *   workflowName: 'orderWorkflow',
+ *   workflowId: Durable.guid(),
  * });
  *
- * //perform actions like send a signal
- * await handle.signal('my-signal', { data: 'Hello' });
+ * // Await the final result
+ * const result = await handle.result();
+ *
+ * // Or interact while running
+ * await handle.signal('approval', { approved: true });
+ * await handle.cancel();
  * ```
  */
 class WorkflowHandleService {
@@ -38,13 +34,14 @@ class WorkflowHandleService {
         this.exporter = new exporter_1.ExporterService(this.hotMesh.appId, this.hotMesh.engine.store, this.hotMesh.engine.logger);
     }
     /**
-     * Exports the workflow state to a JSON object.
+     * Exports the full workflow state (job hash, metadata, activity
+     * results) as a JSON object.
      */
     async export(options) {
         return this.exporter.export(this.workflowId, options);
     }
     /**
-     * Exports the workflow as a Temporal-like execution event history.
+     * Exports the workflow as an execution event history.
      *
      * **Sparse mode** (default): transforms the main workflow's timeline
      * into a flat event list with workflow lifecycle, activity, child workflow,
@@ -57,10 +54,12 @@ class WorkflowHandleService {
         return this.exporter.exportExecution(this.workflowId, this.workflowTopic, options);
     }
     /**
-     * Sends a signal to the workflow. This is a way to send
-     * a message to a workflow that is paused due to having
-     * executed `Durable.workflow.waitFor`. The workflow
-     * will awaken if no other signals are pending.
+     * Delivers a named signal to the workflow. If the workflow is paused
+     * on `Durable.workflow.condition(signalId)`, it resumes with the
+     * provided data.
+     *
+     * @param signalId - Matches the `signalId` passed to `condition()`.
+     * @param data - Payload delivered to the waiting workflow.
      */
     async signal(signalId, data) {
         await this.hotMesh.signal(`${this.hotMesh.appId}.wfs.signal`, {
@@ -69,10 +68,12 @@ class WorkflowHandleService {
         });
     }
     /**
-     * Returns the job state of the workflow. If the workflow has completed
-     * this is also the job output. If the workflow is still running, this
-     * is the current state of the job, but it may change depending upon
-     * the activities that remain.
+     * Returns the current workflow state. For a completed workflow this
+     * is the final output; for a running workflow it reflects the latest
+     * persisted state (may change as activities complete).
+     *
+     * @param metadata - If `true`, returns the full job envelope including
+     *   internal metadata alongside the data.
      */
     async state(metadata = false) {
         const state = await this.hotMesh.getState(`${this.hotMesh.appId}.execute`, this.workflowId);
@@ -82,35 +83,54 @@ class WorkflowHandleService {
         return metadata ? state : state.data;
     }
     /**
-     * Returns the current search state of the workflow. This is
-     * different than the job state or individual activity state.
-     * Search state represents name/value pairs that were added
-     * to the workflow.
+     * Returns key-value pairs previously written via
+     * `Durable.workflow.search()` or `Durable.workflow.enrich()`.
+     *
+     * @param fields - The field names to retrieve.
      */
     async queryState(fields) {
         return await this.hotMesh.getQueryState(this.workflowId, fields);
     }
     /**
-     * Returns the current status of the workflow. This is a semaphore
-     * value that represents the current state of the workflow, where
-     * 0 is complete and a negative value represents that the flow was
-     * interrupted.
+     * Returns the workflow's numeric status code: `0` = completed,
+     * positive = still running, negative = interrupted/errored.
      */
     async status() {
         return await this.hotMesh.getStatus(this.workflowId);
     }
     /**
-     * Interrupts a running workflow. Standard Job Completion tasks will
-     * run. Subscribers will be notified and the job hash will be expired.
+     * Immediately terminates the workflow. The job is marked as interrupted,
+     * subscribers are notified, and the job hash is expired. Unlike
+     * {@link cancel}, this does **not** give the workflow a chance to
+     * run cleanup code.
      */
-    async interrupt(options) {
+    async terminate(options) {
         return await this.hotMesh.interrupt(`${this.hotMesh.appId}.execute`, this.workflowId, options);
     }
     /**
-     * Waits for the workflow to complete and returns the result. If
-     * the workflow response includes an error, this method will rethrow
-     * the error, including the stack trace if available.
-     * Wrap calls in a try/catch as necessary to avoid unhandled exceptions.
+     * Requests cooperative cancellation of the workflow. Unlike
+     * `terminate()` (which terminates immediately), `cancel()` sets
+     * a durable flag that the workflow detects at its next durable
+     * operation (`sleep`, `proxyActivities`, `executeChild`, etc.).
+     * The workflow receives a `CancelledFailure` error that it can
+     * catch to perform cleanup before exiting.
+     *
+     * ```typescript
+     * const handle = await client.workflow.start({ ... });
+     * await handle.cancel();
+     * // Workflow will throw CancelledFailure at its next durable operation
+     * ```
+     */
+    async cancel() {
+        await this.hotMesh.cancel(this.workflowId);
+    }
+    /**
+     * Blocks until the workflow completes and returns the result. If the
+     * workflow failed, the error is rethrown (with stack trace) unless
+     * `throwOnError: false` is set, in which case the error object is
+     * returned directly.
+     *
+     * @template T - The workflow's return type.
      */
     async result(config) {
         const topic = `${this.hotMesh.appId}.executed.${this.workflowId}`;