@firesystem/core/src/interfaces/IFileSystem.ts

Virtual File System core interfaces and types

import type { FileEntry, FileStat, FileMetadata } from "../types/FileEntry";
import type { Disposable } from "../types/Common";
import type { FSEvent } from "../types/Events";
import type { IFileSystemCapabilities } from "./FileSystemCapabilities";

/**
 * Virtual File System interface
 * Provides a uniform API for different storage backends
 */
export interface IFileSystem {
  // File operations
  readFile(path: string): Promise<FileEntry>;
  writeFile(
    path: string,
    content: any,
    metadata?: FileMetadata,
  ): Promise<FileEntry>;
  deleteFile(path: string): Promise<void>;
  exists(path: string): Promise<boolean>;

  // Directory operations
  readDir(path: string): Promise<FileEntry[]>;
  mkdir(path: string, recursive?: boolean): Promise<FileEntry>;
  rmdir(path: string, recursive?: boolean): Promise<void>;

  // File system operations
  rename(oldPath: string, newPath: string): Promise<FileEntry>;
  move(sourcePaths: string[], targetPath: string): Promise<void>;
  copy(sourcePath: string, targetPath: string): Promise<FileEntry>;

  // Watch operations
  watch(pattern: string, callback: (event: FSEvent) => void): Disposable;

  // Utility operations
  stat(path: string): Promise<FileStat>;
  glob(pattern: string): Promise<string[]>;

  // Storage management
  clear(): Promise<void>;
  size(): Promise<number>;

  // Permission checking
  /**
   * Verifica se o caminho pode ser modificado (escrita/delete)
   * @returns true se permitido, false se readonly ou sem permissão
   */
  canModify(path: string): Promise<boolean>;

  /**
   * Verifica se pode criar arquivos no diretório
   * @returns true se permitido, false se readonly ou sem permissão
   */
  canCreateIn(parentPath: string): Promise<boolean>;

  // Atomic operations
  /**
   * Escreve arquivo de forma atômica (write to temp + rename)
   * Fallback para writeFile normal se não suportado
   */
  writeFileAtomic?(
    path: string,
    content: any,
    metadata?: FileMetadata,
  ): Promise<FileEntry>;

  /**
   * Retorna as capacidades deste file system
   */
  readonly capabilities?: IFileSystemCapabilities;
}