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

package/dist/history-filters.d.ts

@@ -0,0 +1,78 @@
+import { HistoryItem, HistoryScope } from '@aiao/rxdb';
+/**
+ * 生成 repository 的缓存键（纯函数）
+ *
+ * @param repository - 带 namespace / entity 的仓储标识
+ * @returns 'namespace:entity' 形式的缓存键
+ *
+ * @internal 供 HistoryManager 与同文件的过滤函数使用
+ */
+export declare const getRepositoryKey: (repository: {
+    namespace: string;
+    entity: string;
+}) => string;
+/**
+ * 合成「每个仓库推到哪了」的水位线映射：已提交的 `RxDBSync` 水位线与正在飞的认领取较大者。
+ *
+ * @param repoSyncs - 当前分支下的 `RxDBSync` 行
+ * @param inFlight - `PushInFlightRegistry.snapshot()`，`namespace:entity` -> 正在飞的最大 change id
+ * @returns `namespace:entity` -> 该仓库「视同已推」的最大 change id
+ *
+ * @remarks
+ * `undoHistories$` 与 `fetchLatestHistories` 两条路径都要这份映射，此前各写一份循环。
+ * 两份必须逐字一致：一边认在飞、另一边不认，反应式的「可撤销」列表就会和真正执行撤销时
+ * 的判定分家 —— UI 上还亮着的那一项点下去什么也不会发生，或者更糟，真的撤销了一条
+ * 已经在飞的变更。
+ *
+ * 取最大值而不是「有在飞就用在飞」：上一轮推到 30、这一轮只在飞到 20 时，
+ * 水位线不许倒退。
+ *
+ * 在飞认领先进 map，因此**没有** `RxDBSync` 行的仓库也报得出来：`RxDBSync` 行由
+ * `planRepositoryPush` 现建，行还没落到本次查询的结果集里时，认领仍然必须生效。
+ */
+export declare function buildLastPushedMap(repoSyncs: readonly {
+    namespace: string;
+    entity: string;
+    lastPushedChangeId: number | null;
+}[], inFlight: ReadonlyMap<string, number>): Map<string, number>;
+/**
+ * 按作用域过滤历史记录（纯函数）
+ *
+ * @param histories - 原始历史记录数组
+ * @param scope - 作用域配置
+ * @returns 过滤后的历史记录数组
+ *
+ * @internal 供 HistoryManager 和单元测试使用
+ */
+export declare function filterHistoriesByScope(histories: HistoryItem[], scope: HistoryScope): HistoryItem[];
+/**
+ * 过滤出可撤销的历史记录（纯函数）
+ *
+ * @param histories - 原始历史记录数组
+ * @param lastPushedMap - namespace:entity -> lastPushedChangeId 的 repository 级水位线映射
+ * @param undoBoundaryChangeId - 同步清空后的永久撤销边界
+ * @param undoBoundaryCreatedAfter - 无数字 change id 时使用的严格时间边界
+ * @returns 可撤销的历史记录数组
+ *
+ * @remarks
+ * undoHistories$（UI 展示）与 undo()（实际执行）共用同一套规则，
+ * 保证 UI 上看不到的历史不会被 undo() 撤销：
+ * 1. history.reverted == false（按 updatedAt 水位合并持久态与本地态，未被撤销）
+ * 2. remoteId == null（只有本地创建的变更才能撤销）
+ * 3. id > 该 repository 的 lastPushedChangeId（未推送到远程；按 repository 独立判断）
+ * 4. id > undoBoundaryChangeId（同步清空前的历史永久不可撤销）
+ * 5. createdAt > undoBoundaryCreatedAfter（无数字 id 时保守隔离旧 session）
+ *
+ * @internal 供 HistoryManager 和单元测试使用
+ */
+export declare function filterUndoableHistories(histories: HistoryItem[], lastPushedMap: Map<string, number>, undoBoundaryChangeId?: number, undoBoundaryCreatedAfter?: Date | null): HistoryItem[];
+/**
+ * 生成作用域缓存键（纯函数）
+ *
+ * @param scope - 作用域配置
+ * @returns 缓存键字符串：'database' | 'namespace:entity' | 'namespace:entity:id'
+ *
+ * @internal 供 HistoryManager 和单元测试使用
+ */
+export declare function getScopeKey(scope: HistoryScope): string;
+//# sourceMappingURL=history-filters.d.ts.map

package/dist/history-filters.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history-filters.d.ts","sourceRoot":"","sources":["../src/history-filters.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAA4B,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AAE3F;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,GAAI,YAAY;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,KAAG,MACrC,CAAC;AAEjD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,SAAS;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EAAE,EAC9F,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GACpC,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAYrB;AAED;;;;;;;;GAQG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,WAAW,EAAE,EAAE,KAAK,EAAE,YAAY,GAAG,WAAW,EAAE,CA2BnG;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,WAAW,EAAE,EACxB,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAClC,oBAAoB,SAAI,EACxB,wBAAwB,GAAE,IAAI,GAAG,IAAW,GAC3C,WAAW,EAAE,CAcf;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,YAAY,GAAG,MAAM,CAQvD"}

package/dist/history-item-builder.d.ts

@@ -0,0 +1,25 @@
+import { HistoryItem, RxDBChange } from '@aiao/rxdb';
+/**
+ * 生成历史项的描述文本
+ *
+ * 规则：
+ * - 单条 INSERT/UPDATE/DELETE → 「创建 Foo」「更新 Foo」「删除 Foo」
+ * - 事务（多条变更）→ 「事务: 创建2条, 更新3条」
+ */
+export declare function generateHistoryDescription(changes: RxDBChange[]): string;
+/**
+ * 从一组同事务的变更构造单个 HistoryItem
+ *
+ * @param changes - 属于同一事务的变更记录（至少一条）
+ * @returns 结构化的历史项，包含描述、类型、状态等信息
+ */
+export declare function createHistoryItem(changes: RxDBChange[]): HistoryItem;
+/**
+ * 把按 id 降序排列的变更列表，转换为按事务分组的 HistoryItem 数组
+ *
+ * 转换逻辑：
+ * - 相同 transactionId 的连续变更合并为一个 HistoryItem
+ * - 无 transactionId 的变更单独成为一个 HistoryItem
+ */
+export declare function convertChangesToHistories(changes: RxDBChange[]): HistoryItem[];
+//# sourceMappingURL=history-item-builder.d.ts.map

package/dist/history-item-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history-item-builder.d.ts","sourceRoot":"","sources":["../src/history-item-builder.ts"],"names":[],"mappings":"AAAA,OAAO,EAA4B,WAAW,EAAE,UAAU,EAAQ,MAAM,YAAY,CAAC;AAErF;;;;;;GAMG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,MAAM,CAsBxE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,WAAW,CA0BpE;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,UAAU,EAAE,GAAG,WAAW,EAAE,CA0B9E"}

package/dist/history-scope-api.d.ts

@@ -0,0 +1,41 @@
+import { EntityType, HistoryItem, HistoryScope, HistoryScopeAPI } from '@aiao/rxdb';
+import { Observable } from 'rxjs';
+import { ActiveUndoSession, UndoBoundary, UndoSession } from './history-undo-session.types.js';
+/**
+ * `history()` 工厂所需的可变状态与委托。
+ *
+ * `history_cache` / `history_ref_counts` 是类持有的同一份 Map，sibling 的 set/delete 必须写回。
+ */
+export interface HistoryScopeApiHost {
+    readonly history_cache: Map<string, HistoryScopeAPI>;
+    readonly history_ref_counts: Map<string, number>;
+    readonly histories$: Observable<HistoryItem[]>;
+    readonly undoHistories$: Observable<HistoryItem[]>;
+    readonly redoHistories$: Observable<HistoryItem[]>;
+    readonly undoSession$: {
+        readonly value: UndoSession;
+    };
+    runSerialized<T>(task: () => Promise<T>): Promise<T>;
+    fetchLatestHistories(boundary: UndoBoundary): Promise<{
+        histories: HistoryItem[];
+        lastPushedMap: Map<string, number>;
+    }>;
+    isUndoSessionCurrent(session: ActiveUndoSession): boolean;
+    selectWholeTransactions(histories: HistoryItem[], scope: HistoryScope, step: number): HistoryItem[];
+    applyUndoRedoHistories(operation: 'undo' | 'redo', histories: HistoryItem[], undoSession?: ActiveUndoSession): Promise<void>;
+}
+/**
+ * 解析 `history()` 入参：无参 → database；显式 HistoryScope；否则 EntityType / 实例。
+ */
+export declare function resolveHistoryScope<T extends EntityType>(options?: T | InstanceType<T> | HistoryScope): HistoryScope;
+/**
+ * 创建（或从缓存取出）特定作用域的历史 API。
+ *
+ * @remarks
+ * 引用计数由 wrapObservable 对称管理（addRef / cleanup 成对出现），不再挂 finalize。
+ * 缓存条目的生死跟着引用计数走：第一个订阅者出现时入表，最后一个退订时摘掉。
+ * 因此「只调方法不订阅」的用法不产生任何常驻状态 —— 它拿到的是个短命对象，
+ * 用完即由 GC 回收。
+ */
+export declare function createHistoryScopeApi<T extends EntityType>(host: HistoryScopeApiHost, options?: T | InstanceType<T> | HistoryScope): HistoryScopeAPI;
+//# sourceMappingURL=history-scope-api.d.ts.map

package/dist/history-scope-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history-scope-api.d.ts","sourceRoot":"","sources":["../src/history-scope-api.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EAEV,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,KAAK,eAAe,EAErB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAuB,UAAU,EAAe,MAAM,MAAM,CAAC;AAEpE,OAAO,KAAK,EAAE,iBAAiB,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AACpG;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACrD,QAAQ,CAAC,kBAAkB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjD,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC,WAAW,EAAE,CAAC,CAAC;IAC/C,QAAQ,CAAC,cAAc,EAAE,UAAU,CAAC,WAAW,EAAE,CAAC,CAAC;IACnD,QAAQ,CAAC,cAAc,EAAE,UAAU,CAAC,WAAW,EAAE,CAAC,CAAC;IACnD,QAAQ,CAAC,YAAY,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAA;KAAE,CAAC;IACvD,aAAa,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACrD,oBAAoB,CAAC,QAAQ,EAAE,YAAY,GAAG,OAAO,CAAC;QACpD,SAAS,EAAE,WAAW,EAAE,CAAC;QACzB,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KACpC,CAAC,CAAC;IACH,oBAAoB,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC;IAC1D,uBAAuB,CAAC,SAAS,EAAE,WAAW,EAAE,EAAE,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,GAAG,WAAW,EAAE,CAAC;IACpG,sBAAsB,CACpB,SAAS,EAAE,MAAM,GAAG,MAAM,EAC1B,SAAS,EAAE,WAAW,EAAE,EACxB,WAAW,CAAC,EAAE,iBAAiB,GAC9B,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,UAAU,EAAE,OAAO,CAAC,EAAE,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,GAAG,YAAY,GAAG,YAAY,CAuBpH;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,UAAU,EACxD,IAAI,EAAE,mBAAmB,EACzB,OAAO,CAAC,EAAE,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,GAAG,YAAY,GAC3C,eAAe,CA+GjB"}

package/dist/history-undo-session.types.d.ts

@@ -0,0 +1,32 @@
+/**
+ * undo session 类型：按分支隔离的撤销边界。
+ *
+ * @internal 供 {@link HistoryManager} 与 undo/redo sibling 共用
+ */
+/** 同步清空后的永久撤销边界 */
+export type UndoBoundary = Readonly<{
+    changeId: number;
+    createdAfter: Date | null;
+}>;
+/** 当前可撤销的 session */
+export type ActiveUndoSession = Readonly<{
+    generation: number;
+    state: 'active';
+    boundary: UndoBoundary;
+}>;
+/** 同步后已清空、等待本地新写入再恢复的 session */
+export type ClearedUndoSession = Readonly<{
+    generation: number;
+    state: 'cleared';
+    boundary: UndoBoundary;
+    clearedAt: Date;
+}>;
+export type UndoSession = ActiveUndoSession | ClearedUndoSession;
+/** 本地写入事件携带的 session 归属信息 */
+export type UndoSessionEvent = Readonly<{
+    generation: number | null;
+    recordAt: Date | null;
+}>;
+/** 未发生过清空时的默认边界 */
+export declare const INITIAL_UNDO_BOUNDARY: UndoBoundary;
+//# sourceMappingURL=history-undo-session.types.d.ts.map

package/dist/history-undo-session.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history-undo-session.types.d.ts","sourceRoot":"","sources":["../src/history-undo-session.types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,mBAAmB;AACnB,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,IAAI,GAAG,IAAI,CAAC;CAC3B,CAAC,CAAC;AAEH,qBAAqB;AACrB,MAAM,MAAM,iBAAiB,GAAG,QAAQ,CAAC;IACvC,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,QAAQ,CAAC;IAChB,QAAQ,EAAE,YAAY,CAAC;CACxB,CAAC,CAAC;AAEH,iCAAiC;AACjC,MAAM,MAAM,kBAAkB,GAAG,QAAQ,CAAC;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,SAAS,CAAC;IACjB,QAAQ,EAAE,YAAY,CAAC;IACvB,SAAS,EAAE,IAAI,CAAC;CACjB,CAAC,CAAC;AAEH,MAAM,MAAM,WAAW,GAAG,iBAAiB,GAAG,kBAAkB,CAAC;AAEjE,6BAA6B;AAC7B,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,EAAE,IAAI,GAAG,IAAI,CAAC;CACvB,CAAC,CAAC;AAEH,mBAAmB;AACnB,eAAO,MAAM,qBAAqB,EAAE,YAAkD,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @packageDocumentation
+ * `@aiao/rxdb-plugin-history` —— 历史、撤销重做与分支。
+ *
+ * @remarks
+ * 核心 `@aiao/rxdb` 只保留**原语**：三张系统表（{@link RxDBBranch} / `RxDBChange` /
+ * `RxDBSync`）、变更编解码、冲突模型与同步资格判定。原因是这些东西并不属于历史子系统 ——
+ * 变更日志触发器直接写 `branchId`，`RxDBChange.branch` 会生成真实的
+ * `REFERENCES rxdb$rxdb_branch(id)` 外键，整条响应式增量链路都跑在 `rxdb_change` 上。
+ *
+ * 搬进本包的是**消费者**：读历史、撤销重做、建/切/合/删分支。
+ *
+ * 推拉同步的调度**不在这里**。US-025 阶段 D 之后它住在 `@aiao/rxdb-plugin-sync`：
+ * `rxdb.syncManager.push()` / `.pull()` / `.sync()`。那个插件 `inject: ['plugin:history']`，
+ * 反向则没有依赖——本包不认识同步包。
+ *
+ * @example
+ * ```ts
+ * import { rxDBPluginHistory } from '@aiao/rxdb-plugin-history';
+ *
+ * rxdb.use(rxDBPluginHistory);
+ * await rxdb.connect();
+ *
+ * // 撤销重做走作用域 API：无参 = 整库，传实体类 = 该仓储，传实例 = 该行
+ * await rxdb.versionManager.history().undo();
+ * ```
+ */
+export * from './plugin.js';
+export { RxDBCrossScopeTransactionError } from './scope-selection.js';
+export type { VersionManager } from './VersionManager.js';
+export { isIgnorableDetachedVersionEventError } from './detached-event-error.js';
+export { PushInFlightRegistry } from './push-inflight.js';
+export type { PushInFlightSession } from './push-inflight.js';
+export type { SyncHistoryBridge } from './sync-history-bridge.js';
+export { find_branch_path_to_root, find_switch_branch_step } from './find-switch-branch-step.js';
+export type { SwitchBranchStep } from './find-switch-branch-step.js';
+export { compute_switch_branch_actions, get_branch_max_change } from './switch-branch-actions.js';
+export type { SwitchBranchActionReaders } from './switch-branch-actions.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;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,cAAc,aAAa,CAAC;AAG5B,OAAO,EAAE,8BAA8B,EAAE,MAAM,sBAAsB,CAAC;AAEtE,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAQ1D,OAAO,EAAE,oCAAoC,EAAE,MAAM,2BAA2B,CAAC;AAGjF,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,YAAY,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC9D,YAAY,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAYlE,OAAO,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AACjG,YAAY,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,6BAA6B,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AAClG,YAAY,EAAE,yBAAyB,EAAE,MAAM,4BAA4B,CAAC"}