@orkestrel/sse 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Orkestrel
+
+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

@@ -0,0 +1,73 @@
+# @orkestrel/sse
+
+A typed Server-Sent Events parser — incremental, spec-compliant parsing of
+event-stream chunks into typed events with `data`, `event`, `id`, and `retry`
+fields. Feed it string chunks as they arrive; a blank line dispatches the
+accumulated event, and a partial line or in-progress event split across
+chunk boundaries is buffered until the rest arrives. The `id` / `retry`
+fields also persist as sticky connection state — surfaced via the `id` /
+`retry` getters for reconnection — and an optional `limit` bounds total
+buffered characters. A pure functional primitive — no Emitter, no events, no
+server / HTTP / agent coupling; it never throws on malformed input, only a
+typed `SSEError('OVERFLOW')` when a configured `limit` is exceeded. Part of
+the `@orkestrel` line.
+
+## Install
+
+```sh
+npm install @orkestrel/sse
+```
+
+## Requirements
+
+- Node.js >= 24
+- ESM + CJS (dual-format build)
+- No runtime dependencies
+
+## Usage
+
+```ts
+import { createSSEParser, isSSEError } from '@orkestrel/sse'
+
+const parser = createSSEParser({ limit: 1_000_000 })
+parser.parse('data: a\ndata: b\n\n') // [{ data: 'a\nb' }] - the two data lines joined
+parser.parse('event: ping\ndata: 1') // [] - buffered until its blank line
+parser.parse('\n\n') // [{ data: '1', event: 'ping' }]
+
+parser.id // '1' - sticky last-event-id, survives dispatch
+parser.retry // undefined - sticky reconnection time, until a retry: field arrives
+
+try {
+	parser.parse('x'.repeat(2_000_000))
+} catch (error) {
+	if (isSSEError(error) && error.code === 'OVERFLOW') parser.reset()
+}
+
+parser.flush() // force out a trailing unterminated event at end-of-stream
+parser.reset() // full reset - drops buffered state and sticky id/retry
+```
+
+Pair it with a `TextDecoder({ stream: true })` when reading a byte stream so
+multi-byte UTF-8 characters split across reads are handled — the decoder
+handles partial characters, this parser handles partial lines and events.
+
+The optional `limit` option caps total buffered characters; when set, a
+`parse(chunk)` call that would exceed it throws a typed `SSEError('OVERFLOW')`
+instead of growing unbounded, leaving parser state unchanged. Without
+`flush()`, a stream that ends without a final blank line has its last event
+discarded per spec — call `flush()` at end-of-stream to force it out.
+
+## Guide
+
+For the full surface — the `SSEParser` class, its `SSEEvent` shape, the wire
+format it implements, and the `createSSEParser` factory — see
+[`guides/src/sse.md`](guides/src/sse.md).
+
+## Package
+
+Published as a single typed entry point per the `exports` field in
+`package.json`.
+
+## License
+
+MIT © [Orkestrel](https://github.com/orkestrel) — see [LICENSE](./LICENSE).

package/dist/src/core/index.cjs

@@ -0,0 +1,304 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/core/constants.ts
+/**
+* The NUL byte (`U+0000`). The SSE spec voids an `id:` field whose value contains
+* it, so an `id` carrying a NUL is never surfaced. Spelled as a codepoint so the
+* wire content is unambiguous in source.
+*/
+var NUL = String.fromCharCode(0);
+/**
+* The byte-order mark (`U+FEFF`), stripped from the very first chunk of an SSE
+* stream (a leading BOM on later chunks is ordinary content). Spelled as a
+* codepoint so the wire content is unambiguous in source.
+*/
+var BOM = String.fromCharCode(65279);
+//#endregion
+//#region src/core/errors.ts
+/**
+* An error thrown by the SSE parser.
+*
+* @remarks
+* Thrown for: a `parse(chunk)` call whose resulting buffered total (un-consumed
+* line buffer + accumulated per-event field lengths + the incoming chunk) would
+* exceed a configured {@link import('./types.js').SSEParserOptions.limit}
+* (`OVERFLOW`). The parser's state is left UNCHANGED by the throwing call - the
+* chunk is not appended - so a consumer may `reset()` and continue. `context`
+* carries at least `{ limit, size }`: the configured limit and the size the
+* buffer would have reached.
+*/
+var SSEError = class extends Error {
+	code;
+	context;
+	constructor(code, message, context) {
+		super(message);
+		this.name = "SSEError";
+		this.code = code;
+		this.context = context;
+	}
+};
+/**
+* Narrow an unknown caught value to an {@link SSEError}.
+*
+* @param value - The value to test (typically a `catch` binding)
+* @returns `true` when `value` is an {@link SSEError}
+*
+* @example
+* ```ts
+* import { isSSEError } from '@src/core'
+*
+* try {
+* 	parser.parse(chunk)
+* } catch (error) {
+* 	if (isSSEError(error) && error.code === 'OVERFLOW') parser.reset()
+* }
+* ```
+*/
+function isSSEError(value) {
+	return value instanceof SSEError;
+}
+//#endregion
+//#region src/core/SSEParser.ts
+/**
+* A stateful Server-Sent-Events (SSE) stream parser - feed it string chunks, get
+* back the complete events dispatched so far.
+*
+* @remarks
+* - **The wire format.** SSE is a UTF-8 text stream of events separated by a blank
+*   line. Within an event each line is a `field: value` (one optional space after the
+*   colon is stripped; a line with no colon is a field with an empty value; a line
+*   STARTING with a colon is a comment and is ignored). The fields: `data` is appended
+*   to the event's data buffer - MULTIPLE `data:` lines concatenate with `\n` between
+*   them (`data: a` + `data: b` → `"a\nb"`), with no trailing newline; `event` sets the
+*   event type (last wins); `id` sets the last-event-id (last wins; an `id` containing a
+*   NUL is ignored per spec); `retry` sets the reconnection time in ms (integer only -
+*   a non-integer is ignored). Unknown fields are ignored.
+* - **Blank-line dispatch.** A blank line flushes the accumulated event: an
+*   {@link SSEEvent} is emitted ONLY when the data buffer is non-empty (a dispatch with
+*   an empty data buffer emits nothing - a comment-only or field-only "event" produces
+*   no event), and the data buffer + event type reset for the next event afterwards.
+*   `id` / `retry` ride on the emitted event for the consumer to track per-event - the
+*   emitted event's shape is unchanged - AND are separately persisted as connection
+*   state, exposed via the sticky `id` / `retry` getters (see below).
+* - **Sticky connection state.** Each valid `id:` field updates a persisted
+*   last-event-id, exposed via the `id` getter; each valid `retry:` field updates a
+*   persisted reconnection time, exposed via the `retry` getter. Neither is cleared
+*   when an event dispatches - only `reset()` clears them - matching WHATWG
+*   last-event-id semantics. A NUL-voided `id` field does not alter the persisted
+*   value.
+* - **Cross-chunk reassembly.** `parse(chunk)` appends `chunk` to an internal buffer,
+*   splits on the line terminator, processes every COMPLETE line, and retains the
+*   trailing partial line (and any in-progress event) for the next call - so an event
+*   split across chunk boundaries is reassembled once its blank line arrives. An
+*   un-terminated final event stays buffered and is never emitted until its blank
+*   line arrives - call `flush()` to force it out at end-of-stream instead.
+* - **Line endings + BOM.** `\r\n`, `\r`, and `\n` are all valid terminators and are
+*   normalized; a CRLF split across two chunks is held safely (a trailing `\r` is
+*   retained, not flushed as a line, until its `\n` is known). A leading byte-order
+*   mark on the first NON-EMPTY chunk is stripped (an empty `parse('')` call before
+*   any content does not arm the BOM check).
+* - **Bounded buffering.** Pass {@link SSEParserOptions.limit} to cap the total
+*   buffered characters (un-consumed line buffer + in-progress event field lengths);
+*   a `parse(chunk)` call that would exceed it throws an {@link SSEError} with code
+*   `'OVERFLOW'` and leaves parser state unchanged - the chunk is not appended.
+* - **Total + event-free.** A pure functional primitive - no Emitter, no events, no
+*   server / HTTP / agent coupling. It never throws on malformed input (a bad `retry`
+*   is ignored, not thrown) - it throws only an {@link SSEError} when a configured
+*   `limit` is exceeded. Testable with plain strings. Pair it with a
+*   `TextDecoder({ stream: true })` when reading a byte stream so multi-byte UTF-8
+*   characters split across reads are handled (the decoder handles partial CHARS, this
+*   parser handles partial LINES + events).
+*
+* @example
+* ```ts
+* const parser = new SSEParser({ limit: 1_000_000 })
+* parser.parse('data: a\ndata: b\n\n') // [{ data: 'a\nb' }] - the two data lines joined
+* parser.parse('event: ping\ndata: 1') // [] - the event is buffered until its blank line
+* parser.parse('\n\n')                  // [{ data: '1', event: 'ping' }]
+* parser.id                             // undefined - no `id:` field has been seen
+* ```
+*/
+var SSEParser = class {
+	#limit;
+	#buffer = "";
+	#offset = 0;
+	#started = false;
+	#carriage = false;
+	#data = [];
+	#event = void 0;
+	#id = void 0;
+	#retry = void 0;
+	#lastId = void 0;
+	#lastRetry = void 0;
+	constructor(options) {
+		this.#limit = options?.limit;
+	}
+	get id() {
+		return this.#lastId;
+	}
+	get retry() {
+		return this.#lastRetry;
+	}
+	parse(chunk) {
+		if (this.#limit !== void 0) {
+			const size = this.#size() + chunk.length;
+			if (size > this.#limit) throw new SSEError("OVERFLOW", `SSE parser buffer would exceed the configured limit of ${this.#limit} characters`, {
+				limit: this.#limit,
+				size
+			});
+		}
+		if (!this.#started && chunk.length > 0) {
+			this.#started = true;
+			if (chunk.startsWith("")) chunk = chunk.slice(1);
+		}
+		this.#buffer += chunk;
+		const events = [];
+		for (;;) {
+			const line = this.#take();
+			if (line === void 0) break;
+			this.#process(line, events);
+		}
+		if (this.#offset > 0) {
+			this.#buffer = this.#buffer.slice(this.#offset);
+			this.#offset = 0;
+		}
+		return events;
+	}
+	flush() {
+		const events = [];
+		if (this.#buffer.length > 0) {
+			const line = this.#buffer;
+			this.#buffer = "";
+			this.#offset = 0;
+			this.#process(line, events);
+		}
+		this.#dispatch(events);
+		return events;
+	}
+	reset() {
+		this.#buffer = "";
+		this.#offset = 0;
+		this.#started = false;
+		this.#carriage = false;
+		this.#clear();
+		this.#lastId = void 0;
+		this.#lastRetry = void 0;
+	}
+	#size() {
+		let dataTotal = 0;
+		for (const segment of this.#data) dataTotal += segment.length;
+		return this.#buffer.length + dataTotal + (this.#event?.length ?? 0) + (this.#id?.length ?? 0);
+	}
+	#take() {
+		if (this.#carriage && this.#offset < this.#buffer.length) {
+			if (this.#buffer[this.#offset] === "\n") this.#offset += 1;
+			this.#carriage = false;
+		}
+		const newline = this.#buffer.indexOf("\n", this.#offset);
+		const carriage = this.#buffer.indexOf("\r", this.#offset);
+		if (newline === -1 && carriage === -1) return void 0;
+		if (carriage !== -1 && (newline === -1 || carriage < newline)) {
+			this.#carriage = true;
+			const line = this.#buffer.slice(this.#offset, carriage);
+			this.#offset = carriage + 1;
+			return line;
+		}
+		const line = this.#buffer.slice(this.#offset, newline);
+		this.#offset = newline + 1;
+		return line;
+	}
+	#process(line, events) {
+		if (line.length === 0) {
+			this.#dispatch(events);
+			return;
+		}
+		if (line.startsWith(":")) return;
+		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);
+		this.#field(field, value);
+	}
+	#field(field, value) {
+		if (field === "data") this.#data.push(value);
+		else if (field === "event") this.#event = value;
+		else if (field === "id") {
+			if (!value.includes("\0")) {
+				this.#id = value;
+				this.#lastId = value;
+			}
+		} else if (field === "retry") {
+			if (/^\d+$/.test(value)) {
+				this.#retry = Number(value);
+				this.#lastRetry = this.#retry;
+			}
+		}
+	}
+	#dispatch(events) {
+		if (this.#data.length > 0) {
+			const event = {
+				data: this.#data.join("\n"),
+				...this.#event !== void 0 ? { event: this.#event } : {},
+				...this.#id !== void 0 ? { id: this.#id } : {},
+				...this.#retry !== void 0 ? { retry: this.#retry } : {}
+			};
+			events.push(event);
+		}
+		this.#clear();
+	}
+	#clear() {
+		this.#data = [];
+		this.#event = void 0;
+		this.#id = void 0;
+		this.#retry = void 0;
+	}
+};
+//#endregion
+//#region src/core/factories.ts
+/**
+* Create a Server-Sent-Events (SSE) stream parser - a stateful handle that turns
+* string chunks into the complete events dispatched so far.
+*
+* @param options - See {@link SSEParserOptions}.
+* @remarks
+* `options.limit` caps the total buffered characters (un-consumed line buffer plus
+* the in-progress event's field lengths); unset → unbounded, the default. Feed
+* chunks to `parse(chunk)` as they arrive; each blank line DISPATCHES an event whose
+* `data` is its `data:` fields joined by `\n` (plus the last `event:` / `id:` /
+* `retry:`), and an in-progress event split across chunk boundaries is buffered until
+* its blank line arrives (or `flush()` forces it out at end-of-stream). The `id` /
+* `retry` getters expose the persisted last-event-id / reconnection time, which
+* survive dispatch and only clear on `reset()`. Generic and event-free - no
+* server / agent coupling; never throws on malformed input, only on a configured
+* `limit` being exceeded (an {@link import('./errors.js').SSEError} with code
+* `'OVERFLOW'`). Pair it with a `TextDecoder({ stream: true })` to also handle
+* multi-byte UTF-8 characters split across byte reads.
+*
+* @returns A working {@link SSEParserInterface}
+*
+* @example
+* ```ts
+* import { createSSEParser, isSSEError } from '@src/core'
+*
+* const parser = createSSEParser({ limit: 1_000_000 })
+* parser.parse('data: a\ndata: b\n\n') // [{ data: 'a\nb' }] - the two data lines joined
+* parser.parse('event: ping\ndata: 1') // [] - buffered until its blank line
+* parser.parse('\n\n')                  // [{ data: '1', event: 'ping' }]
+* try {
+* 	parser.parse('x'.repeat(2_000_000))
+* } catch (error) {
+* 	if (isSSEError(error) && error.code === 'OVERFLOW') parser.reset()
+* }
+* ```
+*/
+function createSSEParser(options) {
+	return new SSEParser(options);
+}
+//#endregion
+exports.BOM = BOM;
+exports.NUL = NUL;
+exports.SSEError = SSEError;
+exports.SSEParser = SSEParser;
+exports.createSSEParser = createSSEParser;
+exports.isSSEError = isSSEError;
+
+//# sourceMappingURL=index.cjs.map

package/dist/src/core/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["#limit","#lastId","#lastRetry","#size","#started","#buffer","#take","#process","#offset","#dispatch","#carriage","#clear","#data","#event","#id","#field","#retry"],"sources":["../../../src/core/constants.ts","../../../src/core/errors.ts","../../../src/core/SSEParser.ts","../../../src/core/factories.ts"],"sourcesContent":["/**\n * The NUL byte (`U+0000`). The SSE spec voids an `id:` field whose value contains\n * it, so an `id` carrying a NUL is never surfaced. Spelled as a codepoint so the\n * wire content is unambiguous in source.\n */\nexport const NUL = String.fromCharCode(0)\n\n/**\n * The byte-order mark (`U+FEFF`), stripped from the very first chunk of an SSE\n * stream (a leading BOM on later chunks is ordinary content). Spelled as a\n * codepoint so the wire content is unambiguous in source.\n */\nexport const BOM = String.fromCharCode(0xfeff)\n","import type { SSEErrorCode } from './types.js'\n\n// AGENTS §12: a configured `limit` exceeded by a `parse(chunk)` call `throw`s an\n// `SSEError` carrying a machine-readable `code`, so a `catch` branches on `error.code`\n// instead of parsing the message. Every other malformed-input case (a bad `retry`, a\n// NUL-voided `id`, an unknown field) is ignored per the WHATWG SSE algorithm and never\n// throws.\n\n/**\n * An error thrown by the SSE parser.\n *\n * @remarks\n * Thrown for: a `parse(chunk)` call whose resulting buffered total (un-consumed\n * line buffer + accumulated per-event field lengths + the incoming chunk) would\n * exceed a configured {@link import('./types.js').SSEParserOptions.limit}\n * (`OVERFLOW`). The parser's state is left UNCHANGED by the throwing call - the\n * chunk is not appended - so a consumer may `reset()` and continue. `context`\n * carries at least `{ limit, size }`: the configured limit and the size the\n * buffer would have reached.\n */\nexport class SSEError extends Error {\n\treadonly code: SSEErrorCode\n\treadonly context?: Readonly<Record<string, unknown>>\n\n\tconstructor(code: SSEErrorCode, message: string, context?: Readonly<Record<string, unknown>>) {\n\t\tsuper(message)\n\t\tthis.name = 'SSEError'\n\t\tthis.code = code\n\t\tthis.context = context\n\t}\n}\n\n/**\n * Narrow an unknown caught value to an {@link SSEError}.\n *\n * @param value - The value to test (typically a `catch` binding)\n * @returns `true` when `value` is an {@link SSEError}\n *\n * @example\n * ```ts\n * import { isSSEError } from '@src/core'\n *\n * try {\n * \tparser.parse(chunk)\n * } catch (error) {\n * \tif (isSSEError(error) && error.code === 'OVERFLOW') parser.reset()\n * }\n * ```\n */\nexport function isSSEError(value: unknown): value is SSEError {\n\treturn value instanceof SSEError\n}\n","import type { SSEEvent, SSEParserInterface, SSEParserOptions } from './types.js'\nimport { BOM, NUL } from './constants.js'\nimport { SSEError } from './errors.js'\n\n/**\n * A stateful Server-Sent-Events (SSE) stream parser - feed it string chunks, get\n * back the complete events dispatched so far.\n *\n * @remarks\n * - **The wire format.** SSE is a UTF-8 text stream of events separated by a blank\n *   line. Within an event each line is a `field: value` (one optional space after the\n *   colon is stripped; a line with no colon is a field with an empty value; a line\n *   STARTING with a colon is a comment and is ignored). The fields: `data` is appended\n *   to the event's data buffer - MULTIPLE `data:` lines concatenate with `\\n` between\n *   them (`data: a` + `data: b` → `\"a\\nb\"`), with no trailing newline; `event` sets the\n *   event type (last wins); `id` sets the last-event-id (last wins; an `id` containing a\n *   NUL is ignored per spec); `retry` sets the reconnection time in ms (integer only -\n *   a non-integer is ignored). Unknown fields are ignored.\n * - **Blank-line dispatch.** A blank line flushes the accumulated event: an\n *   {@link SSEEvent} is emitted ONLY when the data buffer is non-empty (a dispatch with\n *   an empty data buffer emits nothing - a comment-only or field-only \"event\" produces\n *   no event), and the data buffer + event type reset for the next event afterwards.\n *   `id` / `retry` ride on the emitted event for the consumer to track per-event - the\n *   emitted event's shape is unchanged - AND are separately persisted as connection\n *   state, exposed via the sticky `id` / `retry` getters (see below).\n * - **Sticky connection state.** Each valid `id:` field updates a persisted\n *   last-event-id, exposed via the `id` getter; each valid `retry:` field updates a\n *   persisted reconnection time, exposed via the `retry` getter. Neither is cleared\n *   when an event dispatches - only `reset()` clears them - matching WHATWG\n *   last-event-id semantics. A NUL-voided `id` field does not alter the persisted\n *   value.\n * - **Cross-chunk reassembly.** `parse(chunk)` appends `chunk` to an internal buffer,\n *   splits on the line terminator, processes every COMPLETE line, and retains the\n *   trailing partial line (and any in-progress event) for the next call - so an event\n *   split across chunk boundaries is reassembled once its blank line arrives. An\n *   un-terminated final event stays buffered and is never emitted until its blank\n *   line arrives - call `flush()` to force it out at end-of-stream instead.\n * - **Line endings + BOM.** `\\r\\n`, `\\r`, and `\\n` are all valid terminators and are\n *   normalized; a CRLF split across two chunks is held safely (a trailing `\\r` is\n *   retained, not flushed as a line, until its `\\n` is known). A leading byte-order\n *   mark on the first NON-EMPTY chunk is stripped (an empty `parse('')` call before\n *   any content does not arm the BOM check).\n * - **Bounded buffering.** Pass {@link SSEParserOptions.limit} to cap the total\n *   buffered characters (un-consumed line buffer + in-progress event field lengths);\n *   a `parse(chunk)` call that would exceed it throws an {@link SSEError} with code\n *   `'OVERFLOW'` and leaves parser state unchanged - the chunk is not appended.\n * - **Total + event-free.** A pure functional primitive - no Emitter, no events, no\n *   server / HTTP / agent coupling. It never throws on malformed input (a bad `retry`\n *   is ignored, not thrown) - it throws only an {@link SSEError} when a configured\n *   `limit` is exceeded. Testable with plain strings. Pair it with a\n *   `TextDecoder({ stream: true })` when reading a byte stream so multi-byte UTF-8\n *   characters split across reads are handled (the decoder handles partial CHARS, this\n *   parser handles partial LINES + events).\n *\n * @example\n * ```ts\n * const parser = new SSEParser({ limit: 1_000_000 })\n * parser.parse('data: a\\ndata: b\\n\\n') // [{ data: 'a\\nb' }] - the two data lines joined\n * parser.parse('event: ping\\ndata: 1') // [] - the event is buffered until its blank line\n * parser.parse('\\n\\n')                  // [{ data: '1', event: 'ping' }]\n * parser.id                             // undefined - no `id:` field has been seen\n * ```\n */\nexport class SSEParser implements SSEParserInterface {\n\treadonly #limit: number | undefined\n\t#buffer = ''\n\t// Read cursor into `#buffer` for the current `parse()` call - lines are consumed\n\t// by advancing this offset, never by front-slicing `#buffer` per line. The\n\t// invariant `#offset === 0` holds BETWEEN calls: `parse()` compacts `#buffer` to\n\t// its unconsumed tail (and resets `#offset` to 0) once, at the end of the call.\n\t#offset = 0\n\t#started = false\n\t// True when the last consumed line was terminated by a `\\r`: a `\\n` arriving next\n\t// (the second half of a CRLF split across chunks) is then swallowed, not read as a\n\t// fresh blank line. This lets a bare-`\\r` terminator flush immediately AND keeps a\n\t// CRLF straddling a chunk boundary as one terminator.\n\t#carriage = false\n\t// The in-progress event accumulator, reset after each blank-line dispatch.\n\t#data: string[] = []\n\t#event: string | undefined = undefined\n\t#id: string | undefined = undefined\n\t#retry: number | undefined = undefined\n\t// Persisted connection state (WHATWG last-event-id / reconnection time) - updated\n\t// by every valid `id:` / `retry:` field, never cleared on dispatch; only `reset()`\n\t// clears them.\n\t#lastId: string | undefined = undefined\n\t#lastRetry: number | undefined = undefined\n\n\tconstructor(options?: SSEParserOptions) {\n\t\tthis.#limit = options?.limit\n\t}\n\n\tget id(): string | undefined {\n\t\treturn this.#lastId\n\t}\n\n\tget retry(): number | undefined {\n\t\treturn this.#lastRetry\n\t}\n\n\tparse(chunk: string): readonly SSEEvent[] {\n\t\tif (this.#limit !== undefined) {\n\t\t\tconst size = this.#size() + chunk.length\n\t\t\tif (size > this.#limit) {\n\t\t\t\tthrow new SSEError(\n\t\t\t\t\t'OVERFLOW',\n\t\t\t\t\t`SSE parser buffer would exceed the configured limit of ${this.#limit} characters`,\n\t\t\t\t\t{ limit: this.#limit, size },\n\t\t\t\t)\n\t\t\t}\n\t\t}\n\t\t// Strip a leading byte-order mark on the first NON-EMPTY chunk only - an empty\n\t\t// `parse('')` before any content must not disarm the check.\n\t\tif (!this.#started && chunk.length > 0) {\n\t\t\tthis.#started = true\n\t\t\tif (chunk.startsWith(BOM)) chunk = chunk.slice(BOM.length)\n\t\t}\n\t\tthis.#buffer += chunk\n\t\tconst events: SSEEvent[] = []\n\t\t// Pull every COMPLETE line off the buffer by advancing the read cursor, leaving\n\t\t// the trailing partial line buffered (unconsumed) for the next call.\n\t\tfor (;;) {\n\t\t\tconst line = this.#take()\n\t\t\tif (line === undefined) break\n\t\t\tthis.#process(line, events)\n\t\t}\n\t\t// Compact once per call: drop the consumed prefix and reset the cursor.\n\t\tif (this.#offset > 0) {\n\t\t\tthis.#buffer = this.#buffer.slice(this.#offset)\n\t\t\tthis.#offset = 0\n\t\t}\n\t\treturn events\n\t}\n\n\tflush(): SSEEvent[] {\n\t\tconst events: SSEEvent[] = []\n\t\tif (this.#buffer.length > 0) {\n\t\t\tconst line = this.#buffer\n\t\t\tthis.#buffer = ''\n\t\t\tthis.#offset = 0\n\t\t\tthis.#process(line, events)\n\t\t}\n\t\tthis.#dispatch(events)\n\t\treturn events\n\t}\n\n\treset(): void {\n\t\tthis.#buffer = ''\n\t\tthis.#offset = 0\n\t\tthis.#started = false\n\t\tthis.#carriage = false\n\t\tthis.#clear()\n\t\tthis.#lastId = undefined\n\t\tthis.#lastRetry = undefined\n\t}\n\n\t// Total characters currently buffered: the un-consumed line buffer (always\n\t// compacted to offset 0 between calls) plus the in-progress event's accumulated\n\t// field lengths (every `data:` segment + the pending `event` + the pending `id`).\n\t#size(): number {\n\t\tlet dataTotal = 0\n\t\tfor (const segment of this.#data) dataTotal += segment.length\n\t\treturn this.#buffer.length + dataTotal + (this.#event?.length ?? 0) + (this.#id?.length ?? 0)\n\t}\n\n\t// Take the next complete line off the buffer, or `undefined` when only a partial\n\t// line remains. A line ends at `\\n`, a `\\r`, or a `\\r\\n`. A `\\r` flushes its line\n\t// immediately (bare-`\\r` is a valid terminator) and arms {@link #carriage}; a `\\n`\n\t// directly following a consumed `\\r` is the CRLF's second half and is swallowed.\n\t#take(): string | undefined {\n\t\t// Swallow a `\\n` left over from a `\\r\\n` whose `\\r` already terminated a line -\n\t\t// only when a byte is present to inspect, so the flag survives an empty buffer\n\t\t// between calls (a `\\r` ends one chunk, its `\\n` opens the next).\n\t\tif (this.#carriage && this.#offset < this.#buffer.length) {\n\t\t\tif (this.#buffer[this.#offset] === '\\n') this.#offset += 1\n\t\t\tthis.#carriage = false\n\t\t}\n\t\tconst newline = this.#buffer.indexOf('\\n', this.#offset)\n\t\tconst carriage = this.#buffer.indexOf('\\r', this.#offset)\n\t\t// No terminator at all → the rest of the buffer is a partial line.\n\t\tif (newline === -1 && carriage === -1) return undefined\n\t\t// Pick the earliest terminator; a leading `\\r` flushes its line and arms the\n\t\t// carriage flag so the matching `\\n` (this chunk or the next) is swallowed.\n\t\tif (carriage !== -1 && (newline === -1 || carriage < newline)) {\n\t\t\tthis.#carriage = true\n\t\t\tconst line = this.#buffer.slice(this.#offset, carriage)\n\t\t\tthis.#offset = carriage + 1\n\t\t\treturn line\n\t\t}\n\t\tconst line = this.#buffer.slice(this.#offset, newline)\n\t\tthis.#offset = newline + 1\n\t\treturn line\n\t}\n\n\t// Process one complete line: a blank line dispatches the accumulated event; a\n\t// comment (a line starting with `:`) is ignored; otherwise it is a `field: value`.\n\t#process(line: string, events: SSEEvent[]): void {\n\t\tif (line.length === 0) {\n\t\t\tthis.#dispatch(events)\n\t\t\treturn\n\t\t}\n\t\tif (line.startsWith(':')) return // comment line - ignored\n\t\tconst colon = line.indexOf(':')\n\t\t// No colon → the whole line is the field name, value is empty (per spec).\n\t\tconst field = colon === -1 ? line : line.slice(0, colon)\n\t\t// One optional leading space after the colon is stripped; nothing else.\n\t\tlet value = colon === -1 ? '' : line.slice(colon + 1)\n\t\tif (value.startsWith(' ')) value = value.slice(1)\n\t\tthis.#field(field, value)\n\t}\n\n\t// Apply one parsed field to the in-progress event (and the persisted connection\n\t// state for `id` / `retry`). Unknown fields are ignored.\n\t#field(field: string, value: string): void {\n\t\tif (field === 'data') this.#data.push(value)\n\t\telse if (field === 'event') this.#event = value\n\t\telse if (field === 'id') {\n\t\t\t// An `id` containing a NUL is voided per spec - never surfaced, and the\n\t\t\t// persisted last-event-id is left unchanged.\n\t\t\tif (!value.includes(NUL)) {\n\t\t\t\tthis.#id = value\n\t\t\t\tthis.#lastId = value\n\t\t\t}\n\t\t} else if (field === 'retry') {\n\t\t\t// Integer-only; a non-integer reconnection time is ignored (never throws).\n\t\t\tif (/^\\d+$/.test(value)) {\n\t\t\t\tthis.#retry = Number(value)\n\t\t\t\tthis.#lastRetry = this.#retry\n\t\t\t}\n\t\t}\n\t}\n\n\t// Dispatch the accumulated event on a blank line (or on `flush()`): emit ONLY when\n\t// data was buffered (the spec's empty-data rule), then reset the accumulator for\n\t// the next event. Persisted `id` / `retry` state is untouched.\n\t#dispatch(events: SSEEvent[]): void {\n\t\tif (this.#data.length > 0) {\n\t\t\tconst event: SSEEvent = {\n\t\t\t\tdata: this.#data.join('\\n'),\n\t\t\t\t...(this.#event !== undefined ? { event: this.#event } : {}),\n\t\t\t\t...(this.#id !== undefined ? { id: this.#id } : {}),\n\t\t\t\t...(this.#retry !== undefined ? { retry: this.#retry } : {}),\n\t\t\t}\n\t\t\tevents.push(event)\n\t\t}\n\t\tthis.#clear()\n\t}\n\n\t// Reset the in-progress event accumulator (data buffer + last-seen fields).\n\t#clear(): void {\n\t\tthis.#data = []\n\t\tthis.#event = undefined\n\t\tthis.#id = undefined\n\t\tthis.#retry = undefined\n\t}\n}\n","import type { SSEParserInterface, SSEParserOptions } from './types.js'\nimport { SSEParser } from './SSEParser.js'\n\n/**\n * Create a Server-Sent-Events (SSE) stream parser - a stateful handle that turns\n * string chunks into the complete events dispatched so far.\n *\n * @param options - See {@link SSEParserOptions}.\n * @remarks\n * `options.limit` caps the total buffered characters (un-consumed line buffer plus\n * the in-progress event's field lengths); unset → unbounded, the default. Feed\n * chunks to `parse(chunk)` as they arrive; each blank line DISPATCHES an event whose\n * `data` is its `data:` fields joined by `\\n` (plus the last `event:` / `id:` /\n * `retry:`), and an in-progress event split across chunk boundaries is buffered until\n * its blank line arrives (or `flush()` forces it out at end-of-stream). The `id` /\n * `retry` getters expose the persisted last-event-id / reconnection time, which\n * survive dispatch and only clear on `reset()`. Generic and event-free - no\n * server / agent coupling; never throws on malformed input, only on a configured\n * `limit` being exceeded (an {@link import('./errors.js').SSEError} with code\n * `'OVERFLOW'`). Pair it with a `TextDecoder({ stream: true })` to also handle\n * multi-byte UTF-8 characters split across byte reads.\n *\n * @returns A working {@link SSEParserInterface}\n *\n * @example\n * ```ts\n * import { createSSEParser, isSSEError } from '@src/core'\n *\n * const parser = createSSEParser({ limit: 1_000_000 })\n * parser.parse('data: a\\ndata: b\\n\\n') // [{ data: 'a\\nb' }] - the two data lines joined\n * parser.parse('event: ping\\ndata: 1') // [] - buffered until its blank line\n * parser.parse('\\n\\n')                  // [{ data: '1', event: 'ping' }]\n * try {\n * \tparser.parse('x'.repeat(2_000_000))\n * } catch (error) {\n * \tif (isSSEError(error) && error.code === 'OVERFLOW') parser.reset()\n * }\n * ```\n */\nexport function createSSEParser(options?: SSEParserOptions): SSEParserInterface {\n\treturn new SSEParser(options)\n}\n"],"mappings":"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"}