@mittwald/api-code-generator 4.466.0 → 4.468.0

package/dist/esm/generation/dateTime/dateTimeInput.integration.test.js

@@ -0,0 +1,131 @@
+import { CodeGenerationModel } from "../model/CodeGenerationModel.js";
+const doc = {
+    openapi: "3.0.0",
+    info: { title: "test", version: "1" },
+    components: {
+        schemas: {
+            Shared: {
+                type: "object",
+                required: ["createdAt"],
+                properties: {
+                    createdAt: { type: "string", format: "date-time" },
+                },
+            },
+            SharedWrapper: {
+                type: "object",
+                required: ["shared"],
+                properties: {
+                    shared: { $ref: "#/components/schemas/Shared" },
+                },
+            },
+            ResponseOnly: {
+                type: "object",
+                required: ["seenAt"],
+                properties: {
+                    seenAt: { type: "string", format: "date-time" },
+                },
+            },
+        },
+    },
+    paths: {
+        "/things": {
+            post: {
+                operationId: "createThing",
+                parameters: [
+                    {
+                        name: "since",
+                        in: "query",
+                        required: false,
+                        schema: { type: "string", format: "date-time" },
+                    },
+                    {
+                        name: "day",
+                        in: "query",
+                        required: false,
+                        schema: { type: "string", format: "date" },
+                    },
+                ],
+                requestBody: {
+                    content: {
+                        "application/json": {
+                            schema: {
+                                type: "object",
+                                required: ["startsAt", "wrapper"],
+                                properties: {
+                                    startsAt: { type: "string", format: "date-time" },
+                                    dueDay: { type: "string", format: "date" },
+                                    wrapper: { $ref: "#/components/schemas/SharedWrapper" },
+                                },
+                            },
+                        },
+                    },
+                },
+                responses: {
+                    "200": {
+                        description: "ok",
+                        content: {
+                            "application/json": {
+                                schema: {
+                                    type: "object",
+                                    required: ["finishedAt", "shared", "responseOnly"],
+                                    properties: {
+                                        finishedAt: { type: "string", format: "date-time" },
+                                        shared: { $ref: "#/components/schemas/Shared" },
+                                        responseOnly: { $ref: "#/components/schemas/ResponseOnly" },
+                                    },
+                                },
+                            },
+                        },
+                    },
+                },
+            },
+        },
+    },
+};
+const compile = () => CodeGenerationModel.fromDoc("Test", doc).compileTypes({
+    rootNamespace: "Test",
+});
+const lineOf = (types, property) => {
+    const lines = types
+        .split("\n")
+        .filter((l) => l.trim().startsWith(`${property}`));
+    expect(lines.length).toBeGreaterThan(0);
+    return lines.join("\n");
+};
+describe("date-time widening", () => {
+    let types;
+    beforeAll(async () => {
+        types = await compile();
+    });
+    test("request body date-time accepts a Date", () => {
+        expect(lineOf(types, "startsAt")).toContain("string | Date");
+    });
+    test("request body date (YYYY-MM-DD) stays a string", () => {
+        expect(lineOf(types, "dueDay")).not.toContain("Date");
+    });
+    test("query parameter date-time accepts a Date", () => {
+        expect(lineOf(types, "since?")).toContain("string | Date");
+    });
+    test("query parameter date (YYYY-MM-DD) stays a string", () => {
+        expect(lineOf(types, "day?")).not.toContain("Date");
+    });
+    test("response date-time stays a string", () => {
+        expect(lineOf(types, "finishedAt")).not.toContain("Date");
+    });
+    test("shared component schemas stay unchanged", () => {
+        // Components.Schemas.Shared is used by the response and must not change
+        expect(lineOf(types, "createdAt")).toContain("createdAt: string;");
+    });
+    test("a widened request variant is emitted for shared schemas", () => {
+        expect(types).toContain("namespace RequestSchemas");
+        expect(lineOf(types, "createdAt")).toContain("createdAt: string | Date;");
+    });
+    test("request refs point at the widened variant", () => {
+        expect(lineOf(types, "wrapper")).toContain("Test.Components.RequestSchemas.SharedWrapper");
+        expect(lineOf(types, "shared")).toContain("Test.Components.RequestSchemas.Shared");
+        expect(lineOf(types, "shared")).toContain("Test.Components.Schemas.Shared");
+    });
+    test("response-only schemas get no request variant", () => {
+        expect(types).not.toContain("RequestSchemas.ResponseOnly");
+    });
+});

package/dist/esm/generation/dateTime/dateTimeInput.js

@@ -0,0 +1,66 @@
+import is from "@sindresorhus/is";
+import cloneDeep from "clone-deep";
+/**
+ * The TypeScript type emitted for `string` schemas with `format: date-time` in
+ * request position.
+ *
+ * The parentheses are required: `json-schema-to-typescript` appends `[]` to the
+ * `tsType` of array items without wrapping it, so an unparenthesized union
+ * would compile to `string | Date[]` instead of `(string | Date)[]`.
+ */
+export const dateTimeInputTsType = "(string | Date)";
+/**
+ * Only `date-time` is widened, _not_ `date`.
+ *
+ * The wire format of `format: date` is `YYYY-MM-DD`, while a `Date` can only be
+ * serialized generically (i.e. without knowing the schema) to a full ISO 8601
+ * timestamp. Accepting a `Date` there would therefore produce a value the API
+ * rejects.
+ */
+const isDateTimeStringSchema = (schema) => schema.format === "date-time" &&
+    schema.type === "string" &&
+    schema.enum === undefined &&
+    schema.const === undefined &&
+    schema.tsType === undefined;
+/**
+ * Recursively widens every `{ type: "string", format: "date-time" }` sub-schema
+ * to `string | Date`, so that callers may pass a JS `Date` instead of a
+ * hand-formatted ISO 8601 string.
+ *
+ * This must only be applied to schemas in _request_ position: widening a
+ * response type would be a breaking change for consumers.
+ */
+export const widenDateTimeInputs = (something, clone = true) => {
+    if (clone) {
+        something = cloneDeep(something);
+    }
+    if (!is.nonEmptyObject(something)) {
+        return something;
+    }
+    if (is.array(something)) {
+        return something.map((item) => widenDateTimeInputs(item, false));
+    }
+    if (isDateTimeStringSchema(something)) {
+        return { ...something, tsType: dateTimeInputTsType };
+    }
+    return Object.fromEntries(Object.entries(something).map(([key, value]) => [
+        key,
+        widenDateTimeInputs(value, false),
+    ]));
+};
+/**
+ * Returns `true` if the given schema contains a `date-time` string _itself_,
+ * i.e. without following `$ref`s.
+ */
+export const containsDateTimeInput = (something) => {
+    if (!is.nonEmptyObject(something)) {
+        return false;
+    }
+    if (is.array(something)) {
+        return something.some((item) => containsDateTimeInput(item));
+    }
+    if (isDateTimeStringSchema(something)) {
+        return true;
+    }
+    return Object.entries(something).some(([key, value]) => key !== "$ref" && containsDateTimeInput(value));
+};

package/dist/esm/generation/dateTime/dateTimeInput.test.js

@@ -0,0 +1,86 @@
+import { containsDateTimeInput, dateTimeInputTsType, widenDateTimeInputs, } from "./dateTimeInput.js";
+describe("widenDateTimeInputs", () => {
+    test("widens a date-time string", () => {
+        expect(widenDateTimeInputs({ type: "string", format: "date-time" })).toEqual({
+            type: "string",
+            format: "date-time",
+            tsType: dateTimeInputTsType,
+        });
+    });
+    test("does not widen date (YYYY-MM-DD has a different wire format)", () => {
+        const schema = { type: "string", format: "date" };
+        expect(widenDateTimeInputs(schema)).toEqual(schema);
+    });
+    test("does not widen plain strings", () => {
+        const schema = { type: "string" };
+        expect(widenDateTimeInputs(schema)).toEqual(schema);
+    });
+    test("does not widen enums", () => {
+        const schema = {
+            type: "string",
+            format: "date-time",
+            enum: ["2024-01-01T00:00:00Z"],
+        };
+        expect(widenDateTimeInputs(schema)).toEqual(schema);
+    });
+    test("does not overwrite an existing tsType", () => {
+        const schema = {
+            type: "string",
+            format: "date-time",
+            tsType: "SomethingElse",
+        };
+        expect(widenDateTimeInputs(schema)).toEqual(schema);
+    });
+    test("widens nested properties, arrays and compositions", () => {
+        const dateTime = { type: "string", format: "date-time" };
+        const widened = { ...dateTime, tsType: dateTimeInputTsType };
+        expect(widenDateTimeInputs({
+            type: "object",
+            properties: {
+                nested: { type: "object", properties: { at: dateTime } },
+                list: { type: "array", items: dateTime },
+                composed: { anyOf: [dateTime, { type: "null" }] },
+                untouched: { type: "number" },
+            },
+        })).toEqual({
+            type: "object",
+            properties: {
+                nested: { type: "object", properties: { at: widened } },
+                list: { type: "array", items: widened },
+                composed: { anyOf: [widened, { type: "null" }] },
+                untouched: { type: "number" },
+            },
+        });
+    });
+    test("does not mutate the input", () => {
+        const schema = {
+            type: "object",
+            properties: { at: { type: "string", format: "date-time" } },
+        };
+        const before = JSON.stringify(schema);
+        widenDateTimeInputs(schema);
+        expect(JSON.stringify(schema)).toBe(before);
+    });
+    test("leaves refs alone", () => {
+        const schema = { $ref: "#/components/schemas/Foo" };
+        expect(widenDateTimeInputs(schema)).toEqual(schema);
+    });
+});
+describe("containsDateTimeInput", () => {
+    test.each([
+        [{ type: "string", format: "date-time" }, true],
+        [{ type: "object", properties: { at: { $ref: "#/x" } } }, false],
+        [
+            {
+                type: "object",
+                properties: { at: { type: "string", format: "date-time" } },
+            },
+            true,
+        ],
+        [{ type: "object", properties: { at: { type: "string" } } }, false],
+        [{ type: "string", format: "date" }, false],
+        [{}, false],
+    ])("works for test %#", (schema, expected) => {
+        expect(containsDateTimeInput(schema)).toBe(expected);
+    });
+});

package/dist/esm/generation/dateTime/dateTimeInputRefs.js

@@ -0,0 +1,23 @@
+import { refNameToTSName } from "../refs/refNameToTSName.js";
+import { tsNamespaceName } from "../tsNamespaceName.js";
+const schemaRefPrefix = "#/components/schemas/";
+/**
+ * Namespace the widened request variants of component schemas are emitted to.
+ *
+ * A separate namespace (instead of a suffixed name inside `Schemas`) avoids
+ * collisions with schemas that happen to be named `…Request`.
+ */
+export const requestSchemasNs = "requestSchemas";
+/**
+ * Redirects refs to component schemas that have a widened request variant to
+ * that variant; all other refs are resolved as usual.
+ */
+export const dateTimeInputRefTSNameResolver = (variantNames) => (rootNamespace, $ref) => {
+    if ($ref.startsWith(schemaRefPrefix)) {
+        const schemaName = $ref.slice(schemaRefPrefix.length);
+        if (variantNames.has(schemaName)) {
+            return tsNamespaceName(rootNamespace, "components", requestSchemasNs, schemaName);
+        }
+    }
+    return refNameToTSName(rootNamespace, $ref);
+};

package/dist/esm/generation/dateTime/dateTimeInputSchemaNames.js

@@ -0,0 +1,103 @@
+import is from "@sindresorhus/is";
+import { OpenAPIV3 } from "openapi-types";
+import { containsDateTimeInput } from "./dateTimeInput.js";
+const schemaRefPrefix = "#/components/schemas/";
+const collectSchemaRefs = (something, into) => {
+    if (!is.nonEmptyObject(something)) {
+        return;
+    }
+    if (is.array(something)) {
+        something.forEach((item) => collectSchemaRefs(item, into));
+        return;
+    }
+    for (const [key, value] of Object.entries(something)) {
+        if (key === "$ref") {
+            if (typeof value === "string" && value.startsWith(schemaRefPrefix)) {
+                into.add(value.slice(schemaRefPrefix.length));
+            }
+            continue;
+        }
+        collectSchemaRefs(value, into);
+    }
+};
+const refsOf = (something) => {
+    const refs = new Set();
+    collectSchemaRefs(something, refs);
+    return refs;
+};
+const httpMethods = Object.values(OpenAPIV3.HttpMethods);
+/**
+ * Collects every part of the document that ends up in _request_ position, i.e.
+ * request bodies and request parameters.
+ */
+const collectRequestSchemaRoots = (doc) => {
+    const roots = new Set();
+    for (const pathItem of Object.values(doc.paths ?? {})) {
+        if (!pathItem) {
+            continue;
+        }
+        collectSchemaRefs(pathItem.parameters, roots);
+        for (const [key, operation] of Object.entries(pathItem)) {
+            if (!httpMethods.includes(key) || !is.nonEmptyObject(operation)) {
+                continue;
+            }
+            const op = operation;
+            collectSchemaRefs(op.requestBody, roots);
+            collectSchemaRefs(op.parameters, roots);
+        }
+    }
+    collectSchemaRefs(doc.components?.requestBodies, roots);
+    collectSchemaRefs(doc.components?.parameters, roots);
+    return roots;
+};
+/**
+ * Determines for which `components.schemas` entries a widened _request variant_
+ * has to be generated.
+ *
+ * A variant is needed when the schema is reachable from a request body or a
+ * request parameter **and** it contains a `format: date-time` string, either
+ * directly or through one of its `$ref`s.
+ *
+ * Restricting this to request-reachable schemas keeps the generated output
+ * small; schemas that are only ever used in responses stay untouched, which is
+ * what keeps this change backwards compatible.
+ */
+export const dateTimeInputSchemaNames = (doc) => {
+    const schemas = doc.components?.schemas ?? {};
+    const refs = new Map();
+    for (const [name, schema] of Object.entries(schemas)) {
+        refs.set(name, refsOf(schema));
+    }
+    // 1. schemas containing a date-time themselves
+    const containsDateTime = new Set(Object.entries(schemas)
+        .filter(([, schema]) => containsDateTimeInput(schema))
+        .map(([name]) => name));
+    // 2. …plus everything transitively referencing one of them
+    for (let changed = true; changed;) {
+        changed = false;
+        for (const [name, schemaRefs] of refs) {
+            if (containsDateTime.has(name)) {
+                continue;
+            }
+            for (const ref of schemaRefs) {
+                if (containsDateTime.has(ref)) {
+                    containsDateTime.add(name);
+                    changed = true;
+                    break;
+                }
+            }
+        }
+    }
+    // 3. …intersected with the schemas reachable from request position
+    const reachable = new Set();
+    const queue = [...collectRequestSchemaRoots(doc)];
+    while (queue.length > 0) {
+        const name = queue.pop();
+        if (reachable.has(name)) {
+            continue;
+        }
+        reachable.add(name);
+        queue.push(...(refs.get(name) ?? []));
+    }
+    return new Set([...containsDateTime].filter((name) => reachable.has(name)));
+};

package/dist/esm/generation/model/CodeGenerationModel.js

@@ -2,15 +2,22 @@ import { Name } from "./global/Name.js";
 import { Components } from "./components/Components.js";
 import { Paths } from "./paths/Paths.js";
 import { Tag } from "./tags/Tag.js";
+import { dateTimeInputSchemaNames } from "../dateTime/dateTimeInputSchemaNames.js";
 export class CodeGenerationModel {
     rootNamespace;
     paths;
     components;
     tags;
     doc;
+    /**
+     * Component schemas that need a widened request variant, because they are
+     * used in request position and contain a `format: date-time` string.
+     */
+    dateTimeInputSchemaNames;
     constructor(rootNamespace, doc) {
         this.rootNamespace = new Name(rootNamespace);
         this.doc = doc;
+        this.dateTimeInputSchemaNames = dateTimeInputSchemaNames(doc);
         this.components = new Components(this);
         this.tags = this.doc.tags?.map((doc) => Tag.fromDoc(doc)) ?? [];
         this.paths = new Paths(this, this.doc.paths);

package/dist/esm/generation/model/components/Components.js

@@ -1,5 +1,6 @@
 import { Name } from "../global/Name.js";
 import { Schemas } from "./Schemas.js";
+import { RequestSchemas } from "./RequestSchemas.js";
 import { Parameters } from "./Parameters.js";
 import { RequestBodies } from "./RequestBodies.js";
 import { Responses } from "./Responses.js";
@@ -11,6 +12,7 @@ export class Components {
     static ns = "Components";
     name;
     schemas;
+    requestSchemas;
     securitySchemes;
     parameters;
     requestBodies;
@@ -20,6 +22,7 @@ export class Components {
         this.model = model;
         this.name = new Name(Components.ns, model.rootNamespace);
         this.schemas = new Schemas(this, model.doc.components?.schemas ?? {});
+        this.requestSchemas = new RequestSchemas(this, model.doc.components?.schemas ?? {}, model.dateTimeInputSchemaNames);
         this.securitySchemes = new SecuritySchemes(this, model.doc.components?.securitySchemes ?? {});
         this.parameters = new Parameters(this, model.doc.components?.parameters ?? {});
         this.requestBodies = new RequestBodies(this, model.doc.components?.requestBodies ?? {});
@@ -29,6 +32,7 @@ export class Components {
         const t = {
             ns: Components.ns,
             schemas: await this.schemas.compileTypes(opts),
+            requestSchemas: await this.requestSchemas.compileTypes(opts),
             parameters: await this.parameters.compileTypes(opts),
             requestBodies: await this.requestBodies.compileTypes(opts),
             responses: await this.responses.compileTypes(opts),
@@ -37,6 +41,7 @@ export class Components {
         return `\
       namespace ${t.ns} {
         ${t.schemas}
+        ${t.requestSchemas}
         ${t.parameters}
         ${t.requestBodies}
         ${t.responses}

package/dist/esm/generation/model/components/Parameters.js

@@ -19,7 +19,8 @@ export class Parameters {
         });
         const t = {
             ns: Parameters.ns,
-            types: await asyncStringJoin(schemas, (schema) => schema.compile(opts)),
+            // parameters are request-only, so they can be widened in place
+            types: await asyncStringJoin(schemas, (schema) => schema.compileAsRequestInput(opts, this.components.model.dateTimeInputSchemaNames)),
         };
         return `\
       namespace ${t.ns} {

package/dist/esm/generation/model/components/RequestBodies.js

@@ -14,7 +14,8 @@ export class RequestBodies {
     async compileTypes(opts) {
         const t = {
             ns: RequestBodies.ns,
-            types: await asyncStringJoin(this.schemas, (schema) => schema.compile(opts)),
+            // request bodies are request-only, so they can be widened in place
+            types: await asyncStringJoin(this.schemas, (schema) => schema.compileAsRequestInput(opts, this.components.model.dateTimeInputSchemaNames)),
         };
         return `\
       namespace ${t.ns} {

package/dist/esm/generation/model/components/RequestSchemas.js

@@ -0,0 +1,43 @@
+import { JSONSchema } from "../global/JSONSchema.js";
+import { Name } from "../global/Name.js";
+import { asyncStringJoin } from "../../asyncStringJoin.js";
+import { populateNullableTypes } from "../../populateNullableTypes.js";
+import { requestSchemasNs } from "../../dateTime/dateTimeInputRefs.js";
+import { tsTypeName } from "../../tsTypeName.js";
+import cloneDeep from "clone-deep";
+/**
+ * Widened _request_ variants of component schemas.
+ *
+ * Only schemas that are reachable from a request body or request parameter and
+ * that (transitively) contain a `format: date-time` string get a variant here;
+ * see {@link dateTimeInputSchemaNames}. Everything else keeps referring to
+ * `Components.Schemas`.
+ *
+ * This namespace is purely additive: the original `Components.Schemas` types
+ * stay exactly as they were, which is what keeps response types – and therefore
+ * existing consumer code – unchanged.
+ */
+export class RequestSchemas {
+    static ns = tsTypeName(requestSchemasNs);
+    schemas;
+    components;
+    name;
+    constructor(components, schemas, variantNames) {
+        this.components = components;
+        this.name = new Name(RequestSchemas.ns, components.name);
+        this.schemas = Object.entries(schemas ?? {})
+            .filter(([schemaName]) => variantNames.has(schemaName))
+            .map(([schemaName, schema]) => new JSONSchema(new Name(schemaName, this.name), populateNullableTypes(cloneDeep(schema))));
+    }
+    async compileTypes(opts) {
+        const t = {
+            ns: RequestSchemas.ns,
+            types: await asyncStringJoin(this.schemas, (schema) => schema.compileAsRequestInput(opts, this.components.model.dateTimeInputSchemaNames)),
+        };
+        return `\
+      namespace ${t.ns} {
+        ${t.types}
+      }
+    `;
+    }
+}

package/dist/esm/generation/model/global/JSONSchema.js

@@ -2,6 +2,8 @@ import { compileJsonSchema } from "../../compileJsonSchema.js";
 import { Name } from "./Name.js";
 import cloneDeep from "clone-deep";
 import { componentRefsToCustomTypes } from "../../refs/componentRefsToCustomTypes.js";
+import { widenDateTimeInputs } from "../../dateTime/dateTimeInput.js";
+import { dateTimeInputRefTSNameResolver } from "../../dateTime/dateTimeInputRefs.js";
 export class JSONSchema {
     schemaObject;
     name;
@@ -13,6 +15,22 @@ export class JSONSchema {
         const withCustomRefTypes = componentRefsToCustomTypes(opts.rootNamespace, this.schemaObject);
         return compileJsonSchema(withCustomRefTypes, this.name.tsType);
     }
+    /**
+     * Compiles the schema for usage in _request_ position.
+     *
+     * In contrast to {@link compile}, `format: date-time` strings are widened to
+     * `string | Date`, so that a JS `Date` may be passed instead of a
+     * hand-formatted ISO 8601 string. Refs to component schemas that have a
+     * widened request variant are redirected to that variant.
+     *
+     * This must never be used for response types: widening them would be a
+     * breaking change for consumers.
+     */
+    async compileAsRequestInput(opts, dateTimeInputSchemaNames) {
+        const widened = widenDateTimeInputs(this.schemaObject);
+        const withCustomRefTypes = componentRefsToCustomTypes(opts.rootNamespace, widened, false, dateTimeInputRefTSNameResolver(dateTimeInputSchemaNames));
+        return compileJsonSchema(withCustomRefTypes, this.name.tsType);
+    }
     clone() {
         return new JSONSchema(new Name(this.name.raw), cloneDeep(this.schemaObject));
     }

package/dist/esm/generation/model/paths/operation/RequestParameters.js

@@ -63,12 +63,13 @@ export class RequestParameters {
     }
     async compileTypes(opts) {
         const header = this.header?.cloneWithOptionalProperties(opts.optionalHeaders ?? []);
+        const dateTimeInputs = this.operation.path.paths.model.dateTimeInputSchemaNames;
         const t = {
             ns: RequestParameters.ns,
-            path: (await this.path?.compile(opts)) ?? "",
-            body: (await this.body?.compile(opts)) ?? "",
-            header: (await header?.compile(opts)) ?? "",
-            query: (await this.query?.compile(opts)) ?? "",
+            path: (await this.path?.compileAsRequestInput(opts, dateTimeInputs)) ?? "",
+            body: (await this.body?.compileAsRequestInput(opts, dateTimeInputs)) ?? "",
+            header: (await header?.compileAsRequestInput(opts, dateTimeInputs)) ?? "",
+            query: (await this.query?.compileAsRequestInput(opts, dateTimeInputs)) ?? "",
         };
         return `\
       namespace ${t.ns} {

package/dist/esm/generation/refs/componentRefsToCustomTypes.js

@@ -8,7 +8,7 @@ const getComponentRef = (something) => {
         return something.$ref;
     }
 };
-export const componentRefsToCustomTypes = (rootNamespace, something, clone = true) => {
+export const componentRefsToCustomTypes = (rootNamespace, something, clone = true, resolveTSName = refNameToTSName) => {
     if (clone) {
         something = cloneDeep(something);
     }
@@ -16,18 +16,18 @@ export const componentRefsToCustomTypes = (rootNamespace, something, clone = tru
         return something;
     }
     if (is.array(something)) {
-        return something.map((item) => componentRefsToCustomTypes(rootNamespace, item, false));
+        return something.map((item) => componentRefsToCustomTypes(rootNamespace, item, false, resolveTSName));
     }
     const componentRef = getComponentRef(something);
     if (componentRef !== undefined) {
         // see https://github.com/bcherny/json-schema-to-typescript#custom-schema-properties
         return {
-            tsType: refNameToTSName(rootNamespace, componentRef),
+            tsType: resolveTSName(rootNamespace, componentRef),
             type: "object",
         };
     }
     return Object.fromEntries(Object.entries(something).map(([key, value]) => [
         key,
-        componentRefsToCustomTypes(rootNamespace, value, false),
+        componentRefsToCustomTypes(rootNamespace, value, false, resolveTSName),
     ]));
 };

package/dist/types/generation/dateTime/dateTimeInput.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The TypeScript type emitted for `string` schemas with `format: date-time` in
+ * request position.
+ *
+ * The parentheses are required: `json-schema-to-typescript` appends `[]` to the
+ * `tsType` of array items without wrapping it, so an unparenthesized union
+ * would compile to `string | Date[]` instead of `(string | Date)[]`.
+ */
+export declare const dateTimeInputTsType = "(string | Date)";
+/**
+ * Recursively widens every `{ type: "string", format: "date-time" }` sub-schema
+ * to `string | Date`, so that callers may pass a JS `Date` instead of a
+ * hand-formatted ISO 8601 string.
+ *
+ * This must only be applied to schemas in _request_ position: widening a
+ * response type would be a breaking change for consumers.
+ */
+export declare const widenDateTimeInputs: (something: unknown, clone?: boolean) => unknown;
+/**
+ * Returns `true` if the given schema contains a `date-time` string _itself_,
+ * i.e. without following `$ref`s.
+ */
+export declare const containsDateTimeInput: (something: unknown) => boolean;

package/dist/types/generation/dateTime/dateTimeInput.integration.test.d.ts

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

package/dist/types/generation/dateTime/dateTimeInput.test.d.ts

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

package/dist/types/generation/dateTime/dateTimeInputRefs.d.ts

@@ -0,0 +1,13 @@
+import { RefTSNameResolver } from "../refs/componentRefsToCustomTypes.js";
+/**
+ * Namespace the widened request variants of component schemas are emitted to.
+ *
+ * A separate namespace (instead of a suffixed name inside `Schemas`) avoids
+ * collisions with schemas that happen to be named `…Request`.
+ */
+export declare const requestSchemasNs = "requestSchemas";
+/**
+ * Redirects refs to component schemas that have a widened request variant to
+ * that variant; all other refs are resolved as usual.
+ */
+export declare const dateTimeInputRefTSNameResolver: (variantNames: ReadonlySet<string>) => RefTSNameResolver;

package/dist/types/generation/dateTime/dateTimeInputSchemaNames.d.ts

@@ -0,0 +1,14 @@
+import { OpenAPIV3 } from "openapi-types";
+/**
+ * Determines for which `components.schemas` entries a widened _request variant_
+ * has to be generated.
+ *
+ * A variant is needed when the schema is reachable from a request body or a
+ * request parameter **and** it contains a `format: date-time` string, either
+ * directly or through one of its `$ref`s.
+ *
+ * Restricting this to request-reachable schemas keeps the generated output
+ * small; schemas that are only ever used in responses stay untouched, which is
+ * what keeps this change backwards compatible.
+ */
+export declare const dateTimeInputSchemaNames: (doc: OpenAPIV3.Document) => ReadonlySet<string>;

package/dist/types/generation/model/CodeGenerationModel.d.ts

@@ -13,6 +13,11 @@ export declare class CodeGenerationModel {
     readonly components: Components;
     readonly tags: Tag[];
     readonly doc: OpenAPIV3.Document;
+    /**
+     * Component schemas that need a widened request variant, because they are
+     * used in request position and contain a `format: date-time` string.
+     */
+    readonly dateTimeInputSchemaNames: ReadonlySet<string>;
     private constructor();
     static fromDoc(rootNamespace: string, doc: OpenAPIV3.Document): CodeGenerationModel;
     compileTypes(opts: TypeCompilationOptions): Promise<string>;

package/dist/types/generation/model/components/Components.d.ts

@@ -1,6 +1,7 @@
 import { CodeGenerationModel, TypeCompilationOptions } from "../CodeGenerationModel.js";
 import { Name } from "../global/Name.js";
 import { Schemas } from "./Schemas.js";
+import { RequestSchemas } from "./RequestSchemas.js";
 import { Parameters } from "./Parameters.js";
 import { RequestBodies } from "./RequestBodies.js";
 import { Responses } from "./Responses.js";
@@ -13,6 +14,7 @@ export declare class Components {
     static readonly ns = "Components";
     name: Name;
     schemas: Schemas;
+    requestSchemas: RequestSchemas;
     securitySchemes: SecuritySchemes;
     parameters: Parameters;
     requestBodies: RequestBodies;

package/dist/types/generation/model/components/RequestSchemas.d.ts

@@ -0,0 +1,25 @@
+import { JSONSchema } from "../global/JSONSchema.js";
+import { Name } from "../global/Name.js";
+import { Components } from "./Components.js";
+import { TypeCompilationOptions } from "../CodeGenerationModel.js";
+import { OpenAPIV3 } from "openapi-types";
+/**
+ * Widened _request_ variants of component schemas.
+ *
+ * Only schemas that are reachable from a request body or request parameter and
+ * that (transitively) contain a `format: date-time` string get a variant here;
+ * see {@link dateTimeInputSchemaNames}. Everything else keeps referring to
+ * `Components.Schemas`.
+ *
+ * This namespace is purely additive: the original `Components.Schemas` types
+ * stay exactly as they were, which is what keeps response types – and therefore
+ * existing consumer code – unchanged.
+ */
+export declare class RequestSchemas {
+    static readonly ns: string;
+    readonly schemas: JSONSchema[];
+    readonly components: Components;
+    readonly name: Name;
+    constructor(components: Components, schemas: OpenAPIV3.ComponentsObject["schemas"], variantNames: ReadonlySet<string>);
+    compileTypes(opts: TypeCompilationOptions): Promise<string>;
+}

package/dist/types/generation/model/global/JSONSchema.d.ts

@@ -6,6 +6,18 @@ export declare class JSONSchema {
     readonly name: Name;
     constructor(name: Name, data?: JSONSchemaObject);
     compile(opts: TypeCompilationOptions): Promise<string>;
+    /**
+     * Compiles the schema for usage in _request_ position.
+     *
+     * In contrast to {@link compile}, `format: date-time` strings are widened to
+     * `string | Date`, so that a JS `Date` may be passed instead of a
+     * hand-formatted ISO 8601 string. Refs to component schemas that have a
+     * widened request variant are redirected to that variant.
+     *
+     * This must never be used for response types: widening them would be a
+     * breaking change for consumers.
+     */
+    compileAsRequestInput(opts: TypeCompilationOptions, dateTimeInputSchemaNames: ReadonlySet<string>): Promise<string>;
     clone(): JSONSchema;
     cloneWithOptionalProperties(optionalProperties: string[]): JSONSchema;
     private setOptionalPropertiesInSchema;

package/dist/types/generation/refs/componentRefsToCustomTypes.d.ts

@@ -1 +1,7 @@
-export declare const componentRefsToCustomTypes: (rootNamespace: string, something: unknown, clone?: boolean) => unknown;
+/**
+ * Resolves a `#/components/…` ref to the TypeScript type it should be compiled
+ * to. Used to redirect refs to the widened request variant of a component
+ * schema.
+ */
+export type RefTSNameResolver = (rootNamespace: string, $ref: string) => string;
+export declare const componentRefsToCustomTypes: (rootNamespace: string, something: unknown, clone?: boolean, resolveTSName?: RefTSNameResolver) => unknown;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mittwald/api-code-generator",
-  "version": "4.466.0",
+  "version": "4.468.0",
   "type": "module",
   "repository": "https://github.com/mittwald/api-client-js.git",
   "license": "MIT",
@@ -84,5 +84,5 @@
       "@oclif/plugin-plugins"
     ]
   },
-  "gitHead": "58405d84af2171a4f823242baa066bfad61dfcff"
+  "gitHead": "83c2cdc00238d69632f94b07a4b38b80142f733a"
 }