initial

ts/classes/smartfs.directory.ts

@@ -0,0 +1,139 @@
+/**
+ * Directory builder for fluent directory operations
+ */
+
+import type { ISmartFsProvider } from '../interfaces/mod.provider.js';
+import type {
+  TFileMode,
+  IFileStats,
+  IDirectoryEntry,
+  IListOptions,
+} from '../interfaces/mod.types.js';
+
+/**
+ * Directory builder class for fluent directory operations
+ * Configuration methods return `this` for chaining
+ * Action methods return Promises for execution
+ */
+export class SmartFsDirectory {
+  private provider: ISmartFsProvider;
+  private path: string;
+
+  // Configuration options
+  private options: {
+    recursive?: boolean;
+    mode?: TFileMode;
+    filter?: string | RegExp | ((entry: IDirectoryEntry) => boolean);
+    includeStats?: boolean;
+  } = {};
+
+  constructor(provider: ISmartFsProvider, path: string) {
+    this.provider = provider;
+    this.path = this.provider.normalizePath(path);
+  }
+
+  // --- Configuration Methods (return this for chaining) ---
+
+  /**
+   * Enable recursive operations (for list, create, delete)
+   */
+  public recursive(): this {
+    this.options.recursive = true;
+    return this;
+  }
+
+  /**
+   * Set directory permissions/mode
+   * @param mode - Directory mode (e.g., 0o755)
+   */
+  public mode(mode: TFileMode): this {
+    this.options.mode = mode;
+    return this;
+  }
+
+  /**
+   * Filter directory entries
+   * @param filter - String pattern, RegExp, or filter function
+   *
+   * @example
+   * ```typescript
+   * // String pattern (glob-like)
+   * .filter('*.ts')
+   *
+   * // RegExp
+   * .filter(/\.ts$/)
+   *
+   * // Function
+   * .filter(entry => entry.isFile && entry.name.endsWith('.ts'))
+   * ```
+   */
+  public filter(filter: string | RegExp | ((entry: IDirectoryEntry) => boolean)): this {
+    this.options.filter = filter;
+    return this;
+  }
+
+  /**
+   * Include file statistics in directory listings
+   */
+  public includeStats(): this {
+    this.options.includeStats = true;
+    return this;
+  }
+
+  // --- Action Methods (return Promises) ---
+
+  /**
+   * List directory contents
+   * @returns Array of directory entries
+   */
+  public async list(): Promise<IDirectoryEntry[]> {
+    const listOptions: IListOptions = {
+      recursive: this.options.recursive,
+      filter: this.options.filter,
+      includeStats: this.options.includeStats,
+    };
+    return this.provider.listDirectory(this.path, listOptions);
+  }
+
+  /**
+   * Create the directory
+   */
+  public async create(): Promise<void> {
+    return this.provider.createDirectory(this.path, {
+      recursive: this.options.recursive,
+      mode: this.options.mode,
+    });
+  }
+
+  /**
+   * Delete the directory
+   */
+  public async delete(): Promise<void> {
+    return this.provider.deleteDirectory(this.path, {
+      recursive: this.options.recursive,
+    });
+  }
+
+  /**
+   * Check if the directory exists
+   * @returns True if directory exists
+   */
+  public async exists(): Promise<boolean> {
+    return this.provider.directoryExists(this.path);
+  }
+
+  /**
+   * Get directory statistics
+   * @returns Directory stats
+   */
+  public async stat(): Promise<IFileStats> {
+    return this.provider.directoryStat(this.path);
+  }
+
+  /**
+   * Get the directory path
+   */
+  public getPath(): string {
+    return this.path;
+  }
+}

ts/classes/smartfs.file.ts

@@ -0,0 +1,209 @@
+/**
+ * File builder for fluent file operations
+ */
+
+import type { ISmartFsProvider } from '../interfaces/mod.provider.js';
+import type {
+  TEncoding,
+  TFileMode,
+  IFileStats,
+  IReadOptions,
+  IWriteOptions,
+  IStreamOptions,
+  ICopyOptions,
+} from '../interfaces/mod.types.js';
+
+/**
+ * File builder class for fluent file operations
+ * Configuration methods return `this` for chaining
+ * Action methods return Promises for execution
+ */
+export class SmartFsFile {
+  private provider: ISmartFsProvider;
+  private path: string;
+
+  // Configuration options
+  private options: {
+    encoding?: TEncoding;
+    mode?: TFileMode;
+    atomic?: boolean;
+    chunkSize?: number;
+    preserveTimestamps?: boolean;
+    overwrite?: boolean;
+  } = {};
+
+  constructor(provider: ISmartFsProvider, path: string) {
+    this.provider = provider;
+    this.path = this.provider.normalizePath(path);
+  }
+
+  // --- Configuration Methods (return this for chaining) ---
+
+  /**
+   * Set encoding for read/write operations
+   * @param encoding - File encoding
+   */
+  public encoding(encoding: TEncoding): this {
+    this.options.encoding = encoding;
+    return this;
+  }
+
+  /**
+   * Set file permissions/mode
+   * @param mode - File mode (e.g., 0o644)
+   */
+  public mode(mode: TFileMode): this {
+    this.options.mode = mode;
+    return this;
+  }
+
+  /**
+   * Enable atomic write operations
+   * Writes to a temporary file first, then renames
+   */
+  public atomic(): this {
+    this.options.atomic = true;
+    return this;
+  }
+
+  /**
+   * Set chunk size for streaming operations
+   * @param size - Chunk size in bytes
+   */
+  public chunkSize(size: number): this {
+    this.options.chunkSize = size;
+    return this;
+  }
+
+  /**
+   * Preserve timestamps when copying/moving
+   */
+  public preserveTimestamps(): this {
+    this.options.preserveTimestamps = true;
+    return this;
+  }
+
+  /**
+   * Allow overwriting existing files
+   */
+  public overwrite(): this {
+    this.options.overwrite = true;
+    return this;
+  }
+
+  // --- Action Methods (return Promises) ---
+
+  /**
+   * Read the file
+   * @returns File content as Buffer or string (if encoding is set)
+   */
+  public async read(): Promise<Buffer | string> {
+    const readOptions: IReadOptions = {
+      encoding: this.options.encoding,
+    };
+    return this.provider.readFile(this.path, readOptions);
+  }
+
+  /**
+   * Write content to the file
+   * @param content - Content to write
+   */
+  public async write(content: string | Buffer): Promise<void> {
+    const writeOptions: IWriteOptions = {
+      encoding: this.options.encoding,
+      mode: this.options.mode,
+      atomic: this.options.atomic,
+    };
+    return this.provider.writeFile(this.path, content, writeOptions);
+  }
+
+  /**
+   * Append content to the file
+   * @param content - Content to append
+   */
+  public async append(content: string | Buffer): Promise<void> {
+    const writeOptions: IWriteOptions = {
+      encoding: this.options.encoding,
+      mode: this.options.mode,
+    };
+    return this.provider.appendFile(this.path, content, writeOptions);
+  }
+
+  /**
+   * Get a readable stream for the file
+   * @returns ReadableStream of Uint8Array
+   */
+  public async readStream(): Promise<ReadableStream<Uint8Array>> {
+    const streamOptions: IStreamOptions = {
+      chunkSize: this.options.chunkSize,
+    };
+    return this.provider.createReadStream(this.path, streamOptions);
+  }
+
+  /**
+   * Get a writable stream for the file
+   * @returns WritableStream of Uint8Array
+   */
+  public async writeStream(): Promise<WritableStream<Uint8Array>> {
+    const streamOptions: IStreamOptions = {
+      chunkSize: this.options.chunkSize,
+    };
+    return this.provider.createWriteStream(this.path, streamOptions);
+  }
+
+  /**
+   * Copy the file to a new location
+   * @param targetPath - Destination path
+   */
+  public async copy(targetPath: string): Promise<void> {
+    const normalizedTarget = this.provider.normalizePath(targetPath);
+    const copyOptions: ICopyOptions = {
+      preserveTimestamps: this.options.preserveTimestamps,
+      overwrite: this.options.overwrite,
+    };
+    return this.provider.copyFile(this.path, normalizedTarget, copyOptions);
+  }
+
+  /**
+   * Move the file to a new location
+   * @param targetPath - Destination path
+   */
+  public async move(targetPath: string): Promise<void> {
+    const normalizedTarget = this.provider.normalizePath(targetPath);
+    const copyOptions: ICopyOptions = {
+      preserveTimestamps: this.options.preserveTimestamps,
+      overwrite: this.options.overwrite,
+    };
+    return this.provider.moveFile(this.path, normalizedTarget, copyOptions);
+  }
+
+  /**
+   * Delete the file
+   */
+  public async delete(): Promise<void> {
+    return this.provider.deleteFile(this.path);
+  }
+
+  /**
+   * Check if the file exists
+   * @returns True if file exists
+   */
+  public async exists(): Promise<boolean> {
+    return this.provider.fileExists(this.path);
+  }
+
+  /**
+   * Get file statistics
+   * @returns File stats
+   */
+  public async stat(): Promise<IFileStats> {
+    return this.provider.fileStat(this.path);
+  }
+
+  /**
+   * Get the file path
+   */
+  public getPath(): string {
+    return this.path;
+  }
+}

ts/classes/smartfs.transaction.ts

@@ -0,0 +1,207 @@
+/**
+ * Transaction builder for atomic multi-file operations
+ */
+
+import type { ISmartFsProvider } from '../interfaces/mod.provider.js';
+import type { ITransactionOperation, TEncoding } from '../interfaces/mod.types.js';
+
+/**
+ * Transaction file operation builder
+ * Allows chaining file operations within a transaction
+ */
+class TransactionFileBuilder {
+  constructor(
+    private transaction: SmartFsTransaction,
+    private path: string,
+  ) {}
+
+  /**
+   * Write content to the file in this transaction
+   * @param content - Content to write
+   * @param encoding - Optional encoding
+   */
+  public write(content: string | Buffer, encoding?: TEncoding): SmartFsTransaction {
+    this.transaction.addOperation({
+      type: 'write',
+      path: this.path,
+      content,
+      encoding,
+    });
+    return this.transaction;
+  }
+
+  /**
+   * Append content to the file in this transaction
+   * @param content - Content to append
+   * @param encoding - Optional encoding
+   */
+  public append(content: string | Buffer, encoding?: TEncoding): SmartFsTransaction {
+    this.transaction.addOperation({
+      type: 'append',
+      path: this.path,
+      content,
+      encoding,
+    });
+    return this.transaction;
+  }
+
+  /**
+   * Delete the file in this transaction
+   */
+  public delete(): SmartFsTransaction {
+    this.transaction.addOperation({
+      type: 'delete',
+      path: this.path,
+    });
+    return this.transaction;
+  }
+
+  /**
+   * Copy the file to a new location in this transaction
+   * @param targetPath - Destination path
+   */
+  public copy(targetPath: string): SmartFsTransaction {
+    this.transaction.addOperation({
+      type: 'copy',
+      path: this.path,
+      targetPath,
+    });
+    return this.transaction;
+  }
+
+  /**
+   * Move the file to a new location in this transaction
+   * @param targetPath - Destination path
+   */
+  public move(targetPath: string): SmartFsTransaction {
+    this.transaction.addOperation({
+      type: 'move',
+      path: this.path,
+      targetPath,
+    });
+    return this.transaction;
+  }
+}
+
+/**
+ * Transaction builder class for atomic multi-file operations
+ * Build up a set of operations, then commit atomically
+ * Supports rollback on failure
+ */
+export class SmartFsTransaction {
+  private provider: ISmartFsProvider;
+  private operations: ITransactionOperation[] = [];
+  private committed = false;
+  private rolledBack = false;
+
+  constructor(provider: ISmartFsProvider) {
+    this.provider = provider;
+  }
+
+  /**
+   * Add a file operation to the transaction
+   * @param path - Path to the file
+   * @returns TransactionFileBuilder for chaining operations
+   *
+   * @example
+   * ```typescript
+   * await fs.transaction()
+   *   .file('/file1.txt').write('content1')
+   *   .file('/file2.txt').delete()
+   *   .commit()
+   * ```
+   */
+  public file(path: string): TransactionFileBuilder {
+    const normalizedPath = this.provider.normalizePath(path);
+    return new TransactionFileBuilder(this, normalizedPath);
+  }
+
+  /**
+   * Add an operation to the transaction (internal)
+   */
+  public addOperation(operation: ITransactionOperation): void {
+    if (this.committed) {
+      throw new Error('Cannot add operations to a committed transaction');
+    }
+    if (this.rolledBack) {
+      throw new Error('Cannot add operations to a rolled back transaction');
+    }
+    this.operations.push(operation);
+  }
+
+  /**
+   * Commit the transaction
+   * All operations are executed atomically
+   * If any operation fails, all operations are rolled back
+   */
+  public async commit(): Promise<void> {
+    if (this.committed) {
+      throw new Error('Transaction already committed');
+    }
+    if (this.rolledBack) {
+      throw new Error('Cannot commit a rolled back transaction');
+    }
+
+    if (this.operations.length === 0) {
+      this.committed = true;
+      return;
+    }
+
+    try {
+      // Prepare transaction (create backups for rollback)
+      const preparedOperations = await this.provider.prepareTransaction(this.operations);
+      this.operations = preparedOperations;
+
+      // Execute the transaction
+      await this.provider.executeTransaction(this.operations);
+
+      this.committed = true;
+    } catch (error) {
+      // Rollback on error
+      await this.rollback();
+      throw error;
+    }
+  }
+
+  /**
+   * Rollback the transaction
+   * Reverts all operations that have been executed
+   */
+  public async rollback(): Promise<void> {
+    if (this.committed) {
+      throw new Error('Cannot rollback a committed transaction');
+    }
+    if (this.rolledBack) {
+      throw new Error('Transaction already rolled back');
+    }
+
+    if (this.operations.length === 0) {
+      this.rolledBack = true;
+      return;
+    }
+
+    await this.provider.rollbackTransaction(this.operations);
+    this.rolledBack = true;
+  }
+
+  /**
+   * Get all operations in the transaction
+   */
+  public getOperations(): readonly ITransactionOperation[] {
+    return this.operations;
+  }
+
+  /**
+   * Check if the transaction has been committed
+   */
+  public isCommitted(): boolean {
+    return this.committed;
+  }
+
+  /**
+   * Check if the transaction has been rolled back
+   */
+  public isRolledBack(): boolean {
+    return this.rolledBack;
+  }
+}

ts/classes/smartfs.ts

@@ -0,0 +1,108 @@
+/**
+ * SmartFS - Modern pluggable filesystem module
+ * Main entry point for filesystem operations
+ */
+
+import type { ISmartFsProvider } from '../interfaces/mod.provider.js';
+import { SmartFsFile } from './smartfs.file.js';
+import { SmartFsDirectory } from './smartfs.directory.js';
+import { SmartFsTransaction } from './smartfs.transaction.js';
+import { SmartFsWatcher } from './smartfs.watcher.js';
+
+/**
+ * SmartFS main class
+ * Creates builder instances for fluent filesystem operations
+ */
+export class SmartFs {
+  /**
+   * The filesystem provider
+   */
+  public provider: ISmartFsProvider;
+
+  /**
+   * Create a new SmartFS instance with a provider
+   * @param provider - Filesystem provider to use
+   */
+  constructor(provider: ISmartFsProvider) {
+    this.provider = provider;
+  }
+
+  /**
+   * Create a file builder for fluent file operations
+   * @param path - Path to the file
+   * @returns FileBuilder instance
+   *
+   * @example
+   * ```typescript
+   * const content = await fs.file('/path/to/file.txt')
+   *   .encoding('utf8')
+   *   .read()
+   * ```
+   */
+  public file(path: string): SmartFsFile {
+    return new SmartFsFile(this.provider, path);
+  }
+
+  /**
+   * Create a directory builder for fluent directory operations
+   * @param path - Path to the directory
+   * @returns DirectoryBuilder instance
+   *
+   * @example
+   * ```typescript
+   * const files = await fs.directory('/path')
+   *   .recursive()
+   *   .list()
+   * ```
+   */
+  public directory(path: string): SmartFsDirectory {
+    return new SmartFsDirectory(this.provider, path);
+  }
+
+  /**
+   * Create a transaction builder for atomic multi-file operations
+   * @returns TransactionBuilder instance
+   *
+   * @example
+   * ```typescript
+   * await fs.transaction()
+   *   .file('/file1.txt').write('content1')
+   *   .file('/file2.txt').delete()
+   *   .commit()
+   * ```
+   */
+  public transaction(): SmartFsTransaction {
+    return new SmartFsTransaction(this.provider);
+  }
+
+  /**
+   * Create a watcher builder for file system watching
+   * @param path - Path to watch
+   * @returns WatcherBuilder instance
+   *
+   * @example
+   * ```typescript
+   * const watcher = await fs.watch('/path')
+   *   .recursive()
+   *   .onChange(event => console.log(event))
+   *   .start()
+   * ```
+   */
+  public watch(path: string): SmartFsWatcher {
+    return new SmartFsWatcher(this.provider, path);
+  }
+
+  /**
+   * Get provider capabilities
+   */
+  public getCapabilities() {
+    return this.provider.capabilities;
+  }
+
+  /**
+   * Get provider name
+   */
+  public getProviderName(): string {
+    return this.provider.name;
+  }
+}

ts/classes/smartfs.watcher.ts

@@ -0,0 +1,229 @@
+/**
+ * Watcher builder for file system watching
+ */
+
+import type { ISmartFsProvider, IWatcherHandle } from '../interfaces/mod.provider.js';
+import type { IWatchEvent, IWatchOptions, TWatchEventType } from '../interfaces/mod.types.js';
+
+/**
+ * Event handler type
+ */
+type TEventHandler = (event: IWatchEvent) => void | Promise<void>;
+
+/**
+ * Active watcher handle that allows stopping the watcher
+ */
+export class SmartFsActiveWatcher {
+  constructor(private handle: IWatcherHandle) {}
+
+  /**
+   * Stop watching for file system changes
+   */
+  public async stop(): Promise<void> {
+    return this.handle.stop();
+  }
+}
+
+/**
+ * Watcher builder class for file system watching
+ * Configuration methods return `this` for chaining
+ * Call `.start()` to begin watching
+ */
+export class SmartFsWatcher {
+  private provider: ISmartFsProvider;
+  private path: string;
+
+  // Configuration options
+  private options: {
+    recursive?: boolean;
+    filter?: string | RegExp | ((path: string) => boolean);
+    debounce?: number;
+  } = {};
+
+  // Event handlers
+  private handlers: {
+    change?: TEventHandler[];
+    add?: TEventHandler[];
+    delete?: TEventHandler[];
+    all?: TEventHandler[];
+  } = {};
+
+  // Debounce state
+  private debounceTimers: Map<string, NodeJS.Timeout> = new Map();
+
+  constructor(provider: ISmartFsProvider, path: string) {
+    this.provider = provider;
+    this.path = this.provider.normalizePath(path);
+
+    if (!this.provider.capabilities.supportsWatch) {
+      throw new Error(`Provider '${this.provider.name}' does not support file watching`);
+    }
+  }
+
+  // --- Configuration Methods (return this for chaining) ---
+
+  /**
+   * Enable recursive watching (watch subdirectories)
+   */
+  public recursive(): this {
+    this.options.recursive = true;
+    return this;
+  }
+
+  /**
+   * Filter watched paths
+   * @param filter - String pattern, RegExp, or filter function
+   *
+   * @example
+   * ```typescript
+   * // String pattern (glob-like)
+   * .filter('*.ts')
+   *
+   * // RegExp
+   * .filter(/\.ts$/)
+   *
+   * // Function
+   * .filter(path => path.endsWith('.ts'))
+   * ```
+   */
+  public filter(filter: string | RegExp | ((path: string) => boolean)): this {
+    this.options.filter = filter;
+    return this;
+  }
+
+  /**
+   * Debounce events (wait N milliseconds before firing)
+   * Useful for avoiding rapid-fire events
+   * @param ms - Debounce delay in milliseconds
+   */
+  public debounce(ms: number): this {
+    this.options.debounce = ms;
+    return this;
+  }
+
+  // --- Event Handler Registration (return this for chaining) ---
+
+  /**
+   * Register handler for 'change' events (file modified)
+   * @param handler - Event handler function
+   */
+  public onChange(handler: TEventHandler): this {
+    if (!this.handlers.change) {
+      this.handlers.change = [];
+    }
+    this.handlers.change.push(handler);
+    return this;
+  }
+
+  /**
+   * Register handler for 'add' events (file created)
+   * @param handler - Event handler function
+   */
+  public onAdd(handler: TEventHandler): this {
+    if (!this.handlers.add) {
+      this.handlers.add = [];
+    }
+    this.handlers.add.push(handler);
+    return this;
+  }
+
+  /**
+   * Register handler for 'delete' events (file deleted)
+   * @param handler - Event handler function
+   */
+  public onDelete(handler: TEventHandler): this {
+    if (!this.handlers.delete) {
+      this.handlers.delete = [];
+    }
+    this.handlers.delete.push(handler);
+    return this;
+  }
+
+  /**
+   * Register handler for all events
+   * @param handler - Event handler function
+   */
+  public onAll(handler: TEventHandler): this {
+    if (!this.handlers.all) {
+      this.handlers.all = [];
+    }
+    this.handlers.all.push(handler);
+    return this;
+  }
+
+  // --- Action Method ---
+
+  /**
+   * Start watching for file system changes
+   * @returns Active watcher handle that can be stopped
+   */
+  public async start(): Promise<SmartFsActiveWatcher> {
+    const watchOptions: IWatchOptions = {
+      recursive: this.options.recursive,
+      filter: this.options.filter,
+      debounce: this.options.debounce,
+    };
+
+    // Create the callback that dispatches to handlers
+    const callback = async (event: IWatchEvent) => {
+      await this.handleEvent(event);
+    };
+
+    const handle = await this.provider.watch(this.path, callback, watchOptions);
+    return new SmartFsActiveWatcher(handle);
+  }
+
+  /**
+   * Handle incoming watch events (internal)
+   */
+  private async handleEvent(event: IWatchEvent): Promise<void> {
+    // Apply debouncing if configured
+    if (this.options.debounce && this.options.debounce > 0) {
+      const key = `${event.type}:${event.path}`;
+
+      // Clear existing timer
+      const existingTimer = this.debounceTimers.get(key);
+      if (existingTimer) {
+        clearTimeout(existingTimer);
+      }
+
+      // Set new timer
+      const timer = setTimeout(async () => {
+        this.debounceTimers.delete(key);
+        await this.dispatchEvent(event);
+      }, this.options.debounce);
+
+      this.debounceTimers.set(key, timer);
+    } else {
+      // No debouncing, dispatch immediately
+      await this.dispatchEvent(event);
+    }
+  }
+
+  /**
+   * Dispatch event to registered handlers (internal)
+   */
+  private async dispatchEvent(event: IWatchEvent): Promise<void> {
+    // Dispatch to type-specific handlers
+    const typeHandlers = this.handlers[event.type];
+    if (typeHandlers) {
+      for (const handler of typeHandlers) {
+        await handler(event);
+      }
+    }
+
+    // Dispatch to 'all' handlers
+    if (this.handlers.all) {
+      for (const handler of this.handlers.all) {
+        await handler(event);
+      }
+    }
+  }
+
+  /**
+   * Get the watched path
+   */
+  public getPath(): string {
+    return this.path;
+  }
+}

ts/index.ts

@@ -0,0 +1,40 @@
+/**
+ * SmartFS - Modern pluggable filesystem module
+ * @packageDocumentation
+ */
+
+// Main classes
+export { SmartFs } from './classes/smartfs.js';
+export { SmartFsFile } from './classes/smartfs.file.js';
+export { SmartFsDirectory } from './classes/smartfs.directory.js';
+export { SmartFsTransaction } from './classes/smartfs.transaction.js';
+export { SmartFsWatcher, SmartFsActiveWatcher } from './classes/smartfs.watcher.js';
+
+// Providers
+export { SmartFsProviderNode } from './providers/smartfs.provider.node.js';
+export { SmartFsProviderMemory } from './providers/smartfs.provider.memory.js';
+
+// Interfaces and Types
+export type {
+  ISmartFsProvider,
+  IProviderCapabilities,
+  TWatchCallback,
+  IWatcherHandle,
+} from './interfaces/mod.provider.js';
+
+export type {
+  TEncoding,
+  TFileMode,
+  IFileStats,
+  IDirectoryEntry,
+  TWatchEventType,
+  IWatchEvent,
+  TTransactionOperationType,
+  ITransactionOperation,
+  IReadOptions,
+  IWriteOptions,
+  IStreamOptions,
+  ICopyOptions,
+  IListOptions,
+  IWatchOptions,
+} from './interfaces/mod.types.js';

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

ts/paths.ts

@@ -0,0 +1,5 @@
+import * as plugins from './smartfs.plugins.js';
+export const packageDir = plugins.path.join(
+  plugins.smartpath.get.dirnameFromImportMetaUrl(import.meta.url),
+  '../',
+);

ts/providers/smartfs.provider.memory.ts

@@ -0,0 +1,642 @@
+/**
+ * In-memory filesystem provider for SmartFS
+ * Perfect for testing and temporary storage
+ */
+
+import type {
+  ISmartFsProvider,
+  IProviderCapabilities,
+  TWatchCallback,
+  IWatcherHandle,
+} from '../interfaces/mod.provider.js';
+
+import type {
+  IFileStats,
+  IDirectoryEntry,
+  IReadOptions,
+  IWriteOptions,
+  IStreamOptions,
+  ICopyOptions,
+  IListOptions,
+  IWatchOptions,
+  ITransactionOperation,
+  IWatchEvent,
+  TWatchEventType,
+} from '../interfaces/mod.types.js';
+
+/**
+ * In-memory file entry
+ */
+interface IMemoryEntry {
+  type: 'file' | 'directory';
+  content?: Buffer;
+  created: Date;
+  modified: Date;
+  accessed: Date;
+  mode: number;
+}
+
+/**
+ * Watcher registration
+ */
+interface IWatcherRegistration {
+  path: string;
+  callback: TWatchCallback;
+  options?: IWatchOptions;
+}
+
+/**
+ * In-memory filesystem provider
+ */
+export class SmartFsProviderMemory implements ISmartFsProvider {
+  public readonly name = 'memory';
+
+  public readonly capabilities: IProviderCapabilities = {
+    supportsWatch: true,
+    supportsAtomic: true,
+    supportsTransactions: true,
+    supportsStreaming: true,
+    supportsSymlinks: false, // Not implemented yet
+    supportsPermissions: true,
+  };
+
+  private storage: Map<string, IMemoryEntry> = new Map();
+  private watchers: Map<string, IWatcherRegistration> = new Map();
+  private nextWatcherId = 1;
+
+  constructor() {
+    // Create root directory
+    this.storage.set('/', {
+      type: 'directory',
+      created: new Date(),
+      modified: new Date(),
+      accessed: new Date(),
+      mode: 0o755,
+    });
+  }
+
+  // --- File Operations ---
+
+  public async readFile(path: string, options?: IReadOptions): Promise<Buffer | string> {
+    const entry = this.storage.get(path);
+
+    if (!entry) {
+      throw new Error(`ENOENT: no such file or directory, open '${path}'`);
+    }
+
+    if (entry.type !== 'file') {
+      throw new Error(`EISDIR: illegal operation on a directory, read '${path}'`);
+    }
+
+    entry.accessed = new Date();
+
+    if (!entry.content) {
+      return options?.encoding ? '' : Buffer.alloc(0);
+    }
+
+    if (options?.encoding && options.encoding !== 'buffer') {
+      return entry.content.toString(options.encoding as BufferEncoding);
+    }
+
+    return entry.content;
+  }
+
+  public async writeFile(path: string, content: string | Buffer, options?: IWriteOptions): Promise<void> {
+    const buffer = Buffer.isBuffer(content) ? content : Buffer.from(content, options?.encoding as BufferEncoding);
+
+    // Ensure parent directory exists
+    await this.ensureParentDirectory(path);
+
+    const now = new Date();
+    const entry = this.storage.get(path);
+
+    if (entry && entry.type === 'directory') {
+      throw new Error(`EISDIR: illegal operation on a directory, open '${path}'`);
+    }
+
+    this.storage.set(path, {
+      type: 'file',
+      content: buffer,
+      created: entry?.created || now,
+      modified: now,
+      accessed: now,
+      mode: options?.mode || 0o644,
+    });
+
+    await this.emitWatchEvent(path, entry ? 'change' : 'add');
+  }
+
+  public async appendFile(path: string, content: string | Buffer, options?: IWriteOptions): Promise<void> {
+    const buffer = Buffer.isBuffer(content) ? content : Buffer.from(content, options?.encoding as BufferEncoding);
+
+    const entry = this.storage.get(path);
+
+    if (entry && entry.type === 'directory') {
+      throw new Error(`EISDIR: illegal operation on a directory, open '${path}'`);
+    }
+
+    const existingContent = entry?.content || Buffer.alloc(0);
+    const newContent = Buffer.concat([existingContent, buffer]);
+
+    await this.writeFile(path, newContent, options);
+  }
+
+  public async deleteFile(path: string): Promise<void> {
+    const entry = this.storage.get(path);
+
+    if (!entry) {
+      throw new Error(`ENOENT: no such file or directory, unlink '${path}'`);
+    }
+
+    if (entry.type === 'directory') {
+      throw new Error(`EISDIR: illegal operation on a directory, unlink '${path}'`);
+    }
+
+    this.storage.delete(path);
+    await this.emitWatchEvent(path, 'delete');
+  }
+
+  public async copyFile(from: string, to: string, options?: ICopyOptions): Promise<void> {
+    const fromEntry = this.storage.get(from);
+
+    if (!fromEntry) {
+      throw new Error(`ENOENT: no such file or directory, copyfile '${from}'`);
+    }
+
+    if (fromEntry.type !== 'file') {
+      throw new Error(`EISDIR: illegal operation on a directory, copyfile '${from}'`);
+    }
+
+    const toEntry = this.storage.get(to);
+    if (toEntry && !options?.overwrite) {
+      throw new Error(`EEXIST: file already exists, copyfile '${from}' -> '${to}'`);
+    }
+
+    const now = new Date();
+    this.storage.set(to, {
+      type: 'file',
+      content: fromEntry.content ? Buffer.from(fromEntry.content) : undefined,
+      created: now,
+      modified: options?.preserveTimestamps ? fromEntry.modified : now,
+      accessed: now,
+      mode: fromEntry.mode,
+    });
+
+    await this.emitWatchEvent(to, toEntry ? 'change' : 'add');
+  }
+
+  public async moveFile(from: string, to: string, options?: ICopyOptions): Promise<void> {
+    await this.copyFile(from, to, options);
+    await this.deleteFile(from);
+  }
+
+  public async fileExists(path: string): Promise<boolean> {
+    const entry = this.storage.get(path);
+    return entry !== undefined && entry.type === 'file';
+  }
+
+  public async fileStat(path: string): Promise<IFileStats> {
+    const entry = this.storage.get(path);
+
+    if (!entry) {
+      throw new Error(`ENOENT: no such file or directory, stat '${path}'`);
+    }
+
+    if (entry.type !== 'file') {
+      throw new Error(`EISDIR: illegal operation on a directory, stat '${path}'`);
+    }
+
+    return {
+      size: entry.content?.length || 0,
+      birthtime: entry.created,
+      mtime: entry.modified,
+      atime: entry.accessed,
+      isFile: true,
+      isDirectory: false,
+      isSymbolicLink: false,
+      mode: entry.mode,
+    };
+  }
+
+  public async createReadStream(path: string, options?: IStreamOptions): Promise<ReadableStream<Uint8Array>> {
+    const content = await this.readFile(path);
+    const buffer = Buffer.isBuffer(content) ? content : Buffer.from(content);
+    const chunkSize = options?.chunkSize || 64 * 1024;
+
+    let offset = 0;
+
+    return new ReadableStream({
+      pull(controller) {
+        if (offset >= buffer.length) {
+          controller.close();
+          return;
+        }
+
+        const end = Math.min(offset + chunkSize, buffer.length);
+        const chunk = buffer.subarray(offset, end);
+        controller.enqueue(new Uint8Array(chunk));
+        offset = end;
+      },
+    });
+  }
+
+  public async createWriteStream(path: string, options?: IStreamOptions): Promise<WritableStream<Uint8Array>> {
+    const chunks: Buffer[] = [];
+
+    return new WritableStream({
+      write: async (chunk) => {
+        chunks.push(Buffer.from(chunk));
+      },
+      close: async () => {
+        const content = Buffer.concat(chunks);
+        await this.writeFile(path, content);
+      },
+    });
+  }
+
+  // --- Directory Operations ---
+
+  public async listDirectory(path: string, options?: IListOptions): Promise<IDirectoryEntry[]> {
+    const entry = this.storage.get(path);
+
+    if (!entry) {
+      throw new Error(`ENOENT: no such file or directory, scandir '${path}'`);
+    }
+
+    if (entry.type !== 'directory') {
+      throw new Error(`ENOTDIR: not a directory, scandir '${path}'`);
+    }
+
+    const entries: IDirectoryEntry[] = [];
+    const normalizedPath = this.normalizePath(path);
+    const prefix = normalizedPath === '/' ? '/' : `${normalizedPath}/`;
+
+    for (const [entryPath, entryData] of this.storage.entries()) {
+      if (entryPath === normalizedPath) continue;
+
+      if (options?.recursive) {
+        // Recursive: include all descendants
+        if (entryPath.startsWith(prefix)) {
+          const relativePath = entryPath.slice(prefix.length);
+          const name = relativePath.split('/').pop()!;
+
+          const directoryEntry: IDirectoryEntry = {
+            name,
+            path: entryPath,
+            isFile: entryData.type === 'file',
+            isDirectory: entryData.type === 'directory',
+            isSymbolicLink: false,
+          };
+
+          if (this.matchesFilter(directoryEntry, options.filter)) {
+            if (options.includeStats) {
+              directoryEntry.stats = await this.getEntryStats(entryPath, entryData);
+            }
+            entries.push(directoryEntry);
+          }
+        }
+      } else {
+        // Non-recursive: only direct children
+        if (entryPath.startsWith(prefix) && !entryPath.slice(prefix.length).includes('/')) {
+          const name = entryPath.slice(prefix.length);
+
+          const directoryEntry: IDirectoryEntry = {
+            name,
+            path: entryPath,
+            isFile: entryData.type === 'file',
+            isDirectory: entryData.type === 'directory',
+            isSymbolicLink: false,
+          };
+
+          if (this.matchesFilter(directoryEntry, options?.filter)) {
+            if (options?.includeStats) {
+              directoryEntry.stats = await this.getEntryStats(entryPath, entryData);
+            }
+            entries.push(directoryEntry);
+          }
+        }
+      }
+    }
+
+    return entries;
+  }
+
+  public async createDirectory(path: string, options?: { recursive?: boolean; mode?: number }): Promise<void> {
+    const normalizedPath = this.normalizePath(path);
+
+    if (options?.recursive) {
+      // Create parent directories
+      const parts = normalizedPath.split('/').filter(Boolean);
+      let currentPath = '/';
+
+      for (const part of parts) {
+        currentPath = currentPath === '/' ? `/${part}` : `${currentPath}/${part}`;
+
+        if (!this.storage.has(currentPath)) {
+          const now = new Date();
+          this.storage.set(currentPath, {
+            type: 'directory',
+            created: now,
+            modified: now,
+            accessed: now,
+            mode: options?.mode || 0o755,
+          });
+          await this.emitWatchEvent(currentPath, 'add');
+        }
+      }
+    } else {
+      const entry = this.storage.get(normalizedPath);
+
+      if (entry) {
+        throw new Error(`EEXIST: file already exists, mkdir '${normalizedPath}'`);
+      }
+
+      const now = new Date();
+      this.storage.set(normalizedPath, {
+        type: 'directory',
+        created: now,
+        modified: now,
+        accessed: now,
+        mode: options?.mode || 0o755,
+      });
+
+      await this.emitWatchEvent(normalizedPath, 'add');
+    }
+  }
+
+  public async deleteDirectory(path: string, options?: { recursive?: boolean }): Promise<void> {
+    const entry = this.storage.get(path);
+
+    if (!entry) {
+      throw new Error(`ENOENT: no such file or directory, rmdir '${path}'`);
+    }
+
+    if (entry.type !== 'directory') {
+      throw new Error(`ENOTDIR: not a directory, rmdir '${path}'`);
+    }
+
+    if (options?.recursive) {
+      // Delete all descendants
+      const normalizedPath = this.normalizePath(path);
+      const prefix = normalizedPath === '/' ? '/' : `${normalizedPath}/`;
+
+      const toDelete: string[] = [];
+      for (const entryPath of this.storage.keys()) {
+        if (entryPath.startsWith(prefix) || entryPath === normalizedPath) {
+          toDelete.push(entryPath);
+        }
+      }
+
+      for (const entryPath of toDelete) {
+        this.storage.delete(entryPath);
+        await this.emitWatchEvent(entryPath, 'delete');
+      }
+    } else {
+      // Check if directory is empty
+      const children = await this.listDirectory(path);
+      if (children.length > 0) {
+        throw new Error(`ENOTEMPTY: directory not empty, rmdir '${path}'`);
+      }
+
+      this.storage.delete(path);
+      await this.emitWatchEvent(path, 'delete');
+    }
+  }
+
+  public async directoryExists(path: string): Promise<boolean> {
+    const entry = this.storage.get(path);
+    return entry !== undefined && entry.type === 'directory';
+  }
+
+  public async directoryStat(path: string): Promise<IFileStats> {
+    const entry = this.storage.get(path);
+
+    if (!entry) {
+      throw new Error(`ENOENT: no such file or directory, stat '${path}'`);
+    }
+
+    if (entry.type !== 'directory') {
+      throw new Error(`ENOTDIR: not a directory, stat '${path}'`);
+    }
+
+    return {
+      size: 0,
+      birthtime: entry.created,
+      mtime: entry.modified,
+      atime: entry.accessed,
+      isFile: false,
+      isDirectory: true,
+      isSymbolicLink: false,
+      mode: entry.mode,
+    };
+  }
+
+  // --- Watch Operations ---
+
+  public async watch(path: string, callback: TWatchCallback, options?: IWatchOptions): Promise<IWatcherHandle> {
+    const watcherId = `watcher-${this.nextWatcherId++}`;
+
+    this.watchers.set(watcherId, {
+      path: this.normalizePath(path),
+      callback,
+      options,
+    });
+
+    return {
+      stop: async () => {
+        this.watchers.delete(watcherId);
+      },
+    };
+  }
+
+  // --- Transaction Operations ---
+
+  public async prepareTransaction(operations: ITransactionOperation[]): Promise<ITransactionOperation[]> {
+    const prepared: ITransactionOperation[] = [];
+
+    for (const op of operations) {
+      const preparedOp = { ...op };
+      const entry = this.storage.get(op.path);
+
+      if (entry && entry.type === 'file') {
+        preparedOp.backup = {
+          existed: true,
+          content: entry.content ? Buffer.from(entry.content) : undefined,
+          stats: await this.getEntryStats(op.path, entry),
+        };
+      } else {
+        preparedOp.backup = {
+          existed: false,
+        };
+      }
+
+      prepared.push(preparedOp);
+    }
+
+    return prepared;
+  }
+
+  public async executeTransaction(operations: ITransactionOperation[]): Promise<void> {
+    for (const op of operations) {
+      try {
+        switch (op.type) {
+          case 'write':
+            await this.writeFile(op.path, op.content!, { encoding: op.encoding });
+            break;
+          case 'append':
+            await this.appendFile(op.path, op.content!, { encoding: op.encoding });
+            break;
+          case 'delete':
+            await this.deleteFile(op.path);
+            break;
+          case 'copy':
+            await this.copyFile(op.path, op.targetPath!);
+            break;
+          case 'move':
+            await this.moveFile(op.path, op.targetPath!);
+            break;
+        }
+      } catch (error) {
+        // On error, rollback
+        await this.rollbackTransaction(operations);
+        throw error;
+      }
+    }
+  }
+
+  public async rollbackTransaction(operations: ITransactionOperation[]): Promise<void> {
+    for (let i = operations.length - 1; i >= 0; i--) {
+      const op = operations[i];
+      if (!op.backup) continue;
+
+      try {
+        if (op.backup.existed && op.backup.content) {
+          await this.writeFile(op.path, op.backup.content);
+        } else if (!op.backup.existed) {
+          try {
+            await this.deleteFile(op.path);
+          } catch {
+            // Ignore errors
+          }
+        }
+      } catch {
+        // Ignore rollback errors
+      }
+    }
+  }
+
+  // --- Path Operations ---
+
+  public normalizePath(path: string): string {
+    // Simple normalization
+    let normalized = path.replace(/\\/g, '/');
+    normalized = normalized.replace(/\/+/g, '/');
+    if (normalized !== '/' && normalized.endsWith('/')) {
+      normalized = normalized.slice(0, -1);
+    }
+    if (!normalized.startsWith('/')) {
+      normalized = `/${normalized}`;
+    }
+    return normalized;
+  }
+
+  public joinPath(...segments: string[]): string {
+    return this.normalizePath(segments.join('/'));
+  }
+
+  // --- Helper Methods ---
+
+  private async ensureParentDirectory(path: string): Promise<void> {
+    const parentPath = path.split('/').slice(0, -1).join('/') || '/';
+    if (!this.storage.has(parentPath)) {
+      await this.createDirectory(parentPath, { recursive: true });
+    }
+  }
+
+  private async emitWatchEvent(path: string, type: TWatchEventType): Promise<void> {
+    const normalizedPath = this.normalizePath(path);
+
+    for (const { path: watchPath, callback, options } of this.watchers.values()) {
+      const shouldTrigger = options?.recursive
+        ? normalizedPath.startsWith(watchPath)
+        : normalizedPath.split('/').slice(0, -1).join('/') === watchPath;
+
+      if (!shouldTrigger) continue;
+
+      // Apply filter
+      if (options?.filter && !this.matchesPathFilter(normalizedPath, options.filter)) {
+        continue;
+      }
+
+      const entry = this.storage.get(normalizedPath);
+      const event: IWatchEvent = {
+        type,
+        path: normalizedPath,
+        timestamp: new Date(),
+        stats: entry ? await this.getEntryStats(normalizedPath, entry) : undefined,
+      };
+
+      await callback(event);
+    }
+  }
+
+  private async getEntryStats(path: string, entry: IMemoryEntry): Promise<IFileStats> {
+    return {
+      size: entry.content?.length || 0,
+      birthtime: entry.created,
+      mtime: entry.modified,
+      atime: entry.accessed,
+      isFile: entry.type === 'file',
+      isDirectory: entry.type === 'directory',
+      isSymbolicLink: false,
+      mode: entry.mode,
+    };
+  }
+
+  private matchesFilter(
+    entry: IDirectoryEntry,
+    filter?: string | RegExp | ((entry: IDirectoryEntry) => boolean),
+  ): boolean {
+    if (!filter) return true;
+
+    if (typeof filter === 'function') {
+      return filter(entry);
+    } else if (filter instanceof RegExp) {
+      return filter.test(entry.name);
+    } else {
+      const pattern = filter.replace(/\*/g, '.*');
+      const regex = new RegExp(`^${pattern}$`);
+      return regex.test(entry.name);
+    }
+  }
+
+  private matchesPathFilter(
+    path: string,
+    filter: string | RegExp | ((path: string) => boolean),
+  ): boolean {
+    if (typeof filter === 'function') {
+      return filter(path);
+    } else if (filter instanceof RegExp) {
+      return filter.test(path);
+    } else {
+      const pattern = filter.replace(/\*/g, '.*');
+      const regex = new RegExp(`^${pattern}$`);
+      return regex.test(path);
+    }
+  }
+
+  /**
+   * Clear all data (useful for testing)
+   */
+  public clear(): void {
+    this.storage.clear();
+    // Recreate root
+    this.storage.set('/', {
+      type: 'directory',
+      created: new Date(),
+      modified: new Date(),
+      accessed: new Date(),
+      mode: 0o755,
+    });
+  }
+}

ts/providers/smartfs.provider.node.ts

@@ -0,0 +1,514 @@
+/**
+ * Node.js filesystem provider for SmartFS
+ * Uses Node.js fs/promises and fs.watch APIs
+ */
+
+import * as fs from 'fs/promises';
+import * as fsSync from 'fs';
+import * as pathModule from 'path';
+import { Readable, Writable } from 'stream';
+
+import type {
+  ISmartFsProvider,
+  IProviderCapabilities,
+  TWatchCallback,
+  IWatcherHandle,
+} from '../interfaces/mod.provider.js';
+
+import type {
+  IFileStats,
+  IDirectoryEntry,
+  IReadOptions,
+  IWriteOptions,
+  IStreamOptions,
+  ICopyOptions,
+  IListOptions,
+  IWatchOptions,
+  ITransactionOperation,
+  IWatchEvent,
+  TWatchEventType,
+} from '../interfaces/mod.types.js';
+
+/**
+ * Node.js filesystem provider
+ */
+export class SmartFsProviderNode implements ISmartFsProvider {
+  public readonly name = 'node';
+
+  public readonly capabilities: IProviderCapabilities = {
+    supportsWatch: true,
+    supportsAtomic: true,
+    supportsTransactions: true,
+    supportsStreaming: true,
+    supportsSymlinks: true,
+    supportsPermissions: true,
+  };
+
+  // --- File Operations ---
+
+  public async readFile(path: string, options?: IReadOptions): Promise<Buffer | string> {
+    const encoding = options?.encoding === 'buffer' ? undefined : (options?.encoding as BufferEncoding);
+    if (encoding) {
+      return fs.readFile(path, { encoding });
+    }
+    return fs.readFile(path);
+  }
+
+  public async writeFile(path: string, content: string | Buffer, options?: IWriteOptions): Promise<void> {
+    const encoding = options?.encoding === 'buffer' ? undefined : (options?.encoding as BufferEncoding);
+    const mode = options?.mode;
+
+    if (options?.atomic) {
+      // Atomic write: write to temp file, then rename
+      const tempPath = `${path}.tmp.${Date.now()}.${Math.random().toString(36).slice(2)}`;
+      try {
+        await fs.writeFile(tempPath, content, { encoding, mode });
+        await fs.rename(tempPath, path);
+      } catch (error) {
+        // Clean up temp file on error
+        try {
+          await fs.unlink(tempPath);
+        } catch {
+          // Ignore cleanup errors
+        }
+        throw error;
+      }
+    } else {
+      await fs.writeFile(path, content, { encoding, mode });
+    }
+  }
+
+  public async appendFile(path: string, content: string | Buffer, options?: IWriteOptions): Promise<void> {
+    const encoding = options?.encoding === 'buffer' ? undefined : (options?.encoding as BufferEncoding);
+    const mode = options?.mode;
+    await fs.appendFile(path, content, { encoding, mode });
+  }
+
+  public async deleteFile(path: string): Promise<void> {
+    await fs.unlink(path);
+  }
+
+  public async copyFile(from: string, to: string, options?: ICopyOptions): Promise<void> {
+    // Copy the file
+    await fs.copyFile(from, to);
+
+    // Preserve timestamps if requested
+    if (options?.preserveTimestamps) {
+      const stats = await fs.stat(from);
+      await fs.utimes(to, stats.atime, stats.mtime);
+    }
+  }
+
+  public async moveFile(from: string, to: string, options?: ICopyOptions): Promise<void> {
+    try {
+      // Try rename first (fastest if on same filesystem)
+      await fs.rename(from, to);
+
+      // Preserve timestamps if requested
+      if (options?.preserveTimestamps) {
+        const stats = await fs.stat(to);
+        await fs.utimes(to, stats.atime, stats.mtime);
+      }
+    } catch (error: any) {
+      if (error.code === 'EXDEV') {
+        // Cross-device move: copy then delete
+        await this.copyFile(from, to, options);
+        await this.deleteFile(from);
+      } else {
+        throw error;
+      }
+    }
+  }
+
+  public async fileExists(path: string): Promise<boolean> {
+    try {
+      await fs.access(path);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  public async fileStat(path: string): Promise<IFileStats> {
+    const stats = await fs.stat(path);
+    return this.convertStats(stats);
+  }
+
+  public async createReadStream(path: string, options?: IStreamOptions): Promise<ReadableStream<Uint8Array>> {
+    const nodeStream = fsSync.createReadStream(path, {
+      highWaterMark: options?.chunkSize || options?.highWaterMark,
+    });
+
+    return this.nodeReadableToWeb(nodeStream);
+  }
+
+  public async createWriteStream(path: string, options?: IStreamOptions): Promise<WritableStream<Uint8Array>> {
+    const nodeStream = fsSync.createWriteStream(path, {
+      highWaterMark: options?.chunkSize || options?.highWaterMark,
+    });
+
+    return this.nodeWritableToWeb(nodeStream);
+  }
+
+  // --- Directory Operations ---
+
+  public async listDirectory(path: string, options?: IListOptions): Promise<IDirectoryEntry[]> {
+    const entries: IDirectoryEntry[] = [];
+
+    if (options?.recursive) {
+      await this.listDirectoryRecursive(path, entries, options);
+    } else {
+      const dirents = await fs.readdir(path, { withFileTypes: true });
+
+      for (const dirent of dirents) {
+        const entryPath = pathModule.join(path, dirent.name);
+        const entry: IDirectoryEntry = {
+          name: dirent.name,
+          path: entryPath,
+          isFile: dirent.isFile(),
+          isDirectory: dirent.isDirectory(),
+          isSymbolicLink: dirent.isSymbolicLink(),
+        };
+
+        // Apply filter
+        if (options?.filter && !this.matchesFilter(entry, options.filter)) {
+          continue;
+        }
+
+        // Add stats if requested
+        if (options?.includeStats) {
+          try {
+            entry.stats = await this.fileStat(entryPath);
+          } catch {
+            // Ignore stat errors
+          }
+        }
+
+        entries.push(entry);
+      }
+    }
+
+    return entries;
+  }
+
+  private async listDirectoryRecursive(
+    path: string,
+    entries: IDirectoryEntry[],
+    options?: IListOptions,
+  ): Promise<void> {
+    const dirents = await fs.readdir(path, { withFileTypes: true });
+
+    for (const dirent of dirents) {
+      const entryPath = pathModule.join(path, dirent.name);
+      const entry: IDirectoryEntry = {
+        name: dirent.name,
+        path: entryPath,
+        isFile: dirent.isFile(),
+        isDirectory: dirent.isDirectory(),
+        isSymbolicLink: dirent.isSymbolicLink(),
+      };
+
+      // Apply filter
+      if (options?.filter && !this.matchesFilter(entry, options.filter)) {
+        // Skip this entry but continue recursion for directories
+        if (dirent.isDirectory()) {
+          await this.listDirectoryRecursive(entryPath, entries, options);
+        }
+        continue;
+      }
+
+      // Add stats if requested
+      if (options?.includeStats) {
+        try {
+          entry.stats = await this.fileStat(entryPath);
+        } catch {
+          // Ignore stat errors
+        }
+      }
+
+      entries.push(entry);
+
+      // Recurse into subdirectories
+      if (dirent.isDirectory()) {
+        await this.listDirectoryRecursive(entryPath, entries, options);
+      }
+    }
+  }
+
+  public async createDirectory(path: string, options?: { recursive?: boolean; mode?: number }): Promise<void> {
+    await fs.mkdir(path, {
+      recursive: options?.recursive,
+      mode: options?.mode,
+    });
+  }
+
+  public async deleteDirectory(path: string, options?: { recursive?: boolean }): Promise<void> {
+    await fs.rm(path, {
+      recursive: options?.recursive,
+      force: true,
+    });
+  }
+
+  public async directoryExists(path: string): Promise<boolean> {
+    try {
+      const stats = await fs.stat(path);
+      return stats.isDirectory();
+    } catch {
+      return false;
+    }
+  }
+
+  public async directoryStat(path: string): Promise<IFileStats> {
+    const stats = await fs.stat(path);
+    return this.convertStats(stats);
+  }
+
+  // --- Watch Operations ---
+
+  public async watch(path: string, callback: TWatchCallback, options?: IWatchOptions): Promise<IWatcherHandle> {
+    const watcher = fsSync.watch(
+      path,
+      {
+        recursive: options?.recursive,
+      },
+      async (eventType, filename) => {
+        if (!filename) return;
+
+        const fullPath = pathModule.join(path, filename);
+
+        // Apply filter
+        if (options?.filter && !this.matchesPathFilter(fullPath, options.filter)) {
+          return;
+        }
+
+        // Determine event type
+        let type: TWatchEventType = 'change';
+        try {
+          await fs.access(fullPath);
+          type = eventType === 'rename' ? 'add' : 'change';
+        } catch {
+          type = 'delete';
+        }
+
+        // Get stats if available
+        let stats: IFileStats | undefined;
+        if (type !== 'delete') {
+          try {
+            stats = await this.fileStat(fullPath);
+          } catch {
+            // Ignore stat errors
+          }
+        }
+
+        const event: IWatchEvent = {
+          type,
+          path: fullPath,
+          timestamp: new Date(),
+          stats,
+        };
+
+        await callback(event);
+      },
+    );
+
+    return {
+      stop: async () => {
+        watcher.close();
+      },
+    };
+  }
+
+  // --- Transaction Operations ---
+
+  public async prepareTransaction(operations: ITransactionOperation[]): Promise<ITransactionOperation[]> {
+    const prepared: ITransactionOperation[] = [];
+
+    for (const op of operations) {
+      const preparedOp = { ...op };
+
+      // Create backup for rollback
+      try {
+        const exists = await this.fileExists(op.path);
+        if (exists) {
+          const content = await this.readFile(op.path);
+          const stats = await this.fileStat(op.path);
+          preparedOp.backup = {
+            existed: true,
+            content: Buffer.isBuffer(content) ? content : Buffer.from(content),
+            stats,
+          };
+        } else {
+          preparedOp.backup = {
+            existed: false,
+          };
+        }
+      } catch {
+        preparedOp.backup = {
+          existed: false,
+        };
+      }
+
+      prepared.push(preparedOp);
+    }
+
+    return prepared;
+  }
+
+  public async executeTransaction(operations: ITransactionOperation[]): Promise<void> {
+    for (const op of operations) {
+      try {
+        switch (op.type) {
+          case 'write':
+            await this.writeFile(op.path, op.content!, { encoding: op.encoding });
+            break;
+          case 'append':
+            await this.appendFile(op.path, op.content!, { encoding: op.encoding });
+            break;
+          case 'delete':
+            await this.deleteFile(op.path);
+            break;
+          case 'copy':
+            await this.copyFile(op.path, op.targetPath!);
+            break;
+          case 'move':
+            await this.moveFile(op.path, op.targetPath!);
+            break;
+        }
+      } catch (error) {
+        // On error, rollback the transaction
+        await this.rollbackTransaction(operations);
+        throw error;
+      }
+    }
+  }
+
+  public async rollbackTransaction(operations: ITransactionOperation[]): Promise<void> {
+    // Rollback in reverse order
+    for (let i = operations.length - 1; i >= 0; i--) {
+      const op = operations[i];
+      if (!op.backup) continue;
+
+      try {
+        if (op.backup.existed && op.backup.content) {
+          // Restore original content
+          await this.writeFile(op.path, op.backup.content);
+        } else if (!op.backup.existed) {
+          // Delete file that was created
+          try {
+            await this.deleteFile(op.path);
+          } catch {
+            // Ignore errors
+          }
+        }
+      } catch {
+        // Ignore rollback errors
+      }
+    }
+  }
+
+  // --- Path Operations ---
+
+  public normalizePath(path: string): string {
+    return pathModule.normalize(path);
+  }
+
+  public joinPath(...segments: string[]): string {
+    return pathModule.join(...segments);
+  }
+
+  // --- Helper Methods ---
+
+  private convertStats(stats: fsSync.Stats): IFileStats {
+    return {
+      size: stats.size,
+      birthtime: stats.birthtime,
+      mtime: stats.mtime,
+      atime: stats.atime,
+      isFile: stats.isFile(),
+      isDirectory: stats.isDirectory(),
+      isSymbolicLink: stats.isSymbolicLink(),
+      mode: stats.mode,
+    };
+  }
+
+  private matchesFilter(
+    entry: IDirectoryEntry,
+    filter: string | RegExp | ((entry: IDirectoryEntry) => boolean),
+  ): boolean {
+    if (typeof filter === 'function') {
+      return filter(entry);
+    } else if (filter instanceof RegExp) {
+      return filter.test(entry.name);
+    } else {
+      // Simple glob-like pattern matching
+      const pattern = filter.replace(/\*/g, '.*');
+      const regex = new RegExp(`^${pattern}$`);
+      return regex.test(entry.name);
+    }
+  }
+
+  private matchesPathFilter(
+    path: string,
+    filter: string | RegExp | ((path: string) => boolean),
+  ): boolean {
+    if (typeof filter === 'function') {
+      return filter(path);
+    } else if (filter instanceof RegExp) {
+      return filter.test(path);
+    } else {
+      // Simple glob-like pattern matching
+      const pattern = filter.replace(/\*/g, '.*');
+      const regex = new RegExp(`^${pattern}$`);
+      return regex.test(path);
+    }
+  }
+
+  // --- Stream Conversion Helpers ---
+
+  private nodeReadableToWeb(nodeStream: Readable): ReadableStream<Uint8Array> {
+    return new ReadableStream({
+      start(controller) {
+        nodeStream.on('data', (chunk: Buffer) => {
+          controller.enqueue(new Uint8Array(chunk));
+        });
+
+        nodeStream.on('end', () => {
+          controller.close();
+        });
+
+        nodeStream.on('error', (error) => {
+          controller.error(error);
+        });
+      },
+      cancel() {
+        nodeStream.destroy();
+      },
+    });
+  }
+
+  private nodeWritableToWeb(nodeStream: Writable): WritableStream<Uint8Array> {
+    return new WritableStream({
+      write(chunk) {
+        return new Promise((resolve, reject) => {
+          const canContinue = nodeStream.write(Buffer.from(chunk));
+          if (canContinue) {
+            resolve();
+          } else {
+            nodeStream.once('drain', resolve);
+            nodeStream.once('error', reject);
+          }
+        });
+      },
+      close() {
+        return new Promise((resolve, reject) => {
+          nodeStream.end();
+          nodeStream.once('finish', resolve);
+          nodeStream.once('error', reject);
+        });
+      },
+      abort(reason) {
+        nodeStream.destroy(new Error(reason));
+      },
+    });
+  }
+}

ts/smartfs.plugins.ts

@@ -0,0 +1,9 @@
+// native scope
+import * as path from 'path';
+
+export { path };
+
+// @push.rocks scope
+import * as smartpath from '@push.rocks/smartpath';
+
+export { smartpath };