initial

ts/interfaces/mod.provider.ts

@@ -0,0 +1,201 @@
+/**
+ * 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;
+}