@mittwald/api-client-commons 4.466.0 → 4.468.0

package/dist/esm/core/OpenAPIPath.js

@@ -1,3 +1,4 @@
+import { serializeDates } from "./serializeDates.js";
 export class OpenAPIPath {
     rawPath;
     params;
@@ -12,7 +13,7 @@ export class OpenAPIPath {
         const asEntries = Object.entries(params ?? {});
         const finalPath = asEntries.reduce((path, entry) => {
             const [key, value] = entry;
-            return path.replace(`{${key}}`, encodeURIComponent(value));
+            return path.replace(`{${key}}`, encodeURIComponent(String(serializeDates(value))));
         }, path);
         return finalPath.startsWith("/") ? finalPath.substring(1) : finalPath;
     }

package/dist/esm/core/Request.js

@@ -1,4 +1,5 @@
 import OpenAPIPath from "./OpenAPIPath.js";
+import { serializeDates } from "./serializeDates.js";
 import { AxiosError, } from "axios";
 export class Request {
     operationDescriptor;
@@ -31,20 +32,24 @@ export class Request {
     }
     buildAxiosConfig() {
         const { method, path } = this.operationDescriptor;
-        const pathParameters = this.requestObject;
+        /**
+         * Any `Date` passed by the caller – in the body, in query, path or header
+         * parameters, nested at any depth – is converted to an ISO 8601 string
+         * here. The original request object is left untouched.
+         */
+        const requestObject = serializeDates(this.requestObject);
+        const pathParameters = 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
+        const data = requestObject && "data" in requestObject ? requestObject.data : undefined;
+        const headersConfig = requestObject && "headers" in requestObject
+            ? requestObject.headers
             : undefined;
         const headers = headersConfig
             ? this.makeAxiosHeaders(headersConfig)
             : undefined;
-        const queryParametersConfig = this.requestObject && "queryParameters" in this.requestObject
-            ? this.requestObject.queryParameters
+        const queryParametersConfig = requestObject && "queryParameters" in requestObject
+            ? requestObject.queryParameters
             : undefined;
         const params = this.convertQueryToUrlSearchParams(queryParametersConfig);
         return {
@@ -63,7 +68,10 @@ export class Request {
         };
     }
     makeAxiosHeaders(headers) {
-        return Object.fromEntries(Object.entries(headers).map(([key, value]) => [key, value?.toString()]));
+        return Object.fromEntries(Object.entries(serializeDates(headers)).map(([key, value]) => [
+            key,
+            value?.toString(),
+        ]));
     }
     convertQueryToUrlSearchParams(query) {
         if (query === undefined || query === null) {
@@ -77,7 +85,7 @@ export class Request {
         }
         if (typeof query === "object") {
             const searchParams = new URLSearchParams();
-            for (const [key, value] of Object.entries(query)) {
+            for (const [key, value] of Object.entries(serializeDates(query))) {
                 if (value === undefined) {
                     continue;
                 }

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

@@ -50,4 +50,71 @@ describe("query parameters", () => {
         });
         expect(query).toBe("foo=1&bar=true&baz=%7B%22some%22%3A%22value%22%7D");
     });
+    test("Date parameter", () => {
+        const query = executeRequest({
+            since: new Date("2024-10-12T09:08:07.006Z"),
+        });
+        expect(query).toBe("since=2024-10-12T09%3A08%3A07.006Z");
+    });
+    test("Array of Dates", () => {
+        const query = executeRequest({
+            at: [new Date("2024-10-12T09:08:07.006Z")],
+        });
+        expect(query).toBe("at=2024-10-12T09%3A08%3A07.006Z");
+    });
+});
+describe("dates in requests", () => {
+    const date = new Date("2024-10-12T09:08:07.006Z");
+    const iso = "2024-10-12T09:08:07.006Z";
+    const op = {
+        path: "/things/{at}",
+        operationId: "test",
+        method: "POST",
+    };
+    const executeRequest = (
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    requestObject) => {
+        const request = new Request(op, requestObject);
+        request.execute(mockedAxios);
+        return requestFn.mock.calls[0][0];
+    };
+    test("Dates in the request body are serialized to ISO 8601", () => {
+        const config = executeRequest({
+            at: "now",
+            data: {
+                terminationTargetDate: date,
+                nested: { at: date, list: [{ at: date }] },
+                untouched: "10/12/2024",
+                nothing: null,
+            },
+        });
+        expect(config.data).toEqual({
+            terminationTargetDate: iso,
+            nested: { at: iso, list: [{ at: iso }] },
+            untouched: "10/12/2024",
+            nothing: null,
+        });
+    });
+    test("Dates in path parameters are serialized to ISO 8601", () => {
+        const config = executeRequest({ at: date, data: {} });
+        expect(config.url).toBe(`things/${encodeURIComponent(iso)}`);
+    });
+    test("Dates in headers are serialized to ISO 8601", () => {
+        const config = executeRequest({
+            at: "now",
+            data: {},
+            headers: { "x-since": date },
+        });
+        expect(config.headers).toEqual({ "x-since": iso });
+    });
+    test("The request object passed in is not mutated", () => {
+        const requestObject = { at: "now", data: { at: date } };
+        executeRequest(requestObject);
+        expect(requestObject.data.at).toBe(date);
+    });
+    test("Non-plain payloads are passed through by reference", () => {
+        const data = new URLSearchParams({ a: "b" });
+        const config = executeRequest({ at: "now", data });
+        expect(config.data).toBe(data);
+    });
 });

package/dist/esm/core/index.js

@@ -2,3 +2,4 @@ export * from "./ApiClientBase.js";
 export * from "./ApiClientError.js";
 export * from "./OpenAPIPath.js";
 export * from "./Request.js";
+export * from "./serializeDates.js";

package/dist/esm/core/serializeDates.js

@@ -0,0 +1,30 @@
+const isPlainObject = (value) => {
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+};
+/**
+ * Recursively replaces every `Date` in a request payload with its ISO 8601
+ * representation, so that callers may pass a JS `Date` wherever the API expects
+ * a `format: date-time` string.
+ *
+ * The conversion is deliberately schema-agnostic – the runtime has no access to
+ * the OpenAPI schema of the operation being called. Everything that is not a
+ * `Date`, a plain object or an array is returned as-is (and by reference), so
+ * payloads like `FormData`, `Blob`, `ArrayBuffer` or streams are never touched
+ * or cloned.
+ *
+ * The input is never mutated.
+ */
+export const serializeDates = (value) => {
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    if (Array.isArray(value)) {
+        return value.map(serializeDates);
+    }
+    if (typeof value === "object" && value !== null && isPlainObject(value)) {
+        return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, serializeDates(entry)]));
+    }
+    return value;
+};
+export default serializeDates;

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

@@ -0,0 +1,66 @@
+import { serializeDates } from "./serializeDates.js";
+const date = new Date("2024-10-12T09:08:07.006Z");
+const iso = "2024-10-12T09:08:07.006Z";
+describe("serializeDates", () => {
+    test("converts a Date to an ISO 8601 string", () => {
+        expect(serializeDates(date)).toBe(iso);
+    });
+    test("converts Dates nested in objects", () => {
+        expect(serializeDates({ data: { terminationTargetDate: date } })).toEqual({
+            data: { terminationTargetDate: iso },
+        });
+    });
+    test("converts Dates in arrays", () => {
+        expect(serializeDates({ dates: [date, date] })).toEqual({
+            dates: [iso, iso],
+        });
+    });
+    test("converts Dates in arrays of objects", () => {
+        expect(serializeDates([{ at: date }])).toEqual([{ at: iso }]);
+    });
+    test("passes strings through unchanged", () => {
+        expect(serializeDates({ at: iso })).toEqual({ at: iso });
+    });
+    test("keeps null and undefined", () => {
+        expect(serializeDates({ a: null, b: undefined })).toEqual({
+            a: null,
+            b: undefined,
+        });
+        expect(serializeDates(null)).toBeNull();
+        expect(serializeDates(undefined)).toBeUndefined();
+    });
+    test("keeps other primitives", () => {
+        expect(serializeDates({ a: 1, b: true, c: "x" })).toEqual({
+            a: 1,
+            b: true,
+            c: "x",
+        });
+    });
+    test("leaves non-plain objects untouched and by reference", () => {
+        class Custom {
+            at = date;
+        }
+        const custom = new Custom();
+        const params = new URLSearchParams({ a: "b" });
+        const bytes = new Uint8Array([1, 2, 3]);
+        const map = new Map([["a", date]]);
+        const result = serializeDates({ custom, params, bytes, map });
+        expect(result.custom).toBe(custom);
+        expect(result.params).toBe(params);
+        expect(result.bytes).toBe(bytes);
+        expect(result.map).toBe(map);
+    });
+    test("does not mutate the input", () => {
+        const input = { data: { at: date, list: [date] } };
+        serializeDates(input);
+        expect(input.data.at).toBe(date);
+        expect(input.data.list[0]).toBe(date);
+    });
+    test("handles objects without a prototype", () => {
+        const input = Object.assign(Object.create(null), { at: date });
+        expect(serializeDates(input)).toEqual({ at: iso });
+    });
+    test("handles an invalid Date by throwing, as Date#toISOString does", () => {
+        expect(() => serializeDates(new Date(NaN))).toThrow(RangeError);
+    });
+});

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

@@ -2,3 +2,4 @@ export * from "./ApiClientBase.js";
 export * from "./ApiClientError.js";
 export * from "./OpenAPIPath.js";
 export * from "./Request.js";
+export * from "./serializeDates.js";

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

@@ -0,0 +1,15 @@
+/**
+ * Recursively replaces every `Date` in a request payload with its ISO 8601
+ * representation, so that callers may pass a JS `Date` wherever the API expects
+ * a `format: date-time` string.
+ *
+ * The conversion is deliberately schema-agnostic – the runtime has no access to
+ * the OpenAPI schema of the operation being called. Everything that is not a
+ * `Date`, a plain object or an array is returned as-is (and by reference), so
+ * payloads like `FormData`, `Blob`, `ArrayBuffer` or streams are never touched
+ * or cloned.
+ *
+ * The input is never mutated.
+ */
+export declare const serializeDates: <T>(value: T) => T;
+export default serializeDates;

package/dist/types/core/serializeDates.test.d.ts

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

package/dist/types/types/http.d.ts

@@ -4,10 +4,14 @@ export type HttpMediaType = string;
 type SafeHttpMethod = "GET" | "HEAD" | "OPTIONS";
 type UnsafeHttpMethod = "PUT" | "DELETE" | "POST" | "PATCH";
 export type HttpMethod = SafeHttpMethod | UnsafeHttpMethod;
-type HeaderValue = string | number | boolean;
+/**
+ * `Date` is accepted wherever the API expects a `format: date-time` string; it
+ * is serialized to ISO 8601 before the request is sent (see `serializeDates`).
+ */
+type HeaderValue = string | number | boolean | Date;
 export type HttpHeaders = Partial<{
     [TKey: string]: HeaderValue | HeaderValue[];
 }>;
-export type PathParameters = Record<string, string | number>;
+export type PathParameters = Record<string, string | number | Date>;
 export type QueryParameters = Record<string, unknown>;
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mittwald/api-client-commons",
-  "version": "4.466.0",
+  "version": "4.468.0",
   "author": "Mittwald CM Service GmbH & Co. KG <opensource@mittwald.de>",
   "type": "module",
   "description": "Common types and utilities for mittwald API clients",
@@ -79,5 +79,5 @@
       "optional": true
     }
   },
-  "gitHead": "58405d84af2171a4f823242baa066bfad61dfcff"
+  "gitHead": "83c2cdc00238d69632f94b07a4b38b80142f733a"
 }