pg-sse-client 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and the project follows
+[Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-12
+
+### Added
+
+- `connect(url, options)`: a client for pg-sse streams on `fetch`. It sends your headers, resumes from the last `id:`
+  with `Last-Event-ID`, waits the `retry:` and `Retry-After` the server sends, reports the goodbye reason, and backs
+  off with jitter. `onError` decides whether to retry, stop or rest (`wakeOnResume` ends a rest when the browser is
+  back), and `retryNow()` ends a wait. `cursorIn: 'url'` carries the cursor in the URL, which needs no CORS
+  permission for a header.
+- `maxEventChars`: an opt-in limit on how much of one event is held. More fails with `SseEventTooLarge`.
+- `createSseParser` and `readSse`, also under `pg-sse-client/parser`: the text/event-stream parser, for a stream you
+  open yourself.
+
+[Unreleased]: https://github.com/sansanth/pg-sse-client/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/sansanth/pg-sse-client/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sandhu Santhakumar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,121 @@
-# Temporary Holding Version
+# pg-sse-client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/sansanth/pg-sse-client/actions/workflows/ci.yml/badge.svg)](https://github.com/sansanth/pg-sse-client/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/pg-sse-client)](https://www.npmjs.com/package/pg-sse-client)
+
+The browser and Node client for [pg-sse](https://github.com/sansanth/pg-sse) streams, for when `EventSource` is not enough. pg-sse is a Python library (`pip install pg-sse`) that streams Postgres changes from a FastAPI or other Python server; this package is its JavaScript side, not the unrelated `pg-sse` package on npm.
+
+It is `EventSource` on top of `fetch`: it can send an `Authorization` header, and it keeps the parts of the pg-sse contract that `EventSource` handles for you (resume from the last id, the server's reconnect delay, the goodbye frame).
+
+No dependencies, ESM only, about 3.7 kB minified and gzipped (1.2 kB for `pg-sse-client/parser`).
+
+## Do you need it?
+
+If your stream authenticates with a cookie sent to the same origin, or with `withCredentials`, use `EventSource`. It reconnects by itself and sends `Last-Event-ID`, and pg-sse is written for it. Use this package when you need what `EventSource` cannot do:
+
+- send a header (`Authorization: Bearer ...`), or read a token that changes between attempts
+- see why a stream ended and why a request was refused (a 401, a 503 with `Retry-After`)
+- stop retrying on an error that repeating will not fix
+- decide what to do after repeated failures, such as falling back to polling
+
+```sh
+npm install pg-sse-client
+```
+
+## Use it
+
+```ts
+import { connect } from 'pg-sse-client';
+
+const stream = connect('https://api.example/rooms/lobby/stream', {
+  headers: async () => ({ Authorization: `Bearer ${await getToken()}` }), // read before every attempt
+  onEvent: (event) => render(JSON.parse(event.data)),                     // { event, data, id }
+  onEnd: (reason) => console.debug('the server said goodbye:', reason),
+  onClose: (error) => error && showSignIn(),                              // over for good
+});
+
+stream.close();
+```
+
+It starts at once, like `new EventSource(url)`. On the server, set `end_event="end"` on the hub if you want `onEnd` to hear why a stream ended; without it the client still reconnects correctly, it just does not know the reason.
+
+## What it does
+
+| Situation | Behaviour |
+|---|---|
+| Request | `GET` with `Accept: text/event-stream`, your headers, and `Last-Event-ID` once it has a cursor, sent as UTF-8 bytes as `EventSource` does. |
+| `id:` | Moves the cursor when the frame ends. A frame with only an `id:` moves it and delivers nothing (pg-sse sends one first when you pass a cursor). |
+| `retry:` | After a stream that stayed open 5 s or more, the next reconnect waits exactly that long. After a shorter one it is the backoff below, never less than that. No later wait is shorter than the last `retry:` the server sent. |
+| `end` event (`max_age`, `shutdown`, `behind`, `revoked`, `recheck`) | `onEnd(reason)`, then reconnect after the `retry:` that came with it (after a stream open 5 s or more; a shorter one is backed off from, below). The event is not passed to `onEvent`. A reason the client does not know is passed through unchanged. |
+| Stream closes with no goodbye | Reconnect after 0.5 to 2 s, random (never less than the last `retry:`). |
+| Failure (network error, timeout, non-2xx, not an event stream) | `onError`, then wait. The wait doubles from 1 s to 30 s with jitter, never less than a `Retry-After` (plus 0 to 1.5 s of spread) or the last `retry:` the server sent. Those two are capped at `backoff.serverMaxMs`, an hour. |
+| A stream that closed within 5 s of opening | Counts as a failure even if it closed cleanly, so a server that keeps dropping clients is backed off from. `onError` hears a `StreamEndedEarly`. |
+| A stream that stayed open 5 s or more | Healthy, however it ended: the failure count starts again. A clean end reconnects as above; an error is failure 1, backed off from as such. A stream that fails sooner adds to the count. |
+| 4xx other than 408 and 429, a 3xx you chose not to follow, a 2xx that is not an event stream (a 204, say), or an event past `maxEventChars` | Stops, and `onClose(error)` says why. A repeat would only get the same answer, and `EventSource` stops too. A 401 is one of these: when your `headers` function can get a fresh token, return `'retry'` from `onError` for it. |
+| Silence | No bytes (pings count) for 45 s aborts and retries. No response headers in 15 s does too, and a `headers` function that takes that long counts. |
+| Browser | A wait of the client's own choosing ends early when the browser comes back `online` or the tab becomes visible, once it has run a second and as long as the last `retry:`. A wait the server asked for, or `onError` chose with `{ retryAfterMs }`, does not (`retryNow()` still ends it). |
+
+### Options
+
+| Option | Default | |
+|---|---|---|
+| `onEvent(event)` | required | Every event but the goodbye. A throw does not stop the stream: it goes to `onCallbackError`. |
+| `onCallbackError(error)` | | Gets what any callback threw, or the rejection of one that is `async`. Without it a page or a worker has the error rethrown on its own, to `window.onerror`, and anything else logs it with `console.error`. If it throws, that goes the default way. |
+| `onOpen()` | | The server accepted the request. It has sent nothing yet. |
+| `onDisconnect()` | | A stream that had opened has ended, for any reason, before `onError` and the wait. Where a "live" flag goes false. Not called by `close()`. |
+| `onEnd(reason)` | | The goodbye event's `reason`, or `unknown`. Data that is not JSON is the reason as it came. |
+| `onError(error, { failures })` | | Every failed attempt. Return `'retry'`, `'stop'` or `{ retryAfterMs }` (which also resets `failures`), or nothing for the default. `{ retryAfterMs, wakeOnResume: true }` also ends the rest early when the browser comes back `online` or the tab becomes visible, after the first second. May be `async`. |
+| `onClose(error?)` | | The connection is over: `close()` was called (no argument), or an error stopped it. Once. |
+| `headers` | | `HeadersInit`, or a function returning one (or a promise of one), called before every attempt. |
+| `init` | | More `fetch` options, such as `credentials: 'include'`. `method`, `headers`, `body` and `signal` are the client's. `EventSource` sends `cache: 'no-store'`; pg-sse's `Cache-Control: no-cache` does the same job. |
+| `fetch` | global `fetch` | For tests, or a wrapped fetch. Looked up on every attempt, and called with no receiver, as `fetch` must be: bind a method. |
+| `cursorIn` | `'header'` | `'url'` sends the cursor to the URL function and no `Last-Event-ID` header. |
+| `lastEventId` | | Resume from here on the first attempt. |
+| `endEvent` | `end` | The hub's `end_event`. An event of your own with this name is taken for the goodbye, so name yours otherwise or set this. |
+| `maxEventChars` | no limit | The most characters of one event to hold: its lines, field names included, and the line still arriving. More fails the attempt with `SseEventTooLarge`. `EventSource` has no limit and neither does this by default; set one when you do not trust the server to stay small. |
+| `connectTimeoutMs`, `idleTimeoutMs` | 15000, 45000 | `0` turns a timeout off, and so does a value too long for a timer, such as `Infinity`. |
+| `backoff` | see `Backoff` in `src/connect.ts` | `baseMs`, `maxMs`, `shortMs`, `reconnectFloorMs`, `reconnectSpreadMs`, `serverMaxMs`. An entry that is not a finite number of at least 0 keeps its default. |
+
+The first argument is a URL string, a `URL`, or a function returning one, called before every attempt. A function is given the cursor (`''` at first). With `cursorIn: 'url'` it is the only place the cursor goes, and no `Last-Event-ID` header is sent: `` url: (id) => `${base}?cursor=${encodeURIComponent(id)}` ``, encoded. `cursorIn: 'url'` without a URL function, or any `cursorIn` but `'header'` and `'url'`, throws a `TypeError` from `connect`. A string or `URL` that can never be fetched, and `headers` given as a value that cannot be sent, throw a `TypeError` from `connect`, as `new EventSource` throws.
+
+`connect` returns `{ close(), retryNow(), lastEventId }`. `retryNow()` cuts a wait short, for example when your own app learns the network is back.
+
+Errors are `SseEventTooLarge` (`limit`) for an event past `maxEventChars`, `StreamRefused` (`status`, `retryAfterMs`) for a non-2xx answer or a body that is not an event stream, `StreamTimeout` (`phase`) for silence, and `StreamEndedEarly` (`lastedMs`, `reason`) for a stream that closed within `backoff.shortMs` of opening. Anything else is what `fetch` threw.
+
+### Falling back to polling
+
+`failures` in `onError` is the number of attempts in a row that failed. Use it to hand over to polling and rest:
+
+```ts
+onError: (error, { failures }) => {
+  if (failures >= 3) {
+    startPolling();
+    return { retryAfterMs: 3 * 60_000, wakeOnResume: true }; // try the stream again in three minutes, or when the tab is back
+  }
+},
+onOpen: stopPolling,
+```
+
+### Cross-origin requests
+
+`Last-Event-ID` is not a header a cross-origin `fetch` may send without permission (`EventSource` is exempt). If you cannot change the server's CORS, carry the cursor in the URL with `cursorIn: 'url'` (above). Otherwise the server must answer the preflight with `Access-Control-Allow-Headers: Last-Event-ID` (plus `Authorization` if you send it), or the first reconnect fails and the stream never resumes. To read a `Retry-After` from a refusal, the response needs `Access-Control-Expose-Headers: Retry-After`; without it `retryAfterMs` is null.
+
+### Only the parser
+
+```ts
+import { createSseParser, readSse } from 'pg-sse-client/parser';
+
+for await (const event of readSse(response.body!, onActivity)) { /* { event, data, id } */ }
+```
+
+For a stream you open yourself, such as a `POST` that answers with events. The parser follows the WHATWG rules; `parser.lastEventId` and `parser.retry` hold the connection-level state. The parser reads a whole chunk before the first of its events reaches you, so to resume use the `id` of the last event you handled, not `parser.lastEventId`.
+
+## What is not here
+
+- **The meaning of your events.** The client does not know `change` from `ready`; that is your server's protocol.
+- **A message queue.** It delivers what the stream sends; a gap is closed by the server re-reading from the cursor it was sent.
+- **React or any framework.** Wrap `connect` in your own hook; `close()` is the cleanup.
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). The wire contract this client follows is in the [pg-sse README](https://github.com/sansanth/pg-sse#frames-you-will-see).

package/dist/connect.d.ts

@@ -0,0 +1,126 @@
+import { type SseEvent } from './event.js';
+/** The server answered, but not with a stream: a non-2xx status, or a 2xx that is not `text/event-stream`. */
+export declare class StreamRefused extends Error {
+    readonly status: number;
+    /** The server's `Retry-After`, in milliseconds, when it sent one it could be read. */
+    readonly retryAfterMs: number | null;
+    constructor(status: number, 
+    /** The server's `Retry-After`, in milliseconds, when it sent one it could be read. */
+    retryAfterMs?: number | null, message?: string);
+}
+/** The server went quiet: no response headers within `connectTimeoutMs`, or no bytes at all within `idleTimeoutMs`. */
+export declare class StreamTimeout extends Error {
+    readonly phase: 'connect' | 'idle';
+    constructor(phase: 'connect' | 'idle');
+}
+/** A stream opened and then closed within `backoff.shortMs`, with or without a goodbye: a server that keeps dropping clients. */
+export declare class StreamEndedEarly extends Error {
+    readonly lastedMs: number;
+    /** The goodbye reason, or null when the server just closed. */
+    readonly reason: string | null;
+    constructor(lastedMs: number, 
+    /** The goodbye reason, or null when the server just closed. */
+    reason: string | null);
+}
+/**
+ * What `onError` decides. `retry` waits as long as the backoff and the server's hints say, `stop` ends the connection
+ * for good, and `{ retryAfterMs }` waits exactly that long, for example to rest while the caller polls instead. With
+ * `wakeOnResume` the browser coming back online, or the tab becoming visible, ends that rest early, once it has run a second. A `retryAfterMs`
+ * that is not a finite number of at least 0 is ignored, as if `onError` had returned nothing.
+ */
+export type ErrorAction = 'retry' | 'stop' | {
+    retryAfterMs: number;
+    wakeOnResume?: boolean;
+};
+export interface ErrorInfo {
+    /**
+     * Attempts in a row that failed, or that ended within `backoff.shortMs` of opening, this one included. A stream that was
+     * open for `backoff.shortMs` before it failed starts the count again, so it is 1.
+     */
+    failures: number;
+}
+export interface Backoff {
+    /** The first retry waits about this long, then doubles. */
+    baseMs: number;
+    maxMs: number;
+    /**
+     * A stream that closed within this long of opening counts as a failure, even if it closed cleanly: `onError` hears a
+     * `StreamEndedEarly`. One that lasted this long was healthy, however it ended: the failure count starts again, at 0 for a
+     * clean end and at 1 for an error.
+     */
+    shortMs: number;
+    /** After a stream that ended cleanly and long enough, and with no `retry:` from the server, wait this long plus up to `reconnectSpreadMs`. */
+    reconnectFloorMs: number;
+    reconnectSpreadMs: number;
+    /** The longest the client waits on the server's word, a `Retry-After` or a `retry:`. A mistake there must not stop a stream for weeks. */
+    serverMaxMs: number;
+}
+export interface ConnectOptions {
+    /**
+     * Called for every event except the `end` event. A callback that throws does not stop the stream: see `onCallbackError`
+     * for where the error goes.
+     */
+    onEvent(event: SseEvent): void;
+    /** The server accepted the request and a stream is open. It has sent nothing yet. */
+    onOpen?(): void;
+    /**
+     * A stream that had opened has ended, for any reason: a goodbye, the server closing, or an error. It is called before
+     * `onError` and before the wait, so it is the place to mark the stream no longer live. It follows `onEnd`. Not called by
+     * `close()`.
+     */
+    onDisconnect?(): void;
+    /** The server said goodbye (`max_age`, `shutdown`, `behind`, `revoked`, `recheck`) and the client is about to reconnect. */
+    onEnd?(reason: string): void;
+    /**
+     * Every failed attempt, whether or not it will be retried. Return what to do; return nothing for the default: stop
+     * on a 4xx other than 408 and 429, a 3xx that was not followed, a 2xx that is not an event stream, and an event past
+     * `maxEventChars` (answers that repeating will not change), retry anything else. Returning `{ retryAfterMs }` also resets `failures`, so the next attempts are counted afresh. It
+     * may be `async`: the client waits for the answer.
+     */
+    onError?(error: unknown, info: ErrorInfo): ErrorAction | void | Promise<ErrorAction | void>;
+    /** The connection is over for good: `close()` was called, or an error ended it (passed in). Called once. */
+    onClose?(error?: unknown): void;
+    /**
+     * Gets the error a callback threw, or the rejection of one that is `async` (this one's and every other's), instead of
+     * the default: in a page or a worker the error is rethrown on its own, so `window.onerror` sees it, and elsewhere it is
+     * logged with `console.error`. If this throws, that error goes the default way.
+     */
+    onCallbackError?(error: unknown): void;
+    /** Request headers. A function is called before every attempt, so a token can be refreshed. `Accept` and `Last-Event-ID` are the client's: the cursor goes in the header, or in the URL for a URL function that takes it. */
+    headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+    /** More `fetch` options, such as `credentials` or `mode`. `method`, `headers` and `signal` are the client's. */
+    init?: Omit<RequestInit, 'method' | 'headers' | 'signal' | 'body'>;
+    /** A `fetch` to use instead of the global one, looked up on every attempt. */
+    fetch?: typeof fetch;
+    /**
+     * Where the cursor goes: the `Last-Event-ID` header (default), or the URL. `'url'` needs a URL function, which is given
+     * the cursor (`''` at first) whatever this is, and sends no header: a cross-origin server then needs no CORS permission
+     * for one.
+     */
+    cursorIn?: 'header' | 'url';
+    /** Where to resume from on the first attempt, sent as `Last-Event-ID` or given to a URL function. An id with a line break or NUL cannot be one and is ignored. */
+    lastEventId?: string;
+    /** The name of the goodbye event, as set with `end_event` on the hub. Default `end`. */
+    endEvent?: string;
+    /** The most characters of one event to hold, a line still arriving included. More fails the attempt with `SseEventTooLarge`. No limit by default, or when 0. */
+    maxEventChars?: number;
+    /** How long to wait for the response headers, the `headers` function included. Default 15000. */
+    connectTimeoutMs?: number;
+    /** Default 45000, which is more than the 25 s between pg-sse's longest pings, with room for a slow network. 0, or a value too long for a timer, turns it off. */
+    idleTimeoutMs?: number;
+    backoff?: Partial<Backoff>;
+}
+export interface Connection {
+    /** Ends the connection for good. */
+    close(): void;
+    /** Cuts a wait before the next attempt short, or the wait that is about to begin. Does nothing while a stream is open. */
+    retryNow(): void;
+    /** The cursor the next attempt will send, as `Last-Event-ID` or to a URL function. */
+    readonly lastEventId: string;
+}
+/**
+ * Opens a stream the way `EventSource` would, with `fetch` underneath so it can send headers. It reconnects on its own,
+ * sends `Last-Event-ID` from the last `id:` it saw, waits the `retry:` the server asked for, and backs off with jitter
+ * when attempts fail. With `cursorIn: 'url'` the cursor goes to the URL function instead, and no header is sent. It starts at once; call `close()` to end it.
+ */
+export declare function connect(url: string | URL | ((lastEventId: string) => string | URL), options: ConnectOptions): Connection;

package/dist/connect.js

@@ -0,0 +1,477 @@
+import { SseEventTooLarge } from './event.js';
+import { createSseParser } from './parser.js';
+import { readChunks } from './read.js';
+/** The server answered, but not with a stream: a non-2xx status, or a 2xx that is not `text/event-stream`. */
+export class StreamRefused extends Error {
+    status;
+    retryAfterMs;
+    constructor(status, 
+    /** The server's `Retry-After`, in milliseconds, when it sent one it could be read. */
+    retryAfterMs = null, message = `Stream refused: HTTP ${status}`) {
+        super(message);
+        this.status = status;
+        this.retryAfterMs = retryAfterMs;
+        this.name = 'StreamRefused';
+    }
+}
+/** The server went quiet: no response headers within `connectTimeoutMs`, or no bytes at all within `idleTimeoutMs`. */
+export class StreamTimeout extends Error {
+    phase;
+    constructor(phase) {
+        super(`Stream timed out waiting for ${phase === 'connect' ? 'a response' : 'data'}`);
+        this.phase = phase;
+        this.name = 'StreamTimeout';
+    }
+}
+/** A stream opened and then closed within `backoff.shortMs`, with or without a goodbye: a server that keeps dropping clients. */
+export class StreamEndedEarly extends Error {
+    lastedMs;
+    reason;
+    constructor(lastedMs, 
+    /** The goodbye reason, or null when the server just closed. */
+    reason) {
+        super(`The stream closed ${Math.round(lastedMs)} ms after it opened`);
+        this.lastedMs = lastedMs;
+        this.reason = reason;
+        this.name = 'StreamEndedEarly';
+    }
+}
+// `setTimeout` runs a longer delay than this (24.8 days) at once.
+const MAX_TIMER_MS = 2 ** 31 - 1;
+// A timeout of any length, made of several when it is longer than a timer can be. Returns what cancels it.
+function longTimeout(ms, run) {
+    let timer;
+    const sleep = (left) => {
+        timer = setTimeout(left > MAX_TIMER_MS ? () => sleep(left - MAX_TIMER_MS) : run, Math.min(left, MAX_TIMER_MS));
+    };
+    sleep(ms);
+    return () => clearTimeout(timer);
+}
+// Monotonic: a step of the wall clock must not read as a stream gone quiet or a wait that is over.
+const now = () => performance.now();
+// How long a wait must have run before `online` or `visibilitychange` may end it.
+const EARLY_RETRY_MS = 1000;
+const DEFAULT_BACKOFF = {
+    baseMs: 1000,
+    maxMs: 30_000,
+    shortMs: 5000,
+    reconnectFloorMs: 500,
+    reconnectSpreadMs: 1500,
+    serverMaxMs: 3_600_000,
+};
+function retryAfterOf(header) {
+    if (header === null)
+        return null;
+    // Clamped, as a very long string of digits is Infinity.
+    if (/^\d+$/.test(header.trim()))
+        return Math.min(Number(header) * 1000, Number.MAX_SAFE_INTEGER);
+    // An HTTP date starts with a day name and has a time in it. `Date.parse` alone also reads '1.5' or 'May 5' as a date.
+    if (!/^[a-z]{3,9}\b.*\d{2}:\d{2}:\d{2}/i.test(header.trim()))
+        return null;
+    // The asctime form has no zone, and `Date.parse` would read it as local time.
+    const date = Date.parse(/\b(GMT|UTC)\b|\s[+-]\d{4}\s*$/i.test(header) ? header : `${header} GMT`);
+    return Number.isNaN(date) ? null : Math.max(0, date - Date.now());
+}
+// A finite number of at least 0. NaN, a negative and Infinity would each run a timer at once.
+function isDelay(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+// What `onError` returned, if it is something to act on. Anything else leaves it to the default.
+function actionOf(returned) {
+    if (returned === 'retry' || returned === 'stop')
+        return returned;
+    if (typeof returned !== 'object' || returned === null)
+        return null;
+    const ms = returned.retryAfterMs;
+    if (!isDelay(ms))
+        return null;
+    return { retryAfterMs: ms, wakeOnResume: returned.wakeOnResume === true };
+}
+// Not a usable number: the default. Too long for a timer, Infinity say: none, as 0.
+function timeoutOf(value, fallback) {
+    if (value === Number.POSITIVE_INFINITY)
+        return 0;
+    if (!isDelay(value))
+        return fallback;
+    return value > MAX_TIMER_MS ? 0 : value;
+}
+// Stop on what repeating will not change: as `EventSource` does, a 4xx (a timeout and a rate limit aside) and a 2xx that is
+// no stream, and an event that will be as large when sent again.
+function defaultAction(error) {
+    if (error instanceof SseEventTooLarge)
+        return 'stop';
+    if (!(error instanceof StreamRefused))
+        return 'retry';
+    if (error.status < 400)
+        return 'stop';
+    return error.status < 500 && error.status !== 408 && error.status !== 429 ? 'stop' : 'retry';
+}
+// The id goes as its UTF-8 bytes, as `EventSource` sends it: `Headers` throws on a character outside Latin-1.
+function headerValue(id) {
+    return Array.from(new TextEncoder().encode(id), (byte) => String.fromCharCode(byte)).join('');
+}
+// Settles with `work`, or rejects when the signal aborts, so work that never settles cannot hold an attempt. `late` gets
+// what `work` settles with after that.
+function untilAborted(signal, work, late) {
+    return new Promise((resolve, reject) => {
+        const abort = () => reject(signal.reason);
+        Promise.resolve(work)
+            .then((value) => {
+            if (signal.aborted)
+                late?.(value);
+            resolve(value);
+        }, reject)
+            .finally(() => signal.removeEventListener('abort', abort));
+        // `work` may have aborted the signal itself.
+        if (signal.aborted)
+            abort();
+        else
+            signal.addEventListener('abort', abort, { once: true });
+    });
+}
+// The media type is case-insensitive and may have parameters.
+function isEventStream(response) {
+    return (response.headers.get('content-type') ?? '').split(';')[0].trim().toLowerCase() === 'text/event-stream';
+}
+// Frees an answer the client will not read. Not awaited: a cancel that hangs must not hold up the refusal.
+async function discard(response) {
+    try {
+        await response.body?.cancel();
+    }
+    catch {
+        /* nothing to free */
+    }
+}
+function endReason(data) {
+    try {
+        const parsed = JSON.parse(data);
+        const reason = typeof parsed === 'string' ? parsed : parsed?.reason;
+        return typeof reason === 'string' ? reason : 'unknown';
+    }
+    catch {
+        return data || 'unknown';
+    }
+}
+function rethrowLater(error) {
+    queueMicrotask(() => {
+        throw error;
+    });
+}
+// A page or a worker has a handler for an error nobody caught (`window.onerror`), which an error rethrown on its own
+// reaches. Node, Deno, Bun and React Native have no `document`, and an uncaught error ends them: it is logged.
+function reportByDefault(error) {
+    if (typeof document !== 'undefined' || 'WorkerGlobalScope' in globalThis)
+        rethrowLater(error);
+    else
+        console.error(error);
+}
+/**
+ * Opens a stream the way `EventSource` would, with `fetch` underneath so it can send headers. It reconnects on its own,
+ * sends `Last-Event-ID` from the last `id:` it saw, waits the `retry:` the server asked for, and backs off with jitter
+ * when attempts fail. With `cursorIn: 'url'` the cursor goes to the URL function instead, and no header is sent. It starts at once; call `close()` to end it.
+ */
+export function connect(url, options) {
+    if (options.cursorIn !== undefined && options.cursorIn !== 'header' && options.cursorIn !== 'url') {
+        throw new TypeError(`cursorIn is 'header' or 'url', not ${JSON.stringify(options.cursorIn)}`);
+    }
+    if (options.cursorIn === 'url' && typeof url !== 'function') {
+        throw new TypeError("cursorIn: 'url' needs a URL function, which is given the cursor");
+    }
+    // A URL that can never be fetched fails here, as `new EventSource(url)` does, instead of being retried for ever. A `fetch`
+    // of the caller's may read URLs its own way.
+    if (typeof url !== 'function' && !options.fetch && !/^https?:$/.test(new URL(url, globalThis.location?.href).protocol)) {
+        throw new TypeError(`Not a URL fetch can read: ${String(url)}`);
+    }
+    // Headers given as a value, not a function, fail the same way every time: they fail here too.
+    if (typeof options.headers !== 'function')
+        new Headers(options.headers);
+    // An entry that is not a usable number keeps its default.
+    const entries = Object.entries(options.backoff ?? {}).filter(([, value]) => isDelay(value));
+    const backoff = { ...DEFAULT_BACKOFF, ...Object.fromEntries(entries) };
+    const endEvent = options.endEvent ?? 'end';
+    const connectTimeoutMs = timeoutOf(options.connectTimeoutMs, 15_000);
+    const idleTimeoutMs = timeoutOf(options.idleTimeoutMs, 45_000);
+    let closed = false;
+    let finished = false;
+    let controller = null;
+    let wake = null;
+    // From the end of a stream or a failed attempt until the wait begins, `retryNow` has no wait to cut short, and is held.
+    let between = false;
+    let retryAsked = false;
+    // Sent as `Last-Event-ID`: the id of the last event handed over, not the parser's, which can be ahead in the middle of a
+    // chunk. An id that cannot be a header value is no cursor.
+    let cursor = options.lastEventId && !/[\0\r\n]/.test(options.lastEventId) ? options.lastEventId : '';
+    // The last `retry:` any stream sent.
+    let serverRetry = null;
+    function report(error) {
+        try {
+            if (options.onCallbackError)
+                watch(options.onCallbackError(error), reportByDefault);
+            else
+                reportByDefault(error);
+        }
+        catch (inner) {
+            reportByDefault(inner);
+        }
+    }
+    // A rejection of an `async` callback is an error like a throw, not an unhandled rejection.
+    function watch(result, fail = report) {
+        if (typeof result?.then === 'function') {
+            result.then(undefined, fail);
+        }
+    }
+    // Calls a callback as a method of the options. What it throws, or rejects with, goes to `report`.
+    function notify(callback, ...args) {
+        try {
+            watch(callback?.call(options, ...args));
+        }
+        catch (error) {
+            report(error);
+        }
+    }
+    // With no argument for a close, with one, even `undefined`, for an error that ended the connection.
+    function finish(...error) {
+        if (finished)
+            return;
+        finished = true;
+        notify(options.onClose, ...error);
+    }
+    // `holdMs` is how long the wait must run before the browser may end it: all of it when the server or `onError` chose it.
+    function rest(ms, holdMs) {
+        // The browser coming back online, or the page becoming visible, is a reason to try now. `online` needs a global event
+        // target (a page, a worker), `visibilitychange` a `document`.
+        const hold = Math.max(EARLY_RETRY_MS, holdMs);
+        const listening = hold < ms && typeof globalThis.addEventListener === 'function';
+        const page = typeof document === 'undefined' ? null : document;
+        return new Promise((resolve) => {
+            const begun = now();
+            // An event before the hold is over sets the retry for its end, so switching tabs is not a request each time.
+            let early;
+            const onOnline = () => {
+                const left = hold - (now() - begun);
+                if (left <= 0)
+                    done();
+                else
+                    early ??= setTimeout(done, Math.min(left, MAX_TIMER_MS));
+            };
+            const onVisible = () => {
+                if (!page.hidden)
+                    onOnline();
+            };
+            const done = () => {
+                cancel();
+                clearTimeout(early);
+                wake = null;
+                if (listening) {
+                    globalThis.removeEventListener('online', onOnline);
+                    page?.removeEventListener('visibilitychange', onVisible);
+                }
+                resolve();
+            };
+            const cancel = longTimeout(ms, done);
+            wake = done;
+            if (listening) {
+                globalThis.addEventListener('online', onOnline);
+                page?.addEventListener('visibilitychange', onVisible);
+            }
+        });
+    }
+    async function attempt(outcome) {
+        const current = new AbortController();
+        controller = current;
+        between = false;
+        retryAsked = false;
+        const parser = createSseParser({ lastEventId: cursor }, { maxEventChars: options.maxEventChars });
+        let timedOut = null;
+        let opened = false;
+        let timer;
+        let deadline = 0;
+        // A chunk moves the idle deadline without touching the timer, which sleeps on for what is left when it fires early.
+        const arm = (phase, ms) => {
+            clearTimeout(timer);
+            if (ms <= 0)
+                return;
+            deadline = now() + ms;
+            const check = () => {
+                const left = deadline - now();
+                if (left > 0) {
+                    timer = setTimeout(check, left);
+                    return;
+                }
+                timedOut = phase;
+                current.abort();
+            };
+            timer = setTimeout(check, ms);
+        };
+        const touch = () => {
+            deadline = now() + idleTimeoutMs;
+        };
+        try {
+            // The connect timer covers `headers()` too: a dead token endpoint is a silent server.
+            arm('connect', connectTimeoutMs);
+            const given = typeof options.headers === 'function' ? await untilAborted(current.signal, options.headers()) : options.headers;
+            const headers = new Headers(given);
+            headers.set('Accept', 'text/event-stream');
+            // The client's cursor, not one from `headers`.
+            if (cursor && options.cursorIn !== 'url')
+                headers.set('Last-Event-ID', headerValue(cursor));
+            else
+                headers.delete('Last-Event-ID');
+            const fetchFn = options.fetch ?? ((input, init) => fetch(input, init));
+            // A `fetch` that ignores the signal is cut off, and an answer it gives later is freed.
+            const response = await untilAborted(current.signal, fetchFn(typeof url === 'function' ? url(cursor) : url, {
+                ...options.init,
+                body: undefined,
+                method: 'GET',
+                headers,
+                signal: current.signal,
+            }), discard);
+            if (!response.ok) {
+                void discard(response);
+                throw new StreamRefused(response.status, retryAfterOf(response.headers.get('retry-after')));
+            }
+            if (!isEventStream(response)) {
+                void discard(response);
+                throw new StreamRefused(response.status, null, 'The response is not an event stream');
+            }
+            if (!response.body) {
+                throw new StreamRefused(response.status, null, 'The response has no body to read: this runtime\'s fetch does not stream');
+            }
+            arm('idle', idleTimeoutMs);
+            opened = true;
+            outcome.openedAt = now();
+            notify(options.onOpen);
+            if (closed) {
+                void discard(response);
+                return null;
+            }
+            // The cursor is the id of the event being handled, and where the parser stands once a chunk's events are all handed
+            // over, which includes a frame of only an `id:` (pg-sse sends one first).
+            for await (const events of readChunks(response.body, touch, parser, current.signal)) {
+                for (const event of events) {
+                    if (closed)
+                        return null;
+                    cursor = event.id;
+                    if (event.event === endEvent) {
+                        const reason = endReason(event.data);
+                        between = true;
+                        notify(options.onEnd, reason);
+                        return reason;
+                    }
+                    notify(options.onEvent, event);
+                }
+                cursor = parser.lastEventId;
+            }
+            current.signal.throwIfAborted();
+            return null;
+        }
+        catch (error) {
+            if (timedOut)
+                throw new StreamTimeout(timedOut);
+            throw error;
+        }
+        finally {
+            clearTimeout(timer);
+            outcome.retry = parser.retry;
+            if (parser.retry !== null)
+                serverRetry = parser.retry;
+            between = true;
+            if (opened && !closed)
+                notify(options.onDisconnect);
+        }
+    }
+    const capped = (ms) => (ms === null ? null : Math.min(ms, backoff.serverMaxMs));
+    // The server's word (`retry:`, `Retry-After`) is a floor. After a clean end the `retry:` of the stream that ended is the
+    // whole wait, so the pause that follows a goodbye is the server's to set; without one the wait is spread at random.
+    function delayAfter(failures, retryAfterMs, retry) {
+        const hint = capped(retry);
+        if (failures === 0 && hint !== null)
+            return { ms: hint, holdMs: hint };
+        const floor = Math.max(capped(retryAfterMs) ?? 0, capped(serverRetry) ?? 0);
+        const ms = failures === 0
+            ? backoff.reconnectFloorMs + Math.random() * backoff.reconnectSpreadMs
+            : Math.min(backoff.maxMs, backoff.baseMs * 2 ** Math.min(failures - 1, 30)) * (0.5 + Math.random() / 2);
+        // Spread, so the clients a full server refused together do not come back at the same moment.
+        const refused = capped(retryAfterMs);
+        const spread = refused === null ? 0 : refused + Math.random() * backoff.reconnectSpreadMs;
+        return { ms: Math.max(floor, spread, ms), holdMs: Math.max(floor, spread) };
+    }
+    async function run() {
+        let failures = 0;
+        while (!closed) {
+            let wait;
+            let failure;
+            let failed = false;
+            const outcome = { openedAt: null, retry: null };
+            try {
+                const reason = await attempt(outcome);
+                if (closed)
+                    return;
+                // From when the stream opened: the attempt began earlier, with a `headers()` and a connect.
+                const lasted = now() - outcome.openedAt;
+                if (lasted >= backoff.shortMs) {
+                    failures = 0;
+                    wait = delayAfter(0, null, outcome.retry);
+                }
+                else {
+                    failures += 1;
+                    failed = true;
+                    failure = new StreamEndedEarly(lasted, reason);
+                    wait = delayAfter(failures, null, outcome.retry);
+                }
+            }
+            catch (error) {
+                if (closed)
+                    return;
+                failures = outcome.openedAt !== null && now() - outcome.openedAt >= backoff.shortMs ? 1 : failures + 1;
+                failed = true;
+                failure = error;
+                wait = delayAfter(failures, error instanceof StreamRefused ? error.retryAfterMs : null, outcome.retry);
+            }
+            if (failed) {
+                let asked;
+                try {
+                    asked = await options.onError?.(failure, { failures });
+                }
+                catch (error) {
+                    report(error);
+                }
+                const action = actionOf(asked) ?? defaultAction(failure);
+                if (closed)
+                    return;
+                if (action === 'stop') {
+                    finish(failure);
+                    return;
+                }
+                if (typeof action === 'object') {
+                    failures = 0;
+                    retryAsked = false;
+                    wait = { ms: action.retryAfterMs, holdMs: action.wakeOnResume ? 0 : action.retryAfterMs };
+                }
+            }
+            if (retryAsked)
+                continue;
+            between = false;
+            await rest(wait.ms, wait.holdMs);
+        }
+    }
+    // Nothing in `run` is meant to throw. If something does, the connection is over.
+    void run().catch((error) => finish(error));
+    return {
+        close() {
+            closed = true;
+            controller?.abort();
+            wake?.();
+            finish();
+        },
+        retryNow() {
+            if (wake)
+                wake();
+            else if (between)
+                retryAsked = true;
+        },
+        get lastEventId() {
+            return cursor;
+        },
+    };
+}

package/dist/event.d.ts

@@ -0,0 +1,17 @@
+export interface SseEvent {
+    /** The `event:` field, or `message` when the frame had none. */
+    event: string;
+    /** The `data:` lines joined with `\n`. */
+    data: string;
+    /** The stream's last event id once this frame was read: `''` when the server never sent one and the parser was not given one. */
+    id: string;
+}
+/** An event, or a line of one that has not ended yet, grew past `maxEventChars`. */
+export declare class SseEventTooLarge extends Error {
+    readonly limit: number;
+    /** The events the same chunk completed before the one that is too large, which `push` could not return. */
+    readonly events: SseEvent[];
+    constructor(limit: number, 
+    /** The events the same chunk completed before the one that is too large, which `push` could not return. */
+    events?: SseEvent[]);
+}

package/dist/event.js

@@ -0,0 +1,13 @@
+/** An event, or a line of one that has not ended yet, grew past `maxEventChars`. */
+export class SseEventTooLarge extends Error {
+    limit;
+    events;
+    constructor(limit, 
+    /** The events the same chunk completed before the one that is too large, which `push` could not return. */
+    events = []) {
+        super(`An event grew past ${limit} characters`);
+        this.limit = limit;
+        this.events = events;
+        this.name = 'SseEventTooLarge';
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { connect, StreamEndedEarly, StreamRefused, StreamTimeout } from './connect.js';
+export type { Backoff, Connection, ConnectOptions, ErrorAction, ErrorInfo } from './connect.js';
+export { createSseParser, readSse, SseEventTooLarge } from './standalone.js';
+export type { SseEvent, SseParser, SseParserLimits, SseParserState } from './standalone.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { connect, StreamEndedEarly, StreamRefused, StreamTimeout } from './connect.js';
+export { createSseParser, readSse, SseEventTooLarge } from './standalone.js';

package/dist/parser.d.ts

@@ -0,0 +1,34 @@
+import { SseEventTooLarge, type SseEvent } from './event.js';
+export { SseEventTooLarge };
+export type { SseEvent };
+export interface SseParserState {
+    lastEventId?: string;
+    retry?: number | null;
+}
+export interface SseParserLimits {
+    /**
+     * The most characters the parser holds for one event: the lines of the frame it is reading, field names included, and
+     * the line still arriving. More throws `SseEventTooLarge`. No limit by default, as with `EventSource`, or when it is 0;
+     * a client that sends credentials to a server it only half trusts wants one.
+     */
+    maxEventChars?: number;
+}
+export interface SseParser {
+    /** Feeds a decoded chunk in and returns the events it completes. Throws `SseEventTooLarge` past a limit: use a new parser then. */
+    push(chunk: string): SseEvent[];
+    /**
+     * The cursor to send as `Last-Event-ID`. It moves at the end of a frame, including a frame that carries only an `id:`
+     * line, which dispatches nothing.
+     */
+    readonly lastEventId: string;
+    /** The reconnect delay in milliseconds the server last asked for with `retry:`, or null if it never did. */
+    readonly retry: number | null;
+}
+/**
+ * An incremental parser for the text/event-stream format, following the WHATWG rules `EventSource` uses: lines end in
+ * `\n`, `\r\n` or `\r` (a chunk may split `\r\n`), `:` lines are comments, consecutive `data:` lines join with `\n`, a
+ * frame with no `data:` line is dropped, and so is a frame still open when the stream ends.
+ *
+ * `state` carries what outlives a connection: the last event id and the retry delay. The partial frame does not.
+ */
+export declare function createSseParser(state?: SseParserState, limits?: SseParserLimits): SseParser;

package/dist/parser.js

@@ -0,0 +1,143 @@
+import { SseEventTooLarge } from './event.js';
+export { SseEventTooLarge };
+// Where a line ends. Searched with `lastIndex`, so a scan starts where it is told and allocates nothing.
+const LINE_END = /[\r\n]/g;
+/**
+ * An incremental parser for the text/event-stream format, following the WHATWG rules `EventSource` uses: lines end in
+ * `\n`, `\r\n` or `\r` (a chunk may split `\r\n`), `:` lines are comments, consecutive `data:` lines join with `\n`, a
+ * frame with no `data:` line is dropped, and so is a frame still open when the stream ends.
+ *
+ * `state` carries what outlives a connection: the last event id and the retry delay. The partial frame does not.
+ */
+export function createSseParser(state = {}, limits = {}) {
+    // 0, as for the timeouts, is none; so is anything that is not a number above it.
+    const limit = limits.maxEventChars !== undefined && limits.maxEventChars > 0 ? limits.maxEventChars : undefined;
+    // The line still arriving, in the pieces it came in: joined once, when it ends, so a long one is not copied per chunk.
+    let partial = [];
+    let partialLength = 0;
+    let event = '';
+    let data = [];
+    // The characters of the open frame's lines so far, not counting the line still arriving.
+    let held = 0;
+    let pendingId = state.lastEventId ?? '';
+    let lastEventId = pendingId;
+    let retry = state.retry ?? null;
+    // A line that ended in \r at the end of a chunk: a \n that opens the next chunk is the other half of its \r\n.
+    let skipLf = false;
+    // The first chunk of a stream may open with a byte order mark, which is no part of the first line.
+    let fresh = true;
+    // The line still arriving is a comment: it is dropped as it comes, and counts for nothing.
+    let skipLine = false;
+    return {
+        get lastEventId() {
+            return lastEventId;
+        },
+        get retry() {
+            return retry;
+        },
+        push,
+    };
+    function push(chunk) {
+        if (chunk === '')
+            return [];
+        if (fresh) {
+            fresh = false;
+            if (chunk.startsWith('\uFEFF'))
+                chunk = chunk.slice(1);
+            if (chunk === '')
+                return [];
+        }
+        if (skipLf) {
+            skipLf = false;
+            if (chunk.startsWith('\n'))
+                chunk = chunk.slice(1);
+            if (chunk === '')
+                return [];
+        }
+        LINE_END.lastIndex = 0;
+        const ends = LINE_END.test(chunk);
+        if (skipLine) {
+            if (!ends)
+                return [];
+            let cut = LINE_END.lastIndex;
+            if (chunk[cut - 1] === '\r') {
+                if (cut === chunk.length)
+                    skipLf = true;
+                else if (chunk[cut] === '\n')
+                    cut += 1;
+            }
+            skipLine = false;
+            return push(chunk.slice(cut));
+        }
+        if (!ends) {
+            if (partial.length === 0 && chunk.startsWith(':')) {
+                skipLine = true;
+                return [];
+            }
+            partial.push(chunk);
+            partialLength += chunk.length;
+            if (limit !== undefined && held + partialLength > limit)
+                throw new SseEventTooLarge(limit);
+            return [];
+        }
+        const text = partial.length > 0 ? partial.join('') + chunk : chunk;
+        partial = [];
+        partialLength = 0;
+        const events = [];
+        let start = 0;
+        let tooLarge = false;
+        for (;;) {
+            LINE_END.lastIndex = start;
+            if (!LINE_END.test(text))
+                break;
+            const end = LINE_END.lastIndex - 1;
+            const line = text.slice(start, end);
+            // A \r ends the line at once; whether a \n follows it is for the next chunk to say.
+            if (text[end] === '\r' && end === text.length - 1)
+                skipLf = true;
+            start = text[end] === '\r' && text[end + 1] === '\n' ? end + 2 : end + 1;
+            if (line === '') {
+                lastEventId = pendingId;
+                if (data.length > 0)
+                    events.push({ event: event || 'message', data: data.join('\n'), id: lastEventId });
+                event = '';
+                data = [];
+                held = 0;
+                continue;
+            }
+            if (line.startsWith(':'))
+                continue;
+            // The event this line belongs to is too large already, however it ends: it is not read on, so the limit does not
+            // depend on where a chunk happened to end.
+            if (limit !== undefined && held + line.length > limit) {
+                tooLarge = true;
+                break;
+            }
+            held += line.length;
+            const colon = line.indexOf(':');
+            const field = colon === -1 ? line : line.slice(0, colon);
+            let value = colon === -1 ? '' : line.slice(colon + 1);
+            if (value.startsWith(' '))
+                value = value.slice(1);
+            if (field === 'event')
+                event = value;
+            else if (field === 'data')
+                data.push(value);
+            // An id with a NUL is ignored, so a hostile server cannot plant one the next request would send back.
+            else if (field === 'id' && !value.includes('\0'))
+                pendingId = value;
+            else if (field === 'retry' && /^\d+$/.test(value))
+                retry = Math.min(Number(value), Number.MAX_SAFE_INTEGER);
+        }
+        const rest = text.slice(start);
+        if (rest.startsWith(':'))
+            skipLine = true;
+        else if (rest !== '') {
+            partial.push(rest);
+            partialLength = rest.length;
+        }
+        if (tooLarge || (limit !== undefined && held + partialLength > limit))
+            throw new SseEventTooLarge(limit, events);
+        return events;
+    }
+}

package/dist/read.d.ts

@@ -0,0 +1,17 @@
+import { type SseEvent } from './event.js';
+import { type SseParser } from './parser.js';
+/**
+ * Reads a response body a chunk at a time and yields what each chunk completed, an empty array included: a chunk that
+ * completes no event may still have moved the parser's cursor, and the consumer decides when to look at it. Aborting
+ * `signal` cancels the reader, which ends a read still pending even when the body itself ignores the signal. Not exported
+ * from the package: `readSse` is the public way in.
+ */
+export declare function readChunks(body: ReadableStream<Uint8Array>, onActivity: (() => void) | undefined, parser: SseParser, signal?: AbortSignal): AsyncGenerator<SseEvent[]>;
+/**
+ * Yields the events of an SSE response body as they arrive. `onActivity` fires for every chunk of bytes read, comments
+ * and pings included, which is what an idle timeout wants to reset on. Pass a `parser` to read its `lastEventId` and
+ * `retry` while the stream is open or after it has ended. The parser reads a whole chunk before the first of its events
+ * is yielded, so its `lastEventId` can be ahead of the event you hold: to resume, use the `id` of the last event you handled.
+ * Give it a parser made for this body: one that has read before does not take a byte order mark off the start of the next.
+ */
+export declare function readSse(body: ReadableStream<Uint8Array>, onActivity?: () => void, parser?: SseParser): AsyncGenerator<SseEvent>;

package/dist/read.js

@@ -0,0 +1,58 @@
+import { SseEventTooLarge } from './event.js';
+import { createSseParser } from './parser.js';
+/**
+ * Reads a response body a chunk at a time and yields what each chunk completed, an empty array included: a chunk that
+ * completes no event may still have moved the parser's cursor, and the consumer decides when to look at it. Aborting
+ * `signal` cancels the reader, which ends a read still pending even when the body itself ignores the signal. Not exported
+ * from the package: `readSse` is the public way in.
+ */
+export async function* readChunks(body, onActivity, parser, signal) {
+    const reader = body.getReader();
+    // The parser takes a leading byte order mark off, once, wherever its text comes from.
+    const decoder = new TextDecoder('utf-8', { ignoreBOM: true });
+    const cancel = () => void reader.cancel().catch(() => { });
+    // Aborted already: there is no event to wait for, and the read below must not either.
+    if (signal?.aborted)
+        cancel();
+    else
+        signal?.addEventListener('abort', cancel, { once: true });
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                return;
+            onActivity?.();
+            let events;
+            const before = parser.lastEventId;
+            try {
+                events = parser.push(decoder.decode(value, { stream: true }));
+            }
+            catch (error) {
+                // The events before the one that is too large are still the consumer's.
+                if (error instanceof SseEventTooLarge && error.events.length > 0)
+                    yield error.events;
+                throw error;
+            }
+            // A ping completes nothing and moves no cursor: nothing for the consumer to look at.
+            if (events.length > 0 || parser.lastEventId !== before)
+                yield events;
+        }
+    }
+    finally {
+        // Also runs when the consumer stops early or the read throws (an abort): free the connection.
+        signal?.removeEventListener('abort', cancel);
+        cancel();
+    }
+}
+/**
+ * Yields the events of an SSE response body as they arrive. `onActivity` fires for every chunk of bytes read, comments
+ * and pings included, which is what an idle timeout wants to reset on. Pass a `parser` to read its `lastEventId` and
+ * `retry` while the stream is open or after it has ended. The parser reads a whole chunk before the first of its events
+ * is yielded, so its `lastEventId` can be ahead of the event you hold: to resume, use the `id` of the last event you handled.
+ * Give it a parser made for this body: one that has read before does not take a byte order mark off the start of the next.
+ */
+export async function* readSse(body, onActivity, parser = createSseParser()) {
+    // The reader is freed when the consumer stops early or the read throws, because the generator below is closed too.
+    for await (const events of readChunks(body, onActivity, parser))
+        yield* events;
+}

package/dist/standalone.d.ts

@@ -0,0 +1,3 @@
+export { createSseParser, SseEventTooLarge } from './parser.js';
+export type { SseEvent, SseParser, SseParserLimits, SseParserState } from './parser.js';
+export { readSse } from './read.js';

package/dist/standalone.js

@@ -0,0 +1,2 @@
+export { createSseParser, SseEventTooLarge } from './parser.js';
+export { readSse } from './read.js';

package/package.json

@@ -1,6 +1,71 @@
 {
   "name": "pg-sse-client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "A fetch-based server-sent events client for pg-sse streams: custom headers, Last-Event-ID resume, server retry hints and backoff.",
+  "keywords": [
+    "sse",
+    "server-sent-events",
+    "eventsource",
+    "fetch",
+    "pg-sse",
+    "postgres"
+  ],
+  "license": "MIT",
+  "author": "Sandhu Santhakumar <code@sandhu.sh>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sansanth/pg-sse-client.git"
+  },
+  "bugs": "https://github.com/sansanth/pg-sse-client/issues",
+  "type": "module",
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./parser": {
+      "types": "./dist/standalone.d.ts",
+      "default": "./dist/standalone.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "parser": [
+        "./dist/standalone.d.ts"
+      ]
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint --max-warnings 0 .",
+    "test": "vitest run --exclude \"test/integration/**\"",
+    "test:coverage": "vitest run --coverage --exclude \"test/integration/**\"",
+    "check": "npm run typecheck && npm run lint && npm run test:coverage && npm run build && npm run smoke",
+    "prepublishOnly": "npm run check",
+    "smoke": "node scripts/smoke.mjs"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^24.19.1",
+    "@vitest/coverage-v8": "^5.0.3",
+    "eslint": "^10.12.0",
+    "globals": "^17.13.0",
+    "jsdom": "^30.1.2",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.71.1",
+    "vitest": "^5.0.3"
+  }
+}