@durable-streams/client 0.1.0

package/dist/index.cjs

@@ -0,0 +1,1172 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __typeError = (msg) => {
+  throw TypeError(msg);
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var __accessCheck = (obj, member, msg) => member.has(obj) || __typeError("Cannot " + msg);
+var __privateGet = (obj, member, getter) => (__accessCheck(obj, member, "read from private field"), getter ? getter.call(obj) : member.get(obj));
+var __privateAdd = (obj, member, value) => member.has(obj) ? __typeError("Cannot add the same private member more than once") : member instanceof WeakSet ? member.add(obj) : member.set(obj, value);
+var __privateSet = (obj, member, value, setter) => (__accessCheck(obj, member, "write to private field"), setter ? setter.call(obj, value) : member.set(obj, value), value);
+var __privateMethod = (obj, member, method) => (__accessCheck(obj, member, "access private method"), method);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  BackoffDefaults: () => BackoffDefaults,
+  CURSOR_QUERY_PARAM: () => CURSOR_QUERY_PARAM,
+  DURABLE_STREAM_PROTOCOL_QUERY_PARAMS: () => DURABLE_STREAM_PROTOCOL_QUERY_PARAMS,
+  DurableStream: () => DurableStream,
+  DurableStreamError: () => DurableStreamError,
+  FetchBackoffAbortError: () => FetchBackoffAbortError,
+  FetchError: () => FetchError,
+  InvalidSignalError: () => InvalidSignalError,
+  LIVE_QUERY_PARAM: () => LIVE_QUERY_PARAM,
+  MissingStreamUrlError: () => MissingStreamUrlError,
+  OFFSET_QUERY_PARAM: () => OFFSET_QUERY_PARAM,
+  SSE_COMPATIBLE_CONTENT_TYPES: () => SSE_COMPATIBLE_CONTENT_TYPES,
+  STREAM_CURSOR_HEADER: () => STREAM_CURSOR_HEADER,
+  STREAM_EXPIRES_AT_HEADER: () => STREAM_EXPIRES_AT_HEADER,
+  STREAM_OFFSET_HEADER: () => STREAM_OFFSET_HEADER,
+  STREAM_SEQ_HEADER: () => STREAM_SEQ_HEADER,
+  STREAM_TTL_HEADER: () => STREAM_TTL_HEADER,
+  STREAM_UP_TO_DATE_HEADER: () => STREAM_UP_TO_DATE_HEADER,
+  createFetchWithBackoff: () => createFetchWithBackoff,
+  createFetchWithConsumedBody: () => createFetchWithConsumedBody
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/stream.ts
+var import_fetch_event_source = require("@microsoft/fetch-event-source");
+
+// src/error.ts
+var FetchError = class _FetchError extends Error {
+  constructor(status, text, json, headers, url, message) {
+    super(
+      message || `HTTP Error ${status} at ${url}: ${text ?? JSON.stringify(json)}`
+    );
+    this.url = url;
+    this.name = `FetchError`;
+    this.status = status;
+    this.text = text;
+    this.json = json;
+    this.headers = headers;
+  }
+  static async fromResponse(response, url) {
+    const status = response.status;
+    const headers = Object.fromEntries([...response.headers.entries()]);
+    let text = void 0;
+    let json = void 0;
+    const contentType = response.headers.get(`content-type`);
+    if (!response.bodyUsed) {
+      if (contentType && contentType.includes(`application/json`)) {
+        try {
+          json = await response.json();
+        } catch {
+          text = await response.text();
+        }
+      } else {
+        text = await response.text();
+      }
+    }
+    return new _FetchError(status, text, json, headers, url);
+  }
+};
+var FetchBackoffAbortError = class extends Error {
+  constructor() {
+    super(`Fetch with backoff aborted`);
+    this.name = `FetchBackoffAbortError`;
+  }
+};
+var DurableStreamError = class _DurableStreamError extends Error {
+  constructor(message, code, status, details) {
+    super(message);
+    this.name = `DurableStreamError`;
+    this.code = code;
+    this.status = status;
+    this.details = details;
+  }
+  /**
+   * Create a DurableStreamError from an HTTP response.
+   */
+  static async fromResponse(response, url) {
+    const status = response.status;
+    let details;
+    const contentType = response.headers.get(`content-type`);
+    if (!response.bodyUsed) {
+      if (contentType && contentType.includes(`application/json`)) {
+        try {
+          details = await response.json();
+        } catch {
+          details = await response.text();
+        }
+      } else {
+        details = await response.text();
+      }
+    }
+    const code = statusToCode(status);
+    const message = `Durable stream error at ${url}: ${response.statusText || status}`;
+    return new _DurableStreamError(message, code, status, details);
+  }
+  /**
+   * Create a DurableStreamError from a FetchError.
+   */
+  static fromFetchError(error) {
+    const code = statusToCode(error.status);
+    return new _DurableStreamError(
+      error.message,
+      code,
+      error.status,
+      error.json ?? error.text
+    );
+  }
+};
+function statusToCode(status) {
+  switch (status) {
+    case 400:
+      return `BAD_REQUEST`;
+    case 401:
+      return `UNAUTHORIZED`;
+    case 403:
+      return `FORBIDDEN`;
+    case 404:
+      return `NOT_FOUND`;
+    case 409:
+      return `CONFLICT_SEQ`;
+    case 429:
+      return `RATE_LIMITED`;
+    case 503:
+      return `BUSY`;
+    default:
+      return `UNKNOWN`;
+  }
+}
+var MissingStreamUrlError = class extends Error {
+  constructor() {
+    super(`Invalid stream options: missing required url parameter`);
+    this.name = `MissingStreamUrlError`;
+  }
+};
+var InvalidSignalError = class extends Error {
+  constructor() {
+    super(`Invalid signal option. It must be an instance of AbortSignal.`);
+    this.name = `InvalidSignalError`;
+  }
+};
+
+// src/constants.ts
+var STREAM_OFFSET_HEADER = `stream-offset`;
+var STREAM_CURSOR_HEADER = `stream-cursor`;
+var STREAM_UP_TO_DATE_HEADER = `stream-up-to-date`;
+var STREAM_SEQ_HEADER = `stream-seq`;
+var STREAM_TTL_HEADER = `stream-ttl`;
+var STREAM_EXPIRES_AT_HEADER = `stream-expires-at`;
+var OFFSET_QUERY_PARAM = `offset`;
+var LIVE_QUERY_PARAM = `live`;
+var CURSOR_QUERY_PARAM = `cursor`;
+var SSE_COMPATIBLE_CONTENT_TYPES = [`text/`, `application/json`];
+var DURABLE_STREAM_PROTOCOL_QUERY_PARAMS = [
+  OFFSET_QUERY_PARAM,
+  LIVE_QUERY_PARAM,
+  CURSOR_QUERY_PARAM
+];
+
+// src/fetch.ts
+var HTTP_RETRY_STATUS_CODES = [429, 503];
+var BackoffDefaults = {
+  initialDelay: 100,
+  maxDelay: 6e4,
+  // Cap at 60s
+  multiplier: 1.3,
+  maxRetries: Infinity
+  // Retry forever by default
+};
+function parseRetryAfterHeader(retryAfter) {
+  if (!retryAfter) return 0;
+  const retryAfterSec = Number(retryAfter);
+  if (Number.isFinite(retryAfterSec) && retryAfterSec > 0) {
+    return retryAfterSec * 1e3;
+  }
+  const retryDate = Date.parse(retryAfter);
+  if (!isNaN(retryDate)) {
+    const deltaMs = retryDate - Date.now();
+    return Math.max(0, Math.min(deltaMs, 36e5));
+  }
+  return 0;
+}
+function createFetchWithBackoff(fetchClient, backoffOptions = BackoffDefaults) {
+  const {
+    initialDelay,
+    maxDelay,
+    multiplier,
+    debug = false,
+    onFailedAttempt,
+    maxRetries = Infinity
+  } = backoffOptions;
+  return async (...args) => {
+    const url = args[0];
+    const options = args[1];
+    let delay = initialDelay;
+    let attempt = 0;
+    while (true) {
+      try {
+        const result = await fetchClient(...args);
+        if (result.ok) {
+          return result;
+        }
+        const err = await FetchError.fromResponse(result, url.toString());
+        throw err;
+      } catch (e) {
+        onFailedAttempt?.();
+        if (options?.signal?.aborted) {
+          throw new FetchBackoffAbortError();
+        } else if (e instanceof FetchError && !HTTP_RETRY_STATUS_CODES.includes(e.status) && e.status >= 400 && e.status < 500) {
+          throw e;
+        } else {
+          attempt++;
+          if (attempt > maxRetries) {
+            if (debug) {
+              console.log(
+                `Max retries reached (${attempt}/${maxRetries}), giving up`
+              );
+            }
+            throw e;
+          }
+          const serverMinimumMs = e instanceof FetchError ? parseRetryAfterHeader(e.headers[`retry-after`]) : 0;
+          const jitter = Math.random() * delay;
+          const clientBackoffMs = Math.min(jitter, maxDelay);
+          const waitMs = Math.max(serverMinimumMs, clientBackoffMs);
+          if (debug) {
+            const source = serverMinimumMs > 0 ? `server+client` : `client`;
+            console.log(
+              `Retry attempt #${attempt} after ${waitMs}ms (${source}, serverMin=${serverMinimumMs}ms, clientBackoff=${clientBackoffMs}ms)`
+            );
+          }
+          await new Promise((resolve) => setTimeout(resolve, waitMs));
+          delay = Math.min(delay * multiplier, maxDelay);
+        }
+      }
+    }
+  };
+}
+var NO_BODY_STATUS_CODES = [201, 204, 205];
+function createFetchWithConsumedBody(fetchClient) {
+  return async (...args) => {
+    const url = args[0];
+    const res = await fetchClient(...args);
+    try {
+      if (res.status < 200 || NO_BODY_STATUS_CODES.includes(res.status)) {
+        return res;
+      }
+      const buf = await res.arrayBuffer();
+      return new Response(buf, {
+        status: res.status,
+        statusText: res.statusText,
+        headers: res.headers
+      });
+    } catch (err) {
+      if (args[1]?.signal?.aborted) {
+        throw new FetchBackoffAbortError();
+      }
+      throw new FetchError(
+        res.status,
+        void 0,
+        void 0,
+        Object.fromEntries([...res.headers.entries()]),
+        url.toString(),
+        err instanceof Error ? err.message : typeof err === `string` ? err : `failed to read body`
+      );
+    }
+  };
+}
+function chainAborter(aborter, sourceSignal) {
+  let cleanup = noop;
+  if (!sourceSignal) {
+  } else if (sourceSignal.aborted) {
+    aborter.abort(sourceSignal.reason);
+  } else {
+    const abortParent = () => aborter.abort(sourceSignal.reason);
+    sourceSignal.addEventListener(`abort`, abortParent, {
+      once: true,
+      signal: aborter.signal
+    });
+    cleanup = () => sourceSignal.removeEventListener(`abort`, abortParent);
+  }
+  return {
+    signal: aborter.signal,
+    cleanup
+  };
+}
+function noop() {
+}
+
+// src/stream.ts
+var _options, _fetchClient, _sseFetchClient, _onError, _DurableStream_instances, buildRequest_fn, resolveHeaders_fn, parseReadResponse_fn, isSSECompatible_fn, createSSEIterator_fn, parseSSEData_fn;
+var _DurableStream = class _DurableStream {
+  /**
+   * Create a cold handle to a stream.
+   * No network IO is performed by the constructor.
+   */
+  constructor(opts) {
+    __privateAdd(this, _DurableStream_instances);
+    __privateAdd(this, _options);
+    __privateAdd(this, _fetchClient);
+    __privateAdd(this, _sseFetchClient);
+    __privateAdd(this, _onError);
+    validateOptions(opts);
+    this.url = opts.url;
+    __privateSet(this, _options, opts);
+    __privateSet(this, _onError, opts.onError);
+    const baseFetchClient = opts.fetch ?? ((...args) => fetch(...args));
+    const backOffOpts = {
+      ...opts.backoffOptions ?? BackoffDefaults
+    };
+    const fetchWithBackoffClient = createFetchWithBackoff(
+      baseFetchClient,
+      backOffOpts
+    );
+    __privateSet(this, _sseFetchClient, fetchWithBackoffClient);
+    __privateSet(this, _fetchClient, createFetchWithConsumedBody(fetchWithBackoffClient));
+  }
+  // ============================================================================
+  // Static convenience methods
+  // ============================================================================
+  /**
+   * Create a new stream (create-only PUT) and return a handle.
+   * Fails with DurableStreamError(code="CONFLICT_EXISTS") if it already exists.
+   */
+  static async create(opts) {
+    const stream = new _DurableStream(opts);
+    await stream.create({
+      contentType: opts.contentType,
+      ttlSeconds: opts.ttlSeconds,
+      expiresAt: opts.expiresAt,
+      body: opts.body
+    });
+    return stream;
+  }
+  /**
+   * Validate that a stream exists and fetch metadata via HEAD.
+   * Returns a handle with contentType populated (if sent by server).
+   */
+  static async connect(opts) {
+    const stream = new _DurableStream(opts);
+    await stream.head();
+    return stream;
+  }
+  /**
+   * HEAD metadata for a stream without creating a handle.
+   */
+  static async head(opts) {
+    const stream = new _DurableStream(opts);
+    return stream.head();
+  }
+  /**
+   * Delete a stream without creating a handle.
+   */
+  static async delete(opts) {
+    const stream = new _DurableStream(opts);
+    return stream.delete();
+  }
+  // ============================================================================
+  // Instance methods
+  // ============================================================================
+  /**
+   * HEAD metadata for this stream.
+   */
+  async head(opts) {
+    const { requestHeaders, fetchUrl } = await __privateMethod(this, _DurableStream_instances, buildRequest_fn).call(this);
+    const response = await __privateGet(this, _fetchClient).call(this, fetchUrl.toString(), {
+      method: `HEAD`,
+      headers: requestHeaders,
+      signal: opts?.signal ?? __privateGet(this, _options).signal
+    });
+    if (!response.ok) {
+      if (response.status === 404) {
+        throw new DurableStreamError(
+          `Stream not found: ${this.url}`,
+          `NOT_FOUND`,
+          404
+        );
+      }
+      throw await DurableStreamError.fromResponse(response, this.url);
+    }
+    const contentType = response.headers.get(`content-type`) ?? void 0;
+    const offset = response.headers.get(STREAM_OFFSET_HEADER) ?? void 0;
+    const etag = response.headers.get(`etag`) ?? void 0;
+    const cacheControl = response.headers.get(`cache-control`) ?? void 0;
+    if (contentType) {
+      this.contentType = contentType;
+    }
+    return {
+      exists: true,
+      contentType,
+      offset,
+      etag,
+      cacheControl
+    };
+  }
+  /**
+   * Create this stream (create-only PUT) using the URL/auth from the handle.
+   */
+  async create(opts) {
+    const { requestHeaders, fetchUrl } = await __privateMethod(this, _DurableStream_instances, buildRequest_fn).call(this);
+    if (opts?.contentType) {
+      requestHeaders[`content-type`] = opts.contentType;
+    }
+    if (opts?.ttlSeconds !== void 0) {
+      requestHeaders[STREAM_TTL_HEADER] = String(opts.ttlSeconds);
+    }
+    if (opts?.expiresAt) {
+      requestHeaders[STREAM_EXPIRES_AT_HEADER] = opts.expiresAt;
+    }
+    const body = encodeBody(opts?.body);
+    const response = await __privateGet(this, _fetchClient).call(this, fetchUrl.toString(), {
+      method: `PUT`,
+      headers: requestHeaders,
+      body,
+      signal: __privateGet(this, _options).signal
+    });
+    if (!response.ok) {
+      if (response.status === 409) {
+        throw new DurableStreamError(
+          `Stream already exists: ${this.url}`,
+          `CONFLICT_EXISTS`,
+          409
+        );
+      }
+      throw await DurableStreamError.fromResponse(response, this.url);
+    }
+    const responseContentType = response.headers.get(`content-type`);
+    if (responseContentType) {
+      this.contentType = responseContentType;
+    } else if (opts?.contentType) {
+      this.contentType = opts.contentType;
+    }
+    return this;
+  }
+  /**
+   * Delete this stream.
+   */
+  async delete(opts) {
+    const { requestHeaders, fetchUrl } = await __privateMethod(this, _DurableStream_instances, buildRequest_fn).call(this);
+    const response = await __privateGet(this, _fetchClient).call(this, fetchUrl.toString(), {
+      method: `DELETE`,
+      headers: requestHeaders,
+      signal: opts?.signal ?? __privateGet(this, _options).signal
+    });
+    if (!response.ok) {
+      if (response.status === 404) {
+        throw new DurableStreamError(
+          `Stream not found: ${this.url}`,
+          `NOT_FOUND`,
+          404
+        );
+      }
+      throw await DurableStreamError.fromResponse(response, this.url);
+    }
+  }
+  /**
+   * Append a single payload to the stream.
+   *
+   * - `body` may be Uint8Array, string, or any Fetch BodyInit.
+   * - Strings are encoded as UTF-8.
+   * - `seq` (if provided) is sent as stream-seq (writer coordination).
+   */
+  async append(body, opts) {
+    const { requestHeaders, fetchUrl } = await __privateMethod(this, _DurableStream_instances, buildRequest_fn).call(this);
+    if (opts?.contentType) {
+      requestHeaders[`content-type`] = opts.contentType;
+    } else if (this.contentType) {
+      requestHeaders[`content-type`] = this.contentType;
+    }
+    if (opts?.seq) {
+      requestHeaders[STREAM_SEQ_HEADER] = opts.seq;
+    }
+    const encodedBody = encodeBody(body);
+    const response = await __privateGet(this, _fetchClient).call(this, fetchUrl.toString(), {
+      method: `POST`,
+      headers: requestHeaders,
+      body: encodedBody,
+      signal: opts?.signal ?? __privateGet(this, _options).signal
+    });
+    if (!response.ok) {
+      if (response.status === 404) {
+        throw new DurableStreamError(
+          `Stream not found: ${this.url}`,
+          `NOT_FOUND`,
+          404
+        );
+      }
+      if (response.status === 409) {
+        throw new DurableStreamError(
+          `Sequence conflict: seq is lower than last appended`,
+          `CONFLICT_SEQ`,
+          409
+        );
+      }
+      if (response.status === 400) {
+        throw new DurableStreamError(
+          `Bad request (possibly content-type mismatch)`,
+          `BAD_REQUEST`,
+          400
+        );
+      }
+      throw await DurableStreamError.fromResponse(response, this.url);
+    }
+  }
+  /**
+   * Append a streaming body to the stream.
+   *
+   * - `source` yields Uint8Array or string chunks.
+   * - Strings are encoded as UTF-8; no delimiters are added.
+   * - Internally uses chunked transfer or HTTP/2 streaming.
+   */
+  async appendStream(source, opts) {
+    const { requestHeaders, fetchUrl } = await __privateMethod(this, _DurableStream_instances, buildRequest_fn).call(this);
+    if (opts?.contentType) {
+      requestHeaders[`content-type`] = opts.contentType;
+    } else if (this.contentType) {
+      requestHeaders[`content-type`] = this.contentType;
+    }
+    if (opts?.seq) {
+      requestHeaders[STREAM_SEQ_HEADER] = opts.seq;
+    }
+    const body = toReadableStream(source);
+    const response = await __privateGet(this, _fetchClient).call(this, fetchUrl.toString(), {
+      method: `POST`,
+      headers: requestHeaders,
+      body,
+      // @ts-expect-error - duplex is needed for streaming but not in types
+      duplex: `half`,
+      signal: opts?.signal ?? __privateGet(this, _options).signal
+    });
+    if (!response.ok) {
+      if (response.status === 404) {
+        throw new DurableStreamError(
+          `Stream not found: ${this.url}`,
+          `NOT_FOUND`,
+          404
+        );
+      }
+      if (response.status === 409) {
+        throw new DurableStreamError(
+          `Sequence conflict: seq is lower than last appended`,
+          `CONFLICT_SEQ`,
+          409
+        );
+      }
+      throw await DurableStreamError.fromResponse(response, this.url);
+    }
+  }
+  /**
+   * One-shot read.
+   *
+   * Performs a single GET from the specified offset/mode and returns a chunk.
+   * Caller is responsible for persisting the returned offset if they want to resume.
+   */
+  async read(opts) {
+    const { requestHeaders, fetchUrl } = await __privateMethod(this, _DurableStream_instances, buildRequest_fn).call(this, opts);
+    const response = await __privateGet(this, _fetchClient).call(this, fetchUrl.toString(), {
+      method: `GET`,
+      headers: requestHeaders,
+      signal: opts?.signal ?? __privateGet(this, _options).signal
+    });
+    if (!response.ok) {
+      if (response.status === 404) {
+        throw new DurableStreamError(
+          `Stream not found: ${this.url}`,
+          `NOT_FOUND`,
+          404
+        );
+      }
+      if (response.status === 204) {
+        const offset = response.headers.get(STREAM_OFFSET_HEADER) ?? opts?.offset ?? ``;
+        return {
+          data: new Uint8Array(0),
+          offset,
+          upToDate: true,
+          contentType: this.contentType
+        };
+      }
+      throw await DurableStreamError.fromResponse(response, this.url);
+    }
+    return __privateMethod(this, _DurableStream_instances, parseReadResponse_fn).call(this, response);
+  }
+  /**
+   * Follow the stream as an AsyncIterable of chunks.
+   *
+   * Default behaviour:
+   * - From `offset` (or start if omitted), repeatedly perform catch-up reads
+   *   until a chunk with upToDate=true.
+   * - Then switch to live mode:
+   *   - SSE if content-type is text/* or application/json;
+   *   - otherwise long-poll.
+   *
+   * Explicit live override:
+   * - live="catchup": only catch-up, stop at upToDate.
+   * - live="long-poll": start long-polling immediately from offset.
+   * - live="sse": start SSE immediately (throws if SSE not supported).
+   */
+  follow(opts) {
+    const stream = this;
+    const liveMode = opts?.live;
+    let currentOffset = opts?.offset;
+    let currentCursor = opts?.cursor;
+    let isUpToDate = false;
+    const aborter = new AbortController();
+    const { signal, cleanup } = chainAborter(
+      aborter,
+      opts?.signal ?? __privateGet(stream, _options).signal
+    );
+    let sseIterator = null;
+    return {
+      [Symbol.asyncIterator]() {
+        return {
+          async next() {
+            var _a, _b, _c, _d;
+            try {
+              if (signal.aborted) {
+                cleanup();
+                return { done: true, value: void 0 };
+              }
+              if (sseIterator) {
+                const result = await sseIterator.next();
+                if (result.done) {
+                  cleanup();
+                }
+                return result;
+              }
+              if (liveMode === `catchup`) {
+                if (isUpToDate) {
+                  cleanup();
+                  return { done: true, value: void 0 };
+                }
+                const chunk = await stream.read({
+                  offset: currentOffset,
+                  cursor: currentCursor,
+                  signal
+                });
+                currentOffset = chunk.offset;
+                currentCursor = chunk.cursor;
+                isUpToDate = chunk.upToDate;
+                return { done: false, value: chunk };
+              }
+              if (liveMode === `sse`) {
+                sseIterator = __privateMethod(_a = stream, _DurableStream_instances, createSSEIterator_fn).call(_a, currentOffset, currentCursor, signal);
+                return sseIterator.next();
+              }
+              if (liveMode === `long-poll`) {
+                const chunk = await stream.read({
+                  offset: currentOffset,
+                  cursor: currentCursor,
+                  live: `long-poll`,
+                  signal
+                });
+                currentOffset = chunk.offset;
+                currentCursor = chunk.cursor;
+                return { done: false, value: chunk };
+              }
+              if (!isUpToDate) {
+                const chunk = await stream.read({
+                  offset: currentOffset,
+                  cursor: currentCursor,
+                  signal
+                });
+                currentOffset = chunk.offset;
+                currentCursor = chunk.cursor;
+                isUpToDate = chunk.upToDate;
+                if (chunk.contentType && !stream.contentType) {
+                  stream.contentType = chunk.contentType;
+                }
+                return { done: false, value: chunk };
+              }
+              if (__privateMethod(_b = stream, _DurableStream_instances, isSSECompatible_fn).call(_b)) {
+                sseIterator = __privateMethod(_c = stream, _DurableStream_instances, createSSEIterator_fn).call(_c, currentOffset, currentCursor, signal);
+                return sseIterator.next();
+              } else {
+                const chunk = await stream.read({
+                  offset: currentOffset,
+                  cursor: currentCursor,
+                  live: `long-poll`,
+                  signal
+                });
+                currentOffset = chunk.offset;
+                currentCursor = chunk.cursor;
+                return { done: false, value: chunk };
+              }
+            } catch (e) {
+              if (e instanceof FetchBackoffAbortError) {
+                cleanup();
+                return { done: true, value: void 0 };
+              }
+              if (__privateGet(stream, _onError) && e instanceof Error) {
+                const retryOpts = await __privateGet(_d = stream, _onError).call(_d, e);
+                if (retryOpts && typeof retryOpts === `object`) {
+                  if (retryOpts.params) {
+                    __privateGet(stream, _options).params = {
+                      ...__privateGet(stream, _options).params ?? {},
+                      ...retryOpts.params
+                    };
+                  }
+                  if (retryOpts.headers) {
+                    __privateGet(stream, _options).headers = {
+                      ...__privateGet(stream, _options).headers ?? {},
+                      ...retryOpts.headers
+                    };
+                  }
+                  return this.next();
+                }
+              }
+              cleanup();
+              throw e;
+            }
+          },
+          async return() {
+            if (sseIterator?.return) {
+              await sseIterator.return();
+            }
+            cleanup();
+            aborter.abort();
+            return { done: true, value: void 0 };
+          }
+        };
+      }
+    };
+  }
+  /**
+   * Wrap follow() in a Web ReadableStream for piping.
+   *
+   * Backpressure:
+   * - One chunk is pulled from follow() per pull() call, so standard
+   *   Web Streams backpressure semantics apply.
+   *
+   * Cancellation:
+   * - rs.cancel() will stop follow() and abort any in-flight request.
+   */
+  toReadableStream(opts) {
+    const iterator = this.follow(opts)[Symbol.asyncIterator]();
+    return new ReadableStream({
+      async pull(controller) {
+        try {
+          const { done, value } = await iterator.next();
+          if (done) {
+            controller.close();
+          } else {
+            controller.enqueue(value);
+          }
+        } catch (e) {
+          controller.error(e);
+        }
+      },
+      cancel() {
+        iterator.return?.();
+      }
+    });
+  }
+  /**
+   * Wrap follow() in a Web ReadableStream<Uint8Array> for piping raw bytes.
+   *
+   * This is the native format for many web stream APIs.
+   */
+  toByteStream(opts) {
+    const iterator = this.follow(opts)[Symbol.asyncIterator]();
+    return new ReadableStream({
+      async pull(controller) {
+        try {
+          const { done, value } = await iterator.next();
+          if (done) {
+            controller.close();
+          } else {
+            controller.enqueue(value.data);
+          }
+        } catch (e) {
+          controller.error(e);
+        }
+      },
+      cancel() {
+        iterator.return?.();
+      }
+    });
+  }
+  /**
+   * Convenience: interpret data as JSON messages.
+   * Parses each chunk's data as JSON and yields the parsed values.
+   */
+  async *json(opts) {
+    const decoder = new TextDecoder();
+    for await (const chunk of this.follow(opts)) {
+      if (chunk.data.length > 0) {
+        const text = decoder.decode(chunk.data);
+        const lines = text.split(`
+`).filter((l) => l.trim());
+        for (const line of lines) {
+          yield JSON.parse(line);
+        }
+      }
+    }
+  }
+  /**
+   * Convenience: interpret data as text (UTF-8).
+   */
+  async *text(opts) {
+    const decoder = opts?.decoder ?? new TextDecoder();
+    for await (const chunk of this.follow(opts)) {
+      if (chunk.data.length > 0) {
+        yield decoder.decode(chunk.data, { stream: true });
+      }
+    }
+  }
+};
+_options = new WeakMap();
+_fetchClient = new WeakMap();
+_sseFetchClient = new WeakMap();
+_onError = new WeakMap();
+_DurableStream_instances = new WeakSet();
+buildRequest_fn = async function(readOpts) {
+  const requestHeaders = await __privateMethod(this, _DurableStream_instances, resolveHeaders_fn).call(this);
+  const fetchUrl = new URL(this.url);
+  const params = __privateGet(this, _options).params;
+  if (params) {
+    for (const [key, value] of Object.entries(params)) {
+      if (value !== void 0) {
+        const resolved = await resolveValue(value);
+        fetchUrl.searchParams.set(key, resolved);
+      }
+    }
+  }
+  if (readOpts) {
+    if (readOpts.offset) {
+      fetchUrl.searchParams.set(OFFSET_QUERY_PARAM, readOpts.offset);
+    }
+    if (readOpts.live) {
+      fetchUrl.searchParams.set(LIVE_QUERY_PARAM, readOpts.live);
+    }
+    if (readOpts.cursor) {
+      fetchUrl.searchParams.set(CURSOR_QUERY_PARAM, readOpts.cursor);
+    }
+  }
+  return { requestHeaders, fetchUrl };
+};
+resolveHeaders_fn = async function() {
+  const headers = {};
+  const auth = __privateGet(this, _options).auth;
+  if (auth) {
+    if (`token` in auth) {
+      const headerName = auth.headerName ?? `authorization`;
+      headers[headerName] = `Bearer ${auth.token}`;
+    } else if (`headers` in auth) {
+      Object.assign(headers, auth.headers);
+    } else if (`getHeaders` in auth) {
+      const authHeaders = await auth.getHeaders();
+      Object.assign(headers, authHeaders);
+    }
+  }
+  const headersOpt = __privateGet(this, _options).headers;
+  if (headersOpt) {
+    for (const [key, value] of Object.entries(headersOpt)) {
+      headers[key] = await resolveValue(value);
+    }
+  }
+  return headers;
+};
+parseReadResponse_fn = async function(response) {
+  const data = new Uint8Array(await response.arrayBuffer());
+  const offset = response.headers.get(STREAM_OFFSET_HEADER) ?? ``;
+  const cursor = response.headers.get(STREAM_CURSOR_HEADER) ?? void 0;
+  const upToDate = response.headers.has(STREAM_UP_TO_DATE_HEADER);
+  const etag = response.headers.get(`etag`) ?? void 0;
+  const contentType = response.headers.get(`content-type`) ?? void 0;
+  if (contentType && !this.contentType) {
+    this.contentType = contentType;
+  }
+  return {
+    data,
+    offset,
+    cursor,
+    upToDate,
+    etag,
+    contentType
+  };
+};
+/**
+ * Check if the stream's content type is compatible with SSE.
+ */
+isSSECompatible_fn = function() {
+  if (!this.contentType) return false;
+  return SSE_COMPATIBLE_CONTENT_TYPES.some(
+    (prefix) => this.contentType.startsWith(prefix)
+  );
+};
+/**
+ * Create an SSE connection that maintains a persistent connection with an internal queue.
+ * Returns an AsyncIterator that yields chunks as they arrive.
+ *
+ * Follows the Electric client pattern:
+ * - Buffer data events until control event (up-to-date)
+ * - Flush buffer on control event
+ * - Use promise chain for sequential processing
+ */
+createSSEIterator_fn = function(initialOffset, initialCursor, signal) {
+  if (!__privateMethod(this, _DurableStream_instances, isSSECompatible_fn).call(this)) {
+    throw new DurableStreamError(
+      `SSE is not supported for content-type: ${this.contentType}`,
+      `SSE_NOT_SUPPORTED`,
+      400
+    );
+  }
+  const chunkQueue = [];
+  let pendingResolve = null;
+  let currentOffset = initialOffset;
+  let currentCursor = initialCursor;
+  let connectionClosed = false;
+  let connectionError = null;
+  const connectionAbort = new AbortController();
+  let dataBuffer = [];
+  const stream = this;
+  const startConnection = async () => {
+    var _a;
+    const { requestHeaders, fetchUrl } = await __privateMethod(_a = stream, _DurableStream_instances, buildRequest_fn).call(_a, {
+      offset: currentOffset,
+      cursor: currentCursor,
+      live: `sse`
+    });
+    try {
+      await (0, import_fetch_event_source.fetchEventSource)(fetchUrl.toString(), {
+        headers: requestHeaders,
+        fetch: __privateGet(stream, _sseFetchClient),
+        signal: signal.aborted ? signal : connectionAbort.signal,
+        onopen: async (response) => {
+          if (!response.ok) {
+            throw await DurableStreamError.fromResponse(response, stream.url);
+          }
+          const contentType = response.headers.get(`content-type`);
+          if (contentType && !stream.contentType) {
+            stream.contentType = contentType;
+          }
+        },
+        onmessage: (event) => {
+          var _a2;
+          if (event.event === `data` && event.data) {
+            const data = __privateMethod(_a2 = stream, _DurableStream_instances, parseSSEData_fn).call(_a2, event.data);
+            dataBuffer.push(data);
+          } else if (event.event === `control` && event.data) {
+            try {
+              const control = JSON.parse(event.data);
+              const newOffset = control[STREAM_OFFSET_HEADER];
+              const newCursor = control[STREAM_CURSOR_HEADER];
+              const totalSize = dataBuffer.reduce(
+                (sum, buf) => sum + buf.length,
+                0
+              );
+              const combinedData = new Uint8Array(totalSize);
+              let offset = 0;
+              for (const buf of dataBuffer) {
+                combinedData.set(buf, offset);
+                offset += buf.length;
+              }
+              const chunk = {
+                data: combinedData,
+                offset: newOffset ?? currentOffset ?? ``,
+                cursor: newCursor,
+                upToDate: true,
+                contentType: stream.contentType
+              };
+              currentOffset = chunk.offset;
+              currentCursor = chunk.cursor;
+              dataBuffer = [];
+              if (pendingResolve) {
+                const resolve = pendingResolve;
+                pendingResolve = null;
+                resolve({ done: false, value: chunk });
+              } else {
+                chunkQueue.push(chunk);
+              }
+            } catch {
+            }
+          }
+        },
+        onerror: (error) => {
+          throw error;
+        }
+      });
+    } catch (error) {
+      if (connectionAbort.signal.aborted || signal.aborted) {
+        throw new FetchBackoffAbortError();
+      }
+      throw error;
+    }
+  };
+  const connectionPromise = startConnection().catch((e) => {
+    if (e instanceof FetchBackoffAbortError) {
+      connectionClosed = true;
+    } else {
+      connectionError = e;
+      connectionClosed = true;
+    }
+    if (pendingResolve) {
+      const resolve = pendingResolve;
+      pendingResolve = null;
+      resolve({ done: true, value: void 0 });
+    }
+  });
+  const abortHandler = () => {
+    connectionAbort.abort();
+    connectionClosed = true;
+    if (pendingResolve) {
+      const resolve = pendingResolve;
+      pendingResolve = null;
+      resolve({ done: true, value: void 0 });
+    }
+  };
+  signal.addEventListener(`abort`, abortHandler, { once: true });
+  return {
+    async next() {
+      if (chunkQueue.length > 0) {
+        return { done: false, value: chunkQueue.shift() };
+      }
+      if (connectionError) {
+        throw connectionError;
+      }
+      if (connectionClosed || signal.aborted) {
+        return { done: true, value: void 0 };
+      }
+      return new Promise((resolve) => {
+        pendingResolve = resolve;
+      });
+    },
+    async return() {
+      signal.removeEventListener(`abort`, abortHandler);
+      connectionAbort.abort();
+      connectionClosed = true;
+      await connectionPromise.catch(() => {
+      });
+      return { done: true, value: void 0 };
+    }
+  };
+};
+/**
+ * Parse SSE data payload.
+ * For application/json, data is wrapped in [ and ], so we unwrap it.
+ */
+parseSSEData_fn = function(data) {
+  const lines = data.split(`
+`);
+  const content = lines.map((line) => {
+    if (line.startsWith(`data: `)) {
+      return line.slice(6);
+    }
+    return line;
+  }).join(`
+`);
+  let text = content.trim();
+  if (this.contentType?.includes(`application/json`) && text.startsWith(`[`) && text.endsWith(`]`)) {
+    text = text.slice(1, -1).trim();
+    if (text.endsWith(`,`)) {
+      text = text.slice(0, -1);
+    }
+  }
+  return new TextEncoder().encode(text);
+};
+var DurableStream = _DurableStream;
+async function resolveValue(value) {
+  if (typeof value === `function`) {
+    return value();
+  }
+  return value;
+}
+function encodeBody(body) {
+  if (body === void 0) {
+    return void 0;
+  }
+  if (typeof body === `string`) {
+    return new TextEncoder().encode(body);
+  }
+  if (body instanceof Uint8Array) {
+    return body;
+  }
+  return body;
+}
+function toReadableStream(source) {
+  if (source instanceof ReadableStream) {
+    return source.pipeThrough(
+      new TransformStream({
+        transform(chunk, controller) {
+          if (typeof chunk === `string`) {
+            controller.enqueue(new TextEncoder().encode(chunk));
+          } else {
+            controller.enqueue(chunk);
+          }
+        }
+      })
+    );
+  }
+  const encoder = new TextEncoder();
+  const iterator = source[Symbol.asyncIterator]();
+  return new ReadableStream({
+    async pull(controller) {
+      try {
+        const { done, value } = await iterator.next();
+        if (done) {
+          controller.close();
+        } else if (typeof value === `string`) {
+          controller.enqueue(encoder.encode(value));
+        } else {
+          controller.enqueue(value);
+        }
+      } catch (e) {
+        controller.error(e);
+      }
+    },
+    cancel() {
+      iterator.return?.();
+    }
+  });
+}
+function validateOptions(options) {
+  if (!options.url) {
+    throw new MissingStreamUrlError();
+  }
+  if (options.signal && !(options.signal instanceof AbortSignal)) {
+    throw new InvalidSignalError();
+  }
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BackoffDefaults,
+  CURSOR_QUERY_PARAM,
+  DURABLE_STREAM_PROTOCOL_QUERY_PARAMS,
+  DurableStream,
+  DurableStreamError,
+  FetchBackoffAbortError,
+  FetchError,
+  InvalidSignalError,
+  LIVE_QUERY_PARAM,
+  MissingStreamUrlError,
+  OFFSET_QUERY_PARAM,
+  SSE_COMPATIBLE_CONTENT_TYPES,
+  STREAM_CURSOR_HEADER,
+  STREAM_EXPIRES_AT_HEADER,
+  STREAM_OFFSET_HEADER,
+  STREAM_SEQ_HEADER,
+  STREAM_TTL_HEADER,
+  STREAM_UP_TO_DATE_HEADER,
+  createFetchWithBackoff,
+  createFetchWithConsumedBody
+});
+//# sourceMappingURL=index.cjs.map