@undefineds.co/drizzle-solid 0.3.0 → 0.3.2

package/CHANGELOG-DRAFT.md

@@ -392,7 +392,7 @@ npm test
 - [CSS Notifications](./docs/guides/css-notifications.md) - 实时通知支持（79KB）
 
 ### 开发指南
-- [测试策略](./TESTING_STRATEGY.md) - 测试方法和覆盖
+- [测试指南](./docs/guides/testing.md) - 当前测试方法、分层和验证要求
 - [快速开始](./docs/quick-start-local.md) - 本地开发入门
 - [文档索引](./docs/README.md) - 完整文档导航
 

package/README.md

@@ -1,102 +1,81 @@
 # drizzle-solid
 
-`drizzle-solid` is a Drizzle-aligned data layer for application-owned data in Solid Pods.
+Chinese version: [`README.zh-CN.md`](README.zh-CN.md)
 
-这次变化的重点不是强迫你把构造函数名字从 `drizzle()` 换成别的东西，而是把语义讲清楚：
+`drizzle-solid` stores application-owned data in Solid Pods with typed schemas and a Drizzle-aligned developer experience.
 
-- `table` 更接近 **resource layout / collection definition**
-- `link` 字段更接近 **RDF link / IRI link**
-- 实体最终身份更接近 **IRI / @id**，而不只是本地主键
-- 读取和写入不再默认共享 SQL 式语义
+Use it when you want:
 
-## Scope
+- TypeScript schemas for Pod data
+- explicit Pod layout through `base` and `subjectTemplate`
+- a choice between a Solid-first API (`pod()`) and a Drizzle-shaped API (`drizzle()`)
+- exact entity reads and writes by IRI or locator
+- SPARQL-backed reads when your backend exposes query capability
 
-Current v1 solves one problem well:
+## What it is good at
 
-- persist application-owned data into Solid Pods with typed schemas
-- keep Pod layout explicit through `base` and `subjectTemplate`
-- make full IRIs part of the public API instead of hiding them behind local-only IDs
-- give Drizzle users a migration-friendly surface without pretending Solid is a SQL database
-- support adjacent Solid flows such as discovery, notifications, and federation where they fit the Pod model
+- application-owned data in your Pod or a user Pod
+- typed CRUD over known resource layouts
+- gradual migration from `drizzle-orm`
+- Pod-native concepts such as IRIs, documents, links, discovery, notifications, and federation
 
-Not in v1:
+## What it is not trying to be
 
-- full SQL/database feature parity
-- raw SQL as the primary abstraction
-- hiding Pod boundaries, permissions, or network behavior
-- implicit scan-based `updateMany/deleteMany` on backends that do not support set-based mutation
-- universal querying over arbitrary open-world RDF as the main goal
-
-## Constructor Choice
-
-仓库文档与 examples 默认先用 `pod(session, config?)` 讲主线语义：
-
-- `pod(session, config?)`
-- `drizzle(session, config?)`
-
-建议这样理解：
-
-- `pod()` 是语义优先的正式入口，方便把 API 组织成 `collection()` / `entity()` / `bind()`
-- `drizzle()` 是同一运行时上的 Drizzle-aligned 入口，适合迁移或保留 builder/query 代码形状
-- 重要的不是“入口名”，而是下面这些语义：`base`、`subjectTemplate`、`IRI`、exact-target mutation
-
-## Public Surface
-
-当前公开表面可以分成两层：
-
-### Semantic-first surface
-
-- `pod(session, config?)`
-- `client.bind(schema, options)`
-- `client.collection(table)`
-- `client.entity(table, iri)`
-- `client.sparql(query)`
-
-### Drizzle-aligned surface
-
-- `drizzle(session, config?)`
-- `podTable(name, columns, config)`
-- `solidSchema(...)`
-- `select / insert / update / delete`
-- `db.query.*` read facade
+- a general-purpose RDF exploration toolkit
+- full SQL/database parity across every Solid backend
+- a library that hides Pod boundaries, permissions, or network costs
+- a raw SQL-first abstraction
 
 ## Install
 
 ```bash
 yarn add @undefineds.co/drizzle-solid drizzle-orm
-# optional, when your app wants the default SPARQL client engine
+# optional: install when your app wants the built-in SPARQL engine
 yarn add @comunica/query-sparql-solid
 ```
 
 ```bash
 npm install @undefineds.co/drizzle-solid drizzle-orm
+# optional: install when your app wants the built-in SPARQL engine
 npm install @comunica/query-sparql-solid
 ```
 
 `@comunica/query-sparql-solid` is an optional peer dependency.
 
-Install it in the consuming app when you need built-in SPARQL query execution, LDP-backed query fallback, or direct SPARQL workflows.
+Current support stance:
 
-Current public compatibility stance:
+- supported: `@comunica/query-sparql-solid` `4.x`
+- not in the current supported matrix: `3.x`
 
-- officially supported: `@comunica/query-sparql-solid` `4.x`
-- not currently in the supported matrix: `3.x`
+If another in-process runtime already ships Comunica, inject that engine instead of installing a second copy.
 
-If another in-process runtime already carries Comunica (for example `xpod`), inject that engine instead of forcing a second copy. See `docs/api/README.md` and `docs/guides/installation.md`.
+## Choose your API style
 
-## Quick start
+### `pod(session)`
+
+Use this for new code when you want Solid concepts to be explicit in the API:
 
-仓库里的主线 quick start 默认使用 `pod(session)`，因为它会把 `collection()` / `entity()` / `bind()` 语义直接写在代码里。
+- `collection(table)`
+- `entity(table, iri)`
+- `bind(schema, options)`
+- `sparql(query)`
 
-如果你已有大量 Drizzle 风格代码，`drizzle(session)` 仍然是正式可用入口。
+### `drizzle(session)`
+
+Use this when you are migrating from `drizzle-orm` or want to keep builder-shaped code:
+
+- `select / insert / update / delete`
+- `db.query.<table>`
+- `findByLocator / findByIri`
+- `updateByLocator / updateByIri`
+- `deleteByLocator / deleteByIri`
+
+Both styles use the same runtime. The difference is API shape, not storage behavior.
+
+## Quick start
 
 ```ts
-import {
-  pod,
-  podTable,
-  string,
-  datetime,
-} from '@undefineds.co/drizzle-solid';
+import { pod, podTable, string, datetime } from '@undefineds.co/drizzle-solid';
 
 const posts = podTable('posts', {
   id: string('id').primaryKey(),
@@ -112,85 +91,104 @@ const posts = podTable('posts', {
 const client = pod(session);
 await client.init(posts);
 
-const postsCollection = client.collection(posts);
-
-const created = await postsCollection.create({
+const created = await client.collection(posts).create({
   id: 'post-1',
   title: 'Hello Solid',
   content: 'Stored as RDF in a Pod document.',
   createdAt: new Date(),
 });
 
-const first = await postsCollection.first({
-  where: { id: 'post-1' },
-});
+if (!created) {
+  throw new Error('Create failed');
+}
 
-const postIri = created?.['@id'] ?? postsCollection.iriFor({
-  id: 'post-1',
-  title: 'Hello Solid',
-  content: 'Stored as RDF in a Pod document.',
-  createdAt: new Date(),
-});
+const post = client.entity(posts, created['@id']);
 
-const post = client.entity(posts, postIri);
+console.log(await post.get());
 await post.update({ title: 'Updated title' });
 await post.delete();
 ```
 
-> 如果你保持 `drizzle(session)` 作为入口，语义并不会变：`base`、`subjectTemplate`、`IRI`、精确写目标这些约束仍然完全成立。
+## Drizzle-style exact operations
 
-## Reusable schema + runtime binding
+```ts
+import { drizzle, podTable, string } from '@undefineds.co/drizzle-solid';
 
-Use `solidSchema(...)` when you want to separate the reusable data shape from where that data lives in a Pod.
+const posts = podTable('posts', {
+  id: string('id').primaryKey(),
+  title: string('title').predicate('http://schema.org/headline'),
+}, {
+  base: 'https://alice.example/data/posts/',
+  subjectTemplate: '{id}.ttl',
+  type: 'http://schema.org/CreativeWork',
+});
 
-如果你使用 `pod()` façade：
+const db = drizzle(session);
+await db.init(posts);
 
-```ts
-const client = pod(session);
-const profileTable = client.bind(profileSchema, {
-  base: 'https://alice.example/profile/card',
+await db.insert(posts).values({
+  id: 'post-1',
+  title: 'Hello Solid',
 });
-```
 
-如果你保持 `drizzle()` 入口：
+const row = await db.findByLocator(posts, { id: 'post-1' });
 
-```ts
-const db = drizzle(session);
-const profileTable = db.createTable(profileSchema, {
-  base: 'https://alice.example/profile/card',
+await db.updateByLocator(posts, { id: 'post-1' }, {
+  title: 'Updated title',
 });
+
+await db.deleteByLocator(posts, { id: 'post-1' });
 ```
 
-## Identity and placement
+## How Pod layout works
+
+Every model describes both shape and placement.
+
+- `base` defines where documents live
+- `subjectTemplate` defines how business fields map to an IRI
+- `type` is the primary persisted `rdf:type`
+
+Common `subjectTemplate` patterns:
 
-`subjectTemplate` defines how application identity maps onto Pod resources.
+- `#{id}` — many entities in one document
+- `{id}.ttl` — one document per entity
+- `{id}.ttl#it` — one document per entity with a stable fragment
+- `{chatId}/messages.ttl#{id}` — partitioned layout with multiple locator variables
 
-Common patterns:
+If your template uses multiple variables, exact lookup requires either:
 
-- `#{id}`: many entities inside one document
-- `{id}.ttl`: one document per entity
-- `{id}.ttl#it`: one document per entity with stable in-document fragment
-- `{chatId}/messages.ttl#{id}`: multi-variable layouts and partitioned resources
+- the full IRI, or
+- a complete locator with every required variable
 
-这不是命名细节，而是持久化语义本身。
+## Collection reads vs exact entity operations
 
-## Exact-target mutation semantics
+This is the most important runtime rule.
 
-Reads and writes do not intentionally behave the same way.
+### Collection reads
 
-- list / filter reads can stay collection-oriented
-- writes should prefer exact-target semantics
-- incomplete `where(...)` information should not silently degrade into scan + mutate
-- if a subject can only be resolved by multiple template variables, mutation should use an explicit IRI or provide all required variables
+Use collection reads when you want a list or filtered subset:
 
-所以最重要的变化不是“要不要换成 `pod()`”，而是：
+- `client.collection(table).list(...)`
+- `db.select().from(table)...`
+- `db.query.<table>.findMany(...)`
+
+### Exact entity operations
+
+Use exact-target helpers when you mean one concrete entity:
+
+- `client.entity(table, iri)`
+- `db.findByIri(table, iri)`
+- `db.findByLocator(table, locator)`
+- `db.updateByIri(...)`
+- `db.updateByLocator(...)`
+- `db.deleteByIri(...)`
+- `db.deleteByLocator(...)`
 
-- 什么时候你只是在做集合读取
-- 什么时候你已经需要一个确定的实体目标
+Do not rely on `where({ id: ... })` or `where(eq(table.id, ...))` as an exact-target shortcut.
 
-## Server support
+## SPARQL support and backend behavior
 
-### Capability matrix
+`drizzle-solid` works across different Solid runtimes, but capabilities differ.
 
 | Capability | Community Solid Server | xpod |
 | --- | --- | --- |
@@ -198,15 +196,19 @@ Reads and writes do not intentionally behave the same way.
 | Document notifications | ✅ | ✅ |
 | Drizzle-style read facade | ✅ | ✅ |
 | SPARQL pushdown | ⚠️ Limited / often client-assisted | ✅ Better in-process support |
-| Filter / aggregation pushdown | ❌ Mostly fallback execution | ✅ Better server-side support |
+| Filter / aggregation pushdown | ❌ Mostly client-side execution | ✅ Better server-side support |
 | Federated queries | ⚠️ Client-side federation | ⚠️ Client-side federation |
 | In-process local runtime | ⚠️ External setup | ✅ via `@undefineds.co/xpod` |
 
-If `xpod` already ships its own Comunica stack, `drizzle-solid` can reuse that copy instead of requiring another app-level install.
+Practical rule:
 
-## Verified examples
+- if you have a SPARQL endpoint or sidecar, use it for collection queries
+- if you only have plain LDP document access, exact-target reads and writes still work
+- plain-LDP document mode does not silently widen exact operations into scans
 
-The canonical examples in `examples/` are part of the real integration verification flow:
+## Examples
+
+The canonical examples in `examples/` are part of the integration verification flow:
 
 - `examples/01-quick-start.ts`
 - `examples/02-relational-query.ts`
@@ -219,42 +221,24 @@ The canonical examples in `examples/` are part of the real integration verificat
 - `examples/08-schema-inheritance.ts`
 - `examples/09-multi-variable-templates.ts`
 
-See `examples/manifest.json` and `tests/integration/css/examples-verification.test.ts`.
-
-## Migration
+## Documentation
 
-If you already know `drizzle-orm`, start here:
+Start here:
 
+- `docs/guides/installation.md`
+- `docs/api/README.md`
 - `docs/guides/migrating-from-drizzle-orm.md`
-
-那份指南重点解释的是：
-
-- `table/row` → `resource/document/entity/IRI`
-- `link` / relation fields → RDF link / IRI link
-- `where`-style mutation → exact-target mutation
-- `toSQL()` / raw SQL 主心智 → `toSPARQL()` / SPARQL 主心智
-
-而不是要求你第一步先改掉构造函数名。
-
-## Documentation map
-
-- `docs/api/README.md` — current public API and constructor positioning
-- `docs/guides/installation.md` — installation and SPARQL engine setup
-- `docs/guides/migrating-from-drizzle-orm.md` — migration guide for Drizzle users
-- `examples/README.md` — curated runnable examples
-- `docs/guides/data-discovery.md` — discovery workflows
-- `docs/guides/notifications.md` — notification flows
-- `docs/xpod-features.md` — xpod runtime notes
-- `ACTION-PLAN.md` — parity and implementation plan
+- `docs/guides/multi-variable-templates.md`
+- `docs/guides/notifications.md`
+- `docs/guides/data-discovery.md`
 
 ## Contributing
 
 Before pushing:
 
 ```bash
-yarn build
-yarn lint
-SOLID_ENABLE_REAL_TESTS=true SOLID_SERIAL_TESTS=true yarn vitest --run --silent
+yarn quality
+SOLID_ENABLE_REAL_TESTS=true SOLID_SERIAL_TESTS=true yarn vitest --run tests/integration/css
 ```
 
 Examples must remain runnable and verified.

package/README.zh-CN.md

@@ -0,0 +1,254 @@
+# drizzle-solid
+
+English version: [`README.md`](README.md)
+
+`drizzle-solid` 用类型化 schema 和 Drizzle 对齐的开发体验，把应用自有数据存进 Solid Pod。
+
+适合在你需要下面这些能力时使用：
+
+- 用 TypeScript schema 描述 Pod 数据
+- 用 `base` 和 `subjectTemplate` 明确声明数据布局
+- 在 `pod()` 和 `drizzle()` 两种 API 风格之间选择
+- 通过 IRI 或 locator 精确读写单个实体
+- 在后端提供查询能力时走 SPARQL 读取
+
+## 它擅长什么
+
+- 应用自有数据存储在你的 Pod 或用户 Pod 中
+- 对已知资源布局做类型化 CRUD
+- 从 `drizzle-orm` 逐步迁移，而不假装 Pod 就是 SQL 表
+- 使用 IRI、文档、链接、发现、通知、联邦等 Pod 原生概念
+
+## 它不打算做什么
+
+- 通用 RDF 图探索工具
+- 所有 Solid 后端上的完整 SQL / 数据库能力对齐
+- 隐藏 Pod 边界、权限或网络成本
+- raw SQL 优先的抽象层
+
+## 安装
+
+```bash
+yarn add @undefineds.co/drizzle-solid drizzle-orm
+# 可选：当你的应用需要内置 SPARQL 引擎时再安装
+yarn add @comunica/query-sparql-solid
+```
+
+```bash
+npm install @undefineds.co/drizzle-solid drizzle-orm
+# 可选：当你的应用需要内置 SPARQL 引擎时再安装
+npm install @comunica/query-sparql-solid
+```
+
+`@comunica/query-sparql-solid` 是可选 peer dependency。
+
+当前支持范围：
+
+- 支持：`@comunica/query-sparql-solid` `4.x`
+- 当前不在支持矩阵中：`3.x`
+
+如果宿主运行时已经自带 Comunica，就注入那一份，不要再装第二份。
+
+## 选择 API 风格
+
+### `pod(session)`
+
+适合新代码，或者你希望 API 直接体现 Solid 语义：
+
+- `collection(table)`
+- `entity(table, iri)`
+- `bind(schema, options)`
+- `sparql(query)`
+
+### `drizzle(session)`
+
+适合从 `drizzle-orm` 迁移，或者你想保留 builder 形状：
+
+- `select / insert / update / delete`
+- `db.query.<table>`
+- `findByLocator / findByIri`
+- `updateByLocator / updateByIri`
+- `deleteByLocator / deleteByIri`
+
+两者底层是同一个运行时。区别是 API 组织方式，不是存储行为。
+
+## 快速开始
+
+```ts
+import { pod, podTable, string, datetime } from '@undefineds.co/drizzle-solid';
+
+const posts = podTable('posts', {
+  id: string('id').primaryKey(),
+  title: string('title').predicate('http://schema.org/headline'),
+  content: string('content').predicate('http://schema.org/text'),
+  createdAt: datetime('createdAt').predicate('http://schema.org/dateCreated'),
+}, {
+  base: 'https://alice.example/data/posts/',
+  subjectTemplate: '{id}.ttl',
+  type: 'http://schema.org/CreativeWork',
+});
+
+const client = pod(session);
+await client.init(posts);
+
+const created = await client.collection(posts).create({
+  id: 'post-1',
+  title: 'Hello Solid',
+  content: 'Stored as RDF in a Pod document.',
+  createdAt: new Date(),
+});
+
+if (!created) {
+  throw new Error('Create failed');
+}
+
+const post = client.entity(posts, created['@id']);
+
+console.log(await post.get());
+await post.update({ title: 'Updated title' });
+await post.delete();
+```
+
+## Drizzle 风格的精确操作
+
+```ts
+import { drizzle, podTable, string } from '@undefineds.co/drizzle-solid';
+
+const posts = podTable('posts', {
+  id: string('id').primaryKey(),
+  title: string('title').predicate('http://schema.org/headline'),
+}, {
+  base: 'https://alice.example/data/posts/',
+  subjectTemplate: '{id}.ttl',
+  type: 'http://schema.org/CreativeWork',
+});
+
+const db = drizzle(session);
+await db.init(posts);
+
+await db.insert(posts).values({
+  id: 'post-1',
+  title: 'Hello Solid',
+});
+
+const row = await db.findByLocator(posts, { id: 'post-1' });
+
+await db.updateByLocator(posts, { id: 'post-1' }, {
+  title: 'Updated title',
+});
+
+await db.deleteByLocator(posts, { id: 'post-1' });
+```
+
+## Pod 布局怎么理解
+
+每个模型不仅描述字段，也描述落点。
+
+- `base` 决定文档位置
+- `subjectTemplate` 决定业务字段如何映射成 IRI
+- `type` 是主持久化 `rdf:type`
+
+常见 `subjectTemplate`：
+
+- `#{id}`：一个文档里多个实体
+- `{id}.ttl`：一个实体一个文档
+- `{id}.ttl#it`：一个实体一个文档，并带稳定 fragment
+- `{chatId}/messages.ttl#{id}`：多变量分区布局
+
+如果模板用了多个变量，精确定位就必须提供：
+
+- 完整 IRI，或
+- 完整 locator
+
+## 集合读取 vs 精确实体操作
+
+这是最重要的一条运行时规则。
+
+### 集合读取
+
+当你要拿一批数据时，用：
+
+- `client.collection(table).list(...)`
+- `db.select().from(table)...`
+- `db.query.<table>.findMany(...)`
+
+### 精确实体操作
+
+当你要操作一个明确实体时，用：
+
+- `client.entity(table, iri)`
+- `db.findByIri(table, iri)`
+- `db.findByLocator(table, locator)`
+- `db.updateByIri(...)`
+- `db.updateByLocator(...)`
+- `db.deleteByIri(...)`
+- `db.deleteByLocator(...)`
+
+不要再把 `where({ id: ... })` 或 `where(eq(table.id, ...))` 当成精确单体捷径。
+
+## SPARQL 支持与后端差异
+
+`drizzle-solid` 可以跑在不同 Solid 运行时上，但能力有差异。
+
+| 能力 | Community Solid Server | xpod |
+| --- | --- | --- |
+| 基础 CRUD | ✅ | ✅ |
+| 文档通知 | ✅ | ✅ |
+| Drizzle 风格读 facade | ✅ | ✅ |
+| SPARQL 下推 | ⚠️ 有限 / 经常依赖客户端辅助 | ✅ 更好的进程内支持 |
+| 过滤 / 聚合下推 | ❌ 多数走客户端执行 | ✅ 更好的服务端支持 |
+| 联邦查询 | ⚠️ 客户端联邦 | ⚠️ 客户端联邦 |
+| 进程内本地运行时 | ⚠️ 需要额外启动 | ✅ 通过 `@undefineds.co/xpod` |
+
+实用规则：
+
+- 有 SPARQL endpoint 或 sidecar 时，集合查询优先走它
+- 只有 plain LDP document access 时，精确读写仍然可用
+- plain-LDP document mode 不会把精确操作静默扩成扫描
+
+## 示例
+
+仓库里的标准示例会进入集成验证：
+
+- `examples/01-quick-start.ts`
+- `examples/02-relational-query.ts`
+- `examples/03-zero-config-discovery.ts`
+- `examples/04-notifications.ts`
+- `examples/05-data-discovery.ts`
+- `examples/06-federated-query.ts`
+- `examples/07-hooks-and-profile.ts`
+- `examples/08-iri-based-operations.ts`
+- `examples/08-schema-inheritance.ts`
+- `examples/09-multi-variable-templates.ts`
+
+## 文档入口
+
+建议从这里开始：
+
+- `docs/guides/installation.zh-CN.md`
+- `docs/api/README.zh-CN.md`
+- `docs/guides/migrating-from-drizzle-orm.zh-CN.md`
+- `docs/guides/multi-variable-templates.zh-CN.md`
+- `docs/guides/notifications.md`
+- `docs/guides/data-discovery.md`
+
+## 贡献
+
+推送前运行：
+
+```bash
+yarn quality
+SOLID_ENABLE_REAL_TESTS=true SOLID_SERIAL_TESTS=true yarn vitest --run tests/integration/css
+```
+
+示例必须保持可运行且已验证。
+
+## License
+
+MIT
+
+## 相关链接
+
+- GitHub: https://github.com/undefinedsco/drizzle-solid
+- npm: https://www.npmjs.com/package/@undefineds.co/drizzle-solid
+- xpod: https://github.com/undefinedsco/xpod