@openapi-qraft/tanstack-query-react-plugin 2.4.1 → 2.5.0-beta.1

package/src/ts-factory/getServiceFactory.ts

@@ -1,3 +1,4 @@
+import { isReadOnlyOperation } from '@openapi-qraft/plugin/lib/isReadOnlyOperation';
 import { ServiceOperation } from '@openapi-qraft/plugin/lib/open-api/OpenAPIService';
 import camelCase from 'camelcase';
 import ts from 'typescript';
@@ -35,8 +36,9 @@ import { createOperationMethodTSDocExample } from './tsdoc/createOperationMethod
 
 const factory = ts.factory;
 
-export type ServiceImportsFactoryOptions = {
+export type ServiceFactoryOptions = {
   openapiTypesImportPath: string;
+  queryableWriteOperations: boolean;
 };
 
 type Service = { typeName: string; variableName: string };
@@ -44,18 +46,18 @@ type Service = { typeName: string; variableName: string };
 export const getServiceFactory = (
   service: Service,
   operations: ServiceOperation[],
-  { openapiTypesImportPath }: ServiceImportsFactoryOptions
+  options: ServiceFactoryOptions
 ) => {
   const mainNodes = [
-    getServiceInterfaceFactory(service, operations),
+    getServiceInterfaceFactory(service, operations, options),
     getServiceVariableFactory(service, operations),
-    ...getOperationsTypes(operations),
+    ...getOperationsTypes(operations, options),
   ];
 
   const importNodes = [
-    getOpenAPISchemaImportsFactory(openapiTypesImportPath),
+    getOpenAPISchemaImportsFactory(options.openapiTypesImportPath),
     ...getServiceOperationImportsFactory(
-      filterUnusedTypes(getModuleTypeImports(operations), mainNodes)
+      filterUnusedTypes(getModuleTypeImports(operations, options), mainNodes)
     ),
   ];
 
@@ -112,7 +114,8 @@ const getServiceOperationImportsFactory = (
 
 const getServiceInterfaceFactory = (
   service: Service,
-  operations: ServiceOperation[]
+  operations: ServiceOperation[],
+  options: Pick<ServiceFactoryOptions, 'queryableWriteOperations'>
 ) => {
   return factory.createInterfaceDeclaration(
     [factory.createToken(ts.SyntaxKind.ExportKeyword)],
@@ -120,19 +123,27 @@ const getServiceInterfaceFactory = (
     undefined,
     undefined,
     operations.map((operation) =>
-      getServiceInterfaceOperationFactory(operation, service)
+      getServiceInterfaceOperationFactory(operation, service, options)
     )
   );
 };
 
 const getServiceInterfaceOperationFactory = (
   operation: ServiceOperation,
-  service: Service
+  service: Service,
+  options: Pick<ServiceFactoryOptions, 'queryableWriteOperations'>
 ) => {
   const operationMethodNodes = getMethodSignatureNodes(
-    operation.method === 'get'
-      ? createServicesQueryOperationNodes()
-      : createServicesMutationOperationNodes()
+    isReadOnlyOperation(operation)
+      ? createServicesQueryOperationNodes({ omitOperationQueryFnNodes: false })
+      : options.queryableWriteOperations
+        ? [
+            ...createServicesQueryOperationNodes({
+              omitOperationQueryFnNodes: true,
+            }),
+            ...createServicesMutationOperationNodes(),
+          ]
+        : createServicesMutationOperationNodes()
   );
 
   operationMethodNodes.forEach((node) => {
@@ -146,7 +157,8 @@ const getServiceInterfaceOperationFactory = (
         {
           serviceVariableName: service.variableName,
           operationMethodName: node.name.text,
-        }
+        },
+        options
       );
       // Query and Mutation methods (hooks and QueryClient methods)
       ts.addSyntheticLeadingComment(
@@ -176,11 +188,16 @@ const getServiceInterfaceOperationFactory = (
     undefined,
     factory.createTypeLiteralNode([
       ...replaceGenericTypesWithOperationTypes(
-        reduceAreAllOptionalConditionalTParamsType(
-          operationMethodNodes,
+        reduceAreAllOptionalConditionalTVariablesType(
+          reduceAreAllOptionalConditionalTParamsType(
+            operationMethodNodes,
+            operation,
+            options
+          ),
           operation
         ),
-        operation
+        operation,
+        options
       ),
       factory.createPropertySignature(
         undefined,
@@ -202,7 +219,11 @@ const getServiceInterfaceOperationFactory = (
               factory.createIdentifier('parameters'),
               undefined,
               factory.createTypeReferenceNode(
-                getOperationParametersTypeName(operation),
+                getOperationParametersTypeName(
+                  operation,
+                  options,
+                  isReadOnlyOperation(operation) ? 'query' : 'mutation'
+                ),
                 undefined
               )
             ),
@@ -224,7 +245,7 @@ const getServiceInterfaceOperationFactory = (
                 undefined
               )
             ),
-            operation.method !== 'get'
+            !isReadOnlyOperation(operation) || operation.requestBody
               ? factory.createPropertySignature(
                   undefined,
                   factory.createIdentifier('body'),
@@ -362,31 +383,36 @@ const getOperationBodyFactory = (operation: ServiceOperation) => {
     ...mediaTypes.map((mediaType) =>
       factory.createIndexedAccessTypeNode(
         factory.createIndexedAccessTypeNode(
-          factory.createTypeReferenceNode(
-            factory.createIdentifier('NonNullable'),
-            [
+          (() => {
+            const requestBodyNode = factory.createIndexedAccessTypeNode(
               factory.createIndexedAccessTypeNode(
                 factory.createIndexedAccessTypeNode(
-                  factory.createIndexedAccessTypeNode(
-                    factory.createTypeReferenceNode(
-                      factory.createIdentifier('paths'),
-                      undefined
-                    ),
-                    factory.createLiteralTypeNode(
-                      factory.createStringLiteral(operation.path)
-                    )
+                  factory.createTypeReferenceNode(
+                    factory.createIdentifier('paths'),
+                    undefined
                   ),
                   factory.createLiteralTypeNode(
-                    factory.createStringLiteral(operation.method)
+                    factory.createStringLiteral(operation.path)
                   )
                 ),
                 factory.createLiteralTypeNode(
-                  factory.createStringLiteral('requestBody')
+                  factory.createStringLiteral(operation.method)
                 )
               ),
-            ]
-          ),
-          // todo::Add optional NonNullable inference, see `POST /entities/{entity_id}/documents`
+              factory.createLiteralTypeNode(
+                factory.createStringLiteral('requestBody')
+              )
+            );
+
+            if (!operation.requestBody?.required) {
+              return factory.createTypeReferenceNode(
+                factory.createIdentifier('NonNullable'),
+                [requestBodyNode]
+              );
+            }
+
+            return requestBodyNode;
+          })(),
           factory.createLiteralTypeNode(factory.createStringLiteral('content'))
         ),
         factory.createLiteralTypeNode(factory.createStringLiteral(mediaType))
@@ -398,39 +424,63 @@ const getOperationBodyFactory = (operation: ServiceOperation) => {
   ]);
 };
 
-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(
-          ['query', 'header', 'path'].map((name) =>
-            factory.createPropertySignature(
-              undefined,
-              factory.createIdentifier(name),
-              factory.createToken(ts.SyntaxKind.QuestionToken),
-              factory.createKeywordTypeNode(ts.SyntaxKind.NeverKeyword)
+const createOperationParametersFactory = (
+  operation: ServiceOperation,
+  withRequestBody: boolean
+) => {
+  if (isReadOnlyOperation(operation) && !operation.parameters?.length) {
+    return factory.createKeywordTypeNode(ts.SyntaxKind.UndefinedKeyword);
+  }
+
+  const parametersNodes = operation.parameters?.length
+    ? 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('parameters'))
+      )
+    : factory.createTypeLiteralNode(
+        ['query', 'header', 'path'].map((name) =>
+          factory.createPropertySignature(
+            undefined,
+            factory.createIdentifier(name),
+            factory.createToken(ts.SyntaxKind.QuestionToken),
+            factory.createKeywordTypeNode(ts.SyntaxKind.NeverKeyword)
+          )
+        )
+      );
 
-  return factory.createIndexedAccessTypeNode(
-    factory.createIndexedAccessTypeNode(
-      factory.createIndexedAccessTypeNode(
+  if (!withRequestBody || !operation.requestBody) {
+    return parametersNodes;
+  }
+
+  return factory.createIntersectionTypeNode([
+    parametersNodes,
+    factory.createTypeLiteralNode([
+      factory.createPropertySignature(
+        undefined,
+        factory.createIdentifier('body'),
+        operation.requestBody.required
+          ? undefined
+          : factory.createToken(ts.SyntaxKind.QuestionToken),
         factory.createTypeReferenceNode(
-          factory.createIdentifier('paths'),
+          factory.createIdentifier(getOperationBodyTypeName(operation)),
           undefined
-        ),
-        factory.createLiteralTypeNode(
-          factory.createStringLiteral(operation.path)
         )
       ),
-      factory.createLiteralTypeNode(
-        factory.createStringLiteral(operation.method)
-      )
-    ),
-    factory.createLiteralTypeNode(factory.createStringLiteral('parameters'))
-  );
+    ]),
+  ]);
 };
 
 const getServiceVariableFactory = (
@@ -460,7 +510,10 @@ const getServiceVariableFactory = (
   );
 };
 
-const getOperationsTypes = (operations: ServiceOperation[]) => {
+const getOperationsTypes = (
+  operations: ServiceOperation[],
+  options: Pick<ServiceFactoryOptions, 'queryableWriteOperations'>
+) => {
   return operations.flatMap((operation) => {
     const nodes = [
       factory.createTypeAliasDeclaration(
@@ -469,12 +522,39 @@ const getOperationsTypes = (operations: ServiceOperation[]) => {
         undefined,
         getOperationSchemaFactory(operation)
       ),
-      factory.createTypeAliasDeclaration(
-        undefined,
-        factory.createIdentifier(getOperationParametersTypeName(operation)),
-        undefined,
-        createOperationParametersFactory(operation)
-      ),
+      ...(isSeparateParametersOperation(operation, options)
+        ? [
+            factory.createTypeAliasDeclaration(
+              undefined,
+              factory.createIdentifier(
+                getOperationParametersTypeName(operation, options, 'query')
+              ),
+              undefined,
+              createOperationParametersFactory(operation, true)
+            ),
+            factory.createTypeAliasDeclaration(
+              undefined,
+              factory.createIdentifier(
+                getOperationParametersTypeName(operation, options, 'mutation')
+              ),
+              undefined,
+              createOperationParametersFactory(operation, false)
+            ),
+          ]
+        : [
+            factory.createTypeAliasDeclaration(
+              undefined,
+              factory.createIdentifier(
+                getOperationParametersTypeName(
+                  operation,
+                  options,
+                  isReadOnlyOperation(operation) ? 'query' : 'mutation'
+                )
+              ),
+              undefined,
+              createOperationParametersFactory(operation, false)
+            ),
+          ]),
       factory.createTypeAliasDeclaration(
         undefined,
         factory.createIdentifier(getOperationDataTypeName(operation)),
@@ -489,7 +569,7 @@ const getOperationsTypes = (operations: ServiceOperation[]) => {
       ),
     ];
 
-    if (operation.method !== 'get') {
+    if (!isReadOnlyOperation(operation) || operation.requestBody) {
       nodes.push(
         factory.createTypeAliasDeclaration(
           undefined,
@@ -507,8 +587,29 @@ const getOperationsTypes = (operations: ServiceOperation[]) => {
 const getOperationSchemaTypeName = (operation: ServiceOperation) =>
   camelCase(`${operation.name}-Schema`, { pascalCase: true });
 
-const getOperationParametersTypeName = (operation: ServiceOperation) =>
-  camelCase(`${operation.name}-Parameters`, { pascalCase: true });
+const getOperationParametersTypeName = (
+  operation: ServiceOperation,
+  options: Pick<ServiceFactoryOptions, 'queryableWriteOperations'>,
+  desiredPrefix: 'query' | 'mutation'
+) => {
+  const operationPurpose = isSeparateParametersOperation(operation, options)
+    ? `-${desiredPrefix}`
+    : '';
+
+  return camelCase(`${operation.name}${operationPurpose}-Parameters`, {
+    pascalCase: true,
+  });
+};
+
+const isSeparateParametersOperation = (
+  operation: ServiceOperation,
+  options: Pick<ServiceFactoryOptions, 'queryableWriteOperations'>
+) =>
+  Boolean(
+    options.queryableWriteOperations &&
+      operation.requestBody &&
+      !isReadOnlyOperation(operation)
+  );
 
 const getOperationDataTypeName = (operation: ServiceOperation) =>
   camelCase(`${operation.name}-Data`, { pascalCase: true });
@@ -624,7 +725,11 @@ const getOperationSecuritySchemas = (
     Object.keys(security).map((securitySchemaName) => securitySchemaName)
   );
 
-const createServicesQueryOperationNodes = () => [
+const createServicesQueryOperationNodes = ({
+  omitOperationQueryFnNodes,
+}: {
+  omitOperationQueryFnNodes: boolean;
+}) => [
   ...createServiceOperationCancelQueriesNodes(),
   ...createServiceOperationUseQueryNodes(),
   ...createServiceOperationFetchInfiniteQueryNodes(),
@@ -635,7 +740,7 @@ const createServicesQueryOperationNodes = () => [
   ...createServiceOperationGetQueryStateNodes(),
   ...createServiceOperationInvalidateQueriesNodes(),
   ...createServiceOperationIsFetchingQueriesNodes(),
-  ...createServiceOperationQueryFnNodes(),
+  ...(omitOperationQueryFnNodes ? [] : createServiceOperationQueryFnNodes()),
   ...createServiceOperationRefetchQueriesNodes(),
   ...createServiceOperationRemoveQueriesNodes(),
   ...createServiceOperationResetQueriesNodes(),
@@ -674,18 +779,29 @@ const getMethodSignatureNodes = (
 
 /**
  * Returns a list of all the modules that are imported by the operations.
- * @param operations
+ * @param operations The list of service operations to analyze
+ * @param options Options for controlling module imports generation.Options for controlling module imports generation.
  * @returns Record<moduleName, importSpecifierNames[]>
  */
-const getModuleTypeImports = (operations: ServiceOperation[]) => {
-  const nodes = [
-    ...(operations.some((operation) => operation.method === 'get')
-      ? createServicesQueryOperationNodes()
-      : []),
-    ...(operations.some((operation) => operation.method !== 'get')
-      ? createServicesMutationOperationNodes()
-      : []),
-  ];
+const getModuleTypeImports = (
+  operations: ServiceOperation[],
+  options: Pick<ServiceFactoryOptions, 'queryableWriteOperations'>
+) => {
+  const nodes = [];
+
+  const hasReadOnlyOperations = operations.some(isReadOnlyOperation);
+
+  if (hasReadOnlyOperations || options.queryableWriteOperations) {
+    nodes.push(
+      ...createServicesQueryOperationNodes({
+        omitOperationQueryFnNodes: !hasReadOnlyOperations,
+      })
+    );
+  }
+
+  if (operations.some((operation) => !isReadOnlyOperation(operation))) {
+    nodes.push(...createServicesMutationOperationNodes());
+  }
 
   return nodes
     .map((node) =>
@@ -720,12 +836,13 @@ const getModuleTypeImports = (operations: ServiceOperation[]) => {
 /**
  * Replaces generic types with operation types with named types.
  *
- * For example, replaces `TParams` and `TQueryFnData` will be
+ * For example, replaces `TQueryParams` and `TQueryFnData` will be
  * replaced with `GetEntitiesSchemaParameters` and `GetEntitiesSchemaData`.
  */
 function replaceGenericTypesWithOperationTypes<T extends ts.Node>(
   node: T[],
-  operation: ServiceOperation
+  operation: ServiceOperation,
+  options: Pick<ServiceFactoryOptions, 'queryableWriteOperations'>
 ): T[] {
   const transformer =
     (context: ts.TransformationContext) => (rootNode: ts.Node) => {
@@ -735,8 +852,18 @@ function replaceGenericTypesWithOperationTypes<T extends ts.Node>(
 
           if (node.typeName.text === 'TSchema')
             newTypeName = getOperationSchemaTypeName(operation);
-          else if (node.typeName.text === 'TParams')
-            newTypeName = getOperationParametersTypeName(operation);
+          else if (node.typeName.text === 'TQueryParams')
+            newTypeName = getOperationParametersTypeName(
+              operation,
+              options,
+              'query'
+            );
+          else if (node.typeName.text === 'TMutationParams')
+            newTypeName = getOperationParametersTypeName(
+              operation,
+              options,
+              'mutation'
+            );
           else if (
             node.typeName.text === 'TOperationQueryFnData' ||
             node.typeName.text === 'TMutationData'
@@ -765,10 +892,55 @@ function replaceGenericTypesWithOperationTypes<T extends ts.Node>(
 }
 
 /**
- * Replaces `AreAllOptional<TParams>` with `TParams | void` if `TParams` is optional,
- * and  with `TParams` when at least one parameter is required.
+ * Replaces `AreAllOptional<TQueryParams>` with `TQueryParams | void` if `TQueryParams` is optional,
+ * and with `TQueryParams` when at least one parameter or `body` (when --queryable-write-operations enabled) is required.
  */
 function reduceAreAllOptionalConditionalTParamsType<T extends ts.Node>(
+  node: T[],
+  operation: ServiceOperation,
+  options: Pick<ServiceFactoryOptions, 'queryableWriteOperations'>
+): 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 === 'TQueryParams'
+            );
+          })
+        ) {
+          if (
+            operation.parameters?.some((parameter) => parameter.required) ||
+            (options.queryableWriteOperations &&
+              operation.requestBody?.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[];
+}
+
+/**
+ * Replaces `AreAllOptional<TVariables>` with `TVariables | void` if `TVariables` is optional,
+ * and with `TVariables` when `body` is required.
+ */
+function reduceAreAllOptionalConditionalTVariablesType<T extends ts.Node>(
   node: T[],
   operation: ServiceOperation
 ): T[] {
@@ -784,11 +956,11 @@ function reduceAreAllOptionalConditionalTParamsType<T extends ts.Node>(
             return (
               ts.isTypeReferenceNode(node) &&
               ts.isIdentifier(node.typeName) &&
-              node.typeName.text === 'TParams'
+              node.typeName.text === 'TVariables'
             );
           })
         ) {
-          if (operation.parameters?.some((parameter) => parameter.required)) {
+          if (operation.requestBody?.required) {
             return node.falseType;
           } else {
             return node.trueType;

package/src/ts-factory/tsdoc/createOperationMethodTSDocExample.ts

@@ -1,4 +1,5 @@
 import { ServiceOperation } from '@openapi-qraft/plugin/lib/open-api/OpenAPIService';
+import { ServiceFactoryOptions } from '../getServiceFactory.js';
 import { createUseInfiniteQueryOperationTSDocExample } from './createUseInfiniteQueryOperationTSDocExample.js';
 import { createUseIsFetchingOperationTSDocExample } from './createUseIsFetchingOperationTSDocExample.js';
 import { createUseIsMutatingOperationTSDocExample } from './createUseIsMutatingOperationTSDocExample.js';
@@ -18,18 +19,21 @@ export const createOperationMethodTSDocExample = (
   }: {
     serviceVariableName: string;
     operationMethodName: string;
-  }
+  },
+  options: Pick<ServiceFactoryOptions, 'queryableWriteOperations'>
 ) => {
   switch (operationMethodName) {
     case 'useQuery':
       return createUseQueryOperationTSDocExample(
         operation,
-        serviceVariableName
+        serviceVariableName,
+        options
       );
     case 'useSuspenseQuery':
       return createUseSuspenseQueryOperationTSDocExample(
         operation,
-        serviceVariableName
+        serviceVariableName,
+        options
       );
     case 'useMutation':
       return createUseMutationOperationTSDocExample(
@@ -39,17 +43,20 @@ export const createOperationMethodTSDocExample = (
     case 'useInfiniteQuery':
       return createUseInfiniteQueryOperationTSDocExample(
         operation,
-        serviceVariableName
+        serviceVariableName,
+        options
       );
     case 'useSuspenseInfiniteQuery':
       return createUseSuspenseInfiniteQueryOperationTSDocExample(
         operation,
-        serviceVariableName
+        serviceVariableName,
+        options
       );
     case 'useIsFetching':
       return createUseIsFetchingOperationTSDocExample(
         operation,
-        serviceVariableName
+        serviceVariableName,
+        options
       );
     case 'useIsMutating':
       return createUseIsMutatingOperationTSDocExample(
@@ -64,12 +71,14 @@ export const createOperationMethodTSDocExample = (
     case 'useQueries':
       return createUseQueriesOperationTSDocExample(
         operation,
-        serviceVariableName
+        serviceVariableName,
+        options
       );
     case 'useSuspenseQueries':
       return createUseSuspenseQueriesOperationTSDocExample(
         operation,
-        serviceVariableName
+        serviceVariableName,
+        options
       );
     default:
       return undefined;

package/src/ts-factory/tsdoc/createUseInfiniteQueryOperationTSDocExample.ts

@@ -3,12 +3,17 @@ import camelcase from 'camelcase';
 import ts from 'typescript';
 import { createOperationCommonTSDoc } from '../../lib/createOperationCommonTSDoc.js';
 import { astToString } from '../astToString.js';
+import { ServiceFactoryOptions } from '../getServiceFactory.js';
+import { createOperationMethodBodyParametersExampleNode } from './lib/createOperationMethodBodyParametersExampleNode.js';
 import { createOperationMethodCallExpressionExampleNode } from './lib/createOperationMethodCallExpressionExampleNode.js';
 import { createOperationMethodParametersExampleNodes } from './lib/createOperationMethodParametersExampleNodes.js';
 
 export const createUseInfiniteQueryOperationTSDocExample = (
   operation: ServiceOperation,
-  serviceVariableName: string
+  serviceVariableName: string,
+  {
+    queryableWriteOperations,
+  }: Pick<ServiceFactoryOptions, 'queryableWriteOperations'>
 ): string[] => {
   const factory = ts.factory;
 
@@ -36,12 +41,16 @@ export const createUseInfiniteQueryOperationTSDocExample = (
           },
           [
             factory.createObjectLiteralExpression(
-              createOperationMethodParametersExampleNodes({
-                ...operation,
-                parameters: operation.parameters?.filter((parameter) =>
-                  parameter.in === 'query' ? parameter.required : true
-                ),
-              }),
+              [
+                queryableWriteOperations &&
+                  createOperationMethodBodyParametersExampleNode(operation),
+                ...createOperationMethodParametersExampleNodes({
+                  ...operation,
+                  parameters: operation.parameters?.filter((parameter) =>
+                    parameter.in === 'query' ? parameter.required : true
+                  ),
+                }),
+              ].filter((node) => !!node),
               true
             ),
             factory.createObjectLiteralExpression(