@openapi-qraft/tanstack-query-react-plugin 2.0.0-next.0 → 2.0.0-next.10

package/src/ts-factory/getServiceFactory.ts

@@ -1,32 +1,56 @@
 import { ServiceOperation } from '@openapi-qraft/plugin/lib/open-api/getServices';
+import camelCase from 'camelcase';
 import ts from 'typescript';
-
-const SERVICE_OPERATION_QUERY = 'ServiceOperationQuery';
-const SERVICE_OPERATION_MUTATION = 'ServiceOperationMutation';
+import { createOperationCommonTSDoc } from '../lib/createOperationCommonTSDoc.js';
+import { createServiceOperationCancelQueriesNodes } from './service-operation.generated/ServiceOperationCancelQueries.js';
+import { createServiceOperationFetchInfiniteQueryNodes } from './service-operation.generated/ServiceOperationFetchInfiniteQuery.js';
+import { createServiceOperationFetchQueryNodes } from './service-operation.generated/ServiceOperationFetchQuery.js';
+import { createServiceOperationGetInfiniteQueryDataNodes } from './service-operation.generated/ServiceOperationGetInfiniteQueryData.js';
+import { createServiceOperationGetQueriesDataNodes } from './service-operation.generated/ServiceOperationGetQueriesData.js';
+import { createServiceOperationGetQueryDataNodes } from './service-operation.generated/ServiceOperationGetQueryData.js';
+import { createServiceOperationGetQueryStateNodes } from './service-operation.generated/ServiceOperationGetQueryState.js';
+import { createServiceOperationInvalidateQueriesNodes } from './service-operation.generated/ServiceOperationInvalidateQueries.js';
+import { createServiceOperationIsFetchingQueriesNodes } from './service-operation.generated/ServiceOperationIsFetchingQueries.js';
+import { createServiceOperationIsMutatingQueriesNodes } from './service-operation.generated/ServiceOperationIsMutatingQueries.js';
+import { createServiceOperationMutationFnNodes } from './service-operation.generated/ServiceOperationMutationFn.js';
+import { createServiceOperationQueryFnNodes } from './service-operation.generated/ServiceOperationQueryFn.js';
+import { createServiceOperationRefetchQueriesNodes } from './service-operation.generated/ServiceOperationRefetchQueries.js';
+import { createServiceOperationRemoveQueriesNodes } from './service-operation.generated/ServiceOperationRemoveQueries.js';
+import { createServiceOperationResetQueriesNodes } from './service-operation.generated/ServiceOperationResetQueries.js';
+import { createServiceOperationSetInfiniteQueryDataNodes } from './service-operation.generated/ServiceOperationSetInfiniteQueryData.js';
+import { createServiceOperationSetQueriesDataNodes } from './service-operation.generated/ServiceOperationSetQueriesData.js';
+import { createServiceOperationSetQueryDataNodes } from './service-operation.generated/ServiceOperationSetQueryData.js';
+import { createServiceOperationUseInfiniteQueryNodes } from './service-operation.generated/ServiceOperationUseInfiniteQuery.js';
+import { createServiceOperationUseIsFetchingQueriesNodes } from './service-operation.generated/ServiceOperationUseIsFetchingQueries.js';
+import { createServiceOperationUseIsMutatingNodes } from './service-operation.generated/ServiceOperationUseIsMutating.js';
+import { createServiceOperationUseMutationNodes } from './service-operation.generated/ServiceOperationUseMutation.js';
+import { createServiceOperationUseMutationStateNodes } from './service-operation.generated/ServiceOperationUseMutationState.js';
+import { createServiceOperationUseQueriesNodes } from './service-operation.generated/ServiceOperationUseQueries.js';
+import { createServiceOperationUseQueryNodes } from './service-operation.generated/ServiceOperationUseQuery.js';
+import { createServiceOperationUseSuspenseInfiniteQueryNodes } from './service-operation.generated/ServiceOperationUseSuspenseInfiniteQuery.js';
+import { createServiceOperationUseSuspenseQueriesNodes } from './service-operation.generated/ServiceOperationUseSuspenseQueries.js';
+import { createServiceOperationUseSuspenseQueryNodes } from './service-operation.generated/ServiceOperationUseSuspenseQuery.js';
+import { createOperationMethodTSDocExample } from './tsdoc/createOperationMethodTSDocExample.js';
 
 const factory = ts.factory;
 
 export type ServiceImportsFactoryOptions = {
   openapiTypesImportPath: string;
-  operationGenericsImportPath: string;
 };
 
+type Service = { typeName: string; variableName: string };
+
 export const getServiceFactory = (
-  service: { typeName: string; variableName: string },
+  service: Service,
   operations: ServiceOperation[],
-  {
-    openapiTypesImportPath,
-    operationGenericsImportPath,
-  }: ServiceImportsFactoryOptions
+  { openapiTypesImportPath }: ServiceImportsFactoryOptions
 ) => {
   return [
     getOpenAPISchemaImportsFactory(openapiTypesImportPath),
-    getServiceOperationGenericsPathImportsFactory(
-      operationGenericsImportPath,
-      operations
-    ),
+    ...getServiceOperationImportsFactory(operations),
     getServiceInterfaceFactory(service, operations),
     getServiceVariableFactory(service, operations),
+    ...getOperationsTypes(operations),
   ];
 };
 
@@ -50,86 +74,173 @@ const getOpenAPISchemaImportsFactory = (schemaTypesPath: string) => {
   );
 };
 
-const getServiceOperationGenericsPathImportsFactory = (
-  operationGenericsPath: string,
-  operations: ServiceOperation[]
-) => {
+const getServiceOperationImportsFactory = (operations: ServiceOperation[]) => {
   const factory = ts.factory;
 
-  const queryMethods = ['get', 'head', 'options'] as const; // todo::make it shared
-
-  return factory.createImportDeclaration(
-    undefined,
-    factory.createImportClause(
-      true,
-      undefined,
-      factory.createNamedImports(
-        [
-          operations.some((operation) =>
-            queryMethods.some((method) => method === operation.method)
-          )
-            ? factory.createImportSpecifier(
+  const moduleImports = getModuleTypeImports([
+    ...(operations.some((operation) => operation.method === 'get')
+      ? createServicesQueryOperationNodes()
+      : []),
+    ...(operations.some((operation) => operation.method !== 'get')
+      ? createServicesMutationOperationNodes()
+      : []),
+  ]);
+
+  return Object.entries(moduleImports).map(
+    ([moduleName, importSpecifierNames]) => {
+      return factory.createImportDeclaration(
+        undefined,
+        factory.createImportClause(
+          true,
+          undefined,
+          factory.createNamedImports(
+            importSpecifierNames.map((specifier) =>
+              factory.createImportSpecifier(
                 false,
                 undefined,
-                factory.createIdentifier('ServiceOperationQuery')
+                factory.createIdentifier(specifier)
               )
-            : null,
-          operations.some(
-            (operation) =>
-              !queryMethods.some((method) => method === operation.method)
+            )
           )
-            ? factory.createImportSpecifier(
-                false,
-                undefined,
-                factory.createIdentifier('ServiceOperationMutation')
-              )
-            : null,
-        ].filter((node): node is NonNullable<typeof node> => Boolean(node))
-      )
-    ),
-    factory.createStringLiteral(operationGenericsPath)
+        ),
+        factory.createStringLiteral(moduleName)
+      );
+    }
   );
 };
 
 const getServiceInterfaceFactory = (
-  { typeName }: { typeName: string },
+  service: Service,
   operations: ServiceOperation[]
 ) => {
   return factory.createInterfaceDeclaration(
     [factory.createToken(ts.SyntaxKind.ExportKeyword)],
-    factory.createIdentifier(typeName),
+    factory.createIdentifier(service.typeName),
     undefined,
     undefined,
-    operations.map(getServiceInterfaceOperationFactory)
+    operations.map((operation) =>
+      getServiceInterfaceOperationFactory(operation, service)
+    )
   );
 };
 
-const getServiceInterfaceOperationFactory = (operation: ServiceOperation) => {
+const getServiceInterfaceOperationFactory = (
+  operation: ServiceOperation,
+  service: Service
+) => {
+  const operationMethodNodes = getMethodSignatureNodes(
+    operation.method === 'get'
+      ? createServicesQueryOperationNodes()
+      : createServicesMutationOperationNodes()
+  );
+
+  operationMethodNodes.forEach((node) => {
+    if (
+      ts.isMethodSignature(node) &&
+      ts.isIdentifier(node.name) &&
+      node.name.text
+    ) {
+      const operationCustomTSDoc = createOperationMethodTSDocExample(
+        operation,
+        {
+          serviceVariableName: service.variableName,
+          operationMethodName: node.name.text,
+        }
+      );
+      // Query and Mutation methods (hooks and QueryClient methods)
+      ts.addSyntheticLeadingComment(
+        node,
+        ts.SyntaxKind.MultiLineCommentTrivia,
+        createMultilineComment(
+          operationCustomTSDoc
+            ? operationCustomTSDoc
+            : createOperationCommonTSDoc(operation)
+        ),
+        true
+      );
+    } else if (ts.isCallSignatureDeclaration(node)) {
+      // Query and Mutation functions (invoke methods)
+      ts.addSyntheticLeadingComment(
+        node,
+        ts.SyntaxKind.MultiLineCommentTrivia,
+        createMultilineComment([...createOperationCommonTSDoc(operation)]),
+        true
+      );
+    }
+  });
+
   const node = factory.createPropertySignature(
     undefined,
     factory.createIdentifier(operation.name),
     undefined,
-    factory.createTypeReferenceNode(
-      factory.createIdentifier(
-        operation.method === 'get'
-          ? SERVICE_OPERATION_QUERY
-          : SERVICE_OPERATION_MUTATION
+    factory.createTypeLiteralNode([
+      ...replaceGenericTypesWithOperationTypes(
+        reduceAreAllOptionalConditionalTParamsType(
+          operationMethodNodes,
+          operation
+        ),
+        operation
       ),
-      [
-        getOperationSchemaFactory(operation),
-
-        operation.method !== 'get' ? getOperationBodyFactory(operation) : null,
-
-        getOperationResponseFactory(operation, 'success'),
-
-        getOperationParametersFactory(operation),
-
-        getOperationResponseFactory(operation, 'errors'),
-      ].filter((node): node is NonNullable<typeof node> => Boolean(node))
-    )
+      factory.createPropertySignature(
+        undefined,
+        factory.createIdentifier('schema'),
+        undefined,
+        factory.createTypeReferenceNode(
+          getOperationSchemaTypeName(operation),
+          undefined
+        )
+      ),
+      factory.createPropertySignature(
+        undefined,
+        factory.createIdentifier('types'),
+        undefined,
+        factory.createTypeLiteralNode(
+          [
+            factory.createPropertySignature(
+              undefined,
+              factory.createIdentifier('parameters'),
+              undefined,
+              factory.createTypeReferenceNode(
+                getOperationParametersTypeName(operation),
+                undefined
+              )
+            ),
+            factory.createPropertySignature(
+              undefined,
+              factory.createIdentifier('data'),
+              undefined,
+              factory.createTypeReferenceNode(
+                getOperationDataTypeName(operation),
+                undefined
+              )
+            ),
+            factory.createPropertySignature(
+              undefined,
+              factory.createIdentifier('error'),
+              undefined,
+              factory.createTypeReferenceNode(
+                getOperationErrorTypeName(operation),
+                undefined
+              )
+            ),
+            operation.method !== 'get'
+              ? factory.createPropertySignature(
+                  undefined,
+                  factory.createIdentifier('body'),
+                  undefined,
+                  factory.createTypeReferenceNode(
+                    getOperationBodyTypeName(operation),
+                    undefined
+                  )
+                )
+              : undefined,
+          ].filter((node) => !!node)
+        )
+      ),
+    ])
   );
 
-  addSyntheticLeadingOperationComment(node, operation);
+  addOperationTSDoc(node, operation);
 
   return node;
 };
@@ -272,9 +383,12 @@ const getOperationBodyFactory = (operation: ServiceOperation) => {
   );
 };
 
-const getOperationParametersFactory = (operation: ServiceOperation) => {
-  if (!operation.parameters)
-    return factory.createKeywordTypeNode(ts.SyntaxKind.UndefinedKeyword);
+const createOperationParametersFactory = (operation: ServiceOperation) => {
+  if (!operation.parameters?.length)
+    return operation.method === 'get'
+      ? factory.createKeywordTypeNode(ts.SyntaxKind.UndefinedKeyword)
+      : // mutation with predefined parameters fallback to an empty object
+        factory.createTypeLiteralNode([]);
 
   return factory.createIndexedAccessTypeNode(
     factory.createIndexedAccessTypeNode(
@@ -296,7 +410,7 @@ const getOperationParametersFactory = (operation: ServiceOperation) => {
 };
 
 const getServiceVariableFactory = (
-  { variableName }: { variableName: string },
+  service: Service,
   operations: ServiceOperation[]
 ) => {
   return factory.createVariableStatement(
@@ -304,10 +418,12 @@ const getServiceVariableFactory = (
     factory.createVariableDeclarationList(
       [
         factory.createVariableDeclaration(
-          factory.createIdentifier(variableName),
+          factory.createIdentifier(service.variableName),
           undefined,
           factory.createTypeLiteralNode(
-            operations.map(getServiceVariableTypeFactory)
+            operations.map((operation) =>
+              getServiceVariableTypeFactory(operation)
+            )
           ),
           factory.createObjectLiteralExpression(
             operations.map(getServiceVariablePropertyFactory),
@@ -320,6 +436,65 @@ const getServiceVariableFactory = (
   );
 };
 
+const getOperationsTypes = (operations: ServiceOperation[]) => {
+  return operations.flatMap((operation) => {
+    const nodes = [
+      factory.createTypeAliasDeclaration(
+        undefined,
+        factory.createIdentifier(getOperationSchemaTypeName(operation)),
+        undefined,
+        getOperationSchemaFactory(operation)
+      ),
+      factory.createTypeAliasDeclaration(
+        undefined,
+        factory.createIdentifier(getOperationParametersTypeName(operation)),
+        undefined,
+        createOperationParametersFactory(operation)
+      ),
+      factory.createTypeAliasDeclaration(
+        undefined,
+        factory.createIdentifier(getOperationDataTypeName(operation)),
+        undefined,
+        getOperationResponseFactory(operation, 'success')
+      ),
+      factory.createTypeAliasDeclaration(
+        undefined,
+        factory.createIdentifier(getOperationErrorTypeName(operation)),
+        undefined,
+        getOperationResponseFactory(operation, 'errors')
+      ),
+    ];
+
+    if (operation.method !== 'get') {
+      nodes.push(
+        factory.createTypeAliasDeclaration(
+          undefined,
+          factory.createIdentifier(getOperationBodyTypeName(operation)),
+          undefined,
+          getOperationBodyFactory(operation)
+        )
+      );
+    }
+
+    return nodes;
+  });
+};
+
+const getOperationSchemaTypeName = (operation: ServiceOperation) =>
+  camelCase(`${operation.name}-Schema`, { pascalCase: true });
+
+const getOperationParametersTypeName = (operation: ServiceOperation) =>
+  camelCase(`${operation.name}-Parameters`, { pascalCase: true });
+
+const getOperationDataTypeName = (operation: ServiceOperation) =>
+  camelCase(`${operation.name}-Data`, { pascalCase: true });
+
+const getOperationErrorTypeName = (operation: ServiceOperation) =>
+  camelCase(`${operation.name}-Error`, { pascalCase: true });
+
+const getOperationBodyTypeName = (operation: ServiceOperation) =>
+  camelCase(`${operation.name}-Body`, { pascalCase: true });
+
 const getServiceVariableTypeFactory = (operation: ServiceOperation) => {
   const node = factory.createPropertySignature(
     undefined,
@@ -335,7 +510,7 @@ const getServiceVariableTypeFactory = (operation: ServiceOperation) => {
     ])
   );
 
-  addSyntheticLeadingOperationComment(node, operation);
+  addOperationTSDoc(node, operation);
 
   return node;
 };
@@ -402,23 +577,8 @@ const createMultilineComment = (comment: string[]) => {
   return '';
 };
 
-const createOperationComment = (operation: ServiceOperation) => {
-  return createMultilineComment(
-    [
-      operation.deprecated ? '@deprecated' : null,
-      operation.summary ? `@summary ${operation.summary}` : null,
-      operation.description ? `@description ${operation.description}` : null,
-    ].filter((comment): comment is NonNullable<typeof comment> =>
-      Boolean(comment)
-    )
-  );
-};
-
-const addSyntheticLeadingOperationComment = (
-  node: ts.Node,
-  operation: ServiceOperation
-) => {
-  const comment = createOperationComment(operation);
+const addOperationTSDoc = (node: ts.Node, operation: ServiceOperation) => {
+  const comment = createMultilineComment(createOperationCommonTSDoc(operation));
 
   if (comment)
     ts.addSyntheticLeadingComment(
@@ -435,3 +595,177 @@ const getOperationSecuritySchemas = (
   security.flatMap((security) =>
     Object.keys(security).map((securitySchemaName) => securitySchemaName)
   );
+
+const createServicesQueryOperationNodes = () => [
+  ...createServiceOperationCancelQueriesNodes(),
+  ...createServiceOperationUseQueryNodes(),
+  ...createServiceOperationFetchInfiniteQueryNodes(),
+  ...createServiceOperationFetchQueryNodes(),
+  ...createServiceOperationGetInfiniteQueryDataNodes(),
+  ...createServiceOperationGetQueriesDataNodes(),
+  ...createServiceOperationGetQueryDataNodes(),
+  ...createServiceOperationGetQueryStateNodes(),
+  ...createServiceOperationInvalidateQueriesNodes(),
+  ...createServiceOperationIsFetchingQueriesNodes(),
+  ...createServiceOperationQueryFnNodes(),
+  ...createServiceOperationRefetchQueriesNodes(),
+  ...createServiceOperationRemoveQueriesNodes(),
+  ...createServiceOperationResetQueriesNodes(),
+  ...createServiceOperationSetInfiniteQueryDataNodes(),
+  ...createServiceOperationSetQueriesDataNodes(),
+  ...createServiceOperationSetQueryDataNodes(),
+  ...createServiceOperationUseInfiniteQueryNodes(),
+  ...createServiceOperationUseIsFetchingQueriesNodes(),
+  ...createServiceOperationUseQueriesNodes(),
+  ...createServiceOperationUseQueryNodes(),
+  ...createServiceOperationUseSuspenseInfiniteQueryNodes(),
+  ...createServiceOperationUseSuspenseQueriesNodes(),
+  ...createServiceOperationUseSuspenseQueryNodes(),
+];
+
+const createServicesMutationOperationNodes = () => [
+  ...createServiceOperationUseMutationNodes(),
+  ...createServiceOperationUseIsMutatingNodes(),
+  ...createServiceOperationIsMutatingQueriesNodes(),
+  ...createServiceOperationMutationFnNodes(),
+  ...createServiceOperationUseMutationStateNodes(),
+];
+
+const getMethodSignatureNodes = (
+  nodes: ts.Node[]
+): (ts.MethodSignature | ts.CallSignatureDeclaration)[] => {
+  return nodes.flatMap((node) =>
+    ts.isInterfaceDeclaration(node)
+      ? node.members.filter(
+          (node) =>
+            ts.isMethodSignature(node) || ts.isCallSignatureDeclaration(node)
+        )
+      : []
+  );
+};
+
+const getModuleTypeImports = (nodes: ts.Node[]) => {
+  return nodes
+    .map((node) => {
+      const foo =
+        ts.isImportDeclaration(node) &&
+        ts.isStringLiteral(node.moduleSpecifier) &&
+        node.importClause?.isTypeOnly &&
+        node.importClause.namedBindings &&
+        ts.isNamedImports(node.importClause.namedBindings)
+          ? {
+              module: node.moduleSpecifier.text,
+              imports: node.importClause.namedBindings.elements
+                .filter(ts.isImportSpecifier)
+                .map((specifier) => specifier.name.text),
+            }
+          : undefined;
+
+      return foo;
+    })
+    .reduce<Record<string, string[]>>((acc, item) => {
+      if (!item) return acc;
+      if (!acc[item.module])
+        acc[item.module] = item.imports.filter(arrayFilterUniqueCallback);
+      else
+        acc[item.module] = [...acc[item.module], ...item.imports].filter(
+          arrayFilterUniqueCallback
+        );
+
+      return acc;
+    }, {});
+};
+
+/**
+ * Replaces generic types with operation types with named types.
+ *
+ * For example, replaces `TParams` and `TQueryFnData` will be
+ * replaced with `GetEntitiesSchemaParameters` and `GetEntitiesSchemaData`.
+ */
+function replaceGenericTypesWithOperationTypes<T extends ts.Node>(
+  node: T[],
+  operation: ServiceOperation
+): T[] {
+  const transformer =
+    (context: ts.TransformationContext) => (rootNode: ts.Node) => {
+      function visit(node: ts.Node): ts.Node {
+        if (ts.isTypeReferenceNode(node) && ts.isIdentifier(node.typeName)) {
+          let newTypeName;
+
+          if (node.typeName.text === 'TSchema')
+            newTypeName = getOperationSchemaTypeName(operation);
+          else if (node.typeName.text === 'TParams')
+            newTypeName = getOperationParametersTypeName(operation);
+          else if (
+            node.typeName.text === 'TQueryFnData' ||
+            node.typeName.text === 'TMutationData'
+          )
+            newTypeName = getOperationDataTypeName(operation);
+          else if (node.typeName.text === 'TError')
+            newTypeName = getOperationErrorTypeName(operation);
+          else if (node.typeName.text === 'TBody')
+            newTypeName = getOperationBodyTypeName(operation);
+
+          if (newTypeName) {
+            return ts.factory.createTypeReferenceNode(
+              ts.factory.createIdentifier(newTypeName),
+              node.typeArguments
+            );
+          }
+        }
+        return ts.visitEachChild(node, visit, context);
+      }
+      return ts.visitNode(rootNode, visit);
+    };
+
+  const result = ts.transform(node, [transformer]);
+
+  return result.transformed as T[];
+}
+
+/**
+ * Replaces `AreAllOptional<TParams>` with `TParams | void` if `TParams` is optional,
+ * and  with `TParams` when at least one parameter is required.
+ */
+function reduceAreAllOptionalConditionalTParamsType<T extends ts.Node>(
+  node: T[],
+  operation: ServiceOperation
+): T[] {
+  const transformer =
+    (context: ts.TransformationContext) => (rootNode: ts.Node) => {
+      function visit(node: ts.Node): ts.Node {
+        if (
+          ts.isConditionalTypeNode(node) &&
+          ts.isTypeReferenceNode(node.checkType) &&
+          ts.isIdentifier(node.checkType.typeName) &&
+          node.checkType.typeName.text === 'AreAllOptional' &&
+          node.checkType.typeArguments?.every((node) => {
+            return (
+              ts.isTypeReferenceNode(node) &&
+              ts.isIdentifier(node.typeName) &&
+              node.typeName.text === 'TParams'
+            );
+          })
+        ) {
+          if (
+            !operation.parameters?.length ||
+            operation.parameters.every((parameter) => !parameter.required)
+          ) {
+            return node.trueType;
+          } else {
+            return node.falseType;
+          }
+        }
+        return ts.visitEachChild(node, visit, context);
+      }
+      return ts.visitNode(rootNode, visit);
+    };
+
+  const result = ts.transform(node, [transformer]);
+
+  return result.transformed as T[];
+}
+
+function arrayFilterUniqueCallback<T>(value: T, index: number, self: T[]) {
+  return self.indexOf(value) === index;
+}