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

package/src/ts-factory/service-operation.generated/ServiceOperationQueryFn.ts

@@ -109,57 +109,57 @@ export const createServiceOperationQueryFnNodes = () => [
           undefined,
           factory.createIdentifier("options"),
           undefined,
-          factory.createConditionalTypeNode(
+          factory.createUnionTypeNode([
             factory.createTypeReferenceNode(
-              factory.createIdentifier("AreAllOptional"),
-              [factory.createTypeReferenceNode(
-                factory.createIdentifier("TParams"),
-                undefined
-              )]
+              factory.createIdentifier("QueryFnOptionsByQueryKey"),
+              [
+                factory.createTypeReferenceNode(
+                  factory.createIdentifier("TSchema"),
+                  undefined
+                ),
+                factory.createTypeReferenceNode(
+                  factory.createIdentifier("TParams"),
+                  undefined
+                ),
+                factory.createTypeReferenceNode(
+                  factory.createIdentifier("TMeta"),
+                  undefined
+                ),
+                factory.createTypeReferenceNode(
+                  factory.createIdentifier("TSignal"),
+                  undefined
+                )
+              ]
             ),
-            factory.createLiteralTypeNode(factory.createTrue()),
-            factory.createUnionTypeNode([
-              factory.createKeywordTypeNode(ts.SyntaxKind.VoidKeyword),
+            factory.createParenthesizedType(factory.createConditionalTypeNode(
               factory.createTypeReferenceNode(
-                factory.createIdentifier("QueryFnOptionsByParameters"),
-                [
-                  factory.createTypeReferenceNode(
-                    factory.createIdentifier("TParams"),
-                    undefined
-                  ),
-                  factory.createTypeReferenceNode(
-                    factory.createIdentifier("TMeta"),
-                    undefined
-                  ),
-                  factory.createTypeReferenceNode(
-                    factory.createIdentifier("TSignal"),
-                    undefined
-                  )
-                ]
+                factory.createIdentifier("AreAllOptional"),
+                [factory.createTypeReferenceNode(
+                  factory.createIdentifier("TParams"),
+                  undefined
+                )]
               ),
-              factory.createTypeReferenceNode(
-                factory.createIdentifier("QueryFnOptionsByQueryKey"),
-                [
-                  factory.createTypeReferenceNode(
-                    factory.createIdentifier("TSchema"),
-                    undefined
-                  ),
-                  factory.createTypeReferenceNode(
-                    factory.createIdentifier("TParams"),
-                    undefined
-                  ),
-                  factory.createTypeReferenceNode(
-                    factory.createIdentifier("TMeta"),
-                    undefined
-                  ),
-                  factory.createTypeReferenceNode(
-                    factory.createIdentifier("TSignal"),
-                    undefined
-                  )
-                ]
-              )
-            ]),
-            factory.createUnionTypeNode([
+              factory.createLiteralTypeNode(factory.createTrue()),
+              factory.createUnionTypeNode([
+                factory.createTypeReferenceNode(
+                  factory.createIdentifier("QueryFnOptionsByParameters"),
+                  [
+                    factory.createTypeReferenceNode(
+                      factory.createIdentifier("TParams"),
+                      undefined
+                    ),
+                    factory.createTypeReferenceNode(
+                      factory.createIdentifier("TMeta"),
+                      undefined
+                    ),
+                    factory.createTypeReferenceNode(
+                      factory.createIdentifier("TSignal"),
+                      undefined
+                    )
+                  ]
+                ),
+                factory.createKeywordTypeNode(ts.SyntaxKind.VoidKeyword)
+              ]),
               factory.createTypeReferenceNode(
                 factory.createIdentifier("QueryFnOptionsByParameters"),
                 [
@@ -176,30 +176,9 @@ export const createServiceOperationQueryFnNodes = () => [
                     undefined
                   )
                 ]
-              ),
-              factory.createTypeReferenceNode(
-                factory.createIdentifier("QueryFnOptionsByQueryKey"),
-                [
-                  factory.createTypeReferenceNode(
-                    factory.createIdentifier("TSchema"),
-                    undefined
-                  ),
-                  factory.createTypeReferenceNode(
-                    factory.createIdentifier("TParams"),
-                    undefined
-                  ),
-                  factory.createTypeReferenceNode(
-                    factory.createIdentifier("TMeta"),
-                    undefined
-                  ),
-                  factory.createTypeReferenceNode(
-                    factory.createIdentifier("TSignal"),
-                    undefined
-                  )
-                ]
               )
-            ])
-          ),
+            ))
+          ]),
           undefined
         ),
         factory.createParameterDeclaration(

package/src/ts-factory/service-operation.generated/ServiceOperationUseMutation.ts

@@ -139,17 +139,8 @@ export const createServiceOperationUseMutationNodes = () => [
             undefined,
             factory.createIdentifier("TVariables"),
             factory.createTypeReferenceNode(
-              factory.createIdentifier("MutationVariables"),
-              [
-                factory.createTypeReferenceNode(
-                  factory.createIdentifier("TBody"),
-                  undefined
-                ),
-                factory.createTypeReferenceNode(
-                  factory.createIdentifier("TParams"),
-                  undefined
-                )
-              ]
+              factory.createIdentifier("TBody"),
+              undefined
             ),
             undefined
           ),
@@ -165,8 +156,11 @@ export const createServiceOperationUseMutationNodes = () => [
             undefined,
             undefined,
             factory.createIdentifier("parameters"),
-            factory.createToken(ts.SyntaxKind.QuestionToken),
-            factory.createKeywordTypeNode(ts.SyntaxKind.UndefinedKeyword),
+            undefined,
+            factory.createTypeReferenceNode(
+              factory.createIdentifier("TParams"),
+              undefined
+            ),
             undefined
           ),
           factory.createParameterDeclaration(
@@ -223,9 +217,26 @@ export const createServiceOperationUseMutationNodes = () => [
                 undefined
               )
             ]),
-            factory.createTypeReferenceNode(
-              factory.createIdentifier("TVariables"),
-              undefined
+            factory.createConditionalTypeNode(
+              factory.createTypeReferenceNode(
+                factory.createIdentifier("AreAllOptional"),
+                [factory.createTypeReferenceNode(
+                  factory.createIdentifier("TVariables"),
+                  undefined
+                )]
+              ),
+              factory.createLiteralTypeNode(factory.createTrue()),
+              factory.createUnionTypeNode([
+                factory.createTypeReferenceNode(
+                  factory.createIdentifier("TVariables"),
+                  undefined
+                ),
+                factory.createKeywordTypeNode(ts.SyntaxKind.VoidKeyword)
+              ]),
+              factory.createTypeReferenceNode(
+                factory.createIdentifier("TVariables"),
+                undefined
+              )
             ),
             factory.createTypeReferenceNode(
               factory.createIdentifier("TContext"),
@@ -243,8 +254,17 @@ export const createServiceOperationUseMutationNodes = () => [
             undefined,
             factory.createIdentifier("TVariables"),
             factory.createTypeReferenceNode(
-              factory.createIdentifier("TBody"),
-              undefined
+              factory.createIdentifier("MutationVariables"),
+              [
+                factory.createTypeReferenceNode(
+                  factory.createIdentifier("TBody"),
+                  undefined
+                ),
+                factory.createTypeReferenceNode(
+                  factory.createIdentifier("TParams"),
+                  undefined
+                )
+              ]
             ),
             undefined
           ),
@@ -261,27 +281,7 @@ export const createServiceOperationUseMutationNodes = () => [
             undefined,
             factory.createIdentifier("parameters"),
             undefined,
-            factory.createConditionalTypeNode(
-              factory.createTypeReferenceNode(
-                factory.createIdentifier("AreAllOptional"),
-                [factory.createTypeReferenceNode(
-                  factory.createIdentifier("TParams"),
-                  undefined
-                )]
-              ),
-              factory.createLiteralTypeNode(factory.createTrue()),
-              factory.createUnionTypeNode([
-                factory.createTypeReferenceNode(
-                  factory.createIdentifier("TParams"),
-                  undefined
-                ),
-                factory.createKeywordTypeNode(ts.SyntaxKind.VoidKeyword)
-              ]),
-              factory.createTypeReferenceNode(
-                factory.createIdentifier("TParams"),
-                undefined
-              )
-            ),
+            factory.createKeywordTypeNode(ts.SyntaxKind.VoidKeyword),
             undefined
           ),
           factory.createParameterDeclaration(
@@ -338,26 +338,9 @@ export const createServiceOperationUseMutationNodes = () => [
                 undefined
               )
             ]),
-            factory.createConditionalTypeNode(
-              factory.createTypeReferenceNode(
-                factory.createIdentifier("AreAllOptional"),
-                [factory.createTypeReferenceNode(
-                  factory.createIdentifier("TVariables"),
-                  undefined
-                )]
-              ),
-              factory.createLiteralTypeNode(factory.createTrue()),
-              factory.createUnionTypeNode([
-                factory.createTypeReferenceNode(
-                  factory.createIdentifier("TVariables"),
-                  undefined
-                ),
-                factory.createKeywordTypeNode(ts.SyntaxKind.VoidKeyword)
-              ]),
-              factory.createTypeReferenceNode(
-                factory.createIdentifier("TVariables"),
-                undefined
-              )
+            factory.createTypeReferenceNode(
+              factory.createIdentifier("TVariables"),
+              undefined
             ),
             factory.createTypeReferenceNode(
               factory.createIdentifier("TContext"),

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

@@ -0,0 +1,47 @@
+import { ServiceOperation } from '@openapi-qraft/plugin/lib/open-api/getServices';
+import { createUseInfiniteQueryOperationTSDocExample } from './createUseInfiniteQueryOperationTSDocExample.js';
+import { createUseIsFetchingOperationTSDocExample } from './createUseIsFetchingOperationTSDocExample.js';
+import { createUseIsMutatingOperationTSDocExample } from './createUseIsMutatingOperationTSDocExample.js';
+import { createUseMutationOperationTSDocExample } from './createUseMutationOperationTSDocExample.js';
+import { createUseQueryOperationTSDocExample } from './createUseQueryOperationTSDocExample.js';
+
+export const createOperationMethodTSDocExample = (
+  operation: ServiceOperation,
+  {
+    serviceVariableName,
+    operationMethodName,
+  }: {
+    serviceVariableName: string;
+    operationMethodName: string;
+  }
+) => {
+  switch (operationMethodName) {
+    case 'useQuery':
+      return createUseQueryOperationTSDocExample(
+        operation,
+        serviceVariableName
+      );
+    case 'useMutation':
+      return createUseMutationOperationTSDocExample(
+        operation,
+        serviceVariableName
+      );
+    case 'useInfiniteQuery':
+      return createUseInfiniteQueryOperationTSDocExample(
+        operation,
+        serviceVariableName
+      );
+    case 'useIsFetching':
+      return createUseIsFetchingOperationTSDocExample(
+        operation,
+        serviceVariableName
+      );
+    case 'useIsMutating':
+      return createUseIsMutatingOperationTSDocExample(
+        operation,
+        serviceVariableName
+      );
+    default:
+      return undefined;
+  }
+};

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

@@ -0,0 +1,146 @@
+import { ServiceOperation } from '@openapi-qraft/plugin/lib/open-api/getServices';
+import camelcase from 'camelcase';
+import ts from 'typescript';
+import { astToString } from '../astToString.js';
+import { createOperationMethodExampleNodes } from './lib/createOperationMethodExampleNodes.js';
+import { createOperationMethodParametersExampleNodes } from './lib/createOperationMethodParametersExampleNodes.js';
+
+export const createUseInfiniteQueryOperationTSDocExample = (
+  operation: ServiceOperation,
+  serviceVariableName: string
+): string[] => {
+  const factory = ts.factory;
+
+  const commonTSDoc = [
+    'Performs asynchronous data fetching with support for infinite scrolling scenarios.',
+    'Manages paginated data and provides utilities for fetching additional pages.',
+    '',
+    '@see {@link https://openapi-qraft.github.io/openapi-qraft/docs/hooks/useInfiniteQuery|`useInfiniteQuery(...)` documentation}',
+    '',
+  ];
+
+  if (!operation.parameters?.length) {
+    return [
+      ...commonTSDoc,
+      '@example Infinite Query without parameters',
+      '```ts',
+      ...(
+        'const { data, isLoading } = ' +
+        astToString(
+          createOperationMethodExampleNodes(
+            operation,
+            {
+              serviceVariableName,
+              operationMethodName: 'useInfiniteQuery',
+            },
+            undefined
+          )
+        )
+      )
+        .trim()
+        .split('\n'),
+      '```',
+    ];
+  }
+
+  return [
+    ...commonTSDoc,
+    '@example Infinite Query with parameters',
+    '```ts',
+    ...(
+      'const { data, isLoading } = ' +
+      astToString(
+        createOperationMethodExampleNodes(
+          operation,
+          {
+            serviceVariableName,
+            operationMethodName: 'useInfiniteQuery',
+          },
+          [
+            factory.createObjectLiteralExpression(
+              createOperationMethodParametersExampleNodes(operation),
+              true
+            ),
+            createInfiniteQueryOptionsArgumentExampleNodes(operation),
+          ]
+        )
+      )
+    )
+      .trim()
+      .split('\n'),
+    '```',
+  ];
+};
+
+function createInfiniteQueryOptionsArgumentExampleNodes(
+  operation: ServiceOperation
+): ts.ObjectLiteralExpression {
+  const factory = ts.factory;
+
+  return factory.createObjectLiteralExpression(
+    [
+      factory.createPropertyAssignment(
+        factory.createIdentifier('getNextPageParam'),
+        factory.createArrowFunction(
+          undefined,
+          undefined,
+          [
+            factory.createParameterDeclaration(
+              undefined,
+              undefined,
+              factory.createIdentifier('lastPage'),
+              undefined,
+              undefined,
+              undefined
+            ),
+            factory.createParameterDeclaration(
+              undefined,
+              undefined,
+              factory.createIdentifier('allPages'),
+              undefined,
+              undefined,
+              undefined
+            ),
+            factory.createParameterDeclaration(
+              undefined,
+              undefined,
+              factory.createIdentifier('lastPageParam'),
+              undefined,
+              undefined,
+              undefined
+            ),
+            factory.createParameterDeclaration(
+              undefined,
+              undefined,
+              factory.createIdentifier('allPageParams'),
+              undefined,
+              undefined,
+              undefined
+            ),
+          ],
+          undefined,
+          factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken),
+          factory.createCallExpression(
+            factory.createIdentifier('getNextPageParams'),
+            undefined,
+            [factory.createIdentifier('lastPage')]
+          )
+        )
+      ),
+      factory.createPropertyAssignment(
+        factory.createIdentifier('initialPageParam'),
+        factory.createObjectLiteralExpression(
+          createOperationMethodParametersExampleNodes(
+            operation,
+            (operationParameter) =>
+              operationParameter.in === 'query'
+                ? camelcase(`initial-${operationParameter.name}`)
+                : camelcase(operationParameter.name)
+          ),
+          true
+        )
+      ),
+    ],
+    true
+  );
+}

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

@@ -0,0 +1,81 @@
+import { ServiceOperation } from '@openapi-qraft/plugin/lib/open-api/getServices';
+import camelcase from 'camelcase';
+import ts from 'typescript';
+import { astToString } from '../astToString.js';
+import { createOperationMethodExampleNodes } from './lib/createOperationMethodExampleNodes.js';
+import { createOperationMethodParametersExampleNodes } from './lib/createOperationMethodParametersExampleNodes.js';
+
+export const createUseIsFetchingOperationTSDocExample = (
+  operation: ServiceOperation,
+  serviceVariableName: string
+) => {
+  const example: string[] = [
+    'Monitors the number of queries currently fetching, matching the provided filters.',
+    'Useful for creating loading indicators or performing actions based on active requests.',
+    '',
+    '@see {@link https://openapi-qraft.github.io/openapi-qraft/docs/hooks/useIsFetching|`useIsFetching(...)` documentation}',
+    '@example Checks the total number of queries fetching from the specified service method,',
+    'both normal and infinite. If no parameters are provided, no filtering is applied.',
+    '```ts',
+    ...(
+      `const ${camelcase(operation.name + '-total')} = ` +
+      astToString(
+        createOperationMethodExampleNodes(
+          operation,
+          {
+            serviceVariableName,
+            operationMethodName: 'useIsFetching',
+          },
+          undefined
+        )
+      )
+    )
+      .trim()
+      .split('\n'),
+    '```',
+  ];
+
+  if (operation.parameters?.length) {
+    const factory = ts.factory;
+
+    example.push(
+      '@example Checks the number of normal queries fetching with the specified parameters.',
+      '```ts',
+      ...(
+        `const ${camelcase(operation.name + '-by-parameters-total')} = ` +
+        astToString(
+          createOperationMethodExampleNodes(
+            operation,
+            {
+              serviceVariableName,
+              operationMethodName: 'useIsFetching',
+            },
+            [
+              factory.createObjectLiteralExpression(
+                [
+                  factory.createPropertyAssignment(
+                    factory.createIdentifier('infinite'),
+                    factory.createFalse()
+                  ),
+                  factory.createPropertyAssignment(
+                    factory.createIdentifier('parameters'),
+                    factory.createObjectLiteralExpression(
+                      createOperationMethodParametersExampleNodes(operation),
+                      true
+                    )
+                  ),
+                ],
+                true
+              ),
+            ]
+          )
+        )
+      )
+        .trim()
+        .split('\n'),
+      '```'
+    );
+  }
+
+  return example;
+};

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

@@ -0,0 +1,74 @@
+import type { ServiceOperation } from '@openapi-qraft/plugin/lib/open-api/getServices';
+import camelcase from 'camelcase';
+import ts from 'typescript';
+import { createOperationCommonTSDoc } from '../../lib/createOperationCommonTSDoc.js';
+import { astToString } from '../astToString.js';
+import { createOperationMethodExampleNodes } from './lib/createOperationMethodExampleNodes.js';
+import { createOperationMethodParametersExampleNodes } from './lib/createOperationMethodParametersExampleNodes.js';
+
+export const createUseIsMutatingOperationTSDocExample = (
+  operation: ServiceOperation,
+  serviceVariableName: string
+) => {
+  const factory = ts.factory;
+
+  const example: string[] = [
+    'Returns the count of currently in-progress mutations.',
+    '',
+    ...createOperationCommonTSDoc(operation),
+    '@see {@link https://openapi-qraft.github.io/openapi-qraft/docs/hooks/useIsMutating|`useIsMutating(...)` documentation}',
+
+    '@example Check how many mutations are currently in progress for the specified service method.',
+    '```ts',
+    ...(
+      `const ${camelcase(operation.name + '-total')} = ` +
+      astToString(
+        createOperationMethodExampleNodes(
+          operation,
+          {
+            serviceVariableName,
+            operationMethodName: 'useIsMutating',
+          },
+          undefined
+        )
+      )
+    )
+      .trim()
+      .split('\n'),
+    '```',
+
+    '@example Check how many mutations are currently in progress with the specified parameters.',
+    '```ts',
+    ...(
+      `const ${camelcase(operation.name + '-total')} = ` +
+      astToString(
+        createOperationMethodExampleNodes(
+          operation,
+          {
+            serviceVariableName,
+            operationMethodName: 'useIsMutating',
+          },
+          [
+            factory.createObjectLiteralExpression(
+              [
+                factory.createPropertyAssignment(
+                  factory.createIdentifier('parameters'),
+                  factory.createObjectLiteralExpression(
+                    createOperationMethodParametersExampleNodes(operation),
+                    true
+                  )
+                ),
+              ],
+              true
+            ),
+          ]
+        )
+      )
+    )
+      .trim()
+      .split('\n'),
+    '```',
+  ];
+
+  return example;
+};