@openapi-qraft/tanstack-query-react-plugin 2.0.0-next.9 → 2.0.1-beta.0

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

@@ -0,0 +1,292 @@
+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 { 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

@@ -1,8 +1,8 @@
-import { ServiceOperation } from '@openapi-qraft/plugin/lib/open-api/getServices';
+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 { createOperationMethodExampleNodes } from './lib/createOperationMethodExampleNodes.js';
+import { createOperationMethodCallExpressionExampleNode } from './lib/createOperationMethodCallExpressionExampleNode.js';
 import { createOperationMethodParametersExampleNodes } from './lib/createOperationMethodParametersExampleNodes.js';
 
 export const createUseQueryOperationTSDocExample = (
@@ -26,7 +26,7 @@ export const createUseQueryOperationTSDocExample = (
       ...(
         'const { data, isLoading } = ' +
         astToString(
-          createOperationMethodExampleNodes(
+          createOperationMethodCallExpressionExampleNode(
             operation,
             {
               serviceVariableName,
@@ -51,7 +51,7 @@ export const createUseQueryOperationTSDocExample = (
       ...(
         'const { data, isLoading } = ' +
         astToString(
-          createOperationMethodExampleNodes(
+          createOperationMethodCallExpressionExampleNode(
             operation,
             {
               serviceVariableName,

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

@@ -1,4 +1,4 @@
-import { ServiceOperation } from '@openapi-qraft/plugin/lib/open-api/getServices';
+import { ServiceOperation } from '@openapi-qraft/plugin/lib/open-api/OpenAPIService';
 import camelcase from 'camelcase';
 import ts from 'typescript';
 
@@ -46,7 +46,9 @@ export const createOperationMethodParametersExampleNodes = (
           factory.createObjectLiteralExpression(
             operationParameters.map((parameter) =>
               factory.createPropertyAssignment(
-                factory.createStringLiteral(parameter.name),
+                isIdentifierCompatibleVariableName(parameter.name)
+                  ? factory.createIdentifier(parameter.name)
+                  : factory.createStringLiteral(parameter.name),
                 parameter.example // todo:: add example type inferring
                   ? factory.createStringLiteral(parameter.example)
                   : factory.createIdentifier(
@@ -64,3 +66,18 @@ export const createOperationMethodParametersExampleNodes = (
     []
   );
 };
+
+/**
+ * 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);
+}

package/dist/ts-factory/tsdoc/lib/createOperationMethodExampleNodes.d.ts

@@ -1,7 +0,0 @@
-import { ServiceOperation } from '@openapi-qraft/plugin/lib/open-api/getServices';
-import ts from 'typescript';
-export declare const createOperationMethodExampleNodes: (operation: ServiceOperation, { serviceVariableName, operationMethodName, }: {
-    serviceVariableName: string;
-    operationMethodName: string;
-}, nodes: ts.Expression[] | undefined) => ts.ExpressionStatement[];
-//# sourceMappingURL=createOperationMethodExampleNodes.d.ts.map

package/dist/ts-factory/tsdoc/lib/createOperationMethodExampleNodes.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"createOperationMethodExampleNodes.d.ts","sourceRoot":"","sources":["../../../../src/ts-factory/tsdoc/lib/createOperationMethodExampleNodes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,gDAAgD,CAAC;AAClF,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B,eAAO,MAAM,iCAAiC,cACjC,gBAAgB,iDAIxB;IAAE,mBAAmB,EAAE,MAAM,CAAC;IAAC,mBAAmB,EAAE,MAAM,CAAA;CAAE,SACxD,EAAE,CAAC,UAAU,EAAE,GAAG,SAAS,6BAsBnC,CAAC"}

package/dist/ts-factory/tsdoc/lib/createOperationMethodExampleNodes.js

@@ -1,8 +0,0 @@
-import ts from 'typescript';
-export const createOperationMethodExampleNodes = (operation, { serviceVariableName, operationMethodName, }, nodes) => {
-    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)),
-    ];
-};
-//# sourceMappingURL=createOperationMethodExampleNodes.js.map

package/dist/ts-factory/tsdoc/lib/createOperationMethodExampleNodes.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"createOperationMethodExampleNodes.js","sourceRoot":"","sources":["../../../../src/ts-factory/tsdoc/lib/createOperationMethodExampleNodes.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B,MAAM,CAAC,MAAM,iCAAiC,GAAG,CAC/C,SAA2B,EAC3B,EACE,mBAAmB,EACnB,mBAAmB,GAC0C,EAC/D,KAAkC,EAClC,EAAE;IACF,MAAM,OAAO,GAAG,EAAE,CAAC,OAAO,CAAC;IAE3B,OAAO;QACL,OAAO,CAAC,yBAAyB,CAC/B,OAAO,CAAC,oBAAoB,CAC1B,OAAO,CAAC,8BAA8B,CACpC,OAAO,CAAC,8BAA8B,CACpC,OAAO,CAAC,8BAA8B,CACpC,OAAO,CAAC,gBAAgB,CAAC,OAAO,CAAC,EACjC,OAAO,CAAC,gBAAgB,CAAC,mBAAmB,CAAC,CAC9C,EACD,OAAO,CAAC,gBAAgB,CAAC,SAAS,CAAC,IAAI,CAAC,CACzC,EACD,OAAO,CAAC,gBAAgB,CAAC,mBAAmB,CAAC,CAC9C,EACD,SAAS,EACT,KAAK,CACN,CACF;KACF,CAAC;AACJ,CAAC,CAAC"}

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

@@ -1,32 +0,0 @@
-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
-      )
-    ),
-  ];
-};