@ailnaf/zoddb 0.0.0-stage → 0.1.0

package/docs/api.md

@@ -0,0 +1,444 @@
+# zoddb API 契约
+
+> 本文件是公开语义的唯一契约来源。公开运行时 API 只有 graph 建模、`zoddb` 运行时和错误类型；低层 DDL/迁移/表构造器不对外。
+> 所有行为以本文件为准，`test/contract.test.ts` 与 `test/api-surface.test.ts` 钉住契约。
+
+## 入口
+
+```ts
+import {
+  defineSchema, node, edge, manyToMany, zoddb, relationGraph,
+  ZodDbError, UndefinedParamError, NoRowsError, RowValidationError, IncludeAliasError,
+  PgError, UniqueViolationError, NotNullViolationError, ForeignKeyViolationError,
+} from '@ailnaf/zoddb'
+import { authSchema, zodDbAdapter } from '@ailnaf/zoddb/better-auth'
+```
+
+公开运行时导出共 **15 个**（主入口）+ **2 个**（`zoddb/better-auth` 子路径）；完整清单见文末。
+
+## zod-first
+
+### `defineSchema({ nodes, edges })`
+
+一个对象完成表与关系建模：
+
+```ts
+import { z } from 'zod'
+import { defineSchema, edge, manyToMany, node } from '@ailnaf/zoddb'
+
+const schema = defineSchema({
+  nodes: {
+    users: node(z.object({
+      id: z.uuid(),
+      email: z.email(),
+      name: z.string().nullable(),
+      createdAt: z.date(),
+    }), { unique: [['email']] }),
+
+    posts: node(z.object({
+      id: z.uuid(),
+      authorId: z.uuid(),
+      title: z.string(),
+      published: z.boolean().default(false),
+      createdAt: z.date(),
+    })),
+
+    tags: node(z.object({
+      id: z.uuid(),
+      slug: z.string(),
+    }), { unique: [['slug']] }),
+
+    postTags: node(z.object({
+      postId: z.uuid(),
+      tagId: z.uuid(),
+    }), { primaryKey: ['postId', 'tagId'] }),
+  },
+  edges: {
+    users: {
+      posts: edge('posts', { from: 'id', to: 'authorId', kind: 'many' }),
+    },
+    posts: {
+      author: edge('users', { from: 'authorId', to: 'id', onDelete: 'cascade' }),
+      tags: manyToMany('tags', { through: 'postTags', from: 'postId', to: 'tagId' }),
+    },
+  },
+})
+```
+
+- `nodes` 的 key 默认是 schema key；`node` 第二参数可设置 `name`、`primaryKey`、`unique`、`indexes`、`checks`、`defaults`
+- 列名默认 camelCase → snake_case
+- `id: z.uuid()` 自动主键 + `gen_random_uuid()`；`createdAt` / `updatedAt` 自动 `now()`
+- `z.string()` / `z.email()` → text，`z.uuid()` → uuid，`z.int()` → int8，`z.date()` → timestamptz
+- 复杂类型用 `.meta({ sqlType })` 覆盖；无法推断的 zod 类型在构建期报错
+- 关系只写在 `edges[源表]`；不要在 node 里写 `relations`
+
+## 表定义
+
+### `node(shape, options?)`
+
+```ts
+const posts = node(z.object({
+  id: z.uuid(),
+  title: z.string(),
+  published: z.boolean().default(false),
+}), {
+  name: 'posts',
+  unique: [['title']],
+  indexes: [{ columns: ['published'] }],
+  checks: { posts_title_check: "length(title) > 0" },
+})
+```
+
+- `primaryKey: ['orgId', 'userId']` 生成复合主键
+- `.nullable()` 表示 DB 可空；`.default()` 表示插入可省略
+- 唯一/索引/CHECK 由 DDL 与迁移统一管理
+- 不要从公开入口导入 `table()`；它只是内部构造器
+
+### `edge(targetTable, options)` / `manyToMany(targetTable, options)`
+
+```ts
+edges: {
+  posts: {
+    author: edge('users', {
+      from: 'authorId',
+      reverse: 'posts',
+      onDelete: 'cascade',
+    }),
+    tags: manyToMany('tags', {
+      through: 'postTags',
+      from: 'postId',
+      to: 'tagId',
+    }),
+  },
+}
+```
+
+- `from` 是源表列；`to` 默认是目标表的 `id`
+- `reverse` 自动生成反向关系；反向关系只读，不重复生成 FK
+- `onDelete`: `cascade` / `restrict` / `set null` / `no action` / `set default`
+- M2M 必须显式声明 through 表；through 表用复合主键
+- 普通 graph 的 target 在编译期校验；auth graph 的动态表名在运行时校验
+- 关系深度最多 2；不支持 `every`、关系排序和关系聚合
+
+## 连接
+
+### `zoddb(options)`
+
+```ts
+import { zoddb } from '@ailnaf/zoddb'
+
+const db = zoddb({
+  schema,
+  url: process.env.DATABASE_URL!,
+})
+```
+
+- 返回按表命名的客户端：`db.users`、`db.posts`、`db.tags`
+- 每个客户端支持 `create`、`insert`、`insertMany`、`seed`、`update`、`delete`、`upsert`、`count`、`aggregate`、`groupBy`、`findMany`、`findOne`
+- `db.transaction(fn)` 提供同一个 graph 命名空间的事务句柄
+- `db.close()` 关闭连接
+- 也可以用 `connection` 传入已有 postgres.js 连接
+
+## 查询
+
+### `db.<table>.findMany(options?)` / `findOne(options?)`
+
+```ts
+const rows = await db.users.findMany({
+  where: {
+    email: { contains: '@acme', mode: 'insensitive' },
+    name: { isNull: false },
+  },
+  orderBy: [{ createdAt: 'desc' }, { id: 'asc' }],
+  limit: 20,
+  offset: 0,
+})
+
+const one = await db.users.findOne({ where: { email: 'ada@acme.dev' } })
+```
+
+操作符：
+
+| 操作符 | 语义 |
+|---|---|
+| `eq` / `ne` | 等值/不等；`null` → `is [not] null` |
+| `lt` / `lte` / `gt` / `gte` | 比较 |
+| `in` / `notIn` | 数组；空数组分别为 false / true |
+| `contains` / `startsWith` / `endsWith` | 自动转义 `% _ \` |
+| `mode: 'insensitive'` | 模糊匹配改用 `ilike` |
+| `AND` / `OR` / `NOT` | 组合条件 |
+
+- 直接写值等价于 `eq`；写 `null` 等价于 `is null`
+- `select` 只取指定列
+- `cursor` 做 keyset 分页，必须覆盖 `orderBy` 的所有列
+- `update` / `delete` 不接受关系过滤
+
+### `with` 关系读取
+
+```ts
+const users = await db.users.findMany({
+  orderBy: { createdAt: 'desc' },
+  with: {
+    posts: {
+      where: { published: true },
+      orderBy: { createdAt: 'desc' },
+      limit: 2,
+      with: { author: true },
+    },
+  },
+})
+```
+
+- 每个父行独立分页（窗口函数）；不是全局 LIMIT
+- 1 条主查询 + 每条关系 1 条批量查询，不做 N+1
+- 支持嵌套 `with`；关系名和返回类型从 schema 推导
+- `with` 的键拼错会在编译期报错
+
+## 关系
+
+### `some` / `none` 关系过滤
+
+```ts
+const authors = await db.users.findMany({
+  where: {
+    posts: {
+      some: {
+        published: true,
+        tags: { some: { slug: 'orm' } },
+      },
+    },
+  },
+})
+
+const quiet = await db.users.findMany({
+  where: { posts: { none: { published: true } } },
+})
+```
+
+- 编译为 `EXISTS` / `NOT EXISTS` 子查询
+- 支持 forward / reverse / M2M through
+- 最大关系深度 2；超深路径在类型和运行时都拒绝
+- 每层可混用列过滤、`AND` / `OR` / `NOT`
+
+### 多对多写入
+
+```ts
+const post = await db.posts.create({
+  authorId: user.id,
+  title: 'Why zoddb',
+  tags: {
+    connect: [{ id: tag.id }],
+  },
+})
+
+await db.posts.update(
+  { id: post.id },
+  { tags: { set: [{ id: otherTag.id }] } },
+)
+
+await db.posts.update(
+  { id: post.id },
+  { tags: { disconnect: [{ id: otherTag.id }] } },
+)
+```
+
+- `create` 的 M2M 关系只支持 `connect`
+- `update` 支持 `set` / `connect` / `disconnect`；同事务
+- `set` 替换全部 link；只改 link，不创建 target 行
+- `update` 的 where 必须命中恰好一个父行
+- through 额外业务列不支持
+
+## 写
+
+### create / update / delete / upsert
+
+```ts
+const ada = await db.users.create({
+  email: 'ada@acme.dev',
+  name: 'Ada',
+})
+
+const [updated] = await db.users.update(
+  { id: ada.id },
+  { name: 'Ada Lovelace' },
+)
+
+await db.users.upsert(
+  { email: 'ada@acme.dev', name: 'Ada' },
+  { conflict: ['email'], update: ['name'] },
+)
+
+await db.users.delete({ id: ada.id })
+```
+
+- 写入值先过 zod；`id` / `createdAt` / `updatedAt` 自动生成
+- 读出的行默认也过 zod；失败抛 `RowValidationError`
+- `update` / `delete` 条件不能为空
+- 更新会自动刷新 `updatedAt`（存在该列时）
+
+### 嵌套 create
+
+```ts
+const grace = await db.users.create({
+  email: 'grace@acme.dev',
+  name: 'Grace',
+  posts: {
+    create: [
+      { title: 'Type-safe SQL', published: true },
+      { title: 'Draft' },
+    ],
+  },
+})
+// grace.posts: Post[]
+```
+
+- 父行和子行同一事务
+- many 关系支持 `create` / `connect`；one 关系只支持 `connect`
+- 反向关系只读，不支持 nested create
+- 父键支持数据库默认值
+- 嵌套写只做一层
+
+## 事务
+
+```ts
+await db.transaction(async tx => {
+  const user = await tx.users.create({
+    email: 'tx@acme.dev',
+    name: 'TX',
+  })
+
+  await tx.posts.create({
+    authorId: user.id,
+    title: 'created in tx',
+  })
+})
+```
+
+- 回调抛错 → 回滚
+- `tx` 有同样的 graph 命名空间
+- 隔离级别通过 `{ isolation: 'serializable' }` 传入
+
+## 迁移
+
+迁移是 graph 驱动的 CLI 工作流；公开运行时不导出 DDL/迁移函数。
+
+```bash
+# CLI 自动读取项目根 .env；也可显式 export 或传 --url
+# DATABASE_URL=postgres://postgres:postgres@localhost:5432/zoddb
+
+npx zoddb generate --schema ./src/schema.ts --dir ./migrations --name init
+npx zoddb migrate --dir ./migrations
+npx zoddb status --schema ./src/schema.ts --dir ./migrations
+```
+
+- `generate` 只写文件，不执行；破坏性变更默认拒绝，`--allow-destructive` 显式放行
+- `migrate` 用 advisory lock 串行化，每个文件一个事务
+- 历史记录在 `_zoddb_migrations`；缺失、乱序、空文件、checksum 变化默认拒绝
+- `dev --once` 在本地生成并应用 additive 迁移
+
+### 只读 CI / 存量库
+
+```bash
+npx zoddb migrate --dir ./migrations --dry-run
+npx zoddb status --schema ./src/schema.ts --dir ./migrations --json
+npx zoddb baseline --schema ./src/schema.ts --dir ./migrations --through <file>
+```
+
+- `migrate --dry-run` 不加锁、不写历史、不建业务表；有待应用/异常时 exit 1
+- `status --json` 只输出 JSON，exit code 与文本模式一致
+- `baseline` 只标记 through 及之前的文件，不执行文件 SQL；默认要求 schema 与库一致
+- CI 应依赖 exit code/JSON，不要解析日志
+
+## Studio（本地只读 / 可选写模式）
+
+```bash
+npx zoddb studio
+# 或 npx zoddb studio --schema ./src/schema.ts --port 5555
+```
+
+- 由 CLI 读取 config/schema，绑定 `127.0.0.1`，输出带本地 token 的 URL
+- 不配置数据库 URL 时只展示 schema 表、列、PK、唯一列和关系边
+- 配置 `--url` / `DATABASE_URL` 时提供只读数据浏览：`limit/offset`、总数、排序、操作符过滤、`with` 关系预览、`some/none` 关系过滤、FK 跳转、M2M through；`select` 投影已由 `/api/rows` 支持
+- 默认不写数据；`--write` 开启受控写模式（需数据库 URL、本地 token、同源请求）
+- 写模式支持 create / update / delete / upsert / 嵌套 create / M2M 写入 / transaction；删除需二次确认
+- 配置迁移目录时，侧栏只读展示 `status --json` 的 applied / pending / missing / out-of-order / empty / tampered / drift 快照；不执行迁移
+- 迁移状态由 Studio 调用当前 CLI 的公开 `status --json` 获取，不导入内部迁移模块
+- Studio 的 schema 数据只来自公开 `relationGraph(schema)`；不导入内部 table/db/migrations，因此它也是公开接口的验证器
+- 不提供 SQL 控制台，也不在 Studio 中 apply 迁移
+
+## 关系图 IR
+
+```ts
+import { relationGraph } from '@ailnaf/zoddb'
+
+const graph = relationGraph(schema)
+// { nodes: [...], edges: [...] }
+```
+
+- 纯 JSON，包含自动反向关系和 M2M through 边
+- 不连接数据库、不执行 SQL
+- 适合可视化、审计和外部工具
+
+## 错误
+
+```ts
+import { UniqueViolationError } from '@ailnaf/zoddb'
+
+try {
+  await db.users.create({ email: 'ada@acme.dev', name: 'Ada' })
+} catch (e) {
+  if (e instanceof UniqueViolationError) {
+    console.log(e.table, e.columns)
+  }
+}
+```
+
+| 错误 | 场景 |
+|---|---|
+| `ZodDbError` | 库内错误基类 |
+| `UndefinedParamError` | SQL 参数含 `undefined` |
+| `NoRowsError` | `.one()` 无结果 |
+| `RowValidationError` | 读出的行校验失败 |
+| `IncludeAliasError` | include 别名不在结果里 |
+| `PgError` | 其它 PG 错误 |
+| `UniqueViolationError` | 23505 |
+| `NotNullViolationError` | 23502 |
+| `ForeignKeyViolationError` | 23503 |
+
+## better-auth
+
+```ts
+import { betterAuth } from 'better-auth'
+import { authSchema, zodDbAdapter } from '@ailnaf/zoddb/better-auth'
+import { defineSchema, zoddb } from '@ailnaf/zoddb'
+
+const auth = authSchema({ plugins: [] })
+const schema = defineSchema({ nodes: auth.nodes, edges: auth.edges })
+const db = zoddb({ schema, url: process.env.DATABASE_URL! })
+
+const authHandler = betterAuth({
+  database: zodDbAdapter(db, { schema }),
+  emailAndPassword: { enabled: true },
+})
+```
+
+- `authSchema` 生成 core 四表；插件表由 `plugins` 推导
+- `auth.nodes` / `auth.edges` 可直接展开进 `defineSchema`
+- adapter 按 schema 模型名映射；无需手写低层表
+
+## 边界
+
+- 低层 `table` / DDL / `defineDb` / `relations` / `pg` 不对外；它们是内部实现
+- 不提供 query builder、懒加载、任意深度递归、`every`、关系聚合全套
+- 不支持 down migration、shadow DB、零停机在线 DDL
+- 仅 Postgres
+
+## 导出清单
+
+主入口 runtime：
+
+`defineSchema` `node` `edge` `manyToMany` `zoddb` `relationGraph` `ZodDbError` `UndefinedParamError` `NoRowsError` `RowValidationError` `IncludeAliasError` `PgError` `UniqueViolationError` `NotNullViolationError` `ForeignKeyViolationError`
+
+子路径 `zoddb/better-auth`：
+
+`authSchema` `zodDbAdapter`

package/package.json

@@ -1,6 +1,72 @@
 {
   "name": "@ailnaf/zoddb",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./better-auth": {
+      "types": "./dist/better-auth-adapter.d.ts",
+      "import": "./dist/better-auth-adapter.js"
+    }
+  },
+  "scripts": {
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "check": "npm run typecheck && npm run test",
+    "bench": "vitest run --config vitest.bench.config.ts --reporter=verbose",
+    "build": "tsc -p tsconfig.build.json",
+    "prepack": "npm run build",
+    "verify:pack": "bash scripts/verify-pack.sh",
+    "verify:dogfood": "bash scripts/verify-dogfood.sh",
+    "prepublishOnly": "npm run check && npm run build"
+  },
+  "dependencies": {
+    "postgres": "^3.4.9",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.5",
+    "better-auth": "^1.7.10",
+    "expect-type": "^1.4.0",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.5"
+  },
+  "description": "zod-first PostgreSQL ORM with graph schemas, typed CRUD and production migrations",
+  "main": "./dist/index.js",
+  "keywords": [
+    "postgres",
+    "postgresql",
+    "orm",
+    "zod",
+    "typescript",
+    "sql",
+    "migrations",
+    "graph"
+  ],
+  "author": "zoddb contributors",
+  "license": "ISC",
+  "peerDependencies": {
+    "better-auth": "^1.7.0"
+  },
+  "peerDependenciesMeta": {
+    "better-auth": {
+      "optional": true
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "docs",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "bin": {
+    "zoddb": "./dist/cli.js"
+  },
+  "engines": {
+    "node": ">=22.18"
+  }
+}