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

package/src/ts-factory/getServiceFactory.ts

@@ -1,6 +1,8 @@
-import { ServiceOperation } from '@openapi-qraft/plugin/lib/open-api/getServices';
+import { ServiceOperation } from '@openapi-qraft/plugin/lib/open-api/OpenAPIService';
 import camelCase from 'camelcase';
 import ts from 'typescript';
+import { createOperationCommonTSDoc } from '../lib/createOperationCommonTSDoc.js';
+import { filterUnusedTypes } from './filterUnusedTypes.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';
@@ -29,6 +31,7 @@ import { createServiceOperationUseQueryNodes } from './service-operation.generat
 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;
 
@@ -36,18 +39,27 @@ export type ServiceImportsFactoryOptions = {
   openapiTypesImportPath: string;
 };
 
+type Service = { typeName: string; variableName: string };
+
 export const getServiceFactory = (
-  service: { typeName: string; variableName: string },
+  service: Service,
   operations: ServiceOperation[],
   { openapiTypesImportPath }: ServiceImportsFactoryOptions
 ) => {
-  return [
-    getOpenAPISchemaImportsFactory(openapiTypesImportPath),
-    ...getServiceOperationImportsFactory(operations),
+  const mainNodes = [
     getServiceInterfaceFactory(service, operations),
     getServiceVariableFactory(service, operations),
     ...getOperationsTypes(operations),
   ];
+
+  const importNodes = [
+    getOpenAPISchemaImportsFactory(openapiTypesImportPath),
+    ...getServiceOperationImportsFactory(
+      filterUnusedTypes(getModuleTypeImports(operations), mainNodes)
+    ),
+  ];
+
+  return [...importNodes, ...mainNodes];
 };
 
 const getOpenAPISchemaImportsFactory = (schemaTypesPath: string) => {
@@ -70,18 +82,11 @@ const getOpenAPISchemaImportsFactory = (schemaTypesPath: string) => {
   );
 };
 
-const getServiceOperationImportsFactory = (operations: ServiceOperation[]) => {
+const getServiceOperationImportsFactory = (
+  moduleImports: Record<string, string[]>
+) => {
   const factory = ts.factory;
 
-  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(
@@ -105,76 +110,78 @@ const getServiceOperationImportsFactory = (operations: ServiceOperation[]) => {
   );
 };
 
-const __getServiceOperationGenericsPathImportsFactory = (
-  operationGenericsPath: string,
-  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(
-                false,
-                undefined,
-                factory.createIdentifier('ServiceOperationQuery')
-              )
-            : 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)
-  );
-};
-
 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) => void addSyntheticLeadingOperationComment(node, operation)
-  );
+
+  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.createTypeLiteralNode([
-      ...replaceGenericTypesWithOperationTypes(operationMethodNodes, operation),
+      ...replaceGenericTypesWithOperationTypes(
+        reduceAreAllOptionalConditionalTParamsType(
+          operationMethodNodes,
+          operation
+        ),
+        operation
+      ),
       factory.createPropertySignature(
         undefined,
         factory.createIdentifier('schema'),
@@ -234,7 +241,7 @@ const getServiceInterfaceOperationFactory = (operation: ServiceOperation) => {
     ])
   );
 
-  addSyntheticLeadingOperationComment(node, operation);
+  addOperationTSDoc(node, operation);
 
   return node;
 };
@@ -260,13 +267,17 @@ const getOperationSchemaFactory = (operation: ServiceOperation) => {
         )
       ),
 
-      operation.mediaType
+      operation.requestBody
         ? factory.createPropertySignature(
             undefined,
             factory.createIdentifier('mediaType'),
             undefined,
-            factory.createLiteralTypeNode(
-              factory.createStringLiteral(operation.mediaType)
+            factory.createTupleTypeNode(
+              Object.keys(operation.requestBody.content).map((mediaType) =>
+                factory.createLiteralTypeNode(
+                  factory.createStringLiteral(mediaType)
+                )
+              )
             )
           )
         : null,
@@ -342,44 +353,57 @@ const getOperationResponseFactory = (
 };
 
 const getOperationBodyFactory = (operation: ServiceOperation) => {
-  if (!operation.mediaType)
+  if (!operation.requestBody)
     return factory.createKeywordTypeNode(ts.SyntaxKind.UndefinedKeyword);
 
-  return factory.createIndexedAccessTypeNode(
-    factory.createIndexedAccessTypeNode(
-      factory.createTypeReferenceNode(factory.createIdentifier('NonNullable'), [
+  const mediaTypes = Object.keys(operation.requestBody.content);
+
+  return factory.createUnionTypeNode([
+    ...mediaTypes.map((mediaType) =>
+      factory.createIndexedAccessTypeNode(
         factory.createIndexedAccessTypeNode(
-          factory.createIndexedAccessTypeNode(
-            factory.createIndexedAccessTypeNode(
-              factory.createTypeReferenceNode(
-                factory.createIdentifier('paths'),
-                undefined
+          factory.createTypeReferenceNode(
+            factory.createIdentifier('NonNullable'),
+            [
+              factory.createIndexedAccessTypeNode(
+                factory.createIndexedAccessTypeNode(
+                  factory.createIndexedAccessTypeNode(
+                    factory.createTypeReferenceNode(
+                      factory.createIdentifier('paths'),
+                      undefined
+                    ),
+                    factory.createLiteralTypeNode(
+                      factory.createStringLiteral(operation.path)
+                    )
+                  ),
+                  factory.createLiteralTypeNode(
+                    factory.createStringLiteral(operation.method)
+                  )
+                ),
+                factory.createLiteralTypeNode(
+                  factory.createStringLiteral('requestBody')
+                )
               ),
-              factory.createLiteralTypeNode(
-                factory.createStringLiteral(operation.path)
-              )
-            ),
-            factory.createLiteralTypeNode(
-              factory.createStringLiteral(operation.method)
-            )
+            ]
           ),
-          factory.createLiteralTypeNode(
-            factory.createStringLiteral('requestBody')
-          )
+          // todo::Add optional NonNullable inference, see `POST /entities/{entity_id}/documents`
+          factory.createLiteralTypeNode(factory.createStringLiteral('content'))
         ),
-      ]),
-      // todo::Add optional NonNullable inference, see `POST /entities/{entity_id}/documents`
-      factory.createLiteralTypeNode(factory.createStringLiteral('content'))
+        factory.createLiteralTypeNode(factory.createStringLiteral(mediaType))
+      )
     ),
-    factory.createLiteralTypeNode(
-      factory.createStringLiteral(operation.mediaType)
-    )
-  );
+    ...(mediaTypes.some((mediaType) => mediaType.includes('/form-data'))
+      ? [factory.createTypeReferenceNode(factory.createIdentifier('FormData'))]
+      : []),
+  ]);
 };
 
-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(
@@ -401,7 +425,7 @@ const getOperationParametersFactory = (operation: ServiceOperation) => {
 };
 
 const getServiceVariableFactory = (
-  { variableName }: { variableName: string },
+  service: Service,
   operations: ServiceOperation[]
 ) => {
   return factory.createVariableStatement(
@@ -409,10 +433,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),
@@ -438,7 +464,7 @@ const getOperationsTypes = (operations: ServiceOperation[]) => {
         undefined,
         factory.createIdentifier(getOperationParametersTypeName(operation)),
         undefined,
-        getOperationParametersFactory(operation)
+        createOperationParametersFactory(operation)
       ),
       factory.createTypeAliasDeclaration(
         undefined,
@@ -499,7 +525,7 @@ const getServiceVariableTypeFactory = (operation: ServiceOperation) => {
     ])
   );
 
-  addSyntheticLeadingOperationComment(node, operation);
+  addOperationTSDoc(node, operation);
 
   return node;
 };
@@ -521,10 +547,14 @@ const getServiceVariablePropertyFactory = (operation: ServiceOperation) => {
                 factory.createIdentifier('url'),
                 factory.createStringLiteral(operation.path)
               ),
-              operation.mediaType
+              operation.requestBody
                 ? factory.createPropertyAssignment(
                     factory.createIdentifier('mediaType'),
-                    factory.createStringLiteral(operation.mediaType)
+                    factory.createArrayLiteralExpression(
+                      Object.keys(operation.requestBody.content).map(
+                        (mediaType) => factory.createStringLiteral(mediaType)
+                      )
+                    )
                   )
                 : null,
 
@@ -566,23 +596,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(
@@ -648,25 +663,36 @@ const getMethodSignatureNodes = (
   );
 };
 
-const getModuleTypeImports = (nodes: ts.Node[]) => {
+/**
+ * Returns a list of all the modules that are imported by the operations.
+ * @param operations
+ * @returns Record<moduleName, importSpecifierNames[]>
+ */
+const getModuleTypeImports = (operations: ServiceOperation[]) => {
+  const nodes = [
+    ...(operations.some((operation) => operation.method === 'get')
+      ? createServicesQueryOperationNodes()
+      : []),
+    ...(operations.some((operation) => operation.method !== 'get')
+      ? createServicesMutationOperationNodes()
+      : []),
+  ];
+
   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;
-    })
+    .map((node) =>
+      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
+    )
     .reduce<Record<string, string[]>>((acc, item) => {
       if (!item) return acc;
       if (!acc[item.module])
@@ -676,10 +702,18 @@ const getModuleTypeImports = (nodes: ts.Node[]) => {
           arrayFilterUniqueCallback
         );
 
+      acc[item.module].sort();
+
       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
@@ -721,6 +755,46 @@ function replaceGenericTypesWithOperationTypes<T extends ts.Node>(
   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?.some((parameter) => parameter.required)) {
+            return node.falseType;
+          } else {
+            return node.trueType;
+          }
+        }
+        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;
 }

package/src/ts-factory/getServiceIndexFactory.ts

@@ -1,10 +1,10 @@
-import { Service } from '@openapi-qraft/plugin/lib/open-api/getServices';
+import { OpenAPIService } from '@openapi-qraft/plugin/lib/open-api/OpenAPIService';
 import ts from 'typescript';
 
-type Options = { explicitImportExtensions: boolean };
+type Options = { explicitImportExtensions: '.js' | '.ts' | undefined };
 
 export const getServiceIndexFactory = (
-  services: Service[],
+  services: OpenAPIService[],
   options: Options
 ) => {
   return [
@@ -14,7 +14,7 @@ export const getServiceIndexFactory = (
   ];
 };
 
-const getServiceIndexInterfaceFactory = (services: Service[]) => {
+const getServiceIndexInterfaceFactory = (services: OpenAPIService[]) => {
   const factory = ts.factory;
 
   return factory.createTypeAliasDeclaration(
@@ -37,7 +37,7 @@ const getServiceIndexInterfaceFactory = (services: Service[]) => {
   );
 };
 
-const getServiceIndexVariableFactory = (services: Service[]) => {
+const getServiceIndexVariableFactory = (services: OpenAPIService[]) => {
   const factory = ts.factory;
 
   return factory.createVariableStatement(
@@ -71,7 +71,7 @@ const getServiceIndexVariableFactory = (services: Service[]) => {
 };
 
 const getServicesImportsFactory = (
-  services: Service[],
+  services: OpenAPIService[],
   { explicitImportExtensions }: Options
 ) => {
   const factory = ts.factory;
@@ -96,7 +96,7 @@ const getServicesImportsFactory = (
         ])
       ),
       factory.createStringLiteral(
-        `./${fileBaseName}${explicitImportExtensions ? '.js' : ''}`
+        `./${fileBaseName}${explicitImportExtensions ?? ''}`
       )
     )
   );