neoorm 0.6.2 → 0.7.0

package/docs/schema.md

@@ -0,0 +1,265 @@
+# Schema DSL
+
+NeoOrm **0.6** 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
+
+`defineSchema` keys are TypeScript accessors. By default the SQL table name equals the accessor:
+
+```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(),
+  }),
+
+  postTags: table("post_tags", {
+    postId: fk("posts").primary(),
+    tagId: fk("tags").primary(),
+  }),
+});
+```
+
+- `table({ columns, extras? })` — SQL name is filled in from the accessor (`users` → `"users"`).
+- `table("sql_name", { columns }, extras?)` — override the SQL name (`postTags` → `"post_tags"`).
+
+Column field names use camelCase in TypeScript. By default SQL column names are snake_case (`createdAt` → `created_at`). See [column naming](#column-naming-strategy).
+
+## Column types
+
+| Builder | SQL type | TypeScript | Notes |
+|---------|----------|------------|-------|
+| `id()` | `TEXT` | `string` | App-generated `{prefix}_{uuid}` primary key |
+| `uuid()` | `UUID` | `string` | Defaults to UUID v7; `{ 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 |
+| `serial().primary()` | same | `number` | Integer PK |
+| `text()` | `TEXT` | `string \| null` | |
+| `bool()` | `BOOLEAN` | `boolean \| null` | |
+| `int()` | `INTEGER` | `number \| null` | |
+| `bigint()` | `BIGINT` | `bigint \| null` | Maps to `TEXT` on SQLite |
+| `timestamp()` | `TIMESTAMPTZ` | `Date \| null` | `.defaultNow()` / `.updatedAt()` on timestamp builders only |
+| `json()` / `jsonb()` | `JSON` / `JSONB` | `unknown \| null` | Generic: `jsonb<MyType>()` |
+| `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 | |
+| `citext()` | `CITEXT` | `string \| null` | Requires `citext` extension |
+
+All column builders support `.notNull()`, `.unique()`, `.default(value)`, `.primary()`, `.map(name)`, `.hidden()`, `.index()`, and `.check("sql expression")`.
+
+`.hidden()` marks a column as sensitive for API responses. Query results expose `.strip()` on each row to remove hidden fields before returning data.
+
+### Audit timestamps
+
+```ts
+...timestamps(),
+```
+
+`timestamps()` expands to `createdAt` and `updatedAt` — both `notNull`, `defaultNow`, with `updatedAt` auto-updated by the ORM on writes. Or define columns manually:
+
+```ts
+createdAt: timestamp().notNull().defaultNow(),
+updatedAt: timestamp().notNull().defaultNow().updatedAt(),
+```
+
+## Foreign keys
+
+`fk()` targets are **schema accessors**, never SQL table names.
+
+| Target | Example | Resolves to |
+|--------|---------|-------------|
+| accessor | `fk("users")` | target table PK |
+| accessor + column | `fk("users.id")` | that column |
+| hoisted table | `fk(users)` | target PK |
+| hoisted column | `fk(users.id)` | that column |
+
+```ts
+posts: table({
+  id: id(),
+  authorId: fk("users")
+    .notNull()
+    .index()
+    .onDelete("restrict"),
+}),
+```
+
+Relation names are inferred — no `.inverse()` needed on the happy path:
+
+- `authorId` → `author` on `posts` (`with: { author: true }`)
+- inverse on `users` → `posts` (`with: { posts: true }`)
+
+Fluent modifiers (no options bag):
+
+| Method | Effect |
+|--------|--------|
+| `.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 |
+| `.notNull()` | `NOT NULL` |
+| `.unique()` | `UNIQUE` — unique FKs infer a **singular** inverse (`profiles.userId` → `users.profile`) |
+| `.primary()` | part of composite PK |
+| `.index()` | single-column index |
+
+Default inference when `.as()` / `.inverse()` are omitted:
+
+- **this table:** `authorId` → `author` (strip trailing `Id`)
+- **target table (to-many):** source accessor (`posts.authorId` → `users.posts`)
+- **target table (unique to-one):** singular of source accessor (`profiles.userId` → `users.profile`)
+
+### Composite primary keys with FKs
+
+```ts
+postTags: table("post_tags", {
+  postId: fk("posts").primary(),
+  tagId: fk("tags").primary(),
+}),
+```
+
+### Self-relations
+
+```ts
+comments: table({
+  id: id(),
+  parentId: fk("comments").as("parent").inverse("children"),
+  body: text().notNull(),
+}),
+```
+
+### Hoisted table references
+
+```ts
+const users = table({ id: uuid().primary() });
+
+export const schema = defineSchema({
+  users,
+  posts: table({
+    authorId: fk(users).notNull().index(),
+  }),
+});
+```
+
+## Column checks
+
+`.check("price >= 0")` stores a SQL expression on the column (combined with enum `check` mode when both apply):
+
+```ts
+price: decimal({ precision: 10, scale: 2 }).notNull().check("price >= 0"),
+```
+
+## Indexes and composite keys
+
+Single-column indexes: `.index()` on a column.
+
+Composite constraints use an **array** extras callback:
+
+```ts
+posts: table(
+  {
+    id: id(),
+    authorId: fk("users").notNull(),
+    title: text().notNull(),
+    views: int().notNull().default(0),
+  },
+  (t) => [unique(t.authorId, t.title), index(t.views)],
+),
+```
+
+Helpers: `unique(...cols)`, `index(...cols)`, `primaryKey(...cols)`.
+
+### Partial indexes
+
+```ts
+(t) => [index(t.title).where({ published: true })],
+```
+
+Equality map of column refs → values; compiled to `WHERE "published" = true` (or `= 1` on SQLite).
+
+## Many-to-many
+
+Declare a virtual column on the source table:
+
+```ts
+posts: table({
+  id: id(),
+  title: text().notNull(),
+  tags: many("tags"),
+}),
+tags: table({ id: id(), slug: text().notNull().unique() }),
+```
+
+- `"tags"` is the **target accessor**.
+- Junction table is auto-generated when `through` is omitted.
+- SQL name: alpha-sorted SQL table names joined with `_` (e.g. `posts_tags` — no leading `_`).
+- Accessor equals that identifier (`posts_tags`).
+
+Reuse an existing junction by **accessor**:
+
+```ts
+posts: table({
+  tags: many("tags", {
+    through: "postTags",
+    leftKey: "postId",
+    rightKey: "tagId",
+  }),
+}),
+postTags: table("post_tags", {
+  postId: fk("posts").primary(),
+  tagId: fk("tags").primary(),
+}),
+```
+
+`as` / `inverse` override relation names on source and target tables.
+
+Virtual M2M columns are relations only — they appear in `with`, relation filters, and relation writes, not in scalar `select`/`where`/`create` data.
+
+## Column naming strategy
+
+```ts
+export const schema = defineSchema(
+  {
+    users: table({ emailAddress: text().notNull() }), // SQL: email_address
+    legacyUsers: table(
+      "legacy_users",
+      { emailAddress: text().notNull() },
+      { columnNaming: "camelCase" },
+    ),
+  },
+  { columnNaming: "snakeCase" },
+);
+```
+
+## Custom SQL column names (`.map()`)
+
+```ts
+emailAddress: text().notNull().map("email"),
+authorId: fk("users").as("author").map("author_ref"),
+```
+
+## Enum columns
+
+```ts
+status: enumType(["draft", "published", "archived"])
+  .notNull()
+  .default("draft"),
+```
+
+`datasource.enum` in config: `check` (default), `union`, or `native` (PostgreSQL only).
+
+## PostgreSQL extensions
+
+```ts
+export const schema = defineSchema(
+  { /* tables */ },
+  { extensions: ["uuid-ossp", "pg_trgm"] },
+);
+```
+
+Column type plugins still register required extensions automatically.
+
+## SQLite type mapping
+
+Same DSL; see [SQLite](sqlite.md) for storage types and limitations.

package/docs/sqlite.md

@@ -0,0 +1,105 @@
+# SQLite
+
+SQLite is a first-class dialect for local development, testing, and single-file deployments. Everything in the schema DSL, codegen, migrations, and query client works against SQLite with no extra database server.
+
+## Requirements
+
+No SQLite package is required — NeoOrm uses the driver bundled with your runtime:
+
+| Runtime | Driver |
+|---------|--------|
+| Node.js 22.5+ | built-in `node:sqlite` (`DatabaseSync`) |
+| Bun | `bun:sqlite` |
+| Anything else | pass your own `db` instance (see [Custom driver](#custom-driver)) |
+
+If none is available, creating a client throws: `No SQLite driver available. Provide a db instance, or run on Bun or Node.js 22.5+`.
+
+## Configuration
+
+Set `provider: "sqlite"` and point `url` at a file path or `:memory:`:
+
+```ts
+// neoorm.config.ts
+import { defineConfig } from "neoorm";
+
+export default defineConfig({
+  schema: "./schema.ts",
+  out: "./neoorm",
+  datasource: {
+    provider: "sqlite",
+    url: "./dev.db", // or ":memory:"
+  },
+});
+```
+
+`datasource.schema` and `datasource.enum: "native"` are PostgreSQL-only and ignored/unsupported on SQLite. Enums always use the `check` (or `union`) TEXT storage mode.
+
+## Runtime client
+
+```ts
+import { createNeoOrmClient } from "neoorm";
+import { manifest } from "./neoorm/manifest.js";
+
+const db = createNeoOrmClient(manifest, {
+  provider: "sqlite",
+  databasePath: "./dev.db",
+});
+```
+
+Use `databasePath: ":memory:"` for an in-memory database (one connection, no persistence).
+
+### Custom driver
+
+Pass any object implementing `prepare(sql)`, `exec(sql)`, and `close()` — the `node:sqlite` and `bun:sqlite` APIs both match. Useful for sandboxed runtimes or existing database handles:
+
+```ts
+import { DatabaseSync } from "node:sqlite";
+import { createNeoOrmClient } from "neoorm";
+import { manifest } from "./neoorm/manifest.js";
+
+const database = new DatabaseSync("./dev.db");
+const db = createNeoOrmClient(manifest, { db: database });
+```
+
+## CLI
+
+The full CLI works against SQLite:
+
+```bash
+bunx neoorm migrate deploy
+bunx neoorm db push
+bunx neoorm db pull
+bunx neoorm migrate status
+bunx neoorm migrate reset --force
+```
+
+- The migration ledger table is `_neoorm_migrations` (`id INTEGER PRIMARY KEY AUTOINCREMENT`).
+- `migrate reset` drops all non-`sqlite_` tables (there is no schema concept).
+- `db pull` introspects `sqlite_master` back into a schema file.
+
+## Type mapping
+
+| Schema builder | SQLite storage |
+|----------------|----------------|
+| `id`, `text`, `uuid`, `json`, `jsonb`, `decimal`, `textArray`, `intArray`, `citext`, `enumType` | `TEXT` |
+| `int`, `serial` | `INTEGER` |
+| `bigint` | `TEXT` |
+| `serial().primary()` | `INTEGER PRIMARY KEY AUTOINCREMENT` |
+| `bool` | `BOOLEAN` (stored as 0/1) |
+| `timestamp` | `TIMESTAMPTZ` (stored as ISO-8601 text) |
+| `bytea` | `BLOB` |
+| `fk` | the target column's type (default `TEXT`) |
+
+`defaultNow()` compiles to `CURRENT_TIMESTAMP`. Structural table changes that SQLite cannot do in place (column type changes, FK changes) are applied via a table-rebuild strategy: create `__neoorm_<table>_new`, copy rows, drop the old table, rename.
+
+## Differences from PostgreSQL
+
+| Feature | PostgreSQL | SQLite |
+|---------|-----------|--------|
+| `distinct` (`DISTINCT ON`) | supported | throws `distinct is not supported on SQLite` |
+| `datasource.schema` | multi-schema | not applicable |
+| `enum: "native"` | `CREATE TYPE ... AS ENUM` | not applicable (TEXT + CHECK) |
+| transaction options (`readOnly`, `isolationLevel`) | full | outer `BEGIN` only; nested transactions use savepoints |
+| JSON operators | `@>`, `?`, path ops | implemented with `json_each` / `json_object` |
+
+Everything else — relations, nested writes, cursor pagination, aggregates, `groupBy`, upsert, `findOrCreate`, savepoint-based nested transactions — behaves identically.

package/docs/transactions.md

@@ -0,0 +1,54 @@
+# Transactions
+
+## Interactive callback
+
+```ts
+await db.$transaction(async (tx) => {
+  const user = await tx.users.create({ data: { email: "a@b.com" } });
+  await tx.posts.create({
+    data: { title: "Hello", authorId: user.id },
+  });
+});
+```
+
+## Batch steps
+
+Sequential, one transaction:
+
+```ts
+const [user, post] = await db.$transaction([
+  (tx) => tx.users.create({ data: { email: "a@b.com" } }),
+  (tx) => tx.posts.create({ data: { title: "Hello" } }),
+]);
+```
+
+## Options
+
+```ts
+await db.$transaction(fn, {
+  isolationLevel: "Serializable", // ReadUncommitted | ReadCommitted | RepeatableRead | Serializable
+  readOnly: true,
+});
+```
+
+## Nested transactions
+
+Uses database savepoints on the same connection. A nested failure rolls back only that block; the outer transaction can continue.
+
+```ts
+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. `readOnly` and `isolationLevel` apply only to the outermost `BEGIN`.
+
+On SQLite, nested transactions use `SAVEPOINT`/`RELEASE`/`ROLLBACK TO SAVEPOINT`; `readOnly` and `isolationLevel` are rejected on nested transactions (mapped to `BEGIN`/`BEGIN IMMEDIATE`/`BEGIN DEFERRED` on the outer transaction).

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "neoorm",
-	"version": "0.6.2",
+	"version": "0.7.0",
 	"description": "TypeScript-first PostgreSQL and SQLite ORM with schema DSL, codegen, and typed relations",
 	"license": "MIT",
 	"repository": {
@@ -58,6 +58,7 @@
 	},
 	"files": [
 		"dist",
+		"docs",
 		"README.md",
 		"LICENSE"
 	],
@@ -90,6 +91,7 @@
 	},
 	"dependencies": {
 		"commander": "^15.0.0",
+		"marked": "^15.0.12",
 		"pg": "^8.22.0",
 		"tsx": "^4.23.0"
 	}