tanstack-cacher 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,518 @@
+# React Query Cache Manager
+
+[![npm version](https://img.shields.io/npm/v/tanstack-cacher.svg)](https://www.npmjs.com/package/tanstack-cacher)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+
+## Introduction
+
+A robust, TypeScript-first cache manager for React Query that works with **ANY response structure**. Using simple path-based configuration, it handles simple arrays, deeply nested data, paginated responses, and any custom format you throw at it.
+
+**Key Features:**
+- Path-based configuration (e.g., `itemsPath: "data.content"`)
+- Automatic handling of missing data and nested structures
+- Built-in pagination metadata management
+- Works with any response shape
+- Full TypeScript support with type inference
+- Zero dependencies (except React Query)
+
+## Installation
+
+```bash
+npm install @your-scope/tanstack-cacher
+# or
+yarn add @your-scope/tanstack-cacher
+# or
+pnpm add @your-scope/tanstack-cacher
+```
+
+## Quick Start
+
+### 1. Simple Array Response
+
+```typescript
+import { QueryCacheManager } from '@your-scope/tanstack-cacher';
+import { useQueryClient, useMutation } from '@tanstack/react-query';
+
+interface Todo {
+  id: string;
+  title: string;
+}
+
+// API returns: Todo[]
+function TodoList() {
+  const queryClient = useQueryClient();
+
+  const cache = new QueryCacheManager<Todo[], Todo>({
+    queryClient,
+    queryKey: ['todos'],
+    itemsPath: '', // Empty string = data IS the array
+  });
+
+  const createMutation = useMutation({
+    mutationFn: createTodo,
+    onMutate: (newTodo) => cache.add(newTodo),
+    onError: () => cache.invalidate(),
+  });
+
+  const updateMutation = useMutation({
+    mutationFn: updateTodo,
+    onMutate: (todo) => cache.update(todo),
+    onError: () => cache.invalidate(),
+  });
+
+  const deleteMutation = useMutation({
+    mutationFn: deleteTodo,
+    onMutate: (id) => cache.delete(id),
+    onError: () => cache.invalidate(),
+  });
+}
+```
+
+### 2. Nested Response
+
+```typescript
+interface ApiResponse {
+  success: true;
+  data: {
+    items: User[];
+  };
+}
+
+const cache = new QueryCacheManager<ApiResponse, User>({
+  queryClient,
+  queryKey: ['users'],
+  itemsPath: 'data.items', // Path to the array
+});
+```
+
+### 3. Paginated Response (Automatic Metadata Updates!)
+
+```typescript
+interface PaginatedResponse {
+  content: User[];
+  page: {
+    number: number;
+    size: number;
+    totalElements: number;
+    totalPages: number;
+  };
+}
+
+const cache = new QueryCacheManager<PaginatedResponse, User>({
+  queryClient,
+  queryKey: ['users', { page: 0 }],
+  itemsPath: 'content', // Path to items
+  pagination: {
+    totalElementsPath: 'page.totalElements', // Auto-updates on add/delete
+    totalPagesPath: 'page.totalPages', // Auto-recalculated on add/delete
+    currentPagePath: 'page.number',
+    pageSizePath: 'page.size', // Required for totalPages calculation
+  },
+});
+
+// Now when you add/delete, totalElements AND totalPages update automatically!
+cache.add(newUser); // totalElements++, totalPages recalculated
+cache.delete(userId); // totalElements--, totalPages recalculated
+```
+
+### 4. Different Pagination Format
+
+```typescript
+interface Response {
+  items: Product[];
+  meta: {
+    total: number;
+    currentPage: number;
+    totalPages: number;
+  };
+}
+
+const cache = new QueryCacheManager<Response, Product>({
+  queryClient,
+  queryKey: ['products'],
+  itemsPath: 'items',
+  pagination: {
+    totalElementsPath: 'meta.total',
+    totalPagesPath: 'meta.totalPages',
+    currentPagePath: 'meta.currentPage',
+    pageSizePath: 'meta.pageSize', // For auto totalPages calculation
+  },
+});
+```
+
+### 5. Deeply Nested Response
+
+```typescript
+interface ComplexResponse {
+  status: 'ok';
+  result: {
+    data: {
+      users: User[];
+    };
+    metadata: {
+      count: number;
+    };
+  };
+}
+
+const cache = new QueryCacheManager<ComplexResponse, User>({
+  queryClient,
+  queryKey: ['users'],
+  itemsPath: 'result.data.users', // Navigate with dots
+  pagination: {
+    totalElementsPath: 'result.metadata.count',
+  },
+});
+```
+
+## API Reference
+
+### Constructor
+
+```typescript
+new QueryCacheManager<TData, TItem>(config)
+```
+
+**Config Options:**
+
+| Option | Type | Required | Description |
+|--------|------|----------|-------------|
+| `queryClient` | `QueryClient` | Yes | React Query client instance |
+| `queryKey` | `QueryKey` | Yes | Query key for the cache |
+| `itemsPath` | `string` | Yes | Dot-separated path to items array (empty string if data IS array) |
+| `pagination` | `PaginationConfig` | No | Pagination metadata paths |
+| `keyExtractor` | `(item: TItem) => string \| number` | No | Extract unique ID (default: `item.id`) |
+| `initialData` | `TData` | No | Initial structure when cache is empty |
+
+**PaginationConfig:**
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `totalElementsPath` | `string` | Path to total count (auto-updated on add/delete) |
+| `totalPagesPath` | `string` | Path to total pages (auto-recalculated when pageSizePath provided) |
+| `currentPagePath` | `string` | Path to current page number |
+| `pageSizePath` | `string` | Path to page size (required for automatic totalPages recalculation) |
+
+### Methods
+
+#### `add(newItem, position?)`
+Add new item to cache
+```typescript
+cache.add({ id: '1', name: 'John' }); // Adds at start (default)
+cache.add({ id: '2', name: 'Jane' }, 'end'); // Adds at end
+```
+
+#### `update(updatedItem, matcher?)`
+Update existing item
+```typescript
+// Update by ID (default)
+cache.update({ id: '1', name: 'Johnny' });
+
+// Custom matcher
+cache.update(
+  { status: 'active' },
+  (item) => item.email === 'user@example.com'
+);
+```
+
+#### `delete(itemOrId, matcher?)`
+Remove item from cache
+```typescript
+// Delete by ID
+cache.delete('1');
+
+// Delete by object
+cache.delete({ id: '1', name: 'John' });
+
+// Custom matcher
+cache.delete(null, (item) => item.isDeleted);
+```
+
+#### `replace(newData)`
+Replace entire cache data
+```typescript
+cache.replace(newFullData);
+```
+
+#### `clear()`
+Clear all items (resets array to empty, updates pagination to 0)
+```typescript
+cache.clear();
+```
+
+#### `getItemsFromCache()`
+Get current items array
+```typescript
+const items = cache.getItemsFromCache(); // returns TItem[]
+```
+
+#### `getDataFromCache()`
+Get full cache data
+```typescript
+const fullData = cache.getDataFromCache(); // returns TData | undefined
+```
+
+#### `invalidate()`
+Trigger refetch from server
+```typescript
+cache.invalidate();
+```
+
+#### `createHandlers()`
+Get handlers for mutation callbacks
+```typescript
+const handlers = cache.createHandlers();
+
+useMutation({
+  mutationFn: createUser,
+  onMutate: handlers.onAdd,
+  onError: () => cache.invalidate(),
+});
+```
+
+## Real-World Example
+
+```typescript
+import { useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
+import { QueryCacheManager } from '@your-scope/tanstack-cacher';
+
+interface Todo {
+  id: string;
+  title: string;
+  completed: boolean;
+}
+
+function TodoApp() {
+  const queryClient = useQueryClient();
+
+  // Setup cache manager
+  const todoCache = new QueryCacheManager<Todo[], Todo>({
+    queryClient,
+    queryKey: ['todos'],
+    itemsPath: '', // Data IS the array
+  });
+
+  // Fetch todos
+  const { data: todos } = useQuery({
+    queryKey: ['todos'],
+    queryFn: () => fetch('/api/todos').then(r => r.json()),
+  });
+
+  // Mutations with optimistic updates
+  const createMutation = useMutation({
+    mutationFn: async (title: string) => {
+      const res = await fetch('/api/todos', {
+        method: 'POST',
+        body: JSON.stringify({ title }),
+      });
+      return res.json();
+    },
+    onMutate: (title) => {
+      // Optimistically add with temp ID
+      todoCache.add({
+        id: `temp-${Date.now()}`,
+        title,
+        completed: false,
+      });
+    },
+    onError: () => todoCache.invalidate(),
+  });
+
+  const toggleMutation = useMutation({
+    mutationFn: async (todo: Todo) => {
+      const res = await fetch(`/api/todos/${todo.id}`, {
+        method: 'PUT',
+        body: JSON.stringify({ ...todo, completed: !todo.completed }),
+      });
+      return res.json();
+    },
+    onMutate: (todo) => {
+      // Optimistically update
+      todoCache.update({ id: todo.id, completed: !todo.completed });
+    },
+    onError: () => todoCache.invalidate(),
+  });
+
+  const deleteMutation = useMutation({
+    mutationFn: (id: string) => fetch(`/api/todos/${id}`, { method: 'DELETE' }),
+    onMutate: (id) => {
+      // Optimistically remove
+      todoCache.delete(id);
+    },
+    onError: () => todoCache.invalidate(),
+  });
+
+  return (
+    <div>
+      <input
+        onKeyDown={(e) => {
+          if (e.key === 'Enter') {
+            createMutation.mutate(e.currentTarget.value);
+            e.currentTarget.value = '';
+          }
+        }}
+        placeholder="Add todo..."
+      />
+      <ul>
+        {todos?.map((todo) => (
+          <li key={todo.id}>
+            <input
+              type="checkbox"
+              checked={todo.completed}
+              onChange={() => toggleMutation.mutate(todo)}
+            />
+            <span>{todo.title}</span>
+            <button onClick={() => deleteMutation.mutate(todo.id)}>
+              Delete
+            </button>
+          </li>
+        ))}
+      </ul>
+    </div>
+  );
+}
+```
+
+## Next.js Usage
+
+Works seamlessly with Next.js App Router:
+
+```typescript
+// app/users/page.tsx
+'use client';
+
+import { QueryCacheManager } from '@your-scope/tanstack-cacher';
+
+export default function UsersPage() {
+  const queryClient = useQueryClient();
+
+  const cache = new QueryCacheManager({
+    queryClient,
+    queryKey: ['users'],
+    itemsPath: 'data.users',
+  });
+
+  // ... rest of component
+}
+```
+
+## Advanced Examples
+
+### Handling Missing Data
+
+The manager automatically creates the structure if data is missing:
+
+```typescript
+const cache = new QueryCacheManager<ApiResponse, User>({
+  queryClient,
+  queryKey: ['users'],
+  itemsPath: 'data.content',
+  // If cache is empty, this structure is created:
+  initialData: {
+    data: {
+      content: [],
+    },
+    page: {
+      totalElements: 0,
+      totalPages: 0,
+    },
+  },
+});
+
+// Even if cache is empty, this works fine!
+cache.add(newUser); // Creates structure + adds item
+```
+
+### Custom Key Extractor
+
+```typescript
+interface User {
+  userId: string; // Not "id"
+  name: string;
+}
+
+const cache = new QueryCacheManager<User[], User>({
+  queryClient,
+  queryKey: ['users'],
+  itemsPath: '',
+  keyExtractor: (user) => user.userId, // Custom ID field
+});
+```
+
+### Multiple Cache Managers
+
+```typescript
+function App() {
+  const queryClient = useQueryClient();
+
+  // One manager per query
+  const usersCache = new QueryCacheManager({
+    queryClient,
+    queryKey: ['users'],
+    itemsPath: 'data.users',
+  });
+
+  const postsCache = new QueryCacheManager({
+    queryClient,
+    queryKey: ['posts'],
+    itemsPath: 'posts',
+  });
+
+  // Use independently
+  usersCache.add(newUser);
+  postsCache.add(newPost);
+}
+```
+
+## Best Practices
+
+1. **Always handle errors** - Call `invalidate()` on mutation errors to refetch from server
+2. **Use temporary IDs** - For optimistic creates, use `temp-${Date.now()}` or similar
+3. **One manager per query** - Create separate instances for different queries
+4. **Specify paths clearly** - Use dot notation for nested paths: `"data.result.items"`
+5. **Type everything** - Provide TypeScript types for full type safety
+
+## Why This Package?
+
+Traditional cache managers assume your API structure. This package:
+
+- **Works with ANY structure** - Just tell it the path to your data
+- **Handles edge cases** - Missing data, nested objects, pagination metadata
+- **Zero configuration overhead** - No complex setup or boilerplate
+- **Type-safe** - Full TypeScript support with inference
+- **Framework agnostic** - Works anywhere React Query works
+
+## Migration from Old API
+
+If you were using the old `getItems`/`setItems` approach:
+
+```typescript
+// Old way ❌
+const cache = new QueryCacheManager({
+  getItems: (data) => data.content,
+  setItems: (data, items) => ({ ...data, content: items }),
+  onItemsAdd: (data, count) => ({
+    ...data,
+    page: { ...data.page, totalElements: data.page.totalElements + count }
+  }),
+});
+
+// New way ✅
+const cache = new QueryCacheManager({
+  itemsPath: 'content',
+  pagination: {
+    totalElementsPath: 'page.totalElements',
+  },
+});
+```
+
+Much simpler and safer!
+
+## License
+
+MIT
+
+## Contributing
+
+Issues and PRs welcome!

package/dist/index.d.mts

@@ -0,0 +1,43 @@
+import { QueryClient, QueryKey } from '@tanstack/react-query';
+export * from '@tanstack/react-query';
+
+interface PaginationConfig {
+    totalElementsPath?: string;
+    totalPagesPath?: string;
+    currentPagePath?: string;
+    pageSizePath?: string;
+}
+interface CacheConfig<TData, TItem> {
+    queryClient: QueryClient;
+    queryKey: QueryKey;
+    itemsPath: string;
+    pagination?: PaginationConfig;
+    keyExtractor?: (item: TItem) => string | number;
+    initialData?: TData;
+}
+interface CacheHandlers<TItem> {
+    onAdd: (newItem: TItem, position?: 'start' | 'end') => void;
+    onUpdate: (updatedItem: Partial<TItem>, matcher?: (item: TItem) => boolean) => void;
+    onDelete: (itemOrId: TItem | string | number, matcher?: (item: TItem) => boolean) => void;
+}
+type InsertPosition = 'start' | 'end';
+
+declare class QueryCacheManager<TData, TItem> {
+    private config;
+    constructor(config: CacheConfig<TData, TItem>);
+    private getItems;
+    private setItems;
+    private updatePaginationOnAdd;
+    private updatePaginationOnRemove;
+    add(newItem: TItem, position?: InsertPosition): void;
+    update(updatedItem: Partial<TItem>, matcher?: (item: TItem) => boolean): void;
+    delete(itemOrId: TItem | string | number, matcher?: (item: TItem) => boolean): void;
+    replace(newData: TData): void;
+    clear(): void;
+    getItemsFromCache(): TItem[];
+    getDataFromCache(): TData | undefined;
+    invalidate(): void;
+    createHandlers(): CacheHandlers<TItem>;
+}
+
+export { type CacheConfig, type CacheHandlers, type InsertPosition, type PaginationConfig, QueryCacheManager };

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+import { QueryClient, QueryKey } from '@tanstack/react-query';
+export * from '@tanstack/react-query';
+
+interface PaginationConfig {
+    totalElementsPath?: string;
+    totalPagesPath?: string;
+    currentPagePath?: string;
+    pageSizePath?: string;
+}
+interface CacheConfig<TData, TItem> {
+    queryClient: QueryClient;
+    queryKey: QueryKey;
+    itemsPath: string;
+    pagination?: PaginationConfig;
+    keyExtractor?: (item: TItem) => string | number;
+    initialData?: TData;
+}
+interface CacheHandlers<TItem> {
+    onAdd: (newItem: TItem, position?: 'start' | 'end') => void;
+    onUpdate: (updatedItem: Partial<TItem>, matcher?: (item: TItem) => boolean) => void;
+    onDelete: (itemOrId: TItem | string | number, matcher?: (item: TItem) => boolean) => void;
+}
+type InsertPosition = 'start' | 'end';
+
+declare class QueryCacheManager<TData, TItem> {
+    private config;
+    constructor(config: CacheConfig<TData, TItem>);
+    private getItems;
+    private setItems;
+    private updatePaginationOnAdd;
+    private updatePaginationOnRemove;
+    add(newItem: TItem, position?: InsertPosition): void;
+    update(updatedItem: Partial<TItem>, matcher?: (item: TItem) => boolean): void;
+    delete(itemOrId: TItem | string | number, matcher?: (item: TItem) => boolean): void;
+    replace(newData: TData): void;
+    clear(): void;
+    getItemsFromCache(): TItem[];
+    getDataFromCache(): TData | undefined;
+    invalidate(): void;
+    createHandlers(): CacheHandlers<TItem>;
+}
+
+export { type CacheConfig, type CacheHandlers, type InsertPosition, type PaginationConfig, QueryCacheManager };

package/dist/index.js

@@ -0,0 +1,292 @@
+'use strict';
+
+var reactQuery = require('@tanstack/react-query');
+
+// src/index.ts
+
+// src/managers/QueryCacheManager/QueryCache.utils.ts
+function getAtPath(obj, path, defaultValue) {
+  if (!obj || !path) return defaultValue;
+  const keys = path.split(".");
+  let result = obj;
+  for (const key of keys) {
+    if (result === null || result === void 0) {
+      return defaultValue;
+    }
+    result = result[key];
+  }
+  return result !== void 0 ? result : defaultValue;
+}
+function setAtPath(obj, path, value) {
+  if (!path) return obj;
+  const keys = path.split(".");
+  const root = obj ? { ...obj } : {};
+  let current = root;
+  for (let i = 0; i < keys.length - 1; i++) {
+    const key = keys[i];
+    if (!current[key] || typeof current[key] !== "object") {
+      current[key] = {};
+    } else {
+      current[key] = { ...current[key] };
+    }
+    current = current[key];
+  }
+  current[keys[keys.length - 1]] = value;
+  return root;
+}
+function incrementAtPath(obj, path, increment) {
+  const currentValue = getAtPath(obj, path, 0);
+  const newValue = currentValue + increment;
+  return setAtPath(obj, path, newValue);
+}
+
+// src/managers/QueryCacheManager/QueryCache.manager.ts
+var QueryCacheManager = class {
+  constructor(config) {
+    this.config = {
+      ...config,
+      keyExtractor: config.keyExtractor || ((item) => item.id)
+    };
+  }
+  /**
+   * Get items array from data
+   * Returns empty array if path doesn't exist or data is null
+   */
+  getItems(data) {
+    if (!data) return [];
+    if (!this.config.itemsPath) {
+      return Array.isArray(data) ? data : [];
+    }
+    const items = getAtPath(data, this.config.itemsPath, []);
+    return Array.isArray(items) ? items : [];
+  }
+  /**
+   * Set items array in data
+   * Creates nested structure if it doesn't exist
+   */
+  setItems(data, items) {
+    if (!data) {
+      if (this.config.initialData) {
+        data = this.config.initialData;
+      } else {
+        if (!this.config.itemsPath) {
+          return items;
+        }
+        data = {};
+      }
+    }
+    if (!this.config.itemsPath) {
+      return items;
+    }
+    return setAtPath(data, this.config.itemsPath, items);
+  }
+  /**
+   * Update pagination metadata after adding items
+   */
+  updatePaginationOnAdd(data, addedCount) {
+    if (!this.config.pagination) return data;
+    let result = data;
+    if (this.config.pagination.totalElementsPath) {
+      result = incrementAtPath(
+        result,
+        this.config.pagination.totalElementsPath,
+        addedCount
+      );
+    }
+    if (this.config.pagination.totalPagesPath && this.config.pagination.pageSizePath && this.config.pagination.totalElementsPath) {
+      const pageSize = getAtPath(result, this.config.pagination.pageSizePath, 0);
+      const totalElements = getAtPath(
+        result,
+        this.config.pagination.totalElementsPath,
+        0
+      );
+      if (pageSize > 0) {
+        const totalPages = Math.ceil(totalElements / pageSize);
+        result = setAtPath(
+          result,
+          this.config.pagination.totalPagesPath,
+          totalPages
+        );
+      }
+    }
+    return result;
+  }
+  /**
+   * Update pagination metadata after removing items
+   */
+  updatePaginationOnRemove(data, removedCount) {
+    if (!this.config.pagination) return data;
+    let result = data;
+    if (this.config.pagination.totalElementsPath) {
+      result = incrementAtPath(
+        result,
+        this.config.pagination.totalElementsPath,
+        -removedCount
+      );
+    }
+    if (this.config.pagination.totalPagesPath && this.config.pagination.pageSizePath && this.config.pagination.totalElementsPath) {
+      const pageSize = getAtPath(result, this.config.pagination.pageSizePath, 0);
+      const totalElements = getAtPath(
+        result,
+        this.config.pagination.totalElementsPath,
+        0
+      );
+      if (pageSize > 0) {
+        const totalPages = Math.ceil(Math.max(0, totalElements) / pageSize);
+        result = setAtPath(
+          result,
+          this.config.pagination.totalPagesPath,
+          totalPages
+        );
+      }
+    }
+    return result;
+  }
+  /**
+   * Add item to cache
+   *
+   * @param newItem - The item to add
+   * @param position - Where to add: 'start' or 'end'
+   */
+  add(newItem, position = "start") {
+    try {
+      this.config.queryClient.setQueryData(this.config.queryKey, (oldData) => {
+        const items = this.getItems(oldData);
+        const updatedItems = position === "start" ? [newItem, ...items] : [...items, newItem];
+        let result = this.setItems(oldData, updatedItems);
+        result = this.updatePaginationOnAdd(result, 1);
+        return result;
+      });
+    } catch (error) {
+      console.error("[QueryCacheManager] Add failed:", error);
+      this.invalidate();
+    }
+  }
+  /**
+   * Update existing item
+   *
+   * @param updatedItem - Partial item data to update
+   * @param matcher - Optional custom matcher function. Defaults to matching by key
+   */
+  update(updatedItem, matcher) {
+    try {
+      this.config.queryClient.setQueryData(this.config.queryKey, (oldData) => {
+        const items = this.getItems(oldData);
+        const matchFn = matcher || ((item) => this.config.keyExtractor(item) === this.config.keyExtractor(updatedItem));
+        const updatedItems = items.map(
+          (item) => matchFn(item) ? { ...item, ...updatedItem } : item
+        );
+        return this.setItems(oldData, updatedItems);
+      });
+    } catch (error) {
+      console.error("[QueryCacheManager] Update failed:", error);
+      this.invalidate();
+    }
+  }
+  /**
+   * Remove item from cache
+   *
+   * @param itemOrId - Item object or ID to remove
+   * @param matcher - Optional custom matcher function. Defaults to matching by key
+   */
+  delete(itemOrId, matcher) {
+    try {
+      this.config.queryClient.setQueryData(this.config.queryKey, (oldData) => {
+        const items = this.getItems(oldData);
+        const matchFn = matcher || ((item) => {
+          if (typeof itemOrId === "object") {
+            return this.config.keyExtractor(item) === this.config.keyExtractor(itemOrId);
+          }
+          return this.config.keyExtractor(item) === itemOrId;
+        });
+        const originalLength = items.length;
+        const updatedItems = items.filter((item) => !matchFn(item));
+        const removedCount = originalLength - updatedItems.length;
+        let result = this.setItems(oldData, updatedItems);
+        if (removedCount > 0) {
+          result = this.updatePaginationOnRemove(result, removedCount);
+        }
+        return result;
+      });
+    } catch (error) {
+      console.error("[QueryCacheManager] Delete failed:", error);
+      this.invalidate();
+    }
+  }
+  /**
+   * Replace full data
+   *
+   * @param newData - Complete new data to replace cache
+   */
+  replace(newData) {
+    try {
+      this.config.queryClient.setQueryData(this.config.queryKey, newData);
+    } catch (error) {
+      console.error("[QueryCacheManager] Replace failed:", error);
+      this.invalidate();
+    }
+  }
+  /**
+   * Clear all items (keeps structure, empties array)
+   */
+  clear() {
+    try {
+      this.config.queryClient.setQueryData(this.config.queryKey, (oldData) => {
+        let result = this.setItems(oldData, []);
+        if (this.config.pagination?.totalElementsPath) {
+          result = setAtPath(result, this.config.pagination.totalElementsPath, 0);
+        }
+        if (this.config.pagination?.totalPagesPath) {
+          result = setAtPath(result, this.config.pagination.totalPagesPath, 0);
+        }
+        return result;
+      });
+    } catch (error) {
+      console.error("[QueryCacheManager] Clear failed:", error);
+      this.invalidate();
+    }
+  }
+  /**
+   * Get current items from cache
+   *
+   * @returns Current items array or empty array if no data
+   */
+  getItemsFromCache() {
+    const data = this.config.queryClient.getQueryData(this.config.queryKey);
+    return this.getItems(data);
+  }
+  /**
+   * Get full data from cache
+   *
+   * @returns Current full data or undefined if no data
+   */
+  getDataFromCache() {
+    return this.config.queryClient.getQueryData(this.config.queryKey);
+  }
+  /**
+   * Invalidate query to trigger refetch
+   */
+  invalidate() {
+    this.config.queryClient.invalidateQueries({ queryKey: this.config.queryKey });
+  }
+  /**
+   * Get handlers for use with mutations
+   *
+   * @returns Object with onAdd, onUpdate, onDelete handlers
+   */
+  createHandlers() {
+    return {
+      onAdd: (newItem, position) => this.add(newItem, position),
+      onUpdate: (updatedItem, matcher) => this.update(updatedItem, matcher),
+      onDelete: (itemOrId, matcher) => this.delete(itemOrId, matcher)
+    };
+  }
+};
+
+exports.QueryCacheManager = QueryCacheManager;
+Object.keys(reactQuery).forEach(function (k) {
+  if (k !== 'default' && !Object.prototype.hasOwnProperty.call(exports, k)) Object.defineProperty(exports, k, {
+    enumerable: true,
+    get: function () { return reactQuery[k]; }
+  });
+});

package/dist/index.mjs

@@ -0,0 +1,284 @@
+export * from '@tanstack/react-query';
+
+// src/index.ts
+
+// src/managers/QueryCacheManager/QueryCache.utils.ts
+function getAtPath(obj, path, defaultValue) {
+  if (!obj || !path) return defaultValue;
+  const keys = path.split(".");
+  let result = obj;
+  for (const key of keys) {
+    if (result === null || result === void 0) {
+      return defaultValue;
+    }
+    result = result[key];
+  }
+  return result !== void 0 ? result : defaultValue;
+}
+function setAtPath(obj, path, value) {
+  if (!path) return obj;
+  const keys = path.split(".");
+  const root = obj ? { ...obj } : {};
+  let current = root;
+  for (let i = 0; i < keys.length - 1; i++) {
+    const key = keys[i];
+    if (!current[key] || typeof current[key] !== "object") {
+      current[key] = {};
+    } else {
+      current[key] = { ...current[key] };
+    }
+    current = current[key];
+  }
+  current[keys[keys.length - 1]] = value;
+  return root;
+}
+function incrementAtPath(obj, path, increment) {
+  const currentValue = getAtPath(obj, path, 0);
+  const newValue = currentValue + increment;
+  return setAtPath(obj, path, newValue);
+}
+
+// src/managers/QueryCacheManager/QueryCache.manager.ts
+var QueryCacheManager = class {
+  constructor(config) {
+    this.config = {
+      ...config,
+      keyExtractor: config.keyExtractor || ((item) => item.id)
+    };
+  }
+  /**
+   * Get items array from data
+   * Returns empty array if path doesn't exist or data is null
+   */
+  getItems(data) {
+    if (!data) return [];
+    if (!this.config.itemsPath) {
+      return Array.isArray(data) ? data : [];
+    }
+    const items = getAtPath(data, this.config.itemsPath, []);
+    return Array.isArray(items) ? items : [];
+  }
+  /**
+   * Set items array in data
+   * Creates nested structure if it doesn't exist
+   */
+  setItems(data, items) {
+    if (!data) {
+      if (this.config.initialData) {
+        data = this.config.initialData;
+      } else {
+        if (!this.config.itemsPath) {
+          return items;
+        }
+        data = {};
+      }
+    }
+    if (!this.config.itemsPath) {
+      return items;
+    }
+    return setAtPath(data, this.config.itemsPath, items);
+  }
+  /**
+   * Update pagination metadata after adding items
+   */
+  updatePaginationOnAdd(data, addedCount) {
+    if (!this.config.pagination) return data;
+    let result = data;
+    if (this.config.pagination.totalElementsPath) {
+      result = incrementAtPath(
+        result,
+        this.config.pagination.totalElementsPath,
+        addedCount
+      );
+    }
+    if (this.config.pagination.totalPagesPath && this.config.pagination.pageSizePath && this.config.pagination.totalElementsPath) {
+      const pageSize = getAtPath(result, this.config.pagination.pageSizePath, 0);
+      const totalElements = getAtPath(
+        result,
+        this.config.pagination.totalElementsPath,
+        0
+      );
+      if (pageSize > 0) {
+        const totalPages = Math.ceil(totalElements / pageSize);
+        result = setAtPath(
+          result,
+          this.config.pagination.totalPagesPath,
+          totalPages
+        );
+      }
+    }
+    return result;
+  }
+  /**
+   * Update pagination metadata after removing items
+   */
+  updatePaginationOnRemove(data, removedCount) {
+    if (!this.config.pagination) return data;
+    let result = data;
+    if (this.config.pagination.totalElementsPath) {
+      result = incrementAtPath(
+        result,
+        this.config.pagination.totalElementsPath,
+        -removedCount
+      );
+    }
+    if (this.config.pagination.totalPagesPath && this.config.pagination.pageSizePath && this.config.pagination.totalElementsPath) {
+      const pageSize = getAtPath(result, this.config.pagination.pageSizePath, 0);
+      const totalElements = getAtPath(
+        result,
+        this.config.pagination.totalElementsPath,
+        0
+      );
+      if (pageSize > 0) {
+        const totalPages = Math.ceil(Math.max(0, totalElements) / pageSize);
+        result = setAtPath(
+          result,
+          this.config.pagination.totalPagesPath,
+          totalPages
+        );
+      }
+    }
+    return result;
+  }
+  /**
+   * Add item to cache
+   *
+   * @param newItem - The item to add
+   * @param position - Where to add: 'start' or 'end'
+   */
+  add(newItem, position = "start") {
+    try {
+      this.config.queryClient.setQueryData(this.config.queryKey, (oldData) => {
+        const items = this.getItems(oldData);
+        const updatedItems = position === "start" ? [newItem, ...items] : [...items, newItem];
+        let result = this.setItems(oldData, updatedItems);
+        result = this.updatePaginationOnAdd(result, 1);
+        return result;
+      });
+    } catch (error) {
+      console.error("[QueryCacheManager] Add failed:", error);
+      this.invalidate();
+    }
+  }
+  /**
+   * Update existing item
+   *
+   * @param updatedItem - Partial item data to update
+   * @param matcher - Optional custom matcher function. Defaults to matching by key
+   */
+  update(updatedItem, matcher) {
+    try {
+      this.config.queryClient.setQueryData(this.config.queryKey, (oldData) => {
+        const items = this.getItems(oldData);
+        const matchFn = matcher || ((item) => this.config.keyExtractor(item) === this.config.keyExtractor(updatedItem));
+        const updatedItems = items.map(
+          (item) => matchFn(item) ? { ...item, ...updatedItem } : item
+        );
+        return this.setItems(oldData, updatedItems);
+      });
+    } catch (error) {
+      console.error("[QueryCacheManager] Update failed:", error);
+      this.invalidate();
+    }
+  }
+  /**
+   * Remove item from cache
+   *
+   * @param itemOrId - Item object or ID to remove
+   * @param matcher - Optional custom matcher function. Defaults to matching by key
+   */
+  delete(itemOrId, matcher) {
+    try {
+      this.config.queryClient.setQueryData(this.config.queryKey, (oldData) => {
+        const items = this.getItems(oldData);
+        const matchFn = matcher || ((item) => {
+          if (typeof itemOrId === "object") {
+            return this.config.keyExtractor(item) === this.config.keyExtractor(itemOrId);
+          }
+          return this.config.keyExtractor(item) === itemOrId;
+        });
+        const originalLength = items.length;
+        const updatedItems = items.filter((item) => !matchFn(item));
+        const removedCount = originalLength - updatedItems.length;
+        let result = this.setItems(oldData, updatedItems);
+        if (removedCount > 0) {
+          result = this.updatePaginationOnRemove(result, removedCount);
+        }
+        return result;
+      });
+    } catch (error) {
+      console.error("[QueryCacheManager] Delete failed:", error);
+      this.invalidate();
+    }
+  }
+  /**
+   * Replace full data
+   *
+   * @param newData - Complete new data to replace cache
+   */
+  replace(newData) {
+    try {
+      this.config.queryClient.setQueryData(this.config.queryKey, newData);
+    } catch (error) {
+      console.error("[QueryCacheManager] Replace failed:", error);
+      this.invalidate();
+    }
+  }
+  /**
+   * Clear all items (keeps structure, empties array)
+   */
+  clear() {
+    try {
+      this.config.queryClient.setQueryData(this.config.queryKey, (oldData) => {
+        let result = this.setItems(oldData, []);
+        if (this.config.pagination?.totalElementsPath) {
+          result = setAtPath(result, this.config.pagination.totalElementsPath, 0);
+        }
+        if (this.config.pagination?.totalPagesPath) {
+          result = setAtPath(result, this.config.pagination.totalPagesPath, 0);
+        }
+        return result;
+      });
+    } catch (error) {
+      console.error("[QueryCacheManager] Clear failed:", error);
+      this.invalidate();
+    }
+  }
+  /**
+   * Get current items from cache
+   *
+   * @returns Current items array or empty array if no data
+   */
+  getItemsFromCache() {
+    const data = this.config.queryClient.getQueryData(this.config.queryKey);
+    return this.getItems(data);
+  }
+  /**
+   * Get full data from cache
+   *
+   * @returns Current full data or undefined if no data
+   */
+  getDataFromCache() {
+    return this.config.queryClient.getQueryData(this.config.queryKey);
+  }
+  /**
+   * Invalidate query to trigger refetch
+   */
+  invalidate() {
+    this.config.queryClient.invalidateQueries({ queryKey: this.config.queryKey });
+  }
+  /**
+   * Get handlers for use with mutations
+   *
+   * @returns Object with onAdd, onUpdate, onDelete handlers
+   */
+  createHandlers() {
+    return {
+      onAdd: (newItem, position) => this.add(newItem, position),
+      onUpdate: (updatedItem, matcher) => this.update(updatedItem, matcher),
+      onDelete: (itemOrId, matcher) => this.delete(itemOrId, matcher)
+    };
+  }
+};
+
+export { QueryCacheManager };

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "tanstack-cacher",
+  "version": "1.0.0",
+  "description": "A lightweight cache management utility for TanStack Query that simplifies adding, updating, deleting, and synchronizing cached data",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hacagahasanli/tanstack-cacher"
+  },
+  "author": {
+    "name": "Hasanli Hajagha",
+    "email": "hacagahasanli@gmail.com",
+    "url": "https://github.com/hacagahasanli"
+  },
+  "maintainers": [
+    {
+      "name": "Hasanli Hajagha",
+      "email": "hacagahasanli@gmail.com",
+      "web": "http://github.com/hacagahasanli"
+    }
+  ],
+  "homepage": "https://github.com/hacagahasanli/tanstack-cacher",
+  "keywords": [
+    "react",
+    "react-query",
+    "tanstack-query",
+    "cache",
+    "cache-manager",
+    "optimistic-updates"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "lint": "eslint src --ext .ts,.tsx",
+    "lint:fix": "eslint src --ext .ts,.tsx --fix",
+    "type-check": "tsc --noEmit",
+    "prepublishOnly": "npm run build",
+    "test": "echo \"No tests yet\" && exit 0"
+  },
+  "dependencies": {
+    "@tanstack/react-query": "^5.62.11"
+  },
+  "peerDependencies": {
+    "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.12",
+    "@typescript-eslint/eslint-plugin": "^7.18.0",
+    "@typescript-eslint/parser": "^7.18.0",
+    "eslint": "^8.57.1",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-plugin-prettier": "^5.2.1",
+    "prettier": "^3.4.2",
+    "react": "^18.3.1",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2"
+  }
+}