Add some more clarity to the RQ docs (#10120)

src/state/queries/util.ts

@@ -14,6 +14,61 @@ import {
 
 import * as bsky from '#/types/bsky'
 
+export type StructuredQueryKey<T extends Record<string, unknown>> = readonly [
+  string,
+  T,
+  {
+    persistedVersion?: number
+  },
+]
+
+/**
+ * Helper method to ensure consistent query keys and key ordering
+ */
+export function createQueryKey<T extends Record<string, unknown>>(
+  /**
+   * The query key root. All queries must have a root.
+   */
+  root: string,
+  /**
+   * Any arguments the query depends on, and if changed, should result in the query being refetched.
+   */
+  args: T,
+  options: {
+    /**
+     * If provided, this indicates that the query is persisted and the version
+     * of the persisted query format.
+     *
+     * This is used to ensure that when we make breaking changes to the
+     * persisted query format, we can increment the version and avoid trying to
+     * read old persisted queries with the new format.
+     *
+     * If you're persisting your queries, you probably want to set `gcTime:
+     * GCTIME.INFINITY` for this query, otherwise it'll get busted immediately
+     * after being persisted.
+     */
+    persistedVersion?: number
+  } = {},
+): StructuredQueryKey<T> {
+  return [root, args, options] as const
+}
+
+export function isQueryPersisted(
+  queryKey: QueryKey,
+): queryKey is StructuredQueryKey<Record<string, unknown>> {
+  return (
+    Array.isArray(queryKey) &&
+    queryKey.length === 3 &&
+    typeof queryKey[0] === 'string' &&
+    typeof queryKey[1] === 'object' &&
+    queryKey[1] !== null &&
+    typeof queryKey[2] === 'object' &&
+    queryKey[2] !== null &&
+    'persistedVersion' in queryKey[2] &&
+    typeof queryKey[2].persistedVersion === 'number'
+  )
+}
+
 export async function truncateAndInvalidate<T = any>(
   queryClient: QueryClient,
   queryKey: QueryKey,