@acrool/rtk-query-codegen-openapi 0.0.1

package/src/generate.ts

@@ -0,0 +1,627 @@
+import camelCase from 'lodash.camelcase';
+import path from 'node:path';
+import ApiGenerator, {
+  getOperationName as _getOperationName,
+  getReferenceName,
+  isReference,
+  supportDeepObjects,
+  createPropertyAssignment,
+  createQuestionToken,
+  isValidIdentifier,
+  keywordType,
+} from 'oazapfts/generate';
+import type { OpenAPIV3 } from 'openapi-types';
+import ts from 'typescript';
+import type { ObjectPropertyDefinitions } from './codegen';
+import { generateCreateApiCall, generateEndpointDefinition, generateImportNode, generateTagTypes } from './codegen';
+import { generateReactHooks } from './generators/react-hooks';
+import type {
+  EndpointMatcher,
+  EndpointOverrides,
+  GenerationOptions,
+  OperationDefinition,
+  ParameterDefinition,
+  ParameterMatcher,
+  TextMatcher,
+} from './types';
+import { capitalize, getOperationDefinitions, getV3Doc, removeUndefined, isQuery as testIsQuery } from './utils';
+import { factory } from './utils/factory';
+
+const generatedApiName = 'injectedRtkApi';
+const v3DocCache: Record<string, OpenAPIV3.Document> = {};
+
+// Add IUseFetcherArgs import
+const useFetcherImport = generateImportNode('@acrool/react-fetcher', {
+  IUseFetcherArgs: 'IUseFetcherArgs',
+});
+
+function defaultIsDataResponse(
+  code: string,
+  includeDefault: boolean,
+  response: OpenAPIV3.ResponseObject,
+  allResponses: OpenAPIV3.ResponsesObject
+) {
+  if (includeDefault && code === 'default') {
+    return true;
+  }
+  const parsedCode = Number(code);
+  return !Number.isNaN(parsedCode) && parsedCode >= 200 && parsedCode < 300;
+}
+
+function getOperationName({ verb, path, operation }: Pick<OperationDefinition, 'verb' | 'path' | 'operation'>) {
+  return _getOperationName(verb, path, operation.operationId);
+}
+
+function getTags({ verb, pathItem }: Pick<OperationDefinition, 'verb' | 'pathItem'>): string[] {
+  const tags = verb && pathItem[verb]?.tags ? pathItem[verb].tags : [];
+  return tags.map((tag) => tag.toString());
+}
+
+function patternMatches(pattern?: TextMatcher) {
+  const filters = Array.isArray(pattern) ? pattern : [pattern];
+  return function matcher(operationName: string) {
+    if (!pattern) return true;
+    return filters.some((filter) =>
+      typeof filter === 'string' ? filter === operationName : filter?.test(operationName)
+    );
+  };
+}
+
+function operationMatches(pattern?: EndpointMatcher) {
+  const checkMatch = typeof pattern === 'function' ? pattern : patternMatches(pattern);
+  return function matcher(operationDefinition: OperationDefinition) {
+    if (!pattern) return true;
+    const operationName = getOperationName(operationDefinition);
+    return checkMatch(operationName, operationDefinition);
+  };
+}
+
+function argumentMatches(pattern?: ParameterMatcher) {
+  const checkMatch = typeof pattern === 'function' ? pattern : patternMatches(pattern);
+  return function matcher(argumentDefinition: ParameterDefinition) {
+    if (!pattern || argumentDefinition.in === 'path') return true;
+    const argumentName = argumentDefinition.name;
+    return checkMatch(argumentName, argumentDefinition);
+  };
+}
+
+function withQueryComment<T extends ts.Node>(node: T, def: QueryArgDefinition, hasTrailingNewLine: boolean): T {
+  const comment = def.origin === 'param' ? def.param.description : def.body.description;
+  if (comment) {
+    return ts.addSyntheticLeadingComment(
+      node,
+      ts.SyntaxKind.MultiLineCommentTrivia,
+      `* ${comment} `,
+      hasTrailingNewLine
+    );
+  }
+  return node;
+}
+
+export function getOverrides(
+  operation: OperationDefinition,
+  endpointOverrides?: EndpointOverrides[]
+): EndpointOverrides | undefined {
+  return endpointOverrides?.find((override) => operationMatches(override.pattern)(operation));
+}
+
+export async function generateApi(
+  spec: string,
+  {
+    apiFile,
+    apiImport = 'api',
+    exportName = 'enhancedApi',
+    argSuffix = 'ApiArg',
+    responseSuffix = 'ApiResponse',
+    operationNameSuffix = '',
+    hooks = false,
+    tag = false,
+    outputFile,
+    isDataResponse = defaultIsDataResponse,
+    filterEndpoints,
+    endpointOverrides,
+    unionUndefined,
+    encodePathParams = false,
+    encodeQueryParams = false,
+    flattenArg = false,
+    includeDefault = false,
+    useEnumType = false,
+    mergeReadWriteOnly = false,
+    httpResolverOptions,
+  }: GenerationOptions
+) {
+  const v3Doc = (v3DocCache[spec] ??= await getV3Doc(spec, httpResolverOptions));
+
+  const apiGen = new ApiGenerator(v3Doc, {
+    unionUndefined,
+    useEnumType,
+    mergeReadWriteOnly,
+  });
+
+  // temporary workaround for https://github.com/oazapfts/oazapfts/issues/491
+  if (apiGen.spec.components?.schemas) {
+    apiGen.preprocessComponents(apiGen.spec.components.schemas);
+  }
+
+  const operationDefinitions = getOperationDefinitions(v3Doc).filter(operationMatches(filterEndpoints));
+
+  const resultFile = ts.createSourceFile(
+    'someFileName.ts',
+    '',
+    ts.ScriptTarget.Latest,
+    /*setParentNodes*/ false,
+    ts.ScriptKind.TS
+  );
+  const printer = ts.createPrinter({ newLine: ts.NewLineKind.LineFeed });
+
+  const interfaces: Record<string, ts.InterfaceDeclaration | ts.TypeAliasDeclaration> = {};
+  function registerInterface(declaration: ts.InterfaceDeclaration | ts.TypeAliasDeclaration) {
+    const name = declaration.name.escapedText.toString();
+    if (name in interfaces) {
+      throw new Error(`interface/type alias ${name} already registered`);
+    }
+    interfaces[name] = declaration;
+    return declaration;
+  }
+
+  if (outputFile) {
+    outputFile = path.resolve(process.cwd(), outputFile);
+    if (apiFile.startsWith('.')) {
+      apiFile = path.relative(path.dirname(outputFile), apiFile);
+      apiFile = apiFile.replace(/\\/g, '/');
+      if (!apiFile.startsWith('.')) apiFile = `./${apiFile}`;
+    }
+  }
+  apiFile = apiFile.replace(/\.[jt]sx?$/, '');
+
+  return printer.printNode(
+    ts.EmitHint.Unspecified,
+    factory.createSourceFile(
+      [
+        generateImportNode(apiFile, { [apiImport]: 'api' }),
+        ...(tag ? [generateTagTypes({ addTagTypes: extractAllTagTypes({ operationDefinitions }) })] : []),
+        generateCreateApiCall({
+          tag,
+          endpointDefinitions: factory.createObjectLiteralExpression(
+            operationDefinitions.map((operationDefinition) =>
+              generateEndpoint({
+                operationDefinition,
+                overrides: getOverrides(operationDefinition, endpointOverrides),
+              })
+            ),
+            true
+          ),
+        }),
+        factory.createExportDeclaration(
+          undefined,
+          false,
+          factory.createNamedExports([
+            factory.createExportSpecifier(
+              factory.createIdentifier(generatedApiName),
+              factory.createIdentifier(exportName)
+            ),
+          ]),
+          undefined
+        ),
+        ...Object.values(interfaces),
+        ...apiGen.aliases,
+        ...apiGen.enumAliases,
+        ...(hooks
+          ? [
+              generateReactHooks({
+                exportName: generatedApiName,
+                operationDefinitions,
+                endpointOverrides,
+                config: hooks,
+              }),
+            ]
+          : []),
+      ],
+      factory.createToken(ts.SyntaxKind.EndOfFileToken),
+      ts.NodeFlags.None
+    ),
+    resultFile
+  );
+
+  function extractAllTagTypes({ operationDefinitions }: { operationDefinitions: OperationDefinition[] }) {
+    const allTagTypes = new Set<string>();
+
+    for (const operationDefinition of operationDefinitions) {
+      const { verb, pathItem } = operationDefinition;
+      for (const tag of getTags({ verb, pathItem })) {
+        allTagTypes.add(tag);
+      }
+    }
+    return [...allTagTypes];
+  }
+
+  function generateQueryArgType(operationDefinition: OperationDefinition): ts.TypeNode {
+    const {
+      operation: { parameters = [], requestBody },
+    } = operationDefinition;
+
+    const properties: ts.PropertySignature[] = [];
+
+    // Add body property if needed
+    if (requestBody && !isReference(requestBody)) {
+      const bodySchema = requestBody.content?.['application/json']?.schema;
+      if (bodySchema) {
+        properties.push(
+          factory.createPropertySignature(
+            undefined,
+            factory.createIdentifier('body'),
+            undefined,
+            factory.createTypeReferenceNode(factory.createIdentifier('any'), undefined)
+          )
+        );
+      }
+    }
+
+    // Add params property if needed
+    const queryParams = parameters.filter((p): p is OpenAPIV3.ParameterObject => !isReference(p) && p.in === 'query');
+    if (queryParams.length > 0) {
+      properties.push(
+        factory.createPropertySignature(
+          undefined,
+          factory.createIdentifier('params'),
+          undefined,
+          factory.createTypeLiteralNode(
+            queryParams.map((param) =>
+              factory.createPropertySignature(
+                undefined,
+                factory.createIdentifier(param.name),
+                factory.createToken(ts.SyntaxKind.QuestionToken),
+                factory.createKeywordTypeNode(ts.SyntaxKind.StringKeyword)
+              )
+            )
+          )
+        )
+      );
+    }
+
+    // Add headers property if needed
+    const headerParams = parameters.filter((p): p is OpenAPIV3.ParameterObject => !isReference(p) && p.in === 'header');
+    if (headerParams.length > 0) {
+      properties.push(
+        factory.createPropertySignature(
+          undefined,
+          factory.createIdentifier('headers'),
+          undefined,
+          factory.createTypeLiteralNode(
+            headerParams.map((param) =>
+              factory.createPropertySignature(
+                undefined,
+                factory.createIdentifier(param.name),
+                factory.createToken(ts.SyntaxKind.QuestionToken),
+                factory.createKeywordTypeNode(ts.SyntaxKind.StringKeyword)
+              )
+            )
+          )
+        )
+      );
+    }
+
+    return factory.createTypeLiteralNode([
+      factory.createPropertySignature(
+        undefined,
+        factory.createIdentifier('variables'),
+        undefined,
+        factory.createTypeLiteralNode(properties)
+      ),
+      factory.createPropertySignature(
+        undefined,
+        factory.createIdentifier('fetchOptions'),
+        factory.createToken(ts.SyntaxKind.QuestionToken),
+        factory.createTypeReferenceNode(factory.createIdentifier('any'), undefined)
+      ),
+    ]);
+  }
+
+  function generateQueryArgDefinitions(operationDefinition: OperationDefinition): QueryArgDefinitions {
+    const {
+      operation: { parameters = [], requestBody },
+    } = operationDefinition;
+
+    const queryArg: QueryArgDefinitions = {};
+
+    // Add body definition if needed
+    if (requestBody && !isReference(requestBody)) {
+      const bodySchema = requestBody.content?.['application/json']?.schema;
+      if (bodySchema) {
+        queryArg['body'] = {
+          name: 'body',
+          originalName: 'body',
+          type: factory.createKeywordTypeNode(ts.SyntaxKind.AnyKeyword),
+          required: true,
+          origin: 'body',
+          body: requestBody,
+        };
+      }
+    }
+
+    // Add parameter definitions
+    parameters
+      .filter((p): p is OpenAPIV3.ParameterObject => !isReference(p))
+      .forEach((param) => {
+        queryArg[param.name] = {
+          name: param.name,
+          originalName: param.name,
+          type: factory.createKeywordTypeNode(ts.SyntaxKind.StringKeyword),
+          required: param.required || false,
+          origin: 'param',
+          param,
+        };
+      });
+
+    return queryArg;
+  }
+
+  function generateEndpoint({
+    operationDefinition,
+    overrides,
+  }: {
+    operationDefinition: OperationDefinition;
+    overrides?: EndpointOverrides;
+  }) {
+    const {
+      verb,
+      path,
+      pathItem,
+      operation,
+      operation: { responses, requestBody },
+    } = operationDefinition;
+    const operationName = getOperationName({ verb, path, operation });
+    const tags = tag ? getTags({ verb, pathItem }) : [];
+    const isQuery = testIsQuery(verb, overrides);
+
+    const returnsJson = apiGen.getResponseType(responses) === 'json';
+    let ResponseType: ts.TypeNode = factory.createKeywordTypeNode(ts.SyntaxKind.UnknownKeyword);
+    if (returnsJson) {
+      const returnTypes = Object.entries(responses || {})
+        .map(([code, response]) =>
+          isDataResponse(code, includeDefault, response as OpenAPIV3.ResponseObject, responses as OpenAPIV3.ResponsesObject) && response
+            ? apiGen.getTypeFromResponse(response as OpenAPIV3.ResponseObject)
+            : undefined
+        )
+        .filter(removeUndefined);
+
+      if (returnTypes.length === 1) {
+        ResponseType = returnTypes[0];
+      } else if (returnTypes.length > 1) {
+        ResponseType = factory.createUnionTypeNode(returnTypes);
+      }
+    }
+
+    const QueryArg = generateQueryArgType(operationDefinition);
+    const wrappedQueryArg = factory.createTypeReferenceNode(factory.createIdentifier('IUseFetcherArgs'), [QueryArg]);
+
+    const endpointBuilder = factory.createIdentifier('build');
+
+    const Response = factory.createTypeReferenceNode(
+      factory.createIdentifier(`${capitalize(operationName)}${responseSuffix}`),
+      undefined
+    );
+
+    const queryArgDefinitions = generateQueryArgDefinitions(operationDefinition);
+
+    const extraEndpointsProps = isQuery
+      ? generateQueryEndpointProps({ operationDefinition })
+      : generateMutationEndpointProps({ operationDefinition });
+
+    return generateEndpointDefinition({
+      operationName,
+      type: isQuery ? 'query' : 'mutation',
+      Response,
+      QueryArg: wrappedQueryArg,
+      queryFn: generateQueryFn({
+        operationDefinition,
+        queryArg: queryArgDefinitions,
+        isFlatArg: flattenArg,
+        isQuery,
+        encodePathParams,
+        encodeQueryParams,
+      }),
+      extraEndpointsProps,
+      tags,
+      endpointBuilder,
+    });
+  }
+
+  function generateQueryFn({
+    operationDefinition,
+    queryArg,
+    isFlatArg,
+    isQuery,
+    encodePathParams,
+    encodeQueryParams,
+  }: {
+    operationDefinition: OperationDefinition;
+    queryArg: QueryArgDefinitions;
+    isFlatArg: boolean;
+    isQuery: boolean;
+    encodePathParams: boolean;
+    encodeQueryParams: boolean;
+  }) {
+    const {
+      verb,
+      path,
+      operation: { parameters = [], requestBody },
+    } = operationDefinition;
+
+    const bodyParameter =
+      requestBody && !isReference(requestBody) ? requestBody.content?.['application/json']?.schema : undefined;
+    const bodyArg = bodyParameter ? queryArg['body'] : undefined;
+
+    const pathParameters = parameters
+      .filter((p): p is OpenAPIV3.ParameterObject => !isReference(p) && p.in === 'path')
+      .map((param) => ({
+        name: param.name,
+        originalName: param.name,
+        type: factory.createKeywordTypeNode(ts.SyntaxKind.StringKeyword),
+        required: param.required,
+        param,
+        origin: 'param' as const,
+      }));
+
+    const queryParameters = parameters
+      .filter((p): p is OpenAPIV3.ParameterObject => !isReference(p) && p.in === 'query')
+      .map((param) => ({
+        name: param.name,
+        originalName: param.name,
+        type: factory.createKeywordTypeNode(ts.SyntaxKind.StringKeyword),
+        required: param.required,
+        param,
+        origin: 'param' as const,
+      }));
+
+    const headerParameters = parameters
+      .filter((p): p is OpenAPIV3.ParameterObject => !isReference(p) && p.in === 'header')
+      .map((param) => ({
+        name: param.name,
+        originalName: param.name,
+        type: factory.createKeywordTypeNode(ts.SyntaxKind.StringKeyword),
+        required: param.required,
+        param,
+        origin: 'param' as const,
+      }));
+
+    const rootObject = factory.createIdentifier('queryArg');
+
+    const objectProperties: ts.ObjectLiteralElementLike[] = [
+      factory.createPropertyAssignment(
+        'url',
+        generatePathExpression(path, pathParameters, rootObject, isFlatArg, encodePathParams)
+      ),
+      factory.createPropertyAssignment('method', factory.createStringLiteral(verb.toUpperCase())),
+    ];
+
+    if (bodyArg) {
+      objectProperties.push(
+        factory.createPropertyAssignment(
+          'body',
+          factory.createPropertyAccessExpression(
+            factory.createPropertyAccessExpression(rootObject, factory.createIdentifier('variables')),
+            factory.createIdentifier('body')
+          )
+        )
+      );
+    }
+
+    if (queryParameters.length) {
+      objectProperties.push(
+        factory.createPropertyAssignment(
+          'params',
+          factory.createPropertyAccessExpression(
+            factory.createPropertyAccessExpression(rootObject, factory.createIdentifier('variables')),
+            factory.createIdentifier('params')
+          )
+        )
+      );
+    }
+
+    if (headerParameters.length) {
+      objectProperties.push(
+        factory.createPropertyAssignment(
+          'headers',
+          factory.createPropertyAccessExpression(
+            factory.createPropertyAccessExpression(rootObject, factory.createIdentifier('variables')),
+            factory.createIdentifier('headers')
+          )
+        )
+      );
+    }
+
+    // Add fetchOptions
+    objectProperties.push(
+      factory.createPropertyAssignment(
+        'fetchOptions',
+        factory.createPropertyAccessExpression(rootObject, factory.createIdentifier('fetchOptions'))
+      )
+    );
+
+    return factory.createArrowFunction(
+      undefined,
+      undefined,
+      [factory.createParameterDeclaration(undefined, undefined, rootObject)],
+      undefined,
+      factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken),
+      factory.createParenthesizedExpression(factory.createObjectLiteralExpression(objectProperties, true))
+    );
+  }
+
+  // eslint-disable-next-line no-empty-pattern
+  function generateQueryEndpointProps({}: { operationDefinition: OperationDefinition }): ObjectPropertyDefinitions {
+    return {}; /* TODO needs implementation - skip for now */
+  }
+
+  // eslint-disable-next-line no-empty-pattern
+  function generateMutationEndpointProps({}: { operationDefinition: OperationDefinition }): ObjectPropertyDefinitions {
+    return {}; /* TODO needs implementation - skip for now */
+  }
+}
+
+function accessProperty(rootObject: ts.Identifier, propertyName: string) {
+  return isValidIdentifier(propertyName)
+    ? factory.createPropertyAccessExpression(rootObject, factory.createIdentifier(propertyName))
+    : factory.createElementAccessExpression(rootObject, factory.createStringLiteral(propertyName));
+}
+
+function generatePathExpression(
+  path: string,
+  pathParameters: QueryArgDefinition[],
+  rootObject: ts.Identifier,
+  isFlatArg: boolean,
+  encodePathParams: boolean
+): ts.Expression {
+  const expressions: Array<[string, string]> = [];
+
+  const head = path.replace(/\{(.*?)}(.*?)(?=\{|$)/g, (_, expression, literal) => {
+    const param = pathParameters.find((p) => p.originalName === expression);
+    if (!param) {
+      throw new Error(`path parameter ${expression} does not seem to be defined in '${path}'!`);
+    }
+    expressions.push([param.name, literal]);
+    return '';
+  });
+
+  return expressions.length
+    ? factory.createTemplateExpression(
+        factory.createTemplateHead(head, head),
+        expressions.map(([prop, literal], index) => {
+          const value = factory.createPropertyAccessExpression(
+            factory.createPropertyAccessExpression(rootObject, factory.createIdentifier('variables')),
+            factory.createIdentifier(prop)
+          );
+          const encodedValue = encodePathParams
+            ? factory.createCallExpression(factory.createIdentifier('encodeURIComponent'), undefined, [
+                factory.createCallExpression(factory.createIdentifier('String'), undefined, [value]),
+              ])
+            : value;
+          return factory.createTemplateSpan(
+            encodedValue,
+            index === expressions.length - 1
+              ? factory.createTemplateTail(literal, literal)
+              : factory.createTemplateMiddle(literal, literal)
+          );
+        })
+      )
+    : factory.createStringLiteral(head);
+}
+
+type QueryArgDefinition = {
+  name: string;
+  originalName: string;
+  type: ts.TypeNode;
+  required?: boolean;
+  param?: OpenAPIV3.ParameterObject;
+} & (
+  | {
+      origin: 'param';
+      param: OpenAPIV3.ParameterObject;
+    }
+  | {
+      origin: 'body';
+      body: OpenAPIV3.RequestBodyObject;
+    }
+);
+type QueryArgDefinitions = Record<string, QueryArgDefinition>;