@codeleap/query 6.2.3 → 6.8.0

package/src/lib/QueryOperations/types.ts

@@ -1,11 +1,12 @@
 import { QueryClient } from '../../types'
+import { QueryClientEnhanced } from '../QueryClientEnhanced'
 
 /**
  * Configuration options for QueryOperations
  */
 export type QueryOperationsOptions = {
   /** The React Query client instance */
-  queryClient: QueryClient
+  queryClient: QueryClient | QueryClientEnhanced
 }
 
 /**
@@ -13,14 +14,14 @@ export type QueryOperationsOptions = {
  * @template T - The input data type
  * @template R - The return data type
  */
-export type MutationFn<T = any, R = any> = (data: T) => Promise<R> | R
+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> | R
+export type QueryFn<T = any, R = any> = (params?: T) => Promise<R> 
 
 /**
  * Utility type to infer mutation function parameters

package/src/tests/setup.ts

@@ -2,6 +2,7 @@ import { afterEach, beforeEach } from 'bun:test'
 import { QueryClient } from '@tanstack/react-query'
 import { cleanup } from '@testing-library/react'
 
+/** Fixture entity used across `@codeleap/query` test suites. Satisfies `QueryItem` via the `id` field. */
 export interface TestUser {
   id: string
   name: string
@@ -10,11 +11,16 @@ export interface TestUser {
   createdAt: string
 }
 
+/** Filter shape accepted by the mock list API for `TestUser` fixtures. */
 export interface TestUserFilters {
   status?: 'active' | 'inactive'
   search?: string
 }
 
+/**
+ * Creates a `QueryClient` pre-configured for unit tests: retries disabled, zero garbage-collection time.
+ * Construct a fresh instance per test to prevent cache bleed between tests.
+ */
 export const createTestQueryClient = () => {
   return new QueryClient({
     defaultOptions: {
@@ -29,6 +35,7 @@ export const createTestQueryClient = () => {
   })
 }
 
+/** Returns a single `TestUser` fixture. Pass `overrides` to pin specific fields; all others default to deterministic placeholder values. */
 export const createMockUser = (overrides: Partial<TestUser> = {}): TestUser => ({
   id: `user-${Date.now()}-${Math.random()}`,
   name: 'John Doe',
@@ -38,6 +45,7 @@ export const createMockUser = (overrides: Partial<TestUser> = {}): TestUser => (
   ...overrides,
 })
 
+/** Returns an array of `count` distinct `TestUser` fixtures with sequential ids (`user-1`, `user-2`, …). */
 export const createMockUsers = (count: number): TestUser[] => {
   return Array.from({ length: count }, (_, i) => createMockUser({
     id: `user-${i + 1}`,
@@ -46,6 +54,11 @@ export const createMockUsers = (count: number): TestUser[] => {
   }))
 }
 
+/**
+ * Returns a self-contained set of in-memory CRUD functions compatible with `QueryManagerOptions`.
+ * All five API functions share the same internal `users` array — mutations are reflected immediately in subsequent reads without any async delay.
+ * The returned `getUsersArray`, `addUser`, `clearUsers`, and `setUsers` helpers let tests seed or inspect state directly without going through the API layer.
+ */
 export const createMockApiFunctions = () => {
   const users: TestUser[] = []
 
@@ -116,4 +129,5 @@ afterEach(() => {
   cleanup()
 })
 
+/** Pauses execution for `ms` milliseconds. Use in tests to allow async state updates to settle before asserting. */
 export const waitFor = (ms: number) => new Promise(resolve => setTimeout(resolve, ms))

package/src/types/core.ts

@@ -1,22 +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>
+  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>[]

package/src/types/create.ts

@@ -2,15 +2,24 @@ 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>,
+  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'
 }

package/src/types/delete.ts

@@ -2,14 +2,21 @@ 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
+  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
 }

package/src/types/list.ts

@@ -1,6 +1,10 @@
 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>[]
@@ -15,6 +19,7 @@ type InfiniteQueryOptions<T extends QueryItem> = UseInfiniteQueryOptions<
   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

package/src/types/retrieve.ts

@@ -1,12 +1,21 @@
 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
 }

package/src/types/update.ts

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

package/src/types/utility.ts

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

package/src/utils/misc.ts

@@ -36,8 +36,10 @@ function uuidV4() {
   return uuid
 }
 
+/** Prefix used on every optimistically-created item id. Check `id.startsWith(tempIdPrefix)` to distinguish placeholder items from server-assigned ids. */
 export const tempIdPrefix = 'temp-id'
 
+/** Returns a unique placeholder id for optimistic creates. The format is `temp-id-<uuidv4>` and is guaranteed never to collide with server-assigned ids. */
 export const generateTempId = () => {
   return tempIdPrefix + '-' + uuidV4()
 }

package/package.json.bak

@@ -1,27 +0,0 @@
-{
-  "name": "@codeleap/query",
-  "version": "6.2.3",
-  "main": "src/index.ts",
-  "license": "UNLICENSED",
-  "repository": {
-    "url": "https://github.com/codeleap-uk/internal-libs-monorepo.git",
-    "type": "git",
-    "directory": "packages/query"
-  },
-  "devDependencies": {
-    "@codeleap/config": "workspace:*",
-    "@codeleap/types": "workspace:*",
-    "ts-node-dev": "1.1.8"
-  },
-  "scripts": {
-    "build": "echo 'No build needed'"
-  },
-  "peerDependencies": {
-    "@codeleap/types": "workspace:*",
-    "typescript": "5.5.2",
-    "@tanstack/react-query": "5.89.0"
-  },
-  "dependencies": {
-    "fast-deep-equal": "3.1.3"
-  }
-}