fix: types when paginationField is in body (#3635)

ntucker · web-flow · commit 63ee107be9d5 · 2025-11-28T13:21:18.000-05:00
diff --git a/.changeset/lucky-paws-jog.md b/.changeset/lucky-paws-jog.md
@@ -0,0 +1,16 @@
+---
+'@data-client/rest': patch
+---
+
+Fix `getPage` types when paginationField is in body
+
+```ts
+const ep = new RestEndpoint({
+  path: '/rpc',
+  method: 'POST',
+  body: {} as { page?: number; method: string },
+  paginationField: 'page',
+});
+// Before: ep.getPage({ page: 2 }, { method: 'get' }) ❌
+// After:  ep.getPage({ page: 2, method: 'get' })     ✓
+```
diff --git a/packages/rest/src/RestEndpointTypes.ts b/packages/rest/src/RestEndpointTypes.ts
@@ -376,21 +376,70 @@ export type PaginationEndpoint<
     searchParams: Omit<A[0], keyof PathArgs<E['path']>>;
   }
 >;
-export type PaginationFieldEndpoint<
+/** Merge pagination field C into body, making it required */
+type PaginationIntoBody<Body, C extends string> = Body & {
+  [K in C]: string | number | boolean;
+};
+
+/** Paginated searchParams type */
+type PaginatedSearchParams<
+  E extends { searchParams?: any; path?: string },
+  C extends string,
+> = {
+  [K in C]: string | number | boolean;
+} & E['searchParams'] &
+  PathArgs<Exclude<E['path'], undefined>>;
+
+/** searchParams version: pagination in searchParams, optional body support */
+type PaginationFieldInSearchParams<
+  E extends FetchFunction & RestGenerics & { sideEffect?: boolean | undefined },
+  C extends string,
+> = RestInstanceBase<
+  // Union allows calling with just searchParams or with searchParams + body
+  | ParamFetchNoBody<PaginatedSearchParams<E, C>, ResolveType<E>>
+  | ParamFetchWithBody<
+      PaginatedSearchParams<E, C>,
+      NonNullable<E['body']>,
+      ResolveType<E>
+    >,
+  E['schema'],
+  E['sideEffect'],
+  Pick<E, 'path' | 'searchParams' | 'body'> & {
+    searchParams: {
+      [K in C]: string | number | boolean;
+    } & E['searchParams'];
+  }
+> & { paginationField: C };
+
+/** body version: pagination field is in body (body required) */
+type PaginationFieldInBody<
   E extends FetchFunction & RestGenerics & { sideEffect?: boolean | undefined },
   C extends string,
 > = RestInstanceBase<
-  ParamFetchNoBody<
-    { [K in C]: string | number | boolean } & E['searchParams'] &
-      PathArgs<Exclude<E['path'], undefined>>,
+  ParamFetchWithBody<
+    E['searchParams'] & PathArgs<Exclude<E['path'], undefined>>,
+    PaginationIntoBody<E['body'], C>,
     ResolveType<E>
   >,
   E['schema'],
   E['sideEffect'],
-  Pick<E, 'path' | 'searchParams' | 'body'> & {
-    searchParams: { [K in C]: string | number | boolean } & E['searchParams'];
+  Pick<E, 'path' | 'searchParams'> & {
+    body: PaginationIntoBody<E['body'], C>;
   }
 > & { paginationField: C };
+
+/** Retrieves the next page of results by pagination field */
+export type PaginationFieldEndpoint<
+  E extends FetchFunction & RestGenerics & { sideEffect?: boolean | undefined },
+  C extends string,
+> =
+  // If body can be undefined or pagination field not in body, use searchParams
+  undefined extends E['body'] ? PaginationFieldInSearchParams<E, C>
+  : // If pagination field C is a key of body, merge into body
+  C extends keyof E['body'] ? PaginationFieldInBody<E, C>
+  : // Otherwise use searchParams
+    PaginationFieldInSearchParams<E, C>;
+
 export type AddEndpoint<
   F extends FetchFunction = FetchFunction,
   S extends Schema | undefined = any,
diff --git a/packages/rest/typescript-tests/types.test.ts b/packages/rest/typescript-tests/types.test.ts
@@ -1,7 +1,6 @@
-/* eslint-disable @typescript-eslint/ban-ts-comment */
 import { Entity, schema } from '@data-client/endpoint';
 import { useController, useSuspense } from '@data-client/react';
-import { User } from '__tests__/new';
+import { User, Article } from '__tests__/new';
 
 import resource from '../src/resource';
 import RestEndpoint, { GetEndpoint, MutateEndpoint } from '../src/RestEndpoint';
@@ -424,6 +423,172 @@ it('should precisely type function arguments', () => {
   };
 });
 
+it('should handle POST getter endpoints', () => {
+  () => {
+    const getUsers = new RestEndpoint({
+      path: '/users',
+      method: 'POST',
+      sideEffect: false,
+      body: {} as {
+        page?: number;
+        jsonrpc: string;
+        id: number;
+        method: string;
+        params: any[];
+      },
+      paginationField: 'page',
+      schema: new schema.Collection([User]),
+    });
+    getUsers({ jsonrpc: '2.0', id: 1, method: 'users.get', params: [] });
+    useSuspense(getUsers, {
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'users.get',
+      params: [],
+    });
+    // @ts-expect-error
+    getEth({ id: 1, method: 'users.get', params: [] });
+    // @ts-expect-error
+    useSuspense(getUsers, { id: 1, method: 'users.get', params: [] });
+
+    // getPage tests
+    getUsers.getPage({
+      page: 2,
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'users.get',
+      params: [],
+    });
+    getUsers.getPage({
+      // @ts-expect-error page is not a number | string
+      page: { bob: 'hi' },
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'users.get',
+      params: [],
+    });
+    getUsers.getPage({
+      // @ts-expect-error page is not a number | string
+      page: undefined,
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'users.get',
+      params: [],
+    });
+    // @ts-expect-error
+    getUsers.getPage({
+      jsonrpc: '2.0',
+      id: 1,
+      method: 'users.get',
+      params: [],
+    });
+    // @ts-expect-error
+    getUsers.getPage({
+      page: 2,
+      id: 1,
+      method: 'users.get',
+      params: [],
+    });
+    getUsers.getPage(
+      { page: 2 },
+      // @ts-expect-error
+      { jsonrpc: '2.0', id: 1, method: 'users.get', params: [] },
+    );
+  };
+  () => {
+    const getArticles = new RestEndpoint({
+      path: '/articles',
+      method: 'POST',
+      sideEffect: false,
+      searchParams: {} as {
+        page_number?: number;
+        groupId?: string | number;
+      },
+      body: {} as
+        | {
+            authorId?: string | number;
+            createdAt?: string;
+          }
+        | undefined,
+      schema: new schema.Collection([Article]),
+      paginationField: 'page_number',
+    });
+    getArticles({ authorId: 1, createdAt: '2025-01-01' });
+    useSuspense(getArticles, { authorId: 1, createdAt: '2025-01-01' });
+    // @ts-expect-error
+    getArticles({ authorId: 1, createdAt: '2025-01-01', page: 2 });
+    // @ts-expect-error
+    useSuspense(getArticles, { authorId: 1, createdAt: '2025-01-01', page: 2 });
+    getArticles();
+    getArticles({ page_number: 2 });
+    getArticles({ page_number: 2 }, { authorId: 5 });
+
+    getArticles.getPage({ page_number: 2 });
+    getArticles.getPage({ page_number: 2, groupId: 5 });
+    getArticles.getPage({ page_number: 2 }, { authorId: 5 });
+    getArticles.getPage(
+      { page_number: 2 },
+      { authorId: 5, createdAt: '2025-01-01' },
+    );
+
+    // @ts-expect-error requires page_number
+    getArticles.getPage();
+    // @ts-expect-error requires page_number
+    getArticles.getPage({});
+    // @ts-expect-error requires page_number
+    getArticles.getPage({ groupId: 5 });
+    // @ts-expect-error page_number is not a valid search param
+    getArticles.getPage({ page: 5 });
+    // @ts-expect-error page is not page_number
+    getArticles.getPage({ page: 5 });
+    // @ts-expect-error adsdf is not a valid search param
+    getArticles.getPage({ page_number: 2, adsdf: 5 });
+  };
+  () => {
+    const getArticles = new RestEndpoint({
+      path: '/articles/:groupId?',
+      method: 'POST',
+      sideEffect: false,
+      body: {} as
+        | {
+            authorId?: string | number;
+            createdAt?: string;
+          }
+        | undefined,
+      schema: new schema.Collection([Article]),
+      paginationField: 'page_number',
+    });
+    getArticles({ authorId: 1, createdAt: '2025-01-01' });
+    useSuspense(getArticles, { authorId: 1, createdAt: '2025-01-01' });
+    // @ts-expect-error
+    getArticles({ authorId: 1, createdAt: '2025-01-01', page: 2 });
+    // @ts-expect-error
+    useSuspense(getArticles, { authorId: 1, createdAt: '2025-01-01', page: 2 });
+    getArticles();
+
+    getArticles.getPage({ page_number: 2 });
+    getArticles.getPage({ page_number: 2, groupId: 5 });
+    getArticles.getPage({ page_number: 2 }, { authorId: 5 });
+    getArticles.getPage(
+      { page_number: 2 },
+      { authorId: 5, createdAt: '2025-01-01' },
+    );
+
+    // @ts-expect-error requires page_number
+    getArticles.getPage();
+    // @ts-expect-error requires page_number
+    getArticles.getPage({});
+    // @ts-expect-error requires page_number
+    getArticles.getPage({ groupId: 5 });
+    // @ts-expect-error page_number is not a valid search param
+    getArticles.getPage({ page: 5 });
+    // @ts-expect-error page is not page_number
+    getArticles.getPage({ page: 5 });
+    // @ts-expect-error adsdf is not a valid search param
+    getArticles.getPage({ page_number: 2, adsdf: 5 });
+  };
+});
+
 it('should allow sideEffect overrides', () => {
   () => {
     const getEth = new RestEndpoint({
diff --git a/website/src/components/Playground/editor-types/@data-client/rest.d.ts b/website/src/components/Playground/editor-types/@data-client/rest.d.ts
@@ -1205,6 +1205,7 @@ type ExtractCollection<S extends Schema | undefined> = S extends ({
     push: any;
     unshift: any;
     assign: any;
+    remove: any;
     schema: Schema;
 }) ? S : S extends Object$1<infer T> ? ExtractObject<T> : S extends Exclude<Schema, {
     [K: string]: any;
@@ -1356,6 +1357,12 @@ interface RestInstance<F extends FetchFunction = FetchFunction, S extends Schema
     assign: AddEndpoint<F, ExtractCollection<S>, Exclude<O, 'body' | 'method'> & {
         body: Record<string, OptionsToAdderBodyArgument<O>> | FormData;
     }>;
+    /** Remove item(s) (PATCH) from collection
+     * @see https://dataclient.io/rest/api/RestEndpoint#remove
+     */
+    remove: RemoveEndpoint<F, ExtractCollection<S>['remove'], Exclude<O, 'body' | 'method'> & {
+        body: OptionsToAdderBodyArgument<O> | OptionsToAdderBodyArgument<O>[] | FormData;
+    }>;
 }
 type RestEndpointExtendOptions<O extends PartialRestGenerics, E extends {
     body?: any;
@@ -1430,17 +1437,39 @@ type PaginationEndpoint<E extends FetchFunction & RestGenerics & {
 }, A extends any[]> = RestInstanceBase<ParamFetchNoBody<A[0], ResolveType<E>>, E['schema'], E['sideEffect'], Pick<E, 'path' | 'searchParams' | 'body'> & {
     searchParams: Omit<A[0], keyof PathArgs<E['path']>>;
 }>;
-type PaginationFieldEndpoint<E extends FetchFunction & RestGenerics & {
-    sideEffect?: boolean | undefined;
-}, C extends string> = RestInstanceBase<ParamFetchNoBody<{
+/** Merge pagination field C into body, making it required */
+type PaginationIntoBody<Body, C extends string> = Body & {
+    [K in C]: string | number | boolean;
+};
+/** Paginated searchParams type */
+type PaginatedSearchParams<E extends {
+    searchParams?: any;
+    path?: string;
+}, C extends string> = {
     [K in C]: string | number | boolean;
-} & E['searchParams'] & PathArgs<Exclude<E['path'], undefined>>, ResolveType<E>>, E['schema'], E['sideEffect'], Pick<E, 'path' | 'searchParams' | 'body'> & {
+} & E['searchParams'] & PathArgs<Exclude<E['path'], undefined>>;
+/** searchParams version: pagination in searchParams, optional body support */
+type PaginationFieldInSearchParams<E extends FetchFunction & RestGenerics & {
+    sideEffect?: boolean | undefined;
+}, C extends string> = RestInstanceBase<ParamFetchNoBody<PaginatedSearchParams<E, C>, ResolveType<E>> | ParamFetchWithBody<PaginatedSearchParams<E, C>, NonNullable<E['body']>, ResolveType<E>>, E['schema'], E['sideEffect'], Pick<E, 'path' | 'searchParams' | 'body'> & {
     searchParams: {
         [K in C]: string | number | boolean;
     } & E['searchParams'];
 }> & {
     paginationField: C;
 };
+/** body version: pagination field is in body (body required) */
+type PaginationFieldInBody<E extends FetchFunction & RestGenerics & {
+    sideEffect?: boolean | undefined;
+}, C extends string> = RestInstanceBase<ParamFetchWithBody<E['searchParams'] & PathArgs<Exclude<E['path'], undefined>>, PaginationIntoBody<E['body'], C>, ResolveType<E>>, E['schema'], E['sideEffect'], Pick<E, 'path' | 'searchParams'> & {
+    body: PaginationIntoBody<E['body'], C>;
+}> & {
+    paginationField: C;
+};
+/** Retrieves the next page of results by pagination field */
+type PaginationFieldEndpoint<E extends FetchFunction & RestGenerics & {
+    sideEffect?: boolean | undefined;
+}, C extends string> = undefined extends E['body'] ? PaginationFieldInSearchParams<E, C> : C extends keyof E['body'] ? PaginationFieldInBody<E, C> : PaginationFieldInSearchParams<E, C>;
 type AddEndpoint<F extends FetchFunction = FetchFunction, S extends Schema | undefined = any, O extends {
     path: string;
     body: any;
@@ -1451,6 +1480,16 @@ type AddEndpoint<F extends FetchFunction = FetchFunction, S extends Schema | und
 }> = RestInstanceBase<RestFetch<'searchParams' extends keyof O ? O['searchParams'] extends undefined ? PathArgs<Exclude<O['path'], undefined>> : O['searchParams'] & PathArgs<Exclude<O['path'], undefined>> : PathArgs<Exclude<O['path'], undefined>>, O['body'], ResolveType<F>>, S, true, Omit<O, 'method'> & {
     method: 'POST';
 }>;
+type RemoveEndpoint<F extends FetchFunction = FetchFunction, S extends Schema | undefined = any, O extends {
+    path: string;
+    body: any;
+    searchParams?: any;
+} = {
+    path: string;
+    body: any;
+}> = RestInstanceBase<RestFetch<'searchParams' extends keyof O ? O['searchParams'] extends undefined ? PathArgs<Exclude<O['path'], undefined>> : O['searchParams'] & PathArgs<Exclude<O['path'], undefined>> : PathArgs<Exclude<O['path'], undefined>>, O['body'], ResolveType<F>>, S, true, Omit<O, 'method'> & {
+    method: 'PATCH';
+}>;
 type OptionsToAdderBodyArgument<O extends {
     body?: any;
 }> = 'body' extends keyof O ? O['body'] : any;
@@ -1798,4 +1837,4 @@ declare class NetworkError extends Error {
     constructor(response: Response);
 }
 
-export { type AbstractInstanceType, type AddEndpoint, Array$1 as Array, type CheckLoop, Collection, type CustomResource, type DefaultArgs, type Defaults, type Denormalize, type DenormalizeNullable, type DenormalizeNullableObject, type DenormalizeObject, Endpoint, type EndpointExtendOptions, type EndpointExtraOptions, type EndpointInstance, type EndpointInstanceInterface, type EndpointInterface, type EndpointOptions, type EndpointParam, type EndpointToFunction, type EntitiesInterface, type EntitiesPath, Entity, type EntityFields, type EntityInterface, type EntityMap, EntityMixin, type EntityPath, type EntityTable, type ErrorTypes, type ExpiryStatusInterface, ExtendableEndpoint, type ExtendedResource, type FetchFunction, type FetchGet, type FetchMutate, type FromFallBack, type GetEndpoint, type GetEntity, type GetIndex, type HookResource, type HookableEndpointInterface, type IEntityClass, type IEntityInstance, type INormalizeDelegate, type IQueryDelegate, type RestEndpoint$1 as IRestEndpoint, type IndexPath, Invalidate, type KeyofEndpointInstance, type KeyofRestEndpoint, type KeysToArgs, type Mergeable, type MethodToSide, type MutateEndpoint, type NI, NetworkError, type Normalize, type NormalizeNullable, type NormalizeObject, type NormalizedEntity, type NormalizedIndex, type NormalizedNullableObject, type ObjectArgs, type OptionsToFunction, type PaginationEndpoint, type PaginationFieldEndpoint, type ParamFetchNoBody, type ParamFetchWithBody, type ParamToArgs, type PartialRestGenerics, type PathArgs, type PathArgsAndSearch, type PathKeys, type PolymorphicInterface, type Queryable, type ReadEndpoint, type RecordClass, type ResolveType, type Resource, type ResourceEndpointExtensions, type ResourceExtension, type ResourceGenerics, type ResourceInterface, type ResourceOptions, RestEndpoint, type RestEndpointConstructor, type RestEndpointConstructorOptions, type RestEndpointExtendOptions, type RestEndpointOptions, type RestExtendedEndpoint, type RestFetch, type RestGenerics, type RestInstance, type RestInstanceBase, type RestType, type RestTypeNoBody, type RestTypeWithBody, type Schema, type SchemaArgs, type SchemaClass, type SchemaSimple, type Serializable, type ShortenPath, type SnapshotInterface, type UnknownError, type Visit, resource as createResource, getUrlBase, getUrlTokens, hookifyResource, resource, schema_d as schema, validateRequired };
+export { type AbstractInstanceType, type AddEndpoint, Array$1 as Array, type CheckLoop, Collection, type CustomResource, type DefaultArgs, type Defaults, type Denormalize, type DenormalizeNullable, type DenormalizeNullableObject, type DenormalizeObject, Endpoint, type EndpointExtendOptions, type EndpointExtraOptions, type EndpointInstance, type EndpointInstanceInterface, type EndpointInterface, type EndpointOptions, type EndpointParam, type EndpointToFunction, type EntitiesInterface, type EntitiesPath, Entity, type EntityFields, type EntityInterface, type EntityMap, EntityMixin, type EntityPath, type EntityTable, type ErrorTypes, type ExpiryStatusInterface, ExtendableEndpoint, type ExtendedResource, type FetchFunction, type FetchGet, type FetchMutate, type FromFallBack, type GetEndpoint, type GetEntity, type GetIndex, type HookResource, type HookableEndpointInterface, type IEntityClass, type IEntityInstance, type INormalizeDelegate, type IQueryDelegate, type RestEndpoint$1 as IRestEndpoint, type IndexPath, Invalidate, type KeyofEndpointInstance, type KeyofRestEndpoint, type KeysToArgs, type Mergeable, type MethodToSide, type MutateEndpoint, type NI, NetworkError, type Normalize, type NormalizeNullable, type NormalizeObject, type NormalizedEntity, type NormalizedIndex, type NormalizedNullableObject, type ObjectArgs, type OptionsToFunction, type PaginationEndpoint, type PaginationFieldEndpoint, type ParamFetchNoBody, type ParamFetchWithBody, type ParamToArgs, type PartialRestGenerics, type PathArgs, type PathArgsAndSearch, type PathKeys, type PolymorphicInterface, type Queryable, type ReadEndpoint, type RecordClass, type RemoveEndpoint, type ResolveType, type Resource, type ResourceEndpointExtensions, type ResourceExtension, type ResourceGenerics, type ResourceInterface, type ResourceOptions, RestEndpoint, type RestEndpointConstructor, type RestEndpointConstructorOptions, type RestEndpointExtendOptions, type RestEndpointOptions, type RestExtendedEndpoint, type RestFetch, type RestGenerics, type RestInstance, type RestInstanceBase, type RestType, type RestTypeNoBody, type RestTypeWithBody, type Schema, type SchemaArgs, type SchemaClass, type SchemaSimple, type Serializable, type ShortenPath, type SnapshotInterface, type UnknownError, type Visit, resource as createResource, getUrlBase, getUrlTokens, hookifyResource, resource, schema_d as schema, validateRequired };
diff --git a/website/src/components/Playground/editor-types/globals.d.ts b/website/src/components/Playground/editor-types/globals.d.ts
diff --git a/website/src/components/Playground/editor-types/react.d.ts b/website/src/components/Playground/editor-types/react.d.ts
