@simplix-react/react 0.0.1 → 0.0.3

package/README.md

@@ -0,0 +1,234 @@
+# @simplix-react/react
+
+Type-safe React Query hooks derived automatically from an `@simplix-react/contract` API contract.
+
+> **Prerequisites:** Requires a contract defined with `@simplix-react/contract`.
+
+## Installation
+
+```bash
+pnpm add @simplix-react/react
+```
+
+**Peer dependencies:**
+
+| Package | Version |
+| --- | --- |
+| `@simplix-react/contract` | workspace |
+| `@tanstack/react-query` | >= 5.0.0 |
+| `react` | >= 18.0.0 |
+| `zod` | >= 4.0.0 |
+
+## Quick Example
+
+```ts
+import { defineApi, simpleQueryBuilder } from "@simplix-react/contract";
+import { deriveHooks } from "@simplix-react/react";
+import { z } from "zod";
+
+// 1. Define the contract
+const projectContract = defineApi({
+  domain: "project",
+  basePath: "/api",
+  entities: {
+    task: {
+      path: "/tasks",
+      schema: z.object({ id: z.string(), title: z.string(), status: z.string() }),
+      createSchema: z.object({ title: z.string(), status: z.string() }),
+      updateSchema: z.object({ title: z.string().optional(), status: z.string().optional() }),
+    },
+  },
+  queryBuilder: simpleQueryBuilder,
+});
+
+// 2. Derive hooks — one call generates everything
+const hooks = deriveHooks(projectContract);
+
+// 3. Use in components
+function TaskList() {
+  const { data: tasks, isLoading } = hooks.task.useList();
+  const createTask = hooks.task.useCreate();
+
+  if (isLoading) return <p>Loading...</p>;
+
+  return (
+    <ul>
+      {tasks?.map((task) => (
+        <li key={task.id}>{task.title}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+## API Overview
+
+The package exports a single function and a set of type definitions:
+
+| Export | Kind | Description |
+| --- | --- | --- |
+| `deriveHooks` | Function | Derives all hooks from a contract |
+| `EntityHooks` | Type | Hook interface for a single entity |
+| `OperationHooks` | Type | Hook interface for a custom operation |
+| `DerivedListHook` | Type | List query hook signature |
+| `DerivedGetHook` | Type | Detail query hook signature |
+| `DerivedCreateHook` | Type | Create mutation hook signature |
+| `DerivedUpdateHook` | Type | Update mutation hook signature |
+| `DerivedDeleteHook` | Type | Delete mutation hook signature |
+| `DerivedInfiniteListHook` | Type | Infinite list query hook signature |
+| `OperationMutationHook` | Type | Operation mutation hook signature |
+
+## Key Concepts
+
+### Hook Derivation
+
+`deriveHooks()` reads the entity and operation definitions from a contract and generates a typed hook object. Each entity key maps to an `EntityHooks` object, and each operation key maps to an `OperationHooks` object.
+
+```ts
+const hooks = deriveHooks(projectContract);
+// hooks.task    → EntityHooks<TaskSchema, CreateTaskSchema, UpdateTaskSchema>
+// hooks.archiveProject → OperationHooks<ArchiveInput, ArchiveOutput>
+```
+
+### Auto-Invalidation
+
+Mutation hooks automatically invalidate related queries:
+
+- **Entity mutations** (`useCreate`, `useUpdate`, `useDelete`) invalidate all queries under the entity's query key scope.
+- **Operation mutations** invalidate based on the `invalidates` function defined in the operation's contract configuration.
+
+No manual `queryClient.invalidateQueries()` calls are needed.
+
+### TanStack Query Options Passthrough
+
+All hooks accept TanStack Query options as their last argument. Query hooks accept all `UseQueryOptions` except `queryKey` and `queryFn`. Mutation hooks accept all `UseMutationOptions` except `mutationFn`.
+
+```ts
+// Pass query options
+const { data } = hooks.task.useList({ enabled: false });
+
+// Pass mutation options
+const createTask = hooks.task.useCreate(undefined, {
+  onSuccess: (data) => console.log("Created:", data),
+});
+```
+
+## Hook Reference
+
+### `useList`
+
+Fetches a list of entities. Supports three calling conventions:
+
+```ts
+// Top-level entity
+hooks.task.useList();
+hooks.task.useList({ enabled: isReady });
+
+// With filters/sort
+hooks.task.useList({
+  filters: { status: "open" },
+  sort: { field: "createdAt", direction: "desc" },
+});
+
+// Child entity with parent ID
+hooks.task.useList(projectId);
+hooks.task.useList(projectId, { filters: { status: "open" } });
+hooks.task.useList(projectId, { filters: { status: "open" } }, { enabled: isReady });
+```
+
+For child entities, the query is automatically disabled when `parentId` is falsy.
+
+### `useGet`
+
+Fetches a single entity by ID.
+
+```ts
+const { data: task } = hooks.task.useGet(taskId);
+const { data: task } = hooks.task.useGet(taskId, { staleTime: 5000 });
+```
+
+The query is automatically disabled when `id` is falsy.
+
+### `useCreate`
+
+Creates a new entity. For child entities, pass the parent ID.
+
+```ts
+// Top-level entity
+const createTask = hooks.task.useCreate();
+createTask.mutate({ title: "New task", status: "open" });
+
+// Child entity
+const createTask = hooks.task.useCreate(projectId);
+createTask.mutate({ title: "New task", status: "open" });
+```
+
+### `useUpdate`
+
+Updates an existing entity. Supports optimistic updates.
+
+```ts
+// Standard update
+const updateTask = hooks.task.useUpdate();
+updateTask.mutate({ id: taskId, dto: { status: "done" } });
+
+// Optimistic update — UI updates instantly, rolls back on error
+const updateTask = hooks.task.useUpdate({ optimistic: true });
+updateTask.mutate({ id: taskId, dto: { status: "done" } });
+```
+
+### `useDelete`
+
+Deletes an entity by ID.
+
+```ts
+const deleteTask = hooks.task.useDelete();
+deleteTask.mutate(taskId);
+```
+
+### `useInfiniteList`
+
+Fetches paginated data with cursor-based or offset-based pagination. Pagination is managed automatically based on the response's `meta` field.
+
+```ts
+const {
+  data,
+  fetchNextPage,
+  hasNextPage,
+  isFetchingNextPage,
+} = hooks.task.useInfiniteList(projectId, {
+  limit: 10,
+  filters: { status: "open" },
+  sort: { field: "createdAt", direction: "desc" },
+});
+
+// Access flattened data
+const allTasks = data?.pages.flatMap((page) => page.data) ?? [];
+```
+
+### Operation `useMutation`
+
+Custom operations defined in the contract each produce a `useMutation` hook.
+
+```ts
+const archiveProject = hooks.archiveProject.useMutation({
+  onSuccess: () => {
+    // Cache invalidation is already handled via the contract's `invalidates`
+    console.log("Project archived");
+  },
+});
+
+archiveProject.mutate({ projectId: "abc" });
+```
+
+## Related Packages
+
+| Package | Description |
+| --- | --- |
+| `@simplix-react/contract` | Define type-safe API contracts |
+| `@simplix-react/mock` | Generate MSW handlers from contracts for testing |
+| `@simplix-react/i18n` | i18next-based internationalization framework |
+
+---
+
+Next Step → `@simplix-react/mock`

package/dist/index.d.ts

@@ -1,13 +1,93 @@
-import { EntityDefinition, OperationDefinition, ApiContractConfig, QueryKeyFactory } from '@simplix-react/contract';
+import { ListParams, PageInfo, AnyEntityDef, AnyOperationDef, ApiContractConfig, QueryKeyFactory, OperationDefinition } from '@simplix-react/contract';
+import { UseMutationOptions, UseMutationResult, UseQueryOptions, UseQueryResult, UseInfiniteQueryResult } from '@tanstack/react-query';
 import { z } from 'zod';
-import { UseMutationOptions, UseMutationResult, UseQueryOptions, UseQueryResult } from '@tanstack/react-query';
 
 /**
- * Derived query hook with options passthrough (C8 fix)
+ * Represents a derived list query hook with overloaded call signatures.
+ *
+ * Supports three calling conventions:
+ * - `useList(options?)` — top-level entity list
+ * - `useList(params, options?)` — filtered/sorted list
+ * - `useList(parentId, params?, options?)` — child entity list
+ *
+ * All TanStack Query options except `queryKey` and `queryFn` can be passed through.
+ *
+ * @typeParam TData - The entity type returned by the query
+ *
+ * @example
+ * ```ts
+ * import { deriveHooks } from "@simplix-react/react";
+ *
+ * const hooks = deriveHooks(projectContract);
+ * const { data: tasks } = hooks.task.useList(projectId, {
+ *   filters: { status: "open" },
+ *   sort: { field: "createdAt", direction: "desc" },
+ * });
+ * ```
+ *
+ * @see {@link EntityHooks} for the complete set of entity hooks.
+ */
+type DerivedListHook<TData> = (parentIdOrParams?: string | ListParams, paramsOrOptions?: ListParams | Omit<UseQueryOptions<TData[], Error>, "queryKey" | "queryFn">, options?: Omit<UseQueryOptions<TData[], Error>, "queryKey" | "queryFn">) => UseQueryResult<TData[]>;
+/**
+ * Represents a derived detail query hook that fetches a single entity by ID.
+ *
+ * Automatically disables the query when `id` is falsy.
+ *
+ * @typeParam TData - The entity type returned by the query
+ *
+ * @example
+ * ```ts
+ * import { deriveHooks } from "@simplix-react/react";
+ *
+ * const hooks = deriveHooks(projectContract);
+ * const { data: task } = hooks.task.useGet(taskId);
+ * ```
+ *
+ * @see {@link EntityHooks} for the complete set of entity hooks.
  */
-type DerivedListHook<TData> = (parentId: string, options?: Omit<UseQueryOptions<TData[], Error>, "queryKey" | "queryFn">) => UseQueryResult<TData[]>;
 type DerivedGetHook<TData> = (id: string, options?: Omit<UseQueryOptions<TData, Error>, "queryKey" | "queryFn">) => UseQueryResult<TData>;
+/**
+ * Represents a derived create mutation hook.
+ *
+ * Automatically invalidates all entity queries on success.
+ * For child entities, accepts a `parentId` as the first argument.
+ *
+ * @typeParam TInput - The create DTO type (inferred from the entity's createSchema)
+ * @typeParam TOutput - The entity type returned after creation
+ *
+ * @example
+ * ```ts
+ * import { deriveHooks } from "@simplix-react/react";
+ *
+ * const hooks = deriveHooks(projectContract);
+ * const createTask = hooks.task.useCreate(projectId);
+ * createTask.mutate({ title: "New task", status: "open" });
+ * ```
+ *
+ * @see {@link EntityHooks} for the complete set of entity hooks.
+ */
 type DerivedCreateHook<TInput, TOutput> = (parentId?: string, options?: Omit<UseMutationOptions<TOutput, Error, TInput>, "mutationFn">) => UseMutationResult<TOutput, Error, TInput>;
+/**
+ * Represents a derived update mutation hook.
+ *
+ * Accepts `{ id, dto }` as mutation variables. Supports optimistic updates
+ * via the `optimistic` option. Automatically invalidates all entity queries
+ * on settlement.
+ *
+ * @typeParam TInput - The update DTO type (inferred from the entity's updateSchema)
+ * @typeParam TOutput - The entity type returned after update
+ *
+ * @example
+ * ```ts
+ * import { deriveHooks } from "@simplix-react/react";
+ *
+ * const hooks = deriveHooks(projectContract);
+ * const updateTask = hooks.task.useUpdate({ optimistic: true });
+ * updateTask.mutate({ id: taskId, dto: { status: "done" } });
+ * ```
+ *
+ * @see {@link EntityHooks} for the complete set of entity hooks.
+ */
 type DerivedUpdateHook<TInput, TOutput> = (options?: Omit<UseMutationOptions<TOutput, Error, {
     id: string;
     dto: TInput;
@@ -15,9 +95,78 @@ type DerivedUpdateHook<TInput, TOutput> = (options?: Omit<UseMutationOptions<TOu
     id: string;
     dto: TInput;
 }>;
+/**
+ * Represents a derived delete mutation hook.
+ *
+ * Accepts the entity ID as the mutation variable. Automatically invalidates
+ * all entity queries on success.
+ *
+ * @example
+ * ```ts
+ * import { deriveHooks } from "@simplix-react/react";
+ *
+ * const hooks = deriveHooks(projectContract);
+ * const deleteTask = hooks.task.useDelete();
+ * deleteTask.mutate(taskId);
+ * ```
+ *
+ * @see {@link EntityHooks} for the complete set of entity hooks.
+ */
 type DerivedDeleteHook = (options?: Omit<UseMutationOptions<void, Error, string>, "mutationFn">) => UseMutationResult<void, Error, string>;
 /**
- * Entity hooks derived from EntityDefinition
+ * Represents a derived infinite list query hook for cursor-based or offset-based pagination.
+ *
+ * Automatically determines the next page parameter from the response `meta` field.
+ * Pagination parameters are managed internally; callers provide only filters, sort,
+ * and an optional page size limit.
+ *
+ * @typeParam TData - The entity type returned in each page
+ *
+ * @example
+ * ```ts
+ * import { deriveHooks } from "@simplix-react/react";
+ *
+ * const hooks = deriveHooks(projectContract);
+ * const { data, fetchNextPage, hasNextPage } = hooks.task.useInfiniteList(
+ *   projectId,
+ *   { limit: 10, filters: { status: "open" } },
+ * );
+ * ```
+ *
+ * @see {@link EntityHooks} for the complete set of entity hooks.
+ */
+type DerivedInfiniteListHook<TData> = (parentId?: string, params?: Omit<ListParams, "pagination"> & {
+    limit?: number;
+}, options?: Record<string, unknown>) => UseInfiniteQueryResult<{
+    data: TData[];
+    meta: PageInfo;
+}, Error>;
+/**
+ * Represents the complete set of React Query hooks derived from an entity definition.
+ *
+ * Each entity in the contract produces an object conforming to this interface,
+ * with hooks for CRUD operations and infinite scrolling.
+ *
+ * @typeParam TSchema - The Zod schema defining the entity shape
+ * @typeParam TCreate - The Zod schema defining the create DTO shape
+ * @typeParam TUpdate - The Zod schema defining the update DTO shape
+ *
+ * @example
+ * ```ts
+ * import { deriveHooks } from "@simplix-react/react";
+ *
+ * const hooks = deriveHooks(projectContract);
+ *
+ * // hooks.task satisfies EntityHooks<TaskSchema, CreateTaskSchema, UpdateTaskSchema>
+ * const { data } = hooks.task.useList();
+ * const { data: single } = hooks.task.useGet(id);
+ * const create = hooks.task.useCreate();
+ * const update = hooks.task.useUpdate();
+ * const remove = hooks.task.useDelete();
+ * const infinite = hooks.task.useInfiniteList();
+ * ```
+ *
+ * @see {@link deriveHooks} for generating these hooks from a contract.
  */
 interface EntityHooks<TSchema extends z.ZodTypeAny, TCreate extends z.ZodTypeAny, TUpdate extends z.ZodTypeAny> {
     useList: DerivedListHook<z.infer<TSchema>>;
@@ -25,25 +174,107 @@ interface EntityHooks<TSchema extends z.ZodTypeAny, TCreate extends z.ZodTypeAny
     useCreate: DerivedCreateHook<z.infer<TCreate>, z.infer<TSchema>>;
     useUpdate: DerivedUpdateHook<z.infer<TUpdate>, z.infer<TSchema>>;
     useDelete: DerivedDeleteHook;
+    useInfiniteList: DerivedInfiniteListHook<z.infer<TSchema>>;
 }
 /**
- * Operation mutation hook
+ * Represents a derived mutation hook for a custom operation.
+ *
+ * Wraps the operation client function with TanStack Query's `useMutation`.
+ * All mutation options except `mutationFn` can be passed through.
+ *
+ * @typeParam TInput - The input type for the operation
+ * @typeParam TOutput - The output type for the operation
+ *
+ * @example
+ * ```ts
+ * import { deriveHooks } from "@simplix-react/react";
+ *
+ * const hooks = deriveHooks(projectContract);
+ * const archiveProject = hooks.archiveProject.useMutation();
+ * archiveProject.mutate({ projectId: "abc" });
+ * ```
+ *
+ * @see {@link OperationHooks} for the operation hooks container.
  */
 type OperationMutationHook<TInput, TOutput> = (options?: Omit<UseMutationOptions<TOutput, Error, TInput>, "mutationFn">) => UseMutationResult<TOutput, Error, TInput>;
+/**
+ * Represents the hook container for a custom operation defined in the contract.
+ *
+ * Each operation in the contract produces an object with a single `useMutation` hook.
+ * Cache invalidation is handled automatically based on the operation's `invalidates`
+ * configuration in the contract.
+ *
+ * @typeParam TInput - The Zod schema defining the operation input
+ * @typeParam TOutput - The Zod schema defining the operation output
+ *
+ * @example
+ * ```ts
+ * import { deriveHooks } from "@simplix-react/react";
+ *
+ * const hooks = deriveHooks(projectContract);
+ * const { mutate, isPending } = hooks.archiveProject.useMutation({
+ *   onSuccess: () => console.log("Project archived"),
+ * });
+ * ```
+ *
+ * @see {@link deriveHooks} for generating hooks from a contract.
+ */
 interface OperationHooks<TInput extends z.ZodTypeAny, TOutput extends z.ZodTypeAny> {
     useMutation: OperationMutationHook<z.infer<TInput>, z.infer<TOutput>>;
 }
 
-type AnyEntityDef = EntityDefinition<z.ZodTypeAny, z.ZodTypeAny, z.ZodTypeAny>;
-type AnyOperationDef = OperationDefinition<z.ZodTypeAny, z.ZodTypeAny>;
 /**
- * Derive React Query hooks from an API contract.
+ * Derives type-safe React Query hooks from an API contract.
+ *
+ * Generates a complete set of hooks for every entity and operation defined in
+ * the contract. Entity hooks include `useList`, `useGet`, `useCreate`,
+ * `useUpdate`, `useDelete`, and `useInfiniteList`. Operation hooks provide
+ * a single `useMutation` with automatic cache invalidation.
+ *
+ * All hooks support full TanStack Query options passthrough — callers can
+ * provide any option except `queryKey`/`queryFn` (for queries) or
+ * `mutationFn` (for mutations), which are managed internally.
+ *
+ * @typeParam TEntities - Record of entity definitions from the contract
+ * @typeParam TOperations - Record of operation definitions from the contract
+ *
+ * @param contract - The API contract produced by `defineApi()` from `@simplix-react/contract`,
+ *   containing `config`, `client`, and `queryKeys`.
+ *
+ * @returns An object keyed by entity/operation name, each containing its derived hooks.
+ *
+ * @example
+ * ```ts
+ * import { defineApi } from "@simplix-react/contract";
+ * import { deriveHooks } from "@simplix-react/react";
+ * import { z } from "zod";
+ *
+ * const projectContract = defineApi({
+ *   domain: "project",
+ *   basePath: "/api",
+ *   entities: {
+ *     task: {
+ *       path: "/tasks",
+ *       schema: z.object({ id: z.string(), title: z.string(), status: z.string() }),
+ *       createSchema: z.object({ title: z.string(), status: z.string() }),
+ *       updateSchema: z.object({ title: z.string().optional(), status: z.string().optional() }),
+ *     },
+ *   },
+ * });
+ *
+ * // Derive all hooks at once
+ * const hooks = deriveHooks(projectContract);
  *
- * For each entity, generates: useList, useGet, useCreate, useUpdate, useDelete
- * For each operation, generates: useMutation
+ * // Use in components
+ * function TaskList() {
+ *   const { data: tasks } = hooks.task.useList();
+ *   const createTask = hooks.task.useCreate();
+ *   // ...
+ * }
+ * ```
  *
- * All hooks support options passthrough (C8 fix) and
- * cache invalidation via operations.invalidates (C7 fix).
+ * @see {@link EntityHooks} for the per-entity hook interface.
+ * @see {@link OperationHooks} for the per-operation hook interface.
  */
 declare function deriveHooks<TEntities extends Record<string, AnyEntityDef>, TOperations extends Record<string, AnyOperationDef>>(contract: {
     config: ApiContractConfig<TEntities, TOperations>;
@@ -56,4 +287,4 @@ type DerivedHooksResult<TEntities extends Record<string, AnyEntityDef>, TOperati
     [K in keyof TOperations]: TOperations[K] extends OperationDefinition<infer TInput, infer TOutput> ? OperationHooks<TInput, TOutput> : never;
 };
 
-export { type DerivedCreateHook, type DerivedDeleteHook, type DerivedGetHook, type DerivedListHook, type DerivedUpdateHook, type EntityHooks, type OperationHooks, type OperationMutationHook, deriveHooks };
+export { type DerivedCreateHook, type DerivedDeleteHook, type DerivedGetHook, type DerivedInfiniteListHook, type DerivedListHook, type DerivedUpdateHook, type EntityHooks, type OperationHooks, type OperationMutationHook, deriveHooks };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { useQueryClient, useMutation, useQuery } from '@tanstack/react-query';
+import { useInfiniteQuery, useQueryClient, useMutation, useQuery } from '@tanstack/react-query';
 
 // src/derive-hooks.ts
 function deriveHooks(contract) {
@@ -19,14 +19,27 @@ function deriveHooks(contract) {
   }
   return result;
 }
-function createEntityHooks(entity, entityClient, keys, allQueryKeys) {
+function createEntityHooks(entity, entityClient, keys, _allQueryKeys, _config) {
   return {
-    useList(parentId, options) {
+    useList(parentIdOrParams, paramsOrOptions, options) {
+      const { parentId, listParams, queryOptions } = resolveListArgs(
+        parentIdOrParams,
+        paramsOrOptions,
+        options
+      );
+      const keyParams = {};
+      if (entity.parent && parentId) keyParams[entity.parent.param] = parentId;
+      if (listParams) Object.assign(keyParams, listParams);
       return useQuery({
-        queryKey: keys.list(entity.parent ? { [entity.parent.param]: parentId } : {}),
-        queryFn: () => entityClient.list(entity.parent ? parentId : void 0),
+        queryKey: keys.list(keyParams),
+        queryFn: () => {
+          if (entity.parent) {
+            return entityClient.list(parentId, listParams);
+          }
+          return entityClient.list(listParams);
+        },
         enabled: entity.parent ? !!parentId : true,
-        ...options
+        ...queryOptions
       });
     },
     useGet(id, options) {
@@ -55,13 +68,35 @@ function createEntityHooks(entity, entityClient, keys, allQueryKeys) {
     },
     useUpdate(options) {
       const queryClient = useQueryClient();
+      const isOptimistic = options?.optimistic ?? false;
       return useMutation({
         mutationFn: ({ id, dto }) => entityClient.update(id, dto),
+        onMutate: isOptimistic ? async ({ id, dto }) => {
+          await queryClient.cancelQueries({ queryKey: keys.all });
+          const previousData = queryClient.getQueriesData({ queryKey: keys.lists() });
+          queryClient.setQueriesData(
+            { queryKey: keys.lists() },
+            (old) => old?.map(
+              (item) => isRecord(item) && item.id === id ? { ...item, ...dto } : item
+            )
+          );
+          return { previousData };
+        } : void 0,
+        onError: isOptimistic ? (_err, _vars, context) => {
+          const ctx = context;
+          if (ctx?.previousData) {
+            for (const [queryKey, data] of ctx.previousData) {
+              queryClient.setQueryData(queryKey, data);
+            }
+          }
+        } : void 0,
         onSuccess: (...args) => {
-          queryClient.invalidateQueries({ queryKey: keys.all });
           options?.onSuccess?.(...args);
         },
-        ...omit(options, ["onSuccess"])
+        onSettled: () => {
+          queryClient.invalidateQueries({ queryKey: keys.all });
+        },
+        ...omit(options, ["onSuccess", "onMutate", "onError", "onSettled", "optimistic"])
       });
     },
     useDelete(options) {
@@ -74,6 +109,37 @@ function createEntityHooks(entity, entityClient, keys, allQueryKeys) {
         },
         ...omit(options, ["onSuccess"])
       });
+    },
+    useInfiniteList(parentId, params, options) {
+      const limit = params?.limit ?? 20;
+      const keyParams = { infinite: true };
+      if (entity.parent && parentId) keyParams[entity.parent.param] = parentId;
+      if (params?.filters) keyParams.filters = params.filters;
+      if (params?.sort) keyParams.sort = params.sort;
+      return useInfiniteQuery({
+        queryKey: keys.list(keyParams),
+        queryFn: ({ pageParam }) => {
+          const pagination = typeof pageParam === "string" ? { type: "cursor", cursor: pageParam, limit } : { type: "offset", page: pageParam ?? 1, limit };
+          const listParams = {
+            filters: params?.filters,
+            sort: params?.sort,
+            pagination
+          };
+          if (entity.parent) {
+            return entityClient.list(parentId, listParams);
+          }
+          return entityClient.list(listParams);
+        },
+        initialPageParam: 1,
+        getNextPageParam: (lastPage, _allPages, lastPageParam) => {
+          const page = lastPage;
+          if (!page.meta?.hasNextPage) return void 0;
+          if (page.meta.nextCursor) return page.meta.nextCursor;
+          return typeof lastPageParam === "number" ? lastPageParam + 1 : void 0;
+        },
+        enabled: entity.parent ? !!parentId : true,
+        ...options
+      });
     }
   };
 }
@@ -105,5 +171,30 @@ function omit(obj, keys) {
   }
   return result;
 }
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isListParams(value) {
+  if (!isRecord(value)) return false;
+  return "filters" in value || "sort" in value || "pagination" in value;
+}
+function resolveListArgs(firstArg, secondArg, thirdArg) {
+  if (typeof firstArg === "string") {
+    return {
+      parentId: firstArg,
+      listParams: isListParams(secondArg) ? secondArg : void 0,
+      queryOptions: isListParams(secondArg) ? thirdArg : secondArg
+    };
+  }
+  if (isListParams(firstArg)) {
+    return {
+      listParams: firstArg,
+      queryOptions: secondArg
+    };
+  }
+  return {
+    queryOptions: firstArg
+  };
+}
 
 export { deriveHooks };

package/package.json

@@ -1,39 +1,49 @@
 {
   "name": "@simplix-react/react",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "React Query hooks derived from @simplix-react/contract",
   "type": "module",
+  "sideEffects": false,
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js"
     }
   },
-  "files": ["dist"],
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "typecheck": "tsc --noEmit",
-    "lint": "eslint src",
-    "test": "vitest run --passWithNoTests",
-    "clean": "rm -rf dist .turbo"
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
   },
   "peerDependencies": {
-    "@simplix-react/contract": "workspace:*",
     "@tanstack/react-query": ">=5.0.0",
     "react": ">=18.0.0",
-    "zod": ">=4.0.0"
+    "zod": ">=4.0.0",
+    "@simplix-react/contract": "0.0.3"
   },
   "devDependencies": {
-    "@simplix-react/config-typescript": "workspace:*",
-    "@simplix-react/contract": "workspace:*",
     "@tanstack/react-query": "^5.0.0",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
     "@types/react": "^19.0.0",
     "eslint": "^9.39.2",
+    "jsdom": "^28.0.0",
     "react": "^19.0.0",
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vitest": "^3.0.0",
-    "zod": "^4.0.0"
+    "zod": "^4.0.0",
+    "@simplix-react/contract": "0.0.3",
+    "@simplix-react/config-eslint": "0.0.1",
+    "@simplix-react/config-typescript": "0.0.1"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src",
+    "test": "vitest run --passWithNoTests",
+    "clean": "rm -rf dist .turbo"
   }
-}
+}