neoorm 0.6.2 → 0.7.0

package/docs/examples.md

@@ -0,0 +1,498 @@
+# Examples
+
+Copy-paste patterns for common NeoOrm tasks. The full runnable blog demo lives in [`examples/blog/`](https://github.com/xmreur/neoorm/tree/main/examples/blog) (`schema.ts` + `queries.example.ts`). PostGIS sample: [`examples/postgis/`](https://github.com/xmreur/neoorm/tree/main/examples/postgis).
+
+Run `neoorm docs` to browse all documentation locally.
+
+## Blog schema
+
+A small CMS-style schema used throughout these examples:
+
+```ts
+import {
+  bool,
+  defineSchema,
+  enumType,
+  fk,
+  id,
+  int,
+  jsonb,
+  many,
+  table,
+  text,
+  timestamps,
+  uuid,
+} from "neoorm/schema";
+
+export const schema = defineSchema({
+  users: table({
+    id: uuid().primary(),
+    email: text().notNull().unique(),
+    name: text(),
+    password: text().notNull().hidden(),
+    ...timestamps(),
+  }),
+
+  profiles: table({
+    id: id(),
+    userId: fk("users").notNull().unique().onDelete("cascade"),
+    bio: text(),
+  }),
+
+  posts: table({
+    id: id(),
+    authorId: fk("users").notNull().index().onDelete("restrict"),
+    title: text().notNull(),
+    body: text().notNull(),
+    published: bool().notNull().default(false),
+    views: int().notNull().default(0),
+    status: enumType(["draft", "published", "archived"]).notNull().default("draft"),
+    metadata: jsonb<Record<string, unknown>>(),
+    ...timestamps(),
+    tags: many("tags"),
+  }),
+
+  comments: table({
+    id: id(),
+    postId: fk("posts").notNull().onDelete("cascade"),
+    authorId: fk("users").notNull(),
+    body: text().notNull(),
+    createdAt: timestamps().createdAt,
+  }),
+
+  tags: table({
+    id: id(),
+    slug: text().notNull().unique(),
+    name: text().notNull(),
+  }),
+});
+```
+
+Generate the client, then import it:
+
+```ts
+import { db } from "./neoorm/client.js";
+```
+
+## CRUD basics
+
+```ts
+// Create
+const user = await db.users.create({
+  data: { email: "alice@example.com", name: "Alice" },
+});
+
+// Create and return full row
+const post = await db.posts.create({
+  data: {
+    title: "Hello",
+    body: "World",
+    authorId: user.id,
+  },
+  returnCreated: true,
+});
+
+// Find by primary key
+const found = await db.users.findById(user.id);
+
+// Find first match
+const draft = await db.posts.findFirst({
+  where: { published: false },
+  orderBy: { createdAt: "desc" },
+});
+
+// Update
+await db.users.updateById(user.id, {
+  data: { name: "Alice Smith" },
+});
+
+// Update many
+await db.posts.updateMany({
+  where: { published: false },
+  data: { views: 0 },
+});
+
+// Delete
+await db.posts.delete({ where: { id: post.id } });
+await db.users.deleteById(user.id);
+```
+
+## Nested reads (`with`)
+
+```ts
+const user = await db.users.findById("user_1", {
+  with: {
+    profile: true,
+    posts: {
+      where: { published: true },
+      orderBy: { createdAt: "desc" },
+      take: 10,
+      with: {
+        comments: {
+          orderBy: { createdAt: "desc" },
+          take: 5,
+          with: { author: { select: { id: true, name: true } } },
+        },
+        tags: true,
+      },
+    },
+  },
+});
+```
+
+Select only specific columns:
+
+```ts
+const users = await db.users.findMany({
+  select: { id: true, email: true },
+  with: {
+    posts: { select: { title: true, published: true } },
+  },
+});
+```
+
+Omit columns at query time (still fetched from DB):
+
+```ts
+const user = await db.users.findById("user_1", {
+  omit: { createdAt: true, updatedAt: true },
+});
+```
+
+## Where filters
+
+```ts
+// Equality and operators
+const posts = await db.posts.findMany({
+  where: {
+    published: true,
+    views: { gte: 100 },
+    title: { contains: "ORM" },
+  },
+});
+
+// Case-insensitive search
+const hits = await db.posts.findMany({
+  where: { title: { contains: "orm", mode: "insensitive" } },
+});
+
+// Logical combinators
+const filtered = await db.posts.findMany({
+  where: {
+    OR: [
+      { status: "published" },
+      { AND: [{ published: true }, { views: { gt: 50 } }] },
+    ],
+  },
+});
+
+// Filter through relations
+const authors = await db.users.findMany({
+  where: {
+    posts: { some: { published: true, tags: { some: { slug: "typescript" } } } },
+  },
+});
+
+// JSONB containment
+const featured = await db.posts.findMany({
+  where: {
+    metadata: {
+      jsonContains: { featured: true, category: "engineering" },
+    },
+  },
+});
+
+// Exists / count helpers
+const taken = await db.users.exists({ where: { email: "alice@example.com" } });
+const total = await db.posts.count({ where: { published: true } });
+```
+
+## Relation writes
+
+Create with nested relations in one call:
+
+```ts
+const post = await db.posts.create({
+  data: {
+    title: "NeoORM",
+    body: "Typed relations and JSONB.",
+    published: true,
+    status: "published",
+    author: { connect: { id: "user_1" } },
+    tags: {
+      connectOrCreate: [
+        {
+          where: { slug: "orm" },
+          create: { slug: "orm", name: "ORM" },
+        },
+      ],
+    },
+  },
+  with: { author: true, tags: true },
+});
+```
+
+Update relations on an existing row:
+
+```ts
+await db.posts.update({
+  where: { id: post.id },
+  data: {
+    views: { increment: 1 },
+    comments: {
+      create: [
+        {
+          body: "Great post!",
+          author: { connect: { id: "user_1" } },
+        },
+      ],
+    },
+    tags: { set: [{ id: "tag_1" }, { id: "tag_2" }] },
+  },
+});
+```
+
+`connect`, `disconnect`, `set`, `create`, and `delete` work on to-one, one-to-many, and many-to-many relations. See [Relation writes](relations.md).
+
+## Pagination
+
+Offset/limit:
+
+```ts
+const page = await db.posts.findMany({
+  where: { published: true },
+  orderBy: { createdAt: "desc" },
+  take: 20,
+  skip: 40,
+});
+```
+
+Keyset (cursor) pagination for feeds:
+
+```ts
+let cursor: { createdAt: Date; id: string } | null = null;
+
+const page = await db.posts.paginate({
+  where: { published: true },
+  orderBy: { createdAt: "desc" },
+  take: 20,
+  ...(cursor ? { after: cursor } : {}),
+});
+
+cursor = page.nextCursor;
+// page.items, page.hasMore, page.hasPrevious
+```
+
+## Aggregations
+
+```ts
+const byStatus = await db.posts.groupBy({
+  by: ["status"],
+  _count: true,
+  orderBy: { _count: "desc" },
+});
+
+const stats = await db.posts.aggregate({
+  _count: true,
+  _avg: { views: true },
+  where: { published: true },
+});
+```
+
+## Transactions
+
+Batch steps (single transaction):
+
+```ts
+const [author, post] = await db.$transaction([
+  (tx) =>
+    tx.users.create({
+      data: { email: "author@example.com", name: "Author" },
+    }),
+  (tx) =>
+    tx.posts.create({
+      data: {
+        title: "Transactional post",
+        body: "...",
+        author: { connect: { id: "user_1" } },
+      },
+    }),
+]);
+```
+
+Interactive callback with rollback:
+
+```ts
+await db.$transaction(async (tx) => {
+  const user = await tx.users.create({
+    data: { email: "x@y.z", name: "Temp" },
+  });
+  await tx.posts.create({
+    data: {
+      title: "Draft",
+      body: "...",
+      author: { connect: { id: user.id } },
+    },
+  });
+  // throw to roll back everything
+});
+```
+
+Nested savepoints:
+
+```ts
+await db.$transaction(async (tx) => {
+  await tx.users.create({ data: { email: "outer@x.y", name: "Outer" } });
+
+  await tx.$transaction(async (nested) => {
+    await nested.users.create({ data: { email: "inner@x.y", name: "Inner" } });
+    throw new Error("roll back inner only");
+  }).catch(() => undefined);
+});
+```
+
+## Raw SQL
+
+Use `db.sql` when you need full SQL control. Table names in tagged templates use your schema accessors:
+
+```ts
+const rows = await db.sql`
+  SELECT u.id, u.email, count(p.id) AS post_count
+  FROM users u
+  LEFT JOIN posts p ON p.author_id = u.id
+  GROUP BY u.id, u.email
+  ORDER BY post_count DESC
+`;
+```
+
+## API responses (`strip`)
+
+Fetch sensitive fields for auth, then strip before sending JSON:
+
+```ts
+const user = await db.users.findFirst({
+  where: { email: input.email },
+});
+
+if (!user || !verifyPassword(input.password, user.password)) {
+  throw new Error("Invalid credentials");
+}
+
+return user.strip(); // removes .hidden() columns (e.g. password)
+return user.strip({ email: true }); // hidden + extra fields
+```
+
+`.strip()` is non-enumerable and returns a plain object. See [Queries → API responses](queries.md#api-responses-strip).
+
+## Explicit junction table (many-to-many)
+
+Auto-junction works for most cases. For a custom junction table:
+
+```ts
+posts: table({
+  id: id(),
+  tags: many("tags", {
+    through: "postTags",
+    leftKey: "postId",
+    rightKey: "tagId",
+  }),
+}),
+postTags: table("post_tags", {
+  postId: fk("posts").primary(),
+  tagId: fk("tags").primary(),
+}),
+```
+
+`through` is the **accessor** (`postTags`), not the SQL name (`post_tags`).
+
+## SQLite
+
+Same schema and client API — point config at a file:
+
+```ts
+// neoorm.config.ts
+datasource: {
+  provider: "sqlite",
+  url: "./dev.db",
+},
+```
+
+```ts
+import { createNeoOrmClient } from "neoorm";
+import { manifest } from "./neoorm/manifest.js";
+
+const db = createNeoOrmClient(manifest, {
+  provider: "sqlite",
+  databasePath: "./dev.db",
+});
+```
+
+See [SQLite](sqlite.md) for type mapping and limitations.
+
+## PostGIS
+
+```ts
+import "neoorm/plugins/postgis";
+import { geometry, point } from "neoorm/plugins/postgis";
+
+places: table({
+  id: id(),
+  name: text().notNull(),
+  location: geometry({ subtype: "Point", srid: 4326 }).notNull(),
+}),
+```
+
+```ts
+const nearby = await db.places.findMany({
+  where: {
+    location: {
+      dWithin: {
+        geometry: { type: "Point", coordinates: [-122.4, 37.8] },
+        distance: 1000,
+      },
+    },
+  },
+});
+```
+
+See [Plugins](plugins.md).
+
+## Schema extras
+
+Composite unique constraint and partial index:
+
+```ts
+import { fk, id, index, table, text, unique } from "neoorm/schema";
+
+posts: table(
+  {
+    id: id(),
+    authorId: fk("users").notNull(),
+    title: text().notNull(),
+    published: bool().notNull().default(false),
+  },
+  (t) => [
+    unique(t.authorId, t.title),
+    index(t.title).where({ published: true }),
+  ],
+),
+```
+
+SQL name override when accessor differs from table name:
+
+```ts
+postTags: table("post_tags", {
+  postId: fk("posts").primary(),
+  tagId: fk("tags").primary(),
+}),
+```
+
+## Next steps
+
+| Topic | Doc |
+|-------|-----|
+| Schema DSL | [schema.md](schema.md) |
+| Queries | [queries.md](queries.md) |
+| Relation writes | [relations.md](relations.md) |
+| Migrations | [migrations.md](migrations.md) |
+| CLI | [cli.md](cli.md) |

package/docs/getting-started.md

@@ -0,0 +1,122 @@
+# Getting started
+
+## Scaffold a new project
+
+```bash
+bunx neoorm init
+```
+
+This creates `neoorm.config.ts`, `schema.ts`, and `.env.example`. Run `bunx neoorm migrate dev` after setting your database URL.
+
+```bash
+cp .env.example .env
+# edit DATABASE_URL in .env
+bunx neoorm migrate dev
+```
+
+Query:
+
+```ts
+import { db } from "./neoorm/client.js";
+
+const user = await db.users.findById(userId, {
+  with: { posts: { where: { published: true }, orderBy: { createdAt: "desc" }, take: 10 } },
+});
+```
+
+## Manual setup
+
+### 1. Define a schema
+
+```ts
+// schema.ts
+import {
+  defineSchema,
+  fk,
+  id,
+  table,
+  text,
+  timestamps,
+  uuid,
+} from "neoorm/schema";
+
+export const schema = defineSchema({
+  users: table({
+    id: uuid().primary(),
+    email: text().notNull().unique(),
+    ...timestamps(),
+  }),
+
+  posts: table({
+    id: id(),
+    authorId: fk("users").notNull().index(),
+    title: text().notNull(),
+  }),
+});
+```
+
+- `table({ ... })` uses the accessor as the SQL table name.
+- `fk("users")` references the **users accessor** (not a SQL string).
+- Relation names are inferred (`authorId` → `author` on posts, `posts` on users).
+
+See [Schema DSL](schema.md).
+
+Browse [Examples](examples.md) for copy-paste patterns (CRUD, relations, pagination, transactions, `strip`, and more).
+
+### 2. Configure NeoOrm
+
+```ts
+// neoorm.config.ts
+import { defineConfig } from "neoorm";
+
+export default defineConfig({
+  schema: "./schema.ts",
+  out: "./neoorm",
+  datasource: {
+    provider: "postgresql",
+    url: process.env.DATABASE_URL!,
+    schema: "public",
+    enum: "check",
+  },
+});
+```
+
+### 3. Generate the client
+
+```bash
+bunx neoorm generate
+```
+
+## SQLite
+
+Set `provider: "sqlite"` and `url` to a file path or `:memory:`:
+
+```ts
+datasource: {
+  provider: "sqlite",
+  url: "./dev.db",
+},
+```
+
+```ts
+import { createNeoOrmClient } from "neoorm";
+import { manifest } from "./neoorm/manifest.js";
+
+const db = createNeoOrmClient(manifest, {
+  provider: "sqlite",
+  databasePath: "./dev.db",
+});
+```
+
+See [SQLite](sqlite.md).
+
+## Tenant-specific schemas
+
+```ts
+const tenantDb = createNeoOrmClient(manifest, {
+  connectionString: process.env.DATABASE_URL!,
+  schema: "tenant_acme",
+});
+```
+
+Raw `db.sql` / `db.execute` are not rewritten — qualify tenant schema yourself in raw SQL.

package/docs/migrations.md

@@ -0,0 +1,67 @@
+# Migrations
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `neoorm init` | Scaffold `neoorm.config.ts`, `schema.ts`, `.env.example` only (no codegen or migrations; run `neoorm migrate dev` after) |
+| `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 the `public` schema (PostgreSQL) or all tables (SQLite) 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 outcomes
+
+`neoorm generate` always refreshes generated TypeScript files. 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 needed |
+| Migration created | New `migrations/<timestamp>/migration.sql` written |
+| Migration blocked | Destructive or manual changes prevented writing SQL |
+
+When migration is blocked, 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:
+
+```bash
+neoorm generate --accept-data-loss
+```
+
+## Status
+
+```bash
+neoorm migrate status
+```
+
+Shows applied migrations (with timestamps), pending folders on disk, and warnings for drift (applied in DB but missing on disk).
+
+## Reset
+
+```bash
+neoorm migrate reset --force
+```
+
+Drops the `public` schema (PostgreSQL) or all tables (SQLite) and re-applies all migrations from disk. Requires `--force`. Use `--skip-apply` to only drop without re-applying.
+
+## Rollback
+
+`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.
+
+```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`.
+
+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.