feat: Support string type for pageParam and nextPageParam options (#149)

Author: 7nohe

examples/nextjs-app/app/components/PaginatedPets.tsx

@@ -22,7 +22,7 @@ export default function PaginatedPets() {
           </React.Fragment>
         ))}
       </ul>
-      {data?.pages.at(-1)?.nextPage && (
+      {data?.pages.at(-1)?.meta?.next && (
         <button
           type="button"
           onClick={() => fetchNextPage()}

examples/nextjs-app/package.json

@@ -9,7 +9,7 @@
     "build": "next build",
     "start": "next start",
     "lint": "next lint",
-    "generate:api": "rimraf ./openapi && node ../../dist/cli.mjs -i ../petstore.yaml -c axios --request ./request.ts --format=biome --lint=biome"
+    "generate:api": "rimraf ./openapi && node ../../dist/cli.mjs -i ../petstore.yaml -c axios --request ./request.ts --format=biome --lint=biome --nextPageParam=meta.next"
   },
   "dependencies": {
     "@tanstack/react-query": "^5.32.1",

examples/petstore.yaml

@@ -176,10 +176,62 @@ paths:
                     type: array
                     items:
                       $ref: '#/components/schemas/Pet'
-                  nextPage: 
-                    type: integer
-                    format: int32
-                    minimum: 1
+                  meta: 
+                    type: object
+                    properties:
+                      next: 
+                        type: integer
+                        format: int32
+                        minimum: 1
+                      total: 
+                        type: integer
+  /cursor-based-pets:
+    get:
+      description: |
+        Returns cursor-based pets from the system that the user has access to
+      operationId: findCursorBasedPets
+      parameters:
+        - name: page
+          in: query
+          description: string to start from
+          required: false
+          schema:
+            type: string
+        - name: tags
+          in: query
+          description: tags to filter by
+          required: false
+          style: form
+          schema:
+            type: array
+            items:
+              type: string
+        - name: limit
+          in: query
+          description: maximum number of results to return
+          required: false
+          schema:
+            type: integer
+            format: int32
+      responses:
+        '200':
+          description: pet response
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  pets:
+                    type: array
+                    items:
+                      $ref: '#/components/schemas/Pet'
+                  meta: 
+                    type: object
+                    properties:
+                      next: 
+                        type: string
+                      total: 
+                        type: integer
 
 components:
   schemas:

examples/react-app/package.json

@@ -9,7 +9,7 @@
     "dev:mock": "prism mock ../petstore.yaml --dynamic",
     "build": "tsc && vite build",
     "preview": "vite preview",
-    "generate:api": "rimraf ./openapi && node ../../dist/cli.mjs -i ../petstore.yaml -c axios --request ./request.ts --format=biome --lint=biome",
+    "generate:api": "rimraf ./openapi && node ../../dist/cli.mjs -i ../petstore.yaml -c axios --request ./request.ts --format=biome --lint=biome --nextPageParam=meta.next",
     "test:generated": "tsc -p ./tsconfig.openapi.json --noEmit"
   },
   "dependencies": {

lefthook.yml

@@ -2,7 +2,7 @@ pre-commit:
   commands:
     check:
       glob: "*.{js,ts,cjs,mjs,d.cts,d.mts,jsx,tsx,json,jsonc}"
-      run: npx biome check --apply --no-errors-on-unmatched --files-ignore-unknown=true ./ && git update-index --again
+      run: npx biome check --write --no-errors-on-unmatched --files-ignore-unknown=true ./ && git update-index --again
     test:
       glob: "*.{js,ts,cjs,mjs,d.cts,d.mts,jsx,tsx,json,jsonc}"
       run: npx vitest run

src/cli.mts

@@ -103,11 +103,7 @@ async function setupProgram() {
       "Name of the response parameter used for next page",
       "nextPage",
     )
-    .option(
-      "--initialPageParam <value>",
-      "Initial page value to query",
-      "initialPageParam",
-    )
+    .option("--initialPageParam <value>", "Initial page value to query", "1")
     .parse();
 
   const options = program.opts<LimitedUserConfig>();

src/createUseQuery.mts

@@ -1,4 +1,4 @@
-import type { MethodDeclaration } from "ts-morph";
+import type { MethodDeclaration, Symbol as TMSymbol } from "ts-morph";
 import ts from "typescript";
 import {
   BuildCommonTypeName,
@@ -19,7 +19,10 @@ import { addJSDocToNode } from "./util.mjs";
 export const createApiResponseType = ({
   className,
   methodName,
-}: { className: string; methodName: string }) => {
+}: {
+  className: string;
+  methodName: string;
+}) => {
   /** Awaited<ReturnType<typeof myClass.myMethod>> */
   const awaitedResponseDataType = ts.factory.createTypeReferenceNode(
     ts.factory.createIdentifier("Awaited"),
@@ -44,7 +47,9 @@ export const createApiResponseType = ({
   const apiResponse = ts.factory.createTypeAliasDeclaration(
     [ts.factory.createModifier(ts.SyntaxKind.ExportKeyword)],
     ts.factory.createIdentifier(
-      `${capitalizeFirstLetter(className)}${capitalizeFirstLetter(methodName)}DefaultResponse`,
+      `${capitalizeFirstLetter(className)}${capitalizeFirstLetter(
+        methodName,
+      )}DefaultResponse`,
     ),
     undefined,
     awaitedResponseDataType,
@@ -146,7 +151,9 @@ export function createReturnTypeExport({
   return ts.factory.createTypeAliasDeclaration(
     [ts.factory.createModifier(ts.SyntaxKind.ExportKeyword)],
     ts.factory.createIdentifier(
-      `${capitalizeFirstLetter(className)}${capitalizeFirstLetter(methodName)}QueryResult`,
+      `${capitalizeFirstLetter(className)}${capitalizeFirstLetter(
+        methodName,
+      )}QueryResult`,
     ),
     [
       ts.factory.createTypeParameterDeclaration(
@@ -179,7 +186,11 @@ export function createQueryKeyExport({
   className,
   methodName,
   queryKey,
-}: { className: string; methodName: string; queryKey: string }) {
+}: {
+  className: string;
+  methodName: string;
+  queryKey: string;
+}) {
   return ts.factory.createVariableStatement(
     [ts.factory.createModifier(ts.SyntaxKind.ExportKeyword)],
     ts.factory.createVariableDeclarationList(
@@ -201,20 +212,56 @@ export function createQueryKeyExport({
 export function hookNameFromMethod({
   method,
   className,
-}: { method: MethodDeclaration; className: string }) {
+}: {
+  method: MethodDeclaration;
+  className: string;
+}) {
   const methodName = getNameFromMethod(method);
   return `use${className}${capitalizeFirstLetter(methodName)}`;
 }
 
 export function createQueryKeyFromMethod({
   method,
   className,
-}: { method: MethodDeclaration; className: string }) {
+}: {
+  method: MethodDeclaration;
+  className: string;
+}) {
   const customHookName = hookNameFromMethod({ method, className });
   const queryKey = `${customHookName}Key`;
   return queryKey;
 }
 
+/**
+ * Extracts the type of the next page parameter from the given properties.
+ *
+ * @param properties The properties to search through.
+ * @param nextPageParam The name of the next page parameter.
+ * @returns The type of the next page parameter, if found.
+ */
+function findNextPageParamType(
+  properties: TMSymbol[] | undefined,
+  nextPageParam: string,
+): string | undefined {
+  if (!properties) return undefined;
+
+  for (const property of properties) {
+    if (property.getName() === nextPageParam) {
+      return property?.getDeclarations()?.at(0)?.getType()?.getText();
+    }
+
+    const type = property.getDeclarations().at(0)?.getType();
+    const nestedProperties = type?.getProperties();
+
+    if (!type?.isObject() || type.isArray()) continue;
+
+    const result = findNextPageParamType(nestedProperties, nextPageParam);
+    if (result) return result;
+  }
+
+  return undefined;
+}
+
 /**
  * Creates a custom hook for a query
  * @param queryString The type of query to use from react-query
@@ -260,6 +307,18 @@ export function createQueryHook({
   const responseDataTypeIdentifier =
     responseDataTypeRef.typeName as ts.Identifier;
 
+  const arg = method.getReturnType().getTypeArguments().at(0);
+
+  const nextPageParamTypePropetires = arg?.getProperties();
+
+  const nextPageParamType =
+    arg?.isObject() && nextPageParam
+      ? findNextPageParamType(
+          nextPageParamTypePropetires,
+          nextPageParam.split(".").at(-1) ?? "",
+        )
+      : undefined;
+
   const hookExport = ts.factory.createVariableStatement(
     [ts.factory.createModifier(ts.SyntaxKind.ExportKeyword)],
     ts.factory.createVariableDeclarationList(
@@ -430,7 +489,11 @@ export function createQueryHook({
                                                   "pageParam",
                                                 ),
                                                 ts.factory.createKeywordTypeNode(
-                                                  ts.SyntaxKind.NumberKeyword,
+                                                  p.type?.getText() === "number"
+                                                    ? ts.SyntaxKind
+                                                        .NumberKeyword
+                                                    : ts.SyntaxKind
+                                                        .StringKeyword,
                                                 ),
                                               ),
                                             )
@@ -453,6 +516,7 @@ export function createQueryHook({
                     pageParam,
                     nextPageParam,
                     initialPageParam,
+                    nextPageParamType,
                   ),
                   ts.factory.createSpreadAssignment(
                     ts.factory.createIdentifier("options"),
@@ -637,6 +701,7 @@ function createInfiniteQueryParams(
   pageParam?: string,
   nextPageParam?: string,
   initialPageParam = "1",
+  type?: string,
 ) {
   if (pageParam === undefined || nextPageParam === undefined) {
     return [];
@@ -667,18 +732,23 @@ function createInfiniteQueryParams(
           ts.factory.createParenthesizedExpression(
             ts.factory.createAsExpression(
               ts.factory.createIdentifier("response"),
-              nextPageParam.split(".").reduceRight((acc, segment) => {
-                return ts.factory.createTypeLiteralNode([
-                  ts.factory.createPropertySignature(
-                    undefined,
-                    ts.factory.createIdentifier(segment),
-                    undefined,
-                    acc,
-                  ),
-                ]);
-              }, ts.factory.createKeywordTypeNode(
-                ts.SyntaxKind.NumberKeyword,
-              ) as ts.TypeNode),
+              nextPageParam.split(".").reduceRight(
+                (acc, segment) => {
+                  return ts.factory.createTypeLiteralNode([
+                    ts.factory.createPropertySignature(
+                      undefined,
+                      ts.factory.createIdentifier(segment),
+                      undefined,
+                      acc,
+                    ),
+                  ]);
+                },
+                ts.factory.createKeywordTypeNode(
+                  type === "number"
+                    ? ts.SyntaxKind.NumberKeyword
+                    : ts.SyntaxKind.StringKeyword,
+                ) as ts.TypeNode,
+              ),
             ),
           ),
           ts.factory.createIdentifier(nextPageParam),