neoorm 0.1.4 → 0.2.0

package/README.md

@@ -12,7 +12,44 @@ Requires Node.js 20+ and PostgreSQL.
 
 ## Quick start
 
-**1. Define a schema** (`schema.ts`):
+**1. Scaffold a new project**
+
+```bash
+npx neoorm init
+```
+
+This creates `neoorm.config.ts`, `schema.ts`, `.env.example`, generates `neoorm/client.ts` (and related files), and writes the first migration under `neoorm/migrations/`.
+
+**2. Set your database URL**
+
+```bash
+cp .env.example .env
+# edit DATABASE_URL in .env
+```
+
+**3. Apply migrations**
+
+```bash
+npx neoorm migrate deploy
+```
+
+**4. Query**
+
+```ts
+import { db } from "./neoorm/client.js";
+
+const user = await db.users.findById(userId, {
+  with: {
+    posts: { orderBy: { createdAt: "desc" }, limit: 10 },
+  },
+});
+```
+
+### Manual setup
+
+If you prefer to write files yourself instead of `neoorm init`:
+
+**Define a schema** (`schema.ts`):
 
 ```ts
 import { defineSchema, table, uuid, text, timestamp, fk } from "neoorm/schema";
@@ -43,6 +80,7 @@ export default defineConfig({
   datasource: {
     provider: "postgresql",
     url: process.env.DATABASE_URL!,
+    enum: "check", // "check" (default) | "union" | "native"
   },
 });
 ```
@@ -55,18 +93,6 @@ npx neoorm generate
 
 This writes `client.ts`, `manifest.ts`, `models.ts`, `includes.ts`, and migration SQL when the schema changed.
 
-**4. Query**
-
-```ts
-import { db } from "./neoorm/client.js";
-
-const user = await db.users.findById(userId, {
-  with: {
-    posts: { orderBy: { createdAt: "desc" }, limit: 10 },
-  },
-});
-```
-
 ## Schema DSL
 
 ### Tables and accessors
@@ -81,20 +107,148 @@ Column field names use camelCase in TypeScript. By default, SQL column names are
 
 ### Column types
 
-| Builder | SQL type | Notes |
-|---------|----------|-------|
-| `id.primary()` | `TEXT` | App-generated string IDs (e.g. `user_a1b2c3d4`) |
-| `uuid()` | `UUID` | Defaults to UUID v7; pass `{ version: 4 }` for v4 |
-| `uuid().primary()` | `UUID` | Primary key; auto-generated on create if omitted |
-| `text()` | `TEXT` | |
-| `bool()` | `BOOLEAN` | |
-| `int()` | `INTEGER` | |
-| `timestamp()` | `TIMESTAMPTZ` | Use `.defaultNow()` for `DEFAULT NOW()` |
+| Builder | SQL type | TypeScript | Notes |
+|---------|----------|------------|-------|
+| `id.primary()` | `TEXT` | `string` | App-generated string IDs (e.g. `user_a1b2c3d4`) |
+| `uuid()` | `UUID` | `string` | Defaults to UUID v7; pass `{ version: 4 }` for v4 |
+| `uuid().primary()` | `UUID` | `string` | Primary key; auto-generated on create if omitted |
+| `serial()` | `INTEGER GENERATED BY DEFAULT AS IDENTITY` | `number` | Auto-increment; omit on insert, DB assigns via `RETURNING` |
+| `serial().primary()` | same | `number` | Integer PK with DB-generated values |
+| `text()` | `TEXT` | `string \| null` | |
+| `bool()` | `BOOLEAN` | `boolean \| null` | |
+| `int()` | `INTEGER` | `number \| null` | |
+| `timestamp()` | `TIMESTAMPTZ` | `Date \| null` | Use `.defaultNow()` for `DEFAULT NOW()`; use `.updatedAt()` for auto-update on ORM writes |
 
-All column builders support `.notNull()`, `.unique()`, `.default(value)`, `.defaultNow()`, `.primary()`, and `.map(name)`.
+Pair audit timestamps on mutable tables:
+
+```ts
+createdAt: timestamp().notNull().defaultNow(),
+updatedAt: timestamp().notNull().defaultNow().updatedAt(),
+```
+
+`.updatedAt()` is ORM metadata only (no DB trigger). `update`, `updateById`, `updateMany`, and `upsert` always set the column to `NOW()` in SQL; user-provided values in `data` are ignored.
+| `json()` | `JSON` | `unknown \| null` | Generic: `json<MyType>()` |
+| `jsonb()` | `JSONB` | `unknown \| null` | Generic: `jsonb<MyType>()` |
+| `decimal()` / `numeric()` | `NUMERIC` or `NUMERIC(p,s)` | `string \| null` | Use strings to avoid float precision loss |
+| `enumType(["a", "b"])` | mode-dependent | union literals | See [Enum columns](#enum-columns) |
+| `bytea()` | `BYTEA` | `Buffer \| null` | Binary data |
+| `textArray()` | `TEXT[]` | `string[] \| null` | |
+| `intArray()` | `INTEGER[]` | `number[] \| null` | |
+| `citext()` | `CITEXT` | `string \| null` | Case-insensitive text; requires `citext` extension |
+
+All column builders support `.notNull()`, `.unique()`, `.default(value)`, `.defaultNow()`, `.updatedAt()` (timestamp only), `.primary()`, and `.map(name)`.
 
 Foreign keys use `fk("target_table.target_column", { as, inverse, nullable?, onDelete? })`.
 
+### Enum columns
+
+Define allowed values in the schema:
+
+```ts
+import { enumType, table } from "neoorm/schema";
+
+posts: table("posts", {
+  status: enumType(["draft", "published", "archived"] as const)
+    .notNull()
+    .default("draft"),
+})
+```
+
+Control how enums are stored via `datasource.enum` in `neoorm.config.ts`:
+
+| Mode | SQL | DB enforcement |
+|------|-----|----------------|
+| `check` (default) | `TEXT` + `CHECK (...)` | yes |
+| `union` | `TEXT` | no (TypeScript union only) |
+| `native` | Postgres `CREATE TYPE ... AS ENUM` | yes |
+
+```ts
+export default defineConfig({
+  schema: "./schema.ts",
+  out: "./neoorm",
+  datasource: {
+    provider: "postgresql",
+    url: process.env.DATABASE_URL!,
+    enum: "check", // or "union" | "native"
+  },
+});
+```
+
+Optional custom SQL type name for native mode: `enumType(["draft", "published"], { name: "post_status" })`.
+
+Query and mutate enum columns like strings with compile-time union checking:
+
+```ts
+await db.posts.findMany({ where: { status: "published" } });
+await db.posts.create({ data: { title: "Hello", status: "draft" } });
+```
+
+### JSON and decimal columns
+
+```ts
+posts: table("posts", {
+  metadata: jsonb<{ tags: string[]; featured?: boolean }>(),
+  price: decimal({ precision: 10, scale: 2 }).default("0.00"),
+})
+```
+
+```ts
+// jsonb — exact equality on the full object (all keys must match)
+await db.posts.findMany({
+  where: { metadata: { featured: true, category: "engineering" } },
+});
+
+// jsonb — partial / subset match (@> containment)
+await db.posts.findMany({
+  where: { metadata: { jsonContains: { featured: true } } },
+});
+
+// jsonb — key existence and path filters
+await db.posts.findMany({
+  where: {
+    metadata: {
+      hasKey: "featured",
+      hasAnyKeys: ["category", "tags"],
+      path: { segments: ["category"], equals: "engineering" },
+    },
+  },
+});
+
+// decimal — compare as strings
+await db.posts.findMany({
+  where: { price: { gte: "9.99", lte: "49.99" } },
+});
+
+await db.posts.create({
+  data: {
+    title: "Premium",
+    price: "19.99",
+    metadata: { featured: true, tags: ["orm"] },
+  },
+});
+```
+
+### Serial primary keys
+
+```ts
+items: table("items", {
+  id: serial().primary(),
+  name: text().notNull(),
+})
+```
+
+Omit `id` on insert — the database assigns it and `RETURNING` populates the result:
+
+```ts
+const item = await db.items.create({ data: { name: "Widget" } });
+// item.id is the DB-generated integer
+
+// Bulk insert with returned rows (serial IDs, UUIDs, defaults materialized)
+const items = await db.items.createManyAndReturn({
+  data: [{ name: "A" }, { name: "B" }],
+});
+```
+
 ### UUID columns
 
 ```ts
@@ -158,6 +312,142 @@ manyToMany(schema.posts, schema.tags, {
 });
 ```
 
+## Relation writes
+
+`create` and `update` accept nested relation writes alongside scalar fields. Relation-only updates are supported (no scalar `SET` required).
+
+| Relation kind | Operations |
+|---------------|------------|
+| **To-one** (outgoing FK) | `connect`, `create`, `disconnect` (nullable FK only) |
+| **One-to-many** (inverse) | `create`, `connect`, `disconnect`, `set`, `delete` |
+| **Many-to-many** | `connect`, `connectOrCreate`, `disconnect`, `set`, `delete` |
+
+```ts
+// To-one on update
+await db.posts.update({
+  where: { id: postId },
+  data: { author: { connect: { id: userId } } },
+});
+
+// Nested create on one-to-many (full nested relation writes inside create items)
+await db.posts.update({
+  where: { id: postId },
+  data: {
+    comments: {
+      create: [{ body: "Hi", author: { connect: { id: userId } } }],
+      connect: [{ id: commentId }],
+      disconnect: [{ id: oldCommentId }], // or `true` to unlink all
+      set: [{ id: commentId }],           // replace all links
+      delete: [{ id: commentId }],        // or `true` to delete all linked children
+    },
+  },
+});
+
+// M2M on create or update
+await db.posts.update({
+  where: { id: postId },
+  data: {
+    tags: {
+      connect: [{ id: tagId }],
+      set: [{ id: tagId }],
+      connectOrCreate: [
+        { where: { slug: "orm" }, create: { slug: "orm", name: "ORM" } },
+      ],
+      delete: [{ id: tagId }], // removes junction links, then deletes tag rows
+    },
+  },
+});
+
+// updateMany applies scalar SET once, then nested writes per matched parent
+await db.posts.updateMany({
+  where: { published: true },
+  data: {
+    status: "archived",
+    tags: { connect: [{ id: tagId }] },
+  },
+});
+```
+
+Within a single relation field, operations run in order: `delete` → `disconnect` → `set` → `connect` / `connectOrCreate` → `create`. Mixing `set` with `connect` or `create` is discouraged — `set` replaces the full link set.
+
+## Cursor pagination
+
+For feeds, infinite scroll, and large tables, use `paginate` instead of `limit`/`offset`. It uses **keyset pagination** on your `orderBy` columns plus the table primary key as a stable tiebreaker (for example `(createdAt, id)`).
+
+```ts
+let cursor: { createdAt: string; id: string } | null = null;
+
+for (;;) {
+  const page = await db.posts.paginate({
+    where: { published: true },
+    orderBy: { createdAt: "desc" },
+    take: 20,
+    ...(cursor ? { after: cursor } : {}),
+    with: { author: true },
+  });
+
+  for (const post of page.items) {
+    // render post
+  }
+
+  if (!page.hasMore) break;
+  cursor = page.nextCursor;
+}
+```
+
+- `orderBy` is required; scalar `id` is appended automatically when omitted.
+- `take` is the page size; `hasMore` uses a `take + 1` probe row.
+- `after` is a typed cursor object (`nextCursor` from the previous page).
+- For HTTP APIs, encode cursors with `encodeCursor` / `decodeCursor` from `neoorm`.
+
+On feed tables, add a composite index on the sort columns (for example `index().on(t.createdAt, t.id)`).
+
+## Aggregates
+
+### Relation counts in `with`
+
+Load counts without fetching full related rows:
+
+```ts
+const users = await db.users.findMany({
+  with: {
+    _count: { posts: true },
+    profile: true,
+  },
+});
+// users[0]._count.posts === number
+```
+
+Optional per-relation filter: `_count: { posts: { where: { published: true } } }`.
+
+### Table-level `aggregate()`
+
+```ts
+const stats = await db.posts.aggregate({
+  where: { published: true },
+  _count: true,
+  _avg: { views: true },
+});
+// { _count: number, _avg: { views: number | null } }
+```
+
+For grouped dashboards, use `db.sql` or the `sqlBuilder` helper.
+
+## Bulk insert
+
+`createMany` returns the number of rows inserted. Use `createManyAndReturn` when you need serial IDs, generated UUIDs, or default values in the result:
+
+```ts
+const users = await db.users.createManyAndReturn({
+  data: [
+    { email: "a@example.com", name: "A" },
+    { email: "b@example.com", name: "B" },
+  ],
+});
+```
+
+Scalar fields only — no nested relation writes (same as `createMany`).
+
 ## Where clauses
 
 `findMany`, `findFirst`, `findUnique`, `count`, `update`, `updateMany`, `delete`, and `deleteMany` all accept a typed `where` argument.
@@ -180,7 +470,29 @@ await db.posts.findFirst({
 });
 ```
 
-String columns support `equals`, `contains`, `startsWith`, `endsWith`, `in`, and `notIn`. Numeric, boolean, and date columns support `equals`, `gt`, `gte`, `lt`, `lte`, `in`, and `notIn`. All nullable columns also support `isNull` and `isNotNull`.
+String columns support `equals`, `contains`, `startsWith`, `endsWith`, `in`, and `notIn`. Numeric, boolean, and date columns support `equals`, `gt`, `gte`, `lt`, `lte`, `in`, and `notIn`. JSON columns support `jsonContains`, `hasKey`, `hasAnyKeys`, `hasAllKeys`, and `path`. All nullable columns also support `isNull` and `isNotNull`.
+
+### `distinct`
+
+PostgreSQL `DISTINCT ON` — `orderBy` must lead with the same columns:
+
+```ts
+await db.users.findMany({
+  distinct: ["email"],
+  orderBy: { email: "asc" },
+});
+```
+
+### Selective `with` return types
+
+Relation `select` narrows the TypeScript return type at compile time:
+
+```ts
+const users = await db.users.findMany({
+  with: { posts: { select: { title: true } } },
+});
+// users[0].posts[0].title is string; .body is excluded from the type
+```
 
 ```ts
 await db.users.findMany({
@@ -266,26 +578,94 @@ const [user, post] = await db.$transaction([
   (tx) => tx.posts.create({ data: { title: "Hello" } }),
 ]);
 
-// Options
+// Options (outermost transaction only)
 await db.$transaction(fn, {
   isolationLevel: "Serializable", // ReadUncommitted | ReadCommitted | RepeatableRead | Serializable
   readOnly: true,
 });
+
+// Nested $transaction uses PostgreSQL savepoints on the same connection.
+// A nested failure rolls back only that block; the outer transaction can continue.
+await db.$transaction(async (tx) => {
+  await tx.users.create({ data: { email: "outer@example.com" } });
+
+  await tx.$transaction(async (nested) => {
+    await nested.posts.create({
+      data: { title: "Nested", body: "...", authorId: "user_1" },
+    });
+  }).catch(() => undefined);
+
+  // Outer writes are kept even if the nested block failed.
+});
 ```
 
-Nested `create` calls inside a transaction do not start a separate transaction.
+Nested `create` calls inside a transaction do not start a separate transaction. Nested `$transaction` calls use savepoints; `readOnly` and `isolationLevel` apply only to the outermost `BEGIN`.
 
 ## CLI
 
 | Command | Description |
 |---------|-------------|
+| `neoorm init` | Scaffold `neoorm.config.ts`, `schema.ts`, `.env.example`, generate client, and first migration |
 | `neoorm generate` | Emit manifest, typed client, models, includes, and migrations |
 | `neoorm migrate dev` | Apply pending migrations, then generate a new one if the schema changed |
 | `neoorm migrate deploy` | Apply pending migrations |
+| `neoorm migrate status` | List applied vs pending migrations |
+| `neoorm migrate down [--steps N]` | Roll back the last N applied migrations (default 1) |
+| `neoorm migrate reset --force` | Drop public schema and re-apply migrations (local dev) |
 | `neoorm db push` | Push the current snapshot schema to the database |
 | `neoorm db pull` | Introspect the database into a schema file |
 
-`generate` always rewrites generated TypeScript files. Migration SQL is created only when the schema diff produces changes (new tables/columns, column renames via `.map()`).
+### Generate outcomes
+
+`neoorm generate` always refreshes generated TypeScript files (`client.ts`, `manifest.ts`, `models.ts`, etc.). It prints one of four outcomes:
+
+| Outcome | Meaning |
+|---------|---------|
+| **Schema unchanged** | Snapshot hash matches — no manifest or migration changes |
+| **Client regenerated** | Manifest changed but no database DDL was needed (e.g. `enumMode`, relation metadata) |
+| **Migration created** | New `migrations/<timestamp>/migration.sql` written |
+| **Migration blocked** | Destructive or manual changes prevented writing SQL |
+
+When migration is blocked or skipped, the CLI explains why — for example unsupported type casts (`alter_column_type_manual`), enum value changes, or destructive drops. Re-run with `--accept-data-loss` to include destructive DDL, or write a manual migration for unsupported type changes.
+
+```bash
+neoorm generate --accept-data-loss
+```
+
+### Migration status and reset
+
+```bash
+neoorm migrate status
+```
+
+Shows applied migrations (with timestamps), pending folders on disk, and warnings for drift (applied in DB but missing on disk).
+
+```bash
+neoorm migrate reset --force
+```
+
+Drops the `public` schema and re-applies all migrations from disk. Requires `--force`. Use `--skip-apply` to only drop the schema without re-applying.
+
+### Rolling back migrations
+
+```bash
+neoorm migrate down
+neoorm migrate down --steps 2
+```
+
+Rolls back the most recently applied migration(s) by running each migration folder's `down.sql`, removing the ledger entry from `_neoorm_migrations`, and restoring `snapshot.json` from `snapshot.before.json` (the manifest state before that migration was applied).
+
+`down.sql` and `snapshot.before.json` are written automatically when `neoorm generate` or `neoorm migrate dev` creates a migration. The down SQL is the reverse schema diff (`next → prev`), with destructive changes accepted so rollbacks can drop columns or tables added in the forward migration.
+
+Legacy migrations without `down.sql` cannot be rolled back — re-generate the migration or add `down.sql` manually.
+
+Migration folders are not deleted on rollback (same as Prisma). Re-run `neoorm migrate deploy` to re-apply rolled-back migrations.
+
+After rollback, `schema.ts` may still describe a newer schema than the restored snapshot; `neoorm migrate dev` may generate a new forward migration. `db push` and `migrate down` are independent — push ignores the migration ledger.
+
+For a full wipe during local development, use `neoorm migrate reset --force` instead.
+
+`generate` creates migration SQL only when the schema diff produces DDL changes (new tables/columns, column renames via `.map()`, etc.).
 
 ## Plugins
 
@@ -319,6 +699,22 @@ await db.places.findMany({
 
 PostGIS columns are stored as geometry/geography in PostgreSQL and exposed as GeoJSON in TypeScript.
 
+### Citext
+
+`citext()` is registered as a separate plugin that enables the `citext` extension when used in a schema:
+
+```ts
+import { citext, table } from "neoorm/schema";
+
+users: table("users", {
+  email: citext().notNull().unique(),
+})
+```
+
+## Examples
+
+The [blog example](examples/blog/schema.ts) demonstrates relations, many-to-many, `jsonb`, `decimal`, and `enumType` columns. See [queries.example.ts](examples/blog/queries.example.ts) for typed queries and mutations using those types.
+
 ## API surface
 
 | Import | Purpose |