feat(query): add overloaded for optional define options params (#386)

Co-authored-by: Eduardo San Martin Morote <[email protected]>

Author: brolnickij

src/define-query-options.test-d.ts

@@ -256,5 +256,62 @@ describe('typed query keys', () => {
       // allows non typed too with loose types
       queryCache.setQueryData(DOCUMENTS_KEYS.byId('1'), { toto: true })
     })
+
+    it('supports optional params as extra query modifiers', () => {
+      const documentsListQuery = defineQueryOptions(
+        ({ page = 1, withComments = false }: { page?: number; withComments?: boolean } = {}) => ({
+          key: ['documents', page, { comments: withComments }],
+          query: async () => ({
+            page,
+            withComments,
+            list: [] as { id: string; title: string; hasComments: boolean }[],
+          }),
+        }),
+      )
+
+      const r0 = useQuery(documentsListQuery())
+      expectTypeOf(r0.data.value).toEqualTypeOf<
+        | {
+            page: number
+            withComments: boolean
+            list: { id: string; title: string; hasComments: boolean }[]
+          }
+        | undefined
+      >()
+
+      // can also be not called
+      const r1 = useQuery(documentsListQuery)
+      expectTypeOf(r1).toEqualTypeOf(r0)
+
+      const r2 = useQuery(documentsListQuery, () => ({ page: 2, withComments: true }))
+      expectTypeOf(r2.data.value).toEqualTypeOf<
+        | {
+            page: number
+            withComments: boolean
+            list: { id: string; title: string; hasComments: boolean }[]
+          }
+        | undefined
+      >()
+
+      const queryCache = useQueryCache()
+      expectTypeOf(
+        queryCache.getQueryData(documentsListQuery({ page: 3, withComments: true }).key),
+      ).toEqualTypeOf<
+        | {
+            page: number
+            withComments: boolean
+            list: { id: string; title: string; hasComments: boolean }[]
+          }
+        | undefined
+      >()
+      expectTypeOf(queryCache.getQueryData(documentsListQuery().key)).toEqualTypeOf<
+        | {
+            page: number
+            withComments: boolean
+            list: { id: string; title: string; hasComments: boolean }[]
+          }
+        | undefined
+      >()
+    })
   })
 })

src/define-query-options.ts

@@ -15,6 +15,23 @@ export interface DefineQueryOptionsTagged<
   key: EntryKeyTagged<TData, TError, TDataInitial>
 }
 
+/**
+ * Define dynamic query options by passing a function that accepts an optional
+ * arbitrary parameter and returns the query options. Enables type-safe query
+ * keys. Must be passed to {@link useQuery} with or without a getter to
+ * retrieve the params.
+ *
+ * @param setupOptions - A function that returns the query options.
+ */
+export function defineQueryOptions<
+  Params,
+  TData,
+  TError = ErrorDefault,
+  TDataInitial extends TData | undefined = undefined,
+>(
+  setupOptions: (params?: Params) => DefineQueryOptions<TData, TError, TDataInitial>,
+): (params?: Params) => DefineQueryOptionsTagged<TData, TError, TDataInitial>
+
 /**
  * Define dynamic query options by passing a function that accepts an arbitrary
  * parameter and returns the query options. Enables type-safe query keys.