neoorm 0.6.1 → 0.6.3

package/docs/plugins.md

@@ -0,0 +1,47 @@
+# Plugins
+
+## Built-in `id()` and `timestamps()`
+
+```ts
+import { defineSchema, id, table, timestamps, uuid } from "neoorm/schema";
+
+export const schema = defineSchema({
+  users: table({
+    id: uuid().primary(),
+    ...timestamps(),
+  }),
+  posts: table({
+    id: id(), // TEXT PK with {prefix}_{uuid}
+    title: text().notNull(),
+  }),
+});
+```
+
+## PostGIS
+
+```ts
+import "neoorm/plugins/postgis";
+import { geometry, point } from "neoorm/plugins/postgis";
+
+places: table({
+  id: uuid().primary(),
+  location: geometry({ subtype: "Point", srid: 4326 }).notNull(),
+  boundary: point({ srid: 4326 }),
+}),
+```
+
+Spatial `where` operators: `intersects`, `within`, `dWithin`.
+
+## Citext
+
+```ts
+import { citext, table } from "neoorm/schema";
+
+users: table({
+  email: citext().notNull().unique(),
+}),
+```
+
+## Custom plugins
+
+See the plugin registry source for `ColumnTypePlugin` and `NeoOrmPlugin` interfaces.

package/docs/queries.md

@@ -0,0 +1,465 @@
+# Queries
+
+## Find
+
+```ts
+// By ID (scalar primary key — pass a string)
+const user = await db.users.findById(id);
+
+// By composite primary key — pass an object with all PK columns
+const item = await db.items.findById({ tenantId: "t1", itemCode: "c1" });
+
+// First match (null if not found)
+const user = await db.users.findFirst({ where: { email: "a@b.com" } });
+
+// All matching
+const users = await db.users.findMany({
+  where: { published: true },
+  take: 20,
+  skip: 40,
+});
+
+// Unique constraint lookup
+const user = await db.users.findUnique({ where: { slug: "hello" } });
+```
+
+## Create
+
+```ts
+const user = await db.users.create({ data: { email: "a@b.com" } });
+
+// Bulk insert (returns count)
+const count = await db.users.createMany({
+  data: [{ email: "a@b.com" }, { email: "b@b.com" }],
+});
+
+// Skip unique / primary-key conflicts (`ON CONFLICT DO NOTHING`).
+// Does not ignore CHECK or foreign-key violations.
+const skipped = await db.users.createMany({
+  data: [{ email: "a@b.com" }, { email: "a@b.com" }],
+  skipDuplicates: true,
+});
+
+// Bulk insert with returned rows (serial IDs, UUIDs, defaults materialized)
+const users = await db.users.createManyAndReturn({
+  data: [{ email: "a@b.com" }, { email: "b@b.com" }],
+  skipDuplicates: true,
+});
+```
+
+## Update
+
+```ts
+// Single record
+const user = await db.users.update({
+  where: { id: userId },
+  data: { email: "new@b.com" },
+});
+
+// By ID (scalar PK — string; composite PK — object)
+const user = await db.users.updateById(id, { data: { name: "New" } });
+const item = await db.items.updateById(
+  { tenantId: "t1", itemCode: "c1" },
+  { data: { name: "Updated" } },
+);
+
+// Multiple records
+const count = await db.users.updateMany({
+  where: { email: { contains: "@old" } },
+  data: { status: "archived" },
+});
+
+const updated = await db.users.updateManyAndReturn({
+  where: { email: { contains: "@old" } },
+  data: { status: "archived" },
+});
+```
+
+Numeric columns (`int`, `serial`, `decimal`, `bigint`) also accept `{ increment }`, `{ decrement }`, `{ multiply }`, and `{ set }`. These compile to `col = col ±/* $n` so concurrent updates do not clobber each other. `{ set: value }` is the same assignment as a plain value. `NULL + 1` stays SQL NULL.
+
+```ts
+await db.posts.update({
+  where: { id: postId },
+  data: { views: { increment: 1 } },
+});
+
+await db.posts.updateMany({
+  where: { published: true },
+  data: { views: { multiply: 2 } },
+});
+```
+
+## Delete
+
+```ts
+// Returns {} on success, null if no row matched
+await db.users.delete({ where: { id: userId } });
+
+// Pass returnDeleted: true to get the deleted row back
+const deleted = await db.users.delete({
+  where: { id: userId },
+  returnDeleted: true,
+});
+
+// Scalar PK — pass a string
+await db.users.deleteById(userId);
+
+// Composite PK — pass an object
+await db.items.deleteById({ tenantId: "t1", itemCode: "c1" });
+
+const count = await db.users.deleteMany({
+  where: { email: { contains: "@spam" } },
+});
+
+const deletedRows = await db.users.deleteManyAndReturn({
+  where: { email: { contains: "@spam" } },
+});
+```
+
+## Upsert
+
+```ts
+await db.users.upsert({
+  where: { email: "a@b.com" },
+  create: { email: "a@b.com", name: "A" },
+  update: { name: "A" },
+});
+```
+
+## Find or create
+
+Atomically insert a row or return an existing one when a unique constraint matches. Unlike `upsert`, existing rows are never updated.
+
+`where` must identify a unique constraint (same rules as `findUnique` and `upsert`).
+
+```ts
+const { record, created } = await db.tags.findOrCreate({
+  where: { slug: "orm" },
+  create: { slug: "orm", name: "ORM" },
+});
+// created: true if a new row was inserted, false if an existing row was returned
+```
+
+## Where clauses
+
+### Column filters
+
+Equality shorthand and explicit operators:
+
+```ts
+await db.posts.findMany({ where: { published: true } });
+
+await db.posts.findFirst({
+  where: {
+    title: { contains: "ORM" },
+    views: { gte: 100 },
+    id: { in: ["post_1", "post_2"] },
+  },
+});
+```
+
+| Type | Operators |
+|------|-----------|
+| String | `equals`, `contains`, `startsWith`, `endsWith`, `search`, `in`, `notIn`, `mode` |
+| Numeric / Date | `equals`, `gt`, `gte`, `lt`, `lte`, `in`, `notIn` |
+| JSON | `jsonContains`, `hasKey`, `hasAnyKeys`, `hasAllKeys`, `path` |
+| All nullable | `isNull`, `isNotNull` |
+
+`contains`, `startsWith`, and `endsWith` compile to `LIKE`. Pass sibling `mode: "insensitive"` for case-folding (`ILIKE` on Postgres, `LOWER(col) LIKE LOWER($n)` on SQLite). SQLite `LIKE` is ASCII case-insensitive even in default mode.
+
+`search` is POSIX regex (`~`, or `~*` with `mode: "insensitive"`). It is PostgreSQL-only; SQLite throws.
+
+```ts
+await db.posts.findMany({
+  where: { title: { contains: "orm", mode: "insensitive" } },
+});
+
+await db.posts.findMany({
+  where: { title: { search: "^Neo", mode: "insensitive" } },
+});
+```
+
+### Logical combinators
+
+```ts
+await db.users.findMany({
+  where: {
+    OR: [
+      { email: { contains: "@example.com" } },
+      { email: { contains: "@test.com" } },
+    ],
+    NOT: { name: { isNull: true } },
+    createdAt: { gte: new Date("2025-01-01") },
+  },
+});
+```
+
+### Relation filters
+
+```ts
+// users who have at least one published post
+await db.users.findMany({
+  where: { posts: { some: { published: true } } },
+});
+
+// posts whose author has a verified email
+await db.posts.findMany({
+  where: { author: { email: { contains: "@" } } },
+});
+
+// posts tagged "orm" (many-to-many via junction table)
+await db.posts.findMany({
+  where: { tags: { some: { slug: "orm" } } },
+});
+```
+
+| Pattern | Use for |
+|---------|---------|
+| `authorId: "user_1"` | Filter by FK column value |
+| `author: { email: "a@b.c" }` | Filter by related record (to-one) |
+| `posts: { some: { ... } }` | At least one related record matches (to-many) |
+| `posts: { every: { ... } }` | All related records match (to-many) |
+| `posts: { none: { ... } }` | No related records match (to-many) |
+
+Relation filters compile to SQL `EXISTS` subqueries, so they work with `findMany`, `count`, `updateMany`, and `deleteMany` without duplicate rows.
+
+### JSON and decimal filters
+
+```ts
+// 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" } },
+});
+```
+
+### `distinct`
+
+PostgreSQL `DISTINCT ON` — `orderBy` must lead with the same columns:
+
+```ts
+await db.users.findMany({
+  distinct: ["email"],
+  orderBy: { email: "asc" },
+});
+```
+
+Not supported on SQLite (`DISTINCT ON` is PostgreSQL-only) — it throws `distinct is not supported on SQLite`. Use `groupBy({ by: [...] })` or a raw `db.sql` query instead.
+
+## Eager loading with `with`
+
+Relations are eagerly loaded in `findMany`, `findFirst`, and `findById` via the `with` option.
+
+### Strategy
+
+NeoORM uses a relation-loading planner that picks the fewest round-trips per `with` tree:
+
+- **LEFT JOIN** — to-one relations where the parent table owns the foreign key are resolved in the main query. No additional round-trips.
+- **Correlated `json_agg` subquery** — inverse has-many relations (and simple linear nested chains) are embedded in the main `SELECT` as correlated subqueries. Multiple top-level relations can be inlined in the same query alongside JOINs.
+- **Inline `COUNT` subquery** — simple `_count` on has-many relations is embedded in the main `SELECT`.
+- **Batch query** — many-to-many, nested `with` on to-one, sibling-heavy trees, and other complex shapes fall back to batched `WHERE IN (...)` queries (one per relation level). Sibling batch queries at the same level run in parallel.
+
+Typical query counts:
+
+- `with: { author: true }` → **1** query (JOIN)
+- `with: { posts: true }` → **1** query (`json_agg` subquery)
+- `with: { author: true, comments: true }` → **1** query (JOIN + `json_agg`)
+- `with: { posts: { with: { comments: { with: { author: true } } } } }` on a linear chain → **1** query (nested `json_agg`)
+- M2M or sibling nested relations → **1 + batch levels** (parallel per level)
+
+```ts
+// Single query — author via LEFT JOIN
+const posts = await db.posts.findMany({ with: { author: true } });
+
+// Last 5 published comments per post
+const posts = await db.posts.findMany({
+  with: {
+    comments: {
+      where: { published: true },
+      orderBy: { createdAt: "desc" },
+      take: 5,
+    },
+  },
+});
+
+// Single query — author via JOIN, comments via correlated json_agg
+const posts = await db.posts.findMany({
+  with: { author: true, comments: { with: { author: true } } },
+});
+```
+
+To-one includes with `where` load as a batch query: the relation is the matching row, or `null`.
+
+### Selective return types
+
+Root `select` and `omit` project the parent row. Relation shapes still come from `with` (including nested `select`). `select` and `omit` cannot be used together.
+
+```ts
+const users = await db.users.findMany({
+  select: { id: true, email: true },
+  with: { posts: { select: { title: true } } },
+});
+// { id, email, posts: Array<{ title }> }
+
+const publicUsers = await db.users.findMany({
+  omit: { createdAt: true, updatedAt: true },
+});
+```
+
+Nested relation `select` also narrows the TypeScript return type:
+
+```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
+```
+
+### API responses (`strip`)
+
+Use query `omit` when you do not want a column fetched from the database. Use `strip` when you need the full row internally (for example login) but want a safe object for the response.
+
+Mark sensitive columns in the schema with `.hidden()`:
+
+```ts
+password: text().notNull().hidden(),
+```
+
+Every row returned from queries includes a non-enumerable `.strip()` method:
+
+```ts
+const user = await db.users.findById(id);
+if (!user) return null;
+return user.strip();
+// hidden fields removed; nested `with` relations stripped too
+
+const users = await db.users.findMany();
+return users.map((user) => user.strip());
+
+return user.strip({ refreshToken: true }); // hidden + extra column keys
+```
+
+`strip()` returns a plain object (no `.strip` method) suitable for JSON responses. `null` and `undefined` pass through unchanged when using the underlying strip helper directly.
+
+## Cursor pagination
+
+For feeds, infinite scroll, and large tables, use `paginate` instead of `take`/`skip`. It uses **keyset pagination** on your `orderBy` columns plus the table primary key as a stable tiebreaker.
+
+```ts
+let cursor: { createdAt: Date; 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 */ }
+
+  if (!page.hasMore) break;
+  cursor = page.nextCursor;
+}
+```
+
+- `orderBy` is required; scalar `id` is appended automatically when omitted.
+- `take` is the page size; `hasMore` / `hasPrevious` use a `take + 1` probe row (plus whether `after` / `before` was passed).
+- `after` is a typed cursor (`nextCursor` from the previous page). `before` walks the other way (`prevCursor`).
+- `after` and `before` can be combined as exclusive window bounds; pass both on every windowed call.
+- For HTTP APIs, encode cursors with `encodeCursor` / `decodeCursor` from `neoorm`.
+- On feed tables, add a composite index on the sort columns.
+
+Walk backward (e.g. “load newer” on a descending feed):
+
+```ts
+const newer = await db.posts.paginate({
+  where: { published: true },
+  orderBy: { createdAt: "desc" },
+  take: 20,
+  before: page.prevCursor,
+});
+```
+
+## Aggregates
+
+### Relation counts in `with`
+
+```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: { _all: true, authorId: true },
+  _avg: { views: true },
+});
+// { _count: { _all: number, authorId: number }, _avg: { views: number | null } }
+```
+
+`_count: true` is still `COUNT(*)` and returns `_count: number`. A field map uses `COUNT(col)` (nulls are skipped) — not `DISTINCT`.
+
+Single-table grouped stats use `groupBy()`. Cross-table dashboards still use `db.sql` or `sqlBuilder`.
+
+### `groupBy()`
+
+```ts
+const byAuthor = await db.posts.groupBy({
+  by: ["authorId"],
+  where: { published: true },
+  _count: { _all: true, authorId: true },
+  _avg: { views: true },
+  having: { _count: { _all: { gte: 5 }, authorId: { gt: 0 } } },
+  orderBy: { _count: { _all: "desc" } },
+  take: 10,
+});
+// { authorId: string, _count: { _all: number, authorId: number }, _avg: { views: number | null } }[]
+```
+
+Star `_count: true` still works with `having: { _count: { gte: 5 } }` and `orderBy: { _count: "desc" }`.
+
+`where` filters rows before grouping. `having` filters groups (aggregates only). `by` alone lists distinct groups — useful on SQLite where `distinct` is not available.
+
+## Count
+
+```ts
+const total = await db.users.count({ where: { active: true } });
+const uniqueEmails = await db.users.count({ distinct: "email" });
+const fieldCounts = await db.users.count({
+  select: { _all: true, email: true },
+});
+// { _all: number, email: number }
+
+const taken = await db.users.exists({ where: { email: "a@b.com" } });
+```
+
+`count()` returns a number unless `select` is set. `distinct` is `COUNT(DISTINCT col)` on one column and cannot be combined with `select`. Field `select` / `_count` maps are non-null `COUNT(col)`, not distinct.
+
+`exists()` runs `SELECT 1 … LIMIT 1` and returns a boolean. Use `count()` when you need the actual number of matches.

package/docs/relations.md

@@ -0,0 +1,75 @@
+# Relation writes
+
+`create` and `update` accept nested relation writes alongside scalar fields. Relation-only updates are supported (no scalar `SET` required).
+
+## Supported operations
+
+| 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` |
+
+## Examples
+
+### To-one on update
+
+```ts
+await db.posts.update({
+  where: { id: postId },
+  data: { author: { connect: { id: userId } } },
+});
+```
+
+### Nested create on one-to-many
+
+```ts
+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
+    },
+  },
+});
+```
+
+### Many-to-many on create or update
+
+```ts
+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 }],
+    },
+  },
+});
+```
+
+### Relation writes in updateMany
+
+`updateMany` applies scalar `SET` once, then nested writes per matched parent:
+
+```ts
+await db.posts.updateMany({
+  where: { published: true },
+  data: {
+    status: "archived",
+    tags: { connect: [{ id: tagId }] },
+  },
+});
+```
+
+## Operation order
+
+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.