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

package/src/cleanup-expired.ts

@@ -0,0 +1,285 @@
+/**
+ * @fileoverview 过期数据清理
+ *
+ * 清理不再满足 Filter 条件的本地过期数据。
+ * 删除操作不会记录到 RxDBChange，因此不会同步到远程。
+ */
+
+import {
+  declareTrustedWrite,
+  getEntityMetadata,
+  getRxDBChangeEntityIdQueryValues,
+  getRxDBEntityIdentityKey,
+  getSyncConfig,
+  getSyncType,
+  type OperatorName,
+  type Rule,
+  type RuleGroup,
+  RxDBChange,
+  type RxDBEntityId,
+  RxDBError,
+  type SwitchVersionActions,
+  TrustedWriteIntent
+} from '@aiao/rxdb';
+/**
+ * 仅要求「能拿到 RxDBChange 仓库并 find」的最小结构 —— 适配器与
+ * {@link TransactionExecutor} 都满足。声明成两者的联合类型会因泛型方法不可调用而失败。
+ */
+interface RxDBChangeRepositorySource {
+  getRepository(EntityType: typeof RxDBChange): { find(options: never): Promise<unknown> };
+}
+
+import type { SyncManager } from './SyncManager.js';
+
+/**
+ * 过期数据清理选项
+ */
+export interface CleanupExpiredOptions {
+  /**
+   * 过滤条件（可选）
+   * 如果不提供，从实体元数据的 sync.remote.filter() 获取
+   */
+  filter?: RuleGroup;
+
+  /**
+   * 干跑模式，只返回将被删除的数量
+   * @default false
+   */
+  dryRun?: boolean;
+}
+
+/**
+ * 过期数据清理结果
+ */
+export interface CleanupExpiredResult {
+  /**
+   * 被清理的记录数量
+   */
+  removed: number;
+
+  /**
+   * 被清理的实体 ID 列表（仅 dryRun 模式或实际删除时）
+   */
+  removedIds?: RxDBEntityId[];
+}
+
+/**
+ * 清理不再满足过滤条件的本地过期数据
+ *
+ * 注意: 删除操作不会记录到 RxDBChange，因此不会同步到远程
+ * 这适用于"只保留最近 N 天数据"的场景
+ *
+ * @param sm - SyncManager 实例
+ * @param namespace - 命名空间
+ * @param entityName - 实体名
+ * @param options - 清理选项
+ * @returns 清理结果
+ *
+ * @example
+ * ```ts
+ * const thirtyDaysAgo = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
+ * const { removed } = await cleanupExpired(sm, 'public', 'Order', {
+ *   filter: {
+ *     combinator: 'and',
+ *     rules: [{ field: 'updatedAt', operator: '>=', value: thirtyDaysAgo }]
+ *   }
+ * });
+ * console.log(`Removed ${removed} expired records`);
+ * ```
+ */
+export async function cleanupExpired(
+  sm: SyncManager,
+  namespace: string,
+  entityName: string,
+  options?: CleanupExpiredOptions
+): Promise<CleanupExpiredResult> {
+  const rxdb = sm.rxdb;
+  const { adapter: localAdapter } = await sm.getLocalRepositories();
+
+  // 验证实体存在
+  const EntityType = rxdb.config.entities.find(e => {
+    const meta = getEntityMetadata(e);
+    return meta.namespace === namespace && meta.name === entityName;
+  });
+
+  if (!EntityType) {
+    throw new RxDBError(`Entity not found: ${namespace}:${entityName}`);
+  }
+
+  const metadata = getEntityMetadata(EntityType);
+  const syncType = getSyncType(metadata, rxdb.entitySync);
+
+  // 获取 filter 条件
+  let filter = options?.filter;
+  if (!filter && syncType === 'filter') {
+    // 取生效配置而不是装饰器原值：实例覆盖可能换掉了 filter
+    const syncConfig = getSyncConfig(metadata, rxdb.entitySync) as { remote?: { filter?: () => RuleGroup } };
+    if (syncConfig?.remote?.filter) {
+      try {
+        filter = syncConfig.remote.filter();
+      } catch (error) {
+        throw new RxDBError(
+          `Filter function failed for ${namespace}:${entityName}: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    }
+  }
+
+  if (!filter) {
+    throw new RxDBError(
+      `No filter provided and entity ${namespace}:${entityName} does not have a Filter sync configuration.`
+    );
+  }
+
+  // 反转 filter 条件：找出不满足条件的记录
+  const invertedFilter = invertRuleGroup(filter);
+
+  /**
+   * 剔除仍有未推送变更的候选。
+   *
+   * 删除走 `mergeChanges(..., disableTriggers=true)`，**不产生 RxDBChange**。
+   * 若候选还有未推送的 INSERT/UPDATE，删掉就等于让那些变更永远推不出去，
+   * 远端则永久保留一条幽灵记录 —— 本地与远端从此分叉。这类候选一律跳过。
+   *
+   * `source` 必须由调用方传入，**不能在闭包里取**：本函数在事务外（dryRun）与事务内
+   * 各调用一次，两处的仓库归属不同 —— 事务内必须走 executor 的仓库，否则这次读会
+   * 重新排队并排在自己所在的事务后面（队列并发度 1），永久挂起。
+   */
+  const rejectUnpushed = async (
+    candidates: { id: RxDBEntityId }[],
+    source: RxDBChangeRepositorySource
+  ): Promise<{ id: RxDBEntityId }[]> => {
+    if (candidates.length === 0) return candidates;
+    const changeRepo = source.getRepository(RxDBChange);
+    const unpushed = await changeRepo.find({
+      where: {
+        combinator: 'and',
+        rules: [
+          { field: 'namespace', operator: '=', value: namespace },
+          { field: 'entity', operator: '=', value: entityName },
+          { field: 'remoteId', operator: '=', value: null },
+          // 被拒变更（rejectedAt 非空）的 remoteId 也一直是 null，但它永远不会再被推送，
+          // 必须和 remoteId = null 一起排除，否则会被误判成「还占着没推完」而继续
+          // 保护对应实体不被清理
+          { field: 'rejectedAt', operator: '=', value: null },
+          { field: 'revertChangeId', operator: '=', value: null },
+          {
+            field: 'entityId',
+            operator: 'in',
+            value: getRxDBChangeEntityIdQueryValues(candidates.map(record => record.id))
+          }
+        ]
+      }
+    } as never);
+    const blocked = new Set(
+      (unpushed as { entityId: RxDBEntityId }[]).map(change => getRxDBEntityIdentityKey(change.entityId))
+    );
+    return blocked.size === 0 ?
+        candidates
+      : candidates.filter(record => !blocked.has(getRxDBEntityIdentityKey(record.id)));
+  };
+
+  // dryRun 模式只报数、不删除；同样要扣除被保护的候选，否则报的数字是假的
+  if (options?.dryRun) {
+    const repo = localAdapter.getRepository(EntityType);
+    const preview = await rejectUnpushed(await repo.find({ where: invertedFilter }), localAdapter);
+    return {
+      removed: preview.length,
+      removedIds: preview.map(record => record.id)
+    };
+  }
+
+  // 复核 + 保护性检查 + 删除必须在同一本地事务内完成。
+  // 此前是「事务外查一次 → 按旧快照无条件删」：查询后若用户把记录更新回满足 filter，
+  // 仍会被删掉，是稳定可复现的数据破坏。
+  return localAdapter.transaction(async executor => {
+    // 仓库必须在事务体**内**经 executor 获取：事务外取到的句柄绑定在适配器上，
+    // 其读写会重新排队并排在自己这个事务后面
+    const repo = executor.getRepository(EntityType);
+    // 事务内重新查询，拿到的是最新快照（复核 filter）
+    const expiredRecords = await rejectUnpushed(await repo.find({ where: invertedFilter }), executor);
+    const removedIds = expiredRecords.map(record => record.id);
+
+    if (removedIds.length > 0) {
+      const deletes = new Map<string, { patch: null; inversePatch: null }>();
+      for (const record of expiredRecords) {
+        deletes.set(`${namespace}:${entityName}:${getRxDBEntityIdentityKey(record.id)}`, {
+          patch: null,
+          inversePatch: null
+        });
+      }
+      const actions: SwitchVersionActions = { deletes, updates: new Map(), inserts: new Map() };
+      // 使用 mergeChanges + disableTriggers 删除，避免生成 RxDBChange 记录
+      // 过期清理走 cleanup_expired 入口：删的是本地缓存副本，不是用户删的数据。
+      declareTrustedWrite(executor, {
+        file: 'cleanup-expired.ts',
+        symbol: 'cleanupExpired',
+        intent: TrustedWriteIntent.remote_sync
+      });
+      await executor.mergeChanges(actions, undefined, true);
+    }
+
+    return { removed: removedIds.length, removedIds };
+  });
+}
+
+/**
+ * 反转 RuleGroup 条件
+ *
+ * 将 filter 条件转换为"不满足条件"的查询
+ * 例如: updatedAt >= 30天前 → updatedAt < 30天前
+ */
+function invertRuleGroup(rg: RuleGroup): RuleGroup {
+  // 简单实现：使用 NOT 逻辑
+  // 对于 AND 条件：NOT (A AND B) = NOT A OR NOT B
+  // 对于 OR 条件：NOT (A OR B) = NOT A AND NOT B
+  return {
+    combinator: rg.combinator === 'and' ? 'or' : 'and',
+    rules: rg.rules.map(rule => {
+      if ('combinator' in rule) {
+        // 嵌套 RuleGroup
+        return invertRuleGroup(rule);
+      }
+      // 单个 Rule：反转操作符
+      return invertRule(rule);
+    })
+  };
+}
+
+/**
+ * 反转单个 Rule 的操作符
+ */
+function invertRule(rule: Rule): Rule {
+  const invertedOperators: Partial<Record<OperatorName, OperatorName>> = {
+    '=': '!=',
+    '!=': '=',
+    '<': '>=',
+    '<=': '>',
+    '>': '<=',
+    '>=': '<',
+    in: 'notIn',
+    notIn: 'in',
+    contains: 'notContains',
+    notContains: 'contains',
+    startsWith: 'notStartsWith',
+    notStartsWith: 'startsWith',
+    endsWith: 'notEndsWith',
+    notEndsWith: 'endsWith',
+    between: 'notBetween',
+    notBetween: 'between',
+    null: 'notNull',
+    notNull: 'null',
+    exists: 'notExists',
+    notExists: 'exists'
+  };
+
+  const invertedOperator = invertedOperators[rule.operator];
+  if (!invertedOperator) {
+    throw new RxDBError(`Cannot invert operator: ${rule.operator}`);
+  }
+
+  return {
+    ...rule,
+    operator: invertedOperator
+  } as Rule;
+}

package/src/dependency-graph.ts

@@ -0,0 +1,324 @@
+/**
+ * @fileoverview 实体依赖图构建与分析
+ *
+ * 基于 EntityMetadata 的 relations 构建依赖图，用于：
+ * - Pull: 父实体 -> 子实体（确保外键引用的数据已存在）
+ * - Push: 子实体 -> 父实体（确保外键约束不被违反）
+ */
+
+import { RelationKind, type RepositoryIdentifier, RxDBError } from '@aiao/rxdb';
+// 唯一定义收敛到 `VersionManager.interface.ts`。
+interface DependencyGraphEntityRelation {
+  kind: RelationKind;
+  mappedEntity: string;
+  mappedNamespace?: string;
+}
+
+interface DependencyGraphEntityMetadata {
+  name: string;
+  namespace: string;
+  relations?: readonly DependencyGraphEntityRelation[];
+}
+
+export type { RepositoryIdentifier };
+
+/**
+ * Repository 依赖关系
+ */
+export interface RepositoryDependency {
+  /**
+   * 当前 repository
+   */
+  repository: RepositoryIdentifier;
+
+  /**
+   * 依赖的 repository（外键指向的实体）
+   * Pull 时必须先同步这些实体
+   */
+  dependsOn: RepositoryIdentifier[];
+
+  /**
+   * 被依赖的 repository（指向当前实体的外键）
+   * Push 时必须等待这些实体同步完成
+   */
+  requiredBy: RepositoryIdentifier[];
+}
+
+/**
+ * 依赖图
+ * 键：`{namespace}:{entity}`。
+ */
+export type DependencyGraph = Map<string, RepositoryDependency>;
+
+/**
+ * 构建依赖图
+ *
+ * @param entities - 实体元数据数组
+ * @returns 依赖图
+ *
+ * @example
+ * ```ts
+ * const entities = entityManager.getEntities();
+ * const graph = buildDependencyGraph(entities);
+ *
+ * // 查询 Todo 的依赖
+ * const todoDep = graph.get('public:Todo');
+ * console.log(todoDep.dependsOn); // [{ namespace: 'public', entity: 'User' }]
+ * ```
+ */
+export function buildDependencyGraph(entities: readonly DependencyGraphEntityMetadata[]): DependencyGraph {
+  const graph: DependencyGraph = new Map();
+
+  // 第一遍：创建所有节点，分析直接依赖
+  for (const entity of entities) {
+    const key = `${entity.namespace}:${entity.name}`;
+    const dep: RepositoryDependency = {
+      repository: { namespace: entity.namespace, entity: entity.name },
+      dependsOn: [],
+      requiredBy: []
+    };
+
+    // 分析关系，找出外键依赖
+    if (entity.relations) {
+      for (const relation of entity.relations) {
+        // MANY_TO_ONE 和 ONE_TO_ONE 关系中，外键存储在当前实体侧
+        if (relation.kind === RelationKind.MANY_TO_ONE || relation.kind === RelationKind.ONE_TO_ONE) {
+          const mappedEntity = relation.mappedEntity;
+          const mappedNamespace = relation.mappedNamespace || entity.namespace;
+
+          dep.dependsOn.push({
+            namespace: mappedNamespace,
+            entity: mappedEntity
+          });
+        }
+      }
+    }
+
+    graph.set(key, dep);
+  }
+
+  // 第二遍：反向填充 requiredBy
+  for (const dep of graph.values()) {
+    for (const parent of dep.dependsOn) {
+      const parentDep = graph.get(`${parent.namespace}:${parent.entity}`);
+      if (parentDep) {
+        parentDep.requiredBy.push(dep.repository);
+      }
+    }
+  }
+
+  // 检测循环依赖
+  detectCycles(graph);
+
+  return graph;
+}
+
+/**
+ * 检测循环依赖
+ *
+ * 注意：自引用（self-reference）不算循环依赖，因为树形结构是合法的
+ * 例如：RxDBBranch -> RxDBBranch (parent-child 关系)
+ *
+ * @param graph - 依赖图
+ * @throws {RxDBError} 如果检测到循环依赖
+ *
+ * @example
+ * ```ts
+ * // 抛出错误示例：
+ * // User -> Profile -> User (循环依赖)
+ * detectCycles(graph); // 抛出 RxDBError
+ *
+ * // 允许的情况：
+ * // RxDBBranch -> RxDBBranch (自引用，树形结构)
+ * ```
+ */
+export function detectCycles(graph: DependencyGraph): void {
+  const visited = new Set<string>();
+  const recStack = new Set<string>();
+  const path: string[] = [];
+
+  function dfs(key: string): boolean {
+    visited.add(key);
+    recStack.add(key);
+    path.push(key);
+
+    const dep = graph.get(key);
+    if (!dep) {
+      // 悬挂依赖：回滚本次入栈再退出。漏掉回滚会把该 key 永久留在 recStack 里，
+      // 后续任何真实路径再指向它都会被判成循环依赖（误报）。
+      recStack.delete(key);
+      path.pop();
+      return false;
+    }
+
+    for (const parent of dep.dependsOn) {
+      const parentKey = `${parent.namespace}:${parent.entity}`;
+
+      // 跳过自引用（树形结构）
+      if (parentKey === key) {
+        continue;
+      }
+
+      if (!visited.has(parentKey)) {
+        if (dfs(parentKey)) return true;
+      } else if (recStack.has(parentKey)) {
+        // 找到循环依赖
+        const cycleStart = path.indexOf(parentKey);
+        const cycle = [...path.slice(cycleStart), parentKey];
+        throw new RxDBError(`Circular dependency detected: ${cycle.join(' -> ')}`);
+      }
+    }
+
+    recStack.delete(key);
+    path.pop();
+    return false;
+  }
+
+  for (const key of graph.keys()) {
+    if (!visited.has(key)) {
+      dfs(key);
+    }
+  }
+}
+
+/**
+ * 获取 repository 的所有依赖（包括间接依赖）
+ *
+ * 注意：自引用会被跳过，避免无限递归
+ *
+ * @param namespace - 命名空间
+ * @param entity - 实体名称
+ * @param graph - 依赖图
+ * @returns 所有依赖的 repository（拓扑排序，父在前）
+ *
+ * @example
+ * ```ts
+ * // Comment -> Todo -> User
+ * const deps = getAllDependencies('public', 'Comment', graph);
+ * // 返回: [User, Todo, Comment]
+ * ```
+ */
+export function getAllDependencies(namespace: string, entity: string, graph: DependencyGraph): RepositoryIdentifier[] {
+  const key = `${namespace}:${entity}`;
+  const dep = graph.get(key);
+  if (!dep) {
+    throw new RxDBError(`Repository ${key} not found in dependency graph`);
+  }
+
+  const result: RepositoryIdentifier[] = [];
+  const visited = new Set<string>();
+
+  function collect(currentKey: string): void {
+    if (visited.has(currentKey)) return;
+    visited.add(currentKey);
+
+    const currentDep = graph.get(currentKey);
+    if (!currentDep) return;
+
+    // 先递归收集依赖的实体
+    for (const parent of currentDep.dependsOn) {
+      const parentKey = `${parent.namespace}:${parent.entity}`;
+
+      // 跳过自引用（树形结构）
+      if (parentKey === currentKey) {
+        continue;
+      }
+
+      collect(parentKey);
+    }
+
+    // 再添加当前实体
+    result.push(currentDep.repository);
+  }
+
+  collect(key);
+  return result;
+}
+
+/**
+ * 获取 repository 的所有被依赖方（包括间接被依赖）
+ *
+ * 注意：自引用会被跳过，避免无限递归
+ *
+ * @param namespace - 命名空间
+ * @param entity - 实体名称
+ * @param graph - 依赖图
+ * @returns 所有被依赖的 repository（拓扑排序，子在前）
+ *
+ * @example
+ * ```ts
+ * // User <- Todo <- Comment
+ * const requiredBy = getAllRequiredBy('public', 'User', graph);
+ * // 返回: [Comment, Todo, User]
+ * ```
+ */
+export function getAllRequiredBy(namespace: string, entity: string, graph: DependencyGraph): RepositoryIdentifier[] {
+  const key = `${namespace}:${entity}`;
+  const dep = graph.get(key);
+  if (!dep) {
+    throw new RxDBError(`Repository ${key} not found in dependency graph`);
+  }
+
+  const result: RepositoryIdentifier[] = [];
+  const visited = new Set<string>();
+
+  function collect(currentKey: string): void {
+    if (visited.has(currentKey)) return;
+    visited.add(currentKey);
+
+    const currentDep = graph.get(currentKey);
+    if (!currentDep) return;
+
+    // 先递归收集被依赖的实体
+    for (const child of currentDep.requiredBy) {
+      const childKey = `${child.namespace}:${child.entity}`;
+
+      // 跳过自引用（树形结构）
+      if (childKey === currentKey) {
+        continue;
+      }
+
+      collect(childKey);
+    }
+
+    // 再添加当前实体
+    result.push(currentDep.repository);
+  }
+
+  collect(key);
+  return result;
+}
+
+/**
+ * 获取 repository 的直接父实体（一层依赖）
+ *
+ * @param namespace - 命名空间
+ * @param entity - 实体名称
+ * @param graph - 依赖图
+ * @returns 直接父实体列表
+ */
+export function getDirectParents(namespace: string, entity: string, graph: DependencyGraph): RepositoryIdentifier[] {
+  const key = `${namespace}:${entity}`;
+  const dep = graph.get(key);
+  if (!dep) {
+    throw new RxDBError(`Repository ${key} not found in dependency graph`);
+  }
+  return dep.dependsOn;
+}
+
+/**
+ * 获取 repository 的直接子实体（一层被依赖）
+ *
+ * @param namespace - 命名空间
+ * @param entity - 实体名称
+ * @param graph - 依赖图
+ * @returns 直接子实体列表
+ */
+export function getDirectChildren(namespace: string, entity: string, graph: DependencyGraph): RepositoryIdentifier[] {
+  const key = `${namespace}:${entity}`;
+  const dep = graph.get(key);
+  if (!dep) {
+    throw new RxDBError(`Repository ${key} not found in dependency graph`);
+  }
+  return dep.requiredBy;
+}