Callsheet

Reference for the public Callsheet APIs.

Defining Calls

These APIs come from @callsheet/react-query and are used to build the shared call tree.

`defineCalls`

Creates the shared call tree. Takes a nested object of calls and returns the same shape along with call metadata attached.

import { defineCalls, query, mutation } from '@callsheet/react-query';

export const calls = defineCalls({
  films: {
    featured: query(FeaturedFilmsDocument),
    byId: query(FilmByIdDocument, {
      family: ['films', 'detail'],
      key: ({ input }) => [input.id],
      staleTime: 30_000,
    }),
    update: mutation(UpdateFilmDocument, {
      invalidates: [
        ['films', 'list'],
        ['films', 'detail'],
      ],
    }),
  },
});

`query`

Defines a query call. Can take a typed source (GraphQL document, ts-rest route) or be called with just options for manual calls.

// From a typed source
query(FilmByIdDocument);
query(FilmByIdDocument, { family: ['films', 'detail'] });

// Manual (no source)
query<MyInput, MyOutput>({ staleTime: 30_000 });

`mutation`

Defines a mutation call. Same signature pattern as query.

// From a typed source
mutation(UpdateFilmDocument);
mutation(UpdateFilmDocument, { invalidates: [['films', 'list']] });

// Manual (no source)
mutation<MyInput, MyOutput>();

`call`

Defines a call and infers whether it is a query or mutation from the source. Useful when the source already carries kind information.

call(FilmByIdDocument); // inferred as query
call(contract.films.update); // inferred as mutation

Using Calls in React Query

These APIs come from @callsheet/react-query and are used wherever you interact with React Query.

`queryOptions`

Builds a query config from a call definition. The result is passed to useQuery.

import { queryOptions } from '@callsheet/react-query';

const options = queryOptions(calls.films.byId, {
  input: { id: 'wall-e' },
  select: (data) => data.film,
});

The input field is required when the call expects input, else optional when it doesn't. All standard React Query options (enabled, staleTime, select, initialData, etc.) can be passed as well.

`useQuery`

Callsheet's useQuery hook. Thin wrapper around React Query. Takes a query config from queryOptions and returns the standard React Query result. Requires CallsheetProvider in the component tree.

import { queryOptions, useQuery } from '@callsheet/react-query';

const film = useQuery(queryOptions(calls.films.byId, { input: { id } }));

`useMutation`

Callsheet's useMutation hook. Takes a mutation call and optional React Query mutation options. Handles invalidates automatically on success for related queries. Requires CallsheetProvider in the component tree.

import { useMutation } from '@callsheet/react-query';

const updateFilm = useMutation(calls.films.update, {
  onSuccess: () => {
    /* component-level callback */
  },
});

`createReactQueryAdapter`

Creates the adapter that connects Callsheet to React Query. You provide an execute function that knows how to run a call (e.g., make a GraphQL request or REST call).

import { createReactQueryAdapter } from '@callsheet/react-query';

const adapter = createReactQueryAdapter({
  execute: async ({ call, input }) => {
    // Your request logic here
  },
});

The adapter is passed to CallsheetProvider.

`CallsheetProvider`

React context provider that makes the adapter available to useQuery and useMutation.

import { CallsheetProvider } from '@callsheet/react-query';

<CallsheetProvider adapter={adapter}>
  <App />
</CallsheetProvider>;

Code Generation

`defineConfig`

From @callsheet/codegen. Defines the build-time config for generating a calls module.

import { defineConfig } from '@callsheet/codegen';

export default defineConfig({
  sources: {
    /* ... */
  },
  output: { file: './src/generated/calls.ts' },
});

For the full config shape, see Codegen Config.

ts-rest Wrappers

These APIs come from @callsheet/ts-rest and are used when manually wrapping ts-rest contract routes without code generation.

`query` / `mutation` / `call`

Wrap a ts-rest contract route as a Callsheet call when you want to use the dedicated manual ts-rest wrapper package.

The main query, mutation, and call exports in @callsheet/react-query also support ts-rest routes directly.

import { query, mutation, call } from '@callsheet/ts-rest';

query(contract.films.byId);
mutation(contract.films.update, { invalidates: [['films', 'list']] });
call(contract.films.byId);

For more on when to use these, see Using Callsheet with ts-rest.

Calls for how the call model works
Using Callsheet with React Query for shared defaults and overrides
Packages and Imports for package roles
Codegen Config for the full config reference
Using Callsheet with ts-rest for the ts-rest workflow

API Reference