mirror of https://github.com/buster-so/buster.git
80 lines
3.1 KiB
Plaintext
80 lines
3.1 KiB
Plaintext
---
|
|
description: Creating tan stack query options to be consuming in providers and api calls
|
|
globs: src/api/query_keys/**/*
|
|
alwaysApply: false
|
|
---
|
|
# Query Keys Folder Rules
|
|
|
|
## Overview
|
|
The `query-keys` folder is a structured directory that contains files, each serving as a **namespace** for a specific API. These files define TanStack React Query options, ensuring a consistent and maintainable approach to managing query keys.
|
|
|
|
## Structure
|
|
Each file in this folder represents a distinct **namespace** corresponding to an API domain. Within these files, query options must be defined using the `queryOptions` utility from `@tanstack/react-query`.
|
|
|
|
### Example
|
|
Below is an example of how query options should be structured within a file:
|
|
|
|
```ts
|
|
import { queryOptions } from '@tanstack/react-query';
|
|
import type { BusterChat, BusterChatListItem } from '@/api/asset_interfaces';
|
|
import type { GetChatListParams } from '@/api/request_interfaces/chats';
|
|
import { type getListLogs } from '@/api/buster_rest/chats';
|
|
|
|
const chatsGetChat = (chatId: string) =>
|
|
queryOptions<BusterChat>({
|
|
queryKey: ['chats', 'get', chatId] as const,
|
|
staleTime: 10 * 1000
|
|
});
|
|
|
|
const chatsGetList = (filters?: Parameters<typeof getListLogs>[0]>) =>
|
|
queryOptions<BusterChatListItem[]>({
|
|
queryKey: ['chats', 'list', filters] as const,
|
|
staleTime: 10 * 1000
|
|
});
|
|
|
|
export const chatQueryKeys = {
|
|
chatsGetChat,
|
|
chatsGetList
|
|
};
|
|
```
|
|
|
|
## Naming Conventions
|
|
- Each file should follow a **singular, lowercase** naming convention that represents the API namespace (e.g., `chats.ts`, `users.ts`).
|
|
- Query keys should use a structured array format: `[namespace, action, identifier]`.
|
|
- Exported objects should map endpoint-like keys to their respective query functions.
|
|
|
|
## Query Option Requirements
|
|
- Every query must be wrapped in `queryOptions<T>()` to ensure type safety.
|
|
- `queryKey` must be a **constant tuple** to prevent unnecessary re-renders.
|
|
- `staleTime` should be explicitly set based on the expected data refresh frequency.
|
|
- All query options must be **exported in a structured object**, similar to `chatQueryKeys`, to maintain consistency and ease of access across the application.
|
|
|
|
## Common Query Keys File
|
|
There is also a `common.ts` file that consolidates **all** namespaced query keys into a single exported object. All new query namespaces must be added to this file to ensure uniform access across the application.
|
|
|
|
### Example Structure of `common.ts`
|
|
```ts
|
|
import { chatQueryKeys } from './chat';
|
|
import { collectionQueryKeys } from './collection';
|
|
import { userQueryKeys } from './users';
|
|
import { dashboardQueryKeys } from './dashboard';
|
|
import { metricsQueryKeys } from './metric';
|
|
import { searchQueryKeys } from './search';
|
|
import { termsQueryKeys } from './terms';
|
|
import { datasourceQueryKeys } from './datasources';
|
|
|
|
export const queryKeys = {
|
|
...chatQueryKeys,
|
|
...collectionQueryKeys,
|
|
...userQueryKeys,
|
|
...dashboardQueryKeys,
|
|
...metricsQueryKeys,
|
|
...searchQueryKeys,
|
|
...termsQueryKeys,
|
|
...datasourceQueryKeys
|
|
};
|
|
```
|
|
|
|
By following these guidelines, we ensure consistency, readability, and optimal caching behavior in our TanStack React Query implementation.
|
|
|