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

package/dist/plugin.d.ts

@@ -0,0 +1,70 @@
+import { IRxDBPlugin, Plugin, RxDBPluginBase } from '@aiao/rxdb';
+import { LifecycleScope } from '@aiao/utils';
+import { SyncManager } from './SyncManager.js';
+/** 本插件当前不接受任何选项 */
+export type RxDBPluginSyncOptions = object;
+/**
+ * 推拉同步 / 冲突 / 仓库依赖序插件。
+ *
+ * @remarks
+ * **声明 `inject: ['plugin:history']`**，且只声明这一条：
+ *
+ * - 要历史插件，是因为一次往返结束时 undo 边界要作废、待拉计数要结算，而那些状态的主人
+ *   在历史侧。{@link SyncManager} 拿的是 `rxdb.versionManager.syncBridge` 这张窄接口，
+ *   没有它连构造都无从谈起。依赖缺失时宿主不装本插件、只告警一次，`rxdb.syncManager`
+ *   这个槽位于是不存在——没有历史就没有同步，这正是实情。
+ * - **不要 `adapter:remote`**：同步入口本身是按调用发起的，装配阶段一条适配器读写都不发；
+ *   而 {@link SyncManager.init} 挂的 `connected$` 自动回推订阅必须在第一次连接就位之前
+ *   就已经订阅上，声明适配器依赖会把安装推到引导链之后，第一次连接的那一跳回推就丢了。
+ *
+ * 五处宿主改动都登记在 `scope` 上，断开连接时由宿主逆序释放：
+ *
+ * 1. `rxdb.syncManager` 这个实例槽位 —— 释放时连同 `destroy()` 一起撤掉，不给下一个纪元
+ *    留一个指向已拆事件总线的管理器；
+ * 2. {@link RxDB.syncState} 上的「重算待拉数」跳板 —— 远端适配器在实时订阅恢复后按
+ *    `syncState.requestPullableRefresh()` 发信号，它不认识 {@link SyncManager}，接住这一跳
+ *    是本插件的活（US-025 阶段 D 之前这条绑定在历史插件上，随 `refreshPullableCount` 一起
+ *    搬过来）。没装插件时那个请求发进空里，正是「待拉数无人维护」的实情。
+ * 3. {@link RxDB.queryCacheOutbox} 这个出站队列槽 —— QueryCache 实体的读引擎要靠它把
+ *    「远端没返回」和「本地离线写过」区分开。这一条**没有**缺席形态：槽空着时核心在
+ *    `connect()` 就抛 `RxDBMissingPluginError`，因为「当空集」等于把每条离线写都当孤儿删掉。
+ * 4. 宿主的 `online` / `offline` 监听 —— `ReachabilityMonitor` 只在有人 `watch()` 时才往
+ *    `globalThis` 上挂，而这两个事件唯一的消费者是本包的同步监听器（`wakeup$` 驱动回推
+ *    重试）。不同步的库不该因为 `new RxDB()` 就永久多一对活过实例的监听器（US-025 D2）。
+ */
+export declare class RxDBPluginSync extends RxDBPluginBase implements IRxDBPlugin {
+    readonly lifecycle: "scoped";
+    readonly inject: readonly ["plugin:history"];
+    name: Uncapitalize<string>;
+    install(scope: LifecycleScope): void;
+}
+declare module '@aiao/rxdb' {
+    interface RxDB {
+        /**
+         * 推拉同步子系统。
+         *
+         * @remarks
+         * 由 `@aiao/rxdb-plugin-sync` 在连接纪元内装配。**没装插件（或没装它依赖的
+         * `@aiao/rxdb-plugin-history`）时这个槽位不存在**：读它拿到 `undefined`，
+         * 而不是一个什么都不做的空壳——核心不做 fallback 兜底。
+         */
+        syncManager: SyncManager;
+    }
+}
+/**
+ * 同步插件工厂。
+ *
+ * @param db - 宿主实例
+ *
+ * @example
+ * ```ts
+ * import { rxDBPluginHistory } from '@aiao/rxdb-plugin-history';
+ * import { rxDBPluginSync } from '@aiao/rxdb-plugin-sync';
+ *
+ * // 顺序随意：宿主按 `inject` 拓扑排序，历史插件一定先装完。
+ * rxdb.use(rxDBPluginSync);
+ * rxdb.use(rxDBPluginHistory);
+ * ```
+ */
+export declare const rxDBPluginSync: Plugin<RxDBPluginSyncOptions>;
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,EAAQ,cAAc,EAAE,MAAM,YAAY,CAAC;AACvE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAElD,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C,mBAAmB;AACnB,MAAM,MAAM,qBAAqB,GAAG,MAAM,CAAC;AAE3C;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,qBAAa,cAAe,SAAQ,cAAe,YAAW,WAAW;IACvE,QAAQ,CAAC,SAAS,EAAG,QAAQ,CAAU;IACvC,QAAQ,CAAC,MAAM,8BAA+B;IAC9C,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,CAAU;IAEpC,OAAO,CAAC,KAAK,EAAE,cAAc;CA2C9B;AAED,OAAO,QAAQ,YAAY,CAAC;IAC1B,UAAU,IAAI;QACZ;;;;;;;WAOG;QACH,WAAW,EAAE,WAAW,CAAC;KAC1B;CACF;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,cAAc,EAAE,MAAM,CAAC,qBAAqB,CAAwC,CAAC"}

package/dist/pull-ancestor-changes.d.ts

@@ -0,0 +1,41 @@
+import { RemoteChange, RuleGroup, RxDBAdapterRemoteBase } from '@aiao/rxdb';
+/**
+ * 一个仓库跨祖先分支拉取变更所需的全部参数。
+ */
+export interface AncestorPullRequest {
+    /** 仓库命名空间 */
+    namespace: string;
+    /** 实体名 */
+    entity: string;
+    /** 水位线：只拉 id 大于它的变更 */
+    sinceId: number;
+    /** 本轮最多消费多少条 */
+    limit: number;
+    /** 行级过滤条件，`SyncType.Filter` 用；批量路径不支持，故为可选 */
+    filter?: RuleGroup;
+}
+/**
+ * 跨祖先分支拉取**单个仓库**的远端变更，合并成一条按 id 递增、长度不超过 `limit` 的序列。
+ *
+ * @param remoteAdapter - 远端适配器
+ * @param request - 仓库标识、水位线、批量大小与可选行级过滤
+ * @param branchIds - 当前分支及其全部祖先，见 `getAncestorBranchIds`
+ * @returns 合并、排序、截断后的变更序列
+ *
+ * @remarks
+ * **为什么必须逐祖先分支拉。** 分支是 patch 模型，不是快照模型：建分支时只写
+ * `parentId` + `fromChangeId`，一条变更都不复制。所以 feature 分支上可见的数据 =
+ * 父分支在分叉点之前的变更 + feature 自己的变更，而父分支那些记录**物理上仍然
+ * 归属 `branchId='main'`**。`pullChanges` 的 `branchId` 是精确匹配（见其接口契约），
+ * 只传当前分支就永远收不到别人推到 main 的更新 —— 且不会自愈：切回 main 时水位线
+ * 换成了 `${ns}:${entity}:main` 这条**另一个**记录，那段区间从此跳过。
+ *
+ * **为什么合并后必须全局排序再截断。** 每个分支各自取满 `limit` 条，直接拼接会让
+ * 某个分支的高 id 把共享水位线推过另一个分支尚未消费的低 id；那些变更此后都不再满足
+ * `id > lastPullRemoteChangeId`，被永久跳过。排序后只消费前 `limit` 条，其余留给下一轮 ——
+ * 调用方据 `length >= limit` 置 `hasMore` 继续循环。
+ *
+ * 单分支（在 main 上）时只发一次请求，与逐祖先的写法结果一致，不额外分支判断。
+ */
+export declare function pullAncestorBranchChanges(remoteAdapter: RxDBAdapterRemoteBase, request: AncestorPullRequest, branchIds: readonly string[]): Promise<RemoteChange[]>;
+//# sourceMappingURL=pull-ancestor-changes.d.ts.map

package/dist/pull-ancestor-changes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pull-ancestor-changes.d.ts","sourceRoot":"","sources":["../src/pull-ancestor-changes.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAE,KAAK,SAAS,EAAE,KAAK,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAC3F;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,aAAa;IACb,SAAS,EAAE,MAAM,CAAC;IAElB,UAAU;IACV,MAAM,EAAE,MAAM,CAAC;IAEf,uBAAuB;IACvB,OAAO,EAAE,MAAM,CAAC;IAEhB,gBAAgB;IAChB,KAAK,EAAE,MAAM,CAAC;IAEd,8CAA8C;IAC9C,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,yBAAyB,CAC7C,aAAa,EAAE,qBAAqB,EACpC,OAAO,EAAE,mBAAmB,EAC5B,SAAS,EAAE,SAAS,MAAM,EAAE,GAC3B,OAAO,CAAC,YAAY,EAAE,CAAC,CAYzB"}

package/dist/pull-batch.d.ts

@@ -0,0 +1,16 @@
+import { ConflictResolver, PullResult } from '@aiao/rxdb';
+import { SyncManager } from './SyncManager.js';
+/**
+ * 批量拉取所有实体的变更。
+ *
+ * @param sm - SyncManager 实例
+ * @param options.limit - 每个实体单轮的最大变更数，默认 1000
+ * @param options.fetchAll - 为真时循环拉取直到远端排空；默认只拉一轮并用 `hasMore` 告知还有剩余
+ * @returns 各轮累加后的拉取结果
+ */
+export declare function pullBatch(sm: SyncManager, options?: {
+    limit?: number;
+    fetchAll?: boolean;
+    conflictResolver?: ConflictResolver;
+}): Promise<PullResult>;
+//# sourceMappingURL=pull-batch.d.ts.map

package/dist/pull-batch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pull-batch.d.ts","sourceRoot":"","sources":["../src/pull-batch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAEL,KAAK,gBAAgB,EAQrB,KAAK,UAAU,EAOhB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AA8BpD;;;;;;;GAOG;AACH,wBAAsB,SAAS,CAC7B,EAAE,EAAE,WAAW,EACf,OAAO,CAAC,EAAE;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAAC,gBAAgB,CAAC,EAAE,gBAAgB,CAAA;CAAE,GACpF,OAAO,CAAC,UAAU,CAAC,CA8CrB"}

package/dist/pull-conflict-utils.d.ts

@@ -0,0 +1,43 @@
+import { ConflictResolver, IRepository, RemoteChange, RxDBChange, RxDBEntityId, RxDBEvent, SwitchVersionActions, SwitchVersionChange } from '@aiao/rxdb';
+export type ActionType = 'INSERT' | 'UPDATE' | 'DELETE';
+export interface ConflictActionEntry {
+    key: string;
+    entityId: RxDBEntityId;
+    type: ActionType;
+    change: SwitchVersionChange;
+    remote: RemoteChange;
+}
+export declare function createEmptyActions(): SwitchVersionActions;
+export declare function countActions(actions: SwitchVersionActions): number;
+export declare function setAction(actions: SwitchVersionActions, entry: ConflictActionEntry): void;
+export declare function createConflictActionEntries(otherChanges: RemoteChange[], actions: SwitchVersionActions): ConflictActionEntry[];
+export declare function queryPendingLocalChanges(changeRepo: IRepository<typeof RxDBChange>, namespace: string, entity: string, branchId: string, lastPushedChangeId: number | null, entityIds: RxDBEntityId[]): Promise<Map<string, RxDBChange[]>>;
+export declare function markLocalChangesSuperseded(changeRepo: IRepository<typeof RxDBChange>, localChanges: RxDBChange[], remoteId: number): Promise<void>;
+export interface ResolveConflictsContext {
+    changeRepo: IRepository<typeof RxDBChange>;
+    conflictResolver: ConflictResolver;
+    dispatchEvent: (event: RxDBEvent) => void;
+    repoLabel: string;
+    deferLocalChangeSupersession?: boolean;
+    /**
+     * 当前客户端 id，用于给冲突的本地侧打戳。
+     *
+     * @remarks
+     * `RxDBChange` 表没有 clientId 列，直接把本地行交给解决器时 `conflict.local.clientId`
+     * 恒为 `undefined`，LWW 的 tie-breaker 永不触发、永远退回 KEEP_LOCAL —— 两个副本各自
+     * 保留自己，永久分叉。本地未同步的 change 按定义就是本客户端产生的，
+     * 在这里打戳与加列等价，且不需要持久化格式变更。
+     */
+    localClientId?: string;
+}
+export interface LocalChangeSupersession {
+    localChanges: RxDBChange[];
+    remoteId: number;
+}
+export interface ResolveConflictsResult {
+    applyActions: SwitchVersionActions;
+    conflictsResolved: number;
+    localChangeSupersessions: LocalChangeSupersession[];
+}
+export declare function resolveConflictsAndBuildActions(actionEntries: ConflictActionEntry[], pendingLocalChanges: Map<string, RxDBChange[]>, context: ResolveConflictsContext): Promise<ResolveConflictsResult>;
+//# sourceMappingURL=pull-conflict-utils.d.ts.map

package/dist/pull-conflict-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pull-conflict-utils.d.ts","sourceRoot":"","sources":["../src/pull-conflict-utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAIL,KAAK,gBAAgB,EAGrB,KAAK,WAAW,EAChB,KAAK,YAAY,EACjB,UAAU,EAEV,KAAK,YAAY,EAEjB,KAAK,SAAS,EACd,KAAK,oBAAoB,EACzB,KAAK,mBAAmB,EACzB,MAAM,YAAY,CAAC;AACpB,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAExD,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,YAAY,CAAC;IACvB,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,EAAE,mBAAmB,CAAC;IAC5B,MAAM,EAAE,YAAY,CAAC;CACtB;AAED,wBAAgB,kBAAkB,IAAI,oBAAoB,CAMzD;AAED,wBAAgB,YAAY,CAAC,OAAO,EAAE,oBAAoB,GAAG,MAAM,CAElE;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,oBAAoB,EAAE,KAAK,EAAE,mBAAmB,GAAG,IAAI,CAYzF;AAED,wBAAgB,2BAA2B,CACzC,YAAY,EAAE,YAAY,EAAE,EAC5B,OAAO,EAAE,oBAAoB,GAC5B,mBAAmB,EAAE,CAwCvB;AAED,wBAAsB,wBAAwB,CAC5C,UAAU,EAAE,WAAW,CAAC,OAAO,UAAU,CAAC,EAC1C,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,kBAAkB,EAAE,MAAM,GAAG,IAAI,EACjC,SAAS,EAAE,YAAY,EAAE,GACxB,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC,CAoCpC;AAED,wBAAsB,0BAA0B,CAC9C,UAAU,EAAE,WAAW,CAAC,OAAO,UAAU,CAAC,EAC1C,YAAY,EAAE,UAAU,EAAE,EAC1B,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAOf;AAED,MAAM,WAAW,uBAAuB;IACtC,UAAU,EAAE,WAAW,CAAC,OAAO,UAAU,CAAC,CAAC;IAC3C,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,aAAa,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,CAAC;IAC1C,SAAS,EAAE,MAAM,CAAC;IAClB,4BAA4B,CAAC,EAAE,OAAO,CAAC;IACvC;;;;;;;;OAQG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,uBAAuB;IACtC,YAAY,EAAE,UAAU,EAAE,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,sBAAsB;IACrC,YAAY,EAAE,oBAAoB,CAAC;IACnC,iBAAiB,EAAE,MAAM,CAAC;IAC1B,wBAAwB,EAAE,uBAAuB,EAAE,CAAC;CACrD;AAcD,wBAAsB,+BAA+B,CACnD,aAAa,EAAE,mBAAmB,EAAE,EACpC,mBAAmB,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC,EAC9C,OAAO,EAAE,uBAAuB,GAC/B,OAAO,CAAC,sBAAsB,CAAC,CA8EjC"}

package/dist/pull-repository.d.ts

@@ -0,0 +1,36 @@
+import { PullRepositoryOptions, PullRepositoryResult } from '@aiao/rxdb';
+import { SyncManager } from './SyncManager.js';
+export type { PullRepositoryOptions, PullRepositoryResult };
+/**
+ * 从中断错误里取出仓库级的部分进度。
+ *
+ * 结构化校验而非直接断言类型：`RxDBPartialSyncError` 的 `result` 是泛型，
+ * 拿一个 `as PullRepositoryResult` 硬转会在别处抛出别的形状时静默出错。
+ *
+ * @internal
+ */
+export declare function partialRepositoryProgressOf(error: Error): PullRepositoryResult | undefined;
+/**
+ * 为单个仓库拉取变更
+ *
+ * @param sm - SyncManager 实例
+ * @param namespace - 实体命名空间
+ * @param entity - 实体名称
+ * @param options - 拉取选项
+ * @returns 拉取结果
+ *
+ * @example
+ * ```ts
+ * // 在不进行级联的情况下拉取 Todo 仓库
+ * const result = await pullRepository(sm, 'public', 'Todo', {
+ *   includeRelated: false
+ * });
+ *
+ * // 拉取 Todo 及其所有依赖项（如 User）
+ * const result = await pullRepository(sm, 'public', 'Todo', {
+ *   includeRelated: true
+ * });
+ * ```
+ */
+export declare function pullRepository(sm: SyncManager, namespace: string, entity: string, options?: PullRepositoryOptions): Promise<PullRepositoryResult>;
+//# sourceMappingURL=pull-repository.d.ts.map

package/dist/pull-repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pull-repository.d.ts","sourceRoot":"","sources":["../src/pull-repository.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAQL,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EAiB1B,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AA0BpD,YAAY,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,CAAC;AAsB5D;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,KAAK,GAAG,oBAAoB,GAAG,SAAS,CAQ1F;AAcD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,cAAc,CAClC,EAAE,EAAE,WAAW,EACf,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,oBAAoB,CAAC,CA0B/B"}

package/dist/pull.d.ts

@@ -0,0 +1,16 @@
+import { PullOptions, PullResult } from '@aiao/rxdb';
+import { SyncManager } from './SyncManager.js';
+/**
+ * Pull 功能实现
+ *
+ * 从远程拉取变更并应用到本地实体表
+ *
+ * 默认使用 pullBatch 单次 HTTP 请求拉取所有实体的变更。
+ * 当指定 repositoryFilter 时，降级为 bulkSync 逐实体拉取。
+ *
+ * @param sm - SyncManager 实例
+ * @param options - Pull 选项
+ * @returns Pull 结果
+ */
+export declare function pull(sm: SyncManager, options?: PullOptions): Promise<PullResult>;
+//# sourceMappingURL=pull.d.ts.map

package/dist/pull.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pull.d.ts","sourceRoot":"","sources":["../src/pull.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,WAAW,EAEX,UAAU,EAMX,MAAM,YAAY,CAAC;AAIpB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;;;;;;;;;;GAWG;AACH,wBAAsB,IAAI,CAAC,EAAE,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAyCtF"}

package/dist/push-branch.d.ts

@@ -0,0 +1,22 @@
+import { SyncManager } from './SyncManager.js';
+export interface PushBranchResult {
+    synced: number;
+    skipped: string[];
+    /**
+     * 分叉点变更还没有 `remoteId`，本次只能带 `fromChangeId: null` 上行。
+     *
+     * 调用方应在实体变更推送完成、分叉点拿到 `remoteId` 之后重推一次分支，
+     * 把远端那一行补全。
+     */
+    forkPointPending: boolean;
+}
+/**
+ * 将当前激活分支推送到远程
+ *
+ * 规则:
+ * 1. 不推送 id='main' 的分支
+ * 2. 不修改远程分支的 activated 属性（由 SQL 函数保证）
+ * 3. `fromChangeId` 翻译成远端 id 后再上行（见 {@link toRemoteFromChangeId}）
+ */
+export declare function pushBranch(sm: SyncManager): Promise<PushBranchResult>;
+//# sourceMappingURL=push-branch.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"push-branch.d.ts","sourceRoot":"","sources":["../src/push-branch.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB;;;;;OAKG;IACH,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAED;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAAC,EAAE,EAAE,WAAW,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAqC3E"}

package/dist/push-repository.d.ts

@@ -0,0 +1,63 @@
+import { PushRepositoryResult } from '@aiao/rxdb';
+import { SyncManager } from './SyncManager.js';
+/**
+ * 推送仓库选项
+ */
+export interface PushRepositoryOptions {
+    /**
+     * 每批次推送的最大变更数量
+     * @default 1000
+     */
+    batchSize?: number;
+    /**
+     * 是否包含相关实体（级联同步）
+     *
+     * 当为 true 时：
+     * - 自动推送所有子实体（引用当前实体的实体）
+     * - 遵循反向拓扑顺序：子 -> 父
+     * - 示例：推送 User 时会自动推送 Post
+     *
+     * 当为 false 时：
+     * - 仅同步指定仓库
+     * - 可能会导致远端数据不完整
+     *
+     * @default true
+     */
+    includeRelated?: boolean;
+}
+export type { PushRepositoryResult };
+/**
+ * 从异常里取出推送侧的部分进度。
+ *
+ * 与 `partialRepositoryProgressOf`（pull 侧）对称：按 `PushRepositoryResult` 独有的
+ * `pushed` + `originalCount` 两个数值字段判形，`PullRepositoryResult` /
+ * `SyncRepositoryResult` 都没有它们，不会误判。
+ *
+ * @param error - 任意异常
+ * @returns 携带的推送结果；异常不是 `RxDBPartialSyncError` 或负载形状不符时返回 `undefined`
+ */
+export declare function partialPushProgressOf(error: Error): PushRepositoryResult | undefined;
+/**
+ * 为单个仓库推送变更
+ *
+ * @param sm - SyncManager 实例
+ * @param namespace - 实体命名空间
+ * @param entity - 实体名称
+ * @param options - 推送选项
+ * @returns 推送结果
+ *
+ * @example
+ * ```ts
+ * // 在不进行级联的情况下推送 Todo 仓库
+ * const result = await pushRepository(sm, 'public', 'Todo', {
+ *   includeRelated: false
+ * });
+ *
+ * // 推送 Todo 以及所有依赖它的实体（如 Comment）
+ * const result = await pushRepository(sm, 'public', 'Todo', {
+ *   includeRelated: true
+ * });
+ * ```
+ */
+export declare function pushRepository(sm: SyncManager, namespace: string, entity: string, options?: PushRepositoryOptions): Promise<PushRepositoryResult>;
+//# sourceMappingURL=push-repository.d.ts.map

package/dist/push-repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"push-repository.d.ts","sourceRoot":"","sources":["../src/push-repository.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAOL,KAAK,oBAAoB,EAiB1B,MAAM,YAAY,CAAC;AAKpB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;;;;;;;;;OAaG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAKD,YAAY,EAAE,oBAAoB,EAAE,CAAC;AAgBrC;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,KAAK,GAAG,oBAAoB,GAAG,SAAS,CAQpF;AAiCD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,cAAc,CAClC,EAAE,EAAE,WAAW,EACf,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,qBAAqB,GAC9B,OAAO,CAAC,oBAAoB,CAAC,CAoC/B"}

package/dist/push.d.ts

@@ -0,0 +1,14 @@
+import { PushOptions, PushResult } from '@aiao/rxdb';
+import { SyncManager } from './SyncManager.js';
+/**
+ * Push 功能实现
+ *
+ * 将本地未同步的变更推送到远程
+ * 先同步分支数据，再使用 bulkSync 批量推送所有 repositories
+ *
+ * @param sm - SyncManager 实例
+ * @param options - Push 选项
+ * @returns Push 结果
+ */
+export declare function push(sm: SyncManager, options?: PushOptions): Promise<PushResult>;
+//# sourceMappingURL=push.d.ts.map

package/dist/push.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"push.d.ts","sourceRoot":"","sources":["../src/push.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,UAAU,EAMX,MAAM,YAAY,CAAC;AAGpB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;;;;;;;;GASG;AACH,wBAAsB,IAAI,CAAC,EAAE,EAAE,WAAW,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,CAgFtF"}

package/dist/query-cache-outbox.d.ts

@@ -0,0 +1,120 @@
+import { ConflictResolver, isNetworkError, RxDB } from '@aiao/rxdb';
+/**
+ * 一次重放失败。
+ *
+ * @remarks
+ * 出现在 {@link QueryCacheOutboxResult.failures} 里：一轮重放**不因单行失败而中止**，
+ * 失败的行留在队列里等下一轮，成功的行照常推进水位线。
+ */
+export interface QueryCacheOutboxFailure {
+    /** 失败的实体 id；整批性失败（例如元数据探测失败）时为 `null` */
+    entityId: string | null;
+    /** 失败原因，原样透传，不包装 */
+    error: Error;
+}
+/**
+ * 一轮出站重放的结果，{@link flushQueryCacheOutbox} 的返回值。
+ *
+ * @remarks
+ * 四个净操作计数（`replayed` / `discarded` / `noop` 与 `failures.length`）互斥且穷尽：
+ * 压缩之后的每一个净操作恰好落进其中一类。`originalCount - compacted` 是净操作总数。
+ */
+export interface QueryCacheOutboxResult {
+    /** 本轮处理的仓库 */
+    repository: {
+        namespace: string;
+        entity: string;
+    };
+    /** 读到的原始变更行数 */
+    originalCount: number;
+    /** 被本地压缩抵消掉的原始变更行数 */
+    compacted: number;
+    /** 真的发出去并成功的净操作数 */
+    replayed: number;
+    /** LWW 判负、本地改动被丢弃的净操作数 */
+    discarded: number;
+    /** 远端状态已经满足意图、一个请求都没发的净操作数 */
+    noop: number;
+    /** 水位线推进到的 change id；本轮没有推进时为 `null` */
+    watermark: number | null;
+    /**
+     * 冲突判定中远端胜出的实体 id —— 也就是离线期间的本地改动被丢掉的那批。
+     *
+     * @remarks
+     * 只收解决器明确判 `KEEP_REMOTE` 的。「远端这行已经不在了」不算冲突：那种情况没有
+     * 竞争写可比，本地意图是被收敛掉而不是被判负（见 `MISSING_REMOTE`）。
+     */
+    conflicts: string[];
+    /** 本轮的失败；非空即意味着水位线没有推进 */
+    failures: QueryCacheOutboxFailure[];
+    /** 整轮被跳过时的原因（例如同步开关被关掉） */
+    skipped?: string;
+}
+/**
+ * 把某个 QueryCache 仓库积压的离线改动重放回远端。
+ *
+ * @param rxdb - RxDB 实例，用来取分支、本地/远端适配器与实体配置
+ * @param namespace - 实体命名空间
+ * @param entity - 实体名
+ * @param options - 可选的冲突解决器；默认 {@link LWWConflictResolver}
+ * @returns 本轮的重放结果
+ * @throws {@link RxDBError} 该仓库不存在，或它的 `syncType` 不是 `'querycache'`
+ *
+ * @remarks
+ * 同一仓库上的并发调用会复用同一个在飞的 Promise（见 {@link inflight}）。
+ *
+ * **失败即整轮中止、水位线不推进**：REST 没有批级原子性，也没有 per-change 的确认回执。
+ * 已经成功发出去的那几条因此会在下一轮被重发 —— 这与 `pushRepository` 在批次中途失败时
+ * 的暴露面相同。用一个哨兵值去写 `RxDBChange.remoteId` 能消除重发，但那个字段的语义是
+ * 「本地变更对应的远端 changelog 行」，REST 路径根本没有这个 id，写进去会让
+ * `pull-conflict-utils` 与待推计数读到一个不存在的引用。
+ *
+ * @example
+ * ```ts
+ * const result = await flushQueryCacheOutbox(rxdb, 'public', 'Recipe');
+ * if (result.failures.length === 0) {
+ *   console.log(`replayed ${result.replayed}, watermark → ${result.watermark}`);
+ * }
+ * ```
+ */
+export declare function flushQueryCacheOutbox(rxdb: RxDB, namespace: string, entity: string, options?: {
+    conflictResolver?: ConflictResolver;
+}): Promise<QueryCacheOutboxResult>;
+/**
+ * 数一遍所有 QueryCache 仓库在当前分支上还没推回远端的变更行。
+ *
+ * @param rxdb - RxDB 实例
+ * @returns 待重放的变更行数；没有这类仓库时为 0
+ *
+ * @remarks
+ * 口径与 {@link flushQueryCacheOutbox} 的取行条件一致（同分支、未推送、未回滚、
+ * 水位线之后），只是一次把所有 `offlineWrite && !push` 的仓库并成一个 OR 组来数，
+ * 不必逐仓库往返。
+ *
+ * 与 `HistoryManager.pushableCount$` **不重叠**：那一侧按 `capability.push` 取仓库，
+ * 这一侧取它的补集，因此 {@link SyncStateHub} 把两个数直接相加是安全的。
+ */
+export declare function countQueryCacheOutbox(rxdb: RxDB): Promise<number>;
+/**
+ * 取出某个 QueryCache 仓库当前**被出站队列占着**的实体 id。
+ *
+ * @param rxdb - RxDB 实例
+ * @param namespace - 命名空间
+ * @param entity - 实体名
+ * @returns 队列里还没推回远端的那些实体 id；队列为空时是空集
+ *
+ * @remarks
+ * 取行条件与 {@link flushQueryCacheOutbox} 逐字同源（同分支、`remoteId = null`、
+ * `revertChangeId = null`、水位线之后），因为「谁归队列管」和「谁会被重放」必须是
+ * 同一个集合 —— 两边各写一份过滤条件，漂移的那一刻就是数据被误删的那一刻。
+ *
+ * **不**看 `RxDBSync.enabled`：仓库关掉同步时队列永远不会 flush，那些行于是永远留在本地。
+ * 它们仍然是只有本地有的用户数据，按「远端没返回 = 孤儿」删掉就再也找不回来了。
+ *
+ * 没有 `RxDBSync` 记录时按「没有水位线」读全量，不新建记录：这是一次纯读，
+ * 给一个还没同步过的仓库建记录会凭空多出一条水位线为 0 的同步状态。
+ */
+export declare function pendingQueryCacheWriteIds(rxdb: RxDB, namespace: string, entity: string): Promise<ReadonlySet<string>>;
+/** 重导出，方便调用方按同一口径判断 flush 失败是不是网络原因 */
+export { isNetworkError };
+//# sourceMappingURL=query-cache-outbox.d.ts.map

package/dist/query-cache-outbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-cache-outbox.d.ts","sourceRoot":"","sources":["../src/query-cache-outbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,EAGL,KAAK,gBAAgB,EAUrB,cAAc,EAId,KAAK,IAAI,EAQV,MAAM,YAAY,CAAC;AAgBpB;;;;;;GAMG;AACH,MAAM,WAAW,uBAAuB;IACtC,yCAAyC;IACzC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,oBAAoB;IACpB,KAAK,EAAE,KAAK,CAAC;CACd;AAED;;;;;;GAMG;AACH,MAAM,WAAW,sBAAsB;IACrC,cAAc;IACd,UAAU,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAClD,gBAAgB;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,sBAAsB;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,oBAAoB;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,0BAA0B;IAC1B,SAAS,EAAE,MAAM,CAAC;IAClB,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,wCAAwC;IACxC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB;;;;;;OAMG;IACH,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,0BAA0B;IAC1B,QAAQ,EAAE,uBAAuB,EAAE,CAAC;IACpC,2BAA2B;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAwFD;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,IAAI,EACV,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE;IAAE,gBAAgB,CAAC,EAAE,gBAAgB,CAAA;CAAE,GAChD,OAAO,CAAC,sBAAsB,CAAC,CAoBjC;AAkID;;;;;;;;;;;;;GAaG;AACH,wBAAsB,qBAAqB,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,CA8BvE;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,IAAI,EACV,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC,CAe9B;AA0YD,uCAAuC;AACvC,OAAO,EAAE,cAAc,EAAE,CAAC"}

package/dist/sync-branches.d.ts

@@ -0,0 +1,35 @@
+import { SyncManager } from './SyncManager.js';
+export interface SyncBranchesResult {
+    created: number;
+    updated: number;
+    total: number;
+    /**
+     * 因分叉点变更尚未拉到本地而**本轮未创建**的分支 id。
+     *
+     * 远端分支行上的 `fromChangeId` 是远端 change id，落到本地必须翻译成本地 id
+     * （见 {@link toLocalFromChangeId}）。翻译不出来时既不能写远端 id（本地会当自己的 id 消费，
+     * 分叉点变成一个无关变更），也不能写 `null`（`find-switch-branch-step` 会当「分叉于根」，
+     * 切换分支时从第一条变更起算）。唯一无损的选择是本轮跳过，等分叉点变更拉到本地后再建。
+     */
+    skipped: string[];
+}
+/**
+ * 从远程拉取所有分支信息并同步到本地
+ *
+ * 规则：
+ * 1. 远程新分支 → 在本地创建（local: false, remote: true）
+ * 2. 本地已有的远程分支 → 更新 remote 标记为 true
+ * 3. 纯本地分支（remote=false）→ 不受影响
+ *
+ * @remarks
+ * 读本地、排序、落库全部在**同一个事务窗口**内完成：
+ *
+ * - 无事务时中途失败会留下半批已提交的分支，下次重试撞主键，同步就此永久卡死；
+ * - 读若在事务外做，快照与写之间存在窗口，并发建分支会让「本地已有」的判断过时，
+ *   重复 create 同样撞主键。
+ *
+ * 事务体内只能用 `executor` 作用域的仓库。绑在适配器上的那一份走并发度 1 的写队列，
+ * 在事务体内调用会排到自己这个事务后面 —— 直接死锁。
+ */
+export declare function syncBranches(sm: SyncManager): Promise<SyncBranchesResult>;
+//# sourceMappingURL=sync-branches.d.ts.map

package/dist/sync-branches.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-branches.d.ts","sourceRoot":"","sources":["../src/sync-branches.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAEpD,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IAEd;;;;;;;OAOG;IACH,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AA4DD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,YAAY,CAAC,EAAE,EAAE,WAAW,GAAG,OAAO,CAAC,kBAAkB,CAAC,CA2D/E"}

package/dist/sync-listeners.d.ts

@@ -0,0 +1,20 @@
+import { Subscription } from 'rxjs';
+import { SyncManager } from './SyncManager.js';
+/**
+ * 设置 SyncManager 的同步监听器
+ *
+ * 包含两条 reactive 链路：
+ * 1. 「已连接且网络可达」→ 自动重放 QueryCache 出站队列，离线期间由退避节拍驱动重试，
+ *    每个仓库失败仅吞错。changelog 的 `push` 不在其中，见 {@link resumeSync}
+ * 2. Remote 实体事件 → 累计 `pullableCount`（仅统计当前激活分支）
+ *
+ * 调用方负责管理返回的 subscriptions / removers 生命周期（destroy 时清理）。
+ *
+ * @param sm - 当前同步管理器
+ * @returns 已注册的 rxjs subscriptions 和事件解绑闭包
+ */
+export declare function setupSyncListeners(sm: SyncManager): {
+    subscriptions: Subscription[];
+    removers: Array<() => void>;
+};
+//# sourceMappingURL=sync-listeners.d.ts.map

package/dist/sync-listeners.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-listeners.d.ts","sourceRoot":"","sources":["../src/sync-listeners.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAyC,YAAY,EAAE,MAAM,MAAM,CAAC;AAG3E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAiMpD;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,EAAE,WAAW,GAAG;IACnD,aAAa,EAAE,YAAY,EAAE,CAAC;IAC9B,QAAQ,EAAE,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC;CAC7B,CA4DA"}

package/dist/sync-manager.utils.d.ts

@@ -0,0 +1,36 @@
+import { SyncRepositoryResult } from './sync-repository.js';
+/**
+ * 「这次同步已经改写了本地数据」的共同判据形状。
+ *
+ * @remarks
+ * 四个粒度的结果都满足它，所以判据只需要写一份：整库 / 单仓库的 `PullResult` 只有
+ * `historyInvalidated`，`SyncRepositoryResult` 还多一段 `pushResult`。两项都取可选，
+ * 缺哪一段就当那一段没有进度。
+ */
+interface SyncedProgress {
+    readonly historyInvalidated?: boolean;
+    readonly pushResult?: {
+        readonly pushed: number;
+    };
+}
+/** 一次仓库同步是否改写了本地实体数据（undo 历史边界因此失效） */
+export declare const hasSyncedData: (result: SyncedProgress | undefined) => boolean;
+/**
+ * 中断的同步里是否带着「已经落库 / 已经上行」的进度。
+ *
+ * @remarks
+ * 部分成功以 {@link RxDBPartialSyncError} 的形式抛出，进度只挂在它的 `result` 上。
+ * `pull` / `pullRepository` / `sync` / `syncRepository` 四个入口共用这一条判据 ——
+ * 各写各的 `instanceof` + 强转，迟早会有一个入口漏掉 `pushResult` 那一半。
+ */
+export declare const partialSyncInvalidatesHistory: (error: unknown) => boolean;
+/**
+ * 取出失败项里携带的部分进度。
+ *
+ * @remarks
+ * 仓库在失败前可能已经提交了部分结果，它只存在于 {@link RxDBPartialSyncError.result}。
+ * 忽略它会让「远端数据已落库但 undo 边界没推进」的状态逃过检查。
+ */
+export declare const partialResultOf: (error: Error | undefined) => SyncRepositoryResult | undefined;
+export {};
+//# sourceMappingURL=sync-manager.utils.d.ts.map

package/dist/sync-manager.utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sync-manager.utils.d.ts","sourceRoot":"","sources":["../src/sync-manager.utils.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAEjE;;;;;;;GAOG;AACH,UAAU,cAAc;IACtB,QAAQ,CAAC,kBAAkB,CAAC,EAAE,OAAO,CAAC;IACtC,QAAQ,CAAC,UAAU,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CACnD;AAED,uCAAuC;AACvC,eAAO,MAAM,aAAa,GAAI,QAAQ,cAAc,GAAG,SAAS,KAAG,OACW,CAAC;AAE/E;;;;;;;GAOG;AACH,eAAO,MAAM,6BAA6B,GAAI,OAAO,OAAO,KAAG,OACyB,CAAC;AAEzF;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,KAAK,GAAG,SAAS,KAAG,oBAAoB,GAAG,SACU,CAAC"}