typedrest 0.5.0 → 0.6.1

package/endpoints/reactive/StreamingEndpoint.test.ts

@@ -1,130 +0,0 @@
-/**
- * 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);
-});

package/endpoints/rpc/ActionEndpoint.test.ts

@@ -1,36 +0,0 @@
-import fetchMock from 'jest-fetch-mock';
-import { ActionEndpoint } from '.';
-import { EntryEndpoint } from '..';
-import { HttpMethod, HttpHeader } from '../../http';
-
-fetchMock.enableMocks();
-let endpoint: ActionEndpoint;
-
-beforeEach(() => {
-    fetchMock.resetMocks();
-    endpoint = new ActionEndpoint(new EntryEndpoint('http://localhost/'), 'endpoint');
-});
-
-test('probe', async () => {
-    fetchMock.mockOnceIf(
-        req => req.method === HttpMethod.Options && req.url === 'http://localhost/endpoint',
-        async () => {
-            return {
-                headers: {
-                    [HttpHeader.Allow]: HttpMethod.Post
-                }
-            };
-        }
-    );
-    await endpoint.probe();
-
-    expect(endpoint.invokeAllowed).toBe(true);
-});
-
-test('invoke', async () => {
-    fetchMock.mockOnceIf(
-        req => req.method === HttpMethod.Post && req.url === 'http://localhost/endpoint'
-    );
-
-    await endpoint.invoke();
-});

package/endpoints/rpc/ConsumerEndpoint.test.ts

@@ -1,29 +0,0 @@
-import fetchMock from 'jest-fetch-mock';
-import { ConsumerEndpoint } from '.';
-import { EntryEndpoint } from '..';
-import { HttpMethod, HttpHeader } from '../../http';
-
-class MockEntity {
-    constructor(public id: number, public name: string) { }
-}
-
-fetchMock.enableMocks();
-let endpoint: ConsumerEndpoint<MockEntity>;
-
-beforeEach(() => {
-    fetchMock.resetMocks();
-    endpoint = new ConsumerEndpoint(new EntryEndpoint('http://localhost/'), 'endpoint');
-});
-
-test('invoke', async () => {
-    fetchMock.mockOnceIf(
-        req => req.method === HttpMethod.Post && req.url === 'http://localhost/endpoint',
-        async req => {
-            expect(req.headers.get(HttpHeader.ContentType)).toBe('application/json');
-            expect(await req.text()).toBe('{"id":1,"name":"input"}');
-            return {};
-        }
-    );
-
-    await endpoint.invoke(new MockEntity(1, 'input'));
-});

package/endpoints/rpc/FunctionEndpoint.test.ts

@@ -1,29 +0,0 @@
-import fetchMock from 'jest-fetch-mock';
-import { FunctionEndpoint } from '.';
-import { EntryEndpoint } from '..';
-import { HttpMethod, HttpHeader } from '../../http';
-
-fetchMock.enableMocks();
-let endpoint: FunctionEndpoint<{input: string}, {output: string}>;
-
-beforeEach(() => {
-    fetchMock.resetMocks();
-    endpoint = new FunctionEndpoint(new EntryEndpoint('http://localhost/'), 'endpoint');
-});
-
-test('invoke', async () => {
-    fetchMock.mockOnceIf(
-        req => req.method === HttpMethod.Post && req.url === 'http://localhost/endpoint',
-        async req => {
-            expect(req.headers.get(HttpHeader.ContentType)).toBe('application/json');
-            expect(await req.text()).toBe('{"input":"in"}');
-            return {
-                headers: { [HttpHeader.ContentType]: 'application/json' },
-                body: '{"output":"out"}'
-            };
-        }
-    );
-
-    const result = await endpoint.invoke({input: "in"});
-    expect(result).toEqual({output: "out"});
-});

package/endpoints/rpc/ProducerEndpoint.test.ts

@@ -1,32 +0,0 @@
-import fetchMock from 'jest-fetch-mock';
-import { ProducerEndpoint } from '.';
-import { EntryEndpoint } from '..';
-import { HttpMethod, HttpHeader } from '../../http';
-
-class MockEntity {
-    constructor(public id: number, public name: string) { }
-}
-
-fetchMock.enableMocks();
-let endpoint: ProducerEndpoint<MockEntity>;
-
-beforeEach(() => {
-    fetchMock.resetMocks();
-    endpoint = new ProducerEndpoint(new EntryEndpoint('http://localhost/'), 'endpoint');
-});
-
-test('invoke', async () => {
-    fetchMock.mockOnceIf(
-        req => req.method === HttpMethod.Post && req.url === 'http://localhost/endpoint',
-        async req => {
-            expect(req.headers.get(HttpHeader.Accept)).toBe('application/json');
-            return {
-                headers: { [HttpHeader.ContentType]: 'application/json' },
-                body: '{"id":1,"name":"input"}'
-            };
-        }
-    );
-
-    const result = await endpoint.invoke();
-    expect(result).toEqual(new MockEntity(1, 'input'));
-});

package/errors/DefaultErrorHandler.ts

@@ -1,65 +0,0 @@
-import { ErrorHandler } from "./ErrorHandler";
-import { HttpError, BadRequestError, AuthenticationError, AuthorizationError, NotFoundError, TimeoutError, ConflictError, ConcurrencyError, RangeNotSatisfiableError } from "./Errors";
-import { HttpStatusCode, HttpHeader } from "../http";
-
-/**
- * Handles errors in HTTP responses by mapping status codes to common error types.
- */
-export class DefaultErrorHandler implements ErrorHandler {
-    /**
-     * Throws appropriate `Error`s based on HTTP status codes and response bodies.
-     *
-     * @throws {@link errors!BadRequestError}: {@link http!HttpStatusCode.BadRequest}
-     * @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!TimeoutError}: {@link http!HttpStatusCode.RequestTimeout}
-     * @throws {@link errors!ConflictError}: {@link http!HttpStatusCode.Conflict}
-     * @throws {@link errors!ConcurrencyError}: {@link http!HttpStatusCode.PreconditionFailed}
-     * @throws {@link errors!RangeNotSatisfiableError}: {@link http!HttpStatusCode.RangeNotSatisfiable}
-     * @throws {@link errors!HttpError}: Other non-success status code
-     */
-    async handle(response: Response) {
-        if (response.ok) return;
-
-        const contentType = response.headers.get(HttpHeader.ContentType);
-        let jsonBody: any;
-        if (contentType?.startsWith("application/json") || contentType?.includes("+json")) {
-            try {
-                jsonBody = await response.json();
-            } catch {
-                jsonBody = undefined;
-            }
-        }
-
-        const errorType = DefaultErrorHandler.errorType(response.status);
-        throw new errorType(
-            jsonBody?.message ?? jsonBody?.details ?? `HTTP ${response.status} ${response.statusText}`,
-            response.status,
-            jsonBody);
-    }
-
-    private static errorType(status: HttpStatusCode): new (message: string, status: HttpStatusCode, data?: any) => Error {
-        switch (status) {
-            case HttpStatusCode.BadRequest:
-                return BadRequestError;
-            case HttpStatusCode.Unauthorized:
-                return AuthenticationError;
-            case HttpStatusCode.Forbidden:
-                return AuthorizationError;
-            case HttpStatusCode.NotFound:
-            case HttpStatusCode.Gone:
-                return NotFoundError;
-            case HttpStatusCode.RequestTimeout:
-                return TimeoutError;
-            case HttpStatusCode.Conflict:
-                return ConflictError;
-            case HttpStatusCode.PreconditionFailed:
-                return ConcurrencyError;
-            case HttpStatusCode.RangeNotSatisfiable:
-                return RangeNotSatisfiableError;
-            default:
-                return HttpError;
-        }
-    }
-}

package/http/EntityStream.ts

@@ -1,40 +0,0 @@
-import { Serializer } from "../serializers";
-
-/**
- * Exposes the body of a `Response` as a stream of deserialized entities.
- * @typeParam TEntity The type of entity the stream provides.
- * @param response The response to read the body from.
- * @param serializer Controls the deserialization of the entities in the body.
- * @param separator The character sequence used to detect that a new entity starts in the stream.
- * @returns A stream that ends when the server closes the connection.
- */
-export async function* entityStream<TEntity>(response: Response, serializer: Serializer, separator: string = "\n"): AsyncIterableIterator<TEntity> {
-    if (!response.body) return;
-
-    const reader = response.body.getReader();
-    const decoder = new TextDecoder();
-    let buffer = "";
-
-    try {
-        while (true) {
-            const { done, value } = await reader.read();
-            if (done) break;
-
-            buffer += decoder.decode(value, { stream: true });
-
-            let index: number;
-            while ((index = buffer.indexOf(separator)) !== -1) {
-                const entity = buffer.slice(0, index);
-                buffer = buffer.slice(index + separator.length);
-                if (entity.trim()) yield serializer.deserialize<TEntity>(entity);
-            }
-        }
-
-        // Tolerate a missing separator after the last entity
-        buffer += decoder.decode();
-        if (buffer.trim()) yield serializer.deserialize<TEntity>(buffer);
-    } finally {
-        // NOTE: Ignore errors here so that a failure that already ended the stream is not masked.
-        await reader.cancel().catch(() => { });
-    }
-}

package/http/FetchHttpClient.ts

@@ -1,26 +0,0 @@
-import { HttpMethod } from "./HttpMethod";
-import { HttpClient } from "./HttpClient";
-
-/**
- * Communicates with remote resources using JavaScript's standard Fetch API.
- */
-export class FetchHttpClient implements HttpClient {
-    /**
-     * @inheritDoc
-     */
-    defaultHeaders = new Headers();
-
-    /**
-     * @inheritDoc
-     */
-    send(uri: URL, method: HttpMethod, signal?: AbortSignal, headers?: HeadersInit, body?: BodyInit) {
-        const mergedHeaders = new Headers(headers);
-        this.defaultHeaders.forEach((value, key) => {
-            if (!mergedHeaders.has(key)) {
-                mergedHeaders.set(key, value);
-            }
-        });
-
-        return fetch(uri.href, { method, signal, headers: mergedHeaders, body });
-    }
-}

package/http/HttpContentRange.ts

@@ -1,41 +0,0 @@
-import { HttpHeader } from "./HttpHeader";
-
-/**
- * Describes which subset of a set of elements a response contains.
- */
-export class HttpContentRange {
-    /**
-     * Creates a new content range.
-     * @param unit The unit the range is expressed in, e.g. `elements`.
-     * @param from The index at which the data starts.
-     * @param to The index at which the data stops.
-     * @param length The total number of elements available on the server; `undefined` if unknown.
-     */
-    constructor(
-        public readonly unit: string,
-        public readonly from?: number,
-        public readonly to?: number,
-        public readonly length?: number) {
-    }
-
-    private static readonly pattern = /^(\w+) (?:(\d+)-(\d+)|\*)\/(\d+|\*)$/;
-
-    /**
-     * Extracts the content range from a `Response`.
-     * @returns The content range; `undefined` if the response has no (valid) {@link HttpHeader.ContentRange} header.
-     */
-    static from(response: Response): HttpContentRange | undefined {
-        const header = response.headers.get(HttpHeader.ContentRange);
-        if (!header) return undefined;
-
-        const match = HttpContentRange.pattern.exec(header.trim());
-        if (!match) return undefined;
-
-        const [, unit, from, to, length] = match;
-        return new HttpContentRange(
-            unit,
-            from === undefined ? undefined : parseInt(from),
-            to === undefined ? undefined : parseInt(to),
-            length === "*" ? undefined : parseInt(length));
-    }
-}

package/http/ResponseCache.ts

@@ -1,25 +0,0 @@
-import { HttpHeader } from "./HttpHeader";
-
-/**
- * Caches the contents of a `Response`.
- */
-export class ResponseCache {
-    /**
-     * Creates a new cache.
-     * @param content The content of the `Response`.
-     * @param contentType The MIME type of the `content`.
-     * @param eTag The E-Tag associated with the `content`.
-     */
-    constructor(public readonly content: string, public readonly contentType?: string, public readonly eTag?: string) {
-    }
-
-    /**
-     * Creates a new cache from a `Response`.
-     */
-    static async from(response: Response) {
-        return new ResponseCache(
-            await response.text(),
-            response.headers.get(HttpHeader.ContentType) ?? undefined,
-            response.headers.get(HttpHeader.ETag) ?? undefined);
-    }
-}

package/http/RetryAfter.ts

@@ -1,19 +0,0 @@
-import { HttpHeader } from "./HttpHeader";
-
-/**
- * Extracts the delay a server has asked clients to wait for before retrying a request.
- * @param response The response to read the {@link HttpHeader.RetryAfter} header from.
- * @returns The delay in milliseconds; `undefined` if the response has no (valid) header.
- */
-export function retryAfter(response: Response): number | undefined {
-    const header = response.headers.get(HttpHeader.RetryAfter)?.trim();
-    if (!header) return undefined;
-
-    // Either a number of seconds ...
-    if (/^\d+$/.test(header)) return parseInt(header) * 1000;
-
-    // ... or an absolute point in time
-    const date = Date.parse(header);
-    if (Number.isNaN(date)) return undefined;
-    return Math.max(0, date - Date.now());
-}

package/http/ServerSentEvents.ts

@@ -1,145 +0,0 @@
-/**
- * Yields the lines terminated by `\n`, `\r\n` or `\r` within the first `limit` characters of `buffer`.
- * @returns The remaining characters that are not part of a terminated line.
- */
-function* splitLines(buffer: string, limit: number): Generator<string, string> {
-    let start = 0;
-
-    for (let index = 0; index < limit; index++) {
-        const char = buffer[index];
-        if (char !== "\n" && char !== "\r") continue;
-
-        yield buffer.slice(start, index);
-        if (char === "\r" && buffer[index + 1] === "\n") index++;
-        start = index + 1;
-    }
-
-    return buffer.slice(start);
-}
-
-/**
- * A single event read from a Server-Sent Events (SSE) stream.
- */
-export class ServerSentEvent {
-    /**
-     * Creates a new event.
-     * @param type The event type from the `event:` field. {@link defaultEventType} if the server did not specify one.
-     * @param data The concatenated content of the event's `data:` fields.
-     * @param id The id of the most recent `id:` field if any.
-     */
-    constructor(public readonly type: string, public readonly data: string, public readonly id?: string) {
-    }
-}
-
-/**
- * The event type used for events without an explicit `event:` field.
- */
-export const defaultEventType = "message";
-
-/**
- * Reads {@link ServerSentEvent}s from the body of a `Response` in the `text/event-stream` format.
- */
-export class SseReader {
-    /**
-     * Creates a new reader.
-     * @param response The response to read the body from.
-     */
-    constructor(private readonly response: Response) {
-    }
-
-    private _lastEventId?: string;
-
-    /**
-     * The id of the most recent event that carried an `id:` field.<br>
-     * Send this back as a {@link HttpHeader.LastEventId} header when reconnecting to let the server resume where it left off.
-     */
-    get lastEventId() { return this._lastEventId; }
-
-    private _reconnectionInterval?: number;
-
-    /**
-     * The reconnection interval in milliseconds most recently requested by the server via a `retry:` field if any.
-     */
-    get reconnectionInterval() { return this._reconnectionInterval; }
-
-    /**
-     * Reads events until the stream ends.<br>
-     * Any event that is still incomplete when the stream ends is discarded.
-     */
-    async *events(): AsyncIterableIterator<ServerSentEvent> {
-        let type: string | undefined;
-        let data = "";
-
-        for await (const line of this.lines()) {
-            if (line === "") {
-                // A blank line dispatches the event collected so far
-                if (data !== "") {
-                    // Every data field appended a trailing newline; the last one is not part of the payload
-                    yield new ServerSentEvent(type ?? defaultEventType, data.slice(0, -1), this._lastEventId);
-                    data = "";
-                }
-                type = undefined;
-                continue;
-            }
-
-            // Lines starting with a colon are comments, e.g. the ":ping" some servers send to keep the connection alive
-            if (line.startsWith(":")) continue;
-
-            const colonIndex = line.indexOf(":");
-            const field = (colonIndex === -1) ? line : line.slice(0, colonIndex);
-            const value = (colonIndex === -1) ? ""
-                : line.slice((line[colonIndex + 1] === " ") ? colonIndex + 2 : colonIndex + 1);
-
-            switch (field) {
-                case "event":
-                    type = value;
-                    break;
-                case "data":
-                    data += value + "\n";
-                    break;
-                case "id":
-                    if (value.indexOf("\0") === -1) this._lastEventId = value;
-                    break;
-                case "retry":
-                    if (/^\d+$/.test(value)) this._reconnectionInterval = parseInt(value);
-                    break;
-            }
-        }
-    }
-
-    /**
-     * Splits the response body into lines, accepting `\n`, `\r\n` and `\r` as terminators.
-     */
-    private async *lines(): AsyncIterableIterator<string> {
-        if (!this.response.body) return;
-
-        const reader = this.response.body.getReader();
-        const decoder = new TextDecoder();
-        let buffer = "";
-        let stripBom = true;
-
-        try {
-            while (true) {
-                const { done, value } = await reader.read();
-                if (done) break;
-
-                buffer += decoder.decode(value, { stream: true });
-
-                if (stripBom && buffer !== "") {
-                    if (buffer.charCodeAt(0) === 0xFEFF) buffer = buffer.slice(1);
-                    stripBom = false;
-                }
-
-                // NOTE: Keep a trailing "\r" buffered; it may still be followed by a "\n" in the next chunk.
-                buffer = yield* splitLines(buffer, buffer.endsWith("\r") ? buffer.length - 1 : buffer.length);
-            }
-
-            // NOTE: A line that is still unterminated once the stream ends is discarded.
-            buffer += decoder.decode();
-            yield* splitLines(buffer, buffer.length);
-        } finally {
-            // NOTE: Ignore errors here so that a failure that already ended the stream is not masked.
-            await reader.cancel().catch(() => { });
-        }
-    }
-}

package/jest.config.js

@@ -1,12 +0,0 @@
-/** @type {import('ts-jest/dist/types').InitialOptionsTsJest} */
-module.exports = {
-  preset: 'ts-jest',
-  // jsdom is required for Blob() constructor and fetch()!
-  testEnvironment: 'jsdom',
-  testMatch: [
-    "**/?(*.)+(spec|test).ts"
-  ],
-  transform: {
-    "\\.ts$": ["ts-jest", { tsconfig: "tsconfig.test.json" }]
-  },
-};

package/links/AggregateLinkExtractor.ts

@@ -1,28 +0,0 @@
-import { Link } from "./Link";
-import { LinkExtractor } from "./LinkExtractor";
-
-/**
- * Combines the results of multiple {@link LinkExtractor}s.
- */
-export class AggregateLinkExtractor implements LinkExtractor {
-    private extractors: LinkExtractor[];
-
-    /**
-     * Creates a new aggregate link extractor.
-     * @param extractors The link extractors to aggregate.
-     */
-    constructor(...extractors: LinkExtractor[]) {
-        this.extractors = extractors;
-    }
-
-    /**
-     * @inheritDoc
-     */
-    async getLinks(response: Response) {
-        let result: Link[] = [];
-        for (const extractor of this.extractors) {
-            result = result.concat(await extractor.getLinks(response));
-        }
-        return result;
-    }
-}