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

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;
+};

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

@@ -0,0 +1,88 @@
+import type { ServiceOperation } from '@openapi-qraft/plugin/lib/open-api/getServices';
+import ts from 'typescript';
+import { astToString } from '../astToString.js';
+import { createOperationMethodExampleNodes } from './lib/createOperationMethodExampleNodes.js';
+import { createOperationMethodParametersExampleNodes } from './lib/createOperationMethodParametersExampleNodes.js';
+
+export const createUseMutationOperationTSDocExample = (
+  operation: ServiceOperation,
+  serviceVariableName: string
+) => {
+  const factory = ts.factory;
+
+  const example: string[] = [
+    'Enables performing asynchronous data mutation operations such as POST, PUT, PATCH, or DELETE requests.',
+    'Handles loading state, optimistic updates, and error handling.',
+    '',
+    '@see {@link https://openapi-qraft.github.io/openapi-qraft/docs/hooks/useMutation|`useMutation(...)` documentation}',
+    '@example Mutation with predefined parameters, e.g., for updating',
+    '```ts',
+    ...(
+      'const { mutate, isPending } = ' +
+      astToString(
+        createOperationMethodExampleNodes(
+          operation,
+          {
+            serviceVariableName,
+            operationMethodName: 'useMutation',
+          },
+          [
+            factory.createObjectLiteralExpression(
+              createOperationMethodParametersExampleNodes(operation),
+              true
+            ),
+          ]
+        )
+      )
+    )
+      .trim()
+      .split('\n'),
+    'mutate(body);',
+    '```',
+  ];
+
+  example.push(
+    '@example Mutation without predefined parameters, e.g., for creating',
+    '```ts',
+    ...(
+      'const { mutate, isPending } = ' +
+      astToString(
+        createOperationMethodExampleNodes(
+          operation,
+          {
+            serviceVariableName,
+            operationMethodName: 'useMutation',
+          },
+          undefined
+        )
+      )
+    )
+      .trim()
+      .split('\n'),
+    ...astToString([
+      factory.createExpressionStatement(
+        factory.createCallExpression(
+          factory.createIdentifier('mutate'),
+          undefined,
+          [
+            factory.createObjectLiteralExpression(
+              [
+                factory.createPropertyAssignment(
+                  factory.createIdentifier('body'),
+                  factory.createIdentifier('bodyPayload')
+                ),
+                ...createOperationMethodParametersExampleNodes(operation),
+              ],
+              true
+            ),
+          ]
+        )
+      ),
+    ])
+      .trim()
+      .split('\n'),
+    '```'
+  );
+
+  return example;
+};

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

@@ -0,0 +1,76 @@
+import { ServiceOperation } from '@openapi-qraft/plugin/lib/open-api/getServices';
+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 createUseQueryOperationTSDocExample = (
+  operation: ServiceOperation,
+  serviceVariableName: string
+) => {
+  const example: string[] = [
+    'Performs asynchronous data fetching, manages loading states and error handling.',
+    '',
+    ...createOperationCommonTSDoc(operation),
+    '@see {@link https://openapi-qraft.github.io/openapi-qraft/docs/hooks/useQuery|`useQuery(...)` documentation}',
+  ];
+
+  if (
+    !operation.parameters?.length ||
+    operation.parameters.every((parameter) => !parameter.required)
+  ) {
+    example.push(
+      '@example Query without parameters',
+      '```ts',
+      ...(
+        'const { data, isLoading } = ' +
+        astToString(
+          createOperationMethodExampleNodes(
+            operation,
+            {
+              serviceVariableName,
+              operationMethodName: 'useQuery',
+            },
+            undefined
+          )
+        )
+      )
+        .trim()
+        .split('\n'),
+      '```'
+    );
+  }
+
+  if (operation.parameters?.length) {
+    const factory = ts.factory;
+
+    example.push(
+      '@example Query with parameters',
+      '```ts',
+      ...(
+        'const { data, isLoading } = ' +
+        astToString(
+          createOperationMethodExampleNodes(
+            operation,
+            {
+              serviceVariableName,
+              operationMethodName: 'useQuery',
+            },
+            [
+              factory.createObjectLiteralExpression(
+                createOperationMethodParametersExampleNodes(operation),
+                true
+              ),
+            ]
+          )
+        )
+      )
+        .trim()
+        .split('\n'),
+      '```'
+    );
+  }
+
+  return example;
+};

package/src/ts-factory/tsdoc/lib/createOperationMethodExampleNodes.ts

@@ -0,0 +1,32 @@
+import { ServiceOperation } from '@openapi-qraft/plugin/lib/open-api/getServices';
+import ts from 'typescript';
+
+export const createOperationMethodExampleNodes = (
+  operation: ServiceOperation,
+  {
+    serviceVariableName,
+    operationMethodName,
+  }: { serviceVariableName: string; operationMethodName: string },
+  nodes: ts.Expression[] | undefined
+) => {
+  const factory = ts.factory;
+
+  return [
+    factory.createExpressionStatement(
+      factory.createCallExpression(
+        factory.createPropertyAccessExpression(
+          factory.createPropertyAccessExpression(
+            factory.createPropertyAccessExpression(
+              factory.createIdentifier('qraft'),
+              factory.createIdentifier(serviceVariableName)
+            ),
+            factory.createIdentifier(operation.name)
+          ),
+          factory.createIdentifier(operationMethodName)
+        ),
+        undefined,
+        nodes
+      )
+    ),
+  ];
+};

package/src/ts-factory/tsdoc/lib/createOperationMethodParametersExampleNodes.ts

@@ -0,0 +1,66 @@
+import { ServiceOperation } from '@openapi-qraft/plugin/lib/open-api/getServices';
+import camelcase from 'camelcase';
+import ts from 'typescript';
+
+export const createOperationMethodParametersExampleNodes = (
+  operation: ServiceOperation,
+  transformOperationParameterIdentifier?: (
+    operationParameter: NonNullable<ServiceOperation['parameters']>[number]
+  ) => string
+): ts.PropertyAssignment[] => {
+  if (!operation.parameters) return [];
+
+  const parametersTypeList = operation.parameters
+    .map((parameter) => parameter.in)
+    .filter(
+      (parameterKind, index, array) => array.indexOf(parameterKind) === index
+    );
+
+  const operationRequiredParameters = operation.parameters.filter(
+    (parameter) => parameter.required
+  );
+
+  return parametersTypeList.reduce<ts.PropertyAssignment[]>(
+    (acc, parameterKind) => {
+      let operationParameters = operationRequiredParameters.filter(
+        (parameter) => parameter.in === parameterKind
+      );
+
+      if (!operationParameters.length) {
+        const operationParameter = operation.parameters?.find(
+          (parameter) => parameter.in === parameterKind
+        );
+        if (operationParameter) {
+          operationParameters = [operationParameter];
+        }
+      }
+
+      if (!operationParameters.length) return acc;
+
+      const factory = ts.factory;
+
+      return [
+        ...acc,
+        factory.createPropertyAssignment(
+          factory.createIdentifier(parameterKind),
+          factory.createObjectLiteralExpression(
+            operationParameters.map((parameter) =>
+              factory.createPropertyAssignment(
+                factory.createStringLiteral(parameter.name),
+                parameter.example // todo:: add example type inferring
+                  ? factory.createStringLiteral(parameter.example)
+                  : factory.createIdentifier(
+                      transformOperationParameterIdentifier
+                        ? transformOperationParameterIdentifier(parameter)
+                        : camelcase(parameter.name)
+                    )
+              )
+            ),
+            true
+          )
+        ),
+      ];
+    },
+    []
+  );
+};