@aiao/rxdb-plugin-tree 0.0.0-stage → 0.0.28

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Aiao Team
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,112 @@
-# Temporary Holding Version
+# @aiao/rxdb-plugin-tree
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> Implements: [US-025 核心插件化拆分](https://github.com/aiao-io/rxdb/blob/main/requirements/stories/core/US-025-core-plugin-extraction.md)
+
+RxDB 树形结构插件：邻接表模型的实体基类、装饰器、`TreeRepository`，以及四个树查询的**真增量 merge**。
+
+这套能力曾经内置在 `@aiao/rxdb`。核心里躺着 4 个树 task 类型、3 个 merge switch 的树分支和约 1100 行树专属合并逻辑——它们从永远加载的 switch 里可达，tree-shaking 甩不掉，不用树的应用照样付这份体积。外移之后，装插件才有树。
+
+## 安装
+
+```bash
+pnpm add @aiao/rxdb @aiao/rxdb-adapter-wa-sqlite @aiao/rxdb-plugin-tree
+```
+
+## 使用
+
+```typescript
+import { PropertyType, RxDB, SyncType } from '@aiao/rxdb';
+import { RxDBAdapterWaSqlite } from '@aiao/rxdb-adapter-wa-sqlite';
+import { TreeAdjacencyListEntityBase, TreeEntity, rxDBPluginTree } from '@aiao/rxdb-plugin-tree';
+
+@TreeEntity({
+  name: 'Category',
+  properties: [{ name: 'name', type: PropertyType.string }],
+  features: { tree: { hasChildren: true } }
+})
+class Category extends TreeAdjacencyListEntityBase {
+  name!: string;
+}
+
+const rxdb = new RxDB({
+  dbName: 'catalog',
+  entities: [Category],
+  sync: { type: SyncType.None, local: { adapter: 'wa-sqlite' } }
+});
+
+// 必须在 init() 之前 use()：仓储注册发生在 init() 内部，早于实体元数据校验。
+rxdb.use(rxDBPluginTree).adapter('wa-sqlite', db => new RxDBAdapterWaSqlite(db, { vfs: 'MemoryAsyncVFS' }));
+
+await rxdb.connect('wa-sqlite');
+rxdb.init();
+
+Category.findDescendants({ entityId: root.id, level: 2 }).subscribe(nodes => {
+  console.log(nodes.length);
+});
+```
+
+不装插件而实体声明了 `repository: 'TreeRepository'`（`@TreeEntity` 会自动写上），`init()` 直接抛错并列出当前已注册的仓储名。
+
+## 公开面
+
+| 分类 | 符号                                                                                         |
+| ---- | -------------------------------------------------------------------------------------------- |
+| 插件 | `RxDBPluginTree`、`rxDBPluginTree`                                                           |
+| 实体 | `TreeAdjacencyListEntityBase`、`TREE_ADJACENCY_LIST_ENTITY_BASE_OPTIONS`、`@TreeEntity`      |
+| 类型 | `ITreeEntity`、`ISortableTreeEntity`、`TreeEntityType`、`EntityMetadataTreeFeatures`         |
+| 仓储 | `TreeRepository`、`ITreeRepository`、`FindTreeOptions`                                       |
+| 查询 | `FindDescendantsQuery`、`FindAncestorsQuery`、`CountDescendantsQuery`、`CountAncestorsQuery` |
+
+四个查询 task 类型经 `RepositoryQueryExtensions` 模块增强挂进核心的 `QueryOptions` 联合——这是插件给核心闭合联合加分支的唯一缝。
+
+## 查询语义
+
+`level` 包含当前节点本身：`level: 0` 只有当前节点，`level: 1` 是当前节点 + 直接子节点。数字以外的值（字符串、小数、NaN）在适配器层直接抛 `RxDBError`，没有兜底。
+
+- `findDescendants` / `countDescendants`：指定 `entityId` 时**不含**当前节点；不指定时覆盖所有根节点及其后代。
+- `findAncestors` / `countAncestors`：指定 `entityId` 时**含**当前节点。
+
+## 增量 merge
+
+树查询与图查询不同：图查询一律回 SQL `refresh()`，树查询走真增量。`TreeRepository` 构造时按 task 类型注册 `merge_create` / `merge_update` / `merge_remove`，三道前置守卫之后才进增量路径：
+
+1. `task.result === undefined` → refresh；
+2. 事件里有过期实体（`isStaleEntityEvent`）→ refresh；
+3. `findAncestors` 且 `parentId` 变过 → refresh（祖先链已被改写，增量无从谈起）。
+
+`find*` 走 recalculate，`count*` 走 refresh。用到的 merge 原语（`prepareIncrementalUpdate` / `applyExternalEntityUpdate` / `getEntityId` 等）由 `@aiao/rxdb` 公开导出，进基线后受兼容承诺约束；`classifyUpdates` 与 `invalidateEntityFingerprint` 是核心内部装配细节，不在公开面上。
+
+## 连接纪元
+
+插件声明 `lifecycle: 'scoped'`，唯一的宿主改动——注册 `TreeRepository`——登记在 `install(scope)` 收到的作用域上，`disconnectAll()` 时随作用域一起撤销。重新 `connect()` 会重新注册。
+
+## 框架绑定
+
+四个树查询 hook 在各自的框架包里，三端同名同形：
+
+- Angular：[`@aiao/rxdb-plugin-tree-angular`](../rxdb-plugin-tree-angular)
+- React：[`@aiao/rxdb-plugin-tree-react`](../rxdb-plugin-tree-react)
+- Vue：[`@aiao/rxdb-plugin-tree-vue`](../rxdb-plugin-tree-vue)
+
+## 适配器
+
+`TreeRepository` 的名字没变，适配器仍按字符串 `'TreeRepository'` 分发，公开 API 一字未动。PGlite / SQLite / Supabase 三家的 `*TreeRepository` 只把类型来源改到了本包。
+
+## 迁移
+
+从内置树升级见 [tree-split 迁移说明](https://github.com/aiao-io/rxdb/blob/main/website/docs/migration/tree-split.md)。
+
+## 开发命令
+
+```bash
+pnpm nx test rxdb-plugin-tree              # node 环境，只跑构建期生成器 spec
+pnpm nx run rxdb-plugin-tree:test-browser  # 先跑 node 趟（依赖 coverage target），再在真实 chromium 里跑运行时 spec
+```
+
+`vite.config.mts` 按 `VITEST_BROWSER` 环境变量把测试拆成两趟：不设该变量时（`nx test` 走的路径）排除全部 `*.browser.spec.ts`，只剩 `src/__tests__/generator/` 下的构建期生成器 spec；查询 / 合并 / 仓储等运行时 spec 都以 `.browser.spec.ts` 结尾，只有 `VITEST_BROWSER=true`（即 `test-browser`）才会执行。
+
+所以 `pnpm nx test rxdb-plugin-tree --watch` 做 TDD 会**静默**跳过全部运行时 spec——改了查询 / 合并 / 仓储代码，红没红只有 `test-browser` 看得到。
+
+## License
+
+[MIT](https://github.com/aiao-io/rxdb/blob/main/LICENSE)

package/dist/constants-DRludxr-.js

@@ -0,0 +1,41 @@
+import { OnDeleteAction as e, PropertyType as t, RelationKind as n } from "@aiao/rxdb";
+//#region src/constants.ts
+var r = [
+	"findDescendants",
+	"findAncestors",
+	"countDescendants",
+	"countAncestors"
+], i = new Set(r), a = {
+	name: "TreeAdjacencyListEntityBase",
+	abstract: !0,
+	repository: "TreeRepository",
+	computedProperties: [{
+		name: "hasChildren",
+		displayName: "是否有子节点",
+		type: t.boolean,
+		nullable: !0,
+		readonly: !0
+	}],
+	relations: [{
+		name: "children",
+		displayName: "子节点",
+		kind: n.ONE_TO_MANY,
+		mappedEntity: "TreeAdjacencyListEntityBase",
+		mappedProperty: "parent"
+	}, {
+		name: "parent",
+		columnName: "parentId",
+		displayName: "父节点",
+		kind: n.MANY_TO_ONE,
+		mappedEntity: "TreeAdjacencyListEntityBase",
+		mappedProperty: "children",
+		nullable: !0,
+		onDelete: e.CASCADE
+	}],
+	features: { tree: {
+		type: "adjacency-list",
+		hasChildren: !0
+	} }
+};
+//#endregion
+export { i as n, r, a as t };

package/dist/constants.d.ts

@@ -0,0 +1,49 @@
+import { EntityMetadataOptions } from '@aiao/rxdb';
+/**
+ * 树查询任务类型的**单一来源**。
+ *
+ * @remarks
+ * 这四个名字要被三处消费：`*Query` 接口的 `type` 字段（类型侧）、
+ * {@link TREE_QUERY_TYPES}（三个 merge 的首道过滤）、`TreeRepository._STATIC_METHODS`
+ * （挂到实体上的静态方法名）。它们此前各写一份，加第五种树查询时漏掉其中一处
+ * **不会报错**，只会让新任务静默落回核心默认 merge、或者压根不挂到实体上。
+ *
+ * 现在后两者从这里派生，接口侧用 `Extract<TreeQueryType, …>` 与它绑定，
+ * 双向一致性由 `__tests__/contracts/tree-query-type-parity.spec.ts` 在编译期钉死。
+ */
+export declare const TREE_QUERY_TYPE_LIST: readonly ["findDescendants", "findAncestors", "countDescendants", "countAncestors"];
+/**
+ * 树查询任务类型的联合，由 {@link TREE_QUERY_TYPE_LIST} 派生。
+ */
+export type TreeQueryType = (typeof TREE_QUERY_TYPE_LIST)[number];
+/**
+ * 树查询任务类型集合
+ *
+ * @remarks
+ * 三个 merge 函数用它做首道过滤：`TreeRepository` 把自己注册到 `QueryManager` 时是
+ * 按 task 类型逐个登记的，但同一个 Repository 上也跑着 `findAll` / `count` 这类通用查询，
+ * 它们必须原样落回核心的默认 merge。没有这一句，树的增量逻辑会去接管非树任务。
+ *
+ * 元素类型声明成 `string` 而不是 {@link TreeQueryType}：调用方传进来的是
+ * `QueryTask.type`（`string`），收窄成联合反而让 `has()` 在调用点编译失败。
+ */
+export declare const TREE_QUERY_TYPES: ReadonlySet<string>;
+/**
+ * `TreeAdjacencyListEntityBase` 的 `@Entity` 元数据。
+ *
+ * @remarks
+ * 邻接表模型的那一份声明：`parentId` 外键、`children` 一对多自关联、
+ * `hasChildren` 计算属性，以及 `repository: 'TreeRepository'`。子类沿原型链继承整份，
+ * 所以 `@Entity({ name: 'Category' })` 不必重复声明任何一项就有树能力。
+ *
+ * 之所以导出而不是内联进装饰器：`@TreeEntity` 装饰器要拿它去合并用户自己的选项，
+ * 手写实体（不继承基类、自己实现 {@link ITreeEntity}）也要靠它对齐字段，
+ * 两条路径必须用同一份声明，否则「继承来的树」和「手写的树」在 schema 上会分叉。
+ *
+ * 放在这个不含装饰器与 rxjs 的模块里，`/generator` 子路径才能读到它而不必导入
+ * {@link TreeAdjacencyListEntityBase} —— 生成器只在构建期跑。
+ *
+ * @see {@link TreeAdjacencyListEntityBase}
+ */
+export declare const TREE_ADJACENCY_LIST_ENTITY_BASE_OPTIONS: EntityMetadataOptions;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,qBAAqB,EAA8C,MAAM,YAAY,CAAC;AAE/F;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,qFAAsF,CAAC;AAExH;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG,CAAC,OAAO,oBAAoB,CAAC,CAAC,MAAM,CAAC,CAAC;AAElE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,gBAAgB,EAAE,WAAW,CAAC,MAAM,CAAyC,CAAC;AAE3F;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,uCAAuC,EAAE,qBAyC5C,CAAC"}

package/dist/entity/tree-entity-base.d.ts

@@ -0,0 +1,44 @@
+import { EntityBase, RxDBEntityId, UUID } from '@aiao/rxdb';
+import { Observable } from 'rxjs';
+import { FindTreeOptions } from '../repository/tree-repository.interface.js';
+import { ITreeEntity } from './tree-entity.interface.js';
+/**
+ * 树形实体装饰器配置
+ * 定义了树形结构所需的父子关系
+ */
+export declare abstract class TreeAdjacencyListEntityBase<Id extends RxDBEntityId = UUID> extends EntityBase<Id> implements ITreeEntity {
+    /**
+     * 父节点ID
+     */
+    parentId?: Id | null;
+    /**
+     * 是否有子节点，由数据库计算属性自动填充。
+     * `declare` 因为它是 metadata 注入的计算属性，class 不需要初始化。
+     */
+    hasChildren?: boolean | null;
+    /**
+     * 查询所有子孙节点
+     * @param options - 查询选项，包含实体ID和层级深度
+     * @returns Observable 包装的子孙节点数组
+     */
+    static findDescendants: <T extends TreeAdjacencyListEntityBase<RxDBEntityId>>(this: new () => T, options: FindTreeOptions<new () => T>) => Observable<T[]>;
+    /**
+     * 统计子孙节点数量
+     * @param options - 查询选项，包含实体ID和层级深度
+     * @returns Observable 包装的子孙节点数量
+     */
+    static countDescendants: <T extends TreeAdjacencyListEntityBase<RxDBEntityId>>(this: new () => T, options: FindTreeOptions<new () => T>) => Observable<number>;
+    /**
+     * 查询所有祖先节点
+     * @param options - 查询选项，包含实体ID和层级深度
+     * @returns Observable 包装的祖先节点数组
+     */
+    static findAncestors: <T extends TreeAdjacencyListEntityBase<RxDBEntityId>>(this: new () => T, options: FindTreeOptions<new () => T>) => Observable<T[]>;
+    /**
+     * 统计祖先节点数量
+     * @param options - 查询选项，包含实体ID和层级深度
+     * @returns Observable 包装的祖先节点数量
+     */
+    static countAncestors: <T extends TreeAdjacencyListEntityBase<RxDBEntityId>>(this: new () => T, options: FindTreeOptions<new () => T>) => Observable<number>;
+}
+//# sourceMappingURL=tree-entity-base.d.ts.map

package/dist/entity/tree-entity-base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-entity-base.d.ts","sourceRoot":"","sources":["../../src/entity/tree-entity-base.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAU,UAAU,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AACpE,OAAO,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AAElC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,4CAA4C,CAAC;AAClF,OAAO,EAAE,WAAW,EAAE,MAAM,4BAA4B,CAAC;AAEzD;;;GAGG;AACH,8BA8BsB,2BAA2B,CAAC,EAAE,SAAS,YAAY,GAAG,IAAI,CAC9E,SAAQ,UAAU,CAAC,EAAE,CACrB,YAAW,WAAW;IAEtB;;OAEG;IACH,QAAQ,CAAC,EAAE,EAAE,GAAG,IAAI,CAAC;IAErB;;;OAGG;IACK,WAAW,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAErC;;;;OAIG;IACH,OAAe,eAAe,EAAE,CAAC,CAAC,SAAS,2BAA2B,CAAC,YAAY,CAAC,EAClF,IAAI,EAAE,UAAU,CAAC,EACjB,OAAO,EAAE,eAAe,CAAC,UAAU,CAAC,CAAC,KAClC,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC;IAErB;;;;OAIG;IACH,OAAe,gBAAgB,EAAE,CAAC,CAAC,SAAS,2BAA2B,CAAC,YAAY,CAAC,EACnF,IAAI,EAAE,UAAU,CAAC,EACjB,OAAO,EAAE,eAAe,CAAC,UAAU,CAAC,CAAC,KAClC,UAAU,CAAC,MAAM,CAAC,CAAC;IAExB;;;;OAIG;IACH,OAAe,aAAa,EAAE,CAAC,CAAC,SAAS,2BAA2B,CAAC,YAAY,CAAC,EAChF,IAAI,EAAE,UAAU,CAAC,EACjB,OAAO,EAAE,eAAe,CAAC,UAAU,CAAC,CAAC,KAClC,UAAU,CAAC,CAAC,EAAE,CAAC,CAAC;IAErB;;;;OAIG;IACH,OAAe,cAAc,EAAE,CAAC,CAAC,SAAS,2BAA2B,CAAC,YAAY,CAAC,EACjF,IAAI,EAAE,UAAU,CAAC,EACjB,OAAO,EAAE,eAAe,CAAC,UAAU,CAAC,CAAC,KAClC,UAAU,CAAC,MAAM,CAAC,CAAC;CACzB"}

package/dist/entity/tree-entity.decorator.d.ts

@@ -0,0 +1,7 @@
+import { Entity } from '@aiao/rxdb';
+/**
+ * 树形实体装饰器
+ * 用于将类标记为树形结构实体，并处理树形特定的元数据
+ */
+export declare const TreeEntity: typeof Entity;
+//# sourceMappingURL=tree-entity.decorator.d.ts.map

package/dist/entity/tree-entity.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-entity.decorator.d.ts","sourceRoot":"","sources":["../../src/entity/tree-entity.decorator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,MAAM,EAAyB,MAAM,YAAY,CAAC;AAE3D;;;GAGG;AACH,eAAO,MAAM,UAAU,EAAE,OAAO,MAc/B,CAAC"}

package/dist/entity/tree-entity.interface.d.ts

@@ -0,0 +1,36 @@
+import { IEntity, IEntityStaticType, RxDBEntityId, SortOrderKey } from '@aiao/rxdb';
+export interface ITreeEntity extends IEntity {
+    /**
+     * 父节点主键。与 {@link IEntity.id} 同属 {@link RxDBEntityId} 域 ——
+     * 一棵树的 `parentId` 指向的正是另一个节点的 `id`，两者必须允许同样的类型
+     * （`string | number | bigint`），否则数值主键的树在类型层根本无法表达。
+     */
+    parentId?: RxDBEntityId | null;
+    /**
+     * 是否有子节点。由 `TreeAdjacencyListEntityBase` 的计算属性自动填充，应用层只读。
+     * 未启用 `features.tree.hasChildren` 的实体此字段为 `null`。
+     */
+    hasChildren?: boolean | null;
+}
+/**
+ * 支持手动排序的树形实体接口。
+ *
+ * 在 {@link ITreeEntity} 基础上要求实体声明 `sortOrder` 字段（通常用 fractional indexing
+ * 如 `generateKeyBetween` 产生）。拖放、手动排序等场景的算法约束类型。
+ *
+ * @remarks
+ * 键类型取自核心排序模块的 {@link SortOrderKey}（唯一来源），树节点的 `sortOrder` 仍可空可缺省；
+ * 组合的是键类型而不是非空的 `ISortableEntity`。只是类型：实现它不会让实体获得 `manualOrder` 声明。
+ */
+export interface ISortableTreeEntity extends ITreeEntity {
+    sortOrder?: SortOrderKey | null;
+}
+/**
+ * 树形实体类型
+ *
+ * 继承了 {@link IEntity} 的 `id` / `createdAt` 等字段，再加上
+ * `parentId` 与 `hasChildren` 这类树形独有属性。
+ * {@link TreeRepository} 据此提供 `findDescendants` / `countAncestors` 等方法。
+ */
+export type TreeEntityType = IEntityStaticType & (new (...args: never[]) => ITreeEntity);
+//# sourceMappingURL=tree-entity.interface.d.ts.map

package/dist/entity/tree-entity.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-entity.interface.d.ts","sourceRoot":"","sources":["../../src/entity/tree-entity.interface.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEpF,MAAM,WAAW,WAAY,SAAQ,OAAO;IAC1C;;;;OAIG;IACH,QAAQ,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;IAC/B;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAC9B;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,mBAAoB,SAAQ,WAAW;IACtD,SAAS,CAAC,EAAE,YAAY,GAAG,IAAI,CAAC;CACjC;AAED;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,iBAAiB,GAAG,CAAC,KAAK,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,WAAW,CAAC,CAAC"}

package/dist/entity/tree-metadata.interface.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @fileoverview 树形实体的元数据特性
+ *
+ * 经 `plugin.ts` 的 `declare module '@aiao/rxdb'` 挂到 `EntityMetadataFeatures.tree` 上。
+ */
+type TreeType = 'adjacency-list';
+/**
+ * 实体元数据树形结构特性接口
+ */
+export interface EntityMetadataTreeFeatures {
+    /**
+     * 树形结构类型
+     *
+     * 目前仅支持 adjacency-list (邻接表模型)，未来可能支持其他模型：
+     * - 'closure-table': 闭包表模型
+     * - 'nested-set': 嵌套集模型
+     * - 'materialized-path': 物化路径模型
+     *
+     * 参考资料：
+     * - https://www.slideshare.net/slideshow/models-for-hierarchical-data/4179181
+     * - https://schinckel.net/2014/09/13/long-live-adjacency-lists/
+     *
+     * @default 'adjacency-list'
+     */
+    type?: TreeType;
+    /**
+     * 是否有子节点
+     * 在树结构里使用，表示当前节点是否有子节点
+     * @default false
+     */
+    hasChildren?: boolean;
+}
+export {};
+//# sourceMappingURL=tree-metadata.interface.d.ts.map

package/dist/entity/tree-metadata.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-metadata.interface.d.ts","sourceRoot":"","sources":["../../src/entity/tree-metadata.interface.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,KAAK,QAAQ,GAAG,gBAAgB,CAAC;AAEjC;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;;;;;;;;;;;OAaG;IACH,IAAI,CAAC,EAAE,QAAQ,CAAC;IAEhB;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB"}

package/dist/generator/TreeRepositoryGenerator.d.ts

@@ -0,0 +1,37 @@
+import { EntityMetadata, EntityMetadataOptions } from '@aiao/rxdb';
+import { GeneratorContext, RepositoryGeneratorSymbols, RepositoryMethodsGenerator } from '@aiao/rxdb-client-generator';
+/**
+ * 树形结构 Repository 方法生成器
+ * 继承 Repository 基类方法，新增 TreeRepository 特有的查询方法
+ */
+export declare class TreeRepositoryGenerator extends RepositoryMethodsGenerator {
+    readonly name = "TreeRepository";
+    /**
+     * 树实体的基类与配套类型都在 `@aiao/rxdb-plugin-tree`（US-025 阶段 E 起核心不再内置树）。
+     *
+     * @remarks
+     * 这个值同时决定三处产物：`.js` 里 `TreeAdjacencyListEntityBase` 的 import 来源、
+     * `.d.ts` 里 `ITreeEntity` 的 import 来源、以及基类签名带出的 `FindTreeOptions`。
+     */
+    readonly entityBaseModuleSpecifier = "@aiao/rxdb-plugin-tree";
+    /**
+     * `TreeAdjacencyListEntityBase` 的装饰器实参是常量标识符，CLI 静态求值取不到它的值。
+     *
+     * @remarks
+     * 生成器随身带上这份元数据，CLI 才能在分析 `extends TreeAdjacencyListEntityBase` 的实体时
+     * 把它回填；否则生成器包得反向依赖本插件才拿得到（RV-015）。顺序为「自身 → 祖先」。
+     *
+     * `TreeEntityBase` 是 `@TreeEntity` 装饰器给手写实体用的别名，共用同一份声明。
+     */
+    readonly abstractEntityMetadata: ReadonlyMap<string, EntityMetadataOptions[]>;
+    /**
+     * @inheritDoc
+     *
+     * @remarks
+     * 不合并父类结果：`generateMethods` 没有调用 `super`，基类那一份符号由
+     * `entity-definition` 单独跑的基类生成轮次自报。
+     */
+    declareSymbols(metadata: EntityMetadata): RepositoryGeneratorSymbols;
+    protected generateMethods(context: GeneratorContext): void;
+}
+//# sourceMappingURL=TreeRepositoryGenerator.d.ts.map

package/dist/generator/TreeRepositoryGenerator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TreeRepositoryGenerator.d.ts","sourceRoot":"","sources":["../../src/generator/TreeRepositoryGenerator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAgC,KAAK,cAAc,EAAE,KAAK,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAC3G,OAAO,EAGL,KAAK,gBAAgB,EACrB,KAAK,0BAA0B,EAC/B,0BAA0B,EAC3B,MAAM,6BAA6B,CAAC;AAGrC;;;GAGG;AACH,qBAAa,uBAAwB,SAAQ,0BAA0B;IACrE,SAAkB,IAAI,oBAAoB;IAE1C;;;;;;OAMG;IACH,SAAkB,yBAAyB,4BAA4B;IAEvE;;;;;;;;OAQG;IACH,SAAkB,sBAAsB,EAAE,WAAW,CAAC,MAAM,EAAE,qBAAqB,EAAE,CAAC,CAGnF;IAEH;;;;;;OAMG;IACM,cAAc,CAAC,QAAQ,EAAE,cAAc,GAAG,0BAA0B;cAQ1D,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI;CA0FpE"}

package/dist/generator/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @packageDocumentation
+ * Tree 插件的构建期生成器入口
+ *
+ * @remarks
+ * 供 `rxdb-client-generator` 的 CLI 通过 `repositoryGenerators` 装载：
+ *
+ * ```jsonc
+ * { "repositoryGenerators": ["@aiao/rxdb-plugin-tree/generator#TreeRepositoryGenerator"] }
+ * ```
+ *
+ * 与运行时入口分开：本入口只在构建期跑，不应把装饰器与 rxjs 拉进来。
+ *
+ * @module rxdb-plugin-tree/generator
+ */
+export { TreeRepositoryGenerator } from './TreeRepositoryGenerator.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/generator/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/generator/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/generator.js

@@ -0,0 +1,87 @@
+import { t as e } from "./constants-DRludxr-.js";
+import { ENTITY_BASE_METADATA_OPTIONS as t } from "@aiao/rxdb";
+import { RepositoryMethodsGenerator as n, buildRules as r, generateEntityRules as i } from "@aiao/rxdb-client-generator";
+//#region src/generator/TreeRepositoryGenerator.ts
+var a = class extends n {
+	name = "TreeRepository";
+	entityBaseModuleSpecifier = "@aiao/rxdb-plugin-tree";
+	abstractEntityMetadata = /* @__PURE__ */ new Map([["TreeAdjacencyListEntityBase", [e, t]], ["TreeEntityBase", [e, t]]]);
+	declareSymbols(e) {
+		return {
+			entityInterfaces: e.extends[0]?.includes("TreeAdjacencyListEntityBase") ? ["ITreeEntity"] : [],
+			types: [{ name: `${e.name}TreeRule` }, {
+				exported: !0,
+				name: `${e.name}TreeRuleGroup`
+			}]
+		};
+	}
+	generateMethods(e) {
+		let { metadata: t, rxdbNamedImports: n, siblingNamedImports: a, generator: o, file: s, staticTypesInterface: c } = e, { name: l } = t, u = i(o, t).filter((e) => e.key.startsWith("children.") && e.key !== "children.id");
+		if (u.length === 0) throw Error(`${l} TreeRepository requires children query rules`);
+		let d = r(u, n, a), f = u.map((e) => `'${e.key}'`).join(" | ");
+		s.addTypeAlias({
+			name: `${l}TreeRule`,
+			type: Array.from(new Set(d)).join("\n| "),
+			hasDeclareKeyword: !0,
+			docs: ["TreeRule"]
+		}), s.addTypeAlias({
+			name: `${l}TreeRuleGroup`,
+			type: `RuleGroupBase<typeof ${l}, ${f}, ${l}TreeRule>`,
+			hasDeclareKeyword: !0,
+			docs: ["TreeRuleGroup"],
+			isExported: !0
+		}), c.addProperty({
+			name: "entity",
+			type: `${l}`,
+			docs: ["查询的实体"]
+		});
+		let p = `FindTreeOptions<typeof ${l},${l}TreeRuleGroup>`;
+		this.addStaticMethod(e, {
+			method: "findDescendants",
+			options: p,
+			returnType: `${l}[]`,
+			metHodDoc: "查询子孙实体（包含自身）",
+			example: `// 查询某节点的所有后代\n${l}.findDescendants({ entityId: root.id }).subscribe(list => console.log(list));\n\n// 仅查询直接子节点（level 1）\n${l}.findDescendants({ entityId: root.id, level: 1 }).subscribe(children => console.log(children));`,
+			baseSignature: {
+				entityBase: "TreeAdjacencyListEntityBase",
+				options: "FindTreeOptions<new () => T>",
+				returnType: "T[]"
+			}
+		}), this.addStaticMethod(e, {
+			method: "countDescendants",
+			options: p,
+			returnType: "number",
+			metHodDoc: "统计子孙实体数量（不包含自身）",
+			example: `// 统计某节点下的后代数量\n${l}.countDescendants({ entityId: root.id }).subscribe(count => console.log(count));`,
+			baseSignature: {
+				entityBase: "TreeAdjacencyListEntityBase",
+				options: "FindTreeOptions<new () => T>",
+				returnType: "number"
+			}
+		}), this.addStaticMethod(e, {
+			method: "findAncestors",
+			options: p,
+			returnType: `${l}[]`,
+			metHodDoc: "查询祖先实体（包含自身）",
+			example: `// 查询某节点的所有祖先（面包屑导航）\n${l}.findAncestors({ entityId: grand.id }).subscribe(ancestors => console.log(ancestors));\n\n// 仅查询直接父节点（level 1）\n${l}.findAncestors({ entityId: grand.id, level: 1 }).subscribe(parents => console.log(parents));`,
+			baseSignature: {
+				entityBase: "TreeAdjacencyListEntityBase",
+				options: "FindTreeOptions<new () => T>",
+				returnType: "T[]"
+			}
+		}), this.addStaticMethod(e, {
+			method: "countAncestors",
+			options: p,
+			returnType: "number",
+			metHodDoc: "统计祖先实体数量（不包含自身）",
+			example: `// 统计某节点的祖先层级深度\n${l}.countAncestors({ entityId: grand.id }).subscribe(depth => console.log(depth));`,
+			baseSignature: {
+				entityBase: "TreeAdjacencyListEntityBase",
+				options: "FindTreeOptions<new () => T>",
+				returnType: "number"
+			}
+		});
+	}
+};
+//#endregion
+export { a as TreeRepositoryGenerator };

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @packageDocumentation
+ * RxDB Tree 插件
+ * 树形结构插件，提供邻接表模型的实体基类、装饰器、仓储与增量查询合并
+ *
+ * 主要功能：
+ * - 树形实体基类与装饰器（`TreeAdjacencyListEntityBase` / `@TreeEntity`）
+ * - 四个树查询（`findDescendants` / `countDescendants` / `findAncestors` / `countAncestors`）
+ * - 树查询的真增量 merge（不像图查询一律回 SQL 刷新）
+ *
+ * @module rxdb-plugin-tree
+ */
+export * from './constants.js';
+export * from './entity/tree-entity-base.js';
+export * from './entity/tree-entity.decorator.js';
+export * from './entity/tree-entity.interface.js';
+export * from './entity/tree-metadata.interface.js';
+export * from './plugin.js';
+export * from './query/tree-query.interface.js';
+export * from './repository/tree-level.utils.js';
+export * from './repository/tree-repository.interface.js';
+export * from './repository/TreeRepository.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,cAAc,gBAAgB,CAAC;AAC/B,cAAc,8BAA8B,CAAC;AAC7C,cAAc,mCAAmC,CAAC;AAClD,cAAc,mCAAmC,CAAC;AAClD,cAAc,qCAAqC,CAAC;AACpD,cAAc,aAAa,CAAC;AAC5B,cAAc,iCAAiC,CAAC;AAChD,cAAc,kCAAkC,CAAC;AACjD,cAAc,2CAA2C,CAAC;AAC1D,cAAc,gCAAgC,CAAC"}