@vrtmrz/livesync-commonlib 0.1.0-rc.0

package/dist/serviceFeatures/offlineScanner.js

@@ -0,0 +1,553 @@
+import { unique } from "octagonal-wheels/collection";
+import { withConcurrency } from "octagonal-wheels/iterable/map";
+import {
+  LOG_LEVEL_DEBUG,
+  LOG_LEVEL_INFO,
+  LOG_LEVEL_NOTICE,
+  LOG_LEVEL_VERBOSE,
+  isMetaEntry
+} from "../common/types.js";
+import { compareMTime, isAnyNote } from "../common/utils.js";
+import { stripAllPrefixes } from "../string_and_binary/path.js";
+import { createInstanceLogFunction } from "../services/lib/logUtils.js";
+import { BASE_IS_NEW, EVEN, TARGET_IS_NEW } from "../common/models/shared.const.symbols.js";
+import { UnresolvedErrorManager } from "../services/base/UnresolvedErrorManager.js";
+import { compatGlobal } from "../common/coreEnvFunctions.js";
+async function collectDeletedFiles(host, log) {
+  const limitDays = host.services.setting.currentSettings().automaticallyDeleteMetadataOfDeletedFiles;
+  if (limitDays <= 0) return;
+  log(`Checking expired file history`);
+  const limit = Date.now() - 86400 * 1e3 * limitDays;
+  const notes = [];
+  for await (const doc of host.services.database.localDatabase.findAllDocs({ conflicts: true })) {
+    if (isAnyNote(doc)) {
+      if (doc.deleted && doc.mtime - limit < 0) {
+        notes.push({
+          path: doc.path,
+          mtime: doc.mtime,
+          ttl: (doc.mtime - limit) / 1e3 / 86400,
+          doc
+        });
+      }
+    }
+  }
+  if (notes.length === 0) {
+    log("There are no old documents");
+    log(`Checking expired file history done`);
+    return;
+  }
+  for (const v of notes) {
+    log(`Deletion history expired: ${v.path}`);
+    const delDoc = v.doc;
+    delDoc._deleted = true;
+    await host.services.database.localDatabase.putRaw(delDoc);
+  }
+  log(`Checking expired file history done`);
+}
+function getPathFromEntry(host, doc) {
+  const path = host.services.path.getPath(doc);
+  return path;
+}
+async function syncFileBetweenDBandStorage(host, log, file, doc) {
+  const docPath = getPathFromEntry(host, doc);
+  if (!doc) {
+    throw new Error(`Missing doc:${docPath}`);
+  }
+  const compareResult = host.services.path.compareFileFreshness(file, doc);
+  switch (compareResult) {
+    case BASE_IS_NEW:
+      if (!host.services.vault.isFileSizeTooLarge(file.stat.size)) {
+        log("STORAGE -> DB :" + file.path);
+        await host.serviceModules.fileHandler.storeFileToDB(file);
+      } else {
+        log(
+          `STORAGE -> DB : ${file.path} has been skipped due to file size exceeding the limit`,
+          LOG_LEVEL_NOTICE
+        );
+      }
+      break;
+    case TARGET_IS_NEW:
+      if (!host.services.vault.isFileSizeTooLarge(doc.size)) {
+        log("STORAGE <- DB :" + docPath);
+        if (await host.serviceModules.fileHandler.dbToStorage(doc, stripAllPrefixes(docPath), false)) {
+          host.services.context.events.emitEvent("event-file-changed", {
+            file: file.path,
+            automated: true
+          });
+        } else {
+          log(`STORAGE <- DB : Cloud not read ${file.path}, possibly deleted`, LOG_LEVEL_NOTICE);
+        }
+      } else {
+        log(
+          `STORAGE <- DB : ${file.path} has been skipped due to file size exceeding the limit`,
+          LOG_LEVEL_NOTICE
+        );
+      }
+      break;
+    case EVEN:
+      log("STORAGE == DB :" + file.path, LOG_LEVEL_DEBUG);
+      break;
+    default:
+      log("STORAGE ?? DB :" + file.path + " Something got weird");
+  }
+}
+function canProceedScan(host, errorManager, log, showingNotice = false, ignoreSuspending = false) {
+  const settings = host.services.setting.currentSettings();
+  const ERR_NOT_CONFIGURED = "LiveSync is not configured yet. Synchronising between the storage and the local database is now prevented.";
+  if (!settings.isConfigured) {
+    errorManager.showError(ERR_NOT_CONFIGURED, showingNotice ? LOG_LEVEL_NOTICE : LOG_LEVEL_INFO);
+    return false;
+  }
+  errorManager.clearError(ERR_NOT_CONFIGURED);
+  const ERR_SUSPENDING = "Now suspending file watching. Synchronising between the storage and the local database is now prevented.";
+  if (!ignoreSuspending && settings.suspendFileWatching) {
+    errorManager.showError(ERR_SUSPENDING, showingNotice ? LOG_LEVEL_NOTICE : LOG_LEVEL_INFO);
+    return false;
+  }
+  errorManager.clearError(ERR_SUSPENDING);
+  const MSG_IN_REMEDIATION = `Started in remediation Mode! (Max mtime for reflect events is set). Synchronising between the storage and the local database is now prevented.`;
+  if (settings.maxMTimeForReflectEvents > 0) {
+    errorManager.showError(MSG_IN_REMEDIATION, LOG_LEVEL_NOTICE);
+    return false;
+  }
+  errorManager.clearError(MSG_IN_REMEDIATION);
+  return true;
+}
+function convertCase(settings, path) {
+  if (settings.handleFilenameCaseSensitive) {
+    return path;
+  }
+  return path.toLowerCase();
+}
+async function collectFilesOnStorage(host, settings, log) {
+  log("Collecting local files on the storage", LOG_LEVEL_VERBOSE);
+  const filesStorageSrc = await host.serviceModules.storageAccess.getFiles();
+  const _filesStorage = [];
+  for (const f of filesStorageSrc) {
+    if (await host.services.vault.isTargetFile(f.path)) {
+      _filesStorage.push(f);
+    }
+  }
+  const storageFileNameMap = Object.fromEntries(_filesStorage.map((e) => [e.path, e]));
+  const storageFileNames = Object.keys(storageFileNameMap);
+  const storageFileNameCapsPair = storageFileNames.map((e) => [e, convertCase(settings, e)]);
+  const storageFileNameCI2CS = Object.fromEntries(storageFileNameCapsPair.map((e) => [e[1], e[0]]));
+  return { storageFileNameMap, storageFileNames, storageFileNameCI2CS };
+}
+async function collectDatabaseFiles(host, settings, log, showingNotice) {
+  log("Collecting local files on the DB", LOG_LEVEL_VERBOSE);
+  const _DBEntries = [];
+  let count = 0;
+  for await (const doc of host.services.database.localDatabase.findAllNormalDocs({ conflicts: true }) || []) {
+    count++;
+    if (count % 25 === 0)
+      log(
+        `Collecting local files on the DB: ${count}`,
+        showingNotice ? LOG_LEVEL_NOTICE : LOG_LEVEL_INFO,
+        "syncAll"
+      );
+    const path = getPathFromEntry(host, doc);
+    if (host.services.vault.isValidPath(path) && await host.services.vault.isTargetFile(path)) {
+      if (!isMetaEntry(doc)) {
+        log(`Invalid entry: ${path}`, LOG_LEVEL_INFO);
+        continue;
+      }
+      _DBEntries.push(doc);
+    }
+  }
+  const databaseFileNameMap = Object.fromEntries(_DBEntries.map((e) => [getPathFromEntry(host, e), e]));
+  const databaseFileNames = Object.keys(databaseFileNameMap);
+  const databaseFileNameCapsPair = databaseFileNames.map((e) => [e, convertCase(settings, e)]);
+  const databaseFileNameCI2CS = Object.fromEntries(databaseFileNameCapsPair.map((e) => [e[1], e[0]]));
+  return { databaseFileNameMap, databaseFileNames, databaseFileNameCI2CS };
+}
+async function updateToDatabase(host, log, logLevel, file) {
+  if (!host.services.vault.isFileSizeTooLarge(file.stat.size)) {
+    const path = file.path;
+    await host.serviceModules.fileHandler.storeFileToDB(file);
+    host.services.context.events.emitEvent("event-file-changed", { file: path, automated: true });
+  } else {
+    log(`UPDATE DATABASE: ${file.path} has been skipped due to file size exceeding the limit`, logLevel);
+  }
+}
+async function updateToStorage(host, log, logLevel, w) {
+  const path = getPathFromEntry(host, w);
+  if (w && !(w.deleted || w._deleted)) {
+    if (!host.services.vault.isFileSizeTooLarge(w.size)) {
+      if ((w._conflicts?.length ?? 0) > 0) {
+        log(`UPDATE STORAGE: ${path} has conflicts. skipped (x)`, LOG_LEVEL_INFO);
+        return;
+      }
+      await host.serviceModules.fileHandler.dbToStorage(path, null, true);
+      host.services.context.events.emitEvent("event-file-changed", {
+        file: path,
+        automated: true
+      });
+      log(`Check or pull from db:${path} OK`);
+    } else {
+      log(`UPDATE STORAGE: ${path} has been skipped due to file size exceeding the limit`, logLevel);
+    }
+  } else if (w) {
+    log(`Deletion history skipped: ${path}`, LOG_LEVEL_VERBOSE);
+  } else {
+    log(`entry not found: ${path}`);
+  }
+}
+async function syncStorageAndDatabase(host, log, file, logLevel, doc) {
+  if ((doc._conflicts?.length ?? 0) > 0) {
+    log(`SYNC DATABASE AND STORAGE: ${file.path} has conflicts. skipped`, LOG_LEVEL_INFO);
+    return;
+  }
+  if (!host.services.vault.isFileSizeTooLarge(file.stat.size) && !host.services.vault.isFileSizeTooLarge(doc.size)) {
+    await syncFileBetweenDBandStorage(host, log, file, doc);
+  } else {
+    log(
+      `SYNC DATABASE AND STORAGE: ${getPathFromEntry(host, doc)} has been skipped due to file size exceeding the limit`,
+      logLevel
+    );
+  }
+}
+const FullScanModes = {
+  // SAFE: "safe",
+  DB_APPLY: "db-apply",
+  NEWER_WINS: "newer-wins"
+  // STORAGE_ONLY: "local-only",
+};
+const ExtraOnRemote = {
+  /**
+   * Delete database entries if they are missing on storage.
+   */
+  DELETE_LOCAL_MISSING: "delete-local-missing"
+  /**
+   * Apply changes from database to storage.
+   */
+  // APPEND_DB_ONLY: "append-db-only",
+};
+const ExtraOnLocal = {
+  /**
+   * Delete local files if they were deleted on database.
+   */
+  DELETE_DB_DELETED: "delete-db-deleted",
+  /**
+   * Delete local files if they are missing on database or were deleted on database.
+   */
+  DELETE_DB_MISSING: "delete-db-missing",
+  /**
+   * Merge local files to database
+   */
+  APPEND_STORAGE_ONLY: "append-storage-only"
+};
+function isDeletedEntry(entry) {
+  return entry.deleted || entry._deleted || false;
+}
+function getFilePairState(pair) {
+  const { file, doc } = pair;
+  if (file && doc) {
+    return isDeletedEntry(doc) ? "both-db-deleted" : "both";
+  }
+  if (file) {
+    return "storage-only";
+  }
+  if (doc) {
+    return isDeletedEntry(doc) ? "db-only-deleted" : "db-only";
+  }
+  throw new Error("Corrupted file pair");
+}
+function shouldDeleteLocalWhenRemoteMissing(options) {
+  return options.extraOnRemote === ExtraOnRemote.DELETE_LOCAL_MISSING || options.extraOnLocal === ExtraOnLocal.DELETE_DB_MISSING;
+}
+function shouldDeleteLocalWhenRemoteDeleted(options) {
+  return options.extraOnRemote === ExtraOnRemote.DELETE_LOCAL_MISSING || options.extraOnLocal === ExtraOnLocal.DELETE_DB_DELETED || options.extraOnLocal === ExtraOnLocal.DELETE_DB_MISSING;
+}
+function resolveFilePairAction(state, options) {
+  switch (options.mode) {
+    case FullScanModes.DB_APPLY:
+      switch (state) {
+        case "both":
+        case "db-only":
+          return "update-storage";
+        case "storage-only":
+          return shouldDeleteLocalWhenRemoteMissing(options) ? "delete-local" : "skip";
+        case "both-db-deleted":
+          return shouldDeleteLocalWhenRemoteDeleted(options) ? "delete-local" : "skip";
+        case "db-only-deleted":
+          return "skip";
+      }
+      break;
+    case FullScanModes.NEWER_WINS:
+      switch (state) {
+        case "both":
+          return "sync-newer";
+        case "storage-only":
+          return shouldDeleteLocalWhenRemoteMissing(options) ? "delete-local" : "update-db";
+        case "db-only":
+          return "update-storage";
+        case "both-db-deleted":
+          if (shouldDeleteLocalWhenRemoteDeleted(options)) {
+            return "delete-local";
+          }
+          return options.extraOnLocal === ExtraOnLocal.APPEND_STORAGE_ONLY ? "update-db" : "skip";
+        case "db-only-deleted":
+          return "skip";
+      }
+      break;
+  }
+  return "skip";
+}
+async function processFilePair(host, log, pair, options) {
+  const { file, doc } = pair;
+  const canonicalPath = doc ? getPathFromEntry(host, doc) : file?.path;
+  if (!canonicalPath) {
+    throw new Error("Corrupted file pair");
+  }
+  const path = canonicalPath;
+  const fileMapKey = convertCase(host.services.setting.currentSettings(), canonicalPath);
+  if (file) {
+    updateFileMTimeInMap(host, fileMapKey, file.stat.mtime);
+  }
+  if (doc && (doc._conflicts?.length ?? 0) > 0) {
+    log(`SKIP ${options.mode}: ${path} has conflicts`, LOG_LEVEL_INFO);
+    return true;
+  }
+  const state = getFilePairState(pair);
+  let action = resolveFilePairAction(state, options);
+  if (options.mode === FullScanModes.NEWER_WINS && state === "db-only" && doc) {
+    const lastSeenMTime = getFileMTimeFromMap(fileMapKey);
+    if (lastSeenMTime !== void 0) {
+      const recency = compareMTime(lastSeenMTime, doc.mtime);
+      if (recency === BASE_IS_NEW || recency === EVEN) {
+        action = "delete-db";
+        log(`NEWER_WINS: Treating missing local file as deletion (${path})`, LOG_LEVEL_VERBOSE);
+      }
+    }
+  }
+  try {
+    switch (action) {
+      case "update-db":
+        if (!file) {
+          throw new Error(`Missing storage file for ${path}`);
+        }
+        await updateToDatabase(host, log, LOG_LEVEL_INFO, file);
+        return true;
+      case "update-storage":
+        if (!doc) {
+          throw new Error(`Missing database entry for ${path}`);
+        }
+        await updateToStorage(host, log, LOG_LEVEL_INFO, doc);
+        updateFileMTimeInMap(host, fileMapKey, doc.mtime);
+        return true;
+      case "sync-newer":
+        if (!file || !doc) {
+          throw new Error(`Cannot compare freshness for ${path}`);
+        }
+        await syncStorageAndDatabase(host, log, file, LOG_LEVEL_INFO, doc);
+        updateFileMTimeInMap(host, fileMapKey, Math.max(file.stat.mtime, doc.mtime));
+        return true;
+      case "delete-local":
+        if (!file) {
+          log(`DELETE LOCAL: ${path} is already absent from storage`, LOG_LEVEL_VERBOSE);
+          return true;
+        }
+        log(`DELETE LOCAL: ${file.path}`, LOG_LEVEL_INFO);
+        await host.serviceModules.storageAccess.delete(file.path, true);
+        fileMaps.delete(fileMapKey);
+        saveFileStatus(host);
+        return true;
+      case "delete-db": {
+        if (!doc) {
+          throw new Error(`Missing database entry for ${path}`);
+        }
+        log(`DELETE DATABASE: ${path}`, LOG_LEVEL_INFO);
+        const dbDeleted = await host.serviceModules.fileHandler.deleteFileFromDB(stripAllPrefixes(path));
+        if (dbDeleted) {
+          fileMaps.delete(fileMapKey);
+          saveFileStatus(host);
+        } else {
+          log(
+            `DELETE DATABASE did not delete ${path}; keeping last-seen record to avoid resurrecting the file`,
+            LOG_LEVEL_NOTICE
+          );
+        }
+        return true;
+      }
+      case "skip":
+        log(`SKIP ${options.mode}: ${path} (${state})`, LOG_LEVEL_VERBOSE);
+        return true;
+    }
+  } catch (ex) {
+    log(`Error processing ${path} with action ${action}`, LOG_LEVEL_NOTICE);
+    log(ex, LOG_LEVEL_VERBOSE);
+    return false;
+  }
+}
+async function synchroniseAllFilesBetweenDBandStorage(host, log, errorManager, options) {
+  const settings = host.services.setting.currentSettings();
+  const showingNotice = options.showingNotice ?? false;
+  await loadFileStatus(host);
+  const { storageFileNameMap, storageFileNameCI2CS } = await collectFilesOnStorage(host, settings, log);
+  const { databaseFileNameMap, databaseFileNameCI2CS } = await collectDatabaseFiles(
+    host,
+    settings,
+    log,
+    showingNotice
+  );
+  const pairs = [];
+  for (const fileNameLC of unique([
+    ...Object.keys(storageFileNameCI2CS),
+    ...Object.keys(databaseFileNameCI2CS)
+  ])) {
+    const fileName = fileNameLC in storageFileNameCI2CS ? storageFileNameCI2CS[fileNameLC] : void 0;
+    const file = fileName ? storageFileNameMap[fileName] : void 0;
+    const databaseName = fileNameLC in databaseFileNameCI2CS ? databaseFileNameCI2CS[fileNameLC] : void 0;
+    const doc = databaseName ? databaseFileNameMap[databaseName] : void 0;
+    const pair = { file, doc };
+    pairs.push(pair);
+  }
+  log(`Total files to synchronise: ${pairs.length}`, LOG_LEVEL_VERBOSE, "syncAll");
+  let successCount = 0;
+  let processedCount = 0;
+  for await (const result of withConcurrency(
+    pairs,
+    async (e) => {
+      try {
+        return await processFilePair(host, log, e, options);
+      } catch (ex) {
+        log(`Error while synchronising files`, LOG_LEVEL_NOTICE);
+        log(ex, LOG_LEVEL_VERBOSE);
+        return false;
+      }
+    },
+    10
+  )) {
+    processedCount++;
+    if (result) {
+      successCount++;
+    }
+    if (processedCount % 25 === 0) {
+      log(
+        `Processing: ${processedCount}/${pairs.length}`,
+        showingNotice ? LOG_LEVEL_NOTICE : LOG_LEVEL_INFO,
+        "syncAll"
+      );
+    }
+  }
+  log(
+    `Synchronisation completed: ${successCount}/${processedCount} files processed successfully`,
+    showingNotice ? LOG_LEVEL_NOTICE : LOG_LEVEL_INFO,
+    "syncAll"
+  );
+  saveFileStatus(host, true);
+  return successCount === processedCount;
+}
+function normaliseFullScanOptions(showingNoticeOrOptions, ignoreSuspending = false) {
+  if (typeof showingNoticeOrOptions === "object") {
+    return {
+      mode: FullScanModes.NEWER_WINS,
+      ...showingNoticeOrOptions
+    };
+  }
+  return {
+    mode: FullScanModes.NEWER_WINS,
+    showingNotice: showingNoticeOrOptions ?? false,
+    ignoreSuspending
+  };
+}
+let fileMaps = /* @__PURE__ */ new Map();
+async function loadFileStatus(host) {
+  const kvDB = host.services.keyValueDB.kvDB;
+  if (!kvDB?.get) {
+    fileMaps = /* @__PURE__ */ new Map();
+    return;
+  }
+  const mapItems = await kvDB.get("fileStatusMap") || {};
+  fileMaps = new Map(Object.entries(mapItems));
+}
+async function _saveFileStatus(host) {
+  const kvDB = host.services.keyValueDB.kvDB;
+  if (!kvDB?.set) {
+    return;
+  }
+  await kvDB.set("fileStatusMap", Object.fromEntries(fileMaps));
+}
+let saveFileStatusTimeout = null;
+function saveFileStatus(host, immediate = false) {
+  if (immediate) {
+    if (saveFileStatusTimeout !== null) compatGlobal.clearTimeout(saveFileStatusTimeout);
+    saveFileStatusTimeout = compatGlobal.setTimeout(() => {
+      saveFileStatusTimeout = null;
+      void _saveFileStatus(host);
+    }, 0);
+    return;
+  }
+  if (saveFileStatusTimeout === null) {
+    saveFileStatusTimeout = compatGlobal.setTimeout(() => {
+      saveFileStatusTimeout = null;
+      void _saveFileStatus(host);
+    }, 1e3);
+  }
+}
+function updateFileMTimeInMap(host, key, mtime) {
+  fileMaps.set(key, mtime);
+  saveFileStatus(host);
+}
+function getFileMTimeFromMap(key) {
+  return fileMaps.get(key);
+}
+async function performFullScan(host, log, errorManager, showingNoticeOrOptions = false, ignoreSuspending = false) {
+  const options = normaliseFullScanOptions(showingNoticeOrOptions, ignoreSuspending);
+  const showingNotice = options.showingNotice ?? false;
+  const shouldIgnoreSuspending = options.ignoreSuspending ?? false;
+  if (!canProceedScan(host, errorManager, log, showingNotice, shouldIgnoreSuspending)) {
+    return false;
+  }
+  log("Opening the key-value database", LOG_LEVEL_VERBOSE);
+  const isInitialized = await host.services.keyValueDB.kvDB.get("initialized") || false;
+  if (showingNotice) {
+    log("Initializing", LOG_LEVEL_NOTICE, "syncAll");
+  }
+  if (isInitialized) {
+    log("Restoring storage state", LOG_LEVEL_VERBOSE);
+    await host.serviceModules.storageAccess.restoreState();
+  }
+  log("Initialize and checking database files");
+  log("Checking deleted files");
+  await collectDeletedFiles(host, log);
+  await synchroniseAllFilesBetweenDBandStorage(host, log, errorManager, options);
+  log("Initialized, NOW TRACKING!");
+  if (!isInitialized) {
+    await host.services.keyValueDB.kvDB.set("initialized", true);
+  }
+  if (showingNotice) {
+    log("Initialize done!", LOG_LEVEL_NOTICE, "syncAll");
+  }
+  return true;
+}
+function useOfflineScanner(host) {
+  const log = createInstanceLogFunction("SF:OfflineScanner", host.services.API);
+  const errorManager = new UnresolvedErrorManager(host.services.appLifecycle, host.services.context.events);
+  const handleScanVault = async (showingNotice, ignoreSuspending = false) => {
+    return await performFullScan(host, log, errorManager, showingNotice, ignoreSuspending);
+  };
+  host.services.vault.scanVault.addHandler(handleScanVault);
+}
+export {
+  ExtraOnLocal,
+  ExtraOnRemote,
+  FullScanModes,
+  canProceedScan,
+  collectDatabaseFiles,
+  collectDeletedFiles,
+  collectFilesOnStorage,
+  convertCase,
+  getFilePairState,
+  getPathFromEntry,
+  normaliseFullScanOptions,
+  performFullScan,
+  resolveFilePairAction,
+  syncFileBetweenDBandStorage,
+  syncStorageAndDatabase,
+  synchroniseAllFilesBetweenDBandStorage,
+  updateToDatabase,
+  updateToStorage,
+  useOfflineScanner
+};

package/dist/serviceFeatures/prepareDatabaseForUse.d.ts

@@ -0,0 +1,20 @@
+import type { NecessaryServices } from "../interfaces/ServiceModule.js";
+import { UnresolvedErrorManager } from "../services/base/UnresolvedErrorManager.js";
+import { type LogFunction } from "../services/lib/logUtils.js";
+/**
+ * Initialise the database and trigger a full vault scan.
+ * @param host Services container
+ * @param log Logging function
+ * @param errorManager Error manager
+ * @param showingNotice Whether to show notices during initialisation
+ * @param reopenDatabase Whether to reopen the database connection
+ * @param ignoreSuspending Whether to ignore suspension settings
+ * @returns True if initialisation succeeded
+ */
+export declare function prepareDatabaseForUse(host: NecessaryServices<"appLifecycle" | "setting" | "vault" | "path" | "database" | "databaseEvents" | "fileProcessing" | "replicator", never>, log: LogFunction, errorManager: UnresolvedErrorManager, showingNotice?: boolean, reopenDatabase?: boolean, ignoreSuspending?: boolean): Promise<boolean>;
+/**
+ * Associate the initialiser file feature with the app lifecycle events.
+ * This function binds initialization handlers to the appropriate lifecycle events.
+ * @param host Services container with required dependencies
+ */
+export declare function usePrepareDatabaseForUse(host: NecessaryServices<"API" | "appLifecycle" | "setting" | "vault" | "path" | "database" | "databaseEvents" | "fileProcessing" | "replicator", never>): void;

package/dist/serviceFeatures/prepareDatabaseForUse.js

@@ -0,0 +1,39 @@
+import { LOG_LEVEL_NOTICE } from "octagonal-wheels/common/logger";
+import { UnresolvedErrorManager } from "../services/base/UnresolvedErrorManager.js";
+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({
+    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;
+  }
+}
+function usePrepareDatabaseForUse(host) {
+  const log = createInstanceLogFunction("SF:prepareDatabaseForUse", host.services.API);
+  const errorManager = new UnresolvedErrorManager(host.services.appLifecycle, host.services.context.events);
+  const initialiseDatabaseHandler = async (showingNotice = false, reopenDatabase = true, ignoreSuspending = false) => {
+    return await prepareDatabaseForUse(host, log, errorManager, showingNotice, reopenDatabase, ignoreSuspending);
+  };
+  host.services.databaseEvents.initialiseDatabase.addHandler(initialiseDatabaseHandler);
+}
+export {
+  prepareDatabaseForUse,
+  usePrepareDatabaseForUse
+};

package/dist/serviceFeatures/remoteConfig.d.ts

@@ -0,0 +1,46 @@
+import { type LOG_LEVEL } from "../common/logger.js";
+import type { ObsidianLiveSyncSettings } from "../common/models/setting.type.js";
+import type { NecessaryServices } from "../interfaces/ServiceModule.js";
+export type RemoteConfigHost = NecessaryServices<"setting" | "UI" | "replication" | "control" | "appLifecycle" | "API", never>;
+export declare function migrateLegacyRemoteConfigurationsInPlace(settings: ObsidianLiveSyncSettings, log?: (message: string, level?: LOG_LEVEL) => void): boolean;
+/**
+ * Generate a unique ID for a new remote configuration.
+ * @returns A unique string identifier.
+ */
+export declare function createRemoteConfigurationId(): string;
+/**
+ * Keep compatibility for users who were already using P2P as their main active remote.
+ */
+export declare function migrateP2PActiveRemoteConfigurationIdInPlace(settings: ObsidianLiveSyncSettings): boolean;
+/**
+ * SF:RemoteConfig - Service Feature for Remote Configuration Management
+ */
+/**
+ * Migrates existing flat settings to the new multiple remote configurations list.
+ */
+export declare function migrateToMultipleRemoteConfigurations(host: RemoteConfigHost): Promise<boolean>;
+/**
+ * Logic to switch the active configuration.
+ */
+export declare function activateRemoteConfiguration(settings: ObsidianLiveSyncSettings, id: string): ObsidianLiveSyncSettings | false;
+/**
+ * Apply a dedicated P2P remote configuration onto runtime P2P-related fields,
+ * while keeping the current `remoteType` unchanged.
+ */
+export declare function activateP2PRemoteConfiguration(settings: ObsidianLiveSyncSettings, id: string): ObsidianLiveSyncSettings | false;
+/**
+ * Command: Switch Active Remote
+ */
+export declare function commandSwitchActiveRemote(host: RemoteConfigHost): Promise<void>;
+/**
+ * Command: Replicate with specific remote
+ */
+export declare function commandReplicateWithSpecificRemote(host: RemoteConfigHost): Promise<void>;
+/**
+ * Migration feature to be used during initialisation.
+ */
+export declare function useRemoteConfigurationMigration(host: RemoteConfigHost): void;
+/**
+ * Hook to set up remote configuration features (Commands).
+ */
+export declare function useRemoteConfiguration(host: RemoteConfigHost): boolean;