@vrtmrz/livesync-commonlib 0.1.0-rc.0

package/dist/serviceModules/ServiceFileHandlerBase.d.ts

@@ -0,0 +1,52 @@
+import type { AnyEntry, FilePath, FilePathWithPrefix, MetaEntry, UXFileInfo, UXFileInfoStub, UXInternalFileInfoStub } from "../common/types.js";
+import type { LiveSyncEventHub } from "../hub/hub.js";
+import type { IFileHandler } from "../interfaces/FileHandler.js";
+import { ServiceModuleBase } from "./ServiceModuleBase.js";
+import type { APIService } from "../services/base/APIService.js";
+import type { DatabaseFileAccess } from "../interfaces/DatabaseFileAccess.js";
+import type { StorageAccess } from "../interfaces/StorageAccess.js";
+import type { FileProcessingService } from "../services/base/FileProcessingService.js";
+import type { ReplicationService } from "../services/base/ReplicationService.js";
+import type { ConflictService } from "../services/base/ConflictService.js";
+import type { PathService } from "../services/base/PathService.js";
+import type { SettingService } from "../services/base/SettingService.js";
+import type { VaultService } from "../services/base/VaultService.js";
+export interface ServiceFileHandlerDependencies {
+    events: LiveSyncEventHub;
+    API: APIService;
+    databaseFileAccess: DatabaseFileAccess;
+    storageAccess: StorageAccess;
+    fileProcessing: FileProcessingService;
+    replication: ReplicationService;
+    conflict: ConflictService;
+    path: PathService;
+    setting: SettingService;
+    vault: VaultService;
+}
+export declare abstract class ServiceFileHandlerBase extends ServiceModuleBase<ServiceFileHandlerDependencies> implements IFileHandler {
+    private events;
+    private databaseFileAccess;
+    private storageAccess;
+    private conflict;
+    private path;
+    private setting;
+    private vault;
+    constructor(services: ServiceFileHandlerDependencies);
+    get db(): DatabaseFileAccess;
+    get storage(): StorageAccess;
+    getPath(entry: AnyEntry): FilePathWithPrefix;
+    getPathWithoutPrefix(entry: AnyEntry): FilePathWithPrefix;
+    readFileFromStub(file: UXFileInfoStub | UXFileInfo): Promise<UXFileInfo>;
+    private infoToStub;
+    storeFileToDB(info: UXFileInfoStub | UXFileInfo | UXInternalFileInfoStub | FilePathWithPrefix, force?: boolean, onlyChunks?: boolean): Promise<boolean>;
+    deleteFileFromDB(info: UXFileInfoStub | UXInternalFileInfoStub | FilePath): Promise<boolean>;
+    renameFileInDB(info: UXFileInfoStub | UXFileInfo, oldPath: FilePath | FilePathWithPrefix): Promise<boolean>;
+    deleteRevisionFromDB(info: UXFileInfoStub | FilePath | FilePathWithPrefix, rev: string): Promise<boolean | undefined>;
+    resolveConflictedByDeletingRevision(info: UXFileInfoStub | FilePath, rev: string): Promise<boolean | undefined>;
+    dbToStorageWithSpecificRev(info: UXFileInfoStub | UXFileInfo | FilePath | null, rev: string, force?: boolean): Promise<boolean>;
+    dbToStorage(entryInfo: MetaEntry | FilePathWithPrefix, info: UXFileInfoStub | UXFileInfo | FilePath | null, force?: boolean): Promise<boolean>;
+    private preserveUnsyncedStorageAsConflict;
+    private _anyHandlerProcessesFileEvent;
+    _anyProcessReplicatedDoc(entry: MetaEntry): Promise<boolean>;
+    createAllChunks(showingNotice?: boolean): Promise<void>;
+}

package/dist/serviceModules/ServiceFileHandlerBase.js

@@ -0,0 +1,493 @@
+import { LOG_LEVEL_INFO, LOG_LEVEL_NOTICE, LOG_LEVEL_VERBOSE } from "octagonal-wheels/common/logger";
+import { serialized } from "octagonal-wheels/concurrency/lock";
+import {
+  createBlob,
+  getDocDataAsArray,
+  isDocContentSame,
+  isTextBlob,
+  readAsBlob,
+  readContent
+} from "../common/utils.js";
+import { EVENT_CONFLICT_CANCELLED } from "../events/coreEvents.js";
+import { shouldBeIgnored, stripAllPrefixes } from "../string_and_binary/path.js";
+import { Semaphore } from "octagonal-wheels/concurrency/semaphore";
+import { ServiceModuleBase } from "./ServiceModuleBase.js";
+import { getStoragePathFromUXFileInfo } from "../common/typeUtils.js";
+import { EVEN } from "../common/models/shared.const.symbols.js";
+import { tryGetFilePath } from "../common/utils.doc.js";
+async function isIncomingTextClearExtension(incomingContent, localContent) {
+  const incomingBlob = createBlob(incomingContent);
+  const localBlob = createBlob(localContent);
+  if (!isTextBlob(incomingBlob) || !isTextBlob(localBlob)) {
+    return false;
+  }
+  const incomingText = await incomingBlob.text();
+  const localText = await localBlob.text();
+  return incomingText.startsWith(localText) || incomingText.endsWith(localText);
+}
+async function serializedByKeys(keys, callback) {
+  const [key, ...remainingKeys] = keys;
+  if (key === void 0) return await callback();
+  return await serialized(key, () => serializedByKeys(remainingKeys, callback));
+}
+function getParentPath(path) {
+  const lastSeparator = path.lastIndexOf("/");
+  return lastSeparator < 0 ? "" : path.slice(0, lastSeparator);
+}
+function isFolderInfo(info) {
+  return info?.isFolder === true;
+}
+class ServiceFileHandlerBase extends ServiceModuleBase {
+  events;
+  databaseFileAccess;
+  storageAccess;
+  conflict;
+  path;
+  setting;
+  vault;
+  constructor(services) {
+    super(services);
+    this.events = services.events;
+    this.databaseFileAccess = services.databaseFileAccess;
+    this.storageAccess = services.storageAccess;
+    this.conflict = services.conflict;
+    this.path = services.path;
+    this.setting = services.setting;
+    this.vault = services.vault;
+    services.fileProcessing.processFileEvent.addHandler(this._anyHandlerProcessesFileEvent.bind(this), 100);
+    services.replication.processSynchroniseResult.addHandler(this._anyProcessReplicatedDoc.bind(this), 100);
+  }
+  get db() {
+    return this.databaseFileAccess;
+  }
+  get storage() {
+    return this.storageAccess;
+  }
+  getPath(entry) {
+    return this.path.getPath(entry);
+  }
+  getPathWithoutPrefix(entry) {
+    return stripAllPrefixes(this.path.getPath(entry));
+  }
+  async readFileFromStub(file) {
+    if ("body" in file && file.body) {
+      return file;
+    }
+    const readFile = await this.storage.readStubContent(file);
+    if (!readFile) {
+      throw new Error(`File ${file.path} is not exist on the storage`);
+    }
+    return readFile;
+  }
+  async infoToStub(info) {
+    if (info == null) return null;
+    const file = typeof info === "string" ? await this.storage.getFileStub(info) : info;
+    return file;
+  }
+  async storeFileToDB(info, force = false, onlyChunks = false) {
+    const file = await this.infoToStub(info);
+    if (file == null) {
+      this._log(`File ${tryGetFilePath(info)} is not exist on the storage`, LOG_LEVEL_VERBOSE);
+      return false;
+    }
+    if (file.isInternal) {
+      this._log(
+        `Internal file ${file.path} is not allowed to be processed on processFileEvent`,
+        LOG_LEVEL_VERBOSE
+      );
+      return false;
+    }
+    const entry = await this.db.fetchEntry(file, void 0, true, true);
+    if (!entry || entry.deleted || entry._deleted) {
+      const readFile = await this.readFileFromStub(file);
+      if (!onlyChunks) {
+        return await this.db.store(readFile);
+      } else {
+        return await this.db.createChunks(readFile, false, true);
+      }
+    }
+    let shouldApplied = false;
+    if (!force && !onlyChunks) {
+      if (this.path.compareFileFreshness(file, entry) !== EVEN) {
+        shouldApplied = true;
+      }
+      let readFile = void 0;
+      if (!shouldApplied) {
+        readFile = await this.readFileFromStub(file);
+        if (!readFile) {
+          this._log(`File ${file.path} is not exist on the storage`, LOG_LEVEL_NOTICE);
+          return false;
+        }
+        if (await isDocContentSame(getDocDataAsArray(entry.data), readFile.body)) {
+          this.path.markChangesAreSame(readFile, readFile.stat.mtime, entry.mtime);
+        } else {
+          shouldApplied = true;
+        }
+      }
+      if (!shouldApplied) {
+        this._log(`File ${file.path} is not changed`, LOG_LEVEL_VERBOSE);
+        return true;
+      }
+      if (!readFile) readFile = await this.readFileFromStub(file);
+      if (onlyChunks) {
+        return await this.db.createChunks(readFile, false, true);
+      } else {
+        return await this.db.store(readFile, false, true);
+      }
+    } else {
+      const readFile = await this.readFileFromStub(file);
+      if (onlyChunks) {
+        return await this.db.createChunks(readFile, true, true);
+      } else {
+        return await this.db.store(readFile, true, true);
+      }
+    }
+  }
+  async deleteFileFromDB(info) {
+    const file = await this.infoToStub(info);
+    if (file == null) {
+      const path = typeof info === "string" ? info : tryGetFilePath(info);
+      if (path === void 0) {
+        this._log(`File ${tryGetFilePath(info)} is not exist on the storage`, LOG_LEVEL_VERBOSE);
+        return false;
+      }
+      const entryByPath = await this.db.fetchEntry(path, void 0, true, true);
+      if (!entryByPath || entryByPath.deleted || entryByPath._deleted) {
+        this._log(
+          `File ${path} is not exist on the storage nor the database (or already deleted)`,
+          LOG_LEVEL_VERBOSE
+        );
+        return false;
+      }
+      this._log(`File ${path} is missing on storage; deleting from the database by path`, LOG_LEVEL_INFO);
+      return await this.db.delete(path);
+    }
+    if (file.isInternal) {
+      this._log(
+        `Internal file ${file.path} is not allowed to be processed on processFileEvent`,
+        LOG_LEVEL_VERBOSE
+      );
+      return false;
+    }
+    const entry = await this.db.fetchEntry(file, void 0, true, true);
+    if (!entry || entry.deleted || entry._deleted) {
+      this._log(`File ${file.path} is not exist or already deleted on the database`, LOG_LEVEL_VERBOSE);
+      return false;
+    }
+    const conflictedRevs = await this.db.getConflictedRevs(file);
+    if (conflictedRevs.length > 0) {
+      return await this.db.delete(file, entry._rev);
+    }
+    return await this.db.delete(file);
+  }
+  async renameFileInDB(info, oldPath) {
+    const newPath = getStoragePathFromUXFileInfo(info);
+    const [oldDocumentId, newDocumentId] = await Promise.all([
+      this.path.path2id(oldPath),
+      this.path.path2id(newPath)
+    ]);
+    if (oldDocumentId === newDocumentId) {
+      this._log(`Updating the stored path for case-only rename: ${oldPath} -> ${newPath}`, LOG_LEVEL_VERBOSE);
+      return await this.storeFileToDB(info, true);
+    }
+    const oldEntry = await this.db.fetchEntryMeta(oldPath, void 0, true);
+    if (!await this.storeFileToDB(info, true)) {
+      this._log(`Failed to store rename target; preserving source in the database: ${oldPath}`, LOG_LEVEL_NOTICE);
+      return false;
+    }
+    if (!oldEntry || oldEntry.deleted || oldEntry._deleted) {
+      this._log(`Rename source is not present in the database: ${oldPath}`, LOG_LEVEL_VERBOSE);
+      return true;
+    }
+    const oldFile = {
+      path: oldPath,
+      name: oldPath.split("/").pop() ?? info.name,
+      stat: info.stat,
+      deleted: true
+    };
+    return await this.deleteFileFromDB(oldFile);
+  }
+  async deleteRevisionFromDB(info, rev) {
+    return await this.db.delete(info, rev);
+  }
+  async resolveConflictedByDeletingRevision(info, rev) {
+    const path = getStoragePathFromUXFileInfo(info);
+    if (!await this.deleteRevisionFromDB(info, rev)) {
+      this._log(`Failed to delete the conflicted revision ${rev} of ${path}`, LOG_LEVEL_VERBOSE);
+      return false;
+    }
+    if (!await this.dbToStorageWithSpecificRev(info, rev, true)) {
+      this._log(`Failed to apply the resolved revision ${rev} of ${path} to the storage`, LOG_LEVEL_VERBOSE);
+      return false;
+    }
+  }
+  async dbToStorageWithSpecificRev(info, rev, force) {
+    const file = await this.infoToStub(info);
+    if (file == null) {
+      this._log(`File ${tryGetFilePath(info)} is not exist on the storage`, LOG_LEVEL_VERBOSE);
+      return false;
+    }
+    const docEntry = await this.db.fetchEntryMeta(file, rev, true);
+    if (!docEntry) {
+      this._log(`File ${file.path} is not exist on the database`, LOG_LEVEL_VERBOSE);
+      return false;
+    }
+    return await this.dbToStorage(docEntry, file, force);
+  }
+  async dbToStorage(entryInfo, info, force) {
+    const file = await this.infoToStub(info);
+    const mode = file == null ? "create" : "modify";
+    const pathFromEntryInfo = typeof entryInfo === "string" ? entryInfo : this.getPath(entryInfo);
+    const docEntry = await this.db.fetchEntryMeta(pathFromEntryInfo, void 0, true);
+    if (!docEntry) {
+      this._log(`File ${pathFromEntryInfo} is not exist on the database`, LOG_LEVEL_VERBOSE);
+      return false;
+    }
+    const path = this.getPath(docEntry);
+    const settings = this.setting.currentSettings();
+    const revs = await this.db.getConflictedRevs(path);
+    if (revs.length > 0) {
+      if (settings.writeDocumentsIfConflicted) {
+      } else {
+        await this.conflict.queueCheckForIfOpen(path);
+        return true;
+      }
+    }
+    let existDoc = await this.storage.getStub(path);
+    if (isFolderInfo(existDoc)) {
+      this._log(`Folder ${path} is already exist on the storage as a folder`, LOG_LEVEL_VERBOSE);
+      return true;
+    }
+    const existOnDB = !(docEntry._deleted || docEntry.deleted || false);
+    if (!existOnDB && !existDoc) {
+      this._log(`File ${path} seems to be deleted, but already not on storage`, LOG_LEVEL_VERBOSE);
+      return true;
+    }
+    if (!existOnDB && existDoc) {
+      if (!force && !settings.writeDocumentsIfConflicted && await this.preserveUnsyncedStorageAsConflict(path, existDoc, docEntry)) {
+        return true;
+      }
+      await this.storage.deleteVaultItem(path);
+      return true;
+    }
+    if (existDoc && existDoc.path !== path) {
+      const [existingDocumentId, targetDocumentId] = await Promise.all([
+        this.path.path2id(existDoc.path),
+        this.path.path2id(path)
+      ]);
+      if (existingDocumentId !== targetDocumentId) {
+        this._log(
+          `Refusing to overwrite ${existDoc.path} while applying the distinct path ${path}`,
+          LOG_LEVEL_NOTICE
+        );
+        return false;
+      }
+      if (getParentPath(existDoc.path) !== getParentPath(path)) {
+        this._log(
+          `Refusing to apply a filename case change across differently cased parent directories: ${existDoc.path} -> ${path}`,
+          LOG_LEVEL_NOTICE
+        );
+        return false;
+      }
+      const renamedFile = await this.storage.renameFile(existDoc, path);
+      if (!renamedFile) {
+        this._log(`Could not apply the stored filename case: ${existDoc.path} -> ${path}`, LOG_LEVEL_NOTICE);
+        return false;
+      }
+      existDoc = renamedFile;
+    }
+    const docRead = await this.db.fetchEntryFromMeta(docEntry);
+    if (!docRead) {
+      this._log(`File ${path} is not exist on the database`, LOG_LEVEL_VERBOSE);
+      return false;
+    }
+    if (!settings.processSizeMismatchedFiles) {
+      if (docRead.size != 0 && docRead.size !== readAsBlob(docRead).size) {
+        this._log(
+          `File ${path} seems to be corrupted! Writing prevented. (${docRead.size} != ${readAsBlob(docRead).size})`,
+          LOG_LEVEL_NOTICE
+        );
+        return false;
+      }
+    }
+    const docData = readContent(docRead);
+    if (existDoc && !force) {
+      let shouldApplied = false;
+      const freshness = this.path.compareFileFreshness(existDoc, docEntry);
+      if (freshness !== EVEN) {
+        shouldApplied = true;
+      }
+      if (!shouldApplied) {
+        const readFile = await this.readFileFromStub(existDoc);
+        if (await isDocContentSame(docData, readFile.body)) {
+          shouldApplied = false;
+          this.path.markChangesAreSame(docRead, docRead.mtime, existDoc.stat.mtime);
+        } else {
+          shouldApplied = true;
+        }
+      }
+      if (!shouldApplied) {
+        this._log(`File ${docRead.path} is not changed`, LOG_LEVEL_VERBOSE);
+        return true;
+      }
+      if (!force && !settings.writeDocumentsIfConflicted && await this.preserveUnsyncedStorageAsConflict(path, existDoc, docEntry, docData)) {
+        return true;
+      }
+    } else {
+      this._log(
+        `File ${docRead.path} ${existDoc ? "(new) " : ""} ${force ? " (forced)" : ""}`,
+        LOG_LEVEL_VERBOSE
+      );
+    }
+    await this.storage.ensureDir(path);
+    const ret = await this.storage.writeFileAuto(path, docData, { ctime: docRead.ctime, mtime: docRead.mtime });
+    await this.storage.touched(path);
+    this.storage.triggerFileEvent(mode, path);
+    return ret;
+  }
+  async preserveUnsyncedStorageAsConflict(path, existDoc, incomingEntry, incomingContent) {
+    const readFile = await this.readFileFromStub(existDoc);
+    if (incomingContent && await isDocContentSame(incomingContent, readFile.body)) {
+      return false;
+    }
+    if (incomingContent && await isIncomingTextClearExtension(incomingContent, readFile.body)) {
+      return false;
+    }
+    if (!incomingEntry._rev) {
+      return false;
+    }
+    if (await this.db.hasContentInRevisionHistory(path, readFile.body, incomingEntry._rev)) {
+      return false;
+    }
+    const stored = await this.db.storeAsConflictedRevision(readFile, incomingEntry._rev, true);
+    if (!stored) {
+      this._log(`Prevented overwriting unsynchronised local changes for ${path}`, LOG_LEVEL_NOTICE);
+      return true;
+    }
+    this._log(`Preserved unsynchronised local changes as a conflict for ${path}`, LOG_LEVEL_NOTICE);
+    await this.conflict.queueCheckFor(path);
+    return true;
+  }
+  async _anyHandlerProcessesFileEvent(item) {
+    const eventItem = item.args;
+    const type = item.type;
+    const path = eventItem.file.path;
+    if (!await this.vault.isTargetFile(path)) {
+      this._log(`File ${path} is not the target file`, LOG_LEVEL_VERBOSE);
+      return false;
+    }
+    if (shouldBeIgnored(path)) {
+      this._log(`File ${path} should be ignored`, LOG_LEVEL_VERBOSE);
+      return false;
+    }
+    if (type === "RENAME" && !eventItem.oldPath) {
+      this._log(`Rename event for ${path} has no source path`, LOG_LEVEL_VERBOSE);
+      return false;
+    }
+    const eventPaths = type === "RENAME" ? [path, eventItem.oldPath] : [path];
+    const documentIds = await Promise.all(eventPaths.map((eventPath) => this.path.path2id(eventPath)));
+    const lockKeys = [...new Set(documentIds)].sort().map((documentId) => `processFileEvent-${documentId}`);
+    return await serializedByKeys(lockKeys, async () => {
+      switch (type) {
+        case "CREATE":
+        case "CHANGED":
+          return await this.storeFileToDB(item.args.file);
+        case "DELETE":
+          return await this.deleteFileFromDB(item.args.file);
+        case "RENAME":
+          return await this.renameFileInDB(
+            item.args.file,
+            item.args.oldPath
+          );
+        case "INTERNAL":
+          return false;
+        default:
+          this._log(`Unsupported event type: ${type}`, LOG_LEVEL_VERBOSE);
+          return false;
+      }
+    });
+  }
+  async _anyProcessReplicatedDoc(entry) {
+    return await serialized(`processReplicatedDoc-${entry._id}`, async () => {
+      if (!await this.vault.isTargetFile(entry.path)) {
+        this._log(`File ${entry.path} is not the target file`, LOG_LEVEL_VERBOSE);
+        return false;
+      }
+      if (this.vault.isFileSizeTooLarge(entry.size)) {
+        this._log(`File ${entry.path} is too large (on database) to be processed`, LOG_LEVEL_VERBOSE);
+        return false;
+      }
+      if (shouldBeIgnored(entry.path)) {
+        this._log(`File ${entry.path} should be ignored`, LOG_LEVEL_VERBOSE);
+        return false;
+      }
+      const path = this.getPath(entry);
+      const targetFile = await this.storage.getStub(this.getPathWithoutPrefix(entry));
+      if (isFolderInfo(targetFile)) {
+        this._log(`${path} is already exist as the folder`);
+        return true;
+      } else {
+        if (targetFile && this.vault.isFileSizeTooLarge(targetFile.stat.size)) {
+          this._log(`File ${targetFile.path} is too large (on storage) to be processed`, LOG_LEVEL_VERBOSE);
+          return false;
+        }
+        this._log(
+          `Processing ${path} (${entry._id.substring(0, 8)} :${entry._rev?.substring(0, 5)}) : Started...`,
+          LOG_LEVEL_VERBOSE
+        );
+        this.events.emitEvent(EVENT_CONFLICT_CANCELLED, path);
+        const ret = await this.dbToStorage(entry, targetFile);
+        this._log(`Processing ${path} (${entry._id.substring(0, 8)} :${entry._rev?.substring(0, 5)}) : Done`);
+        return ret;
+      }
+    });
+  }
+  async createAllChunks(showingNotice) {
+    this._log("Collecting local files on the storage", LOG_LEVEL_VERBOSE);
+    const semaphore = Semaphore(10);
+    let processed = 0;
+    const filesStorageSrc = await this.storage.getFiles();
+    const incProcessed = () => {
+      processed++;
+      if (processed % 25 == 0)
+        this._log(
+          `Creating missing chunks: ${processed} of ${total} files`,
+          showingNotice ? LOG_LEVEL_NOTICE : LOG_LEVEL_INFO,
+          "chunkCreation"
+        );
+    };
+    const total = filesStorageSrc.length;
+    const procAllChunks = filesStorageSrc.map(async (file) => {
+      if (!await this.vault.isTargetFile(file)) {
+        incProcessed();
+        return true;
+      }
+      if (this.vault.isFileSizeTooLarge(file.stat.size)) {
+        incProcessed();
+        return true;
+      }
+      if (shouldBeIgnored(file.path)) {
+        incProcessed();
+        return true;
+      }
+      const release = await semaphore.acquire();
+      incProcessed();
+      try {
+        await this.storeFileToDB(file, false, true);
+      } catch (ex) {
+        this._log(ex, LOG_LEVEL_VERBOSE);
+      } finally {
+        release();
+      }
+    });
+    await Promise.all(procAllChunks);
+    this._log(
+      `Creating chunks Done: ${processed} of ${total} files`,
+      showingNotice ? LOG_LEVEL_NOTICE : LOG_LEVEL_INFO,
+      "chunkCreation"
+    );
+  }
+}
+export {
+  ServiceFileHandlerBase
+};

package/dist/serviceModules/ServiceModuleBase.d.ts

@@ -0,0 +1,10 @@
+import type { APIService } from "../services/base/APIService.js";
+import { createInstanceLogFunction } from "../services/lib/logUtils.js";
+export interface ServiceModuleBaseDependencies {
+    API: APIService;
+}
+export declare abstract class ServiceModuleBase<T extends ServiceModuleBaseDependencies> {
+    _log: ReturnType<typeof createInstanceLogFunction>;
+    get name(): string;
+    constructor(services: T);
+}

package/dist/serviceModules/ServiceModuleBase.js

@@ -0,0 +1,13 @@
+import { createInstanceLogFunction } from "../services/lib/logUtils.js";
+class ServiceModuleBase {
+  _log;
+  get name() {
+    return this.constructor.name;
+  }
+  constructor(services) {
+    this._log = createInstanceLogFunction(this.name, services.API);
+  }
+}
+export {
+  ServiceModuleBase
+};

package/dist/serviceModules/adapters/IConversionAdapter.d.ts

@@ -0,0 +1,15 @@
+import type { UXFileInfoStub, UXFolderInfo } from "../../common/types.js";
+/**
+ * Conversion adapter interface
+ * Converts between native file system types and universal types
+ */
+export interface IConversionAdapter<TNativeFile = any, TNativeFolder = any> {
+    /**
+     * Convert a native file object to a universal file info stub
+     */
+    nativeFileToUXFileInfoStub(file: TNativeFile): UXFileInfoStub;
+    /**
+     * Convert a native folder object to a universal folder info
+     */
+    nativeFolderToUXFolder(folder: TNativeFolder): UXFolderInfo;
+}

package/dist/serviceModules/adapters/IFileSystemAdapter.d.ts

@@ -0,0 +1,47 @@
+import type { FilePath, UXStat } from "../../common/types.js";
+import type { IPathAdapter } from "./IPathAdapter.js";
+import type { ITypeGuardAdapter } from "./ITypeGuardAdapter.js";
+import type { IConversionAdapter } from "./IConversionAdapter.js";
+import type { IStorageAdapter } from "./IStorageAdapter.js";
+import type { IVaultAdapter } from "./IVaultAdapter.js";
+/**
+ * Main file system adapter interface
+ * Composes all other adapters and provides platform-specific operations
+ */
+export interface IFileSystemAdapter<TNativeAbstractFile = any, TNativeFile = any, TNativeFolder = any, TStat extends UXStat = UXStat> {
+    /** Path operations */
+    readonly path: IPathAdapter<TNativeAbstractFile>;
+    /** Type guard operations */
+    readonly typeGuard: ITypeGuardAdapter<TNativeFile, TNativeFolder>;
+    /** Conversion operations */
+    readonly conversion: IConversionAdapter<TNativeFile, TNativeFolder>;
+    /** Storage operations */
+    readonly storage: IStorageAdapter<TStat>;
+    /** Vault operations */
+    readonly vault: IVaultAdapter<TNativeFile>;
+    /**
+     * Get a file or folder by path (case-sensitive)
+     */
+    getAbstractFileByPath(path: FilePath | string): Promise<TNativeAbstractFile | null>;
+    /**
+     * Get a file or folder by path (case-insensitive)
+     */
+    getAbstractFileByPathInsensitive(path: FilePath | string): Promise<TNativeAbstractFile | null>;
+    /**
+     * Get all files in the vault
+     */
+    getFiles(): Promise<TNativeFile[]>;
+    /**
+     * Rename a file and refresh any platform-specific caches
+     */
+    renameFile(file: TNativeFile, newPath: string): Promise<TNativeFile>;
+    /**
+     * Get file statistics from a native file object
+     */
+    statFromNative(file: TNativeFile): Promise<UXStat>;
+    /**
+     * Reconcile internal file state
+     * Platform-specific operation for syncing internal metadata
+     */
+    reconcileInternalFile(path: string): Promise<void>;
+}

package/dist/serviceModules/adapters/IPathAdapter.d.ts

@@ -0,0 +1,15 @@
+import type { FilePath } from "../../common/types.js";
+/**
+ * Path operations adapter interface
+ * Handles path normalization and extraction
+ */
+export interface IPathAdapter<TNativeAbstractFile = any> {
+    /**
+     * Get the path from a file object or return the path string as-is
+     */
+    getPath(file: TNativeAbstractFile | string): FilePath;
+    /**
+     * Normalize a path according to the platform's conventions
+     */
+    normalisePath(path: string): string;
+}