schematic-pg 0.1.3 → 0.1.5

package/README.md

@@ -1,5 +1,8 @@
 # schematic-pg
 
+<img width="1254" height="1254" alt="schematic" src="https://github.com/user-attachments/assets/5b8f35b3-7e99-4779-aca3-ec3dbe27be56" />
+
+
 > A single-file backend framework for PostgreSQL and Node.js. Define your database schema, ACL policies, and validations in one declarative DSL — then generate the SQL, the API, and the types.
 
 ---
@@ -9,7 +12,7 @@
 Most backend frameworks force you to scatter your truth across migrations, ORM models, Zod schemas, route handlers, and access control lists. schematic-pg inverts that: **your schema definition is the source of truth** for everything — the database, the REST API, and the runtime validations.
 
 - **One file.** Schema, relations, triggers, indexes, and ACL in a single `.schema` file.
-- **Zero ORM.** We generate raw PostgreSQL and parameterized queries. No hidden query builders, no N+1 surprises.
+- **Zero ORM.** We generate raw PostgreSQL and parameterized queries. No hidden query builders — relation loading is explicit via `include`, with batched queries that avoid N+1 and cartesian explosion.
 - **Hand-written parser.** A small, fast recursive-descent lexer/parser with zero parser-generator dependencies.
 - **Hono-based runtime.** Lightweight HTTP handlers generated from your schema, with Zod validation on every write.
 
@@ -19,7 +22,7 @@ Most backend frameworks force you to scatter your truth across migrations, ORM m
 
 - **Declarative Schema DSL** — PostgreSQL-native types, enums, extensions, indexes, and triggers
 - **Automatic SQL Generation** — idempotent DDL with snake_case naming conventions
-- **Type-safe Database Client** — Prisma-like query API over parameterized raw SQL (`pg` Pool, no ORM)
+- **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
 - **Inline ACL** — Row-level and role-based access control via `@policy` directives, enforced at runtime in generated routes
@@ -179,7 +182,7 @@ models {
 
 1. **Parse** — The hand-written lexer and recursive-descent parser turn your `.schema` file into a typed AST.
 2. **Generate SQL** — The DDL generator emits idempotent PostgreSQL: extensions, enums, tables, foreign keys, indexes, and triggers. All identifiers are automatically converted to `snake_case`.
-3. **Generate DB client** — The client generator emits TypeScript interfaces and a `createDbClient(pool)` factory with per-model CRUD methods backed by a runtime query builder. All SQL uses `$1`, `$2`, … placeholders — user input is never interpolated.
+3. **Generate DB client** — The client generator emits TypeScript interfaces (including `{Model}Include` types), relation metadata, and a `createDbClient(pool)` factory with per-model CRUD methods and nested `include` eager-loading. All SQL uses `$1`, `$2`, … placeholders — user input is never interpolated.
 4. **Generate API** — The route generator emits Hono routers with:
    - Zod-validated request bodies and path params (driven by `@regex` and `@range`)
    - Full CRUD handlers backed by the generated DB client
@@ -200,6 +203,14 @@ cd my-app
 
 Edit `app.schema`, then generate code and start the API:
 
+```bash
+make dev
+# → starts PostgreSQL, generates code, bootstraps the DB, and runs the dev server
+# → http://localhost:3000
+```
+
+Or run each step individually:
+
 ```bash
 # Start PostgreSQL (PostGIS-enabled, matches .env defaults)
 docker compose up -d
@@ -222,6 +233,7 @@ The `init` command creates everything you need to get running:
 | `app.schema` | Starter schema (one `User` model) — edit this |
 | `.env` | `DATABASE_URL`, JWT settings |
 | `docker-compose.yml` | Local PostGIS PostgreSQL on `:5432` |
+| `Makefile` | `make dev` — docker compose + generate + db:bootstrap + dev |
 | `tsconfig.json` | TypeScript config for `generated/` and `src/routes/` |
 | `package.json` | `schematic-pg` + runtime deps (`hono`, `pg`, `zod`, …) |
 | `src/routes/health.ts` | Example custom route mounted at `/health` |
@@ -283,6 +295,7 @@ schematic-pg dev [schema]   # generate:client + generate:api, then start generat
 Equivalent npm scripts in a project created by `init`:
 
 ```bash
+make dev           # docker compose up -d + generate + db:bootstrap + dev
 npm run dev        # schematic-pg dev
 npm run generate   # schematic-pg generate
 ```
@@ -348,8 +361,8 @@ Outputs:
 
 | File | Purpose |
 |------|---------|
-| `generated/db-types.ts` | Per-model interfaces: `User`, `UserCreateInput`, `UserUpdateInput`, `UserWhereInput`, `UserOrderByInput`, enum unions |
-| `generated/db-model-meta.ts` | Serialized field/column metadata consumed at runtime |
+| `generated/db-types.ts` | Per-model interfaces: `User`, `UserCreateInput`, `UserWhereInput`, `UserInclude`, enum unions |
+| `generated/db-model-meta.ts` | Serialized field/column and relation metadata consumed at runtime |
 | `generated/db.ts` | `createDbClient(pool)` factory wiring all models |
 
 ### Usage
@@ -382,6 +395,29 @@ const many = await db.user.findMany({
 });
 const total = await db.user.count({ where: { role: 'ADMIN' } });
 
+// Eager-load relations (nested)
+const usersWithOrders = await db.user.findMany({
+  where: { role: 'ADMIN' },
+  include: {
+    profile: true,
+    orders: {
+      where: { status: 'PENDING' },
+      orderBy: { createdAt: 'desc' },
+      include: {
+        products: {
+          include: { product: true },
+        },
+      },
+    },
+  },
+});
+
+// include works on all read methods
+const oneWithProfile = await db.user.findUnique(
+  { id: user.id },
+  { include: { profile: true } },
+);
+
 // Update
 const updated = await db.user.update({
   where: { id: user.id },
@@ -404,10 +440,10 @@ Each model in `app.schema` becomes a camelCase property on the client (`User`
 | Method | SQL shape |
 |--------|-----------|
 | `create(data)` | `INSERT INTO … VALUES ($1, …) RETURNING *` |
-| `findUnique(where)` | `SELECT * … WHERE … LIMIT 1` |
-| `findFirst({ where, orderBy })` | `SELECT * … ORDER BY … LIMIT 1` |
-| `findMany({ where, orderBy, take, skip })` | `SELECT * … ORDER BY … LIMIT … OFFSET …` |
-| `count({ where })` | `SELECT COUNT(*) …` |
+| `findUnique(where, { include, … })` | `SELECT * … WHERE … LIMIT 1` (+ batched relation queries when `include` is set) |
+| `findFirst({ where, orderBy, include, … })` | `SELECT * … ORDER BY … LIMIT 1` (+ relation queries when `include` is set) |
+| `findMany({ where, orderBy, take, skip, include, … })` | `SELECT * … ORDER BY … LIMIT … OFFSET …` (+ relation queries when `include` is set) |
+| `count({ where })` | `SELECT COUNT(*) …` (no `include`) |
 | `update({ where, data })` | `UPDATE … SET … WHERE … RETURNING *` |
 | `updateMany({ where, data })` | `UPDATE … SET … WHERE … RETURNING *` |
 | `delete(where)` | `DELETE … WHERE … RETURNING *` |
@@ -415,6 +451,85 @@ Each model in `app.schema` becomes a camelCase property on the client (`User`
 
 Mutations return the full row (`RETURNING *`). Rows are mapped from `snake_case` columns to `camelCase` TypeScript fields.
 
+### Eager loading (`include`)
+
+Load related models in one call and get back a nested JSON tree. Relation fields are inferred from your schema (`orders: Order[]`, `profile: Profile?`, `@relation(fields: …, references: …)`).
+
+**Supported on:** `findMany`, `findFirst`, and `findUnique`. Not on `count`.
+
+```typescript
+// Shorthand — load all columns for the relation
+await db.user.findMany({
+  include: { profile: true, orders: true },
+});
+
+// Nested — arbitrary depth
+await db.user.findMany({
+  include: {
+    orders: {
+      include: {
+        products: {
+          include: { product: true },
+        },
+      },
+    },
+  },
+});
+
+// Filter, sort, and paginate inner relations
+await db.user.findMany({
+  include: {
+    orders: {
+      where: { status: 'PENDING' },
+      orderBy: { createdAt: 'desc' },
+      take: 5,
+      include: { products: true },
+    },
+  },
+});
+```
+
+Each relation key accepts `true` or a `{ where?, orderBy?, take?, skip?, include? }` object (typed as `{Model}IncludeArgs` in `generated/db-types.ts`).
+
+**Return shape:** scalar relation fields (`profile: Profile?`) become `Profile | null`. List relations (`orders: Order[]`) become arrays on the result object. Nested `include` keys are attached on each child row the same way.
+
+#### Loading strategies
+
+By default the client uses **query splitting**: one SQL query for the root rows, then one batched query per included relation level (`WHERE foreign_key = ANY($1)` with deduplicated parent keys). This avoids cartesian explosion when loading multiple `hasMany` relations at the same level (e.g. `profile` + `orders` on `User`).
+
+```typescript
+// Default — split queries (recommended for large result sets)
+await db.user.findMany({
+  include: { orders: true },
+});
+
+// Optional — single round-trip via PostgreSQL LATERAL + json_agg
+await db.user.findMany({
+  include: { profile: true, orders: true },
+  relationLoadStrategy: 'join',
+});
+```
+
+| Strategy | Option | Behavior |
+|----------|--------|----------|
+| Split (default) | omit or `'split'` | One query per relation edge; no row duplication on the wire |
+| Join | `'join'` | One SQL statement; nested JSON built in PostgreSQL |
+
+Use `'join'` when latency dominates (fewer round trips). Use the default split strategy when loading many rows or several sibling collections.
+
+#### How it works
+
+```
+findMany({ include })  →  buildLoadPlan (relation tree from schema metadata)
+                        →  SELECT root rows
+                        →  for each included relation: SELECT … WHERE fk = ANY($parentIds)
+                        →  stitch (hash-join children onto parents in O(n))
+```
+
+Relation metadata is generated into `generated/db-model-meta.ts` and resolved through an in-memory model registry inside `createDbClient`. Include depth is capped at 10 levels.
+
+Generated types: `{Model}Include` and `{Model}IncludeArgs` in `generated/db-types.ts`.
+
 ### Where filters
 
 Direct values are treated as equality. Structured operators are supported per field type:
@@ -492,12 +607,12 @@ schematic-pg/dist/db/        # Published runtime (import as schematic-pg/db/*)
 ├── query-builder.ts        # INSERT / SELECT / UPDATE / DELETE / COUNT
 ├── where-translator.ts     # WhereInput → SQL + params
 ├── model-client.ts         # createModelClient factory
+├── include/                # Eager-loading planner, executor, hydrator, json_agg
+├── utils/relations.ts      # Relation graph from schema AST
 ├── row-mapper.ts           # snake_case rows → camelCase + coercion
 └── errors.ts               # UniqueConstraintError, ForeignKeyConstraintError, …
 ```
 
-Relation `include` (e.g. `findMany({ include: { profile: true } })`) is planned for a future release.
-
 ### Integration tests
 
 One command starts Docker Postgres, generates the client and API, and runs all integration tests (DB client + ACL):
@@ -508,7 +623,7 @@ npm run test:integration
 
 This resets the `public` schema, bootstraps from `app.schema`, seeds test data, and exercises:
 
-- **DB client** — CRUD, filters, and error handling ([`src/db/__tests__/db-client.integration.test.ts`](src/db/__tests__/db-client.integration.test.ts))
+- **DB client** — CRUD, filters, nested `include` eager-loading, and error handling ([`src/db/__tests__/db-client.integration.test.ts`](src/db/__tests__/db-client.integration.test.ts))
 - **ACL over HTTP** — role checks, row-level filters, JWT auth, and open endpoints ([`src/api/__tests__/acl.integration.test.ts`](src/api/__tests__/acl.integration.test.ts))
 
 Tests run in-process via Hono `app.request()` against the exported `createApp()` factory from `generated/app.ts`.
@@ -640,13 +755,46 @@ Every router exposes the same CRUD shape. Models with `@policy` attributes enfor
 
 | Method | Path | Handler | Validation |
 |--------|------|---------|------------|
-| `GET` | `/` | `findMany({ where: policyWhere })` | — |
+| `GET` | `/` | `findMany({ where: mergeWhere(queryWhere, policyWhere), orderBy, take, skip })` | Query params |
 | `GET` | `/{pk}` | `findUnique(mergeWhere(pk, policyWhere))` | Path 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 |
 
-`POST` returns `201 Created`. Missing records on `GET` return `404`.
+`POST` returns `201 Created`. Missing records on `GET` return `404`. All handlers strip `@omit` fields from JSON responses before returning.
+
+### Query filters (`GET /`)
+
+All stored scalar fields are URL-filterable by default. Opt out with `@unfilterable` on a field. Fields marked `@omit` are never filterable.
+
+Query params use **API field names** (camelCase), not SQL column names:
+
+| Param | Maps to |
+|-------|---------|
+| `?role=ADMIN` | `{ role: 'ADMIN' }` |
+| `?email_contains=@` | `{ email: { contains: '@' } }` |
+| `?balance_gte=100` | `{ balance: { gte: 100 } }` |
+| `?role_in=ADMIN,USER` | `{ role: { in: ['ADMIN', 'USER'] } }` |
+| `?limit=20` | `take: 20` (max 100) |
+| `?offset=40` | `skip: 40` |
+| `?sort=-createdAt` | `orderBy: { createdAt: 'desc' }` |
+
+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"
+```
+
+### 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.
+
+```ts
+passwordHash: VARCHAR(255) @omit @unfilterable @default("")
+```
+
+Generated types include `{Model}Response` (for example `UserResponse = Omit<User, 'passwordHash'>`) in `generated/schemas/validation.ts`.
 
 ### Validation
 
@@ -678,6 +826,9 @@ Fields with `@default` or optional (`?`) types are optional on create. Update sc
 # Health check (custom route from src/routes/health.ts)
 curl http://localhost:3000/health
 
+# List users with filters
+curl "http://localhost:3000/users?role=USER&limit=10"
+
 # List users
 curl http://localhost:3000/users
 
@@ -767,8 +918,6 @@ your-project/src/routes/    # Hand-written custom Hono routers (auto-imported)
 
 The generators live in this repo under `src/api-generator/` and are invoked by the CLI at build time.
 
-URL query-string filters for `findMany` (e.g. `?role=ADMIN`) are planned for a future release.
-
 ---
 
 ## Access Control (`@policy`)
@@ -966,7 +1115,7 @@ postgrest.js/
 ├── src/
 │   ├── schema-dsl/         # Lexer, parser, AST
 │   ├── sql-generator/      # DDL + migration planner
-│   ├── db/                 # Query builder + client runtime
+│   ├── db/                 # Query builder + client runtime + include eager-loading
 │   ├── api/                # Hono runtime (published as schematic-pg/api/*)
 │   ├── api-generator/      # AST → routes, Zod, policies, app
 │   ├── cli/                # init templates + command helpers
@@ -986,7 +1135,7 @@ postgrest.js/
 | Schema truth | Migrations + models + Zod + routes | One `.schema` file |
 | Query visibility | Hidden behind ORM methods | Raw, parameterized SQL |
 | Client ergonomics | ORM model API | Generated Prisma-like client, no ORM runtime |
-| Performance | N+1, lazy loading pitfalls | Explicit joins, no magic |
+| Performance | N+1, lazy loading pitfalls | Explicit `include`; batched split queries by default |
 | ACL | External service or manual checks | Inline `@policy` directives |
 | Validation | Separate Zod schemas | Derived from `@regex` / `@range` |
 | Dependencies | Heavy (Prisma, Drizzle, etc.) | Hono + pg + Zod + hand-written parser |
@@ -1005,7 +1154,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)
-- [ ] Relation `include` in DB client
+- [x] Relation `include` in DB client (nested eager-loading, split + json_agg strategies)
 - [ ] Type generation for frontend consumption
 - [ ] Tree-sitter grammar for editor support
 - [x] VS Code extension with syntax highlighting and language server

package/dist/api/middleware/validate.d.ts

@@ -20,4 +20,14 @@ export declare function validateParam<T extends ZodSchema>(schema: T): import("h
         param: T extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").output<T> : T extends import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>> ? import("zod").infer<T> : never;
     };
 }, Response>;
+export declare function validateQuery<T extends ZodSchema>(schema: T): import("hono").MiddlewareHandler<import("hono").Env, string, {
+    in: (undefined extends (T extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<T> : T extends import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>> ? import("zod").input<T> : never) ? true : false) extends true ? {
+        query?: ([T extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<T> : T extends import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>> ? import("zod").input<T> : never] extends [Record<string, string | string[]>] ? Record<string, string | string[]> & (T extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<T> : T extends import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>> ? import("zod").input<T> : never) : [Exclude<T extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<T> : T extends import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>> ? import("zod").input<T> : never, undefined>] extends [never] ? {} : [Exclude<T extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<T> : T extends import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>> ? import("zod").input<T> : never, undefined>] extends [object] ? undefined extends (T extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<T> : T extends import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>> ? import("zod").input<T> : never) ? ((T extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<T> : T extends import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>> ? import("zod").input<T> : never) & undefined) | (((Exclude<T extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<T> : T extends import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>> ? import("zod").input<T> : never, (T extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<T> : T extends import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>> ? import("zod").input<T> : never) & undefined> extends infer T_3 ? { [K_2 in keyof T_3]: ([Exclude<T_3[K_2], undefined>] extends [string] ? [string & Exclude<T_3[K_2], undefined>] extends [import("hono/utils/types").UnionToIntersection<string & Exclude<T_3[K_2], undefined>>] ? false : true : false) extends true ? T_3[K_2] : ([unknown] extends [T_3[K_2]] ? false : undefined extends T_3[K_2] ? true : false) extends true ? T_3[K_2] : Target extends "form" ? T$1 | T$1[] : Target extends "query" ? string | string[] : Target extends "param" ? string : Target extends "header" ? string : Target extends "cookie" ? string : unknown; } : never) extends infer T_2 ? { [K_1 in keyof T_2]: T_2[K_1]; } : never) extends infer T_1 ? { [K in keyof T_1]: T_1[K]; } : never) : (((T extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<T> : T extends import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>> ? import("zod").input<T> : never) extends infer T_6 ? { [K_5 in keyof T_6]: ([Exclude<T_6[K_5], undefined>] extends [string] ? [string & Exclude<T_6[K_5], undefined>] extends [import("hono/utils/types").UnionToIntersection<string & Exclude<T_6[K_5], undefined>>] ? false : true : false) extends true ? T_6[K_5] : ([unknown] extends [T_6[K_5]] ? false : undefined extends T_6[K_5] ? true : false) extends true ? T_6[K_5] : Target extends "form" ? T$1 | T$1[] : Target extends "query" ? string | string[] : Target extends "param" ? string : Target extends "header" ? string : Target extends "cookie" ? string : unknown; } : never) extends infer T_5 ? { [K_4 in keyof T_5]: T_5[K_4]; } : never) extends infer T_4 ? { [K_3 in keyof T_4]: T_4[K_3]; } : never : {}) | undefined;
+    } : {
+        query: [T extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<T> : T extends import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>> ? import("zod").input<T> : never] extends [Record<string, string | string[]>] ? Record<string, string | string[]> & (T extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<T> : T extends import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>> ? import("zod").input<T> : never) : [Exclude<T extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<T> : T extends import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>> ? import("zod").input<T> : never, undefined>] extends [never] ? {} : [Exclude<T extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<T> : T extends import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>> ? import("zod").input<T> : never, undefined>] extends [object] ? undefined extends (T extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<T> : T extends import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>> ? import("zod").input<T> : never) ? ((T extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<T> : T extends import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>> ? import("zod").input<T> : never) & undefined) | (((Exclude<T extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<T> : T extends import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>> ? import("zod").input<T> : never, (T extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<T> : T extends import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>> ? import("zod").input<T> : never) & undefined> extends infer T_9 ? { [K_2 in keyof T_9]: ([Exclude<T_9[K_2], undefined>] extends [string] ? [string & Exclude<T_9[K_2], undefined>] extends [import("hono/utils/types").UnionToIntersection<string & Exclude<T_9[K_2], undefined>>] ? false : true : false) extends true ? T_9[K_2] : ([unknown] extends [T_9[K_2]] ? false : undefined extends T_9[K_2] ? true : false) extends true ? T_9[K_2] : Target extends "form" ? T$1 | T$1[] : Target extends "query" ? string | string[] : Target extends "param" ? string : Target extends "header" ? string : Target extends "cookie" ? string : unknown; } : never) extends infer T_8 ? { [K_1 in keyof T_8]: T_8[K_1]; } : never) extends infer T_7 ? { [K in keyof T_7]: T_7[K]; } : never) : (((T extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").input<T> : T extends import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>> ? import("zod").input<T> : never) extends infer T_12 ? { [K_5 in keyof T_12]: ([Exclude<T_12[K_5], undefined>] extends [string] ? [string & Exclude<T_12[K_5], undefined>] extends [import("hono/utils/types").UnionToIntersection<string & Exclude<T_12[K_5], undefined>>] ? false : true : false) extends true ? T_12[K_5] : ([unknown] extends [T_12[K_5]] ? false : undefined extends T_12[K_5] ? true : false) extends true ? T_12[K_5] : Target extends "form" ? T$1 | T$1[] : Target extends "query" ? string | string[] : Target extends "param" ? string : Target extends "header" ? string : Target extends "cookie" ? string : unknown; } : never) extends infer T_11 ? { [K_4 in keyof T_11]: T_11[K_4]; } : never) extends infer T_10 ? { [K_3 in keyof T_10]: T_10[K_3]; } : never : {};
+    };
+    out: {
+        query: T extends import("zod/v3").ZodType<any, import("zod/v3").ZodTypeDef, any> ? import("zod/v3").output<T> : T extends import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>> ? import("zod").infer<T> : never;
+    };
+}, Response>;
 export type ValidationTarget = keyof ValidationTargets;

package/dist/api/middleware/validate.js

@@ -11,3 +11,6 @@ export function validateJson(schema) {
 export function validateParam(schema) {
     return zValidator('param', schema, validationHook);
 }
+export function validateQuery(schema) {
+    return zValidator('query', schema, validationHook);
+}

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

@@ -0,0 +1,16 @@
+import type { WhereInput } from '../../db/where-translator.js';
+export type FilterFieldKind = 'string' | 'enum' | 'numeric' | 'boolean' | 'timestamp' | 'json' | 'other';
+export type FilterOperator = 'equals' | 'contains' | 'startsWith' | 'endsWith' | 'gt' | 'gte' | 'lt' | 'lte' | 'in';
+export interface FilterFieldMeta {
+    name: string;
+    kind: FilterFieldKind;
+    operators: readonly FilterOperator[];
+    enumValues?: readonly string[];
+}
+export interface ListQueryResult {
+    where: WhereInput;
+    orderBy?: Record<string, 'asc' | 'desc'>;
+    take?: number;
+    skip?: number;
+}
+export declare function buildListQuery(query: Record<string, unknown>, fields: readonly FilterFieldMeta[], sortableFields: readonly string[]): ListQueryResult;

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

@@ -0,0 +1,99 @@
+function queryParamKey(fieldName, operator) {
+    if (operator === 'equals') {
+        return fieldName;
+    }
+    return `${fieldName}_${operator}`;
+}
+function parseFilterValue(rawValue, kind, operator) {
+    if (rawValue === undefined || rawValue === null || rawValue === '') {
+        return undefined;
+    }
+    if (operator === 'in') {
+        const values = String(rawValue)
+            .split(',')
+            .map((entry) => entry.trim())
+            .filter((entry) => entry.length > 0);
+        return values.length > 0 ? values : undefined;
+    }
+    if (kind === 'boolean') {
+        if (typeof rawValue === 'boolean') {
+            return rawValue;
+        }
+        const normalized = String(rawValue).toLowerCase();
+        if (normalized === 'true') {
+            return true;
+        }
+        if (normalized === 'false') {
+            return false;
+        }
+        return rawValue;
+    }
+    if (kind === 'numeric') {
+        if (typeof rawValue === 'number') {
+            return rawValue;
+        }
+        const parsed = Number(rawValue);
+        return Number.isNaN(parsed) ? rawValue : parsed;
+    }
+    if (kind === 'timestamp' && !(rawValue instanceof Date)) {
+        const parsed = new Date(String(rawValue));
+        return Number.isNaN(parsed.getTime()) ? rawValue : parsed;
+    }
+    return rawValue;
+}
+function buildFieldCondition(field, operator, rawValue) {
+    const value = parseFilterValue(rawValue, field.kind, operator);
+    if (value === undefined) {
+        return undefined;
+    }
+    if (operator === 'equals') {
+        return { [field.name]: value };
+    }
+    return { [field.name]: { [operator]: value } };
+}
+export function buildListQuery(query, fields, sortableFields) {
+    const whereParts = [];
+    for (const field of fields) {
+        let equalitySet = false;
+        for (const operator of field.operators) {
+            const key = queryParamKey(field.name, operator);
+            if (!(key in query)) {
+                continue;
+            }
+            const condition = buildFieldCondition(field, operator, query[key]);
+            if (!condition) {
+                continue;
+            }
+            if (operator === 'equals') {
+                equalitySet = true;
+            }
+            else if (equalitySet) {
+                continue;
+            }
+            whereParts.push(condition);
+        }
+    }
+    let where = {};
+    if (whereParts.length === 1) {
+        where = whereParts[0];
+    }
+    else if (whereParts.length > 1) {
+        where = { AND: whereParts };
+    }
+    const result = { where };
+    if (query.limit !== undefined && query.limit !== '') {
+        result.take = Number(query.limit);
+    }
+    if (query.offset !== undefined && query.offset !== '') {
+        result.skip = Number(query.offset);
+    }
+    if (typeof query.sort === 'string' && query.sort.length > 0) {
+        const descending = query.sort.startsWith('-');
+        const fieldName = descending ? query.sort.slice(1) : query.sort;
+        if (!sortableFields.includes(fieldName)) {
+            throw new Error(`Invalid sort field "${fieldName}"`);
+        }
+        result.orderBy = { [fieldName]: descending ? 'desc' : 'asc' };
+    }
+    return result;
+}

package/dist/api/utils/omit-fields.d.ts

@@ -0,0 +1,2 @@
+export declare function omitFields<T extends Record<string, unknown>>(row: T, omitted: readonly string[]): Omit<T, (typeof omitted)[number]>;
+export declare function omitFieldsMany<T extends Record<string, unknown>>(rows: T[], omitted: readonly string[]): Array<Omit<T, (typeof omitted)[number]>>;

package/dist/api/utils/omit-fields.js

@@ -0,0 +1,16 @@
+export function omitFields(row, omitted) {
+    if (omitted.length === 0) {
+        return row;
+    }
+    const result = { ...row };
+    for (const field of omitted) {
+        delete result[field];
+    }
+    return result;
+}
+export function omitFieldsMany(rows, omitted) {
+    if (omitted.length === 0) {
+        return rows;
+    }
+    return rows.map((row) => omitFields(row, omitted));
+}

package/dist/api-generator/route-generator.d.ts

@@ -4,6 +4,8 @@ export declare class RouteGenerator {
     private readonly schema;
     constructor(model: Model, schema: Schema);
     generate(): string;
+    private jsonRow;
+    private jsonRows;
     private generateListRoute;
     private generateGetRoute;
     private generateCreateRoute;