typedrest 0.4.0 → 0.5.0

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

package/endpoints/reactive/StreamingCollectionEndpoint.test.ts

@@ -0,0 +1,110 @@
+/**
+ * NOTE: The jsdom environment strips the "Range" request header, so these tests need the node environment.
+ * @jest-environment node
+ */
+
+import fetchMock from 'jest-fetch-mock';
+import { StreamingCollectionEndpoint } from '.';
+import { EntryEndpoint } from '..';
+import { HttpHeader, HttpStatusCode } from '../../http';
+
+class MockEntity {
+    constructor(public id: number, public name: string) { }
+}
+
+fetchMock.enableMocks();
+let endpoint: StreamingCollectionEndpoint<MockEntity>;
+
+beforeEach(() => {
+    fetchMock.resetMocks();
+    endpoint = new StreamingCollectionEndpoint<MockEntity>(new EntryEndpoint('http://localhost/'), 'endpoint');
+    endpoint.pollingInterval = 0;
+});
+
+function mockRangeOnce(body: string, contentRange?: string, retryAfterHeader?: string) {
+    const headers: { [key: string]: string; } = {};
+    if (contentRange) headers[HttpHeader.ContentRange] = contentRange;
+    if (retryAfterHeader) headers[HttpHeader.RetryAfter] = retryAfterHeader;
+
+    fetchMock.mockResponseOnce(body, { status: HttpStatusCode.PartialContent, headers });
+}
+
+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 () => {
+    mockRangeOnce('[{"id":5,"name":"test1"},{"id":6,"name":"test2"}]', 'elements 0-1/*');
+    mockRangeOnce('[{"id":7,"name":"test3"}]', 'elements 2-2/3', '42');
+
+    expect(await collect(endpoint.stream())).toEqual([
+        new MockEntity(5, 'test1'),
+        new MockEntity(6, 'test2'),
+        new MockEntity(7, 'test3')
+    ]);
+    expect(requestHeader(0, HttpHeader.Range)).toBe('elements=0-');
+    expect(requestHeader(1, HttpHeader.Range)).toBe('elements=2-');
+    expect(endpoint.pollingInterval).toBe(42000);
+});
+
+test('streamOffset', async () => {
+    mockRangeOnce('[{"id":7,"name":"test3"}]', 'elements 2-2/3');
+
+    expect(await collect(endpoint.stream(2))).toEqual([new MockEntity(7, 'test3')]);
+    expect(requestHeader(0, HttpHeader.Range)).toBe('elements=2-');
+});
+
+test('streamTail', async () => {
+    mockRangeOnce('[{"id":7,"name":"test3"}]', 'elements 2-2/3');
+
+    expect(await collect(endpoint.stream(-1))).toEqual([new MockEntity(7, 'test3')]);
+    expect(requestHeader(0, HttpHeader.Range)).toBe('elements=-1');
+});
+
+test('streamAsyncIterator', async () => {
+    mockRangeOnce('[{"id":5,"name":"test1"}]', 'elements 0-0/1');
+
+    expect(await collect(endpoint)).toEqual([new MockEntity(5, 'test1')]);
+});
+
+test('streamKeepsPollingWhileRangeNotSatisfiable', async () => {
+    mockRangeOnce('[{"id":5,"name":"test1"}]', 'elements 0-0/*');
+    fetchMock.mockResponseOnce('', { status: HttpStatusCode.RangeNotSatisfiable });
+    mockRangeOnce('[{"id":6,"name":"test2"}]', 'elements 1-1/2');
+
+    expect(await collect(endpoint.stream())).toEqual([
+        new MockEntity(5, 'test1'),
+        new MockEntity(6, 'test2')
+    ]);
+    expect(requestHeader(1, HttpHeader.Range)).toBe('elements=1-');
+    expect(requestHeader(2, HttpHeader.Range)).toBe('elements=1-');
+});
+
+test('streamEndsWithoutContentRange', async () => {
+    fetchMock.mockResponseOnce('[{"id":5,"name":"test1"}]');
+
+    expect(await collect(endpoint.stream())).toEqual([new MockEntity(5, 'test1')]);
+    expect(fetchMock.mock.calls.length).toBe(1);
+});
+
+test('streamAbort', async () => {
+    fetchMock.mockResponse('[{"id":5,"name":"test1"}]', {
+        status: HttpStatusCode.PartialContent,
+        headers: { [HttpHeader.ContentRange]: 'elements 0-0/*' }
+    });
+    const controller = new AbortController();
+
+    const result: MockEntity[] = [];
+    for await (const element of endpoint.stream(0, controller.signal)) {
+        result.push(element);
+        controller.abort();
+    }
+
+    expect(result).toEqual([new MockEntity(5, 'test1')]);
+});

package/endpoints/reactive/StreamingCollectionEndpoint.ts

@@ -0,0 +1,20 @@
+import { GenericStreamingCollectionEndpoint } from "./GenericStreamingCollectionEndpoint";
+import { ElementEndpoint } from "../generic/ElementEndpoint";
+import { Endpoint } from "../Endpoint";
+
+/**
+ * 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.
+ */
+export class StreamingCollectionEndpoint<TEntity> extends GenericStreamingCollectionEndpoint<TEntity, ElementEndpoint<TEntity>> {
+    /**
+     * 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: Endpoint, relativeUri: URL | string) {
+        super(referrer, relativeUri, ElementEndpoint);
+    }
+}

package/endpoints/reactive/StreamingEndpoint.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StreamingEndpoint = void 0;
+const Endpoint_1 = require("../Endpoint");
+const http_1 = require("../../http");
+/**
+ * Endpoint for a stream of `TEntity`s using a persistent HTTP connection.
+ * @typeParam TEntity The type of individual elements in the stream.
+ */
+class StreamingEndpoint extends Endpoint_1.Endpoint {
+    /**
+     * Creates a new 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 separator The character sequence used to detect that a new element starts in the HTTP stream.
+     */
+    constructor(referrer, relativeUri, separator = "\n") {
+        super(referrer, relativeUri);
+        this.separator = separator;
+    }
+    /**
+     * Provides a stream of `TEntity`s, keeping the HTTP connection open until the server closes it.
+     * @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) {
+        // 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 response = await this.send(http_1.HttpMethod.Get, controller.signal);
+            yield* (0, http_1.entityStream)(response, this.serializer, this.separator);
+        }
+        catch (err) {
+            // Aborting is a regular way of ending the stream, not an error
+            if (!(signal === null || signal === void 0 ? void 0 : signal.aborted))
+                throw err;
+        }
+        finally {
+            signal === null || signal === void 0 ? void 0 : signal.removeEventListener("abort", onAbort);
+            controller.abort();
+        }
+    }
+    /**
+     * Provides a stream of `TEntity`s using {@link stream}.
+     */
+    [Symbol.asyncIterator]() { return this.stream(); }
+}
+exports.StreamingEndpoint = StreamingEndpoint;
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiU3RyZWFtaW5nRW5kcG9pbnQuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyJTdHJlYW1pbmdFbmRwb2ludC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiOzs7QUFBQSwwQ0FBdUM7QUFDdkMscUNBQXNEO0FBRXREOzs7R0FHRztBQUNILE1BQWEsaUJBQTJCLFNBQVEsbUJBQVE7SUFDcEQ7Ozs7O09BS0c7SUFDSCxZQUFZLFFBQWtCLEVBQUUsV0FBeUIsRUFBbUIsWUFBb0IsSUFBSTtRQUNoRyxLQUFLLENBQUMsUUFBUSxFQUFFLFdBQVcsQ0FBQyxDQUFDO1FBRDJDLGNBQVMsR0FBVCxTQUFTLENBQWU7SUFFcEcsQ0FBQztJQUVEOzs7Ozs7O09BT0c7SUFDSCxLQUFLLENBQUMsQ0FBQyxNQUFNLENBQUMsTUFBb0I7UUFDOUIsc0dBQXNHO1FBQ3RHLE1BQU0sVUFBVSxHQUFHLElBQUksZUFBZSxFQUFFLENBQUM7UUFDekMsTUFBTSxPQUFPLEdBQUcsR0FBRyxFQUFFLENBQUMsVUFBVSxDQUFDLEtBQUssRUFBRSxDQUFDO1FBQ3pDLE1BQU0sYUFBTixNQUFNLHVCQUFOLE1BQU0sQ0FBRSxnQkFBZ0IsQ0FBQyxPQUFPLEVBQUUsT0FBTyxFQUFFLEVBQUUsSUFBSSxFQUFFLElBQUksRUFBRSxDQUFDLENBQUM7UUFDM0QsSUFBSSxNQUFNLGFBQU4sTUFBTSx1QkFBTixNQUFNLENBQUUsT0FBTztZQUFFLFVBQVUsQ0FBQyxLQUFLLEVBQUUsQ0FBQztRQUV4QyxJQUFJLENBQUM7WUFDRCxNQUFNLFFBQVEsR0FBRyxNQUFNLElBQUksQ0FBQyxJQUFJLENBQUMsaUJBQVUsQ0FBQyxHQUFHLEVBQUUsVUFBVSxDQUFDLE1BQU0sQ0FBQyxDQUFDO1lBQ3BFLEtBQUssQ0FBQyxDQUFDLElBQUEsbUJBQVksRUFBVSxRQUFRLEVBQUUsSUFBSSxDQUFDLFVBQVUsRUFBRSxJQUFJLENBQUMsU0FBUyxDQUFDLENBQUM7UUFDNUUsQ0FBQztRQUFDLE9BQU8sR0FBRyxFQUFFLENBQUM7WUFDWCwrREFBK0Q7WUFDL0QsSUFBSSxDQUFDLENBQUEsTUFBTSxhQUFOLE1BQU0sdUJBQU4sTUFBTSxDQUFFLE9BQU8sQ0FBQTtnQkFBRSxNQUFNLEdBQUcsQ0FBQztRQUNwQyxDQUFDO2dCQUFTLENBQUM7WUFDUCxNQUFNLGFBQU4sTUFBTSx1QkFBTixNQUFNLENBQUUsbUJBQW1CLENBQUMsT0FBTyxFQUFFLE9BQU8sQ0FBQyxDQUFDO1lBQzlDLFVBQVUsQ0FBQyxLQUFLLEVBQUUsQ0FBQztRQUN2QixDQUFDO0lBQ0wsQ0FBQztJQUVEOztPQUVHO0lBQ0gsQ0FBQyxNQUFNLENBQUMsYUFBYSxDQUFDLEtBQUssT0FBTyxJQUFJLENBQUMsTUFBTSxFQUFFLENBQUMsQ0FBQyxDQUFDO0NBQ3JEO0FBMUNELDhDQTBDQyJ9

package/endpoints/reactive/StreamingEndpoint.test.ts

@@ -0,0 +1,130 @@
+/**
+ * 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 { StreamingEndpoint } from '.';
+import { EntryEndpoint } from '..';
+import { NotFoundError } from '../../errors';
+import { HttpStatusCode } from '../../http';
+
+class MockEntity {
+    constructor(public id: number, public name: string) { }
+}
+
+fetchMock.enableMocks();
+let entryEndpoint: EntryEndpoint;
+
+beforeEach(() => {
+    fetchMock.resetMocks();
+    entryEndpoint = new EntryEndpoint('http://localhost/');
+});
+
+/**
+ * Mocks a response whose body is streamed in multiple chunks.
+ * @param chunks The chunks to send, in order.
+ * @param close Whether to close the connection after the last chunk.
+ * @returns A callback reporting whether the client has cancelled the connection.
+ */
+function mockStream(chunks: string[], close: boolean = true) {
+    let cancelled = false;
+
+    fetchMock.mockImplementation(async (_input, init) => {
+        let streamController: ReadableStreamDefaultController<Uint8Array> | undefined;
+        const body = new ReadableStream<Uint8Array>({
+            start(controller) {
+                streamController = controller;
+                const encoder = new TextEncoder();
+                for (const chunk of chunks) controller.enqueue(encoder.encode(chunk));
+                if (close) controller.close();
+            },
+            cancel() { cancelled = true; }
+        });
+
+        // Emulate how aborting a real request fails the response body
+        init?.signal?.addEventListener('abort', () => {
+            try { streamController?.error(new Error('aborted')); } catch { }
+        }, { once: true });
+
+        return new Response(body);
+    });
+
+    return () => cancelled;
+}
+
+async function collect<T>(stream: AsyncIterable<T>) {
+    const result: T[] = [];
+    for await (const element of stream) result.push(element);
+    return result;
+}
+
+test('stream', async () => {
+    mockStream(['{"id":5,"name":"test1"}\n', '{"id":6,"name":"test2"}\n']);
+    const endpoint = new StreamingEndpoint<MockEntity>(entryEndpoint, 'endpoint');
+
+    expect(await collect(endpoint.stream())).toEqual([new MockEntity(5, 'test1'), new MockEntity(6, 'test2')]);
+});
+
+test('streamSplitAcrossChunks', async () => {
+    mockStream(['{"id":5,"na', 'me":"test1"}\n{"id":6,', '"name":"test2"}\n']);
+    const endpoint = new StreamingEndpoint<MockEntity>(entryEndpoint, 'endpoint');
+
+    expect(await collect(endpoint.stream())).toEqual([new MockEntity(5, 'test1'), new MockEntity(6, 'test2')]);
+});
+
+test('streamWithoutTrailingSeparator', async () => {
+    mockStream(['{"id":5,"name":"test1"}\n{"id":6,"name":"test2"}']);
+    const endpoint = new StreamingEndpoint<MockEntity>(entryEndpoint, 'endpoint');
+
+    expect(await collect(endpoint.stream())).toEqual([new MockEntity(5, 'test1'), new MockEntity(6, 'test2')]);
+});
+
+test('streamCustomSeparator', async () => {
+    mockStream(['{"id":5,"name":"test1"}|{"id":6,"name":"test2"}']);
+    const endpoint = new StreamingEndpoint<MockEntity>(entryEndpoint, 'endpoint', '|');
+
+    expect(await collect(endpoint.stream())).toEqual([new MockEntity(5, 'test1'), new MockEntity(6, 'test2')]);
+});
+
+test('streamAsyncIterator', async () => {
+    mockStream(['{"id":5,"name":"test1"}\n']);
+    const endpoint = new StreamingEndpoint<MockEntity>(entryEndpoint, 'endpoint');
+
+    expect(await collect(endpoint)).toEqual([new MockEntity(5, 'test1')]);
+});
+
+test('streamBreak', async () => {
+    const cancelled = mockStream(['{"id":5,"name":"test1"}\n', '{"id":6,"name":"test2"}\n'], false);
+    const endpoint = new StreamingEndpoint<MockEntity>(entryEndpoint, 'endpoint');
+
+    const result: MockEntity[] = [];
+    for await (const element of endpoint.stream()) {
+        result.push(element);
+        break;
+    }
+
+    expect(result).toEqual([new MockEntity(5, 'test1')]);
+    expect(cancelled()).toBe(true);
+});
+
+test('streamAbort', async () => {
+    mockStream(['{"id":5,"name":"test1"}\n', '{"id":6,"name":"test2"}\n'], false);
+    const endpoint = new StreamingEndpoint<MockEntity>(entryEndpoint, 'endpoint');
+    const controller = new AbortController();
+
+    const result: MockEntity[] = [];
+    for await (const element of endpoint.stream(controller.signal)) {
+        result.push(element);
+        if (result.length === 2) controller.abort();
+    }
+
+    expect(result).toEqual([new MockEntity(5, 'test1'), new MockEntity(6, 'test2')]);
+});
+
+test('streamError', async () => {
+    fetchMock.mockResponseOnce('', { status: HttpStatusCode.NotFound });
+    const endpoint = new StreamingEndpoint<MockEntity>(entryEndpoint, 'endpoint');
+
+    await expect(collect(endpoint.stream())).rejects.toThrow(NotFoundError);
+});