@vrtmrz/livesync-commonlib 0.2.1 → 0.2.3

package/dist/replication/trystero/TrysteroReplicator.js

@@ -1,3 +1,4 @@
+import { parsePeerPatterns } from "./peerPatterns.js";
 import {
   TweakValuesShouldMatchedTemplate,
   omitP2PRuntimeSettings
@@ -171,12 +172,10 @@ class TrysteroReplicator {
     }
   }
   get autoSyncPeers() {
-    const peers = this.currentSettings.P2P_AutoSyncPeers.split(",").map((e) => e.trim()).filter((e) => e.length > 0).map((e) => e.startsWith("~") ? new RegExp(e.substring(1), "i") : new RegExp(`^${e}$`, "i"));
-    return peers;
+    return parsePeerPatterns(this.currentSettings.P2P_AutoSyncPeers);
   }
   get autoWatchPeers() {
-    const peers = this.currentSettings.P2P_AutoWatchPeers.split(",").map((e) => e.trim()).filter((e) => e.length > 0).map((e) => e.startsWith("~") ? new RegExp(e.substring(1), "i") : new RegExp(`^${e}$`, "i"));
-    return peers;
+    return parsePeerPatterns(this.currentSettings.P2P_AutoWatchPeers);
   }
   async onNewPeer(peer) {
     const peerName = peer.name;

package/dist/replication/trystero/TrysteroReplicatorP2PServer.js

@@ -1,3 +1,4 @@
+import { parsePeerPatterns } from "./peerPatterns.js";
 import { selfId, joinRoom } from "@trystero-p2p/nostr";
 import { AutoAccepting, LOG_LEVEL_INFO, LOG_LEVEL_NOTICE } from "../../common/types.js";
 import { LOG_LEVEL_VERBOSE, Logger } from "../../common/logger.js";
@@ -281,12 +282,12 @@ You can chose as follows:
   }
   _acceptablePeers = new Computed({
     evaluation: (settings) => {
-      return `${settings?.P2P_AutoAcceptingPeers ?? ""}`.split(",").map((e) => e.trim()).filter((e) => !!e).map((e) => e.startsWith("~") ? new RegExp(e.substring(1), "i") : new RegExp(`^${e}$`, "i"));
+      return parsePeerPatterns(`${settings?.P2P_AutoAcceptingPeers ?? ""}`);
     }
   });
   _shouldDenyPeers = new Computed({
     evaluation: (settings) => {
-      return `${settings?.P2P_AutoDenyingPeers ?? ""}`.split(",").map((e) => e.trim()).filter((e) => !!e).map((e) => e.startsWith("~") ? new RegExp(e.substring(1), "i") : new RegExp(`^${e}$`, "i"));
+      return parsePeerPatterns(`${settings?.P2P_AutoDenyingPeers ?? ""}`);
     }
   });
   /**

package/dist/replication/trystero/peerPatterns.d.ts

@@ -0,0 +1 @@
+export declare function parsePeerPatterns(value: string): RegExp[];

package/dist/replication/trystero/peerPatterns.js

@@ -0,0 +1,6 @@
+function parsePeerPatterns(value) {
+  return value.split(",").map((entry) => entry.trim()).filter((entry) => entry.length > 0).map((entry) => entry.startsWith("~") ? new RegExp(entry.substring(1), "i") : new RegExp(`^${entry}$`, "i"));
+}
+export {
+  parsePeerPatterns
+};

package/dist/rpc/RpcRoom.d.ts

@@ -8,7 +8,7 @@ export declare class RpcRoom {
     private sessions;
     private outgoingChunkMap;
     private incomingChunkMap;
-    private incomingChunkTimers;
+    private incomingChunkWaits;
     private peerVersion;
     private disposers;
     private closed;
@@ -32,7 +32,11 @@ export declare class RpcRoom {
     private notifyRemoteCancellation;
     private abortInboundCall;
     private sendEnvelope;
+    private sendChunk;
+    private sendErrorResponse;
     private scheduleMissingAck;
     private onWireMessage;
     private onEnvelopePayload;
+    private onRequest;
+    private runMethod;
 }

package/dist/rpc/RpcRoom.js

@@ -1,4 +1,7 @@
 import { compatGlobal } from "../common/coreEnvFunctions.js";
+import {
+  createDeferredAction
+} from "octagonal-wheels/concurrency/deferredAction";
 import { IncomingChunkBuffer, estimateBytes, splitIntoChunks } from "./chunking.js";
 import { asRpcErrorShape, RpcError } from "./errors.js";
 import { RpcSession } from "./RpcSession.js";
@@ -12,6 +15,10 @@ function newId(prefix) {
 function validNamespacedMethod(method) {
   return method.includes(".") || method.includes("/");
 }
+const scheduleRpcTimeout = (callback, delayMs) => {
+  const handle = compatGlobal.setTimeout(callback, delayMs);
+  return () => compatGlobal.clearTimeout(handle);
+};
 class RpcRoom {
   options;
   pending = /* @__PURE__ */ new Map();
@@ -21,7 +28,7 @@ class RpcRoom {
   sessions = /* @__PURE__ */ new Map();
   outgoingChunkMap = /* @__PURE__ */ new Map();
   incomingChunkMap = /* @__PURE__ */ new Map();
-  incomingChunkTimers = /* @__PURE__ */ new Map();
+  incomingChunkWaits = /* @__PURE__ */ new Map();
   peerVersion = /* @__PURE__ */ new Map();
   disposers = [];
   closed = false;
@@ -83,8 +90,8 @@ class RpcRoom {
     this.sessions.clear();
     this.outgoingChunkMap.clear();
     this.incomingChunkMap.clear();
-    this.incomingChunkTimers.forEach((h) => compatGlobal.clearTimeout(h));
-    this.incomingChunkTimers.clear();
+    this.incomingChunkWaits.forEach((wait) => wait.dispose());
+    this.incomingChunkWaits.clear();
   }
   session(peerId) {
     const existing = this.sessions.get(peerId);
@@ -125,30 +132,32 @@ class RpcRoom {
     const requestId = newId("req");
     let pending;
     const p = new Promise((resolve, reject) => {
+      const signal = options.signal;
+      const onAbort = () => {
+        const current = this.pending.get(requestId);
+        if (!current) return;
+        this.rejectPending(requestId, new RpcError("CANCELLED", `RPC cancelled: ${method}`), true);
+      };
+      const deadline = timeoutMs > 0 ? createDeferredAction(() => {
+        this.rejectPending(requestId, new RpcError("TIMEOUT", `RPC timed out: ${method}`), true);
+      }, scheduleRpcTimeout) : void 0;
       pending = {
         peerId,
         method,
         resolve,
         reject,
-        signal: options.signal,
+        releaseWait: () => {
+          deadline?.dispose();
+          signal?.removeEventListener("abort", onAbort);
+        },
         requestSent: false,
         cancelRequested: false
       };
-      if (timeoutMs > 0) {
-        pending.timeoutHandle = compatGlobal.setTimeout(() => {
-          this.rejectPending(requestId, new RpcError("TIMEOUT", `RPC timed out: ${method}`), true);
-        }, timeoutMs);
-      }
+      deadline?.schedule(timeoutMs);
       this.pending.set(requestId, pending);
-      if (options.signal) {
-        const onAbort = () => {
-          const current = this.pending.get(requestId);
-          if (!current) return;
-          this.rejectPending(requestId, new RpcError("CANCELLED", `RPC cancelled: ${method}`), true);
-        };
-        pending.abortListener = onAbort;
-        options.signal.addEventListener("abort", onAbort, { once: true });
-        if (options.signal.aborted) onAbort();
+      if (signal) {
+        signal.addEventListener("abort", onAbort, { once: true });
+        if (signal.aborted) onAbort();
       }
     });
     const sendTask = this.sendEnvelope(peerId, {
@@ -191,12 +200,7 @@ class RpcRoom {
     const pending = this.pending.get(requestId);
     if (!pending) return void 0;
     this.pending.delete(requestId);
-    if (pending.timeoutHandle !== void 0) {
-      compatGlobal.clearTimeout(pending.timeoutHandle);
-    }
-    if (pending.signal && pending.abortListener) {
-      pending.signal.removeEventListener("abort", pending.abortListener);
-    }
+    pending.releaseWait();
     return pending;
   }
   rejectPending(requestId, error, notifyRemote = false) {
@@ -229,28 +233,25 @@ class RpcRoom {
     const chunks = splitIntoChunks(serialized, this.options.maxWirePayloadBytes);
     this.outgoingChunkMap.set(streamId, { peerId, chunks });
     for (let i = 0; i < chunks.length; i++) {
-      await this.options.transport.send(
-        {
-          wire: "chunk",
-          streamId,
-          index: i,
-          total: chunks.length,
-          payload: chunks[i]
-        },
-        peerId
-      );
+      await this.sendChunk(peerId, streamId, chunks.length, i, chunks[i]);
     }
   }
+  sendChunk(peerId, streamId, total, index, payload) {
+    return this.options.transport.send({ wire: "chunk", streamId, index, total, payload }, peerId);
+  }
+  sendErrorResponse(peerId, requestId, error) {
+    return this.sendEnvelope(peerId, { kind: "response", requestId, ok: false, error });
+  }
   scheduleMissingAck(streamId, peerId) {
-    const existing = this.incomingChunkTimers.get(streamId);
-    if (existing) compatGlobal.clearTimeout(existing);
-    const handle = compatGlobal.setTimeout(() => {
+    this.incomingChunkWaits.get(streamId)?.dispose();
+    const wait = createDeferredAction(() => {
       const state = this.incomingChunkMap.get(streamId);
       if (!state || state.isComplete()) return;
       const missing = state.missingIndices();
       void this.options.transport.send({ wire: "chunk-ack", streamId, missing }, peerId);
-    }, this.options.chunkMissingRetryMs);
-    this.incomingChunkTimers.set(streamId, handle);
+    }, scheduleRpcTimeout);
+    wait.schedule(this.options.chunkMissingRetryMs);
+    this.incomingChunkWaits.set(streamId, wait);
   }
   async onWireMessage(message, peerId) {
     if (message.wire === "raw") {
@@ -266,9 +267,8 @@ class RpcRoom {
       state2.add(message.index, message.payload);
       this.scheduleMissingAck(message.streamId, peerId);
       if (state2.isComplete()) {
-        const timer = this.incomingChunkTimers.get(message.streamId);
-        if (timer) compatGlobal.clearTimeout(timer);
-        this.incomingChunkTimers.delete(message.streamId);
+        this.incomingChunkWaits.get(message.streamId)?.dispose();
+        this.incomingChunkWaits.delete(message.streamId);
         this.incomingChunkMap.delete(message.streamId);
         await this.options.transport.send(
           { wire: "chunk-ack", streamId: message.streamId, missing: [] },
@@ -287,16 +287,7 @@ class RpcRoom {
     for (const index of message.missing) {
       const payload = state.chunks[index];
       if (payload === void 0) continue;
-      await this.options.transport.send(
-        {
-          wire: "chunk",
-          streamId: message.streamId,
-          index,
-          total: state.chunks.length,
-          payload
-        },
-        state.peerId
-      );
+      await this.sendChunk(state.peerId, message.streamId, state.chunks.length, index, payload);
     }
   }
   async onEnvelopePayload(payload, peerId) {
@@ -319,8 +310,8 @@ class RpcRoom {
       return;
     }
     if (envelope.kind === "cancel") {
-      const ctx2 = this.inboundCalls.get(envelope.requestId);
-      if (ctx2 && ctx2.peerId === peerId) this.abortInboundCall(envelope.requestId, ctx2);
+      const ctx = this.inboundCalls.get(envelope.requestId);
+      if (ctx && ctx.peerId === peerId) this.abortInboundCall(envelope.requestId, ctx);
       return;
     }
     if (envelope.kind === "response") {
@@ -335,6 +326,9 @@ class RpcRoom {
       }
       return;
     }
+    return this.onRequest(envelope, peerId);
+  }
+  async onRequest(envelope, peerId) {
     const controller = new AbortController();
     const ctx = { controller, signal: controller.signal, peerId };
     this.inboundCalls.set(envelope.requestId, ctx);
@@ -344,12 +338,7 @@ class RpcRoom {
     } catch (ex) {
       this.inboundCalls.delete(envelope.requestId);
       if (!ctx.signal.aborted && !this.closed) {
-        await this.sendEnvelope(peerId, {
-          kind: "response",
-          requestId: envelope.requestId,
-          ok: false,
-          error: asRpcErrorShape(ex)
-        });
+        await this.sendErrorResponse(peerId, envelope.requestId, asRpcErrorShape(ex));
       }
       return;
     }
@@ -364,14 +353,9 @@ class RpcRoom {
     const version = this.peerVersion.get(peerId);
     if (version && version.major !== RPC_VERSION_MAJOR) {
       if (!ctx.signal.aborted && !this.closed) {
-        await this.sendEnvelope(peerId, {
-          kind: "response",
-          requestId: envelope.requestId,
-          ok: false,
-          error: {
-            code: "REMOTE_ERROR",
-            message: `RPC major mismatch: local=${RPC_VERSION_MAJOR}, remote=${version.major}`
-          }
+        await this.sendErrorResponse(peerId, envelope.requestId, {
+          code: "REMOTE_ERROR",
+          message: `RPC major mismatch: local=${RPC_VERSION_MAJOR}, remote=${version.major}`
         });
       }
       this.inboundCalls.delete(envelope.requestId);
@@ -386,48 +370,15 @@ class RpcRoom {
     const method = this.methods.get(envelope.method);
     if (!method) {
       if (!ctx.signal.aborted && !this.closed) {
-        await this.sendEnvelope(peerId, {
-          kind: "response",
-          requestId: envelope.requestId,
-          ok: false,
-          error: {
-            code: "REMOTE_ERROR",
-            message: `Method not found: ${envelope.method}`
-          }
+        await this.sendErrorResponse(peerId, envelope.requestId, {
+          code: "REMOTE_ERROR",
+          message: `Method not found: ${envelope.method}`
         });
       }
       this.inboundCalls.delete(envelope.requestId);
       return;
     }
-    const runner = async () => {
-      try {
-        if (ctx.signal.aborted || this.closed) return;
-        const data = method.cancellationAware ? await method.handler(
-          ctx,
-          peerId,
-          ...envelope.args
-        ) : await method.handler(peerId, ...envelope.args);
-        if (ctx.signal.aborted || this.closed) return;
-        await this.sendEnvelope(peerId, {
-          kind: "response",
-          requestId: envelope.requestId,
-          ok: true,
-          data
-        });
-      } catch (ex) {
-        if (ctx.signal.aborted || this.closed) return;
-        await this.sendEnvelope(peerId, {
-          kind: "response",
-          requestId: envelope.requestId,
-          ok: false,
-          error: asRpcErrorShape(ex)
-        });
-      } finally {
-        if (this.inboundCalls.get(envelope.requestId) === ctx) {
-          this.inboundCalls.delete(envelope.requestId);
-        }
-      }
-    };
+    const runner = () => this.runMethod(method, envelope, peerId, ctx);
     if (method.serial) {
       method.queue = method.queue.then(runner, runner);
       await method.queue;
@@ -435,6 +386,30 @@ class RpcRoom {
       await runner();
     }
   }
+  async runMethod(method, envelope, peerId, ctx) {
+    try {
+      if (ctx.signal.aborted || this.closed) return;
+      const data = method.cancellationAware ? await method.handler(
+        ctx,
+        peerId,
+        ...envelope.args
+      ) : await method.handler(peerId, ...envelope.args);
+      if (ctx.signal.aborted || this.closed) return;
+      await this.sendEnvelope(peerId, {
+        kind: "response",
+        requestId: envelope.requestId,
+        ok: true,
+        data
+      });
+    } catch (ex) {
+      if (ctx.signal.aborted || this.closed) return;
+      await this.sendErrorResponse(peerId, envelope.requestId, asRpcErrorShape(ex));
+    } finally {
+      if (this.inboundCalls.get(envelope.requestId) === ctx) {
+        this.inboundCalls.delete(envelope.requestId);
+      }
+    }
+  }
 }
 export {
   RpcRoom

package/dist/serviceFeatures/offlineScanner.d.ts

@@ -3,7 +3,7 @@ import { type LogFunction } from "../services/lib/logUtils.js";
 import type { NecessaryServices } from "../interfaces/ServiceModule.js";
 import type { IPathService } from "../services/base/IService.js";
 import { UnresolvedErrorManager } from "../services/base/UnresolvedErrorManager.js";
-import { VaultScanResults, type VaultScanResult } from "../services/base/VaultScanResult.js";
+import { VaultScanResults, type VaultScanResult, type VaultScanOptions } from "../services/base/VaultScanResult.js";
 export { VaultScanResults };
 export type { VaultScanResult };
 /**
@@ -156,7 +156,7 @@ export declare function getPathFromEntry(host: {
  * @param file Storage file information
  * @param doc Database entry
  */
-export declare function syncFileBetweenDBandStorage(host: NecessaryServices<"setting" | "vault" | "path", "storageAccess" | "fileHandler">, log: LogFunction, file: UXFileInfoStub, doc: MetaEntry): Promise<FilePairProcessResult>;
+export declare function syncFileBetweenDBandStorage(host: NecessaryServices<"setting" | "vault" | "path", "storageAccess" | "fileHandler">, log: LogFunction, file: UXFileInfoStub, doc: MetaEntry, scanOptions?: VaultScanOptions): Promise<FilePairProcessResult>;
 export declare function canProceedScan(host: NecessaryServices<"keyValueDB" | "setting", never>, errorManager: UnresolvedErrorManager, log: LogFunction, showingNotice?: boolean, ignoreSuspending?: boolean): boolean;
 /**
  * Normalise the logical comparison key and lower case it when filename case should be handled insensitively.
@@ -180,7 +180,7 @@ export declare function collectDatabaseFiles(host: NecessaryServices<"database"
 }>;
 export declare function updateToDatabase(host: NecessaryServices<"vault", "fileHandler">, log: LogFunction, logLevel: LOG_LEVEL, file: UXFileInfoStub): Promise<FilePairProcessResult>;
 export declare function updateToStorage(host: NecessaryServices<"vault" | "path", "fileHandler">, log: LogFunction, logLevel: LOG_LEVEL, w: MetaEntry): Promise<FilePairProcessResult>;
-export declare function syncStorageAndDatabase(host: NecessaryServices<"setting" | "vault" | "path", "storageAccess" | "fileHandler">, log: LogFunction, file: UXFileInfoStub, logLevel: LOG_LEVEL, doc: MetaEntry): Promise<FilePairProcessResult>;
+export declare function syncStorageAndDatabase(host: NecessaryServices<"setting" | "vault" | "path", "storageAccess" | "fileHandler">, log: LogFunction, file: UXFileInfoStub, logLevel: LOG_LEVEL, doc: MetaEntry, scanOptions?: VaultScanOptions): Promise<FilePairProcessResult>;
 export declare const FullScanModes: {
     readonly DB_APPLY: "db-apply";
     readonly NEWER_WINS: "newer-wins";
@@ -205,7 +205,7 @@ export declare const ExtraOnLocal: {
      */
     readonly APPEND_STORAGE_ONLY: "append-storage-only";
 };
-export interface FullScanOptions {
+export interface FullScanOptions extends VaultScanOptions {
     mode: FullScanMode;
     extraOnLocal?: (typeof ExtraOnLocal)[keyof typeof ExtraOnLocal];
     extraOnRemote?: (typeof ExtraOnRemote)[keyof typeof ExtraOnRemote];
@@ -245,7 +245,7 @@ export declare function resolveFilePairAction(state: FilePairState, options: Ful
  * @param options Full scan options
  * @returns The scan result for all file pairs
  */
-export declare function synchroniseAllFilesBetweenDBandStorage(host: NecessaryServices<"setting" | "vault" | "path" | "fileProcessing" | "database" | "keyValueDB", "storageAccess" | "fileHandler">, log: LogFunction, errorManager: UnresolvedErrorManager, options: FullScanOptions): Promise<VaultScanResult>;
+export declare function synchroniseAllFilesBetweenDBandStorage(host: NecessaryServices<"setting" | "vault" | "path" | "database" | "keyValueDB", "storageAccess" | "fileHandler">, log: LogFunction, errorManager: UnresolvedErrorManager, options: FullScanOptions): Promise<VaultScanResult>;
 export declare function normaliseFullScanOptions(showingNoticeOrOptions: Partial<FullScanOptions> | boolean | undefined, ignoreSuspending?: boolean): FullScanOptions;
 /**
  * Remove one path from the Offline Scanner's durable last-seen state.
@@ -264,11 +264,11 @@ export declare function clearOfflineScannerLastSeen(host: NecessaryServices<"set
  * @param ignoreSuspending Legacy suspension flag used with the notice flag
  * @returns The scan outcome, including accepted individual file failures
  */
-export declare function performFullScan(host: NecessaryServices<"setting" | "vault" | "path" | "fileProcessing" | "database" | "keyValueDB", "storageAccess" | "fileHandler">, log: LogFunction, errorManager: UnresolvedErrorManager, options?: Partial<FullScanOptions>): Promise<VaultScanResult>;
-export declare function performFullScan(host: NecessaryServices<"setting" | "vault" | "path" | "fileProcessing" | "database" | "keyValueDB", "storageAccess" | "fileHandler">, log: LogFunction, errorManager: UnresolvedErrorManager, showingNotice?: boolean, ignoreSuspending?: boolean): Promise<VaultScanResult>;
+export declare function performFullScan(host: NecessaryServices<"setting" | "vault" | "path" | "database" | "keyValueDB", "storageAccess" | "fileHandler">, log: LogFunction, errorManager: UnresolvedErrorManager, options?: Partial<FullScanOptions>): Promise<VaultScanResult>;
+export declare function performFullScan(host: NecessaryServices<"setting" | "vault" | "path" | "database" | "keyValueDB", "storageAccess" | "fileHandler">, log: LogFunction, errorManager: UnresolvedErrorManager, showingNotice?: boolean, ignoreSuspending?: boolean): Promise<VaultScanResult>;
 /**
  * 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 useOfflineScanner(host: NecessaryServices<"API" | "appLifecycle" | "setting" | "vault" | "path" | "database" | "databaseEvents" | "fileProcessing" | "keyValueDB" | "replicator", "storageAccess" | "fileHandler">): void;
+export declare function useOfflineScanner(host: NecessaryServices<"API" | "appLifecycle" | "setting" | "vault" | "path" | "database" | "keyValueDB", "storageAccess" | "fileHandler">): void;

package/dist/serviceFeatures/offlineScanner.js

@@ -15,7 +15,7 @@ import { BASE_IS_NEW, EVEN, TARGET_IS_NEW } from "../common/models/shared.const.
 import { UnresolvedErrorManager } from "../services/base/UnresolvedErrorManager.js";
 import { compatGlobal } from "../common/coreEnvFunctions.js";
 import { ICHeader, ICXHeader, PSCHeader } from "../common/models/fileaccess.const.js";
-import { serialized } from "octagonal-wheels/concurrency/lock";
+import { serialized, withLocks } from "octagonal-wheels/concurrency/lock";
 import { VaultScanResults } from "../services/base/VaultScanResult.js";
 const FilePairProcessResults = {
   COMPLETED: "completed",
@@ -218,17 +218,10 @@ function createReaddressedMetadata(source, expectedDocumentId) {
 }
 async function serializedByMetadataDocumentIds(documentIds, callback) {
   const lockKeys = [...new Set(documentIds)].sort().map((documentId) => `processFileEvent-${documentId}`);
-  const acquire = async (index) => {
-    const key = lockKeys[index];
-    if (key === void 0) return await callback();
-    return await serialized(key, () => acquire(index + 1));
-  };
-  return await acquire(0);
+  return await withLocks(lockKeys, callback);
 }
 function findRepairEntry(entries, actualDocumentId) {
-  return entries.find(
-    ({ inspection }) => inspection.diagnostic.actualDocumentId === actualDocumentId
-  );
+  return entries.find(({ inspection }) => inspection.diagnostic.actualDocumentId === actualDocumentId);
 }
 async function repairMetadataDocumentIdentity(host, request) {
   const baseResult = {
@@ -350,7 +343,7 @@ function getPathFromEntry(host, doc) {
   const path = host.services.path.getPath(doc);
   return path;
 }
-async function syncFileBetweenDBandStorage(host, log, file, doc) {
+async function syncFileBetweenDBandStorage(host, log, file, doc, scanOptions) {
   const docPath = getPathFromEntry(host, doc);
   if (!doc) {
     throw new Error(`Missing doc:${docPath}`);
@@ -393,6 +386,10 @@ async function syncFileBetweenDBandStorage(host, log, file, doc) {
         log(`STORAGE ? DB : ${file.path} has been skipped due to file size exceeding the limit`, LOG_LEVEL_NOTICE);
         return FilePairProcessResults.SKIPPED;
       }
+      if (scanOptions?.strictContentCheck === false && await host.serviceModules.fileHandler.canSkipUnchangedFile?.(file, doc)) {
+        log(`STORAGE ? DB : ${file.path} skipped using unchanged storage and revision metadata`, LOG_LEVEL_DEBUG);
+        return FilePairProcessResults.SKIPPED;
+      }
       if (doc._rev && await host.serviceModules.fileHandler.tryRecordUntrackedFileRevision(file, doc._rev)) {
         log("STORAGE == DB :" + file.path, LOG_LEVEL_DEBUG);
         return FilePairProcessResults.COMPLETED;
@@ -439,6 +436,9 @@ function convertCase(settings, path) {
   }
   return normalisedPath.toLowerCase();
 }
+function createComparisonPathLookup(settings, paths) {
+  return Object.fromEntries(paths.map((path) => [convertCase(settings, path), path]));
+}
 async function collectFilesOnStorage(host, settings, log) {
   log("Collecting local files on the storage", LOG_LEVEL_VERBOSE);
   const filesStorageSrc = await host.serviceModules.storageAccess.getFiles();
@@ -451,8 +451,7 @@ async function collectFilesOnStorage(host, settings, log) {
   }
   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]]));
+  const storageFileNameCI2CS = createComparisonPathLookup(settings, storageFileNames);
   return { storageFileNameMap, storageFileNames, storageFileNameCI2CS };
 }
 async function collectDatabaseFiles(host, settings, log, showingNotice) {
@@ -496,8 +495,7 @@ async function collectDatabaseFiles(host, settings, log, showingNotice) {
   }
   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]]));
+  const databaseFileNameCI2CS = createComparisonPathLookup(settings, databaseFileNames);
   const quarantinedFileNamesLC = new Set(
     [...unresolvedFileNamesLC].filter((path) => !resolvableFileNamesLC.has(path))
   );
@@ -549,13 +547,13 @@ async function updateToStorage(host, log, logLevel, w) {
     return FilePairProcessResults.FAILED;
   }
 }
-async function syncStorageAndDatabase(host, log, file, logLevel, doc) {
+async function syncStorageAndDatabase(host, log, file, logLevel, doc, scanOptions) {
   if ((doc._conflicts?.length ?? 0) > 0) {
     log(`SYNC DATABASE AND STORAGE: ${file.path} has conflicts. skipped`, LOG_LEVEL_INFO);
     return FilePairProcessResults.SKIPPED;
   }
   if (!host.services.vault.isFileSizeTooLarge(file.stat.size) && !host.services.vault.isFileSizeTooLarge(doc.size)) {
-    return await syncFileBetweenDBandStorage(host, log, file, doc);
+    return await syncFileBetweenDBandStorage(host, log, file, doc, scanOptions);
   } else {
     log(
       `SYNC DATABASE AND STORAGE: ${getPathFromEntry(host, doc)} has been skipped due to file size exceeding the limit`,
@@ -698,7 +696,7 @@ async function processFilePair(host, log, pair, options) {
         if (!file || !doc) {
           throw new Error(`Cannot compare freshness for ${path}`);
         }
-        const syncResult = await syncStorageAndDatabase(host, log, file, LOG_LEVEL_INFO, doc);
+        const syncResult = await syncStorageAndDatabase(host, log, file, LOG_LEVEL_INFO, doc, options);
         if (syncResult === FilePairProcessResults.COMPLETED) {
           updateFileMTimeInMap(host, fileMapKey, Math.max(file.stat.mtime, doc.mtime));
         }
@@ -746,7 +744,12 @@ async function synchroniseAllFilesBetweenDBandStorage(host, log, errorManager, o
   const showingNotice = options.showingNotice ?? false;
   await loadFileStatus(host);
   const { storageFileNameMap, storageFileNameCI2CS } = await collectFilesOnStorage(host, settings, log);
-  const { databaseFileNameMap, databaseFileNameCI2CS, quarantinedFileNamesLC } = await collectDatabaseFiles(host, settings, log, showingNotice);
+  const { databaseFileNameMap, databaseFileNameCI2CS, quarantinedFileNamesLC } = await collectDatabaseFiles(
+    host,
+    settings,
+    log,
+    showingNotice
+  );
   const pairs = [];
   for (const fileNameLC of unique([
     ...Object.keys(storageFileNameCI2CS),
@@ -922,11 +925,12 @@ async function performFullScan(host, log, errorManager, showingNoticeOrOptions =
 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, continueOnFileFailure = false) => {
+  const handleScanVault = async (showingNotice, ignoreSuspending = false, continueOnFileFailure = false, scanOptions) => {
     return await performFullScan(host, log, errorManager, {
       showingNotice,
       ignoreSuspending,
-      continueOnFileFailure
+      continueOnFileFailure,
+      strictContentCheck: scanOptions?.strictContentCheck
     });
   };
   host.services.vault.scanVault.addHandler(handleScanVault);

package/dist/serviceFeatures/prepareDatabaseForUse.d.ts

@@ -1,7 +1,7 @@
 import type { NecessaryServices } from "../interfaces/ServiceModule.js";
 import { UnresolvedErrorManager } from "../services/base/UnresolvedErrorManager.js";
 import { type LogFunction } from "../services/lib/logUtils.js";
-import { type VaultScanResult } from "../services/base/VaultScanResult.js";
+import { type VaultScanResult, type VaultScanOptions } from "../services/base/VaultScanResult.js";
 /**
  * Initialise the database and trigger a full vault scan.
  * @param host Services container
@@ -11,12 +11,13 @@ import { type VaultScanResult } from "../services/base/VaultScanResult.js";
  * @param reopenDatabase Whether to reopen the database connection
  * @param ignoreSuspending Whether to ignore suspension settings
  * @param continueOnFileFailure Whether individual file failures may satisfy application readiness
+ * @param scanOptions Optional content-check policy; omitted options keep strict checks
  * @returns The initialisation outcome, including accepted individual file failures
  */
-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, continueOnFileFailure?: boolean): Promise<VaultScanResult>;
+export declare function prepareDatabaseForUse(host: NecessaryServices<"appLifecycle" | "vault" | "database" | "databaseEvents" | "fileProcessing" | "replicator", never>, log: LogFunction, errorManager: UnresolvedErrorManager, showingNotice?: boolean, reopenDatabase?: boolean, ignoreSuspending?: boolean, continueOnFileFailure?: boolean, scanOptions?: VaultScanOptions): Promise<VaultScanResult>;
 /**
  * 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;
+export declare function usePrepareDatabaseForUse(host: NecessaryServices<"API" | "appLifecycle" | "vault" | "database" | "databaseEvents" | "fileProcessing" | "replicator", never>): void;

package/dist/serviceFeatures/prepareDatabaseForUse.js

@@ -6,7 +6,7 @@ function reportPreparationFailure(log, message) {
   log(message, LOG_LEVEL_VERBOSE);
   return false;
 }
-async function prepareDatabaseForUse(host, log, errorManager, showingNotice = false, reopenDatabase = true, ignoreSuspending = false, continueOnFileFailure = false) {
+async function prepareDatabaseForUse(host, log, errorManager, showingNotice = false, reopenDatabase = true, ignoreSuspending = false, continueOnFileFailure = false, scanOptions) {
   const appLifecycle = host.services.appLifecycle;
   appLifecycle.resetIsReady();
   try {
@@ -25,7 +25,7 @@ async function prepareDatabaseForUse(host, log, errorManager, showingNotice = fa
         "Database preparation stopped because the local database is not ready."
       );
     }
-    const scanResult = await host.services.vault.scanVault(showingNotice, ignoreSuspending, continueOnFileFailure);
+    const scanResult = await host.services.vault.scanVault(showingNotice, ignoreSuspending, continueOnFileFailure, scanOptions);
     if (scanResult === VaultScanResults.FAILED) {
       return reportPreparationFailure(log, "Database preparation stopped because the Vault scan failed.");
     }
@@ -57,7 +57,7 @@ async function prepareDatabaseForUse(host, log, errorManager, showingNotice = fa
 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, continueOnFileFailure = false) => {
+  const initialiseDatabaseHandler = async (showingNotice = false, reopenDatabase = true, ignoreSuspending = false, continueOnFileFailure = false, scanOptions) => {
     return await prepareDatabaseForUse(
       host,
       log,
@@ -65,7 +65,8 @@ function usePrepareDatabaseForUse(host) {
       showingNotice,
       reopenDatabase,
       ignoreSuspending,
-      continueOnFileFailure
+      continueOnFileFailure,
+      scanOptions
     );
   };
   host.services.databaseEvents.initialiseDatabase.addHandler(initialiseDatabaseHandler);