typedrest 0.4.0 → 0.5.0

package/endpoints/reactive/Delay.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.delay = delay;
+/**
+ * Waits for a specific amount of time.
+ * @param ms The time to wait in milliseconds.
+ * @param signal Used to cancel the wait.
+ * @returns `true` if the time has elapsed; `false` if the wait was cancelled via the `signal`.
+ */
+function delay(ms, signal) {
+    return new Promise(resolve => {
+        if (signal === null || signal === void 0 ? void 0 : signal.aborted) {
+            resolve(false);
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timeout);
+            resolve(false);
+        };
+        const timeout = setTimeout(() => {
+            signal === null || signal === void 0 ? void 0 : signal.removeEventListener("abort", onAbort);
+            resolve(true);
+        }, ms);
+        signal === null || signal === void 0 ? void 0 : signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiRGVsYXkuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyJEZWxheS50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOztBQU1BLHNCQW1CQztBQXpCRDs7Ozs7R0FLRztBQUNILFNBQWdCLEtBQUssQ0FBQyxFQUFVLEVBQUUsTUFBb0I7SUFDbEQsT0FBTyxJQUFJLE9BQU8sQ0FBQyxPQUFPLENBQUMsRUFBRTtRQUN6QixJQUFJLE1BQU0sYUFBTixNQUFNLHVCQUFOLE1BQU0sQ0FBRSxPQUFPLEVBQUUsQ0FBQztZQUNsQixPQUFPLENBQUMsS0FBSyxDQUFDLENBQUM7WUFDZixPQUFPO1FBQ1gsQ0FBQztRQUVELE1BQU0sT0FBTyxHQUFHLEdBQUcsRUFBRTtZQUNqQixZQUFZLENBQUMsT0FBTyxDQUFDLENBQUM7WUFDdEIsT0FBTyxDQUFDLEtBQUssQ0FBQyxDQUFDO1FBQ25CLENBQUMsQ0FBQztRQUVGLE1BQU0sT0FBTyxHQUFHLFVBQVUsQ0FBQyxHQUFHLEVBQUU7WUFDNUIsTUFBTSxhQUFOLE1BQU0sdUJBQU4sTUFBTSxDQUFFLG1CQUFtQixDQUFDLE9BQU8sRUFBRSxPQUFPLENBQUMsQ0FBQztZQUM5QyxPQUFPLENBQUMsSUFBSSxDQUFDLENBQUM7UUFDbEIsQ0FBQyxFQUFFLEVBQUUsQ0FBQyxDQUFDO1FBRVAsTUFBTSxhQUFOLE1BQU0sdUJBQU4sTUFBTSxDQUFFLGdCQUFnQixDQUFDLE9BQU8sRUFBRSxPQUFPLEVBQUUsRUFBRSxJQUFJLEVBQUUsSUFBSSxFQUFFLENBQUMsQ0FBQztJQUMvRCxDQUFDLENBQUMsQ0FBQztBQUNQLENBQUMifQ==

package/endpoints/reactive/Delay.ts

@@ -0,0 +1,26 @@
+/**
+ * Waits for a specific amount of time.
+ * @param ms The time to wait in milliseconds.
+ * @param signal Used to cancel the wait.
+ * @returns `true` if the time has elapsed; `false` if the wait was cancelled via the `signal`.
+ */
+export function delay(ms: number, signal?: AbortSignal): Promise<boolean> {
+    return new Promise(resolve => {
+        if (signal?.aborted) {
+            resolve(false);
+            return;
+        }
+
+        const onAbort = () => {
+            clearTimeout(timeout);
+            resolve(false);
+        };
+
+        const timeout = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve(true);
+        }, ms);
+
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}

package/endpoints/reactive/GenericStreamingCollectionEndpoint.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GenericStreamingCollectionEndpoint = void 0;
+const GenericCollectionEndpoint_1 = require("../generic/GenericCollectionEndpoint");
+const Delay_1 = require("./Delay");
+const http_1 = require("../../http");
+const errors_1 = require("../../errors");
+/**
+ * Endpoint for a collection of `TEntity`s observable as an append-only stream using long-polling.<br>
+ * Use {@link StreamingCollectionEndpoint} instead if you wish to use the default {@link ElementEndpoint} type.
+ * @typeParam TEntity The type of individual elements in the collection.
+ * @typeParam TElementEndpoint The type of {@link ElementEndpoint} to provide for individual `TEntity`s.
+ */
+class GenericStreamingCollectionEndpoint extends GenericCollectionEndpoint_1.GenericCollectionEndpoint {
+    constructor() {
+        super(...arguments);
+        /**
+         * 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 `TEntity`s, polling the server for elements appended to the collection.
+     * @param startIndex The index of the first element to return. Use a negative value to start with the last `-startIndex` elements ("tail").
+     * @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!HttpError}: Other non-success status code
+     */
+    async *stream(startIndex = 0, signal) {
+        var _a;
+        let currentStartIndex = startIndex;
+        while (!(signal === null || signal === void 0 ? void 0 : signal.aborted)) {
+            let response;
+            try {
+                response = (currentStartIndex >= 0)
+                    // Offset
+                    ? await this.readRange(currentStartIndex, undefined, signal)
+                    // Tail
+                    : await this.readRange(undefined, -currentStartIndex, 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;
+                if (!(err instanceof errors_1.RangeNotSatisfiableError))
+                    throw err;
+                // No new data available yet, keep polling
+                if (!await (0, Delay_1.delay)(this.pollingInterval, signal))
+                    return;
+                continue;
+            }
+            yield* response.elements;
+            if (response.endReached)
+                return;
+            // Continue polling for more data
+            if (((_a = response.range) === null || _a === void 0 ? void 0 : _a.to) === undefined)
+                return;
+            currentStartIndex = response.range.to + 1;
+            if (!await (0, Delay_1.delay)(this.pollingInterval, signal))
+                return;
+        }
+    }
+    /**
+     * Provides a stream of `TEntity`s using {@link stream}.
+     */
+    [Symbol.asyncIterator]() { return this.stream(); }
+}
+exports.GenericStreamingCollectionEndpoint = GenericStreamingCollectionEndpoint;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiR2VuZXJpY1N0cmVhbWluZ0NvbGxlY3Rpb25FbmRwb2ludC5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIkdlbmVyaWNTdHJlYW1pbmdDb2xsZWN0aW9uRW5kcG9pbnQudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6Ijs7O0FBQ0Esb0ZBQWlGO0FBRWpGLG1DQUFnQztBQUNoQyxxQ0FBd0M7QUFDeEMseUNBQXdEO0FBRXhEOzs7OztHQUtHO0FBQ0gsTUFBYSxrQ0FBK0YsU0FBUSxxREFBb0Q7SUFBeEs7O1FBQ0k7OztXQUdHO1FBQ0gsb0JBQWUsR0FBRyxJQUFJLENBQUM7SUFzRDNCLENBQUM7SUFwREc7O09BRUc7SUFDTyxLQUFLLENBQUMsTUFBTSxDQUFDLFFBQWtCOztRQUNyQyxNQUFNLEtBQUssQ0FBQyxNQUFNLENBQUMsUUFBUSxDQUFDLENBQUM7UUFDN0IsSUFBSSxDQUFDLGVBQWUsR0FBRyxNQUFBLElBQUEsaUJBQVUsRUFBQyxRQUFRLENBQUMsbUNBQUksSUFBSSxDQUFDLGVBQWUsQ0FBQztJQUN4RSxDQUFDO0lBRUQ7Ozs7Ozs7T0FPRztJQUNILEtBQUssQ0FBQyxDQUFDLE1BQU0sQ0FBQyxhQUFxQixDQUFDLEVBQUUsTUFBb0I7O1FBQ3RELElBQUksaUJBQWlCLEdBQUcsVUFBVSxDQUFDO1FBRW5DLE9BQU8sQ0FBQyxDQUFBLE1BQU0sYUFBTixNQUFNLHVCQUFOLE1BQU0sQ0FBRSxPQUFPLENBQUEsRUFBRSxDQUFDO1lBQ3RCLElBQUksUUFBa0MsQ0FBQztZQUN2QyxJQUFJLENBQUM7Z0JBQ0QsUUFBUSxHQUFHLENBQUMsaUJBQWlCLElBQUksQ0FBQyxDQUFDO29CQUMvQixTQUFTO29CQUNULENBQUMsQ0FBQyxNQUFNLElBQUksQ0FBQyxTQUFTLENBQUMsaUJBQWlCLEVBQUUsU0FBUyxFQUFFLE1BQU0sQ0FBQztvQkFDNUQsT0FBTztvQkFDUCxDQUFDLENBQUMsTUFBTSxJQUFJLENBQUMsU0FBUyxDQUFDLFNBQVMsRUFBRSxDQUFDLGlCQUFpQixFQUFFLE1BQU0sQ0FBQyxDQUFDO1lBQ3RFLENBQUM7WUFBQyxPQUFPLEdBQUcsRUFBRSxDQUFDO2dCQUNYLCtEQUErRDtnQkFDL0QsSUFBSSxNQUFNLGFBQU4sTUFBTSx1QkFBTixNQUFNLENBQUUsT0FBTztvQkFBRSxPQUFPO2dCQUM1QixJQUFJLENBQUMsQ0FBQyxHQUFHLFlBQVksaUNBQXdCLENBQUM7b0JBQUUsTUFBTSxHQUFHLENBQUM7Z0JBRTFELDBDQUEwQztnQkFDMUMsSUFBSSxDQUFDLE1BQU0sSUFBQSxhQUFLLEVBQUMsSUFBSSxDQUFDLGVBQWUsRUFBRSxNQUFNLENBQUM7b0JBQUUsT0FBTztnQkFDdkQsU0FBUztZQUNiLENBQUM7WUFFRCxLQUFLLENBQUMsQ0FBQyxRQUFRLENBQUMsUUFBUSxDQUFDO1lBQ3pCLElBQUksUUFBUSxDQUFDLFVBQVU7Z0JBQUUsT0FBTztZQUVoQyxpQ0FBaUM7WUFDakMsSUFBSSxDQUFBLE1BQUEsUUFBUSxDQUFDLEtBQUssMENBQUUsRUFBRSxNQUFLLFNBQVM7Z0JBQUUsT0FBTztZQUM3QyxpQkFBaUIsR0FBRyxRQUFRLENBQUMsS0FBSyxDQUFDLEVBQUUsR0FBRyxDQUFDLENBQUM7WUFFMUMsSUFBSSxDQUFDLE1BQU0sSUFBQSxhQUFLLEVBQUMsSUFBSSxDQUFDLGVBQWUsRUFBRSxNQUFNLENBQUM7Z0JBQUUsT0FBTztRQUMzRCxDQUFDO0lBQ0wsQ0FBQztJQUVEOztPQUVHO0lBQ0gsQ0FBQyxNQUFNLENBQUMsYUFBYSxDQUFDLEtBQUssT0FBTyxJQUFJLENBQUMsTUFBTSxFQUFFLENBQUMsQ0FBQyxDQUFDO0NBQ3JEO0FBM0RELGdGQTJEQyJ9

package/endpoints/reactive/GenericStreamingCollectionEndpoint.ts

@@ -0,0 +1,73 @@
+import { ElementEndpoint } from "../generic/ElementEndpoint";
+import { GenericCollectionEndpoint } from "../generic/GenericCollectionEndpoint";
+import { PartialResponse } from "../generic/PartialResponse";
+import { delay } from "./Delay";
+import { retryAfter } from "../../http";
+import { RangeNotSatisfiableError } from "../../errors";
+
+/**
+ * Endpoint for a collection of `TEntity`s observable as an append-only stream using long-polling.<br>
+ * Use {@link StreamingCollectionEndpoint} instead if you wish to use the default {@link ElementEndpoint} type.
+ * @typeParam TEntity The type of individual elements in the collection.
+ * @typeParam TElementEndpoint The type of {@link ElementEndpoint} to provide for individual `TEntity`s.
+ */
+export class GenericStreamingCollectionEndpoint<TEntity, TElementEndpoint extends ElementEndpoint<TEntity>> extends GenericCollectionEndpoint<TEntity, TElementEndpoint> {
+    /**
+     * 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 `TEntity`s, polling the server for elements appended to the collection.
+     * @param startIndex The index of the first element to return. Use a negative value to start with the last `-startIndex` elements ("tail").
+     * @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!HttpError}: Other non-success status code
+     */
+    async *stream(startIndex: number = 0, signal?: AbortSignal): AsyncIterableIterator<TEntity> {
+        let currentStartIndex = startIndex;
+
+        while (!signal?.aborted) {
+            let response: PartialResponse<TEntity>;
+            try {
+                response = (currentStartIndex >= 0)
+                    // Offset
+                    ? await this.readRange(currentStartIndex, undefined, signal)
+                    // Tail
+                    : await this.readRange(undefined, -currentStartIndex, signal);
+            } catch (err) {
+                // Aborting is a regular way of ending the stream, not an error
+                if (signal?.aborted) return;
+                if (!(err instanceof RangeNotSatisfiableError)) throw err;
+
+                // No new data available yet, keep polling
+                if (!await delay(this.pollingInterval, signal)) return;
+                continue;
+            }
+
+            yield* response.elements;
+            if (response.endReached) return;
+
+            // Continue polling for more data
+            if (response.range?.to === undefined) return;
+            currentStartIndex = response.range.to + 1;
+
+            if (!await delay(this.pollingInterval, signal)) return;
+        }
+    }
+
+    /**
+     * Provides a stream of `TEntity`s using {@link stream}.
+     */
+    [Symbol.asyncIterator]() { return this.stream(); }
+}

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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