@tanstack/ai-client 0.20.0 → 0.22.0

package/dist/esm/chat-client.d.ts

@@ -1,6 +1,6 @@
 import { AnyClientTool, ModelMessage, StreamChunk } from '@tanstack/ai/client';
 import { ConnectionAdapter } from './connection-adapters.js';
-import { ChatClientOptions, ChatClientState, ChatFetcher, ConnectionStatus, MultimodalContent, UIMessage } from './types.js';
+import { ChatClientOptions, ChatClientState, ChatFetcher, ConnectionStatus, MultimodalContent, QueueOption, QueueStrategy, QueuedMessage, SendMessageOptions, UIMessage, WhenBusy } from './types.js';
 type ChatClientUpdateOptionsWithoutContext<TTools extends ReadonlyArray<AnyClientTool>> = {
     connection?: ConnectionAdapter;
     fetcher?: ChatFetcher;
@@ -8,6 +8,7 @@ type ChatClientUpdateOptionsWithoutContext<TTools extends ReadonlyArray<AnyClien
     body?: Record<string, any>;
     forwardedProps?: Record<string, any>;
     tools?: TTools;
+    queue?: QueueOption;
     onResponse?: (response?: Response) => void | Promise<void>;
     onChunk?: (chunk: StreamChunk) => void;
     onFinish?: (message: UIMessage) => void;
@@ -15,6 +16,7 @@ type ChatClientUpdateOptionsWithoutContext<TTools extends ReadonlyArray<AnyClien
     onSubscriptionChange?: (isSubscribed: boolean) => void;
     onConnectionStatusChange?: (status: ConnectionStatus) => void;
     onSessionGeneratingChange?: (isGenerating: boolean) => void;
+    onQueueChange?: (queue: Array<QueuedMessage>) => void;
     onCustomEvent?: (eventType: string, data: unknown, context: {
         toolCallId?: string;
     }) => void;
@@ -26,6 +28,14 @@ type ClientToolResult = {
     state?: 'output-available' | 'output-error';
     errorText?: string;
 };
+export interface NormalizedQueueConfig {
+    whenBusy: WhenBusy;
+    drain: 'fifo' | 'batch';
+    onOverflow: 'reject' | 'drop-oldest';
+    maxSize?: number;
+    strategy?: QueueStrategy;
+}
+export declare function normalizeQueueOption(option: QueueOption | undefined): NormalizedQueueConfig;
 export declare class ChatClient<TTools extends ReadonlyArray<AnyClientTool> = any, TContext = unknown> {
     private readonly processor;
     private connection;
@@ -37,6 +47,31 @@ export declare class ChatClient<TTools extends ReadonlyArray<AnyClientTool> = an
     private forwardedPropsOption;
     private context;
     private pendingMessageBody;
+    private queueConfig;
+    private messageQueue;
+    /**
+     * True from the moment `sendMessage` claims the client until its
+     * `streamResponse` settles. Closes the race where concurrent callers both
+     * see `isLoading === false`, both append a user message, and only one stream
+     * actually runs (leaving stranded user messages with no reply).
+     */
+    private sendInFlight;
+    /**
+     * True while `drainQueue` is delivering queued messages. Concurrent
+     * `sendMessage` calls during a drain are treated as busy and follow
+     * `whenBusy` (default: queue).
+     */
+    private messageQueueDraining;
+    /**
+     * Set by `whenBusy: 'interrupt'` so an in-progress FIFO drain loop stops
+     * before starting the next queued item (the interrupting send owns the client).
+     */
+    private stopMessageQueueDrain;
+    /**
+     * Sync claim held for the duration of `deliverMessage` so concurrent
+     * deliverers cannot both append a user message before only one stream runs.
+     */
+    private deliverClaim;
     private isLoading;
     private isSubscribed;
     private error;
@@ -119,6 +154,8 @@ export declare class ChatClient<TTools extends ReadonlyArray<AnyClientTool> = an
      *   - A MultimodalContent object with content array and optional custom ID
      * @param body - Optional body parameters to merge with the client's base body for this request.
      *               Uses shallow merge with per-message body taking priority.
+     * @param sendOptions - Per-call overrides, e.g. `{ whenBusy: 'interrupt' }` to
+     *                      override the configured queue policy for this one send.
      *
      * @example
      * ```ts
@@ -128,6 +165,9 @@ export declare class ChatClient<TTools extends ReadonlyArray<AnyClientTool> = an
      * // Text message with custom body params
      * await client.sendMessage('Hello!', { temperature: 0.7 })
      *
+     * // Per-call whenBusy override (body must still be the 2nd arg on ChatClient)
+     * await client.sendMessage('Urgent', undefined, { whenBusy: 'interrupt' })
+     *
      * // Multimodal message with image
      * await client.sendMessage({
      *   content: [
@@ -149,7 +189,24 @@ export declare class ChatClient<TTools extends ReadonlyArray<AnyClientTool> = an
      * )
      * ```
      */
-    sendMessage(content: string | MultimodalContent, body?: Record<string, any>): Promise<void>;
+    sendMessage(content: string | MultimodalContent, body?: Record<string, any>, sendOptions?: SendMessageOptions): Promise<void>;
+    /** True while a stream is active, a send is claiming the client, or the queue is draining. */
+    private isSendBusy;
+    private resolveBusyReason;
+    /**
+     * Append a user message and run the stream. Used by both direct sends and
+     * queue drains — callers are responsible for busy/queue policy.
+     *
+     * Claims delivery synchronously before appending so concurrent callers
+     * cannot both add a user message when only one stream can run.
+     */
+    private deliverMessage;
+    /**
+     * Resolve the effective action for a send that arrives while busy.
+     * The returned `id` is the id that will be stored if the action is `queue`.
+     */
+    private decideWhenBusy;
+    private enqueueMessage;
     /**
      * Normalize the message input to extract content and optional id.
      * Trims string content automatically.
@@ -223,6 +280,43 @@ export declare class ChatClient<TTools extends ReadonlyArray<AnyClientTool> = an
      * Get current messages
      */
     getMessages(): Array<UIMessage<TTools>>;
+    /**
+     * True when an interrupt (or another direct send) claimed the client during
+     * a drain. Read via a method so cross-await mutations are not constant-folded
+     * by control-flow analysis.
+     */
+    private shouldAbortMessageQueueDrain;
+    /**
+     * Deliver queued messages after a successful settle.
+     * - `batch`: merge everything currently queued into one send, looping so
+     *   messages enqueued during that batch stream are not stranded.
+     * - `fifo`: walk the queue in a loop, one stream at a time, until empty
+     *   (or until another send claims the client via interrupt).
+     *
+     * Uses `deliverMessage` directly so drains do not re-enter `sendMessage`'s
+     * busy/queue policy (which would re-queue items and strand the rest).
+     */
+    private drainQueue;
+    /**
+     * Drop any in-flight send claim and discard pending queued messages
+     * (stop / error / clear / unsubscribe / reload).
+     */
+    private discardPendingSends;
+    /**
+     * Get the current send queue (messages held while a stream was in flight).
+     */
+    getQueue(): Array<QueuedMessage>;
+    private emitQueueChange;
+    /**
+     * Remove a queued message by id before it drains.
+     */
+    cancelQueued(id: string): void;
+    /**
+     * Discard all pending queued messages (stop / error / clear / unsubscribe /
+     * reload). Does not send them. Emits `onQueueChange([])` when anything was
+     * removed.
+     */
+    private flushQueue;
     /**
      * Get loading state
      */

package/dist/esm/chat-client.js

@@ -13,6 +13,60 @@ function resolveTransport(transport) {
   if (fetcher) return fetcherToConnectionAdapter(fetcher);
   throw new Error("ChatClient: either `connection` or `fetcher` is required.");
 }
+function normalizeQueueOption(option) {
+  const base = {
+    whenBusy: "queue",
+    drain: "fifo",
+    onOverflow: "reject"
+  };
+  if (!option) return base;
+  if (typeof option === "string") return { ...base, whenBusy: option };
+  if (typeof option === "function") return { ...base, strategy: option };
+  const maxSize = option.maxSize;
+  if (maxSize !== void 0) {
+    if (!Number.isInteger(maxSize) || maxSize < 0) {
+      throw new Error(
+        "ChatClient: queue.maxSize must be a non-negative integer"
+      );
+    }
+  }
+  return {
+    whenBusy: option.whenBusy ?? "queue",
+    drain: option.drain ?? "fifo",
+    onOverflow: option.onOverflow ?? "reject",
+    ...maxSize !== void 0 ? { maxSize } : {}
+  };
+}
+function mergeQueuedMessages(items) {
+  const body = items.at(-1)?.body;
+  const stringContents = [];
+  for (const item of items) {
+    if (typeof item.content !== "string") {
+      break;
+    }
+    stringContents.push(item.content);
+  }
+  if (stringContents.length === items.length) {
+    return {
+      content: stringContents.join("\n"),
+      ...body !== void 0 ? { body } : {}
+    };
+  }
+  const parts = [];
+  for (const item of items) {
+    if (typeof item.content === "string") {
+      parts.push({ type: "text", content: item.content });
+    } else if (typeof item.content.content === "string") {
+      parts.push({ type: "text", content: item.content.content });
+    } else {
+      parts.push(...item.content.content);
+    }
+  }
+  return {
+    content: { content: parts },
+    ...body !== void 0 ? { body } : {}
+  };
+}
 class ChatClient {
   processor;
   connection;
@@ -31,6 +85,31 @@ class ChatClient {
   forwardedPropsOption = {};
   context = void 0;
   pendingMessageBody = void 0;
+  queueConfig;
+  messageQueue = [];
+  /**
+   * True from the moment `sendMessage` claims the client until its
+   * `streamResponse` settles. Closes the race where concurrent callers both
+   * see `isLoading === false`, both append a user message, and only one stream
+   * actually runs (leaving stranded user messages with no reply).
+   */
+  sendInFlight = false;
+  /**
+   * True while `drainQueue` is delivering queued messages. Concurrent
+   * `sendMessage` calls during a drain are treated as busy and follow
+   * `whenBusy` (default: queue).
+   */
+  messageQueueDraining = false;
+  /**
+   * Set by `whenBusy: 'interrupt'` so an in-progress FIFO drain loop stops
+   * before starting the next queued item (the interrupting send owns the client).
+   */
+  stopMessageQueueDrain = false;
+  /**
+   * Sync claim held for the duration of `deliverMessage` so concurrent
+   * deliverers cannot both append a user message before only one stream runs.
+   */
+  deliverClaim = false;
   isLoading = false;
   isSubscribed = false;
   error = void 0;
@@ -80,6 +159,7 @@ class ChatClient {
     this.bodyOption = options.body || {};
     this.forwardedPropsOption = options.forwardedProps || {};
     this.context = options.context;
+    this.queueConfig = normalizeQueueOption(options.queue);
     this.connection = normalizeConnectionAdapter(resolveTransport(options));
     this.clientToolsRef = { current: /* @__PURE__ */ new Map() };
     if (options.tools) {
@@ -113,6 +193,8 @@ class ChatClient {
         }),
         onSessionGeneratingChange: options.onSessionGeneratingChange || (() => {
         }),
+        onQueueChange: options.onQueueChange || (() => {
+        }),
         onCustomEvent: options.onCustomEvent || (() => {
         })
       }
@@ -383,6 +465,7 @@ class ChatClient {
       connectionStatus: this.connectionStatus,
       sessionGenerating: this.sessionGenerating,
       activeRunIds: Array.from(this.activeRunIds),
+      queue: this.getQueue(),
       ...this.error ? { error: this.error.message } : {}
     };
   }
@@ -412,6 +495,7 @@ class ChatClient {
     }
     this.resolveProcessing();
     this.setIsLoading(false);
+    this.deliverClaim = false;
     if (options?.setReadyStatus) {
       this.setStatus("ready");
     }
@@ -513,6 +597,8 @@ class ChatClient {
    *   - A MultimodalContent object with content array and optional custom ID
    * @param body - Optional body parameters to merge with the client's base body for this request.
    *               Uses shallow merge with per-message body taking priority.
+   * @param sendOptions - Per-call overrides, e.g. `{ whenBusy: 'interrupt' }` to
+   *                      override the configured queue policy for this one send.
    *
    * @example
    * ```ts
@@ -522,6 +608,9 @@ class ChatClient {
    * // Text message with custom body params
    * await client.sendMessage('Hello!', { temperature: 0.7 })
    *
+   * // Per-call whenBusy override (body must still be the 2nd arg on ChatClient)
+   * await client.sendMessage('Urgent', undefined, { whenBusy: 'interrupt' })
+   *
    * // Multimodal message with image
    * await client.sendMessage({
    *   content: [
@@ -543,20 +632,107 @@ class ChatClient {
    * )
    * ```
    */
-  async sendMessage(content, body) {
+  async sendMessage(content, body, sendOptions) {
     this.mountDevtools();
     const emptyMessage = typeof content === "string" && !content.trim();
-    if (emptyMessage || this.isLoading) {
+    if (emptyMessage) {
       return;
     }
-    const normalizedContent = this.normalizeMessageInput(content);
-    this.pendingMessageBody = body;
-    const userMessage = this.processor.addUserMessage(
-      normalizedContent.content,
-      normalizedContent.id
-    );
-    this.events.messageSent(userMessage.id, normalizedContent.content);
-    await this.streamResponse();
+    if (this.isSendBusy()) {
+      const { action, id } = this.decideWhenBusy(content, sendOptions);
+      if (action === "drop") {
+        return;
+      }
+      if (action === "queue") {
+        this.enqueueMessage(content, body, id);
+        return;
+      }
+      this.stopMessageQueueDrain = true;
+      this.sendInFlight = true;
+      this.cancelInFlightStream({ setReadyStatus: true });
+      this.resetSessionGenerating();
+    } else {
+      this.sendInFlight = true;
+    }
+    try {
+      await this.deliverMessage(content, body);
+    } finally {
+      this.sendInFlight = false;
+    }
+  }
+  /** True while a stream is active, a send is claiming the client, or the queue is draining. */
+  isSendBusy() {
+    return this.isLoading || this.sendInFlight || this.messageQueueDraining;
+  }
+  resolveBusyReason() {
+    if (this.isLoading) return "streaming";
+    if (this.messageQueueDraining) return "draining";
+    return "sendInFlight";
+  }
+  /**
+   * Append a user message and run the stream. Used by both direct sends and
+   * queue drains — callers are responsible for busy/queue policy.
+   *
+   * Claims delivery synchronously before appending so concurrent callers
+   * cannot both add a user message when only one stream can run.
+   */
+  async deliverMessage(content, body) {
+    if (this.isLoading || this.deliverClaim) {
+      return false;
+    }
+    this.deliverClaim = true;
+    try {
+      const normalizedContent = this.normalizeMessageInput(content);
+      this.pendingMessageBody = body;
+      const userMessage = this.processor.addUserMessage(
+        normalizedContent.content,
+        normalizedContent.id
+      );
+      this.events.messageSent(userMessage.id, normalizedContent.content);
+      return await this.streamResponse();
+    } finally {
+      this.deliverClaim = false;
+    }
+  }
+  /**
+   * Resolve the effective action for a send that arrives while busy.
+   * The returned `id` is the id that will be stored if the action is `queue`.
+   */
+  decideWhenBusy(content, sendOptions) {
+    const id = this.generateUniqueId("queued");
+    if (sendOptions?.whenBusy) {
+      return { action: sendOptions.whenBusy, id };
+    }
+    const { strategy, whenBusy } = this.queueConfig;
+    if (strategy) {
+      const { action } = strategy({
+        pending: {
+          id,
+          content,
+          createdAt: Date.now()
+        },
+        busyReason: this.resolveBusyReason(),
+        queued: this.getQueue()
+      });
+      return { action, id };
+    }
+    return { action: whenBusy, id };
+  }
+  enqueueMessage(content, body, id) {
+    const { maxSize, onOverflow } = this.queueConfig;
+    if (maxSize !== void 0 && this.messageQueue.length >= maxSize) {
+      if (onOverflow === "reject" || maxSize === 0) {
+        return;
+      }
+      this.messageQueue.shift();
+    }
+    this.messageQueue.push({
+      id: id ?? this.generateUniqueId("queued"),
+      content,
+      createdAt: Date.now(),
+      ...body !== void 0 ? { body } : {}
+    });
+    this.emitQueueChange();
   }
   /**
    * Normalize the message input to extract content and optional id.
@@ -602,6 +778,7 @@ class ChatClient {
     const runId = `run-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
     this.currentRunId = runId;
     this.setIsLoading(true);
+    this.deliverClaim = false;
     this.setStatus("submitted");
     this.setError(void 0);
     this.errorReportedGeneration = null;
@@ -740,10 +917,18 @@ class ChatClient {
               await this.checkForContinuation();
             } catch (error) {
               console.error("Failed to continue flow after tool result:", error);
+              await this.drainQueue();
+            }
+          } else {
+            if (this.status !== "ready") {
+              this.setStatus("ready");
+            }
+            if (!this.messageQueueDraining) {
+              await this.drainQueue();
             }
-          } else if (this.status !== "ready") {
-            this.setStatus("ready");
           }
+        } else {
+          this.flushQueue();
         }
       }
     }
@@ -774,6 +959,7 @@ class ChatClient {
       setReadyStatus: true,
       abortSubscription: true
     });
+    this.discardPendingSends();
     this.resetSessionGenerating();
     this.setIsSubscribed(false);
     this.setConnectionStatus("disconnected");
@@ -791,6 +977,7 @@ class ChatClient {
     if (this.isLoading) {
       this.cancelInFlightStream();
     }
+    this.discardPendingSends();
     this.events.reloaded(lastUserMessageIndex);
     this.processor.removeMessagesAfter(lastUserMessageIndex);
     this.devtoolsBridge.emitSnapshot();
@@ -802,6 +989,7 @@ class ChatClient {
   stop() {
     const hadLocalStream = this.abortController !== null;
     this.cancelInFlightStream({ setReadyStatus: true });
+    this.discardPendingSends();
     if (hadLocalStream) {
       this.resetSessionGenerating();
     }
@@ -826,6 +1014,7 @@ class ChatClient {
       this.persistor.beginClear();
     }
     this.processor.clearMessages();
+    this.discardPendingSends();
     this.persistor?.remove();
     this.setError(void 0);
     this.events.messagesCleared();
@@ -974,6 +1163,109 @@ class ChatClient {
   getMessages() {
     return this.processor.getMessages();
   }
+  /**
+   * True when an interrupt (or another direct send) claimed the client during
+   * a drain. Read via a method so cross-await mutations are not constant-folded
+   * by control-flow analysis.
+   */
+  shouldAbortMessageQueueDrain() {
+    return this.isLoading || this.stopMessageQueueDrain;
+  }
+  /**
+   * Deliver queued messages after a successful settle.
+   * - `batch`: merge everything currently queued into one send, looping so
+   *   messages enqueued during that batch stream are not stranded.
+   * - `fifo`: walk the queue in a loop, one stream at a time, until empty
+   *   (or until another send claims the client via interrupt).
+   *
+   * Uses `deliverMessage` directly so drains do not re-enter `sendMessage`'s
+   * busy/queue policy (which would re-queue items and strand the rest).
+   */
+  async drainQueue() {
+    if (this.messageQueueDraining || this.isLoading || this.messageQueue.length === 0) {
+      return;
+    }
+    this.messageQueueDraining = true;
+    this.stopMessageQueueDrain = false;
+    try {
+      if (this.queueConfig.drain === "batch") {
+        while (this.messageQueue.length > 0) {
+          if (this.shouldAbortMessageQueueDrain()) {
+            return;
+          }
+          const items = this.messageQueue.splice(0);
+          this.emitQueueChange();
+          const merged = mergeQueuedMessages(items);
+          const completed = await this.deliverMessage(
+            merged.content,
+            merged.body
+          );
+          if (!completed || this.shouldAbortMessageQueueDrain()) {
+            return;
+          }
+        }
+        return;
+      }
+      while (this.messageQueue.length > 0) {
+        if (this.shouldAbortMessageQueueDrain()) {
+          return;
+        }
+        const next = this.messageQueue.shift();
+        if (next === void 0) {
+          return;
+        }
+        this.emitQueueChange();
+        const completed = await this.deliverMessage(next.content, next.body);
+        if (!completed || this.shouldAbortMessageQueueDrain()) {
+          return;
+        }
+      }
+    } finally {
+      this.messageQueueDraining = false;
+      this.stopMessageQueueDrain = false;
+    }
+  }
+  /**
+   * Drop any in-flight send claim and discard pending queued messages
+   * (stop / error / clear / unsubscribe / reload).
+   */
+  discardPendingSends() {
+    this.sendInFlight = false;
+    this.flushQueue();
+  }
+  /**
+   * Get the current send queue (messages held while a stream was in flight).
+   */
+  getQueue() {
+    return this.messageQueue.map(({ id, content, createdAt }) => ({
+      id,
+      content,
+      createdAt
+    }));
+  }
+  emitQueueChange() {
+    this.callbacksRef.current.onQueueChange(this.getQueue());
+    this.devtoolsBridge.emitSnapshot();
+  }
+  /**
+   * Remove a queued message by id before it drains.
+   */
+  cancelQueued(id) {
+    const index = this.messageQueue.findIndex((m) => m.id === id);
+    if (index === -1) return;
+    this.messageQueue.splice(index, 1);
+    this.emitQueueChange();
+  }
+  /**
+   * Discard all pending queued messages (stop / error / clear / unsubscribe /
+   * reload). Does not send them. Emits `onQueueChange([])` when anything was
+   * removed.
+   */
+  flushQueue() {
+    if (this.messageQueue.length === 0) return;
+    this.messageQueue = [];
+    this.emitQueueChange();
+  }
   /**
    * Get loading state
    */
@@ -1060,6 +1352,9 @@ class ChatClient {
       }
       this.devtoolsBridge.notifyToolsChanged();
     }
+    if (options.queue !== void 0) {
+      this.queueConfig = normalizeQueueOption(options.queue);
+    }
     if (options.onResponse !== void 0) {
       this.callbacksRef.current.onResponse = options.onResponse;
     }
@@ -1081,6 +1376,9 @@ class ChatClient {
     if (options.onSessionGeneratingChange !== void 0) {
       this.callbacksRef.current.onSessionGeneratingChange = options.onSessionGeneratingChange;
     }
+    if (options.onQueueChange !== void 0) {
+      this.callbacksRef.current.onQueueChange = options.onQueueChange;
+    }
     if (options.onCustomEvent !== void 0) {
       this.callbacksRef.current.onCustomEvent = options.onCustomEvent;
     }
@@ -1092,6 +1390,7 @@ class ChatClient {
   }
 }
 export {
-  ChatClient
+  ChatClient,
+  normalizeQueueOption
 };
 //# sourceMappingURL=chat-client.js.map