@aiao/rxdb-plugin-sync 0.0.0-stage → 0.0.26

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,82 @@
-# Temporary Holding Version
+# @aiao/rxdb-plugin-sync
 
-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.syncManager` 才存在。
+
+核心 `@aiao/rxdb` 保留的是**原语**：`RxDBSync` 水位表、变更编解码、冲突模型（`ConflictResolution` / `RxDBConflictError`）与同步资格判定。搬进本包的是**消费者**：整库与单仓库两个粒度的 push / pull / sync、冲突落地、依赖拓扑序、过期清理与 QueryCache 出站队列。
+
+## 安装
+
+```bash
+pnpm add @aiao/rxdb @aiao/rxdb-plugin-history @aiao/rxdb-plugin-sync
+```
+
+`@aiao/rxdb-plugin-history` 不是可选的：本包声明 `inject: ['plugin:history']`。
+
+## 使用
+
+```typescript
+import { RxDB, SyncType } from '@aiao/rxdb';
+import { rxDBPluginHistory } from '@aiao/rxdb-plugin-history';
+import { rxDBPluginSync } from '@aiao/rxdb-plugin-sync';
+
+const rxdb = new RxDB({
+  dbName: 'notes',
+  entities: [Note],
+  sync: { type: SyncType.Full, local: { adapter: 'wa-sqlite' }, remote: { adapter: 'supabase' } }
+});
+
+// 传工厂函数本身，不要调用它；两句 use() 的先后随意——宿主按 inject 拓扑排序
+rxdb.use(rxDBPluginHistory).use(rxDBPluginSync).adapter('wa-sqlite' /* … */);
+
+await rxdb.connect('wa-sqlite');
+
+await rxdb.syncManager.sync();
+await rxdb.syncManager.pushRepository('public', 'note');
+```
+
+`use()` 必须早于 `connect()`——`connect()` 内部就会调 `init()`。
+
+`connect()` 返回之前本包的 `install()` 一定跑完，这一点比没有 `inject` 的插件更值得留意：声明了依赖的插件**不在** `init()` 里安装，它要等历史插件装好、状态转 `active`，宿主再对齐一趟才轮到它。`rxdb.init()` 之后紧接着读 `rxdb.syncManager` 会读到 `undefined`，那不是缺陷而是时序——`connect()` 是这条链的静止点。
+
+## 主要能力
+
+| 分组     | 入口                                                                                          |
+| -------- | --------------------------------------------------------------------------------------------- |
+| 推拉     | `push()` / `pull()` / `sync()` / `pushRepository()` / `pullRepository()` / `syncRepository()` |
+| 批量     | `bulkSync()` / `getRepositoryDependencyGraph()` / `getRepositorySyncOrder()`                  |
+| 仓储状态 | `getRepositorySyncStatus()` / `getAllRepositorySyncStatus()` / `checkRepositoryUpdates()`     |
+| 分支     | `syncBranches()`                                                                              |
+| 计数     | `refreshPullableCount()`                                                                      |
+| 清理     | `cleanupExpired()`                                                                            |
+
+水位线是 `RxDBSync.lastPushedChangeId`，push 与 QueryCache 出站共用同一条——两者都在把本地变更送去远端，各记一条水位会让「已推到哪」在同一张表上有两个答案。
+
+## 与历史插件的关系
+
+单向：本包 `inject: ['plugin:history']`，历史包不认识本包。耦合只走一张窄接口（`SyncHistoryBridge`）——一次往返结束时 undo 边界要作废、待拉计数要结算，而那些状态的主人在历史侧。
+
+两件事的生命周期本就不同，所以它们各自成包：撤销重做要在第一条 `rxdb_change` 之前就位（历史插件因此**不**声明任何 `inject`），推拉同步则只在配了远端时才有意义。
+
+## 与 QueryCache 插件的关系
+
+只有 `import type { QueryCacheRemoteAdapter }`，**不产生** `inject` 运行期依赖。装了本包、没装 `@aiao/rxdb-plugin-querycache` 且没有 QueryCache 实体的工作区照常运行。
+
+## 没装插件时
+
+`rxdb.syncManager` **不存在**（读到 `undefined`），核心不给一个什么都不做的空壳。
+
+只装了本包、忘了装历史插件时，本包停在 `waiting` 永远装不上——依赖来源尘埃落定后宿主会点名一次：
+
+```
+[RxDB] Plugin 'sync' is not installed: unsatisfied dependencies [plugin:history]
+```
+
+`syncState` 面板上的待拉数由本包维护：远端适配器在实时订阅恢复后发 `syncState.requestPullableRefresh()`，本包接住它并调 `refreshPullableCount()`。没装本包，那个读数就是无人维护——这正是实情，不是零。
+
+## 连接纪元
+
+插件声明 `lifecycle: 'scoped'`，三处宿主改动全部登记在 `install(scope)` 收到的作用域上，`disconnectAll()` 时逆序释放，宿主不调用 `destroy()`：`SyncManager` 实例本身（`destroy()` 随它撤掉 `connected$` 自动回推订阅与远端事件监听）、`rxdb.syncManager` 槽位、`syncState.bindPullableRefresh()` 跳板。释放走逆拓扑序，本包先于历史插件撤销。
+
+重新 `connect()` 装的是一个全新的管理器，而不是复活上一纪元那个——后者指向的事件总线已经拆了。

package/dist/SyncManager.d.ts

@@ -0,0 +1,412 @@
+import { PullOptions, PullResult, PushOptions, PushResult, RxDB, SyncResult } from '@aiao/rxdb';
+import { PushInFlightRegistry, SyncHistoryBridge } from '@aiao/rxdb-plugin-history';
+import { BulkSyncOptions, BulkSyncResult } from './bulk-sync.js';
+import { CheckRepositoryUpdatesResult } from './check-repository-updates.js';
+import { CleanupExpiredOptions, CleanupExpiredResult } from './cleanup-expired.js';
+import { DependencyGraph, RepositoryIdentifier } from './dependency-graph.js';
+import { GetAllRepositorySyncStatusFilter } from './get-all-repository-sync-status.js';
+import { RepositorySyncStatus } from './get-repository-sync-status.js';
+import { PullRepositoryOptions, PullRepositoryResult } from './pull-repository.js';
+import { PushRepositoryOptions, PushRepositoryResult } from './push-repository.js';
+import { SyncBranchesResult } from './sync-branches.js';
+import { SyncRepositoryOptions, SyncRepositoryResult } from './sync-repository.js';
+import { SortDirection } from './topological-sort.js';
+/**
+ * 同步管理器
+ *
+ * 负责整库与单仓库两个粒度的推拉同步：
+ * - `pull` / `push` / `sync`：整库
+ * - `pullRepository` / `pushRepository` / `syncRepository` / `bulkSync`：按仓库
+ * - `getRepositorySyncStatus` / `checkRepositoryUpdates` / `cleanupExpired`：状态与清理
+ * - `getRepositoryDependencyGraph` / `getRepositorySyncOrder`：依赖图与同步顺序
+ *
+ * @remarks
+ * US-025 阶段 D 之前这些入口挂在 `@aiao/rxdb-plugin-history` 的 `VersionManager` 上。
+ * 切开的理由是两件事的生命周期本就不同：撤销重做要在第一条 `rxdb_change` 之前就位，
+ * 推拉同步则只在配了远端时才有意义。
+ *
+ * 切开之后仍有一条**单向**耦合：一次同步往返结束时 undo 边界要作废、待拉计数要结算，
+ * 而那些状态的主人是历史侧。它经 {@link SyncHistoryBridge} 这一张窄接口相遇 ——
+ * 本插件 `inject: ['plugin:history']`，历史插件则对本包一无所知。
+ */
+export declare class SyncManager {
+    #private;
+    readonly rxdb: RxDB;
+    readonly history: SyncHistoryBridge;
+    /**
+     * 「哪些变更此刻正在飞往远端」的登记处。
+     *
+     * @remarks
+     * push 与 undo 唯一的会合点，实例的主人在历史侧（`rxdb.versionManager.pushInFlight`）。
+     * 两边读的必须是同一个，见 `PushInFlightRegistry`：push 在远端往返之前认领区间，
+     * undo 把认领区间当成已推 —— 各持一份，往返窗口内的一次撤销就会造成永久分叉。
+     *
+     * @internal
+     */
+    get pushInFlight(): PushInFlightRegistry;
+    /**
+     * @param rxdb - 宿主实例
+     * @param history - 历史侧借来的那一小块面，由 `rxdb.versionManager.syncBridge` 提供
+     */
+    constructor(rxdb: RxDB, history: SyncHistoryBridge);
+    /** 装上 connected$ 自动回推与远端事件计数两条链路 */
+    init(): void;
+    /** 拆掉 {@link init} 装上的全部监听与订阅 */
+    destroy(): void;
+    /** 取本地适配器上的系统表仓库 */
+    getLocalRepositories(): Promise<{
+        branchRepository: import('@aiao/rxdb').LocalRxDBBranchRepository;
+        changeRepository: import('@aiao/rxdb').LocalRxDBChangeRepository;
+        adapter: import('@aiao/rxdb').IRxDBAdapter & import('@aiao/rxdb').RxDBAdapterLocalBase;
+    }>;
+    /** 取远端适配器上的系统表仓库 */
+    getRemoteRepositories(): Promise<{
+        branchRepository: import('@aiao/rxdb').RemoteRxDBBranchRepository;
+        changeRepository: import('@aiao/rxdb').RemoteRxDBChangeRepository;
+        adapter: import('@aiao/rxdb').IRxDBAdapter & import('@aiao/rxdb').RxDBAdapterRemoteBase;
+    }>;
+    /**
+     * 取当前分支；没有激活分支时激活（或新建）`main`。
+     *
+     * @remarks
+     * 同步链路里每条远端事件都要调它（`sync-listeners` 的 `filterByBranch`），
+     * 热路径不开事务，见 `getCurrentBranch`。
+     */
+    getCurrentBranch(): Promise<import('@aiao/rxdb').RxDBBranch>;
+    /**
+     * 从远程同步所有分支信息到本地
+     *
+     * 远程新分支 → 在本地创建（local: false, remote: true）
+     * 本地已有的远程分支 → 更新 remote 标记为 true
+     * 纯本地分支 → 不受影响
+     *
+     * @returns 同步结果
+     *
+     * @example
+     * ```typescript
+     * const result = await rxdb.syncManager.syncBranches();
+     * console.log(`新增 ${result.created}，更新 ${result.updated}`);
+     * ```
+     */
+    syncBranches(): Promise<SyncBranchesResult>;
+    /**
+     * 从远程拉取变更并应用到本地数据库
+     *
+     * 当 autoSync=false 时，会先应用 Realtime 缓存的变更，再拉取远程变更。
+     *
+     * @param options - 可选配置
+     * @returns 拉取结果
+     *
+     * @example
+     * ```typescript
+     * // 基本用法
+     * const result = await rxdb.syncManager.pull();
+     * console.log(`Pulled ${result.pulled} changes`);
+     *
+     * // 拉取所有数据
+     * const result = await rxdb.syncManager.pull({ fetchAll: true });
+     * ```
+     */
+    pull(options?: PullOptions): Promise<PullResult>;
+    /**
+     * 将本地未同步的变更推送到远程数据库
+     *
+     * 推送时会自动：
+     * 1. 查询 lastPushedChangeId 之后的新变更
+     * 2. 过滤已撤销的变更（revertChangeId != null）
+     * 3. 压缩变更（INSERT→DELETE 丢弃，INSERT→UPDATE* 合并为 INSERT）
+     * 4. 批量推送到远程
+     * 5. 更新 lastPushedChangeId 和 lastPushedAt
+     *
+     * @param options - 可选配置
+     * @returns 推送结果
+     *
+     * @example
+     * ```typescript
+     * // 基本用法
+     * const result = await rxdb.syncManager.push();
+     * console.log(`Pushed ${result.pushed} changes`);
+     *
+     * // 自定义批量大小
+     * const result = await rxdb.syncManager.push({ batchSize: 500 });
+     * ```
+     */
+    push(options?: PushOptions): Promise<PushResult>;
+    /**
+     * 执行完整的同步操作（先 pull 再 push）
+     *
+     * 推荐在重连后使用此方法，确保：
+     * 1. 先获取远程最新变更（避免覆盖他人数据）
+     * 2. 再推送本地变更
+     *
+     * @param options - 可选配置
+     * @returns 同步结果（包含 pull 和 push 结果）
+     *
+     * @example
+     * ```typescript
+     * // 基本用法
+     * const result = await rxdb.syncManager.sync();
+     * console.log(`Pulled ${result.pullResult.pulled}, Pushed ${result.pushResult.pushed}`);
+     * ```
+     */
+    sync(options?: {
+        pull?: PullOptions;
+        push?: PushOptions;
+    }): Promise<SyncResult>;
+    /**
+     * 拉取指定 Repository 的远程变更
+     *
+     * 提供实体类型级别的精细同步控制，支持级联同步以自动拉取关联实体。
+     *
+     * @param namespace - 实体命名空间（如 "public"）
+     * @param entity - 实体名称（如 "Todo"）
+     * @param options - 拉取选项
+     * @returns 拉取结果
+     *
+     * @example
+     * ```typescript
+     * // 拉取 Todo 并级联拉取依赖
+     * const result = await rxdb.syncManager.pullRepository('public', 'Todo', {
+     *   includeRelated: true // 默认：若 Todo 有外键则自动拉取 User
+     * });
+     *
+     * // 不级联拉取
+     * const result = await rxdb.syncManager.pullRepository('public', 'Todo', {
+     *   includeRelated: false // 仅拉取 Todo，可能引发外键错误
+     * });
+     * ```
+     */
+    pullRepository(namespace: string, entity: string, options?: PullRepositoryOptions): Promise<PullRepositoryResult>;
+    /**
+     * 推送指定 Repository 的本地变更
+     *
+     * 提供实体类型级别的精细同步控制，支持级联同步以自动推送依赖实体。
+     *
+     * @param namespace - 实体命名空间（如 "public"）
+     * @param entity - 实体名称（如 "User"）
+     * @param options - 推送选项
+     * @returns 推送结果
+     *
+     * @example
+     * ```typescript
+     * // 推送 User 并级联推送依赖方
+     * const result = await rxdb.syncManager.pushRepository('public', 'User', {
+     *   includeRelated: true // 默认：若 Post 引用 User 则自动推送 Post
+     * });
+     *
+     * // 不级联推送
+     * const result = await rxdb.syncManager.pushRepository('public', 'User', {
+     *   includeRelated: false // 仅推送 User，依赖数据可能不完整
+     * });
+     * ```
+     */
+    pushRepository(namespace: string, entity: string, options?: PushRepositoryOptions): Promise<PushRepositoryResult>;
+    /**
+     * 同步指定 Repository（先 pull 再 push）
+     *
+     * 将单个 Repository 的 pull 和 push 合并为一次操作，保证正确的执行顺序。
+     * 推荐在需要确保特定实体类型数据一致性时使用。
+     *
+     * @param namespace - 实体命名空间（如 "public"）
+     * @param entity - 实体名称（如 "Todo"）
+     * @param options - 同步选项（分别配置 pull 和 push）
+     * @returns 同步结果（包含 pull 和 push 结果）
+     *
+     * @example
+     * ```typescript
+     * // 基本用法
+     * const result = await rxdb.syncManager.syncRepository('public', 'Todo');
+     * console.log(`Pulled ${result.pullResult.pulled}, Pushed ${result.pushResult.pushed}`);
+     *
+     * // 自定义 pull 和 push 选项
+     * const result = await rxdb.syncManager.syncRepository('public', 'Todo', {
+     *   pull: { limit: 500, fetchAll: true },
+     *   push: { batchSize: 100 }
+     * });
+     * ```
+     */
+    syncRepository(namespace: string, entity: string, options?: SyncRepositoryOptions): Promise<SyncRepositoryResult>;
+    /**
+     * 清理不再满足过滤条件的本地过期数据
+     *
+     * 用于 SyncType.Filter 场景，删除不满足 filter 条件的本地数据
+     * 例如：清理超过 30 天的订单数据
+     *
+     * @param namespace - 实体命名空间
+     * @param entity - 实体名称
+     * @param options - 清理选项
+     * @returns 清理结果
+     *
+     * @example
+     * ```ts
+     * const thirtyDaysAgo = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
+     * const { removed } = await rxdb.syncManager.cleanupExpired('public', 'Order', {
+     *   filter: {
+     *     combinator: 'and',
+     *     rules: [{ field: 'updatedAt', operator: '>=', value: thirtyDaysAgo }]
+     *   }
+     * });
+     * console.log(`Removed ${removed} expired records`);
+     * ```
+     */
+    cleanupExpired(namespace: string, entity: string, options?: CleanupExpiredOptions): Promise<CleanupExpiredResult>;
+    /**
+     * 检查远程是否有更新，不下载数据
+     *
+     * 仅查询远程有多少新变更，不实际拉取数据。
+     * 适用于显示「有 N 条远程更新」提示，节省带宽和时间。
+     *
+     * @param namespace - 实体命名空间（如 "public"）
+     * @param entity - 实体名称（如 "Todo"）
+     * @returns 更新检查结果
+     *
+     * @example
+     * ```typescript
+     * // 检查 Todo 是否有远程更新
+     * const result = await rxdb.syncManager.checkRepositoryUpdates('public', 'Todo');
+     * if (result.hasUpdates) {
+     *   console.log(`有 ${result.pendingCount} 条更新可拉取`);
+     *   // 用户点击「更新」按钮后再调用 pullRepository()
+     * }
+     * ```
+     */
+    checkRepositoryUpdates(namespace: string, entity: string): Promise<CheckRepositoryUpdatesResult>;
+    /**
+     * 获取单个 Repository 的同步状态
+     *
+     * 返回完整的同步状态信息，包括：
+     * - syncType（full/remote/local/disabled）
+     * - pushableCount（待推送的本地变更数）
+     * - pullableCount（可拉取的远程变更数）
+     * - 最近同步时间戳
+     *
+     * @param namespace - 实体命名空间（如 "public"）
+     * @param entity - 实体名称（如 "Todo"）
+     * @returns Repository 同步状态
+     *
+     * @example
+     * ```typescript
+     * const status = await rxdb.syncManager.getRepositorySyncStatus('public', 'Todo');
+     * console.log(`同步类型: ${status.syncType}`);
+     * console.log(`待推送: ${status.pushableCount}，可拉取: ${status.pullableCount}`);
+     * ```
+     */
+    getRepositorySyncStatus(namespace: string, entity: string): Promise<RepositorySyncStatus>;
+    /**
+     * 获取所有 Repository 的同步状态
+     *
+     * 返回所有已注册实体的状态，支持可选过滤。
+     *
+     * @param filter - 可选过滤条件
+     * @returns Repository 同步状态数组
+     *
+     * @example
+     * ```typescript
+     * // 获取全部状态
+     * const statuses = await rxdb.syncManager.getAllRepositorySyncStatus();
+     *
+     * // 仅获取有待处理变更的 Repository
+     * const pending = await rxdb.syncManager.getAllRepositorySyncStatus({
+     *   hasPendingChanges: true
+     * });
+     *
+     * // 仅获取已启用的全量同步 Repository
+     * const fullSync = await rxdb.syncManager.getAllRepositorySyncStatus({
+     *   syncType: ['full'],
+     *   enabled: true
+     * });
+     * ```
+     */
+    getAllRepositorySyncStatus(filter?: GetAllRepositorySyncStatusFilter): Promise<RepositorySyncStatus[]>;
+    /**
+     * 按各仓库持久化的远端水位线重新计算待拉变更数
+     *
+     * @returns 当前远端待拉变更总数
+     *
+     * @remarks
+     * 远程适配器在实时订阅恢复后调用。若刷新期间又收到实时事件，保留两者中的较大值，
+     * 避免把查询快照之后到达的通知覆盖掉。
+     */
+    refreshPullableCount(): Promise<number>;
+    /**
+     * 批量同步多个 Repository
+     *
+     * 在单次操作中同步多个 Repository，支持顺序或并发执行。
+     *
+     * @param options - 批量同步选项
+     * @returns 批量同步结果（包含成功/失败计数）
+     *
+     * @example
+     * ```typescript
+     * // 顺序同步所有已启用的 Repository
+     * const result = await rxdb.syncManager.bulkSync();
+     * console.log(`成功: ${result.succeeded}，失败: ${result.failed}`);
+     *
+     * // 同步指定 Repository
+     * const result = await rxdb.syncManager.bulkSync({
+     *   repositories: [
+     *     { namespace: 'public', entity: 'Todo' },
+     *     { namespace: 'public', entity: 'User' }
+     *   ]
+     * });
+     *
+     * // 并发模式仅 pull
+     * const result = await rxdb.syncManager.bulkSync({
+     *   concurrent: true,
+     *   concurrency: 3,
+     *   push: false
+     * });
+     *
+     * // 检查每项结果
+     * for (const item of result.results) {
+     *   if (item.success) {
+     *     console.log(`${item.repository.entity}: 已拉取 ${item.result?.pullResult.pulled ?? 0} 条`);
+     *   } else {
+     *     console.error(`${item.repository.entity}: ${item.error.message}`);
+     *   }
+     * }
+     * ```
+     */
+    bulkSync(options?: BulkSyncOptions): Promise<BulkSyncResult>;
+    /**
+     * 获取所有 Repository 的依赖图
+     *
+     * 分析实体关系（MANY_TO_ONE、ONE_TO_ONE）以构建依赖图，
+     * 展示各 Repository 之间的依赖关系。
+     *
+     * @returns 包含依赖关系的依赖图
+     *
+     * @example
+     * ```typescript
+     * const graph = rxdb.syncManager.getRepositoryDependencyGraph();
+     *
+     * // 遍历依赖关系
+     * for (const [key, dep] of graph) {
+     *   console.log(`${key} 依赖:`, dep.dependsOn);
+     *   console.log(`${key} 被依赖:`, dep.requiredBy);
+     * }
+     * ```
+     */
+    getRepositoryDependencyGraph(): DependencyGraph;
+    /**
+     * 根据依赖关系获取 Repository 的同步顺序
+     *
+     * 通过拓扑排序确定基于依赖关系的正确同步顺序。
+     *
+     * @param direction - 排序方向：'pull'（父节点优先）或 'push'（子节点优先）
+     * @returns 有序的 Repository 列表
+     *
+     * @example
+     * ```typescript
+     * // 获取 pull 顺序（父节点优先）
+     * const pullOrder = rxdb.syncManager.getRepositorySyncOrder('pull');
+     * // [User, Todo, Comment]
+     *
+     * // 获取 push 顺序（子节点优先）
+     * const pushOrder = rxdb.syncManager.getRepositorySyncOrder('push');
+     * // [Comment, Todo, User]
+     * ```
+     */
+    getRepositorySyncOrder(direction: SortDirection): RepositoryIdentifier[];
+}
+//# sourceMappingURL=SyncManager.d.ts.map

package/dist/SyncManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SyncManager.d.ts","sourceRoot":"","sources":["../src/SyncManager.ts"],"names":[],"mappings":"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"}

package/dist/branch-change-id.d.ts

@@ -0,0 +1,31 @@
+import { IRepository, RxDBChange } from '@aiao/rxdb';
+/** 本模块只依赖 change 仓库的 `find`，用最小接口收窄，便于在事务 executor 上复用。 */
+type ChangeFinder = Pick<IRepository<typeof RxDBChange>, 'find'>;
+/**
+ * 本地分叉点 → 远端 change id。
+ *
+ * @param repository - 本地 `RxDBChange` 仓库
+ * @param localFromChangeId - 本地分支的 `fromChangeId`
+ * @returns 远端 id；分叉点尚未推送（`remoteId` 为空）时返回 `null`
+ * @throws RxDBError 本地压根不存在这条变更 —— 这是分支表与变更表已经不一致，不能猜
+ *
+ * @remarks
+ * 返回 `null` 表示「远端此刻确实不知道这个分叉点」，而不是「分叉点在根」。调用方要据此
+ * 决定是否在实体变更推送完成后重推一次分支，见 {@link pushBranch}。
+ */
+export declare const toRemoteFromChangeId: (repository: ChangeFinder, localFromChangeId: number) => Promise<number | null>;
+/**
+ * 远端分叉点 → 本地 change id。
+ *
+ * @param repository - 本地 `RxDBChange` 仓库（事务内请传 executor 作用域的那一份）
+ * @param remoteFromChangeId - 远端分支行上的 `fromChangeId`
+ * @returns 本地 id；对应的变更尚未拉到本地时返回 `null`
+ *
+ * @remarks
+ * 返回 `null` 时**不可**退化成 `null`/`0` 写进本地分支行：`find-switch-branch-step` 会把它
+ * 当「分叉于根」处理，切换分支时应用的区间从第一条变更起算。调用方应跳过该分支，
+ * 等分叉点变更拉到本地后的下一轮再建。
+ */
+export declare const toLocalFromChangeId: (repository: ChangeFinder, remoteFromChangeId: number) => Promise<number | null>;
+export {};
+//# sourceMappingURL=branch-change-id.d.ts.map

package/dist/branch-change-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-change-id.d.ts","sourceRoot":"","sources":["../src/branch-change-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,KAAK,WAAW,EAAE,UAAU,EAAa,MAAM,YAAY,CAAC;AACrE,2DAA2D;AAC3D,KAAK,YAAY,GAAG,IAAI,CAAC,WAAW,CAAC,OAAO,UAAU,CAAC,EAAE,MAAM,CAAC,CAAC;AAcjE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,oBAAoB,GAC/B,YAAY,YAAY,EACxB,mBAAmB,MAAM,KACxB,OAAO,CAAC,MAAM,GAAG,IAAI,CAMvB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,GAC9B,YAAY,YAAY,EACxB,oBAAoB,MAAM,KACzB,OAAO,CAAC,MAAM,GAAG,IAAI,CAGvB,CAAC"}

package/dist/branch-utils.d.ts

@@ -0,0 +1,8 @@
+import { SyncManager } from './SyncManager.js';
+/**
+ * 获取当前分支及其所有祖先分支的 ID 列表
+ *
+ * @returns [currentBranch, parent, grandparent, ...] 例如 ['dev', 'main']
+ */
+export declare function getAncestorBranchIds(sm: SyncManager, branchId: string): Promise<string[]>;
+//# sourceMappingURL=branch-utils.d.ts.map

package/dist/branch-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-utils.d.ts","sourceRoot":"","sources":["../src/branch-utils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;;;GAIG;AACH,wBAAsB,oBAAoB,CAAC,EAAE,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CA4B/F"}