@aiao/rxdb 0.0.5 → 0.0.7

package/dist/version/VersionManager.d.ts

@@ -0,0 +1,407 @@
+import { EntityType } from '../entity/entity.interface.js';
+import { RestoreEntityOptions } from '../rxdb-adapter.js';
+import { RxDB } from '../RxDB.js';
+import { RxDBBranch } from '../system/branch.js';
+import { LocalRxDBBranchRepository, LocalRxDBChangeRepository } from '../system/types.local.js';
+import { RemoteRxDBBranchRepository, RemoteRxDBChangeRepository } from '../system/types.remote.js';
+import { BulkSyncOptions, BulkSyncResult } from './bulk-sync.js';
+import { CheckRepositoryUpdatesResult } from './check-repository-updates.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 { SyncRepositoryOptions, SyncRepositoryResult } from './sync-repository.js';
+import { SortDirection } from './topological-sort.js';
+import { HistoryScopeAPI, PullOptions, PullResult, PushOptions, PushResult, SyncResult } from './VersionManager.interface.js';
+/**
+ * 版本管理器
+ *
+ * 负责管理数据库的分支、撤销/重做功能和版本历史
+ * 核心功能包括：
+ * - 分支管理（创建、删除、切换）
+ * - 撤销/重做操作（数据库级别）
+ * - Redo 栈的自动失效（当有新操作时）
+ * - pull/push 同步到本地缓存
+ */
+export declare class VersionManager {
+    #private;
+    readonly rxdb: RxDB;
+    /**
+     * 撤销/重做辅助类
+     * 管理历史记录和内存 redo 栈
+     */
+    private historyManager;
+    /**
+     * 可 push 的变更数量流
+     *
+     * 实时追踪本地未推送的有效变更数量：
+     * - 排除已撤销的变更（revertChangeId != null）
+     * - 排除从远程 pull 来的变更（remoteId != null）
+     */
+    get pushableCount$(): import('rxjs').Observable<number>;
+    /**
+     * 远程待 pull 的变更数量流
+     *
+     * 通过监听远程事件（INSERT/UPDATE/DELETE）累计：
+     * - 收到远程变更事件时计数+1
+     * - pull 完成后计数重置为 0
+     *
+     * 用于 UI 显示"有 N 条远程更新可拉取"
+     */
+    get pullableCount$(): import('rxjs').Observable<number>;
+    constructor(rxdb: RxDB);
+    init(): void;
+    /**
+     * 创建新分支
+     * @param branchId 分支 id
+     * @param fromChangeId 从哪个 changeId 创建新分支
+     */
+    createBranch(branchId: string, fromChangeId?: number): Promise<InstanceType<typeof RxDBBranch>>;
+    /**
+     * 删除分支
+     * @param branchId 分支 id
+     */
+    removeBranch(branchId: string): Promise<void>;
+    /**
+     * 从远程拉取变更并应用到本地数据库
+     *
+     * 当 autoSync=false 时，会先应用 Realtime 缓存的变更，再拉取远程变更。
+     *
+     * @param options - 可选配置
+     * @returns 拉取结果
+     *
+     * @example
+     * ```typescript
+     * // 基本用法
+     * const result = await rxdb.versionManager.pull();
+     * console.log(`Pulled ${result.pulled} changes`);
+     *
+     * // 拉取所有数据
+     * const result = await rxdb.versionManager.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.versionManager.push();
+     * console.log(`Pushed ${result.pushed} changes`);
+     *
+     * // 自定义批量大小
+     * const result = await rxdb.versionManager.push({ batchSize: 500 });
+     * ```
+     */
+    push(options?: PushOptions): Promise<PushResult>;
+    /**
+     * 执行完整的同步操作（先 pull 再 push）
+     *
+     * 推荐在重连后使用此方法，确保：
+     * 1. 先获取远程最新变更（避免覆盖他人数据）
+     * 2. 再推送本地变更
+     *
+     * @param options - 可选配置
+     * @returns 同步结果（包含 pull 和 push 结果）
+     *
+     * @example
+     * ```typescript
+     * // 基本用法
+     * const result = await rxdb.versionManager.sync();
+     * console.log(`Pulled ${result.pullResult.pulled}, Pushed ${result.pushResult.pushed}`);
+     * ```
+     */
+    sync(options?: {
+        pull?: PullOptions;
+        push?: PushOptions;
+    }): Promise<SyncResult>;
+    /**
+     * Pull changes for a specific repository
+     *
+     * Provides fine-grained control over synchronization at the entity type level.
+     * Supports cascade synchronization to automatically pull related entities.
+     *
+     * @param namespace - Entity namespace (e.g., "public")
+     * @param entity - Entity name (e.g., "Todo")
+     * @param options - Pull options
+     * @returns Pull result
+     *
+     * @example
+     * ```typescript
+     * // Pull Todo repository with cascading dependencies
+     * const result = await rxdb.versionManager.pullRepository('public', 'Todo', {
+     *   includeRelated: true // Default: automatically pulls User if Todo has foreign key
+     * });
+     *
+     * // Pull without cascading
+     * const result = await rxdb.versionManager.pullRepository('public', 'Todo', {
+     *   includeRelated: false // Only pull Todo, may cause foreign key errors
+     * });
+     * ```
+     */
+    pullRepository(namespace: string, entity: string, options?: PullRepositoryOptions): Promise<PullRepositoryResult>;
+    /**
+     * Push changes for a specific repository
+     *
+     * Provides fine-grained control over synchronization at the entity type level.
+     * Supports cascade synchronization to automatically push dependent entities.
+     *
+     * @param namespace - Entity namespace (e.g., "public")
+     * @param entity - Entity name (e.g., "User")
+     * @param options - Push options
+     * @returns Push result
+     *
+     * @example
+     * ```typescript
+     * // Push User repository with cascading dependents
+     * const result = await rxdb.versionManager.pushRepository('public', 'User', {
+     *   includeRelated: true // Default: automatically pushes Post if Post references User
+     * });
+     *
+     * // Push without cascading
+     * const result = await rxdb.versionManager.pushRepository('public', 'User', {
+     *   includeRelated: false // Only push User, dependent data may be incomplete
+     * });
+     * ```
+     */
+    pushRepository(namespace: string, entity: string, options?: PushRepositoryOptions): Promise<PushRepositoryResult>;
+    /**
+     * Sync a specific repository (pull then push)
+     *
+     * Combines pull and push operations for a single repository, ensuring proper execution order.
+     * Recommended for ensuring data consistency when syncing a specific entity type.
+     *
+     * @param namespace - Entity namespace (e.g., "public")
+     * @param entity - Entity name (e.g., "Todo")
+     * @param options - Sync options (separate pull and push options)
+     * @returns Sync result (contains both pull and push results)
+     *
+     * @example
+     * ```typescript
+     * // Basic usage
+     * const result = await rxdb.versionManager.syncRepository('public', 'Todo');
+     * console.log(`Pulled ${result.pullResult.pulled}, Pushed ${result.pushResult.pushed}`);
+     *
+     * // Custom options for pull and push
+     * const result = await rxdb.versionManager.syncRepository('public', 'Todo', {
+     *   pull: { limit: 500, fetchAll: true },
+     *   push: { batchSize: 100 }
+     * });
+     * ```
+     */
+    syncRepository(namespace: string, entity: string, options?: SyncRepositoryOptions): Promise<SyncRepositoryResult>;
+    /**
+     * Check for remote updates without downloading data (T040, US2)
+     *
+     * This method only queries how many new changes exist remotely,
+     * without actually pulling the data. Useful for showing
+     * "N updates available" messages to save bandwidth and time.
+     *
+     * @param namespace - Entity namespace (e.g., "public")
+     * @param entity - Entity name (e.g., "Todo")
+     * @returns Update check result
+     *
+     * @example
+     * ```typescript
+     * // Check if Todo has remote updates
+     * const result = await rxdb.versionManager.checkRepositoryUpdates('public', 'Todo');
+     * if (result.hasUpdates) {
+     *   console.log(`${result.pendingCount} updates available`);
+     *   // User clicks "Update" button, then call pullRepository()
+     * }
+     * ```
+     */
+    checkRepositoryUpdates(namespace: string, entity: string): Promise<CheckRepositoryUpdatesResult>;
+    /**
+     * Get sync status for a single repository (T052, US3)
+     *
+     * Returns comprehensive sync status including:
+     * - syncType (full/remote/local/disabled)
+     * - pushableCount (number of local changes pending push)
+     * - pullableCount (number of remote changes available to pull)
+     * - Last sync timestamps
+     *
+     * @param namespace - Entity namespace (e.g., "public")
+     * @param entity - Entity name (e.g., "Todo")
+     * @returns Repository sync status
+     *
+     * @example
+     * ```typescript
+     * const status = await rxdb.versionManager.getRepositorySyncStatus('public', 'Todo');
+     * console.log(`Sync type: ${status.syncType}`);
+     * console.log(`Pushable: ${status.pushableCount}, Pullable: ${status.pullableCount}`);
+     * ```
+     */
+    getRepositorySyncStatus(namespace: string, entity: string): Promise<RepositorySyncStatus>;
+    /**
+     * Get sync status for all repositories (T053, US3)
+     *
+     * Returns status for all registered entities, with optional filtering.
+     *
+     * @param filter - Optional filter conditions
+     * @returns Array of repository sync statuses
+     *
+     * @example
+     * ```typescript
+     * // Get all statuses
+     * const statuses = await rxdb.versionManager.getAllRepositorySyncStatus();
+     *
+     * // Only get repositories with pending changes
+     * const pending = await rxdb.versionManager.getAllRepositorySyncStatus({
+     *   hasPendingChanges: true
+     * });
+     *
+     * // Only get enabled full-sync repositories
+     * const fullSync = await rxdb.versionManager.getAllRepositorySyncStatus({
+     *   syncType: ['full'],
+     *   enabled: true
+     * });
+     * ```
+     */
+    getAllRepositorySyncStatus(filter?: GetAllRepositorySyncStatusFilter): Promise<RepositorySyncStatus[]>;
+    /**
+     * Bulk sync multiple repositories
+     *
+     * Syncs multiple repositories in a single operation with support for
+     * sequential or concurrent execution.
+     *
+     * @param options - Bulk sync options
+     * @returns Bulk sync result with success/failure counts
+     *
+     * @example
+     * ```typescript
+     * // Sync all enabled repositories sequentially
+     * const result = await rxdb.versionManager.bulkSync();
+     * console.log(`Succeeded: ${result.succeeded}, Failed: ${result.failed}`);
+     *
+     * // Sync specific repositories
+     * const result = await rxdb.versionManager.bulkSync({
+     *   repositories: [
+     *     { namespace: 'public', entity: 'Todo' },
+     *     { namespace: 'public', entity: 'User' }
+     *   ]
+     * });
+     *
+     * // Concurrent sync with pull only
+     * const result = await rxdb.versionManager.bulkSync({
+     *   concurrent: true,
+     *   concurrency: 3,
+     *   push: false
+     * });
+     *
+     * // Inspect results
+     * for (const item of result.results) {
+     *   if (item.success) {
+     *     console.log(`${item.repository.entity}: pulled ${item.result.pull?.pulled || 0}`);
+     *   } else {
+     *     console.error(`${item.repository.entity}: ${item.error.message}`);
+     *   }
+     * }
+     * ```
+     */
+    bulkSync(options?: BulkSyncOptions): Promise<BulkSyncResult>;
+    /**
+     * Get dependency graph for all repositories
+     *
+     * Analyzes entity relationships (MANY_TO_ONE, ONE_TO_ONE) to build
+     * a dependency graph showing which repositories depend on others.
+     *
+     * @returns Dependency graph with repository dependencies
+     *
+     * @example
+     * ```typescript
+     * const graph = rxdb.versionManager.getRepositoryDependencyGraph();
+     *
+     * // Iterate through dependencies
+     * for (const [key, dep] of graph) {
+     *   console.log(`${key} depends on:`, dep.dependsOn);
+     *   console.log(`${key} is required by:`, dep.requiredBy);
+     * }
+     * ```
+     */
+    getRepositoryDependencyGraph(): DependencyGraph;
+    /**
+     * Get sync order for repositories based on dependencies
+     *
+     * Uses topological sort to determine the correct order for syncing
+     * repositories based on their dependencies.
+     *
+     * @param direction - Sort direction: 'pull' (parent first) or 'push' (child first)
+     * @returns Ordered list of repositories
+     *
+     * @example
+     * ```typescript
+     * // Get pull order (parents before children)
+     * const pullOrder = rxdb.versionManager.getRepositorySyncOrder('pull');
+     * // [User, Todo, Comment]
+     *
+     * // Get push order (children before parents)
+     * const pushOrder = rxdb.versionManager.getRepositorySyncOrder('push');
+     * // [Comment, Todo, User]
+     * ```
+     */
+    getRepositorySyncOrder(direction: SortDirection): RepositoryIdentifier[];
+    /**
+     * 切换到指定分支
+     *
+     * @param branchId - 目标分支 ID
+     *
+     * @remarks
+     * 切换分支后会自动清空 redo 栈，因为 redo 历史在新分支中不再有效。
+     * 如果目标分支与当前分支相同，则直接返回，避免不必要的操作。
+     */
+    switchBranch(branchId: string): Promise<void>;
+    /**
+     * 获取特定作用域的历史记录 API
+     *
+     * @param options - 作用域选项：
+     *   - 不传参数 → database 作用域（整个数据库）
+     *   - EntityType 类 → repository 作用域（该实体的所有记录）
+     *   - 实体实例 → entity 作用域（该实例的历史）
+     * @returns 统一的历史记录 API 接口
+     *
+     * @example
+     * ```ts
+     * // 数据库级别
+     * const dbHistory = versionManager.history();
+     *
+     * // 仓库级别（所有 User 记录）
+     * const userHistory = versionManager.history(User);
+     *
+     * // 实体级别（单个用户）
+     * const entityHistory = versionManager.history(userInstance);
+     * ```
+     */
+    history<T extends EntityType>(options?: T | InstanceType<T>): HistoryScopeAPI;
+    /**
+     * 恢复某个实体
+     * 复制实体的某个历史版本
+     * @param entity
+     * @param options
+     */
+    restoreEntity<T extends EntityType>(entity: InstanceType<T>, options: RestoreEntityOptions): Promise<InstanceType<T>>;
+    getLocalRepositories(): Promise<{
+        branchRepository: LocalRxDBBranchRepository;
+        changeRepository: LocalRxDBChangeRepository;
+        adapter: import('../rxdb-adapter.js').IRxDBAdapter & import('../rxdb-adapter.js').RxDBAdapterLocalBase;
+    }>;
+    getRemoteRepositories(): Promise<{
+        branchRepository: RemoteRxDBBranchRepository;
+        changeRepository: RemoteRxDBChangeRepository;
+        adapter: import('../rxdb-adapter.js').IRxDBAdapter & import('../rxdb-adapter.js').RxDBAdapterRemoteBase;
+    }>;
+    getCurrentBranch(): Promise<RxDBBranch>;
+}
+//# sourceMappingURL=VersionManager.d.ts.map

package/dist/version/VersionManager.d.ts.map

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