feat(plugin): auto abort fetchFirst & fetchMany

Author: Akryum

docs/guide/plugin/hooks.md

@@ -49,6 +49,16 @@ hook('fetchFirst', (payload) => {
 Markers are used to remember if a query has already been fetched or not where it is not based on the item key. For example, if you have a query that fetches all items with a certain filter, the marker is used to remember if the query has already been fetched or not.
 :::
 
+::: warning Auto-abort remaining callbacks
+If a non-null result is set with `setResult`, the remaining callbacks for this hook will not be called by default. This is useful in case you have multiple plugins that can fetch the same collections (for example, one local and one remote). The first plugin to set a non-null result will abort the remaining callbacks.
+
+You can override this behavior by passing `{ abort: false }` as the second argument to `setResult`.
+
+```ts
+setResult(result, { abort: false })
+```
+:::
+
 Example:
 
 ::: code-group
@@ -110,6 +120,16 @@ hook('fetchMany', (payload) => {
 })
 ```
 
+::: warning Auto-abort remaining callbacks
+If a non-null result is set with `setResult`, the remaining callbacks for this hook will not be called by default. This is useful in case you have multiple plugins that can fetch the same collections (for example, one local and one remote). The first plugin to set a non-null result will abort the remaining callbacks.
+
+You can override this behavior by passing `{ abort: false }` as the second argument to `setResult`.
+
+```ts
+setResult(result, { abort: false })
+```
+:::
+
 Example:
 
 ::: code-group

packages/core/src/query/findFirst.ts

@@ -96,15 +96,19 @@ async function _findFirst<
       },
     })
 
+    const abort = store.$hooks.withAbort()
     await store.$hooks.callHook('fetchFirst', {
       store,
       meta,
       collection,
       key: findOptions.key,
       findOptions,
       getResult: () => result,
-      setResult: (value) => {
+      setResult: (value, options) => {
         result = value
+        if (result && options?.abort !== false) {
+          abort()
+        }
       },
       setMarker: (value) => {
         marker = value

packages/core/src/query/findMany.ts

@@ -61,7 +61,7 @@ async function _findMany<
   findOptions = findOptions ?? {}
   const fetchPolicy = store.$getFetchPolicy(findOptions.fetchPolicy)
 
-  let result: any
+  let result: any[] | undefined
   let marker: string | undefined
 
   if (shouldReadCacheFromFetchPolicy(fetchPolicy)) {
@@ -91,14 +91,18 @@ async function _findMany<
       },
     })
 
+    const abort = store.$hooks.withAbort()
     await store.$hooks.callHook('fetchMany', {
       store,
       meta,
       collection,
       findOptions,
-      getResult: () => result,
-      setResult: (value) => {
+      getResult: () => result ?? [],
+      setResult: (value, options) => {
         result = value
+        if (result?.length && options?.abort !== false) {
+          abort()
+        }
       },
       setMarker: (value) => {
         marker = value
@@ -121,25 +125,25 @@ async function _findMany<
       for (const item of result) {
         store.$processItemParsing(collection, item)
       }
-    }
 
-    if (fetchPolicy !== 'no-cache') {
-      const items = result
-      const writes: Array<WriteItem<TCollection, TCollectionDefaults, TSchema>> = []
-      for (const item of items) {
-        const key = collection.getKey(item)
-        if (!key) {
-          console.warn(`Key is undefined for ${collection.name}. Item was not written to cache.`)
-          continue
+      if (fetchPolicy !== 'no-cache') {
+        const items = result
+        const writes: Array<WriteItem<TCollection, TCollectionDefaults, TSchema>> = []
+        for (const item of items) {
+          const key = collection.getKey(item)
+          if (!key) {
+            console.warn(`Key is undefined for ${collection.name}. Item was not written to cache.`)
+            continue
+          }
+          writes.push({ key, value: item })
+        }
+        if (writes.length) {
+          store.$cache.writeItems<TCollection>({
+            collection,
+            items: writes,
+            marker: getMarker('many', marker),
+          })
         }
-        writes.push({ key, value: item })
-      }
-      if (writes.length) {
-        store.$cache.writeItems<TCollection>({
-          collection,
-          items: writes,
-          marker: getMarker('many', marker),
-        })
       }
     }
   }
@@ -160,7 +164,7 @@ async function _findMany<
   }
 
   return {
-    result,
+    result: result ?? [],
     marker,
   }
 }

packages/core/test/query/findFirst.spec.ts

@@ -320,4 +320,88 @@ describe('findFirst', () => {
       ])
     })
   })
+
+  describe('abort fetchFirst', () => {
+    it('should abort fetchFirst if setResult is called', async () => {
+      const fetchFirstHook1 = vi.fn((payload) => {
+        payload.setResult({ id: '42' })
+      })
+      const fetchFirstHook2 = vi.fn((payload) => {
+        payload.setResult({ id: '43' })
+      })
+      mockStore.$hooks.hook('fetchFirst', fetchFirstHook1)
+      mockStore.$hooks.hook('fetchFirst', fetchFirstHook2)
+
+      const result = await findFirst({
+        store: mockStore,
+        collection,
+        findOptions: '42',
+      })
+
+      expect(result.result).toEqual({ id: '42' })
+      expect(fetchFirstHook1).toHaveBeenCalled()
+      expect(fetchFirstHook2).not.toHaveBeenCalled()
+    })
+
+    it('should not abort if setResult is not called', async () => {
+      const fetchFirstHook1 = vi.fn()
+      const fetchFirstHook2 = vi.fn((payload) => {
+        payload.setResult({ id: '43' })
+      })
+      mockStore.$hooks.hook('fetchFirst', fetchFirstHook1)
+      mockStore.$hooks.hook('fetchFirst', fetchFirstHook2)
+
+      const result = await findFirst({
+        store: mockStore,
+        collection,
+        findOptions: '42',
+      })
+
+      expect(result.result).toEqual({ id: '43' })
+      expect(fetchFirstHook1).toHaveBeenCalled()
+      expect(fetchFirstHook2).toHaveBeenCalled()
+    })
+
+    it('should not abort if setResult is called with abort: false', async () => {
+      const fetchFirstHook1 = vi.fn((payload) => {
+        payload.setResult({ id: '42' }, { abort: false })
+      })
+      const fetchFirstHook2 = vi.fn((payload) => {
+        payload.setResult({ id: '43' })
+      })
+      mockStore.$hooks.hook('fetchFirst', fetchFirstHook1)
+      mockStore.$hooks.hook('fetchFirst', fetchFirstHook2)
+
+      const result = await findFirst({
+        store: mockStore,
+        collection,
+        findOptions: '42',
+      })
+
+      expect(result.result).toEqual({ id: '43' })
+      expect(fetchFirstHook1).toHaveBeenCalled()
+      expect(fetchFirstHook2).toHaveBeenCalled()
+    })
+
+    it('should not abort if result is nil', async () => {
+      const fetchFirstHook1 = vi.fn((payload) => {
+        payload.setResult(null)
+      })
+      const fetchFirstHook2 = vi.fn((payload) => {
+        payload.setResult({ id: '43' })
+      })
+      mockStore.$hooks.hook('fetchFirst', fetchFirstHook1)
+      mockStore.$hooks.hook('fetchFirst', fetchFirstHook2)
+
+      const result = await findFirst({
+        store: mockStore,
+        collection,
+        findOptions: '42',
+      })
+
+      expect(result.result).toEqual({ id: '43' })
+      expect(fetchFirstHook1).toHaveBeenCalled()
+      expect(fetchFirstHook2).toHaveBeenCalled()
+    })
+  })
 })

packages/core/test/query/findMany.spec.ts

@@ -266,4 +266,109 @@ describe('findMany', () => {
       ])
     })
   })
+
+  describe('abort fetchMany', () => {
+    it('should abort fetchMany if setResult is called', async () => {
+      const fetchManyHook1 = vi.fn((payload) => {
+        payload.setResult([{ id: '42' }])
+      })
+      const fetchManyHook2 = vi.fn((payload) => {
+        payload.setResult([{ id: '43' }])
+      })
+      mockStore.$hooks.hook('fetchMany', fetchManyHook1)
+      mockStore.$hooks.hook('fetchMany', fetchManyHook2)
+
+      const result = await findMany({
+        store: mockStore,
+        collection,
+        findOptions: { params: { teamId: '42' } },
+      })
+
+      expect(result.result).toEqual([{ id: '42' }])
+      expect(fetchManyHook1).toHaveBeenCalled()
+      expect(fetchManyHook2).not.toHaveBeenCalled()
+    })
+
+    it('should not abort if setResult is not called', async () => {
+      const fetchManyHook1 = vi.fn()
+      const fetchManyHook2 = vi.fn((payload) => {
+        payload.setResult([{ id: '43' }])
+      })
+      mockStore.$hooks.hook('fetchMany', fetchManyHook1)
+      mockStore.$hooks.hook('fetchMany', fetchManyHook2)
+
+      const result = await findMany({
+        store: mockStore,
+        collection,
+        findOptions: { params: { teamId: '42' } },
+      })
+
+      expect(result.result).toEqual([{ id: '43' }])
+      expect(fetchManyHook1).toHaveBeenCalled()
+      expect(fetchManyHook2).toHaveBeenCalled()
+    })
+
+    it('should not abort if setResult is called with abort: false', async () => {
+      const fetchManyHook1 = vi.fn((payload) => {
+        payload.setResult([{ id: '42' }], { abort: false })
+      })
+      const fetchManyHook2 = vi.fn((payload) => {
+        payload.setResult([{ id: '43' }])
+      })
+      mockStore.$hooks.hook('fetchMany', fetchManyHook1)
+      mockStore.$hooks.hook('fetchMany', fetchManyHook2)
+
+      const result = await findMany({
+        store: mockStore,
+        collection,
+        findOptions: { params: { teamId: '42' } },
+      })
+
+      expect(result.result).toEqual([{ id: '43' }])
+      expect(fetchManyHook1).toHaveBeenCalled()
+      expect(fetchManyHook2).toHaveBeenCalled()
+    })
+
+    it('should not abort if result is nil', async () => {
+      const fetchManyHook1 = vi.fn((payload) => {
+        payload.setResult(null)
+      })
+      const fetchManyHook2 = vi.fn((payload) => {
+        payload.setResult([{ id: '43' }])
+      })
+      mockStore.$hooks.hook('fetchMany', fetchManyHook1)
+      mockStore.$hooks.hook('fetchMany', fetchManyHook2)
+
+      const result = await findMany({
+        store: mockStore,
+        collection,
+        findOptions: { params: { teamId: '42' } },
+      })
+
+      expect(result.result).toEqual([{ id: '43' }])
+      expect(fetchManyHook1).toHaveBeenCalled()
+      expect(fetchManyHook2).toHaveBeenCalled()
+    })
+
+    it('should not abort if result is empty array', async () => {
+      const fetchManyHook1 = vi.fn((payload) => {
+        payload.setResult([])
+      })
+      const fetchManyHook2 = vi.fn((payload) => {
+        payload.setResult([{ id: '43' }])
+      })
+      mockStore.$hooks.hook('fetchMany', fetchManyHook1)
+      mockStore.$hooks.hook('fetchMany', fetchManyHook2)
+
+      const result = await findMany({
+        store: mockStore,
+        collection,
+        findOptions: { params: { teamId: '42' } },
+      })
+
+      expect(result.result).toEqual([{ id: '43' }])
+      expect(fetchManyHook1).toHaveBeenCalled()
+      expect(fetchManyHook2).toHaveBeenCalled()
+    })
+  })
 })

packages/shared/src/types/hooks.ts

@@ -9,6 +9,14 @@ import type { Awaitable, Path, PathValue } from './utils'
 
 export interface CustomHookMeta {}
 
+export interface AbortableOptions {
+  /**
+   * If true, the remaining hooks in the queue will not be called.
+   * @default true
+   */
+  abort?: boolean
+}
+
 export interface HookDefinitions<
   TSchema extends StoreSchema,
   TCollectionDefaults extends CollectionDefaults,
@@ -62,7 +70,7 @@ export interface HookDefinitions<
       key?: string | number
       findOptions?: FindOptions<TCollection, TCollectionDefaults, TSchema>
       getResult: () => ResolvedCollectionItemBase<TCollection, TCollectionDefaults, TSchema> | undefined
-      setResult: (result: ResolvedCollectionItemBase<TCollection, TCollectionDefaults, TSchema>) => void
+      setResult: (result: ResolvedCollectionItemBase<TCollection, TCollectionDefaults, TSchema>, options?: AbortableOptions) => void
       setMarker: (marker: string) => void
     }
   ) => Awaitable<void>
@@ -110,7 +118,7 @@ export interface HookDefinitions<
       collection: ResolvedCollection<TCollection, TCollectionDefaults, TSchema>
       findOptions?: FindOptions<TCollection, TCollectionDefaults, TSchema>
       getResult: () => Array<ResolvedCollectionItemBase<TCollection, TCollectionDefaults, TSchema>>
-      setResult: (result: Array<ResolvedCollectionItemBase<TCollection, TCollectionDefaults, TSchema>>) => void
+      setResult: (result: Array<ResolvedCollectionItemBase<TCollection, TCollectionDefaults, TSchema>>, options?: AbortableOptions) => void
       setMarker: (marker: string) => void
     }
   ) => Awaitable<void>