typedrest 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typedrest",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "author": "Bastian Eicher",
   "license": "MIT",
   "description": "TypedRest helps you build type-safe fluent-style REST API clients.",
@@ -15,28 +15,78 @@
   },
   "homepage": "https://typedrest.net",
   "main": "index.js",
-  "types": "index.ts",
+  "types": "index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./endpoints": {
+      "types": "./endpoints/index.d.ts",
+      "default": "./endpoints/index.js"
+    },
+    "./endpoints/generic": {
+      "types": "./endpoints/generic/index.d.ts",
+      "default": "./endpoints/generic/index.js"
+    },
+    "./endpoints/rpc": {
+      "types": "./endpoints/rpc/index.d.ts",
+      "default": "./endpoints/rpc/index.js"
+    },
+    "./endpoints/raw": {
+      "types": "./endpoints/raw/index.d.ts",
+      "default": "./endpoints/raw/index.js"
+    },
+    "./endpoints/reactive": {
+      "types": "./endpoints/reactive/index.d.ts",
+      "default": "./endpoints/reactive/index.js"
+    },
+    "./http": {
+      "types": "./http/index.d.ts",
+      "default": "./http/index.js"
+    },
+    "./errors": {
+      "types": "./errors/index.d.ts",
+      "default": "./errors/index.js"
+    },
+    "./serializers": {
+      "types": "./serializers/index.d.ts",
+      "default": "./serializers/index.js"
+    },
+    "./links": {
+      "types": "./links/index.d.ts",
+      "default": "./links/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "files": [
-    "**/*.js",
-    "**/*.ts",
-    "!_doc.*",
-    "!docs/"
+    "index.js",
+    "index.d.ts",
+    "endpoints/**/*.js",
+    "endpoints/**/*.d.ts",
+    "errors/**/*.js",
+    "errors/**/*.d.ts",
+    "http/**/*.js",
+    "http/**/*.d.ts",
+    "links/**/*.js",
+    "links/**/*.d.ts",
+    "serializers/**/*.js",
+    "serializers/**/*.d.ts",
+    "!**/_doc.*",
+    "!**/*.test.*"
   ],
   "scripts": {
     "build": "tsc",
-    "test": "jest",
+    "test": "vitest run",
     "docs": "typedoc"
   },
   "devDependencies": {
-    "@types/node": "26.4.1",
-    "@types/jest": "30.0.0",
+    "@types/node": "26.6.6",
     "@types/url-template": "2.0.31",
-    "jest": "30.5.1",
-    "jest-environment-jsdom": "30.5.1",
-    "jest-fetch-mock": "4.2.0",
-    "ts-jest": "29.4.12",
     "typedoc": "0.28.20",
-    "typescript": "6.0.3"
+    "typescript": "6.0.3",
+    "vitest": "5.1.0",
+    "vitest-fetch-mock": "0.4.5"
   },
   "dependencies": {
     "url-template": "^2.0.8"

package/serializers/JsonSerializer.d.ts

@@ -0,0 +1,18 @@
+import { Serializer } from "./Serializer";
+/**
+ * Serializes and deserializes entities as JSON.
+ */
+export declare class JsonSerializer implements Serializer {
+    /**
+     * @inheritDoc
+     */
+    readonly supportedMediaTypes: string[];
+    /**
+     * @inheritDoc
+     */
+    serialize<T>(entity: T): string;
+    /**
+     * @inheritDoc
+     */
+    deserialize<T>(text: string): T;
+}

package/serializers/{Serializer.ts → Serializer.d.ts}

@@ -6,14 +6,12 @@ export interface Serializer {
      * A list of MIME types this serializer supports.
      */
     readonly supportedMediaTypes: string[];
-
     /**
      * Serializes an entity.
      * @typeParam T The type of entity to serialize.
      * @param entity The entity to serialize.
      */
     serialize<T>(entity: T): string;
-
     /**
      * Deserializes an entity.
      * @typeParam T The type of entity to deserialize.

package/endpoints/Endpoint.test.ts

@@ -1,300 +0,0 @@
-import fetchMock from 'jest-fetch-mock';
-import { Endpoint, EntryEndpoint } from '.';
-import { HttpMethod, HttpHeader, HttpStatusCode } from '../http';
-import { ActionEndpoint } from './rpc';
-import { ConflictError } from '../errors';
-
-class CustomEndpoint extends Endpoint {
-    async get() { await this.send(HttpMethod.Get); }
-
-    isMethodAllowedPublic(method: HttpMethod) { return this.isMethodAllowed(method); }
-}
-
-fetchMock.enableMocks();
-let endpoint: CustomEndpoint;
-
-beforeEach(() => {
-    fetchMock.resetMocks();
-    endpoint = new CustomEndpoint(new EntryEndpoint('http://localhost/'), 'endpoint');
-});
-
-test('acceptHeader', async () => {
-    fetchMock.mockOnceIf(
-        req => req.url === 'http://localhost/endpoint',
-        async req => {
-            expect(req.headers.get(HttpHeader.Accept)).toBe('application/json');
-            return {};
-        }
-    );
-
-    await endpoint.get();
-});
-
-test('allowHeader', async () => {
-    fetchMock.mockOnceIf('http://localhost/endpoint',
-        '{}',
-        {
-            headers: {
-                [HttpHeader.Allow]: HttpMethod.Put + ", " + HttpMethod.Post
-            }
-        });
-    await endpoint.get();
-
-    expect(endpoint.isMethodAllowedPublic(HttpMethod.Put)).toBe(true);
-    expect(endpoint.isMethodAllowedPublic(HttpMethod.Post)).toBe(true);
-    expect(endpoint.isMethodAllowedPublic(HttpMethod.Delete)).toBe(false);
-});
-
-test('link', async () => {
-    fetchMock.mockOnceIf('http://localhost/endpoint',
-        '{}',
-        {
-            headers: {
-                [HttpHeader.Link]: '<a>; rel=target1, <b>; rel=target2'
-            }
-        });
-    await endpoint.get();
-
-    expect(endpoint.link('target1')).toEqual(new URL('http://localhost/a'));
-    expect(endpoint.link('target2')).toEqual(new URL('http://localhost/b'));
-});
-
-test('linkAbsolute', async () => {
-    fetchMock.mockOnceIf('http://localhost/endpoint',
-        '{}',
-        {
-            headers: {
-                [HttpHeader.Link]: '<http://localhost/b>; rel=target1'
-            }
-        });
-    await endpoint.get();
-
-    expect(endpoint.link('target1')).toEqual(new URL('http://localhost/b'));
-});
-
-test('linkError', async () => {
-    fetchMock.mockOnceIf('http://localhost/endpoint',
-        '{}',
-        {
-            headers: {
-                [HttpHeader.Link]: '<http://localhost/a>; rel=target1'
-            }
-        });
-    await endpoint.get();
-
-    expect(() => endpoint.link('target2')).toThrow();
-});
-
-test('getLinks', async () => {
-    fetchMock.mockOnceIf('http://localhost/endpoint',
-        '{}',
-        {
-            headers: {
-                [HttpHeader.Link]: '<target1>; rel=child; title=Title, <target2>; rel=child'
-            }
-        });
-    await endpoint.get();
-
-    expect(endpoint.getLinks('child')).toEqual([
-        { uri: new URL('http://localhost/target1'), title: 'Title' },
-        { uri: new URL('http://localhost/target2') }
-    ]);
-});
-
-test('getLinksEscaping', async () => {
-    fetchMock.mockOnceIf('http://localhost/endpoint',
-        '{}',
-        {
-            headers: {
-                [HttpHeader.Link]: '<target1>; rel=child; title="Title,= 1", <target2>; rel=child'
-            }
-        });
-    await endpoint.get();
-
-    expect(endpoint.getLinks('child')).toEqual([
-        { uri: new URL('http://localhost/target1'), title: 'Title,= 1' },
-        { uri: new URL('http://localhost/target2') }
-    ]);
-});
-
-test('setDefaultLink', () => {
-    endpoint.setDefaultLink('child', 'target');
-    expect(endpoint.link('child')).toEqual(new URL('http://localhost/target'));
-});
-
-test('linkTemplate', async () => {
-    fetchMock.mockOnceIf('http://localhost/endpoint',
-        '{}',
-        {
-            headers: {
-                [HttpHeader.Link]: '<a{?x}>; rel=child; templated=true'
-            }
-        });
-    await endpoint.get();
-
-    expect(endpoint.getLinkTemplate('child')).toBe('a{?x}');
-});
-
-test('linkTemplateResolve', async () => {
-    fetchMock.mockOnceIf('http://localhost/endpoint',
-        '{}',
-        {
-            headers: {
-                [HttpHeader.Link]: '<a{?x}>; rel=child; templated=true'
-            }
-        });
-    await endpoint.get();
-
-    expect(endpoint.linkTemplate('child', { x: '1' }))
-        .toEqual(new URL('http://localhost/a?x=1'));
-});
-
-test('linkTemplateResolveAbsolute', async () => {
-    fetchMock.mockOnceIf('http://localhost/endpoint',
-        '{}',
-        {
-            headers: {
-                [HttpHeader.Link]: '<http://localhost/b{?x}>; rel=child; templated=true'
-            }
-        });
-    await endpoint.get();
-
-    expect(endpoint.linkTemplate('child', { x: '1' }))
-        .toEqual(new URL('http://localhost/b?x=1'));
-});
-
-test('linkTemplateResolveQuery', async () => {
-    fetchMock.mockOnceIf('http://localhost/endpoint',
-        '{}',
-        {
-            headers: {
-                [HttpHeader.Link]: '<http://localhost/b{?x,y}>; rel=search; templated=true'
-            }
-        });
-    await endpoint.get();
-
-    expect(endpoint.linkTemplate('search', { x: '1', y: '2' }))
-        .toEqual(new URL('http://localhost/b?x=1&y=2'));
-});
-
-test('linkTemplateError', async () => {
-    fetchMock.mockOnceIf('http://localhost/endpoint',
-        '{}',
-        {
-            headers: {
-                [HttpHeader.Link]: '<a>; rel=child; templated=true'
-            }
-        });
-    await endpoint.get();
-
-    expect(() => endpoint.getLinkTemplate('child2')).toThrow();
-});
-
-test('linkHal', async () => {
-    fetchMock.mockOnceIf('http://localhost/endpoint',
-        JSON.stringify({
-            _links: {
-                single: { href: 'a' },
-                collection: [{ href: 'b', title: 'Title 1' }, { href: 'c' }],
-                template: [{ href: '{id}', templated: true }]
-            }
-        }),
-        {
-            headers: {
-                [HttpHeader.ContentType]: 'application/hal+json'
-            }
-        });
-    await endpoint.get();
-
-    expect(endpoint.link('single')).toEqual(new URL('http://localhost/a'));
-    expect(endpoint.getLinks('collection')).toEqual([
-        { uri: new URL('http://localhost/b'), title: 'Title 1' },
-        { uri: new URL('http://localhost/c') }
-    ]);
-    expect(endpoint.getLinkTemplate('template')).toEqual('{id}');
-});
-
-test('setDefaultLinkTemplate', () => {
-    endpoint.setDefaultLinkTemplate('child', 'a');
-    expect(endpoint.getLinkTemplate('child')).toBe('a');
-});
-
-test('ensureTrailingSlashOnReferrerUri', () => {
-    expect(new ActionEndpoint(endpoint, 'subresource').uri).toEqual(new URL('http://localhost/subresource'));
-    expect(new ActionEndpoint(endpoint, './subresource').uri).toEqual(new URL('http://localhost/endpoint/subresource'));
-});
-
-test('errorHandlingWithNoContent', async () => {
-    fetchMock.mockOnceIf('http://localhost/endpoint',
-        '{}',
-        {
-            status: HttpStatusCode.Conflict
-        });
-
-    let errorThrown = false;
-    try {
-        await endpoint.get();
-    } catch (err) {
-        errorThrown = err instanceof ConflictError;
-    }
-    expect(errorThrown).toBe(true);
-});
-
-test('errorHandlingWithMessage', async () => {
-    fetchMock.mockOnceIf('http://localhost/endpoint',
-        '{"message":"my message","extra":"info"}',
-        {
-            status: HttpStatusCode.Conflict,
-            headers: {
-                [HttpHeader.ContentType]: 'application/json'
-            }
-        });
-
-    let errorThrown = false;
-    try {
-        await endpoint.get();
-    } catch (err) {
-        errorThrown = err instanceof ConflictError
-            && err.message === 'my message'
-            && err.data.extra === 'info';
-    }
-    expect(errorThrown).toBe(true);
-});
-
-test('errorHandlingWithArray', async () => {
-    fetchMock.mockOnceIf('http://localhost/endpoint',
-        '[{"message":"my message"}]',
-        {
-            status: HttpStatusCode.Conflict,
-            headers: {
-                [HttpHeader.ContentType]: 'application/json'
-            }
-        });
-
-    let errorThrown = false;
-    try {
-        await endpoint.get();
-    } catch (err) {
-        errorThrown = err instanceof ConflictError;
-    }
-    expect(errorThrown).toBe(true);
-});
-
-test('errorHandlingWithUnknownContentType', async () => {
-    fetchMock.mockOnceIf('http://localhost/endpoint',
-        '...',
-        {
-            status: HttpStatusCode.Conflict,
-            headers: {
-                [HttpHeader.ContentType]: 'dummy/type'
-            }
-        });
-
-    let errorThrown = false;
-    try {
-        await endpoint.get();
-    } catch (err) {
-        errorThrown = err instanceof ConflictError;
-    }
-    expect(errorThrown).toBe(true);
-});

package/endpoints/Endpoint.ts

@@ -1,247 +0,0 @@
-import { HttpMethod, HttpHeader, HttpStatusCode, HttpClient } from "../http";
-import { Serializer } from "../serializers";
-import { ErrorHandler, NotFoundError } from "../errors";
-import { LinkExtractor, Link } from "../links";
-import template from 'url-template';
-
-export class Endpoint {
-    /**
-     * The HTTP URI of the remote resource.
-     */
-    readonly uri: URL;
-
-    /**
-     * The HTTP client used to communicate with the remote resource.
-     */
-    readonly httpClient: HttpClient;
-
-    /**
-     * Controls the serialization of entities sent to and received from the server.
-     */
-    readonly serializer: Serializer;
-
-    /**
-     * Handles errors in responses.
-     */
-    readonly errorHandler: ErrorHandler;
-
-    /**
-     * Extracts links from responses.
-     */
-    readonly linkExtractor: LinkExtractor;
-
-    /**
-     * Creates a new endpoint.
-     * @param referrer The endpoint used to navigate to this one. Must be defined except for top-level endpoint.
-     * @param uri The HTTP URI of the remote element. May be relative if `referrer` is defined.
-     * @param serializer Controls the serialization of entities sent to and received from the server. Taken from `referrer` instead if it is defined.
-     * @param errorHandler Handles errors in responses. Taken from `referrer` instead if it is defined.
-     * @param linkExtractor Extracts links from responses. Taken from `referrer` instead if it is defined.
-     * @param httpClient The HTTP client used to communicate with the remote resource. Taken from `referrer` instead if it is defined.
-     */
-    constructor(
-        referrer: Endpoint | undefined,
-        uri: URL | string,
-        serializer?: Serializer,
-        errorHandler?: ErrorHandler,
-        linkExtractor?: LinkExtractor,
-        httpClient?: HttpClient) {
-        if (referrer) {
-            this.uri = (typeof uri === "string") ? referrer.join(uri) : uri;
-            if (serializer)
-                throw new Error("serializer must not be specified if referrer is specified.");
-            this.serializer = referrer.serializer;
-            if (errorHandler)
-                throw new Error("errorHandler must not be specified if referrer is specified.");
-            this.errorHandler = referrer.errorHandler;
-            if (linkExtractor)
-                throw new Error("linkExtractor must not be specified if referrer is specified.");
-            this.linkExtractor = referrer.linkExtractor;
-            if (httpClient)
-                throw new Error("httpClient must not be specified if referrer is specified.");
-            this.httpClient = referrer.httpClient;
-        } else {
-            this.uri = (typeof uri === "string") ? new URL(uri) : uri;
-            if (!serializer)
-                throw new Error("serializer must be specified if referrer is not specified.");
-            this.serializer = serializer;
-            if (!errorHandler)
-                throw new Error("errorHandler must be specified if referrer is not specified.");
-            this.errorHandler = errorHandler;
-            if (!linkExtractor)
-                throw new Error("linkExtractor must be specified if referrer is not specified.");
-            this.linkExtractor = linkExtractor;
-            if (!httpClient)
-                throw new Error("httpClient must be specified if referrer is not specified.");
-            this.httpClient = httpClient;
-        }
-    }
-
-    /**
-     * Resolves a relative URI using this endpoint's URI as the base.
-     * @param relativeUri The relative URI to resolve. Prepend `./` to imply a trailing slash in the base URI even if it is missing there.
-     */
-    protected join(relativeUri: string): URL {
-        return new URL(
-            relativeUri,
-            relativeUri.startsWith("./") ? Endpoint.ensureTrailingSlash(this.uri) : this.uri);
-    }
-
-    /**
-     * Adds a trailing slash to the URI if it does not already have one.
-     */
-    protected static ensureTrailingSlash(uri: URL | string): URL {
-        let uriString = (typeof uri === "string") ? uri : uri.href;
-        if (!uriString.endsWith("/"))
-            uriString += "/";
-        return new URL(uriString);
-    }
-
-    /**
-     * Sends an HTTP request to this endpoint's URI.
-     * Handles various cross-cutting concerns regarding a response message such as discovering links and handling errors.
-     * @param method The HTTP method to use.
-     * @param signal Used to cancel the request.
-     * @param headers The HTTP headers to set.
-     * @param body The body to send.
-     * @throws {@link errors!HttpError}
-     */
-    protected async send(method: HttpMethod, signal?: AbortSignal, headers?: HeadersInit, body?: BodyInit): Promise<Response> {
-        const response = await this.httpClient.send(this.uri, method, signal, headers, body);
-        await this.handle(response);
-        return response;
-    }
-
-    /**
-     * Handles various cross-cutting concerns regarding a response message such as discovering links and handling errors.
-     * @param response The response to process.
-     * @throws {@link errors!HttpError}
-     */
-    protected async handle(response: Response) {
-        this.links = await this.linkExtractor.getLinks(response);
-        this.handleCapabilities(response);
-        await this.errorHandler.handle(response);
-    }
-
-    // NOTE: Always replace entire array rather than modifying it to avoid async issues.
-    private links: Link[] = [];
-
-    // NOTE: Only modified during initial setup of the endpoint.
-    private defaultLinks = new Map<string, URL>();
-    private defaultLinkTemplates = new Map<string, string>();
-
-    /**
-     * Registers one or more default links for a specific relation type.
-     * These links are used when no links with this relation type are provided by the server.
-     * This should only be called during initial setup of the endpoint.
-     * @param rel The relation type of the link to add.
-     * @param href The href of the link relative to this endpoint's URI. Leave unspecified to remove any previous entries for the relation type.
-     */
-    setDefaultLink(rel: string, href?: string) {
-        if (href) {
-            this.defaultLinks.set(rel, this.join(href));
-        } else {
-            this.defaultLinks.delete(rel);
-        }
-    }
-
-    /**
-     * Registers a default link template for a specific relation type.
-     * This template is used when no template with this relation type is provided by the server.
-     * This should only be called during initial setup of the endpoint.
-     * @param rel The relation type of the link to add.
-     * @param href The templates href relative to this endpoint's URI. Leave unspecified to remove any previous entries for the relation type.
-     */
-    setDefaultLinkTemplate(rel: string, href?: string) {
-        if (href) {
-            this.defaultLinkTemplates.set(rel, href);
-        } else {
-            this.defaultLinkTemplates.delete(rel);
-        }
-    }
-
-    /**
-     * Resolves all links with a specific relation type. Uses cached data from last response.
-     * @param rel The relation type of the links to look for.
-     */
-    getLinks(rel: string): { uri: URL; title?: string; }[] {
-        const links: { uri: URL; title?: string; }[] = this.links
-            .filter(x => !x.templated && x.rel === rel)
-            .map(x => {
-                return { uri: this.join(x.href), title: x.title };
-            });
-
-        const defaultLink = this.defaultLinks.get(rel);
-        if (links.length === 0 && defaultLink) {
-            links.push({ uri: defaultLink });
-        }
-
-        return links;
-    }
-
-    /**
-     * Resolves a single link with a specific relation type. Uses cached data from last response.
-     * @param rel The relation type of the link to look for.
-     * @throws {@link errors!NotFoundError}: No link with the specified `rel` could be found.
-     */
-    link(rel: string): URL {
-        const links = this.getLinks(rel);
-
-        if (links.length === 0)
-            throw new NotFoundError(`No link with rel=${rel} provided by endpoint ${this.uri}.`, HttpStatusCode.NotFound);
-
-        return links[0].uri;
-    }
-
-    /**
-     * Resolves a link template with a specific relation type. Uses cached data from last response.
-     * @param rel The relation type of the link template to look for.
-     * @param variables Variables for resolving the template.
-     * @throws {@link errors!NotFoundError}: No link template with the specified `rel` could be found.
-     */
-    linkTemplate(rel: string, variables: { [key: string]: any; }): URL {
-        const tmpl = template.parse(this.getLinkTemplate(rel))
-        return new URL(this.join(tmpl.expand(variables)))
-    }
-
-    /**
-     * Retrieves a link template with a specific relation type. Uses cached data from last response. Prefer {@link linkTemplate} when possible.
-     * @param rel The relation type of the link template to look for.
-     * @throws {@link errors!NotFoundError}: No link template with the specified `rel` could be found.
-     */
-    getLinkTemplate(rel: string) {
-        const template = this.links.find(x => x.templated && x.rel === rel)?.href
-            ?? this.defaultLinkTemplates.get(rel);
-
-        if (!template)
-            throw new NotFoundError(`No link template with rel=${rel} provided by endpoint ${this.uri}.`, HttpStatusCode.NotFound);
-
-        return template;
-    }
-
-    // NOTE: Always replace entire array rather than modifying it to avoid async issues.
-    private allowedMethods: HttpMethod[] = [];
-
-    /**
-     * Handles allowed HTTP methods and other capabilities reported by the server.
-     */
-    protected handleCapabilities(response: Response) {
-        const header = response.headers.get(HttpHeader.Allow);
-        if (header) {
-            this.allowedMethods = header.split(", ") as HttpMethod[];
-        }
-    }
-
-    /**
-     * Shows whether the server has indicated that a specific HTTP method is currently allowed.
-     * Uses cached data from last response.
-     * @param method The HTTP methods (e.g. GET, POST, ...) to check.
-     * @returns `true` if the method is allowed, `false` if the method is not allowed, `undefined` if no request has been sent yet or the server did not specify allowed methods.
-     */
-    protected isMethodAllowed(method: HttpMethod): boolean | undefined {
-        if (this.allowedMethods.length === 0)
-            return undefined;
-
-        return this.allowedMethods.indexOf(method) !== -1;
-    }
-}