@vrtmrz/livesync-commonlib 0.1.18 → 0.1.19-rc.0

package/dist/API/DirectFileManipulatorV2.js

@@ -48,7 +48,9 @@ class DirectFileManipulator {
   async init() {
     try {
       await this.services.appLifecycle.onReady();
-      await this.liveSyncLocalDB.initializeDatabase();
+      if (!await this.liveSyncLocalDB.initializeDatabase()) {
+        throw new Error("Direct database initialisation was rejected.");
+      }
       this.liveSyncLocalDB.refreshSettings();
       this.ready.resolve();
     } catch (error) {

package/dist/common/models/fileaccess.type.d.ts

@@ -59,6 +59,13 @@ export type FileEventItem = {
     type: FileEventType;
     args: FileEventArgs;
     key: string;
+    /**
+     * The event was loaded from the persisted storage-operation snapshot.
+     *
+     * A restored event records pending operation intent, not current storage
+     * state. File handlers must revalidate it before applying side effects.
+     */
+    restoredFromPreviousRuntime?: true;
     skipBatchWait?: boolean;
     cancelled?: boolean;
     batched?: boolean;

package/dist/interfaces/DatabaseRebuilder.d.ts

@@ -17,7 +17,9 @@ export interface Rebuilder {
     /** See {@link scheduleRebuild}; this variant writes the Fetch flag. */
     scheduleFetch(prepareBeforeRestart?: () => Promise<void>): Promise<boolean>;
     /**
-     * Declares the finish of the rebuild process and unlock remote, resume reflecting the changes.
+     * Complete the final reflection scan and checks owned by a fetch, then establish application readiness.
+     *
+     * @returns `true` when every required completion phase succeeded; otherwise, `false`.
      */
-    finishRebuild(): Promise<void>;
+    finishRebuild(): Promise<boolean>;
 }

package/dist/managers/StorageEventManager.d.ts

@@ -21,6 +21,9 @@ type FileEventItemSentinelFlush = {
     type: typeof TYPE_SENTINEL_FLUSH;
 };
 export type FileEventItemSentinel = FileEventItemSentinelFlush;
+type RunQueuedEventsOptions = {
+    waitForProcessing?: boolean;
+};
 export interface StorageEventManagerBaseDependencies {
     setting: SettingService;
     vaultService: IVaultService;
@@ -61,13 +64,11 @@ export declare abstract class StorageEventManagerBase<TAdapter extends IStorageE
     protected updateStatus(): void;
     /**
      * Snapshot restoration promise.
-     * Snapshot will be restored before starting to watch vault changes.
-     * In designed time, this has been called from Initialisation process, which has been implemented on `ModuleInitializerFile.ts`.
+     * It resolves after the restored file operations have finished, before Vault watching begins.
      */
     snapShotRestored: Promise<void> | null;
     /**
-     * Restore the previous snapshot if exists.
-     * @returns
+     * Restore and complete the previous storage-event snapshot when it exists.
      */
     restoreState(): Promise<void>;
     appendQueue(params: FileEvent[], ctx?: unknown): Promise<void>;
@@ -111,7 +112,17 @@ export declare abstract class StorageEventManagerBase<TAdapter extends IStorageE
     processFileEvent(fei: FileEventItem): Promise<void>;
     _takeSnapshot(): Promise<void>;
     _restoreFromSnapshot(): Promise<void>;
-    protected runQueuedEvents(): Promise<void>;
+    /**
+     * Dispatch buffered storage events.
+     *
+     * Ordinary watcher events retain the existing fire-and-forget behaviour.
+     * Snapshot restoration requests completion so its caller can use the replay as
+     * a lifecycle boundary. In that mode, a sentinel also waits for every operation
+     * dispatched before it, preserving the ordering represented by the snapshot.
+     * An individual restored operation failure is logged but does not prevent the
+     * following Offline Scanner from reconciling the resulting current state.
+     */
+    protected runQueuedEvents(options?: RunQueuedEventsOptions): Promise<void>;
     protected processingCount: number;
     protected requestProcessQueue(fei: FileEventItem): Promise<void>;
     isWaiting(filename: FilePath): boolean;

package/dist/managers/StorageEventManager.js

@@ -72,13 +72,11 @@ class StorageEventManagerBase extends StorageEventManager {
   }
   /**
    * Snapshot restoration promise.
-   * Snapshot will be restored before starting to watch vault changes.
-   * In designed time, this has been called from Initialisation process, which has been implemented on `ModuleInitializerFile.ts`.
+   * It resolves after the restored file operations have finished, before Vault watching begins.
    */
   snapShotRestored = null;
   /**
-   * Restore the previous snapshot if exists.
-   * @returns
+   * Restore and complete the previous storage-event snapshot when it exists.
    */
   restoreState() {
     this.snapShotRestored = this._restoreFromSnapshot();
@@ -371,15 +369,44 @@ class StorageEventManagerBase extends StorageEventManager {
     const snapShot = await this._loadSnapshot();
     if (snapShot && Array.isArray(snapShot) && snapShot.length > 0) {
       this._log(`Restoring storage operation snapshot: ${snapShot.length} items`, LOG_LEVEL_VERBOSE);
-      this.bufferedQueuedItems = snapShot.map((e) => ({ ...e, skipBatchWait: true }));
+      this.bufferedQueuedItems = snapShot.map(
+        (event) => event.type === TYPE_SENTINEL_FLUSH ? event : { ...event, restoredFromPreviousRuntime: true, skipBatchWait: true }
+      );
       this.updateStatus();
-      await this.runQueuedEvents();
+      await this.runQueuedEvents({ waitForProcessing: true });
     } else {
       this._log(`No snapshot to restore`, LOG_LEVEL_VERBOSE);
     }
   }
-  runQueuedEvents() {
+  /**
+   * Dispatch buffered storage events.
+   *
+   * Ordinary watcher events retain the existing fire-and-forget behaviour.
+   * Snapshot restoration requests completion so its caller can use the replay as
+   * a lifecycle boundary. In that mode, a sentinel also waits for every operation
+   * dispatched before it, preserving the ordering represented by the snapshot.
+   * An individual restored operation failure is logged but does not prevent the
+   * following Offline Scanner from reconciling the resulting current state.
+   */
+  runQueuedEvents(options = {}) {
+    const waitForProcessing = options.waitForProcessing ?? false;
     return skipIfDuplicated("storage-event-manager-run-queued-events", async () => {
+      let dispatched = [];
+      const waitForDispatched = async () => {
+        if (dispatched.length === 0) return;
+        const pending = dispatched;
+        dispatched = [];
+        const results = await Promise.allSettled(pending.map(({ processing }) => processing));
+        for (const [index, result] of results.entries()) {
+          if (result.status === "rejected") {
+            this._log(
+              `Restored storage operation failed for ${pending[index].path}; the Offline Scanner will reconcile the current state`,
+              LOG_LEVEL_NOTICE
+            );
+            this._log(result.reason, LOG_LEVEL_VERBOSE);
+          }
+        }
+      };
       do {
         if (this.bufferedQueuedItems.length === 0) {
           break;
@@ -392,12 +419,23 @@ class StorageEventManagerBase extends StorageEventManager {
         this.updateStatus();
         if (fei.type === TYPE_SENTINEL_FLUSH) {
           this._log(`Waiting for idle`, LOG_LEVEL_VERBOSE);
+          if (waitForProcessing) {
+            await waitForDispatched();
+          }
           await this.waitForIdle();
           this.updateStatus();
           continue;
         }
-        fireAndForget(() => this.processFileEvent(fei));
+        const processing = this.processFileEvent(fei);
+        if (waitForProcessing) {
+          dispatched.push({ path: fei.args.file.path, processing });
+        } else {
+          fireAndForget(processing);
+        }
       } while (this.bufferedQueuedItems.length > 0);
+      if (waitForProcessing) {
+        await waitForDispatched();
+      }
     });
   }
   processingCount = 0;

package/dist/pouchdb/LiveSyncLocalDB.d.ts

@@ -46,11 +46,17 @@ export declare class LiveSyncLocalDB {
     env: LiveSyncLocalDBEnv;
     clearCaches(): void;
     _prepareHashFunctions(): Promise<void>;
-    onunload(): void;
     refreshSettings(): void;
     offRemoteChunkFetchedHandler?: ReturnType<LiveSyncEventHub["onEvent"]>;
+    private databaseCloseCleanup?;
+    private databaseUnloadNotification?;
     constructor(dbname: string, env: LiveSyncLocalDBEnv);
+    /** Notify dependent services at most once for each physical database lifecycle. */
+    private notifyDatabaseUnload;
+    onunload(): void;
     close(): Promise<void>;
+    private teardownDatabaseDependencies;
+    private rollbackFailedInitialisation;
     onNewLeaf(chunk: EntryLeaf): void;
     initializeDatabase(): Promise<boolean>;
     /**

package/dist/pouchdb/LiveSyncLocalDB.js

@@ -37,16 +37,14 @@ class LiveSyncLocalDB {
   async _prepareHashFunctions() {
     await this._managers?.prepareHashFunction();
   }
-  onunload() {
-    void this.env.services.databaseEvents.onUnloadDatabase(this);
-    this.localDatabase.removeAllListeners();
-  }
   refreshSettings() {
     const settings = this.env.services.setting.currentSettings();
     this.settings = settings;
     void this._prepareHashFunctions();
   }
   offRemoteChunkFetchedHandler;
+  databaseCloseCleanup;
+  databaseUnloadNotification;
   constructor(dbname, env) {
     this.auth = {
       username: "",
@@ -57,14 +55,79 @@ class LiveSyncLocalDB {
     this._log = createInstanceLogFunction("LiveSyncLocalDB", this.env.services.API);
     this.refreshSettings();
   }
+  /** Notify dependent services at most once for each physical database lifecycle. */
+  notifyDatabaseUnload() {
+    if (!this.databaseUnloadNotification) {
+      this.databaseUnloadNotification = Promise.resolve().then(async () => {
+        await this.env.services.databaseEvents.onUnloadDatabase(this);
+      });
+    }
+    return this.databaseUnloadNotification;
+  }
+  onunload() {
+    void this.notifyDatabaseUnload();
+  }
   async close() {
     this._log("Database closed (by close)");
     this.isReady = false;
     this.offRemoteChunkFetchedHandler?.();
+    this.offRemoteChunkFetchedHandler = void 0;
     if (this.localDatabase != null) {
-      await this.localDatabase.close();
+      const database = this.localDatabase;
+      await database.close();
+      if (this.databaseCloseCleanup?.database === database) {
+        await this.databaseCloseCleanup.promise;
+      }
+      if (this.localDatabase === database) {
+        this.localDatabase = null;
+      }
+    }
+    this._managers = void 0;
+    await this.notifyDatabaseUnload();
+  }
+  async teardownDatabaseDependencies(managers) {
+    try {
+      await Promise.resolve(this.env.services.replicator.getActiveReplicator()?.closeReplication());
+    } catch (error) {
+      this._log("Failed to close replication while tearing down the local database.", LOG_LEVEL_VERBOSE);
+      this._log(error, LOG_LEVEL_VERBOSE);
+    }
+    try {
+      await managers.teardownManagers();
+    } catch (error) {
+      this._log("Failed to tear down managers while closing the local database.", LOG_LEVEL_VERBOSE);
+      this._log(error, LOG_LEVEL_VERBOSE);
+    }
+  }
+  async rollbackFailedInitialisation(database, managers) {
+    this.isReady = false;
+    this.offRemoteChunkFetchedHandler?.();
+    this.offRemoteChunkFetchedHandler = void 0;
+    const closeCleanup = this.databaseCloseCleanup?.database === database ? this.databaseCloseCleanup : void 0;
+    if (closeCleanup) {
+      await closeCleanup.promise;
+    } else {
+      database.removeAllListeners();
+      await this.teardownDatabaseDependencies(managers);
+      try {
+        await database.close();
+      } catch (error) {
+        this._log("Failed to close the database after its initialisation was rejected.", LOG_LEVEL_VERBOSE);
+        this._log(error, LOG_LEVEL_VERBOSE);
+      }
+    }
+    if (this.localDatabase === database) {
+      this.localDatabase = null;
+    }
+    if (this._managers === managers) {
+      this._managers = void 0;
+    }
+    try {
+      await this.notifyDatabaseUnload();
+    } catch (error) {
+      this._log("A database unload handler failed after initialisation was rejected.", LOG_LEVEL_VERBOSE);
+      this._log(error, LOG_LEVEL_VERBOSE);
     }
-    await this.env.services.databaseEvents.onUnloadDatabase(this);
   }
   onNewLeaf(chunk) {
     this.managers.chunkManager?.emitEvent(EVENT_CHUNK_FETCHED, chunk);
@@ -84,6 +147,7 @@ class LiveSyncLocalDB {
         deterministic_revs: true
       }
     );
+    this.databaseUnloadNotification = void 0;
     const manager = new LiveSyncManagers({
       database: this.localDatabase,
       APIService: this.env.services.API,
@@ -93,38 +157,53 @@ class LiveSyncLocalDB {
       databaseService: this.env.services.database
     });
     this._managers = manager;
-    if (!await this.env.services.databaseEvents.onDatabaseInitialisation(this)) {
-      this._log("Initializing Database has been failed on some module", LOG_LEVEL_NOTICE);
-    }
-    this._log("Opening Database...");
-    this._log("Database info", LOG_LEVEL_VERBOSE);
-    this._log(JSON.stringify(await this.localDatabase.info(), null, 2), LOG_LEVEL_VERBOSE);
-    await this.managers.initialise();
-    this.localDatabase.on("close", () => {
-      this._log("Database closed.");
-      this.isReady = false;
-      this.localDatabase.removeAllListeners();
-      this.env.services.replicator.getActiveReplicator()?.closeReplication();
-      void this.managers.teardownManagers();
-    });
-    const _instance = new FallbackWeakRef(this);
-    const unload = this.env.services.context.events.onEvent(REMOTE_CHUNK_FETCHED, (chunk) => {
-      if (_instance.deref() == null) {
-        unload();
+    const openedDatabase = this.localDatabase;
+    this.databaseCloseCleanup = void 0;
+    try {
+      if (!await this.env.services.databaseEvents.onDatabaseInitialisation(this)) {
+        await this.rollbackFailedInitialisation(openedDatabase, manager);
+        this._log("Database initialisation was rejected by a required module.", LOG_LEVEL_NOTICE);
+        return false;
       }
-      _instance.deref()?.onNewLeaf(chunk);
-    });
-    this.offRemoteChunkFetchedHandler = unload;
-    this.isReady = true;
-    if (!await this.env.services.databaseEvents.onDatabaseHasReady()) {
-      this._log(
-        "Some module has prevented the database from being ready. The database is initialised but not ready for use.",
-        LOG_LEVEL_NOTICE
-      );
-      return false;
+      this._log("Opening Database...");
+      this._log("Database info", LOG_LEVEL_VERBOSE);
+      this._log(JSON.stringify(await openedDatabase.info(), null, 2), LOG_LEVEL_VERBOSE);
+      await manager.initialise();
+      openedDatabase.on("close", () => {
+        this._log("Database closed.");
+        this.isReady = false;
+        openedDatabase.removeAllListeners();
+        if (this.databaseCloseCleanup?.database !== openedDatabase) {
+          this.databaseCloseCleanup = {
+            database: openedDatabase,
+            promise: this.teardownDatabaseDependencies(manager)
+          };
+        }
+      });
+      const _instance = new FallbackWeakRef(this);
+      const unload = this.env.services.context.events.onEvent(REMOTE_CHUNK_FETCHED, (chunk) => {
+        if (_instance.deref() == null) {
+          unload();
+        }
+        _instance.deref()?.onNewLeaf(chunk);
+      });
+      this.offRemoteChunkFetchedHandler = unload;
+      this.isReady = true;
+      const readyAccepted = await this.env.services.databaseEvents.onDatabaseHasReady();
+      if (!readyAccepted || this.localDatabase !== openedDatabase || !this.isReady) {
+        await this.rollbackFailedInitialisation(openedDatabase, manager);
+        this._log(
+          "Some module has prevented the database from being ready. The database is initialised but not ready for use.",
+          LOG_LEVEL_NOTICE
+        );
+        return false;
+      }
+      this._log("Database is now ready.");
+      return true;
+    } catch (error) {
+      await this.rollbackFailedInitialisation(openedDatabase, manager);
+      throw error;
     }
-    this._log("Database is now ready.");
-    return true;
   }
   /**
    * Retrieve all used and existing chunks in the database.
@@ -212,6 +291,7 @@ class LiveSyncLocalDB {
     return { used, existing };
   }
   async resetDatabase() {
+    this.isReady = false;
     await this.managers.teardownManagers();
     this.env.services.replicator.getActiveReplicator()?.closeReplication();
     if (!await this.env.services.databaseEvents.onResetDatabase(this)) {
@@ -219,10 +299,12 @@ class LiveSyncLocalDB {
       return false;
     }
     Logger("Database closed for reset Database.");
-    this.isReady = false;
     await this.localDatabase.destroy();
     this.localDatabase = null;
-    await this.initializeDatabase();
+    if (!await this.initializeDatabase()) {
+      this._log("Local Database could not be reinitialised after reset.", LOG_LEVEL_NOTICE);
+      return false;
+    }
     this._log("Local Database Reset", LOG_LEVEL_NOTICE);
     return true;
   }

package/dist/serviceFeatures/prepareDatabaseForUse.js

@@ -4,26 +4,29 @@ import { createInstanceLogFunction } from "../services/lib/logUtils.js";
 async function prepareDatabaseForUse(host, log, errorManager, showingNotice = false, reopenDatabase = true, ignoreSuspending = false) {
   const appLifecycle = host.services.appLifecycle;
   appLifecycle.resetIsReady();
-  if (!reopenDatabase || await host.services.database.openDatabase({
+  if (reopenDatabase && !await host.services.database.openDatabase({
     databaseEvents: host.services.databaseEvents,
     replicator: host.services.replicator
   })) {
-    if (host.services.database.localDatabase.isReady) {
-      await host.services.vault.scanVault(showingNotice, ignoreSuspending);
-    }
-    const ERR_INITIALISATION_FAILED = `Initializing database has been failed on some module!`;
-    if (!await host.services.databaseEvents.onDatabaseInitialised(showingNotice)) {
-      errorManager.showError(ERR_INITIALISATION_FAILED, LOG_LEVEL_NOTICE);
-      return false;
-    }
-    errorManager.clearError(ERR_INITIALISATION_FAILED);
-    appLifecycle.markIsReady();
-    await host.services.fileProcessing.commitPendingFileEvents();
-    return true;
-  } else {
-    appLifecycle.resetIsReady();
     return false;
   }
+  if (!host.services.database.isDatabaseReady()) {
+    return false;
+  }
+  if (!await host.services.vault.scanVault(showingNotice, ignoreSuspending)) {
+    return false;
+  }
+  const ERR_INITIALISATION_FAILED = `Initializing database has been failed on some module!`;
+  if (!await host.services.databaseEvents.onDatabaseInitialised(showingNotice)) {
+    errorManager.showError(ERR_INITIALISATION_FAILED, LOG_LEVEL_NOTICE);
+    return false;
+  }
+  errorManager.clearError(ERR_INITIALISATION_FAILED);
+  if (!await host.services.fileProcessing.commitPendingFileEvents()) {
+    return false;
+  }
+  appLifecycle.markIsReady();
+  return true;
 }
 function usePrepareDatabaseForUse(host) {
   const log = createInstanceLogFunction("SF:prepareDatabaseForUse", host.services.API);

package/dist/serviceModules/Rebuilder.d.ts

@@ -14,6 +14,7 @@ import type { StorageAccess } from "../interfaces/StorageAccess.js";
 import type { LiveSyncEventHub } from "../hub/hub.js";
 import { ServiceModuleBase } from "./ServiceModuleBase.js";
 import type { ControlService } from "../services/base/ControlService.js";
+import type { IFileProcessingService } from "../services/base/IService.js";
 export interface ServiceRebuilderDependencies {
     events: LiveSyncEventHub;
     appLifecycle: AppLifecycleService;
@@ -28,6 +29,7 @@ export interface ServiceRebuilderDependencies {
     replication: ReplicationService;
     database: DatabaseService;
     fileHandler: IFileHandler;
+    fileProcessing: IFileProcessingService;
     control: ControlService;
 }
 export declare class ServiceRebuilder extends ServiceModuleBase<ServiceRebuilderDependencies> implements Rebuilder {
@@ -44,6 +46,7 @@ export declare class ServiceRebuilder extends ServiceModuleBase<ServiceRebuilder
     private replication;
     private database;
     private fileHandler;
+    private fileProcessing;
     private control;
     constructor(services: ServiceRebuilderDependencies);
     $performRebuildDB(method: "localOnly" | "remoteOnly" | "rebuildBothByThisDevice" | "localOnlyWithChunks"): Promise<void>;
@@ -63,17 +66,37 @@ export declare class ServiceRebuilder extends ServiceModuleBase<ServiceRebuilder
     private _onResetLocalDatabase;
     suspendAllSync(): Promise<void>;
     suspendReflectingDatabase(ignoreMinIO?: boolean): Promise<void>;
-    resumeReflectingDatabase(ignoreMinIO?: boolean): Promise<void>;
+    /**
+     * Stage reflection resumption and perform the final reconciliation checks.
+     *
+     * File watching is resumed in memory before the final scan so that changes
+     * made while the scan is running can enter the storage-event queue. This
+     * phase deliberately does not persist the resumed settings. The owning
+     * completion boundary persists them only after the scan, replication
+     * pre-check, and current batch-wait release have succeeded.
+     *
+     * @param ignoreMinIO Whether to resume reflection for a MinIO remote.
+     * @returns `true` when the applicable reconciliation checks succeeded.
+     */
+    resumeReflectingDatabase(ignoreMinIO?: boolean): Promise<boolean>;
+    private prepareLocalDatabaseForRebuild;
+    private completePreparedRebuild;
     fetchLocal(makeLocalChunkBeforeSync?: boolean, preventMakeLocalFilesBeforeSync?: boolean, autoResume?: boolean): Promise<void>;
     private performFetchLocal;
     fetchLocalDBFast(autoResume: boolean): Promise<void>;
     private performFetchLocalDBFast;
     /**
-     * Finish rebuild process with resuming the reflection.
+     * Complete the final rebuild phases and establish application readiness.
+     *
+     * A failed completion restores the previous reflection settings in memory.
+     * Persistence atomicity remains a responsibility of the host setting store;
+     * Commonlib cannot roll back a store which writes successfully and then
+     * reports an error.
      *
-     * @param ignoreMinIO Whether to ignore minio for resuming the reflection.
+     * @param ignoreMinIO Whether to resume reflection for a MinIO remote.
+     * @returns `true` when finalisation completed; otherwise, `false`.
      */
-    finishRebuild(ignoreMinIO?: boolean): Promise<void>;
+    finishRebuild(ignoreMinIO?: boolean): Promise<boolean>;
     /**
      * Fetch local database with making all chunks.
      * This is a wrapper for {@link fetchLocal} with makeLocalChunkBeforeSync = true.