@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: '[email protected]' },
);

// 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)