@openapi-qraft/tanstack-query-react-plugin 2.2.0 → 2.2.2

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

@@ -40,25 +40,7 @@ export const createUseQueriesOperationTSDocExample = (
                     [
                       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
-                        )
+                        createQueriesArrayExpression(operation, factory)
                       ),
                     ],
                     true
@@ -70,68 +52,9 @@ export const createUseQueriesOperationTSDocExample = (
           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
-                  ),
-                ]
-              )
-            ),
-          ]
-        )
+      createResultsForEachExpression(
+        camelcase(operation.name + '-results'),
+        factory
       ),
     ])
       .trim()
@@ -162,71 +85,11 @@ export const createUseQueriesOperationTSDocExample = (
                     [
                       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')
-                                )
-                              ),
-                            ]
-                          )
-                        )
+                        createCombineFunction(factory)
                       ),
                       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
-                        )
+                        createQueriesArrayExpression(operation, factory)
                       ),
                     ],
                     true
@@ -238,55 +101,198 @@ export const createUseQueriesOperationTSDocExample = (
           ts.NodeFlags.Const
         )
       ),
-      factory.createExpressionStatement(
-        factory.createCallExpression(
-          factory.createPropertyAccessExpression(
-            factory.createIdentifier(
-              camelcase(operation.name + '-combined-results')
+      createCombinedResultsForEachExpression(
+        camelcase(operation.name + '-combined-results'),
+        factory
+      ),
+    ])
+      .trim()
+      .split('\n'),
+    '```',
+  ];
+
+  return example;
+};
+
+export const createQueriesArrayExpression = (
+  operation: ServiceOperation,
+  factory: ts.NodeFactory
+): ts.ArrayLiteralExpression => {
+  return factory.createArrayLiteralExpression(
+    [
+      factory.createObjectLiteralExpression(
+        createOperationMethodParametersExampleNodes(operation, (parameter) =>
+          camelcase(`${parameter.name}-1`)
+        ),
+        true
+      ),
+      factory.createObjectLiteralExpression(
+        createOperationMethodParametersExampleNodes(operation, (parameter) =>
+          camelcase(`${parameter.name}-2`)
+        ),
+        true
+      ),
+    ],
+    true
+  );
+};
+
+export const createCombineFunction = (
+  factory: ts.NodeFactory
+): ts.ArrowFunction => {
+  return 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')
             ),
-            factory.createIdentifier('forEach')
-          ),
+          ],
+          undefined,
+          factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken),
+          factory.createPropertyAccessExpression(
+            factory.createIdentifier('result'),
+            factory.createIdentifier('data')
+          )
+        ),
+      ]
+    )
+  );
+};
+
+export const createResultsForEachExpression = (
+  variableName: string,
+  factory: ts.NodeFactory
+): ts.ExpressionStatement => {
+  return factory.createExpressionStatement(
+    factory.createCallExpression(
+      factory.createPropertyAccessExpression(
+        factory.createIdentifier(variableName),
+        factory.createIdentifier('forEach')
+      ),
+      undefined,
+      [
+        factory.createArrowFunction(
+          undefined,
           undefined,
           [
-            factory.createArrowFunction(
+            factory.createParameterDeclaration(
               undefined,
               undefined,
-              [
-                factory.createParameterDeclaration(
+              factory.createObjectBindingPattern([
+                factory.createBindingElement(
+                  undefined,
+                  undefined,
+                  factory.createIdentifier('isSuccess')
+                ),
+                factory.createBindingElement(
                   undefined,
                   undefined,
                   factory.createIdentifier('data')
                 ),
-              ],
-              undefined,
-              factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken),
-              factory.createCallExpression(
-                factory.createPropertyAccessExpression(
-                  factory.createIdentifier('console'),
-                  factory.createIdentifier('log')
+                factory.createBindingElement(
+                  undefined,
+                  undefined,
+                  factory.createIdentifier('error')
                 ),
-                undefined,
+              ])
+            ),
+          ],
+          undefined,
+          factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken),
+          factory.createCallExpression(
+            factory.createPropertyAccessExpression(
+              factory.createIdentifier('console'),
+              factory.createIdentifier('log')
+            ),
+            undefined,
+            [
+              factory.createObjectLiteralExpression(
                 [
-                  factory.createObjectLiteralExpression(
-                    [
-                      factory.createShorthandPropertyAssignment(
-                        factory.createIdentifier('data'),
-                        undefined
-                      ),
-                    ],
-                    false
+                  factory.createShorthandPropertyAssignment(
+                    factory.createIdentifier('isSuccess')
                   ),
-                ]
-              )
-            ),
-          ]
-        )
-      ),
-    ])
-      .trim()
-      .split('\n'),
-    '```',
-  ];
+                  factory.createShorthandPropertyAssignment(
+                    factory.createIdentifier('data')
+                  ),
+                  factory.createShorthandPropertyAssignment(
+                    factory.createIdentifier('error')
+                  ),
+                ],
+                false
+              ),
+            ]
+          )
+        ),
+      ]
+    )
+  );
+};
 
-  return example;
+export const createCombinedResultsForEachExpression = (
+  variableName: string,
+  factory: ts.NodeFactory
+): ts.ExpressionStatement => {
+  return factory.createExpressionStatement(
+    factory.createCallExpression(
+      factory.createPropertyAccessExpression(
+        factory.createIdentifier(variableName),
+        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')
+                  ),
+                ],
+                false
+              ),
+            ]
+          )
+        ),
+      ]
+    )
+  );
 };

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

@@ -0,0 +1,121 @@
+import type { ServiceOperation } from '@openapi-qraft/plugin/lib/open-api/OpenAPIService';
+import camelcase from 'camelcase';
+import ts from 'typescript';
+import { createOperationCommonTSDoc } from '../../lib/createOperationCommonTSDoc.js';
+import { astToString } from '../astToString.js';
+import {
+  createCombinedResultsForEachExpression,
+  createCombineFunction,
+  createQueriesArrayExpression,
+  createResultsForEachExpression,
+} from './createUseQueriesOperationTSDocExample.js';
+import { createOperationMethodCallExpressionExampleNode } from './lib/createOperationMethodCallExpressionExampleNode.js';
+
+export const createUseSuspenseQueriesOperationTSDocExample = (
+  operation: ServiceOperation,
+  serviceVariableName: string
+) => {
+  const factory = ts.factory;
+
+  const example: string[] = [
+    'Allows you to execute multiple asynchronous data fetching operations concurrently with Suspense support.',
+    'Similar to useQueries but integrates with React Suspense for loading states.',
+    '',
+    ...createOperationCommonTSDoc(operation),
+    '@see {@link https://openapi-qraft.github.io/openapi-qraft/docs/hooks/useSuspenseQueries|`useSuspenseQueries(...)` documentation}',
+
+    '@example Basic usage with Suspense',
+    '```ts',
+    ...astToString([
+      factory.createVariableStatement(
+        undefined,
+        factory.createVariableDeclarationList(
+          [
+            factory.createVariableDeclaration(
+              factory.createIdentifier(camelcase(operation.name + '-data')),
+              undefined,
+              undefined,
+              createOperationMethodCallExpressionExampleNode(
+                operation,
+                {
+                  serviceVariableName,
+                  operationMethodName: 'useSuspenseQueries',
+                },
+                [
+                  factory.createObjectLiteralExpression(
+                    [
+                      factory.createPropertyAssignment(
+                        factory.createIdentifier('queries'),
+                        createQueriesArrayExpression(operation, factory)
+                      ),
+                    ],
+                    true
+                  ),
+                ]
+              )
+            ),
+          ],
+          ts.NodeFlags.Const
+        )
+      ),
+      createResultsForEachExpression(
+        camelcase(operation.name + '-results'),
+        factory
+      ),
+    ])
+      .trim()
+      .split('\n'),
+    '```',
+
+    '@example With data transformation using combine',
+    '```ts',
+    ...astToString([
+      factory.createVariableStatement(
+        undefined,
+        factory.createVariableDeclarationList(
+          [
+            factory.createVariableDeclaration(
+              factory.createIdentifier(
+                camelcase(operation.name + '-combined-data')
+              ),
+              undefined,
+              undefined,
+              createOperationMethodCallExpressionExampleNode(
+                operation,
+                {
+                  serviceVariableName,
+                  operationMethodName: 'useSuspenseQueries',
+                },
+                [
+                  factory.createObjectLiteralExpression(
+                    [
+                      factory.createPropertyAssignment(
+                        factory.createIdentifier('combine'),
+                        createCombineFunction(factory)
+                      ),
+                      factory.createPropertyAssignment(
+                        factory.createIdentifier('queries'),
+                        createQueriesArrayExpression(operation, factory)
+                      ),
+                    ],
+                    true
+                  ),
+                ]
+              )
+            ),
+          ],
+          ts.NodeFlags.Const
+        )
+      ),
+      createCombinedResultsForEachExpression(
+        camelcase(operation.name + '-combined-data'),
+        factory
+      ),
+    ])
+      .trim()
+      .split('\n'),
+    '```',
+  ];
+
+  return example;
+};

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

@@ -0,0 +1,77 @@
+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 createUseSuspenseQueryOperationTSDocExample = (
+  operation: ServiceOperation,
+  serviceVariableName: string
+) => {
+  const example: string[] = [
+    'Performs asynchronous data fetching with Suspense support.',
+    'Similar to useQuery but integrates with React Suspense for loading states.',
+    '',
+    ...createOperationCommonTSDoc(operation),
+    '@see {@link https://openapi-qraft.github.io/openapi-qraft/docs/hooks/useSuspenseQuery|`useSuspenseQuery(...)` documentation}',
+  ];
+
+  if (
+    !operation.parameters?.length ||
+    operation.parameters.every((parameter) => !parameter.required)
+  ) {
+    example.push(
+      '@example Suspense Query without parameters',
+      '```ts',
+      ...(
+        'const data = ' +
+        astToString(
+          createOperationMethodCallExpressionExampleNode(
+            operation,
+            {
+              serviceVariableName,
+              operationMethodName: 'useSuspenseQuery',
+            },
+            undefined
+          )
+        )
+      )
+        .trim()
+        .split('\n'),
+      '```'
+    );
+  }
+
+  if (operation.parameters?.length) {
+    const factory = ts.factory;
+
+    example.push(
+      '@example Suspense Query with parameters',
+      '```ts',
+      ...(
+        'const data = ' +
+        astToString(
+          createOperationMethodCallExpressionExampleNode(
+            operation,
+            {
+              serviceVariableName,
+              operationMethodName: 'useSuspenseQuery',
+            },
+            [
+              factory.createObjectLiteralExpression(
+                createOperationMethodParametersExampleNodes(operation),
+                true
+              ),
+            ]
+          )
+        )
+      )
+        .trim()
+        .split('\n'),
+      '```'
+    );
+  }
+
+  return example;
+};