@stackline/sse 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes are documented in this file.
+
+## [1.0.0] - 2026-08-16
+
+### Added
+
+- WHATWG-compatible incremental SSE parser for strings and UTF-8 bytes.
+- Pull-based decoding for Response, Web Stream, async iterable, and iterable sources.
+- JSON event decoding with optional completion sentinel support.
+- Injection-resistant text and JSON encoders.
+- Fetch client with resume IDs, retry policy, jitter, Retry-After, and timeouts.
+- Callback compatibility for `eventsource-parser` and `@microsoft/fetch-event-source` migrations.
+- Backpressure-aware server channel and async-iterable Response helper.
+- Default line, event, and callback queue limits.
+- ESM, CommonJS, browser, and TypeScript declarations.
+- Cross-runtime CI, security tests, deterministic fuzzing, and release artifacts.
+- Abort-safe custom Fetch, body factories, and async iterators, including late-response cleanup.
+- Request header preservation when adding SSE negotiation and resume headers.
+
+[1.0.0]: https://github.com/alexandroit/stackline-sse/releases/tag/v1.0.0

package/CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Contributing
+
+Contributions are welcome through focused issues and pull requests.
+
+## Requirements
+
+- Node.js 20.20 or newer for development;
+- npm with lockfile support;
+- no new runtime dependency without a documented architectural reason.
+
+## Setup
+
+```bash
+npm ci
+npm test
+```
+
+Useful commands:
+
+```bash
+npm run test:unit
+npm run test:coverage
+npm run test:types
+npm run test:attw
+npm run benchmark
+npm run docs:serve
+```
+
+## Change expectations
+
+- Preserve WHATWG parsing behavior unless a deviation is explicitly documented.
+- Add a regression test for every bug fix.
+- Exercise arbitrary chunk boundaries for parser changes.
+- Preserve Node.js 14 parser and encoder compatibility.
+- Keep callback failures from causing automatic event replay.
+- Keep all externally controlled buffers bounded.
+- Update README, changelog, types, and examples with public API changes.
+
+Performance changes should include correctness assertions and benchmark output.
+Benchmarks are evidence, not a substitute for tests.
+
+## Commit and review scope
+
+Keep commits narrow and do not reformat unrelated files. Pull requests should
+describe behavior, compatibility impact, security impact, and verification.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alexandro Paixao Marques
+
+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/NOTICE

@@ -0,0 +1,6 @@
+@stackline/sse
+Copyright 2026 Alexandro Paixao Marques
+
+This is an independently designed implementation of the Server-Sent Events
+wire format defined by the WHATWG HTML Living Standard. Runtime code does not
+include source copied from the packages used for development comparisons.

package/README.md

@@ -0,0 +1,340 @@
+# @stackline/sse
+
+[![npm version](https://img.shields.io/npm/v/@stackline/sse.svg)](https://www.npmjs.com/package/@stackline/sse)
+[![npm downloads](https://img.shields.io/npm/dm/@stackline/sse.svg)](https://www.npmjs.com/package/@stackline/sse)
+[![CI](https://github.com/alexandroit/stackline-sse/actions/workflows/ci.yml/badge.svg)](https://github.com/alexandroit/stackline-sse/actions/workflows/ci.yml)
+[![CodeQL](https://github.com/alexandroit/stackline-sse/actions/workflows/codeql.yml/badge.svg)](https://github.com/alexandroit/stackline-sse/actions/workflows/codeql.yml)
+[![license](https://img.shields.io/npm/l/@stackline/sse.svg)](LICENSE)
+
+One zero-dependency toolkit for consuming, parsing, encoding, serving, and
+reconnecting Server-Sent Events. It is designed for AI token streams, live
+interfaces, serverless runtimes, browsers, and Node.js services.
+
+```bash
+npm install @stackline/sse
+```
+
+## Why this package
+
+SSE projects commonly combine one parser package, another encoder, a stale
+fetch wrapper, and custom server code. `@stackline/sse` gives those layers one
+consistent contract:
+
+- WHATWG-compatible incremental parsing of strings and UTF-8 bytes;
+- pull-based async iteration with real stream backpressure;
+- `fetch` streaming with POST, auth headers, retries, timeouts, and resume IDs;
+- safe event encoding that rejects CRLF and `Last-Event-ID` injection;
+- Web Stream and `Response` helpers for edge and server runtimes;
+- bounded line, event, and callback queues by default;
+- ESM, CommonJS, browser global, TypeScript 3.9 through 7, Deno, and Bun;
+- zero runtime dependencies.
+
+## AI streaming
+
+```js
+import { fetchSSE } from '@stackline/sse';
+
+const controller = new AbortController();
+
+for await (const event of fetchSSE('https://api.example.com/responses', {
+  method: 'POST',
+  headers: {
+    Authorization: `Bearer ${process.env.API_TOKEN}`,
+    'Content-Type': 'application/json'
+  },
+  body: JSON.stringify({ model: 'example-model', stream: true }),
+  signal: controller.signal,
+  connectTimeout: 10_000,
+  idleTimeout: 45_000,
+  totalTimeout: 5 * 60_000,
+  retry: {
+    retries: 3,
+    minDelay: 500,
+    maxDelay: 10_000
+  }
+})) {
+  if (event.data === '[DONE]') break;
+  console.log(event.event, JSON.parse(event.data));
+}
+```
+
+`fetchSSE` accepts all ordinary `fetch` request options. Node.js 18 and newer
+provide `fetch`; Node.js 14 and 16 can pass an implementation with `fetch`.
+
+## Parse any stream
+
+### Async iterator
+
+```js
+import { decodeSSE } from '@stackline/sse';
+
+const response = await fetch('/events');
+
+for await (const event of decodeSSE(response)) {
+  console.log(event.event, event.data, event.lastEventId);
+}
+```
+
+The source can be a `Response`, `ReadableStream`, `AsyncIterable`, or ordinary
+`Iterable` of `string` and `Uint8Array` chunks.
+
+### Incremental callback parser
+
+```js
+import { createParser } from '@stackline/sse';
+
+const parser = createParser({
+  onEvent(event) {
+    console.log(event.data);
+  },
+  onRetry(milliseconds) {
+    console.log('Server retry interval:', milliseconds);
+  }
+});
+
+parser.feed('id: 7\ndata: first chunk\n');
+parser.feed('data: second chunk\n\n');
+```
+
+Each event contains:
+
+```ts
+interface SSEEvent<T = string> {
+  data: T;
+  event?: string;
+  id?: string;         // ID field in this event block
+  lastEventId: string; // committed resume ID, including inherited IDs
+}
+```
+
+An `id`-only block commits `lastEventId` even when no message is dispatched.
+That detail matters when a connection closes immediately after a checkpoint.
+
+## JSON streams
+
+```js
+import { decodeJSON } from '@stackline/sse';
+
+for await (const event of decodeJSON(response, {
+  doneSentinel: '[DONE]'
+})) {
+  console.log(event.data); // parsed JSON value
+}
+```
+
+Invalid JSON throws `SSEParseError`. Set `ignoreInvalidJSON: true` only when a
+mixed text and JSON protocol intentionally requires it.
+
+## Encode events
+
+```js
+import { encodeJSON, encodeSSE } from '@stackline/sse';
+
+encodeSSE({
+  id: '42',
+  event: 'delta',
+  retry: 3000,
+  data: 'line one\nline two'
+});
+
+encodeJSON({ token: 'hello' }, { event: 'delta', id: '43' });
+```
+
+`id` and `event` values cannot contain line breaks. IDs also reject NUL. This
+prevents a value from injecting additional SSE fields or HTTP resume headers.
+
+## Serve events
+
+### Response from an async generator
+
+```js
+import { eventStreamResponse } from '@stackline/sse';
+
+async function* updates() {
+  yield { event: 'ready', data: 'connected', id: '1' };
+  yield { event: 'delta', data: 'hello', id: '2' };
+}
+
+export function GET() {
+  return eventStreamResponse(updates());
+}
+```
+
+The response includes `text/event-stream`, `no-cache, no-transform`, and
+`X-Accel-Buffering: no` headers unless the caller overrides them.
+
+### Push channel
+
+```js
+import { createSSEChannel } from '@stackline/sse';
+
+const channel = createSSEChannel({
+  heartbeatInterval: 15_000
+});
+
+const response = channel.toResponse();
+
+if (!channel.sendJSON({ progress: 25 }, { event: 'progress' })) {
+  await channel.ready;
+}
+
+channel.close();
+```
+
+`send` and `sendJSON` return `false` when the stream applies backpressure.
+Wait for `channel.ready` before producing more data.
+
+## Reconnection behavior
+
+`fetchSSE` follows SSE resume semantics and adds explicit production controls:
+
+- sends `Accept: text/event-stream` and `Cache-Control: no-store` behavior;
+- commits and forwards `Last-Event-ID` on reconnect;
+- honors valid `retry:` fields and `Retry-After` headers;
+- retries network failures and HTTP 408, 425, 429, 500, 502, 503, and 504;
+- rejects other HTTP statuses and incorrect content types;
+- uses exponential backoff with full jitter by default;
+- stops permanently on HTTP 204;
+- never replays a streaming request body without `bodyFactory`.
+
+Native EventSource reconnects indefinitely, so the default retry budget is
+also unlimited. Production applications should pass an `AbortSignal`, a finite
+`retry.retries`, or `totalTimeout`.
+
+```js
+const options = {
+  retry: {
+    retries: 5,
+    minDelay: 500,
+    maxDelay: 30_000,
+    factor: 2,
+    jitter: 'full'
+  },
+  onRetry({ delay, reconnects, error }) {
+    console.warn({ delay, reconnects, error });
+  }
+};
+```
+
+For a body that must be recreated on every attempt, `bodyFactory` receives the
+attempt number, committed resume ID, and that attempt's abort signal:
+
+```js
+const options = {
+  bodyFactory({ attempt, lastEventId, signal }) {
+    return createUploadStream({ attempt, lastEventId, signal });
+  }
+};
+```
+
+When the input is a `Request`, its headers are preserved unless `options.headers`
+explicitly replaces them. The SSE `Accept` and resume headers are then merged
+case-insensitively.
+
+## Memory safety
+
+The parser is bounded by default:
+
+| Limit | Default | Purpose |
+| --- | ---: | --- |
+| `maxLineLength` | 1 MiB | unterminated or oversized field line |
+| `maxEventSize` | 1 MiB | accumulated multiline event |
+| `maxQueuedEvents` | 4096 | callback burst inside one feed slice |
+| `feedSize` | 16 KiB | limits work admitted before yielding |
+
+Raise a limit explicitly for a trusted protocol that carries larger events.
+Limit failures terminate the parser with a stable `ERR_SSE_*` code.
+
+## Migration
+
+### From eventsource-parser
+
+Direct dependency:
+
+```bash
+npm install @stackline/sse
+```
+
+The familiar API is available:
+
+```js
+import { createParser } from '@stackline/sse';
+```
+
+For a low-change trial, npm aliases preserve the old import name:
+
+```bash
+npm install eventsource-parser@npm:@stackline/sse
+```
+
+`createParser({ onEvent, onRetry, onComment, onError, maxBufferSize })` is
+supported. The additional `lastEventId` property follows WHATWG resume
+semantics. Security limits are enabled by default, unlike unbounded parsers.
+
+### From @microsoft/fetch-event-source
+
+```bash
+npm install @stackline/sse
+```
+
+```js
+import { fetchEventSource } from '@stackline/sse';
+
+await fetchEventSource('/events', {
+  onopen(response) {},
+  onmessage(event) {},
+  onclose(context) {},
+  onerror(error) {}
+});
+```
+
+An alias can support staged migration:
+
+```bash
+npm install @microsoft/fetch-event-source@npm:@stackline/sse
+```
+
+The callback names are supported. `openWhenHidden` is accepted but this package
+does not silently disconnect a healthy stream when a page becomes hidden.
+
+## Runtime matrix
+
+| Runtime | Parser / encoder | Fetch client | Server helpers |
+| --- | --- | --- | --- |
+| Modern browsers | Yes | Yes | Yes |
+| Node.js 18+ | Yes | Yes | Yes |
+| Node.js 14 / 16 | Yes | Inject `fetch` | Inject Web Streams if needed |
+| Deno 2 | Yes | Yes | Yes |
+| Bun | Yes | Yes | Yes |
+| Cloudflare Workers | Yes | Yes | Yes |
+
+The package ships ESM, CommonJS, a browser IIFE, and declarations tested with
+TypeScript 3.9, 4.7, 4.9, 5.x, 6.x, and 7.x.
+
+## Errors
+
+| Class | Code | Meaning |
+| --- | --- | --- |
+| `SSEParseError` | `ERR_SSE_PARSE` and specific variants | malformed or limited stream |
+| `SSEEncodeError` | `ERR_SSE_ENCODE` | unsafe or unsupported output field |
+| `SSEHTTPError` | `ERR_SSE_HTTP` | rejected HTTP response |
+| `SSETimeoutError` | `ERR_SSE_TIMEOUT` | connect, idle, or total deadline |
+| `SSERetryError` | `ERR_SSE_RETRY` | finite reconnect budget exhausted |
+| `SSEReplayError` | `ERR_SSE_BODY_REPLAY` | non-replayable request body |
+
+## Package integrity
+
+- zero runtime dependencies;
+- no install scripts;
+- deterministic ESM, CommonJS, and browser builds;
+- CI tests Node.js 14 through 24, Windows, macOS, Linux, Deno, and Bun;
+- CodeQL, npm audit, registry signature verification, `publint`, and
+  Are the Types Wrong checks;
+- release tarballs include SHA-512 checksums and a CycloneDX SBOM.
+
+See [SECURITY.md](SECURITY.md) for vulnerability reporting and
+[CONTRIBUTING.md](CONTRIBUTING.md) for development instructions.
+
+## License
+
+[MIT](LICENSE) Copyright 2026 Alexandro Paixao Marques.

package/SECURITY.md

@@ -0,0 +1,35 @@
+# Security Policy
+
+## Supported versions
+
+| Version | Supported |
+| --- | --- |
+| 1.x | Yes |
+| Pre-release or unpublished builds | No |
+
+Security fixes are released as new immutable npm versions. A vulnerable
+published version is deprecated when appropriate; it is not silently replaced.
+
+## Reporting a vulnerability
+
+Do not open a public issue for an undisclosed vulnerability. Use GitHub's
+private vulnerability reporting for
+[alexandroit/stackline-sse](https://github.com/alexandroit/stackline-sse/security/advisories/new).
+
+Include:
+
+- affected version and runtime;
+- minimal reproduction or malformed byte sequence;
+- security impact and expected behavior;
+- whether the issue affects parser, encoder, client, or server APIs.
+
+Reports are acknowledged as soon as practical. Confirmed issues receive a
+coordinated fix, regression tests, release notes, and credit when requested.
+
+## Security boundaries
+
+The package limits parser memory and validates encoded control fields. It does
+not authenticate event producers, authorize endpoints, validate event JSON
+schemas, encrypt transport, or make arbitrary event data safe for HTML output.
+Applications must still use HTTPS, validate origin and payloads, and escape
+data at the rendering boundary.