@codeleap/query 5.8.2 → 5.8.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@codeleap/query",
-  "version": "5.8.2",
+  "version": "5.8.4",
   "main": "src/index.ts",
   "license": "UNLICENSED",
   "repository": {
@@ -9,23 +9,19 @@
     "directory": "packages/query"
   },
   "devDependencies": {
-    "@codeleap/config": "5.8.2",
-    "@codeleap/types": "5.8.2",
-    "@codeleap/utils": "5.8.2",
-    "@codeleap/hooks": "5.8.2",
+    "@codeleap/config": "5.8.4",
+    "@codeleap/types": "5.8.4",
     "ts-node-dev": "1.1.8"
   },
   "scripts": {
     "build": "echo 'No build needed'"
   },
   "peerDependencies": {
-    "@codeleap/types": "5.8.2",
-    "@codeleap/utils": "5.8.2",
-    "@codeleap/hooks": "5.8.2",
+    "@codeleap/types": "5.8.4",
     "typescript": "5.5.2",
-    "@tanstack/react-query": "5.60.6"
+    "@tanstack/react-query": "5.89.0"
   },
   "dependencies": {
-    "immer": "10.1.1"
+    "fast-deep-equal": "3.1.3"
   }
 }

package/package.json.bak

@@ -1,6 +1,6 @@
 {
   "name": "@codeleap/query",
-  "version": "5.8.2",
+  "version": "5.8.4",
   "main": "src/index.ts",
   "license": "UNLICENSED",
   "repository": {
@@ -11,8 +11,6 @@
   "devDependencies": {
     "@codeleap/config": "workspace:*",
     "@codeleap/types": "workspace:*",
-    "@codeleap/utils": "workspace:*",
-    "@codeleap/hooks": "workspace:*",
     "ts-node-dev": "1.1.8"
   },
   "scripts": {
@@ -20,12 +18,10 @@
   },
   "peerDependencies": {
     "@codeleap/types": "workspace:*",
-    "@codeleap/utils": "workspace:*",
-    "@codeleap/hooks": "workspace:*",
     "typescript": "5.5.2",
-    "@tanstack/react-query": "5.60.6"
+    "@tanstack/react-query": "5.89.0"
   },
   "dependencies": {
-    "immer": "10.1.1"
+    "fast-deep-equal": "3.1.3"
   }
 }

package/src/factors/createQueryManager.ts

@@ -0,0 +1,38 @@
+import { QueryManager } from '../lib'
+import { QueryItem, QueryManagerOptions } from '../types'
+
+/**
+ * Factory function to create a new QueryManager instance
+ * @template T - The query item type that extends QueryItem
+ * @template F - The filter type used for list queries
+ * @param options - Configuration options for the query manager
+ * @returns New QueryManager instance
+ * 
+ * @example
+ * ```typescript
+ * interface User extends QueryItem {
+ *   name: string
+ *   email: string
+ *   status: 'active' | 'inactive'
+ * }
+ * 
+ * interface UserFilters {
+ *   status?: 'active' | 'inactive'
+ *   search?: string
+ * }
+ * 
+ * const userQueryManager = createQueryManager<User, UserFilters>({
+ *   name: 'users',
+ *   queryClient,
+ *   listFn: (limit, offset, filters) => api.getUsers({ limit, offset, ...filters }),
+ *   retrieveFn: (id) => api.getUser(id),
+ *   createFn: (data) => api.createUser(data),
+ *   updateFn: (data) => api.updateUser(data.id, data),
+ *   deleteFn: (id) => api.deleteUser(id),
+ *   listLimit: 20
+ * })
+ * ```
+ */
+export const createQueryManager = <T extends QueryItem, F = {}>(options: QueryManagerOptions<T, F>) => {
+  return new QueryManager<T, F>(options)
+}

package/src/factors/createQueryOperations.ts

@@ -0,0 +1,37 @@
+import { QueryOperations } from '../lib'
+import { QueryOperationsOptions } from '../lib/QueryOperations/types'
+
+/**
+ * Factory function to create a new QueryOperations builder instance
+ * @param options - Configuration options including the QueryClient
+ * @returns New QueryOperations instance ready for operation registration
+ * 
+ * @description
+ * This is the entry point for creating a new QueryOperations instance. Use this
+ * function to start building your collection of queries and mutations.
+ * 
+ * @example
+ * ```typescript
+ * import { QueryClient } from '@tanstack/react-query'
+ * 
+ * const queryClient = new QueryClient()
+ * 
+ * const userOperations = createQueryOperations({ queryClient })
+ *   .query('getUser', async (id: string) => fetchUser(id))
+ *   .query('getUsers', async (filters?: UserFilters) => fetchUsers(filters))
+ *   .mutation('createUser', async (data: CreateUserData) => createUser(data))
+ *   .mutation('updateUser', async (data: UpdateUserData) => updateUser(data))
+ *   .mutation('deleteUser', async (id: string) => deleteUser(id))
+ * 
+ * // In components
+ * function UserList() {
+ *   const usersQuery = userOperations.useQuery('getUsers', { active: true })
+ *   const createMutation = userOperations.useMutation('createUser')
+ *   
+ *   // Both hooks are fully type-safe
+ * }
+ * ```
+ */
+export function createQueryOperations(options: QueryOperationsOptions) {
+  return new QueryOperations(options)
+}

package/src/factors/index.ts

@@ -0,0 +1,2 @@
+export * from './createQueryManager'
+export * from './createQueryOperations'

package/src/index.ts

@@ -1,9 +1,3 @@
-export * from './QueryManager'
-export * from './queryClient'
+export * from './lib'
 export * from './types'
-
-import * as ReactQuery from '@tanstack/react-query'
-
-export {
-  ReactQuery
-}
+export * from './factors'

package/src/lib/Mutations.ts

@@ -0,0 +1,280 @@
+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'
+
+/**
+ * Class for managing mutations and cache updates for React Query list data
+ * @template T - The query item type that extends QueryItem
+ * @template F - The filter type used for list queries
+ */
+export class Mutations<T extends QueryItem, F> {
+  /**
+   * Creates a new Mutations instance
+   * @param queryKeys - The QueryKeys instance for managing query keys
+   * @param queryClient - The React Query client instance
+   * @param queryName - The name of the query used for identification
+   */
+  constructor(
+    private queryKeys: QueryKeys<T, F>,
+    private queryClient: QueryClient,
+    private queryName: string
+  ) { }
+
+  /**
+   * Adds a new item to the cached list data
+   * @param newItem - The new item to add to the list
+   * @param position - Where to add the item: 'start', 'end', or a RemovedItemMap for specific positions
+   * @param listFilters - Optional filters to target specific list queries
+   * 
+   * @example
+   * ```typescript
+   * // Add item to the beginning
+   * mutations.addItem(newUser, 'start')
+   * 
+   * // Add item to the end with filters
+   * mutations.addItem(newUser, 'end', { status: 'active' })
+   * 
+   * // Add item to specific positions (restore from removed item map)
+   * mutations.addItem(newUser, removedItemMap)
+   * ```
+   */
+  addItem(newItem: T, position: 'start' | 'end' | RemovedItemMap = 'start', listFilters?: F) {
+    const isMultiQueryKeys = Array.isArray(position) && position?.length >= 1
+
+    if (isMultiQueryKeys) {
+      for (const [queryKey, itemPosition] of position) {
+        const currentData = this.queryClient.getQueryData<InfiniteData<ListPaginationResponse<T>, PageParam>>(queryKey)
+
+        const updatedPages = [...currentData.pages]
+
+        if (itemPosition.pageIndex < updatedPages.length) {
+          const targetPage = [...updatedPages[itemPosition.pageIndex]]
+
+          const insertIndex = Math.min(itemPosition.itemIndex, targetPage.length)
+          targetPage.splice(insertIndex, 0, newItem)
+          updatedPages[itemPosition.pageIndex] = targetPage
+        } else {
+          const lastPageIndex = updatedPages.length - 1
+          if (lastPageIndex >= 0) {
+            updatedPages[lastPageIndex] = [...updatedPages[lastPageIndex], newItem]
+          } else {
+            updatedPages.push([newItem])
+          }
+        }
+
+        const newData = {
+          ...currentData,
+          pages: updatedPages
+        }
+
+        this.queryClient.setQueryData(queryKey, newData)
+      }
+
+      return
+    }
+
+    const queryKey = this.queryKeys.listKeyWithFilters(listFilters)
+
+    const currentData = this.queryClient.getQueryData<InfiniteData<ListPaginationResponse<T>, PageParam>>(queryKey)
+
+    if (!currentData) {
+      const newData = {
+        pageParams: [0],
+        pages: [[newItem]]
+      }
+
+      this.queryClient.setQueryData(queryKey, newData)
+
+      return
+    }
+
+    const updatedPages = [...currentData.pages]
+
+    if (position === 'start') {
+      if (updatedPages.length > 0) {
+        updatedPages[0] = [newItem, ...updatedPages[0]]
+      } else {
+        updatedPages.push([newItem])
+      }
+    } else if (position === 'end') {
+      if (updatedPages.length > 0) {
+        const lastPageIndex = updatedPages.length - 1
+        updatedPages[lastPageIndex] = [...updatedPages[lastPageIndex], newItem]
+      } else {
+        updatedPages.push([newItem])
+      }
+    }
+
+    const newData = {
+      ...currentData,
+      pages: updatedPages
+    }
+
+    this.queryClient.setQueryData(queryKey, newData)
+  }
+
+  /**
+   * Removes an item from all cached list queries and returns the positions where it was found
+   * @param itemId - The ID of the item to remove
+   * @returns A RemovedItemMap containing the query keys and positions where the item was found, or null if not found
+   * 
+   * @example
+   * ```typescript
+   * const removedPositions = mutations.removeItem('user-123')
+   * 
+   * // Later, restore the item to its original positions
+   * if (removedPositions) {
+   *   mutations.addItem(restoredUser, removedPositions)
+   * }
+   * ```
+   */
+  removeItem(itemId: QueryItem['id']): RemovedItemMap | null {
+    this.queryKeys.removeRetrieveQueryData(itemId)
+
+    const listQueries = this.queryKeys.getAllListQueries()
+
+    const removedItemMap: RemovedItemMap = []
+
+    for (const query of listQueries) {
+      const currentData = query.state?.data
+      const queryKey = query?.queryKey
+
+      if (!currentData) continue
+
+      let removedItemPosition: ItemPosition | null = null
+
+      for (let pageIndex = 0; pageIndex < currentData?.pages?.length; pageIndex++) {
+        const page = currentData.pages[pageIndex]
+        const itemIndex = page.findIndex((item: T) => item?.id === itemId)
+
+        if (itemIndex !== -1) {
+          removedItemPosition = {
+            pageIndex,
+            itemIndex,
+          }
+          break
+        }
+      }
+
+      if (!removedItemPosition) continue
+
+      removedItemMap.push([queryKey, removedItemPosition])
+
+      const updatedPages = currentData.pages.map(page =>
+        page.filter((item: T) => item?.id !== itemId)
+      )
+
+      const filteredPages = updatedPages.filter(page => page?.length > 0)
+      const finalPages = filteredPages?.length > 0 ? filteredPages : [[]]
+      const newPageParams = currentData?.pageParams?.slice(0, finalPages?.length)
+
+      const newData = {
+        ...currentData,
+        pages: finalPages,
+        pageParams: newPageParams
+      }
+
+      this.queryClient.setQueryData(queryKey, newData)
+    }
+
+    return removedItemMap
+  }
+
+  /**
+   * Updates existing items in all cached list queries and individual retrieve queries
+   * @param data - Single item or array of items to update. Items can have tempId for temporary identification
+   * 
+   * @description
+   * This method:
+   * - Finds items by their ID or tempId in all list queries
+   * - Updates the items only if the data has actually changed (uses deep equality check)
+   * - Updates both list cache and individual retrieve cache
+   * - Removes tempId from the final cached data
+   * 
+   * @example
+   * ```typescript
+   * // Update single item
+   * mutations.updateItems({ id: 'user-123', name: 'Updated Name', tempId: 'temp-1' })
+   * 
+   * // Update multiple items
+   * mutations.updateItems([
+   *   { id: 'user-123', name: 'Updated Name' },
+   *   { id: 'user-456', status: 'active' }
+   * ])
+   * ```
+   */
+  updateItems(data: WithTempId<T> | WithTempId<T>[]) {
+    const listQueries = this.queryKeys.getAllListQueries()
+
+    const dataArray = Array.isArray(data) ? data : [data]
+
+    for (const item of dataArray) {
+      const { tempId, ...updateData } = item
+      const cachedQueryKey = this.queryKeys.keys.retrieve(updateData.id)
+      const cachedItemData = this.queryKeys.getRetrieveData(updateData.id)
+      if (!deepEqual(cachedItemData, updateData)) {
+        this.queryClient.setQueryData(cachedQueryKey, updateData)
+      }
+    }
+
+    const dataMap = Object.fromEntries(dataArray.map(item => [item?.tempId ?? item?.id, item]))
+
+    for (const query of listQueries) {
+      const oldData = query.state?.data
+      const queryKey = query?.queryKey
+
+      if (!oldData) continue
+
+      let hasChanges = false
+
+      const updatedPages = oldData.pages.map(page => {
+        let pageChanged = false
+
+        const updatedPage = page.map((item) => {
+          if (dataMap?.[item?.id]) {
+            const { tempId, ...updateData } = dataMap?.[item?.id]
+
+            const needsUpdate = !deepEqual(item, updateData)
+
+            if (needsUpdate) {
+              pageChanged = true
+              hasChanges = true
+              return updateData
+            }
+          }
+
+          return item
+        })
+
+        return pageChanged ? updatedPage : page
+      })
+
+      if (hasChanges) {
+        this.queryClient.setQueryData(queryKey, {
+          ...oldData,
+          pages: updatedPages
+        })
+      }
+    }
+  }
+}
+
+/**
+ * Factory function to create a new Mutations instance
+ * @template T - The query item type that extends QueryItem
+ * @template F - The filter type used for list queries
+ * @param queryKeys - The QueryKeys instance for managing query keys
+ * @param queryClient - The React Query client instance
+ * @param queryName - The name of the query used for identification
+ * @returns New Mutations instance
+ * 
+ * @example
+ * ```typescript
+ * const userQueryKeys = createQueryKeys<User, UserFilters>('users', queryClient)
+ * const userMutations = createMutations(userQueryKeys, queryClient, 'users')
+ * ```
+ */
+export const createMutations = <T extends QueryItem, F>(queryKeys: QueryKeys<T, F>, queryClient: QueryClient, queryName: string) => {
+  return new Mutations<T, F>(queryKeys, queryClient, queryName)
+}

package/src/{queryClient.ts → lib/QueryClientEnhanced/index.ts}

@@ -1,45 +1,11 @@
-import * as ReactQuery from '@tanstack/react-query'
 import { waitFor } from '@codeleap/utils'
-import { QueryManagerOptions, QueryManagerItem } from './types'
-import { QueryManager } from './QueryManager'
+import { QueryClient, QueryKey, Query, hashKey, QueryCacheNotifyEvent, matchQuery, QueryOptions } from '@tanstack/react-query'
+import { DynamicEnhancedQuery, EnhancedQuery, PollQueryOptions, PollingResult, QueryKeyBuilder } from './types'
 
-export type QueryKeyBuilder<Args extends any[] = any[]> = (...args:Args) => ReactQuery.QueryKey
+export class QueryClientEnhanced {
+  constructor(public client: QueryClient) { }
 
-type PollingResult<T> = {
-  stop: boolean
-  data: T
-}
-
-type PollingCallback<T, R> = (query: ReactQuery.Query<T>, count: number, prev?: R) => Promise<PollingResult<R>>
-
-type PollQueryOptions<T, R> = {
-  interval: number
-  callback: PollingCallback<T, R>
-  leading?: boolean
-  initialData?: R
-}
-
-interface EnhancedQuery<T> extends ReactQuery.Query<T> {
-  waitForRefresh(): Promise<ReactQuery.Query<T>>
-  listen(callback: (e: ReactQuery.QueryCacheNotifyEvent) => void): () => void
-  refresh(): Promise<T>
-  poll<R>(
-    options: PollQueryOptions<T, R>
-  ): Promise<R>
-  getData(): T
-  ensureData(options?: Partial<ReactQuery.EnsureQueryDataOptions<T, Error, T, ReactQuery.QueryKey, never>>): Promise<T>
-  key: ReactQuery.QueryKey
-}
-
-type DynamicEnhancedQuery<T, BuilderArgs extends any[]> = {
-  [P in keyof EnhancedQuery<T>]: (...args: BuilderArgs) => EnhancedQuery<T>[P]
-}
-
-export class CodeleapQueryClient {
-  constructor(public client: ReactQuery.QueryClient) {
-  }
-
-  listenToQuery(key: ReactQuery.QueryKey, callback: (e: ReactQuery.QueryCacheNotifyEvent) => void) {
+  listenToQuery(key: QueryKey, callback: (e: QueryCacheNotifyEvent) => void) {
     const cache = this.client.getQueryCache()
 
     const query = cache.find({ exact: true, queryKey: key })
@@ -49,7 +15,7 @@ export class CodeleapQueryClient {
     }
 
     const removeListener = cache.subscribe((e) => {
-      const matches = ReactQuery.matchQuery({ exact: true, queryKey: key }, e.query)
+      const matches = matchQuery({ exact: true, queryKey: key }, e.query)
 
       if (matches) {
         callback(e)
@@ -61,7 +27,7 @@ export class CodeleapQueryClient {
   }
 
   async pollQuery<T, R>(
-    key: ReactQuery.QueryKey,
+    key: QueryKey,
     options: PollQueryOptions<T, R>,
   ) {
     const { interval, callback, initialData, leading = false } = options
@@ -100,10 +66,9 @@ export class CodeleapQueryClient {
     }
 
     return result?.data
-
   }
 
-  queryProxy<T>(key: ReactQuery.QueryKey) {
+  queryProxy<T>(key: QueryKey) {
     const getClient = () => this
 
     return new Proxy<EnhancedQuery<T>>({} as EnhancedQuery<T>, {
@@ -133,15 +98,16 @@ export class CodeleapQueryClient {
         }
 
         switch (p) {
-
           case 'waitForRefresh':
             return () => {
               return client.waitForRefresh<T>(key)
             }
+
           case 'listen':
-            return (callback: (e: ReactQuery.QueryCacheNotifyEvent) => void) => {
+            return (callback: (e: QueryCacheNotifyEvent) => void) => {
               return client.listenToQuery(key, callback)
             }
+
           case 'ensureData':
             return (options) => {
               return client.client.ensureQueryData<T>({
@@ -149,6 +115,7 @@ export class CodeleapQueryClient {
                 ...options
               })
             }
+
           case 'refresh':
             return async () => {
               client.client.refetchQueries({
@@ -158,19 +125,20 @@ export class CodeleapQueryClient {
               const newQuery = await client.waitForRefresh<T>(key)
               return newQuery.state.data
             }
+
           case 'poll':
             return (options: PollQueryOptions<T, any>) => {
               return client.pollQuery(key, options)
             }
+
           default:
             return Reflect.get(query, p, receiver)
         }
       },
-
     })
   }
 
-  waitForRefresh<T>(key: ReactQuery.QueryKey) {
+  waitForRefresh<T>(key: QueryKey) {
     const initialQuery = this.client.getQueryCache().find({ exact: true, queryKey: key })
 
     if (!initialQuery) {
@@ -180,7 +148,7 @@ export class CodeleapQueryClient {
     const updateTime = initialQuery.state.dataUpdatedAt
     const errorTime = initialQuery.state.errorUpdatedAt
 
-    return new Promise<ReactQuery.Query<T>>((resolve, reject) => {
+    return new Promise<Query<T>>((resolve, reject) => {
       const removeListener = this.listenToQuery(key, (e) => {
         const query = e.query
 
@@ -207,21 +175,19 @@ export class CodeleapQueryClient {
 
   }
 
-  queryKey<Data>(k: ReactQuery.QueryKey, options?: ReactQuery.QueryOptions<Data>) {
-
-    if(options){
-      
+  queryKey<Data>(k: QueryKey, options?: QueryOptions<Data>) {
+    if (options) {
       this.client.setQueryDefaults(k, options)
 
       const cache = this.client.getQueryCache()
-      
-      const q = new ReactQuery.Query({
-        cache,
+
+      const q = new Query({
+        client: this.client,
         queryKey: k,
-        queryHash: ReactQuery.hashKey(k),
+        queryHash: hashKey(k),
         ...options,
       })
-      
+
       cache.add(q)
     }
 
@@ -229,12 +195,11 @@ export class CodeleapQueryClient {
   }
 
   dynamicQueryKey<Data, BuilderArgs extends any[] = any[]>(k: QueryKeyBuilder<BuilderArgs>) {
-
     const getClient = () => this
 
     return new Proxy<DynamicEnhancedQuery<Data, BuilderArgs>>({} as DynamicEnhancedQuery<Data, BuilderArgs>, {
       get(target, p, receiver) {
-        return (...params:BuilderArgs) => {
+        return (...params: BuilderArgs) => {
           const key = k(...params)
 
           const proxy = getClient().queryProxy<Data>(key)
@@ -244,17 +209,4 @@ export class CodeleapQueryClient {
       },
     })
   }
-
-  queryManager<T extends QueryManagerItem, Args>(name:string, options: Partial<QueryManagerOptions<T, Args>>) {
-    // @ts-expect-error
-    const m = new QueryManager<T, Args>({
-      name,
-      queryClient: this.client,
-      ...options,
-
-    })
-
-    return m
-  }
-
 }

package/src/lib/QueryClientEnhanced/types.ts

@@ -0,0 +1,38 @@
+import {
+  QueryKey,
+  Query,
+  QueryCacheNotifyEvent,
+  EnsureQueryDataOptions,
+} from '@tanstack/react-query'
+
+export type QueryKeyBuilder<Args extends any[] = any[]> = (...args: Args) => QueryKey
+
+export type PollingResult<T> = {
+  stop: boolean
+  data: T
+}
+
+export type PollingCallback<T, R> = (query: Query<T>, count: number, prev?: R) => Promise<PollingResult<R>>
+
+export type PollQueryOptions<T, R> = {
+  interval: number
+  callback: PollingCallback<T, R>
+  leading?: boolean
+  initialData?: R
+}
+
+export interface EnhancedQuery<T> extends Query<T> {
+  waitForRefresh(): Promise<Query<T>>
+  listen(callback: (e: QueryCacheNotifyEvent) => void): () => void
+  refresh(): Promise<T>
+  poll<R>(
+    options: PollQueryOptions<T, R>
+  ): Promise<R>
+  getData(): T
+  ensureData(options?: Partial<EnsureQueryDataOptions<T, Error, T, QueryKey, never>>): Promise<T>
+  key: QueryKey
+}
+
+export type DynamicEnhancedQuery<T, BuilderArgs extends any[]> = {
+  [P in keyof EnhancedQuery<T>]: (...args: BuilderArgs) => EnhancedQuery<T>[P]
+}