@simplix-react/mock 0.0.1 → 0.0.2

package/README.md

@@ -0,0 +1,304 @@
+# @simplix-react/mock
+
+Auto-generated MSW handlers and PGlite repositories from `@simplix-react/contract`.
+
+> **Prerequisites:** Requires a contract defined with `@simplix-react/contract`.
+
+## Installation
+
+```bash
+pnpm add @simplix-react/mock
+```
+
+Peer dependencies:
+
+| Package | Required | Notes |
+| --- | --- | --- |
+| `@simplix-react/contract` | Yes | Provides the API contract definition |
+| `zod` | Yes | `>=4.0.0` |
+| `msw` | Optional | `>=2.0.0` — needed for MSW handler generation |
+| `@electric-sql/pglite` | Optional | `>=0.2.0` — needed for in-browser PostgreSQL |
+
+## Quick Example
+
+```ts
+import { defineContract } from "@simplix-react/contract";
+import {
+  setupMockWorker,
+  deriveMockHandlers,
+  executeSql,
+} from "@simplix-react/mock";
+import { z } from "zod";
+
+// 1. Define your contract
+const projectContract = defineContract({
+  domain: "project",
+  basePath: "/api",
+  entities: {
+    task: {
+      path: "/tasks",
+      schema: z.object({
+        id: z.string(),
+        title: z.string(),
+        status: z.enum(["todo", "done"]),
+        createdAt: z.date(),
+      }),
+      createSchema: z.object({ title: z.string() }),
+      updateSchema: z.object({ status: z.enum(["todo", "done"]).optional() }),
+    },
+  },
+});
+
+// 2. Derive handlers and bootstrap
+await setupMockWorker({
+  dataDir: "idb://project-mock",
+  migrations: [
+    async (db) => {
+      await executeSql(db, `
+        CREATE TABLE IF NOT EXISTS tasks (
+          id TEXT PRIMARY KEY,
+          title TEXT NOT NULL,
+          status TEXT NOT NULL DEFAULT 'todo',
+          created_at TIMESTAMP DEFAULT NOW(),
+          updated_at TIMESTAMP DEFAULT NOW()
+        )
+      `);
+    },
+  ],
+  seed: [],
+  handlers: deriveMockHandlers(projectContract.config),
+});
+```
+
+After `setupMockWorker` resolves, every `fetch("/api/tasks")` call in your application is intercepted by MSW and served from the in-browser PGlite database.
+
+## API Overview
+
+### Core
+
+| Export | Description |
+| --- | --- |
+| `setupMockWorker(config)` | Bootstraps PGlite + MSW in one call |
+| `deriveMockHandlers(config, mockConfig?)` | Generates CRUD MSW handlers from a contract |
+| `MockServerConfig` | Configuration for `setupMockWorker` |
+| `MockEntityConfig` | Per-entity mock configuration (table name, limits, relations) |
+
+### PGlite Lifecycle
+
+| Export | Description |
+| --- | --- |
+| `initPGlite(dataDir)` | Initializes the PGlite singleton |
+| `getPGliteInstance()` | Returns the active instance (throws if uninitialized) |
+| `resetPGliteInstance()` | Clears the singleton (for test teardown) |
+
+### Result Types
+
+| Export | Description |
+| --- | --- |
+| `MockResult<T>` | Discriminated success/failure result type |
+| `mockSuccess(data)` | Creates a success result |
+| `mockFailure(error)` | Creates a failure result |
+
+### SQL Utilities
+
+| Export | Description |
+| --- | --- |
+| `mapRow(row)` | Converts a snake_case DB row to camelCase (with Date parsing) |
+| `mapRows(rows)` | Maps an array of rows |
+| `toCamelCase(str)` | `snake_case` → `camelCase` |
+| `toSnakeCase(str)` | `camelCase` → `snake_case` |
+| `DbRow` | Type alias for `Record<string, unknown>` |
+| `buildSetClause(input)` | Builds a parameterized SQL SET clause |
+| `SetClauseResult` | Return type of `buildSetClause` |
+| `mapPgError(err)` | Maps PGlite errors to HTTP-friendly `MockError` |
+| `MockError` | Structured error with status, code, message |
+
+### Migration Helpers
+
+| Export | Description |
+| --- | --- |
+| `tableExists(db, tableName)` | Checks if a table exists |
+| `columnExists(db, tableName, columnName)` | Checks if a column exists |
+| `executeSql(db, sql)` | Executes semicolon-separated SQL statements |
+| `addColumnIfNotExists(db, table, column, def)` | Idempotent column addition |
+
+## Key Concepts
+
+### MSW Handler Derivation
+
+`deriveMockHandlers` reads your contract's entity definitions and generates five handlers per entity:
+
+```
+GET    {basePath}{entityPath}        → List (with filter, sort, pagination)
+GET    {basePath}{entityPath}/:id    → Get by ID (with relation loading)
+POST   {basePath}{entityPath}        → Create (auto-generates UUID)
+PATCH  {basePath}{entityPath}/:id    → Partial update
+DELETE {basePath}{entityPath}/:id    → Delete
+```
+
+For child entities with a `parent` definition, list and create routes are nested under the parent path:
+
+```
+GET    {basePath}{parentPath}/:parentId{entityPath}     → List by parent
+POST   {basePath}{parentPath}/:parentId{entityPath}     → Create under parent
+```
+
+#### Query Parameters
+
+List endpoints support the following query parameters:
+
+| Parameter | Example | Description |
+| --- | --- | --- |
+| `sort` | `sort=title:asc,createdAt:desc` | Comma-separated `field:direction` pairs |
+| `page` | `page=2` | Offset-based page number (1-indexed) |
+| `limit` | `limit=20` | Rows per page (capped by `maxLimit`) |
+| `{field}` | `status=done` | Equality filter on any column |
+
+#### Relation Loading
+
+Configure `belongsTo` relations in `MockEntityConfig` to automatically JOIN related data on GET-by-ID requests:
+
+```ts
+const handlers = deriveMockHandlers(contract.config, {
+  task: {
+    relations: {
+      project: {
+        table: "projects",
+        localKey: "projectId",
+        foreignKey: "id",      // defaults to "id"
+        type: "belongsTo",
+      },
+    },
+  },
+});
+```
+
+### PGlite Integration
+
+PGlite provides a full PostgreSQL database running in the browser via WebAssembly. This package manages a singleton instance:
+
+```
+initPGlite(dataDir) → getPGliteInstance() → resetPGliteInstance()
+```
+
+Data persists across page reloads via IndexedDB when using an `idb://` data directory.
+
+### SQL Utilities
+
+The SQL utility modules handle the mapping between JavaScript (camelCase) and PostgreSQL (snake_case) conventions:
+
+- **Row mapping** — `mapRow`/`mapRows` convert query results to JS objects, automatically parsing `_at` columns as `Date` instances.
+- **Query building** — `buildSetClause` constructs parameterized UPDATE queries from partial objects, always appending `updated_at = NOW()`.
+- **Error mapping** — `mapPgError` classifies PGlite exceptions into structured errors with appropriate HTTP status codes.
+- **Migration helpers** — Idempotent utilities (`tableExists`, `addColumnIfNotExists`, `executeSql`) for writing safe migration functions.
+
+## Guides
+
+### Writing Migrations
+
+Migrations are async functions that receive a PGlite instance. Use the migration helpers for idempotent operations:
+
+```ts
+import type { PGlite } from "@electric-sql/pglite";
+import { tableExists, executeSql, addColumnIfNotExists } from "@simplix-react/mock";
+
+export async function migrate(db: PGlite) {
+  if (!(await tableExists(db, "tasks"))) {
+    await executeSql(db, `
+      CREATE TABLE tasks (
+        id TEXT PRIMARY KEY,
+        title TEXT NOT NULL,
+        status TEXT NOT NULL DEFAULT 'todo',
+        project_id TEXT,
+        created_at TIMESTAMP DEFAULT NOW(),
+        updated_at TIMESTAMP DEFAULT NOW()
+      )
+    `);
+  }
+
+  // Safe to call multiple times
+  await addColumnIfNotExists(db, "tasks", "priority", "INTEGER DEFAULT 0");
+}
+```
+
+### Writing Seed Functions
+
+Seed functions populate the database with initial data after migrations:
+
+```ts
+import type { PGlite } from "@electric-sql/pglite";
+
+export async function seed(db: PGlite) {
+  await db.query(
+    `INSERT INTO tasks (id, title, status) VALUES ($1, $2, $3)
+     ON CONFLICT (id) DO NOTHING`,
+    ["task-1", "Sample Task", "todo"],
+  );
+}
+```
+
+### Custom Repository Handlers
+
+For advanced use cases beyond auto-generated CRUD, use the SQL utilities directly:
+
+```ts
+import { http, HttpResponse } from "msw";
+import {
+  getPGliteInstance,
+  mapRows,
+  mapPgError,
+  mockSuccess,
+  mockFailure,
+} from "@simplix-react/mock";
+
+const customHandler = http.get("/api/tasks/overdue", async () => {
+  try {
+    const db = getPGliteInstance();
+    const result = await db.query(
+      "SELECT * FROM tasks WHERE status != 'done' AND created_at < NOW() - INTERVAL '7 days'",
+    );
+    const tasks = mapRows(result.rows as Record<string, unknown>[]);
+    return HttpResponse.json({ data: mockSuccess(tasks) });
+  } catch (err) {
+    const mapped = mapPgError(err);
+    return HttpResponse.json(
+      { code: mapped.code, message: mapped.message },
+      { status: mapped.status },
+    );
+  }
+});
+```
+
+### Testing with PGlite
+
+Reset the singleton between tests to ensure isolation:
+
+```ts
+import { initPGlite, resetPGliteInstance, executeSql } from "@simplix-react/mock";
+import { afterEach, beforeEach, describe, it } from "vitest";
+
+describe("task repository", () => {
+  beforeEach(async () => {
+    const db = await initPGlite("memory://");
+    await executeSql(db, `
+      CREATE TABLE tasks (id TEXT PRIMARY KEY, title TEXT NOT NULL)
+    `);
+  });
+
+  afterEach(() => {
+    resetPGliteInstance();
+  });
+
+  it("inserts a task", async () => {
+    // ...
+  });
+});
+```
+
+## Related Packages
+
+| Package | Description |
+| --- | --- |
+| [`@simplix-react/contract`](../contract) | Define type-safe API contracts consumed by this package |
+| [`@simplix-react/react`](../react) | React Query hooks derived from the same contract |
+| [`@simplix-react/testing`](../testing) | Test utilities for contract-based mocking |

package/dist/index.d.ts

@@ -4,73 +4,270 @@ import { EntityDefinition, OperationDefinition, ApiContractConfig } from '@simpl
 import { z } from 'zod';
 
 /**
- * Initialize a PGlite instance with IndexedDB persistence.
+ * Initializes a singleton PGlite instance with the given data directory.
+ *
+ * Uses a dynamic import so that `@electric-sql/pglite` remains an optional peer
+ * dependency. Subsequent calls return the already-initialized instance.
+ *
+ * @param dataDir - The IndexedDB data directory for persistence (e.g. `"idb://simplix-mock"`).
+ * @returns The initialized PGlite instance.
+ *
+ * @example
+ * ```ts
+ * import { initPGlite } from "@simplix-react/mock";
+ *
+ * const db = await initPGlite("idb://project-mock");
+ * await db.query("SELECT 1");
+ * ```
+ *
+ * @see {@link getPGliteInstance} - Retrieves the current instance without re-initializing.
+ * @see {@link resetPGliteInstance} - Clears the singleton for testing.
  */
 declare function initPGlite(dataDir: string): Promise<PGlite>;
 /**
- * Get the current PGlite instance.
- * Throws if not initialized.
+ * Returns the current PGlite singleton instance.
+ *
+ * Throws an error if {@link initPGlite} has not been called yet.
+ *
+ * @returns The active PGlite instance.
+ * @throws Error if PGlite has not been initialized.
+ *
+ * @example
+ * ```ts
+ * import { getPGliteInstance } from "@simplix-react/mock";
+ *
+ * const db = getPGliteInstance();
+ * const result = await db.query("SELECT * FROM tasks");
+ * ```
  */
 declare function getPGliteInstance(): PGlite;
 /**
- * Reset the PGlite instance (for testing).
+ * Resets the PGlite singleton instance to `null`.
+ *
+ * Intended for use in test teardown to ensure a clean state between test runs.
+ *
+ * @example
+ * ```ts
+ * import { resetPGliteInstance } from "@simplix-react/mock";
+ *
+ * afterEach(() => {
+ *   resetPGliteInstance();
+ * });
+ * ```
  */
 declare function resetPGliteInstance(): void;
 
 type RequestHandler = unknown;
+/**
+ * Describes the configuration required by {@link setupMockWorker}.
+ *
+ * Combines PGlite database setup (migrations and seed data) with MSW request
+ * handlers into a single bootstrap configuration.
+ *
+ * @example
+ * ```ts
+ * import type { MockServerConfig } from "@simplix-react/mock";
+ * import { deriveMockHandlers } from "@simplix-react/mock";
+ * import { projectContract } from "./contract";
+ * import { runMigrations } from "./migrations";
+ * import { seedData } from "./seed";
+ *
+ * const config: MockServerConfig = {
+ *   dataDir: "idb://project-mock",
+ *   migrations: [runMigrations],
+ *   seed: [seedData],
+ *   handlers: deriveMockHandlers(projectContract.config),
+ * };
+ * ```
+ *
+ * @see {@link setupMockWorker} - Consumes this config to bootstrap the mock environment.
+ */
 interface MockServerConfig {
     /**
-     * IndexedDB data directory for PGlite persistence
+     * IndexedDB data directory for PGlite persistence.
+     *
+     * @defaultValue `"idb://simplix-mock"`
      */
     dataDir?: string;
     /**
-     * Migration functions to run in order
+     * Migration functions to run in order.
+     *
+     * Each function receives the PGlite instance and should create or alter tables.
      */
     migrations: Array<(db: PGlite) => Promise<void>>;
     /**
-     * Seed functions to run in order (after migrations)
+     * Seed functions to run in order (after migrations).
+     *
+     * Each function receives the PGlite instance and should insert initial data.
      */
     seed: Array<(db: PGlite) => Promise<void>>;
     /**
-     * MSW request handlers
+     * MSW request handlers to register with the service worker.
+     *
+     * Typically produced by {@link deriveMockHandlers}.
      */
     handlers: RequestHandler[];
 }
 /**
- * Set up the mock server with PGlite + MSW.
+ * Bootstraps a complete mock environment with PGlite and MSW.
  *
- * 1. Initializes PGlite at the given dataDir
- * 2. Runs all migrations sequentially
+ * Performs the following steps in order:
+ * 1. Initializes a PGlite instance at the configured `dataDir`
+ * 2. Runs all migration functions sequentially
  * 3. Runs all seed functions sequentially
- * 4. Starts the MSW service worker
+ * 4. Starts the MSW service worker with the provided handlers
+ *
+ * @param config - The {@link MockServerConfig} describing database setup and handlers.
+ *
+ * @example
+ * ```ts
+ * import { setupMockWorker, deriveMockHandlers } from "@simplix-react/mock";
+ * import { projectContract } from "./contract";
+ * import { runMigrations } from "./migrations";
+ * import { seedData } from "./seed";
+ *
+ * await setupMockWorker({
+ *   dataDir: "idb://project-mock",
+ *   migrations: [runMigrations],
+ *   seed: [seedData],
+ *   handlers: deriveMockHandlers(projectContract.config),
+ * });
+ * ```
+ *
+ * @see {@link MockServerConfig} - Configuration shape.
+ * @see {@link deriveMockHandlers} - Generates MSW handlers from a contract.
+ * @see {@link initPGlite} - Underlying PGlite initialization.
  */
 declare function setupMockWorker(config: MockServerConfig): Promise<void>;
 
 type AnyEntityDef = EntityDefinition<z.ZodTypeAny, z.ZodTypeAny, z.ZodTypeAny>;
 type AnyOperationDef = OperationDefinition<z.ZodTypeAny, z.ZodTypeAny>;
 /**
- * Extended entity definition with mock-specific config.
- * Users pass this as part of the contract config.
+ * Provides per-entity configuration for mock handler generation.
+ *
+ * Allows overriding the default table name, pagination limits, sort order,
+ * and relation loading for a specific entity when calling {@link deriveMockHandlers}.
+ *
+ * @example
+ * ```ts
+ * import type { MockEntityConfig } from "@simplix-react/mock";
+ *
+ * const taskConfig: MockEntityConfig = {
+ *   tableName: "tasks",
+ *   defaultLimit: 20,
+ *   maxLimit: 100,
+ *   defaultSort: "created_at DESC",
+ *   relations: {
+ *     project: {
+ *       table: "projects",
+ *       localKey: "projectId",
+ *       type: "belongsTo",
+ *     },
+ *   },
+ * };
+ * ```
+ *
+ * @see {@link deriveMockHandlers} - Consumes this config per entity.
  */
 interface MockEntityConfig {
+    /** Overrides the auto-derived PostgreSQL table name. */
     tableName?: string;
+    /**
+     * Default number of rows per page.
+     *
+     * @defaultValue 50
+     */
+    defaultLimit?: number;
+    /**
+     * Maximum allowed rows per page.
+     *
+     * @defaultValue 100
+     */
+    maxLimit?: number;
+    /**
+     * Default SQL ORDER BY clause.
+     *
+     * @defaultValue `"created_at DESC"`
+     */
+    defaultSort?: string;
+    /** Map of relation names to their `belongsTo` join configuration. */
+    relations?: Record<string, {
+        table: string;
+        localKey: string;
+        foreignKey?: string;
+        type: "belongsTo";
+    }>;
 }
 /**
- * Derive MSW request handlers from an API contract config.
+ * Derives MSW request handlers from an {@link @simplix-react/contract!ApiContractConfig}.
  *
- * Generates standard CRUD handlers for each entity:
- * - GET list (by parent if defined)
- * - GET by id
- * - POST create
- * - PATCH update
- * - DELETE
+ * Generates a complete set of CRUD handlers for every entity defined in the contract:
  *
- * For entities with mock.tableName defined, auto-generates SQL queries.
+ * - **GET list** — supports query-param filtering, sorting, and offset-based pagination
+ * - **GET by id** — supports `belongsTo` relation loading via joins
+ * - **POST create** — auto-generates a UUID `id` when not provided
+ * - **PATCH update** — partial updates with automatic `updated_at` timestamp
+ * - **DELETE** — removes the row by `id`
+ *
+ * All handlers read from and write to the PGlite singleton managed by
+ * {@link initPGlite}/{@link getPGliteInstance}.
+ *
+ * @typeParam TEntities - The entities map from the contract config.
+ * @typeParam TOperations - The operations map from the contract config.
+ * @param config - The API contract configuration object.
+ * @param mockConfig - Optional per-entity mock configuration keyed by entity name.
+ * @returns An array of MSW `HttpHandler` instances ready for use with `setupWorker`.
+ *
+ * @example
+ * ```ts
+ * import { deriveMockHandlers } from "@simplix-react/mock";
+ * import { projectContract } from "./contract";
+ *
+ * const handlers = deriveMockHandlers(projectContract.config, {
+ *   task: {
+ *     tableName: "tasks",
+ *     defaultLimit: 20,
+ *     relations: {
+ *       project: {
+ *         table: "projects",
+ *         localKey: "projectId",
+ *         type: "belongsTo",
+ *       },
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * @see {@link MockEntityConfig} - Per-entity configuration options.
+ * @see {@link setupMockWorker} - High-level bootstrap that accepts these handlers.
+ * @see {@link @simplix-react/contract!ApiContractConfig} - The contract config shape.
  */
 declare function deriveMockHandlers<TEntities extends Record<string, AnyEntityDef>, TOperations extends Record<string, AnyOperationDef>>(config: ApiContractConfig<TEntities, TOperations>, mockConfig?: Record<string, MockEntityConfig>): msw.HttpHandler[];
 
 /**
- * Unified result type for all mock repository operations.
+ * Represents the outcome of a mock repository operation.
+ *
+ * Encapsulates either a successful result with data or a failure with an error code
+ * and message. Used throughout `@simplix-react/mock` to provide consistent return
+ * types from all database operations.
+ *
+ * @typeParam T - The type of the data payload on success.
+ *
+ * @example
+ * ```ts
+ * import type { MockResult } from "@simplix-react/mock";
+ *
+ * function handleResult(result: MockResult<{ id: string; name: string }>) {
+ *   if (result.success) {
+ *     console.log(result.data?.name);
+ *   } else {
+ *     console.error(result.error?.code, result.error?.message);
+ *   }
+ * }
+ * ```
+ *
+ * @see {@link mockSuccess} - Creates a successful result.
+ * @see {@link mockFailure} - Creates a failure result.
  */
 interface MockResult<T> {
     success: boolean;
@@ -81,11 +278,34 @@ interface MockResult<T> {
     };
 }
 /**
- * Create a successful result.
+ * Creates a successful {@link MockResult} wrapping the given data.
+ *
+ * @typeParam T - The type of the data payload.
+ * @param data - The data to wrap in a success result.
+ * @returns A {@link MockResult} with `success: true` and the provided data.
+ *
+ * @example
+ * ```ts
+ * import { mockSuccess } from "@simplix-react/mock";
+ *
+ * const result = mockSuccess({ id: "1", title: "My Task" });
+ * // { success: true, data: { id: "1", title: "My Task" } }
+ * ```
  */
 declare function mockSuccess<T>(data: T): MockResult<T>;
 /**
- * Create a failure result.
+ * Creates a failure {@link MockResult} with the given error code and message.
+ *
+ * @param error - An object containing an error `code` and human-readable `message`.
+ * @returns A {@link MockResult} with `success: false` and the provided error.
+ *
+ * @example
+ * ```ts
+ * import { mockFailure } from "@simplix-react/mock";
+ *
+ * const result = mockFailure({ code: "not_found", message: "Task not found" });
+ * // { success: false, error: { code: "not_found", message: "Task not found" } }
+ * ```
  */
 declare function mockFailure(error: {
     code: string;
@@ -93,65 +313,259 @@ declare function mockFailure(error: {
 }): MockResult<never>;
 
 /**
- * Database row type
+ * Represents a raw database row with unknown column values.
+ *
+ * Used as the input type for row-mapping functions that convert snake_case
+ * database columns to camelCase JavaScript properties.
+ *
+ * @see {@link mapRow} - Maps a single row.
+ * @see {@link mapRows} - Maps an array of rows.
  */
 type DbRow = Record<string, unknown>;
 /**
- * Convert snake_case string to camelCase
+ * Converts a snake_case string to camelCase.
+ *
+ * @param str - The snake_case input string.
+ * @returns The camelCase equivalent.
+ *
+ * @example
+ * ```ts
+ * import { toCamelCase } from "@simplix-react/mock";
+ *
+ * toCamelCase("created_at"); // "createdAt"
+ * toCamelCase("project_id"); // "projectId"
+ * ```
  */
 declare function toCamelCase(str: string): string;
 /**
- * Convert camelCase string to snake_case
+ * Converts a camelCase string to snake_case.
+ *
+ * @param str - The camelCase input string.
+ * @returns The snake_case equivalent.
+ *
+ * @example
+ * ```ts
+ * import { toSnakeCase } from "@simplix-react/mock";
+ *
+ * toSnakeCase("createdAt"); // "created_at"
+ * toSnakeCase("projectId"); // "project_id"
+ * ```
  */
 declare function toSnakeCase(str: string): string;
 /**
- * Map a database row (snake_case) to a camelCase object.
- * Automatically converts columns ending in `_at` to Date objects.
+ * Maps a single database row from snake_case columns to a camelCase object.
+ *
+ * Columns ending in `_at` are automatically converted to `Date` objects.
+ *
+ * @typeParam T - The expected shape of the mapped object.
+ * @param row - The raw database row with snake_case keys.
+ * @returns The mapped object with camelCase keys.
+ *
+ * @example
+ * ```ts
+ * import { mapRow } from "@simplix-react/mock";
+ *
+ * const row = { id: "1", project_id: "p1", created_at: "2025-01-01T00:00:00Z" };
+ * const mapped = mapRow<{ id: string; projectId: string; createdAt: Date }>(row);
+ * // { id: "1", projectId: "p1", createdAt: Date("2025-01-01T00:00:00Z") }
+ * ```
+ *
+ * @see {@link mapRows} - Maps an array of rows.
+ * @see {@link toCamelCase} - Underlying case conversion.
  */
 declare function mapRow<T>(row: DbRow): T;
 /**
- * Map an array of database rows to camelCase objects.
+ * Maps an array of database rows from snake_case to camelCase objects.
+ *
+ * Delegates to {@link mapRow} for each row.
+ *
+ * @typeParam T - The expected shape of each mapped object.
+ * @param rows - The array of raw database rows.
+ * @returns An array of mapped camelCase objects.
+ *
+ * @example
+ * ```ts
+ * import { mapRows } from "@simplix-react/mock";
+ *
+ * const rows = [
+ *   { id: "1", task_name: "Build" },
+ *   { id: "2", task_name: "Test" },
+ * ];
+ * const mapped = mapRows<{ id: string; taskName: string }>(rows);
+ * // [{ id: "1", taskName: "Build" }, { id: "2", taskName: "Test" }]
+ * ```
  */
 declare function mapRows<T>(rows: DbRow[]): T[];
 
+/**
+ * Represents the result of {@link buildSetClause}.
+ *
+ * Contains the SQL SET clause string, the ordered parameter values, and the next
+ * available parameter index for appending additional conditions (e.g. a WHERE clause).
+ *
+ * @see {@link buildSetClause} - Produces this result.
+ */
 interface SetClauseResult {
+    /** The SQL SET clause string (e.g. `"name = $1, updated_at = NOW()"`). */
     clause: string;
+    /** The ordered parameter values corresponding to the placeholders. */
     values: unknown[];
+    /** The next available `$N` parameter index. */
     nextIndex: number;
 }
 /**
- * Build a dynamic SQL SET clause from a partial object.
- * Converts camelCase keys to snake_case columns.
- * Skips undefined values.
- * Automatically appends `updated_at = NOW()`.
+ * Builds a parameterized SQL SET clause from a partial update object.
+ *
+ * Converts camelCase object keys to snake_case column names, skips `undefined`
+ * values, serializes nested objects as JSONB, and automatically appends
+ * `updated_at = NOW()`.
+ *
+ * @typeParam T - The shape of the update DTO.
+ * @param input - The partial object whose defined keys become SET assignments.
+ * @param startIndex - The starting `$N` placeholder index.
+ * @returns A {@link SetClauseResult} with the clause, values, and next index.
+ *
+ * @example
+ * ```ts
+ * import { buildSetClause } from "@simplix-react/mock";
+ *
+ * const { clause, values, nextIndex } = buildSetClause(
+ *   { title: "Updated Task", status: "done" },
+ * );
+ * // clause:    "title = $1, status = $2, updated_at = NOW()"
+ * // values:    ["Updated Task", "done"]
+ * // nextIndex: 3
+ *
+ * const sql = `UPDATE tasks SET ${clause} WHERE id = $${nextIndex}`;
+ * // sql: "UPDATE tasks SET title = $1, status = $2, updated_at = NOW() WHERE id = $3"
+ * ```
+ *
+ * @see {@link SetClauseResult} - The return type.
  */
 declare function buildSetClause<T extends object>(input: T, startIndex?: number): SetClauseResult;
 
+/**
+ * Represents a mapped database error with an HTTP-friendly status code.
+ *
+ * Produced by {@link mapPgError} from raw PostgreSQL/PGlite exceptions.
+ *
+ * @see {@link mapPgError} - Creates instances from raw errors.
+ */
 interface MockError {
+    /** The HTTP status code corresponding to the error type. */
     status: number;
+    /** A machine-readable error code (e.g. `"unique_violation"`, `"not_found"`). */
     code: string;
+    /** A human-readable error description. */
     message: string;
 }
 /**
- * Map PostgreSQL errors to HTTP-friendly MockError.
+ * Maps a raw PostgreSQL/PGlite error to an HTTP-friendly {@link MockError}.
+ *
+ * Inspects the error message to classify the error:
+ *
+ * | Pattern                  | Code                    | HTTP Status |
+ * | ------------------------ | ----------------------- | ----------- |
+ * | unique / duplicate       | `unique_violation`      | 409         |
+ * | foreign key              | `foreign_key_violation` | 422         |
+ * | not-null / null value    | `not_null_violation`    | 422         |
+ * | not found / no rows      | `not_found`             | 404         |
+ * | (unrecognized)           | `query_error`           | 500         |
+ *
+ * @param err - The raw error thrown by a PGlite query.
+ * @returns A structured {@link MockError} with status, code, and message.
+ *
+ * @example
+ * ```ts
+ * import { mapPgError } from "@simplix-react/mock";
+ *
+ * try {
+ *   await db.query("INSERT INTO tasks ...");
+ * } catch (err) {
+ *   const mapped = mapPgError(err);
+ *   console.error(mapped.code, mapped.status); // e.g. "unique_violation" 409
+ * }
+ * ```
  */
 declare function mapPgError(err: unknown): MockError;
 
 /**
- * Check if a table exists in the database.
+ * Checks whether a table exists in the database by querying `information_schema.tables`.
+ *
+ * @param db - The PGlite instance.
+ * @param tableName - The name of the table to check.
+ * @returns `true` if the table exists, `false` otherwise.
+ *
+ * @example
+ * ```ts
+ * import { initPGlite, tableExists } from "@simplix-react/mock";
+ *
+ * const db = await initPGlite("idb://project-mock");
+ * if (!(await tableExists(db, "tasks"))) {
+ *   await db.query("CREATE TABLE tasks (id TEXT PRIMARY KEY)");
+ * }
+ * ```
  */
 declare function tableExists(db: PGlite, tableName: string): Promise<boolean>;
 /**
- * Check if a column exists in a table.
+ * Checks whether a column exists in a table by querying `information_schema.columns`.
+ *
+ * @param db - The PGlite instance.
+ * @param tableName - The table to inspect.
+ * @param columnName - The column name to check for.
+ * @returns `true` if the column exists, `false` otherwise.
+ *
+ * @example
+ * ```ts
+ * import { initPGlite, columnExists } from "@simplix-react/mock";
+ *
+ * const db = await initPGlite("idb://project-mock");
+ * const has = await columnExists(db, "tasks", "priority");
+ * ```
  */
 declare function columnExists(db: PGlite, tableName: string, columnName: string): Promise<boolean>;
 /**
- * Execute multiple SQL statements separated by semicolons.
+ * Executes multiple SQL statements separated by semicolons.
+ *
+ * Splits the input on `;`, trims each statement, filters out empty strings,
+ * and executes them sequentially.
+ *
+ * @param db - The PGlite instance.
+ * @param sql - A string containing one or more semicolon-separated SQL statements.
+ *
+ * @example
+ * ```ts
+ * import { initPGlite, executeSql } from "@simplix-react/mock";
+ *
+ * const db = await initPGlite("idb://project-mock");
+ * await executeSql(db, `
+ *   CREATE TABLE projects (id TEXT PRIMARY KEY, name TEXT NOT NULL);
+ *   CREATE TABLE tasks (id TEXT PRIMARY KEY, project_id TEXT REFERENCES projects(id));
+ * `);
+ * ```
  */
 declare function executeSql(db: PGlite, sql: string): Promise<void>;
 /**
- * Add a column to a table if it doesn't exist.
+ * Adds a column to a table only if it does not already exist.
+ *
+ * Combines {@link columnExists} with an `ALTER TABLE ADD COLUMN` statement
+ * for safe, idempotent schema migrations.
+ *
+ * @param db - The PGlite instance.
+ * @param tableName - The target table.
+ * @param columnName - The column name to add.
+ * @param columnDef - The column type definition (e.g. `"TEXT NOT NULL DEFAULT ''"`).
+ *
+ * @example
+ * ```ts
+ * import { initPGlite, addColumnIfNotExists } from "@simplix-react/mock";
+ *
+ * const db = await initPGlite("idb://project-mock");
+ * await addColumnIfNotExists(db, "tasks", "priority", "INTEGER DEFAULT 0");
+ * ```
+ *
+ * @see {@link columnExists} - Used internally to check existence.
  */
 declare function addColumnIfNotExists(db: PGlite, tableName: string, columnName: string, columnDef: string): Promise<void>;
 
-export { type DbRow, type MockError, type MockResult, type MockServerConfig, type SetClauseResult, addColumnIfNotExists, buildSetClause, columnExists, deriveMockHandlers, executeSql, getPGliteInstance, initPGlite, mapPgError, mapRow, mapRows, mockFailure, mockSuccess, resetPGliteInstance, setupMockWorker, tableExists, toCamelCase, toSnakeCase };
+export { type DbRow, type MockEntityConfig, type MockError, type MockResult, type MockServerConfig, type SetClauseResult, addColumnIfNotExists, buildSetClause, columnExists, deriveMockHandlers, executeSql, getPGliteInstance, initPGlite, mapPgError, mapRow, mapRows, mockFailure, mockSuccess, resetPGliteInstance, setupMockWorker, tableExists, toCamelCase, toSnakeCase };

package/dist/index.js

@@ -144,37 +144,65 @@ function deriveMockHandlers(config, mockConfig) {
   const handlers = [];
   const { basePath, entities } = config;
   for (const [name, entity] of Object.entries(entities)) {
-    const tableName = mockConfig?.[name]?.tableName ?? toSnakeCase(name) + "s";
+    const entityConfig = mockConfig?.[name];
+    const tableName = entityConfig?.tableName ?? toSnakeCase(name) + "s";
+    const defaultLimit = entityConfig?.defaultLimit ?? 50;
+    const maxLimit = entityConfig?.maxLimit ?? 100;
+    const defaultSort = entityConfig?.defaultSort ?? "created_at DESC";
+    const relations = entityConfig?.relations;
     if (entity.parent) {
       const listPath = `${basePath}${entity.parent.path}/:${entity.parent.param}${entity.path}`;
       handlers.push(
-        http.get(listPath, async ({ params }) => {
-          const parentId = params[entity.parent.param];
+        http.get(listPath, async ({ request, params: routeParams }) => {
+          const parentId = routeParams[entity.parent.param];
           const parentColumn = toSnakeCase(entity.parent.param);
+          const searchParams = parseSearchParams(request.url);
           return toResponse(
-            await queryList(tableName, parentColumn, parentId)
+            await queryListWithParams(
+              tableName,
+              parentColumn,
+              parentId,
+              searchParams,
+              defaultLimit,
+              maxLimit,
+              defaultSort
+            )
           );
         })
       );
     } else {
       handlers.push(
-        http.get(`${basePath}${entity.path}`, async () => {
-          return toResponse(await queryAll(tableName));
+        http.get(`${basePath}${entity.path}`, async ({ request }) => {
+          const searchParams = parseSearchParams(request.url);
+          return toResponse(
+            await queryListWithParams(
+              tableName,
+              void 0,
+              void 0,
+              searchParams,
+              defaultLimit,
+              maxLimit,
+              defaultSort
+            )
+          );
         })
       );
     }
     handlers.push(
-      http.get(`${basePath}${entity.path}/:id`, async ({ params }) => {
-        const id = params.id;
+      http.get(`${basePath}${entity.path}/:id`, async ({ params: routeParams }) => {
+        const id = routeParams.id;
+        if (relations) {
+          return toResponse(await queryByIdWithRelations(tableName, id, relations));
+        }
         return toResponse(await queryById(tableName, id));
       })
     );
     if (entity.parent) {
       const createPath = `${basePath}${entity.parent.path}/:${entity.parent.param}${entity.path}`;
       handlers.push(
-        http.post(createPath, async ({ request, params }) => {
+        http.post(createPath, async ({ request, params: routeParams }) => {
           const dto = await request.json();
-          const parentId = params[entity.parent.param];
+          const parentId = routeParams[entity.parent.param];
           dto[entity.parent.param] = parentId;
           return toResponse(await insertRow(tableName, dto), 201);
         })
@@ -188,52 +216,137 @@ function deriveMockHandlers(config, mockConfig) {
       );
     }
     handlers.push(
-      http.patch(`${basePath}${entity.path}/:id`, async ({ request, params }) => {
-        const id = params.id;
+      http.patch(`${basePath}${entity.path}/:id`, async ({ request, params: routeParams }) => {
+        const id = routeParams.id;
         const dto = await request.json();
         return toResponse(await updateRow(tableName, id, dto));
       })
     );
     handlers.push(
-      http.delete(`${basePath}${entity.path}/:id`, async ({ params }) => {
-        const id = params.id;
+      http.delete(`${basePath}${entity.path}/:id`, async ({ params: routeParams }) => {
+        const id = routeParams.id;
         return toResponse(await deleteRow(tableName, id));
       })
     );
   }
   return handlers;
 }
-async function queryAll(tableName) {
+function parseSearchParams(requestUrl) {
+  const url = new URL(requestUrl, "http://localhost");
+  const filters = {};
+  let sort;
+  let page;
+  let limit;
+  let cursor;
+  url.searchParams.forEach((value, key) => {
+    if (key === "sort") {
+      sort = value;
+    } else if (key === "page") {
+      page = parseInt(value, 10);
+    } else if (key === "limit") {
+      limit = parseInt(value, 10);
+    } else if (key === "cursor") {
+      cursor = value;
+    } else {
+      filters[key] = value;
+    }
+  });
+  return { filters, sort, page, limit, cursor };
+}
+async function queryListWithParams(tableName, parentColumn, parentId, searchParams, defaultLimit, maxLimit, defaultSort) {
   try {
     const db = getPGliteInstance();
-    const result = await db.query(`SELECT * FROM ${tableName} ORDER BY created_at DESC`);
-    return mockSuccess(mapRows(result.rows));
+    const conditions = [];
+    const values = [];
+    let paramIndex = 1;
+    if (parentColumn && parentId) {
+      conditions.push(`${parentColumn} = $${paramIndex}`);
+      values.push(parentId);
+      paramIndex++;
+    }
+    for (const [key, value] of Object.entries(searchParams.filters)) {
+      const column = toSnakeCase(key);
+      conditions.push(`${column} = $${paramIndex}`);
+      values.push(value);
+      paramIndex++;
+    }
+    const whereClause = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+    let orderClause = `ORDER BY ${defaultSort}`;
+    if (searchParams.sort) {
+      const sortParts = searchParams.sort.split(",").map((s) => {
+        const [field, dir] = s.trim().split(":");
+        const column = toSnakeCase(field);
+        const direction = dir === "desc" ? "DESC" : "ASC";
+        return `${column} ${direction}`;
+      });
+      orderClause = `ORDER BY ${sortParts.join(", ")}`;
+    }
+    const hasPagination = searchParams.page !== void 0 || searchParams.cursor !== void 0;
+    const limit = Math.min(searchParams.limit ?? defaultLimit, maxLimit);
+    if (hasPagination) {
+      const countSql = `SELECT COUNT(*) as count FROM ${tableName} ${whereClause}`;
+      const countResult = await db.query(countSql, values);
+      const total = parseInt(String(countResult.rows[0].count), 10);
+      const page = searchParams.page ?? 1;
+      const offset = (page - 1) * limit;
+      const dataSql = `SELECT * FROM ${tableName} ${whereClause} ${orderClause} LIMIT ${limit} OFFSET ${offset}`;
+      const dataResult = await db.query(dataSql, values);
+      const rows = mapRows(dataResult.rows);
+      return mockSuccess({
+        data: rows,
+        meta: {
+          total,
+          page,
+          limit,
+          hasNextPage: offset + rows.length < total
+        }
+      });
+    }
+    const sql = `SELECT * FROM ${tableName} ${whereClause} ${orderClause}`;
+    const result = await db.query(sql, values);
+    return mockSuccess({ data: mapRows(result.rows) });
   } catch (err) {
     const mapped = mapPgError(err);
     return mockFailure({ code: mapped.code, message: mapped.message });
   }
 }
-async function queryList(tableName, parentColumn, parentId) {
+async function queryById(tableName, id) {
   try {
     const db = getPGliteInstance();
-    const result = await db.query(
-      `SELECT * FROM ${tableName} WHERE ${parentColumn} = $1 ORDER BY created_at DESC`,
-      [parentId]
-    );
-    return mockSuccess(mapRows(result.rows));
+    const result = await db.query(`SELECT * FROM ${tableName} WHERE id = $1`, [id]);
+    if (result.rows.length === 0) {
+      return mockFailure({ code: "not_found", message: `${tableName} not found` });
+    }
+    return mockSuccess(mapRow(result.rows[0]));
   } catch (err) {
     const mapped = mapPgError(err);
     return mockFailure({ code: mapped.code, message: mapped.message });
   }
 }
-async function queryById(tableName, id) {
+async function queryByIdWithRelations(tableName, id, relations) {
   try {
     const db = getPGliteInstance();
-    const result = await db.query(`SELECT * FROM ${tableName} WHERE id = $1`, [id]);
-    if (result.rows.length === 0) {
+    const mainResult = await db.query(`SELECT * FROM ${tableName} WHERE id = $1`, [id]);
+    if (mainResult.rows.length === 0) {
       return mockFailure({ code: "not_found", message: `${tableName} not found` });
     }
-    return mockSuccess(mapRow(result.rows[0]));
+    const row = mainResult.rows[0];
+    const mapped = mapRow(row);
+    for (const [relationName, relation] of Object.entries(relations)) {
+      const localColumn = toSnakeCase(relation.localKey);
+      const fkValue = row[localColumn];
+      if (fkValue) {
+        const foreignKey = relation.foreignKey ?? "id";
+        const relResult = await db.query(
+          `SELECT * FROM ${relation.table} WHERE ${foreignKey} = $1`,
+          [fkValue]
+        );
+        if (relResult.rows.length > 0) {
+          mapped[relationName] = mapRow(relResult.rows[0]);
+        }
+      }
+    }
+    return mockSuccess(mapped);
   } catch (err) {
     const mapped = mapPgError(err);
     return mockFailure({ code: mapped.code, message: mapped.message });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplix-react/mock",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "description": "Auto-generated MSW handlers and PGlite repositories from @simplix-react/contract",
   "type": "module",
   "exports": {
@@ -9,7 +9,12 @@
       "import": "./dist/index.js"
     }
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
@@ -19,19 +24,24 @@
     "clean": "rm -rf dist .turbo"
   },
   "peerDependencies": {
-    "@simplix-react/contract": "workspace:*",
     "@electric-sql/pglite": ">=0.2.0",
+    "@simplix-react/contract": "workspace:*",
     "msw": ">=2.0.0",
     "zod": ">=4.0.0"
   },
   "peerDependenciesMeta": {
-    "@electric-sql/pglite": { "optional": true },
-    "msw": { "optional": true }
+    "@electric-sql/pglite": {
+      "optional": true
+    },
+    "msw": {
+      "optional": true
+    }
   },
   "devDependencies": {
+    "@electric-sql/pglite": "^0.3.14",
+    "@simplix-react/config-eslint": "workspace:*",
     "@simplix-react/config-typescript": "workspace:*",
     "@simplix-react/contract": "workspace:*",
-    "@electric-sql/pglite": "^0.3.14",
     "eslint": "^9.39.2",
     "msw": "^2.7.0",
     "tsup": "^8.5.1",