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

package/src/constants.ts

@@ -0,0 +1,97 @@
+/**
+ * @fileoverview Tree 插件常量
+ */
+
+import { EntityMetadataOptions, OnDeleteAction, PropertyType, RelationKind } 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 const TREE_QUERY_TYPE_LIST = ['findDescendants', 'findAncestors', 'countDescendants', 'countAncestors'] as const;
+
+/**
+ * 树查询任务类型的联合，由 {@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 const TREE_QUERY_TYPES: ReadonlySet<string> = new Set<string>(TREE_QUERY_TYPE_LIST);
+
+/**
+ * `TreeAdjacencyListEntityBase` 的 `@Entity` 元数据。
+ *
+ * @remarks
+ * 邻接表模型的那一份声明：`parentId` 外键、`children` 一对多自关联、
+ * `hasChildren` 计算属性，以及 `repository: 'TreeRepository'`。子类沿原型链继承整份，
+ * 所以 `@Entity({ name: 'Category' })` 不必重复声明任何一项就有树能力。
+ *
+ * 之所以导出而不是内联进装饰器：`@TreeEntity` 装饰器要拿它去合并用户自己的选项，
+ * 手写实体（不继承基类、自己实现 {@link ITreeEntity}）也要靠它对齐字段，
+ * 两条路径必须用同一份声明，否则「继承来的树」和「手写的树」在 schema 上会分叉。
+ *
+ * 放在这个不含装饰器与 rxjs 的模块里，`/generator` 子路径才能读到它而不必导入
+ * {@link TreeAdjacencyListEntityBase} —— 生成器只在构建期跑。
+ *
+ * @see {@link TreeAdjacencyListEntityBase}
+ */
+export const TREE_ADJACENCY_LIST_ENTITY_BASE_OPTIONS: EntityMetadataOptions = {
+  name: 'TreeAdjacencyListEntityBase',
+  abstract: true, // 标记为抽象类，不会直接创建此类的实例
+  // 基类声明了 findDescendants / countAncestors 等静态方法，而这些只由 TreeRepository 注入。
+  // 因此这里必须显式声明 —— 子类沿原型链继承到它，才不会「类型上有、运行时没有」。
+  // 不写 repository 的子类（`@Entity({ name: 'Category' })`）正是靠这一行拿到树查询能力。
+  repository: 'TreeRepository',
+  computedProperties: [
+    {
+      name: 'hasChildren', // 是否有子节点
+      displayName: '是否有子节点',
+      type: PropertyType.boolean, // 布尔类型
+      nullable: true,
+      readonly: true
+    }
+  ],
+  relations: [
+    {
+      name: 'children', // 子节点关系名称
+      displayName: '子节点',
+      kind: RelationKind.ONE_TO_MANY, // 一对多关系
+      mappedEntity: 'TreeAdjacencyListEntityBase', // 关联到同一实体类型
+      mappedProperty: 'parent' // 映射到子实体的 parent 属性
+    },
+    {
+      name: 'parent', // 父节点关系名称
+      columnName: 'parentId', // 外键列名
+      displayName: '父节点',
+      kind: RelationKind.MANY_TO_ONE, // 多对一关系
+      mappedEntity: 'TreeAdjacencyListEntityBase', // 关联到同一实体类型
+      mappedProperty: 'children', // 映射到父实体的 children 属性
+      nullable: true, // 允许根节点没有父节点
+      onDelete: OnDeleteAction.CASCADE // 删除父节点时级联删除子节点
+    }
+  ],
+  features: {
+    tree: {
+      type: 'adjacency-list', // 指定为邻接表树形结构
+      hasChildren: true // 启用 hasChildren 计算属性
+    }
+  }
+} as const;

package/src/entity/tree-entity-base.ts

@@ -0,0 +1,100 @@
+/**
+ * @fileoverview 树形实体基类定义文件
+ * 提供基于邻接表模型的树形结构实体基类
+ */
+
+import { Entity, EntityBase, RxDBEntityId, UUID } from '@aiao/rxdb';
+import { Observable } from 'rxjs';
+import { TREE_ADJACENCY_LIST_ENTITY_BASE_OPTIONS } from '../constants.js';
+import type { FindTreeOptions } from '../repository/tree-repository.interface.js';
+import { ITreeEntity } from './tree-entity.interface.js';
+
+/**
+ * 树形实体装饰器配置
+ * 定义了树形结构所需的父子关系
+ */
+@Entity(TREE_ADJACENCY_LIST_ENTITY_BASE_OPTIONS)
+
+/**
+ * 邻接表树形结构实体基类
+ *
+ * 基于邻接表模型实现的树形结构，每个节点通过 parent 引用其父节点，
+ * 通过 children 集合引用其所有子节点。
+ *
+ * 邻接表模型是实现树形结构的简单高效方式，适合大多数树形数据场景。
+ *
+ * 参考资料：
+ * - https://www.slideshare.net/slideshow/models-for-hierarchical-data/4179181
+ * - https://schinckel.net/2014/09/13/long-live-adjacency-lists/
+ *
+ * @typeParam Id - 主键类型，与 {@link EntityBase} 的 `Id` 同源，缺省 {@link UUID}。
+ *   `parentId` 跟随收窄 —— 一个节点的 `parentId` 指向的正是同类节点的 `id`，
+ *   两者必须是同一个类型，数值主键的树才能在类型层表达。
+ *
+ * @example
+ * ```typescript
+ * @Entity({ name: 'Category' })
+ * class Category extends TreeAdjacencyListEntityBase {
+ * }
+ *
+ * // 数值主键的树
+ * @Entity({ name: 'Menu', properties: [{ name: 'id', type: PropertyType.integer, primary: true }] })
+ * class Menu extends TreeAdjacencyListEntityBase<number> {
+ * }
+ * ```
+ */
+export abstract class TreeAdjacencyListEntityBase<Id extends RxDBEntityId = UUID>
+  extends EntityBase<Id>
+  implements ITreeEntity
+{
+  /**
+   * 父节点ID
+   */
+  parentId?: Id | null;
+
+  /**
+   * 是否有子节点，由数据库计算属性自动填充。
+   * `declare` 因为它是 metadata 注入的计算属性，class 不需要初始化。
+   */
+  declare hasChildren?: boolean | null;
+
+  /**
+   * 查询所有子孙节点
+   * @param options - 查询选项，包含实体ID和层级深度
+   * @returns Observable 包装的子孙节点数组
+   */
+  declare static findDescendants: <T extends TreeAdjacencyListEntityBase<RxDBEntityId>>(
+    this: new () => T,
+    options: FindTreeOptions<new () => T>
+  ) => Observable<T[]>;
+
+  /**
+   * 统计子孙节点数量
+   * @param options - 查询选项，包含实体ID和层级深度
+   * @returns Observable 包装的子孙节点数量
+   */
+  declare static countDescendants: <T extends TreeAdjacencyListEntityBase<RxDBEntityId>>(
+    this: new () => T,
+    options: FindTreeOptions<new () => T>
+  ) => Observable<number>;
+
+  /**
+   * 查询所有祖先节点
+   * @param options - 查询选项，包含实体ID和层级深度
+   * @returns Observable 包装的祖先节点数组
+   */
+  declare static findAncestors: <T extends TreeAdjacencyListEntityBase<RxDBEntityId>>(
+    this: new () => T,
+    options: FindTreeOptions<new () => T>
+  ) => Observable<T[]>;
+
+  /**
+   * 统计祖先节点数量
+   * @param options - 查询选项，包含实体ID和层级深度
+   * @returns Observable 包装的祖先节点数量
+   */
+  declare static countAncestors: <T extends TreeAdjacencyListEntityBase<RxDBEntityId>>(
+    this: new () => T,
+    options: FindTreeOptions<new () => T>
+  ) => Observable<number>;
+}

package/src/entity/tree-entity.decorator.ts

@@ -0,0 +1,37 @@
+/**
+ * @fileoverview 树形实体装饰器
+ *
+ * `@TreeEntity(...)` 是 `@Entity(...)` 在"树形结构"特化下的封装：
+ *
+ * - **补全 `features.tree.type`**：缺省时落回 `'adjacency-list'`（邻接表），
+ *   未来加入 `nested-set` / `path-enumeration` 等模型时只需扩这里。
+ * - **补全 `features.tree.hasChildren`**：默认 `false`，由 {@link TREE_ADJACENCY_LIST_ENTITY_BASE_OPTIONS}
+ *   在 `hasChildren: true` 时挂上同名计算属性（`TreeRepository` 用它做轻量 hasChildren 查询）。
+ * - **强制 `repository: 'TreeRepository'`**：子类不写 `repository` 也能拿到 `findDescendants` /
+ *   `countAncestors` 这类树查询方法。`Entity` 装饰器单独使用时如果不写 `repository`，
+ *   只会得到普通的 `Repository`（没有树 API）。
+ *
+ * 也就是说，业务方"用 `@Entity` 还是 `@TreeEntity`"决定了仓库能力，不要混淆。
+ */
+
+import { Entity, EntityMetadataOptions } from '@aiao/rxdb';
+
+/**
+ * 树形实体装饰器
+ * 用于将类标记为树形结构实体，并处理树形特定的元数据
+ */
+export const TreeEntity: typeof Entity = (metadataOptions: EntityMetadataOptions) => {
+  const tree = metadataOptions.features?.tree ?? {};
+  return Entity({
+    ...metadataOptions,
+    features: {
+      ...metadataOptions.features,
+      tree: {
+        ...tree,
+        type: tree.type ?? 'adjacency-list',
+        hasChildren: tree.hasChildren ?? false
+      }
+    },
+    repository: metadataOptions.repository ?? 'TreeRepository'
+  });
+};

package/src/entity/tree-entity.interface.ts

@@ -0,0 +1,43 @@
+/**
+ * @packageDocumentation
+ * 树形实体接口定义
+ * 扩展基础实体接口,添加父子关系支持
+ */
+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);

package/src/entity/tree-metadata.interface.ts

@@ -0,0 +1,35 @@
+/**
+ * @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;
+}

package/src/generator/TreeRepositoryGenerator.ts

@@ -0,0 +1,153 @@
+/**
+ * @fileoverview 树形结构 Repository 生成器
+ * 继承基础 Repository 方法生成器，为树形结构实体生成特有的查询方法
+ *
+ * @module rxdb-plugin-tree/generator
+ */
+
+import { ENTITY_BASE_METADATA_OPTIONS, type EntityMetadata, type EntityMetadataOptions } from '@aiao/rxdb';
+import {
+  buildRules,
+  generateEntityRules,
+  type GeneratorContext,
+  type RepositoryGeneratorSymbols,
+  RepositoryMethodsGenerator
+} from '@aiao/rxdb-client-generator';
+import { TREE_ADJACENCY_LIST_ENTITY_BASE_OPTIONS } from '../constants.js';
+
+/**
+ * 树形结构 Repository 方法生成器
+ * 继承 Repository 基类方法，新增 TreeRepository 特有的查询方法
+ */
+export class TreeRepositoryGenerator extends RepositoryMethodsGenerator {
+  override readonly name = 'TreeRepository';
+
+  /**
+   * 树实体的基类与配套类型都在 `@aiao/rxdb-plugin-tree`（US-025 阶段 E 起核心不再内置树）。
+   *
+   * @remarks
+   * 这个值同时决定三处产物：`.js` 里 `TreeAdjacencyListEntityBase` 的 import 来源、
+   * `.d.ts` 里 `ITreeEntity` 的 import 来源、以及基类签名带出的 `FindTreeOptions`。
+   */
+  override readonly entityBaseModuleSpecifier = '@aiao/rxdb-plugin-tree';
+
+  /**
+   * `TreeAdjacencyListEntityBase` 的装饰器实参是常量标识符，CLI 静态求值取不到它的值。
+   *
+   * @remarks
+   * 生成器随身带上这份元数据，CLI 才能在分析 `extends TreeAdjacencyListEntityBase` 的实体时
+   * 把它回填；否则生成器包得反向依赖本插件才拿得到（RV-015）。顺序为「自身 → 祖先」。
+   *
+   * `TreeEntityBase` 是 `@TreeEntity` 装饰器给手写实体用的别名，共用同一份声明。
+   */
+  override readonly abstractEntityMetadata: ReadonlyMap<string, EntityMetadataOptions[]> = new Map([
+    ['TreeAdjacencyListEntityBase', [TREE_ADJACENCY_LIST_ENTITY_BASE_OPTIONS, ENTITY_BASE_METADATA_OPTIONS]],
+    ['TreeEntityBase', [TREE_ADJACENCY_LIST_ENTITY_BASE_OPTIONS, ENTITY_BASE_METADATA_OPTIONS]]
+  ]);
+
+  /**
+   * @inheritDoc
+   *
+   * @remarks
+   * 不合并父类结果：`generateMethods` 没有调用 `super`，基类那一份符号由
+   * `entity-definition` 单独跑的基类生成轮次自报。
+   */
+  override declareSymbols(metadata: EntityMetadata): RepositoryGeneratorSymbols {
+    return {
+      // `ITreeEntity` 只由邻接表基类带出：`TreeEntityBase` 的实体走默认的 `IEntity`
+      entityInterfaces: metadata.extends[0]?.includes('TreeAdjacencyListEntityBase') ? ['ITreeEntity'] : [],
+      types: [{ name: `${metadata.name}TreeRule` }, { exported: true, name: `${metadata.name}TreeRuleGroup` }]
+    };
+  }
+
+  protected override generateMethods(context: GeneratorContext): void {
+    // Tree 特有方法（基类方法已在 generator_entity_definition.ts 中单独生成）
+    const { metadata, rxdbNamedImports, siblingNamedImports, generator, file, staticTypesInterface } = context;
+    const { name: className } = metadata;
+
+    // TreeRuleGroup 规则。
+    const entityRules = generateEntityRules(generator, metadata).filter(
+      d => d.key.startsWith('children.') && d.key !== 'children.id'
+    );
+    if (entityRules.length === 0) {
+      throw new Error(`${className} TreeRepository requires children query rules`);
+    }
+    const rules = buildRules(entityRules, rxdbNamedImports, siblingNamedImports);
+    const names = entityRules.map(r => `'${r.key}'`).join(' | ');
+
+    file.addTypeAlias({
+      name: `${className}TreeRule`,
+      type: Array.from(new Set(rules)).join('\n| '),
+      hasDeclareKeyword: true,
+      docs: ['TreeRule']
+    });
+    file.addTypeAlias({
+      name: `${className}TreeRuleGroup`,
+      type: `RuleGroupBase<typeof ${className}, ${names}, ${className}TreeRule>`,
+      hasDeclareKeyword: true,
+      docs: ['TreeRuleGroup'],
+      isExported: true
+    });
+
+    // 添加 entity 属性到静态类型（Tree 特有）
+    staticTypesInterface.addProperty({
+      name: 'entity',
+      type: `${className}`,
+      docs: ['查询的实体']
+    });
+
+    const treeOptions = `FindTreeOptions<typeof ${className},${className}TreeRuleGroup>`;
+
+    this.addStaticMethod(context, {
+      method: 'findDescendants',
+      options: treeOptions,
+      returnType: `${className}[]`,
+      metHodDoc: '查询子孙实体（包含自身）',
+      example: `// 查询某节点的所有后代\n${className}.findDescendants({ entityId: root.id }).subscribe(list => console.log(list));\n\n// 仅查询直接子节点（level 1）\n${className}.findDescendants({ entityId: root.id, level: 1 }).subscribe(children => console.log(children));`,
+      baseSignature: {
+        entityBase: 'TreeAdjacencyListEntityBase',
+        options: 'FindTreeOptions<new () => T>',
+        returnType: 'T[]'
+      }
+    });
+
+    this.addStaticMethod(context, {
+      method: 'countDescendants',
+      options: treeOptions,
+      returnType: `number`,
+      metHodDoc: '统计子孙实体数量（不包含自身）',
+      example: `// 统计某节点下的后代数量\n${className}.countDescendants({ entityId: root.id }).subscribe(count => console.log(count));`,
+      baseSignature: {
+        entityBase: 'TreeAdjacencyListEntityBase',
+        options: 'FindTreeOptions<new () => T>',
+        returnType: 'number'
+      }
+    });
+
+    this.addStaticMethod(context, {
+      method: 'findAncestors',
+      options: treeOptions,
+      returnType: `${className}[]`,
+      metHodDoc: '查询祖先实体（包含自身）',
+      example: `// 查询某节点的所有祖先（面包屑导航）\n${className}.findAncestors({ entityId: grand.id }).subscribe(ancestors => console.log(ancestors));\n\n// 仅查询直接父节点（level 1）\n${className}.findAncestors({ entityId: grand.id, level: 1 }).subscribe(parents => console.log(parents));`,
+      baseSignature: {
+        entityBase: 'TreeAdjacencyListEntityBase',
+        options: 'FindTreeOptions<new () => T>',
+        returnType: 'T[]'
+      }
+    });
+
+    this.addStaticMethod(context, {
+      method: 'countAncestors',
+      options: treeOptions,
+      returnType: `number`,
+      metHodDoc: '统计祖先实体数量（不包含自身）',
+      example: `// 统计某节点的祖先层级深度\n${className}.countAncestors({ entityId: grand.id }).subscribe(depth => console.log(depth));`,
+      baseSignature: {
+        entityBase: 'TreeAdjacencyListEntityBase',
+        options: 'FindTreeOptions<new () => T>',
+        returnType: 'number'
+      }
+    });
+  }
+}

package/src/generator/index.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';

package/src/index.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';

package/src/plugin.ts

@@ -0,0 +1,111 @@
+/**
+ * @fileoverview RxDB Tree 插件
+ * 树形结构插件入口，提供 TreeRepository 注册与树能力扩展
+ *
+ * @module rxdb-plugin-tree
+ */
+
+import { IRxDBPlugin, Plugin, RxDB, RxDBPluginBase, SyncType } from '@aiao/rxdb';
+import type { LifecycleScope } from '@aiao/utils';
+import { EntityMetadataTreeFeatures } from './entity/tree-metadata.interface.js';
+import { TreeRepository } from './repository/TreeRepository.js';
+
+/**
+ * {@link rxDBPluginTree} 的选项。
+ *
+ * @remarks
+ * 目前无可配项：树的所有行为都由实体元数据（`features.tree`）和查询选项决定，
+ * 没有需要在装配期敲定的开关。保留这个类型是为了让 `Plugin<…>` 的形参具名 ——
+ * 将来加选项时是加字段，不是改签名。
+ */
+type RxDBPluginTreeOptions = object;
+
+/**
+ * 树形结构插件。
+ *
+ * @remarks
+ * 只做一件事：把 {@link TreeRepository} 登记到 `rxdb` 的仓储注册表，并声明它撑不住
+ * `SyncType.QueryCache`。登记是 **scoped** 的 —— 连接断开时随 scope 一起撤销，
+ * 不会把指向已拆纪元的仓储留在 `rxdb` 上。
+ *
+ * 四个树查询（`findDescendants` / `countDescendants` / `findAncestors` / `countAncestors`）
+ * 与它们的增量 merge 都挂在 `TreeRepository` 上，不装本插件的应用连 `QueryOptions`
+ * 里都没有这四支。
+ *
+ * 一般不直接 `new`，用工厂 {@link rxDBPluginTree} 交给 `.use()`。
+ *
+ * @example
+ * ```typescript
+ * import { rxDBPluginTree } from '@aiao/rxdb-plugin-tree';
+ *
+ * const rxdb = new RxDB({ entities: [Category] }).use(rxDBPluginTree);
+ * ```
+ */
+export class RxDBPluginTree extends RxDBPluginBase implements IRxDBPlugin {
+  readonly lifecycle = 'scoped' as const;
+  name: Uncapitalize<string> = 'tree';
+
+  install(scope: LifecycleScope) {
+    // 传 scope：断开连接时这条注册跟着一起撤销，与 graph 插件同一处理。
+    this.rxdb.repository(
+      'TreeRepository',
+      {
+        class: TreeRepository,
+        // 这条限制原先是核心 `metadata-validate.ts` 里硬编码的 `unsupportedTreeQueryCache`
+        // 规则。核心不该知道 'TreeRepository' 是什么，所以改由注册方自己声明；
+        // 核心只负责把声明翻译成 `unsupportedRepositorySyncType` 违规。
+        unsupportedSyncTypes: {
+          [SyncType.QueryCache]:
+            `树查询依赖本地完整的祖先链，而缓存只覆盖查过的 where 命中的行，` +
+            `递归会在缺口处静默截断。改用 SyncType.Full / Filter，或把该实体换成普通 Repository。`
+        }
+      },
+      scope
+    );
+  }
+}
+
+declare module '@aiao/rxdb' {
+  interface RxDB {
+    tree: RxDBPluginTree;
+  }
+  /**
+   * 把 `TreeRepository` 登进门面轴注册表
+   *
+   * @remarks
+   * 与上面 `install()` 里的 `rxdb.repository('TreeRepository', …)` 成对：
+   * 那一处是运行期登记，这一处是类型登记。少了它，`@Entity({ repository: 'TreeRepository' })`
+   * 只能落到 `RxDBRepositoryName` 的 `(string & {})` 那一支，补全里一个字都没有。
+   */
+  interface RxDBRepositories {
+    TreeRepository: typeof TreeRepository;
+  }
+  /**
+   * 扩展 EntityMetadataFeatures，添加 tree 字段
+   */
+  interface EntityMetadataFeatures {
+    /**
+     * 树形特性配置
+     * 由 rxdb-plugin-tree 插件提供
+     */
+    tree?: EntityMetadataTreeFeatures;
+  }
+}
+
+/**
+ * {@link RxDBPluginTree} 的工厂，交给 `RxDB.use()`。
+ *
+ * @remarks
+ * 注册树实体（继承 `TreeAdjacencyListEntityBase` 或 `@TreeEntity` 标注）的应用**必须**
+ * 装它：没装时 `repository: 'TreeRepository'` 在注册期找不到仓储，实体初始化直接抛错
+ * （契约见 `__tests__/contracts/missing-plugin-error.spec.ts`），不会静默降级成普通仓储。
+ *
+ * @param db - 宿主 `RxDB` 实例，由 `use()` 注入
+ * @returns 插件实例
+ *
+ * @example
+ * ```typescript
+ * const rxdb = new RxDB({ entities: [Category] }).use(rxDBPluginTree);
+ * ```
+ */
+export const rxDBPluginTree: Plugin<RxDBPluginTreeOptions> = (db: RxDB) => new RxDBPluginTree(db);