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

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 { createOperationMethodCallExpressionExampleNode } from './lib/createOperationMethodCallExpressionExampleNode.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(
+        createOperationMethodCallExpressionExampleNode(
+          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(
+        createOperationMethodCallExpressionExampleNode(
+          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 { createOperationMethodCallExpressionExampleNode } from './lib/createOperationMethodCallExpressionExampleNode.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(
+        createOperationMethodCallExpressionExampleNode(
+          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(
+        createOperationMethodCallExpressionExampleNode(
+          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/createUseMutationStateOperationTSDocExample.ts

@@ -0,0 +1,154 @@
+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 { createOperationMethodCallExpressionExampleNode } from './lib/createOperationMethodCallExpressionExampleNode.js';
+import { createOperationMethodParametersExampleNodes } from './lib/createOperationMethodParametersExampleNodes.js';
+
+export const createUseMutationStateOperationTSDocExample = (
+  operation: ServiceOperation,
+  serviceVariableName: string
+) => {
+  const factory = ts.factory;
+
+  const example: string[] = [
+    'Provides access to the current state of a mutation, including its status, any resulting data, and associated errors.',
+    '',
+    ...createOperationCommonTSDoc(operation),
+    '@see {@link https://openapi-qraft.github.io/openapi-qraft/docs/hooks/useMutationState|`useMutationState(...)` documentation}',
+
+    '@example Get all variables of all running mutations.',
+    '```ts',
+    ...(
+      `const ${camelcase(operation.name + '-pending-mutation-variables')} = ` +
+      astToString(
+        createOperationMethodCallExpressionExampleNode(
+          operation,
+          {
+            serviceVariableName,
+            operationMethodName: 'useMutationState',
+          },
+          [
+            factory.createObjectLiteralExpression(
+              [
+                factory.createPropertyAssignment(
+                  factory.createIdentifier('filters'),
+                  factory.createObjectLiteralExpression(
+                    [
+                      factory.createPropertyAssignment(
+                        factory.createIdentifier('status'),
+                        factory.createStringLiteral('pending')
+                      ),
+                    ],
+                    true
+                  )
+                ),
+                factory.createPropertyAssignment(
+                  factory.createIdentifier('select'),
+                  factory.createArrowFunction(
+                    undefined,
+                    undefined,
+                    [
+                      factory.createParameterDeclaration(
+                        undefined,
+                        undefined,
+                        factory.createIdentifier('mutation'),
+                        undefined,
+                        undefined,
+                        undefined
+                      ),
+                    ],
+                    undefined,
+                    factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken),
+                    factory.createPropertyAccessExpression(
+                      factory.createPropertyAccessExpression(
+                        factory.createIdentifier('mutation'),
+                        factory.createIdentifier('state')
+                      ),
+                      factory.createIdentifier('variables')
+                    )
+                  )
+                ),
+              ],
+              true
+            ),
+          ]
+        )
+      )
+    )
+      .trim()
+      .split('\n'),
+    '```',
+
+    '@example Get all data for specific mutations via the `parameters`.',
+    '```ts',
+    ...(
+      `const ${camelcase(operation.name + '-mutation-data')} = ` +
+      astToString(
+        createOperationMethodCallExpressionExampleNode(
+          operation,
+          {
+            serviceVariableName,
+            operationMethodName: 'useMutationState',
+          },
+          [
+            factory.createObjectLiteralExpression(
+              [
+                factory.createPropertyAssignment(
+                  factory.createIdentifier('filters'),
+                  factory.createObjectLiteralExpression(
+                    [
+                      factory.createPropertyAssignment(
+                        factory.createIdentifier('parameters'),
+                        factory.createObjectLiteralExpression(
+                          createOperationMethodParametersExampleNodes(
+                            operation
+                          ),
+                          true
+                        )
+                      ),
+                    ],
+                    true
+                  )
+                ),
+                factory.createPropertyAssignment(
+                  factory.createIdentifier('select'),
+                  factory.createArrowFunction(
+                    undefined,
+                    undefined,
+                    [
+                      factory.createParameterDeclaration(
+                        undefined,
+                        undefined,
+                        factory.createIdentifier('mutation'),
+                        undefined,
+                        undefined,
+                        undefined
+                      ),
+                    ],
+                    undefined,
+                    factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken),
+                    factory.createPropertyAccessExpression(
+                      factory.createPropertyAccessExpression(
+                        factory.createIdentifier('mutation'),
+                        factory.createIdentifier('state')
+                      ),
+                      factory.createIdentifier('data')
+                    )
+                  )
+                ),
+              ],
+              true
+            ),
+          ]
+        )
+      )
+    )
+      .trim()
+      .split('\n'),
+    '```',
+  ];
+
+  return example;
+};

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

@@ -0,0 +1,292 @@
+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 { createOperationMethodCallExpressionExampleNode } from './lib/createOperationMethodCallExpressionExampleNode.js';
+import { createOperationMethodParametersExampleNodes } from './lib/createOperationMethodParametersExampleNodes.js';
+
+export const createUseQueriesOperationTSDocExample = (
+  operation: ServiceOperation,
+  serviceVariableName: string
+) => {
+  const factory = ts.factory;
+
+  const example: string[] = [
+    'Allows you to execute multiple asynchronous data fetching operations concurrently. This is especially useful for managing complex data dependencies in parallel.',
+    '',
+    ...createOperationCommonTSDoc(operation),
+    '@see {@link https://openapi-qraft.github.io/openapi-qraft/docs/hooks/useQueries|`useQueries(...)` documentation}',
+
+    '@example Multiple queries. Returns `data`, `error`, `isSuccess` and other properties.',
+    '```ts',
+    ...astToString([
+      factory.createVariableStatement(
+        undefined,
+        factory.createVariableDeclarationList(
+          [
+            factory.createVariableDeclaration(
+              factory.createIdentifier(camelcase(operation.name + '-results')),
+              undefined,
+              undefined,
+              createOperationMethodCallExpressionExampleNode(
+                operation,
+                {
+                  serviceVariableName,
+                  operationMethodName: 'useQueries',
+                },
+                [
+                  factory.createObjectLiteralExpression(
+                    [
+                      factory.createPropertyAssignment(
+                        factory.createIdentifier('queries'),
+                        factory.createArrayLiteralExpression(
+                          [
+                            factory.createObjectLiteralExpression(
+                              createOperationMethodParametersExampleNodes(
+                                operation,
+                                (parameter) => camelcase(`${parameter.name}-1`)
+                              ),
+                              true
+                            ),
+                            factory.createObjectLiteralExpression(
+                              createOperationMethodParametersExampleNodes(
+                                operation,
+                                (parameter) => camelcase(`${parameter.name}-2`)
+                              ),
+                              true
+                            ),
+                          ],
+                          true
+                        )
+                      ),
+                    ],
+                    true
+                  ),
+                ]
+              )
+            ),
+          ],
+          ts.NodeFlags.Const
+        )
+      ),
+      factory.createExpressionStatement(
+        factory.createCallExpression(
+          factory.createPropertyAccessExpression(
+            factory.createIdentifier(camelcase(operation.name + '-results')),
+            factory.createIdentifier('forEach')
+          ),
+          undefined,
+          [
+            factory.createArrowFunction(
+              undefined,
+              undefined,
+              [
+                factory.createParameterDeclaration(
+                  undefined,
+                  undefined,
+                  factory.createObjectBindingPattern([
+                    factory.createBindingElement(
+                      undefined,
+                      undefined,
+                      factory.createIdentifier('isSuccess')
+                    ),
+                    factory.createBindingElement(
+                      undefined,
+                      undefined,
+                      factory.createIdentifier('data')
+                    ),
+                    factory.createBindingElement(
+                      undefined,
+                      undefined,
+                      factory.createIdentifier('error')
+                    ),
+                  ])
+                ),
+              ],
+              undefined,
+              factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken),
+              factory.createCallExpression(
+                factory.createPropertyAccessExpression(
+                  factory.createIdentifier('console'),
+                  factory.createIdentifier('log')
+                ),
+                undefined,
+                [
+                  factory.createObjectLiteralExpression(
+                    [
+                      factory.createShorthandPropertyAssignment(
+                        factory.createIdentifier('isSuccess')
+                      ),
+                      factory.createShorthandPropertyAssignment(
+                        factory.createIdentifier('data')
+                      ),
+                      factory.createShorthandPropertyAssignment(
+                        factory.createIdentifier('error')
+                      ),
+                    ],
+                    false
+                  ),
+                ]
+              )
+            ),
+          ]
+        )
+      ),
+    ])
+      .trim()
+      .split('\n'),
+    '```',
+
+    '@example Combined results. Only the data will be returned.',
+    '```ts',
+    ...astToString([
+      factory.createVariableStatement(
+        undefined,
+        factory.createVariableDeclarationList(
+          [
+            factory.createVariableDeclaration(
+              factory.createIdentifier(
+                camelcase(operation.name + '-combined-results')
+              ),
+              undefined,
+              undefined,
+              createOperationMethodCallExpressionExampleNode(
+                operation,
+                {
+                  serviceVariableName,
+                  operationMethodName: 'useQueries',
+                },
+                [
+                  factory.createObjectLiteralExpression(
+                    [
+                      factory.createPropertyAssignment(
+                        factory.createIdentifier('combine'),
+                        factory.createArrowFunction(
+                          undefined,
+                          undefined,
+                          [
+                            factory.createParameterDeclaration(
+                              undefined,
+                              undefined,
+                              factory.createIdentifier('results')
+                            ),
+                          ],
+                          undefined,
+                          factory.createToken(
+                            ts.SyntaxKind.EqualsGreaterThanToken
+                          ),
+                          factory.createCallExpression(
+                            factory.createPropertyAccessExpression(
+                              factory.createIdentifier('results'),
+                              factory.createIdentifier('map')
+                            ),
+                            undefined,
+                            [
+                              factory.createArrowFunction(
+                                undefined,
+                                undefined,
+                                [
+                                  factory.createParameterDeclaration(
+                                    undefined,
+                                    undefined,
+                                    factory.createIdentifier('result')
+                                  ),
+                                ],
+                                undefined,
+                                factory.createToken(
+                                  ts.SyntaxKind.EqualsGreaterThanToken
+                                ),
+                                factory.createPropertyAccessExpression(
+                                  factory.createIdentifier('result'),
+                                  factory.createIdentifier('data')
+                                )
+                              ),
+                            ]
+                          )
+                        )
+                      ),
+                      factory.createPropertyAssignment(
+                        factory.createIdentifier('queries'),
+                        factory.createArrayLiteralExpression(
+                          [
+                            factory.createObjectLiteralExpression(
+                              createOperationMethodParametersExampleNodes(
+                                operation,
+                                (parameter) => camelcase(`${parameter.name}-1`)
+                              ),
+                              true
+                            ),
+                            factory.createObjectLiteralExpression(
+                              createOperationMethodParametersExampleNodes(
+                                operation,
+                                (parameter) => camelcase(`${parameter.name}-2`)
+                              ),
+                              true
+                            ),
+                          ],
+                          true
+                        )
+                      ),
+                    ],
+                    true
+                  ),
+                ]
+              )
+            ),
+          ],
+          ts.NodeFlags.Const
+        )
+      ),
+      factory.createExpressionStatement(
+        factory.createCallExpression(
+          factory.createPropertyAccessExpression(
+            factory.createIdentifier(
+              camelcase(operation.name + '-combined-results')
+            ),
+            factory.createIdentifier('forEach')
+          ),
+          undefined,
+          [
+            factory.createArrowFunction(
+              undefined,
+              undefined,
+              [
+                factory.createParameterDeclaration(
+                  undefined,
+                  undefined,
+                  factory.createIdentifier('data')
+                ),
+              ],
+              undefined,
+              factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken),
+              factory.createCallExpression(
+                factory.createPropertyAccessExpression(
+                  factory.createIdentifier('console'),
+                  factory.createIdentifier('log')
+                ),
+                undefined,
+                [
+                  factory.createObjectLiteralExpression(
+                    [
+                      factory.createShorthandPropertyAssignment(
+                        factory.createIdentifier('data'),
+                        undefined
+                      ),
+                    ],
+                    false
+                  ),
+                ]
+              )
+            ),
+          ]
+        )
+      ),
+    ])
+      .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 { 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;
+};