@mittwald/api-code-generator 4.461.0 → 4.462.0

package/dist/esm/generation/compileJsonSchema.test.js

@@ -0,0 +1,66 @@
+import { compileJsonSchema } from "./compileJsonSchema.js";
+const normalize = (typeScript) => typeScript.replace(/\s+/g, " ").trim();
+test.each([
+    ["boolean", { type: "boolean", const: false }, "value: false;"],
+    ["string", { type: "string", const: "foo" }, 'value: "foo";'],
+    ["number", { type: "number", const: 42 }, "value: 42;"],
+    ["integer", { type: "integer", const: 0 }, "value: 0;"],
+    ["null", { type: "null", const: null }, "value: null;"],
+])("const keyword on a %s property compiles to a literal type", async (_name, propertySchema, expected) => {
+    const compiled = await compileJsonSchema({
+        type: "object",
+        required: ["value"],
+        properties: { value: propertySchema },
+    }, "WithConst");
+    expect(normalize(compiled)).toContain(expected);
+});
+test("const keyword is equivalent to a single-valued enum", async () => {
+    const schemaWithConst = {
+        type: "object",
+        required: ["value"],
+        properties: { value: { type: "string", const: "foo" } },
+    };
+    const schemaWithEnum = {
+        type: "object",
+        required: ["value"],
+        properties: { value: { type: "string", enum: ["foo"] } },
+    };
+    expect(await compileJsonSchema(schemaWithConst, "Tagged")).toEqual(await compileJsonSchema(schemaWithEnum, "Tagged"));
+});
+test("const-tagged members compile to a discriminated union", async () => {
+    const compiled = await compileJsonSchema({
+        oneOf: [
+            {
+                type: "object",
+                required: ["event", "done", "progress"],
+                properties: {
+                    event: { type: "string", const: "progress" },
+                    done: { type: "boolean", const: false },
+                    progress: { type: "number" },
+                },
+            },
+            {
+                type: "object",
+                required: ["event", "done"],
+                properties: {
+                    event: { type: "string", const: "done" },
+                    done: { type: "boolean", const: true },
+                },
+            },
+        ],
+    }, "StreamEvent");
+    // Both discriminants must be literal types, otherwise TypeScript cannot
+    // narrow the union by checking `event` or `done`.
+    expect(normalize(compiled)).toEqual(normalize(`
+      export type StreamEvent =
+        | {
+            event: "progress";
+            done: false;
+            progress: number;
+          }
+        | {
+            event: "done";
+            done: true;
+          };
+    `));
+});

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

@@ -0,0 +1,66 @@
+import { OpenApiSpec } from "../../openapi/OpenApiSpec.js";
+import { CodeGenerationModel } from "./CodeGenerationModel.js";
+const normalize = (typeScript) => typeScript.replace(/\s+/g, " ").trim();
+/**
+ * End-to-end check for the `const` keyword: an OpenAPI document describing a
+ * server-sent-event stream as a discriminated union has to pass validation and
+ * has to compile into literal types, so that consumers can narrow the union.
+ *
+ * @see https://spec.openapis.org/oas/v3.2.0.html#server-sent-event-streams
+ */
+test("const keywords survive from the spec into the generated types", async () => {
+    const document = {
+        openapi: "3.0.3",
+        info: { title: "Test", version: "1.0.0" },
+        paths: {},
+        components: {
+            schemas: {
+                ProgressEvent: {
+                    type: "object",
+                    required: ["event", "done", "progress"],
+                    properties: {
+                        event: { type: "string", const: "progress" },
+                        done: { type: "boolean", const: false },
+                        progress: { type: "number" },
+                    },
+                },
+                DoneEvent: {
+                    type: "object",
+                    required: ["event", "done", "exitCode"],
+                    properties: {
+                        event: { type: "string", const: "done" },
+                        done: { type: "boolean", const: true },
+                        exitCode: { type: "integer", const: 0 },
+                    },
+                },
+                StreamEvent: {
+                    oneOf: [
+                        { $ref: "#/components/schemas/ProgressEvent" },
+                        { $ref: "#/components/schemas/DoneEvent" },
+                    ],
+                },
+            },
+        },
+    };
+    const spec = await OpenApiSpec.parse(document);
+    const model = CodeGenerationModel.fromDoc("Api", spec.document);
+    const types = normalize(await model.compileTypes({ rootNamespace: "Api" }));
+    expect(types).toContain(normalize(`
+      export interface ProgressEvent {
+        event: "progress";
+        done: false;
+        progress: number;
+      }
+    `));
+    expect(types).toContain(normalize(`
+      export interface DoneEvent {
+        event: "done";
+        done: true;
+        exitCode: 0;
+      }
+    `));
+    expect(types).toContain(normalize(`
+      export type StreamEvent = Api.Components.Schemas.ProgressEvent
+        | Api.Components.Schemas.DoneEvent;
+    `));
+});

package/dist/esm/openapi/OpenApiSpec.js

@@ -1,11 +1,20 @@
 import { OpenAPISchemaValidationError } from "./OpenAPISchemaValidationError.js";
 import VError from "verror";
 import { makeError } from "../lib/makeError.js";
-import OpenAPISchemaValidator from "openapi-schema-validator";
+import openApiSchemaValidatorModule from "openapi-schema-validator";
 import { convert } from "swagger2openapi";
 import { ux } from "@oclif/core";
-const validator = new OpenAPISchemaValidator.default({
+import { openApiSchemaValidatorExtensions } from "./openApiSchemaValidatorExtensions.js";
+/**
+ * `openapi-schema-validator` is a CommonJS module. Depending on the module
+ * interop of the environment, the default import either _is_ the class or is a
+ * namespace object carrying it in a nested `default` property.
+ */
+const interopDefault = (imported) => typeof imported === "function" ? imported : imported.default;
+const OpenAPISchemaValidator = interopDefault(openApiSchemaValidatorModule);
+const validator = new OpenAPISchemaValidator({
     version: 3,
+    extensions: openApiSchemaValidatorExtensions,
 });
 export class OpenApiSpec {
     document;

package/dist/esm/openapi/OpenApiSpec.test.js

@@ -0,0 +1,49 @@
+import { OpenApiSpec } from "./OpenApiSpec.js";
+const documentWithSchemas = (schemas) => ({
+    openapi: "3.0.3",
+    info: { title: "Test", version: "1.0.0" },
+    paths: {},
+    components: { schemas },
+});
+test.each([
+    ["boolean", { type: "boolean", const: false }],
+    ["string", { type: "string", const: "foo" }],
+    ["number", { type: "number", const: 42 }],
+    ["integer", { type: "integer", const: 0 }],
+])("a %s schema using the const keyword validates", async (_name, schema) => {
+    const spec = await OpenApiSpec.parse(documentWithSchemas({ Tagged: schema }));
+    expect(spec.document.components?.schemas?.Tagged).toEqual(schema);
+});
+test("a discriminated union tagged with const validates", async () => {
+    const schemas = {
+        ProgressEvent: {
+            type: "object",
+            required: ["event", "done"],
+            properties: {
+                event: { type: "string", const: "progress" },
+                done: { type: "boolean", const: false },
+            },
+        },
+        DoneEvent: {
+            type: "object",
+            required: ["event", "done"],
+            properties: {
+                event: { type: "string", const: "done" },
+                done: { type: "boolean", const: true },
+            },
+        },
+        StreamEvent: {
+            oneOf: [
+                { $ref: "#/components/schemas/ProgressEvent" },
+                { $ref: "#/components/schemas/DoneEvent" },
+            ],
+        },
+    };
+    const spec = await OpenApiSpec.parse(documentWithSchemas(schemas));
+    expect(spec.document.components?.schemas).toEqual(schemas);
+});
+test("unknown schema keywords are still rejected", async () => {
+    await expect(OpenApiSpec.parse(documentWithSchemas({
+        Broken: { type: "string", definitelyNotAKeyword: true },
+    }))).rejects.toThrow(/Failed parsing OpenAPISpec/);
+});

package/dist/esm/openapi/openApiSchemaValidatorExtensions.js

@@ -0,0 +1,30 @@
+/**
+ * The meta schema shipped with `openapi-schema-validator` describes OpenAPI
+ * 3.0, whose Schema Object is a subset of JSON Schema Draft Wright 00 and is
+ * declared with `additionalProperties: false`. Keywords that were only added to
+ * the Schema Object with OpenAPI 3.1 (which aligns with JSON Schema 2020-12)
+ * are therefore rejected as "additional properties" — even though they are
+ * perfectly understood by the code generation further down the pipeline.
+ *
+ * These extensions are deep-merged into the meta schema by
+ * `openapi-schema-validator` and re-allow such keywords.
+ *
+ * @see https://spec.openapis.org/oas/v3.1.0.html#schema-object
+ * @see https://json-schema.org/draft/2020-12/json-schema-validation#name-const
+ */
+export const openApiSchemaValidatorExtensions = {
+    definitions: {
+        schema: {
+            properties: {
+                /**
+                 * `const` restricts a schema to exactly one value; it is the JSON
+                 * Schema 2020-12 equivalent of a single-valued `enum` and is compiled
+                 * into a TypeScript literal type. Any JSON value is allowed here.
+                 */
+                const: {
+                    description: "The value of this keyword MAY be of any type, including null.",
+                },
+            },
+        },
+    },
+};

package/dist/types/generation/compileJsonSchema.test.d.ts

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

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

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

package/dist/types/openapi/OpenApiSpec.test.d.ts

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

package/dist/types/openapi/openApiSchemaValidatorExtensions.d.ts

@@ -0,0 +1,16 @@
+import { IJsonSchema } from "openapi-types";
+/**
+ * The meta schema shipped with `openapi-schema-validator` describes OpenAPI
+ * 3.0, whose Schema Object is a subset of JSON Schema Draft Wright 00 and is
+ * declared with `additionalProperties: false`. Keywords that were only added to
+ * the Schema Object with OpenAPI 3.1 (which aligns with JSON Schema 2020-12)
+ * are therefore rejected as "additional properties" — even though they are
+ * perfectly understood by the code generation further down the pipeline.
+ *
+ * These extensions are deep-merged into the meta schema by
+ * `openapi-schema-validator` and re-allow such keywords.
+ *
+ * @see https://spec.openapis.org/oas/v3.1.0.html#schema-object
+ * @see https://json-schema.org/draft/2020-12/json-schema-validation#name-const
+ */
+export declare const openApiSchemaValidatorExtensions: IJsonSchema;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mittwald/api-code-generator",
-  "version": "4.461.0",
+  "version": "4.462.0",
   "type": "module",
   "repository": "https://github.com/mittwald/api-client-js.git",
   "license": "MIT",
@@ -84,5 +84,5 @@
       "@oclif/plugin-plugins"
     ]
   },
-  "gitHead": "2b61c3876f8da60cb1a641e96af4a8dcfd7ca1eb"
+  "gitHead": "74172d743808cc6b5f91fa20dfc9d19daa6dc6cc"
 }