@ai-sdk/rsc 2.0.45 → 2.0.46

package/src/streamable-value/create-streamable-value.ts

@@ -0,0 +1,296 @@
+import { HANGING_STREAM_WARNING_TIME_MS } from '../util/constants';
+import { createResolvablePromise } from '../util/create-resolvable-promise';
+import {
+  STREAMABLE_VALUE_TYPE,
+  StreamablePatch,
+  StreamableValue,
+} from './streamable-value';
+
+const STREAMABLE_VALUE_INTERNAL_LOCK = Symbol('streamable.value.lock');
+
+/**
+ * Create a wrapped, changeable value that can be streamed to the client.
+ * On the client side, the value can be accessed via the readStreamableValue() API.
+ */
+function createStreamableValue<T = any, E = any>(
+  initialValue?: T | ReadableStream<T>,
+) {
+  const isReadableStream =
+    initialValue instanceof ReadableStream ||
+    (typeof initialValue === 'object' &&
+      initialValue !== null &&
+      'getReader' in initialValue &&
+      typeof initialValue.getReader === 'function' &&
+      'locked' in initialValue &&
+      typeof initialValue.locked === 'boolean');
+
+  if (!isReadableStream) {
+    return createStreamableValueImpl<T, E>(initialValue);
+  }
+
+  const streamableValue = createStreamableValueImpl<T, E>();
+
+  // Since the streamable value will be from a readable stream, it's not allowed
+  // to update the value manually as that introduces race conditions and
+  // unexpected behavior.
+  // We lock the value to prevent any updates from the user.
+  streamableValue[STREAMABLE_VALUE_INTERNAL_LOCK] = true;
+
+  (async () => {
+    try {
+      // Consume the readable stream and update the value.
+      const reader = initialValue.getReader();
+
+      while (true) {
+        const { value, done } = await reader.read();
+        if (done) {
+          break;
+        }
+
+        // Unlock the value to allow updates.
+        streamableValue[STREAMABLE_VALUE_INTERNAL_LOCK] = false;
+        if (typeof value === 'string') {
+          streamableValue.append(value);
+        } else {
+          streamableValue.update(value);
+        }
+        // Lock the value again.
+        streamableValue[STREAMABLE_VALUE_INTERNAL_LOCK] = true;
+      }
+
+      streamableValue[STREAMABLE_VALUE_INTERNAL_LOCK] = false;
+      streamableValue.done();
+    } catch (e) {
+      streamableValue[STREAMABLE_VALUE_INTERNAL_LOCK] = false;
+      streamableValue.error(e);
+    }
+  })();
+
+  return streamableValue;
+}
+
+// It's necessary to define the type manually here, otherwise TypeScript compiler
+// will not be able to infer the correct return type as it's circular.
+type StreamableValueWrapper<T, E> = {
+  /**
+   * The value of the streamable. This can be returned from a Server Action and
+   * received by the client. To read the streamed values, use the
+   * `readStreamableValue` or `useStreamableValue` APIs.
+   */
+  readonly value: StreamableValue<T, E>;
+
+  /**
+   * This method updates the current value with a new one.
+   */
+  update(value: T): StreamableValueWrapper<T, E>;
+
+  /**
+   * This method is used to append a delta string to the current value. It
+   * requires the current value of the streamable to be a string.
+   *
+   * @example
+   * ```jsx
+   * const streamable = createStreamableValue('hello');
+   * streamable.append(' world');
+   *
+   * // The value will be 'hello world'
+   * ```
+   */
+  append(value: T): StreamableValueWrapper<T, E>;
+
+  /**
+   * This method is used to signal that there is an error in the value stream.
+   * It will be thrown on the client side when consumed via
+   * `readStreamableValue` or `useStreamableValue`.
+   */
+  error(error: any): StreamableValueWrapper<T, E>;
+
+  /**
+   * This method marks the value as finalized. You can either call it without
+   * any parameters or with a new value as the final state.
+   * Once called, the value cannot be updated or appended anymore.
+   *
+   * This method is always **required** to be called, otherwise the response
+   * will be stuck in a loading state.
+   */
+  done(...args: [T] | []): StreamableValueWrapper<T, E>;
+
+  /**
+   * @internal This is an internal lock to prevent the value from being
+   * updated by the user.
+   */
+  [STREAMABLE_VALUE_INTERNAL_LOCK]: boolean;
+};
+
+function createStreamableValueImpl<T = any, E = any>(initialValue?: T) {
+  let closed = false;
+  let locked = false;
+  let resolvable = createResolvablePromise<StreamableValue<T, E>>();
+
+  let currentValue = initialValue;
+  let currentError: E | undefined;
+  let currentPromise: typeof resolvable.promise | undefined =
+    resolvable.promise;
+  let currentPatchValue: StreamablePatch;
+
+  function assertStream(method: string) {
+    if (closed) {
+      throw new Error(method + ': Value stream is already closed.');
+    }
+    if (locked) {
+      throw new Error(
+        method + ': Value stream is locked and cannot be updated.',
+      );
+    }
+  }
+
+  let warningTimeout: NodeJS.Timeout | undefined;
+  function warnUnclosedStream() {
+    if (process.env.NODE_ENV === 'development') {
+      if (warningTimeout) {
+        clearTimeout(warningTimeout);
+      }
+      warningTimeout = setTimeout(() => {
+        console.warn(
+          'The streamable value has been slow to update. This may be a bug or a performance issue or you forgot to call `.done()`.',
+        );
+      }, HANGING_STREAM_WARNING_TIME_MS);
+    }
+  }
+  warnUnclosedStream();
+
+  function createWrapped(initialChunk?: boolean): StreamableValue<T, E> {
+    // This makes the payload much smaller if there're mutative updates before the first read.
+    let init: Partial<StreamableValue<T, E>>;
+
+    if (currentError !== undefined) {
+      init = { error: currentError };
+    } else {
+      if (currentPatchValue && !initialChunk) {
+        init = { diff: currentPatchValue };
+      } else {
+        init = { curr: currentValue };
+      }
+    }
+
+    if (currentPromise) {
+      init.next = currentPromise;
+    }
+
+    if (initialChunk) {
+      init.type = STREAMABLE_VALUE_TYPE;
+    }
+
+    return init;
+  }
+
+  // Update the internal `currentValue` and `currentPatchValue` if needed.
+  function updateValueStates(value: T) {
+    // If we can only send a patch over the wire, it's better to do so.
+    currentPatchValue = undefined;
+    if (typeof value === 'string') {
+      if (typeof currentValue === 'string') {
+        if (value.startsWith(currentValue)) {
+          currentPatchValue = [0, value.slice(currentValue.length)];
+        }
+      }
+    }
+
+    currentValue = value;
+  }
+
+  const streamable: StreamableValueWrapper<T, E> = {
+    set [STREAMABLE_VALUE_INTERNAL_LOCK](state: boolean) {
+      locked = state;
+    },
+    get value() {
+      return createWrapped(true);
+    },
+    update(value: T) {
+      assertStream('.update()');
+
+      const resolvePrevious = resolvable.resolve;
+      resolvable = createResolvablePromise();
+
+      updateValueStates(value);
+      currentPromise = resolvable.promise;
+      resolvePrevious(createWrapped());
+
+      warnUnclosedStream();
+
+      return streamable;
+    },
+    append(value: T) {
+      assertStream('.append()');
+
+      if (
+        typeof currentValue !== 'string' &&
+        typeof currentValue !== 'undefined'
+      ) {
+        throw new Error(
+          `.append(): The current value is not a string. Received: ${typeof currentValue}`,
+        );
+      }
+      if (typeof value !== 'string') {
+        throw new Error(
+          `.append(): The value is not a string. Received: ${typeof value}`,
+        );
+      }
+
+      const resolvePrevious = resolvable.resolve;
+      resolvable = createResolvablePromise();
+
+      if (typeof currentValue === 'string') {
+        currentPatchValue = [0, value];
+        (currentValue as string) = currentValue + value;
+      } else {
+        currentPatchValue = undefined;
+        currentValue = value;
+      }
+
+      currentPromise = resolvable.promise;
+      resolvePrevious(createWrapped());
+
+      warnUnclosedStream();
+
+      return streamable;
+    },
+    error(error: any) {
+      assertStream('.error()');
+
+      if (warningTimeout) {
+        clearTimeout(warningTimeout);
+      }
+      closed = true;
+      currentError = error;
+      currentPromise = undefined;
+
+      resolvable.resolve({ error });
+
+      return streamable;
+    },
+    done(...args: [] | [T]) {
+      assertStream('.done()');
+
+      if (warningTimeout) {
+        clearTimeout(warningTimeout);
+      }
+      closed = true;
+      currentPromise = undefined;
+
+      if (args.length) {
+        updateValueStates(args[0]);
+        resolvable.resolve(createWrapped());
+        return streamable;
+      }
+
+      resolvable.resolve({});
+
+      return streamable;
+    },
+  };
+
+  return streamable;
+}
+
+export { createStreamableValue };

package/src/streamable-value/is-streamable-value.ts

@@ -0,0 +1,10 @@
+import { STREAMABLE_VALUE_TYPE, StreamableValue } from './streamable-value';
+
+export function isStreamableValue(value: unknown): value is StreamableValue {
+  return (
+    value != null &&
+    typeof value === 'object' &&
+    'type' in value &&
+    value.type === STREAMABLE_VALUE_TYPE
+  );
+}

package/src/streamable-value/read-streamable-value.tsx

@@ -0,0 +1,113 @@
+import { isStreamableValue } from './is-streamable-value';
+import { StreamableValue } from './streamable-value';
+
+/**
+ * `readStreamableValue` takes a streamable value created via the `createStreamableValue().value` API,
+ * and returns an async iterator.
+ *
+ * ```js
+ * // Inside your AI action:
+ *
+ * async function action() {
+ *   'use server'
+ *   const streamable = createStreamableValue();
+ *
+ *   streamable.update(1);
+ *   streamable.update(2);
+ *   streamable.done(3);
+ *   // ...
+ *   return streamable.value;
+ * }
+ * ```
+ *
+ * And to read the value:
+ *
+ * ```js
+ * const streamableValue = await action()
+ * for await (const v of readStreamableValue(streamableValue)) {
+ *   console.log(v)
+ * }
+ * ```
+ *
+ * This logs out 1, 2, 3 on console.
+ */
+export function readStreamableValue<T = unknown>(
+  streamableValue: StreamableValue<T>,
+): AsyncIterable<T | undefined> {
+  if (!isStreamableValue(streamableValue)) {
+    throw new Error(
+      'Invalid value: this hook only accepts values created via `createStreamableValue`.',
+    );
+  }
+
+  return {
+    [Symbol.asyncIterator]() {
+      let row: StreamableValue<T> | Promise<StreamableValue<T>> =
+        streamableValue;
+      let value = row.curr; // the current value
+      let isDone = false;
+      let isFirstIteration = true;
+
+      return {
+        async next() {
+          // the iteration is done already, return the last value:
+          if (isDone) return { value, done: true };
+
+          // resolve the promise at the beginning of each iteration:
+          row = await row;
+
+          // throw error if any:
+          if (row.error !== undefined) {
+            throw row.error;
+          }
+
+          // if there is a value or a patch, use it:
+          if ('curr' in row || row.diff) {
+            if (row.diff) {
+              // streamable patch (text only):
+              if (row.diff[0] === 0) {
+                if (typeof value !== 'string') {
+                  throw new Error(
+                    'Invalid patch: can only append to string types. This is a bug in the AI SDK.',
+                  );
+                }
+
+                // casting required to remove T & string limitation
+                (value as string) = value + row.diff[1];
+              }
+            } else {
+              // replace the value (full new value)
+              value = row.curr;
+            }
+
+            // The last emitted { done: true } won't be used as the value
+            // by the for await...of syntax.
+            if (!row.next) {
+              isDone = true;
+              return { value, done: false };
+            }
+          }
+
+          // there are no further rows to iterate over:
+          if (row.next === undefined) {
+            return { value, done: true };
+          }
+
+          row = row.next;
+
+          if (isFirstIteration) {
+            isFirstIteration = false; // TODO should this be set for every return?
+
+            if (value === undefined) {
+              // This is the initial chunk and there isn't an initial value yet.
+              // Let's skip this one.
+              return this.next();
+            }
+          }
+
+          return { value, done: false };
+        },
+      };
+    },
+  };
+}

package/src/streamable-value/read-streamable-value.ui.test.tsx

@@ -0,0 +1,165 @@
+import { delay } from '@ai-sdk/provider-utils';
+import { createStreamableValue } from './create-streamable-value';
+import { readStreamableValue } from './read-streamable-value';
+import { it, expect } from 'vitest';
+
+it('should return an async iterable', () => {
+  const streamable = createStreamableValue();
+  const result = readStreamableValue(streamable.value);
+  streamable.done();
+
+  expect(result).toBeDefined();
+  expect(result[Symbol.asyncIterator]).toBeDefined();
+});
+
+it('should support reading streamed values and errors', async () => {
+  const streamable = createStreamableValue(1);
+
+  (async () => {
+    await delay();
+    streamable.update(2);
+    await delay();
+    streamable.update(3);
+    await delay();
+    streamable.error('This is an error');
+  })();
+
+  const values = [];
+
+  try {
+    for await (const v of readStreamableValue(streamable.value)) {
+      values.push(v);
+    }
+    expect.fail('should not be reached');
+  } catch (e) {
+    expect(e).toStrictEqual('This is an error');
+  }
+
+  expect(values).toStrictEqual([1, 2, 3]);
+});
+
+it('should be able to read values asynchronously with different value types', async () => {
+  const streamable = createStreamableValue({});
+
+  (async () => {
+    await delay();
+    streamable.update([1]);
+    streamable.update(['2']);
+    streamable.done({ 3: 3 });
+  })();
+
+  const values = [];
+  for await (const v of readStreamableValue(streamable.value)) {
+    values.push(v);
+  }
+
+  expect(values).toStrictEqual([{}, [1], ['2'], { '3': 3 }]);
+});
+
+it('should be able to replay errors', async () => {
+  const streamable = createStreamableValue(0);
+
+  (async () => {
+    await delay();
+    streamable.update(1);
+    streamable.update(2);
+    streamable.error({ customErrorMessage: 'this is an error' });
+  })();
+
+  const values = [];
+
+  try {
+    for await (const v of readStreamableValue(streamable.value)) {
+      values.push(v);
+    }
+
+    expect.fail('should not be reached');
+  } catch (e) {
+    expect(e).toStrictEqual({
+      customErrorMessage: 'this is an error',
+    });
+  }
+  expect(values).toStrictEqual([0, 1, 2]);
+});
+
+it('should be able to append strings as patch', async () => {
+  const streamable = createStreamableValue();
+  const value = streamable.value;
+
+  streamable.update('hello');
+  streamable.update('hello world');
+  streamable.update('hello world!');
+  streamable.update('new string');
+  streamable.done('new string with patch!');
+
+  const values = [];
+  for await (const v of readStreamableValue(value)) {
+    values.push(v);
+  }
+
+  expect(values).toStrictEqual([
+    'hello',
+    'hello world',
+    'hello world!',
+    'new string',
+    'new string with patch!',
+  ]);
+});
+
+it('should be able to call .append() to send patches', async () => {
+  const streamable = createStreamableValue();
+  const value = streamable.value;
+
+  streamable.append('hello');
+  streamable.append(' world');
+  streamable.append('!');
+  streamable.done();
+
+  const values = [];
+  for await (const v of readStreamableValue(value)) {
+    values.push(v);
+  }
+
+  expect(values).toStrictEqual(['hello', 'hello world', 'hello world!']);
+});
+
+it('should be able to mix .update() and .append() with optimized payloads', async () => {
+  const streamable = createStreamableValue('hello');
+  const value = streamable.value;
+
+  streamable.append(' world');
+  streamable.update('hello world!!');
+  streamable.update('some new');
+  streamable.update('some new string');
+  streamable.append(' with patch!');
+  streamable.done();
+
+  const values = [];
+  for await (const v of readStreamableValue(value)) {
+    values.push(v);
+  }
+
+  expect(values).toStrictEqual([
+    'hello',
+    'hello world',
+    'hello world!!',
+    'some new',
+    'some new string',
+    'some new string with patch!',
+  ]);
+});
+
+it('should behave like .update() with .append() and .done()', async () => {
+  const streamable = createStreamableValue('hello');
+  const value = streamable.value;
+
+  streamable.append(' world');
+  streamable.done('fin');
+
+  const values = [];
+  for await (const v of readStreamableValue(value)) {
+    values.push(v);
+  }
+
+  expect(values).toStrictEqual(['hello', 'hello world', 'fin']);
+});

package/src/streamable-value/streamable-value.ts

@@ -0,0 +1,37 @@
+export const STREAMABLE_VALUE_TYPE = Symbol.for('ui.streamable.value');
+
+export type StreamablePatch = undefined | [0, string]; // Append string.
+
+declare const __internal_curr: unique symbol;
+declare const __internal_error: unique symbol;
+
+/**
+ * StreamableValue is a value that can be streamed over the network via AI Actions.
+ * To read the streamed values, use the `readStreamableValue` or `useStreamableValue` APIs.
+ */
+export type StreamableValue<T = any, E = any> = {
+  /**
+   * @internal Use `readStreamableValue` to read the values.
+   */
+  type?: typeof STREAMABLE_VALUE_TYPE;
+  /**
+   * @internal Use `readStreamableValue` to read the values.
+   */
+  curr?: T;
+  /**
+   * @internal Use `readStreamableValue` to read the values.
+   */
+  error?: E;
+  /**
+   * @internal Use `readStreamableValue` to read the values.
+   */
+  diff?: StreamablePatch;
+  /**
+   * @internal Use `readStreamableValue` to read the values.
+   */
+  next?: Promise<StreamableValue<T, E>>;
+
+  // branded types to maintain type signature after internal properties are stripped.
+  [__internal_curr]?: T;
+  [__internal_error]?: E;
+};

package/src/streamable-value/use-streamable-value.tsx

@@ -0,0 +1,91 @@
+import { startTransition, useLayoutEffect, useState } from 'react';
+import { readStreamableValue } from './read-streamable-value';
+import { StreamableValue } from './streamable-value';
+import { isStreamableValue } from './is-streamable-value';
+
+function checkStreamableValue(value: unknown): value is StreamableValue {
+  const hasSignature = isStreamableValue(value);
+
+  if (!hasSignature && value !== undefined) {
+    throw new Error(
+      'Invalid value: this hook only accepts values created via `createStreamableValue`.',
+    );
+  }
+
+  return hasSignature;
+}
+
+/**
+ * `useStreamableValue` is a React hook that takes a streamable value created via the `createStreamableValue().value` API,
+ * and returns the current value, error, and pending state.
+ *
+ * This is useful for consuming streamable values received from a component's props. For example:
+ *
+ * ```js
+ * function MyComponent({ streamableValue }) {
+ *   const [data, error, pending] = useStreamableValue(streamableValue);
+ *
+ *   if (pending) return <div>Loading...</div>;
+ *   if (error) return <div>Error: {error.message}</div>;
+ *
+ *   return <div>Data: {data}</div>;
+ * }
+ * ```
+ */
+export function useStreamableValue<T = unknown, Error = unknown>(
+  streamableValue?: StreamableValue<T>,
+): [data: T | undefined, error: Error | undefined, pending: boolean] {
+  const [curr, setCurr] = useState<T | undefined>(
+    checkStreamableValue(streamableValue) ? streamableValue.curr : undefined,
+  );
+  const [error, setError] = useState<Error | undefined>(
+    checkStreamableValue(streamableValue) ? streamableValue.error : undefined,
+  );
+  const [pending, setPending] = useState<boolean>(
+    checkStreamableValue(streamableValue) ? !!streamableValue.next : false,
+  );
+
+  useLayoutEffect(() => {
+    if (!checkStreamableValue(streamableValue)) return;
+
+    let cancelled = false;
+
+    const iterator = readStreamableValue(streamableValue);
+    if (streamableValue.next) {
+      startTransition(() => {
+        if (cancelled) return;
+        setPending(true);
+      });
+    }
+
+    (async () => {
+      try {
+        for await (const value of iterator) {
+          if (cancelled) return;
+          startTransition(() => {
+            if (cancelled) return;
+            setCurr(value);
+          });
+        }
+      } catch (e) {
+        if (cancelled) return;
+        startTransition(() => {
+          if (cancelled) return;
+          setError(e as Error);
+        });
+      } finally {
+        if (cancelled) return;
+        startTransition(() => {
+          if (cancelled) return;
+          setPending(false);
+        });
+      }
+    })();
+
+    return () => {
+      cancelled = true;
+    };
+  }, [streamableValue]);
+
+  return [curr, error, pending];
+}