@durable-streams/client 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,627 @@
+/**
+ * Durable Streams TypeScript Client Types
+ *
+ * Following the Electric Durable Stream Protocol specification.
+ */
+/**
+ * Offset string - opaque to the client.
+ * Format: "<read-seq>_<byte-offset>"
+ *
+ * Always use the returned `offset` field from reads/follows as the next `offset` you pass in.
+ */
+type Offset = string;
+/**
+ * Type for values that can be provided immediately or resolved asynchronously.
+ */
+type MaybePromise<T> = T | Promise<T>;
+/**
+ * Auth configuration for requests.
+ *
+ * Supports:
+ * - Fixed tokens with optional custom header name
+ * - Arbitrary static headers
+ * - Async header resolution (e.g., for short-lived tokens)
+ */
+type Auth = {
+    token: string;
+    headerName?: string;
+} | {
+    headers: Record<string, string>;
+} | {
+    getHeaders: () => Promise<Record<string, string>>;
+};
+/**
+ * Headers record where values can be static strings or async functions.
+ * Following the @electric-sql/client pattern for dynamic headers.
+ */
+type HeadersRecord = {
+    [key: string]: string | (() => MaybePromise<string>);
+};
+/**
+ * Params record where values can be static or async functions.
+ * Following the @electric-sql/client pattern for dynamic params.
+ */
+type ParamsRecord = {
+    [key: string]: string | (() => MaybePromise<string>) | undefined;
+};
+/**
+ * Base options for all stream operations.
+ */
+interface StreamOptions {
+    /**
+     * The full URL to the durable stream.
+     * E.g., "https://streams.example.com/my-account/chat/room-1"
+     */
+    url: string;
+    /**
+     * Authentication configuration.
+     * If using auth, you can provide:
+     * - A token (sent as Bearer token in Authorization header by default)
+     * - Custom headers
+     * - An async function to get headers (for refreshing tokens)
+     */
+    auth?: Auth;
+    /**
+     * Additional headers to include in requests.
+     * Values can be strings or functions (sync or async) that return strings.
+     * Function values are resolved when needed, making this useful
+     * for dynamic headers like authentication tokens.
+     */
+    headers?: HeadersRecord;
+    /**
+     * Additional query parameters to include in requests.
+     * Values can be strings or functions (sync or async) that return strings.
+     */
+    params?: ParamsRecord;
+    /**
+     * Custom fetch implementation.
+     * Defaults to globalThis.fetch.
+     */
+    fetch?: typeof globalThis.fetch;
+    /**
+     * Default AbortSignal for operations.
+     * Individual operations can override this.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Options for creating a new stream.
+ */
+interface CreateOptions extends StreamOptions {
+    /**
+     * The content type for the stream.
+     * This is set once on creation and cannot be changed.
+     */
+    contentType?: string;
+    /**
+     * Time-to-live in seconds (relative TTL).
+     */
+    ttlSeconds?: number;
+    /**
+     * Absolute expiry time (RFC3339 format).
+     */
+    expiresAt?: string;
+    /**
+     * Initial body to append on creation.
+     */
+    body?: BodyInit | Uint8Array | string;
+}
+/**
+ * Options for appending data to a stream.
+ */
+interface AppendOptions {
+    /**
+     * Writer coordination sequence (stream-seq header).
+     * Monotonic, lexicographic sequence for coordinating multiple writers.
+     * If lower than last appended seq, server returns 409 Conflict.
+     * Not related to read offsets.
+     */
+    seq?: string;
+    /**
+     * Content type for this append.
+     * Must match the stream's content type.
+     */
+    contentType?: string;
+    /**
+     * AbortSignal for this operation.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Live mode for reading from a stream.
+ */
+type LiveMode = `catchup` | `long-poll` | `sse`;
+/**
+ * Options for reading from a stream.
+ */
+interface ReadOptions {
+    /**
+     * Starting offset, passed as ?offset=...
+     * If omitted, reads from the start of the stream.
+     */
+    offset?: Offset;
+    /**
+     * Live mode behavior:
+     * - undefined (default for follow()): Start catch-up, then auto-select SSE or long-poll
+     * - "catchup": Only catch-up, stop after up-to-date
+     * - "long-poll": Skip catch-up, start long-polling immediately
+     * - "sse": Skip catch-up, start SSE immediately (throws if unsupported)
+     */
+    live?: LiveMode;
+    /**
+     * Override cursor for the request.
+     * By default, the client echoes the last stream-cursor value.
+     */
+    cursor?: string;
+    /**
+     * AbortSignal for this operation.
+     */
+    signal?: AbortSignal;
+}
+/**
+ * Result from a HEAD request on a stream.
+ */
+interface HeadResult {
+    /**
+     * Whether the stream exists.
+     */
+    exists: true;
+    /**
+     * The stream's content type.
+     */
+    contentType?: string;
+    /**
+     * The tail offset (next offset after current end of stream).
+     * Provided by server as stream-offset header on HEAD.
+     */
+    offset?: Offset;
+    /**
+     * ETag for the stream (format: {internal_stream_id}:{end_offset}).
+     */
+    etag?: string;
+    /**
+     * Cache-Control header value.
+     */
+    cacheControl?: string;
+}
+/**
+ * Result from a read operation.
+ */
+interface ReadResult {
+    /**
+     * The data read from the stream.
+     */
+    data: Uint8Array;
+    /**
+     * Next offset to read from.
+     * This is the HTTP stream-offset header value.
+     */
+    offset: Offset;
+    /**
+     * Cursor for CDN collapsing (stream-cursor header).
+     */
+    cursor?: string;
+    /**
+     * True if stream-up-to-date header was present.
+     * Indicates the response ends at the current end of the stream.
+     */
+    upToDate: boolean;
+    /**
+     * ETag for caching.
+     */
+    etag?: string;
+    /**
+     * Content type of the data.
+     */
+    contentType?: string;
+}
+/**
+ * A chunk returned from follow() or toReadableStream().
+ * Same structure as ReadResult.
+ */
+interface StreamChunk extends ReadResult {
+}
+/**
+ * Error codes for DurableStreamError.
+ */
+type DurableStreamErrorCode = `NOT_FOUND` | `CONFLICT_SEQ` | `CONFLICT_EXISTS` | `BAD_REQUEST` | `BUSY` | `SSE_NOT_SUPPORTED` | `UNAUTHORIZED` | `FORBIDDEN` | `RATE_LIMITED` | `UNKNOWN`;
+/**
+ * Options returned from onError handler to retry with modified params/headers.
+ * Following the Electric client pattern.
+ */
+type RetryOpts = {
+    params?: ParamsRecord;
+    headers?: HeadersRecord;
+};
+/**
+ * Error handler callback type.
+ *
+ * Called when a recoverable error occurs during streaming.
+ *
+ * **Return value behavior** (following Electric client pattern):
+ * - Return `{}` to retry with the same params/headers
+ * - Return `{ params }` to retry with merged params (existing params are preserved)
+ * - Return `{ headers }` to retry with merged headers (existing headers are preserved)
+ * - Return `void`/`undefined` to stop the stream and propagate the error
+ *
+ * Note: Automatic retries with exponential backoff are already applied
+ * for 5xx server errors, network errors, and 429 rate limits before
+ * this handler is called.
+ *
+ * @example
+ * ```typescript
+ * // Retry on any error
+ * onError: (error) => ({})
+ *
+ * // Refresh auth token on 401
+ * onError: async (error) => {
+ *   if (error instanceof FetchError && error.status === 401) {
+ *     const newToken = await refreshAuthToken()
+ *     return { headers: { Authorization: `Bearer ${newToken}` } }
+ *   }
+ *   // Don't retry other errors
+ * }
+ * ```
+ */
+type StreamErrorHandler = (error: Error) => void | RetryOpts | Promise<void | RetryOpts>;
+
+/**
+ * Fetch utilities with retry and backoff support.
+ * Based on @electric-sql/client patterns.
+ */
+/**
+ * Options for configuring exponential backoff retry behavior.
+ */
+interface BackoffOptions {
+    /**
+     * Initial delay before retrying in milliseconds.
+     */
+    initialDelay: number;
+    /**
+     * Maximum retry delay in milliseconds.
+     * After reaching this, delay stays constant.
+     */
+    maxDelay: number;
+    /**
+     * Multiplier for exponential backoff.
+     */
+    multiplier: number;
+    /**
+     * Callback invoked on each failed attempt.
+     */
+    onFailedAttempt?: () => void;
+    /**
+     * Enable debug logging.
+     */
+    debug?: boolean;
+    /**
+     * Maximum number of retry attempts before giving up.
+     * Set to Infinity for indefinite retries (useful for offline scenarios).
+     */
+    maxRetries?: number;
+}
+/**
+ * Default backoff options.
+ */
+declare const BackoffDefaults: BackoffOptions;
+/**
+ * Creates a fetch client that retries failed requests with exponential backoff.
+ *
+ * @param fetchClient - The base fetch client to wrap
+ * @param backoffOptions - Options for retry behavior
+ * @returns A fetch function with automatic retry
+ */
+declare function createFetchWithBackoff(fetchClient: typeof fetch, backoffOptions?: BackoffOptions): typeof fetch;
+/**
+ * Creates a fetch client that ensures the response body is fully consumed.
+ * This prevents issues with connection pooling when bodies aren't read.
+ *
+ * Uses arrayBuffer() instead of text() to preserve binary data integrity.
+ *
+ * @param fetchClient - The base fetch client to wrap
+ * @returns A fetch function that consumes response bodies
+ */
+declare function createFetchWithConsumedBody(fetchClient: typeof fetch): typeof fetch;
+
+/**
+ * DurableStream - A handle to a remote durable stream.
+ *
+ * Following the Electric Durable Stream Protocol specification.
+ */
+
+/**
+ * Options for DurableStream constructor.
+ */
+interface DurableStreamOptions extends StreamOptions {
+    /**
+     * Backoff options for retry behavior.
+     */
+    backoffOptions?: BackoffOptions;
+    /**
+     * Error handler for recoverable errors.
+     *
+     * **Automatic retries**: The client automatically retries 5xx server errors, network
+     * errors, and 429 rate limits with exponential backoff. The `onError` callback is
+     * only invoked after these automatic retries are exhausted, or for non-retryable errors.
+     *
+     * **Return value behavior** (following Electric client pattern):
+     * - Return `{}` to retry with the same params/headers
+     * - Return `{ params }` to retry with merged params
+     * - Return `{ headers }` to retry with merged headers
+     * - Return `void`/`undefined` to stop the stream and propagate the error
+     *
+     * @example
+     * ```typescript
+     * // Refresh auth token on 401
+     * onError: async (error) => {
+     *   if (error instanceof FetchError && error.status === 401) {
+     *     const newToken = await refreshAuthToken()
+     *     return { headers: { Authorization: `Bearer ${newToken}` } }
+     *   }
+     * }
+     * ```
+     */
+    onError?: StreamErrorHandler;
+}
+/**
+ * A handle to a remote durable stream.
+ *
+ * This is a lightweight, reusable handle - not a persistent connection.
+ * It does not automatically start reading or listening.
+ * Create sessions as needed via read(), follow(), or toReadableStream().
+ *
+ * @example
+ * ```typescript
+ * // Create a handle without any network IO
+ * const stream = new DurableStream({
+ *   url: "https://streams.example.com/my-stream",
+ *   auth: { token: "my-token" }
+ * });
+ *
+ * // One-shot read
+ * const result = await stream.read({ offset: savedOffset });
+ *
+ * // Follow for live updates
+ * for await (const chunk of stream.follow()) {
+ *   console.log(new TextDecoder().decode(chunk.data));
+ * }
+ * ```
+ */
+declare class DurableStream {
+    #private;
+    /**
+     * The URL of the durable stream.
+     */
+    readonly url: string;
+    /**
+     * The content type of the stream (populated after connect/head/read).
+     */
+    contentType?: string;
+    /**
+     * Create a cold handle to a stream.
+     * No network IO is performed by the constructor.
+     */
+    constructor(opts: DurableStreamOptions);
+    /**
+     * Create a new stream (create-only PUT) and return a handle.
+     * Fails with DurableStreamError(code="CONFLICT_EXISTS") if it already exists.
+     */
+    static create(opts: CreateOptions): Promise<DurableStream>;
+    /**
+     * Validate that a stream exists and fetch metadata via HEAD.
+     * Returns a handle with contentType populated (if sent by server).
+     */
+    static connect(opts: StreamOptions): Promise<DurableStream>;
+    /**
+     * HEAD metadata for a stream without creating a handle.
+     */
+    static head(opts: StreamOptions): Promise<HeadResult>;
+    /**
+     * Delete a stream without creating a handle.
+     */
+    static delete(opts: StreamOptions): Promise<void>;
+    /**
+     * HEAD metadata for this stream.
+     */
+    head(opts?: {
+        signal?: AbortSignal;
+    }): Promise<HeadResult>;
+    /**
+     * Create this stream (create-only PUT) using the URL/auth from the handle.
+     */
+    create(opts?: Omit<CreateOptions, keyof StreamOptions>): Promise<this>;
+    /**
+     * Delete this stream.
+     */
+    delete(opts?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /**
+     * 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).
+     */
+    append(body: BodyInit | Uint8Array | string, opts?: AppendOptions): Promise<void>;
+    /**
+     * 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.
+     */
+    appendStream(source: ReadableStream<Uint8Array | string> | AsyncIterable<Uint8Array | string>, opts?: AppendOptions): Promise<void>;
+    /**
+     * 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.
+     */
+    read(opts?: ReadOptions): Promise<ReadResult>;
+    /**
+     * 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?: ReadOptions): AsyncIterable<StreamChunk>;
+    /**
+     * 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?: ReadOptions & {
+        signal?: AbortSignal;
+    }): ReadableStream<StreamChunk>;
+    /**
+     * Wrap follow() in a Web ReadableStream<Uint8Array> for piping raw bytes.
+     *
+     * This is the native format for many web stream APIs.
+     */
+    toByteStream(opts?: ReadOptions & {
+        signal?: AbortSignal;
+    }): ReadableStream<Uint8Array>;
+    /**
+     * Convenience: interpret data as JSON messages.
+     * Parses each chunk's data as JSON and yields the parsed values.
+     */
+    json<T = unknown>(opts?: ReadOptions): AsyncIterable<T>;
+    /**
+     * Convenience: interpret data as text (UTF-8).
+     */
+    text(opts?: ReadOptions & {
+        decoder?: TextDecoder;
+    }): AsyncIterable<string>;
+}
+
+/**
+ * Error thrown for transport/network errors.
+ * Following the @electric-sql/client FetchError pattern.
+ */
+declare class FetchError extends Error {
+    url: string;
+    status: number;
+    text?: string;
+    json?: object;
+    headers: Record<string, string>;
+    constructor(status: number, text: string | undefined, json: object | undefined, headers: Record<string, string>, url: string, message?: string);
+    static fromResponse(response: Response, url: string): Promise<FetchError>;
+}
+/**
+ * Error thrown when a fetch operation is aborted during backoff.
+ */
+declare class FetchBackoffAbortError extends Error {
+    constructor();
+}
+/**
+ * Protocol-level error for Durable Streams operations.
+ * Provides structured error handling with error codes.
+ */
+declare class DurableStreamError extends Error {
+    /**
+     * HTTP status code, if applicable.
+     */
+    status?: number;
+    /**
+     * Structured error code for programmatic handling.
+     */
+    code: DurableStreamErrorCode;
+    /**
+     * Additional error details (e.g., raw response body).
+     */
+    details?: unknown;
+    constructor(message: string, code: DurableStreamErrorCode, status?: number, details?: unknown);
+    /**
+     * Create a DurableStreamError from an HTTP response.
+     */
+    static fromResponse(response: Response, url: string): Promise<DurableStreamError>;
+    /**
+     * Create a DurableStreamError from a FetchError.
+     */
+    static fromFetchError(error: FetchError): DurableStreamError;
+}
+/**
+ * Error thrown when stream URL is missing.
+ */
+declare class MissingStreamUrlError extends Error {
+    constructor();
+}
+/**
+ * Error thrown when signal option is invalid.
+ */
+declare class InvalidSignalError extends Error {
+    constructor();
+}
+
+/**
+ * Durable Streams Protocol Constants
+ *
+ * Header and query parameter names following the Electric Durable Stream Protocol.
+ */
+/**
+ * Response header containing the next offset to read from.
+ * Format: "<read-seq>_<byte-offset>"
+ */
+declare const STREAM_OFFSET_HEADER = "stream-offset";
+/**
+ * Response header for cursor (used for CDN collapsing).
+ * Echo this value in subsequent long-poll requests.
+ */
+declare const STREAM_CURSOR_HEADER = "stream-cursor";
+/**
+ * Presence header indicating response ends at current end of stream.
+ * When present (any value), indicates up-to-date.
+ */
+declare const STREAM_UP_TO_DATE_HEADER = "stream-up-to-date";
+/**
+ * Request header for writer coordination sequence.
+ * Monotonic, lexicographic. If lower than last appended seq -> 409 Conflict.
+ */
+declare const STREAM_SEQ_HEADER = "stream-seq";
+/**
+ * Request header for stream TTL in seconds (on create).
+ */
+declare const STREAM_TTL_HEADER = "stream-ttl";
+/**
+ * Request header for absolute stream expiry time (RFC3339, on create).
+ */
+declare const STREAM_EXPIRES_AT_HEADER = "stream-expires-at";
+/**
+ * Query parameter for starting offset.
+ */
+declare const OFFSET_QUERY_PARAM = "offset";
+/**
+ * Query parameter for live mode.
+ * Values: "long-poll", "sse"
+ */
+declare const LIVE_QUERY_PARAM = "live";
+/**
+ * Query parameter for echoing cursor (CDN collapsing).
+ */
+declare const CURSOR_QUERY_PARAM = "cursor";
+/**
+ * Content types that support SSE mode.
+ * SSE is only valid for text/* or application/json streams.
+ */
+declare const SSE_COMPATIBLE_CONTENT_TYPES: string[];
+/**
+ * Protocol query parameters that should not be set by users.
+ */
+declare const DURABLE_STREAM_PROTOCOL_QUERY_PARAMS: Array<string>;
+
+export { type AppendOptions, type Auth, BackoffDefaults, type BackoffOptions, CURSOR_QUERY_PARAM, type CreateOptions, DURABLE_STREAM_PROTOCOL_QUERY_PARAMS, DurableStream, DurableStreamError, type DurableStreamErrorCode, type DurableStreamOptions, FetchBackoffAbortError, FetchError, type HeadResult, type HeadersRecord, InvalidSignalError, LIVE_QUERY_PARAM, type LiveMode, type MaybePromise, MissingStreamUrlError, OFFSET_QUERY_PARAM, type Offset, type ParamsRecord, type ReadOptions, type ReadResult, type RetryOpts, 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, type StreamChunk, type StreamErrorHandler, type StreamOptions, createFetchWithBackoff, createFetchWithConsumedBody };