@ciscode/query-kit

Typed abstractions over TanStack Query v5. Define queries and mutations once — get typed keys, typed fetchers, and typed cache helpers everywhere.

Installation

npm install @ciscode/query-kit

Peer dependencies

npm install @tanstack/react-query@^5 react@^18 react-dom@^18

Requires @tanstack/react-query >= 5, react >= 18, react-dom >= 18.

Quick start

Wrap your app in QueryClientProvider from @tanstack/react-query as usual, then use @ciscode/query-kit to define and consume queries.

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';

const client = new QueryClient();

export function App() {
  return (
    <QueryClientProvider client={client}>
      <YourApp />
    </QueryClientProvider>
  );
}

createQuery

Define a query once and get a fully typed definition that carries its key builder, fetcher, and a useQuery shorthand together.

// queries/userQuery.ts
import { createQuery } from '@ciscode/query-kit';

interface User {
  id: number;
  name: string;
  email: string;
}

export const userQuery = createQuery(
  (params: { id: number }) => ['users', params.id] as const,
  async (params) => {
    const res = await fetch(`/api/users/${params.id}`);
    if (!res.ok) throw new Error('Failed to fetch user');
    return res.json() as Promise<User>;
  },
);

Using the query in a component

// components/UserProfile.tsx
import { userQuery } from '../queries/userQuery';

export function UserProfile({ userId }: { userId: number }) {
  const { data, isLoading, isError, error } = userQuery.useQuery({ id: userId });

  if (isLoading) return <p>Loading…</p>;
  if (isError) return <p>Error: {error.message}</p>;

  return (
    <div>
      <h1>{data.name}</h1>
      <p>{data.email}</p>
    </div>
  );
}

Using the key and fetcher directly

// Access the key builder (e.g. for manual cache operations)
const key = userQuery.queryKey({ id: 42 }); // ['users', 42]

// Call the fetcher directly (e.g. in a server-side loader)
const user = await userQuery.queryFn({ id: 42 });

usePaginatedQuery

Wraps either useQuery (offset mode) or useInfiniteQuery (cursor mode) behind a unified API. Both modes return a flat data array.

Offset-based pagination

import { usePaginatedQuery } from '@ciscode/query-kit';
import { postsQuery } from '../queries/postsQuery';

// postsQuery is a createQuery definition whose fetcher accepts { page, pageSize }
export function PostsList() {
  const { data, isLoading, page, pageSize, nextPage, prevPage } = usePaginatedQuery(
    postsQuery,
    { page: 1, pageSize: 10 },
    { mode: 'offset', pageSize: 10, initialPage: 1 },
  );

  if (isLoading) return <p>Loading…</p>;

  return (
    <div>
      {data.map((post) => (
        <article key={post.id}>{post.title}</article>
      ))}
      <button onClick={prevPage} disabled={page === 1}>
        Previous
      </button>
      <span>Page {page}</span>
      <button onClick={nextPage}>Next</button>
    </div>
  );
}

Offset result shape

Property	Type	Description
`data`	`T[]`	Flat array of current page items
`page`	`number`	Current page (starts at 1)
`pageSize`	`number`	Items per page (default `20`)
`totalPages`	`number \| undefined`	Total pages if known
`nextPage`	`() => void`	Increment page
`prevPage`	`() => void`	Decrement page (floor at 1)
`isLoading`	`boolean`
`isFetching`	`boolean`
`isError`	`boolean`
`error`	`Error \| null`

Cursor-based pagination

import { usePaginatedQuery } from '@ciscode/query-kit';
import { feedQuery } from '../queries/feedQuery';

// feedQuery fetcher accepts { cursor?: string | number | null | undefined }
export function Feed() {
  const { data, isLoading, fetchNextPage, hasNextPage, isFetching } = usePaginatedQuery(
    feedQuery,
    { cursor: undefined },
    {
      mode: 'cursor',
      getCursor: (page) => (page.length > 0 ? page[page.length - 1].id : undefined),
    },
  );

  if (isLoading) return <p>Loading…</p>;

  return (
    <div>
      {data.map((item) => (
        <article key={item.id}>{item.title}</article>
      ))}
      {hasNextPage && (
        <button onClick={fetchNextPage} disabled={isFetching}>
          {isFetching ? 'Loading…' : 'Load more'}
        </button>
      )}
    </div>
  );
}

Cursor result shape

Property	Type	Description
`data`	`T[]`	Flat array of all loaded items
`fetchNextPage`	`() => void`	Fetch the next page
`hasNextPage`	`boolean`	`true` when `getCursor` returns a value
`nextCursor`	`string \| number \| null \| undefined`	Cursor for the next page
`isLoading`	`boolean`
`isFetching`	`boolean`
`isError`	`boolean`
`error`	`Error \| null`

createMutation

Define a mutation once and use it anywhere with full type safety.

// mutations/updateUser.ts
import { createMutation } from '@ciscode/query-kit';

interface UpdateUserInput {
  id: number;
  name: string;
}

interface User {
  id: number;
  name: string;
  email: string;
}

export const updateUserMutation = createMutation(async (input: UpdateUserInput): Promise<User> => {
  const res = await fetch(`/api/users/${input.id}`, {
    method: 'PATCH',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ name: input.name }),
  });
  if (!res.ok) throw new Error('Failed to update user');
  return res.json();
});

Using the mutation in a component

// components/EditUserForm.tsx
import { useQueryClient } from '@tanstack/react-query';
import { updateUserMutation } from '../mutations/updateUser';
import { userQuery } from '../queries/userQuery';
import { invalidateQueries } from '@ciscode/query-kit';

export function EditUserForm({ userId }: { userId: number }) {
  const queryClient = useQueryClient();
  const { mutate, isPending, isError, error } = updateUserMutation.useMutation();

  function handleSubmit(name: string) {
    mutate(
      { id: userId, name },
      {
        onSuccess: () => {
          // Invalidate the user query so it re-fetches fresh data.
          // No raw string keys — the key comes from userQuery.
          invalidateQueries(queryClient, userQuery, { id: userId });
        },
      },
    );
  }

  return (
    <form
      onSubmit={(e) => {
        e.preventDefault();
        const name = new FormData(e.currentTarget).get('name') as string;
        handleSubmit(name);
      }}
    >
      <input name="name" required />
      <button type="submit" disabled={isPending}>
        {isPending ? 'Saving…' : 'Save'}
      </button>
      {isError && <p role="alert">Error: {error.message}</p>}
    </form>
  );
}

Cache helpers

invalidateQueries

Marks all matching queries as stale so they re-fetch. Uses the query definition's key builder — no raw strings.

import { invalidateQueries } from '@ciscode/query-kit';

// Invalidate a specific user
await invalidateQueries(queryClient, userQuery, { id: 42 });

// Invalidate all queries matching the userQuery key prefix
await invalidateQueries(queryClient, userQuery);

setQueryData

Write directly into the cache without a network request. Passing the wrong TData shape is a TypeScript compile error.

import { setQueryData } from '@ciscode/query-kit';

// Direct replacement
setQueryData(
  queryClient,
  userQuery,
  { id: 42 },
  { id: 42, name: 'Alice', email: 'alice@example.com' },
);

// Updater function — receives the old value
setQueryData(queryClient, userQuery, { id: 42 }, (prev) => ({
  ...prev!,
  name: 'Alice Updated',
}));

Full end-to-end pattern

define once (createQuery / createMutation)
     ↓
use in component (queryDef.useQuery / mutationDef.useMutation)
     ↓
on success → invalidateQueries / setQueryData (no raw strings)

API reference

Export	Kind	Description
`createQuery`	`function`	Creates a `QueryDefinition` (key + fetcher + hook)
`usePaginatedQuery`	`function`	Offset or cursor pagination hook
`createMutation`	`function`	Creates a `MutationDefinition` (fn + hook)
`invalidateQueries`	`function`	Type-safe query invalidation via `QueryDefinition`
`setQueryData`	`function`	Type-safe cache write via `QueryDefinition`
`QueryDefinition`	`type`	Shape returned by `createQuery`
`MutationDefinition`	`type`	Shape returned by `createMutation`
`OffsetPaginationOptions`	`type`	Options for `usePaginatedQuery` offset mode
`CursorPaginationOptions`	`type`	Options for `usePaginatedQuery` cursor mode

Scripts

npm run build       # build to dist/ (tsup — ESM + CJS + types)
npm test            # run tests (vitest)
npm run typecheck   # TypeScript typecheck
npm run lint        # ESLint
npm run format      # Prettier check
npx changeset       # create a changeset

Release flow

Work on a feat/* branch from develop
Merge to develop via PR
Add a changeset: npx changeset
Promote develop → master via PR
Tag vX.Y.Z to publish (npm OIDC)

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

@ciscode/query-kit

Installation

Peer dependencies

Quick start

createQuery

Using the query in a component

Using the key and fetcher directly

usePaginatedQuery

Offset-based pagination

Cursor-based pagination

createMutation

Using the mutation in a component

Cache helpers

invalidateQueries

setQueryData

Full end-to-end pattern

API reference

Scripts

Release flow

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

@ciscode/query-kit

Installation

Peer dependencies

Quick start

createQuery

Using the query in a component

Using the key and fetcher directly

usePaginatedQuery

Offset-based pagination

Cursor-based pagination

createMutation

Using the mutation in a component

Cache helpers

invalidateQueries

setQueryData

Full end-to-end pattern

API reference

Scripts

Release flow