@codeleap/query 5.8.7 → 5.8.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codeleap/query",
-  "version": "5.8.7",
+  "version": "5.8.9",
   "main": "src/index.ts",
   "license": "UNLICENSED",
   "repository": {
@@ -9,15 +9,15 @@
     "directory": "packages/query"
   },
   "devDependencies": {
-    "@codeleap/config": "5.8.7",
-    "@codeleap/types": "5.8.7",
+    "@codeleap/config": "5.8.9",
+    "@codeleap/types": "5.8.9",
     "ts-node-dev": "1.1.8"
   },
   "scripts": {
     "build": "echo 'No build needed'"
   },
   "peerDependencies": {
-    "@codeleap/types": "5.8.7",
+    "@codeleap/types": "5.8.9",
     "typescript": "5.5.2",
     "@tanstack/react-query": "5.89.0"
   },

package/package.json.bak

@@ -1,6 +1,6 @@
 {
   "name": "@codeleap/query",
-  "version": "5.8.7",
+  "version": "5.8.9",
   "main": "src/index.ts",
   "license": "UNLICENSED",
   "repository": {

package/src/lib/Mutations.ts

@@ -2,6 +2,7 @@ import { InfiniteData } from '@tanstack/query-core'
 import { QueryKeys } from './QueryKeys'
 import { ItemPosition, ListPaginationResponse, PageParam, QueryClient, QueryItem, RemovedItemMap, WithTempId } from '../types'
 import deepEqual from 'fast-deep-equal'
+import { TypeGuards } from '@codeleap/types'
 
 /**
  * Class for managing mutations and cache updates for React Query list data
@@ -129,10 +130,10 @@ export class Mutations<T extends QueryItem, F> {
    * }
    * ```
    */
-  removeItem(itemId: QueryItem['id']): RemovedItemMap | null {
+  removeItem(itemId: QueryItem['id'], listFilters?: F): RemovedItemMap | null {
     this.queryKeys.removeRetrieveQueryData(itemId)
 
-    const listQueries = this.queryKeys.getAllListQueries()
+    const listQueries = TypeGuards.isNil(listFilters) ? this.queryKeys.getAllListQueries() : [this.queryKeys.getListQuery(listFilters)]
 
     const removedItemMap: RemovedItemMap = []
 

package/src/lib/QueryKeys.ts

@@ -1,7 +1,7 @@
 import { CancelOptions, InfiniteData, InvalidateOptions, InvalidateQueryFilters, Query, QueryFilters, QueryKey, RefetchOptions, RefetchQueryFilters } from '@tanstack/react-query'
 import { useMemo } from 'react'
 import { TypeGuards } from '@codeleap/types'
-import { ListPaginationResponse, ListSelector, PageParam, QueryClient, QueryItem } from '../types'
+import { ListPaginationResponse, ListSelector, PageParam, QueryClient, QueryItem, RetrieveDataOptions } from '../types'
 import deepEqual from 'fast-deep-equal'
 
 /**
@@ -272,25 +272,57 @@ export class QueryKeys<T extends QueryItem, F> {
   }
 
   /**
-   * Gets retrieve data from cache, with fallback to list data
-   * @param id - The ID of the item to retrieve
-   * @param onlyQueryData - If true, only returns data from the specific retrieve query, not from list data
-   * @returns The item data or undefined if not found
+    * Retrieves item data from cache with intelligent fallback strategies
+    * 
+    * @description Searches for an item using a multi-layered approach:
+    * 1. Direct cache lookup using retrieve query
+    * 2. Fallback to itemMap from list data (shallow search)  
+    * 3. Deep search through all paginated list queries
+    * 
+    * @param {QueryItem['id']} id - The unique identifier of the item to retrieve
+    * @param {RetrieveDataOptions} [options] - Configuration options for retrieval behavior
+    * @param {boolean} [options.onlyQueryData=false] - If true, only returns data from the specific retrieve query cache, ignoring list data fallbacks
+    * @param {boolean} [options.deepSearch=true] - If true, performs deep search through paginated queries when item not found in direct cache or itemMap
+    * 
+    * @returns Item | undefined
    */
-  getRetrieveData(id: QueryItem['id'], onlyQueryData = false): T | undefined {
+  getRetrieveData(id: QueryItem['id'], options: RetrieveDataOptions = {}): T | undefined {
+    const {
+      onlyQueryData = false,
+      deepSearch = false,
+    } = options
+
     if (TypeGuards.isNil(id)) return undefined
 
     const queryKey = this.keys.retrieve(id)
 
     const queryData = this.queryClient.getQueryData<T>(queryKey)
 
-    if (!queryData?.id && !onlyQueryData) {
+    if (queryData?.id) return queryData
+
+    if (onlyQueryData) return undefined
+
+    if (!deepSearch) {
       const { itemMap } = this.getListData()
 
       return itemMap?.[id]
     }
 
-    return queryData
+    const queries = this.getAllListQueries()
+
+    for (const query of queries) {
+      const pages = query.state.data?.pages
+      if (!pages?.length) continue
+
+      const item = pages
+        .filter(Boolean)
+        .flatMap(page => Array.isArray(page) ? page : [])
+        .find(item => item?.id === id)
+
+      if (item) return item
+    }
+
+    return undefined
   }
 
   /**
@@ -304,6 +336,14 @@ export class QueryKeys<T extends QueryItem, F> {
 
     return queries as Query<ListPaginationResponse<T>, Error, Omit<ListSelector<T>, 'allItems'>, QueryKey>[]
   }
+
+  getListQuery(listFilters?: F) {
+    const query = this.queryClient.getQueryCache().find({
+      queryKey: this.listKeyWithFilters(listFilters)
+    })
+
+    return query as Query<ListPaginationResponse<T>, Error, Omit<ListSelector<T>, 'allItems'>, QueryKey>
+  }
 }
 
 /**

package/src/lib/QueryManager.ts

@@ -1,4 +1,4 @@
-import { FetchQueryOptions, InfiniteData, MutationFunctionContext, QueryKey, useInfiniteQuery, useMutation, useQuery } from '@tanstack/react-query'
+import { FetchInfiniteQueryOptions, FetchQueryOptions, InfiniteData, MutationFunctionContext, QueryKey, useInfiniteQuery, useMutation, useQuery } from '@tanstack/react-query'
 import { useCallback } from 'react'
 import { createQueryKeys, QueryKeys } from './QueryKeys'
 import { createMutations, Mutations } from './Mutations'
@@ -485,4 +485,39 @@ export class QueryManager<T extends QueryItem, F> {
       queryFn: () => this.options.retrieveFn(id),
     })
   }
+
+  /**
+   * Prefetches a paginated list with filters for improved performance
+   * @param filters - Filter parameters to apply to the list query
+   * @param options - Prefetch options compatible with React Query's infinite queries
+   * @param options.initialOffset - Starting offset for pagination (default: 0)
+   * @returns Promise that resolves when prefetch is complete
+   * 
+   * @description
+   * Use this method to preload paginated list data that users are likely to need soon.
+   * 
+   * @example
+   * ```typescript
+   * const handle = () => {
+   *   queryManager.prefetchList(
+   *     { category: 'electronics' },
+   *     { staleTime: 5 * 60 * 1000 }
+   *   )
+   * }
+   * 
+   * ```
+   */
+  prefetchList(
+    filters?: F,
+    options: Omit<FetchInfiniteQueryOptions<ListPaginationResponse<T>, Error, ListPaginationResponse<T>, QueryKey, number>, 'queryKey' | 'queryFn' | 'initialPageParam'> & { initialOffset?: number } = {}
+  ) {
+    const { initialOffset = 0, ...prefetchOptions } = options
+
+    return this.options.queryClient.prefetchInfiniteQuery({
+      ...prefetchOptions as any,
+      initialPageParam: initialOffset,
+      queryKey: this.queryKeys.listKeyWithFilters(filters),
+      queryFn: () => this.options.listFn(this.options.listLimit ?? 10, initialOffset, filters),
+    })
+  }
 }

package/src/types/retrieve.ts

@@ -5,3 +5,8 @@ export type RetrieveQueryOptions<T extends QueryItem> = Omit<
   UndefinedInitialDataOptions<T, Error, T, QueryKey>,
   'queryKey' | 'queryFn'
 >
+
+export type RetrieveDataOptions = {
+  onlyQueryData?: boolean
+  deepSearch?: boolean
+}