@codeleap/query 6.2.3 → 6.8.0

package/dist/factors/createQueryManager.d.ts

@@ -0,0 +1,36 @@
+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 declare const createQueryManager: <T extends QueryItem, F = {}>(options: QueryManagerOptions<T, F>) => QueryManager<T, F>;
+//# sourceMappingURL=createQueryManager.d.ts.map

package/dist/factors/createQueryManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createQueryManager.d.ts","sourceRoot":"","sources":["../../src/factors/createQueryManager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAA;AACrC,OAAO,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAA;AAEzD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,eAAO,MAAM,kBAAkB,GAAI,CAAC,SAAS,SAAS,EAAE,CAAC,GAAG,EAAE,EAAE,SAAS,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC,uBAEjG,CAAA"}

package/dist/factors/createQueryOperations.d.ts

@@ -0,0 +1,35 @@
+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 declare function createQueryOperations(options: QueryOperationsOptions): QueryOperations<unknown, unknown>;
+//# sourceMappingURL=createQueryOperations.d.ts.map

package/dist/factors/createQueryOperations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createQueryOperations.d.ts","sourceRoot":"","sources":["../../src/factors/createQueryOperations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,QAAQ,CAAA;AACxC,OAAO,EAAE,sBAAsB,EAAE,MAAM,8BAA8B,CAAA;AAErE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,qCAEpE"}

package/dist/factors/index.d.ts

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

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

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

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from './lib';
+export * from './types';
+export * from './factors';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,OAAO,CAAA;AACrB,cAAc,SAAS,CAAA;AACvB,cAAc,WAAW,CAAA"}

package/dist/lib/Mutations.d.ts

@@ -0,0 +1,103 @@
+import { Query } from '@tanstack/query-core';
+import { QueryKeys } from './QueryKeys';
+import { QueryClient, QueryItem, RemovedItemMap, WithTempId } from '../types';
+/**
+ * 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 declare class Mutations<T extends QueryItem, F> {
+    private queryKeys;
+    private queryClient;
+    private queryName;
+    /**
+     * 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(queryKeys: QueryKeys<T, F>, queryClient: QueryClient, 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)
+     * ```
+     */
+    private _addItemAtKey;
+    addItem(newItem: T, position?: 'start' | 'end' | RemovedItemMap, listFilters?: F): void;
+    addItemToQuery(newItem: T, position: "start" | "end" | undefined, query: Query): void;
+    /**
+     * Removes an item from all or specific cached list query and returns the positions where it was found
+     * @param itemId - The ID of the item to remove
+     * @param listFilters - Optional filters to target a specific list query. If omitted, removes from all list queries
+     * @returns A RemovedItemMap containing the query keys and positions where the item was found, or null if not found in any query
+     *
+     * @example
+     * ```typescript
+     * // Remove from all list queries
+     * const removedPositions = mutations.removeItem('user-123')
+     *
+     * // Remove from a specific filtered list
+     * const removedPositions = mutations.removeItem('user-123', { status: 'active' })
+     *
+     * // Later, restore the item to its original positions
+     * if (removedPositions) {
+     *   mutations.addItem(restoredUser, removedPositions)
+     * }
+     * ```
+     */
+    removeItem(itemId: QueryItem['id'], listFilters?: F): RemovedItemMap | null;
+    /**
+     * 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>[]): void;
+}
+/**
+ * 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 declare const createMutations: <T extends QueryItem, F>(queryKeys: QueryKeys<T, F>, queryClient: QueryClient, queryName: string) => Mutations<T, F>;
+//# sourceMappingURL=Mutations.d.ts.map

package/dist/lib/Mutations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Mutations.d.ts","sourceRoot":"","sources":["../../src/lib/Mutations.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgB,KAAK,EAAY,MAAM,sBAAsB,CAAA;AACpE,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAA;AACvC,OAAO,EAAmD,WAAW,EAAE,SAAS,EAAE,cAAc,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAI9H;;;;GAIG;AACH,qBAAa,SAAS,CAAC,CAAC,SAAS,SAAS,EAAE,CAAC;IAQzC,OAAO,CAAC,SAAS;IACjB,OAAO,CAAC,WAAW;IACnB,OAAO,CAAC,SAAS;IATnB;;;;;OAKG;gBAEO,SAAS,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,EAC1B,WAAW,EAAE,WAAW,EACxB,SAAS,EAAE,MAAM;IAG3B;;;;;;;;;;;;;;;;;OAiBG;IACH,OAAO,CAAC,aAAa;IAwBrB,OAAO,CAAC,OAAO,EAAE,CAAC,EAAE,QAAQ,GAAE,OAAO,GAAG,KAAK,GAAG,cAAwB,EAAE,WAAW,CAAC,EAAE,CAAC;IAiCzF,cAAc,CAAC,OAAO,EAAE,CAAC,EAAE,QAAQ,EAAE,OAAO,GAAG,KAAK,YAAU,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI;IAInF;;;;;;;;;;;;;;;;;;;OAmBG;IACH,UAAU,CAAC,MAAM,EAAE,SAAS,CAAC,IAAI,CAAC,EAAE,WAAW,CAAC,EAAE,CAAC,GAAG,cAAc,GAAG,IAAI;IAoD3E;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,WAAW,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,EAAE;CAsDlD;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,eAAe,GAAI,CAAC,SAAS,SAAS,EAAE,CAAC,EAAE,WAAW,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,aAAa,WAAW,EAAE,WAAW,MAAM,oBAE9H,CAAA"}

package/dist/lib/QueryClientEnhanced/index.d.ts

@@ -0,0 +1,41 @@
+import { QueryClient, QueryKey, Query, QueryCacheNotifyEvent, QueryOptions } from '@tanstack/react-query';
+import { DynamicEnhancedQuery, EnhancedQuery, PollQueryOptions, 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 declare class QueryClientEnhanced {
+    client: QueryClient;
+    constructor(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): (() => void) | undefined;
+    /**
+     * 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.
+     */
+    pollQuery<T, R>(key: QueryKey, options: PollQueryOptions<T, R>): Promise<R>;
+    /**
+     * 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): EnhancedQuery<T>;
+    /**
+     * 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): Promise<Query<T, Error, T, readonly unknown[]>>;
+    /**
+     * 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>): EnhancedQuery<Data>;
+    /**
+     * 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>): DynamicEnhancedQuery<Data, BuilderArgs>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/QueryClientEnhanced/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/QueryClientEnhanced/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,KAAK,EAAW,qBAAqB,EAAc,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAC9H,OAAO,EAAE,oBAAoB,EAAE,aAAa,EAAE,gBAAgB,EAAiB,eAAe,EAAE,MAAM,SAAS,CAAA;AAE/G;;;GAGG;AACH,qBAAa,mBAAmB;IACX,MAAM,EAAE,WAAW;gBAAnB,MAAM,EAAE,WAAW;IAEtC;;;OAGG;IACH,aAAa,CAAC,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC,CAAC,EAAE,qBAAqB,KAAK,IAAI;IAqBzE;;;OAGG;IACG,SAAS,CAAC,CAAC,EAAE,CAAC,EAClB,GAAG,EAAE,QAAQ,EACb,OAAO,EAAE,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC;IAwCjC;;;OAGG;IACH,UAAU,CAAC,CAAC,EAAE,GAAG,EAAE,QAAQ;IA6E3B;;;OAGG;IACH,cAAc,CAAC,CAAC,EAAE,GAAG,EAAE,QAAQ;IAqC/B;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,YAAY,CAAC,IAAI,CAAC;IAmBxD;;;OAGG;IACH,eAAe,CAAC,IAAI,EAAE,WAAW,SAAS,GAAG,EAAE,GAAG,GAAG,EAAE,EAAE,CAAC,EAAE,eAAe,CAAC,WAAW,CAAC;CAezF"}

package/dist/lib/QueryClientEnhanced/types.d.ts

@@ -0,0 +1,51 @@
+import { QueryKey, Query, QueryCacheNotifyEvent, 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];
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/lib/QueryClientEnhanced/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/lib/QueryClientEnhanced/types.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,QAAQ,EACR,KAAK,EACL,qBAAqB,EACrB,sBAAsB,EACvB,MAAM,uBAAuB,CAAA;AAE9B,qKAAqK;AACrK,MAAM,MAAM,eAAe,CAAC,IAAI,SAAS,GAAG,EAAE,GAAG,GAAG,EAAE,IAAI,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,QAAQ,CAAA;AAErF,0GAA0G;AAC1G,MAAM,MAAM,aAAa,CAAC,CAAC,IAAI;IAC7B,IAAI,EAAE,OAAO,CAAA;IACb,IAAI,EAAE,CAAC,CAAA;CACR,CAAA;AAED;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,CAAA;AAE3G,MAAM,MAAM,gBAAgB,CAAC,CAAC,EAAE,CAAC,IAAI;IACnC,iDAAiD;IACjD,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,eAAe,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;IAC/B,+GAA+G;IAC/G,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,CAAC,CAAA;CAChB,CAAA;AAED;;;;GAIG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,CAAE,SAAQ,KAAK,CAAC,CAAC,CAAC;IAChD,oIAAoI;IACpI,cAAc,IAAI,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;IACnC,8FAA8F;IAC9F,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,qBAAqB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;IAChE,wEAAwE;IACxE,OAAO,IAAI,OAAO,CAAC,CAAC,CAAC,CAAA;IACrB,IAAI,CAAC,CAAC,EACJ,OAAO,EAAE,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,GAC9B,OAAO,CAAC,CAAC,CAAC,CAAA;IACb,0FAA0F;IAC1F,OAAO,IAAI,CAAC,CAAA;IACZ,UAAU,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,sBAAsB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAA;IAC/F,GAAG,EAAE,QAAQ,CAAA;CACd;AAED;;;GAGG;AACH,MAAM,MAAM,oBAAoB,CAAC,CAAC,EAAE,WAAW,SAAS,GAAG,EAAE,IAAI;KAC9D,CAAC,IAAI,MAAM,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,IAAI,EAAE,WAAW,KAAK,aAAa,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;CAC7E,CAAA"}

package/dist/lib/QueryKeys.d.ts

@@ -0,0 +1,173 @@
+import { CancelOptions, InvalidateOptions, InvalidateQueryFilters, Query, QueryFilters, QueryKey, RefetchOptions, RefetchQueryFilters } from '@tanstack/react-query';
+import { ListPaginationResponse, ListSelector, QueryClient, QueryItem, RetrieveDataOptions } from '../types';
+/**
+ * Class for managing React Query keys and operations for a specific query type
+ * @template T - The query item type that extends QueryItem
+ * @template F - The filter type used for list queries
+ */
+export declare class QueryKeys<T extends QueryItem, F> {
+    private queryName;
+    private queryClient;
+    /**
+     * Creates a new QueryKeys instance
+     * @param queryName - The name of the query used as base for all keys
+     * @param queryClient - The React Query client instance
+     */
+    constructor(queryName: string, queryClient: QueryClient);
+    /**
+     * Gets the base query keys for different operations
+     * @returns Object containing base query keys for list, retrieve, create, update, and delete operations
+     */
+    get keys(): {
+        list: QueryKey;
+        retrieve: (id: QueryItem["id"]) => QueryKey;
+        create: QueryKey;
+        update: QueryKey;
+        delete: QueryKey;
+    };
+    /**
+     * Generates a list query key with optional filters
+     * @param filters - Optional filters to include in the query key
+     * @returns Query key array with or without filters
+     */
+    listKeyWithFilters(filters?: F): QueryKey;
+    /**
+     * React hook that returns a memoized list query key with filters
+     * @param filters - Optional filters to include in the query key
+     * @returns Memoized query key array
+     */
+    useListKeyWithFilters(filters?: F): readonly unknown[];
+    /**
+     * React hook that returns a memoized retrieve query key
+     * @param id - The ID of the item to retrieve
+     * @returns Memoized query key array for retrieve operation
+     */
+    useRetrieveKey(id: QueryItem['id']): readonly unknown[];
+    /**
+     * Predicate function to check if a query belongs to this query name (all operations)
+     * @private
+     * @param queryName - The query name to match against
+     * @param query - The query object to check
+     * @returns True if the query matches the query name
+     */
+    private predicateQueryKeyAll;
+    /**
+     * Predicate function to check if a query is a list query for this query name
+     * @private
+     * @param queryName - The query name to match against
+     * @param query - The query object to check
+     * @param toIgnoreQueryKeys - Query keys to ignore in the matching
+     * @returns True if the query is a list query and not in the ignore list
+     */
+    private predicateQueryKeyList;
+    /**
+     * Invalidates all queries for this query name
+     * @param filters - Optional filters to apply to the invalidation
+     * @param options - Optional invalidation options
+     * @returns Promise that resolves when invalidation is complete
+     */
+    invalidateAll(filters?: InvalidateQueryFilters<QueryKey>, options?: InvalidateOptions): Promise<void>;
+    /**
+     * Invalidates list queries, optionally with specific filters
+     * @param listFilters - Optional filters to target specific list queries
+     * @param ignoreQueryKeys - Query keys to ignore during invalidation
+     * @param filters - Optional filters to apply to the invalidation
+     * @param options - Optional invalidation options
+     * @returns Promise that resolves when invalidation is complete
+     */
+    invalidateList(listFilters?: F, ignoreQueryKeys?: QueryKey | QueryKey[], filters?: InvalidateQueryFilters<QueryKey>, options?: InvalidateOptions): Promise<void>;
+    /**
+     * Invalidates a specific retrieve query by ID
+     * @param id - The ID of the item to invalidate
+     * @param filters - Optional filters to apply to the invalidation
+     * @param options - Optional invalidation options
+     * @returns Promise that resolves when invalidation is complete
+     */
+    invalidateRetrieve(id: QueryItem['id'], filters?: InvalidateQueryFilters<QueryKey>, options?: InvalidateOptions): Promise<void>;
+    /**
+     * Refetches all queries for this query name
+     * @param filters - Optional filters to apply to the refetch
+     * @param options - Optional refetch options
+     * @returns Promise that resolves when refetch is complete
+     */
+    refetchAll(filters?: RefetchQueryFilters<QueryKey>, options?: RefetchOptions): Promise<void>;
+    /**
+     * Refetches list queries, optionally with specific filters
+     * @param listFilters - Optional filters to target specific list queries
+     * @param ignoreQueryKeys - Query keys to ignore during refetch
+     * @param filters - Optional filters to apply to the refetch
+     * @param options - Optional refetch options
+     * @returns Promise that resolves when refetch is complete
+     */
+    refetchList(listFilters?: F, ignoreQueryKeys?: QueryKey | QueryKey[], filters?: RefetchQueryFilters<QueryKey>, options?: RefetchOptions): Promise<void>;
+    /**
+     * Refetches a specific retrieve query by ID
+     * @param id - The ID of the item to refetch
+     * @param filters - Optional filters to apply to the refetch
+     * @param options - Optional refetch options
+     * @returns Promise that resolves when refetch is complete
+     */
+    refetchRetrieve(id: QueryItem['id'], filters?: RefetchQueryFilters<QueryKey>, options?: RefetchOptions): Promise<void>;
+    /**
+     * Removes a specific retrieve query data from the cache
+     * @param id - The ID of the item to remove from cache
+     * @param filters - Optional filters to apply to the removal
+     * @returns Promise that resolves when removal is complete
+     */
+    removeRetrieveQueryData(id: QueryItem['id'], filters?: QueryFilters<QueryKey>): Promise<void>;
+    /**
+     * Cancels list queries that are currently in flight
+     * @param listFilters - Optional filters to target specific list queries
+     * @param ignoreQueryKeys - Query keys to ignore during cancellation
+     * @param filters - Optional filters to apply to the cancellation
+     * @param options - Optional cancellation options
+     * @returns Promise that resolves when cancellation is complete
+     */
+    cancelListQueries(listFilters?: F, ignoreQueryKeys?: QueryKey | QueryKey[], filters?: QueryFilters<QueryKey>, options?: CancelOptions): Promise<void>;
+    /**
+     * Gets list data from the cache, including both items array and item map
+     * @param filters - Optional filters to target specific list data
+     * @returns Object containing items array and itemMap (keyed by ID)
+     */
+    getListData(filters?: F): {
+        items: T[];
+        itemMap: Record<string | number, T>;
+    };
+    /**
+      * 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'], options?: RetrieveDataOptions): T | undefined;
+    /**
+     * Gets all list queries from the query cache
+     * @returns Array of list queries for this query name
+     */
+    getAllListQueries(): Query<ListPaginationResponse<T>, Error, Omit<ListSelector<T>, "allItems">, QueryKey>[];
+    /**
+     * Gets a specific list query from the query cache
+     * @param listFilters - Optional filters to identify a specific list query. If omitted, returns the unfiltered list query
+     * @returns The matching list query, or undefined if not found
+     */
+    getListQuery(listFilters?: F): Query<ListPaginationResponse<T>, Error, Omit<ListSelector<T>, "allItems">, QueryKey>;
+}
+/**
+ * Factory function to create a new QueryKeys instance
+ * @template T - The query item type that extends QueryItem
+ * @template F - The filter type used for list queries
+ * @param name - The name of the query used as base for all keys
+ * @param queryClient - The React Query client instance
+ * @returns New QueryKeys instance
+ */
+export declare const createQueryKeys: <T extends QueryItem, F>(name: string, queryClient: QueryClient) => QueryKeys<T, F>;
+//# sourceMappingURL=QueryKeys.d.ts.map

package/dist/lib/QueryKeys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QueryKeys.d.ts","sourceRoot":"","sources":["../../src/lib/QueryKeys.ts"],"names":[],"mappings":"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"}