ai 6.0.33 → 6.0.34

package/src/util/async-iterable-stream.ts

@@ -0,0 +1,94 @@
+/**
+ * A type that combines AsyncIterable and ReadableStream.
+ * This allows a ReadableStream to be consumed using for-await-of syntax.
+ */
+export type AsyncIterableStream<T> = AsyncIterable<T> & ReadableStream<T>;
+
+/**
+ * Wraps a ReadableStream and returns an object that is both a ReadableStream and an AsyncIterable.
+ * This enables consumption of the stream using for-await-of, with proper resource cleanup on early exit or error.
+ *
+ * @template T The type of the stream's chunks.
+ * @param source The source ReadableStream to wrap.
+ * @returns An AsyncIterableStream that can be used as both a ReadableStream and an AsyncIterable.
+ */
+export function createAsyncIterableStream<T>(
+  source: ReadableStream<T>,
+): AsyncIterableStream<T> {
+  // Pipe through a TransformStream to ensure a fresh, unlocked stream.
+  const stream = source.pipeThrough(new TransformStream<T, T>());
+
+  /**
+   * Implements the async iterator protocol for the stream.
+   * Ensures proper cleanup (cancelling and releasing the reader) on completion, early exit, or error.
+   */
+  (stream as AsyncIterableStream<T>)[Symbol.asyncIterator] = function (
+    this: ReadableStream<T>,
+  ): AsyncIterator<T> {
+    const reader = this.getReader();
+
+    let finished = false;
+
+    /**
+     * Cleans up the reader by cancelling and releasing the lock.
+     */
+    async function cleanup(cancelStream: boolean) {
+      if (finished) return;
+
+      finished = true;
+      try {
+        if (cancelStream) {
+          await reader.cancel?.();
+        }
+      } finally {
+        try {
+          reader.releaseLock();
+        } catch {}
+      }
+    }
+
+    return {
+      /**
+       * Reads the next chunk from the stream.
+       * @returns A promise resolving to the next IteratorResult.
+       */
+      async next(): Promise<IteratorResult<T>> {
+        if (finished) {
+          return { done: true, value: undefined };
+        }
+
+        const { done, value } = await reader.read();
+
+        if (done) {
+          await cleanup(true);
+          return { done: true, value: undefined };
+        }
+
+        return { done: false, value };
+      },
+
+      /**
+       * May be called on early exit (e.g., break from for-await) or after completion.
+       * Ensures the stream is cancelled and resources are released.
+       * @returns A promise resolving to a completed IteratorResult.
+       */
+      async return(): Promise<IteratorResult<T>> {
+        await cleanup(true);
+        return { done: true, value: undefined };
+      },
+
+      /**
+       * Called on early exit with error.
+       * Ensures the stream is cancelled and resources are released, then rethrows the error.
+       * @param err The error to throw.
+       * @returns A promise that rejects with the provided error.
+       */
+      async throw(err: unknown): Promise<IteratorResult<T>> {
+        await cleanup(true);
+        throw err;
+      },
+    };
+  };
+
+  return stream as AsyncIterableStream<T>;
+}

package/src/util/consume-stream.ts

@@ -0,0 +1,29 @@
+/**
+ * Consumes a ReadableStream until it's fully read.
+ *
+ * This function reads the stream chunk by chunk until the stream is exhausted.
+ * It doesn't process or return the data from the stream; it simply ensures
+ * that the entire stream is read.
+ *
+ * @param {ReadableStream} stream - The ReadableStream to be consumed.
+ * @returns {Promise<void>} A promise that resolves when the stream is fully consumed.
+ */
+export async function consumeStream({
+  stream,
+  onError,
+}: {
+  stream: ReadableStream;
+  onError?: (error: unknown) => void;
+}): Promise<void> {
+  const reader = stream.getReader();
+  try {
+    while (true) {
+      const { done } = await reader.read();
+      if (done) break;
+    }
+  } catch (error) {
+    onError?.(error);
+  } finally {
+    reader.releaseLock();
+  }
+}

package/src/util/cosine-similarity.test.ts

@@ -0,0 +1,57 @@
+import { cosineSimilarity } from './cosine-similarity';
+import { it, expect } from 'vitest';
+
+it('should calculate cosine similarity correctly', () => {
+  const vector1 = [1, 2, 3];
+  const vector2 = [4, 5, 6];
+
+  const result = cosineSimilarity(vector1, vector2);
+
+  // test against pre-calculated value:
+  expect(result).toBeCloseTo(0.9746318461970762, 5);
+});
+
+it('should calculate negative cosine similarity correctly', () => {
+  const vector1 = [1, 0];
+  const vector2 = [-1, 0];
+
+  const result = cosineSimilarity(vector1, vector2);
+
+  // test against pre-calculated value:
+  expect(result).toBeCloseTo(-1, 5);
+});
+
+it('should throw an error when vectors have different lengths', () => {
+  const vector1 = [1, 2, 3];
+  const vector2 = [4, 5];
+
+  expect(() => cosineSimilarity(vector1, vector2)).toThrowError();
+});
+
+it('should give 0 when one of the vectors is a zero vector', () => {
+  const vector1 = [0, 1, 2];
+  const vector2 = [0, 0, 0];
+
+  const result = cosineSimilarity(vector1, vector2);
+
+  expect(result).toBe(0);
+
+  const result2 = cosineSimilarity(vector2, vector1);
+
+  expect(result2).toBe(0);
+});
+
+it('should handle vectors with very small magnitudes', () => {
+  const vector1 = [1e-10, 0, 0];
+  const vector2 = [2e-10, 0, 0];
+
+  const result = cosineSimilarity(vector1, vector2);
+
+  expect(result).toBe(1);
+
+  const vector3 = [1e-10, 0, 0];
+  const vector4 = [-1e-10, 0, 0];
+
+  const result2 = cosineSimilarity(vector3, vector4);
+  expect(result2).toBe(-1);
+});

package/src/util/cosine-similarity.ts

@@ -0,0 +1,47 @@
+import { InvalidArgumentError } from '../error/invalid-argument-error';
+
+/**
+ * Calculates the cosine similarity between two vectors. This is a useful metric for
+ * comparing the similarity of two vectors such as embeddings.
+ *
+ * @param vector1 - The first vector.
+ * @param vector2 - The second vector.
+ *
+ * @returns The cosine similarity between vector1 and vector2.
+ * @returns 0 if either vector is the zero vector.
+ *
+ * @throws {InvalidArgumentError} If the vectors do not have the same length.
+ */
+export function cosineSimilarity(vector1: number[], vector2: number[]): number {
+  if (vector1.length !== vector2.length) {
+    throw new InvalidArgumentError({
+      parameter: 'vector1,vector2',
+      value: { vector1Length: vector1.length, vector2Length: vector2.length },
+      message: `Vectors must have the same length`,
+    });
+  }
+
+  const n = vector1.length;
+
+  if (n === 0) {
+    return 0; // Return 0 for empty vectors if no error is thrown
+  }
+
+  let magnitudeSquared1 = 0;
+  let magnitudeSquared2 = 0;
+  let dotProduct = 0;
+
+  for (let i = 0; i < n; i++) {
+    const value1 = vector1[i];
+    const value2 = vector2[i];
+
+    magnitudeSquared1 += value1 * value1;
+    magnitudeSquared2 += value2 * value2;
+    dotProduct += value1 * value2;
+  }
+
+  return magnitudeSquared1 === 0 || magnitudeSquared2 === 0
+    ? 0
+    : dotProduct /
+        (Math.sqrt(magnitudeSquared1) * Math.sqrt(magnitudeSquared2));
+}

package/src/util/create-resolvable-promise.ts

@@ -0,0 +1,30 @@
+import { ErrorHandler } from './error-handler';
+
+/**
+ * Creates a Promise with externally accessible resolve and reject functions.
+ *
+ * @template T - The type of the value that the Promise will resolve to.
+ * @returns An object containing:
+ *   - promise: A Promise that can be resolved or rejected externally.
+ *   - resolve: A function to resolve the Promise with a value of type T.
+ *   - reject: A function to reject the Promise with an error.
+ */
+export function createResolvablePromise<T = any>(): {
+  promise: Promise<T>;
+  resolve: (value: T) => void;
+  reject: ErrorHandler;
+} {
+  let resolve: (value: T) => void;
+  let reject: ErrorHandler;
+
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+
+  return {
+    promise,
+    resolve: resolve!,
+    reject: reject!,
+  };
+}

package/src/util/create-stitchable-stream.test.ts

@@ -0,0 +1,239 @@
+import {
+  convertArrayToReadableStream,
+  convertReadableStreamToArray,
+} from '@ai-sdk/provider-utils/test';
+import { describe, it, expect } from 'vitest';
+import { createStitchableStream } from './create-stitchable-stream';
+
+describe('createStitchableStream', () => {
+  describe('read full streams after they are added', () => {
+    it('should return no stream when immediately closed', async () => {
+      const { stream, close } = createStitchableStream<number>();
+
+      close();
+
+      expect(await convertReadableStreamToArray(stream)).toEqual([]);
+    });
+
+    it('should return all values from a single inner stream', async () => {
+      const { stream, addStream, close } = createStitchableStream<number>();
+
+      addStream(convertArrayToReadableStream([1, 2, 3]));
+      close();
+
+      expect(await convertReadableStreamToArray(stream)).toEqual([1, 2, 3]);
+    });
+
+    it('should return all values from 2 inner streams', async () => {
+      const { stream, addStream, close } = createStitchableStream<number>();
+
+      addStream(convertArrayToReadableStream([1, 2, 3]));
+      addStream(convertArrayToReadableStream([4, 5, 6]));
+      close();
+
+      expect(await convertReadableStreamToArray(stream)).toEqual([
+        1, 2, 3, 4, 5, 6,
+      ]);
+    });
+
+    it('should return all values from 3 inner streams', async () => {
+      const { stream, addStream, close } = createStitchableStream<number>();
+
+      addStream(convertArrayToReadableStream([1, 2, 3]));
+      addStream(convertArrayToReadableStream([4, 5, 6]));
+      addStream(convertArrayToReadableStream([7, 8, 9]));
+      close();
+
+      expect(await convertReadableStreamToArray(stream)).toEqual([
+        1, 2, 3, 4, 5, 6, 7, 8, 9,
+      ]);
+    });
+
+    it('should handle empty inner streams', async () => {
+      const { stream, addStream, close } = createStitchableStream<number>();
+
+      addStream(convertArrayToReadableStream([]));
+      addStream(convertArrayToReadableStream([1, 2]));
+      addStream(convertArrayToReadableStream([]));
+      addStream(convertArrayToReadableStream([3, 4]));
+      close();
+
+      expect(await convertReadableStreamToArray(stream)).toEqual([1, 2, 3, 4]);
+    });
+
+    it('should handle reading a single value before it is added', async () => {
+      const { stream, addStream, close } = createStitchableStream<number>();
+
+      // Start reading before any values are added
+      const reader = stream.getReader();
+      const readPromise = reader.read();
+
+      // Add value with delay after starting read
+      Promise.resolve().then(() => {
+        addStream(convertArrayToReadableStream([42]));
+        close();
+      });
+
+      // Value should be returned once available
+      expect(await readPromise).toEqual({ done: false, value: 42 });
+
+      // Stream should complete after value is read
+      expect(await reader.read()).toEqual({ done: true, value: undefined });
+    });
+  });
+
+  describe('read from partial stream and with interruptions', async () => {
+    it('should return all values from 2 inner streams', async () => {
+      const { stream, addStream, close } = createStitchableStream<number>();
+
+      // read 5 values from the stream before they are added
+      // (added asynchronously)
+      const reader = stream.getReader();
+      const results: Array<{ done: boolean; value?: number }> = [];
+      for (let i = 0; i < 5; i++) {
+        reader.read().then(result => {
+          results.push(result);
+        });
+      }
+
+      addStream(convertArrayToReadableStream([1, 2, 3]));
+      addStream(convertArrayToReadableStream([4, 5]));
+      close();
+
+      // wait for the stream to finish via await:
+      expect(await reader.read()).toEqual({ done: true, value: undefined });
+
+      expect(results).toEqual([
+        { done: false, value: 1 },
+        { done: false, value: 2 },
+        { done: false, value: 3 },
+        { done: false, value: 4 },
+        { done: false, value: 5 },
+      ]);
+    });
+  });
+
+  describe('error handling', () => {
+    it('should handle errors from inner streams', async () => {
+      const { stream, addStream, close } = createStitchableStream<number>();
+
+      const errorStream = new ReadableStream({
+        start(controller) {
+          controller.error(new Error('Test error'));
+        },
+      });
+
+      addStream(convertArrayToReadableStream([1, 2]));
+      addStream(errorStream);
+      addStream(convertArrayToReadableStream([3, 4]));
+      close();
+
+      await expect(convertReadableStreamToArray(stream)).rejects.toThrow(
+        'Test error',
+      );
+    });
+  });
+
+  describe('cancellation & closing', () => {
+    it('should cancel all inner streams when cancelled', async () => {
+      const { stream, addStream } = createStitchableStream<number>();
+
+      let stream1Cancelled = false;
+      let stream2Cancelled = false;
+
+      const mockStream1 = new ReadableStream({
+        start(controller) {
+          controller.enqueue(1);
+          controller.enqueue(2);
+        },
+        cancel() {
+          stream1Cancelled = true;
+        },
+      });
+
+      const mockStream2 = new ReadableStream({
+        start(controller) {
+          controller.enqueue(3);
+          controller.enqueue(4);
+        },
+        cancel() {
+          stream2Cancelled = true;
+        },
+      });
+
+      addStream(mockStream1);
+      addStream(mockStream2);
+
+      await stream.cancel();
+
+      expect(stream1Cancelled).toBe(true);
+      expect(stream2Cancelled).toBe(true);
+    });
+
+    it('should throw an error when adding a stream after closing', async () => {
+      const { addStream, close } = createStitchableStream<number>();
+
+      close();
+
+      expect(() => addStream(convertArrayToReadableStream([1, 2]))).toThrow(
+        'Cannot add inner stream: outer stream is closed',
+      );
+    });
+  });
+
+  describe('terminate', () => {
+    it('should immediately close the stream and cancel all inner streams', async () => {
+      const { stream, addStream, terminate } = createStitchableStream<number>();
+
+      let stream1Cancelled = false;
+      let stream2Cancelled = false;
+
+      const mockStream1 = new ReadableStream({
+        start(controller) {
+          controller.enqueue(1);
+          controller.enqueue(2);
+        },
+        cancel() {
+          stream1Cancelled = true;
+        },
+      });
+
+      const mockStream2 = new ReadableStream({
+        start(controller) {
+          controller.enqueue(3);
+          controller.enqueue(4);
+        },
+        cancel() {
+          stream2Cancelled = true;
+        },
+      });
+
+      addStream(mockStream1);
+      addStream(mockStream2);
+
+      // Start reading from the stream
+      const reader = stream.getReader();
+      const firstRead = await reader.read();
+
+      terminate();
+
+      // Should immediately close without reading remaining values
+      const finalRead = await reader.read();
+
+      expect(firstRead).toEqual({ done: false, value: 1 });
+      expect(finalRead).toEqual({ done: true, value: undefined });
+      expect(stream1Cancelled).toBe(true);
+      expect(stream2Cancelled).toBe(true);
+    });
+
+    it('should throw an error when adding a stream after terminating', async () => {
+      const { addStream, terminate } = createStitchableStream<number>();
+
+      terminate();
+
+      expect(() => addStream(convertArrayToReadableStream([1, 2]))).toThrow(
+        'Cannot add inner stream: outer stream is closed',
+      );
+    });
+  });
+});

package/src/util/create-stitchable-stream.ts

@@ -0,0 +1,112 @@
+import { createResolvablePromise } from './create-resolvable-promise';
+
+/**
+ * Creates a stitchable stream that can pipe one stream at a time.
+ *
+ * @template T - The type of values emitted by the streams.
+ * @returns {Object} An object containing the stitchable stream and control methods.
+ */
+export function createStitchableStream<T>(): {
+  stream: ReadableStream<T>;
+  addStream: (innerStream: ReadableStream<T>) => void;
+  close: () => void;
+  terminate: () => void;
+} {
+  let innerStreamReaders: ReadableStreamDefaultReader<T>[] = [];
+  let controller: ReadableStreamDefaultController<T> | null = null;
+  let isClosed = false;
+  let waitForNewStream = createResolvablePromise<void>();
+
+  const terminate = () => {
+    isClosed = true;
+    waitForNewStream.resolve();
+
+    innerStreamReaders.forEach(reader => reader.cancel());
+    innerStreamReaders = [];
+    controller?.close();
+  };
+
+  const processPull = async () => {
+    // Case 1: Outer stream is closed and no more inner streams
+    if (isClosed && innerStreamReaders.length === 0) {
+      controller?.close();
+      return;
+    }
+
+    // Case 2: No inner streams available, but outer stream is open
+    // wait for a new inner stream to be added or the outer stream to close
+    if (innerStreamReaders.length === 0) {
+      waitForNewStream = createResolvablePromise<void>();
+      await waitForNewStream.promise;
+      return processPull();
+    }
+
+    try {
+      const { value, done } = await innerStreamReaders[0].read();
+
+      if (done) {
+        // Case 3: Current inner stream is done
+        innerStreamReaders.shift(); // Remove the finished stream
+
+        if (innerStreamReaders.length === 0 && isClosed) {
+          // when closed and no more inner streams, stop pulling
+          controller?.close();
+        } else {
+          // continue pulling from the next stream
+          await processPull();
+        }
+      } else {
+        // Case 4: Current inner stream returns an item
+        controller?.enqueue(value);
+      }
+    } catch (error) {
+      // Case 5: Current inner stream throws an error
+      controller?.error(error);
+      innerStreamReaders.shift(); // Remove the errored stream
+      terminate(); // we have errored, terminate all streams
+    }
+  };
+
+  return {
+    stream: new ReadableStream<T>({
+      start(controllerParam) {
+        controller = controllerParam;
+      },
+      pull: processPull,
+      async cancel() {
+        for (const reader of innerStreamReaders) {
+          await reader.cancel();
+        }
+        innerStreamReaders = [];
+        isClosed = true;
+      },
+    }),
+    addStream: (innerStream: ReadableStream<T>) => {
+      if (isClosed) {
+        throw new Error('Cannot add inner stream: outer stream is closed');
+      }
+
+      innerStreamReaders.push(innerStream.getReader());
+      waitForNewStream.resolve();
+    },
+
+    /**
+     * Gracefully close the outer stream. This will let the inner streams
+     * finish processing and then close the outer stream.
+     */
+    close: () => {
+      isClosed = true;
+      waitForNewStream.resolve();
+
+      if (innerStreamReaders.length === 0) {
+        controller?.close();
+      }
+    },
+
+    /**
+     * Immediately close the outer stream. This will cancel all inner streams
+     * and close the outer stream.
+     */
+    terminate,
+  };
+}

package/src/util/data-url.ts

@@ -0,0 +1,17 @@
+/**
+ * Converts a data URL of type text/* to a text string.
+ */
+export function getTextFromDataUrl(dataUrl: string): string {
+  const [header, base64Content] = dataUrl.split(',');
+  const mediaType = header.split(';')[0].split(':')[1];
+
+  if (mediaType == null || base64Content == null) {
+    throw new Error('Invalid data URL format');
+  }
+
+  try {
+    return window.atob(base64Content);
+  } catch (error) {
+    throw new Error(`Error decoding data URL`);
+  }
+}