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.

Changelog

All notable changes to this project will be documented in this file.

[1.0.0] - 2025-01-04

• Changed

  • createQueryKeyFactory now checks runtime type of keys.
  • detail is changed to item.
  • lists, items, actions has params method.

[0.7.0] - 2024-09-20

• Changed
  • lists(), details(), actions() now returns an array that is not chainable.
  • key inputs other than primitive values are now allowed.
  • a type annotation of chains only represents its base key.

[0.6.2] - 2024-08-21

• Changed

added items at each step is now an object instead of string.

[0.5.2] - 2024-08-05

• Changed

Refactored the code. .all() returns #all instead of all.

[0.5.1] - 2024-07-14

• Changed

Changed the type of Arrays to ReadonlyArray from Readonly<Array<T>>

[0.4.5] - 2024-07-08

• Changed

Changed appended values from list, detail, action to #list, #detail, #action to avoid clashing with key inputs.

• Fixed

Fixed a bug in the typing for createQueryKeyFactory.

[0.4.2] - 2024-07-08

• Added

createQueryKeyFactory which is useful when you want to create a query key that enforce a certain keys.

• Changed

createQueryFactory has been renamed to createQueryKey queryChain has been renamed to keyChain

Type names ends with QueryArray has been changed to name with ending Key or Keys

Updated README.md.