tbdb 0.0.0 → 0.0.6

package/dist/adapter/SQLite/test/side-table-bug-verify.test.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 侧表机制验证测试
+ *
+ * 此测试文件验证侧表机制的正确性，包括 null/undefined 查询
+ *
+ * ✅ 已修复的问题：
+ * - null/undefined 查询现在使用纯 SQL 实现
+ * - 生成的 SQL 正确匹配：字段不存在、字段值为 null、数组包含 null
+ *
+ * MongoDB 语义说明：
+ * - undefined 在存入时会被转换为 null
+ * - 查询 { field: null } 应匹配：字段值为 null、字段不存在、数组包含 null
+ */
+export {};

package/dist/adapter/SQLite/test/side-table-bugs.test.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 侧表机制 BUG 测试
+ *
+ * 目标：找出 SQLiteAdapter 中侧表（Side Table）机制的潜在 BUG
+ *
+ * 侧表机制说明：
+ * - 侧表用于数组字段的倒排索引，存储 (val, id) 对
+ * - 使用 SQLite Trigger 在 INSERT/UPDATE/DELETE 时自动维护
+ * - 用于加速数组包含查询，如 { tags: "A" } 可以利用侧表实现快速查询
+ *
+ * 潜在问题：
+ * 1. Trigger 使用 NEW.id/OLD.id（用户 ID）进行关联，而非 _id（内部自增 ID）
+ * 2. 如果用户 ID 有特殊字符或格式，可能导致查询失败
+ * 3. 更新/删除后侧表同步问题
+ * 4. 批量操作后侧表重建问题
+ */
+export {};

package/dist/adapter/SQLite/test/side-table-edge-cases.test.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 侧表机制边界情况 BUG 测试
+ *
+ * 这些测试针对更极端的边界情况，旨在找出侧表机制中隐藏的 BUG
+ *
+ * 主要测试点：
+ * 1. 数组嵌套层级问题
+ * 2. 特殊值（NaN, Infinity, undefined）在数组中的处理
+ * 3. 重复元素处理
+ * 4. 数组元素顺序变化
+ * 5. 大量唯一值的性能和正确性
+ * 6. 索引字段不存在或为 undefined
+ * 7. 侧表与主表数据不一致检测
+ */
+export {};

package/dist/adapter/SQLite/test/sqlite-datatypes.test.d.ts

@@ -0,0 +1,5 @@
+/**
+ * SQLiteAdapter 数据类型和边缘情况测试
+ * 确保各种 JS 数据类型的序列化/反序列化正确性
+ */
+export {};

package/dist/adapter/SQLite/test/sqlite-multi-driver.test.d.ts

@@ -0,0 +1,6 @@
+/**
+ * SQLiteAdapter 多驱动测试
+ *
+ * 测试 SQLiteAdapter 使用不同驱动（better-sqlite3 和 node:sqlite）时的功能一致性
+ */
+export {};

package/dist/adapter/SQLite/test/sqlite-query-ops.test.d.ts

@@ -0,0 +1,4 @@
+/**
+ * SQLiteAdapter 查询操作符和高级边缘情况测试
+ */
+export {};

package/dist/adapter/SQLite/utils/mongoToSql.d.ts

@@ -7,4 +7,7 @@ export interface ISqlQuery {
     limit?: number;
     offset?: number;
 }
-export declare function mongoToSql(filter: ITableFilter, options?: ITableFindOptions): Promise<ISqlQuery>;
+export declare function mongoToSql(filter: ITableFilter, options?: ITableFindOptions, schemaStats?: Map<string, {
+    hasArray: boolean;
+    hasSpecial: boolean;
+}>): Promise<ISqlQuery>;

package/dist/adapter/SQLite/utils/projection.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 规范化投影参数（数组转对象）
+ */
+export declare function normalizeProjection(proj?: string[] | Record<string, 1 | -1 | 0>): Record<string, number> | undefined;
+/**
+ * 投影 (Projection) 处理函数
+ *
+ * 类似于 MongoDB 的 project 逻辑：
+ * - 如果指定了包含 (inclusion mode): 只返回指定的字段 + _id (除非显式排除了 _id)。
+ * - 如果指定了排除 (exclusion mode): 返回所有字段，除了指定的字段。
+ *
+ * @param doc 原始文档对象
+ * @param projection 投影配置 (e.g. { name: 1, age: 1 } 或 { password: 0 })
+ * @returns 投影后的新对象
+ */
+export declare function project(doc: any, projection: any): any;

package/dist/adapter/SQLite/utils/queryAnalysis.d.ts

@@ -0,0 +1,54 @@
+import { ITableFilter } from "../../../core/types";
+export interface CompatibilityResult {
+    compatible: boolean;
+    reasons: Array<{
+        path: string;
+        reason: string;
+        value?: any;
+    }>;
+}
+/**
+ * 判断值是否可以直接在 SQL 中安全比较
+ *
+ * 目前支持：
+ * - string, boolean (直接 SQL 映射)
+ * - number (需要排除 NaN, Infinity)
+ * - Date (作为时间戳或 ISO 字符串比较，通常视具体序列化实现而定，这里假设 adapter 处理了)
+ *
+ * 不支持：
+ * - object, array (需要 JSON 解析)
+ * - null, undefined (SQL NULL 语义复杂，保守起见可能需要特殊处理)
+ * - bigint (可能超出 SQL INTEGER 范围或需要特殊转换)
+ */
+export declare function isCompatibleValue(val: any): boolean;
+/**
+ * 分析查询兼容性 (Query Compatibility Analysis)
+ *
+ * 目的：
+ * 判断一个 MongoDB 风格的 filter 是否可以完全、等价地转换为一族 SQL WHERE 子句。
+ *
+ * 策略选择：
+ * - 如果 Compatible=true: 使用纯 SQL 查询 (高性能)。
+ * - 如果 Compatible=false: 使用混合查询 (Hybrid Mode)，即 "SQL 粗筛 + JS 精确匹配"。
+ *
+ * 不兼容情况 (Incompatible Scenarios):
+ * 1. 特殊操作符: $where, $nor (SQL 难以直接表达其短路或逻辑).
+ * 2. 数组/对象全量匹配: { tags: ["A", "B"] } (需要严格顺序和内容匹配).
+ * 3. 隐式数组包含: { tags: "A" } 且 tags 是数组 (MongoDB 语义是 distinct contains, SQL 默认是 equality).
+ * 4. 特殊数值: NaN, Infinity (SQL 标准浮点数处理可能不一致).
+ * 5. 深层点号路径: "a.b.c" 涉及中间路径可能是数组的情况 (需要 unwind).
+ *
+ * @param filter 用户查询对象
+ * @param schemaStats 字段统计信息，用于判断某个路径是否曾经存储过数组 (Schema Dirty Tracking).
+ */
+export declare function analyzeQueryCompatibility(filter: ITableFilter, schemaStats?: Map<string, {
+    hasArray: boolean;
+    hasSpecial: boolean;
+}>): CompatibilityResult;
+/**
+ * 简化的兼容性判断入口
+ */
+export declare function isQuerySqlCompatible(filter: ITableFilter, schemaStats?: Map<string, {
+    hasArray: boolean;
+    hasSpecial: boolean;
+}>): boolean;

package/dist/adapter/SQLite/utils/serializer.d.ts

@@ -1,10 +1,27 @@
 /**
+ * 检测 JSON 字符串是否包含特殊类型标记
+ * 用于快速判断是否需要完整的反序列化流程
+ * @param json JSON 字符串
+ * @returns 如果包含特殊类型标记（如 "$t"）返回 true，否则返回 false
+ */
+export declare function needsSpecialDeserialization(json: string): boolean;
+/**
+ * 快速反序列化
+ * 如果 JSON 不包含特殊类型，直接使用 JSON.parse
+ * 否则使用完整的 deserialize 流程
+ */
+export declare function fastDeserialize(json: string): any;
+/**
+ * 异步序列化版本
  * 将 JS 对象序列化为 SQLite 可存储的 JSON 友好格式
- * 异步版本：支持 Blob 转 Base64
+ * 支持 Blob 转 Base64
  */
 export declare function serialize(value: any): Promise<any>;
 /**
- * 同步版本：不支持 Blob (除非 Blob逻辑是sync的，但通常不是)
+ * 同步序列化版本
+ * 减少异步调用的开销，提高性能
+ * 将 JS 对象序列化为 SQLite 可存储的 JSON 友好格式
+ * 不支持 Blob，因为 Blob 需要异步读取文件内容
  * 用于 JsPatch 等同步环境
  */
 export declare function serializeSync(value: any): any;

package/dist/adapter/SQLite/utils/zstdHelper.d.ts

@@ -1,4 +1,4 @@
-import { Database } from "better-sqlite3";
+import type { ISqliteDatabase } from "../driver/types";
 /**
  * 检查文件是否为 ZSTD 压缩文件 (Magic Number: 0xFD2FB528)
  */
@@ -8,5 +8,5 @@ export declare function isZstdFile(filepath: string): boolean;
  * @param filename 数据库文件名
  */
 export declare function checkAndDecompressDb(filename: string): void;
-export declare function prepareForCompression(db: Database): void;
+export declare function prepareForCompression(db: ISqliteDatabase): void;
 export declare function compressFile(filename: string): void;

package/dist/adapter/adapter.d.ts

@@ -16,7 +16,9 @@ export interface ITableDBAdapterInstance {
     set(id: any, value: Partial<ITableDoc>): Promise<void>;
     delete(id: any): Promise<void>;
     has(id: any): Promise<boolean>;
-    count(filter?: ITableFilter): Promise<number>;
+    count(filter?: ITableFilter, options?: {
+        debug?: ITableDebugResult;
+    }): Promise<number>;
     /** 清空所有数据，不包括索引 */
     clear(): Promise<void>;
     /** 清除所有数据和索引 */
@@ -62,7 +64,7 @@ export interface ITableDBAdapterInstance {
      *
      * 根据 filter 的匹配结果，可能会删除多个文档
      */
-    deleteMany(filter: ITableFilter): Promise<ITableDeletedResult>;
+    deleteMany(filter: ITableFilter, options?: ITableDeleteOptions): Promise<ITableDeletedResult>;
     /** 删除单个文档
      *
      * 只会删除第一个匹配的文档
@@ -111,7 +113,7 @@ export interface ITableFindOptions {
      *
      *  可以是 plv 预设投影名称
      */
-    projection?: string[] | Record<string, 1 | -1>;
+    projection?: string[] | Record<string, 1 | -1> | string;
     /** 排序字段列表
      *
      * 可以是字符串数组， 前面加 `-` 表示降序，\
@@ -126,6 +128,9 @@ export interface ITableFindOptions {
     numericOrdering?: boolean;
     /** 是否忽略标记删除逻辑，默认 false */
     ignoreMarkDelete?: boolean;
+    /** 调试信息存储对象
+     *  提供一个对象用来接受调试信息，调试信息会写入该对象 */
+    debug?: ITableDebugResult;
 }
 export interface ITableUpdateOptions {
     /** 是否在没有匹配的文档时插入一个新文档，然后再进行更新操作 */
@@ -137,6 +142,9 @@ export interface ITableUpdateOptions {
      * 也可以是字段映射对象，1 表示升序，-1 表示降序
      */
     sort?: string[] | Record<string, 1 | -1>;
+    /** 调试信息存储对象
+     *  提供一个对象用来接受调试信息，调试信息会写入该对象 */
+    debug?: ITableDebugResult;
 }
 export interface ITableDeleteOptions {
     /** 排序字段列表
@@ -148,6 +156,9 @@ export interface ITableDeleteOptions {
     sort?: string[] | Record<string, 1 | -1>;
     /** 是否忽略标记删除逻辑，直接物理删除文档，默认 false */
     readDelete?: boolean;
+    /** 调试信息存储对象
+     *  提供一个对象用来接受调试信息，调试信息会写入该对象 */
+    debug?: ITableDebugResult;
 }
 export interface ITableSetOptions {
     /** 是否合并对象字段而不是覆盖，默认 false
@@ -162,6 +173,54 @@ export interface ITableSetOptions {
     insertOnly?: boolean;
     /** 是否只更新已存在的文档，不存在的文档不进行插入 */
     updateOnly?: boolean;
+    /** 仅在插入新文档时设置的字段
+     *  类似于 updateOp 的 $setOnInsert，用于设置 _createDate 等元数据
+     */
+    setOnInsert?: Record<string, any>;
+    /** 调试信息存储对象
+     *  提供一个对象用来接受调试信息，调试信息会写入该对象 */
+    debug?: ITableDebugResult;
+}
+export interface ITableDebugResult {
+    /** SQL 语句及其参数，结构化存储，支持多条（如批量操作或回退查询） */
+    sql?: Array<{
+        query: string;
+        params: any[];
+        /** 该条 SQL 的实际执行耗时 (ms) */
+        executionTimeMs?: number;
+    }>;
+    /** EXPLAIN QUERY PLAN 的原始输出 (通常对应最后一条 SQL) */
+    sqlPlan?: Array<{
+        id: number;
+        parent: number;
+        detail: string;
+    }>;
+    /** 适配器总耗时 (ms, 从调用开始到返回) */
+    totalTimeMs?: number;
+    /** SQL 准备耗时 (ms, mongoToSql 解析 + 序列化开销) */
+    prepareTimeMs?: number;
+    /** 实际数据库交互总耗时 (ms) */
+    dbExecTimeMs?: number;
+    /** 查询策略: 'SQL' (纯SQL) | 'HYBRID' (混合) | 'JS' (纯JS兜底) */
+    strategy?: "SQL" | "HYBRID" | "JS";
+    /** 是否触发了侧表优化 */
+    isSideTableUsed?: boolean;
+    /** 具体的索引使用情况 (如果有) */
+    usedIndexes?: string[];
+    /** 导致无法使用纯 SQL 的原因列表 (替换 dirtyQueries) */
+    dirtyReasons?: Array<{
+        /** 字段路径 */
+        path: string;
+        /** 原因 (e.g., "Array containment", "$where operator") */
+        reason: string;
+        /** 导致问题的值 */
+        value?: any;
+    }>;
+    /** 是否全表扫描 (从 sqlPlan 分析得出) */
+    isFullScan?: boolean;
+    /** 事务状态 */
+    isTransaction?: boolean;
+    [key: string]: any;
 }
 export interface ITableDefineIndexesOptions {
     /** 是否强制重新创建索引，默认 false */

package/dist/benchmark/dist/base.try.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/core/Table.d.ts

@@ -1,9 +1,10 @@
+import { EventHub } from "fzz";
 import { ITableDBAdapterInstance, ITableDBAdapter, ITableDefineIndexesOptions, ITableDeletedResult, ITableDeleteOptions, ITableDoc, ITableFindOptions, ITableIndexConfig, ITableInsertResult, ITableSetOptions, ITableSetResult, ITableUpdateOptions, ITableUpdateResult } from "../adapter/adapter";
 import { exportBinary, exportBinaryToFile, importBinary, importBinaryFromFile } from "./backup";
-import { __check_filter, __check_find_options, __check_input_doc, __check_output_doc, __check_update_op } from "./check";
 import { ICursorPagingOptions, IReCursorPaging, IReSkipPaging, ISkipPagingOptions } from "./list";
-import { __schema_init, ISchemaHints } from "./schema";
+import { ISchemaHints } from "./schema";
 import { ITableFilter, ITableUpdateOp } from "./types";
+import { TableEeventDefifne } from "./event";
 export interface ITableOptions<TSchema, TPlv extends IPlvMap = IPlvMap> {
     /** Talbe 名称
      *
@@ -24,6 +25,8 @@ export interface ITableOptions<TSchema, TPlv extends IPlvMap = IPlvMap> {
     adapter?: ITableDBAdapter;
     /** 是否启用标记删除功能 */
     enableMarkDelete?: boolean;
+    /** 是否启用自动元数据功能（_updateDate, _createDate, _deleteDate） */
+    enableAutoMetadata?: boolean;
     /** 是否启用目录树功能 */
     enableTree?: boolean;
     /** 预设投影列表 */
@@ -51,15 +54,16 @@ export declare class Table<TSchema extends ITableDoc = ITableDoc, TPlv extends I
     adapter: ITableDBAdapterInstance;
     schema: TSchema;
     inited: Promise<boolean>;
+    eventHub: EventHub<typeof TableEeventDefifne>;
     constructor(tableOptions: ITableOptions<TSchema, TPlv>);
     init(): Promise<boolean>;
     __schema_hints: ISchemaHints;
-    __schema_init: typeof __schema_init;
-    __check_filter: typeof __check_filter;
-    __check_output_doc: typeof __check_output_doc;
-    __check_find_options: typeof __check_find_options;
-    __check_input_doc: typeof __check_input_doc;
-    __check_update_op: typeof __check_update_op;
+    private __schema_init;
+    private __check_filter;
+    private __check_output_doc;
+    private __check_find_options;
+    private __check_input_doc;
+    private __check_update_op;
     /** 获取单个文档 */
     get(id: any, options?: ITableGetBaseOptions): Promise<TSchema | void>;
     /** 设置单个文档 */
@@ -69,7 +73,9 @@ export declare class Table<TSchema extends ITableDoc = ITableDoc, TPlv extends I
     /** 检查单个文档是否存在 */
     has(id: any, options?: ITableGetBaseOptions): Promise<boolean>;
     /** 统计文档数量 */
-    count(filter?: ITableFilter, options?: ITableGetBaseOptions): Promise<number>;
+    count(filter?: ITableFilter, options?: ITableGetBaseOptions & {
+        debug?: any;
+    }): Promise<number>;
     /** 清空所有文档 */
     clear(): Promise<void>;
     /** 清除所有文档和索引 */

package/dist/core/defineTable.d.ts

@@ -18,9 +18,15 @@ import { ITableOptions, Table } from "./Table";
  * // 如果要指定 adapter
  * const useCustomTable = defineTable({adapter : SQLiteAdapter({filename: ":memory:"})})
  */
-export declare function defineTable<TSchema extends ITableDoc = ITableDoc>(tableOptions: ITableOptions<TSchema>): UseTalbeFunction<TSchema>;
-export type UseTalbeFunction<TSchema extends ITableDoc = ITableDoc> = (opitons?: {
+export declare function defineTable<TSchema extends ITableDoc = ITableDoc, TTable extends Table<TSchema> = Table<TSchema>>(tableOptions: ITableOptions<TSchema>, TableClass?: new (options: ITableOptions<TSchema>) => TTable): UseTableFunction<TSchema, TTable>;
+/** 兼容旧的拼写错误类型 */
+export type UseTalbeFunction<TSchema extends ITableDoc = ITableDoc, TTable extends Table<TSchema> = Table<TSchema>> = UseTableFunction<TSchema, TTable>;
+/** 定义使用 Table 函数的类型 */
+export type UseTableFunction<TSchema extends ITableDoc = ITableDoc, TTable extends Table<TSchema> = Table<TSchema>> = (options?: {
     adapter?: ITableDBAdapter;
-}) => Promise<Table<TSchema>>;
-/** 定义全局的数据库适配器（SQLite/MongoDB） */
+}) => Promise<TTable>;
+/** 定义全局的数据库适配器（SQLite/MongoDB）
+ *
+ * @param adapter 数据库适配器实例
+ */
 export declare function defineGlobalDBAdapter(adapter: ITableDBAdapter): void;

package/dist/core/event.d.ts

@@ -0,0 +1,24 @@
+import { ITableFilter, ITableUpdateOp } from "./types";
+import { ITableDoc } from "../adapter/adapter";
+export declare const TableEeventDefifne: {
+    CheckFilter: {
+        filter: ITableFilter;
+        options?: {
+            ignoreMarkDelete?: boolean;
+            realDelete?: boolean;
+        } & Record<string, any>;
+    };
+    CheckInputDoc: Partial<ITableDoc> | void;
+    CheckFindOptions: {
+        projection?: any;
+    };
+    CheckOutputDoc: Partial<ITableDoc> | void;
+    CheckUpdateOp: ITableUpdateOp | void;
+};
+export declare const TabeEvents: {
+    CheckFilter: "CheckFilter";
+    CheckInputDoc: "CheckInputDoc";
+    CheckFindOptions: "CheckFindOptions";
+    CheckOutputDoc: "CheckOutputDoc";
+    CheckUpdateOp: "CheckUpdateOp";
+};

package/dist/core/types.d.ts

@@ -2,7 +2,7 @@ import { ITableDoc } from "../adapter/adapter";
 /** Table 的基本类型
  *  这格式可以直接存入 Table 后取出时，类型不会变化，Table 会保持其原始类型
  */
-export type ITablePrimitive = string | number | boolean | null | undefined | Date | RegExp | Map<any, any> | Set<any> | bigint | Blob | File | ArrayBuffer | DataView | Int8Array | Int16Array | Int32Array | Uint8Array | Uint8ClampedArray | Uint16Array | Uint32Array | Float32Array | Float64Array | BigInt64Array | BigUint64Array;
+export type ITablePrimitive = string | number | boolean | null | undefined | Date | RegExp | Map<any, any> | Set<any> | bigint | Blob | File | ArrayBuffer | DataView | Int8Array | Int16Array | Int32Array | Uint8Array | Uint8ClampedArray | Uint16Array | Uint32Array | Float32Array | Float64Array | BigInt64Array | BigUint64Array | Error;
 /**
  * Table 的数据类型，可以是基本类型、对象或数组
  *

package/dist/extension/tree/TableTree.d.ts

@@ -0,0 +1,49 @@
+import { Table, ITableOptions } from "../../core/Table";
+import { ITreeNode } from "./tree.types";
+import { createNodes } from "./core/createNodes";
+import { updateNodes } from "./core/updateNodes";
+import { setNodes } from "./core/setNodes";
+import { deleteNodes } from "./core/deleteNodes";
+import { unDeleteNodes } from "./core/unDeleteNodes";
+import { moveNodes } from "./core/moveNodes";
+import { copyNodes } from "./core/copyNodes";
+import { listNodes } from "./core/listNodes";
+import { listNodesByCursor } from "./core/listNodesByCursor";
+import { preOverwriteNodes } from "./core/preOverwriteNodes";
+import { presyncNodes } from "./core/presyncNodes";
+import { UseTableFunction } from "../../core/defineTable";
+/**
+ * 目录树表
+ * 预置了常用的树形结构操作方法，如创建节点、删除节点、更新节点等
+ * 每个文档被视为一个节点，必须包含 parentId 字段来表示父子关系
+ * 会自动维护节点的层级关系和修改标记
+ *
+ */
+export declare class TableTree<TNode extends ITreeNode = ITreeNode> extends Table<TNode> {
+    createNodes: typeof createNodes;
+    updateNodes: typeof updateNodes;
+    setNodes: typeof setNodes;
+    deleteNodes: typeof deleteNodes;
+    unDeleteNodes: typeof unDeleteNodes;
+    moveNodes: typeof moveNodes;
+    copyNodes: typeof copyNodes;
+    listNodes: typeof listNodes;
+    listNodesByCursor: typeof listNodesByCursor;
+    preOverwriteNodes: typeof preOverwriteNodes;
+    presyncNodes: typeof presyncNodes;
+}
+/**
+ * 定义目录树表，返回一个 useTableTree 函数
+ *
+ * @param tableOptions TableTree 的配置选项
+ * @returns 返回一个异步获取 TableTree 实例的函数
+ *
+ * @example
+ * ```ts
+ * const useFileTree = defineTableTree<ZFile>({
+ *     name: "file-tree",
+ * })
+ * const fileTree = await useFileTree()
+ * ```
+ */
+export declare function defineTableTree<TNode extends ITreeNode = ITreeNode>(tableOptions: ITableOptions<TNode>): UseTableFunction<TNode, TableTree<TNode>>;

package/dist/extension/tree/core/copyNodes.d.ts

@@ -0,0 +1,36 @@
+import type { TableTree } from "../TableTree";
+import type { ITreeIndexOptions, ITreeNode, ITreeOverwriteOptions } from "../tree.types";
+/** 复制节点选项 */
+export type ITreeCopyNodesOptions = ITreeOverwriteOptions & {
+    /** 是否自动计算并写入排序索引 */
+    index?: ITreeIndexOptions;
+    /** 是否递归复制子节点 */
+    deep?: boolean;
+    /** 复制后的节点是否自动重命名
+     *  使用 getUniqueFileNames() 获得独特名字
+     */
+    renameOnCopy?: boolean;
+};
+export interface ITreeCopyResult {
+    /** 创建的节点 id 列表（如果有递归，不算子文件，只有 `srcNodeIds` 对应复制的节点） */
+    createdNodeIds: string[];
+}
+/**
+ * 复制节点
+ *
+ * 将已存在节点复制到目标父级，并为复制出的每个节点生成新的 ID。
+ *
+ * 核心流程：
+ * 1. 去重并读取源节点，父子混合选择时只保留最外层源节点，避免子节点被重复复制。
+ * 2. 按 renameOnCopy 规则为顶层副本预生成名称；默认复制到同级时自动避让重名。
+ * 3. 递归构造待写入节点列表，deep 模式下复制整棵子树，所有副本共享本次复制的 modif。
+ * 4. 只给顶层副本计算目标父级下的 index，子节点在各自新父级下保持构造顺序。
+ * 5. 交给 setNodes 统一处理覆盖策略、metadata、标记删除恢复和最终写入。
+ * 6. 返回仍然可见的顶层副本 ID；如果覆盖策略跳过了某些副本，它们不会出现在结果里。
+ *
+ */
+export declare function copyNodes(this: TableTree<ITreeNode>, 
+/** 待复制的源节点 ID 列表 */
+srcNodeIds: string[], 
+/** 目标父节点 ID，如果为 "/" 表示根节点 */
+parentId: string, options?: ITreeCopyNodesOptions): Promise<ITreeCopyResult>;

package/dist/extension/tree/core/createNodes.d.ts

@@ -0,0 +1,33 @@
+import type { TableTree } from "../TableTree";
+import type { ITreeNode, ITreeIndexOptions } from "../tree.types";
+/** 创建节点选项 */
+export interface ITreeCreateNodesOptions {
+    /** 是否自动计算并写入排序索引 */
+    index?: ITreeIndexOptions;
+    /** 是否在创建后返回新节点的数据，默认为 false */
+    returnNewNodes?: boolean;
+}
+export interface ITreeCreateResult {
+    /** 创建的节点 id 列表 */
+    createdNodeIds: string[];
+    /** 创建的节点数据列表，仅在 options.returnNewNodes 为 true 时返回 */
+    newNodes?: ITreeNode[];
+}
+/**
+ * 创建节点
+ *
+ * 在指定父级下批量插入新节点，并维护目录树需要的排序和统计字段。
+ *
+ * 核心流程：
+ * 1. 先校验父级是否存在，避免写入孤儿节点。
+ * 2. 将外部传入的 Partial 节点归一化为完整可写节点，并统一本次操作的 modif。
+ * 3. 根据显式 index 选项或父级当前排序状态，为缺少 index 的节点补齐排序值。
+ * 4. 调用底层 insertMany 写入；如果遇到重复 ID，底层会跳过，所以后续只处理实际插入成功的节点。
+ * 5. 用实际插入节点的贡献量增量刷新父级及祖先 metadata，并按需触发 index 智能重排。
+ *
+ */
+export declare function createNodes(this: TableTree<ITreeNode>, 
+/** 要创建的节点文档 */
+nodes: Partial<ITreeNode>[], 
+/** 父级节点 id ，如果为 "/" 表示根节点 */
+parentId: string, options?: ITreeCreateNodesOptions): Promise<ITreeCreateResult>;

package/dist/extension/tree/core/deleteNodes.d.ts

@@ -0,0 +1,33 @@
+import type { TableTree } from "../TableTree";
+import type { ITreeNode } from "../tree.types";
+/** 删除节点选项 */
+export interface ITreeDeleteNodesOptions {
+    /** 是否强制物理删除 */
+    realDelete?: boolean;
+}
+/** 删除节点结果 */
+export interface ITreeDeleteResult {
+    /** 是否有节点被删除 */
+    hasDeleted: boolean;
+    /** 是否有子节点被删除 */
+    hasChildDeleted: boolean;
+    /** 被删除的节点数量 */
+    deletedCount: number;
+}
+/**
+ * 删除节点
+ *
+ * 删除指定节点及其全部后代。
+ *
+ * 核心流程：
+ * 1. 去重输入 ID，并读取这些节点连同所有后代，确保目录删除会覆盖整棵子树。
+ * 2. 计算“最外层被删除节点”，父子同时删除时只用父节点扣减 metadata，避免后代重复扣减。
+ * 3. 根据 TableTree 的标记删除配置选择物理删除或软删除；软删除会写入统一 modif。
+ * 4. 用最外层节点对父级的贡献量做负增量，刷新父级及祖先的统计和 childLastIndex。
+ *
+ * 要注意递归删除可能会导致性能问题，尤其是当删除的节点有大量子孙节点时。
+ *
+ */
+export declare function deleteNodes(this: TableTree<ITreeNode>, 
+/** 要删除的节点 id 列表 */
+nodeIds: string[], options?: ITreeDeleteNodesOptions): Promise<ITreeDeleteResult>;

package/dist/extension/tree/core/listNodes.d.ts

@@ -0,0 +1,32 @@
+import type { TableTree } from "../TableTree";
+import type { ITableFilter } from "../../../core/types";
+import type { ITreeNode } from "../tree.types";
+import type { IReSkipPaging, ISkipPagingOptions } from "../../../core/list";
+/** 子节点分页查询选项（skip/limit） */
+export interface ITreeListNodesOptions extends ISkipPagingOptions {
+    /** 仅返回指定类型的节点（优先级高于 onlyNotTypes） */
+    onlyTypes?: string[];
+    /** 排除指定类型的节点 */
+    onlyNotTypes?: string[];
+    /** 是否忽略标记删除（结果包括被标记删除的节点） */
+    ignoreMarkDelete?: boolean;
+    /** 额外的 filter，可以手动指定更多的限定范围以提高性能 */
+    filter?: ITableFilter;
+}
+/** 子节点分页查询结果（skip/limit） */
+export type ITreeListNodesResult<TNode extends ITreeNode = ITreeNode> = IReSkipPaging<TNode>;
+/**
+ * 列出节点列表（skip/limit 分页）
+ *
+ * 获取指定父级的直属子节点。
+ *
+ * 核心流程：
+ * 1. 先通过 buildTreeListFilter 固定 parentId，确保额外 filter 不能越权查询其他父级。
+ * 2. 根据 onlyTypes / onlyNotTypes 追加类型过滤，onlyTypes 优先级更高。
+ * 3. 默认按 index 升序返回，符合目录树手动排序语义；调用方仍可通过 options.sort 覆盖。
+ * 4. 将 ignoreMarkDelete 透传给底层分页，让调用方可选择是否读取软删除节点。
+ */
+export declare function listNodes(this: TableTree<ITreeNode>, 
+/** 要获取的节点，可以用 '/' 表示根节点 */
+parentId: string, options?: ITreeListNodesOptions): Promise<ITreeListNodesResult<ITreeNode>>;
+export declare function buildTreeListFilter(parentId: string, options?: ITreeListNodesOptions): ITableFilter;

package/dist/extension/tree/core/listNodesByCursor.d.ts

@@ -0,0 +1,31 @@
+import { ICursorPagingOptions, IReCursorPaging } from "../../../core/list";
+import { ITableFilter } from "../../../core/types";
+import { TableTree } from "../TableTree";
+import { ITreeNode } from "../tree.types";
+/** 子节点分页查询选项（cursor） */
+export interface ITreeListNodesByCursorOptions extends ICursorPagingOptions {
+    /** 仅返回指定类型的节点（优先级高于 onlyNotTypes） */
+    onlyTypes?: string[];
+    /** 排除指定类型的节点 */
+    onlyNotTypes?: string[];
+    /** 是否忽略标记删除（结果包括被标记删除的节点） */
+    ignoreMarkDelete?: boolean;
+    /** 额外的 filter，可以手动指定更多的限定范围以提高性能 */
+    filter?: ITableFilter;
+}
+/** 子节点分页查询结果（cursor） */
+export type ITreeListNodesByCursorResult<TNode extends ITreeNode = ITreeNode> = IReCursorPaging<TNode>;
+/**
+ * 列出节点列表（游标分页）
+ *
+ * 获取指定父级的直属子节点，适合“继续加载下一页”的场景。
+ *
+ * 核心流程：
+ * 1. 复用 buildTreeListFilter，保证父级限定和类型过滤与 listNodes 完全一致。
+ * 2. 使用底层 listPagingByCursor 实现游标分页，避免大页码 skip 的性能问题。
+ * 3. 默认 sortKey 为 id，sortOrder 为升序；调用方可以显式指定其他游标排序字段。
+ * 4. 透传 ignoreMarkDelete，保持软删除读取语义与 skip/limit 分页一致。
+ */
+export declare function listNodesByCursor(this: TableTree<ITreeNode>, 
+/** 要获取的节点，可以用 '/' 表示根节点 */
+parentId: string, options?: ITreeListNodesByCursorOptions): Promise<ITreeListNodesByCursorResult<ITreeNode>>;