@vrtmrz/livesync-commonlib 0.1.0-rc.0

package/dist/managers/StorageEventManager.js

@@ -0,0 +1,564 @@
+import { shouldBeIgnored } from "../string_and_binary/path.js";
+import {
+  DEFAULT_SETTINGS,
+  LOG_LEVEL_DEBUG,
+  LOG_LEVEL_INFO,
+  LOG_LEVEL_NOTICE,
+  LOG_LEVEL_VERBOSE
+} from "../common/types.js";
+import { delay, fireAndForget, throttle } from "../common/utils.js";
+import {} from "../common/types.js";
+import { serialized, skipIfDuplicated } from "octagonal-wheels/concurrency/lock";
+import { isWaitingForTimeout } from "octagonal-wheels/concurrency/task";
+import { Semaphore } from "octagonal-wheels/concurrency/semaphore";
+import { promiseWithResolvers } from "octagonal-wheels/promises";
+import { StorageEventManager } from "../interfaces/StorageEventManager.js";
+import { createInstanceLogFunction } from "../services/lib/logUtils.js";
+import { compatGlobal } from "../common/coreEnvFunctions.js";
+const TYPE_SENTINEL_FLUSH = "SENTINEL_FLUSH";
+class StorageEventManagerBase extends StorageEventManager {
+  _log;
+  setting;
+  vaultService;
+  fileProcessing;
+  storageAccess;
+  adapter;
+  get shouldBatchSave() {
+    return this.settings?.batchSave && this.settings?.liveSync != true;
+  }
+  get batchSaveMinimumDelay() {
+    return this.settings?.batchSaveMinimumDelay ?? DEFAULT_SETTINGS.batchSaveMinimumDelay;
+  }
+  get batchSaveMaximumDelay() {
+    return this.settings?.batchSaveMaximumDelay ?? DEFAULT_SETTINGS.batchSaveMaximumDelay;
+  }
+  get settings() {
+    return this.setting.currentSettings();
+  }
+  constructor(adapter, dependencies) {
+    super();
+    this.adapter = adapter;
+    this.setting = dependencies.setting;
+    this.vaultService = dependencies.vaultService;
+    this.fileProcessing = dependencies.fileProcessing;
+    this.storageAccess = dependencies.storageAccessManager;
+    this._log = createInstanceLogFunction("StorageEventManager", dependencies.APIService);
+  }
+  // Delegated methods to adapter
+  _saveSnapshot(snapshot) {
+    return this.adapter.persistence.saveSnapshot(snapshot);
+  }
+  _loadSnapshot() {
+    return this.adapter.persistence.loadSnapshot();
+  }
+  // Type guard methods delegated to adapter
+  isFolder(file) {
+    return this.adapter.typeGuard.isFolder(file);
+  }
+  isFile(file) {
+    return this.adapter.typeGuard.isFile(file);
+  }
+  updateStatus() {
+    const allFileEventItems = this.bufferedQueuedItems.filter((e) => "args" in e);
+    const allItems = allFileEventItems.filter((e) => !e.cancelled);
+    const totalItems = allItems.length + this.concurrentProcessing.waiting;
+    const processing = this.processingCount;
+    const batchedCount = this._waitingMap.size;
+    this.adapter.status.updateStatus({
+      batched: batchedCount,
+      processing,
+      totalQueued: totalItems + batchedCount + processing
+    });
+  }
+  /**
+   * 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`.
+   */
+  snapShotRestored = null;
+  /**
+   * Restore the previous snapshot if exists.
+   * @returns
+   */
+  restoreState() {
+    this.snapShotRestored = this._restoreFromSnapshot();
+    return this.snapShotRestored;
+  }
+  async appendQueue(params, ctx) {
+    const settings = this.settings;
+    if (!settings.isConfigured) return;
+    if (settings.suspendFileWatching) return;
+    if (settings.maxMTimeForReflectEvents > 0) {
+      return;
+    }
+    this.fileProcessing.onStorageFileEvent();
+    for (const param of params) {
+      const atomicKey = [0, 0, 0, 0, 0, 0].map((e) => `${Math.floor(Math.random() * 1e5)}`).join("-");
+      let type = param.type;
+      let file = param.file;
+      const oldPath = param.oldPath;
+      if (this.isFolder(file)) {
+        this._log(`Folder event skipped: ${file.path}`, LOG_LEVEL_VERBOSE);
+        continue;
+      }
+      const isTargetPath = async (path) => {
+        if (shouldBeIgnored(path)) return false;
+        if (!settings.syncInternalFiles && path.startsWith(".")) return false;
+        return await this.vaultService.isTargetFile(path);
+      };
+      if (type === "RENAME") {
+        const renamedFile = file;
+        if (!oldPath || !this.isFile(file) || !renamedFile.stat) {
+          this._log(`Invalid rename event skipped: ${file.path}`, LOG_LEVEL_VERBOSE);
+          continue;
+        }
+        const oldPathIsTarget = await isTargetPath(oldPath);
+        let newPathIsTarget = await isTargetPath(file.path);
+        if (newPathIsTarget && this.vaultService.isFileSizeTooLarge(renamedFile.stat.size)) {
+          this._log(
+            `The storage file has been changed but exceeds the maximum size. Skipping: ${param.file.path}`,
+            LOG_LEVEL_NOTICE
+          );
+          newPathIsTarget = false;
+        }
+        if (!oldPathIsTarget && !newPathIsTarget) {
+          continue;
+        }
+        if (oldPathIsTarget && !newPathIsTarget) {
+          type = "DELETE";
+          file = {
+            path: oldPath,
+            name: oldPath.split("/").pop() ?? file.name,
+            stat: renamedFile.stat,
+            deleted: true
+          };
+        } else if (!oldPathIsTarget && newPathIsTarget) {
+          type = "CREATE";
+        }
+      } else {
+        if (!await isTargetPath(file.path)) continue;
+        if (type !== "INTERNAL") {
+          const size = file.stat.size;
+          if (this.vaultService.isFileSizeTooLarge(size) && (type == "CREATE" || type == "CHANGED")) {
+            this._log(
+              `The storage file has been changed but exceeds the maximum size. Skipping: ${param.file.path}`,
+              LOG_LEVEL_NOTICE
+            );
+            continue;
+          }
+        }
+      }
+      if (this.isFile(file)) {
+        if (type == "CREATE" || type == "CHANGED" || type == "RENAME") {
+          await delay(10);
+          if (this.storageAccess.recentlyTouched({
+            path: file.path,
+            stat: file.stat ?? { ctime: 0, mtime: 0, size: 0 }
+          })) {
+            continue;
+          }
+        }
+      }
+      let cache = void 0;
+      if (param.cachedData) {
+        cache = param.cachedData;
+      }
+      void this.enqueue({
+        type,
+        args: {
+          file,
+          oldPath: type === "RENAME" ? oldPath : void 0,
+          cache,
+          ctx
+        },
+        skipBatchWait: param.skipBatchWait,
+        key: atomicKey
+      });
+    }
+  }
+  // Cache file and waiting to can be proceed.
+  bufferedQueuedItems = [];
+  enqueue(newItem) {
+    if (newItem.type == "DELETE" || newItem.type == "RENAME") {
+      this.bufferedQueuedItems.push({
+        type: TYPE_SENTINEL_FLUSH
+      });
+    }
+    this.updateStatus();
+    this.bufferedQueuedItems.push(newItem);
+    fireAndForget(() => this._takeSnapshot().then(() => this.runQueuedEvents()));
+  }
+  /**
+   * Immediately take snapshot.
+   */
+  _triggerTakeSnapshot() {
+    void this._takeSnapshot();
+  }
+  /**
+   * Trigger taking snapshot after throttled period.
+   */
+  triggerTakeSnapshot = throttle(() => this._triggerTakeSnapshot(), 100);
+  // Limit concurrent processing to reduce the IO load. file-processing + scheduler (1), so file events can be processed in 4 slots.
+  concurrentProcessing = Semaphore(5);
+  _waitingMap = /* @__PURE__ */ new Map();
+  _waitForIdle = null;
+  /**
+   * Wait until all queued events are processed.
+   * Subsequent new events will not be waited, but new events will not be added.
+   * @returns
+   */
+  waitForIdle() {
+    if (this._waitingMap.size === 0) {
+      return Promise.resolve();
+    }
+    if (this._waitForIdle) {
+      return this._waitForIdle;
+    }
+    const promises = [...this._waitingMap.entries()].map(([key, waitInfo]) => {
+      return new Promise((resolve) => {
+        waitInfo.canProceed.promise.then(() => {
+          this._log(`Processing ${key}: Wait for idle completed`, LOG_LEVEL_DEBUG);
+        }).catch((e) => {
+          this._log(`Processing ${key}: Wait for idle error`, LOG_LEVEL_INFO);
+          this._log(e, LOG_LEVEL_VERBOSE);
+        }).finally(() => {
+          resolve();
+        });
+        this._proceedWaiting(key);
+      });
+    });
+    const waitPromise = Promise.all(promises).then(() => {
+      this._waitForIdle = null;
+      this._log(`All wait for idle completed`, LOG_LEVEL_VERBOSE);
+    });
+    this._waitForIdle = waitPromise;
+    return waitPromise;
+  }
+  /**
+   * Proceed waiting for the given key immediately.
+   */
+  _proceedWaiting(key) {
+    const waitInfo = this._waitingMap.get(key);
+    if (waitInfo) {
+      waitInfo.canProceed.resolve(true);
+      compatGlobal.clearTimeout(waitInfo.timerHandler);
+      this._waitingMap.delete(key);
+    }
+    this.triggerTakeSnapshot();
+  }
+  /**
+   * Cancel waiting for the given key.
+   */
+  _cancelWaiting(key) {
+    const waitInfo = this._waitingMap.get(key);
+    if (waitInfo) {
+      waitInfo.canProceed.resolve(false);
+      compatGlobal.clearTimeout(waitInfo.timerHandler);
+      this._waitingMap.delete(key);
+    }
+    this.triggerTakeSnapshot();
+  }
+  /**
+   * Add waiting for the given key.
+   * @param key
+   * @param event
+   * @param waitedSince Optional waited since timestamp to calculate the remaining delay.
+   */
+  _addWaiting(key, event, waitedSince) {
+    if (this._waitingMap.has(key)) {
+      throw new Error(`Already waiting for key: ${key}`);
+    }
+    const resolver = promiseWithResolvers();
+    const now = Date.now();
+    const since = waitedSince ?? now;
+    const elapsed = now - since;
+    const maxDelay = this.batchSaveMaximumDelay * 1e3;
+    const remainingDelay = Math.max(0, maxDelay - elapsed);
+    const nextDelay = Math.min(remainingDelay, this.batchSaveMinimumDelay * 1e3);
+    if (elapsed >= maxDelay) {
+      this._log(`Processing ${key}: Batch save maximum delay already exceeded: ${event.type}`, LOG_LEVEL_DEBUG);
+    } else {
+      this._log(
+        `Processing ${key}: Adding waiting for batch save: ${event.type} (${nextDelay}ms)`,
+        LOG_LEVEL_DEBUG
+      );
+    }
+    const waitInfo = {
+      since,
+      type: event.type,
+      event,
+      canProceed: resolver,
+      timerHandler: compatGlobal.setTimeout(() => {
+        this._log(`Processing ${key}: Batch save timeout reached: ${event.type}`, LOG_LEVEL_DEBUG);
+        this._proceedWaiting(key);
+      }, nextDelay)
+    };
+    this._waitingMap.set(key, waitInfo);
+    this.triggerTakeSnapshot();
+    return waitInfo;
+  }
+  /**
+   * Process the given file event.
+   */
+  async processFileEvent(fei) {
+    const releaser = await this.concurrentProcessing.acquire();
+    try {
+      this.updateStatus();
+      const filename = fei.args.file.path;
+      const waitingKey = `${filename}`;
+      const previous = this._waitingMap.get(waitingKey);
+      let isShouldBeCancelled = fei.skipBatchWait || false;
+      let previousPromise = Promise.resolve(true);
+      let waitPromise = Promise.resolve(true);
+      if (previous) {
+        previousPromise = previous.canProceed.promise;
+        if (isShouldBeCancelled) {
+          this._log(
+            `Processing ${filename}: Requested to perform immediately, cancelling previous waiting: ${fei.type}`,
+            LOG_LEVEL_DEBUG
+          );
+        }
+        if (!isShouldBeCancelled && fei.type === "DELETE") {
+          this._log(
+            `Processing ${filename}: DELETE requested, cancelling previous waiting: ${fei.type}`,
+            LOG_LEVEL_DEBUG
+          );
+          isShouldBeCancelled = true;
+        }
+        if (!isShouldBeCancelled && previous.type === fei.type) {
+          this._log(`Processing ${filename}: Cancelling previous waiting: ${fei.type}`, LOG_LEVEL_DEBUG);
+          isShouldBeCancelled = true;
+        }
+        if (isShouldBeCancelled) {
+          this._cancelWaiting(waitingKey);
+          this._log(`Processing ${filename}: Previous cancelled: ${fei.type}`, LOG_LEVEL_DEBUG);
+          isShouldBeCancelled = true;
+        }
+        if (!isShouldBeCancelled) {
+          this._log(`Processing ${filename}: Waiting for previous to complete: ${fei.type}`, LOG_LEVEL_DEBUG);
+          this._proceedWaiting(waitingKey);
+          this._log(`Processing ${filename}: Previous completed: ${fei.type}`, LOG_LEVEL_DEBUG);
+        }
+      }
+      await previousPromise;
+      if (this.shouldBatchSave && !fei.skipBatchWait) {
+        if (fei.type == "CREATE" || fei.type == "CHANGED") {
+          const info = this._addWaiting(waitingKey, fei, previous?.since);
+          waitPromise = info.canProceed.promise;
+        } else if (fei.type == "DELETE") {
+        }
+        this._log(`Processing ${filename}: Waiting for batch save: ${fei.type}`, LOG_LEVEL_DEBUG);
+        const canProceed = await waitPromise;
+        if (!canProceed) {
+          this._log(`Processing ${filename}: Cancelled by new queue: ${fei.type}`, LOG_LEVEL_DEBUG);
+          return;
+        }
+      }
+      await this.requestProcessQueue(fei);
+    } finally {
+      await this._takeSnapshot();
+      releaser();
+    }
+  }
+  async _takeSnapshot() {
+    const processingEvents = [...this._waitingMap.values()].map((e) => e.event);
+    const waitingEvents = this.bufferedQueuedItems;
+    const snapShot = [...processingEvents, ...waitingEvents];
+    await this._saveSnapshot(snapShot);
+    this.updateStatus();
+  }
+  async _restoreFromSnapshot() {
+    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.updateStatus();
+      await this.runQueuedEvents();
+    } else {
+      this._log(`No snapshot to restore`, LOG_LEVEL_VERBOSE);
+    }
+  }
+  runQueuedEvents() {
+    return skipIfDuplicated("storage-event-manager-run-queued-events", async () => {
+      do {
+        if (this.bufferedQueuedItems.length === 0) {
+          break;
+        }
+        const fei = this.bufferedQueuedItems.shift();
+        await this._takeSnapshot();
+        this.updateStatus();
+        const releaser = await this.concurrentProcessing.acquire();
+        releaser();
+        this.updateStatus();
+        if (fei.type === TYPE_SENTINEL_FLUSH) {
+          this._log(`Waiting for idle`, LOG_LEVEL_VERBOSE);
+          await this.waitForIdle();
+          this.updateStatus();
+          continue;
+        }
+        fireAndForget(() => this.processFileEvent(fei));
+      } while (this.bufferedQueuedItems.length > 0);
+    });
+  }
+  processingCount = 0;
+  async requestProcessQueue(fei) {
+    try {
+      this.processingCount++;
+      this.updateStatus();
+      await this.handleFileEvent(fei);
+      await this._takeSnapshot();
+    } finally {
+      this.processingCount--;
+      this.updateStatus();
+    }
+  }
+  isWaiting(filename) {
+    return isWaitingForTimeout(`storage-event-manager-batchsave-${filename}`);
+  }
+  async handleFileEvent(queue) {
+    const file = queue.args.file;
+    const lockKey = `handleFile:${file.path}`;
+    await serialized(lockKey, async () => {
+      if (queue.cancelled) {
+        this._log(`File event cancelled before processing: ${file.path}`, LOG_LEVEL_INFO);
+        return;
+      }
+      if (queue.type == "INTERNAL" || file.isInternal) {
+        await this.fileProcessing.processOptionalFileEvent(file.path);
+      } else {
+        const last = 0;
+        if (queue.type == "DELETE") {
+          await this.fileProcessing.processFileEvent(queue);
+        } else {
+          if (file.stat.mtime == last) {
+            this._log(
+              `File has been already scanned on ${queue.type}, skip: ${file.path}`,
+              LOG_LEVEL_VERBOSE
+            );
+            return;
+          }
+          if (!await this.fileProcessing.processFileEvent(queue)) {
+            this._log(
+              `STORAGE -> DB: Handler failed, cancel the relative operations: ${file.path}`,
+              LOG_LEVEL_INFO
+            );
+            this.cancelRelativeEvent(queue);
+            return;
+          }
+        }
+      }
+    });
+    this.updateStatus();
+    return;
+  }
+  cancelRelativeEvent(item) {
+    this._cancelWaiting(item.args.file.path);
+  }
+  /**
+   * Begin watching for storage events
+   */
+  async beginWatch() {
+    await this.snapShotRestored;
+    await this.adapter.watch.beginWatch({
+      onCreate: (file, ctx) => this.watchVaultCreate(file, ctx),
+      onChange: (file, ctx) => this.watchVaultChange(file, ctx),
+      onDelete: (file, ctx) => this.watchVaultDelete(file, ctx),
+      onRename: (file, oldPath, ctx) => this.watchVaultRename(file, oldPath, ctx),
+      onRaw: (path) => this.watchVaultRawEvents(path),
+      onEditorChange: (editor, info) => this.watchEditorChange(editor, info)
+    });
+  }
+  /**
+   * Platform-agnostic event handlers
+   */
+  watchEditorChange(editor, info) {
+    if (typeof info !== "object" || info === null) {
+      return;
+    }
+    if (!("path" in info)) {
+      return;
+    }
+    if (!this.shouldBatchSave) {
+      return;
+    }
+    if (!("file" in info)) {
+      return;
+    }
+    const file = info?.file;
+    if (!file) return;
+    const path = this.adapter.typeGuard.isFile(file) ? file.path : info.path;
+    if (!path) return;
+    if (this.storageAccess.isFileProcessing(path)) {
+      return;
+    }
+    if (!this.isWaiting(path)) {
+      return;
+    }
+    const data = info?.data;
+    const fi = {
+      type: "CHANGED",
+      file: this.adapter.converter.toFileInfo(file),
+      cachedData: data
+    };
+    void this.appendQueue([fi]);
+  }
+  watchVaultCreate(file, ctx) {
+    if (this.adapter.typeGuard.isFolder(file)) return;
+    const path = file.path;
+    if (this.storageAccess.isFileProcessing(path)) {
+      return;
+    }
+    const fileInfo = this.adapter.converter.toFileInfo(file);
+    void this.appendQueue([{ type: "CREATE", file: fileInfo }], ctx);
+  }
+  watchVaultChange(file, ctx) {
+    if (this.adapter.typeGuard.isFolder(file)) return;
+    const path = file.path;
+    if (this.storageAccess.isFileProcessing(path)) {
+      return;
+    }
+    const fileInfo = this.adapter.converter.toFileInfo(file);
+    void this.appendQueue([{ type: "CHANGED", file: fileInfo }], ctx);
+  }
+  watchVaultDelete(file, ctx) {
+    if (this.adapter.typeGuard.isFolder(file)) return;
+    const path = file.path;
+    if (this.storageAccess.isFileProcessing(path)) {
+      return;
+    }
+    const fileInfo = this.adapter.converter.toFileInfo(file, true);
+    void this.appendQueue([{ type: "DELETE", file: fileInfo }], ctx);
+  }
+  watchVaultRename(file, oldPath, ctx) {
+    if (this.adapter.typeGuard.isFile(file)) {
+      const fileInfo = this.adapter.converter.toFileInfo(file);
+      void this.appendQueue(
+        [
+          {
+            type: "RENAME",
+            file: fileInfo,
+            oldPath,
+            skipBatchWait: true
+          }
+        ],
+        ctx
+      );
+    }
+  }
+  watchVaultRawEvents(path) {
+    if (this.storageAccess.isFileProcessing(path)) {
+      return;
+    }
+    if (!this.settings) return;
+    if (this.settings.useIgnoreFiles) {
+      void this.vaultService.isTargetFile(path).then(() => this._watchVaultRawEvents(path));
+    } else {
+      void this._watchVaultRawEvents(path);
+    }
+  }
+  async _watchVaultRawEvents(path) {
+  }
+}
+export {
+  StorageEventManagerBase
+};

package/dist/managers/StorageProcessingManager.d.ts

@@ -0,0 +1,14 @@
+import type { FilePathWithPrefix } from "../common/models/db.type.js";
+import type { UXFileInfoStub } from "../common/models/fileaccess.type.js";
+import type { IStorageAccessManager } from "../interfaces/StorageAccess.js";
+import type { FileWithFileStat, FileWithStatAsProp } from "../common/models/fileaccess.type.js";
+export declare class StorageAccessManager implements IStorageAccessManager {
+    processingFiles: Set<FilePathWithPrefix>;
+    processWriteFile<T>(file: UXFileInfoStub | FilePathWithPrefix, proc: () => Promise<T>): Promise<T>;
+    processReadFile<T>(file: UXFileInfoStub | FilePathWithPrefix, proc: () => Promise<T>): Promise<T>;
+    isFileProcessing(file: UXFileInfoStub | FilePathWithPrefix): boolean;
+    private touchedFiles;
+    touch(file: FileWithFileStat | FileWithStatAsProp): void;
+    recentlyTouched(file: FileWithStatAsProp | FileWithFileStat): boolean;
+    clearTouched(): void;
+}

package/dist/managers/StorageProcessingManager.js

@@ -0,0 +1,48 @@
+import { serialized } from "octagonal-wheels/concurrency/lock";
+const fileLockPrefix = "file-lock:";
+class StorageAccessManager {
+  processingFiles = /* @__PURE__ */ new Set();
+  processWriteFile(file, proc) {
+    const path = typeof file === "string" ? file : file.path;
+    return serialized(`${fileLockPrefix}${path}`, async () => {
+      try {
+        this.processingFiles.add(path);
+        return await proc();
+      } finally {
+        this.processingFiles.delete(path);
+      }
+    });
+  }
+  processReadFile(file, proc) {
+    const path = typeof file === "string" ? file : file.path;
+    return serialized(`${fileLockPrefix}${path}`, async () => {
+      try {
+        this.processingFiles.add(path);
+        return await proc();
+      } finally {
+        this.processingFiles.delete(path);
+      }
+    });
+  }
+  isFileProcessing(file) {
+    const path = typeof file === "string" ? file : file.path;
+    return this.processingFiles.has(path);
+  }
+  touchedFiles = [];
+  touch(file) {
+    const key = "stat" in file ? `${file.path}-${file.stat.mtime}-${file.stat.size}` : `${file.path}-${file.mtime}-${file.size}`;
+    this.touchedFiles.unshift(key);
+    this.touchedFiles = this.touchedFiles.slice(0, 100);
+  }
+  recentlyTouched(file) {
+    const key = "stat" in file ? `${file.path}-${file.stat.mtime}-${file.stat.size}` : `${file.path}-${file.mtime}-${file.size}`;
+    if (this.touchedFiles.indexOf(key) == -1) return false;
+    return true;
+  }
+  clearTouched() {
+    this.touchedFiles = [];
+  }
+}
+export {
+  StorageAccessManager
+};

package/dist/managers/adapters/IStorageEventConverterAdapter.d.ts

@@ -0,0 +1,16 @@
+import type { FilePath, UXFileInfoStub, UXInternalFileInfoStub } from "../../common/types.js";
+/**
+ * Adapter interface for converting platform-specific file types to UX types
+ *
+ * @template TFile - Platform-specific file type
+ */
+export interface IStorageEventConverterAdapter<TFile> {
+    /**
+     * Convert platform-specific file to UXFileInfoStub
+     */
+    toFileInfo(file: TFile, deleted?: boolean): UXFileInfoStub;
+    /**
+     * Convert path to UXInternalFileInfoStub
+     */
+    toInternalFileInfo(path: FilePath): UXInternalFileInfoStub;
+}

package/dist/managers/adapters/IStorageEventManagerAdapter.d.ts

@@ -0,0 +1,18 @@
+import type { IStorageEventTypeGuardAdapter } from "./IStorageEventTypeGuardAdapter.js";
+import type { IStorageEventPersistenceAdapter } from "./IStorageEventPersistenceAdapter.js";
+import type { IStorageEventWatchAdapter } from "./IStorageEventWatchAdapter.js";
+import type { IStorageEventStatusAdapter } from "./IStorageEventStatusAdapter.js";
+import type { IStorageEventConverterAdapter } from "./IStorageEventConverterAdapter.js";
+/**
+ * Composite adapter interface for StorageEventManager
+ *
+ * @template TFile - Platform-specific file type
+ * @template TFolder - Platform-specific folder type
+ */
+export interface IStorageEventManagerAdapter<TFile, TFolder> {
+    readonly typeGuard: IStorageEventTypeGuardAdapter<TFile, TFolder>;
+    readonly persistence: IStorageEventPersistenceAdapter;
+    readonly watch: IStorageEventWatchAdapter<TFile, unknown>;
+    readonly status: IStorageEventStatusAdapter;
+    readonly converter: IStorageEventConverterAdapter<TFile>;
+}

package/dist/managers/adapters/IStorageEventPersistenceAdapter.d.ts

@@ -0,0 +1,15 @@
+import type { FileEventItem } from "../../common/types.js";
+import type { FileEventItemSentinel } from "../StorageEventManager.js";
+/**
+ * Adapter interface for snapshot persistence operations
+ */
+export interface IStorageEventPersistenceAdapter {
+    /**
+     * Save the snapshot of pending events
+     */
+    saveSnapshot(snapshot: (FileEventItem | FileEventItemSentinel)[]): Promise<void>;
+    /**
+     * Load the snapshot of pending events
+     */
+    loadSnapshot(): Promise<(FileEventItem | FileEventItemSentinel)[] | null>;
+}

package/dist/managers/adapters/IStorageEventStatusAdapter.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Adapter interface for status update operations
+ */
+export interface IStorageEventStatusAdapter {
+    /**
+     * Update the status display
+     */
+    updateStatus(status: {
+        batched: number;
+        processing: number;
+        totalQueued: number;
+    }): void;
+}