typedrest 0.4.1 → 0.5.0

package/endpoints/reactive/PollingEndpoint.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PollingEndpoint = void 0;
+const ElementEndpoint_1 = require("../generic/ElementEndpoint");
+const Delay_1 = require("./Delay");
+const http_1 = require("../../http");
+/**
+ * Endpoint for a resource that can be polled for state changes.
+ * @typeParam TEntity The type of entity the endpoint represents.
+ */
+class PollingEndpoint extends ElementEndpoint_1.ElementEndpoint {
+    /**
+     * Creates a new polling endpoint.
+     * @param referrer The endpoint used to navigate to this one.
+     * @param relativeUri The URI of this endpoint relative to the `referrer`'s. Add a `./` prefix here to imply a trailing slash in the `referrer`'s URI.
+     * @param endCondition A check to determine whether the entity has reached its final state and no further polling is required.
+     */
+    constructor(referrer, relativeUri, endCondition) {
+        super(referrer, relativeUri);
+        this.endCondition = endCondition;
+        /**
+         * The interval in milliseconds to wait between polling requests.
+         * Automatically updated whenever the server sends a {@link http!HttpHeader.RetryAfter} header.
+         */
+        this.pollingInterval = 3000;
+    }
+    /**
+     * @inheritDoc
+     */
+    async handle(response) {
+        var _a;
+        await super.handle(response);
+        this.pollingInterval = (_a = (0, http_1.retryAfter)(response)) !== null && _a !== void 0 ? _a : this.pollingInterval;
+    }
+    /**
+     * Provides a stream of the `TEntity`'s states, polling the server for changes.
+     * States that are identical to the previously provided one are skipped.
+     * @param signal Used to stop polling.
+     * @throws {@link errors!AuthenticationError}: {@link http!HttpStatusCode.Unauthorized}
+     * @throws {@link errors!AuthorizationError}: {@link http!HttpStatusCode.Forbidden}
+     * @throws {@link errors!NotFoundError}: {@link http!HttpStatusCode.NotFound} or {@link http!HttpStatusCode.Gone}
+     * @throws {@link errors!HttpError}: Other non-success status code
+     */
+    async *stream(signal) {
+        var _a;
+        // NOTE: Compare the serialized form because every poll deserializes a new object instance.
+        let previous;
+        while (!(signal === null || signal === void 0 ? void 0 : signal.aborted)) {
+            const entity = await this.read(signal);
+            const serialized = this.serializer.serialize(entity);
+            if (serialized !== previous) {
+                previous = serialized;
+                yield entity;
+            }
+            if ((_a = this.endCondition) === null || _a === void 0 ? void 0 : _a.call(this, entity))
+                return;
+            if (!await (0, Delay_1.delay)(this.pollingInterval, signal))
+                return;
+        }
+    }
+    /**
+     * Provides a stream of the `TEntity`'s states using {@link stream}.
+     */
+    [Symbol.asyncIterator]() { return this.stream(); }
+}
+exports.PollingEndpoint = PollingEndpoint;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiUG9sbGluZ0VuZHBvaW50LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiUG9sbGluZ0VuZHBvaW50LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7OztBQUFBLGdFQUE2RDtBQUU3RCxtQ0FBZ0M7QUFDaEMscUNBQXdDO0FBRXhDOzs7R0FHRztBQUNILE1BQWEsZUFBeUIsU0FBUSxpQ0FBd0I7SUFDbEU7Ozs7O09BS0c7SUFDSCxZQUFZLFFBQWtCLEVBQUUsV0FBeUIsRUFBbUIsWUFBMkM7UUFDbkgsS0FBSyxDQUFDLFFBQVEsRUFBRSxXQUFXLENBQUMsQ0FBQztRQUQyQyxpQkFBWSxHQUFaLFlBQVksQ0FBK0I7UUFJdkg7OztXQUdHO1FBQ0gsb0JBQWUsR0FBRyxJQUFJLENBQUM7SUFOdkIsQ0FBQztJQVFEOztPQUVHO0lBQ08sS0FBSyxDQUFDLE1BQU0sQ0FBQyxRQUFrQjs7UUFDckMsTUFBTSxLQUFLLENBQUMsTUFBTSxDQUFDLFFBQVEsQ0FBQyxDQUFDO1FBQzdCLElBQUksQ0FBQyxlQUFlLEdBQUcsTUFBQSxJQUFBLGlCQUFVLEVBQUMsUUFBUSxDQUFDLG1DQUFJLElBQUksQ0FBQyxlQUFlLENBQUM7SUFDeEUsQ0FBQztJQUVEOzs7Ozs7OztPQVFHO0lBQ0gsS0FBSyxDQUFDLENBQUMsTUFBTSxDQUFDLE1BQW9COztRQUM5QiwyRkFBMkY7UUFDM0YsSUFBSSxRQUE0QixDQUFDO1FBRWpDLE9BQU8sQ0FBQyxDQUFBLE1BQU0sYUFBTixNQUFNLHVCQUFOLE1BQU0sQ0FBRSxPQUFPLENBQUEsRUFBRSxDQUFDO1lBQ3RCLE1BQU0sTUFBTSxHQUFHLE1BQU0sSUFBSSxDQUFDLElBQUksQ0FBQyxNQUFNLENBQUMsQ0FBQztZQUV2QyxNQUFNLFVBQVUsR0FBRyxJQUFJLENBQUMsVUFBVSxDQUFDLFNBQVMsQ0FBQyxNQUFNLENBQUMsQ0FBQztZQUNyRCxJQUFJLFVBQVUsS0FBSyxRQUFRLEVBQUUsQ0FBQztnQkFDMUIsUUFBUSxHQUFHLFVBQVUsQ0FBQztnQkFDdEIsTUFBTSxNQUFNLENBQUM7WUFDakIsQ0FBQztZQUVELElBQUksTUFBQSxJQUFJLENBQUMsWUFBWSxxREFBRyxNQUFNLENBQUM7Z0JBQUUsT0FBTztZQUN4QyxJQUFJLENBQUMsTUFBTSxJQUFBLGFBQUssRUFBQyxJQUFJLENBQUMsZUFBZSxFQUFFLE1BQU0sQ0FBQztnQkFBRSxPQUFPO1FBQzNELENBQUM7SUFDTCxDQUFDO0lBRUQ7O09BRUc7SUFDSCxDQUFDLE1BQU0sQ0FBQyxhQUFhLENBQUMsS0FBSyxPQUFPLElBQUksQ0FBQyxNQUFNLEVBQUUsQ0FBQyxDQUFDLENBQUM7Q0FDckQ7QUF4REQsMENBd0RDIn0=

package/endpoints/reactive/PollingEndpoint.test.ts

@@ -0,0 +1,84 @@
+import fetchMock from 'jest-fetch-mock';
+import { PollingEndpoint } from '.';
+import { EntryEndpoint } from '..';
+import { HttpHeader } from '../../http';
+
+class MockEntity {
+    constructor(public id: number, public name: string) { }
+}
+
+fetchMock.enableMocks();
+let endpoint: PollingEndpoint<MockEntity>;
+
+beforeEach(() => {
+    fetchMock.resetMocks();
+    endpoint = new PollingEndpoint<MockEntity>(new EntryEndpoint('http://localhost/'), 'endpoint', x => x.id === 3);
+    endpoint.pollingInterval = 0;
+});
+
+async function collect<T>(stream: AsyncIterable<T>) {
+    const result: T[] = [];
+    for await (const element of stream) result.push(element);
+    return result;
+}
+
+test('stream', async () => {
+    fetchMock.mockResponses(
+        '{"id":1,"name":"test"}',
+        '{"id":2,"name":"test"}',
+        ['{"id":3,"name":"test"}', { headers: { [HttpHeader.RetryAfter]: '42' } }]
+    );
+
+    expect(await collect(endpoint.stream())).toEqual([
+        new MockEntity(1, 'test'),
+        new MockEntity(2, 'test'),
+        new MockEntity(3, 'test')
+    ]);
+    expect(endpoint.pollingInterval).toBe(42000);
+});
+
+test('streamSkipsUnchanged', async () => {
+    fetchMock.mockResponses(
+        '{"id":1,"name":"test"}',
+        '{"id":1,"name":"test"}',
+        '{"id":2,"name":"test"}',
+        '{"id":3,"name":"test"}'
+    );
+
+    expect(await collect(endpoint.stream())).toEqual([
+        new MockEntity(1, 'test'),
+        new MockEntity(2, 'test'),
+        new MockEntity(3, 'test')
+    ]);
+});
+
+test('streamAsyncIterator', async () => {
+    fetchMock.mockResponses('{"id":3,"name":"test"}');
+
+    expect(await collect(endpoint)).toEqual([new MockEntity(3, 'test')]);
+});
+
+test('streamAbort', async () => {
+    fetchMock.mockResponse('{"id":1,"name":"test"}');
+    const controller = new AbortController();
+
+    const result: MockEntity[] = [];
+    for await (const element of endpoint.stream(controller.signal)) {
+        result.push(element);
+        controller.abort();
+    }
+
+    expect(result).toEqual([new MockEntity(1, 'test')]);
+});
+
+test('streamBreak', async () => {
+    fetchMock.mockResponse('{"id":1,"name":"test"}');
+
+    const result: MockEntity[] = [];
+    for await (const element of endpoint.stream()) {
+        result.push(element);
+        break;
+    }
+
+    expect(result).toEqual([new MockEntity(1, 'test')]);
+});

package/endpoints/reactive/PollingEndpoint.ts

@@ -0,0 +1,66 @@
+import { ElementEndpoint } from "../generic/ElementEndpoint";
+import { Endpoint } from "../Endpoint";
+import { delay } from "./Delay";
+import { retryAfter } from "../../http";
+
+/**
+ * Endpoint for a resource that can be polled for state changes.
+ * @typeParam TEntity The type of entity the endpoint represents.
+ */
+export class PollingEndpoint<TEntity> extends ElementEndpoint<TEntity> {
+    /**
+     * Creates a new polling endpoint.
+     * @param referrer The endpoint used to navigate to this one.
+     * @param relativeUri The URI of this endpoint relative to the `referrer`'s. Add a `./` prefix here to imply a trailing slash in the `referrer`'s URI.
+     * @param endCondition A check to determine whether the entity has reached its final state and no further polling is required.
+     */
+    constructor(referrer: Endpoint, relativeUri: URL | string, private readonly endCondition?: (entity: TEntity) => boolean) {
+        super(referrer, relativeUri);
+    }
+
+    /**
+     * The interval in milliseconds to wait between polling requests.
+     * Automatically updated whenever the server sends a {@link http!HttpHeader.RetryAfter} header.
+     */
+    pollingInterval = 3000;
+
+    /**
+     * @inheritDoc
+     */
+    protected async handle(response: Response) {
+        await super.handle(response);
+        this.pollingInterval = retryAfter(response) ?? this.pollingInterval;
+    }
+
+    /**
+     * Provides a stream of the `TEntity`'s states, polling the server for changes.
+     * States that are identical to the previously provided one are skipped.
+     * @param signal Used to stop polling.
+     * @throws {@link errors!AuthenticationError}: {@link http!HttpStatusCode.Unauthorized}
+     * @throws {@link errors!AuthorizationError}: {@link http!HttpStatusCode.Forbidden}
+     * @throws {@link errors!NotFoundError}: {@link http!HttpStatusCode.NotFound} or {@link http!HttpStatusCode.Gone}
+     * @throws {@link errors!HttpError}: Other non-success status code
+     */
+    async *stream(signal?: AbortSignal): AsyncIterableIterator<TEntity> {
+        // NOTE: Compare the serialized form because every poll deserializes a new object instance.
+        let previous: string | undefined;
+
+        while (!signal?.aborted) {
+            const entity = await this.read(signal);
+
+            const serialized = this.serializer.serialize(entity);
+            if (serialized !== previous) {
+                previous = serialized;
+                yield entity;
+            }
+
+            if (this.endCondition?.(entity)) return;
+            if (!await delay(this.pollingInterval, signal)) return;
+        }
+    }
+
+    /**
+     * Provides a stream of the `TEntity`'s states using {@link stream}.
+     */
+    [Symbol.asyncIterator]() { return this.stream(); }
+}

package/endpoints/reactive/SseStreamingEndpoint.js

@@ -0,0 +1,120 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SseStreamingEndpoint = void 0;
+const Endpoint_1 = require("../Endpoint");
+const Delay_1 = require("./Delay");
+const http_1 = require("../../http");
+const eventStreamMediaType = "text/event-stream";
+/**
+ * Endpoint for a stream of `TEntity`s using Server-Sent Events (SSE).<br>
+ * Sends `Accept: text/event-stream`. By default, transparently reconnects on connection drops or transient errors,
+ * honoring the server-supplied `retry:` interval and resuming via the {@link http!HttpHeader.LastEventId} header.
+ * @typeParam TEntity The type of individual elements in the stream.
+ */
+class SseStreamingEndpoint extends Endpoint_1.Endpoint {
+    /**
+     * Creates a new SSE streaming endpoint.
+     * @param referrer The endpoint used to navigate to this one.
+     * @param relativeUri The URI of this endpoint relative to the `referrer`'s. Add a `./` prefix here to imply a trailing slash in the `referrer`'s URI.
+     * @param eventType If set, only events with this `event:` type are provided; others are ignored. Leave unspecified to provide all events.
+     */
+    constructor(referrer, relativeUri, eventType) {
+        super(referrer, relativeUri);
+        this.eventType = eventType;
+        /**
+         * Whether to transparently reconnect on connection drops, transient transport errors and 5xx responses.
+         */
+        this.autoReconnect = true;
+        /**
+         * The reconnection interval in milliseconds used when the server has not (yet) supplied one via the SSE `retry:` field.
+         */
+        this.defaultReconnectionInterval = 3000;
+    }
+    /**
+     * Provides a stream of `TEntity`s, reconnecting as needed unless {@link autoReconnect} is disabled.
+     * @param signal Used to close the connection.
+     * @throws {@link errors!AuthenticationError}: {@link http!HttpStatusCode.Unauthorized}
+     * @throws {@link errors!AuthorizationError}: {@link http!HttpStatusCode.Forbidden}
+     * @throws {@link errors!NotFoundError}: {@link http!HttpStatusCode.NotFound} or {@link http!HttpStatusCode.Gone}
+     * @throws {@link errors!HttpError}: Other non-success status code
+     */
+    async *stream(signal) {
+        const state = { lastEventId: undefined, reconnectionInterval: this.defaultReconnectionInterval };
+        while (!(signal === null || signal === void 0 ? void 0 : signal.aborted)) {
+            let reconnect;
+            try {
+                reconnect = yield* this.consumeOnce(state, signal);
+            }
+            catch (err) {
+                // Aborting is a regular way of ending the stream, not an error
+                if (signal === null || signal === void 0 ? void 0 : signal.aborted)
+                    return;
+                // Transport-level failures are the ones worth retrying; anything else is the server telling us no
+                if (!this.autoReconnect || !SseStreamingEndpoint.isTransient(err))
+                    throw err;
+                reconnect = true;
+            }
+            if (!reconnect)
+                return;
+            if (!await (0, Delay_1.delay)(state.reconnectionInterval, signal))
+                return;
+        }
+    }
+    /**
+     * Provides a stream of `TEntity`s using {@link stream}.
+     */
+    [Symbol.asyncIterator]() { return this.stream(); }
+    /**
+     * Opens a connection and provides events until the stream ends.
+     * @param state Carries the last event id and the reconnection interval over to the next attempt.
+     * @param signal Used to close the connection.
+     * @returns `true` if another connection attempt should be made; `false` if the stream has ended for good.
+     */
+    async *consumeOnce(state, signal) {
+        var _a;
+        // NOTE: Abort the request when the consumer stops iterating, not just when the caller's signal fires.
+        const controller = new AbortController();
+        const onAbort = () => controller.abort();
+        signal === null || signal === void 0 ? void 0 : signal.addEventListener("abort", onAbort, { once: true });
+        if (signal === null || signal === void 0 ? void 0 : signal.aborted)
+            controller.abort();
+        try {
+            const headers = new Headers({ [http_1.HttpHeader.Accept]: eventStreamMediaType });
+            if (state.lastEventId)
+                headers.set(http_1.HttpHeader.LastEventId, state.lastEventId);
+            const response = await this.httpClient.send(this.uri, http_1.HttpMethod.Get, controller.signal, headers);
+            if (response.status === http_1.HttpStatusCode.NoContent)
+                return false;
+            if (this.autoReconnect && response.status >= 500)
+                return true;
+            await this.handle(response);
+            const reader = new http_1.SseReader(response);
+            try {
+                for await (const event of reader.events()) {
+                    if (this.eventType !== undefined && event.type !== this.eventType)
+                        continue;
+                    yield this.serializer.deserialize(event.data);
+                }
+            }
+            finally {
+                state.lastEventId = (_a = reader.lastEventId) !== null && _a !== void 0 ? _a : state.lastEventId;
+                if (reader.reconnectionInterval !== undefined)
+                    state.reconnectionInterval = reader.reconnectionInterval;
+            }
+            return this.autoReconnect;
+        }
+        finally {
+            signal === null || signal === void 0 ? void 0 : signal.removeEventListener("abort", onAbort);
+            controller.abort();
+        }
+    }
+    /**
+     * Determines whether an error is a transport-level failure that may succeed on a retry.
+     * The Fetch API reports these as `TypeError`s, while responses the server actually sent become {@link errors!HttpError}s.
+     */
+    static isTransient(err) {
+        return err instanceof TypeError;
+    }
+}
+exports.SseStreamingEndpoint = SseStreamingEndpoint;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiU3NlU3RyZWFtaW5nRW5kcG9pbnQuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyJTc2VTdHJlYW1pbmdFbmRwb2ludC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7QUFBQSwwQ0FBdUM7QUFDdkMsbUNBQWdDO0FBQ2hDLHFDQUErRTtBQUUvRSxNQUFNLG9CQUFvQixHQUFHLG1CQUFtQixDQUFDO0FBRWpEOzs7OztHQUtHO0FBQ0gsTUFBYSxvQkFBOEIsU0FBUSxtQkFBUTtJQUN2RDs7Ozs7T0FLRztJQUNILFlBQVksUUFBa0IsRUFBRSxXQUF5QixFQUFtQixTQUFrQjtRQUMxRixLQUFLLENBQUMsUUFBUSxFQUFFLFdBQVcsQ0FBQyxDQUFDO1FBRDJDLGNBQVMsR0FBVCxTQUFTLENBQVM7UUFJOUY7O1dBRUc7UUFDSCxrQkFBYSxHQUFHLElBQUksQ0FBQztRQUVyQjs7V0FFRztRQUNILGdDQUEyQixHQUFHLElBQUksQ0FBQztJQVZuQyxDQUFDO0lBWUQ7Ozs7Ozs7T0FPRztJQUNILEtBQUssQ0FBQyxDQUFDLE1BQU0sQ0FBQyxNQUFvQjtRQUM5QixNQUFNLEtBQUssR0FBRyxFQUFFLFdBQVcsRUFBRSxTQUErQixFQUFFLG9CQUFvQixFQUFFLElBQUksQ0FBQywyQkFBMkIsRUFBRSxDQUFDO1FBRXZILE9BQU8sQ0FBQyxDQUFBLE1BQU0sYUFBTixNQUFNLHVCQUFOLE1BQU0sQ0FBRSxPQUFPLENBQUEsRUFBRSxDQUFDO1lBQ3RCLElBQUksU0FBa0IsQ0FBQztZQUN2QixJQUFJLENBQUM7Z0JBQ0QsU0FBUyxHQUFHLEtBQUssQ0FBQyxDQUFDLElBQUksQ0FBQyxXQUFXLENBQUMsS0FBSyxFQUFFLE1BQU0sQ0FBQyxDQUFDO1lBQ3ZELENBQUM7WUFBQyxPQUFPLEdBQUcsRUFBRSxDQUFDO2dCQUNYLCtEQUErRDtnQkFDL0QsSUFBSSxNQUFNLGFBQU4sTUFBTSx1QkFBTixNQUFNLENBQUUsT0FBTztvQkFBRSxPQUFPO2dCQUU1QixrR0FBa0c7Z0JB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

package/endpoints/reactive/SseStreamingEndpoint.test.ts

@@ -0,0 +1,169 @@
+/**
+ * NOTE: The jsdom environment does not expose response bodies as streams, so these tests need the node environment.
+ * @jest-environment node
+ */
+
+import fetchMock from 'jest-fetch-mock';
+import { SseStreamingEndpoint } from '.';
+import { EntryEndpoint } from '..';
+import { ConflictError } from '../../errors';
+import { HttpHeader, HttpStatusCode } from '../../http';
+
+class MockEntity {
+    constructor(public id: number, public name: string) { }
+}
+
+fetchMock.enableMocks();
+let entryEndpoint: EntryEndpoint;
+let endpoint: SseStreamingEndpoint<MockEntity>;
+
+beforeEach(() => {
+    fetchMock.resetMocks();
+    entryEndpoint = new EntryEndpoint('http://localhost/');
+    endpoint = new SseStreamingEndpoint<MockEntity>(entryEndpoint, 'endpoint');
+    endpoint.autoReconnect = false;
+});
+
+function sseEvent(data: string, type?: string, id?: string) {
+    return (type ? `event: ${type}\n` : '')
+        + (id ? `id: ${id}\n` : '')
+        + `data: ${data}\n\n`;
+}
+
+/**
+ * Mocks a response that ends the stream for good.<br>
+ * NOTE: Needs a `null` body because a 204 response must not have one.
+ */
+function mockNoContentOnce() {
+    fetchMock.mockImplementationOnce(async () => new Response(null, { status: HttpStatusCode.NoContent }));
+}
+
+function requestHeader(index: number, header: HttpHeader) {
+    return new Headers(fetchMock.mock.calls[index][1]?.headers).get(header);
+}
+
+async function collect<T>(stream: AsyncIterable<T>) {
+    const result: T[] = [];
+    for await (const element of stream) result.push(element);
+    return result;
+}
+
+test('stream', async () => {
+    fetchMock.mockResponseOnce(
+        sseEvent('{"id":5,"name":"test1"}')
+        + sseEvent('{"id":6,"name":"test2"}')
+        + sseEvent('{"id":7,"name":"test3"}'));
+
+    expect(await collect(endpoint.stream())).toEqual([
+        new MockEntity(5, 'test1'),
+        new MockEntity(6, 'test2'),
+        new MockEntity(7, 'test3')
+    ]);
+    expect(requestHeader(0, HttpHeader.Accept)).toBe('text/event-stream');
+});
+
+test('streamAsyncIterator', async () => {
+    fetchMock.mockResponseOnce(sseEvent('{"id":5,"name":"test1"}'));
+
+    expect(await collect(endpoint)).toEqual([new MockEntity(5, 'test1')]);
+});
+
+test('streamEventTypeFilter', async () => {
+    endpoint = new SseStreamingEndpoint<MockEntity>(entryEndpoint, 'endpoint', 'update');
+    endpoint.autoReconnect = false;
+
+    fetchMock.mockResponseOnce(
+        sseEvent('{"id":1,"name":"skip"}', 'ignored')
+        + sseEvent('{"id":5,"name":"test1"}', 'update')
+        + sseEvent('{"id":99,"name":"default"}')
+        + sseEvent('{"id":6,"name":"test2"}', 'update'));
+
+    expect(await collect(endpoint.stream())).toEqual([
+        new MockEntity(5, 'test1'),
+        new MockEntity(6, 'test2')
+    ]);
+});
+
+test('streamComments', async () => {
+    fetchMock.mockResponseOnce(': keep-alive\n\n' + sseEvent('{"id":5,"name":"test1"}'));
+
+    expect(await collect(endpoint.stream())).toEqual([new MockEntity(5, 'test1')]);
+});
+
+test('streamMultiLineData', async () => {
+    fetchMock.mockResponseOnce('data: {"id":5,\ndata: "name":"test1"}\n\n');
+
+    expect(await collect(endpoint.stream())).toEqual([new MockEntity(5, 'test1')]);
+});
+
+test('streamCarriageReturns', async () => {
+    fetchMock.mockResponseOnce('data: {"id":5,"name":"test1"}\r\n\r\ndata: {"id":6,"name":"test2"}\r\r');
+
+    expect(await collect(endpoint.stream())).toEqual([
+        new MockEntity(5, 'test1'),
+        new MockEntity(6, 'test2')
+    ]);
+});
+
+test('streamError', async () => {
+    fetchMock.mockResponseOnce('{"message":"my message"}', {
+        status: HttpStatusCode.Conflict,
+        headers: { [HttpHeader.ContentType]: 'application/json' }
+    });
+
+    await expect(collect(endpoint.stream())).rejects.toThrow(new ConflictError('my message', HttpStatusCode.Conflict));
+});
+
+test('streamNoContentCompletes', async () => {
+    endpoint.autoReconnect = true;
+    mockNoContentOnce();
+
+    expect(await collect(endpoint.stream())).toEqual([]);
+});
+
+test('streamReconnectsWithLastEventId', async () => {
+    endpoint.autoReconnect = true;
+    endpoint.defaultReconnectionInterval = 0;
+    fetchMock.mockResponseOnce(sseEvent('{"id":5,"name":"test1"}', undefined, '42'));
+    mockNoContentOnce();
+
+    expect(await collect(endpoint.stream())).toEqual([new MockEntity(5, 'test1')]);
+    expect(requestHeader(0, HttpHeader.LastEventId)).toBeNull();
+    expect(requestHeader(1, HttpHeader.LastEventId)).toBe('42');
+});
+
+test('streamReconnectsOnServerError', async () => {
+    endpoint.autoReconnect = true;
+    endpoint.defaultReconnectionInterval = 0;
+    fetchMock.mockResponseOnce('', { status: 503 });
+    fetchMock.mockResponseOnce(sseEvent('{"id":5,"name":"test1"}'));
+    mockNoContentOnce();
+
+    expect(await collect(endpoint.stream())).toEqual([new MockEntity(5, 'test1')]);
+});
+
+test('streamHonorsRetryField', async () => {
+    endpoint.autoReconnect = true;
+    endpoint.defaultReconnectionInterval = 0;
+    fetchMock.mockResponseOnce('retry: 42\n\n' + sseEvent('{"id":5,"name":"test1"}'));
+    mockNoContentOnce();
+
+    const start = Date.now();
+    expect(await collect(endpoint.stream())).toEqual([new MockEntity(5, 'test1')]);
+    expect(Date.now() - start).toBeGreaterThanOrEqual(42);
+});
+
+test('streamAbort', async () => {
+    endpoint.autoReconnect = true;
+    endpoint.defaultReconnectionInterval = 0;
+    fetchMock.mockResponse(sseEvent('{"id":5,"name":"test1"}'));
+    const controller = new AbortController();
+
+    const result: MockEntity[] = [];
+    for await (const element of endpoint.stream(controller.signal)) {
+        result.push(element);
+        controller.abort();
+    }
+
+    expect(result).toEqual([new MockEntity(5, 'test1')]);
+});

package/endpoints/reactive/SseStreamingEndpoint.ts

@@ -0,0 +1,115 @@
+import { Endpoint } from "../Endpoint";
+import { delay } from "./Delay";
+import { HttpMethod, HttpHeader, HttpStatusCode, SseReader } from "../../http";
+
+const eventStreamMediaType = "text/event-stream";
+
+/**
+ * Endpoint for a stream of `TEntity`s using Server-Sent Events (SSE).<br>
+ * Sends `Accept: text/event-stream`. By default, transparently reconnects on connection drops or transient errors,
+ * honoring the server-supplied `retry:` interval and resuming via the {@link http!HttpHeader.LastEventId} header.
+ * @typeParam TEntity The type of individual elements in the stream.
+ */
+export class SseStreamingEndpoint<TEntity> extends Endpoint {
+    /**
+     * Creates a new SSE streaming endpoint.
+     * @param referrer The endpoint used to navigate to this one.
+     * @param relativeUri The URI of this endpoint relative to the `referrer`'s. Add a `./` prefix here to imply a trailing slash in the `referrer`'s URI.
+     * @param eventType If set, only events with this `event:` type are provided; others are ignored. Leave unspecified to provide all events.
+     */
+    constructor(referrer: Endpoint, relativeUri: URL | string, private readonly eventType?: string) {
+        super(referrer, relativeUri);
+    }
+
+    /**
+     * Whether to transparently reconnect on connection drops, transient transport errors and 5xx responses.
+     */
+    autoReconnect = true;
+
+    /**
+     * The reconnection interval in milliseconds used when the server has not (yet) supplied one via the SSE `retry:` field.
+     */
+    defaultReconnectionInterval = 3000;
+
+    /**
+     * Provides a stream of `TEntity`s, reconnecting as needed unless {@link autoReconnect} is disabled.
+     * @param signal Used to close the connection.
+     * @throws {@link errors!AuthenticationError}: {@link http!HttpStatusCode.Unauthorized}
+     * @throws {@link errors!AuthorizationError}: {@link http!HttpStatusCode.Forbidden}
+     * @throws {@link errors!NotFoundError}: {@link http!HttpStatusCode.NotFound} or {@link http!HttpStatusCode.Gone}
+     * @throws {@link errors!HttpError}: Other non-success status code
+     */
+    async *stream(signal?: AbortSignal): AsyncIterableIterator<TEntity> {
+        const state = { lastEventId: undefined as string | undefined, reconnectionInterval: this.defaultReconnectionInterval };
+
+        while (!signal?.aborted) {
+            let reconnect: boolean;
+            try {
+                reconnect = yield* this.consumeOnce(state, signal);
+            } catch (err) {
+                // Aborting is a regular way of ending the stream, not an error
+                if (signal?.aborted) return;
+
+                // Transport-level failures are the ones worth retrying; anything else is the server telling us no
+                if (!this.autoReconnect || !SseStreamingEndpoint.isTransient(err)) throw err;
+                reconnect = true;
+            }
+
+            if (!reconnect) return;
+            if (!await delay(state.reconnectionInterval, signal)) return;
+        }
+    }
+
+    /**
+     * Provides a stream of `TEntity`s using {@link stream}.
+     */
+    [Symbol.asyncIterator]() { return this.stream(); }
+
+    /**
+     * Opens a connection and provides events until the stream ends.
+     * @param state Carries the last event id and the reconnection interval over to the next attempt.
+     * @param signal Used to close the connection.
+     * @returns `true` if another connection attempt should be made; `false` if the stream has ended for good.
+     */
+    private async *consumeOnce(state: { lastEventId?: string; reconnectionInterval: number; }, signal?: AbortSignal): AsyncGenerator<TEntity, boolean> {
+        // NOTE: Abort the request when the consumer stops iterating, not just when the caller's signal fires.
+        const controller = new AbortController();
+        const onAbort = () => controller.abort();
+        signal?.addEventListener("abort", onAbort, { once: true });
+        if (signal?.aborted) controller.abort();
+
+        try {
+            const headers = new Headers({ [HttpHeader.Accept]: eventStreamMediaType });
+            if (state.lastEventId) headers.set(HttpHeader.LastEventId, state.lastEventId);
+
+            const response = await this.httpClient.send(this.uri, HttpMethod.Get, controller.signal, headers);
+            if (response.status === HttpStatusCode.NoContent) return false;
+            if (this.autoReconnect && response.status >= 500) return true;
+            await this.handle(response);
+
+            const reader = new SseReader(response);
+            try {
+                for await (const event of reader.events()) {
+                    if (this.eventType !== undefined && event.type !== this.eventType) continue;
+                    yield this.serializer.deserialize<TEntity>(event.data);
+                }
+            } finally {
+                state.lastEventId = reader.lastEventId ?? state.lastEventId;
+                if (reader.reconnectionInterval !== undefined) state.reconnectionInterval = reader.reconnectionInterval;
+            }
+
+            return this.autoReconnect;
+        } finally {
+            signal?.removeEventListener("abort", onAbort);
+            controller.abort();
+        }
+    }
+
+    /**
+     * Determines whether an error is a transport-level failure that may succeed on a retry.
+     * The Fetch API reports these as `TypeError`s, while responses the server actually sent become {@link errors!HttpError}s.
+     */
+    private static isTransient(err: unknown) {
+        return err instanceof TypeError;
+    }
+}

package/endpoints/reactive/StreamingCollectionEndpoint.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StreamingCollectionEndpoint = void 0;
+const GenericStreamingCollectionEndpoint_1 = require("./GenericStreamingCollectionEndpoint");
+const ElementEndpoint_1 = require("../generic/ElementEndpoint");
+/**
+ * Endpoint for a collection of `TEntity`s observable as an append-only stream using long-polling,
+ * addressable as {@link ElementEndpoint}s.<br>
+ * Use {@link GenericStreamingCollectionEndpoint} instead if you wish to customize the element endpoint type.
+ * @typeParam TEntity The type of individual elements in the collection.
+ */
+class StreamingCollectionEndpoint extends GenericStreamingCollectionEndpoint_1.GenericStreamingCollectionEndpoint {
+    /**
+     * Creates a new streaming collection endpoint.
+     * @param referrer The endpoint used to navigate to this one.
+     * @param relativeUri The URI of this endpoint relative to the `referrer`'s. Add a `./` prefix here to imply a trailing slash in the `referrer`'s URI.
+     */
+    constructor(referrer, relativeUri) {
+        super(referrer, relativeUri, ElementEndpoint_1.ElementEndpoint);
+    }
+}
+exports.StreamingCollectionEndpoint = StreamingCollectionEndpoint;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiU3RyZWFtaW5nQ29sbGVjdGlvbkVuZHBvaW50LmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiU3RyZWFtaW5nQ29sbGVjdGlvbkVuZHBvaW50LnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiI7OztBQUFBLDZGQUEwRjtBQUMxRixnRUFBNkQ7QUFHN0Q7Ozs7O0dBS0c7QUFDSCxNQUFhLDJCQUFxQyxTQUFRLHVFQUFxRTtJQUMzSDs7OztPQUlHO0lBQ0gsWUFBWSxRQUFrQixFQUFFLFdBQXlCO1FBQ3JELEtBQUssQ0FBQyxRQUFRLEVBQUUsV0FBVyxFQUFFLGlDQUFlLENBQUMsQ0FBQztJQUNsRCxDQUFDO0NBQ0o7QUFURCxrRUFTQyJ9