@codeleap/query 6.2.3 → 6.8.0

package/dist/types/update.d.ts

@@ -0,0 +1,13 @@
+import { UseMutationOptions } from '@tanstack/react-query';
+import { QueryItem } from './core';
+/** Rollback context captured before an optimistic update is applied. Both fields are `undefined` when the item was not in cache at mutation time. */
+export type UpdateMutationCtx<T> = {
+    previousItem: T | undefined;
+    optimisticItem: T | undefined;
+};
+/** Options forwarded to React Query's `useMutation` for an update operation. `mutationKey` and `mutationFn` are managed internally. */
+export type UpdateMutationOptions<T extends QueryItem, F> = Omit<UseMutationOptions<T, Error, Partial<T>, UpdateMutationCtx<T>>, 'mutationKey' | 'mutationFn'> & {
+    /** Apply the updated fields to the cache immediately and revert to `previousItem` on error. */
+    optimistic?: boolean;
+};
+//# sourceMappingURL=update.d.ts.map

package/dist/types/update.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update.d.ts","sourceRoot":"","sources":["../../src/types/update.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAA;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAA;AAElC,qJAAqJ;AACrJ,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI;IACjC,YAAY,EAAE,CAAC,GAAG,SAAS,CAAA;IAC3B,cAAc,EAAE,CAAC,GAAG,SAAS,CAAA;CAC9B,CAAA;AAED,uIAAuI;AACvI,MAAM,MAAM,qBAAqB,CAAC,CAAC,SAAS,SAAS,EAAE,CAAC,IAAI,IAAI,CAC9D,kBAAkB,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAAC,EAC9D,aAAa,GAAG,YAAY,CAC7B,GAAG;IACF,+FAA+F;IAC/F,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB,CAAA"}

package/dist/types/utility.d.ts

@@ -0,0 +1,23 @@
+import { QueryItem } from './core';
+import { QueryKey, useQueryClient } from '@tanstack/react-query';
+/** Alias for the React Query client instance type — avoids importing `useQueryClient` at every call site. */
+export type QueryClient = ReturnType<typeof useQueryClient>;
+/** An entity that may carry a client-generated `tempId` while an optimistic create is in-flight. */
+export type WithTempId<T extends QueryItem> = T & {
+    tempId?: QueryItem['id'];
+};
+/** Exact location of an item inside the paginated cache: which page it lives on and its index within that page. */
+export type ItemPosition = {
+    pageIndex: number;
+    itemIndex: number;
+};
+/** Sparse map of every cached list that contained a deleted item, together with the position it occupied. Used to re-insert the item on rollback. */
+export type RemovedItemMap = [QueryKey, ItemPosition][];
+/** Standard DRF-style paginated envelope. Wrap your API response in this type when the backend uses `count / next / previous / results`. */
+export type PaginationResponse<T extends QueryItem> = {
+    count: number;
+    next: string;
+    previous: string;
+    results: T[];
+};
+//# sourceMappingURL=utility.d.ts.map

package/dist/types/utility.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utility.d.ts","sourceRoot":"","sources":["../../src/types/utility.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AACnC,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAEhE,6GAA6G;AAC7G,MAAM,MAAM,WAAW,GAAG,UAAU,CAAC,OAAO,cAAc,CAAC,CAAA;AAE3D,oGAAoG;AACpG,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,SAAS,IAAI,CAAC,GAAG;IAChD,MAAM,CAAC,EAAE,SAAS,CAAC,IAAI,CAAC,CAAA;CACzB,CAAA;AAED,mHAAmH;AACnH,MAAM,MAAM,YAAY,GAAG;IACzB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;CAClB,CAAA;AAED,qJAAqJ;AACrJ,MAAM,MAAM,cAAc,GAAG,CAAC,QAAQ,EAAE,YAAY,CAAC,EAAE,CAAA;AAEvD,4IAA4I;AAC5I,MAAM,MAAM,kBAAkB,CAAC,CAAC,SAAS,SAAS,IAAI;IACpD,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,CAAC,EAAE,CAAA;CACb,CAAA"}

package/dist/utils/index.d.ts

@@ -0,0 +1,2 @@
+export * from './misc';
+//# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAA"}

package/dist/utils/misc.d.ts

@@ -0,0 +1,5 @@
+/** Prefix used on every optimistically-created item id. Check `id.startsWith(tempIdPrefix)` to distinguish placeholder items from server-assigned ids. */
+export declare const tempIdPrefix = "temp-id";
+/** Returns a unique placeholder id for optimistic creates. The format is `temp-id-<uuidv4>` and is guaranteed never to collide with server-assigned ids. */
+export declare const generateTempId: () => string;
+//# sourceMappingURL=misc.d.ts.map

package/dist/utils/misc.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"misc.d.ts","sourceRoot":"","sources":["../../src/utils/misc.ts"],"names":[],"mappings":"AAsCA,0JAA0J;AAC1J,eAAO,MAAM,YAAY,YAAY,CAAA;AAErC,4JAA4J;AAC5J,eAAO,MAAM,cAAc,cAE1B,CAAA"}

package/package.json

@@ -1,7 +1,20 @@
 {
   "name": "@codeleap/query",
-  "version": "6.2.3",
+  "version": "6.8.0",
   "main": "src/index.ts",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
   "license": "UNLICENSED",
   "repository": {
     "url": "https://github.com/codeleap-uk/internal-libs-monorepo.git",
@@ -9,19 +22,21 @@
     "directory": "packages/query"
   },
   "devDependencies": {
-    "@codeleap/config": "6.2.3",
-    "@codeleap/types": "6.2.3",
+    "@codeleap/config": "6.8.0",
+    "@codeleap/types": "6.8.0",
+    "@codeleap/utils": "6.8.0",
     "ts-node-dev": "1.1.8"
   },
   "scripts": {
-    "build": "echo 'No build needed'"
+    "build": "tsc --build tsconfig.build.json",
+    "typecheck": "bun tsc --noEmit -p ./tsconfig.json"
   },
   "peerDependencies": {
-    "@codeleap/types": "6.2.3",
-    "typescript": "5.5.2",
-    "@tanstack/react-query": "5.89.0"
+    "@codeleap/types": "6.8.0",
+    "typescript": "6.0.3",
+    "@tanstack/react-query": "5.100.9"
   },
   "dependencies": {
     "fast-deep-equal": "3.1.3"
   }
-}
+}

package/src/lib/Mutations.ts

@@ -1,4 +1,4 @@
-import { InfiniteData } from '@tanstack/query-core'
+import { InfiniteData, Query, QueryKey } from '@tanstack/query-core'
 import { QueryKeys } from './QueryKeys'
 import { ItemPosition, ListPaginationResponse, PageParam, QueryClient, QueryItem, RemovedItemMap, WithTempId } from '../types'
 import deepEqual from 'fast-deep-equal'
@@ -40,6 +40,30 @@ export class Mutations<T extends QueryItem, F> {
    * mutations.addItem(newUser, removedItemMap)
    * ```
    */
+  private _addItemAtKey(newItem: T, position: 'start' | 'end', queryKey: QueryKey): void {
+    const currentData = this.queryClient.getQueryData<InfiniteData<ListPaginationResponse<T>, PageParam>>(queryKey)
+
+    if (!currentData) {
+      this.queryClient.setQueryData(queryKey, { pageParams: [0], pages: [[newItem]] })
+      return
+    }
+
+    const updatedPages = [...currentData.pages]
+
+    if (position === 'start') {
+      updatedPages.length > 0
+        ? updatedPages[0] = [newItem, ...updatedPages[0]]
+        : updatedPages.push([newItem])
+    } else {
+      const last = updatedPages.length - 1
+      updatedPages.length > 0
+        ? updatedPages[last] = [...updatedPages[last], newItem]
+        : updatedPages.push([newItem])
+    }
+
+    this.queryClient.setQueryData(queryKey, { ...currentData, pages: updatedPages })
+  }
+
   addItem(newItem: T, position: 'start' | 'end' | RemovedItemMap = 'start', listFilters?: F) {
     const isMultiQueryKeys = Array.isArray(position) && position?.length >= 1
 
@@ -64,55 +88,17 @@ export class Mutations<T extends QueryItem, F> {
           }
         }
 
-        const newData = {
-          ...currentData,
-          pages: updatedPages
-        }
-
-        this.queryClient.setQueryData(queryKey, newData)
+        this.queryClient.setQueryData(queryKey, { ...currentData, pages: updatedPages })
       }
 
       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._addItemAtKey(newItem, position as 'start' | 'end', this.queryKeys.listKeyWithFilters(listFilters))
+  }
 
-    this.queryClient.setQueryData(queryKey, newData)
+  addItemToQuery(newItem: T, position: 'start' | 'end' = 'start', query: Query): void {
+    this._addItemAtKey(newItem, position, query.queryKey)
   }
 
   /**

package/src/lib/QueryClientEnhanced/index.ts

@@ -2,9 +2,17 @@ import { waitFor } from '@codeleap/utils'
 import { QueryClient, QueryKey, Query, hashKey, QueryCacheNotifyEvent, matchQuery, QueryOptions } from '@tanstack/react-query'
 import { DynamicEnhancedQuery, EnhancedQuery, PollQueryOptions, PollingResult, QueryKeyBuilder } from './types'
 
+/**
+ * Thin wrapper around React Query's `QueryClient` that adds async primitives for polling, event listening, and proxy-based query handles.
+ * Pass an instance of this class wherever `QueryClient | QueryClientEnhanced` is accepted to unlock the enhanced API.
+ */
 export class QueryClientEnhanced {
   constructor(public client: QueryClient) { }
 
+  /**
+   * Subscribes to cache events for a single query key.
+   * Returns the unsubscribe function, or `undefined` when the query is not yet in the cache.
+   */
   listenToQuery(key: QueryKey, callback: (e: QueryCacheNotifyEvent) => void) {
     const cache = this.client.getQueryCache()
 
@@ -26,6 +34,10 @@ export class QueryClientEnhanced {
     return removeListener
   }
 
+  /**
+   * Repeatedly refetches a query on a fixed `interval` until the `callback` returns `{ stop: true }`.
+   * Rejects immediately if the query key is not present in the cache when called.
+   */
   async pollQuery<T, R>(
     key: QueryKey,
     options: PollQueryOptions<T, R>,
@@ -42,7 +54,7 @@ export class QueryClientEnhanced {
     let count = 0
     let result: PollingResult<R> = {
       stop: false,
-      data: initialData,
+      data: initialData as R,
     }
 
     while (!result?.stop) {
@@ -68,6 +80,10 @@ export class QueryClientEnhanced {
     return result?.data
   }
 
+  /**
+   * Returns an `EnhancedQuery<T>` Proxy for `key`.
+   * `getData` and `setData` work even when the query is not yet in the cache; all other members log a warning and return `undefined` when the query is absent.
+   */
   queryProxy<T>(key: QueryKey) {
     const getClient = () => this
 
@@ -116,11 +132,11 @@ export class QueryClientEnhanced {
             }
 
           case 'ensureData':
-            return (options) => {
+            return (options: Partial<Parameters<typeof client.client.ensureQueryData<T>>[0]>) => {
               return client.client.ensureQueryData<T>({
                 queryKey: key,
                 ...options
-              })
+              } as Parameters<typeof client.client.ensureQueryData<T>>[0])
             }
 
           case 'refresh':
@@ -145,6 +161,10 @@ export class QueryClientEnhanced {
     })
   }
 
+  /**
+   * Resolves with the refreshed `Query` object once it reaches a settled `idle` state with a `dataUpdatedAt` or `errorUpdatedAt` timestamp newer than the moment of the call.
+   * Rejects when the query is absent from the cache or when the fetch results in an error.
+   */
   waitForRefresh<T>(key: QueryKey) {
     const initialQuery = this.client.getQueryCache().find({ exact: true, queryKey: key })
 
@@ -175,13 +195,17 @@ export class QueryClientEnhanced {
             reject()
           }
 
-          removeListener()
+          removeListener?.()
         }
       })
     })
 
   }
 
+  /**
+   * Registers a static query key and returns an `EnhancedQuery<Data>` proxy for it.
+   * When `options` are provided they are applied as query defaults and the query is pre-seeded in the cache — useful for initialising queries outside of a React component.
+   */
   queryKey<Data>(k: QueryKey, options?: QueryOptions<Data>) {
     if (options) {
       this.client.setQueryDefaults(k, options)
@@ -201,6 +225,10 @@ export class QueryClientEnhanced {
     return this.queryProxy<Data>(k)
   }
 
+  /**
+   * Returns a `DynamicEnhancedQuery` proxy whose every member is a function that accepts `BuilderArgs` to derive the final key before delegating.
+   * Use this when the query key depends on runtime parameters (e.g. `(id: string) => ['users', id]`).
+   */
   dynamicQueryKey<Data, BuilderArgs extends any[] = any[]>(k: QueryKeyBuilder<BuilderArgs>) {
     const getClient = () => this
 

package/src/lib/QueryClientEnhanced/types.ts

@@ -5,34 +5,59 @@ import {
   EnsureQueryDataOptions,
 } from '@tanstack/react-query'
 
+/** A function that accepts typed arguments and returns the `QueryKey` array for a given query. Used with `dynamicQueryKey` to create parameterised query proxies. */
 export type QueryKeyBuilder<Args extends any[] = any[]> = (...args: Args) => QueryKey
 
+/** Value returned by a `PollingCallback` on each tick. Set `stop: true` to terminate the polling loop. */
 export type PollingResult<T> = {
   stop: boolean
   data: T
 }
 
+/**
+ * Called after each poll tick.
+ * @param query — the refreshed query snapshot
+ * @param count — zero-based tick counter
+ * @param prev  — result data from the previous tick, `undefined` on the first call
+ * Return `{ stop: true, data }` to end polling; `{ stop: false, data }` to continue.
+ */
 export type PollingCallback<T, R> = (query: Query<T>, count: number, prev?: R) => Promise<PollingResult<R>>
 
 export type PollQueryOptions<T, R> = {
+  /** Milliseconds to wait between each refetch. */
   interval: number
   callback: PollingCallback<T, R>
+  /** When `true`, fires the first refetch immediately instead of waiting one `interval`. Defaults to `false`. */
   leading?: boolean
+  /** Seed value passed as `prev` to the callback on the very first tick. */
   initialData?: R
 }
 
+/**
+ * A Proxy-based handle to a specific query inside `QueryClientEnhanced`.
+ * Extends the raw React Query `Query` object with ergonomic async helpers.
+ * Obtain via `queryKey()` or `queryProxy()` — do not instantiate directly.
+ */
 export interface EnhancedQuery<T> extends Query<T> {
+  /** Resolves once the query transitions to a settled `idle` state newer than when the call was made. Rejects if the query errors. */
   waitForRefresh(): Promise<Query<T>>
+  /** Subscribe to every cache notification for this query. Returns the unsubscribe function. */
   listen(callback: (e: QueryCacheNotifyEvent) => void): () => void
+  /** Triggers a refetch and resolves with the fresh data once settled. */
   refresh(): Promise<T>
   poll<R>(
     options: PollQueryOptions<T, R>
   ): Promise<R>
+  /** Synchronous cache read — returns `undefined` when the query has never been fetched. */
   getData(): T
   ensureData(options?: Partial<EnsureQueryDataOptions<T, Error, T, QueryKey, never>>): Promise<T>
   key: QueryKey
 }
 
+/**
+ * Parameterised variant of `EnhancedQuery` produced by `dynamicQueryKey`.
+ * Every method accepts `BuilderArgs` to resolve the key before delegating to the underlying `EnhancedQuery`.
+ */
 export type DynamicEnhancedQuery<T, BuilderArgs extends any[]> = {
   [P in keyof EnhancedQuery<T>]: (...args: BuilderArgs) => EnhancedQuery<T>[P]
 }

package/src/lib/QueryKeys.ts

@@ -43,14 +43,16 @@ export class QueryKeys<T extends QueryItem, F> {
    * @returns Query key array with or without filters
    */
   listKeyWithFilters(filters?: F): QueryKey {
-    const hasValidFilters = filters != null && (
+    const hasValidFilters = !TypeGuards.isNil(filters) && (
       typeof filters !== 'object'
         ? Boolean(filters)
-        : Object.values(filters).some(value =>
+        : Object.values(filters ?? {}).some(value =>
           value != null && (typeof value !== 'string' || value.trim() !== '')
         )
     )
 
+ 
+
     return hasValidFilters ? [...this.keys.list, filters] : this.keys.list
   }
 

package/src/lib/QueryManager.ts

@@ -1,10 +1,11 @@
-import { FetchInfiniteQueryOptions, FetchQueryOptions, InfiniteData, MutationFunctionContext, QueryKey, useInfiniteQuery, useMutation, useQuery } from '@tanstack/react-query'
+import { FetchInfiniteQueryOptions, FetchQueryOptions, InfiniteData, MutationFunctionContext, QueryClient, QueryKey, useInfiniteQuery, useMutation, useQuery } from '@tanstack/react-query'
 import { useCallback } from 'react'
 import { createQueryKeys, QueryKeys } from './QueryKeys'
 import { createMutations, Mutations } from './Mutations'
 import { CreateMutationCtx, CreateMutationOptions, ListPaginationResponse, ListQueryOptions, PageParam, QueryItem, QueryManagerOptions, RetrieveQueryOptions, UpdateMutationCtx, UpdateMutationOptions, DeleteMutationCtx, DeleteMutationOptions } from '../types'
 import { generateTempId } from '../utils'
 import { TypeGuards } from '@codeleap/types'
+import { QueryClientEnhanced } from './QueryClientEnhanced'
 
 /**
  * Comprehensive query manager class that provides hooks and utilities for managing CRUD operations with React Query
@@ -19,13 +20,15 @@ import { TypeGuards } from '@codeleap/types'
  * - Built-in error handling and rollback mechanisms
  */
 export class QueryManager<T extends QueryItem, F> {
+  queryClient: QueryClient
   /**
    * Creates a new QueryManager instance
    * @param options - Configuration options for the query manager
    */
   constructor(private options: QueryManagerOptions<T, F>) {
-    this.queryKeys = createQueryKeys<T, F>(options.name, options.queryClient)
-    this.mutations = createMutations<T, F>(this.queryKeys, options.queryClient, options.name)
+    this.queryClient = options.queryClient instanceof QueryClientEnhanced ? options.queryClient.client : options.queryClient
+    this.queryKeys = createQueryKeys<T, F>(options.name, this.queryClient)
+    this.mutations = createMutations<T, F>(this.queryKeys, this.queryClient, options.name)
   }
 
   /**
@@ -96,7 +99,7 @@ export class QueryManager<T extends QueryItem, F> {
       queryFn: async (query) => {
         const listOffset = query?.pageParam ?? 0
 
-        const data = await this.options?.listFn?.(listLimit, listOffset, filters)
+        const data = await this.options?.listFn?.(listLimit, listOffset, filters as F)
 
         return TypeGuards.isArray(data) ? data : [] as ListPaginationResponse<T>
       },
@@ -185,7 +188,7 @@ export class QueryManager<T extends QueryItem, F> {
       queryKey,
 
       queryFn: () => {
-        return this.options.retrieveFn(id)
+        return this.options.retrieveFn!(id)
       },
 
       select: (data) => {
@@ -234,7 +237,7 @@ export class QueryManager<T extends QueryItem, F> {
       ...mutationOptions
     } = options
 
-    const onMutate = useCallback(async (data: Partial<T>, context: MutationFunctionContext) => {
+    const onMutate = useCallback(async (data: Partial<T>, context: MutationFunctionContext): Promise<CreateMutationCtx | undefined> => {
       if (providedOnMutate) providedOnMutate?.(data, context)
 
       if (optimistic) {
@@ -252,16 +255,16 @@ export class QueryManager<T extends QueryItem, F> {
       }
     }, [providedOnMutate, optimistic, listFilters])
 
-    const onError = useCallback((error: Error, variables: Partial<T>, onMutateResult: CreateMutationCtx, context: MutationFunctionContext) => {
-      if (providedOnError) providedOnError?.(error, variables, onMutateResult, context)
+    const onError = useCallback((error: Error, variables: Partial<T>, onMutateResult: CreateMutationCtx | undefined, context: MutationFunctionContext) => {
+      if (providedOnError && onMutateResult) providedOnError?.(error, variables, onMutateResult, context)
 
       if (!TypeGuards.isNil(onMutateResult?.tempId)) {
         this.mutations.removeItem(onMutateResult?.tempId)
       }
     }, [providedOnError])
 
-    const onSuccess = useCallback((data: T, variables: Partial<T>, onMutateResult: CreateMutationCtx, context: MutationFunctionContext) => {
-      if (providedOnSuccess) providedOnSuccess?.(data, variables, onMutateResult, context)
+    const onSuccess = useCallback((data: T, variables: Partial<T>, onMutateResult: CreateMutationCtx | undefined, context: MutationFunctionContext) => {
+      if (providedOnSuccess) providedOnSuccess?.(data, variables, onMutateResult , context)
 
       if (TypeGuards.isNil(onMutateResult?.tempId)) {
         this.mutations.addItem(data, appendTo, listFilters)
@@ -270,13 +273,13 @@ export class QueryManager<T extends QueryItem, F> {
       }
     }, [providedOnSuccess, listFilters])
 
-    const mutation = useMutation<T, Error, Partial<T>, CreateMutationCtx>({
+    const mutation = useMutation<T, Error, Partial<T>, CreateMutationCtx | undefined>({
       ...mutationOptions,
 
       mutationKey: this.queryKeys.keys.create,
 
       mutationFn: (data: Partial<T>) => {
-        return this.options.createFn(data)
+        return this.options.createFn!(data)
       },
 
       onMutate,
@@ -320,11 +323,12 @@ export class QueryManager<T extends QueryItem, F> {
       ...mutationOptions
     } = options
 
-    const onMutate = useCallback(async (data: Partial<T>, context: MutationFunctionContext) => {
+    const onMutate = useCallback(async (data: Partial<T>, context: MutationFunctionContext): Promise<UpdateMutationCtx<T> | undefined> => {
       if (providedOnMutate) providedOnMutate?.(data, context)
 
       if (optimistic) {
-        const previousItem = this.queryKeys.getRetrieveData(data?.id)
+        if (data?.id == null) return
+        const previousItem = this.queryKeys.getRetrieveData(data.id)
 
         if (!previousItem) return
 
@@ -342,27 +346,27 @@ export class QueryManager<T extends QueryItem, F> {
       }
     }, [providedOnMutate, optimistic])
 
-    const onError = useCallback((error: Error, variables: Partial<T>, onMutateResult: UpdateMutationCtx<T>, context: MutationFunctionContext) => {
-      if (providedOnError) providedOnError?.(error, variables, onMutateResult, context)
+    const onError = useCallback((error: Error, variables: Partial<T>, onMutateResult: UpdateMutationCtx<T> | undefined, context: MutationFunctionContext) => {
+      if (providedOnError && onMutateResult) providedOnError?.(error, variables, onMutateResult, context)
 
       if (!TypeGuards.isNil(onMutateResult?.previousItem?.id)) {
         this.mutations.updateItems(onMutateResult?.previousItem)
       }
     }, [providedOnError])
 
-    const onSuccess = useCallback((data: T, variables: Partial<T>, onMutateResult: UpdateMutationCtx<T>, context: MutationFunctionContext) => {
-      if (providedOnSuccess) providedOnSuccess?.(data, variables, onMutateResult, context)
+    const onSuccess = useCallback((data: T, variables: Partial<T>, onMutateResult: UpdateMutationCtx<T> | undefined, context: MutationFunctionContext) => {
+      if (providedOnSuccess && onMutateResult) providedOnSuccess?.(data, variables, onMutateResult, context)
 
       this.mutations.updateItems(data)
     }, [providedOnSuccess])
 
-    const mutation = useMutation<T, Error, Partial<T>, UpdateMutationCtx<T>>({
+    const mutation = useMutation<T, Error, Partial<T>, UpdateMutationCtx<T> | undefined>({
       ...mutationOptions,
 
       mutationKey: this.queryKeys.keys.update,
 
       mutationFn: (data: Partial<T>) => {
-        return this.options.updateFn(data)
+        return this.options.updateFn!(data)
       },
 
       onMutate,
@@ -407,7 +411,7 @@ export class QueryManager<T extends QueryItem, F> {
       ...mutationOptions
     } = options
 
-    const onMutate = useCallback(async (id: T['id'], context: MutationFunctionContext) => {
+    const onMutate = useCallback(async (id: T['id'], context: MutationFunctionContext): Promise<DeleteMutationCtx<T> | undefined> => {
       if (providedOnMutate) providedOnMutate?.(id, context)
 
       if (optimistic) {
@@ -424,32 +428,32 @@ export class QueryManager<T extends QueryItem, F> {
       }
     }, [providedOnMutate, optimistic])
 
-    const onError = useCallback((error: Error, variables: T['id'], onMutateResult: DeleteMutationCtx<T>, context: MutationFunctionContext) => {
-      if (providedOnError) providedOnError?.(error, variables, onMutateResult, context)
+    const onError = useCallback((error: Error, variables: T['id'], onMutateResult: DeleteMutationCtx<T> | undefined, context: MutationFunctionContext) => {
+      if (providedOnError && onMutateResult) providedOnError?.(error, variables, onMutateResult, context)
 
       if (!TypeGuards.isNil(onMutateResult?.previousItem?.id)) {
         this.mutations.addItem(
           onMutateResult?.previousItem,
-          onMutateResult?.removedAt,
+          onMutateResult?.removedAt ?? undefined,
         )
       }
     }, [providedOnError])
 
-    const onSuccess = useCallback((data: T['id'], variables: T['id'], onMutateResult: DeleteMutationCtx<T>, context: MutationFunctionContext) => {
-      if (providedOnSuccess) providedOnSuccess?.(data, variables, onMutateResult, context)
+    const onSuccess = useCallback((data: unknown, variables: T['id'], onMutateResult: DeleteMutationCtx<T> | undefined, context: MutationFunctionContext) => {
+      if (providedOnSuccess && onMutateResult) providedOnSuccess?.(data as T['id'], variables, onMutateResult, context)
 
       if (TypeGuards.isNil(onMutateResult?.previousItem?.id)) {
-        this.mutations.removeItem(data)
+        this.mutations.removeItem(data as T['id'])
       }
     }, [providedOnSuccess])
 
-    const mutation = useMutation<unknown, Error, T['id'], DeleteMutationCtx<T>>({
+    const mutation = useMutation<unknown, Error, T['id'], DeleteMutationCtx<T> | undefined>({
       ...mutationOptions,
 
       mutationKey: this.queryKeys.keys.delete,
 
       mutationFn: async (id: QueryItem['id']) => {
-        return this.options.deleteFn(id)
+        return this.options.deleteFn!(id)
       },
 
       onMutate,
@@ -481,10 +485,10 @@ export class QueryManager<T extends QueryItem, F> {
    * ```
    */
   prefetchRetrieve(id: T['id'], options: Omit<FetchQueryOptions<T, Error, T, QueryKey, never>, 'queryKey' | 'queryFn'> = {}) {
-    return this.options.queryClient.prefetchQuery({
+    return this.queryClient.prefetchQuery({
       ...options,
       queryKey: this.queryKeys.keys.retrieve(id),
-      queryFn: () => this.options.retrieveFn(id),
+      queryFn: () => this.options.retrieveFn!(id),
     })
   }
 
@@ -515,11 +519,11 @@ export class QueryManager<T extends QueryItem, F> {
   ) {
     const { initialOffset = 0, ...prefetchOptions } = options
 
-    return this.options.queryClient.prefetchInfiniteQuery({
+    return this.queryClient.prefetchInfiniteQuery({
       ...prefetchOptions as any,
       initialPageParam: initialOffset,
       queryKey: this.queryKeys.listKeyWithFilters(filters),
-      queryFn: () => this.options.listFn(this.options.listLimit ?? 10, initialOffset, filters),
+      queryFn: () => this.options.listFn!(this.options.listLimit ?? 10, initialOffset, filters as F),
     })
   }
 }

package/src/lib/QueryOperations/index.ts

@@ -1,5 +1,6 @@
 import { useMutation, useQuery, UseQueryOptions, UseMutationOptions, QueryKey, FetchQueryOptions } from '@tanstack/react-query'
 import { QueryOperationsOptions, MutationFn, QueryFn, InferMutationParams, InferMutationReturn, InferQueryParams, InferQueryReturn } from './types'
+import { QueryClientEnhanced } from '../QueryClientEnhanced'
 
 /**
  * Builder class for creating type-safe query and mutation operations
@@ -41,6 +42,13 @@ export class QueryOperations<
     return this._mutations
   }
 
+  get queryClient(){
+    if(this._options.queryClient instanceof QueryClientEnhanced) {
+      return this._options.queryClient.client
+    }
+    return this._options.queryClient
+  }
+
   /**
    * Gets all registered query functions
    * @returns Readonly record of query functions
@@ -297,7 +305,7 @@ export class QueryOperations<
 
     const queryFn = this._queries[queryKey] as QueryFn
 
-    return this._options.queryClient.prefetchQuery<InferQueryReturn<TQueries[K]>, Error, T, QueryKey>({
+    return this.queryClient.prefetchQuery<InferQueryReturn<TQueries[K]>, Error, T, QueryKey>({
       queryKey: prefetchQueryKey,
       queryFn: queryFn,
       ...options,
@@ -340,12 +348,12 @@ export class QueryOperations<
   ) {
     const prefetchQueryKey = this.getQueryKey(queryKey, params)
 
-    const cachedData = this._options.queryClient.getQueryData<T, QueryKey>(prefetchQueryKey)
+    const cachedData = this.queryClient.getQueryData<T, QueryKey>(prefetchQueryKey)
 
     if (!cachedData) {
       await this.prefetchQuery(queryKey, params, options)
     }
 
-    return this._options.queryClient.getQueryData<T, QueryKey>(prefetchQueryKey)
+    return this.queryClient.getQueryData<T, QueryKey>(prefetchQueryKey)
   }
 }