@lukemorales/query-key-factory

The library provides two ways to access the underlying key arrays for cache management (like invalidation):

• queryKey: Returns the full, specific array for a particular query instance (including all dynamic parameters).
• _def: Returns the base definition array for a query type, useful for invalidating all queries of that type (e.g., invalidating all 'list' queries regardless of filters).

You can declare queries that are dependent on a parent context using the contextQueries property. These sub-queries are accessible via the _ctx property on the parent query object. The library automatically handles the key nesting (e.g., appending the sub-query key to the parent key).

export const users = createQueryKeys('users', {
  detail: (userId: string) => ({
    queryKey: [userId],
    queryFn: () => api.getUser(userId),
    contextQueries: {
      likes: {
        queryKey: null,
        queryFn: () => api.getUserLikes(userId),
      },
    },
  }),
});

// Accessing the contextual query:
// users.detail(userId)._ctx.likes

Install the package using your preferred package manager to start managing typesafe query keys for @tanstack/query.

npm install @lukemorales/query-key-factory

For larger applications, use createQueryKeys to define keys for specific features in separate files. You can then combine them into a single access point using mergeQueryKeys.

import { createQueryKeys, mergeQueryKeys } from "@lukemorales/query-key-factory";

// queries/users.ts
export const users = createQueryKeys('users', {
  all: null,
  detail: (userId: string) => ({
    queryKey: [userId],
    queryFn: () => api.getUser(userId),
  }),
});

// queries/todos.ts
export const todos = createQueryKeys('todos', {
  detail: (todoId: string) => [todoId],
  list: (filters: TodoFilters) => ({
    queryKey: [{ filters }],
    queryFn: (ctx) => api.getTodos({ filters, page: ctx.pageParam }),
  }),
});

// queries/index.ts
export const queries = mergeQueryKeys(users, todos);

The schema allows you to define how query keys are composed and how queryFns are attached.

• queryKey: Defines the base key for the property.
• queryFn: Defines the fetcher function. When provided, the factory generates objects compatible with TanStack Query's useQuery (containing both queryKey and queryFn).
• contextQueries: Enables a hierarchical structure where sub-queries are accessible via a _ctx property on the parent object.

When building a MutationFactorySchema, the type of value assigned to a key determines the output shape:

Static Properties

If a property is a KeyTuple or a MutationKeyRecord, the factory generates a static object containing the composed mutationKey.

Functional (Dynamic) Properties

If a property is a MutationDynamicKey (a function), the factory generates a function. When you call this function with arguments, it returns the mutation options or keys based on the function's return value.

Contextual Mutations

If a property includes contextMutations, the resulting output will include a _ctx object. This object provides access to nested mutation factories that are scoped to the current key context.

A QueryFactorySchema is the core configuration object used to define your query keys and their associated logic. It is a Record<string, FactoryProperty | DynamicKey> where each key represents a named query or a group of queries.

Properties in the schema can be:

• Static keys: A KeyTuple (e.g., ['users']) that defines a fixed part of the query key.
• Query functions: A $QueryFactorySchema which includes a queryFn to automatically generate queryOptions (containing both queryKey and queryFn).
• Contextual queries: A KeySchemaWithContextualQueries which provides a contextQueries object, allowing you to nest related queries under a _ctx property.
• Dynamic keys: A function (DynamicKey) that accepts arguments and returns a new schema or key tuple, allowing for parameterized queries (e.g., user(id => ({ queryKey: ['user', id] }))).

Use inferQueryKeyStore (for stores created with createQueryKeyStore) or inferQueryKeys (for features created with createQueryKeys) to extract types from your definitions. This enables full autocomplete and type safety when using the keys in your application.

// For a merged store
import { mergeQueryKeys, inferQueryKeyStore } from "@lukemorales/query-key-factory";
import { users } from './users';
import { todos } from './todos';

export const queries = mergeQueryKeys(users, todos);
export type QueryKeys = inferQueryKeyStore<typeof queries>;

// For a single feature
import { createQueryKeys, inferQueryKeys } from "@lukemorales/query-key-factory";
export const todos = createQueryKeys('todos', { /* ... */ });
export type TodosKeys = inferQueryKeys<typeof todos>;

To get accurate types for the ctx argument inside your queryFn, you can extract the type of the queryKey from your inferred keys and pass it to QueryFunctionContext.

import type { QueryFunctionContext } from '@tanstack/react-query';
import type { QueryKeys } from "../queries";

type TodosList = QueryKeys['todos']['list'];

const fetchTodos = async (ctx: QueryFunctionContext<TodosList['queryKey']>) => {
  // ctx.queryKey is now typed based on the definition
  const [, , { filters }] = ctx.queryKey;
  return api.getTodos({ filters, page: ctx.pageParam });
};