vibeorm 1.1.1 → 1.1.4

package/README.md

@@ -1,71 +1,316 @@
-# vibeorm
+# VibeORM
 
-CLI for VibeORM — generate clients, run migrations, and manage your PostgreSQL database.
+A type-safe TypeScript ORM for **Bun + PostgreSQL**. Parses Prisma `.prisma` schema files and generates a fully typed client that executes raw SQL — no build step, no runtime overhead.
 
-## Installation
+## Quick Start
+
+### Prerequisites
+
+- [Bun](https://bun.sh) >= 1.1.0
+- PostgreSQL
+
+### 1. Install
+
+```bash
+bun add vibeorm @vibeorm/runtime @vibeorm/adapter-bun
+```
+
+Or with `node-postgres`:
+
+```bash
+bun add vibeorm @vibeorm/runtime @vibeorm/adapter-pg pg
+```
+
+### 2. Initialize
+
+```bash
+bunx vibeorm init
+```
+
+This scaffolds your project with a starter schema, seed script, `.env` file, and adds convenience scripts to `package.json`.
+
+### 3. Define your schema
+
+Edit `prisma/schema.prisma`:
+
+```prisma
+datasource db {
+  provider = "postgresql"
+  url      = env("DATABASE_URL")
+}
+
+model User {
+  id        Int      @id @default(autoincrement())
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+  email     String   @unique
+  name      String?
+  posts     Post[]
+}
+
+model Post {
+  id        Int      @id @default(autoincrement())
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
+  title     String
+  content   String?
+  published Boolean  @default(false)
+  authorId  Int
+  author    User     @relation(fields: [authorId], references: [id])
+}
+```
+
+### 4. Generate and push
 
 ```bash
-bun add -d vibeorm
+bunx vibeorm generate
+bunx vibeorm db push --force
+```
+
+### 5. Use the client
+
+```ts
+import { VibeClient } from "./generated/vibeorm/index.ts";
+import { bunAdapter } from "@vibeorm/adapter-bun";
+
+const db = VibeClient({ adapter: bunAdapter() });
+
+// Create
+const user = await db.user.create({
+  data: { email: "alice@example.com", name: "Alice" },
+});
+
+// Query with relations
+const users = await db.user.findMany({
+  where: { email: { contains: "alice", mode: "insensitive" } },
+  include: { posts: true },
+  orderBy: { createdAt: "desc" },
+});
+
+// Type-safe select — return type is narrowed to only { id, email }
+const emails = await db.user.findMany({
+  select: { id: true, email: true },
+});
+
+await db.$disconnect();
+```
+
+---
+
+## Schema
+
+VibeORM uses the Prisma `.prisma` DSL. All standard Prisma features are supported:
+
+- **Scalar types:** `String`, `Int`, `BigInt`, `Float`, `Decimal`, `Boolean`, `DateTime`, `Json`, `Bytes`
+- **Scalar lists:** `String[]`, `Int[]`, etc.
+- **Enums** with `@@map`
+- **ID fields:** `@id`, `@@id` (composite primary keys)
+- **Unique constraints:** `@unique`, `@@unique` (compound)
+- **Defaults:** `@default(autoincrement())`, `@default(now())`, `@default(uuid())`, `@default(cuid())`, `@default(nanoid())`, `@default(ulid())`
+- **Auto-updated timestamps:** `@updatedAt`
+- **Column/table mapping:** `@map`, `@@map`
+- **Relations:** `@relation` for 1:1, 1:N, N:M (implicit join tables), self-referential
+- **Indexes:** `@@index`
+- **Multi-file schemas:** directory of `.prisma` files (loaded alphabetically)
+- **Native type annotations:** `@db.VarChar(255)`, etc.
+- **Custom ID prefixes:** `/// @vibeorm.idPrefix("usr_")`
+
+### Multi-file schemas
+
+Instead of a single schema file, you can split your schema across multiple files in a directory:
+
 ```
+prisma/schema/
+  01-base.prisma       # datasource block
+  02-user.prisma       # User model
+  03-content.prisma    # Post, Comment models
+```
+
+Configure the `schema` option to point to the directory instead of a file.
+
+---
 
-## Commands
+## CLI Commands
 
 ```bash
 bunx vibeorm <command> [options]
 ```
 
-### Code Generation
+### `init`
+
+Scaffold a new VibeORM project in the current directory.
+
+```bash
+bunx vibeorm init
+bunx vibeorm init --empty              # No example models
+bunx vibeorm init --adapter pg         # Use node-postgres in templates
+bunx vibeorm init --schema ./db/schema.prisma --output ./src/generated
+```
+
+Creates:
+- `prisma/schema.prisma` — starter schema with `User` and `Post` models
+- `prisma/seed.ts` — seed script using the generated client
+- `.env` — `DATABASE_URL` placeholder
+- Updates `package.json` with `vibeorm` config and convenience scripts
+
+| Flag | Description |
+|------|-------------|
+| `--empty` | Skip example models, create only the datasource block |
+| `--adapter <name>` | Adapter for seed template: `bun` (default) or `pg` |
+| `--schema <path>` | Custom schema path (default: `./prisma/schema.prisma`) |
+| `--output <path>` | Custom output directory (default: `./generated/vibeorm`) |
+
+### `generate`
+
+Parse the `.prisma` schema and generate TypeScript client files.
+
+```bash
+bunx vibeorm generate
+```
+
+Generates 8 TypeScript files in the configured output directory:
+
+| File | Contents |
+|------|----------|
+| `index.ts` | `VibeClient()` factory, model metadata, re-exports |
+| `enums.ts` | TypeScript enums |
+| `models.ts` | Model types and payload types |
+| `inputs.ts` | Where, Create, Update, OrderBy input types and filter types |
+| `args.ts` | Per-model operation argument types (FindManyArgs, CreateArgs, etc.) |
+| `result.ts` | Type narrowing logic for select/include/omit |
+| `delegates.ts` | Per-model delegate types with JSDoc examples |
+| `schemas.ts` | Zod v4 validation schemas |
+
+### `db push`
+
+Push the schema directly to the database without creating migration files. Ideal for prototyping.
+
+```bash
+bunx vibeorm db push                   # Safe changes only
+bunx vibeorm db push --force           # Allow destructive changes
+bunx vibeorm db push --dry-run         # Print SQL without executing
+```
+
+| Flag | Description |
+|------|-------------|
+| `--force` / `--accept-data-loss` | Allow destructive changes (drop columns, tables) |
+| `--dry-run` | Print the DDL SQL without executing |
+
+### `db pull`
+
+Introspect an existing database and generate a `.prisma` schema file from it.
+
+```bash
+bunx vibeorm db pull                   # Write to schema file
+bunx vibeorm db pull --print           # Print to stdout instead
+```
+
+### `db reset`
+
+Drop the entire `public` schema, re-apply all migrations, and optionally run the seed script.
+
+```bash
+bunx vibeorm db reset --force
+bunx vibeorm db reset --force --skip-seed
+```
+
+| Flag | Description |
+|------|-------------|
+| `--force` | Required — confirms you want to drop everything |
+| `--skip-seed` | Skip running the seed script after migrations |
+
+### `db seed`
+
+Run the configured seed script.
+
+```bash
+bunx vibeorm db seed
+```
+
+Spawns `bun run <seedPath>` as a subprocess.
+
+### `db execute`
+
+Execute a raw SQL file against the database.
+
+```bash
+bunx vibeorm db execute --file ./scripts/cleanup.sql
+```
+
+### `migrate generate`
+
+Generate a new migration by diffing the current schema against the last snapshot. Does **not** require a database connection.
+
+```bash
+bunx vibeorm migrate generate --name add-posts-table
+bunx vibeorm migrate generate --dry-run
+```
+
+Creates `migrations/<timestamp>_<name>/migration.sql` + `down.sql` and updates the snapshot journal.
 
-| Command | Description |
-|---------|-------------|
-| `generate` | Parse `.prisma` schema and generate TypeScript client files |
+| Flag | Description |
+|------|-------------|
+| `--name <name>` | Migration name (default: `migration`) |
+| `--dry-run` | Print the SQL without writing files |
 
-### Database Management
+### `migrate apply`
 
-| Command | Description |
-|---------|-------------|
-| `db push` | Diff schema against database and apply changes |
-| `db pull` | Introspect database and write `.prisma` schema |
-| `db reset` | Drop schema, re-apply migrations, optionally seed |
-| `db seed` | Run configured seed script |
-| `db execute` | Execute a raw SQL file |
+Apply all pending migrations in order.
 
-Options for `db push`: `--force`, `--accept-data-loss`, `--dry-run`
-Options for `db pull`: `--print`
-Options for `db reset`: `--force` (required), `--skip-seed`
-Options for `db execute`: `--file <path>`
+```bash
+bunx vibeorm migrate apply
+bunx vibeorm migrate apply --dry-run
+```
 
-### Migrations
+### `migrate status`
 
-| Command | Description |
-|---------|-------------|
-| `migrate generate` | Create migration SQL from schema diff |
-| `migrate apply` | Apply pending migrations |
-| `migrate status` | Show applied vs pending migrations |
-| `migrate resolve` | Repair migration state |
+Show which migrations are applied, pending, or modified.
 
-Options for `migrate generate`: `--name <name>`, `--dry-run`
-Options for `migrate apply`: `--dry-run`
-Options for `migrate resolve`: `--applied <name>`, `--rolled-back <name>`
+```bash
+bunx vibeorm migrate status
+```
+
+### `migrate rollback`
+
+Roll back the last N applied migrations using their `down.sql` files.
+
+```bash
+bunx vibeorm migrate rollback              # Roll back 1
+bunx vibeorm migrate rollback --steps 3    # Roll back 3
+bunx vibeorm migrate rollback --dry-run
+```
+
+### `migrate resolve`
+
+Repair migration state when things get out of sync.
+
+```bash
+bunx vibeorm migrate resolve --applied my-migration    # Mark as applied without running
+bunx vibeorm migrate resolve --rolled-back my-migration # Remove from applied records
+```
 
 ### Global Options
 
-All commands accept:
+All commands accept these flags:
+
+| Flag | Description |
+|------|-------------|
+| `--schema <path>` | Path to `.prisma` schema file or directory |
+| `--output <path>` | Output directory for generated files |
+| `--migrations <path>` | Migrations directory |
+| `--seed <path>` | Seed script path |
+| `--url <url>` | Database connection string (overrides `DATABASE_URL` env) |
 
-- `--schema <path>` — path to `.prisma` schema file or directory
-- `--output <path>` — output directory for generated files
-- `--migrations <path>` — migrations directory
-- `--seed <path>` — seed script path
-- `--url <postgres-url>` — database connection string
+---
 
 ## Configuration
 
-Config priority (last wins):
+Config is resolved in this order (last wins):
 
-1. Defaults (`./prisma/schema.prisma`, `./generated/vibeorm`, `./migrations`)
-2. `package.json` `vibeorm` key
-3. `vibeorm.config.ts`
-4. CLI flags
+1. **Defaults** — `./prisma/schema.prisma`, `./generated/vibeorm`, `./migrations`
+2. **`package.json`** — `vibeorm` key
+3. **`vibeorm.config.ts`** — config file in project root
+4. **CLI flags** — `--schema`, `--output`, `--migrations`, `--seed`
 
 ### package.json
 
@@ -91,6 +336,815 @@ export const config = {
 };
 ```
 
+### Typical migration workflow
+
+```bash
+# 1. Edit your schema
+# 2. Generate a migration
+bunx vibeorm migrate generate --name add-comments
+
+# 3. Review the generated SQL in migrations/<timestamp>_add-comments/migration.sql
+
+# 4. Apply pending migrations
+bunx vibeorm migrate apply
+
+# 5. Regenerate the client
+bunx vibeorm generate
+```
+
+### Prototyping workflow (no migrations)
+
+```bash
+bunx vibeorm db push --force
+bunx vibeorm generate
+```
+
+---
+
+## Client API
+
+### Instantiation
+
+```ts
+import { VibeClient } from "./generated/vibeorm/index.ts";
+import { bunAdapter } from "@vibeorm/adapter-bun";
+
+const db = VibeClient({
+  // Required
+  adapter: bunAdapter({ url: "postgres://..." }),
+  // Or let it read DATABASE_URL from env:
+  // adapter: bunAdapter(),
+
+  // Optional
+  log: "query",                 // false | true | "query" | "info" | "warn" | "error"
+  relationStrategy: "query",    // "query" (batched WHERE IN) | "join" (LATERAL JOIN)
+  countStrategy: "direct",      // "direct" | "subquery"
+  eager: true,                  // Warm up connection pool immediately
+  validate: false,              // false | true | "input" | "output" | "all"
+  defaultOrderByPk: false,      // Add ORDER BY pk to all queries without explicit orderBy
+  debug: true,                  // false | true | ((params: { profile }) => void)
+  idGenerator: ({ model, field, defaultKind }) => {
+    return `${model.toLowerCase().slice(0, 3)}_${crypto.randomUUID()}`;
+  },
+});
+```
+
+With `node-postgres`:
+
+```ts
+import { pgAdapter } from "@vibeorm/adapter-pg";
+
+const db = VibeClient({
+  adapter: pgAdapter({ connectionString: "postgres://..." }),
+});
+```
+
+### Connection management
+
+```ts
+await db.$connect();     // Explicitly warm up the connection pool
+await db.$disconnect();  // Close all connections
+```
+
+---
+
+### Read Operations
+
+#### `findMany`
+
+```ts
+const users = await db.user.findMany({
+  where: { email: { endsWith: "@example.com" } },
+  include: { posts: true },
+  orderBy: { email: "asc" },
+  take: 20,
+  skip: 0,
+});
+```
+
+With all options:
+
+```ts
+const users = await db.user.findMany({
+  where: { ... },
+  select: { id: true, email: true },     // Only these fields
+  include: { posts: true },              // Load relations (alongside all scalars)
+  omit: { createdAt: true },             // Exclude specific scalars
+  orderBy: [{ role: "desc" }, { name: "asc" }],
+  take: 20,
+  skip: 0,
+  cursor: { id: 10 },                    // Cursor-based pagination
+  distinct: ["role"],                     // DISTINCT ON
+  relationStrategy: "join",              // Per-query override
+});
+```
+
+#### `findFirst`
+
+```ts
+const user = await db.user.findFirst({
+  where: { role: "ADMIN" },
+  orderBy: { createdAt: "desc" },
+});
+// Returns: User | null
+```
+
+#### `findUnique`
+
+```ts
+const user = await db.user.findUnique({
+  where: { id: 1 },
+  include: { posts: true },
+});
+// Returns: User | null
+
+// Compound unique:
+const follow = await db.follow.findUnique({
+  where: { followerId_followingId: { followerId: 1, followingId: 2 } },
+});
+```
+
+#### `findFirstOrThrow` / `findUniqueOrThrow`
+
+Same as `findFirst`/`findUnique` but throw `VibeRequestError` with code `"NOT_FOUND"` if no match.
+
+```ts
+const user = await db.user.findUniqueOrThrow({
+  where: { id: 1 },
+});
+// Throws if not found — return type is never null
+```
+
+---
+
+### Write Operations
+
+#### `create`
+
+```ts
+const user = await db.user.create({
+  data: {
+    email: "alice@example.com",
+    name: "Alice",
+  },
+  select: { id: true, email: true },  // Narrow the return type
+});
+```
+
+With nested create:
+
+```ts
+const user = await db.user.create({
+  data: {
+    email: "alice@example.com",
+    name: "Alice",
+    posts: {
+      create: [
+        { title: "First Post", content: "Hello world" },
+        { title: "Second Post" },
+      ],
+    },
+  },
+  include: { posts: true },
+});
+```
+
+#### `createMany`
+
+```ts
+const result = await db.user.createMany({
+  data: [
+    { email: "alice@example.com" },
+    { email: "bob@example.com" },
+  ],
+  skipDuplicates: true,   // ON CONFLICT DO NOTHING
+});
+// Returns: { count: number }
+```
+
+#### `createManyAndReturn`
+
+```ts
+const users = await db.user.createManyAndReturn({
+  data: [
+    { email: "alice@example.com" },
+    { email: "bob@example.com" },
+  ],
+  select: { id: true, email: true },
+});
+// Returns: Array of created records
+```
+
+#### `update`
+
+```ts
+const user = await db.user.update({
+  where: { id: 1 },
+  data: { name: "Updated Name" },
+  select: { id: true, name: true },
+});
+// Throws NOT_FOUND if where matches nothing
+```
+
+Atomic operations on numeric fields:
+
+```ts
+await db.post.update({
+  where: { id: 1 },
+  data: {
+    viewCount: { increment: 1 },
+    // Also: decrement, multiply, divide, set
+  },
+});
+```
+
+#### `updateMany`
+
+```ts
+const result = await db.user.updateMany({
+  where: { role: "USER" },
+  data: { role: "ADMIN" },
+});
+// Returns: { count: number }
+```
+
+#### `upsert`
+
+```ts
+const user = await db.user.upsert({
+  where: { email: "alice@example.com" },
+  create: { email: "alice@example.com", name: "Alice" },
+  update: { name: "Alice Updated" },
+});
+```
+
+#### `delete`
+
+```ts
+const user = await db.user.delete({
+  where: { id: 1 },
+  select: { id: true, email: true },
+});
+// Throws NOT_FOUND if where matches nothing
+```
+
+#### `deleteMany`
+
+```ts
+const result = await db.user.deleteMany({
+  where: { role: "USER" },
+});
+// Returns: { count: number }
+```
+
+---
+
+### Nested Writes
+
+Nested operations are available inside `create` and `update` data:
+
+```ts
+// In create
+await db.user.create({
+  data: {
+    email: "alice@example.com",
+    posts: {
+      create: { title: "New Post" },
+      connect: [{ id: 5 }],
+      connectOrCreate: {
+        where: { id: 10 },
+        create: { title: "If not exists" },
+      },
+    },
+    profile: {
+      create: { bio: "Hello" },
+    },
+  },
+});
+
+// In update
+await db.user.update({
+  where: { id: 1 },
+  data: {
+    posts: {
+      create: { title: "New Post" },
+      connect: [{ id: 5 }],
+      disconnect: [{ id: 3 }],
+      delete: [{ id: 2 }],
+      set: [{ id: 5 }, { id: 6 }],               // Replace all
+      update: [{ where: { id: 5 }, data: { title: "Updated" } }],
+      upsert: [{ where: { id: 5 }, create: { title: "New" }, update: { title: "Upd" } }],
+      updateMany: [{ where: { published: false }, data: { published: true } }],
+      deleteMany: [{ authorId: 1 }],
+      connectOrCreate: { where: { id: 10 }, create: { title: "Created" } },
+    },
+    profile: {
+      create: { bio: "New" },
+      update: { bio: "Updated" },
+      upsert: { create: { bio: "New" }, update: { bio: "Updated" } },
+      connect: { id: 5 },
+      disconnect: true,
+      delete: true,
+      connectOrCreate: { where: { userId: 1 }, create: { bio: "Hello" } },
+    },
+  },
+});
+```
+
+---
+
+### Where Filters
+
+#### Scalar filters
+
+```ts
+where: {
+  // Equality (shorthand)
+  email: "alice@example.com",
+
+  // Explicit operators
+  email: { equals: "alice@example.com" },
+  email: { not: "alice@example.com" },
+  email: { in: ["alice@example.com", "bob@example.com"] },
+  email: { notIn: ["alice@example.com"] },
+
+  // String filters
+  email: { contains: "alice" },
+  email: { startsWith: "alice" },
+  email: { endsWith: "@example.com" },
+  email: { contains: "alice", mode: "insensitive" },  // Case-insensitive
+
+  // Numeric / DateTime comparisons
+  id: { lt: 10 },
+  id: { lte: 10 },
+  id: { gt: 5 },
+  id: { gte: 5 },
+
+  // Null checks
+  name: null,              // IS NULL
+  name: { not: null },     // IS NOT NULL
+
+  // Boolean
+  published: true,
+}
+```
+
+#### Logical combinators
+
+```ts
+where: {
+  AND: [{ role: "ADMIN" }, { name: { not: null } }],
+  OR: [{ role: "ADMIN" }, { role: "MODERATOR" }],
+  NOT: { role: "USER" },
+  NOT: [{ role: "USER" }, { email: { contains: "test" } }],
+}
+```
+
+#### Relation filters
+
+```ts
+where: {
+  // To-many relations
+  posts: {
+    some: { published: true },     // At least one post is published
+    none: { published: false },    // No posts are unpublished
+    every: { published: true },    // All posts are published
+  },
+
+  // To-one relations
+  author: {
+    is: { role: "ADMIN" },
+    isNot: { role: "USER" },
+    is: null,                      // FK IS NULL (no related record)
+  },
+
+  // Shorthand — object is treated as "is" (to-one) or "some" (to-many)
+  author: { role: "ADMIN" },
+  posts: { published: true },
+}
+```
+
+#### JSON filters
+
+```ts
+where: {
+  metadata: { equals: { key: "value" } },
+  metadata: { path: ["nested", "key"], equals: "value" },
+  metadata: { path: ["arr"], array_contains: [1, 2] },
+  metadata: { path: ["arr"], array_starts_with: [1] },
+  metadata: { path: ["arr"], array_ends_with: [3] },
+}
+```
+
+#### Scalar list (array) filters
+
+```ts
+where: {
+  tags: { has: "typescript" },
+  tags: { hasEvery: ["typescript", "orm"] },
+  tags: { hasSome: ["typescript", "javascript"] },
+  tags: { isEmpty: true },
+  tags: { equals: ["typescript", "orm"] },
+}
+```
+
+---
+
+### Select, Include, and Omit
+
+These options control which fields and relations are returned. **The return type is narrowed at compile time** — you get exact types for every query.
+
+#### `select` — return only specified fields
+
+```ts
+const users = await db.user.findMany({
+  select: {
+    id: true,
+    email: true,
+    posts: {
+      select: { title: true, published: true },
+      where: { published: true },
+      take: 5,
+    },
+    _count: { select: { posts: true } },
+  },
+});
+// Type: { id: number; email: string; posts: { title: string; published: boolean }[]; _count: { posts: number } }[]
+```
+
+#### `include` — load relations alongside all scalar fields
+
+```ts
+const users = await db.user.findMany({
+  include: {
+    posts: true,                                 // All posts
+    posts: {                                     // With filtering/pagination
+      where: { published: true },
+      orderBy: { createdAt: "desc" },
+      take: 5,
+      include: { comments: true },               // Nested include
+    },
+    profile: true,
+    _count: true,                                // Count all list relations
+    _count: { select: { posts: true } },         // Count specific relations
+  },
+});
+```
+
+#### `omit` — exclude specific scalar fields
+
+```ts
+const users = await db.user.findMany({
+  omit: { createdAt: true, updatedAt: true },
+});
+// Returns all scalar fields except createdAt and updatedAt
+```
+
+---
+
+### OrderBy, Pagination, and Distinct
+
+#### OrderBy
+
+```ts
+// Single field
+orderBy: { createdAt: "desc" },
+
+// Multiple fields
+orderBy: [{ role: "desc" }, { name: "asc" }],
+
+// Null ordering
+orderBy: { name: { sort: "desc", nulls: "last" } },
+
+// Relation field
+orderBy: { author: { name: "asc" } },
+
+// Relation count
+orderBy: { posts: { _count: "desc" } },
+```
+
+#### Cursor pagination
+
+```ts
+// Forward pagination
+const page = await db.post.findMany({
+  cursor: { id: lastSeenId },
+  take: 20,
+  orderBy: { id: "asc" },
+});
+
+// Backward pagination (negative take)
+const prevPage = await db.post.findMany({
+  cursor: { id: firstSeenId },
+  take: -20,
+  orderBy: { id: "asc" },
+});
+```
+
+#### Offset pagination
+
+```ts
+const page = await db.post.findMany({
+  skip: 20,
+  take: 10,
+  orderBy: { createdAt: "desc" },
+});
+```
+
+#### Distinct
+
+```ts
+const roles = await db.user.findMany({
+  distinct: ["role"],
+  select: { role: true },
+});
+```
+
+---
+
+### Aggregation
+
+#### `count`
+
+```ts
+const total = await db.post.count({
+  where: { published: true },
+});
+// Returns: number
+```
+
+#### `aggregate`
+
+```ts
+const stats = await db.post.aggregate({
+  where: { published: true },
+  _count: true,
+  _avg: { viewCount: true },
+  _sum: { viewCount: true },
+  _min: { createdAt: true },
+  _max: { createdAt: true },
+});
+// Returns: { _count: number, _avg: { viewCount: number | null }, _sum: {...}, _min: {...}, _max: {...} }
+```
+
+#### `groupBy`
+
+```ts
+const grouped = await db.post.groupBy({
+  by: ["published", "authorId"],
+  where: { createdAt: { gte: new Date("2024-01-01") } },
+  _count: true,
+  _avg: { viewCount: true },
+  having: {
+    viewCount: { _avg: { gte: 10 } },
+  },
+  orderBy: { published: "desc" },
+  take: 10,
+});
+// Returns: Array of { published, authorId, _count, _avg: { viewCount } }
+```
+
+---
+
+### Raw SQL
+
+#### Tagged template literals (parameterized)
+
+```ts
+const admins = await db.$queryRaw<{ id: number; email: string }>`
+  SELECT id, email FROM "User" WHERE role = ${"ADMIN"}
+`;
+
+const affected = await db.$executeRaw`
+  UPDATE "Post" SET published = true WHERE "authorId" = ${1}
+`;
+// Returns: number (affected row count)
+```
+
+#### Unsafe variants (string + params)
+
+```ts
+const rows = await db.$queryRawUnsafe<{ count: number }>(
+  'SELECT COUNT(*) as count FROM "User" WHERE role = $1',
+  "ADMIN"
+);
+
+const affected = await db.$executeRawUnsafe(
+  'DELETE FROM "User" WHERE id = $1',
+  123
+);
+```
+
+---
+
+### Transactions
+
+#### Callback style
+
+```ts
+const result = await db.$transaction(async (tx) => {
+  const user = await tx.user.create({
+    data: { email: "alice@example.com" },
+  });
+  await tx.post.create({
+    data: { title: "Hello", authorId: user.id },
+  });
+  return user;
+}, {
+  isolationLevel: "Serializable",    // "ReadCommitted" | "RepeatableRead" | "Serializable"
+  timeout: 5000,                     // ms
+});
+```
+
+#### Array style
+
+```ts
+const [user, posts] = await db.$transaction([
+  db.user.create({ data: { email: "alice@example.com" } }),
+  db.post.findMany({ where: { published: true } }),
+]);
+```
+
+---
+
+### Relation Loading Strategies
+
+| Strategy | Behavior | Best for |
+|----------|----------|----------|
+| `"query"` (default) | Parent query + batched `WHERE IN` relation queries. Sibling relations load in parallel. | Deep/nested includes |
+| `"join"` | Single query with `LEFT JOIN LATERAL` + JSON aggregation | Flat includes, fewer round-trips |
+
+Set globally:
+
+```ts
+const db = VibeClient({
+  adapter: bunAdapter(),
+  relationStrategy: "join",
+});
+```
+
+Or per-query:
+
+```ts
+const users = await db.user.findMany({
+  include: { posts: true },
+  relationStrategy: "join",
+});
+```
+
+---
+
+## Error Handling
+
+VibeORM provides structured error classes with codes and metadata:
+
+```
+VibeError (base)
+  VibeRequestError (deterministic / data errors)
+    VibeValidationError (Zod validation failures)
+  VibeTransientError (retryable infrastructure errors)
+```
+
+### Error codes
+
+| Class | Code | Meaning |
+|-------|------|---------|
+| `VibeRequestError` | `UNIQUE_CONSTRAINT` | Duplicate value on unique field |
+| | `FOREIGN_KEY_VIOLATION` | FK reference doesn't exist |
+| | `NOT_NULL_VIOLATION` | Required field is null |
+| | `CHECK_CONSTRAINT` | Check constraint failed |
+| | `NOT_FOUND` | `findUniqueOrThrow`/`update`/`delete` found no match |
+| | `VALIDATION_ERROR` | Zod schema validation failed |
+| `VibeTransientError` | `CONNECTION_ERROR` | Can't reach database |
+| | `DEADLOCK` | Transaction deadlock |
+| | `SERIALIZATION_FAILURE` | Serializable isolation conflict |
+| | `STATEMENT_TIMEOUT` | Query exceeded timeout |
+| | `TOO_MANY_CONNECTIONS` | Pool exhausted |
+
+### Example
+
+```ts
+import { VibeRequestError, VibeTransientError } from "@vibeorm/runtime";
+
+try {
+  await db.user.create({ data: { email: "taken@example.com" } });
+} catch (error) {
+  if (error instanceof VibeRequestError) {
+    if (error.code === "UNIQUE_CONSTRAINT") {
+      console.log(error.meta.constraint);  // "User_email_key"
+      console.log(error.meta.detail);      // 'Key (email)=(taken@...) already exists.'
+    }
+  }
+  if (error instanceof VibeTransientError) {
+    // error.retryable === true — safe to retry
+  }
+}
+```
+
+---
+
+## Validation
+
+The generated client includes Zod v4 schemas for every model. Enable runtime validation with the `validate` option:
+
+```ts
+const db = VibeClient({
+  adapter: bunAdapter(),
+  validate: true,
+});
+```
+
+| Value | Behavior |
+|-------|----------|
+| `false` (default) | No validation, zero overhead |
+| `"input"` | Validate `data` on create/update/upsert |
+| `"output"` | Validate every returned record |
+| `true` / `"all"` | Both input and output |
+
+---
+
+## Adapters
+
+### `@vibeorm/adapter-bun` (recommended)
+
+Uses Bun's built-in `bun:sql` PostgreSQL driver. Zero external dependencies.
+
+```ts
+import { bunAdapter } from "@vibeorm/adapter-bun";
+
+const db = VibeClient({
+  adapter: bunAdapter({
+    url: "postgres://...",  // Or reads DATABASE_URL
+  }),
+});
+```
+
+### `@vibeorm/adapter-pg`
+
+Uses `node-postgres` (`pg`). Install separately:
+
+```bash
+bun add @vibeorm/adapter-pg pg
+```
+
+```ts
+import { pgAdapter } from "@vibeorm/adapter-pg";
+
+const db = VibeClient({
+  adapter: pgAdapter({
+    connectionString: "postgres://...",
+  }),
+});
+```
+
+---
+
+## ID Generation
+
+Built-in cryptographically secure generators for schema-defined defaults:
+
+| Default | Format | Example |
+|---------|--------|---------|
+| `@default(uuid())` | UUID v4 | `550e8400-e29b-41d4-a716-446655440000` |
+| `@default(cuid())` | CUID2 (24 chars) | `clx1234abcde567890fghij` |
+| `@default(nanoid())` | NanoID (21 chars) | `V1StGXR8_Z5jdHi6B-myT` |
+| `@default(ulid())` | ULID (26 chars, sortable) | `01ARZ3NDEKTSV4RRFFQ69G5FAV` |
+
+Custom ID prefixes via Prisma doc comments:
+
+```prisma
+model User {
+  /// @vibeorm.idPrefix("usr_")
+  id String @id @default(cuid())
+}
+// Generates IDs like: "usr_clx1234abcde567890fghij"
+```
+
+Override globally:
+
+```ts
+const db = VibeClient({
+  adapter: bunAdapter(),
+  idGenerator: ({ model, field, defaultKind }) => {
+    return `${model.toLowerCase().slice(0, 3)}_${crypto.randomUUID()}`;
+  },
+});
+```
+
+---
+
+## Packages
+
+| Package | npm | Purpose |
+|---------|-----|---------|
+| `vibeorm` | [`vibeorm`](https://www.npmjs.com/package/vibeorm) | CLI |
+| `@vibeorm/runtime` | [`@vibeorm/runtime`](https://www.npmjs.com/package/@vibeorm/runtime) | Query engine and client runtime |
+| `@vibeorm/adapter-bun` | [`@vibeorm/adapter-bun`](https://www.npmjs.com/package/@vibeorm/adapter-bun) | `bun:sql` adapter |
+| `@vibeorm/adapter-pg` | [`@vibeorm/adapter-pg`](https://www.npmjs.com/package/@vibeorm/adapter-pg) | `node-postgres` adapter |
+| `@vibeorm/parser` | [`@vibeorm/parser`](https://www.npmjs.com/package/@vibeorm/parser) | Prisma schema parser |
+| `@vibeorm/generator` | [`@vibeorm/generator`](https://www.npmjs.com/package/@vibeorm/generator) | TypeScript client generator |
+| `@vibeorm/migrate` | [`@vibeorm/migrate`](https://www.npmjs.com/package/@vibeorm/migrate) | Migration and introspection toolkit |
+
 ## License
 
 [MIT](../../LICENSE)