@vulog/aima-core/README.md

Shared types and Zod schema helpers for pagination and patch actions.

# @vulog/aima-core

Shared types and Zod schema helpers for pagination and patch actions.

## Installation

```sh
npm install @vulog/aima-core zod
```

## Usage

```ts
import { createPaginableOptionsSchema, PaginableOptions, PaginableResponse, PatchAction } from '@vulog/aima-core';

// Create a schema for paginated options with custom filters
const schema = createPaginableOptionsSchema(myFiltersSchema, mySortSchema);
```

## API Reference

### createPaginableOptionsSchema

```ts
createPaginableOptionsSchema<T, S>(optionsSchema?: T, sortSchema?: S): ZodObject
```

Zod schema factory for paginated query options.

| Parameter | Type | Description |
|-----------|------|-------------|
| `optionsSchema` | `T` (optional) | Zod schema for filter fields — produces a `filters` key when provided |
| `sortSchema` | `S` (optional) | Zod schema for the `sort` field — defaults to `z.string().optional()` |

Generated schema fields:

| Field | Type | Default |
|-------|------|---------|
| `page` | integer >= 0 | `0` |
| `pageSize` | integer 1–1000 | `100` |
| `sort` | from `sortSchema` | `undefined` |
| `sortDirection` | `'ASC' \| 'DESC'` | `'ASC'` |
| `filters` | from `optionsSchema` | — (only present when `optionsSchema` is provided) |

## Types

### PaginableOptions

```ts
// Without filters (T = void):
type PaginableOptions<T = void, S = string> = {
    page?: number;
    pageSize?: number;
    sort?: S;
    sortDirection?: 'ASC' | 'DESC';
};

// With filters (T provided):
type PaginableOptions<T, S = string> = {
    page?: number;
    pageSize?: number;
    sort?: S;
    sortDirection?: 'ASC' | 'DESC';
    filters?: T;
};
```

### PaginableResponse

```ts
type PaginableResponse<T> = {
    data: T[];
    page: number;
    pageSize: number;
    total: number;
    totalPages: number;
};
```

### PatchAction

```ts
type PatchAction<T extends string> =
    | { op: 'add' | 'replace'; path: T; value: string }
    | { op: 'remove'; path: T };
```