neoorm 0.8.0 → 0.8.2

package/docs/queries.md

@@ -30,7 +30,7 @@ await db.users.findFirst({
 const user = await db.users.findUnique({ where: { slug: "hello" } });
 ```
 
-Unique `where` (`findUnique`, `upsert`, `findOrCreate`, singular `update`/`delete`) is scalar equality per unique field — `{ email: "a@b.com" }`, not a filter. `{ equals: value }` is accepted and unwrapped to the scalar. Other operators (`contains`, `in`, `mode: "insensitive"`) throw `unique_where_invalid`.
+Unique `where` (`findUnique`, `upsert`, `findOrCreate`, singular `update`/`delete`) is scalar equality per unique field — `{ email: "a@b.com" }`, not a filter. `{ equals: value }` is accepted and unwrapped to the scalar. Other operators (`contains`, `in`, `mode: "insensitive"`) throw `unique_where_invalid`. Partial unique indexes are valid targets: pass the indexed columns; the index `WHERE` is applied automatically so the lookup stays unique.
 
 ## Create
 
@@ -73,7 +73,7 @@ Unknown keys in `data` fail at compile time (`unknown_column`), same as `where`.
 
 ## Update
 
-Singular `update` requires a unique `where` (primary key, `@unique` column, or composite unique index), same as `findUnique`. Use `updateMany` when the filter can match multiple rows.
+Singular `update` requires a unique `where` (primary key, `@unique` column, composite unique index, or partial unique index), same as `findUnique`. Use `updateMany` when the filter can match multiple rows.
 
 ```ts
 // Returns {} on success, null if no row matched
@@ -181,7 +181,7 @@ Atomically insert a row or return an existing one when a unique constraint match
 
 Postgres issues `INSERT … ON CONFLICT DO UPDATE` with a no-op assignment so `RETURNING` always includes the row — including when a concurrent session already inserted it. `created` is `(xmax = 0)` (inserted vs existing). A no-op update can fire `UPDATE` triggers; column values are not changed.
 
-Under `SERIALIZABLE` (and sometimes `REPEATABLE READ`), a concurrent insert can still abort the transaction with a serialization failure. Retry the whole `$transaction`. SQLite uses find-then-insert and retries the find after a unique violation.
+Under `SERIALIZABLE` (and sometimes `REPEATABLE READ`), a concurrent insert can still abort the transaction with a serialization failure. Retry the whole `$transaction`. SQLite, MySQL, and MariaDB use find-then-insert and retry the find after a unique violation.
 
 ```ts
 const { record, created } = await db.tags.findOrCreate({
@@ -219,11 +219,11 @@ Unknown column names and operators fail at compile time (`unknown_column`, with
 | PostGIS (`geometry`, `geography`, `point`) | `intersects`, `within`, `dWithin` |
 | All nullable | `isNull`, `isNotNull` |
 
-`contains`, `startsWith`, `endsWith`, and `equals` compile to `LIKE` / `=`. Pass sibling `mode: "insensitive"` for case-folding (`ILIKE` on Postgres, `LOWER(col) LIKE LOWER($n)` on SQLite). SQLite `LIKE` is ASCII case-insensitive even in default mode.
+`contains`, `startsWith`, `endsWith`, and `equals` compile to `LIKE` / `=`. Pass sibling `mode: "insensitive"` for case-folding (`ILIKE` on Postgres, `LOWER(col) LIKE LOWER($n)` on SQLite/MySQL/MariaDB). SQLite `LIKE` is ASCII case-insensitive even in default mode. `%` and `_` in the search string are matched literally (`ESCAPE '\'` on Postgres/SQLite, `ESCAPE '\\'` on MySQL/MariaDB).
 
-`search` is POSIX regex (`~`, or `~*` with `mode: "insensitive"`). It is PostgreSQL-only; SQLite throws.
+`search` is POSIX regex on PostgreSQL (`~`, or `~*` with `mode: "insensitive"`), `REGEXP_LIKE` on MySQL 8, `REGEXP` on MariaDB, and JavaScript `RegExp` (`REGEXP` / `regexp_i`) on SQLite.
 
-JSON operators on PostgreSQL use `@>`, `?`, and `#>` / `#>>`. On SQLite they compile to `json_patch` (object containment), `json_each` (key existence), and `json_extract` (path).
+JSON operators on PostgreSQL use `@>`, `?`, and `#>` / `#>>`. On SQLite they compile to `json_patch` (object containment), `json_each` (key existence), and `json_extract` (path). On MySQL and MariaDB they compile to `JSON_CONTAINS`, `JSON_CONTAINS_PATH`, and `JSON_EXTRACT`.
 
 ```ts
 await db.posts.findMany({
@@ -321,7 +321,7 @@ await db.users.findMany({
 });
 ```
 
-Not supported on SQLite (`DISTINCT ON` is PostgreSQL-only) — it throws `distinct is not supported on SQLite`. Use `groupBy({ by: [...] })` or a raw `db.sql` query instead.
+Not supported on MySQL or MariaDB (`DISTINCT ON` is PostgreSQL-only; SQLite emulates it with `ROW_NUMBER()`). Use `groupBy({ by: [...] })` or a raw `db.sql` query instead.
 
 ## Eager loading with `with`
 
@@ -524,7 +524,7 @@ const byAuthor = await db.posts.groupBy({
 
 Star `_count: true` still works with `having: { _count: { gte: 5 } }` and `orderBy: { _count: "desc" }`.
 
-`where` filters rows before grouping. `having` filters groups (aggregates only). `by` alone lists distinct groups — useful on SQLite where `distinct` is not available.
+`where` filters rows before grouping. `having` filters groups (aggregates only). `by` alone lists distinct groups — useful when you need grouped aggregates rather than `findMany({ distinct })`.
 
 ## Count
 
@@ -545,7 +545,7 @@ const taken = await db.users.exists({ where: { email: "a@b.com" } });
 
 ## Raw SQL
 
-`db.sql` and `import { sql } from "neoorm/sql"` share one compiler. Interpolate values, `sqlId("table")`, nested `sql\`...\`` fragments, or `sqlBuilder.compile()`. `sqlBuilder` itself has no WHERE, LIMIT, or params — add those in the `db.sql` tag.
+`db.sql` and `import { sql } from "neoorm/sql"` share one compiler. Interpolate values, `sqlId("table")`, nested `sql\`...\`` fragments, or `sqlBuilder.compile()`. `sqlBuilder` covers select/join/where/group/order/limit with bound params; use `db.sql` for HAVING and other raw tails.
 
 ```ts
 import { sql, sqlBuilder, sqlId } from "neoorm/sql";
@@ -557,12 +557,15 @@ const rows = await db.sql`SELECT * FROM ${ident} WHERE ${filter}`;
 const grouped = sqlBuilder
   .selectFrom("users")
   .select(["id", "email"])
+  .where("email", "=", "a@b.com")
+  .orWhere(sql`role = ${"admin"}`)
   .groupBy("id", "email")
+  .limit(10)
   .compile();
-await db.sql`${grouped} LIMIT ${10}`;
+await db.sql`${grouped} HAVING count(*) > ${0}`;
 ```
 
-`db.execute({ text, params })` runs already-compiled SQL. Raw SQL is not rewritten for tenant `schema` — qualify identifiers yourself.
+`db.execute({ text, params })` runs already-compiled SQL. With PostgreSQL tenant `schema`, `db.sql` / `db.execute` qualify unqualified manifest table names (same as `db.sqlId("users")`). Already-qualified `schema.table` identifiers are unchanged.
 
 ## Logging SQL
 

package/docs/relations.md

@@ -6,13 +6,13 @@
 
 | Relation kind | Operations |
 |---------------|------------|
-| **To-one** (outgoing FK) | `connect`, `create`, `disconnect` (nullable FK only) |
+| **To-one** (outgoing FK) | `connect`, `connectOrCreate`, `create`, `disconnect` (nullable FK only) |
 | **One-to-many** (inverse) | `create`, `connect`, `disconnect`, `set`, `delete` |
 | **Many-to-many** | `connect`, `connectOrCreate`, `disconnect`, `set`, `delete` |
 
-`connect`, `set`, `disconnect`, and `delete` identify related rows by the **target table's scalar primary key** (`{ id: ... }` when the PK is `id`, `{ userId: ... }` when it is `userId`). Composite-PK connect is not supported.
+`connect`, `set`, `disconnect`, and `delete` identify related rows by the **target table's primary key**: `{ id: ... }` or `{ userId: ... }` for a scalar PK, or an object with **every** PK column for a composite key. A single-column `fk()` still stores one referenced value; a composite `foreignKey()` extra assigns **each** local column from the matching target field (never a concatenated PK string).
 
-A relation field must be a **pure write bag**: every key is one of those operations. Mixing a write op with extra fields (`{ create: { name: "A" }, foo: 1 }`), passing a scalar, or passing `{}` throws `invalid_nested_write` — the parent row is not written.
+A relation field must be a **pure write bag**: every key is one of those operations. Mixing a write op with extra fields (`{ create: { name: "A" }, foo: 1 }`), passing a scalar, or passing `{}` throws `invalid_nested_write` — the parent row is not written. To-one `connectOrCreate` cannot be mixed with `connect` or `create`.
 
 ## Examples
 
@@ -21,7 +21,22 @@ A relation field must be a **pure write bag**: every key is one of those operati
 ```ts
 await db.posts.update({
   where: { id: postId },
-  data: { author: { connect: { id: userId } } },
+  data: {
+    author: { connect: { id: userId } },
+    // or create the author if missing:
+    // author: { connectOrCreate: { where: { email }, create: { email, password } } },
+  },
+});
+```
+
+Composite primary key:
+
+```ts
+await db.orders.update({
+  where: { id: orderId },
+  data: {
+    lines: { connect: [{ tenantId: "acme", lineNo: 1 }] },
+  },
 });
 ```
 

package/docs/schema.md

@@ -1,6 +1,6 @@
 # Schema DSL
 
-NeoOrm **0.8.0** uses accessor-based identity: schema keys, `fk("users")`, `many("tags")`, and `through: "postTags"` all refer to **accessors**, not raw SQL names. `schemaToManifest` resolves accessors to SQL before migrations and the typed client are generated.
+NeoOrm **0.8.0** and later uses accessor-based identity: schema keys, `fk("users")`, `many("tags")`, and `through: "postTags"` all refer to **accessors**, not raw SQL names. `schemaToManifest` resolves accessors to SQL before migrations and the typed client are generated.
 
 ## Tables and accessors
 
@@ -48,10 +48,21 @@ Column field names use camelCase in TypeScript. By default SQL column names are
 | `decimal()` / `numeric()` | `NUMERIC` | `string \| null` | Use strings to avoid float loss |
 | `enumType(["a", "b"])` | mode-dependent | union literals | See [Enum columns](#enum-columns) |
 | `bytea()` | `BYTEA` | `Buffer \| null` | |
-| `textArray()` / `intArray()` | arrays | arrays \| null | |
+| `textArray()` / `intArray()` | arrays | arrays \| null | JSON on SQLite/MySQL |
+| `uuidArray()` | `UUID[]` | `string[] \| null` | JSON on SQLite/MySQL |
+| `enumArray(["a", "b"])` | `TEXT[]` or `name[]` | union arrays \| null | Same enum storage mode as `enumType`; JSON on SQLite/MySQL |
+| `real()` / `float()` | `REAL` | `number \| null` | 32-bit. Prisma `Float` is `double()`. MySQL `FLOAT`, SQLite `REAL` |
+| `double()` | `DOUBLE PRECISION` | `number \| null` | MySQL `DOUBLE`, SQLite `REAL` |
+| `date()` | `DATE` | `string \| null` | `YYYY-MM-DD`, not `Date`. SQLite `TEXT`, MySQL `DATE` |
+| `time()` | `TIME` | `string \| null` | SQLite `TEXT`, MySQL `TIME` |
+| `interval()` | `INTERVAL` | `string \| null` | SQLite `TEXT`; rejected on MySQL/MariaDB |
+| `inet()` / `cidr()` | `INET` / `CIDR` | `string \| null` | SQLite `TEXT`; rejected on MySQL/MariaDB |
+| `xml()` | `XML` | `string \| null` | MySQL `LONGTEXT`, SQLite `TEXT` |
+| `money()` | `MONEY` | `string \| null` | MySQL `DECIMAL(19,4)`, SQLite `TEXT` |
+| `int4Range()` / `int8Range()` / `numRange()` / `tsRange()` / `tstzRange()` / `dateRange()` | matching PG ranges | `string \| null` | PostgreSQL only (rejected on SQLite and MySQL/MariaDB) |
 | `citext()` | `CITEXT` | `string \| null` | Requires `citext` extension |
 
-All column builders support `.notNull()`, `.unique()`, `.default(value)`, `.primary()`, `.map(name)`, `.hidden()`, `.index()`, and `.check("sql expression")`.
+All column builders support `.notNull()`, `.unique()`, `.default(value)`, `.primary()`, `.map(name)`, `.hidden()`, `.index()`, and `.check("sql expression")`. Text columns add `.maxLength()`, `.minLength()`, `.notEmpty()`, `.email()`, and `.url()`. Numeric columns (`int`, `bigint`, `serial`, `decimal`, `real`, `double`) add `.min()`, `.max()`, and `.positive()`.
 
 `.hidden()` marks a column as sensitive. It is omitted from default query output on the root table and on nested `with` includes. Pass `includeHidden: true` when the app needs the value (for example password verification on login). Use `.strip()` to remove any remaining sensitive fields before JSON responses.
 
@@ -100,7 +111,9 @@ Fluent modifiers (no options bag):
 |--------|--------|
 | `.as("author")` | override relation name on this table (default: strip `Id` from column name) |
 | `.inverse("articles")` | override relation name on the target table (rare — see defaults below) |
-| `.onDelete("cascade" \| "restrict" \| "set null" \| "no action")` | FK action |
+| `.onDelete("cascade" \| "restrict" \| "set null" \| "no action")` | FK `ON DELETE` |
+| `.onUpdate("cascade" \| "restrict" \| "set null" \| "no action")` | FK `ON UPDATE` |
+| `.deferrable("immediate" \| "deferred")` | `DEFERRABLE` (Postgres and SQLite; rejected on MySQL/MariaDB) |
 | `.notNull()` | `NOT NULL` |
 | `.unique()` | `UNIQUE` — unique FKs infer a **singular** inverse (`profiles.userId` → `users.profile`) |
 | `.primary()` | part of composite PK |
@@ -123,6 +136,39 @@ postTags: table("post_tags", {
 
 Multiple `.primary()` columns infer a composite key. `primaryKey(t.colA, t.colB)` in extras is optional when you want to name the key without marking every column.
 
+### Composite foreign keys
+
+Use table extras `foreignKey()` when several local columns form one constraint (and one relation). Do not also mark those columns `fk()`.
+
+```ts
+orders: table(
+  {
+    id: id(),
+    tenantId: text().notNull(),
+    userId: text().notNull(),
+  },
+  (t) => [
+    foreignKey(t.tenantId, t.userId)
+      .references("users", "tenantId", "id")
+      .as("user")
+      .inverse("orders")
+      .onDelete("cascade")
+      .onUpdate("cascade"),
+  ],
+),
+```
+
+The target column list must match a primary key or unique index. `.as()` and `.inverse()` are required. Connect still uses the target table's full primary key:
+
+```ts
+await db.orders.create({
+  data: {
+    tenantId: "acme",
+    user: { connect: { tenantId: "acme", id: userId } },
+  },
+});
+```
+
 ### Self-relations
 
 ```ts
@@ -148,7 +194,35 @@ export const schema = defineSchema({
 
 ## Column checks
 
-`.check("price >= 0")` stores a SQL expression on the column (combined with enum `check` mode when both apply):
+Use `.check("sql expression")` for custom CHECK constraints, or the typed helpers below. Helpers compile to database CHECK constraints (and `VARCHAR(n)` for text length on Postgres). They are not runtime validators by themselves. With [`generate.zod`](zod.md), [`generate.typebox`](typebox.md), or [`generate.elysia`](elysia.md), the same helpers are copied into generated validation schemas at your API boundary.
+
+### Typed constraint helpers
+
+| Method | Column types | Postgres | SQLite |
+|--------|--------------|----------|--------|
+| `.maxLength(n)` / `text({ maxLength: n })` | `text` | `VARCHAR(n)` | `TEXT` + `CHECK (length(col) <= n)` |
+| `.minLength(n)` | `text`, `citext` | CHECK | CHECK |
+| `.notEmpty()` | `text`, `citext` | CHECK | CHECK |
+| `.email()` | `text`, `citext` | — | — |
+| `.url()` | `text`, `citext` | — | — |
+| `.min(n)` / `.max(n)` | `int`, `bigint`, `serial`, `decimal` | CHECK | CHECK |
+| `.positive()` | same numeric types | CHECK | CHECK |
+
+```ts
+email: text({ maxLength: 255 }).notNull().unique()
+title: text().notNull().minLength(1).maxLength(200)
+bio: text().notEmpty()
+handle: text().notNull().email()
+website: text().notNull().url()
+views: int().notNull().min(0)
+price: decimal({ precision: 10, scale: 2 }).notNull().positive()
+```
+
+`.email()` and `.url()` are validation-only: they do not emit a SQL CHECK. With [`generate.zod`](zod.md), [`generate.typebox`](typebox.md), or [`generate.elysia`](elysia.md), columns named `email` or ending in `Email` (`contactEmail`) become email-format strings, and columns named `url` or ending in `Url` (`avatarUrl`) become URL-format strings. You can also mark any `text` / `citext` column with `.email()` or `.url()`. Foreign keys follow the **referenced** column (`authorEmail` pointing at a uuid PK stays a uuid).
+
+`citext` length helpers use CHECK only (no `VARCHAR`). NULL still bypasses CHECK — pair `.notEmpty()` with `.notNull()` to reject empty strings.
+
+Custom `.check()` expressions are combined with helpers and enum `check` mode using AND. Prefer helpers over raw SQL so constraints use the mapped SQL column name after `.map()`.
 
 ```ts
 price: decimal({ precision: 10, scale: 2 }).notNull().check("price >= 0"),
@@ -172,7 +246,24 @@ posts: table(
 ),
 ```
 
-Helpers: `unique(...cols)`, `index(...cols)`, `primaryKey(...cols)`. `unique()` and `index()` both support `.where()` for partial indexes.
+Helpers: `unique(...cols)`, `index(...cols)`, `primaryKey(...cols)`, `expr("sql")`. `unique()` and `index()` support `.using()`, `.ops()`, and `.where()` for partial indexes.
+
+### Index methods and expressions
+
+```ts
+(t) => [
+  index(t.tags).using("gin"),
+  index(t.metadata).using("gin").ops("jsonb_path_ops"),
+  index(t.location).using("gist"),
+  index(t.createdAt).using("brin"),
+  unique(expr("lower(email)")),
+  index(t.authorId, expr("date_trunc('day', created_at)")),
+],
+```
+
+Default method is btree (`USING btree` is omitted in SQL). Postgres also emits `gin`, `gist`, `brin`, and `hash`. SQLite allows expression keys and partial `WHERE`, but not those access methods. MySQL/MariaDB allow `USING HASH` and functional `(expr)` keys; they reject GIN/GiST/BRIN and partial `WHERE`.
+
+`unique()` cannot use `gin` / `gist` / `brin`. Expression unique indexes are not `findUnique` / `upsert` targets.
 
 ### Partial indexes
 
@@ -183,7 +274,7 @@ Helpers: `unique(...cols)`, `index(...cols)`, `primaryKey(...cols)`. `unique()`
 ],
 ```
 
-Equality map of column refs → values; compiled to `WHERE "published" = true` (or `= 1` on SQLite). Partial uniques emit as `CREATE UNIQUE INDEX ... WHERE ...`, not table-level `UNIQUE (...)`. They are not usable as `findUnique` / `upsert` targets.
+Equality map of column refs → values; compiled to `WHERE "published" = true` (or `= 1` on SQLite). Partial uniques emit as `CREATE UNIQUE INDEX ... WHERE ...`, not table-level `UNIQUE (...)`. They are valid `findUnique` / `upsert` / `findOrCreate` targets: `where` uses the indexed columns, and the index predicate is applied automatically (`AND` on lookups, `ON CONFLICT (…) WHERE …` on Postgres and SQLite).
 
 ## Many-to-many
 
@@ -254,7 +345,7 @@ status: enumType(["draft", "published", "archived"])
   .default("draft"),
 ```
 
-`datasource.enum` in config: `check` (default), `union`, or `native` (PostgreSQL only).
+`datasource.enum` in config: `check` (default), `union`, or `native` (PostgreSQL `CREATE TYPE` / MySQL and MariaDB column `ENUM`).
 
 ## PostgreSQL extensions
 
@@ -269,4 +360,4 @@ Column type plugins still register required extensions automatically.
 
 ## SQLite type mapping
 
-Same DSL; see [SQLite](sqlite.md) for storage types and limitations.
+Same DSL; see [SQLite](sqlite.md), [MySQL](mysql.md), and [MariaDB](mariadb.md) for storage types and limitations.

package/docs/sqlite.md

@@ -75,6 +75,14 @@ const db = createNeoOrmClientFromSqlite(manifest, database);
 
 `$disconnect()` does not close the handle — call `database.close()` yourself. `createNeoOrmClient(manifest, { db: database })` is the same ownership model.
 
+`sqliteDialect` is exported from `neoorm` (alongside `postgresDialect`) for `dbPush`, migrate helpers, and custom executor wiring:
+
+```ts
+import { dbPush, sqliteDialect } from "neoorm";
+
+await dbPush(client, sqliteDialect, manifest);
+```
+
 ## CLI
 
 The full CLI works against SQLite:
@@ -95,9 +103,11 @@ bunx neoorm migrate reset --force
 
 | Schema builder | SQLite storage |
 |----------------|----------------|
-| `id`, `text`, `uuid`, `json`, `jsonb`, `decimal`, `textArray`, `intArray`, `citext`, `enumType` | `TEXT` |
+| `id`, `text`, `uuid`, `json`, `jsonb`, `decimal`, `textArray`, `intArray`, `uuidArray`, `enumArray`, `citext`, `enumType`, `date`, `time`, `interval`, `inet`, `cidr`, `xml`, `money` | `TEXT` |
 | `int`, `serial` | `INTEGER` |
+| `real`, `double` | `REAL` |
 | `bigint` | `TEXT` |
+| `int4Range` … `dateRange` | rejected at schema compile |
 | `serial().primary()` | `INTEGER PRIMARY KEY AUTOINCREMENT` |
 | `bool` | `BOOLEAN` (stored as 0/1) |
 | `timestamp` | `TEXT` (ISO-8601) |
@@ -110,9 +120,11 @@ bunx neoorm migrate reset --force
 
 | Feature | PostgreSQL | SQLite |
 |---------|-----------|--------|
-| `distinct` (`DISTINCT ON`) | supported | throws `distinct is not supported on SQLite` |
+| `distinct` (`DISTINCT ON`) | supported | `ROW_NUMBER()` per distinct columns (same `orderBy` prefix rule) |
+| `search` | POSIX `~` / `~*` | JavaScript `RegExp` via `REGEXP` / `regexp_i` |
 | `datasource.schema` | multi-schema | not applicable |
 | `enum: "native"` | `CREATE TYPE ... AS ENUM` | not applicable (TEXT + CHECK) |
+| range types | supported | rejected at schema compile |
 | transaction options (`readOnly`, `isolationLevel`) | `BEGIN READ ONLY` / `ISOLATION LEVEL` | `readOnly` → `PRAGMA query_only`; `RepeatableRead`/`Serializable` → `BEGIN IMMEDIATE`; other isolation → `BEGIN` |
 | JSON operators | `@>`, `?`, `#>` | `json_patch` / `json_each` / `json_extract` |
 

package/docs/typebox.md

@@ -0,0 +1,139 @@
+# TypeBox schemas
+
+`neoorm generate` can print Select, Create, and Update **scalar** TypeBox schemas next to the typed client. Codegen maps your schema to a validator-neutral IR first; TypeBox 1.x is one printer (alongside [Zod](zod.md) and [Elysia `t`](elysia.md)).
+
+Generated schemas match the TypeScript shapes of row / insert / update scalars — not nested relation writes (`connect`, `create`, `set`). Those stay TypeScript-only.
+
+Schemas target **TypeBox 1.x** (`typebox` on npm), not `@sinclair/typebox` 0.x. For Elysia 1.x route `body:`, use [`generate.elysia`](elysia.md) instead.
+
+## Enable
+
+Install TypeBox 1.x in the app, then opt in:
+
+```bash
+bun add typebox
+```
+
+```ts
+// neoorm.config.ts
+import { defineConfig } from "neoorm";
+
+export default defineConfig({
+  schema: "./schema.ts",
+  out: "./neoorm",
+  datasource: {
+    provider: "postgresql",
+    url: process.env.DATABASE_URL!,
+  },
+  generate: {
+    typebox: true,
+  },
+});
+```
+
+Re-run `neoorm generate` (or `neoorm migrate dev`). Output:
+
+- `out/typebox.ts` — generated schemas
+- `out/client.ts` re-exports them
+
+Disable `generate.typebox` and generate again to remove `typebox.ts`.
+
+`typebox` is an optional peer of NeoOrm. The generated file imports `typebox` directly; NeoOrm does not bundle it. If `generate.typebox` is on and `typebox` is not installed, `neoorm generate` still writes `typebox.ts` and prints a warning (`bun add typebox`).
+
+You can enable Zod, TypeBox, and Elysia together. When Zod is on, `client.ts` keeps Zod as a flat `export *` and namespaces TypeBox and Elysia (`export * as typebox` / `export * as elysia`). TypeBox + Elysia without Zod keeps TypeBox flat and namespaces Elysia. Import TypeBox from `./typebox.js` (or `typebox.UserCreateSchema` from the client) when it is namespaced. For Elysia 1.x `body:`, use [`generate.elysia`](elysia.md).
+
+## Usage
+
+```ts
+import Value from "typebox/value";
+import { db, UserCreateSchema, type UserCreate } from "./neoorm/client.js";
+
+const data: UserCreate = Value.Decode(UserCreateSchema, body);
+await db.users.create({ data });
+```
+
+`Value.Check` returns a boolean and does not run codecs. Use `Value.Decode` when you need timestamp fields as `Date` (the TypeBox equivalent of Zod `parse`). Invalid data throws.
+
+Per table (accessor `users` → model `User`):
+
+| Export | Shape |
+|--------|--------|
+| `UserSchema` / `UserSelect` | Select row (default query output: no `.hidden()`, includes `timestamps()`) |
+| `UserCreateSchema` / `UserCreate` | Insert scalars (no primary / serial / `timestamps()`; defaults optional; includes `.hidden()`) |
+| `UserUpdateSchema` / `UserUpdate` | Update scalars (no primary / `timestamps()`; all optional; includes `.hidden()`) |
+
+`UserSelect` / `UserCreate` / `UserUpdate` are `Type.StaticDecode` aliases. They are named that way so they do not collide with the model type `User` from `models.ts`. Hoisted enums also get a type (`PostStatus` from `PostStatusSchema`).
+
+`schemas.users.select` / `.create` / `.update` are the same objects.
+
+`.hidden()` columns (for example `password`) are omitted from select schemas so they match default query results. They stay on create and update so login/register and password-change payloads can still be parsed. Use `includeHidden: true` on the query when the app needs those fields internally.
+
+`createdAt` and `updatedAt` from `timestamps()` (and any `timestamp().defaultNow()` / `.updatedAt()` column) are ORM-managed. They appear on select schemas only — create and update parsers reject them so API clients cannot stamp those fields. A plain `timestamp()` without `defaultNow` stays on create/update.
+
+Create with `author: { connect: { id } }` is not in `PostCreateSchema`. Pass the FK scalar (`authorId`) or keep nested writes in TypeScript.
+
+## Junction (M2M) tables
+
+Many-to-many through tables (auto `posts_tags` from `tags: many("tags")`, or an explicit `through` table) are not ordinary entities. Both FK columns are usually the composite primary key, so a naive Create/Update export would be `Type.Object({})`.
+
+Codegen treats them as **link** tables:
+
+| Export | Shape |
+|--------|--------|
+| `{Model}Schema` / `{Model}Select` | Junction row (both FK ids, plus extras like `priority`) |
+| `{Model}LinkCreateSchema` / `{Model}LinkCreate` | Both FK ids required; extra create-allowed columns |
+| `{Model}CreateSchema` / `{Model}Create` | Alias of `LinkCreateSchema` |
+| `{Model}UpdateSchema` | Extra scalar columns only. **Omitted** when the junction has no updatable fields |
+
+Generated comments point at nested writes on the parent (`db.posts.update({ data: { tags: { connect: [{ id }] } } })`). Direct `db.posts_tags.create` is rarely needed. `schemas.posts_tags` has `select` and `create`; `update` is present only when the through table has extra columns.
+
+Prefer validating parent payloads in TypeScript (`tags: { connect, set, … }`). Junction TypeBox is for the rare case you insert a link row yourself.
+
+## Types and constraints
+
+Timestamp columns accept both ORM `Date` values and JSON ISO-8601 strings (`2020-01-01T00:00:00.000Z`, including offsets). `Value.Decode` always returns a `Date`, so the same schema works for HTTP bodies and query results. `Value.Check` accepts either form without converting.
+
+`Type.BigInt()` and `Buffer` still match generated models, not JSON. Wrap those fields if the payload is a JSON number/string.
+
+The generated file registers `uuid`, `email`, `url`, and `date-time` on TypeBox’s `Format` registry when those formats appear, without overwriting a format you already set.
+
+Typed schema helpers map into TypeBox:
+
+| Schema | TypeBox |
+|--------|---------|
+| `.minLength()` / `.maxLength()` / `.notEmpty()` | `Type.String({ minLength, maxLength })` |
+| `email` / `*Email` column names, or `.email()` on `text` / `citext` | `Type.String({ format: "email" })` |
+| `url` / `*Url` column names, or `.url()` on `text` / `citext` | `Type.String({ format: "url" })` |
+| `.min()` / `.max()` / `.positive()` on int/serial | `Type.Integer({ minimum, maximum, exclusiveMinimum: 0 })` |
+| same helpers on `bigint` | `Type.BigInt({ minimum, maximum, exclusiveMinimum: 0n })` |
+| same helpers on `decimal()` | `Type.Refine(Type.String(), …)` |
+| `enumType([...])` | hoisted `Type.Enum` |
+| `json()` / `jsonb()` with no type arg | `Type.Record(Type.String(), Type.Unknown())` |
+| `jsonb<Record<string, unknown>>()` | `Type.Record(Type.String(), Type.Unknown())` |
+| `jsonb<{ featured: boolean }>()` (inline object type) | `Type.Object({ featured: Type.Boolean(), … })` |
+| `json()` / `jsonb()` with `.schema()` validation IR | same as IR (`Type.Object`, nested `Type.Record`, …); wins over generics |
+| `timestamp()` | `Date` or ISO datetime string → `Date` (`Type.Codec` + `Value.Decode`) |
+| `bytea()` | `Type.Refine` + `Buffer.isBuffer` |
+
+Raw `.check("sql")` is not mapped. With `generate.typebox: true` (or `generate.zod` / `generate.elysia`), codegen reads inline `json()` / `jsonb()` type arguments from `schema.ts` and maps object literals to `Type.Object`, `Record<K,V>` to `Type.Record`, and primitives to the matching TypeBox types. Type aliases and imported types are not resolved yet — use an inline type or `.schema()` for those.
+
+```ts
+metadata: jsonb<{ featured: boolean; category?: string }>(),
+// → metadata: Type.Union([Type.Object({ featured: Type.Boolean(), category: Type.Optional(Type.String()) }), Type.Null()])
+```
+
+For shapes codegen cannot infer from the generic, use `.schema()`:
+
+```ts
+metadata: jsonb().schema({
+  kind: "object",
+  fields: [
+    {
+      name: "featured",
+      type: { kind: "boolean" },
+      nullable: false,
+      optional: false,
+    },
+  ],
+}),
+```

package/docs/zod.md

@@ -0,0 +1,128 @@
+# Zod schemas
+
+`neoorm generate` can print Select, Create, and Update **scalar** Zod schemas next to the typed client. Codegen maps your schema to a validator-neutral IR first; Zod, [TypeBox](typebox.md), and [Elysia `t`](elysia.md) are the printers shipped today.
+
+Generated schemas match the TypeScript shapes of row / insert / update scalars — not nested relation writes (`connect`, `create`, `set`). Those stay TypeScript-only.
+
+## Enable
+
+Install Zod 4 in the app, then opt in:
+
+```bash
+bun add zod
+```
+
+```ts
+// neoorm.config.ts
+import { defineConfig } from "neoorm";
+
+export default defineConfig({
+  schema: "./schema.ts",
+  out: "./neoorm",
+  datasource: {
+    provider: "postgresql",
+    url: process.env.DATABASE_URL!,
+  },
+  generate: {
+    zod: true,
+  },
+});
+```
+
+Re-run `neoorm generate` (or `neoorm migrate dev`). Output:
+
+- `out/zod.ts` — generated schemas
+- `out/client.ts` re-exports them
+
+Disable `generate.zod` and generate again to remove `zod.ts`.
+
+`zod` is an optional peer of NeoOrm. The generated file imports `zod` directly; NeoOrm does not bundle it. If `generate.zod` is on and `zod` is not installed, `neoorm generate` still writes `zod.ts` and prints a warning (`bun add zod`).
+
+## Usage
+
+```ts
+import { db, UserCreateSchema, type UserCreate } from "./neoorm/client.js";
+
+const data: UserCreate = UserCreateSchema.parse(body);
+await db.users.create({ data });
+```
+
+Per table (accessor `users` → model `User`):
+
+| Export | Shape |
+|--------|--------|
+| `UserSchema` / `UserSelect` | Select row (default query output: no `.hidden()`, includes `timestamps()`) |
+| `UserCreateSchema` / `UserCreate` | Insert scalars (no primary / serial / `timestamps()`; defaults optional; includes `.hidden()`) |
+| `UserUpdateSchema` / `UserUpdate` | Update scalars (no primary / `timestamps()`; all optional; includes `.hidden()`) |
+
+`UserSelect` / `UserCreate` / `UserUpdate` are `z.infer` aliases. They are named that way so they do not collide with the model type `User` from `models.ts`. Hoisted enums also get a type (`PostStatus` from `PostStatusSchema`).
+
+`schemas.users.select` / `.create` / `.update` are the same objects.
+
+`.hidden()` columns (for example `password`) are omitted from select schemas so they match default query results. They stay on create and update so login/register and password-change payloads can still be parsed. Use `includeHidden: true` on the query when the app needs those fields internally.
+
+`createdAt` and `updatedAt` from `timestamps()` (and any `timestamp().defaultNow()` / `.updatedAt()` column) are ORM-managed. They appear on select schemas only — create and update parsers reject them so API clients cannot stamp those fields. A plain `timestamp()` without `defaultNow` stays on create/update.
+
+Create with `author: { connect: { id } }` is not in `PostCreateSchema`. Pass the FK scalar (`authorId`) or keep nested writes in TypeScript.
+
+## Junction (M2M) tables
+
+Many-to-many through tables (auto `posts_tags` from `tags: many("tags")`, or an explicit `through` table) are not ordinary entities. Both FK columns are usually the composite primary key, so a naive Create/Update export would be `z.object({})`.
+
+Codegen treats them as **link** tables:
+
+| Export | Shape |
+|--------|--------|
+| `{Model}Schema` / `{Model}Select` | Junction row (both FK ids, plus extras like `priority`) |
+| `{Model}LinkCreateSchema` / `{Model}LinkCreate` | Both FK ids required; extra create-allowed columns |
+| `{Model}CreateSchema` / `{Model}Create` | Alias of `LinkCreateSchema` |
+| `{Model}UpdateSchema` | Extra scalar columns only. **Omitted** when the junction has no updatable fields |
+
+Generated comments point at nested writes on the parent (`db.posts.update({ data: { tags: { connect: [{ id }] } } })`). Direct `db.posts_tags.create` is rarely needed. `schemas.posts_tags` has `select` and `create`; `update` is present only when the through table has extra columns.
+
+Prefer validating parent payloads in TypeScript (`tags: { connect, set, … }`). Junction Zod is for the rare case you insert a link row yourself.
+
+## Types and constraints
+
+Timestamp columns accept both ORM `Date` values and JSON ISO-8601 strings (`2020-01-01T00:00:00.000Z`, including offsets). `parse` always returns a `Date`, so the same schema works for HTTP bodies and query results.
+
+`z.bigint()` and `Buffer` still match generated models, not JSON. Wrap those fields if the payload is a JSON number/string.
+
+Typed schema helpers map into Zod:
+
+| Schema | Zod |
+|--------|-----|
+| `.minLength()` / `.maxLength()` / `.notEmpty()` | `z.string().min()` / `.max()` |
+| `email` / `*Email` column names, or `.email()` on `text` / `citext` | `z.email()` |
+| `url` / `*Url` column names, or `.url()` on `text` / `citext` | `z.url()` |
+| `.min()` / `.max()` / `.positive()` on int/serial/bigint | matching number/bigint checks |
+| same helpers on `decimal()` | `z.string().refine(...)` |
+| `enumType([...])` | hoisted `z.enum` |
+| `json()` / `jsonb()` with no type arg | `z.record(z.string(), z.unknown())` |
+| `jsonb<Record<string, unknown>>()` | `z.record(z.string(), z.unknown())` |
+| `jsonb<{ featured: boolean }>()` (inline object type) | `z.object({ featured: z.boolean(), … })` |
+| `json()` / `jsonb()` with `.schema()` validation IR | same as IR (`z.object`, nested `z.record`, …); wins over generics |
+| `timestamp()` | `Date` or ISO datetime string → `Date` |
+
+Raw `.check("sql")` is not mapped. With `generate.zod: true`, `generate.typebox: true`, or `generate.elysia: true`, codegen reads inline `json()` / `jsonb()` type arguments from `schema.ts` and maps object literals to `z.object`, `Record<K,V>` to `z.record`, and primitives to the matching Zod types. Type aliases and imported types are not resolved yet — use an inline type or `.schema()` for those.
+
+```ts
+metadata: jsonb<{ featured: boolean; category?: string }>(),
+// → metadata: z.object({ featured: z.boolean(), category: z.string().optional() }).nullable()
+```
+
+For shapes codegen cannot infer from the generic, use `.schema()`:
+
+```ts
+metadata: jsonb().schema({
+  kind: "object",
+  fields: [
+    {
+      name: "featured",
+      type: { kind: "boolean" },
+      nullable: false,
+      optional: false,
+    },
+  ],
+}),
+```