@mittwald/api-code-generator 4.12.0

package/README.md

@@ -0,0 +1,73 @@
+Common code base used by `@mittwald/api-client-*` package.
+
+## CLI
+
+Use the CLI commands provided by this package to build your API client and
+validate the OpenAPI-Spec:
+
+```shell
+acg validate spec/openapi.json
+acg generate --name MittwaldAPIV2 spec/openapi.json src/generated --optionalHeader x-access-token
+```
+
+## TypeScript API
+
+If you need to generate the client in code, you can use the TypeScript API
+demonstrated in this template:
+
+```typescript
+import * as path from "path";
+import { UniversalContentLoader } from "@mittwald/api-code-generator/js";
+import { UniversalFileLoader } from "@mittwald/api-code-generator/js";
+import { OpenApiSpec } from "@mittwald/api-code-generator/js";
+import { CodeGenerationModel } from "@mittwald/api-code-generator/js";
+import { prepareTypeScriptOutput } from "@mittwald/api-code-generator/js";
+import { writeIfChangedAsync } from "@mittwald/api-code-generator/js";
+
+const name = "MittwaldAPIV2";
+const inout = `${process.cwd()}/spec/openapi.json`;
+const output = `${process.cwd()}/src/generated`;
+
+// Loading OpenAPI spec
+const loader = new UniversalContentLoader(new UniversalFileLoader(input));
+const openApiDoc = await loader.load();
+
+// Parsing OpenAPI spec
+const spec = await OpenApiSpec.parse(openApiDoc, {
+  skipValidation: flags.skipValidation,
+});
+
+// Building transformation model
+const model = CodeGenerationModel.fromDoc(name, spec.document);
+
+// Generating descriptors
+const descriptorsFileContent = model.paths.compileDescriptors();
+await writeIfChangedAsync(
+  path.join(output, "descriptors.ts"),
+  await prepareTypeScriptOutput(descriptorsFileContent),
+);
+
+// Generating types
+const typesFileContent = await model.compileTypes({
+  rootNamespace: flags.name,
+  optionalHeaders: ["x-access-token"],
+});
+await writeIfChangedAsync(
+  path.join(output, "types.ts"),
+  await prepareTypeScriptOutput(typesFileContent),
+);
+
+// Generating client
+const clientFileContent = model.paths.compileClient();
+await writeIfChangedAsync(
+  path.join(output, "client.ts"),
+  await prepareTypeScriptOutput(clientFileContent),
+);
+
+// if needed: Generating React client
+const reactClientFileContent = model.paths.compileReactClient();
+await writeIfChangedAsync(
+  path.join(output, "client-react.ts"),
+  await prepareTypeScriptOutput(reactClientFileContent),
+);
+```

package/bin/cli.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+import oclif from "@oclif/core";
+
+oclif
+  .run(process.argv.slice(2), import.meta.url)
+  .then(oclif.flush)
+  .catch(oclif.Errors.handle);

package/dist/esm/commands/generate/index.js

@@ -0,0 +1,70 @@
+import { Args, Command, Flags, ux } from "@oclif/core";
+import { UniversalContentLoader } from "../../loading/UniversalContentLoader.js";
+import { OpenApiSpec } from "../../openapi/OpenApiSpec.js";
+import { CodeGenerationModel } from "../../generation/model/CodeGenerationModel.js";
+import * as path from "path";
+import { prepareTypeScriptOutput } from "../../generation/prepareTypeScriptOutput.js";
+import { UniversalFileLoader } from "../../loading/UniversalFileLoader.js";
+import { writeIfChangedAsync } from "../../lib/writeIfChangedAsync.js";
+export default class Generate extends Command {
+    static description = "Generate code from the provided OpenAPI spec.";
+    static flags = {
+        skipValidation: Flags.boolean({
+            required: false,
+            default: false,
+            description: "Skip validation of input OpenAPI spec",
+        }),
+        name: Flags.string({
+            required: false,
+            default: "Api",
+        }),
+        optionalHeader: Flags.string({
+            required: false,
+            multiple: true,
+            description: "Makes the given header optional in generated types",
+            default: [],
+        }),
+    };
+    static args = {
+        input: Args.directory({
+            required: true,
+        }),
+        output: Args.directory({
+            required: true,
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(Generate);
+        const loader = new UniversalContentLoader(new UniversalFileLoader(args.input));
+        ux.action.start("Loading OpenAPI spec");
+        const openApiDoc = await loader.load();
+        ux.action.stop();
+        ux.action.start("Parsing OpenAPI spec");
+        const spec = await OpenApiSpec.parse(openApiDoc, {
+            skipValidation: flags.skipValidation,
+        });
+        ux.action.stop();
+        ux.action.start("Building transformation model");
+        const model = CodeGenerationModel.fromDoc(flags.name, spec.document);
+        ux.action.stop();
+        ux.action.start("Generating descriptors");
+        const descriptorsFileContent = model.paths.compileDescriptors();
+        await writeIfChangedAsync(path.join(args.output, "descriptors.ts"), await prepareTypeScriptOutput(descriptorsFileContent));
+        ux.action.stop();
+        ux.action.start("Generating types");
+        const typesFileContent = await model.compileTypes({
+            rootNamespace: flags.name,
+            optionalHeaders: flags.optionalHeader,
+        });
+        await writeIfChangedAsync(path.join(args.output, "types.ts"), await prepareTypeScriptOutput(typesFileContent));
+        ux.action.stop();
+        ux.action.start("Generating client");
+        const clientFileContent = model.paths.compileClient();
+        await writeIfChangedAsync(path.join(args.output, "client.ts"), await prepareTypeScriptOutput(clientFileContent));
+        ux.action.stop();
+        ux.action.start("Generating React client");
+        const reactClientFileContent = model.paths.compileReactClient();
+        await writeIfChangedAsync(path.join(args.output, "client-react.ts"), await prepareTypeScriptOutput(reactClientFileContent));
+        ux.action.stop();
+    }
+}

package/dist/esm/commands/validate/index.js

@@ -0,0 +1,21 @@
+import { Args, Command } from "@oclif/core";
+import { UniversalContentLoader } from "../../loading/UniversalContentLoader.js";
+import { OpenApiSpec } from "../../openapi/OpenApiSpec.js";
+import { UniversalFileLoader } from "../../loading/UniversalFileLoader.js";
+export default class Validate extends Command {
+    static description = "Validate the provided OpenAPI spec.";
+    static args = {
+        input: Args.string({
+            required: true,
+        }),
+    };
+    async run() {
+        const { args } = await this.parse(Validate);
+        const loader = new UniversalContentLoader(new UniversalFileLoader(args.input));
+        const openApiDoc = await loader.load();
+        await OpenApiSpec.parse(openApiDoc, {
+            skipValidation: false,
+        });
+        this.log("OK");
+    }
+}

package/dist/esm/generation/asyncStringJoin.js

@@ -0,0 +1,4 @@
+export const asyncStringJoin = async (items, contentGenerator, separator = "\r\n") => {
+    const mappedItems = await Promise.all(items.map(contentGenerator));
+    return mappedItems.join(separator);
+};

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

@@ -0,0 +1,5 @@
+import { asyncStringJoin } from "./asyncStringJoin.js";
+test("asyncStringJoin() joins each item with an async generator function", async () => {
+    const result = await asyncStringJoin(["Foo", "Bar"], (item) => Promise.resolve(`Async${item}`));
+    expect(result).toMatch("AsyncFoo\r\nAsyncBar");
+});

package/dist/esm/generation/compileJsonSchema.js

@@ -0,0 +1,10 @@
+import { compile } from "json-schema-to-typescript";
+const defaultCompileOptions = {
+    bannerComment: "",
+    additionalProperties: false,
+    maxItems: 5,
+};
+export const compileJsonSchema = (schema, name, options = {}) => compile(schema, name, {
+    ...defaultCompileOptions,
+    ...options,
+});

package/dist/esm/generation/format.js

@@ -0,0 +1,17 @@
+import prettier from "prettier";
+import VError from "verror";
+import { makeError } from "../lib/makeError.js";
+export const format = async (ts) => {
+    try {
+        return await prettier.format(ts, {
+            plugins: [],
+            parser: "typescript",
+        });
+    }
+    catch (error) {
+        throw new VError({
+            cause: makeError(error),
+            name: "CodeFormattingError",
+        }, "Failed to format the generated code. This usually happens, when the generated code has syntax errors. Please file an issue.");
+    }
+};

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

@@ -0,0 +1,43 @@
+import { Name } from "./global/Name.js";
+import { Components } from "./components/Components.js";
+import { Paths } from "./paths/Paths.js";
+import { Tag } from "./tags/Tag.js";
+export class CodeGenerationModel {
+    rootNamespace;
+    paths;
+    components;
+    tags;
+    doc;
+    constructor(rootNamespace, doc) {
+        this.rootNamespace = new Name(rootNamespace);
+        this.doc = doc;
+        this.components = new Components(this);
+        this.tags = this.doc.tags?.map((doc) => Tag.fromDoc(doc)) ?? [];
+        this.paths = new Paths(this, this.doc.paths);
+    }
+    static fromDoc(rootNamespace, doc) {
+        return new CodeGenerationModel(rootNamespace, doc);
+    }
+    async compileTypes(opts) {
+        const t = {
+            ns: this.rootNamespace.tsType,
+            components: await this.components.compileTypes(opts),
+            operationTypes: await this.paths.compileOperationTypes(),
+            paths: await this.paths.compileTypes(opts),
+        };
+        return `\
+      import * as descriptors from "./descriptors.js";
+      import { 
+        InferredRequestData, 
+        InferredResponseData, 
+        HttpStatus 
+      } from "@mittwald/api-client-commons";
+
+      export declare module ${t.ns} {
+        ${t.operationTypes}
+        ${t.components}
+        ${t.paths}
+      }
+    `;
+    }
+}

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

@@ -0,0 +1,61 @@
+import { Name } from "../global/Name.js";
+import { Schemas } from "./Schemas.js";
+import { Parameters } from "./Parameters.js";
+import { RequestBodies } from "./RequestBodies.js";
+import { Responses } from "./Responses.js";
+import { SecuritySchemes } from "./SecuritySchemes.js";
+import { extractComponentRefName } from "../../refs/extractComponentRefName.js";
+import { assertNoRefs } from "../../refs/assertNoRefs.js";
+import invariant from "invariant";
+export class Components {
+    static ns = "Components";
+    name;
+    schemas;
+    securitySchemes;
+    parameters;
+    requestBodies;
+    responses;
+    model;
+    constructor(model) {
+        this.model = model;
+        this.name = new Name(Components.ns, model.rootNamespace);
+        this.schemas = new Schemas(this, model.doc.components?.schemas ?? {});
+        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 ?? {});
+        this.responses = new Responses(this, model.doc.components?.responses ?? {});
+    }
+    async compileTypes(opts) {
+        const t = {
+            ns: Components.ns,
+            schemas: await this.schemas.compileTypes(opts),
+            parameters: await this.parameters.compileTypes(opts),
+            requestBodies: await this.requestBodies.compileTypes(opts),
+            responses: await this.responses.compileTypes(opts),
+            securitySchemes: await this.securitySchemes.compileTypes(opts),
+        };
+        return `\
+      namespace ${t.ns} {
+        ${t.schemas}
+        ${t.parameters}
+        ${t.requestBodies}
+        ${t.responses}
+        ${t.securitySchemes}
+      }
+    `;
+    }
+    resolveRef(componentType, obj) {
+        if ("$ref" in obj) {
+            invariant(typeof obj.$ref === "string", "PathItemRefs are not supported by now");
+            const refName = extractComponentRefName(obj.$ref, componentType);
+            const resolved = this.model.doc.components?.[componentType]?.[refName];
+            if (resolved === undefined) {
+                throw new Error(`Could not find ref ${obj.$ref} in components.${componentType}`);
+            }
+            assertNoRefs(resolved);
+            return resolved;
+        }
+        assertNoRefs(obj);
+        return obj;
+    }
+}

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

@@ -0,0 +1,30 @@
+import { JSONSchema } from "../global/JSONSchema.js";
+import { Name } from "../global/Name.js";
+import { asyncStringJoin } from "../../asyncStringJoin.js";
+import { assertNoRefs } from "../../refs/assertNoRefs.js";
+export class Parameters {
+    static ns = "Parameters";
+    components;
+    name;
+    parameters;
+    constructor(components, parametersObject) {
+        this.components = components;
+        this.name = new Name(Parameters.ns, components.name);
+        this.parameters = parametersObject;
+    }
+    async compileTypes(opts) {
+        const schemas = Object.entries(this.parameters).map(([name, param]) => {
+            assertNoRefs(param);
+            return new JSONSchema(new Name(name, this.name), param.schema);
+        });
+        const t = {
+            ns: Parameters.ns,
+            types: await asyncStringJoin(schemas, (schema) => schema.compile(opts)),
+        };
+        return `\
+      namespace ${t.ns} {
+        ${t.types}
+      }
+    `;
+    }
+}

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

@@ -0,0 +1,25 @@
+import { JSONSchema } from "../global/JSONSchema.js";
+import { Name } from "../global/Name.js";
+import { asyncStringJoin } from "../../asyncStringJoin.js";
+export class RequestBodies {
+    static ns = "RequestBodies";
+    schemas;
+    components;
+    name;
+    constructor(components, schemas) {
+        this.components = components;
+        this.name = new Name(RequestBodies.ns, components.name);
+        this.schemas = Object.entries(schemas ?? {}).map(([schemaName, schema]) => new JSONSchema(new Name(schemaName, this.name), schema));
+    }
+    async compileTypes(opts) {
+        const t = {
+            ns: RequestBodies.ns,
+            types: await asyncStringJoin(this.schemas, (schema) => schema.compile(opts)),
+        };
+        return `\
+      namespace ${t.ns} {
+        ${t.types}
+      }
+    `;
+    }
+}

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

@@ -0,0 +1,27 @@
+import { ResponseContent } from "./ResponseContent.js";
+import { asyncStringJoin } from "../../asyncStringJoin.js";
+import invariant from "invariant";
+export class Response {
+    name;
+    responses;
+    contents;
+    constructor(name, responses, mediaTypesDoc) {
+        this.name = name;
+        this.responses = responses;
+        this.contents = Object.entries(mediaTypesDoc).map(([mediaType, mediaTypeObj]) => {
+            invariant(!!mediaTypeObj?.schema, "No schema set");
+            return new ResponseContent(this, mediaType, mediaTypeObj?.schema);
+        });
+    }
+    async compileTypes(opts) {
+        const t = {
+            ns: this.name.tsType,
+            types: await asyncStringJoin(this.contents, (content) => content.schema.compile(opts)),
+        };
+        return `\
+      namespace ${t.ns} {
+        ${t.types}      
+      }    
+    `;
+    }
+}

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

@@ -0,0 +1,12 @@
+import { Name } from "../global/Name.js";
+import { JSONSchema } from "../global/JSONSchema.js";
+export class ResponseContent {
+    mediaType;
+    schema;
+    response;
+    constructor(response, mediaType, schema) {
+        this.mediaType = new Name(mediaType, response.name);
+        this.response = response;
+        this.schema = new JSONSchema(this.mediaType, schema);
+    }
+}

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

@@ -0,0 +1,29 @@
+import { Name } from "../global/Name.js";
+import { asyncStringJoin } from "../../asyncStringJoin.js";
+import { Response } from "./Response.js";
+import { assertNoRefs } from "../../refs/assertNoRefs.js";
+export class Responses {
+    static ns = "Responses";
+    responses;
+    components;
+    name;
+    constructor(components, responses = {}) {
+        this.components = components;
+        this.name = new Name(Responses.ns, components.name);
+        this.responses = Object.entries(responses).map(([name, response]) => {
+            assertNoRefs(response);
+            return new Response(new Name(name, this.name), this, response.content ?? {});
+        });
+    }
+    async compileTypes(opts) {
+        const t = {
+            ns: Responses.ns,
+            types: await asyncStringJoin(this.responses, (response) => response.compileTypes(opts)),
+        };
+        return `\
+      namespace ${t.ns} {
+        ${t.types}
+      }
+    `;
+    }
+}

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

@@ -0,0 +1,25 @@
+import { JSONSchema } from "../global/JSONSchema.js";
+import { Name } from "../global/Name.js";
+import { asyncStringJoin } from "../../asyncStringJoin.js";
+export class Schemas {
+    static ns = "Schemas";
+    schemas;
+    components;
+    name;
+    constructor(components, schemas) {
+        this.components = components;
+        this.name = new Name(Schemas.ns, components.name);
+        this.schemas = Object.entries(schemas ?? {}).map(([schemaName, schema]) => new JSONSchema(new Name(schemaName, this.name), schema));
+    }
+    async compileTypes(opts) {
+        const t = {
+            ns: Schemas.ns,
+            types: await asyncStringJoin(this.schemas, (schema) => schema.compile(opts)),
+        };
+        return `\
+      namespace ${t.ns} {
+        ${t.types}
+      }
+    `;
+    }
+}

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

@@ -0,0 +1,21 @@
+import { Name } from "../global/Name.js";
+import { JSONSchema } from "../global/JSONSchema.js";
+export class SecurityScheme {
+    in;
+    name;
+    jsonSchema;
+    constructor(schemes, name, doc) {
+        this.name = new Name(name, schemes.name);
+        this.in = doc.in;
+        this.jsonSchema = new JSONSchema(this.name, {
+            type: "object",
+            description: doc.description,
+            properties: {
+                [doc.name]: {
+                    type: "string",
+                },
+            },
+            required: [doc.name],
+        });
+    }
+}

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

@@ -0,0 +1,43 @@
+import { Name } from "../global/Name.js";
+import invariant from "invariant";
+import { assertNoRefs } from "../../refs/assertNoRefs.js";
+import { asyncStringJoin } from "../../asyncStringJoin.js";
+import { SecurityScheme } from "./SecurityScheme.js";
+export class SecuritySchemes {
+    static ns = "SecuritySchemes";
+    schemes;
+    components;
+    name;
+    constructor(components, doc = {}) {
+        this.components = components;
+        this.name = new Name(SecuritySchemes.ns, components.name);
+        Object.values(doc).forEach((scheme) => {
+            assertNoRefs(scheme);
+            invariant(scheme.type === "apiKey", `Security scheme type '${scheme.type}' is not supported (allowed types: 'apiKey')`);
+        });
+        this.schemes = Object.entries(doc).map(([name, scheme]) => new SecurityScheme(this, name, scheme));
+    }
+    requireScheme(name) {
+        const scheme = this.schemes.find((s) => s.name.raw === name);
+        invariant(!!scheme, `Required security scheme '${name}' not found`);
+        return scheme;
+    }
+    async compileTypes(opts) {
+        const t = {
+            ns: SecuritySchemes.ns,
+            types: await asyncStringJoin(this.schemes, (scheme) => {
+                const { optionalHeaders } = opts;
+                const mustSetOptionalHeaders = scheme.in === "header" && !!optionalHeaders;
+                const jsonSchema = mustSetOptionalHeaders
+                    ? scheme.jsonSchema.cloneWithOptionalProperties(optionalHeaders)
+                    : scheme.jsonSchema;
+                return jsonSchema.compile(opts);
+            }),
+        };
+        return `\
+      namespace ${t.ns} {
+        ${t.types}      
+      }
+    `;
+    }
+}

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

@@ -0,0 +1,44 @@
+import { compileJsonSchema } from "../../compileJsonSchema.js";
+import { Name } from "./Name.js";
+import cloneDeep from "clone-deep";
+import { componentRefsToCustomTypes } from "../../refs/componentRefsToCustomTypes.js";
+export class JSONSchema {
+    schemaObject;
+    name;
+    constructor(name, data = { type: "any" }) {
+        this.name = name;
+        this.schemaObject = data;
+    }
+    async compile(opts) {
+        const withCustomRefTypes = componentRefsToCustomTypes(opts.rootNamespace, this.schemaObject);
+        return compileJsonSchema(withCustomRefTypes, this.name.tsType);
+    }
+    clone() {
+        return new JSONSchema(new Name(this.name.raw), cloneDeep(this.schemaObject));
+    }
+    cloneWithOptionalProperties(optionalProperties) {
+        const withOptionalProperties = this.clone();
+        this.setOptionalPropertiesInSchema(optionalProperties, withOptionalProperties.schemaObject);
+        return withOptionalProperties;
+    }
+    setOptionalPropertiesInSchema(optionalProperties, schema) {
+        for (const optionalProp of optionalProperties) {
+            const requiredProperties = schema.required;
+            if (Array.isArray(requiredProperties)) {
+                schema.required = requiredProperties.filter((p) => p !== optionalProp);
+            }
+        }
+        for (const subSchema of schema.allOf ?? []) {
+            this.setOptionalPropertiesInSchema(optionalProperties, subSchema);
+        }
+        for (const subSchema of schema.anyOf ?? []) {
+            this.setOptionalPropertiesInSchema(optionalProperties, subSchema);
+        }
+    }
+    asCustomTypeRef() {
+        return {
+            tsType: this.name.tsTypeWithNamespace,
+            type: "object",
+        };
+    }
+}

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

@@ -0,0 +1,20 @@
+import { tsTypeName } from "../../tsTypeName.js";
+import camelcase from "camelcase";
+export class Name {
+    raw;
+    tsType;
+    tsVar;
+    parent;
+    constructor(raw, parent) {
+        this.raw = raw;
+        this.tsType = tsTypeName(raw);
+        this.tsVar = camelcase(this.tsType);
+        this.parent = parent;
+    }
+    get tsTypeWithNamespace() {
+        if (this.parent) {
+            return `${this.parent.tsTypeWithNamespace}.${this.tsType}`;
+        }
+        return this.tsType;
+    }
+}

package/dist/esm/generation/model/global/Name.test.js

@@ -0,0 +1,10 @@
+import { Name } from "./Name.js";
+const parentName = new Name("Parent");
+test("TS variable name is camelcased", () => {
+    const testName = new Name("ChildName");
+    expect(testName.tsVar).toEqual("childName");
+});
+test("Namespaced name includes parent name", () => {
+    const testName = new Name("ChildName", parentName);
+    expect(testName.tsTypeWithNamespace).toEqual("Parent.ChildName");
+});

package/dist/esm/generation/model/paths/Path.js

@@ -0,0 +1,35 @@
+import { Operation } from "./operation/Operation.js";
+import { Name } from "../global/Name.js";
+import { asyncStringJoin } from "../../asyncStringJoin.js";
+import { OpenAPIV3 } from "openapi-types";
+export class Path {
+    paths;
+    name;
+    operations;
+    constructor(paths, name, operationsDoc) {
+        this.paths = paths;
+        this.name = name;
+        this.operations = Object.values(OpenAPIV3.HttpMethods)
+            .map((method) => {
+            const operationDoc = operationsDoc[method];
+            if (operationDoc && operationDoc.deprecated !== true) {
+                return Operation.fromDoc(this, method, operationDoc);
+            }
+        })
+            .filter((o) => !!o);
+    }
+    static fromDoc(paths, name, operationsDoc) {
+        return new Path(paths, new Name(name, paths.name), operationsDoc);
+    }
+    async compileTypes(options) {
+        const t = {
+            ns: this.name.tsType,
+            types: await asyncStringJoin(this.operations, (operation) => operation.compileTypes(options)),
+        };
+        return `\
+      namespace ${t.ns} {
+        ${t.types}
+      }    
+    `;
+    }
+}