@mittwald/api-code-generator 0.0.0-development-04b7288-20240610 → 0.0.0-development-7c0a25b-20240611

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

@@ -0,0 +1,192 @@
+import { Name } from "../global/Name.js";
+import { Path } from "./Path.js";
+import { asyncStringJoin } from "../../asyncStringJoin.js";
+import camelcase from "camelcase";
+export class Paths {
+    static ns = "Paths";
+    paths;
+    model;
+    name;
+    constructor(model, paths) {
+        this.model = model;
+        this.name = new Name(Paths.ns, model.rootNamespace);
+        this.paths = Object.entries(paths ?? {})
+            .map(([name, pathDoc]) => {
+            if (pathDoc) {
+                return Path.fromDoc(this, name, pathDoc);
+            }
+        })
+            .filter((p) => !!p);
+    }
+    async compileTypes(opts) {
+        const t = {
+            ns: Paths.ns,
+            types: await asyncStringJoin(this.paths, (path) => path.compileTypes(opts)),
+        };
+        return `\
+      namespace ${t.ns} {
+        ${t.types}
+      }
+    `;
+    }
+    async compileOperationTypes() {
+        const t = {
+            types: this.getFlattenedOperations()
+                .map((operation) => operation.compileRequestResponseTypes())
+                .join("\r\n"),
+        };
+        return `
+      namespace Operations {
+        ${t.types}      
+      }
+    `;
+    }
+    compileDescriptors() {
+        const t = {
+            ns: this.model.rootNamespace.tsType,
+            descriptors: this.getFlattenedOperations()
+                .map((operation) => operation.compileDescriptor())
+                .join("\r\n"),
+        };
+        return `\
+      import { Simplify } from "@mittwald/api-client-commons";
+      import { RequestType } from "@mittwald/api-client-commons";
+      import { Response } from "@mittwald/api-client-commons";
+      import { OpenAPIOperation } from "@mittwald/api-client-commons";    
+      import { ${t.ns} } from "./types.js";
+      
+      ${t.descriptors}
+    `;
+    }
+    getFlattenedOperations(httpMethod) {
+        return this.paths
+            .flatMap((p) => p.operations)
+            .filter((p) => httpMethod === undefined ||
+            p.httpMethod.raw.toLowerCase() === httpMethod.toLowerCase());
+    }
+    getGroupedOperationsByTag(httpMethod) {
+        const result = new Map();
+        for (const operation of this.getFlattenedOperations(httpMethod)) {
+            for (const tag of operation.tags) {
+                const operationsOfTag = result.get(tag);
+                if (operationsOfTag) {
+                    operationsOfTag.push(operation);
+                }
+                else {
+                    result.set(tag, [operation]);
+                }
+            }
+        }
+        return Array.from(result.entries());
+    }
+    compileClientMethodsOfTag(tag, operations) {
+        const t = {
+            tag: tag.name.tsVar,
+            comment: tag.description,
+            methods: operations
+                .map((op) => op.compileClientMethod(tag))
+                .join(",\r\n"),
+        };
+        return `\
+      /** ${t.comment} */
+      public readonly ${t.tag} = {
+        ${t.methods}      
+      }
+    `;
+    }
+    compileClient() {
+        const t = {
+            clientClassName: `${this.model.rootNamespace.tsType}Client`,
+            methods: this.getGroupedOperationsByTag()
+                .map(([tag, operations]) => this.compileClientMethodsOfTag(tag, operations))
+                .join("\r\n"),
+        };
+        return `\
+      import * as descriptors from "./descriptors.js";
+      import { ApiClientBase } from "@mittwald/api-client-commons";
+
+      export class ${t.clientClassName} extends ApiClientBase {
+        ${t.methods}
+      }
+      
+      export default ${t.clientClassName}
+    `;
+    }
+    compileReactClientApiName(tag) {
+        return `build${camelcase(tag.name.tsVar, {
+            pascalCase: true,
+        })}Api`;
+    }
+    compileReactClientApiBuilderOfTag(baseClientClassName, tag, operations) {
+        const t = {
+            apiName: this.compileReactClientApiName(tag),
+            methods: operations
+                .map((op) => op.compileReactClientMethod(tag))
+                .join(",\r\n"),
+            baseClientClassName,
+        };
+        return `\
+      const ${t.apiName} = (baseClient: ${t.baseClientClassName}) => ({
+        ${t.methods}      
+      })
+    `;
+    }
+    compileReactClientPropertyInitializer(tag) {
+        const tagName = tag.name.tsVar;
+        const t = {
+            apiName: this.compileReactClientApiName(tag),
+            comment: tag.description,
+        };
+        return `\
+      this.${tagName} = ${t.apiName}(baseClient);
+    `;
+    }
+    compileReactClientProperties(tag) {
+        const tagName = tag.name.tsVar;
+        const t = {
+            apiName: this.compileReactClientApiName(tag),
+            comment: tag.description,
+        };
+        return `\
+      /** ${t.comment} */
+      public readonly ${tagName}: ReturnType<typeof ${t.apiName}>;
+    `;
+    }
+    compileReactClient() {
+        const baseClientClassName = `${this.model.rootNamespace.tsType}Client`;
+        const clientClassName = `${this.model.rootNamespace.tsType}ClientReact`;
+        const t = {
+            baseClientClassName,
+            clientClassName,
+            apiBuilder: this.getGroupedOperationsByTag("GET")
+                .map(([tag, operations]) => this.compileReactClientApiBuilderOfTag(baseClientClassName, tag, operations))
+                .join("\r\n"),
+            clientProperties: this.getGroupedOperationsByTag("GET")
+                .map(([tag]) => this.compileReactClientProperties(tag))
+                .join("\r\n"),
+            clientPropertyInitializers: this.getGroupedOperationsByTag("GET")
+                .map(([tag]) => this.compileReactClientPropertyInitializer(tag))
+                .join("\r\n"),
+        };
+        return `\
+      import ${t.baseClientClassName} from "./client.js";
+      import { ApiCallAsyncResourceFactory } from "@mittwald/api-client-commons/react";
+      import * as descriptors from "./descriptors.js";
+      export * from "@mittwald/react-use-promise";
+      
+      ${t.apiBuilder}   
+      
+      export class ${t.clientClassName} {
+        ${t.clientProperties}
+        
+        private constructor(baseClient: ${t.baseClientClassName}) {
+          ${t.clientPropertyInitializers}
+        }
+        
+        public static fromBaseClient(baseClient: ${t.baseClientClassName}): ${t.clientClassName} {
+          return new ${t.clientClassName}(baseClient);        
+        }
+      }
+    `;
+    }
+}

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

@@ -0,0 +1,108 @@
+import { RequestParameters } from "./RequestParameters.js";
+import { Name } from "../../global/Name.js";
+import { Responses } from "./responses/Responses.js";
+export class Operation {
+    path;
+    id;
+    httpMethod;
+    parameters;
+    responses;
+    summary;
+    tags;
+    constructor(path, httpMethod, doc) {
+        const fallbackId = `${httpMethod.raw}-${path.name.raw}`;
+        this.id = new Name(doc.operationId ?? fallbackId);
+        this.path = path;
+        this.httpMethod = httpMethod;
+        this.parameters = RequestParameters.fromDoc(this, doc);
+        this.responses = new Responses(this, doc.responses);
+        this.summary = doc.summary;
+        this.tags =
+            doc.tags
+                ?.map((name) => path.paths.model.tags.find((t) => t.name.raw === name))
+                .filter((t) => !!t) ?? [];
+    }
+    static fromDoc(path, httpMethod, doc) {
+        return new Operation(path, new Name(httpMethod, path.name), doc);
+    }
+    async compileTypes(options) {
+        const t = {
+            ns: this.httpMethod.tsType,
+            parameters: await this.parameters.compileTypes(options),
+            responses: await this.responses.compileTypes(options),
+        };
+        return `\
+      namespace ${t.ns} {
+        ${t.parameters};
+        ${t.responses};
+      }
+    `;
+    }
+    compileDescriptor() {
+        const t = {
+            constName: this.id.tsVar,
+            requestType: this.parameters.compileDescriptorRequestType(),
+            responseTypes: this.responses.compileDescriptorTypes(),
+            path: this.path.name.raw,
+            method: this.httpMethod.raw.toUpperCase(),
+            operationId: this.id.raw,
+        };
+        return `\
+        /** ${this.summary} */        
+        export const ${t.constName}: OpenAPIOperation<
+          ${t.requestType},
+          ${t.responseTypes}
+        > = {
+          path: "${t.path}",
+          method: "${t.method}",
+          operationId: "${t.operationId}",
+        };
+    `;
+    }
+    compileRequestResponseTypes() {
+        const t = {
+            ns: this.id.tsType,
+            descriptor: this.id.tsVar,
+        };
+        return `\
+        namespace ${t.ns} {
+          type RequestData = InferredRequestData<typeof descriptors.${t.descriptor}>;
+          type ResponseData<TStatus extends HttpStatus = 200> = InferredResponseData<typeof descriptors.${t.descriptor}, TStatus>;
+        }
+    `;
+    }
+    getMethodName(tag) {
+        const methodName = this.id.tsVar;
+        return new Name(methodName.startsWith(tag.name.tsVar)
+            ? methodName.substring(tag.name.tsVar.length)
+            : methodName).tsVar;
+    }
+    compileClientMethod(tag) {
+        const methodName = this.getMethodName(tag);
+        const t = {
+            methodName,
+            descriptorName: this.id.tsVar,
+        };
+        return `\
+      /** ${this.summary} */        
+      ${t.methodName}: this.requestFunctionFactory(
+        descriptors.${t.descriptorName}
+      )
+    `;
+    }
+    compileReactClientMethod(tag) {
+        const methodName = this.getMethodName(tag);
+        const t = {
+            methodName,
+            descriptorName: this.id.tsVar,
+            tag: tag.name.tsVar,
+        };
+        return `\
+      /** ${this.summary} */        
+      ${t.methodName}: new ApiCallAsyncResourceFactory(
+        descriptors.${t.descriptorName},
+        baseClient.${t.tag}.${t.methodName}
+      ).getApiResource
+    `;
+    }
+}

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

@@ -0,0 +1,98 @@
+import { JSONSchema } from "../../global/JSONSchema.js";
+import { Name } from "../../global/Name.js";
+import { isRef } from "../../../refs/isRef.js";
+import invariant from "invariant";
+export class RequestParameters {
+    static ns = "Parameters";
+    path;
+    query;
+    header;
+    body;
+    operation;
+    constructor(operation, body, path, query, header) {
+        this.operation = operation;
+        this.path = path;
+        this.query = query;
+        this.header = header;
+        this.body = body;
+    }
+    static constructParametersSchema(components, name, $in, parameters = [], securitySchemes) {
+        const properties = {};
+        const required = [];
+        for (const parameter of parameters) {
+            const resolvedParameter = components.resolveRef("parameters", parameter);
+            if (resolvedParameter.in === $in) {
+                const jsonSchemaObject = isRef(parameter)
+                    ? parameter
+                    : parameter.schema;
+                invariant(!!jsonSchemaObject, `Could not find schema for request parameter ${name.raw}`);
+                properties[resolvedParameter.name] = jsonSchemaObject;
+                if (resolvedParameter.required) {
+                    required.push(resolvedParameter.name);
+                }
+            }
+        }
+        const securitySchemesJSONSchemas = securitySchemes
+            .filter((s) => s.in === $in)
+            .map((s) => s.jsonSchema.asCustomTypeRef());
+        const jsonSchemaObject = {
+            allOf: [
+                { type: "object", required, properties },
+                ...securitySchemesJSONSchemas,
+            ],
+        };
+        return new JSONSchema(new Name($in, name), jsonSchemaObject);
+    }
+    static fromDoc(operation, doc) {
+        const name = new Name(RequestParameters.ns, operation.httpMethod);
+        const requestBodySchema = doc.requestBody &&
+            "content" in doc.requestBody &&
+            "application/json" in doc.requestBody.content
+            ? doc.requestBody.content["application/json"].schema
+            : doc.requestBody;
+        const body = requestBodySchema
+            ? new JSONSchema(new Name("requestBody", name), requestBodySchema)
+            : undefined;
+        const requiredSecuritySchemeNames = doc.security?.flatMap((obj) => Object.keys(obj)) ?? [];
+        const requiredSecuritySchemes = requiredSecuritySchemeNames.map((name) => operation.path.paths.model.components.securitySchemes.requireScheme(name));
+        const components = operation.path.paths.model.components;
+        const path = RequestParameters.constructParametersSchema(components, name, "path", doc.parameters, requiredSecuritySchemes);
+        const header = RequestParameters.constructParametersSchema(components, name, "header", doc.parameters, requiredSecuritySchemes);
+        const query = RequestParameters.constructParametersSchema(components, name, "query", doc.parameters, requiredSecuritySchemes);
+        return new RequestParameters(operation, body, path, query, header);
+    }
+    async compileTypes(opts) {
+        const header = this.header?.cloneWithOptionalProperties(opts.optionalHeaders ?? []);
+        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)) ?? "",
+        };
+        return `\
+      namespace ${t.ns} {
+        ${t.path}
+        ${t.body}
+        ${t.header}
+        ${t.query}
+      }      
+    `;
+    }
+    compileDescriptorRequestType() {
+        const t = {
+            body: this.body?.name.tsTypeWithNamespace ?? "null",
+            path: this.path?.name.tsTypeWithNamespace ?? "null",
+            header: this.header?.name.tsTypeWithNamespace ?? "null",
+            query: this.query?.name.tsTypeWithNamespace ?? "null",
+        };
+        return `\
+      RequestType<
+        Simplify<${t.body}>,
+        Simplify<${t.path}>,
+        Simplify<${t.query}>,
+        Simplify<${t.header}>
+      >      
+    `;
+    }
+}

package/dist/esm/generation/model/paths/operation/responses/Response.js

@@ -0,0 +1,25 @@
+import { ResponseContentTypes } from "./ResponseContentTypes.js";
+export class Response {
+    responses;
+    contentTypes;
+    httpStatus;
+    constructor(responses, httpStatus, doc) {
+        this.responses = responses;
+        this.httpStatus = httpStatus;
+        this.contentTypes = new ResponseContentTypes(this, doc);
+    }
+    static fromDoc(responses, httpStatus, doc) {
+        return new Response(responses, httpStatus, doc);
+    }
+    async compileContentTypes(opts) {
+        const t = {
+            ns: this.httpStatus.tsType,
+            types: await this.contentTypes.compileTypes(opts),
+        };
+        return `\
+      namespace ${this.httpStatus.tsType} {
+        ${t.types}
+      }    
+    `;
+    }
+}

package/dist/esm/generation/model/paths/operation/responses/ResponseContent.js

@@ -0,0 +1,31 @@
+import { JSONSchema } from "../../../global/JSONSchema.js";
+import { Name } from "../../../global/Name.js";
+export class ResponseContent {
+    mediaType;
+    schema;
+    contentTypes;
+    constructor(contentTypes, mediaType, schema) {
+        this.mediaType = new Name(mediaType, contentTypes.name);
+        this.schema = new JSONSchema(this.mediaType, schema);
+        this.contentTypes = contentTypes;
+    }
+    static buildEmpty(contentTypes) {
+        return new ResponseContent(contentTypes, "empty");
+    }
+    compileDescriptorsResponseContentType() {
+        const t = {
+            type: this.mediaType.tsTypeWithNamespace,
+            httpStatus: this.contentTypes.response.httpStatus.raw === "default"
+                ? '"default"'
+                : this.contentTypes.response.httpStatus.raw,
+            mediaType: this.mediaType.raw,
+        };
+        return `\
+      Response<
+        Simplify<${t.type}>,
+        ${t.httpStatus},
+        "${t.mediaType}"
+      >
+    `;
+    }
+}

package/dist/esm/generation/model/paths/operation/responses/ResponseContentTypes.js

@@ -0,0 +1,47 @@
+import { Name } from "../../../global/Name.js";
+import { ResponseContent } from "./ResponseContent.js";
+import { asyncStringJoin } from "../../../../asyncStringJoin.js";
+import invariant from "invariant";
+export class ResponseContentTypes {
+    static ns = "Content";
+    contentTypes;
+    name;
+    response;
+    constructor(response, responseDoc) {
+        this.response = response;
+        this.name = new Name(ResponseContentTypes.ns, response.httpStatus);
+        this.contentTypes =
+            "content" in responseDoc
+                ? this.buildContentTypesFromResponseObject(responseDoc)
+                : "$ref" in responseDoc
+                    ? this.buildContentTypesFromReferenceObject(responseDoc)
+                    : [ResponseContent.buildEmpty(this)];
+    }
+    buildContentTypesFromResponseObject(doc) {
+        return Object.entries(doc.content ?? {}).map(([mediaType, mediaTypeObject]) => new ResponseContent(this, mediaType, mediaTypeObject.schema));
+    }
+    buildContentTypesFromReferenceObject(doc) {
+        const responseComponents = this.response.responses.operation.path.paths.model.components.responses
+            .responses;
+        const referencedResponse = responseComponents.find((r) => `#/components/responses/${r.name.raw}` === doc.$ref);
+        invariant(!!referencedResponse, `Referenced response ${doc.$ref} not found`);
+        return referencedResponse.contents.map((c) => new ResponseContent(this, c.mediaType.raw, c.schema));
+    }
+    compileDescriptorTypes() {
+        return this.contentTypes
+            .flatMap((contentType) => contentType.compileDescriptorsResponseContentType())
+            .filter((s) => s !== "")
+            .join(" | ");
+    }
+    async compileTypes(opts) {
+        const t = {
+            ns: ResponseContentTypes.ns,
+            types: await asyncStringJoin(this.contentTypes, (contentType) => contentType.schema.compile(opts)),
+        };
+        return `\
+      namespace ${t.ns} {
+        ${t.types}
+      }    
+    `;
+    }
+}

package/dist/esm/generation/model/paths/operation/responses/Responses.js

@@ -0,0 +1,31 @@
+import { Name } from "../../../global/Name.js";
+import { asyncStringJoin } from "../../../../asyncStringJoin.js";
+import { Response } from "./Response.js";
+export class Responses {
+    static ns = "Responses";
+    responses;
+    operation;
+    name;
+    constructor(operation, responses) {
+        this.operation = operation;
+        this.name = new Name(Responses.ns, operation.httpMethod);
+        this.responses = Object.entries(responses ?? {}).map(([name, response]) => Response.fromDoc(this, new Name(name, this.name), response));
+    }
+    async compileTypes(opts) {
+        const t = {
+            responses: await asyncStringJoin(this.responses, (response) => response.compileContentTypes(opts)),
+            ns: Responses.ns,
+        };
+        return `\
+      namespace ${t.ns} {
+        ${t.responses}
+      }
+    `;
+    }
+    compileDescriptorTypes() {
+        return this.responses
+            .flatMap((response) => response.contentTypes.compileDescriptorTypes())
+            .filter((s) => s !== "")
+            .join(" | ");
+    }
+}

package/dist/esm/generation/model/tags/Tag.js

@@ -0,0 +1,12 @@
+import { Name } from "../global/Name.js";
+export class Tag {
+    name;
+    description;
+    constructor(name, description) {
+        this.name = name;
+        this.description = description;
+    }
+    static fromDoc(doc) {
+        return new Tag(new Name(doc.name), doc.description);
+    }
+}

package/dist/esm/generation/prepareTypeScriptOutput.js

@@ -0,0 +1,10 @@
+import { format } from "./format.js";
+const header = `\
+/* eslint-disable */
+/* prettier-ignore */
+/* This file is auto-generated with acg (@mittwald/api-code-generator) */
+`;
+export const prepareTypeScriptOutput = async (content) => {
+    const formatted = await format(content);
+    return header + formatted;
+};

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

@@ -0,0 +1,6 @@
+import { isRef } from "./isRef.js";
+export function assertNoRefs(obj) {
+    if (isRef(obj)) {
+        throw new Error(`$ref's are not supported here (ref: ${obj.$ref})`);
+    }
+}

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

@@ -0,0 +1,33 @@
+import { refNameToTSName } from "./refNameToTSName.js";
+import is from "@sindresorhus/is";
+import cloneDeep from "clone-deep";
+const getComponentRef = (something) => {
+    if ("$ref" in something &&
+        typeof something.$ref === "string" &&
+        something.$ref.startsWith("#/components/")) {
+        return something.$ref;
+    }
+};
+export const componentRefsToCustomTypes = (rootNamespace, something, clone = true) => {
+    if (clone) {
+        something = cloneDeep(something);
+    }
+    if (!is.nonEmptyObject(something)) {
+        return something;
+    }
+    if (is.array(something)) {
+        return something.map((item) => componentRefsToCustomTypes(rootNamespace, item, false));
+    }
+    const componentRef = getComponentRef(something);
+    if (componentRef !== undefined) {
+        // see https://github.com/bcherny/json-schema-to-typescript#custom-schema-properties
+        return {
+            tsType: refNameToTSName(rootNamespace, componentRef),
+            type: "object",
+        };
+    }
+    return Object.fromEntries(Object.entries(something).map(([key, value]) => [
+        key,
+        componentRefsToCustomTypes(rootNamespace, value, false),
+    ]));
+};

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

@@ -0,0 +1,44 @@
+import { componentRefsToCustomTypes } from "./componentRefsToCustomTypes.js";
+test.each([
+    [
+        {
+            $ref: "#/components/foo/bar",
+        },
+        {
+            type: "object",
+            tsType: "Test.Components.Foo.Bar",
+        },
+    ],
+    [
+        {
+            $ref: "#/no/component",
+        },
+        {
+            $ref: "#/no/component",
+        },
+    ],
+    [
+        {
+            noRef: "No fun",
+        },
+        {
+            noRef: "No fun",
+        },
+    ],
+    [
+        {
+            nested: {
+                $ref: "#/components/foo/bar",
+            },
+        },
+        {
+            nested: {
+                type: "object",
+                tsType: "Test.Components.Foo.Bar",
+            },
+        },
+    ],
+])("componentRefsToCustomTypes works for test %#", (input, expected) => {
+    const result = componentRefsToCustomTypes("test", input);
+    expect(result).toMatchObject(expected);
+});

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

@@ -0,0 +1,8 @@
+import { splitRefNamespaces } from "./splitRefNamespaces.js";
+export const extractComponentRefName = (ref, component) => {
+    const parts = splitRefNamespaces(ref);
+    if (parts[parts.length - 2] === component) {
+        return parts[parts.length - 1];
+    }
+    throw new Error(`Could not extract ref name (component: ${component}, ref: ${ref})`);
+};

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

@@ -0,0 +1,3 @@
+export function isRef(obj) {
+    return "$ref" in obj && typeof obj.$ref === "string";
+}

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

@@ -0,0 +1,3 @@
+import { splitRefNamespaces } from "./splitRefNamespaces.js";
+import { tsNamespaceName } from "../tsNamespaceName.js";
+export const refNameToTSName = (rootNamespace, $ref) => tsNamespaceName(rootNamespace, ...splitRefNamespaces($ref));

package/dist/esm/generation/refs/refNameToTSName.test.js

@@ -0,0 +1,9 @@
+import { refNameToTSName } from "./refNameToTSName.js";
+test.each([
+    ["#/foo/bar", "Test.Foo.Bar"],
+    ["foo", "Test.Foo"],
+    ["#/", "Test"],
+])("splitRefNamespaces works for test %#", (input, expected) => {
+    const result = refNameToTSName("Test", input);
+    expect(result).toEqual(expected);
+});

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

@@ -0,0 +1 @@
+export const splitRefNamespaces = ($ref) => $ref.split("/").filter((ns) => ns !== "#" && ns !== "");