From bf48f023617de2d36ffa695ded1b7065fc7cf830 Mon Sep 17 00:00:00 2001
From: Nate Kelley <nate@buster.so>
Date: Thu, 13 Feb 2025 23:11:32 -0700
Subject: [PATCH] create query key rules

---
 web/.cursor/rules/api_buster_query_keys.mdc | 77 +++++++++++++++++++++
 web/src/api/query_keys/chat.ts              |  2 +-
 2 files changed, 78 insertions(+), 1 deletion(-)
 create mode 100644 web/.cursor/rules/api_buster_query_keys.mdc

diff --git a/web/.cursor/rules/api_buster_query_keys.mdc b/web/.cursor/rules/api_buster_query_keys.mdc
new file mode 100644
index 000000000..9acbe66d2
--- /dev/null
+++ b/web/.cursor/rules/api_buster_query_keys.mdc
@@ -0,0 +1,77 @@
+---
+description: Creating tan stack query options to be consuming in providers and api calls
+globs: src/api/query_keys/**/*
+---
+# 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';
+
+const chatsGetChat = (chatId: string) =>
+  queryOptions<BusterChat>({
+    queryKey: ['chats', 'get', chatId] as const,
+    staleTime: 10 * 1000
+  });
+
+const chatsGetList = (filters?: GetChatListParams) =>
+  queryOptions<BusterChatListItem[]>({
+    queryKey: ['chats', 'list', filters] as const,
+    staleTime: 10 * 1000
+  });
+
+export const chatQueryKeys = {
+  '/chats/get:getChat': chatsGetChat,
+  '/chats/list:getChatsList': 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.
+
diff --git a/web/src/api/query_keys/chat.ts b/web/src/api/query_keys/chat.ts
index 8dd42f6c6..3818e3b4d 100644
--- a/web/src/api/query_keys/chat.ts
+++ b/web/src/api/query_keys/chat.ts
@@ -1,4 +1,4 @@
-import { queryOptions, useQuery, useQueryClient } from '@tanstack/react-query';
+import { queryOptions } from '@tanstack/react-query';
 import type { BusterChat, BusterChatListItem } from '@/api/asset_interfaces';
 import type { GetChatListParams } from '@/api/request_interfaces/chats';