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

package/src/sync-repository.ts

@@ -0,0 +1,307 @@
+import {
+  getEntityMetadata,
+  getSyncCapability,
+  getSyncType,
+  RepositorySyncBeginEvent,
+  RepositorySyncCompleteEvent,
+  RepositorySyncErrorEvent,
+  RxDBError,
+  RxDBPartialSyncError,
+  type SyncProgress,
+  type SyncRejection
+} from '@aiao/rxdb';
+import type { SyncManager } from './SyncManager.js';
+import {
+  partialRepositoryProgressOf,
+  pullRepository,
+  type PullRepositoryOptions,
+  type PullRepositoryResult
+} from './pull-repository.js';
+import {
+  partialPushProgressOf,
+  pushRepository,
+  type PushRepositoryOptions,
+  type PushRepositoryResult
+} from './push-repository.js';
+/**
+ * @fileoverview 仓库级别的同步操作
+ *
+ * 将仓库的拉取（pull）和推送（push）操作组合在一起，保证正确的执行顺序。
+ */
+
+/**
+ * 仓库同步选项
+ */
+export interface SyncRepositoryOptions {
+  /**
+   * 同步方向
+   * @default 'sync'
+   */
+  direction?: 'pull' | 'push' | 'sync';
+
+  /**
+   * 拉取（pull）选项
+   */
+  pull?: PullRepositoryOptions;
+
+  /**
+   * 推送（push）选项
+   */
+  push?: PushRepositoryOptions;
+}
+
+/**
+ * 仓库同步结果
+ */
+export interface SyncRepositoryResult extends SyncProgress {
+  /**
+   * 拉取结果
+   */
+  pullResult: PullRepositoryResult;
+
+  /**
+   * 推送结果
+   */
+  pushResult: PushRepositoryResult;
+}
+
+/**
+ * 跳过拉取时的占位结果（未发生任何拉取，进度两项都为 false）
+ */
+function emptyPullResult(namespace: string, entity: string): PullRepositoryResult {
+  return {
+    repository: { namespace, entity },
+    pulled: 0,
+    compacted: 0,
+    applied: 0,
+    hasMore: false,
+    conflictsResolved: 0,
+    conflictsDeferred: 0,
+    persistedProgress: false,
+    historyInvalidated: false,
+    failures: []
+  };
+}
+
+/**
+ * 跳过推送时的占位结果
+ */
+function emptyPushResult(namespace: string, entity: string): PushRepositoryResult {
+  return {
+    repository: { namespace, entity },
+    pushed: 0,
+    rejected: 0,
+    failed: 0,
+    compacted: 0,
+    originalCount: 0,
+    failures: []
+  };
+}
+
+/**
+ * 把仓库级 pull 的中断错误重新包装成**仓库同步**粒度的中断错误。
+ *
+ * `pullRepository` 抛出的 `RxDBPartialSyncError.result` 是 `PullRepositoryResult`，
+ * 而 `bulkSync` 会把它当成 `SyncRepositoryResult` 挂到 `result` 上给调用方读
+ * `result.pullResult` —— 不在这里转一道，那个字段永远是 undefined，
+ * 失败仓库的已提交进度照样丢。
+ */
+function rewrapPullFailure(error: unknown, namespace: string, entity: string): unknown {
+  if (!(error instanceof RxDBPartialSyncError)) return error;
+  const pullResult = partialRepositoryProgressOf(error);
+  if (!pullResult) return error;
+  const wrapped: SyncRepositoryResult = {
+    pullResult,
+    pushResult: emptyPushResult(namespace, entity),
+    persistedProgress: pullResult.persistedProgress,
+    historyInvalidated: pullResult.historyInvalidated
+  };
+  return new RxDBPartialSyncError<SyncRepositoryResult>(wrapped, error.cause);
+}
+
+/**
+ * 把仓库级 push 的失败重新包装成**仓库同步**粒度的中断错误。
+ *
+ * 两段进度都不能因为 push 抛错而消失：
+ *
+ * - pull 阶段已落库的部分（`pullResult.persistedProgress`）；
+ * - push 阶段已发到远端、**不会回滚**的部分（`RxDBPartialSyncError.result.pushed > 0`）。
+ *   此前这里恒填 `emptyPushResult`，已经发出去的条目在聚合层看起来一条没推，
+ *   调用方据此重试就是重复推送。
+ *
+ * 两段都没有时原样抛：包一层空进度只会让调用方多剥一层。
+ *
+ * @param error - `pushRepository` 抛出的任意异常
+ * @param pullResult - 同一轮里 pull 阶段的结果，进度要一起交出去
+ * @param namespace - 实体命名空间
+ * @param entity - 实体名称
+ * @returns 待抛出的异常
+ */
+function rewrapPushFailure(
+  error: unknown,
+  pullResult: PullRepositoryResult,
+  namespace: string,
+  entity: string
+): unknown {
+  const normalized = error instanceof Error ? error : new Error(String(error));
+  const pushProgress = partialPushProgressOf(normalized);
+  const pushResult = pushProgress === undefined ? emptyPushResult(namespace, entity) : pushProgress;
+  const persistedProgress = pullResult.persistedProgress || pushResult.pushed > 0;
+  if (!persistedProgress) return normalized;
+
+  const partial: SyncRepositoryResult = {
+    pullResult,
+    pushResult,
+    persistedProgress,
+    historyInvalidated: pullResult.historyInvalidated
+  };
+  // 已经是 partial error 时取根因，避免调用方拿到「错误里套错误」
+  return new RxDBPartialSyncError<SyncRepositoryResult>(
+    partial,
+    normalized instanceof RxDBPartialSyncError ? normalized.cause : normalized
+  );
+}
+
+/**
+ * 同步一个仓库（先拉取再推送）
+ *
+ * @param sm - SyncManager 实例
+ * @param namespace - 实体命名空间
+ * @param entity - 实体名称
+ * @param options - 同步选项
+ * @param rejectionSink - 推送被拒清单收集器，语义同 {@link pushRepository} 的同名参数
+ * @returns 同步结果
+ *
+ * @example
+ * ```ts
+ * // 同步 Todo 仓库（pull + push）
+ * const result = await syncRepository(sm, 'public', 'Todo');
+ *
+ * // 使用自定义选项同步
+ * const result = await syncRepository(sm, 'public', 'Todo', {
+ *   pull: { limit: 500, fetchAll: true },
+ *   push: { batchSize: 100 }
+ * });
+ * ```
+ */
+export async function syncRepository(
+  sm: SyncManager,
+  namespace: string,
+  entity: string,
+  options?: SyncRepositoryOptions,
+  rejectionSink?: SyncRejection[]
+): Promise<SyncRepositoryResult> {
+  const rxdb = sm.rxdb;
+
+  // 触发开始事件
+  const includeRelated = options?.pull?.includeRelated ?? options?.push?.includeRelated ?? true;
+  rxdb.dispatchEvent(new RepositorySyncBeginEvent('sync', namespace, entity, includeRelated));
+
+  try {
+    const result = await _syncRepositoryImpl(sm, namespace, entity, options, rejectionSink);
+
+    // 触发完成事件
+    // 两个子结果在 SyncRepositoryResult 上都是必填：跳过的方向由 emptyPullResult /
+    // emptyPushResult 交出各计数为 0 的占位。此前的 `?.x ?? 0` 是跑不到的分支，
+    // 真出现 undefined 时它会把「结果缺失」伪装成「同步了 0 条」。
+    const { pullResult, pushResult } = result;
+    const stats = {
+      pulled: pullResult.pulled,
+      pushed: pushResult.pushed,
+      compacted: pullResult.compacted + pushResult.compacted,
+      failed: pushResult.failed,
+      conflictsResolved: pullResult.conflictsResolved,
+      conflictsDeferred: pullResult.conflictsDeferred
+    };
+    rxdb.dispatchEvent(new RepositorySyncCompleteEvent('sync', namespace, entity, stats));
+
+    return result;
+  } catch (error) {
+    // 触发错误事件
+    rxdb.dispatchEvent(new RepositorySyncErrorEvent('sync', namespace, entity, error as Error));
+    throw error;
+  }
+}
+
+/**
+ * syncRepository 的内部实现
+ */
+async function _syncRepositoryImpl(
+  sm: SyncManager,
+  namespace: string,
+  entity: string,
+  options?: SyncRepositoryOptions,
+  rejectionSink?: SyncRejection[]
+): Promise<SyncRepositoryResult> {
+  // 验证仓库是否存在
+  const EntityType = sm.rxdb.config.entities.find(e => {
+    const meta = getEntityMetadata(e);
+    return meta.namespace === namespace && meta.name === entity;
+  });
+
+  if (!EntityType) {
+    throw new RxDBError(`Entity not found: ${namespace}:${entity}`);
+  }
+
+  const metadata = getEntityMetadata(EntityType);
+
+  // 检查同步类型（支持全局配置回退）
+  const syncType = getSyncType(metadata, sm.rxdb.entitySync);
+  if (syncType === 'none') {
+    throw new RxDBError(
+      `Cannot sync repository ${namespace}:${entity}: syncType is 'none'. ` +
+        `This entity is not configured for remote synchronization.`
+    );
+  }
+
+  // 先执行拉取（确保我们拥有最新数据）
+  //
+  // 方向能力从 `getSyncCapability` 取，不再内联枚举 —— 此前这里漏了
+  // `querycache`（批量与单仓路径一直在拉它），同一个仓库走 sync 和走 pull 结果不一样。
+  // `RxDBSync.enabled` 不在这层判定：pullRepository / pushRepository 各自会拒，
+  // 在这里再判一次只会多读一遍系统表。
+  let pullResult: PullRepositoryResult;
+  const shouldPull =
+    (options?.direction === 'pull' || options?.direction === 'sync' || !options?.direction) &&
+    getSyncCapability(syncType).pull;
+
+  if (shouldPull) {
+    try {
+      pullResult = await pullRepository(sm, namespace, entity, options?.pull);
+    } catch (error) {
+      throw rewrapPullFailure(error, namespace, entity);
+    }
+  } else {
+    // 仅本地或仅推送：跳过拉取，创建占位结果
+    pullResult = emptyPullResult(namespace, entity);
+  }
+
+  // 执行推送（发送本地变更）
+  //
+  // 'local' 不可推：它的定义是「SyncType.None + 只配了 local adapter、没有 remote」，
+  // 公开契约把它写成「只在本地」。把它算成可推等于把私有本地数据送出去，
+  // 而且这类仓库根本没有 remote adapter，推送本就无意义。fail-closed。
+  let pushResult: PushRepositoryResult;
+  const shouldPush =
+    (options?.direction === 'push' || options?.direction === 'sync' || !options?.direction) &&
+    getSyncCapability(syncType).push;
+
+  if (shouldPush) {
+    try {
+      pushResult = await pushRepository(sm, namespace, entity, options?.push, rejectionSink);
+    } catch (error) {
+      // pull 已落库的进度、push 已发到远端的进度，都不能因为这次抛错就消失
+      throw rewrapPushFailure(error, pullResult, namespace, entity);
+    }
+  } else {
+    // 仅远端或仅拉取：跳过推送，创建占位结果
+    pushResult = emptyPushResult(namespace, entity);
+  }
+
+  return {
+    pullResult,
+    pushResult,
+    persistedProgress: pullResult.persistedProgress || pushResult.pushed > 0,
+    historyInvalidated: pullResult.historyInvalidated
+  };
+}

package/src/topological-sort.ts

@@ -0,0 +1,246 @@
+/**
+ * @fileoverview 拓扑排序算法
+ *
+ * 提供两种排序方向：
+ * - Pull（父->子）: 确保父实体先同步，外键引用的数据已存在
+ * - Push（子->父）: 确保子实体先同步，避免外键约束错误
+ */
+
+import { RxDBError } from '@aiao/rxdb';
+import type { DependencyGraph, RepositoryIdentifier } from './dependency-graph.js';
+
+/**
+ * 排序方向
+ */
+export type SortDirection = 'pull' | 'push';
+
+/**
+ * 依赖图上的一条边。
+ *
+ * - `dependsOn`：本仓库**依赖**的仓库（父，外键指过去的那一端）
+ * - `requiredBy`：**依赖本仓库**的仓库（子，外键指过来的那一端）
+ */
+export type DependencyEdge = 'dependsOn' | 'requiredBy';
+
+/**
+ * 排序方向沿依赖图上的哪条边展开。
+ *
+ * 这条对应关系是整个级联调度的枢纽，所以只在这里写一次：拓扑序沿哪条边建立，
+ * 「谁排在我前面」就是哪条边，级联的依赖闸门也必须看同一条边。
+ * 从前它以 `direction === 'pull' ? dep.dependsOn : dep.requiredBy` 的形式散在
+ * {@link topologicalSort} 里，闸门那一侧则各写各的，于是 DELETE 相位的闸门看错了边。
+ */
+export function dependencyEdgeOf(direction: SortDirection): DependencyEdge {
+  return direction === 'pull' ? 'dependsOn' : 'requiredBy';
+}
+
+/**
+ * 本相位该按哪个方向排序。
+ *
+ * DELETE 子先父后、INSERT/UPDATE 父先子后，理由见 {@link topologicalSortForAction}。
+ */
+function sortDirectionForAction(action: SortActionKind): SortDirection {
+  return action === 'DELETE' ? 'push' : 'pull';
+}
+
+/**
+ * 本相位的依赖闸门该看哪条边 —— 也就是「本相位里谁排在我前面」。
+ *
+ * DELETE 相位子先父后，父被子阻断，看 `requiredBy`；
+ * INSERT/UPDATE 相位父先子后，子被父阻断，看 `dependsOn`。
+ *
+ * 与 {@link topologicalSortForAction} 共用 {@link sortDirectionForAction}，
+ * 保证「执行顺序」和「阻断关系」不可能各说各话。
+ *
+ * @param action - 本相位提交的变更类型
+ * @returns 该相位下判定阻断所依据的依赖边
+ */
+export function dependencyEdgeForAction(action: SortActionKind): DependencyEdge {
+  return dependencyEdgeOf(sortDirectionForAction(action));
+}
+
+/**
+ * 拓扑排序
+ *
+ * @param graph - 依赖图
+ * @param direction - 排序方向
+ *   - 'pull': 父实体在前（User -> Todo -> Comment）
+ *   - 'push': 子实体在前（Comment -> Todo -> User）
+ * @returns 排序后的 repository 列表
+ *
+ * @example
+ * ```ts
+ * // Pull 顺序（父在前）
+ * const pullOrder = topologicalSort(graph, 'pull');
+ * // 返回: [User, Todo, Comment]
+ *
+ * // Push 顺序（子在前）
+ * const pushOrder = topologicalSort(graph, 'push');
+ * // 返回: [Comment, Todo, User]
+ * ```
+ */
+export function topologicalSort(graph: DependencyGraph, direction: SortDirection): RepositoryIdentifier[] {
+  // Pull: 使用 dependsOn（父实体先）
+  // Push: 使用 requiredBy（子实体先）
+  const result: RepositoryIdentifier[] = [];
+  const visited = new Set<string>();
+  const tempMarked = new Set<string>();
+
+  function visit(key: string): void {
+    if (visited.has(key)) return;
+
+    if (tempMarked.has(key)) {
+      throw new RxDBError(`Circular dependency detected at ${key}`);
+    }
+
+    tempMarked.add(key);
+
+    const dep = graph.get(key);
+    if (!dep) {
+      throw new RxDBError(`Repository ${key} not found in dependency graph`);
+    }
+
+    // 根据方向选择遍历的邻居（边的选择集中在 dependencyEdgeOf，闸门那一侧读同一份）
+    const neighbors = dep[dependencyEdgeOf(direction)];
+
+    for (const neighbor of neighbors) {
+      const neighborKey = `${neighbor.namespace}:${neighbor.entity}`;
+      // 跳过自引用（树形结构）
+      if (neighborKey === key) continue;
+      // 跳过悬挂依赖：关系可以指向没被注册进 config.entities 的实体（跨 namespace
+      // 部分注册、按需加载模块）。buildDependencyGraph 反向填充 requiredBy 时同样
+      // 是宽容的，这里不跳过就会让整个 pull/push 链路因一条无关关系而不可用。
+      if (!graph.has(neighborKey)) continue;
+      visit(neighborKey);
+    }
+
+    tempMarked.delete(key);
+    visited.add(key);
+
+    // Pull: 父实体先访问，后添加 -> 父在前
+    // Push: 子实体先访问，后添加 -> 子在前
+    result.push(dep.repository);
+  }
+
+  // 遍历所有节点
+  for (const key of graph.keys()) {
+    visit(key);
+  }
+
+  return result;
+}
+
+/**
+ * 拓扑排序（Pull 方向）
+ *
+ * 确保父实体在前，适用于 Pull 同步
+ *
+ * @param graph - 依赖图
+ * @returns 排序后的 repository 列表
+ */
+export function topologicalSortForPull(graph: DependencyGraph): RepositoryIdentifier[] {
+  return topologicalSort(graph, 'pull');
+}
+
+/**
+ * 拓扑排序（Push 方向）
+ *
+ * 确保子实体在前，适用于 Push 同步
+ *
+ * @param graph - 依赖图
+ * @returns 排序后的 repository 列表
+ */
+export function topologicalSortForPush(graph: DependencyGraph): RepositoryIdentifier[] {
+  return topologicalSort(graph, 'push');
+}
+
+/**
+ * 变更类型：决定安全的提交顺序
+ */
+export type SortActionKind = 'INSERT' | 'UPDATE' | 'DELETE';
+
+/**
+ * 按变更类型选排序方向
+ *
+ * 同一张依赖图，INSERT 和 DELETE 需要的顺序**正好相反**，「push 就是子→父」这个说法
+ * 只对 DELETE 成立：
+ *
+ * - `INSERT` / `UPDATE` → **父先**。子行的外键指向父行，父行不先落库就是悬空引用，FK 失败。
+ * - `DELETE` → **子先**。父行还被子行引用着，先删父同样 FK 失败。
+ *
+ * 所以一次级联推送不可能靠单一顺序扫完，必须分相位：DELETE 走一遍子→父，
+ * INSERT/UPDATE 再走一遍父→子。
+ *
+ * @param graph - 依赖图
+ * @param action - 本相位要提交的变更类型
+ * @returns 该类型下安全的提交顺序
+ *
+ * @example
+ * ```ts
+ * topologicalSortForAction(graph, 'INSERT'); // [User, Todo, Comment]
+ * topologicalSortForAction(graph, 'DELETE'); // [Comment, Todo, User]
+ * ```
+ */
+export function topologicalSortForAction(graph: DependencyGraph, action: SortActionKind): RepositoryIdentifier[] {
+  return topologicalSort(graph, sortDirectionForAction(action));
+}
+
+/**
+ * 过滤并排序指定的 repository 列表
+ *
+ * 从依赖图中只选择指定的 repositories，并按拓扑顺序排序
+ *
+ * @param graph - 完整依赖图
+ * @param repositories - 要排序的 repository 列表
+ * @param direction - 排序方向
+ * @returns 排序后的 repository 列表
+ *
+ * @example
+ * ```ts
+ * // 只同步 Todo 和 Comment
+ * const filtered = filterAndSort(
+ *   graph,
+ *   [
+ *     { namespace: 'public', entity: 'Todo' },
+ *     { namespace: 'public', entity: 'Comment' }
+ *   ],
+ *   'pull'
+ * );
+ * // 返回: [Todo, Comment]（按依赖顺序）
+ * ```
+ */
+export function filterAndSort(
+  graph: DependencyGraph,
+  repositories: RepositoryIdentifier[],
+  direction: SortDirection
+): RepositoryIdentifier[] {
+  // 创建子图，只包含指定的 repositories
+  const subGraph: DependencyGraph = new Map();
+  const keys = new Set(repositories.map(r => `${r.namespace}:${r.entity}`));
+
+  for (const key of keys) {
+    const dep = graph.get(key);
+    if (!dep) {
+      throw new RxDBError(`Repository ${key} not found in dependency graph`);
+    }
+
+    // 过滤依赖，只保留在 keys 中的
+    const filteredDependsOn = dep.dependsOn.filter(parent => {
+      const parentKey = `${parent.namespace}:${parent.entity}`;
+      return keys.has(parentKey);
+    });
+
+    const filteredRequiredBy = dep.requiredBy.filter(child => {
+      const childKey = `${child.namespace}:${child.entity}`;
+      return keys.has(childKey);
+    });
+
+    subGraph.set(key, {
+      repository: dep.repository,
+      dependsOn: filteredDependsOn,
+      requiredBy: filteredRequiredBy
+    });
+  }
+
+  return topologicalSort(subGraph, direction);
+}