smartfs/ts/interfaces/mod.provider.ts

/**
 * Provider interface for SmartFS
 * All filesystem backends must implement this interface
 */

import type {
  IFileStats,
  IDirectoryEntry,
  IWatchEvent,
  IReadOptions,
  IWriteOptions,
  IStreamOptions,
  ICopyOptions,
  IListOptions,
  IWatchOptions,
  ITransactionOperation,
} from './mod.types.js';

/**
 * Provider capabilities interface
 */
export interface IProviderCapabilities {
  /**
   * Supports file watching
   */
  supportsWatch: boolean;

  /**
   * Supports atomic writes
   */
  supportsAtomic: boolean;

  /**
   * Supports transactions
   */
  supportsTransactions: boolean;

  /**
   * Supports streaming
   */
  supportsStreaming: boolean;

  /**
   * Supports symbolic links
   */
  supportsSymlinks: boolean;

  /**
   * Supports file permissions
   */
  supportsPermissions: boolean;
}

/**
 * Watch callback type
 */
export type TWatchCallback = (event: IWatchEvent) => void | Promise<void>;

/**
 * Watcher handle interface
 */
export interface IWatcherHandle {
  /**
   * Stop watching
   */
  stop(): Promise<void>;
}

/**
 * Base provider interface that all filesystem backends must implement
 */
export interface ISmartFsProvider {
  /**
   * Provider name (e.g., 'node', 'memory', 's3')
   */
  readonly name: string;

  /**
   * Provider capabilities
   */
  readonly capabilities: IProviderCapabilities;

  // --- File Operations ---

  /**
   * Read a file
   */
  readFile(path: string, options?: IReadOptions): Promise<Buffer | string>;

  /**
   * Write a file
   */
  writeFile(path: string, content: string | Buffer, options?: IWriteOptions): Promise<void>;

  /**
   * Append to a file
   */
  appendFile(path: string, content: string | Buffer, options?: IWriteOptions): Promise<void>;

  /**
   * Delete a file
   */
  deleteFile(path: string): Promise<void>;

  /**
   * Copy a file
   */
  copyFile(from: string, to: string, options?: ICopyOptions): Promise<void>;

  /**
   * Move a file
   */
  moveFile(from: string, to: string, options?: ICopyOptions): Promise<void>;

  /**
   * Check if a file exists
   */
  fileExists(path: string): Promise<boolean>;

  /**
   * Get file statistics
   */
  fileStat(path: string): Promise<IFileStats>;

  /**
   * Create a readable stream
   */
  createReadStream(path: string, options?: IStreamOptions): Promise<ReadableStream<Uint8Array>>;

  /**
   * Create a writable stream
   */
  createWriteStream(path: string, options?: IStreamOptions): Promise<WritableStream<Uint8Array>>;

  // --- Directory Operations ---

  /**
   * List directory contents
   */
  listDirectory(path: string, options?: IListOptions): Promise<IDirectoryEntry[]>;

  /**
   * Create a directory
   */
  createDirectory(path: string, options?: { recursive?: boolean; mode?: number }): Promise<void>;

  /**
   * Delete a directory
   */
  deleteDirectory(path: string, options?: { recursive?: boolean }): Promise<void>;

  /**
   * Check if a directory exists
   */
  directoryExists(path: string): Promise<boolean>;

  /**
   * Get directory statistics
   */
  directoryStat(path: string): Promise<IFileStats>;

  // --- Watch Operations ---

  /**
   * Watch a path for changes
   * Returns a handle to stop watching
   */
  watch(path: string, callback: TWatchCallback, options?: IWatchOptions): Promise<IWatcherHandle>;

  // --- Transaction Operations ---

  /**
   * Execute a transaction
   * Providers should implement this to support atomic multi-file operations
   * If not supported, should execute operations sequentially
   */
  executeTransaction(operations: ITransactionOperation[]): Promise<void>;

  /**
   * Prepare a transaction (create backups for rollback)
   * Returns prepared operations with backup data
   */
  prepareTransaction(operations: ITransactionOperation[]): Promise<ITransactionOperation[]>;

  /**
   * Rollback a transaction using backup data
   */
  rollbackTransaction(operations: ITransactionOperation[]): Promise<void>;

  // --- Path Operations ---

  /**
   * Normalize a path according to the provider's conventions
   */
  normalizePath(path: string): string;

  /**
   * Join path segments
   */
  joinPath(...segments: string[]): string;
}