query-key-chain

A simple and functional query key management solution for React Query, using a cascading array structure.

Table of Contents

• query-key-chain
  • Table of Contents
  • Installation
  • Note
  • Usage
  • Example
    • Basic Usage
    • With @tanstack/react-query
  • License

Installation

npm install query-key-chain

yarn add query-key-chain

pnpm add query-key-chain

Note

1. TypeScript is strongly recommended for better type safety and enhanced development experience.
2. This package uses the Proxy API, Ensure your target ECMAScript version (ES6 and above) supports Proxies.

Usage

Easily generate unique query keys when using @tanstack/react-query.

chain function dynamically generates hierarchical arrays: all > list > item > action > params. Each level can be combined or omitted. You can get grouped keys all at once using methods such as lists, items, actions.

Example

Basic Usage

import { createQueryKey } from "query-key-chain";

export const c = createQueryKeyFactory(
  ["user", "post", "comment"],
  // optional
  {
    // 'error' | 'console' | 'silent'
    severity: "error",
  }
);

const usersKey = c("user").lists().params({ foo: "true" });
const invalidKey = c("invalid_key"); // error

// without validation.
import { chain } from "query-key-chain";

const usersKey = chain("user").lists().params({ foo: "true" });

With @tanstack/react-query

// example/dashboard.queries.ts
import { queryOptions, useQueryClient } from "@tanstack/react-query";
import { chain } from "query-key-chain";

// key declarations & invalidations.
export const getAllBoards = (params: ListParams) =>
  queryOptions({
    queryKey: chain("board").lists().params(params),
    queryFn: () => fetchBoards(params),
  });

export const getBoard = (boardId: string, params: ListParams) =>
  queryOptions({
    queryKey: chain("board").list(boardId).params(params),
    queryFn: () => fetchBoard(boardId, params),
  });

export const getBoardArticle = (
  boardId: string,
  articleId: string,
  params: ArticleParams
) =>
  queryOptions({
    queryKey: chain("board").list(boardId).item(articleId).params(params),
    queryFn: () => fetchBoardArticle(boardId, articleId, params),
  });

useMutation({
  mutationFn: (params: EditParams) => deleteBoardArticle(params),
  onSuccess: () => {
    // this will invalidate board & related articles.
    queryClient.invalidateQueries({
      queryKey: chain("board").list(boardId),
    });

    // or you can just invalidate all..
    queryClient.invalidateQueries({ queryKey: chain("board").all() });
  },
});

License

This project is licensed under the MIT License.