@codeleap/query 7.0.2 → 7.1.2

package/src/lib/QueryManager.ts

@@ -1,8 +1,8 @@
 import { FetchInfiniteQueryOptions, FetchQueryOptions, InfiniteData, MutationFunctionContext, QueryClient, QueryKey, useInfiniteQuery, useMutation, useQuery } from '@tanstack/react-query'
-import { useCallback } from 'react'
+import { useCallback, useMemo } from 'react'
 import { createQueryKeys, QueryKeys } from './QueryKeys'
 import { createMutations, Mutations } from './Mutations'
-import { CreateMutationCtx, CreateMutationOptions, ListPaginationResponse, ListQueryOptions, PageParam, QueryItem, QueryManagerOptions, RetrieveQueryOptions, UpdateMutationCtx, UpdateMutationOptions, DeleteMutationCtx, DeleteMutationOptions } from '../types'
+import { CreateMutationCtx, CreateMutationOptions, ListPaginationResponse, ListQueryOptions, ListResponseMeta, PageParam, QueryItem, QueryManagerOptions, RetrieveQueryOptions, UpdateMutationCtx, UpdateMutationOptions, DeleteMutationCtx, DeleteMutationOptions } from '../types'
 import { generateTempId } from '../utils'
 import { TypeGuards } from '@codeleap/types'
 import { QueryClientEnhanced } from './QueryClientEnhanced'
@@ -11,21 +11,23 @@ import { QueryClientEnhanced } from './QueryClientEnhanced'
  * 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
- * 
+ * @template M - Optional metadata shape returned alongside list items (e.g. `{ count: number }`). Defaults to `Record<string, unknown>`.
+ *
  * @description
  * QueryManager provides a complete solution for managing list and individual item queries with:
  * - Infinite scroll pagination for lists
+ * - Support for list response metadata (e.g. total count) via envelope responses
  * - Optimistic updates for create, update, and delete operations
  * - Automatic cache synchronization between list and individual queries
  * - Built-in error handling and rollback mechanisms
  */
-export class QueryManager<T extends QueryItem, F> {
+export class QueryManager<T extends QueryItem, F, M extends ListResponseMeta = ListResponseMeta> {
   queryClient: QueryClient
   /**
    * Creates a new QueryManager instance
    * @param options - Configuration options for the query manager
    */
-  constructor(private options: QueryManagerOptions<T, F>) {
+  constructor(private options: QueryManagerOptions<T, F, M>) {
     this.queryClient = options.queryClient instanceof QueryClientEnhanced ? options.queryClient.client : options.queryClient
     this.queryKeys = createQueryKeys<T, F>(options.name, this.queryClient)
     this.mutations = createMutations<T, F>(this.queryKeys, this.queryClient, options.name)
@@ -62,17 +64,28 @@ export class QueryManager<T extends QueryItem, 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
-   * 
+   * @returns Object containing items array, response metadata, query key, and query object
+   *
+   * @description
+   * When `listFn` returns a `ListPaginationEnvelope` (an object with `listItems` and extra fields),
+   * the extra fields are exposed as typed `meta` in the return value. When `listFn` returns a plain
+   * array, `meta` is `null`. Meta is stored in the query cache under a companion key, so it
+   * survives component remounts and is available even when React Query serves from cache.
+   *
    * @example
    * ```typescript
+   * // Plain array response (backward compatible)
    * const { items, query } = queryManager.useList({
    *   filters: { status: 'active' },
    *   limit: 20
    * })
+   *
+   * // Envelope response with metadata
+   * const { items, meta } = queryManager.useList({ filters })
+   * console.log(meta?.count) // total item count from the API
    * ```
    */
-  useList(options: ListQueryOptions<T, F> = {}) {
+  useList(options: ListQueryOptions<T, F, M> = {}) {
     const {
       limit,
       filters,
@@ -83,15 +96,19 @@ export class QueryManager<T extends QueryItem, F> {
 
     const queryKey = this.queryKeys.useListKeyWithFilters(filters)
 
+    const metaQueryKey = useMemo(() => [...queryKey, '__meta'], [queryKey])
+
     const onSelect = useCallback((data: InfiniteData<ListPaginationResponse<T>, PageParam>) => {
       const pages = data?.pages ?? []
+      const meta = this.queryClient.getQueryData<M>(metaQueryKey) ?? null
 
       return {
         pageParams: data?.pageParams,
         pages,
         allItems: pages.flat(),
+        meta,
       }
-    }, [])
+    }, [metaQueryKey])
 
     const query = useInfiniteQuery({
       queryKey,
@@ -99,9 +116,19 @@ export class QueryManager<T extends QueryItem, F> {
       queryFn: async (query) => {
         const listOffset = query?.pageParam ?? 0
 
-        const data = await this.options?.listFn?.(listLimit, listOffset, filters as F)
+        const raw = await this.options?.listFn?.(listLimit, listOffset, filters as F)
+
+        if (TypeGuards.isArray(raw)) {
+          return raw as ListPaginationResponse<T>
+        }
+
+        if (raw && typeof raw === 'object' && 'listItems' in raw) {
+          const { listItems, ...meta } = raw
+          this.queryClient.setQueryData(metaQueryKey, meta as unknown as M)
+          return TypeGuards.isArray(listItems) ? listItems : [] as ListPaginationResponse<T>
+        }
 
-        return TypeGuards.isArray(data) ? data : [] as ListPaginationResponse<T>
+        return [] as ListPaginationResponse<T>
       },
 
       initialPageParam: 0,
@@ -137,8 +164,10 @@ export class QueryManager<T extends QueryItem, F> {
 
     return {
       items,
+      meta: query.data?.meta ?? null,
       queryKey,
       query,
+      listLimit
     }
   }
 
@@ -498,10 +527,12 @@ export class QueryManager<T extends QueryItem, F> {
    * @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.
-   * 
+   * Handles both plain array and envelope responses from `listFn`, but only caches the
+   * items — metadata is discarded during prefetch and populated on the first client-side fetch.
+   *
    * @example
    * ```typescript
    * const handle = () => {
@@ -510,7 +541,6 @@ export class QueryManager<T extends QueryItem, F> {
    *     { staleTime: 5 * 60 * 1000 }
    *   )
    * }
-   * 
    * ```
    */
   prefetchList(
@@ -523,7 +553,17 @@ export class QueryManager<T extends QueryItem, F> {
       ...prefetchOptions as any,
       initialPageParam: initialOffset,
       queryKey: this.queryKeys.listKeyWithFilters(filters),
-      queryFn: () => this.options.listFn!(this.options.listLimit ?? 10, initialOffset, filters as F),
+      queryFn: async () => {
+        const raw = await this.options.listFn!(this.options.listLimit ?? 10, initialOffset, filters as F)
+
+        if (TypeGuards.isArray(raw)) return raw
+
+        if (raw && typeof raw === 'object' && 'listItems' in raw) {
+          return TypeGuards.isArray(raw.listItems) ? raw.listItems : []
+        }
+
+        return []
+      },
     })
   }
 }

package/src/types/core.ts

@@ -12,13 +12,31 @@ 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> = {
+/** Extra metadata from a paginated API response (everything except the items array). */
+export type ListResponseMeta = Record<string, unknown>
+
+/** Envelope returned by `listFn` when it includes metadata beyond the items array. `listItems` holds the page items; all other fields are treated as metadata. */
+export type ListPaginationEnvelope<T extends QueryItem, M extends ListResponseMeta = ListResponseMeta> = {
+  listItems: T[]
+} & M
+
+/** What `listFn` is allowed to return: a flat array (backward compat) or an envelope with metadata. */
+export type ListFnResponse<T extends QueryItem, M extends ListResponseMeta = ListResponseMeta> =
+  | T[]
+  | ListPaginationEnvelope<T, M>
+
+/**
+ * Constructor options for `QueryManager`. All `*Fn` fields are optional; omitting one disables the corresponding operation and its generated hooks.
+ * @template T - The query item type that extends QueryItem
+ * @template F - The filter type used for list queries
+ * @template M - Optional metadata shape returned alongside list items (e.g. `{ count: number }`). Defaults to `Record<string, unknown>`.
+ */
+export type QueryManagerOptions<T extends QueryItem, F, M extends ListResponseMeta = ListResponseMeta> = {
   name: string
 
   queryClient: ReturnType<typeof useQueryClient> | QueryClientEnhanced
 
-  listFn?: (limit: number, offset: number, filters: F) => Promise<ListPaginationResponse<T>>
+  listFn?: (limit: number, offset: number, filters: F) => Promise<ListFnResponse<T, M>>
 
   /** Page size sent to `listFn`. Defaults to 10 when omitted. */
   listLimit?: number
@@ -28,6 +46,7 @@ export type QueryManagerOptions<T extends QueryItem, F> = {
     pageParams: number[]
     pages: ListPaginationResponse<T>[]
     allItems: T[]
+    meta: M | null
   }, Error>) => void
 
   retrieveFn?: (id: T['id']) => Promise<T>

package/src/types/list.ts

@@ -1,26 +1,28 @@
 import { QueryKey, UseInfiniteQueryOptions } from '@tanstack/react-query'
-import { ListPaginationResponse, PageParam, QueryItem } from './core'
+import { ListPaginationResponse, ListResponseMeta, 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.
+ * `meta` holds extra data from the most recent `listFn` response (e.g. total count), or `null` when `listFn` returns a plain array.
  */
-export type ListSelector<T extends QueryItem> = {
+export type ListSelector<T extends QueryItem, M extends ListResponseMeta = ListResponseMeta> = {
   pageParams: PageParam[]
   pages: ListPaginationResponse<T>[]
   allItems: T[]
+  meta: M | null
 }
 
-type InfiniteQueryOptions<T extends QueryItem> = UseInfiniteQueryOptions<
+type InfiniteQueryOptions<T extends QueryItem, M extends ListResponseMeta = ListResponseMeta> = UseInfiniteQueryOptions<
   ListPaginationResponse<T>,
   Error,
-  ListSelector<T>,
+  ListSelector<T, M>,
   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>> & {
+export type ListQueryOptions<T extends QueryItem, F, M extends ListResponseMeta = ListResponseMeta> = Partial<InfiniteQueryOptions<T, M>> & {
   limit?: number
   filters?: F
 }