neoorm 0.9.3 → 0.9.6

package/docs/cli.md

@@ -30,6 +30,7 @@ neoorm generate [options]
 ```
 
 Options:
+- `-n, --name <name>` — migration name (e.g. `--name add_users`). Only needed when a migration is created: prompts on a TTY at that point, errors in CI. Folders are `<timestamp>_<slug>` with the slug capped at 50 chars. No-change runs (client regeneration only) and pending-apply-only `dev` runs never prompt and succeed without `--name`.
 - `--accept-data-loss` — include destructive DDL changes (column drops, type changes)
 
 ## `neoorm migrate dev`
@@ -37,9 +38,26 @@ Options:
 Apply pending migrations, then generate a new migration if the schema changed. If a pending `CREATE TABLE` targets a relation that already exists, catch the live database up to `schema.ts` and record those files as applied instead of re-running the create.
 
 ```
-neoorm migrate dev
+neoorm migrate dev --name <name>
 ```
 
+- `-n, --name <name>` — same as `generate`: only needed when `dev` creates a migration, prompts on a TTY at that point, errors in CI. Applying pending migrations never requires `--name`. Not used by `deploy`, `status`, `reset`, or `down`.
+
+## `neoorm migrate diff`
+
+Preview the migration SQL `generate` / `migrate dev` would write, without writing anything.
+
+```
+neoorm migrate diff [--accept-data-loss] [--json]
+```
+
+Read-only: diffs `schema.ts` against `snapshot.json` only. No database connection, no files written, and `--name` is never needed (ignored if passed). Shows the exact statements that would go into `migration.sql`, so you can inspect a change before naming it.
+
+- `--accept-data-loss` — include destructive DDL in the preview (by default destructive changes are reported as blocked, same as `generate`)
+- `--json` — print `{ schemaChanged, sql, blocked, destructiveBlocked, warnings }` instead of human-readable text
+
+Exit code is `1` when destructive changes would block the migration (mirrors `generate`), `0` otherwise. For already-written but unapplied migrations, use `migrate status`.
+
 ## `neoorm migrate deploy`
 
 Apply all pending migrations. Throws `migration_drift` if a pending `CREATE TABLE` would hit an existing relation.
@@ -83,6 +101,19 @@ neoorm migrate reset --force [--skip-apply]
 
 PostgreSQL: the connecting role owns the recreated schema. `PUBLIC` is not granted.
 
+## `neoorm seed`
+
+Run a seed script against the database inside a single transaction. Any failure rolls the whole seed back.
+
+```
+neoorm seed [--env <name>] [--file <path>]
+```
+
+- `--env <name>` — run `seeds/<name>.ts` (next to `schema.ts`) instead of `seed.ts`
+- `--file <path>` — run a specific seed file (wins over `--env` and config)
+
+Resolution order: `--file` → config `seed.file` → `seeds/<env>.ts` → `seed.ts`. The client is compiled from `schema.ts`, so seeding works on a fresh checkout with no codegen. Write idempotent seeds (`upsert`, `findOrCreate`, `createMany` with `skipDuplicates`) — re-runs are by convention, there is no seed ledger. See [Seeding](seeding.md).
+
 ## `neoorm docs`
 
 Serve the NeoOrm documentation locally in your browser.

package/docs/configuration.md

@@ -33,6 +33,8 @@ CLI commands load `.env` from the project directory before evaluating this file,
 | `generate.zod` | `boolean` | `false` | Emit Select/Create/Update Zod schemas to `out/zod.ts`. See [Zod schemas](zod.md). |
 | `generate.typebox` | `boolean` | `false` | Emit Select/Create/Update TypeBox schemas to `out/typebox.ts`. See [TypeBox schemas](typebox.md). |
 | `generate.elysia` | `boolean` | `false` | Emit Select/Create/Update Elysia `t` schemas to `out/elysia.ts`. See [Elysia schemas](elysia.md). |
+| `seed.file` | `string` | unset | Default seed file, project-root relative. CLI `--file` overrides it. See [Seeding](seeding.md). |
+| `seed.env` | `string` | unset | Default environment: runs `seeds/<env>.ts` next to the schema. CLI `--env` overrides it. |
 
 ### Validation emit
 

package/docs/migrations.md

@@ -5,8 +5,9 @@
 | 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 (or record colliding CREATE TABLE files against the live schema), then generate a new one if `schema.ts` changed |
+| `neoorm generate [--name <name>]` | Emit manifest, typed client, models, includes, and migrations (`--name` only when a migration is created) |
+| `neoorm migrate dev [--name <name>]` | Apply pending migrations (or record colliding CREATE TABLE files against the live schema), then generate a new one if `schema.ts` changed (`--name` only when a new migration is created) |
+| `neoorm migrate diff [--accept-data-loss] [--json]` | Preview the SQL a new migration would contain — no files written, no `--name` needed |
 | `neoorm migrate deploy` | Apply pending migrations (throws `migration_drift` if a pending `CREATE TABLE` targets a relation that already exists) |
 | `neoorm migrate status` | List applied vs pending migrations |
 | `neoorm migrate down [--steps N]` | Roll back the last N applied migrations (default 1) |
@@ -22,13 +23,22 @@
 |---------|---------|
 | 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 created | New `migrations/<timestamp>_<name>/migration.sql` written |
 | Migration blocked | Destructive or manual changes prevented writing SQL |
 
+Migration names are slugified (`Add Users` → `add_users`, capped at 50 chars) and prefixed with a timestamp so folders sort in apply order. `--name` is only needed when a migration is created: the CLI prompts on a TTY at that point (after pending migrations are applied in `dev`) and errors in non-interactive runs. Runs with no schema changes (client regeneration only) and pending-apply-only `dev` runs succeed without `--name` and never prompt. Older `*_migration` folders still apply in order.
+
 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
+neoorm generate --name add_users --accept-data-loss
+```
+
+To inspect the SQL before naming the migration, preview it first (read-only, needs no `--name`):
+
+```bash
+neoorm migrate diff
+neoorm migrate diff --json
 ```
 
 ## Existing tables vs pending CREATE TABLE

package/docs/seeding.md

@@ -0,0 +1,67 @@
+# Seeding
+
+`neoorm seed` runs a seed script against the database inside a single transaction. Any failure rolls the whole seed back, so failed runs are safe to retry.
+
+```
+neoorm seed [--env <name>] [--file <path>]
+```
+
+## Seed files
+
+By convention the seed lives next to the schema as `seed.ts` and exports a `seed(db)` function. `db` is a transaction-scoped client, so every write in the file is atomic:
+
+```ts
+// seed.ts
+import type { TransactionClient } from "neoorm";
+import { schema } from "./schema.js";
+
+export async function seed(db: TransactionClient<typeof schema._tables>) {
+	await db.users.upsert({
+		where: { email: "admin@example.com" },
+		create: { email: "admin@example.com", name: "Admin" },
+		update: {},
+	});
+	await db.tags.createMany({
+		data: [
+			{ slug: "news", name: "News" },
+			{ slug: "guides", name: "Guides" },
+		],
+		skipDuplicates: true,
+	});
+}
+```
+
+Annotating with `TransactionClient<typeof schema._tables>` gives fully typed repositories — the same types as the generated client. A default-exported function works too, and `SeedContext` from `neoorm` is available for manifest-agnostic helpers.
+
+## Environments
+
+`--env <name>` runs `seeds/<name>.ts` instead of `seed.ts`:
+
+```bash
+neoorm seed --env dev
+neoorm seed --file ./seeds/manual.ts
+```
+
+`--file` wins over `--env`, and both win over config (see below).
+
+## Idempotency
+
+Seeds are re-run by convention — there is no seed ledger. Write seeds so running them twice is safe: `upsert`, `findOrCreate`, and `createMany({ skipDuplicates: true })` are the building blocks. The transaction guarantees all-or-nothing per run, not across runs.
+
+## Configuration
+
+Pin defaults in `neoorm.config.ts` (CLI flags override them):
+
+```ts
+export default defineConfig({
+	// ...
+	seed: { env: "dev", file: "./seeds/base.ts" },
+});
+```
+
+| Key | Type | Description |
+|-----|------|-------------|
+| `seed.file` | `string` | Default seed file, project-root relative |
+| `seed.env` | `string` | Default environment, runs `seeds/<env>.ts` next to the schema |
+
+See [Configuration](configuration.md) for the full config reference.