schematic-pg 0.1.6 → 0.1.8

package/README.md

@@ -25,6 +25,7 @@ Most backend frameworks force you to scatter your truth across migrations, ORM m
 - **Type-safe Database Client** — Prisma-like query API over parameterized raw SQL (`pg` Pool, no ORM), with nested `include` eager-loading
 - **Type-safe REST API** — Hono routes with generated Zod validation
 - **Custom routes** — Hand-written Hono routers in `src/routes/` auto-imported into the generated app
+- **Lifecycle hooks** — Before/after create, update, and delete with Express-style `next()` cancel semantics; scaffold via `hooks:add`
 - **Inline ACL** — Row-level and role-based access control via `@policy` directives, enforced at runtime in generated routes
 - **Validation Rules** — `@regex` and `@range` constraints that flow into generated Zod request validators (with custom error messages from the schema)
 - **Migration Ready** — Full regeneration today, diff-based migrations tomorrow
@@ -58,7 +59,7 @@ models {
     createdAt: TIMESTAMP   @default(now())
     updatedAt: TIMESTAMP?
 
-    profile:   Profile?    @relation(name: "UserProfile")
+    profile:   Profile?
     orders:    Order[]
 
     @policy(role: USER, allow: [select, insert, update], where: "id = {{auth.user.id}}")
@@ -88,7 +89,6 @@ models {
     location: POINT
 
     user:     User        @relation(
-      name: "UserProfile",
       fields: [userId],
       references: [id],
       onDelete: CASCADE,
@@ -155,6 +155,62 @@ models {
 }
 ```
 
+### Relations (`@relation`)
+
+Relation fields point at another model (`Profile?`, `Order[]`). The side that owns the foreign-key column must declare `@relation` with `fields` and `references`:
+
+```ts
+model User {
+  profile: Profile?   // inverse — no @relation needed
+  orders:  Order[]
+}
+
+model Profile {
+  userId: UUID @unique
+  user:   User @relation(
+    fields: [userId],
+    references: [id],
+    onDelete: CASCADE,   // optional
+    onUpdate: SET_NULL   // optional
+  )
+}
+
+model Order {
+  userId: UUID
+  user:   User @relation(fields: [userId], references: [id])
+}
+```
+
+| Argument | Required | Side | Purpose |
+|----------|----------|------|---------|
+| `fields` | Yes (FK side) | FK owner | Local column(s) on this model |
+| `references` | Yes (FK side) | FK owner | Target column(s) on the related model |
+| `onDelete` | No | FK side | PostgreSQL `ON DELETE` action (`CASCADE`, `SET NULL`, …) |
+| `onUpdate` | No | FK side | PostgreSQL `ON UPDATE` action |
+| `name` | No | Both (must match) | Disambiguates multiple relations between the same two models |
+
+**FK owner vs inverse.** Put `fields` and `references` on the model that stores the foreign key (`Profile.userId` → `user` on `Profile`). The other side (`User.profile`) is inferred automatically — list fields become `hasMany`, optional scalars become `hasOne` / `belongsTo` on the FK side.
+
+**`name` is only for disambiguation.** When a single link exists between two models (like `User` ↔ `Profile`), you do not need `name` on either side. Use matching `name` values only when two models relate more than once:
+
+```ts
+model User {
+  writtenPosts: Post[] @relation(name: "PostAuthor")
+  editedPosts:  Post[] @relation(name: "PostEditor")
+}
+
+model Post {
+  authorId: UUID
+  editorId: UUID?
+  author: User @relation(name: "PostAuthor", fields: [authorId], references: [id])
+  editor: User? @relation(name: "PostEditor", fields: [editorId], references: [id])
+}
+```
+
+If either side declares `name`, the other side must use the same `name` (or omit `@relation` entirely on the inverse when no `name` is used anywhere).
+
+**Runtime keys.** `include` and API relation paths use the **field name** (`profile`, `orders`, `user`) — not the optional `name` argument. `name` is never used for SQL constraint names; foreign keys are named from table and column names.
+
 ---
 
 ## How It Works
@@ -267,7 +323,7 @@ Generated code imports the runtime from the `schematic-pg` package (`schematic-p
 | `JWT_ROLE_CLAIM` | `role` | JWT claim mapped to `auth.role` |
 | `JWT_USER_ID_CLAIM` | `sub` | JWT claim mapped to `auth.user.id` |
 
-Set these in `.env` before running `dev` or `db:bootstrap`.
+Set these in `.env` before running `dev`, `start`, or `db:bootstrap`.
 
 ---
 
@@ -292,6 +348,14 @@ schematic-pg generate:api [schema]      # generated/app.ts, routes/, policies, s
 
 Run `generate:client` before `generate:api` when using the split commands — routes depend on `generated/db.ts`.
 
+### Lifecycle hooks scaffolding
+
+```bash
+schematic-pg hooks:add [schema] [--model ModelName]
+```
+
+Reads `app.schema`, prompts for a model (or accepts `--model`), and writes `src/hooks/{Model}.ts` with all six lifecycle hooks pre-filled. Delete any hooks you do not need, then run `generate:api` to wire them into POST/PUT/DELETE routes. Existing hook files are never overwritten.
+
 ### Development server
 
 ```bash
@@ -312,9 +376,55 @@ Equivalent npm scripts in a project created by `init`:
 ```bash
 make dev           # docker compose up -d --wait + schematic-pg dev
 npm run dev        # schematic-pg dev
+npm run start      # schematic-pg start (production)
 npm run generate   # schematic-pg generate
 ```
 
+### Production server
+
+```bash
+schematic-pg start [schema] [--no-migrate]
+```
+
+`start` runs the app in production mode — no code generation, no schema watching:
+
+1. Verifies `generated/app.ts` exists (run `generate` in your build step if missing)
+2. Waits for PostgreSQL to accept connections
+3. Applies pending migration files (default; skip with `--no-migrate`)
+4. Starts `generated/app.ts` with `NODE_ENV=production` until exit
+
+The optional `[schema]` argument is only used for migration snapshot resolution (same as `db:migrate`).
+
+| Step | `dev` | `start` |
+|------|-------|---------|
+| Generate code | Yes | No |
+| DB bootstrap | Yes | No |
+| Apply pending migrations | No | Yes (default) |
+| Wait for Postgres | Yes (via bootstrap) | Yes |
+| Schema file watch | Yes (default) | No |
+| `NODE_ENV` | unset | `production` |
+
+Example deploy flow:
+
+```bash
+npx schematic-pg generate          # build step in CI
+npx schematic-pg start             # migrate DB + run server
+# or: npm run start
+```
+
+Pass `--no-migrate` when migrations are applied separately (e.g. in a release job):
+
+```bash
+npx schematic-pg db:migrate
+npx schematic-pg start --no-migrate
+```
+
+Equivalent npm scripts in a project created by `init`:
+
+```bash
+npm run start      # schematic-pg start
+```
+
 ### Database commands
 
 ```bash
@@ -355,6 +465,7 @@ npm run generate:client       # write generated/db*.ts
 npm run generate:api          # write generated/app.ts, routes/, schemas/
 npm run db:bootstrap          # apply DDL + snapshot schema state
 npm run dev:api               # regenerate client + API and start server on :3000
+npm run start                 # production server (migrate + run generated/app.ts)
 npm test                      # unit tests
 npm run test:integration      # Docker + generate + DB client + ACL integration tests
 ```
@@ -676,7 +787,15 @@ npx schematic-pg dev
 # → regenerates client + API, then starts http://localhost:3000
 ```
 
-Or run the generated entry point directly after generation:
+For production (no regenerate, no schema watch):
+
+```bash
+npx schematic-pg start
+# or: npm run start
+# → waits for DB, applies pending migrations, starts http://localhost:3000
+```
+
+Or run the generated entry point directly after generation (skips migration wait):
 
 ```bash
 npx tsx generated/app.ts
@@ -764,14 +883,110 @@ router.get('/me', async (c) => {
 
 **Do not edit** `generated/app.ts` manually for custom routes — add files under `src/routes/` and regenerate.
 
+### Lifecycle hooks
+
+Run business logic before or after write operations (POST, PUT, DELETE) without editing generated route files. Hooks live under `src/hooks/` and are discovered when you run `schematic-pg generate:api` (or `schematic-pg dev`).
+
+**Convention**
+
+| Rule | Example |
+|------|---------|
+| Location | `src/hooks/{Model}.ts` (PascalCase model name) |
+| Export | `export default defineHooks(...)` |
+| Scaffold | `schematic-pg hooks:add` (interactive model picker) |
+| Regenerate | `schematic-pg generate:api` or `schematic-pg dev` after adding or editing hooks |
+
+**Request flow**
+
+```
+validate → assertPolicy → beforeHooks (can cancel) → db.create/update/delete → afterHooks → response
+```
+
+Before-hooks run after policy checks — unauthorized requests never execute hook logic. After-hooks see the DB result and can mutate `ctx.result` before the response is sent.
+
+**`next()` contract**
+
+| Action | Effect |
+|--------|--------|
+| `await next()` | Proceed to the next hook, or to the DB operation when all hooks call `next()` |
+| `return ctx.abort(status, message)` | Cancel; return that JSON error response; DB untouched |
+| `return ctx.json(body, status)` | Cancel with a custom response body |
+| Return without calling `next()` | Cancel with default `409` |
+| `throw` | Cancel; mapped by global error handler |
+
+**Scaffold a hook file**
+
+```bash
+schematic-pg hooks:add          # interactive — pick a model
+schematic-pg hooks:add --model User
+# edit src/hooks/User.ts — delete unused hooks
+schematic-pg generate:api
+```
+
+**Example** — `src/hooks/User.ts`:
+
+```typescript
+import { defineHooks } from 'schematic-pg/api/hooks';
+import type { User, UserCreateInput, UserUpdateInput } from '../../generated/db-types.js';
+
+export default defineHooks<User, UserCreateInput, UserUpdateInput>({
+  async beforeCreate(ctx, next) {
+    ctx.data.email = ctx.data.email.toLowerCase();
+    if (ctx.data.balance < 0) {
+      return ctx.abort(422, 'balance must be >= 0');
+    }
+    await next();
+  },
+
+  async afterCreate(ctx) {
+    await ctx.db.log.create({
+      level: 'info',
+      message: `User created: ${ctx.result.id}`,
+    });
+  },
+
+  async beforeDelete(ctx, next) {
+    if (ctx.auth.role !== 'ADMIN') {
+      return ctx.abort(403, 'Only admins can delete users');
+    }
+    await next();
+  },
+});
+```
+
+After `schematic-pg generate:api`, `generated/routes/users.ts` wraps POST/PUT/DELETE with hook calls, and `generated/app.ts` loads the registry:
+
+```typescript
+import { HOOKS } from './hooks.js';
+import { configureHooks } from 'schematic-pg/api/hooks';
+// ...
+configureHooks(HOOKS);
+```
+
+**Hook context**
+
+| Field | beforeCreate / beforeUpdate | beforeDelete | after* |
+|-------|----------------------------|--------------|--------|
+| `ctx.data` | Create/update payload (mutable) | — | — |
+| `ctx.params` | Route params (`:id`, composite PK fields) | Route params | Route params |
+| `ctx.result` | — | — | DB row (mutable) |
+| `ctx.auth` | JWT auth context | JWT auth context | JWT auth context |
+| `ctx.db` | Generated DB client | Generated DB client | Generated DB client |
+| `ctx.abort(status, msg)` | Cancel with JSON error | Cancel with JSON error | — |
+| `ctx.json(body, status)` | Cancel with custom body | Cancel with custom body | — |
+
+**Skipped files** — The scanner ignores `*.test.ts`, `*.d.ts`, and any file whose name starts with `_`.
+
+**Do not edit** generated route hook wiring manually — add or edit files under `src/hooks/` and regenerate.
+
 ### Endpoints
 
 Every router exposes the same CRUD shape. Models with `@policy` attributes enforce role checks and row-level filters on every handler; models without policies behave as open endpoints.
 
 | Method | Path | Handler | Validation |
 |--------|------|---------|------------|
-| `GET` | `/` | `findMany({ where: mergeWhere(queryWhere, policyWhere), orderBy, take, skip })` | Query params |
-| `GET` | `/{pk}` | `findUnique(mergeWhere(pk, policyWhere))` | Path params |
+| `GET` | `/` | `findMany({ where: mergeWhere(queryWhere, policyWhere), orderBy, take, skip, include })` | Query params |
+| `GET` | `/{pk}` | `findUnique(mergeWhere(pk, policyWhere), { include })` | Path params + query params |
 | `POST` | `/` | `create(body)` — policy check only | JSON body |
 | `PUT` | `/{pk}` | `update({ where: mergeWhere(pk, policyWhere), data })` | Path params + JSON body |
 | `DELETE` | `/{pk}` | `delete(mergeWhere(pk, policyWhere))` | Path params |
@@ -793,17 +1008,43 @@ Query params use **API field names** (camelCase), not SQL column names:
 | `?limit=20` | `take: 20` (max 100) |
 | `?offset=40` | `skip: 40` |
 | `?sort=-createdAt` | `orderBy: { createdAt: 'desc' }` |
+| `?include=profile,orders` | `include: { profile: true, orders: true }` |
+| `?include=orders.products.product` | nested boolean includes |
 
 On models with `@policy`, user filters are combined with the policy row filter via `mergeWhere` (AND). A USER calling `GET /users?role=ADMIN` still only sees rows allowed by policy.
 
 ```bash
 curl "http://localhost:3000/products?category=books&limit=10"
 curl "http://localhost:3000/users?role=USER&isActive=true" -H "Authorization: Bearer $TOKEN"
+curl "http://localhost:3000/users/USER_ID?include=profile,orders" -H "Authorization: Bearer $TOKEN"
 ```
 
+### Relation includes (`GET /`, `GET /{pk}`)
+
+Load related models via the `include` query param. Paths are comma-separated; use dots for nesting:
+
+```bash
+curl "http://localhost:3000/users?include=profile,orders"
+curl "http://localhost:3000/users/USER_ID?include=orders.products.product"
+```
+
+Each segment must name a relation field on the current model (or nested target model). Unknown relations return `400`. Maximum depth and path count are capped (see `MAX_INCLUDE_DEPTH` / `MAX_INCLUDE_PATHS` in the runtime).
+
+Opt out of HTTP includes on a relation field with `@unincludeable`:
+
+```ts
+orders: Order[] @unincludeable
+```
+
+**v1 limits:**
+
+- Boolean includes only — no nested `where`, `take`, or `skip` via URL (use the DB client or a custom route for that).
+- `@policy` row filters apply to the **root** model only; included relations are not policy-filtered separately.
+- `@omit` fields are stripped recursively on nested included objects in read responses.
+
 ### Response shaping (`@omit`)
 
-Mark sensitive stored fields with `@omit` to exclude them from generated route JSON responses (`GET`, `POST`, `PUT`, `DELETE`). The ORM client still returns full entities.
+Mark sensitive stored fields with `@omit` to exclude them from generated route JSON responses. On read endpoints with `include`, omitted fields are stripped recursively on nested relation objects as well. Mutation responses (`POST`, `PUT`, `DELETE`) strip `@omit` fields on the root model only. The ORM client still returns full entities.
 
 ```ts
 passwordHash: VARCHAR(255) @omit @unfilterable @default("")
@@ -1110,6 +1351,7 @@ my-app/
 │   ├── db-model-meta.ts    # Runtime column metadata
 │   ├── app.ts              # Hono entry point (starts server on :3000)
 │   ├── policies.ts         # Generated ACL metadata from @policy
+│   ├── hooks.ts            # Registry of src/hooks/* (wired at startup)
 │   ├── routes/
 │   │   ├── users.ts
 │   │   ├── profiles.ts
@@ -1117,11 +1359,13 @@ my-app/
 │   └── schemas/
 │       └── validation.ts   # Generated Zod schemas
 └── src/
-    └── routes/
-        └── health.ts       # Custom route → GET /health
+    ├── routes/
+    │   └── health.ts       # Custom route → GET /health
+    └── hooks/
+        └── User.ts         # Lifecycle hooks → POST/PUT/DELETE /users
 ```
 
-Framework runtime (query builder, auth middleware, validation) is **not** copied into your project — it is imported from `node_modules/schematic-pg` at runtime. Only `generated/` and `src/routes/` contain project-specific code.
+Framework runtime (query builder, auth middleware, validation, hook registry) is **not** copied into your project — it is imported from `node_modules/schematic-pg` at runtime. Only `generated/`, `src/routes/`, and `src/hooks/` contain project-specific code.
 
 ### This repository (framework source)
 
@@ -1159,7 +1403,7 @@ postgrest.js/
 
 ## Roadmap
 
-- [x] npm package + CLI (`schematic-pg init`, `generate`, `dev`, `db:*`)
+- [x] npm package + CLI (`schematic-pg init`, `generate`, `dev`, `start`, `db:*`)
 - [x] Hand-written lexer & recursive-descent parser
 - [x] SQL DDL generator (full regeneration)
 - [x] Type-safe database client generator (`createDbClient`, parameterized query builder)
@@ -1169,6 +1413,7 @@ postgrest.js/
 - [x] Row-level policy injection (`WHERE` clause from `where:` templates)
 - [x] JWT authentication (default Bearer resolver, pluggable `AuthResolver`)
 - [x] Custom routes (`src/routes/` auto-imported into generated app)
+- [x] Lifecycle hooks (`src/hooks/` before/after create-update-delete, `hooks:add` CLI)
 - [x] Relation `include` in DB client (nested eager-loading, split + json_agg strategies)
 - [ ] Type generation for frontend consumption
 - [ ] Tree-sitter grammar for editor support

package/dist/api/hooks/define.d.ts

@@ -0,0 +1,10 @@
+import type { AfterHook, BeforeHook, ModelHooks } from './types.js';
+export interface TypedModelHooks<TRow, TCreate, TUpdate> {
+    beforeCreate?: BeforeHook | BeforeHook[];
+    afterCreate?: AfterHook | AfterHook[];
+    beforeUpdate?: BeforeHook | BeforeHook[];
+    afterUpdate?: AfterHook | AfterHook[];
+    beforeDelete?: BeforeHook | BeforeHook[];
+    afterDelete?: AfterHook | AfterHook[];
+}
+export declare function defineHooks<TRow, TCreate, TUpdate>(hooks: TypedModelHooks<TRow, TCreate, TUpdate>): ModelHooks;

package/dist/api/hooks/define.js

@@ -0,0 +1,3 @@
+export function defineHooks(hooks) {
+    return hooks;
+}

package/dist/api/hooks/index.d.ts

@@ -0,0 +1,4 @@
+export { defineHooks } from './define.js';
+export type { TypedModelHooks } from './define.js';
+export { cancelledResponse, configureHooks, createHookContext, runAfterHooks, runBeforeHooks, } from './registry.js';
+export type { AfterHook, AfterHookContext, BeforeHook, BeforeHookContext, BeforeHookNext, BeforeHookResult, CreateHookContextInput, HookOperation, HookRegistry, ModelHooks, } from './types.js';

package/dist/api/hooks/index.js

@@ -0,0 +1,2 @@
+export { defineHooks } from './define.js';
+export { cancelledResponse, configureHooks, createHookContext, runAfterHooks, runBeforeHooks, } from './registry.js';

package/dist/api/hooks/registry.d.ts

@@ -0,0 +1,8 @@
+import type { Context } from 'hono';
+import type { AppEnv } from '../types.js';
+import type { AfterHookContext, BeforeHookContext, BeforeHookResult, CreateHookContextInput, HookOperation, HookRegistry } from './types.js';
+export declare function configureHooks(next: HookRegistry): void;
+export declare function createHookContext(init: CreateHookContextInput): BeforeHookContext;
+export declare function cancelledResponse(c: Context<AppEnv>): Response;
+export declare function runBeforeHooks(model: string, operation: HookOperation, ctx: BeforeHookContext): Promise<BeforeHookResult>;
+export declare function runAfterHooks(model: string, operation: HookOperation, ctx: AfterHookContext): Promise<void>;

package/dist/api/hooks/registry.js

@@ -0,0 +1,94 @@
+const HOOK_CANCELLED_STATUS = 409;
+const HOOK_CANCELLED_MESSAGE = 'Operation cancelled by lifecycle hook';
+const BEFORE_HOOK_KEYS = {
+    create: 'beforeCreate',
+    update: 'beforeUpdate',
+    delete: 'beforeDelete',
+};
+const AFTER_HOOK_KEYS = {
+    create: 'afterCreate',
+    update: 'afterUpdate',
+    delete: 'afterDelete',
+};
+let hooks = {};
+export function configureHooks(next) {
+    hooks = next;
+}
+export function createHookContext(init) {
+    return {
+        model: init.model,
+        operation: init.operation,
+        auth: init.auth,
+        params: init.params,
+        db: init.db,
+        c: init.c,
+        data: init.data ?? {},
+        result: init.result,
+        abort(status, message) {
+            return init.c.json({ error: message }, status);
+        },
+        json(body, status = 200) {
+            return init.c.json(body, status);
+        },
+    };
+}
+export function cancelledResponse(c) {
+    return c.json({ error: HOOK_CANCELLED_MESSAGE }, HOOK_CANCELLED_STATUS);
+}
+export async function runBeforeHooks(model, operation, ctx) {
+    const modelHooks = hooks[model];
+    if (!modelHooks) {
+        return { proceed: true };
+    }
+    const hookDef = modelHooks[BEFORE_HOOK_KEYS[operation]];
+    if (!hookDef) {
+        return { proceed: true };
+    }
+    const hookList = normalizeHookList(hookDef);
+    let index = -1;
+    return dispatchBeforeHooks(hookList, ctx, 0, () => index, (nextIndex) => {
+        index = nextIndex;
+    });
+}
+export async function runAfterHooks(model, operation, ctx) {
+    const modelHooks = hooks[model];
+    if (!modelHooks) {
+        return;
+    }
+    const hookDef = modelHooks[AFTER_HOOK_KEYS[operation]];
+    if (!hookDef) {
+        return;
+    }
+    const hookList = normalizeHookList(hookDef);
+    for (const hook of hookList) {
+        await hook(ctx);
+    }
+}
+function normalizeHookList(hookDef) {
+    return Array.isArray(hookDef) ? hookDef : [hookDef];
+}
+async function dispatchBeforeHooks(hookList, ctx, currentIndex, getDispatchedIndex, setDispatchedIndex) {
+    if (currentIndex <= getDispatchedIndex()) {
+        throw new Error('next() called multiple times');
+    }
+    setDispatchedIndex(currentIndex);
+    if (currentIndex === hookList.length) {
+        return { proceed: true };
+    }
+    const hook = hookList[currentIndex];
+    let innerResult = { proceed: false };
+    let nextCalled = false;
+    const next = async () => {
+        nextCalled = true;
+        innerResult = await dispatchBeforeHooks(hookList, ctx, currentIndex + 1, getDispatchedIndex, setDispatchedIndex);
+        return innerResult;
+    };
+    const result = await hook(ctx, next);
+    if (result instanceof Response) {
+        return { proceed: false, response: result };
+    }
+    if (!nextCalled) {
+        return { proceed: false };
+    }
+    return innerResult;
+}

package/dist/api/hooks/types.d.ts

@@ -0,0 +1,48 @@
+import type { Context } from 'hono';
+import type { DbClient } from 'generated/db.js';
+import type { AuthContext } from '../auth/types.js';
+import type { AppEnv } from '../types.js';
+export type HookOperation = 'create' | 'update' | 'delete';
+export interface HookContextBase {
+    model: string;
+    operation: HookOperation;
+    auth: AuthContext;
+    params?: Record<string, unknown>;
+    db: DbClient;
+    c: Context<AppEnv>;
+    abort: (status: number, message: string) => Response;
+    json: (body: unknown, status?: number) => Response;
+}
+export interface BeforeHookContext<TData = Record<string, unknown>> extends HookContextBase {
+    data: TData;
+    result?: unknown;
+}
+export interface AfterHookContext<TRow = Record<string, unknown>> extends HookContextBase {
+    result: TRow;
+}
+export type BeforeHookNext = () => Promise<BeforeHookResult>;
+export type BeforeHook = (ctx: BeforeHookContext, next: BeforeHookNext) => Promise<Response | void>;
+export type AfterHook = (ctx: AfterHookContext) => Promise<void>;
+export interface ModelHooks {
+    beforeCreate?: BeforeHook | BeforeHook[];
+    afterCreate?: AfterHook | AfterHook[];
+    beforeUpdate?: BeforeHook | BeforeHook[];
+    afterUpdate?: AfterHook | AfterHook[];
+    beforeDelete?: BeforeHook | BeforeHook[];
+    afterDelete?: AfterHook | AfterHook[];
+}
+export type HookRegistry = Record<string, ModelHooks>;
+export interface BeforeHookResult {
+    proceed: boolean;
+    response?: Response;
+}
+export interface CreateHookContextInput {
+    c: Context<AppEnv>;
+    db: DbClient;
+    auth: AuthContext;
+    model: string;
+    operation: HookOperation;
+    data?: Record<string, unknown>;
+    params?: Record<string, unknown>;
+    result?: unknown;
+}

package/dist/api/hooks/types.js

@@ -0,0 +1 @@
+export {};

package/dist/api/utils/include-query.d.ts

@@ -0,0 +1,6 @@
+import type { IncludeInput } from '../../db/include/types.js';
+export interface IncludableRelationTree {
+    [relationName: string]: IncludableRelationTree;
+}
+export declare function validateIncludePaths(raw: string, tree: IncludableRelationTree): string | undefined;
+export declare function parseIncludeQuery(raw: string, tree: IncludableRelationTree): IncludeInput;

package/dist/api/utils/include-query.js

@@ -0,0 +1,75 @@
+import { MAX_INCLUDE_DEPTH, MAX_INCLUDE_PATHS } from '../../constants.js';
+export function validateIncludePaths(raw, tree) {
+    const segments = splitIncludePaths(raw);
+    if (segments.some((segment) => segment.length === 0)) {
+        return 'Include paths cannot contain empty relation segments';
+    }
+    if (segments.length === 0) {
+        return 'Include parameter must contain at least one relation path';
+    }
+    if (segments.length > MAX_INCLUDE_PATHS) {
+        return `Include parameter exceeds maximum of ${MAX_INCLUDE_PATHS} paths`;
+    }
+    for (const segment of segments) {
+        const parts = segment.split('.');
+        if (parts.length > MAX_INCLUDE_DEPTH) {
+            return `Include path "${segment}" exceeds maximum depth of ${MAX_INCLUDE_DEPTH}`;
+        }
+        let currentTree = tree;
+        for (const part of parts) {
+            if (!part) {
+                return 'Include paths cannot contain empty relation segments';
+            }
+            const nextTree = currentTree[part];
+            if (!nextTree) {
+                return `Unknown include relation "${part}" in path "${segment}"`;
+            }
+            currentTree = nextTree;
+        }
+    }
+    return undefined;
+}
+export function parseIncludeQuery(raw, tree) {
+    const error = validateIncludePaths(raw, tree);
+    if (error) {
+        throw new Error(error);
+    }
+    const root = {};
+    for (const segment of splitIncludePaths(raw)) {
+        mergeIncludePath(root, segment.split('.'));
+    }
+    return toIncludeInput(root);
+}
+function splitIncludePaths(raw) {
+    return raw.split(',').map((segment) => segment.trim());
+}
+function mergeIncludePath(root, parts) {
+    let current = root;
+    for (let index = 0; index < parts.length; index += 1) {
+        const part = parts[index];
+        const isLeaf = index === parts.length - 1;
+        if (!current[part]) {
+            current[part] = {};
+        }
+        if (isLeaf) {
+            continue;
+        }
+        if (!current[part].include) {
+            current[part].include = {};
+        }
+        current = current[part].include;
+    }
+}
+function toIncludeInput(nodes) {
+    const include = {};
+    for (const [relationName, node] of Object.entries(nodes)) {
+        if (node.include && Object.keys(node.include).length > 0) {
+            include[relationName] = {
+                include: toIncludeInput(node.include),
+            };
+            continue;
+        }
+        include[relationName] = true;
+    }
+    return include;
+}

package/dist/api/utils/read-query.d.ts

@@ -0,0 +1,12 @@
+import type { FilterFieldMeta } from './list-query.js';
+import { buildListQuery } from './list-query.js';
+import type { IncludeInput } from '../../db/include/types.js';
+import type { IncludableRelationTree } from './include-query.js';
+export interface ReadQueryResult {
+    where: ReturnType<typeof buildListQuery>['where'];
+    orderBy?: ReturnType<typeof buildListQuery>['orderBy'];
+    take?: number;
+    skip?: number;
+    include?: IncludeInput;
+}
+export declare function buildReadQuery(query: Record<string, unknown>, fields: readonly FilterFieldMeta[], sortableFields: readonly string[], includableRelations: IncludableRelationTree): ReadQueryResult;

package/dist/api/utils/read-query.js

@@ -0,0 +1,10 @@
+import { buildListQuery } from './list-query.js';
+import { parseIncludeQuery } from './include-query.js';
+export function buildReadQuery(query, fields, sortableFields, includableRelations) {
+    const { where, orderBy, take, skip } = buildListQuery(query, fields, sortableFields);
+    const result = { where, orderBy, take, skip };
+    if (typeof query.include === 'string' && query.include.length > 0) {
+        result.include = parseIncludeQuery(query.include, includableRelations);
+    }
+    return result;
+}