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

package/src/bulk-sync.ts

@@ -0,0 +1,349 @@
+/**
+ * @fileoverview 批量同步实现
+ *
+ * 提供在单次操作中同步多个仓库的功能，支持顺序或并发执行模式。
+ */
+
+import {
+  findCurrentSyncRecord,
+  getEntityMetadata,
+  getSyncCapability,
+  getSyncType,
+  isRepositorySyncEnabled,
+  type RxDB,
+  RxDBError,
+  RxDBPartialSyncError,
+  type SyncRejection
+} from '@aiao/rxdb';
+import type { RepositoryIdentifier } from './dependency-graph.js';
+import type { PullRepositoryOptions } from './pull-repository.js';
+import { type PushRepositoryOptions, reportPushRejections } from './push-repository.js';
+import { syncRepository, type SyncRepositoryOptions, type SyncRepositoryResult } from './sync-repository.js';
+import type { SyncManager } from './SyncManager.js';
+/**
+ * 批量同步选项
+ */
+export interface BulkSyncOptions {
+  /**
+   * 同步操作类型
+   * @default 'sync'
+   */
+  operation?: 'pull' | 'push' | 'sync';
+
+  /**
+   * 目标仓库列表
+   * 如果为空，则同步所有启用的仓库
+   */
+  repositories?: RepositoryIdentifier[];
+
+  /**
+   * 拉取选项（应用于所有仓库）
+   */
+  pull?: PullRepositoryOptions;
+
+  /**
+   * 推送选项（应用于所有仓库）
+   */
+  push?: PushRepositoryOptions;
+
+  /**
+   * 是否并发执行
+   * @default false
+   */
+  concurrent?: boolean;
+
+  /**
+   * 并发限制（只有 concurrent=true 时生效）
+   * @default 3
+   */
+  concurrency?: number;
+}
+
+/**
+ * 批量同步结果
+ */
+export interface BulkSyncResult {
+  /**
+   * 成功的仓库数量
+   */
+  succeeded: number;
+
+  /**
+   * 失败的仓库数量
+   */
+  failed: number;
+
+  /**
+   * 每个仓库的详细结果
+   */
+  results: Array<{
+    repository: RepositoryIdentifier;
+    success: boolean;
+    result?: SyncRepositoryResult;
+    error?: Error;
+  }>;
+
+  /**
+   * 总耗时（毫秒）
+   */
+  durationMs: number;
+}
+
+/**
+ * 获取需要同步的仓库列表
+ *
+ * 如果 options.repositories 有值则使用该值；否则从 rxdb.config.entities 中挑出**真正能同步**的仓库。
+ *
+ * @param rxdb - RxDB 实例
+ * @param options - 批量同步选项
+ * @returns 需要同步的仓库列表
+ *
+ * @remarks
+ * 这里是枚举路径，资格不足一律**跳过**（单仓入口才抛错）。两条过滤：
+ * - 能力矩阵：两个方向都不可同步的（`none` / `local`）没有理由进队列。此前只跳
+ *   `none`，`local` 会一路走到 `syncRepository` 才被 `shouldPull` / `shouldPush`
+ *   双双判负，凭空多出一条「同步了 0 条」的结果。
+ * - `RxDBSync.enabled`：被用户关掉的仓库跳过。留着它只会在 `pullRepository` /
+ *   `pushRepository` 里抛错，把「我关的」变成一条同步失败。
+ *
+ * @internal
+ */
+export async function getRepositoriesToSync(rxdb: RxDB, options: BulkSyncOptions): Promise<RepositoryIdentifier[]> {
+  // 如果明确指定了 repositories，则直接使用：调用方点名要同步谁，
+  // 资格判定交给 syncRepository 去抛错，这里不替他做主
+  if (options.repositories && options.repositories.length > 0) {
+    return options.repositories;
+  }
+
+  const repositories: RepositoryIdentifier[] = [];
+
+  for (const EntityClass of rxdb.config.entities) {
+    const metadata = getEntityMetadata(EntityClass);
+
+    // 检查 syncType（支持全局配置回退）
+    const capability = getSyncCapability(getSyncType(metadata, rxdb.entitySync));
+    if (!capability.pull && !capability.push) {
+      continue;
+    }
+
+    const repoSync = await findCurrentSyncRecord(rxdb, metadata.namespace, metadata.name);
+    if (!isRepositorySyncEnabled(repoSync)) {
+      continue;
+    }
+
+    repositories.push({
+      namespace: metadata.namespace,
+      entity: metadata.name
+    });
+  }
+
+  return repositories;
+}
+
+/**
+ * 同步单个仓库并处理错误
+ *
+ * @param sm - 调用方持有的同步管理器实例
+ * @param repo - 要同步的仓库
+ * @param syncOptions - 同步选项
+ * @param rejections - 本轮被拒清单收集器，由 {@link bulkSync} 统一上报
+ * @returns 带有成功标志的结果对象
+ */
+async function syncSingleRepository(
+  sm: SyncManager,
+  repo: RepositoryIdentifier,
+  syncOptions: SyncRepositoryOptions,
+  rejections: SyncRejection[]
+): Promise<{
+  repository: RepositoryIdentifier;
+  success: boolean;
+  result?: SyncRepositoryResult;
+  error?: Error;
+}> {
+  try {
+    const result = await syncRepository(sm, repo.namespace, repo.entity, syncOptions, rejections);
+
+    return {
+      repository: repo,
+      success: true,
+      result
+    };
+  } catch (error) {
+    const normalized = error instanceof Error ? error : new Error(String(error));
+    return {
+      repository: repo,
+      success: false,
+      // 失败前已提交的部分进度同时挂到 `result` 上：只留 `error` 的话，调用方要想知道
+      // 「这个仓库其实已经落了多少数据」就得自己去拆 RxDBPartialSyncError
+      result: normalized instanceof RxDBPartialSyncError ? (normalized.result as SyncRepositoryResult) : undefined,
+      error: normalized
+    };
+  }
+}
+
+/**
+ * 顺序执行批量同步
+ *
+ * @param sm - 调用方持有的同步管理器实例
+ * @param repositories - 仓库列表
+ * @param syncOptions - 同步选项
+ * @param rejections - 本轮被拒清单收集器
+ * @returns 结果数组
+ */
+async function executeSyncSequentially(
+  sm: SyncManager,
+  repositories: RepositoryIdentifier[],
+  syncOptions: SyncRepositoryOptions,
+  rejections: SyncRejection[]
+): Promise<
+  Array<{
+    repository: RepositoryIdentifier;
+    success: boolean;
+    result?: SyncRepositoryResult;
+    error?: Error;
+  }>
+> {
+  const results: Array<{
+    repository: RepositoryIdentifier;
+    success: boolean;
+    result?: SyncRepositoryResult;
+    error?: Error;
+  }> = [];
+
+  for (const repo of repositories) {
+    const result = await syncSingleRepository(sm, repo, syncOptions, rejections);
+    results.push(result);
+  }
+
+  return results;
+}
+
+/**
+ * 并发执行批量同步（带并发限制）
+ *
+ * @param sm - 调用方持有的同步管理器实例
+ * @param repositories - 仓库列表
+ * @param syncOptions - 同步选项
+ * @param concurrency - 最大并发操作数
+ * @param rejections - 本轮被拒清单收集器
+ * @returns 结果数组
+ */
+async function executeSyncConcurrently(
+  sm: SyncManager,
+  repositories: RepositoryIdentifier[],
+  syncOptions: SyncRepositoryOptions,
+  concurrency: number,
+  rejections: SyncRejection[]
+): Promise<
+  Array<{
+    repository: RepositoryIdentifier;
+    success: boolean;
+    result?: SyncRepositoryResult;
+    error?: Error;
+  }>
+> {
+  const results: Array<{
+    repository: RepositoryIdentifier;
+    success: boolean;
+    result?: SyncRepositoryResult;
+    error?: Error;
+  }> = [];
+
+  // 按并发限制分批处理
+  for (let i = 0; i < repositories.length; i += concurrency) {
+    const batch = repositories.slice(i, i + concurrency);
+    const batchPromises = batch.map(repo => syncSingleRepository(sm, repo, syncOptions, rejections));
+    const batchResults = await Promise.all(batchPromises);
+    results.push(...batchResults);
+  }
+
+  return results;
+}
+
+/**
+ * 对多个仓库执行批量同步
+ *
+ * 支持顺序和并发两种执行模式。
+ * 在顺序模式下，仓库将被逐个同步。
+ * 在并发模式下，可以同时并发同步多个仓库。
+ *
+ * @param rxdb - RxDB 实例
+ * @param options - 批量同步选项
+ * @returns 带有成功/失败计数的批量同步结果
+ *
+ * @example
+ * ```typescript
+ * // 顺序同步所有启用的仓库
+ * const result = await bulkSync(rxdb);
+ *
+ * // 同步指定仓库
+ * const result = await bulkSync(rxdb, {
+ *   repositories: [
+ *     { namespace: 'public', entity: 'Todo' },
+ *     { namespace: 'public', entity: 'User' }
+ *   ]
+ * });
+ *
+ * // 并发同步并限制并发数
+ * const result = await bulkSync(rxdb, {
+ *   concurrent: true,
+ *   concurrency: 3
+ * });
+ * ```
+ */
+export async function bulkSync(rxdb: RxDB, options: BulkSyncOptions = {}): Promise<BulkSyncResult> {
+  const startTime = Date.now();
+
+  // 槽位只在入口解析这一次。`rxdb.syncManager` 由插件作用域挂着，批处理跑到一半时
+  // 最后一个适配器断开就会把它删掉；逐轮重解析会让剩余仓库全部解引用 `undefined`，
+  // 被逐仓库的 try/catch 收成一串 TypeError，崩溃于是伪装成「同步失败」。
+  const sm = rxdb.syncManager;
+
+  // 1. 获取需要同步的仓库
+  const repositories = await getRepositoriesToSync(rxdb, options);
+
+  // 2. 构建同步选项
+  const syncOptions: SyncRepositoryOptions = {
+    direction: options.operation,
+    pull: options.pull,
+    push: options.push
+  };
+
+  // 3. 执行同步（顺序或并发）
+  const concurrent = options.concurrent ?? false;
+  const concurrency = options.concurrency ?? 3;
+  // 非正或非整的并发度会让 `executeSyncConcurrently` 的 `i += concurrency` 永不前进，
+  // 公开 Promise 永久 pending。挂死比报错难排查得多，入口就地 fail-fast
+  if (concurrent && (!Number.isSafeInteger(concurrency) || concurrency < 1)) {
+    throw new RxDBError(`bulkSync: concurrency 必须是不小于 1 的安全整数，收到 ${String(concurrency)}`);
+  }
+
+  let results: Array<{
+    repository: RepositoryIdentifier;
+    success: boolean;
+    result?: SyncRepositoryResult;
+    error?: Error;
+  }>;
+
+  // 本轮各仓已落库的被拒汇总后只报一次：`reportRejections` 整体替换，逐仓报会互相覆盖。
+  // 逐仓的失败都被 syncSingleRepository 收成结果，不会越过这里，前仓已落库的被拒照报
+  const rejections: SyncRejection[] = [];
+  if (concurrent) {
+    results = await executeSyncConcurrently(sm, repositories, syncOptions, concurrency, rejections);
+  } else {
+    results = await executeSyncSequentially(sm, repositories, syncOptions, rejections);
+  }
+  reportPushRejections(sm, rejections);
+
+  // 4. 计算统计信息
+  const succeeded = results.filter(r => r.success).length;
+  const failed = results.filter(r => !r.success).length;
+  const durationMs = Date.now() - startTime;
+
+  return {
+    succeeded,
+    failed,
+    results,
+    durationMs
+  };
+}

package/src/cascade-blocking.ts

@@ -0,0 +1,61 @@
+/**
+ * @fileoverview 级联阻断判定：在依赖图上找出挡住当前仓库的那个失败依赖。
+ *
+ * 与 {@link ../sync-contract/cascade-contract.js | cascade-contract} 分家的理由见后者的文件头 ——
+ * 这一半读依赖图，跟着级联调度器走；那一半只做资格判定，核心的 QueryCache 出站队列也要用。
+ */
+
+import { type RepositoryIdentifier, repositoryKey } from '@aiao/rxdb';
+import type { DependencyGraph } from './dependency-graph.js';
+import type { DependencyEdge } from './topological-sort.js';
+/**
+ * 被依赖失败阻断的仓库，及其阻断来源
+ */
+export interface CascadeBlock {
+  /** 直接导致阻断的依赖仓库 */
+  dependency: RepositoryIdentifier;
+
+  /** 该依赖仓库失败的错误 */
+  cause: Error;
+}
+
+/**
+ * 在依赖图上查找阻断当前仓库的第一个失败依赖
+ *
+ * @param graph - 依赖图
+ * @param repoKey - 当前仓库的 `namespace:entity` 键
+ * @param failed - 已失败仓库到其错误的映射（键同为 `namespace:entity`）
+ * @param edge - 本相位沿哪条依赖边判定阻断，取自 `dependencyEdgeForAction`。
+ * **没有默认值是刻意的**：这个值必须和本相位的
+ * 拓扑序同源，随手给一个默认就等于允许两者各说各话。
+ * @returns 存在失败依赖时返回该依赖与其错误；否则返回 `undefined`
+ *
+ * @remarks
+ * 只看直接邻居：级联按拓扑序执行，间接依赖的失败会先把中间那一层标成失败，
+ * 再经由这一层传导下来。
+ *
+ * 边必须跟着相位走，不能一律取 `dependsOn`：
+ *
+ * - **INSERT/UPDATE** 父先子后，父建不出来子就挂不上外键 → 子被 `dependsOn` 阻断；
+ * - **DELETE** 子先父后，子删不掉父就删不得（外键还指着它）→ 父被 `requiredBy` 阻断。
+ *
+ * 此前两个相位都取 `dependsOn`，等于把 DELETE 的方向反过来看：子仓删除失败时
+ * 父仓照删不误，远端要么直接违反外键约束、要么留下指向已删父行的孤儿；反过来
+ * 父仓删除失败又会白白挡住子仓——删子从来不会破坏父。
+ */
+export function findBlockingDependency(
+  graph: DependencyGraph,
+  repoKey: string,
+  failed: ReadonlyMap<string, Error>,
+  edge: DependencyEdge
+): CascadeBlock | undefined {
+  const dep = graph.get(repoKey);
+  if (!dep) return undefined;
+
+  for (const dependency of dep[edge]) {
+    const cause = failed.get(repositoryKey(dependency));
+    if (cause) return { dependency, cause };
+  }
+
+  return undefined;
+}

package/src/check-repository-updates.ts

@@ -0,0 +1,143 @@
+/**
+ * 预检远程更新（不下载数据）
+ * 此函数只查询远程有多少新变更，不会实际拉取数据
+ * 用于"有 N 条更新"的场景，节省流量和时间
+ *
+ * User Story 2: 按需同步
+ */
+
+import { getEntityMetadata, needsPull, type RepositoryIdentifier, type RxDB, RxDBSync } from '@aiao/rxdb';
+import { getAncestorBranchIds } from './branch-utils.js';
+// `RepositoryIdentifier` 此前在 4 个文件里各写了一份同形状定义，
+// 统一收敛到 `VersionManager.interface.ts`（那份才是 `index.ts` 真正导出的）。
+export type { RepositoryIdentifier };
+
+/**
+ * 仓库更新检查结果。
+ */
+export interface CheckRepositoryUpdatesResult {
+  /**
+   * Repository 标识
+   */
+  repository: RepositoryIdentifier;
+
+  /**
+   * 远程最新的 changeId
+   */
+  remoteLatestChangeId: number;
+
+  /**
+   * 本地最后拉取的远程 changeId
+   */
+  localLastPullRemoteChangeId: number | null;
+
+  /**
+   * 待拉取的变更数量
+   */
+  pendingCount: number;
+
+  /**
+   * 是否有更新
+   */
+  hasUpdates: boolean;
+}
+
+/**
+ * 预检远程更新（不下载数据）
+ *
+ * @param rxdb - RxDB 实例
+ * @param namespace - 命名空间
+ * @param entity - 实体名称
+ * @returns 更新检查结果
+ *
+ * @example
+ * ```typescript
+ * // 检查 Todo 是否有远程更新
+ * const result = await checkRepositoryUpdates(rxdb, 'public', 'Todo');
+ * if (result.hasUpdates) {
+ *   console.log(`有 ${result.pendingCount} 条更新待拉取`);
+ *   // 用户点击"更新"按钮后再调用 pullRepository()
+ * }
+ * ```
+ */
+export async function checkRepositoryUpdates(
+  rxdb: RxDB,
+  namespace: string,
+  entity: string
+): Promise<CheckRepositoryUpdatesResult> {
+  const repository: RepositoryIdentifier = { namespace, entity };
+
+  // 1. 检查同步配置
+  const EntityType = rxdb.config.entities.find(e => {
+    const meta = getEntityMetadata(e);
+    return meta.namespace === namespace && meta.name === entity;
+  });
+
+  if (!EntityType) {
+    throw new Error(`Entity not found: ${namespace}.${entity}`);
+  }
+
+  const metadata = getEntityMetadata(EntityType);
+
+  // 如果不需要 pull（Local 或 None），直接返回无更新
+  if (!needsPull(metadata, rxdb.entitySync)) {
+    return {
+      repository,
+      remoteLatestChangeId: 0,
+      localLastPullRemoteChangeId: null,
+      pendingCount: 0,
+      hasUpdates: false
+    };
+  }
+
+  // 2. 获取 RxDBSync 记录
+  // 槽位只解析这一次：断连会把 `rxdb.syncManager` 删掉，一次查询里重解析四回
+  // 等于给自己留四个 `undefined` 的窗口。
+  const sm = rxdb.syncManager;
+  const branch = await sm.getCurrentBranch();
+  const branchId = branch.id;
+
+  const { adapter: localAdapter } = await sm.getLocalRepositories();
+  const repoSyncRepo = localAdapter.getRepository(RxDBSync);
+  const repoSyncId = `${namespace}:${entity}:${branchId}`;
+
+  const repoSyncResults = await repoSyncRepo.find({
+    where: {
+      combinator: 'and',
+      rules: [{ field: 'id', operator: '=', value: repoSyncId }]
+    },
+    limit: 1
+  });
+
+  const repoSync = repoSyncResults[0];
+  const localLastPullRemoteChangeId = repoSync?.lastPullRemoteChangeId ?? null;
+
+  // 3. 调用适配器的 getChangeCount() 查询远程变更数量
+  const { adapter: remoteAdapter } = await sm.getRemoteRepositories();
+  if (!remoteAdapter) {
+    throw new Error('Remote adapter not configured');
+  }
+
+  const sinceId = localLastPullRemoteChangeId ?? 0;
+  // 计数范围必须和 pull 的拉取范围一致，否则这个函数就是在回答另一个问题：
+  // `getChangeCount` 的 branchId 是精确匹配，只传当前分支时父分支上的新变更一条都不计入，
+  // 于是 `hasUpdates` 报 false、界面显示「已全部同步」，而 pull 其实还有东西要拉。
+  // 此前只传裸实体名，同名实体跨 namespace 存在时会解析歧义
+  const branchIds = await getAncestorBranchIds(sm, branchId);
+  const perBranch = await Promise.all(
+    branchIds.map(ancestorBranchId =>
+      remoteAdapter.getChangeCount(sinceId, [`${namespace}:${metadata.name}`], ancestorBranchId)
+    )
+  );
+  // 条数跨分支相加；`latestChangeId` 是同一个远端序列上的最大值，取 max 而非相加
+  const count = perBranch.reduce((sum, item) => sum + item.count, 0);
+  const latestChangeId = perBranch.reduce((max, item) => (item.latestChangeId > max ? item.latestChangeId : max), 0);
+  // 4. 构造返回结果
+  return {
+    repository,
+    remoteLatestChangeId: latestChangeId,
+    localLastPullRemoteChangeId,
+    pendingCount: count,
+    hasUpdates: count > 0
+  };
+}