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;
+}

ts/interfaces/mod.types.ts

@@ -0,0 +1,217 @@
+/**
+ * Core type definitions for SmartFS
+ */
+
+/**
+ * File encoding types
+ */
+export type TEncoding = 'utf8' | 'utf-8' | 'ascii' | 'base64' | 'hex' | 'binary' | 'buffer';
+
+/**
+ * File mode (permissions)
+ */
+export type TFileMode = number;
+
+/**
+ * File statistics interface
+ */
+export interface IFileStats {
+  /**
+   * File size in bytes
+   */
+  size: number;
+
+  /**
+   * Creation time
+   */
+  birthtime: Date;
+
+  /**
+   * Last modification time
+   */
+  mtime: Date;
+
+  /**
+   * Last access time
+   */
+  atime: Date;
+
+  /**
+   * Is this a file?
+   */
+  isFile: boolean;
+
+  /**
+   * Is this a directory?
+   */
+  isDirectory: boolean;
+
+  /**
+   * Is this a symbolic link?
+   */
+  isSymbolicLink: boolean;
+
+  /**
+   * File permissions/mode
+   */
+  mode: number;
+}
+
+/**
+ * Directory entry interface
+ */
+export interface IDirectoryEntry {
+  /**
+   * Entry name (filename or directory name)
+   */
+  name: string;
+
+  /**
+   * Full path to the entry
+   */
+  path: string;
+
+  /**
+   * Is this entry a file?
+   */
+  isFile: boolean;
+
+  /**
+   * Is this entry a directory?
+   */
+  isDirectory: boolean;
+
+  /**
+   * Is this entry a symbolic link?
+   */
+  isSymbolicLink: boolean;
+
+  /**
+   * File statistics
+   */
+  stats?: IFileStats;
+}
+
+/**
+ * Watch event types
+ */
+export type TWatchEventType = 'add' | 'change' | 'delete';
+
+/**
+ * Watch event interface
+ */
+export interface IWatchEvent {
+  /**
+   * Event type
+   */
+  type: TWatchEventType;
+
+  /**
+   * Path that triggered the event
+   */
+  path: string;
+
+  /**
+   * Timestamp of the event
+   */
+  timestamp: Date;
+
+  /**
+   * File statistics (if available)
+   */
+  stats?: IFileStats;
+}
+
+/**
+ * Transaction operation types
+ */
+export type TTransactionOperationType = 'write' | 'delete' | 'copy' | 'move' | 'append';
+
+/**
+ * Transaction operation interface
+ */
+export interface ITransactionOperation {
+  /**
+   * Operation type
+   */
+  type: TTransactionOperationType;
+
+  /**
+   * Source path
+   */
+  path: string;
+
+  /**
+   * Target path (for copy/move operations)
+   */
+  targetPath?: string;
+
+  /**
+   * Content to write (for write/append operations)
+   */
+  content?: string | Buffer;
+
+  /**
+   * Encoding (for write/append operations)
+   */
+  encoding?: TEncoding;
+
+  /**
+   * Backup data for rollback
+   */
+  backup?: {
+    existed: boolean;
+    content?: Buffer;
+    stats?: IFileStats;
+  };
+}
+
+/**
+ * Read options interface
+ */
+export interface IReadOptions {
+  encoding?: TEncoding;
+}
+
+/**
+ * Write options interface
+ */
+export interface IWriteOptions {
+  encoding?: TEncoding;
+  mode?: TFileMode;
+  atomic?: boolean;
+}
+
+/**
+ * Stream options interface
+ */
+export interface IStreamOptions {
+  chunkSize?: number;
+  highWaterMark?: number;
+}
+
+/**
+ * Copy/Move options interface
+ */
+export interface ICopyOptions {
+  preserveTimestamps?: boolean;
+  overwrite?: boolean;
+}
+
+/**
+ * List options interface
+ */
+export interface IListOptions {
+  recursive?: boolean;
+  filter?: string | RegExp | ((entry: IDirectoryEntry) => boolean);
+  includeStats?: boolean;
+}
+
+/**
+ * Watch options interface
+ */
+export interface IWatchOptions {
+  recursive?: boolean;
+  filter?: string | RegExp | ((path: string) => boolean);
+  debounce?: number;
+}