@7nohe/openapi-react-query-codegen 1.2.0 → 1.2.1

package/README.md

@@ -2,13 +2,15 @@
 
 > Node.js library that generates [React Query (also called TanStack Query)](https://tanstack.com/query) hooks based on an OpenAPI specification file.
 
+[![npm version](https://badge.fury.io/js/%407nohe%2Fopenapi-react-query-codegen.svg)](https://badge.fury.io/js/%407nohe%2Fopenapi-react-query-codegen)
+
 ## Features
 
-- Supports generation of custom react hooks that use React Query's `useQuery` and `useMutation` hooks
-- Supports generation of query keys for query caching
-- Supports the option to use pure TypeScript clients generated by [@hey-api/openapi-ts](https://github.com/hey-api/openapi-ts)
+- Generates custom react hooks that use React Query's `useQuery`, `useSuspenseQuery` and `useMutation` hooks
+- Generates query keys and functions for query caching
+- Generates pure TypeScript clients generated by [@hey-api/openapi-ts](https://github.com/hey-api/openapi-ts)
 
-## Install
+## Installation
 
 ```
 $ npm install -D @7nohe/openapi-react-query-codegen
@@ -48,7 +50,7 @@ Options:
   --format <value>           Process output folder with formatter? ['biome', 'prettier']
   --lint   <value>           Process output folder with linter? ['eslint', 'biome']
   --operationId              Use operation ID to generate operation names?
-  --serviceResponse <value>  Define shape of returned value from service calls ['body', 'generics', 'response']
+  --serviceResponse <value>  Define shape of returned value from service calls ['body', 'response'] (default: "body")
   --base <value>             Manually set base in OpenAPI config instead of inferring from server value
   --enums <value>            Generate JavaScript objects from enum definitions? ['javascript', 'typescript']
   --useDateType              Use Date type instead of string for date types for models, this will not convert the data to a Date object
@@ -58,27 +60,32 @@ Options:
   -h, --help                 display help for command
 ```
 
-## Example Usage
+### Example Usage
 
-### Command
+#### Command
 
 ```
 $ openapi-rq -i ./petstore.yaml
 ```
 
-### Output directory structure
+#### Output directory structure
 
 ```
 - openapi
   - queries
-    - index.ts <- main file that exports common types, variables, and hooks
+    - index.ts <- main file that exports common types, variables, and queries. Does not export suspense or prefetch hooks
     - common.ts <- common types
     - queries.ts <- generated query hooks
     - suspenses.ts <- generated suspense hooks
+    - prefetch.ts <- generated prefetch hooks learn more about prefetching in in link below
   - requests <- output code generated by @hey-api/openapi-ts
 ```
 
-### In your app
+- [Prefetching docs](https://tanstack.com/query/latest/docs/framework/react/guides/advanced-ssr#prefetching-and-dehydrating-data)
+
+#### In your app
+
+##### Using the generated hooks
 
 ```tsx
 // App.tsx
@@ -97,7 +104,7 @@ function App() {
 export default App;
 ```
 
-You can also use pure TS clients.
+##### Using the generated typescript client
 
 ```tsx
 import { useQuery } from "@tanstack/react-query";
@@ -120,7 +127,7 @@ function App() {
 export default App;
 ```
 
-You can also use suspense hooks.
+##### Using Suspense Hooks
 
 ```tsx
 // App.tsx
@@ -153,6 +160,34 @@ function App() {
 export default App;
 ```
 
+##### Runtime Configuration
+
+You can modify the default values used by the generated service calls by modifying the OpenAPI configuration singleton object.
+
+It's default location is `openapi/requests/core/OpenAPI.ts` and it is also exported from `openapi/index.ts`
+
+Import the constant into your runtime and modify it before setting up the react app.
+
+```typescript
+/** main.tsx */
+import { OpenAPI as OpenAPIConfig } from './openapi/requests/core/OpenAPI';
+...
+OpenAPIConfig.BASE = 'www.domain.com/api';
+OpenAPIConfig.HEADERS = {
+  'x-header-1': 'value-1',
+  'x-header-2': 'value-2',
+};
+...
+ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
+  <React.StrictMode>
+    <QueryClientProvider client={queryClient}>
+      <App />
+    </QueryClientProvider>
+  </React.StrictMode>
+);
+
+```
+
 ## License
 
 MIT

package/dist/cli.mjs

@@ -25,7 +25,9 @@ async function setupProgram() {
         .addOption(new Option("--format <value>", "Process output folder with formatter?").choices(["biome", "prettier"]))
         .addOption(new Option("--lint <value>", "Process output folder with linter?").choices(["biome", "eslint"]))
         .option("--operationId", "Use operation ID to generate operation names?")
-        .addOption(new Option("--serviceResponse <value>", "Define shape of returned value from service calls").choices(["body", "response"]))
+        .addOption(new Option("--serviceResponse <value>", "Define shape of returned value from service calls")
+        .choices(["body", "response"])
+        .default("body"))
         .option("--base <value>", "Manually set base in OpenAPI config instead of inferring from server value")
         .addOption(new Option("--enums <value>", "Generate JavaScript objects from enum definitions?").choices(["javascript", "typescript"]))
         .option("--useDateType", "Use Date type instead of string for date types for models, this will not convert the data to a Date object")

package/dist/constants.mjs

@@ -3,3 +3,10 @@ export const queriesOutputPath = "queries";
 export const requestsOutputPath = "requests";
 export const serviceFileName = "services.gen";
 export const modalsFileName = "types.gen";
+export const OpenApiRqFiles = {
+    queries: "queries",
+    common: "common",
+    suspense: "suspense",
+    index: "index",
+    prefetch: "prefetch",
+};

package/dist/createExports.mjs

@@ -1,5 +1,6 @@
 import { createUseQuery } from "./createUseQuery.mjs";
 import { createUseMutation } from "./createUseMutation.mjs";
+import { createPrefetch } from "./createPrefetch.mjs";
 export const createExports = (service) => {
     const { klasses } = service;
     const methods = klasses.map((k) => k.methods).flat();
@@ -9,6 +10,7 @@ export const createExports = (service) => {
     const allPatch = methods.filter((m) => m.httpMethodName.toUpperCase().includes("PATCH"));
     const allDelete = methods.filter((m) => m.httpMethodName.toUpperCase().includes("DELETE"));
     const allGetQueries = allGet.map((m) => createUseQuery(m));
+    const allPrefetchQueries = allGet.map((m) => createPrefetch(m));
     const allPostMutations = allPost.map((m) => createUseMutation(m));
     const allPutMutations = allPut.map((m) => createUseMutation(m));
     const allPatchMutations = allPatch.map((m) => createUseMutation(m));
@@ -36,6 +38,10 @@ export const createExports = (service) => {
         .map(({ suspenseQueryHook }) => [suspenseQueryHook])
         .flat();
     const suspenseExports = [...suspenseQueries];
+    const allPrefetches = allPrefetchQueries
+        .map(({ prefetchHook }) => [prefetchHook])
+        .flat();
+    const allPrefetchExports = [...allPrefetches];
     return {
         /**
          * Common types and variables between queries (regular and suspense) and mutations
@@ -49,5 +55,9 @@ export const createExports = (service) => {
          * Suspense exports are the hooks that are used in the suspense components
          */
         suspenseExports,
+        /**
+         * Prefetch exports are the hooks that are used in the prefetch components
+         */
+        allPrefetchExports,
     };
 };

package/dist/createPrefetch.mjs

@@ -0,0 +1,58 @@
+import ts from "typescript";
+import { BuildCommonTypeName, extractPropertiesFromObjectParam, getNameFromMethod, } from "./common.mjs";
+import { createQueryKeyFromMethod, getRequestParamFromMethod, hookNameFromMethod, } from "./createUseQuery.mjs";
+import { addJSDocToNode } from "./util.mjs";
+/**
+ * Creates a prefetch function for a query
+ */
+function createPrefetchHook({ requestParams, method, className, }) {
+    const methodName = getNameFromMethod(method);
+    const queryName = hookNameFromMethod({ method, className });
+    const customHookName = `prefetch${queryName.charAt(0).toUpperCase() + queryName.slice(1)}`;
+    const queryKey = createQueryKeyFromMethod({ method, className });
+    // const
+    const hookExport = ts.factory.createVariableStatement(
+    // export
+    [ts.factory.createModifier(ts.SyntaxKind.ExportKeyword)], ts.factory.createVariableDeclarationList([
+        ts.factory.createVariableDeclaration(ts.factory.createIdentifier(customHookName), undefined, undefined, ts.factory.createArrowFunction(undefined, undefined, [
+            ts.factory.createParameterDeclaration(undefined, undefined, "queryClient", undefined, ts.factory.createTypeReferenceNode(ts.factory.createIdentifier("QueryClient"))),
+            ...requestParams,
+        ], undefined, ts.factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken), ts.factory.createCallExpression(ts.factory.createIdentifier("queryClient.prefetchQuery"), undefined, [
+            ts.factory.createObjectLiteralExpression([
+                ts.factory.createPropertyAssignment(ts.factory.createIdentifier("queryKey"), ts.factory.createArrayLiteralExpression([
+                    BuildCommonTypeName(queryKey),
+                    method.getParameters().length
+                        ? ts.factory.createArrayLiteralExpression([
+                            ts.factory.createObjectLiteralExpression(method
+                                .getParameters()
+                                .map((param) => extractPropertiesFromObjectParam(param).map((p) => ts.factory.createShorthandPropertyAssignment(ts.factory.createIdentifier(p.name))))
+                                .flat()),
+                        ])
+                        : ts.factory.createArrayLiteralExpression([]),
+                ], false)),
+                ts.factory.createPropertyAssignment(ts.factory.createIdentifier("queryFn"), ts.factory.createArrowFunction(undefined, undefined, [], undefined, ts.factory.createToken(ts.SyntaxKind.EqualsGreaterThanToken), ts.factory.createCallExpression(ts.factory.createPropertyAccessExpression(ts.factory.createIdentifier(className), ts.factory.createIdentifier(methodName)), undefined, method.getParameters().length
+                    ? [
+                        ts.factory.createObjectLiteralExpression(method
+                            .getParameters()
+                            .map((param) => extractPropertiesFromObjectParam(param).map((p) => ts.factory.createShorthandPropertyAssignment(ts.factory.createIdentifier(p.name))))
+                            .flat()),
+                    ]
+                    : undefined))),
+            ]),
+        ]))),
+    ], ts.NodeFlags.Const));
+    return hookExport;
+}
+export const createPrefetch = ({ className, method, jsDoc, }) => {
+    const requestParam = getRequestParamFromMethod(method);
+    const requestParams = requestParam ? [requestParam] : [];
+    const prefetchHook = createPrefetchHook({
+        requestParams,
+        method,
+        className,
+    });
+    const hookWithJsDoc = addJSDocToNode(prefetchHook, jsDoc);
+    return {
+        prefetchHook: hookWithJsDoc,
+    };
+};

package/dist/createSource.mjs

@@ -1,9 +1,10 @@
 import ts from "typescript";
+import { Project } from "ts-morph";
+import { join } from "path";
+import { OpenApiRqFiles } from "./constants.mjs";
 import { createImports } from "./createImports.mjs";
 import { createExports } from "./createExports.mjs";
 import { getServices } from "./service.mjs";
-import { Project } from "ts-morph";
-import { join } from "path";
 const createSourceFile = async (outputPath, serviceEndName) => {
     const project = new Project({
         // Optionally specify compiler options, tsconfig.json, in-memory file system, and more here.
@@ -21,29 +22,32 @@ const createSourceFile = async (outputPath, serviceEndName) => {
     });
     const exports = createExports(service);
     const commonSource = ts.factory.createSourceFile([...imports, ...exports.allCommon], ts.factory.createToken(ts.SyntaxKind.EndOfFileToken), ts.NodeFlags.None);
-    const commonImport = ts.factory.createImportDeclaration(undefined, ts.factory.createImportClause(false, ts.factory.createIdentifier("* as Common"), undefined), ts.factory.createStringLiteral("./common"), undefined);
-    const commonExport = ts.factory.createExportDeclaration(undefined, false, undefined, ts.factory.createStringLiteral("./common"), undefined);
-    const queriesExport = ts.factory.createExportDeclaration(undefined, false, undefined, ts.factory.createStringLiteral("./queries"), undefined);
+    const commonImport = ts.factory.createImportDeclaration(undefined, ts.factory.createImportClause(false, ts.factory.createIdentifier("* as Common"), undefined), ts.factory.createStringLiteral(`./${OpenApiRqFiles.common}`), undefined);
+    const commonExport = ts.factory.createExportDeclaration(undefined, false, undefined, ts.factory.createStringLiteral(`./${OpenApiRqFiles.common}`), undefined);
+    const queriesExport = ts.factory.createExportDeclaration(undefined, false, undefined, ts.factory.createStringLiteral(`./${OpenApiRqFiles.queries}`), undefined);
     const mainSource = ts.factory.createSourceFile([commonImport, ...imports, ...exports.mainExports], ts.factory.createToken(ts.SyntaxKind.EndOfFileToken), ts.NodeFlags.None);
     const suspenseSource = ts.factory.createSourceFile([commonImport, ...imports, ...exports.suspenseExports], ts.factory.createToken(ts.SyntaxKind.EndOfFileToken), ts.NodeFlags.None);
     const indexSource = ts.factory.createSourceFile([commonExport, queriesExport], ts.factory.createToken(ts.SyntaxKind.EndOfFileToken), ts.NodeFlags.None);
+    const prefetchSource = ts.factory.createSourceFile([commonImport, ...imports, ...exports.allPrefetchExports], ts.factory.createToken(ts.SyntaxKind.EndOfFileToken), ts.NodeFlags.None);
     return {
         commonSource,
         mainSource,
         suspenseSource,
         indexSource,
+        prefetchSource,
     };
 };
 export const createSource = async ({ outputPath, version, serviceEndName, }) => {
-    const queriesFile = ts.createSourceFile("queries.ts", "", ts.ScriptTarget.Latest, false, ts.ScriptKind.TS);
-    const commonFile = ts.createSourceFile("common.ts", "", ts.ScriptTarget.Latest, false, ts.ScriptKind.TS);
-    const suspenseFile = ts.createSourceFile("suspense.ts", "", ts.ScriptTarget.Latest, false, ts.ScriptKind.TS);
-    const indexFile = ts.createSourceFile("index.ts", "", ts.ScriptTarget.Latest, false, ts.ScriptKind.TS);
+    const queriesFile = ts.createSourceFile(`${OpenApiRqFiles.queries}.ts`, "", ts.ScriptTarget.Latest, false, ts.ScriptKind.TS);
+    const commonFile = ts.createSourceFile(`${OpenApiRqFiles.common}.ts`, "", ts.ScriptTarget.Latest, false, ts.ScriptKind.TS);
+    const suspenseFile = ts.createSourceFile(`${OpenApiRqFiles.suspense}.ts`, "", ts.ScriptTarget.Latest, false, ts.ScriptKind.TS);
+    const indexFile = ts.createSourceFile(`${OpenApiRqFiles.index}.ts`, "", ts.ScriptTarget.Latest, false, ts.ScriptKind.TS);
+    const prefetchFile = ts.createSourceFile(`${OpenApiRqFiles.prefetch}.ts`, "", ts.ScriptTarget.Latest, false, ts.ScriptKind.TS);
     const printer = ts.createPrinter({
         newLine: ts.NewLineKind.LineFeed,
         removeComments: false,
     });
-    const { commonSource, mainSource, suspenseSource, indexSource } = await createSourceFile(outputPath, serviceEndName);
+    const { commonSource, mainSource, suspenseSource, indexSource, prefetchSource, } = await createSourceFile(outputPath, serviceEndName);
     const comment = `// generated with @7nohe/openapi-react-query-codegen@${version} \n\n`;
     const commonResult = comment +
         printer.printNode(ts.EmitHint.Unspecified, commonSource, commonFile);
@@ -53,22 +57,28 @@ export const createSource = async ({ outputPath, version, serviceEndName, }) =>
         printer.printNode(ts.EmitHint.Unspecified, suspenseSource, suspenseFile);
     const indexResult = comment +
         printer.printNode(ts.EmitHint.Unspecified, indexSource, indexFile);
+    const prefetchResult = comment +
+        printer.printNode(ts.EmitHint.Unspecified, prefetchSource, prefetchFile);
     return [
         {
-            name: "index.ts",
+            name: `${OpenApiRqFiles.index}.ts`,
             content: indexResult,
         },
         {
-            name: "common.ts",
+            name: `${OpenApiRqFiles.common}.ts`,
             content: commonResult,
         },
         {
-            name: "queries.ts",
+            name: `${OpenApiRqFiles.queries}.ts`,
             content: mainResult,
         },
         {
-            name: "suspense.ts",
+            name: `${OpenApiRqFiles.suspense}.ts`,
             content: suspenseResult,
         },
+        {
+            name: `${OpenApiRqFiles.prefetch}.ts`,
+            content: prefetchResult,
+        },
     ];
 };

package/dist/createUseQuery.mjs

@@ -73,11 +73,11 @@ export function createQueryKeyExport({ className, methodName, queryKey, }) {
         ts.factory.createVariableDeclaration(ts.factory.createIdentifier(queryKey), undefined, undefined, ts.factory.createStringLiteral(`${className}${capitalizeFirstLetter(methodName)}`)),
     ], ts.NodeFlags.Const));
 }
-function hookNameFromMethod({ method, className, }) {
+export function hookNameFromMethod({ method, className, }) {
     const methodName = getNameFromMethod(method);
     return `use${className}${capitalizeFirstLetter(methodName)}`;
 }
-function createQueryKeyFromMethod({ method, className, }) {
+export function createQueryKeyFromMethod({ method, className, }) {
     const customHookName = hookNameFromMethod({ method, className });
     const queryKey = `${customHookName}Key`;
     return queryKey;
@@ -87,7 +87,7 @@ function createQueryKeyFromMethod({ method, className, }) {
  * @param queryString The type of query to use from react-query
  * @param suffix The suffix to append to the hook name
  */
-function createQueryHook({ queryString, suffix, responseDataType, requestParams, method, className, }) {
+export function createQueryHook({ queryString, suffix, responseDataType, requestParams, method, className, }) {
     const methodName = getNameFromMethod(method);
     const customHookName = hookNameFromMethod({ method, className });
     const queryKey = createQueryKeyFromMethod({ method, className });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@7nohe/openapi-react-query-codegen",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "OpenAPI React Query Codegen",
   "bin": {
     "openapi-rq": "dist/cli.mjs"