@mittwald/api-client-commons 4.2.0-alpha.6 → 4.2.1-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Mittwald CM Service GmbH & Co. KG and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/esm/axios.js

@@ -0,0 +1 @@
+export * from "axios";

package/dist/esm/core/ApiClientBase.js

@@ -0,0 +1,13 @@
+import axios, { Axios } from "axios";
+import Request from "./Request.js";
+export class ApiClientBase {
+    axios;
+    constructor(axiosConfig = axios) {
+        this.axios =
+            axiosConfig instanceof Axios ? axiosConfig : axios.create(axiosConfig);
+    }
+    requestFunctionFactory(operation) {
+        return (conf) => new Request(operation, conf).execute(this.axios);
+    }
+}
+export default ApiClientBase;

package/dist/esm/core/ApiClientError.js

@@ -0,0 +1,12 @@
+import { AxiosError } from "axios";
+export class ApiClientError extends AxiosError {
+    constructor(message, code, config, request, response) {
+        super(message, code, config, request, response);
+        Object.setPrototypeOf(this, ApiClientError.prototype);
+        this.name = "ApiClientError";
+    }
+    static fromResponse(message, response) {
+        return new ApiClientError(message, undefined, response.config, response.request, response);
+    }
+}
+export default ApiClientError;

package/dist/esm/core/OpenAPIPath.js

@@ -0,0 +1,20 @@
+export class OpenAPIPath {
+    rawPath;
+    params;
+    constructor(rawPath, params) {
+        this.rawPath = rawPath;
+        this.params = params;
+    }
+    buildUrl() {
+        return OpenAPIPath.setPathParams(this.rawPath, this.params);
+    }
+    static setPathParams(path, params) {
+        const asEntries = Object.entries(params ?? {});
+        const finalPath = asEntries.reduce((path, entry) => {
+            const [key, value] = entry;
+            return path.replace(`{${key}}`, encodeURIComponent(value));
+        }, path);
+        return finalPath.startsWith("/") ? finalPath.substring(1) : finalPath;
+    }
+}
+export default OpenAPIPath;

package/dist/esm/core/Request.js

@@ -0,0 +1,76 @@
+import OpenAPIPath from "./OpenAPIPath.js";
+export class Request {
+    operationDescriptor;
+    requestObject;
+    requestConfig;
+    constructor(operationDescriptor, requestObject) {
+        this.operationDescriptor = operationDescriptor;
+        this.requestObject = requestObject;
+        this.requestConfig = Object.freeze(this.buildAxiosConfig());
+    }
+    execute(axios) {
+        return axios.request(this.requestConfig);
+    }
+    buildAxiosConfig() {
+        const { method, path } = this.operationDescriptor;
+        const pathParameters = this.requestObject;
+        const openApiPath = new OpenAPIPath(path, pathParameters);
+        const url = openApiPath.buildUrl();
+        const data = this.requestObject && "data" in this.requestObject
+            ? this.requestObject.data
+            : undefined;
+        const headersConfig = this.requestObject && "headers" in this.requestObject
+            ? this.requestObject.headers
+            : undefined;
+        const headers = headersConfig
+            ? this.makeAxiosHeaders(headersConfig)
+            : undefined;
+        const queryParametersConfig = this.requestObject && "queryParameters" in this.requestObject
+            ? this.requestObject.queryParameters
+            : undefined;
+        const params = this.convertQueryToUrlSearchParams(queryParametersConfig);
+        return {
+            url,
+            method,
+            headers,
+            // Must be a plain object or an URLSearchParams object
+            params,
+            data,
+            validateStatus: () => true,
+        };
+    }
+    makeAxiosHeaders(headers) {
+        return Object.fromEntries(Object.entries(headers).map(([key, value]) => [key, value?.toString()]));
+    }
+    convertQueryToUrlSearchParams(query) {
+        if (query === undefined || query === null) {
+            return undefined;
+        }
+        if (query instanceof URLSearchParams) {
+            return query;
+        }
+        if (typeof query === "string") {
+            return new URLSearchParams(query);
+        }
+        if (typeof query === "object") {
+            const searchParams = new URLSearchParams();
+            for (const [key, value] of Object.entries(query)) {
+                if (Array.isArray(value)) {
+                    for (const arrayItem of value) {
+                        searchParams.append(key, arrayItem);
+                    }
+                }
+                else {
+                    searchParams.append(key, typeof value === "string" ||
+                        typeof value === "number" ||
+                        typeof value === "boolean"
+                        ? value.toString()
+                        : JSON.stringify(value));
+                }
+            }
+            return searchParams;
+        }
+        throw new Error(`Unexpected query parameter type (${typeof query})`);
+    }
+}
+export default Request;

package/dist/esm/core/Request.test.js

@@ -0,0 +1,53 @@
+import Request from "./Request.js";
+import { jest } from "@jest/globals";
+const requestFn = jest.fn();
+const mockedAxios = {
+    request: requestFn,
+};
+beforeEach(() => {
+    jest.resetAllMocks();
+});
+describe("query parameters", () => {
+    const op = {
+        path: "/",
+        operationId: "test",
+        method: "GET",
+    };
+    const executeRequest = (query) => {
+        const request = new Request(op, { queryParameters: query });
+        request.execute(mockedAxios);
+        const requestConfig = requestFn.mock.calls[0][0];
+        return requestConfig.params.toString();
+    };
+    test("Empty query", () => {
+        const query = executeRequest({});
+        expect(query).toBe("");
+    });
+    test("Simple parameter", () => {
+        const query = executeRequest({
+            foo: "bar",
+        });
+        expect(query).toBe("foo=bar");
+    });
+    test("Two parameters", () => {
+        const query = executeRequest({
+            foo: "bar",
+            bam: "baz",
+        });
+        expect(query).toBe("foo=bar&bam=baz");
+    });
+    test("Array parameters", () => {
+        const query = executeRequest({
+            foo: ["bar", "bam"],
+        });
+        expect(query).toBe("foo=bar&foo=bam");
+    });
+    test("Number, boolean, JSON", () => {
+        const query = executeRequest({
+            foo: 1,
+            bar: true,
+            baz: { some: "value" },
+        });
+        expect(query).toBe("foo=1&bar=true&baz=%7B%22some%22%3A%22value%22%7D");
+    });
+});

package/dist/esm/core/index.js

@@ -0,0 +1,4 @@
+export * from "./ApiClientBase.js";
+export * from "./ApiClientError.js";
+export * from "./OpenAPIPath.js";
+export * from "./Request.js";

package/dist/esm/index.js

@@ -0,0 +1,3 @@
+export * from "./core/index.js";
+export * from "./types/index.js";
+export * from "./axios.js";

package/dist/esm/react/ApiCallAsyncResourceFactory.js

@@ -0,0 +1,35 @@
+import { getAsyncResource } from "@mittwald/react-use-promise";
+import { assertStatus, } from "../types/index.js";
+import Request from "../core/Request.js";
+export class ApiCallAsyncResourceFactory {
+    static namespace = "@mittwald/api-client";
+    operation;
+    requestFn;
+    constructor(operation, requestFn) {
+        this.operation = operation;
+        this.requestFn = requestFn;
+    }
+    getAsyncResourceId() {
+        return `${ApiCallAsyncResourceFactory.namespace}/${this.operation.operationId}`;
+    }
+    getAsyncResourceTags(request) {
+        const url = request.requestConfig.url ?? "";
+        return [
+            this.getAsyncResourceId(),
+            `${ApiCallAsyncResourceFactory.namespace}/${this.operation.method}`,
+            `${ApiCallAsyncResourceFactory.namespace}/${url}`,
+        ];
+    }
+    async executeRequest(requestObj) {
+        const response = await this.requestFn(requestObj);
+        assertStatus(response, 200);
+        return response.data;
+    }
+    getApiResource = ((requestObj) => {
+        const request = new Request(this.operation, requestObj);
+        return getAsyncResource((requestObj) => this.executeRequest(requestObj), [requestObj], {
+            tags: this.getAsyncResourceTags(request),
+            loaderId: this.getAsyncResourceId(),
+        });
+    });
+}

package/dist/esm/react/ApiCallAsyncResourceFactory.test-types.js

@@ -0,0 +1,36 @@
+import { ApiCallAsyncResourceFactory } from "./ApiCallAsyncResourceFactory.js";
+const getStuff = new ApiCallAsyncResourceFactory({
+    operationId: "getStuff",
+    path: "/stuff",
+    method: "GET",
+}, {});
+function ignoredCheckRequestType() {
+    getStuff.getApiResource({
+        data: {
+            // @ts-expect-error Not matching request type
+            foo: "",
+        },
+    });
+    getStuff.getApiResource({
+        data: {
+            requestString: "",
+        },
+    });
+}
+function ignoredCheckResponseType() {
+    const stuff = getStuff
+        .getApiResource({
+        data: {
+            requestString: "",
+        },
+    })
+        .use();
+    // @ts-expect-error Accessing unknown prop
+    stuff.foo;
+    (function (ignored) {
+        // @ts-expect-error is a number
+    })(stuff.responseData);
+    (function (ignored) {
+        // is number
+    })(stuff.responseData);
+}

package/dist/esm/react/ApiCallAsyncResourceFactory.test.js

@@ -0,0 +1,46 @@
+import { beforeEach, expect, jest } from "@jest/globals";
+import { ApiCallAsyncResourceFactory } from "./ApiCallAsyncResourceFactory.js";
+import { refresh } from "@mittwald/react-use-promise";
+beforeEach(() => {
+    refresh();
+    jest.resetAllMocks();
+});
+const requestMock = jest.fn();
+const getStuff = new ApiCallAsyncResourceFactory({
+    operationId: "getStuff",
+    path: "/stuff",
+    method: "GET",
+}, requestMock);
+const testRequest1 = {
+    data: {
+        foo: "bar",
+    },
+};
+const testRequest2 = {
+    data: {
+        foo: "baz",
+    },
+};
+test("Resource loader executes request", async () => {
+    await getStuff.getApiResource(testRequest1).load();
+    expect(requestMock).toHaveBeenCalledTimes(1);
+    const firstRequestParams = requestMock.mock.calls[0][0];
+    expect(firstRequestParams).toMatchObject(testRequest1);
+});
+test("Resource is cached under URL", async () => {
+    await getStuff.getApiResource(testRequest1).load();
+    expect(requestMock).toHaveBeenCalledTimes(1);
+    await getStuff.getApiResource(testRequest1).load();
+    expect(requestMock).toHaveBeenCalledTimes(1);
+    refresh({
+        tag: "@mittwald/api-client/stuff",
+    });
+    await getStuff.getApiResource(testRequest1).load();
+    expect(requestMock).toHaveBeenCalledTimes(2);
+});
+test("Resources are different when request object changes", async () => {
+    await getStuff.getApiResource(testRequest1).load();
+    expect(requestMock).toHaveBeenCalledTimes(1);
+    await getStuff.getApiResource(testRequest2).load();
+    expect(requestMock).toHaveBeenCalledTimes(2);
+});

package/dist/esm/react/index.js

@@ -0,0 +1 @@
+export * from "./ApiCallAsyncResourceFactory.js";

package/dist/esm/react/types.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/types/NullableOnNoRequiredKeysDeep.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/types/OpenAPIOperation.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/types/RequestFunction.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/types/RequestFunction.test-types.js

@@ -0,0 +1,29 @@
+function ignoredTestEmptyRequestTypes() {
+    const f = {};
+    void f();
+    void f({
+        headers: {},
+    });
+    void f({
+        headers: { extra: true },
+    });
+}
+function ignoredTestOptionalHeadersRequestTypes() {
+    const f = {};
+    void f();
+    void f({
+        headers: {},
+    });
+    void f({
+        headers: { extra: true },
+    });
+}
+function ignoredTestPathParametersAreInRootOfRequestConfig() {
+    const f = {};
+    void f({
+        foo: "",
+    });
+    // @ts-expect-error Missing parameter
+    void f({});
+}
+export {};

package/dist/esm/types/RequestType.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/types/RequestType.test-types.js

@@ -0,0 +1,146 @@
+import { expectAssignable } from "tsd";
+function ignoredTestEmptyRequestTypes() {
+    expectAssignable({});
+    // @ts-expect-error Not assignable
+    expectAssignable({ extra: true });
+    // @ts-expect-error Not assignable
+    expectAssignable({ data: {} });
+    // @ts-expect-error Not assignable
+    expectAssignable({ data: null });
+    // @ts-expect-error Not assignable
+    expectAssignable({ pathParameters: {} });
+}
+function ignoredTestRequestTypesWithDataType() {
+    expectAssignable({ data: { foo: "" } });
+    // @ts-expect-error Not assignable
+    expectAssignable({});
+    expectAssignable({
+        // @ts-expect-error Not assignable
+        data: { foo: "", extra: "" },
+    });
+    // @ts-expect-error Not assignable
+    expectAssignable({ data: { noFoo: "" } });
+}
+function ignoredTestRequestTypesWithPathParameters() {
+    expectAssignable({
+        data: { foo: "" },
+        pathParameters: { bar: "" },
+    });
+    expectAssignable({
+        pathParameters: { bar: "" },
+    });
+    // @ts-expect-error Not assignable
+    expectAssignable({});
+    expectAssignable({
+        // @ts-expect-error Not assignable
+        pathParameters: {},
+    });
+    expectAssignable({
+        // @ts-expect-error Not assignable
+        pathParameters: { foo: "", extra: "" },
+    });
+}
+function ignoredTestRequestTypesWithHeader() {
+    expectAssignable({
+        data: {
+            foo: "",
+        },
+        pathParameters: { bar: "" },
+        headers: { baz: "" },
+    });
+    expectAssignable({
+        pathParameters: { bar: "" },
+        headers: { baz: "" },
+    });
+    expectAssignable({
+        headers: { baz: "" },
+    });
+    // @ts-expect-error Not assignable
+    expectAssignable({});
+    expectAssignable({
+        headers: {
+            // @ts-expect-error Not assignable
+            baz: 42,
+        },
+    });
+    expectAssignable({
+        // @ts-expect-error Not assignable
+        headers: {},
+    });
+    expectAssignable({
+        // @ts-expect-error Not assignable
+        data: {},
+        headers: {
+            baz: "",
+        },
+    });
+    expectAssignable({
+        // @ts-expect-error Not assignable
+        pathParameters: {},
+        headers: {
+            baz: "",
+        },
+    });
+}
+function ignoredTestRequestTypesWithQuery() {
+    expectAssignable({
+        data: {
+            foo: "",
+        },
+        pathParameters: { bar: "" },
+        headers: { baz: "" },
+        queryParameters: {
+            whut: "",
+        },
+    });
+    expectAssignable({
+        pathParameters: { bar: "" },
+        headers: { baz: "" },
+        queryParameters: {
+            whut: "",
+        },
+    });
+    expectAssignable({
+        queryParameters: {
+            whut: "",
+        },
+    });
+    // @ts-expect-error Not assignable
+    expectAssignable({});
+    expectAssignable({
+        queryParameters: {
+            // @ts-expect-error Not assignable
+            whut: 42,
+        },
+    });
+    expectAssignable({
+        // @ts-expect-error Not assignable
+        queryParameters: {},
+    });
+}
+function ignoredTestAdditionalHeadersCanAlwaysBeSet() {
+    expectAssignable({
+        headers: { extra: true },
+    });
+    expectAssignable({
+        headers: { extra: true },
+    });
+    expectAssignable({
+        headers: { extra: true },
+    });
+    expectAssignable({
+        data: {
+            foo: "",
+        },
+        headers: { extra: true },
+    });
+    expectAssignable({
+        pathParameters: {
+            bar: "",
+        },
+        headers: { extra: true },
+    });
+    expectAssignable({
+        headers: { extra: true, baz: "" },
+    });
+}

package/dist/esm/types/Response.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/types/Response.test-types.js

@@ -0,0 +1,70 @@
+import { expectAssignable, expectNotAssignable, expectType } from "tsd";
+const additionalAxiosResponseData = {
+    statusText: "",
+    headers: {},
+    config: {},
+    mediaType: "application/json",
+};
+expectAssignable({
+    data: { a: "" },
+    status: 200,
+    ...additionalAxiosResponseData,
+});
+expectNotAssignable({
+    data: { a: "", extra: "!" },
+    status: 200,
+    ...additionalAxiosResponseData,
+});
+expectAssignable({
+    data: {
+        b: "",
+    },
+    status: 201,
+    ...additionalAxiosResponseData,
+});
+expectAssignable({
+    data: null,
+    status: 400,
+    ...additionalAxiosResponseData,
+});
+expectNotAssignable({
+    data: null,
+    status: 42,
+    ...additionalAxiosResponseData,
+});
+expectNotAssignable({
+    data: null,
+    status: 42,
+    extra: "!",
+    ...additionalAxiosResponseData,
+});
+expectNotAssignable({
+    data: { extraContent: "" },
+    status: 400,
+    ...additionalAxiosResponseData,
+});
+function ignoredTestRequestTypesWithDataPathParameters() {
+    const someResponse = {};
+    expectType(someResponse.status);
+    if (someResponse.status === 200) {
+        // @ts-expect-error > a is not in data
+        someResponse.data.a;
+        // @ts-expect-error > b is not in data
+        someResponse.data.b;
+        if (someResponse.mediaType === "text/plain") {
+            // @ts-expect-error > a is not in data
+            someResponse.data.a;
+            expectType(someResponse.data.text);
+        }
+        else {
+            // @ts-expect-error > text is not in data
+            someResponse.data.text;
+            expectType(someResponse.data.a);
+        }
+    }
+    else if (someResponse.status === 201) {
+        expectType(someResponse.data.b);
+        // @ts-expect-error > a is not in data
+        someResponse.data.a;
+    }
+}

package/dist/esm/types/assertStatus.js

@@ -0,0 +1,7 @@
+import ApiClientError from "../core/ApiClientError.js";
+export function assertStatus(response, expectedStatus) {
+    if (response.status !== expectedStatus) {
+        throw ApiClientError.fromResponse(`Unexpected response status (expected ${expectedStatus}, got: ${response.status})`, response);
+    }
+}
+export default assertStatus;

package/dist/esm/types/assertStatus.test-types.js

@@ -0,0 +1,8 @@
+import { expectAssignable } from "tsd";
+import assertStatus from "./assertStatus.js";
+function ignoredTestAssertStatusAssertsAlsoTheCorrectResponseType() {
+    assertStatus(someResponse, 200);
+    expectAssignable(someResponse);
+    // @ts-expect-error Not assignable
+    expectAssignable(someResponse);
+}

package/dist/esm/types/http.js

@@ -0,0 +1 @@
+export {};

package/dist/esm/types/index.js

@@ -0,0 +1,7 @@
+export * from "./RequestType.js";
+export * from "./RequestFunction.js";
+export * from "./Response.js";
+export * from "./OpenAPIOperation.js";
+export * from "./http.js";
+export * from "./simplify.js";
+export * from "./assertStatus.js";

package/dist/esm/types/simplify.js

@@ -0,0 +1 @@
+export {};

package/dist/types/axios.d.ts

@@ -0,0 +1 @@
+export * from "axios";

package/dist/types/core/ApiClientBase.d.ts

@@ -0,0 +1,9 @@
+import { AxiosInstance, CreateAxiosDefaults } from "axios";
+import { RequestFunction } from "../types/index.js";
+import { OpenAPIOperation } from "../types/index.js";
+export declare abstract class ApiClientBase {
+    axios: AxiosInstance;
+    constructor(axiosConfig?: AxiosInstance | CreateAxiosDefaults);
+    protected requestFunctionFactory<TOp extends OpenAPIOperation>(operation: TOp): RequestFunction<TOp>;
+}
+export default ApiClientBase;

package/dist/types/core/ApiClientError.d.ts

@@ -0,0 +1,7 @@
+import { AxiosError, AxiosResponse, InternalAxiosRequestConfig } from "axios";
+import { AnyResponse } from "../types/Response.js";
+export declare class ApiClientError<T = unknown, D = unknown> extends AxiosError<T, D> {
+    constructor(message?: string, code?: string, config?: InternalAxiosRequestConfig<D>, request?: unknown, response?: AxiosResponse<T, D>);
+    static fromResponse(message: string, response: AnyResponse): ApiClientError;
+}
+export default ApiClientError;

package/dist/types/core/OpenAPIPath.d.ts

@@ -0,0 +1,9 @@
+import { PathParameters } from "../types/http.js";
+export declare class OpenAPIPath {
+    private readonly rawPath;
+    private readonly params?;
+    constructor(rawPath: string, params?: PathParameters);
+    buildUrl(): string;
+    private static setPathParams;
+}
+export default OpenAPIPath;