@ai-sdk/provider-utils 4.0.4 → 4.0.6

package/src/create-tool-name-mapping.ts

@@ -0,0 +1,66 @@
+import {
+  LanguageModelV3FunctionTool,
+  LanguageModelV3ProviderTool,
+} from '@ai-sdk/provider';
+
+/**
+ * Interface for mapping between custom tool names and provider tool names.
+ */
+export interface ToolNameMapping {
+  /**
+   * Maps a custom tool name (used by the client) to the provider's tool name.
+   * If the custom tool name does not have a mapping, returns the input name.
+   *
+   * @param customToolName - The custom name of the tool defined by the client.
+   * @returns The corresponding provider tool name, or the input name if not mapped.
+   */
+  toProviderToolName: (customToolName: string) => string;
+
+  /**
+   * Maps a provider tool name to the custom tool name used by the client.
+   * If the provider tool name does not have a mapping, returns the input name.
+   *
+   * @param providerToolName - The name of the tool as understood by the provider.
+   * @returns The corresponding custom tool name, or the input name if not mapped.
+   */
+  toCustomToolName: (providerToolName: string) => string;
+}
+
+/**
+ * @param tools - Tools that were passed to the language model.
+ * @param providerToolNames - Maps the provider tool ids to the provider tool names.
+ */
+export function createToolNameMapping({
+  tools = [],
+  providerToolNames,
+}: {
+  /**
+   * Tools that were passed to the language model.
+   */
+  tools:
+    | Array<LanguageModelV3FunctionTool | LanguageModelV3ProviderTool>
+    | undefined;
+
+  /**
+   * Maps the provider tool ids to the provider tool names.
+   */
+  providerToolNames: Record<`${string}.${string}`, string>;
+}): ToolNameMapping {
+  const customToolNameToProviderToolName: Record<string, string> = {};
+  const providerToolNameToCustomToolName: Record<string, string> = {};
+
+  for (const tool of tools) {
+    if (tool.type === 'provider' && tool.id in providerToolNames) {
+      const providerToolName = providerToolNames[tool.id];
+      customToolNameToProviderToolName[tool.name] = providerToolName;
+      providerToolNameToCustomToolName[providerToolName] = tool.name;
+    }
+  }
+
+  return {
+    toProviderToolName: (customToolName: string) =>
+      customToolNameToProviderToolName[customToolName] ?? customToolName,
+    toCustomToolName: (providerToolName: string) =>
+      providerToolNameToCustomToolName[providerToolName] ?? providerToolName,
+  };
+}

package/src/delay.test.ts

@@ -0,0 +1,212 @@
+import { delay } from './delay';
+import { describe, beforeEach, afterEach, expect, it, vi } from 'vitest';
+
+describe('delay', () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  describe('basic delay functionality', () => {
+    it('should resolve after the specified delay', async () => {
+      const delayPromise = delay(1000);
+
+      // Promise should not be resolved immediately
+      let resolved = false;
+      delayPromise.then(() => {
+        resolved = true;
+      });
+
+      expect(resolved).toBe(false);
+
+      // Advance timers by less than the delay
+      await vi.advanceTimersByTimeAsync(500);
+      expect(resolved).toBe(false);
+
+      // Advance timers to complete the delay
+      await vi.advanceTimersByTimeAsync(500);
+      expect(resolved).toBe(true);
+
+      // Verify the promise resolves
+      await expect(delayPromise).resolves.toBeUndefined();
+    });
+
+    it('should resolve immediately when delayInMs is null', async () => {
+      const delayPromise = delay(null);
+      await expect(delayPromise).resolves.toBeUndefined();
+    });
+
+    it('should resolve immediately when delayInMs is undefined', async () => {
+      const delayPromise = delay(undefined);
+      await expect(delayPromise).resolves.toBeUndefined();
+    });
+
+    it('should resolve immediately when delayInMs is 0', async () => {
+      const delayPromise = delay(0);
+
+      // Even with 0 delay, setTimeout is used, so we need to advance timers
+      await vi.advanceTimersByTimeAsync(0);
+      await expect(delayPromise).resolves.toBeUndefined();
+    });
+  });
+
+  describe('abort signal functionality', () => {
+    it('should reject immediately if signal is already aborted', async () => {
+      const controller = new AbortController();
+      controller.abort();
+
+      const delayPromise = delay(1000, { abortSignal: controller.signal });
+
+      await expect(delayPromise).rejects.toThrow('Delay was aborted');
+      expect(vi.getTimerCount()).toBe(0); // No timer should be set
+    });
+
+    it('should reject when signal is aborted during delay', async () => {
+      const controller = new AbortController();
+      const delayPromise = delay(1000, { abortSignal: controller.signal });
+
+      // Advance time partially
+      await vi.advanceTimersByTimeAsync(500);
+
+      // Abort the signal
+      controller.abort();
+
+      await expect(delayPromise).rejects.toThrow('Delay was aborted');
+    });
+
+    it('should clean up timeout when aborted', async () => {
+      const controller = new AbortController();
+      const delayPromise = delay(1000, { abortSignal: controller.signal });
+
+      expect(vi.getTimerCount()).toBe(1);
+
+      controller.abort();
+
+      try {
+        await delayPromise;
+      } catch {
+        // Expected to throw
+      }
+
+      expect(vi.getTimerCount()).toBe(0);
+    });
+
+    it('should clean up event listener when delay completes normally', async () => {
+      const controller = new AbortController();
+      const addEventListenerSpy = vi.spyOn(
+        controller.signal,
+        'addEventListener',
+      );
+      const removeEventListenerSpy = vi.spyOn(
+        controller.signal,
+        'removeEventListener',
+      );
+
+      const delayPromise = delay(1000, { abortSignal: controller.signal });
+
+      expect(addEventListenerSpy).toHaveBeenCalledWith(
+        'abort',
+        expect.any(Function),
+      );
+
+      await vi.advanceTimersByTimeAsync(1000);
+      await delayPromise;
+
+      expect(removeEventListenerSpy).toHaveBeenCalledWith(
+        'abort',
+        expect.any(Function),
+      );
+    });
+
+    it('should work without signal option', async () => {
+      const delayPromise = delay(1000);
+
+      await vi.advanceTimersByTimeAsync(1000);
+      await expect(delayPromise).resolves.toBeUndefined();
+    });
+  });
+
+  describe('error handling', () => {
+    it('should create proper DOMException for abort', async () => {
+      const controller = new AbortController();
+      controller.abort();
+
+      const delayPromise = delay(1000, { abortSignal: controller.signal });
+
+      try {
+        await delayPromise;
+        expect.fail('Should have thrown');
+      } catch (error) {
+        expect(error).toBeInstanceOf(DOMException);
+        expect((error as DOMException).message).toBe('Delay was aborted');
+        expect((error as DOMException).name).toBe('AbortError');
+      }
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should handle very large delays', async () => {
+      const delayPromise = delay(Number.MAX_SAFE_INTEGER);
+
+      await vi.advanceTimersByTimeAsync(1000);
+      let resolved = false;
+      delayPromise.then(() => {
+        resolved = true;
+      });
+
+      expect(resolved).toBe(false);
+
+      // Fast forward to complete
+      await vi.advanceTimersByTimeAsync(1000);
+      await expect(delayPromise).resolves.toBeUndefined();
+    });
+
+    it('should handle negative delays (treated as 0)', async () => {
+      const delayPromise = delay(-100);
+
+      vi.advanceTimersByTime(0);
+      await expect(delayPromise).resolves.toBeUndefined();
+    });
+
+    it('should handle multiple delays simultaneously', async () => {
+      const delay1 = delay(100);
+      const delay2 = delay(200);
+      const delay3 = delay(300);
+
+      let resolved1 = false;
+      let resolved2 = false;
+      let resolved3 = false;
+
+      delay1.then(() => {
+        resolved1 = true;
+      });
+      delay2.then(() => {
+        resolved2 = true;
+      });
+      delay3.then(() => {
+        resolved3 = true;
+      });
+
+      // After 100ms, only first should resolve
+      await vi.advanceTimersByTimeAsync(100);
+      expect(resolved1).toBe(true);
+      expect(resolved2).toBe(false);
+      expect(resolved3).toBe(false);
+
+      // After 200ms, first two should resolve
+      await vi.advanceTimersByTimeAsync(100);
+      expect(resolved1).toBe(true);
+      expect(resolved2).toBe(true);
+      expect(resolved3).toBe(false);
+
+      // After 300ms, all should resolve
+      await vi.advanceTimersByTimeAsync(100);
+      expect(resolved1).toBe(true);
+      expect(resolved2).toBe(true);
+      expect(resolved3).toBe(true);
+    });
+  });
+});

package/src/delay.ts

@@ -0,0 +1,47 @@
+/**
+ * Creates a Promise that resolves after a specified delay
+ * @param delayInMs - The delay duration in milliseconds. If null or undefined, resolves immediately.
+ * @param signal - Optional AbortSignal to cancel the delay
+ * @returns A Promise that resolves after the specified delay
+ * @throws {DOMException} When the signal is aborted
+ */
+export async function delay(
+  delayInMs?: number | null,
+  options?: {
+    abortSignal?: AbortSignal;
+  },
+): Promise<void> {
+  if (delayInMs == null) {
+    return Promise.resolve();
+  }
+
+  const signal = options?.abortSignal;
+
+  return new Promise<void>((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(createAbortError());
+      return;
+    }
+
+    const timeoutId = setTimeout(() => {
+      cleanup();
+      resolve();
+    }, delayInMs);
+
+    const cleanup = () => {
+      clearTimeout(timeoutId);
+      signal?.removeEventListener('abort', onAbort);
+    };
+
+    const onAbort = () => {
+      cleanup();
+      reject(createAbortError());
+    };
+
+    signal?.addEventListener('abort', onAbort);
+  });
+}
+
+function createAbortError(): DOMException {
+  return new DOMException('Delay was aborted', 'AbortError');
+}

package/src/delayed-promise.test.ts

@@ -0,0 +1,132 @@
+import { DelayedPromise } from './delayed-promise';
+import { delay } from '@ai-sdk/provider-utils';
+import { describe, it, expect } from 'vitest';
+
+describe('DelayedPromise', () => {
+  it('should resolve when accessed after resolution', async () => {
+    const dp = new DelayedPromise<string>();
+    dp.resolve('success');
+    expect(await dp.promise).toBe('success');
+  });
+
+  it('should reject when accessed after rejection', async () => {
+    const dp = new DelayedPromise<string>();
+    const error = new Error('failure');
+    dp.reject(error);
+    await expect(dp.promise).rejects.toThrow('failure');
+  });
+
+  it('should resolve when accessed before resolution', async () => {
+    const dp = new DelayedPromise<string>();
+    const promise = dp.promise;
+    dp.resolve('success');
+    expect(await promise).toBe('success');
+  });
+
+  it('should reject when accessed before rejection', async () => {
+    const dp = new DelayedPromise<string>();
+    const promise = dp.promise;
+    const error = new Error('failure');
+    dp.reject(error);
+    await expect(promise).rejects.toThrow('failure');
+  });
+
+  it('should maintain the resolved state after multiple accesses', async () => {
+    const dp = new DelayedPromise<string>();
+    dp.resolve('success');
+    expect(await dp.promise).toBe('success');
+    expect(await dp.promise).toBe('success');
+  });
+
+  it('should maintain the rejected state after multiple accesses', async () => {
+    const dp = new DelayedPromise<string>();
+    const error = new Error('failure');
+    dp.reject(error);
+    await expect(dp.promise).rejects.toThrow('failure');
+    await expect(dp.promise).rejects.toThrow('failure');
+  });
+
+  it('should block until resolved when accessed before resolution', async () => {
+    const dp = new DelayedPromise<string>();
+    let resolved = false;
+
+    // Access the promise before resolving
+    const promise = dp.promise.then(value => {
+      resolved = true;
+      return value;
+    });
+
+    // Promise should not be resolved yet
+    expect(resolved).toBe(false);
+
+    // Wait a bit to ensure it's truly blocking
+    await delay(10);
+    expect(resolved).toBe(false);
+
+    // Now resolve it
+    dp.resolve('delayed-success');
+
+    // Should now resolve
+    const result = await promise;
+    expect(result).toBe('delayed-success');
+    expect(resolved).toBe(true);
+  });
+
+  it('should block until rejected when accessed before rejection', async () => {
+    const dp = new DelayedPromise<string>();
+    let rejected = false;
+
+    // Access the promise before rejecting
+    const promise = dp.promise.catch(error => {
+      rejected = true;
+      throw error;
+    });
+
+    // Promise should not be rejected yet
+    expect(rejected).toBe(false);
+
+    // Wait a bit to ensure it's truly blocking
+    await delay(10);
+    expect(rejected).toBe(false);
+
+    // Now reject it
+    const error = new Error('delayed-failure');
+    dp.reject(error);
+
+    // Should now reject
+    await expect(promise).rejects.toThrow('delayed-failure');
+    expect(rejected).toBe(true);
+  });
+
+  it('should resolve all pending promises when resolved after access', async () => {
+    const dp = new DelayedPromise<string>();
+    const results: string[] = [];
+
+    // Access the promise multiple times before resolution
+    const promise1 = dp.promise.then(value => {
+      results.push(`first: ${value}`);
+      return value;
+    });
+
+    const promise2 = dp.promise.then(value => {
+      results.push(`second: ${value}`);
+      return value;
+    });
+
+    // Neither should be resolved yet
+    expect(results).toHaveLength(0);
+
+    // Wait to ensure they're blocking
+    await delay(10);
+    expect(results).toHaveLength(0);
+
+    // Resolve the promise
+    dp.resolve('success');
+
+    // Both should resolve
+    await Promise.all([promise1, promise2]);
+    expect(results).toHaveLength(2);
+    expect(results).toContain('first: success');
+    expect(results).toContain('second: success');
+  });
+});

package/src/delayed-promise.ts

@@ -0,0 +1,61 @@
+/**
+ * Delayed promise. It is only constructed once the value is accessed.
+ * This is useful to avoid unhandled promise rejections when the promise is created
+ * but not accessed.
+ */
+export class DelayedPromise<T> {
+  private status:
+    | { type: 'pending' }
+    | { type: 'resolved'; value: T }
+    | { type: 'rejected'; error: unknown } = { type: 'pending' };
+  private _promise: Promise<T> | undefined;
+  private _resolve: undefined | ((value: T) => void) = undefined;
+  private _reject: undefined | ((error: unknown) => void) = undefined;
+
+  get promise(): Promise<T> {
+    if (this._promise) {
+      return this._promise;
+    }
+
+    this._promise = new Promise<T>((resolve, reject) => {
+      if (this.status.type === 'resolved') {
+        resolve(this.status.value);
+      } else if (this.status.type === 'rejected') {
+        reject(this.status.error);
+      }
+
+      this._resolve = resolve;
+      this._reject = reject;
+    });
+
+    return this._promise;
+  }
+
+  resolve(value: T): void {
+    this.status = { type: 'resolved', value };
+
+    if (this._promise) {
+      this._resolve?.(value);
+    }
+  }
+
+  reject(error: unknown): void {
+    this.status = { type: 'rejected', error };
+
+    if (this._promise) {
+      this._reject?.(error);
+    }
+  }
+
+  isResolved(): boolean {
+    return this.status.type === 'resolved';
+  }
+
+  isRejected(): boolean {
+    return this.status.type === 'rejected';
+  }
+
+  isPending(): boolean {
+    return this.status.type === 'pending';
+  }
+}

package/src/download-blob.test.ts

@@ -0,0 +1,145 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { downloadBlob } from './download-blob';
+import { DownloadError } from './download-error';
+
+describe('downloadBlob()', () => {
+  const originalFetch = globalThis.fetch;
+
+  beforeEach(() => {
+    vi.resetAllMocks();
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  it('should download a blob successfully', async () => {
+    const mockBlob = new Blob(['test content'], { type: 'image/png' });
+    globalThis.fetch = vi.fn().mockResolvedValue({
+      ok: true,
+      blob: () => Promise.resolve(mockBlob),
+    });
+
+    const result = await downloadBlob('https://example.com/image.png');
+
+    expect(result).toBe(mockBlob);
+    expect(fetch).toHaveBeenCalledWith('https://example.com/image.png');
+  });
+
+  it('should throw DownloadError on non-ok response', async () => {
+    globalThis.fetch = vi.fn().mockResolvedValue({
+      ok: false,
+      status: 404,
+      statusText: 'Not Found',
+    });
+
+    await expect(
+      downloadBlob('https://example.com/not-found.png'),
+    ).rejects.toThrow(DownloadError);
+
+    try {
+      await downloadBlob('https://example.com/not-found.png');
+    } catch (error) {
+      expect(DownloadError.isInstance(error)).toBe(true);
+      if (DownloadError.isInstance(error)) {
+        expect(error.url).toBe('https://example.com/not-found.png');
+        expect(error.statusCode).toBe(404);
+        expect(error.statusText).toBe('Not Found');
+        expect(error.message).toBe(
+          'Failed to download https://example.com/not-found.png: 404 Not Found',
+        );
+      }
+    }
+  });
+
+  it('should throw DownloadError on network error', async () => {
+    const networkError = new Error('Network error');
+    globalThis.fetch = vi.fn().mockRejectedValue(networkError);
+
+    await expect(
+      downloadBlob('https://example.com/network-error.png'),
+    ).rejects.toThrow(DownloadError);
+
+    try {
+      await downloadBlob('https://example.com/network-error.png');
+    } catch (error) {
+      expect(DownloadError.isInstance(error)).toBe(true);
+      if (DownloadError.isInstance(error)) {
+        expect(error.url).toBe('https://example.com/network-error.png');
+        expect(error.cause).toBe(networkError);
+        expect(error.message).toContain('Network error');
+      }
+    }
+  });
+
+  it('should re-throw DownloadError without wrapping', async () => {
+    const originalError = new DownloadError({
+      url: 'https://example.com/original.png',
+      statusCode: 500,
+      statusText: 'Internal Server Error',
+    });
+    globalThis.fetch = vi.fn().mockRejectedValue(originalError);
+
+    try {
+      await downloadBlob('https://example.com/test.png');
+    } catch (error) {
+      expect(error).toBe(originalError);
+      expect(DownloadError.isInstance(error)).toBe(true);
+      if (DownloadError.isInstance(error)) {
+        expect(error.url).toBe('https://example.com/original.png');
+        expect(error.statusCode).toBe(500);
+      }
+    }
+  });
+});
+
+describe('DownloadError', () => {
+  it('should create error with status code and text', () => {
+    const error = new DownloadError({
+      url: 'https://example.com/test.png',
+      statusCode: 403,
+      statusText: 'Forbidden',
+    });
+
+    expect(error.name).toBe('AI_DownloadError');
+    expect(error.url).toBe('https://example.com/test.png');
+    expect(error.statusCode).toBe(403);
+    expect(error.statusText).toBe('Forbidden');
+    expect(error.message).toBe(
+      'Failed to download https://example.com/test.png: 403 Forbidden',
+    );
+  });
+
+  it('should create error with cause', () => {
+    const cause = new Error('Connection refused');
+    const error = new DownloadError({
+      url: 'https://example.com/test.png',
+      cause,
+    });
+
+    expect(error.url).toBe('https://example.com/test.png');
+    expect(error.cause).toBe(cause);
+    expect(error.message).toContain('Connection refused');
+  });
+
+  it('should create error with custom message', () => {
+    const error = new DownloadError({
+      url: 'https://example.com/test.png',
+      message: 'Custom error message',
+    });
+
+    expect(error.message).toBe('Custom error message');
+  });
+
+  it('should identify DownloadError instances correctly', () => {
+    const downloadError = new DownloadError({
+      url: 'https://example.com/test.png',
+    });
+    const regularError = new Error('Not a download error');
+
+    expect(DownloadError.isInstance(downloadError)).toBe(true);
+    expect(DownloadError.isInstance(regularError)).toBe(false);
+    expect(DownloadError.isInstance(null)).toBe(false);
+    expect(DownloadError.isInstance(undefined)).toBe(false);
+  });
+});

package/src/download-blob.ts

@@ -0,0 +1,31 @@
+import { DownloadError } from './download-error';
+
+/**
+ * Download a file from a URL and return it as a Blob.
+ *
+ * @param url - The URL to download from.
+ * @returns A Promise that resolves to the downloaded Blob.
+ *
+ * @throws DownloadError if the download fails.
+ */
+export async function downloadBlob(url: string): Promise<Blob> {
+  try {
+    const response = await fetch(url);
+
+    if (!response.ok) {
+      throw new DownloadError({
+        url,
+        statusCode: response.status,
+        statusText: response.statusText,
+      });
+    }
+
+    return await response.blob();
+  } catch (error) {
+    if (DownloadError.isInstance(error)) {
+      throw error;
+    }
+
+    throw new DownloadError({ url, cause: error });
+  }
+}