@rivetkit/workflow-engine 2.1.0-rc.1 → 2.1.0

package/dist/tsup/index.d.cts

@@ -181,8 +181,6 @@ interface WorkflowQueueNextOptions {
      * If omitted, receives from all queue names.
      */
     names?: readonly string[];
-    /** Maximum number of messages to receive. Defaults to 1. */
-    count?: number;
     /**
      * Timeout in milliseconds.
      * Omit to wait indefinitely.
@@ -191,6 +189,13 @@ interface WorkflowQueueNextOptions {
     /** Whether returned messages must be manually completed. */
     completable?: boolean;
 }
+/**
+ * Options for receiving a batch of queue messages in workflows.
+ */
+interface WorkflowQueueNextBatchOptions extends WorkflowQueueNextOptions {
+    /** Maximum number of messages to receive. Defaults to 1. */
+    count?: number;
+}
 /**
  * Message returned by workflow queue operations.
  */
@@ -205,7 +210,8 @@ interface WorkflowQueueMessage<TBody = unknown> {
  * Workflow queue interface.
  */
 interface WorkflowQueue {
-    next<TBody = unknown>(name: string, opts?: WorkflowQueueNextOptions): Promise<Array<WorkflowQueueMessage<TBody>>>;
+    next<TBody = unknown>(name: string, opts?: WorkflowQueueNextOptions): Promise<WorkflowQueueMessage<TBody>>;
+    nextBatch<TBody = unknown>(name: string, opts?: WorkflowQueueNextBatchOptions): Promise<Array<WorkflowQueueMessage<TBody>>>;
     send(name: string, body: unknown): Promise<void>;
 }
 /**
@@ -313,13 +319,20 @@ type LoopResult<S, T> = {
     break: true;
     value: T;
 };
+/**
+ * Return type for a loop iteration callback.
+ *
+ * Stateless loops (state = undefined) may return void/undefined, which is treated as
+ * `Loop.continue(undefined)`.
+ */
+type LoopIterationResult<S, T> = Promise<LoopResult<S, T> | (S extends undefined ? void : never)>;
 /**
  * Configuration for a loop.
  */
 interface LoopConfig<S, T> {
     name: string;
     state?: S;
-    run: (ctx: WorkflowContextInterface, state: S) => Promise<LoopResult<S, T>>;
+    run: (ctx: WorkflowContextInterface, state: S) => LoopIterationResult<S, T>;
     commitInterval?: number;
     /** Trim loop history every N iterations. Defaults to commitInterval or 20. */
     historyEvery?: number;
@@ -345,7 +358,7 @@ interface WorkflowContextInterface {
     readonly queue: WorkflowQueue;
     step<T>(name: string, run: () => Promise<T>): Promise<T>;
     step<T>(config: StepConfig<T>): Promise<T>;
-    loop<T>(name: string, run: (ctx: WorkflowContextInterface) => Promise<LoopResult<undefined, T>>): Promise<T>;
+    loop<T>(name: string, run: (ctx: WorkflowContextInterface) => LoopIterationResult<undefined, T>): Promise<T>;
     loop<S, T>(config: LoopConfig<S, T>): Promise<T>;
     sleep(name: string, durationMs: number): Promise<void>;
     sleepUntil(name: string, timestampMs: number): Promise<void>;
@@ -623,7 +636,7 @@ declare class WorkflowContextImpl implements WorkflowContextInterface {
      */
     private executeStepRollback;
     private executeWithTimeout;
-    loop<S, T>(nameOrConfig: string | LoopConfig<S, T>, run?: (ctx: WorkflowContextInterface) => Promise<LoopResult<undefined, T>>): Promise<T>;
+    loop<S, T>(nameOrConfig: string | LoopConfig<S, T>, run?: (ctx: WorkflowContextInterface) => LoopIterationResult<undefined, T>): Promise<T>;
     private executeLoop;
     /**
      * Delete old loop iteration entries to save storage space.
@@ -647,7 +660,8 @@ declare class WorkflowContextImpl implements WorkflowContextInterface {
     private executeRollbackCheckpoint;
     private queueSend;
     private queueNext;
-    private executeQueueNext;
+    private queueNextBatch;
+    private executeQueueNextBatch;
     private normalizeQueueNames;
     private messageNamesLabel;
     private receiveMessagesNow;
@@ -881,4 +895,4 @@ declare const Loop: {
 
 declare function runWorkflow<TInput, TOutput>(workflowId: string, workflowFn: WorkflowFunction<TInput, TOutput>, input: TInput, driver: EngineDriver, options?: RunWorkflowOptions): WorkflowHandle<TOutput>;
 
-export { type BranchConfig, type BranchOutput, type BranchStatus, type BranchStatusType, CancelledError, CriticalError, DEFAULT_LOOP_COMMIT_INTERVAL, DEFAULT_LOOP_HISTORY_EVERY, DEFAULT_LOOP_HISTORY_KEEP, DEFAULT_MAX_RETRIES, DEFAULT_RETRY_BACKOFF_BASE, DEFAULT_RETRY_BACKOFF_MAX, DEFAULT_STEP_TIMEOUT, type EngineDriver, type Entry, EntryInProgressError, type EntryKind, type EntryKindType, type EntryMetadata, type EntryStatus, EvictedError, type History, HistoryDivergedError, type JoinEntry, JoinError, type KVEntry, type KVWrite, type Location, Loop, type LoopConfig, type LoopEntry, type LoopIterationMarker, type LoopResult, type Message, type MessageEntry, MessageWaitError, type NameIndex, type PathSegment, type RaceEntry, RaceError, type RemovedEntry, type RollbackCheckpointEntry, RollbackCheckpointError, type RollbackContextInterface, RollbackError, type RunWorkflowOptions, type SleepEntry, SleepError, type SleepState, type StepConfig, type StepEntry, StepExhaustedError, StepFailedError, type Storage, WorkflowContextImpl, type WorkflowContextInterface, type WorkflowEntryMetadataSnapshot, type WorkflowFunction, type WorkflowHandle, type WorkflowHistoryEntry, type WorkflowHistorySnapshot, type WorkflowMessageDriver, type WorkflowQueue, type WorkflowQueueMessage, type WorkflowQueueNextOptions, type WorkflowResult, type WorkflowRunMode, type WorkflowState, appendLoopIteration, appendName, createEntry, createHistorySnapshot, createStorage, deleteEntriesWithPrefix, emptyLocation, flush, generateId, getEntry, getOrCreateMetadata, isLocationPrefix, isLoopIterationMarker, loadMetadata, loadStorage, locationToKey, locationsEqual, parentLocation, registerName, resolveName, runWorkflow, setEntry };
+export { type BranchConfig, type BranchOutput, type BranchStatus, type BranchStatusType, CancelledError, CriticalError, DEFAULT_LOOP_COMMIT_INTERVAL, DEFAULT_LOOP_HISTORY_EVERY, DEFAULT_LOOP_HISTORY_KEEP, DEFAULT_MAX_RETRIES, DEFAULT_RETRY_BACKOFF_BASE, DEFAULT_RETRY_BACKOFF_MAX, DEFAULT_STEP_TIMEOUT, type EngineDriver, type Entry, EntryInProgressError, type EntryKind, type EntryKindType, type EntryMetadata, type EntryStatus, EvictedError, type History, HistoryDivergedError, type JoinEntry, JoinError, type KVEntry, type KVWrite, type Location, Loop, type LoopConfig, type LoopEntry, type LoopIterationMarker, type LoopResult, type Message, type MessageEntry, MessageWaitError, type NameIndex, type PathSegment, type RaceEntry, RaceError, type RemovedEntry, type RollbackCheckpointEntry, RollbackCheckpointError, type RollbackContextInterface, RollbackError, type RunWorkflowOptions, type SleepEntry, SleepError, type SleepState, type StepConfig, type StepEntry, StepExhaustedError, StepFailedError, type Storage, WorkflowContextImpl, type WorkflowContextInterface, type WorkflowEntryMetadataSnapshot, type WorkflowFunction, type WorkflowHandle, type WorkflowHistoryEntry, type WorkflowHistorySnapshot, type WorkflowMessageDriver, type WorkflowQueue, type WorkflowQueueMessage, type WorkflowQueueNextBatchOptions, type WorkflowQueueNextOptions, type WorkflowResult, type WorkflowRunMode, type WorkflowState, appendLoopIteration, appendName, createEntry, createHistorySnapshot, createStorage, deleteEntriesWithPrefix, emptyLocation, flush, generateId, getEntry, getOrCreateMetadata, isLocationPrefix, isLoopIterationMarker, loadMetadata, loadStorage, locationToKey, locationsEqual, parentLocation, registerName, resolveName, runWorkflow, setEntry };

package/dist/tsup/index.d.ts

@@ -181,8 +181,6 @@ interface WorkflowQueueNextOptions {
      * If omitted, receives from all queue names.
      */
     names?: readonly string[];
-    /** Maximum number of messages to receive. Defaults to 1. */
-    count?: number;
     /**
      * Timeout in milliseconds.
      * Omit to wait indefinitely.
@@ -191,6 +189,13 @@ interface WorkflowQueueNextOptions {
     /** Whether returned messages must be manually completed. */
     completable?: boolean;
 }
+/**
+ * Options for receiving a batch of queue messages in workflows.
+ */
+interface WorkflowQueueNextBatchOptions extends WorkflowQueueNextOptions {
+    /** Maximum number of messages to receive. Defaults to 1. */
+    count?: number;
+}
 /**
  * Message returned by workflow queue operations.
  */
@@ -205,7 +210,8 @@ interface WorkflowQueueMessage<TBody = unknown> {
  * Workflow queue interface.
  */
 interface WorkflowQueue {
-    next<TBody = unknown>(name: string, opts?: WorkflowQueueNextOptions): Promise<Array<WorkflowQueueMessage<TBody>>>;
+    next<TBody = unknown>(name: string, opts?: WorkflowQueueNextOptions): Promise<WorkflowQueueMessage<TBody>>;
+    nextBatch<TBody = unknown>(name: string, opts?: WorkflowQueueNextBatchOptions): Promise<Array<WorkflowQueueMessage<TBody>>>;
     send(name: string, body: unknown): Promise<void>;
 }
 /**
@@ -313,13 +319,20 @@ type LoopResult<S, T> = {
     break: true;
     value: T;
 };
+/**
+ * Return type for a loop iteration callback.
+ *
+ * Stateless loops (state = undefined) may return void/undefined, which is treated as
+ * `Loop.continue(undefined)`.
+ */
+type LoopIterationResult<S, T> = Promise<LoopResult<S, T> | (S extends undefined ? void : never)>;
 /**
  * Configuration for a loop.
  */
 interface LoopConfig<S, T> {
     name: string;
     state?: S;
-    run: (ctx: WorkflowContextInterface, state: S) => Promise<LoopResult<S, T>>;
+    run: (ctx: WorkflowContextInterface, state: S) => LoopIterationResult<S, T>;
     commitInterval?: number;
     /** Trim loop history every N iterations. Defaults to commitInterval or 20. */
     historyEvery?: number;
@@ -345,7 +358,7 @@ interface WorkflowContextInterface {
     readonly queue: WorkflowQueue;
     step<T>(name: string, run: () => Promise<T>): Promise<T>;
     step<T>(config: StepConfig<T>): Promise<T>;
-    loop<T>(name: string, run: (ctx: WorkflowContextInterface) => Promise<LoopResult<undefined, T>>): Promise<T>;
+    loop<T>(name: string, run: (ctx: WorkflowContextInterface) => LoopIterationResult<undefined, T>): Promise<T>;
     loop<S, T>(config: LoopConfig<S, T>): Promise<T>;
     sleep(name: string, durationMs: number): Promise<void>;
     sleepUntil(name: string, timestampMs: number): Promise<void>;
@@ -623,7 +636,7 @@ declare class WorkflowContextImpl implements WorkflowContextInterface {
      */
     private executeStepRollback;
     private executeWithTimeout;
-    loop<S, T>(nameOrConfig: string | LoopConfig<S, T>, run?: (ctx: WorkflowContextInterface) => Promise<LoopResult<undefined, T>>): Promise<T>;
+    loop<S, T>(nameOrConfig: string | LoopConfig<S, T>, run?: (ctx: WorkflowContextInterface) => LoopIterationResult<undefined, T>): Promise<T>;
     private executeLoop;
     /**
      * Delete old loop iteration entries to save storage space.
@@ -647,7 +660,8 @@ declare class WorkflowContextImpl implements WorkflowContextInterface {
     private executeRollbackCheckpoint;
     private queueSend;
     private queueNext;
-    private executeQueueNext;
+    private queueNextBatch;
+    private executeQueueNextBatch;
     private normalizeQueueNames;
     private messageNamesLabel;
     private receiveMessagesNow;
@@ -881,4 +895,4 @@ declare const Loop: {
 
 declare function runWorkflow<TInput, TOutput>(workflowId: string, workflowFn: WorkflowFunction<TInput, TOutput>, input: TInput, driver: EngineDriver, options?: RunWorkflowOptions): WorkflowHandle<TOutput>;
 
-export { type BranchConfig, type BranchOutput, type BranchStatus, type BranchStatusType, CancelledError, CriticalError, DEFAULT_LOOP_COMMIT_INTERVAL, DEFAULT_LOOP_HISTORY_EVERY, DEFAULT_LOOP_HISTORY_KEEP, DEFAULT_MAX_RETRIES, DEFAULT_RETRY_BACKOFF_BASE, DEFAULT_RETRY_BACKOFF_MAX, DEFAULT_STEP_TIMEOUT, type EngineDriver, type Entry, EntryInProgressError, type EntryKind, type EntryKindType, type EntryMetadata, type EntryStatus, EvictedError, type History, HistoryDivergedError, type JoinEntry, JoinError, type KVEntry, type KVWrite, type Location, Loop, type LoopConfig, type LoopEntry, type LoopIterationMarker, type LoopResult, type Message, type MessageEntry, MessageWaitError, type NameIndex, type PathSegment, type RaceEntry, RaceError, type RemovedEntry, type RollbackCheckpointEntry, RollbackCheckpointError, type RollbackContextInterface, RollbackError, type RunWorkflowOptions, type SleepEntry, SleepError, type SleepState, type StepConfig, type StepEntry, StepExhaustedError, StepFailedError, type Storage, WorkflowContextImpl, type WorkflowContextInterface, type WorkflowEntryMetadataSnapshot, type WorkflowFunction, type WorkflowHandle, type WorkflowHistoryEntry, type WorkflowHistorySnapshot, type WorkflowMessageDriver, type WorkflowQueue, type WorkflowQueueMessage, type WorkflowQueueNextOptions, type WorkflowResult, type WorkflowRunMode, type WorkflowState, appendLoopIteration, appendName, createEntry, createHistorySnapshot, createStorage, deleteEntriesWithPrefix, emptyLocation, flush, generateId, getEntry, getOrCreateMetadata, isLocationPrefix, isLoopIterationMarker, loadMetadata, loadStorage, locationToKey, locationsEqual, parentLocation, registerName, resolveName, runWorkflow, setEntry };
+export { type BranchConfig, type BranchOutput, type BranchStatus, type BranchStatusType, CancelledError, CriticalError, DEFAULT_LOOP_COMMIT_INTERVAL, DEFAULT_LOOP_HISTORY_EVERY, DEFAULT_LOOP_HISTORY_KEEP, DEFAULT_MAX_RETRIES, DEFAULT_RETRY_BACKOFF_BASE, DEFAULT_RETRY_BACKOFF_MAX, DEFAULT_STEP_TIMEOUT, type EngineDriver, type Entry, EntryInProgressError, type EntryKind, type EntryKindType, type EntryMetadata, type EntryStatus, EvictedError, type History, HistoryDivergedError, type JoinEntry, JoinError, type KVEntry, type KVWrite, type Location, Loop, type LoopConfig, type LoopEntry, type LoopIterationMarker, type LoopResult, type Message, type MessageEntry, MessageWaitError, type NameIndex, type PathSegment, type RaceEntry, RaceError, type RemovedEntry, type RollbackCheckpointEntry, RollbackCheckpointError, type RollbackContextInterface, RollbackError, type RunWorkflowOptions, type SleepEntry, SleepError, type SleepState, type StepConfig, type StepEntry, StepExhaustedError, StepFailedError, type Storage, WorkflowContextImpl, type WorkflowContextInterface, type WorkflowEntryMetadataSnapshot, type WorkflowFunction, type WorkflowHandle, type WorkflowHistoryEntry, type WorkflowHistorySnapshot, type WorkflowMessageDriver, type WorkflowQueue, type WorkflowQueueMessage, type WorkflowQueueNextBatchOptions, type WorkflowQueueNextOptions, type WorkflowResult, type WorkflowRunMode, type WorkflowState, appendLoopIteration, appendName, createEntry, createHistorySnapshot, createStorage, deleteEntriesWithPrefix, emptyLocation, flush, generateId, getEntry, getOrCreateMetadata, isLocationPrefix, isLoopIterationMarker, loadMetadata, loadStorage, locationToKey, locationsEqual, parentLocation, registerName, resolveName, runWorkflow, setEntry };

package/dist/tsup/index.js

@@ -43,7 +43,7 @@ import {
   resolveName,
   runWorkflow,
   setEntry
-} from "./chunk-JWHWQBZP.js";
+} from "./chunk-WA4TXB6Y.js";
 export {
   CancelledError,
   CriticalError,

package/dist/tsup/testing.cjs

@@ -47,7 +47,7 @@
 
 
 
-var _chunkGJ66YE5Wcjs = require('./chunk-GJ66YE5W.cjs');
+var _chunk6TTCEQL3cjs = require('./chunk-6TTCEQL3.cjs');
 
 // src/testing.ts
 var InMemoryWorkflowMessageDriver = class {
@@ -95,7 +95,7 @@ var InMemoryWorkflowMessageDriver = class {
   }
   async waitForMessages(messageNames, abortSignal) {
     if (abortSignal.aborted) {
-      throw new (0, _chunkGJ66YE5Wcjs.EvictedError)();
+      throw new (0, _chunk6TTCEQL3cjs.EvictedError)();
     }
     const nameSet = messageNames.length > 0 ? new Set(messageNames) : void 0;
     if (this.#messages.some(
@@ -116,7 +116,7 @@ var InMemoryWorkflowMessageDriver = class {
         },
         abortSignal,
         onAbort: () => {
-          waiter.reject(new (0, _chunkGJ66YE5Wcjs.EvictedError)());
+          waiter.reject(new (0, _chunk6TTCEQL3cjs.EvictedError)());
         }
       };
       abortSignal.addEventListener("abort", waiter.onAbort, { once: true });
@@ -154,48 +154,48 @@ var InMemoryDriver = (_class = class {constructor() { _class.prototype.__init.ca
   __init4() {this.workerPollInterval = 100}
   __init5() {this.messageDriver = this.#inMemoryMessageDriver}
   async get(key) {
-    await _chunkGJ66YE5Wcjs.sleep.call(void 0, this.latency);
-    const entry = this.kv.get(_chunkGJ66YE5Wcjs.keyToHex.call(void 0, key));
+    await _chunk6TTCEQL3cjs.sleep.call(void 0, this.latency);
+    const entry = this.kv.get(_chunk6TTCEQL3cjs.keyToHex.call(void 0, key));
     return _nullishCoalesce((entry == null ? void 0 : entry.value), () => ( null));
   }
   async set(key, value) {
-    await _chunkGJ66YE5Wcjs.sleep.call(void 0, this.latency);
-    this.kv.set(_chunkGJ66YE5Wcjs.keyToHex.call(void 0, key), { key, value });
+    await _chunk6TTCEQL3cjs.sleep.call(void 0, this.latency);
+    this.kv.set(_chunk6TTCEQL3cjs.keyToHex.call(void 0, key), { key, value });
   }
   async delete(key) {
-    await _chunkGJ66YE5Wcjs.sleep.call(void 0, this.latency);
-    this.kv.delete(_chunkGJ66YE5Wcjs.keyToHex.call(void 0, key));
+    await _chunk6TTCEQL3cjs.sleep.call(void 0, this.latency);
+    this.kv.delete(_chunk6TTCEQL3cjs.keyToHex.call(void 0, key));
   }
   async deletePrefix(prefix) {
-    await _chunkGJ66YE5Wcjs.sleep.call(void 0, this.latency);
+    await _chunk6TTCEQL3cjs.sleep.call(void 0, this.latency);
     for (const [hexKey, entry] of this.kv) {
-      if (_chunkGJ66YE5Wcjs.keyStartsWith.call(void 0, entry.key, prefix)) {
+      if (_chunk6TTCEQL3cjs.keyStartsWith.call(void 0, entry.key, prefix)) {
         this.kv.delete(hexKey);
       }
     }
   }
   async list(prefix) {
-    await _chunkGJ66YE5Wcjs.sleep.call(void 0, this.latency);
+    await _chunk6TTCEQL3cjs.sleep.call(void 0, this.latency);
     const results = [];
     for (const entry of this.kv.values()) {
-      if (_chunkGJ66YE5Wcjs.keyStartsWith.call(void 0, entry.key, prefix)) {
+      if (_chunk6TTCEQL3cjs.keyStartsWith.call(void 0, entry.key, prefix)) {
         results.push({ key: entry.key, value: entry.value });
       }
     }
-    return results.sort((a, b) => _chunkGJ66YE5Wcjs.compareKeys.call(void 0, a.key, b.key));
+    return results.sort((a, b) => _chunk6TTCEQL3cjs.compareKeys.call(void 0, a.key, b.key));
   }
   async batch(writes) {
-    await _chunkGJ66YE5Wcjs.sleep.call(void 0, this.latency);
+    await _chunk6TTCEQL3cjs.sleep.call(void 0, this.latency);
     for (const { key, value } of writes) {
-      this.kv.set(_chunkGJ66YE5Wcjs.keyToHex.call(void 0, key), { key, value });
+      this.kv.set(_chunk6TTCEQL3cjs.keyToHex.call(void 0, key), { key, value });
     }
   }
   async setAlarm(workflowId, wakeAt) {
-    await _chunkGJ66YE5Wcjs.sleep.call(void 0, this.latency);
+    await _chunk6TTCEQL3cjs.sleep.call(void 0, this.latency);
     this.alarms.set(workflowId, wakeAt);
   }
   async clearAlarm(workflowId) {
-    await _chunkGJ66YE5Wcjs.sleep.call(void 0, this.latency);
+    await _chunk6TTCEQL3cjs.sleep.call(void 0, this.latency);
     this.alarms.delete(workflowId);
   }
   async waitForMessages(messageNames, abortSignal) {
@@ -206,7 +206,7 @@ var InMemoryDriver = (_class = class {constructor() { _class.prototype.__init.ca
     }
     while (true) {
       if (abortSignal.aborted) {
-        throw new (0, _chunkGJ66YE5Wcjs.EvictedError)();
+        throw new (0, _chunk6TTCEQL3cjs.EvictedError)();
       }
       const messages = await this.messageDriver.receiveMessages({
         names: messageNames.length > 0 ? messageNames : void 0,
@@ -216,7 +216,7 @@ var InMemoryDriver = (_class = class {constructor() { _class.prototype.__init.ca
       if (messages.length > 0) {
         return;
       }
-      await _chunkGJ66YE5Wcjs.sleep.call(void 0, Math.max(1, this.latency));
+      await _chunk6TTCEQL3cjs.sleep.call(void 0, Math.max(1, this.latency));
     }
   }
   /**
@@ -312,5 +312,5 @@ var InMemoryDriver = (_class = class {constructor() { _class.prototype.__init.ca
 
 
 
-exports.CancelledError = _chunkGJ66YE5Wcjs.CancelledError; exports.CriticalError = _chunkGJ66YE5Wcjs.CriticalError; exports.DEFAULT_LOOP_COMMIT_INTERVAL = _chunkGJ66YE5Wcjs.DEFAULT_LOOP_COMMIT_INTERVAL; exports.DEFAULT_LOOP_HISTORY_EVERY = _chunkGJ66YE5Wcjs.DEFAULT_LOOP_HISTORY_EVERY; exports.DEFAULT_LOOP_HISTORY_KEEP = _chunkGJ66YE5Wcjs.DEFAULT_LOOP_HISTORY_KEEP; exports.DEFAULT_MAX_RETRIES = _chunkGJ66YE5Wcjs.DEFAULT_MAX_RETRIES; exports.DEFAULT_RETRY_BACKOFF_BASE = _chunkGJ66YE5Wcjs.DEFAULT_RETRY_BACKOFF_BASE; exports.DEFAULT_RETRY_BACKOFF_MAX = _chunkGJ66YE5Wcjs.DEFAULT_RETRY_BACKOFF_MAX; exports.DEFAULT_STEP_TIMEOUT = _chunkGJ66YE5Wcjs.DEFAULT_STEP_TIMEOUT; exports.EntryInProgressError = _chunkGJ66YE5Wcjs.EntryInProgressError; exports.EvictedError = _chunkGJ66YE5Wcjs.EvictedError; exports.HistoryDivergedError = _chunkGJ66YE5Wcjs.HistoryDivergedError; exports.InMemoryDriver = InMemoryDriver; exports.JoinError = _chunkGJ66YE5Wcjs.JoinError; exports.Loop = _chunkGJ66YE5Wcjs.Loop; exports.MessageWaitError = _chunkGJ66YE5Wcjs.MessageWaitError; exports.RaceError = _chunkGJ66YE5Wcjs.RaceError; exports.RollbackCheckpointError = _chunkGJ66YE5Wcjs.RollbackCheckpointError; exports.RollbackError = _chunkGJ66YE5Wcjs.RollbackError; exports.SleepError = _chunkGJ66YE5Wcjs.SleepError; exports.StepExhaustedError = _chunkGJ66YE5Wcjs.StepExhaustedError; exports.StepFailedError = _chunkGJ66YE5Wcjs.StepFailedError; exports.WorkflowContextImpl = _chunkGJ66YE5Wcjs.WorkflowContextImpl; exports.appendLoopIteration = _chunkGJ66YE5Wcjs.appendLoopIteration; exports.appendName = _chunkGJ66YE5Wcjs.appendName; exports.createEntry = _chunkGJ66YE5Wcjs.createEntry; exports.createHistorySnapshot = _chunkGJ66YE5Wcjs.createHistorySnapshot; exports.createStorage = _chunkGJ66YE5Wcjs.createStorage; exports.deleteEntriesWithPrefix = _chunkGJ66YE5Wcjs.deleteEntriesWithPrefix; exports.emptyLocation = _chunkGJ66YE5Wcjs.emptyLocation; exports.flush = _chunkGJ66YE5Wcjs.flush; exports.generateId = _chunkGJ66YE5Wcjs.generateId; exports.getEntry = _chunkGJ66YE5Wcjs.getEntry; exports.getOrCreateMetadata = _chunkGJ66YE5Wcjs.getOrCreateMetadata; exports.isLocationPrefix = _chunkGJ66YE5Wcjs.isLocationPrefix; exports.isLoopIterationMarker = _chunkGJ66YE5Wcjs.isLoopIterationMarker; exports.loadMetadata = _chunkGJ66YE5Wcjs.loadMetadata; exports.loadStorage = _chunkGJ66YE5Wcjs.loadStorage; exports.locationToKey = _chunkGJ66YE5Wcjs.locationToKey; exports.locationsEqual = _chunkGJ66YE5Wcjs.locationsEqual; exports.parentLocation = _chunkGJ66YE5Wcjs.parentLocation; exports.registerName = _chunkGJ66YE5Wcjs.registerName; exports.resolveName = _chunkGJ66YE5Wcjs.resolveName; exports.runWorkflow = _chunkGJ66YE5Wcjs.runWorkflow; exports.setEntry = _chunkGJ66YE5Wcjs.setEntry;
+exports.CancelledError = _chunk6TTCEQL3cjs.CancelledError; exports.CriticalError = _chunk6TTCEQL3cjs.CriticalError; exports.DEFAULT_LOOP_COMMIT_INTERVAL = _chunk6TTCEQL3cjs.DEFAULT_LOOP_COMMIT_INTERVAL; exports.DEFAULT_LOOP_HISTORY_EVERY = _chunk6TTCEQL3cjs.DEFAULT_LOOP_HISTORY_EVERY; exports.DEFAULT_LOOP_HISTORY_KEEP = _chunk6TTCEQL3cjs.DEFAULT_LOOP_HISTORY_KEEP; exports.DEFAULT_MAX_RETRIES = _chunk6TTCEQL3cjs.DEFAULT_MAX_RETRIES; exports.DEFAULT_RETRY_BACKOFF_BASE = _chunk6TTCEQL3cjs.DEFAULT_RETRY_BACKOFF_BASE; exports.DEFAULT_RETRY_BACKOFF_MAX = _chunk6TTCEQL3cjs.DEFAULT_RETRY_BACKOFF_MAX; exports.DEFAULT_STEP_TIMEOUT = _chunk6TTCEQL3cjs.DEFAULT_STEP_TIMEOUT; exports.EntryInProgressError = _chunk6TTCEQL3cjs.EntryInProgressError; exports.EvictedError = _chunk6TTCEQL3cjs.EvictedError; exports.HistoryDivergedError = _chunk6TTCEQL3cjs.HistoryDivergedError; exports.InMemoryDriver = InMemoryDriver; exports.JoinError = _chunk6TTCEQL3cjs.JoinError; exports.Loop = _chunk6TTCEQL3cjs.Loop; exports.MessageWaitError = _chunk6TTCEQL3cjs.MessageWaitError; exports.RaceError = _chunk6TTCEQL3cjs.RaceError; exports.RollbackCheckpointError = _chunk6TTCEQL3cjs.RollbackCheckpointError; exports.RollbackError = _chunk6TTCEQL3cjs.RollbackError; exports.SleepError = _chunk6TTCEQL3cjs.SleepError; exports.StepExhaustedError = _chunk6TTCEQL3cjs.StepExhaustedError; exports.StepFailedError = _chunk6TTCEQL3cjs.StepFailedError; exports.WorkflowContextImpl = _chunk6TTCEQL3cjs.WorkflowContextImpl; exports.appendLoopIteration = _chunk6TTCEQL3cjs.appendLoopIteration; exports.appendName = _chunk6TTCEQL3cjs.appendName; exports.createEntry = _chunk6TTCEQL3cjs.createEntry; exports.createHistorySnapshot = _chunk6TTCEQL3cjs.createHistorySnapshot; exports.createStorage = _chunk6TTCEQL3cjs.createStorage; exports.deleteEntriesWithPrefix = _chunk6TTCEQL3cjs.deleteEntriesWithPrefix; exports.emptyLocation = _chunk6TTCEQL3cjs.emptyLocation; exports.flush = _chunk6TTCEQL3cjs.flush; exports.generateId = _chunk6TTCEQL3cjs.generateId; exports.getEntry = _chunk6TTCEQL3cjs.getEntry; exports.getOrCreateMetadata = _chunk6TTCEQL3cjs.getOrCreateMetadata; exports.isLocationPrefix = _chunk6TTCEQL3cjs.isLocationPrefix; exports.isLoopIterationMarker = _chunk6TTCEQL3cjs.isLoopIterationMarker; exports.loadMetadata = _chunk6TTCEQL3cjs.loadMetadata; exports.loadStorage = _chunk6TTCEQL3cjs.loadStorage; exports.locationToKey = _chunk6TTCEQL3cjs.locationToKey; exports.locationsEqual = _chunk6TTCEQL3cjs.locationsEqual; exports.parentLocation = _chunk6TTCEQL3cjs.parentLocation; exports.registerName = _chunk6TTCEQL3cjs.registerName; exports.resolveName = _chunk6TTCEQL3cjs.resolveName; exports.runWorkflow = _chunk6TTCEQL3cjs.runWorkflow; exports.setEntry = _chunk6TTCEQL3cjs.setEntry;
 //# sourceMappingURL=testing.cjs.map

package/dist/tsup/testing.d.cts

@@ -1,5 +1,5 @@
 import { EngineDriver, WorkflowMessageDriver, KVEntry, KVWrite } from './index.cjs';
-export { BranchConfig, BranchOutput, BranchStatus, BranchStatusType, CancelledError, CriticalError, DEFAULT_LOOP_COMMIT_INTERVAL, DEFAULT_LOOP_HISTORY_EVERY, DEFAULT_LOOP_HISTORY_KEEP, DEFAULT_MAX_RETRIES, DEFAULT_RETRY_BACKOFF_BASE, DEFAULT_RETRY_BACKOFF_MAX, DEFAULT_STEP_TIMEOUT, Entry, EntryInProgressError, EntryKind, EntryKindType, EntryMetadata, EntryStatus, EvictedError, History, HistoryDivergedError, JoinEntry, JoinError, Location, Loop, LoopConfig, LoopEntry, LoopIterationMarker, LoopResult, Message, MessageEntry, MessageWaitError, NameIndex, PathSegment, RaceEntry, RaceError, RemovedEntry, RollbackCheckpointEntry, RollbackCheckpointError, RollbackContextInterface, RollbackError, RunWorkflowOptions, SleepEntry, SleepError, SleepState, StepConfig, StepEntry, StepExhaustedError, StepFailedError, Storage, WorkflowContextImpl, WorkflowContextInterface, WorkflowEntryMetadataSnapshot, WorkflowFunction, WorkflowHandle, WorkflowHistoryEntry, WorkflowHistorySnapshot, WorkflowQueue, WorkflowQueueMessage, WorkflowQueueNextOptions, WorkflowResult, WorkflowRunMode, WorkflowState, appendLoopIteration, appendName, createEntry, createHistorySnapshot, createStorage, deleteEntriesWithPrefix, emptyLocation, flush, generateId, getEntry, getOrCreateMetadata, isLocationPrefix, isLoopIterationMarker, loadMetadata, loadStorage, locationToKey, locationsEqual, parentLocation, registerName, resolveName, runWorkflow, setEntry } from './index.cjs';
+export { BranchConfig, BranchOutput, BranchStatus, BranchStatusType, CancelledError, CriticalError, DEFAULT_LOOP_COMMIT_INTERVAL, DEFAULT_LOOP_HISTORY_EVERY, DEFAULT_LOOP_HISTORY_KEEP, DEFAULT_MAX_RETRIES, DEFAULT_RETRY_BACKOFF_BASE, DEFAULT_RETRY_BACKOFF_MAX, DEFAULT_STEP_TIMEOUT, Entry, EntryInProgressError, EntryKind, EntryKindType, EntryMetadata, EntryStatus, EvictedError, History, HistoryDivergedError, JoinEntry, JoinError, Location, Loop, LoopConfig, LoopEntry, LoopIterationMarker, LoopResult, Message, MessageEntry, MessageWaitError, NameIndex, PathSegment, RaceEntry, RaceError, RemovedEntry, RollbackCheckpointEntry, RollbackCheckpointError, RollbackContextInterface, RollbackError, RunWorkflowOptions, SleepEntry, SleepError, SleepState, StepConfig, StepEntry, StepExhaustedError, StepFailedError, Storage, WorkflowContextImpl, WorkflowContextInterface, WorkflowEntryMetadataSnapshot, WorkflowFunction, WorkflowHandle, WorkflowHistoryEntry, WorkflowHistorySnapshot, WorkflowQueue, WorkflowQueueMessage, WorkflowQueueNextBatchOptions, WorkflowQueueNextOptions, WorkflowResult, WorkflowRunMode, WorkflowState, appendLoopIteration, appendName, createEntry, createHistorySnapshot, createStorage, deleteEntriesWithPrefix, emptyLocation, flush, generateId, getEntry, getOrCreateMetadata, isLocationPrefix, isLoopIterationMarker, loadMetadata, loadStorage, locationToKey, locationsEqual, parentLocation, registerName, resolveName, runWorkflow, setEntry } from './index.cjs';
 import 'pino';
 
 /**

package/dist/tsup/testing.d.ts

@@ -1,5 +1,5 @@
 import { EngineDriver, WorkflowMessageDriver, KVEntry, KVWrite } from './index.js';
-export { BranchConfig, BranchOutput, BranchStatus, BranchStatusType, CancelledError, CriticalError, DEFAULT_LOOP_COMMIT_INTERVAL, DEFAULT_LOOP_HISTORY_EVERY, DEFAULT_LOOP_HISTORY_KEEP, DEFAULT_MAX_RETRIES, DEFAULT_RETRY_BACKOFF_BASE, DEFAULT_RETRY_BACKOFF_MAX, DEFAULT_STEP_TIMEOUT, Entry, EntryInProgressError, EntryKind, EntryKindType, EntryMetadata, EntryStatus, EvictedError, History, HistoryDivergedError, JoinEntry, JoinError, Location, Loop, LoopConfig, LoopEntry, LoopIterationMarker, LoopResult, Message, MessageEntry, MessageWaitError, NameIndex, PathSegment, RaceEntry, RaceError, RemovedEntry, RollbackCheckpointEntry, RollbackCheckpointError, RollbackContextInterface, RollbackError, RunWorkflowOptions, SleepEntry, SleepError, SleepState, StepConfig, StepEntry, StepExhaustedError, StepFailedError, Storage, WorkflowContextImpl, WorkflowContextInterface, WorkflowEntryMetadataSnapshot, WorkflowFunction, WorkflowHandle, WorkflowHistoryEntry, WorkflowHistorySnapshot, WorkflowQueue, WorkflowQueueMessage, WorkflowQueueNextOptions, WorkflowResult, WorkflowRunMode, WorkflowState, appendLoopIteration, appendName, createEntry, createHistorySnapshot, createStorage, deleteEntriesWithPrefix, emptyLocation, flush, generateId, getEntry, getOrCreateMetadata, isLocationPrefix, isLoopIterationMarker, loadMetadata, loadStorage, locationToKey, locationsEqual, parentLocation, registerName, resolveName, runWorkflow, setEntry } from './index.js';
+export { BranchConfig, BranchOutput, BranchStatus, BranchStatusType, CancelledError, CriticalError, DEFAULT_LOOP_COMMIT_INTERVAL, DEFAULT_LOOP_HISTORY_EVERY, DEFAULT_LOOP_HISTORY_KEEP, DEFAULT_MAX_RETRIES, DEFAULT_RETRY_BACKOFF_BASE, DEFAULT_RETRY_BACKOFF_MAX, DEFAULT_STEP_TIMEOUT, Entry, EntryInProgressError, EntryKind, EntryKindType, EntryMetadata, EntryStatus, EvictedError, History, HistoryDivergedError, JoinEntry, JoinError, Location, Loop, LoopConfig, LoopEntry, LoopIterationMarker, LoopResult, Message, MessageEntry, MessageWaitError, NameIndex, PathSegment, RaceEntry, RaceError, RemovedEntry, RollbackCheckpointEntry, RollbackCheckpointError, RollbackContextInterface, RollbackError, RunWorkflowOptions, SleepEntry, SleepError, SleepState, StepConfig, StepEntry, StepExhaustedError, StepFailedError, Storage, WorkflowContextImpl, WorkflowContextInterface, WorkflowEntryMetadataSnapshot, WorkflowFunction, WorkflowHandle, WorkflowHistoryEntry, WorkflowHistorySnapshot, WorkflowQueue, WorkflowQueueMessage, WorkflowQueueNextBatchOptions, WorkflowQueueNextOptions, WorkflowResult, WorkflowRunMode, WorkflowState, appendLoopIteration, appendName, createEntry, createHistorySnapshot, createStorage, deleteEntriesWithPrefix, emptyLocation, flush, generateId, getEntry, getOrCreateMetadata, isLocationPrefix, isLoopIterationMarker, loadMetadata, loadStorage, locationToKey, locationsEqual, parentLocation, registerName, resolveName, runWorkflow, setEntry } from './index.js';
 import 'pino';
 
 /**

package/dist/tsup/testing.js

@@ -47,7 +47,7 @@ import {
   runWorkflow,
   setEntry,
   sleep
-} from "./chunk-JWHWQBZP.js";
+} from "./chunk-WA4TXB6Y.js";
 
 // src/testing.ts
 var InMemoryWorkflowMessageDriver = class {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rivetkit/workflow-engine",
-  "version": "2.1.0-rc.1",
+  "version": "2.1.0",
   "description": "Durable workflow engine with reentrant execution",
   "license": "Apache-2.0",
   "keywords": [

package/src/context.ts

@@ -40,6 +40,7 @@ import type {
 	EntryMetadata,
 	Location,
 	LoopConfig,
+	LoopIterationResult,
 	LoopResult,
 	Message,
 	RollbackContextInterface,
@@ -48,6 +49,7 @@ import type {
 	WorkflowContextInterface,
 	WorkflowQueue,
 	WorkflowQueueMessage,
+	WorkflowQueueNextBatchOptions,
 	WorkflowQueueNextOptions,
 	WorkflowMessageDriver,
 } from "./types.js";
@@ -145,6 +147,7 @@ export class WorkflowContextImpl implements WorkflowContextInterface {
 	get queue(): WorkflowQueue {
 		return {
 			next: async (name, opts) => await this.queueNext(name, opts),
+			nextBatch: async (name, opts) => await this.queueNextBatch(name, opts),
 			send: async (name, body) => await this.queueSend(name, body),
 		};
 	}
@@ -591,7 +594,7 @@ export class WorkflowContextImpl implements WorkflowContextInterface {
 		nameOrConfig: string | LoopConfig<S, T>,
 		run?: (
 			ctx: WorkflowContextInterface,
-		) => Promise<LoopResult<undefined, T>>,
+		) => LoopIterationResult<undefined, T>,
 	): Promise<T> {
 		this.assertNotInProgress();
 		this.checkEvicted();
@@ -708,7 +711,16 @@ export class WorkflowContextImpl implements WorkflowContextInterface {
 			const branchCtx = this.createBranch(iterationLocation);
 
 			// Execute iteration
-			const result = await config.run(branchCtx, state);
+			const iterationResult = await config.run(branchCtx, state);
+			if (iterationResult === undefined && state !== undefined) {
+				throw new Error(
+					`Loop "${config.name}" returned undefined for a stateful iteration. Return Loop.continue(state) or Loop.break(value).`,
+				);
+			}
+			const result =
+				iterationResult === undefined
+					? ({ continue: true, state } as LoopResult<S, T>)
+					: iterationResult;
 
 			// Validate branch completed cleanly
 			branchCtx.validateComplete();
@@ -975,21 +987,38 @@ export class WorkflowContextImpl implements WorkflowContextInterface {
 	private async queueNext<T>(
 		name: string,
 		opts?: WorkflowQueueNextOptions,
+	): Promise<WorkflowQueueMessage<T>> {
+		const messages = await this.queueNextBatch<T>(name, {
+			...(opts ?? {}),
+			count: 1,
+		});
+		const message = messages[0];
+		if (!message) {
+			throw new Error(
+				`queue.next("${name}") timed out before receiving a message. Use queue.nextBatch(...) for optional/time-limited reads.`,
+			);
+		}
+		return message;
+	}
+
+	private async queueNextBatch<T>(
+		name: string,
+		opts?: WorkflowQueueNextBatchOptions,
 	): Promise<Array<WorkflowQueueMessage<T>>> {
 		this.assertNotInProgress();
 		this.checkEvicted();
 
 		this.entryInProgress = true;
 		try {
-			return await this.executeQueueNext<T>(name, opts);
+			return await this.executeQueueNextBatch<T>(name, opts);
 		} finally {
 			this.entryInProgress = false;
 		}
 	}
 
-	private async executeQueueNext<T>(
+	private async executeQueueNextBatch<T>(
 		name: string,
-		opts?: WorkflowQueueNextOptions,
+		opts?: WorkflowQueueNextBatchOptions,
 	): Promise<Array<WorkflowQueueMessage<T>>> {
 		if (this.pendingCompletableMessageIds.size > 0) {
 			throw new Error(

package/src/index.ts

@@ -99,6 +99,7 @@ export type {
 	WorkflowHandle,
 	WorkflowQueue,
 	WorkflowQueueMessage,
+	WorkflowQueueNextBatchOptions,
 	WorkflowQueueNextOptions,
 	WorkflowMessageDriver,
 	WorkflowResult,

package/src/types.ts

@@ -212,8 +212,6 @@ export interface WorkflowQueueNextOptions {
 	 * If omitted, receives from all queue names.
 	 */
 	names?: readonly string[];
-	/** Maximum number of messages to receive. Defaults to 1. */
-	count?: number;
 	/**
 	 * Timeout in milliseconds.
 	 * Omit to wait indefinitely.
@@ -223,6 +221,16 @@ export interface WorkflowQueueNextOptions {
 	completable?: boolean;
 }
 
+/**
+ * Options for receiving a batch of queue messages in workflows.
+ */
+export interface WorkflowQueueNextBatchOptions
+	extends WorkflowQueueNextOptions
+{
+	/** Maximum number of messages to receive. Defaults to 1. */
+	count?: number;
+}
+
 /**
  * Message returned by workflow queue operations.
  */
@@ -241,6 +249,10 @@ export interface WorkflowQueue {
 	next<TBody = unknown>(
 		name: string,
 		opts?: WorkflowQueueNextOptions,
+	): Promise<WorkflowQueueMessage<TBody>>;
+	nextBatch<TBody = unknown>(
+		name: string,
+		opts?: WorkflowQueueNextBatchOptions,
 	): Promise<Array<WorkflowQueueMessage<TBody>>>;
 	send(name: string, body: unknown): Promise<void>;
 }
@@ -356,13 +368,26 @@ export type LoopResult<S, T> =
 	| { continue: true; state: S }
 	| { break: true; value: T };
 
+/**
+ * Return type for a loop iteration callback.
+ *
+ * Stateless loops (state = undefined) may return void/undefined, which is treated as
+ * `Loop.continue(undefined)`.
+ */
+export type LoopIterationResult<S, T> = Promise<
+	LoopResult<S, T> | (S extends undefined ? void : never)
+>;
+
 /**
  * Configuration for a loop.
  */
 export interface LoopConfig<S, T> {
 	name: string;
 	state?: S;
-	run: (ctx: WorkflowContextInterface, state: S) => Promise<LoopResult<S, T>>;
+	run: (
+		ctx: WorkflowContextInterface,
+		state: S,
+	) => LoopIterationResult<S, T>;
 	commitInterval?: number;
 	/** Trim loop history every N iterations. Defaults to commitInterval or 20. */
 	historyEvery?: number;
@@ -397,7 +422,7 @@ export interface WorkflowContextInterface {
 		name: string,
 		run: (
 			ctx: WorkflowContextInterface,
-		) => Promise<LoopResult<undefined, T>>,
+		) => LoopIterationResult<undefined, T>,
 	): Promise<T>;
 	loop<S, T>(config: LoopConfig<S, T>): Promise<T>;