feat: findDefaults + resolveFindOptions

Akryum · Akryum · commit 2eab3fc65299 · 2025-11-27T16:35:15.000+01:00
diff --git a/docs/guide/data/query.md b/docs/guide/data/query.md
@@ -535,6 +535,21 @@ The cache will automatically resolve the relations as soon as the data is availa
 
 Plugins hooked on the `fetchRelations` hook will also be called to potentially fetch the data of the relations. See [Plugin hooks](../plugin/hooks.md#fetching-relations) for more details.
 
+## Default find options <Badge text="New in v0.8.3" />
+
+You can set default find options for all queries in the store by using the `findDefaults` option when creating the store:
+
+```ts
+const store = createStore({
+  schema,
+  plugins,
+  findDefaults: {
+    fetchPolicy: 'cache-and-fetch',
+    // Other default find options...
+  },
+})
+```
+
 ## Customizing Find Options Types <Badge text="Changed in v0.7" type="warning" />
 
 You can customize the `FindOptions` type used in the `first` and `many` query builder methods and in the `peek*`/`find*` methods by declaring a module augmentation for `@rstore/vue` and extending the `FindOptions` interface.
diff --git a/docs/guide/plugin/hooks.md b/docs/guide/plugin/hooks.md
@@ -972,3 +972,18 @@ hook('afterFetch', (payload) => {
   )
 })
 ```
+
+### resolveFindOptions <Badge text="New in v0.8.3" />
+
+```ts
+hook('resolveFindOptions', (payload) => {
+  console.log(
+    payload.store,
+    payload.meta,
+    payload.collection, // The current collection
+    payload.many, // Boolean indicating if the query is for many items or one item
+    payload.findOptions, // The find options passed to the query, such as filter or params
+    payload.updateFindOptions, // A function to update the find options
+  )
+})
+```
diff --git a/packages/core/src/query/findFirst.ts b/packages/core/src/query/findFirst.ts
@@ -64,16 +64,8 @@ async function _findFirst<
       }
     : keyOrOptions
 
-  if (findOptions.meta) {
-    Object.assign(meta, findOptions.meta)
-  }
-
-  const fetchPolicy = store.$getFetchPolicy(findOptions?.fetchPolicy)
-
-  findOptions = {
-    ...findOptions,
-    fetchPolicy,
-  }
+  findOptions = store.$resolveFindOptions(collection, findOptions, false, meta)
+  const fetchPolicy = findOptions.fetchPolicy
 
   let result: any
   let marker: string | undefined
diff --git a/packages/core/src/query/findMany.ts b/packages/core/src/query/findMany.ts
@@ -59,16 +59,8 @@ async function _findMany<
   meta ??= {}
   findOptions ??= {}
 
-  if (findOptions.meta) {
-    Object.assign(meta, findOptions.meta)
-  }
-
-  const fetchPolicy = store.$getFetchPolicy(findOptions.fetchPolicy)
-
-  findOptions = {
-    ...findOptions,
-    fetchPolicy,
-  }
+  findOptions = store.$resolveFindOptions(collection, findOptions, true, meta)
+  const fetchPolicy = findOptions.fetchPolicy
 
   let result: any[] | undefined
   let marker: string | undefined
diff --git a/packages/core/src/query/peekFirst.ts b/packages/core/src/query/peekFirst.ts
@@ -30,19 +30,16 @@ export function peekFirst<
 }: PeekFirstOptions<TCollection, TCollectionDefaults, TSchema>): QueryResult<WrappedItem<TCollection, TCollectionDefaults, TSchema> | null> {
   meta ??= {}
 
-  const findOptions: FindFirstOptions<TCollection, TCollectionDefaults, TSchema> = typeof keyOrOptions === 'string' || typeof keyOrOptions === 'number'
+  let findOptions: FindFirstOptions<TCollection, TCollectionDefaults, TSchema> = typeof keyOrOptions === 'string' || typeof keyOrOptions === 'number'
     ? {
         key: keyOrOptions,
       }
     : keyOrOptions
 
-  const key = findOptions?.key
-
-  if (findOptions.meta) {
-    Object.assign(meta, findOptions.meta)
-  }
+  findOptions = store.$resolveFindOptions(collection, findOptions, false, meta)
+  const fetchPolicy = findOptions.fetchPolicy
 
-  const fetchPolicy = store.$getFetchPolicy(findOptions?.fetchPolicy)
+  const key = findOptions?.key
 
   if (force || shouldReadCacheFromFetchPolicy(fetchPolicy)) {
     let result: any
diff --git a/packages/core/src/query/peekMany.ts b/packages/core/src/query/peekMany.ts
@@ -30,11 +30,9 @@ export function peekMany<
 }: PeekManyOptions<TCollection, TCollectionDefaults, TSchema>): QueryResult<Array<WrappedItem<TCollection, TCollectionDefaults, TSchema>>> {
   meta ??= {}
 
-  if (findOptions?.meta) {
-    Object.assign(meta, findOptions.meta)
-  }
+  findOptions = store.$resolveFindOptions(collection, findOptions ?? {}, true, meta)
+  const fetchPolicy = findOptions.fetchPolicy
 
-  const fetchPolicy = store.$getFetchPolicy(findOptions?.fetchPolicy)
   if (force || shouldReadCacheFromFetchPolicy(fetchPolicy)) {
     let marker: string | undefined = defaultMarker(collection, findOptions)
     let overrideFilter: ((item: ResolvedCollectionItemBase<TCollection, TCollectionDefaults, TSchema>) => boolean) | undefined
diff --git a/packages/core/src/store.ts b/packages/core/src/store.ts
@@ -20,6 +20,8 @@ export interface CreateStoreCoreOptions<
   syncImmediately?: boolean
 }
 
+const resolvedFindOptionsMarker = Symbol('resolvedFindOptions')
+
 export async function createStoreCore<
   TSchema extends StoreSchema = StoreSchema,
   TCollectionDefaults extends CollectionDefaults = CollectionDefaults,
@@ -38,8 +40,33 @@ export async function createStoreCore<
     $plugins: sortPlugins(optionPlugins.map(p => ({ ...p, hooks: {} }))),
     $hooks: options.hooks,
     $findDefaults: options.findDefaults ?? {},
-    $getFetchPolicy(value) {
-      return value ?? store.$findDefaults.fetchPolicy ?? defaultFetchPolicy
+    $resolveFindOptions(collection, options, many, meta) {
+      if ((options as any)[resolvedFindOptionsMarker]) {
+        return options as any
+      }
+      const resolvedOptions: FindOptions<any, any, any> = {
+        ...store.$findDefaults,
+        ...options,
+        fetchPolicy: options.fetchPolicy ?? store.$findDefaults.fetchPolicy ?? defaultFetchPolicy,
+      }
+      store.$hooks.callHookSync('resolveFindOptions', {
+        store: store as unknown as GlobalStoreType,
+        collection,
+        many,
+        meta,
+        findOptions: resolvedOptions,
+        updateFindOptions: (newFindOptions: any) => {
+          Object.assign(resolvedOptions, newFindOptions)
+        },
+      })
+      if (resolvedOptions.meta) {
+        Object.assign(meta, resolvedOptions.meta)
+      }
+      Object.defineProperty(resolvedOptions, resolvedFindOptionsMarker, {
+        value: true,
+        enumerable: false,
+      })
+      return resolvedOptions
     },
     $processItemParsing(collection, item) {
       store.$hooks.callHookSync('parseItem', {
diff --git a/packages/core/test/mutation/updateMany.spec.ts b/packages/core/test/mutation/updateMany.spec.ts
@@ -32,7 +32,10 @@ describe('updateMany', () => {
       $mutationHistory: [],
       $processItemParsing: vi.fn(),
       $processItemSerialization: vi.fn(),
-      $getFetchPolicy: vi.fn(() => 'cache-first'),
+      $resolveFindOptions: (collection: any, options: any) => ({
+        fetchPolicy: 'cache-first',
+        ...options,
+      }),
     } as unknown as StoreCore<StoreSchema, CollectionDefaults>
 
     mockCollection = {
diff --git a/packages/core/test/query/findFirst.spec.ts b/packages/core/test/query/findFirst.spec.ts
@@ -48,7 +48,10 @@ describe('findFirst', () => {
         }),
       },
       $hooks: createHooks(),
-      $getFetchPolicy: () => 'cache-first',
+      $resolveFindOptions: (collection: any, options: any) => ({
+        fetchPolicy: 'cache-first',
+        ...options,
+      }),
       $processItemParsing: vi.fn(),
       $dedupePromises: new Map(),
     } as any
@@ -105,15 +108,17 @@ describe('findFirst', () => {
   })
 
   it('should write item to cache if fetch policy allows', async () => {
-    mockStore.$getFetchPolicy = () => 'cache-and-fetch'
     mockStore.$hooks.hook('fetchFirst', (payload) => {
       payload.setResult({ id: '42' })
     })
 
     const result = await findFirst({
       store: mockStore,
       collection,
-      findOptions: '42',
+      findOptions: {
+        key: '42',
+        fetchPolicy: 'cache-and-fetch',
+      },
     })
 
     expect(mockStore.$cache.writeItem).toHaveBeenCalledWith(expect.objectContaining({
@@ -124,29 +129,33 @@ describe('findFirst', () => {
   })
 
   it('should not write item to cache if fetch policy is no-cache', async () => {
-    mockStore.$getFetchPolicy = () => 'no-cache'
     mockStore.$hooks.hook('fetchFirst', (payload) => {
       payload.setResult({ id: '1' })
     })
     await findFirst({
       store: mockStore,
       collection,
-      findOptions: '1',
+      findOptions: {
+        key: '1',
+        fetchPolicy: 'no-cache',
+      },
     })
 
     expect(mockStore.$cache.writeItem).not.toHaveBeenCalled()
   })
 
   it('should wrap item with noCache if fetch policy is no-cache', async () => {
-    mockStore.$getFetchPolicy = () => 'no-cache'
     mockStore.$hooks.hook('fetchFirst', (payload) => {
       payload.setResult({ id: '1' })
     })
 
     await findFirst({
       store: mockStore,
       collection,
-      findOptions: '1',
+      findOptions: {
+        key: '1',
+        fetchPolicy: 'no-cache',
+      },
     })
 
     expect(mockStore.$cache.wrapItem).toHaveBeenCalledOnce()
diff --git a/packages/core/test/query/findMany.spec.ts b/packages/core/test/query/findMany.spec.ts
@@ -44,7 +44,10 @@ describe('findMany', () => {
         },
       },
       $hooks: createHooks(),
-      $getFetchPolicy: () => 'cache-first',
+      $resolveFindOptions: (collection: any, options: any) => ({
+        fetchPolicy: 'cache-first',
+        ...options,
+      }),
       $processItemParsing: vi.fn(),
       $dedupePromises: new Map(),
     } as any
@@ -95,7 +98,6 @@ describe('findMany', () => {
   })
 
   it('should write items to cache if fetch policy allows', async () => {
-    mockStore.$getFetchPolicy = () => 'cache-and-fetch'
     mockStore.$hooks.hook('fetchMany', (payload) => {
       payload.setResult([{ id: '42', name: 'Fetched Item' }])
     })
@@ -107,6 +109,7 @@ describe('findMany', () => {
         params: {
           email: '42',
         },
+        fetchPolicy: 'cache-and-fetch',
       },
     })
 
@@ -118,14 +121,14 @@ describe('findMany', () => {
   })
 
   it('should not write items to cache if fetch policy is no-cache', async () => {
-    mockStore.$getFetchPolicy = () => 'no-cache'
     await findMany({
       store: mockStore,
       collection,
       findOptions: {
         params: {
           email: '42',
         },
+        fetchPolicy: 'no-cache',
       },
     })
 
diff --git a/packages/core/test/query/peekFirst.spec.ts b/packages/core/test/query/peekFirst.spec.ts
@@ -22,7 +22,10 @@ describe('peekFirst', () => {
         readItems: () => [{ id: '1', name: 'Test Item 1' }, { id: '2', name: 'Test Item 2' }],
       },
       $hooks: createHooks(),
-      $getFetchPolicy: () => 'cache-first',
+      $resolveFindOptions: (collection: any, options: any) => ({
+        fetchPolicy: 'cache-first',
+        ...options,
+      }),
     } as any
 
     collection = {
diff --git a/packages/core/test/query/peekMany.spec.ts b/packages/core/test/query/peekMany.spec.ts
@@ -21,7 +21,10 @@ describe('peekMany', () => {
         readItems: () => [{ id: '1', name: 'Test Item 1' }, { id: '2', name: 'Test Item 2' }],
       },
       $hooks: createHooks(),
-      $getFetchPolicy: () => 'cache-first',
+      $resolveFindOptions: (collection: any, options: any) => ({
+        fetchPolicy: 'cache-first',
+        ...options,
+      }),
     } as any
 
     collection = {
diff --git a/packages/core/test/store.spec.ts b/packages/core/test/store.spec.ts
@@ -1,4 +1,4 @@
-import type { Cache, CollectionDefaults, FetchPolicy, Plugin, StoreSchema } from '@rstore/shared'
+import type { Cache, CollectionDefaults, Plugin, StoreSchema } from '@rstore/shared'
 import type { CreateStoreCoreOptions } from '../src/store'
 import { createHooks } from '@rstore/shared'
 import { beforeEach, describe, expect, it, vi } from 'vitest'
@@ -199,26 +199,68 @@ describe('createStoreCore', () => {
     })
   })
 
-  describe('getFetchPolicy', () => {
-    it('should return default fetch policy if no value is provided', async () => {
+  describe('resolve find options', () => {
+    it('should resolve to default fetch policy if not provided', async () => {
+      options.schema = [
+        { name: 'messages' },
+      ]
       const store = await createStoreCore(options)
-      const fetchPolicy = store.$getFetchPolicy(undefined)
-      expect(fetchPolicy).toBe(defaultFetchPolicy)
+
+      const collection = store.$collections.find(c => c.name === 'messages')!
+
+      const resolved = store.$resolveFindOptions(collection, {}, true, {})
+
+      expect(resolved.fetchPolicy).toBe(defaultFetchPolicy)
     })
 
-    it('should return provided fetch policy if value is provided', async () => {
-      const customFetchPolicy = 'some-policy' as FetchPolicy
+    it('should usee the default find options from the store', async () => {
+      options.schema = [
+        { name: 'messages' },
+      ]
+      options.findDefaults = {
+        fetchPolicy: 'fetch-only',
+      }
       const store = await createStoreCore(options)
-      const fetchPolicy = store.$getFetchPolicy(customFetchPolicy)
-      expect(fetchPolicy).toBe(customFetchPolicy)
+      const collection = store.$collections.find(c => c.name === 'messages')!
+
+      const resolved = store.$resolveFindOptions(collection, {}, true, {})
+
+      expect(resolved.fetchPolicy).toBe('fetch-only')
     })
 
-    it('should return findDefaults fetch policy if no value is provided and findDefaults has fetch policy', async () => {
-      const customFetchPolicy = 'find-default-policy' as FetchPolicy
-      options.findDefaults = { fetchPolicy: customFetchPolicy }
+    it('should override default find options with provided options', async () => {
+      options.schema = [
+        { name: 'messages' },
+      ]
+      options.findDefaults = {
+        pageSize: 25,
+        fetchPolicy: 'fetch-only',
+      }
       const store = await createStoreCore(options)
-      const fetchPolicy = store.$getFetchPolicy(undefined)
-      expect(fetchPolicy).toBe(customFetchPolicy)
+      const collection = store.$collections.find(c => c.name === 'messages')!
+
+      const resolved = store.$resolveFindOptions(collection, { fetchPolicy: 'cache-and-fetch' }, true, {})
+
+      expect(resolved.fetchPolicy).toBe('cache-and-fetch')
+      expect(resolved.pageSize).toBe(25)
+    })
+
+    it('should call resolveFindOptions hook', async () => {
+      options.schema = [
+        { name: 'messages' },
+      ]
+      options.hooks = createHooks()
+      options.hooks.hook('resolveFindOptions', ({ updateFindOptions }) => {
+        updateFindOptions({
+          fetchPolicy: 'cache-and-fetch',
+        })
+      })
+      const store = await createStoreCore(options)
+      const collection = store.$collections.find(c => c.name === 'messages')!
+
+      const resolved = store.$resolveFindOptions(collection, { fetchPolicy: 'cache-only' }, true, {})
+
+      expect(resolved.fetchPolicy).toBe('cache-and-fetch')
     })
   })
 
diff --git a/packages/shared/src/types/hooks.ts b/packages/shared/src/types/hooks.ts
diff --git a/packages/shared/src/types/store.ts b/packages/shared/src/types/store.ts
diff --git a/packages/vue/src/api.ts b/packages/vue/src/api.ts
diff --git a/packages/vue/src/query.ts b/packages/vue/src/query.ts
diff --git a/packages/vue/test/item.spec.ts b/packages/vue/test/item.spec.ts
