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

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

@@ -0,0 +1,76 @@
+import { ServiceOperation } from '@openapi-qraft/plugin/lib/open-api/OpenAPIService';
+import ts from 'typescript';
+import { createOperationCommonTSDoc } from '../../lib/createOperationCommonTSDoc.js';
+import { astToString } from '../astToString.js';
+import { createOperationMethodCallExpressionExampleNode } from './lib/createOperationMethodCallExpressionExampleNode.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(
+          createOperationMethodCallExpressionExampleNode(
+            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(
+          createOperationMethodCallExpressionExampleNode(
+            operation,
+            {
+              serviceVariableName,
+              operationMethodName: 'useQuery',
+            },
+            [
+              factory.createObjectLiteralExpression(
+                createOperationMethodParametersExampleNodes(operation),
+                true
+              ),
+            ]
+          )
+        )
+      )
+        .trim()
+        .split('\n'),
+      '```'
+    );
+  }
+
+  return example;
+};

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

@@ -0,0 +1,63 @@
+import { ServiceOperation } from '@openapi-qraft/plugin/lib/open-api/OpenAPIService';
+import ts from 'typescript';
+import { astToString } from '../astToString.js';
+import { createInfiniteQueryOptionsArgumentExamplePropertyAssignmentNodes } from './createUseInfiniteQueryOperationTSDocExample.js';
+import { createOperationMethodCallExpressionExampleNode } from './lib/createOperationMethodCallExpressionExampleNode.js';
+import { createOperationMethodParametersExampleNodes } from './lib/createOperationMethodParametersExampleNodes.js';
+
+export const createUseSuspenseInfiniteQueryOperationTSDocExample = (
+  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.',
+    'It functions similarly to `useInfiniteQuery`, but with added support for React Suspense.',
+    '',
+    '@see {@link https://openapi-qraft.github.io/openapi-qraft/docs/hooks/useSuspenseInfiniteQuery|`useSuspenseInfiniteQuery(...)` documentation}',
+    '',
+  ];
+
+  return [
+    ...commonTSDoc,
+    '@example Suspense Infinite Query',
+    '```ts',
+    ...(
+      'const { data, isLoading, fetchNextPage } = ' +
+      astToString(
+        createOperationMethodCallExpressionExampleNode(
+          operation,
+          {
+            serviceVariableName,
+            operationMethodName: 'useSuspenseInfiniteQuery',
+          },
+          [
+            factory.createObjectLiteralExpression(
+              createOperationMethodParametersExampleNodes({
+                ...operation,
+                parameters: operation.parameters?.filter((parameter) =>
+                  parameter.in === 'query' ? parameter.required : true
+                ),
+              }),
+              true
+            ),
+            factory.createObjectLiteralExpression(
+              createInfiniteQueryOptionsArgumentExamplePropertyAssignmentNodes(
+                operation
+              ),
+              true
+            ),
+          ]
+        )
+      )
+    )
+      .trim()
+      .split('\n'),
+    '',
+    'console.log(data);',
+    'fetchNextPage(); // Fetch the next page',
+    '```',
+  ];
+};

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

@@ -0,0 +1,28 @@
+import { ServiceOperation } from '@openapi-qraft/plugin/lib/open-api/OpenAPIService';
+import ts from 'typescript';
+
+export const createOperationMethodCallExpressionExampleNode = (
+  operation: ServiceOperation,
+  {
+    serviceVariableName,
+    operationMethodName,
+  }: { serviceVariableName: string; operationMethodName: string },
+  nodes: ts.Expression[] | undefined
+) => {
+  const factory = ts.factory;
+
+  return 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,83 @@
+import { ServiceOperation } from '@openapi-qraft/plugin/lib/open-api/OpenAPIService';
+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(
+                isIdentifierCompatibleVariableName(parameter.name)
+                  ? factory.createIdentifier(parameter.name)
+                  : factory.createStringLiteral(parameter.name),
+                parameter.example // todo:: add example type inferring
+                  ? factory.createStringLiteral(parameter.example)
+                  : factory.createIdentifier(
+                      transformOperationParameterIdentifier
+                        ? transformOperationParameterIdentifier(parameter)
+                        : camelcase(parameter.name)
+                    )
+              )
+            ),
+            true
+          )
+        ),
+      ];
+    },
+    []
+  );
+};
+
+/**
+ * Checks if the given name is a valid identifier name.
+ *
+ * @example
+ * ```ts
+ * isIdentifierCompatibleVariableName('foo'); // true
+ * isIdentifierCompatibleVariableName('foo-bar'); // false
+ * isIdentifierCompatibleVariableName('foo_bar'); // true
+ * isIdentifierCompatibleVariableName('foo.bar'); // false
+ * ```
+ */
+function isIdentifierCompatibleVariableName(name: string) {
+  return !/[^a-zA-Z0-9_$]/.test(name);
+}