@codeleap/query 6.3.0 → 6.8.0

package/dist/lib/QueryManager.d.ts

@@ -0,0 +1,202 @@
+import { FetchInfiniteQueryOptions, FetchQueryOptions, QueryClient, QueryKey } from '@tanstack/react-query';
+import { QueryKeys } from './QueryKeys';
+import { Mutations } from './Mutations';
+import { CreateMutationCtx, CreateMutationOptions, ListPaginationResponse, ListQueryOptions, QueryItem, QueryManagerOptions, RetrieveQueryOptions, UpdateMutationCtx, UpdateMutationOptions, DeleteMutationCtx, DeleteMutationOptions } from '../types';
+/**
+ * Comprehensive query manager class that provides hooks and utilities for managing CRUD operations with React Query
+ * @template T - The query item type that extends QueryItem
+ * @template F - The filter type used for list queries
+ *
+ * @description
+ * QueryManager provides a complete solution for managing list and individual item queries with:
+ * - Infinite scroll pagination for lists
+ * - Optimistic updates for create, update, and delete operations
+ * - Automatic cache synchronization between list and individual queries
+ * - Built-in error handling and rollback mechanisms
+ */
+export declare class QueryManager<T extends QueryItem, F> {
+    private options;
+    queryClient: QueryClient;
+    /**
+     * Creates a new QueryManager instance
+     * @param options - Configuration options for the query manager
+     */
+    constructor(options: QueryManagerOptions<T, F>);
+    /**
+     * Gets the name of this query manager
+     * @returns The query name used for identification
+     */
+    get name(): string;
+    /**
+     * Gets the configured CRUD functions
+     * @returns Object containing all configured function handlers
+     */
+    get functions(): {
+        list: ((limit: number, offset: number, filters: F) => Promise<ListPaginationResponse<T>>) | undefined;
+        retrieve: ((id: T["id"]) => Promise<T>) | undefined;
+        create: ((data: Partial<T>) => Promise<T>) | undefined;
+        update: ((data: Partial<T>) => Promise<T>) | undefined;
+        delete: ((id: T["id"]) => Promise<T["id"]>) | undefined;
+    };
+    /** QueryKeys instance for managing query keys and cache operations */
+    queryKeys: QueryKeys<T, F>;
+    /** Mutations instance for managing cache mutations */
+    mutations: Mutations<T, F>;
+    /**
+     * React hook for infinite scroll list queries with pagination
+     * @param options - Configuration options for the list query
+     * @returns Object containing items array, query key, and query object
+     *
+     * @example
+     * ```typescript
+     * const { items, query } = queryManager.useList({
+     *   filters: { status: 'active' },
+     *   limit: 20
+     * })
+     * ```
+     */
+    useList(options?: ListQueryOptions<T, F>): {
+        items: T[];
+        queryKey: readonly unknown[];
+        query: import("@tanstack/react-query").UseInfiniteQueryResult<import("..").ListSelector<T>, Error>;
+    };
+    /**
+     * React hook for retrieving a single item by ID
+     * @param id - The ID of the item to retrieve
+     * @param options - Configuration options for the retrieve query
+     * @returns Object containing the item data, query key, and query object
+     *
+     * @description
+     * This hook automatically:
+     * - Uses list cache as initial data if available
+     * - Updates list cache when retrieve data changes
+     * - Synchronizes data between list and individual caches
+     *
+     * @example
+     * ```typescript
+     * const { item, query } = queryManager.useRetrieve('user-123', {
+     *   enabled: !!userId
+     * })
+     * ```
+     */
+    useRetrieve(id: T['id'], options?: RetrieveQueryOptions<T>): {
+        item: import("@tanstack/query-core").NoInfer<T> | undefined;
+        queryKey: readonly unknown[];
+        query: import("@tanstack/react-query").UseQueryResult<import("@tanstack/query-core").NoInfer<T>, Error>;
+    };
+    /**
+     * React hook for creating new items with optimistic updates
+     * @param options - Configuration options for the create mutation
+     * @returns React Query mutation object for create operations
+     *
+     * @description
+     * This hook supports optimistic updates by:
+     * - Immediately adding a temporary item to the cache
+     * - Rolling back on error by removing the temporary item
+     * - Replacing temporary item with real data on success
+     *
+     * @example
+     * ```typescript
+     * const createMutation = queryManager.useCreate({
+     *   optimistic: true,
+     *   appendTo: 'start',
+     *   listFilters: { status: 'active' }
+     * })
+     *
+     * // Usage
+     * createMutation.mutate({ name: 'New User', email: 'user@example.com' })
+     * ```
+     */
+    useCreate(options?: CreateMutationOptions<T, F>): import("@tanstack/react-query").UseMutationResult<T, Error, Partial<T>, CreateMutationCtx | undefined>;
+    /**
+     * React hook for updating existing items with optimistic updates
+     * @param options - Configuration options for the update mutation
+     * @returns React Query mutation object for update operations
+     *
+     * @description
+     * This hook supports optimistic updates by:
+     * - Immediately updating the item in cache with new data
+     * - Rolling back to previous data on error
+     * - Confirming updates with server response on success
+     *
+     * @example
+     * ```typescript
+     * const updateMutation = queryManager.useUpdate({
+     *   optimistic: true,
+     *   onSuccess: (data) => console.log('Updated:', data)
+     * })
+     *
+     * // Usage
+     * updateMutation.mutate({ id: 'user-123', name: 'Updated Name' })
+     * ```
+     */
+    useUpdate(options?: UpdateMutationOptions<T, F>): import("@tanstack/react-query").UseMutationResult<T, Error, Partial<T>, UpdateMutationCtx<T> | undefined>;
+    /**
+     * React hook for deleting items with optimistic updates
+     * @param options - Configuration options for the delete mutation
+     * @returns React Query mutation object for delete operations
+     *
+     * @description
+     * This hook supports optimistic updates by:
+     * - Immediately removing the item from cache
+     * - Storing the removal positions for potential rollback
+     * - Restoring the item to original positions on error
+     * - Confirming deletion on success
+     *
+     * @example
+     * ```typescript
+     * const deleteMutation = queryManager.useDelete({
+     *   optimistic: true,
+     *   onSuccess: () => console.log('Item deleted successfully')
+     * })
+     *
+     * // Usage
+     * deleteMutation.mutate('user-123')
+     * ```
+     */
+    useDelete(options?: DeleteMutationOptions<T, F>): import("@tanstack/react-query").UseMutationResult<unknown, Error, T["id"], DeleteMutationCtx<T> | undefined>;
+    /**
+     * Prefetches a single item by ID for improved performance
+     * @param id - The ID of the item to prefetch
+     * @param options - Prefetch options compatible with React Query
+     * @returns Promise that resolves when prefetch is complete
+     *
+     * @description
+     * Use this method to preload data that users are likely to need soon,
+     * such as when hovering over links or preparing for navigation.
+     *
+     * @example
+     * ```typescript
+     * // Prefetch on hover
+     * const handleHover = (userId: string) => {
+     *   queryManager.prefetchRetrieve(userId, { staleTime: 5 * 60 * 1000 })
+     * }
+     * ```
+     */
+    prefetchRetrieve(id: T['id'], options?: Omit<FetchQueryOptions<T, Error, T, QueryKey, never>, 'queryKey' | 'queryFn'>): Promise<void>;
+    /**
+     * Prefetches a paginated list with filters for improved performance
+     * @param filters - Filter parameters to apply to the list query
+     * @param options - Prefetch options compatible with React Query's infinite queries
+     * @param options.initialOffset - Starting offset for pagination (default: 0)
+     * @returns Promise that resolves when prefetch is complete
+     *
+     * @description
+     * Use this method to preload paginated list data that users are likely to need soon.
+     *
+     * @example
+     * ```typescript
+     * const handle = () => {
+     *   queryManager.prefetchList(
+     *     { category: 'electronics' },
+     *     { staleTime: 5 * 60 * 1000 }
+     *   )
+     * }
+     *
+     * ```
+     */
+    prefetchList(filters?: F, options?: Omit<FetchInfiniteQueryOptions<ListPaginationResponse<T>, Error, ListPaginationResponse<T>, QueryKey, number>, 'queryKey' | 'queryFn' | 'initialPageParam'> & {
+        initialOffset?: number;
+    }): Promise<void>;
+}
+//# sourceMappingURL=QueryManager.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"QueryManager.d.ts","sourceRoot":"","sources":["../../src/lib/QueryManager.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,yBAAyB,EAAE,iBAAiB,EAAyC,WAAW,EAAE,QAAQ,EAA2C,MAAM,uBAAuB,CAAA;AAE3L,OAAO,EAAmB,SAAS,EAAE,MAAM,aAAa,CAAA;AACxD,OAAO,EAAmB,SAAS,EAAE,MAAM,aAAa,CAAA;AACxD,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,gBAAgB,EAAa,SAAS,EAAE,mBAAmB,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,UAAU,CAAA;AAKlQ;;;;;;;;;;;GAWG;AACH,qBAAa,YAAY,CAAC,CAAC,SAAS,SAAS,EAAE,CAAC;IAMlC,OAAO,CAAC,OAAO;IAL3B,WAAW,EAAE,WAAW,CAAA;IACxB;;;OAGG;gBACiB,OAAO,EAAE,mBAAmB,CAAC,CAAC,EAAE,CAAC,CAAC;IAMtD;;;OAGG;IACH,IAAI,IAAI,WAEP;IAED;;;OAGG;IACH,IAAI,SAAS;;;;;;MAQZ;IAED,sEAAsE;IACtE,SAAS,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;IAE1B,sDAAsD;IACtD,SAAS,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA;IAE1B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,OAAO,GAAE,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAM;;;;;IAsE5C;;;;;;;;;;;;;;;;;;OAkBG;IACH,WAAW,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,OAAO,GAAE,oBAAoB,CAAC,CAAC,CAAM;;;;;IA0C9D;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,SAAS,CAAC,OAAO,GAAE,qBAAqB,CAAC,CAAC,EAAE,CAAC,CAAM;IAkEnD;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,SAAS,CAAC,OAAO,GAAE,qBAAqB,CAAC,CAAC,EAAE,CAAC,CAAM;IAiEnD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,SAAS,CAAC,OAAO,GAAE,qBAAqB,CAAC,CAAC,EAAE,CAAC,CAAM;IAgEnD;;;;;;;;;;;;;;;;;OAiBG;IACH,gBAAgB,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,OAAO,GAAE,IAAI,CAAC,iBAAiB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,KAAK,CAAC,EAAE,UAAU,GAAG,SAAS,CAAM;IAQzH;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,YAAY,CACV,OAAO,CAAC,EAAE,CAAC,EACX,OAAO,GAAE,IAAI,CAAC,yBAAyB,CAAC,sBAAsB,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,sBAAsB,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,UAAU,GAAG,SAAS,GAAG,kBAAkB,CAAC,GAAG;QAAE,aAAa,CAAC,EAAE,MAAM,CAAA;KAAO;CAWzM"}

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

@@ -0,0 +1,228 @@
+import { UseQueryOptions, UseMutationOptions, QueryKey, FetchQueryOptions } from '@tanstack/react-query';
+import { QueryOperationsOptions, MutationFn, QueryFn, InferMutationParams, InferMutationReturn, InferQueryParams, InferQueryReturn } from './types';
+/**
+ * Builder class for creating type-safe query and mutation operations
+ * @template TMutations - Record type containing all registered mutation functions
+ * @template TQueries - Record type containing all registered query functions
+ *
+ * @description
+ * QueryOperations provides a fluent interface for building collections of queries and mutations
+ * with full type safety. It acts as a centralized registry for all data operations and provides
+ * corresponding React hooks that are automatically typed based on the registered functions.
+ *
+ * Key features:
+ * - Fluent builder pattern for registering operations
+ * - Automatic type inference for parameters and return types
+ * - Type-safe React hooks generation
+ * - Immutable operation registration (returns new instances)
+ */
+export declare class QueryOperations<TMutations, TQueries> {
+    private _options;
+    private _mutations;
+    private _queries;
+    /**
+     * Creates a new QueryOperations instance
+     * @param _options - Configuration options including QueryClient
+     * @param _mutations - Record of registered mutation functions (internal)
+     * @param _queries - Record of registered query functions (internal)
+     */
+    constructor(_options: QueryOperationsOptions, _mutations?: TMutations, _queries?: TQueries);
+    /**
+     * Gets all registered mutation functions
+     * @returns Readonly record of mutation functions
+     */
+    get mutations(): Readonly<TMutations>;
+    get queryClient(): import("@tanstack/query-core").QueryClient;
+    /**
+     * Gets all registered query functions
+     * @returns Readonly record of query functions
+     */
+    get queries(): Readonly<TQueries>;
+    /**
+     * Registers a new mutation function
+     * @template K - The name/key for the mutation
+     * @template T - The input data type for the mutation
+     * @template R - The return data type for the mutation
+     * @param name - Unique name identifier for the mutation
+     * @param fn - The mutation function that performs the operation
+     * @returns New QueryOperations instance with the mutation added
+     *
+     * @example
+     * ```typescript
+     * const operations = createQueryOperations({ queryClient })
+     *   .mutation('createUser', async (userData: CreateUserData) => {
+     *     return api.post('/users', userData)
+     *   })
+     *   .mutation('updateUser', async (userData: UpdateUserData) => {
+     *     return api.put(`/users/${userData.id}`, userData)
+     *   })
+     * ```
+     */
+    mutation<K extends string, T = any, R = any>(name: K, fn: MutationFn<T, R>): QueryOperations<TMutations & Record<K, MutationFn<T, R>>, TQueries>;
+    /**
+     * Registers a new query function
+     * @template K - The name/key for the query
+     * @template T - The parameters type for the query
+     * @template R - The return data type for the query
+     * @param name - Unique name identifier for the query
+     * @param fn - The query function that fetches the data
+     * @returns New QueryOperations instance with the query added
+     *
+     * @example
+     * ```typescript
+     * const operations = createQueryOperations({ queryClient })
+     *   .query('getUser', async (userId: string) => {
+     *     return api.get(`/users/${userId}`)
+     *   })
+     *   .query('getUsers', async (filters?: UserFilters) => {
+     *     return api.get('/users', { params: filters })
+     *   })
+     * ```
+     */
+    query<K extends string, T = any, R = any>(name: K, fn: QueryFn<T, R>): QueryOperations<TMutations, TQueries & Record<K, QueryFn<T, R>>>;
+    /**
+     * React hook for executing mutations with full type safety
+     * @template K - The mutation key type
+     * @param mutationKey - The name of the registered mutation to use
+     * @param options - React Query mutation options (excluding mutationFn and mutationKey)
+     * @returns React Query mutation object with inferred types
+     *
+     * @description
+     * This hook automatically provides type-safe parameters and return types based on the
+     * registered mutation function. It handles error cases and provides proper TypeScript
+     * inference for the mutation data and variables.
+     *
+     * @example
+     * ```typescript
+     * const createUserMutation = operations.useMutation('createUser', {
+     *   onSuccess: (user) => {
+     *     // 'user' is automatically typed as the return type of createUser
+     *     console.log('Created user:', user.id)
+     *   }
+     * })
+     *
+     * // Usage - parameters are type-checked
+     * createUserMutation.mutate({ name: 'John', email: 'john@example.com' })
+     * ```
+     */
+    useMutation<K extends keyof TMutations>(mutationKey: K, options?: Omit<UseMutationOptions<InferMutationReturn<TMutations[K]>, Error, InferMutationParams<TMutations[K]>>, 'mutationFn'>): import("@tanstack/react-query").UseMutationResult<InferMutationReturn<TMutations[K]>, Error, InferMutationParams<TMutations[K]>, unknown>;
+    /**
+     * React hook for executing queries with full type safety
+     * @template K - The query key type
+     * @param queryKey - The name of the registered query to use
+     * @param params - Parameters to pass to the query function (optional if query doesn't require params)
+     * @param options - React Query options (excluding queryKey and queryFn)
+     * @returns React Query query object with inferred types
+     *
+     * @description
+     * This hook automatically provides type-safe parameters and return types based on the
+     * registered query function. It generates appropriate query keys and handles parameter
+     * validation.
+     *
+     * @example
+     * ```typescript
+     * // Query with parameters
+     * const userQuery = operations.useQuery('getUser', 'user-123', {
+     *   enabled: !!userId
+     * })
+     *
+     * // Query without parameters
+     * const usersQuery = operations.useQuery('getUsers', undefined, {
+     *   refetchInterval: 30000
+     * })
+     *
+     * // Query with optional parameters
+     * const filteredUsersQuery = operations.useQuery('getUsers', { status: 'active' })
+     * ```
+     */
+    useQuery<K extends keyof TQueries, T = InferQueryReturn<TQueries[K]>>(queryKey: K, params?: InferQueryParams<TQueries[K]>, options?: Omit<Partial<UseQueryOptions<InferQueryReturn<TQueries[K]>, Error, T, QueryKey>>, 'queryFn'>): import("@tanstack/react-query").DefinedUseQueryResult<import("@tanstack/query-core").NoInfer<T>, Error>;
+    /**
+     * Generates a properly typed query key for React Query
+     * @template K - The query key type
+     * @param queryKey - The name of the query
+     * @param params - Optional parameters for the query
+     * @returns Query key array, with params included only when necessary
+     *
+     * @description
+     * This method creates React Query compatible keys that include parameters when present.
+     * The return type is conditionally typed based on whether the query requires parameters.
+     *
+     * @example
+     * ```typescript
+     * // Returns ['getUser', 'user-123']
+     * const keyWithParams = operations.getQueryKey('getUser', 'user-123')
+     *
+     * // Returns ['getUsers']
+     * const keyWithoutParams = operations.getQueryKey('getUsers')
+     * ```
+     */
+    getQueryKey<K extends keyof TQueries>(queryKey: K, params?: InferQueryParams<TQueries[K]>): QueryKey;
+    /**
+     * Generates a mutation key for React Query
+     * @template K - The mutation key type
+     * @param mutationKey - The name of the mutation
+     * @returns Mutation key array containing only the mutation name
+     *
+     * @example
+     * ```typescript
+     * // Returns ['createUser']
+     * const mutationKey = operations.getMutationKey('createUser')
+     * ```
+     */
+    getMutationKey<K extends keyof TMutations>(mutationKey: K): QueryKey;
+    /**
+     * Prefetches a query to populate the cache ahead of time
+     * @template K - The query key type
+     * @param queryKey - The name of the registered query to prefetch
+     * @param params - Parameters to pass to the query function (optional if query doesn't require params)
+     * @param options - React Query prefetch options
+     * @returns Promise that resolves when the prefetch is complete
+     *
+     * @example
+     * ```typescript
+     * // Prefetch user data when hovering over a user link
+     * const handleUserHover = async (userId: string) => {
+     *   await operations.prefetchQuery('getUser', userId, {
+     *     staleTime: 5 * 60 * 1000 // 5 minutes
+     *   })
+     * }
+     *
+     * // Prefetch data on route change
+     * useEffect(() => {
+     *   operations.prefetchQuery('getUsers', { status: 'active' })
+     * }, [])
+     * ```
+     */
+    prefetchQuery<K extends keyof TQueries, T = InferQueryReturn<TQueries[K]>>(queryKey: K, params?: InferQueryParams<TQueries[K]>, options?: FetchQueryOptions<InferQueryReturn<TQueries[K]>, Error, T, QueryKey, never>): Promise<void>;
+    /**
+     * Retrieves cached query data if it exists
+     * @template K - The query key type
+     * @template T - The expected return type (defaults to inferred query return type)
+     * @param queryKey - The name of the registered query
+     * @param params - Parameters used when the query was cached (optional if query doesn't require params)
+     * @returns The cached data if it exists, undefined otherwise
+     *
+     * @example
+     * ```typescript
+     * // Get cached user data
+     * const cachedUser = operations.getQueryData('getUser', 'user-123')
+     * if (cachedUser) {
+     *   console.log('User already in cache:', cachedUser.name)
+     * }
+     *
+     * // Check if users list is cached before showing loading state
+     * const cachedUsers = operations.getQueryData('getUsers')
+     * const showSkeleton = !cachedUsers
+     *
+     * // Access cached data in event handlers
+     * const handleUserAction = () => {
+     *   const currentUser = operations.getQueryData('getCurrentUser')
+     *   if (currentUser?.role === 'admin') {
+     *     // Perform admin action
+     *   }
+     * }
+     * ```
+     */
+    getQueryData<K extends keyof TQueries, T = InferQueryReturn<TQueries[K]>>(queryKey: K, params?: InferQueryParams<TQueries[K]>, options?: FetchQueryOptions<InferQueryReturn<TQueries[K]>, Error, T, QueryKey, never>): Promise<T | undefined>;
+}
+//# sourceMappingURL=index.d.ts.map

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

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

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

@@ -0,0 +1,42 @@
+import { QueryClient } from '../../types';
+import { QueryClientEnhanced } from '../QueryClientEnhanced';
+/**
+ * Configuration options for QueryOperations
+ */
+export type QueryOperationsOptions = {
+    /** The React Query client instance */
+    queryClient: QueryClient | QueryClientEnhanced;
+};
+/**
+ * Generic mutation function type
+ * @template T - The input data type
+ * @template R - The return data type
+ */
+export type MutationFn<T = any, R = any> = (data: T) => Promise<R>;
+/**
+ * Generic query function type
+ * @template T - The parameters type
+ * @template R - The return data type
+ */
+export type QueryFn<T = any, R = any> = (params?: T) => Promise<R>;
+/**
+ * Utility type to infer mutation function parameters
+ * @template T - The mutation function type
+ */
+export type InferMutationParams<T> = T extends MutationFn<infer P, any> ? P : never;
+/**
+ * Utility type to infer mutation function return type
+ * @template T - The mutation function type
+ */
+export type InferMutationReturn<T> = T extends MutationFn<any, infer R> ? R : never;
+/**
+ * Utility type to infer query function parameters
+ * @template T - The query function type
+ */
+export type InferQueryParams<T> = T extends QueryFn<infer P, any> ? P : never;
+/**
+ * Utility type to infer query function return type
+ * @template T - The query function type
+ */
+export type InferQueryReturn<T> = T extends QueryFn<any, infer R> ? R : never;
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/lib/QueryOperations/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,EAAE,mBAAmB,EAAE,MAAM,wBAAwB,CAAA;AAE5D;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC,sCAAsC;IACtC,WAAW,EAAE,WAAW,GAAG,mBAAmB,CAAA;CAC/C,CAAA;AAED;;;;GAIG;AACH,MAAM,MAAM,UAAU,CAAC,CAAC,GAAG,GAAG,EAAE,CAAC,GAAG,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAA;AAElE;;;;GAIG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,GAAG,GAAG,EAAE,CAAC,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAA;AAElE;;;GAGG;AACH,MAAM,MAAM,mBAAmB,CAAC,CAAC,IAAI,CAAC,SAAS,UAAU,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAA;AAEnF;;;GAGG;AACH,MAAM,MAAM,mBAAmB,CAAC,CAAC,IAAI,CAAC,SAAS,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAA;AAEnF;;;GAGG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,CAAC,SAAS,OAAO,CAAC,MAAM,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAA;AAE7E;;;GAGG;AACH,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,CAAC,SAAS,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAA"}

package/dist/lib/index.d.ts

@@ -0,0 +1,6 @@
+export * from './QueryClientEnhanced';
+export * from './QueryKeys';
+export * from './Mutations';
+export * from './QueryManager';
+export * from './QueryOperations';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/index.ts"],"names":[],"mappings":"AAAA,cAAc,uBAAuB,CAAA;AACrC,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,mBAAmB,CAAA"}

package/dist/types/core.d.ts

@@ -0,0 +1,29 @@
+import { UseInfiniteQueryResult, useQueryClient } from '@tanstack/react-query';
+import { QueryClientEnhanced } from '../lib';
+/** Minimum shape required for any entity managed by QueryManager. */
+export type QueryItem = {
+    id: string | number;
+};
+/** Cursor value used to request a specific page in an infinite list query. */
+export type PageParam = number;
+/** Raw page payload returned by `listFn` — a flat array of items for one page. */
+export type ListPaginationResponse<T extends QueryItem> = T[];
+/** Constructor options for `QueryManager`. All `*Fn` fields are optional; omitting one disables the corresponding operation and its generated hooks. */
+export type QueryManagerOptions<T extends QueryItem, F> = {
+    name: string;
+    queryClient: ReturnType<typeof useQueryClient> | QueryClientEnhanced;
+    listFn?: (limit: number, offset: number, filters: F) => Promise<ListPaginationResponse<T>>;
+    /** Page size sent to `listFn`. Defaults to 10 when omitted. */
+    listLimit?: number;
+    /** Side-effect hook called on every render with the current infinite-list query result. Useful for syncing list state into external stores. */
+    useListEffect?: (listQuery: UseInfiniteQueryResult<{
+        pageParams: number[];
+        pages: ListPaginationResponse<T>[];
+        allItems: T[];
+    }, Error>) => void;
+    retrieveFn?: (id: T['id']) => Promise<T>;
+    createFn?: (data: Partial<T>) => Promise<T>;
+    updateFn?: (data: Partial<T>) => Promise<T>;
+    deleteFn?: (id: T['id']) => Promise<T['id']>;
+};
+//# sourceMappingURL=core.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../src/types/core.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAC9E,OAAO,EAAE,mBAAmB,EAAE,MAAM,QAAQ,CAAA;AAE5C,qEAAqE;AACrE,MAAM,MAAM,SAAS,GAAG;IACtB,EAAE,EAAE,MAAM,GAAG,MAAM,CAAA;CACpB,CAAA;AAED,8EAA8E;AAC9E,MAAM,MAAM,SAAS,GAAG,MAAM,CAAA;AAE9B,kFAAkF;AAClF,MAAM,MAAM,sBAAsB,CAAC,CAAC,SAAS,SAAS,IAAI,CAAC,EAAE,CAAA;AAE7D,wJAAwJ;AACxJ,MAAM,MAAM,mBAAmB,CAAC,CAAC,SAAS,SAAS,EAAE,CAAC,IAAI;IACxD,IAAI,EAAE,MAAM,CAAA;IAEZ,WAAW,EAAE,UAAU,CAAC,OAAO,cAAc,CAAC,GAAG,mBAAmB,CAAA;IAEpE,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,KAAK,OAAO,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC,CAAA;IAE1F,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAA;IAElB,+IAA+I;IAC/I,aAAa,CAAC,EAAE,CAAC,SAAS,EAAE,sBAAsB,CAAC;QACjD,UAAU,EAAE,MAAM,EAAE,CAAA;QACpB,KAAK,EAAE,sBAAsB,CAAC,CAAC,CAAC,EAAE,CAAA;QAClC,QAAQ,EAAE,CAAC,EAAE,CAAA;KACd,EAAE,KAAK,CAAC,KAAK,IAAI,CAAA;IAElB,UAAU,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAA;IAExC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAA;IAE3C,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAA;IAE3C,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAA;CAC7C,CAAA"}

package/dist/types/create.d.ts

@@ -0,0 +1,21 @@
+import { UseMutationOptions } from '@tanstack/react-query';
+import { QueryItem } from './core';
+import { RemovedItemMap } from './utility';
+/** Rollback context threaded through an optimistic create mutation. `tempId` identifies the placeholder item inserted before the server responds. */
+export type CreateMutationCtx = {
+    tempId?: QueryItem['id'];
+};
+/** Options forwarded to React Query's `useMutation` for a create operation. `mutationKey` and `mutationFn` are managed internally. */
+export type CreateMutationOptions<T extends QueryItem, F> = Omit<UseMutationOptions<T, Error, Partial<T>, CreateMutationCtx | undefined>, 'mutationKey' | 'mutationFn'> & {
+    /** Insert a placeholder item immediately and replace it on success; roll back on error. */
+    optimistic?: boolean;
+    /** List query filters active at the time of the create, used to target the correct cached list for the optimistic insert. */
+    listFilters?: F;
+    /**
+     * Where to insert the item in the cached list.
+     * - `'start'` / `'end'` — prepend or append to the flat item array.
+     * - `RemovedItemMap` — re-insert at the exact page/index coordinates recorded during a previous delete (used internally for rollback).
+     */
+    appendTo?: RemovedItemMap | 'start' | 'end';
+};
+//# sourceMappingURL=create.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../../src/types/create.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAA;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAA;AAClC,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAE1C,qJAAqJ;AACrJ,MAAM,MAAM,iBAAiB,GAAG;IAC9B,MAAM,CAAC,EAAE,SAAS,CAAC,IAAI,CAAC,CAAA;CACzB,CAAA;AAED,sIAAsI;AACtI,MAAM,MAAM,qBAAqB,CAAC,CAAC,SAAS,SAAS,EAAE,CAAC,IAAI,IAAI,CAC9D,kBAAkB,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,iBAAiB,GAAC,SAAS,CAAC,EACrE,aAAa,GAAG,YAAY,CAC7B,GAAG;IACF,2FAA2F;IAC3F,UAAU,CAAC,EAAE,OAAO,CAAA;IACpB,6HAA6H;IAC7H,WAAW,CAAC,EAAE,CAAC,CAAA;IACf;;;;OAIG;IACH,QAAQ,CAAC,EAAE,cAAc,GAAG,OAAO,GAAG,KAAK,CAAA;CAC5C,CAAA"}

package/dist/types/delete.d.ts

@@ -0,0 +1,18 @@
+import { UseMutationOptions } from '@tanstack/react-query';
+import { QueryItem } from './core';
+import { RemovedItemMap } from './utility';
+/**
+ * Rollback context captured before an optimistic delete.
+ * `removedAt` records the exact page/index coordinates of the removed item so it can be re-inserted at the same position if the mutation fails.
+ * `null` means the item was not found in any cached page.
+ */
+export type DeleteMutationCtx<T> = {
+    previousItem: T | undefined;
+    removedAt: RemovedItemMap | null;
+};
+/** Options forwarded to React Query's `useMutation` for a delete operation. `mutationKey` and `mutationFn` are managed internally. */
+export type DeleteMutationOptions<T extends QueryItem, F> = Omit<UseMutationOptions<unknown, Error, T['id'], DeleteMutationCtx<T>>, 'mutationKey' | 'mutationFn'> & {
+    /** Remove the item from every cached list page immediately and restore it on error. */
+    optimistic?: boolean;
+};
+//# sourceMappingURL=delete.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"delete.d.ts","sourceRoot":"","sources":["../../src/types/delete.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAA;AAC1D,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAA;AAClC,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAE1C;;;;GAIG;AACH,MAAM,MAAM,iBAAiB,CAAC,CAAC,IAAI;IACjC,YAAY,EAAE,CAAC,GAAG,SAAS,CAAA;IAC3B,SAAS,EAAE,cAAc,GAAG,IAAI,CAAA;CACjC,CAAA;AAED,sIAAsI;AACtI,MAAM,MAAM,qBAAqB,CAAC,CAAC,SAAS,SAAS,EAAE,CAAC,IAAI,IAAI,CAC9D,kBAAkB,CAAC,OAAO,EAAE,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,EAAE,iBAAiB,CAAC,CAAC,CAAC,CAAC,EACjE,aAAa,GAAG,YAAY,CAC7B,GAAG;IACF,uFAAuF;IACvF,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB,CAAA"}

package/dist/types/index.d.ts

@@ -0,0 +1,8 @@
+export * from './core';
+export * from './list';
+export * from './utility';
+export * from './retrieve';
+export * from './create';
+export * from './update';
+export * from './delete';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAA;AACtB,cAAc,QAAQ,CAAA;AACtB,cAAc,WAAW,CAAA;AACzB,cAAc,YAAY,CAAA;AAC1B,cAAc,UAAU,CAAA;AACxB,cAAc,UAAU,CAAA;AACxB,cAAc,UAAU,CAAA"}

package/dist/types/list.d.ts

@@ -0,0 +1,19 @@
+import { QueryKey, UseInfiniteQueryOptions } from '@tanstack/react-query';
+import { ListPaginationResponse, PageParam, QueryItem } from './core';
+/**
+ * Normalised shape of the infinite-query cache entry.
+ * `allItems` is a convenience flat-merge of every page's items — use it for rendering; use `pages` when you need per-page boundaries.
+ */
+export type ListSelector<T extends QueryItem> = {
+    pageParams: PageParam[];
+    pages: ListPaginationResponse<T>[];
+    allItems: T[];
+};
+type InfiniteQueryOptions<T extends QueryItem> = UseInfiniteQueryOptions<ListPaginationResponse<T>, Error, ListSelector<T>, QueryKey, PageParam>;
+/** Options accepted by the generated `useList` hook. Extends React Query's infinite-query options; `limit` and `filters` are forwarded to `listFn`. */
+export type ListQueryOptions<T extends QueryItem, F> = Partial<InfiniteQueryOptions<T>> & {
+    limit?: number;
+    filters?: F;
+};
+export {};
+//# sourceMappingURL=list.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../src/types/list.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,uBAAuB,EAAE,MAAM,uBAAuB,CAAA;AACzE,OAAO,EAAE,sBAAsB,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAA;AAErE;;;GAGG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,SAAS,IAAI;IAC9C,UAAU,EAAE,SAAS,EAAE,CAAA;IACvB,KAAK,EAAE,sBAAsB,CAAC,CAAC,CAAC,EAAE,CAAA;IAClC,QAAQ,EAAE,CAAC,EAAE,CAAA;CACd,CAAA;AAED,KAAK,oBAAoB,CAAC,CAAC,SAAS,SAAS,IAAI,uBAAuB,CACtE,sBAAsB,CAAC,CAAC,CAAC,EACzB,KAAK,EACL,YAAY,CAAC,CAAC,CAAC,EACf,QAAQ,EACR,SAAS,CACV,CAAA;AAED,uJAAuJ;AACvJ,MAAM,MAAM,gBAAgB,CAAC,CAAC,SAAS,SAAS,EAAE,CAAC,IAAI,OAAO,CAAC,oBAAoB,CAAC,CAAC,CAAC,CAAC,GAAG;IACxF,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,OAAO,CAAC,EAAE,CAAC,CAAA;CACZ,CAAA"}

package/dist/types/retrieve.d.ts

@@ -0,0 +1,17 @@
+import { QueryKey, UndefinedInitialDataOptions } from '@tanstack/react-query';
+import { QueryItem } from './core';
+/** Pass-through options forwarded to React Query's `useQuery` for a retrieve query. `queryKey` and `queryFn` are managed internally and cannot be overridden. */
+export type RetrieveQueryOptions<T extends QueryItem> = Omit<UndefinedInitialDataOptions<T, Error, T, QueryKey>, 'queryKey' | 'queryFn'>;
+export type RetrieveDataOptions = {
+    /**
+     * When `true`, skips the network fetch and returns only what is already in the cache.
+     * When `false` (default), falls back to a network fetch if the cache is empty.
+     */
+    onlyQueryData?: boolean;
+    /**
+     * When `true`, searches all cached list pages for the item before issuing a dedicated retrieve request.
+     * Avoids a redundant round-trip when the item was already loaded by a list query.
+     */
+    deepSearch?: boolean;
+};
+//# sourceMappingURL=retrieve.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"retrieve.d.ts","sourceRoot":"","sources":["../../src/types/retrieve.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,2BAA2B,EAAE,MAAM,uBAAuB,CAAA;AAC7E,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAA;AAElC,iKAAiK;AACjK,MAAM,MAAM,oBAAoB,CAAC,CAAC,SAAS,SAAS,IAAI,IAAI,CAC1D,2BAA2B,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,QAAQ,CAAC,EAClD,UAAU,GAAG,SAAS,CACvB,CAAA;AAED,MAAM,MAAM,mBAAmB,GAAG;IAChC;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAA;IACvB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAA;CACrB,CAAA"}