openai 7.3.0 → 7.5.0

package/src/core/streaming.ts

@@ -1,36 +1,51 @@
-import { OpenAIError } from './error';
-import { type ReadableStream } from '../internal/shim-types';
-import { makeReadableStream } from '../internal/shims';
+import { OpenAIError, APIError } from './error';
+import type { ReadableStream } from '../internal/shim-types';
+import { makeReadableStream, ReadableStreamToAsyncIterable } from '../internal/shims';
 import { findDoubleNewlineIndex, LineDecoder } from '../internal/decoders/line';
-import { ReadableStreamToAsyncIterable } from '../internal/shims';
 import { isAbortError } from '../internal/errors';
 import { encodeUTF8 } from '../internal/utils/bytes';
 import { loggerFor } from '../internal/utils/log';
 import type { OpenAI } from '../client';
 
-import { APIError } from './error';
-
 type Bytes = string | ArrayBuffer | Uint8Array | null | undefined;
 
+/** A decoded server-sent event before its JSON payload has been parsed. */
 export type ServerSentEvent = {
+  /** Explicit SSE event name, or `null` when the event has no `event:` field. */
   event: string | null;
+  /** Joined contents of the event's `data:` fields. */
   data: string;
+  /** Original event lines retained for diagnostics when parsing fails. */
   raw: string[];
 };
 
+/**
+ * A single-consumption asynchronous API response stream.
+ *
+ * Use {@link Stream.tee} when two consumers need the same events. Breaking out of
+ * a response-backed stream early aborts its request; branches created by `tee()`
+ * instead share {@link Stream.controller} for explicit cancellation.
+ */
 export class Stream<Item> implements AsyncIterable<Item> {
+  /** Abort controller for the underlying request and all branches created with `tee()`. */
   controller: AbortController;
   #client: OpenAI | undefined;
+  private iterator: () => AsyncIterator<Item>;
 
-  constructor(
-    private iterator: () => AsyncIterator<Item>,
-    controller: AbortController,
-    client?: OpenAI,
-  ) {
+  /** Wraps an asynchronous event iterator and the controller that owns its request. */
+  constructor(iterator: () => AsyncIterator<Item>, controller: AbortController, client?: OpenAI) {
+    this.iterator = iterator;
     this.controller = controller;
     this.#client = client;
   }
 
+  /**
+   * Decodes an SSE response into parsed JSON events.
+   *
+   * The resulting stream can be consumed only once, ignores events after `[DONE]`, and
+   * surfaces API error payloads as `APIError` instances. When
+   * `synthesizeEventData` is enabled, each item also includes its SSE event name.
+   */
   static fromSSEResponse<Item>(
     response: Response,
     controller: AbortController,
@@ -46,13 +61,12 @@ export class Stream<Item> implements AsyncIterable<Item> {
       }
       consumed = true;
       let done = false;
+      let receivedCompletionSentinel = false;
       try {
         for await (const sse of _iterSSEMessages(response, controller)) {
-          if (done) continue;
-
           if (sse.data.startsWith('[DONE]')) {
-            done = true;
-            continue;
+            receivedCompletionSentinel = true;
+            break;
           }
 
           if (sse.event === null || !sse.event.startsWith('thread.')) {
@@ -80,21 +94,29 @@ export class Stream<Item> implements AsyncIterable<Item> {
               console.error(`From chunk:`, sse.raw);
               throw e;
             }
-            // TODO: Is this where the error should be thrown?
-            if (sse.event == 'error') {
+            // SSE error events surface as APIError instances.
+            if (sse.event === 'error') {
               throw new APIError(undefined, data.error, data.message, undefined);
             }
-            yield { event: sse.event, data: data } as any;
+            yield { event: sse.event, data } as any;
           }
         }
         done = true;
       } catch (e) {
-        // If the user calls `stream.controller.abort()`, we should exit without throwing.
-        if (isAbortError(e)) return;
+        // Abort errors and cleanup failures after the completion sentinel are non-fatal.
+        if (
+          receivedCompletionSentinel ||
+          isAbortError(e) ||
+          (controller.signal.aborted && e === controller.signal.reason)
+        ) {
+          return;
+        }
         throw e;
       } finally {
         // If the user `break`s, abort the ongoing request.
-        if (!done) controller.abort();
+        if (!done) {
+          controller.abort();
+        }
       }
     }
 
@@ -119,7 +141,7 @@ export class Stream<Item> implements AsyncIterable<Item> {
       let cancelPromise: Promise<void> | undefined;
       const cancel = () => {
         cancelPromise ??= reader.cancel();
-        cancelPromise.catch(() => {});
+        cancelPromise.catch(() => undefined);
       };
 
       controller.signal.addEventListener('abort', cancel, { once: true });
@@ -135,22 +157,32 @@ export class Stream<Item> implements AsyncIterable<Item> {
             closed = true;
             break;
           }
-          if (controller.signal.aborted) return;
+          if (controller.signal.aborted) {
+            return;
+          }
 
           for (const line of lineDecoder.decode(chunk)) {
-            if (controller.signal.aborted) return;
+            if (controller.signal.aborted) {
+              return;
+            }
             yield line;
           }
         }
 
-        if (controller.signal.aborted) return;
+        if (controller.signal.aborted) {
+          return;
+        }
         for (const line of lineDecoder.flush()) {
-          if (controller.signal.aborted) return;
+          if (controller.signal.aborted) {
+            return;
+          }
           yield line;
         }
       } finally {
         controller.signal.removeEventListener('abort', cancel);
-        if (!closed) cancel();
+        if (!closed) {
+          cancel();
+        }
         reader.releaseLock();
       }
     }
@@ -163,23 +195,32 @@ export class Stream<Item> implements AsyncIterable<Item> {
       let done = false;
       try {
         for await (const line of iterLines()) {
-          if (done) continue;
-          if (line) yield JSON.parse(line) as Item;
+          if (done) {
+            continue;
+          }
+          if (line) {
+            yield JSON.parse(line) as Item;
+          }
         }
         done = true;
       } catch (e) {
         // If the user calls `stream.controller.abort()`, we should exit without throwing.
-        if (controller.signal.aborted || isAbortError(e)) return;
+        if (controller.signal.aborted || isAbortError(e)) {
+          return;
+        }
         throw e;
       } finally {
         // If the user `break`s, abort the ongoing request.
-        if (!done) controller.abort();
+        if (!done) {
+          controller.abort();
+        }
       }
     }
 
     return new Stream(iterator, controller, client);
   }
 
+  /** Starts consuming this stream; attempting to consume it again throws. */
   [Symbol.asyncIterator](): AsyncIterator<Item> {
     return this.iterator();
   }
@@ -189,22 +230,20 @@ export class Stream<Item> implements AsyncIterable<Item> {
    * independently read from at different speeds.
    */
   tee(): [Stream<Item>, Stream<Item>] {
-    const left: Array<Promise<IteratorResult<Item>>> = [];
-    const right: Array<Promise<IteratorResult<Item>>> = [];
+    const left: Promise<IteratorResult<Item>>[] = [];
+    const right: Promise<IteratorResult<Item>>[] = [];
     const iterator = this.iterator();
 
-    const teeIterator = (queue: Array<Promise<IteratorResult<Item>>>): AsyncIterator<Item> => {
-      return {
-        next: () => {
-          if (queue.length === 0) {
-            const result = iterator.next();
-            left.push(result);
-            right.push(result);
-          }
-          return queue.shift()!;
-        },
-      };
-    };
+    const teeIterator = (queue: Promise<IteratorResult<Item>>[]): AsyncIterator<Item> => ({
+      next: () => {
+        if (queue.length === 0) {
+          const result = iterator.next();
+          left.push(result);
+          right.push(result);
+        }
+        return queue.shift()!;
+      },
+    });
 
     return [
       new Stream(() => teeIterator(left), this.controller, this.#client),
@@ -218,17 +257,18 @@ export class Stream<Item> implements AsyncIterable<Item> {
    * which can be turned back into a Stream with `Stream.fromReadableStream()`.
    */
   toReadableStream(): ReadableStream {
-    const self = this;
     let iter: AsyncIterator<Item>;
 
     return makeReadableStream({
-      async start() {
-        iter = self[Symbol.asyncIterator]();
+      start: async () => {
+        iter = this[Symbol.asyncIterator]();
       },
       async pull(ctrl: any) {
         try {
           const { value, done } = await iter.next();
-          if (done) return ctrl.close();
+          if (done) {
+            return ctrl.close();
+          }
 
           const bytes = encodeUTF8(JSON.stringify(value) + '\n');
 
@@ -244,6 +284,11 @@ export class Stream<Item> implements AsyncIterable<Item> {
   }
 }
 
+/**
+ * Decodes complete SSE records from a response and aborts when its body is absent.
+ *
+ * @yields {ServerSentEvent} Each decoded server-sent event in wire order.
+ */
 export async function* _iterSSEMessages(
   response: Response,
   controller: AbortController,
@@ -251,7 +296,7 @@ export async function* _iterSSEMessages(
   if (!response.body) {
     controller.abort();
     if (
-      typeof (globalThis as any).navigator !== 'undefined' &&
+      (globalThis as any).navigator !== undefined &&
       (globalThis as any).navigator.product === 'ReactNative'
     ) {
       throw new OpenAIError(
@@ -268,69 +313,105 @@ export async function* _iterSSEMessages(
   for await (const sseChunk of iterSSEChunks(iter)) {
     for (const line of lineDecoder.decode(sseChunk)) {
       const sse = sseDecoder.decode(line);
-      if (sse) yield sse;
+      if (sse) {
+        yield sse;
+      }
     }
   }
 
   for (const line of lineDecoder.flush()) {
     const sse = sseDecoder.decode(line);
-    if (sse) yield sse;
+    if (sse) {
+      yield sse;
+    }
   }
 }
 
+// A `\r\n\r\n` separator may retain up to three bytes from the previous chunk.
+const DOUBLE_NEWLINE_DELIMITER_MAX_OVERLAP_BYTES = 3;
+
 /**
  * Given an async iterable iterator, iterates over it and yields full
  * SSE chunks, i.e. yields when a double new-line is encountered.
+ *
+ * @yields {Uint8Array} A complete SSE chunk.
  */
 async function* iterSSEChunks(iterator: AsyncIterableIterator<Bytes>): AsyncGenerator<Uint8Array> {
   let data = new Uint8Array();
+  let dataStart = 0;
+  let dataEnd = 0;
+  let searchStartIndex = 0;
 
   for await (const chunk of iterator) {
     if (chunk == null) {
       continue;
     }
 
-    const binaryChunk =
-      chunk instanceof ArrayBuffer ? new Uint8Array(chunk)
-      : typeof chunk === 'string' ? encodeUTF8(chunk)
-      : chunk;
+    let binaryChunk: Uint8Array;
+    if (chunk instanceof ArrayBuffer) {
+      binaryChunk = new Uint8Array(chunk);
+    } else if (typeof chunk === 'string') {
+      binaryChunk = encodeUTF8(chunk);
+    } else {
+      binaryChunk = chunk;
+    }
+
+    if (dataEnd + binaryChunk.length > data.length) {
+      const bufferedLength = dataEnd - dataStart;
 
-    let newData = new Uint8Array(data.length + binaryChunk.length);
-    newData.set(data);
-    newData.set(binaryChunk, data.length);
-    data = newData;
+      // Compact only when it reclaims substantial space without moving a large live tail repeatedly.
+      if (dataStart >= data.length / 2 && bufferedLength + binaryChunk.length <= data.length) {
+        data.copyWithin(0, dataStart, dataEnd);
+      } else {
+        const newData = new Uint8Array(Math.max(data.length * 2, bufferedLength + binaryChunk.length));
+        newData.set(data.subarray(dataStart, dataEnd));
+        data = newData;
+      }
+
+      searchStartIndex -= dataStart;
+      dataStart = 0;
+      dataEnd = bufferedLength;
+    }
+
+    data.set(binaryChunk, dataEnd);
+    dataEnd += binaryChunk.length;
 
     let patternIndex;
-    while ((patternIndex = findDoubleNewlineIndex(data)) !== -1) {
-      yield data.slice(0, patternIndex);
-      data = data.slice(patternIndex);
+    while ((patternIndex = findDoubleNewlineIndex(data.subarray(searchStartIndex, dataEnd))) !== -1) {
+      patternIndex += searchStartIndex;
+      yield data.slice(dataStart, patternIndex);
+      dataStart = patternIndex;
+      searchStartIndex = dataStart;
     }
+
+    searchStartIndex = Math.max(dataStart, dataEnd - DOUBLE_NEWLINE_DELIMITER_MAX_OVERLAP_BYTES);
   }
 
-  if (data.length > 0) {
-    yield data;
+  if (dataEnd > dataStart) {
+    yield data.slice(dataStart, dataEnd);
   }
 }
 
 class SSEDecoder {
   private data: string[];
-  private event: string | null;
+  private event: string | null = null;
   private chunks: string[];
 
   constructor() {
-    this.event = null;
     this.data = [];
     this.chunks = [];
   }
 
   decode(line: string) {
     if (line.endsWith('\r')) {
-      line = line.substring(0, line.length - 1);
+      line = line.slice(0, -1);
     }
 
     if (!line) {
       // empty line and we didn't previously encounter any messages
-      if (!this.event && !this.data.length) return null;
+      if (!this.event && !this.data.length) {
+        return null;
+      }
 
       const sse: ServerSentEvent = {
         event: this.event,
@@ -351,10 +432,11 @@ class SSEDecoder {
       return null;
     }
 
-    let [fieldname, _, value] = partition(line, ':');
+    const [fieldname, , initialValue] = partition(line, ':');
+    let value = initialValue;
 
     if (value.startsWith(' ')) {
-      value = value.substring(1);
+      value = value.slice(1);
     }
 
     if (fieldname === 'event') {
@@ -370,7 +452,7 @@ class SSEDecoder {
 function partition(str: string, delimiter: string): [string, string, string] {
   const index = str.indexOf(delimiter);
   if (index !== -1) {
-    return [str.substring(0, index), delimiter, str.substring(index + delimiter.length)];
+    return [str.slice(0, index), delimiter, str.slice(index + delimiter.length)];
   }
 
   return [str, '', ''];

package/src/helpers/audio.ts

@@ -4,7 +4,7 @@ import type { ReadableStream as NodeReadableStream } from 'node:stream/web';
 import { platform, versions } from 'node:process';
 import { checkFileSupport } from '../internal/uploads';
 
-const DEFAULT_SAMPLE_RATE = 24000;
+const DEFAULT_SAMPLE_RATE = 24_000;
 const DEFAULT_CHANNELS = 1;
 
 const isNode = Boolean(versions?.node);
@@ -24,7 +24,7 @@ const recordingProviders: Record<NodeJS.Platform, string> = {
 };
 
 function isResponse(stream: NodeJS.ReadableStream | Response | File): stream is Response {
-  return typeof (stream as any).body !== 'undefined';
+  return (stream as any).body !== undefined;
 }
 
 function isFile(stream: NodeJS.ReadableStream | Response | File): stream is File {
@@ -35,22 +35,28 @@ function isFile(stream: NodeJS.ReadableStream | Response | File): stream is File
 async function nodejsPlayAudio(stream: NodeJS.ReadableStream | Response | File): Promise<void> {
   return new Promise((resolve, reject) => {
     try {
-      const ffplay = spawn('ffplay', ['-autoexit', '-nodisp', '-i', 'pipe:0']);
-
       let source: NodeJS.ReadableStream;
       if (isResponse(stream)) {
-        const body = stream.body! as NodeReadableStream | NodeJS.ReadableStream;
-        if ('pipe' in body && typeof body.pipe === 'function') {
-          source = body;
-        } else {
-          source = Readable.fromWeb(body as NodeReadableStream);
+        const body = stream.body as NodeReadableStream | NodeJS.ReadableStream | null;
+        if (!body) {
+          throw new Error('Cannot play audio from a response without a body');
         }
+
+        source =
+          'pipe' in body && typeof body.pipe === 'function'
+            ? body
+            : Readable.fromWeb(body as NodeReadableStream);
       } else if (isFile(stream)) {
         source = Readable.from(stream.stream());
       } else {
         source = stream;
       }
 
+      const ffplay = spawn('ffplay', ['-autoexit', '-nodisp', '-i', 'pipe:0']);
+      ffplay.stdout?.resume();
+      ffplay.stderr?.resume();
+      ffplay.on('error', reject);
+
       pipeline(source, ffplay.stdin, (error) => {
         if (error) {
           ffplay.kill();
@@ -61,6 +67,7 @@ async function nodejsPlayAudio(stream: NodeJS.ReadableStream | Response | File):
       ffplay.on('close', (code: number) => {
         if (code !== 0) {
           reject(new Error(`ffplay process exited with code ${code}`));
+          return;
         }
         resolve();
       });
@@ -70,6 +77,17 @@ async function nodejsPlayAudio(stream: NodeJS.ReadableStream | Response | File):
   });
 }
 
+/**
+ * Plays audio from a Node.js readable stream, fetch response, or `File`.
+ *
+ * This helper is supported only in Node.js-compatible runtimes and requires
+ * the `ffplay` executable from FFmpeg to be available on `PATH`. Audio is
+ * streamed to `ffplay` without first buffering the complete input.
+ *
+ * @param input Audio data in a format recognized by `ffplay`.
+ * @throws {Error} If playback is unsupported, `ffplay` cannot start or exits
+ * unsuccessfully, the response has no body, or reading the audio input fails.
+ */
 export async function playAudio(input: NodeJS.ReadableStream | Response | File): Promise<void> {
   if (isNode) {
     return nodejsPlayAudio(input);
@@ -80,9 +98,15 @@ export async function playAudio(input: NodeJS.ReadableStream | Response | File):
   );
 }
 
+/** Controls microphone selection and when an in-progress recording is finalized. */
 type RecordAudioOptions = {
+  /** Stops recording when aborted and resolves with the audio captured so far. */
   signal?: AbortSignal;
+
+  /** Zero-based audio-input device number passed to FFmpeg; defaults to `0`. */
   device?: number;
+
+  /** Positive recording duration in milliseconds; nonpositive values disable the timeout. */
   timeout?: number;
 };
 
@@ -91,8 +115,51 @@ function nodejsRecordAudio({ signal, device, timeout }: RecordAudioOptions = {})
   return new Promise((resolve, reject) => {
     const data: any[] = [];
     const provider = recordingProviders[platform];
+    let ffmpeg: ReturnType<typeof spawn> | undefined;
+    let internalSignal: AbortSignal | undefined;
+    let wasStopped = false;
+    let settled = false;
+
+    const collectData = (chunk: Buffer) => {
+      data.push(chunk);
+    };
+    const stopRecording = () => {
+      if (!settled && ffmpeg) {
+        wasStopped ||= ffmpeg.kill('SIGTERM');
+      }
+    };
+    const cleanup = () => {
+      if (settled) {
+        return false;
+      }
+
+      settled = true;
+      signal?.removeEventListener('abort', stopRecording);
+      internalSignal?.removeEventListener('abort', stopRecording);
+      ffmpeg?.stdout?.removeListener('data', collectData);
+      return true;
+    };
+    const rejectRecording = (error: unknown) => {
+      if (cleanup()) {
+        reject(error);
+      }
+    };
+    const returnData = () => {
+      if (!cleanup()) {
+        return;
+      }
+
+      const audioBuffer = Buffer.concat(data);
+      const audioFile = new File([audioBuffer], 'audio.wav', { type: 'audio/wav' });
+      resolve(audioFile);
+    };
+
     try {
-      const ffmpeg = spawn(
+      if (typeof timeout === 'number' && (timeout > 0 || Number.isNaN(timeout))) {
+        internalSignal = AbortSignal.timeout(timeout);
+      }
+
+      ffmpeg = spawn(
         'ffmpeg',
         [
           '-f',
@@ -108,48 +175,56 @@ function nodejsRecordAudio({ signal, device, timeout }: RecordAudioOptions = {})
           'pipe:1',
         ],
         {
-          stdio: ['ignore', 'pipe', 'pipe'],
+          stdio: ['ignore', 'pipe', 'ignore'],
         },
       );
 
-      ffmpeg.stdout.on('data', (chunk) => {
-        data.push(chunk);
-      });
+      ffmpeg.stdout?.on('data', collectData);
 
       ffmpeg.on('error', (error) => {
         console.error(error);
-        reject(error);
+        rejectRecording(error);
       });
 
       ffmpeg.on('close', (code) => {
+        if (code !== 0 && !wasStopped) {
+          rejectRecording(new Error(`ffmpeg process exited with code ${code}`));
+          return;
+        }
         returnData();
       });
 
-      function returnData() {
-        const audioBuffer = Buffer.concat(data);
-        const audioFile = new File([audioBuffer], 'audio.wav', { type: 'audio/wav' });
-        resolve(audioFile);
-      }
-
-      if (typeof timeout === 'number' && timeout > 0) {
-        const internalSignal = AbortSignal.timeout(timeout);
-        internalSignal.addEventListener('abort', () => {
-          ffmpeg.kill('SIGTERM');
-        });
-      }
+      internalSignal?.addEventListener('abort', stopRecording, { once: true });
 
       if (signal) {
-        signal.addEventListener('abort', () => {
-          ffmpeg.kill('SIGTERM');
-        });
+        if (signal.aborted) {
+          stopRecording();
+        } else {
+          signal.addEventListener('abort', stopRecording, { once: true });
+        }
       }
     } catch (error) {
-      reject(error);
+      stopRecording();
+      rejectRecording(error);
     }
   });
 }
 
-export async function recordAudio(options: RecordAudioOptions = {}) {
+/**
+ * Records microphone audio into a mono, 24 kHz WAV `File` named `audio.wav`.
+ *
+ * This helper is supported only in Node.js-compatible runtimes and requires
+ * the `ffmpeg` executable from FFmpeg to be available on `PATH`. Recording
+ * continues until the FFmpeg process exits, the supplied signal is aborted, or
+ * a positive timeout elapses. Aborting or timing out finalizes and returns the
+ * audio captured so far instead of rejecting.
+ *
+ * @param options Audio-input device, optional abort signal, and recording timeout.
+ * @returns The captured WAV file with MIME type `audio/wav`.
+ * @throws {Error} If recording is unsupported, `ffmpeg` cannot start, or the
+ * recording process exits unsuccessfully before an intentional stop.
+ */
+export async function recordAudio(options: RecordAudioOptions = {}): Promise<File> {
   if (isNode) {
     return nodejsRecordAudio(options);
   }