@componentor/fs 1.2.7 → 2.0.0

package/dist/index.d.ts

@@ -1,548 +1,606 @@
 /**
- * File system constants matching Node.js fs.constants
+ * File system types matching Node.js fs module interfaces
  */
-interface FSConstants {
-    F_OK: number;
-    R_OK: number;
-    W_OK: number;
-    X_OK: number;
-    COPYFILE_EXCL: number;
-    COPYFILE_FICLONE: number;
-    COPYFILE_FICLONE_FORCE: number;
-    O_RDONLY: number;
-    O_WRONLY: number;
-    O_RDWR: number;
-    O_CREAT: number;
-    O_EXCL: number;
-    O_TRUNC: number;
-    O_APPEND: number;
-    S_IFMT: number;
-    S_IFREG: number;
-    S_IFDIR: number;
-    S_IFLNK: number;
+type Encoding = 'utf8' | 'utf-8' | 'ascii' | 'base64' | 'hex' | 'binary';
+interface ReadOptions {
+    encoding?: Encoding | null;
+    flag?: string;
 }
-/**
- * Configuration options for OPFS instance
- */
-interface OPFSOptions {
-    /** Use synchronous access handles when available (default: true) */
-    useSync?: boolean;
-    /** Enable verbose logging (default: false) */
-    verbose?: boolean;
-    /** Enable compression for batch writes (default: false) */
-    useCompression?: boolean;
-    /** Enable CRC32 checksum for batch writes (default: true) */
-    useChecksum?: boolean;
-}
-/**
- * Options for readFile operation
- */
-interface ReadFileOptions {
-    /** Text encoding (e.g., 'utf-8'). If not provided, returns Uint8Array */
-    encoding?: string;
+interface WriteOptions {
+    encoding?: Encoding;
+    mode?: number;
+    flag?: string;
+    /**
+     * Whether to flush data to storage after writing.
+     * - true (default): Data is immediately persisted - safe but slower
+     * - false: Data is written but not flushed - faster but may be lost on crash
+     */
+    flush?: boolean;
 }
-/**
- * Options for writeFile operation
- */
-interface WriteFileOptions {
-    /** Text encoding for string data */
-    encoding?: string;
+interface MkdirOptions {
+    recursive?: boolean;
+    mode?: number;
 }
-/**
- * Entry for batch file write operation
- */
-interface BatchWriteEntry {
-    /** File path to write */
-    path: string;
-    /** Data to write (string or binary) */
-    data: string | Uint8Array;
+interface RmdirOptions {
+    recursive?: boolean;
 }
-/**
- * Result entry for batch file read operation
- */
-interface BatchReadResult {
-    /** File path */
-    path: string;
-    /** File data (null if file doesn't exist or error occurred) */
-    data: Uint8Array | null;
-    /** Error if read failed */
-    error?: Error;
+interface RmOptions {
+    recursive?: boolean;
+    force?: boolean;
 }
-/**
- * Options for readdir operation
- */
 interface ReaddirOptions {
-    /** Return Dirent objects instead of strings */
+    encoding?: Encoding | null;
     withFileTypes?: boolean;
 }
-/**
- * Directory entry (Dirent-like object)
- */
-interface Dirent {
-    name: string;
+interface StatOptions {
+    bigint?: boolean;
+}
+interface Stats {
     isFile(): boolean;
     isDirectory(): boolean;
+    isBlockDevice(): boolean;
+    isCharacterDevice(): boolean;
     isSymbolicLink(): boolean;
-}
-/**
- * File statistics
- */
-interface Stats {
-    type: 'file' | 'dir' | 'symlink';
-    size: number;
+    isFIFO(): boolean;
+    isSocket(): boolean;
+    dev: number;
+    ino: number;
     mode: number;
-    ctime: Date;
+    nlink: number;
+    uid: number;
+    gid: number;
+    rdev: number;
+    size: number;
+    blksize: number;
+    blocks: number;
+    atimeMs: number;
+    mtimeMs: number;
     ctimeMs: number;
+    birthtimeMs: number;
+    atime: Date;
     mtime: Date;
-    mtimeMs: number;
-    target?: string;
+    ctime: Date;
+    birthtime: Date;
+}
+interface Dirent {
+    name: string;
     isFile(): boolean;
     isDirectory(): boolean;
+    isBlockDevice(): boolean;
+    isCharacterDevice(): boolean;
     isSymbolicLink(): boolean;
+    isFIFO(): boolean;
+    isSocket(): boolean;
 }
-/**
- * Options for rm operation
- */
-interface RmOptions {
-    /** Remove directories and their contents recursively */
-    recursive?: boolean;
-    /** Ignore if path doesn't exist */
-    force?: boolean;
-}
-/**
- * Options for cp operation
- */
-interface CpOptions {
-    /** Copy directories recursively */
-    recursive?: boolean;
-    /** Overwrite existing files */
-    force?: boolean;
-    /** Throw if destination exists */
-    errorOnExist?: boolean;
-}
-/**
- * Options for watch operation
- */
-interface WatchOptions {
-    /** Keep the process running while watching (default: true) */
-    persistent?: boolean;
-    /** Watch subdirectories recursively */
-    recursive?: boolean;
-    /** Abort signal to stop watching */
-    signal?: AbortSignal;
-    /** Encoding for filename (default: 'utf8') */
-    encoding?: string;
-}
-/**
- * Watch event
- */
-interface WatchEvent {
-    eventType: 'rename' | 'change';
-    filename: string;
-}
-/**
- * File watcher
- */
-interface FSWatcher {
-    close(): void;
-    ref(): FSWatcher;
-    unref(): FSWatcher;
-    [Symbol.asyncIterator](): AsyncIterator<WatchEvent>;
+interface FileSystemPromises {
+    readFile(path: string, options?: ReadOptions | Encoding | null): Promise<Uint8Array | string>;
+    writeFile(path: string, data: Uint8Array | string, options?: WriteOptions | Encoding): Promise<void>;
+    appendFile(path: string, data: Uint8Array | string, options?: WriteOptions | Encoding): Promise<void>;
+    mkdir(path: string, options?: MkdirOptions | number): Promise<string | undefined>;
+    rmdir(path: string, options?: RmdirOptions): Promise<void>;
+    rm(path: string, options?: RmOptions): Promise<void>;
+    unlink(path: string): Promise<void>;
+    readdir(path: string, options?: ReaddirOptions | Encoding | null): Promise<string[] | Dirent[]>;
+    stat(path: string, options?: StatOptions): Promise<Stats>;
+    lstat(path: string, options?: StatOptions): Promise<Stats>;
+    access(path: string, mode?: number): Promise<void>;
+    rename(oldPath: string, newPath: string): Promise<void>;
+    copyFile(src: string, dest: string, mode?: number): Promise<void>;
+    truncate(path: string, len?: number): Promise<void>;
+    realpath(path: string): Promise<string>;
+    /**
+     * Check if a path exists.
+     * Note: This is not in Node.js fs.promises but is commonly needed.
+     */
+    exists(path: string): Promise<boolean>;
+    /**
+     * Change file mode (no-op in OPFS - permissions not supported).
+     */
+    chmod(path: string, mode: number): Promise<void>;
+    /**
+     * Change file owner (no-op in OPFS - ownership not supported).
+     */
+    chown(path: string, uid: number, gid: number): Promise<void>;
+    /**
+     * Change file timestamps (no-op in OPFS - timestamps are read-only).
+     */
+    utimes(path: string, atime: Date | number, mtime: Date | number): Promise<void>;
+    /**
+     * Create a symbolic link.
+     * Emulated by storing target path in a special file format.
+     */
+    symlink(target: string, path: string, type?: string): Promise<void>;
+    /**
+     * Read a symbolic link target.
+     */
+    readlink(path: string): Promise<string>;
+    /**
+     * Create a hard link.
+     * Emulated by copying the file (true hard links not supported in OPFS).
+     */
+    link(existingPath: string, newPath: string): Promise<void>;
+    /**
+     * Open a file and return a FileHandle.
+     */
+    open(path: string, flags?: string | number, mode?: number): Promise<FileHandle>;
+    /**
+     * Open a directory for iteration.
+     */
+    opendir(path: string): Promise<Dir>;
+    /**
+     * Create a unique temporary directory.
+     */
+    mkdtemp(prefix: string): Promise<string>;
+    /**
+     * Watch a file or directory for changes.
+     */
+    watch(path: string, options?: WatchOptions): AsyncIterable<WatchEventType>;
+    /**
+     * Flush all pending writes to storage.
+     * Use after writes with { flush: false } to ensure data is persisted.
+     */
+    flush(): Promise<void>;
+    /**
+     * Purge all kernel caches.
+     * Use between major operations to ensure clean state.
+     */
+    purge(): Promise<void>;
 }
-/**
- * Read stream options
- */
+type PathLike = string;
 interface ReadStreamOptions {
-    /** Start reading from this byte position */
+    flags?: string;
+    encoding?: Encoding | null;
+    fd?: number | null;
+    mode?: number;
+    autoClose?: boolean;
+    emitClose?: boolean;
     start?: number;
-    /** Stop reading at this byte position */
     end?: number;
-    /** Chunk size for reading (default: 64KB) */
     highWaterMark?: number;
 }
-/**
- * Write stream options
- */
 interface WriteStreamOptions {
-    /** File open flags (default: 'w') */
     flags?: string;
-    /** Start writing at this byte position */
+    encoding?: Encoding;
+    fd?: number | null;
+    mode?: number;
+    autoClose?: boolean;
+    emitClose?: boolean;
     start?: number;
+    highWaterMark?: number;
+    flush?: boolean;
 }
-/**
- * Symlink definition for batch operations
- */
-interface SymlinkDefinition {
-    target: string;
-    path: string;
+interface WatchOptions {
+    persistent?: boolean;
+    recursive?: boolean;
+    encoding?: Encoding;
+    signal?: AbortSignal;
 }
-/**
- * Result of read operation on FileHandle
- */
-interface ReadResult {
-    bytesRead: number;
-    buffer: Uint8Array;
+interface WatchFileOptions {
+    persistent?: boolean;
+    interval?: number;
 }
-/**
- * Result of write operation on FileHandle
- */
-interface WriteResult {
-    bytesWritten: number;
-    buffer: Uint8Array;
+interface WatchEventType {
+    eventType: 'rename' | 'change';
+    filename: string | null;
 }
-/**
- * FileHandle interface (returned by open())
- */
 interface FileHandle {
     fd: number;
-    read(buffer: Uint8Array, offset?: number, length?: number, position?: number | null): Promise<ReadResult>;
-    write(buffer: Uint8Array, offset?: number, length?: number, position?: number | null): Promise<WriteResult>;
-    close(): Promise<void>;
-    stat(): Promise<Stats>;
+    read(buffer: Uint8Array, offset?: number, length?: number, position?: number | null): Promise<{
+        bytesRead: number;
+        buffer: Uint8Array;
+    }>;
+    write(buffer: Uint8Array, offset?: number, length?: number, position?: number | null): Promise<{
+        bytesWritten: number;
+        buffer: Uint8Array;
+    }>;
+    readFile(options?: ReadOptions | Encoding | null): Promise<Uint8Array | string>;
+    writeFile(data: Uint8Array | string, options?: WriteOptions | Encoding): Promise<void>;
     truncate(len?: number): Promise<void>;
+    stat(): Promise<Stats>;
     sync(): Promise<void>;
     datasync(): Promise<void>;
-    readFile(options?: ReadFileOptions): Promise<string | Uint8Array>;
-    writeFile(data: string | Uint8Array, options?: WriteFileOptions): Promise<void>;
-    appendFile(data: string | Uint8Array, options?: WriteFileOptions): Promise<void>;
-    [Symbol.asyncDispose](): Promise<void>;
+    close(): Promise<void>;
 }
-/**
- * Directory handle (returned by opendir())
- */
 interface Dir {
     path: string;
     read(): Promise<Dirent | null>;
     close(): Promise<void>;
     [Symbol.asyncIterator](): AsyncIterableIterator<Dirent>;
 }
-/**
- * Disk usage result
- */
-interface DiskUsage {
-    path: string;
-    size: number;
+interface FSWatcher {
+    close(): void;
+    ref(): this;
+    unref(): this;
 }
-/**
- * Filesystem statistics (similar to Node.js fs.statfs)
- */
-interface StatFs {
-    /** Filesystem type (always 0 for OPFS) */
-    type: number;
-    /** Optimal transfer block size (simulated as 4096) */
-    bsize: number;
-    /** Total blocks in filesystem */
-    blocks: number;
-    /** Free blocks in filesystem */
-    bfree: number;
-    /** Available blocks for unprivileged users */
-    bavail: number;
-    /** Total file nodes (0 - not available in browser) */
-    files: number;
-    /** Free file nodes (0 - not available in browser) */
-    ffree: number;
-    /** Bytes used by origin (from Storage API) */
-    usage: number;
-    /** Total bytes available to origin (from Storage API) */
-    quota: number;
+interface StatWatcher {
+    ref(): this;
+    unref(): this;
 }
-/**
- * Internal symlink cache structure
- */
-type SymlinkCache = Record<string, string>;
-/**
- * Watch callback function
- */
-type WatchCallback = (eventType: string, filename: string) => void;
-/**
- * Internal watch registration
- */
-interface WatchRegistration {
-    path: string;
-    callbacks: Set<WatchCallback>;
-    recursive: boolean;
+type WatchListener = (eventType: 'rename' | 'change', filename: string | null) => void;
+type WatchFileListener = (curr: Stats, prev: Stats) => void;
+interface FileSystemChangeRecord {
+    changedHandle: FileSystemHandle | null;
+    relativePathComponents: string[];
+    relativePathMovedFrom: string[] | null;
+    root: FileSystemHandle;
+    type: 'appeared' | 'disappeared' | 'modified' | 'moved' | 'errored' | 'unknown';
 }
-
-/**
- * File system constants matching Node.js fs.constants
- */
-declare const constants: FSConstants;
-
-type Backend = 'main' | 'worker';
-interface OPFSHybridOptions {
-    /** Backend for read operations (default: 'main') */
-    read?: Backend;
-    /** Backend for write operations (default: 'worker') */
-    write?: Backend;
-    /** Worker URL (required if using worker backend) */
-    workerUrl?: URL | string;
-    /** Enable verbose logging */
-    verbose?: boolean;
+type FileSystemObserverCallback = (records: FileSystemChangeRecord[], observer: FileSystemObserverInterface) => void;
+interface FileSystemObserverInterface {
+    observe(handle: FileSystemHandle, options?: {
+        recursive?: boolean;
+    }): Promise<void>;
+    disconnect(): void;
 }
-/**
- * Hybrid OPFS implementation that routes operations to optimal backends
- */
-declare class OPFSHybrid {
-    private mainFs;
-    private workerFs;
-    private readBackend;
-    private writeBackend;
-    private workerUrl?;
-    private workerReady;
-    private verbose;
-    constructor(options?: OPFSHybridOptions);
-    /**
-     * Wait for all backends to be ready
-     */
-    ready(): Promise<void>;
-    /**
-     * Terminate worker if active
-     */
-    terminate(): void;
-    private getReadFs;
-    private getWriteFs;
-    readFile(path: string, options?: ReadFileOptions): Promise<Uint8Array | string>;
-    readFileBatch(paths: string[]): Promise<BatchReadResult[]>;
-    readdir(path: string, options?: ReaddirOptions): Promise<string[] | Dirent[]>;
-    stat(path: string): Promise<Stats>;
-    lstat(path: string): Promise<Stats>;
-    exists(path: string): Promise<boolean>;
-    access(path: string, mode?: number): Promise<void>;
-    readlink(path: string): Promise<string>;
-    realpath(path: string): Promise<string>;
-    statfs(path?: string): Promise<StatFs>;
-    du(path: string): Promise<DiskUsage>;
-    writeFile(path: string, data: string | Uint8Array, options?: WriteFileOptions): Promise<void>;
-    writeFileBatch(entries: BatchWriteEntry[]): Promise<void>;
-    appendFile(path: string, data: string | Uint8Array, options?: WriteFileOptions): Promise<void>;
-    mkdir(path: string): Promise<void>;
-    rmdir(path: string): Promise<void>;
-    unlink(path: string): Promise<void>;
-    truncate(path: string, len?: number): Promise<void>;
-    symlink(target: string, path: string): Promise<void>;
-    symlinkBatch(symlinks: SymlinkDefinition[]): Promise<void>;
-    rename(oldPath: string, newPath: string): Promise<void>;
-    copyFile(src: string, dest: string, mode?: number): Promise<void>;
-    cp(src: string, dest: string, options?: CpOptions): Promise<void>;
-    rm(path: string, options?: RmOptions): Promise<void>;
-    chmod(path: string, mode: number): Promise<void>;
-    chown(path: string, uid: number, gid: number): Promise<void>;
-    utimes(path: string, atime: Date | number, mtime: Date | number): Promise<void>;
-    lutimes(path: string, atime: Date | number, mtime: Date | number): Promise<void>;
-    mkdtemp(prefix: string): Promise<string>;
-    /**
-     * Reset internal caches on both backends
-     */
-    resetCache(): Promise<void>;
-    /**
-     * Force full garbage collection on both backends
-     * More aggressive than resetCache() - reinitializes the worker's OPFS instance
-     */
-    gc(): Promise<void>;
+declare global {
+    interface Window {
+        FileSystemObserver?: new (callback: FileSystemObserverCallback) => FileSystemObserverInterface;
+    }
+    var FileSystemObserver: (new (callback: FileSystemObserverCallback) => FileSystemObserverInterface) | undefined;
 }
 
-/** Extended options that include hybrid mode support */
-interface OPFSExtendedOptions extends OPFSOptions {
-    /** Worker script URL - when provided, enables hybrid mode (reads on main, writes on worker) */
-    workerUrl?: URL | string;
-    /** Override read backend when using hybrid mode (default: 'main') */
-    read?: Backend;
-    /** Override write backend when using hybrid mode (default: 'worker') */
-    write?: Backend;
-}
 /**
- * OPFS-based filesystem implementation compatible with Node.js fs/promises API
- *
- * When `workerUrl` is provided, automatically uses hybrid mode for optimal performance:
- * - Reads on main thread (no message passing overhead)
- * - Writes on worker (sync access handles are faster)
+ * OPFS FileSystem - Node.js fs-compatible API
+ * Supports two performance tiers:
+ * - Tier 1 (Sync): SharedArrayBuffer + Atomics - requires crossOriginIsolated (COOP/COEP headers)
+ * - Tier 2 (Async): Promises API using Worker kernel - always available
  */
-declare class OPFS {
-    private useSync;
-    private verbose;
-    private handleManager;
-    private symlinkManager;
-    private packedStorage;
-    private watchCallbacks;
-    private tmpCounter;
-    /** Hybrid instance when workerUrl is provided */
-    private hybrid;
-    /** File system constants */
-    readonly constants: FSConstants;
-    constructor(options?: OPFSExtendedOptions);
-    /**
-     * Wait for the filesystem to be ready (only needed for hybrid mode)
-     */
-    ready(): Promise<void>;
-    /**
-     * Terminate any background workers (only needed for hybrid mode)
-     */
-    terminate(): void;
-    private log;
-    private logError;
-    /**
-     * Execute tasks with limited concurrency to avoid overwhelming the system
-     * @param items - Array of items to process
-     * @param maxConcurrent - Maximum number of concurrent operations (default: 10)
-     * @param taskFn - Function to execute for each item
-     */
-    private limitConcurrency;
-    /**
-     * Read file contents
-     */
-    readFile(path: string, options?: ReadFileOptions): Promise<string | Uint8Array>;
-    /**
-     * Read multiple files efficiently in a batch operation
-     * Uses packed storage batch read (single index load), falls back to individual files
-     * Returns results in the same order as input paths
-     */
-    readFileBatch(paths: string[]): Promise<BatchReadResult[]>;
-    /**
-     * Write data to a file
-     */
-    writeFile(path: string, data: string | Uint8Array, options?: WriteFileOptions): Promise<void>;
-    /**
-     * Write multiple files efficiently in a batch operation
-     * Uses packed storage (single file) for maximum performance
-     */
-    writeFileBatch(entries: BatchWriteEntry[]): Promise<void>;
-    /**
-     * Create a directory
-     */
-    mkdir(path: string): Promise<void>;
-    /**
-     * Remove a directory
-     */
-    rmdir(path: string): Promise<void>;
-    /**
-     * Remove a file or symlink
-     */
-    unlink(path: string): Promise<void>;
-    /**
-     * Read directory contents
-     */
-    readdir(path: string, options?: ReaddirOptions): Promise<string[] | Dirent[]>;
-    /**
-     * Get file/directory statistics (follows symlinks)
-     */
-    stat(path: string): Promise<Stats>;
-    /**
-     * Get file/directory statistics (does not follow symlinks)
-     */
-    lstat(path: string): Promise<Stats>;
-    /**
-     * Rename a file or directory
-     */
-    rename(oldPath: string, newPath: string): Promise<void>;
-    /**
-     * Create a symbolic link
-     */
-    symlink(target: string, path: string): Promise<void>;
-    /**
-     * Read symlink target
-     */
-    readlink(path: string): Promise<string>;
-    /**
-     * Create multiple symlinks efficiently
-     */
-    symlinkBatch(links: SymlinkDefinition[]): Promise<void>;
-    /**
-     * Check file accessibility
-     */
-    access(path: string, mode?: number): Promise<void>;
-    /**
-     * Append data to a file
-     */
-    appendFile(path: string, data: string | Uint8Array, options?: WriteFileOptions): Promise<void>;
-    /**
-     * Copy a file
-     */
-    copyFile(src: string, dest: string, mode?: number): Promise<void>;
-    /**
-     * Copy files/directories recursively
-     */
-    cp(src: string, dest: string, options?: CpOptions): Promise<void>;
-    /**
-     * Check if path exists
-     */
-    exists(path: string): Promise<boolean>;
-    /**
-     * Resolve symlinks to get real path
-     */
-    realpath(path: string): Promise<string>;
-    /**
-     * Remove files and directories
-     */
-    rm(path: string, options?: RmOptions): Promise<void>;
-    /**
-     * Truncate file to specified length
-     */
-    truncate(path: string, len?: number): Promise<void>;
-    /**
-     * Create a unique temporary directory
-     */
-    mkdtemp(prefix: string): Promise<string>;
-    /**
-     * Change file mode (no-op for OPFS compatibility)
-     */
-    chmod(path: string, mode: number): Promise<void>;
-    /**
-     * Change file owner (no-op for OPFS compatibility)
-     */
-    chown(path: string, uid: number, gid: number): Promise<void>;
-    /**
-     * Update file timestamps (no-op for OPFS compatibility)
-     */
-    utimes(path: string, atime: Date | number, mtime: Date | number): Promise<void>;
-    /**
-     * Update symlink timestamps (no-op)
-     */
-    lutimes(path: string, atime: Date | number, mtime: Date | number): Promise<void>;
-    /**
-     * Open file and return FileHandle
-     */
-    open(path: string, flags?: string | number, mode?: number): Promise<FileHandle>;
-    /**
-     * Open directory for iteration
-     */
-    opendir(path: string): Promise<Dir>;
-    /**
-     * Watch for file changes
-     */
-    watch(path: string, options?: WatchOptions): FSWatcher;
-    /**
-     * Create read stream
-     */
-    createReadStream(path: string, options?: ReadStreamOptions): ReadableStream<Uint8Array>;
+
+declare class OPFSFileSystem {
+    private worker;
+    private pending;
+    private initialized;
+    private initPromise;
+    private fdTable;
+    private nextFd;
+    private statCache;
+    constructor();
+    private invalidateStat;
+    private invalidateStatsUnder;
+    private initWorker;
+    private asyncCall;
+    private syncKernel;
+    private syncKernelReady;
+    /**
+     * Initialize sync operations with a kernel worker loaded from URL.
+     * Required for Tier 1 (SharedArrayBuffer + Atomics) to work in nested Workers.
+     * @param kernelUrl URL to the kernel.js file (defaults to '/kernel.js')
+     */
+    initSync(kernelUrl?: string): Promise<void>;
+    private static readonly META_SIZE;
+    private static readonly DEFAULT_DATA_SIZE;
+    private static readonly MAX_CHUNK_SIZE;
+    private syncBufferPool;
+    private getSyncBuffers;
+    private syncCallTier1;
+    private asyncOperationPromise;
+    private syncCallTier1Async;
+    private syncCallTier1AsyncImpl;
+    private syncStatTier1Async;
+    private syncCallTier1ChunkedAsync;
+    private syncCallTier1ChunkedReadAsync;
+    private syncCallTier1Chunked;
+    private syncCallTier1ChunkedRead;
+    private syncStatTier1;
+    private syncCall;
+    readFileSync(filePath: string, options?: ReadOptions | Encoding | null): Uint8Array | string;
+    writeFileSync(filePath: string, data: Uint8Array | string, options?: WriteOptions | Encoding): void;
+    appendFileSync(filePath: string, data: Uint8Array | string, options?: WriteOptions | Encoding): void;
+    existsSync(filePath: string): boolean;
+    mkdirSync(filePath: string, options?: MkdirOptions | number): string | undefined;
+    rmdirSync(filePath: string, options?: RmdirOptions): void;
+    rmSync(filePath: string, options?: RmOptions): void;
+    unlinkSync(filePath: string): void;
+    readdirSync(filePath: string, options?: ReaddirOptions | Encoding | null): string[] | Dirent[];
+    statSync(filePath: string): Stats;
+    lstatSync(filePath: string): Stats;
+    /**
+     * Create stats object for a symlink file.
+     */
+    private createSymlinkStats;
+    renameSync(oldPath: string, newPath: string): void;
+    copyFileSync(src: string, dest: string): void;
+    truncateSync(filePath: string, len?: number): void;
+    /**
+     * Flush all pending writes to storage.
+     * Use this after writes with { flush: false } to ensure data is persisted.
+     */
+    flushSync(): void;
+    /**
+     * Alias for flushSync() - matches Node.js fdatasync behavior
+     */
+    fdatasyncSync(): void;
+    /**
+     * Purge all kernel caches (sync handles, directory handles).
+     * Use between major operations to ensure clean state.
+     */
+    purgeSync(): void;
+    accessSync(filePath: string, _mode?: number): void;
+    openSync(filePath: string, flags?: string | number): number;
+    closeSync(fd: number): void;
+    readSync(fd: number, buffer: Uint8Array, offset: number, length: number, position: number | null): number;
+    writeSync(fd: number, buffer: Uint8Array, offset: number, length: number, position: number | null): number;
+    fstatSync(fd: number): Stats;
+    ftruncateSync(fd: number, len?: number): void;
+    /**
+     * Resolve a path to an absolute path.
+     * OPFS doesn't support symlinks, so this just normalizes the path.
+     */
+    realpathSync(filePath: string): string;
+    /**
+     * Change file mode (no-op in OPFS - permissions not supported).
+     */
+    chmodSync(_filePath: string, _mode: number): void;
+    /**
+     * Change file owner (no-op in OPFS - ownership not supported).
+     */
+    chownSync(_filePath: string, _uid: number, _gid: number): void;
+    /**
+     * Change file timestamps (no-op in OPFS - timestamps are read-only).
+     */
+    utimesSync(_filePath: string, _atime: Date | number, _mtime: Date | number): void;
+    private static readonly SYMLINK_MAGIC;
+    /**
+     * Create a symbolic link.
+     * Emulated by storing target path in a special file format.
+     */
+    symlinkSync(target: string, filePath: string, _type?: string): void;
+    /**
+     * Read a symbolic link target.
+     */
+    readlinkSync(filePath: string): string;
+    /**
+     * Check if a file is a symlink (sync).
+     */
+    private isSymlinkSync;
+    /**
+     * Check if a file is a symlink (async).
+     */
+    private isSymlinkAsync;
+    /**
+     * Create a hard link.
+     * Emulated by copying the file (true hard links not supported in OPFS).
+     */
+    linkSync(existingPath: string, newPath: string): void;
+    private parseFlags;
+    private fastCall;
+    promises: FileSystemPromises;
+    /**
+     * Async flush - use after promises.writeFile with { flush: false }
+     */
+    flush(): Promise<void>;
+    /**
+     * Async purge - clears all kernel caches
+     */
+    purge(): Promise<void>;
+    constants: {
+        readonly F_OK: 0;
+        readonly R_OK: 4;
+        readonly W_OK: 2;
+        readonly X_OK: 1;
+        readonly COPYFILE_EXCL: 1;
+        readonly COPYFILE_FICLONE: 2;
+        readonly COPYFILE_FICLONE_FORCE: 4;
+        readonly O_RDONLY: 0;
+        readonly O_WRONLY: 1;
+        readonly O_RDWR: 2;
+        readonly O_CREAT: 64;
+        readonly O_EXCL: 128;
+        readonly O_TRUNC: 512;
+        readonly O_APPEND: 1024;
+        readonly O_SYNC: 4096;
+        readonly S_IFMT: 61440;
+        readonly S_IFREG: 32768;
+        readonly S_IFDIR: 16384;
+        readonly S_IFCHR: 8192;
+        readonly S_IFBLK: 24576;
+        readonly S_IFIFO: 4096;
+        readonly S_IFLNK: 40960;
+        readonly S_IFSOCK: 49152;
+        readonly S_IRWXU: 448;
+        readonly S_IRUSR: 256;
+        readonly S_IWUSR: 128;
+        readonly S_IXUSR: 64;
+        readonly S_IRWXG: 56;
+        readonly S_IRGRP: 32;
+        readonly S_IWGRP: 16;
+        readonly S_IXGRP: 8;
+        readonly S_IRWXO: 7;
+        readonly S_IROTH: 4;
+        readonly S_IWOTH: 2;
+        readonly S_IXOTH: 1;
+    };
+    private createFileHandle;
+    private createDir;
+    private watchedFiles;
+    private static readonly hasNativeObserver;
+    private getDirectoryHandle;
+    private getFileHandle;
+    private mapChangeType;
+    private createAsyncWatcher;
+    private createNativeAsyncWatcher;
+    private createPollingAsyncWatcher;
     /**
-     * Create write stream
+     * Watch a file or directory for changes.
+     * Uses native FileSystemObserver when available, falls back to polling.
      */
-    createWriteStream(path: string, options?: WriteStreamOptions): WritableStream<Uint8Array>;
+    watch(filePath: string, options?: WatchOptions | WatchListener, listener?: WatchListener): FSWatcher;
+    private createNativeWatcher;
+    private createPollingWatcher;
     /**
-     * Get file statistics (alias for stat)
+     * Watch a file for changes using native FileSystemObserver or stat polling.
      */
-    backFile(path: string): Promise<Stats>;
+    watchFile(filePath: string, options?: WatchFileOptions | WatchFileListener, listener?: WatchFileListener): StatWatcher;
     /**
-     * Get disk usage for a path
+     * Stop watching a file.
      */
-    du(path: string): Promise<DiskUsage>;
+    unwatchFile(filePath: string, listener?: WatchFileListener): void;
     /**
-     * Get filesystem statistics (similar to Node.js fs.statfs)
-     * Uses the Storage API to get quota and usage information
-     * Note: Values are estimates for the entire origin, not per-path
+     * Create a readable stream for a file.
      */
-    statfs(path?: string): Promise<StatFs>;
+    createReadStream(filePath: string, options?: ReadStreamOptions | string): ReadableStream<Uint8Array>;
     /**
-     * Reset internal caches
-     * Useful when external processes modify the filesystem
+     * Create a writable stream for a file.
      */
-    resetCache(): void;
+    createWriteStream(filePath: string, options?: WriteStreamOptions | string): WritableStream<Uint8Array>;
     /**
-     * Force full garbage collection
-     * Releases all handles and caches, reinitializes the worker in hybrid mode
-     * Use this for long-running operations to prevent memory leaks
+     * Open a directory for iteration (sync).
      */
-    gc(): Promise<void>;
+    opendirSync(dirPath: string): Dir;
+    /**
+     * Create a unique temporary directory (sync).
+     */
+    mkdtempSync(prefix: string): string;
 }
 
-export { type Backend, type BatchReadResult, type BatchWriteEntry, type CpOptions, type Dir, type Dirent, type DiskUsage, type FSConstants, type FSWatcher, type FileHandle, type OPFSExtendedOptions, OPFSHybrid, type OPFSHybridOptions, type OPFSOptions, type ReadFileOptions, type ReadResult, type ReadStreamOptions, type ReaddirOptions, type RmOptions, type StatFs, type Stats, type SymlinkCache, type SymlinkDefinition, type WatchCallback, type WatchEvent, type WatchOptions, type WatchRegistration, type WriteFileOptions, type WriteResult, type WriteStreamOptions, constants, OPFS as default };
+/**
+ * File system constants matching Node.js fs.constants
+ */
+declare const constants: {
+    readonly F_OK: 0;
+    readonly R_OK: 4;
+    readonly W_OK: 2;
+    readonly X_OK: 1;
+    readonly COPYFILE_EXCL: 1;
+    readonly COPYFILE_FICLONE: 2;
+    readonly COPYFILE_FICLONE_FORCE: 4;
+    readonly O_RDONLY: 0;
+    readonly O_WRONLY: 1;
+    readonly O_RDWR: 2;
+    readonly O_CREAT: 64;
+    readonly O_EXCL: 128;
+    readonly O_TRUNC: 512;
+    readonly O_APPEND: 1024;
+    readonly O_SYNC: 4096;
+    readonly S_IFMT: 61440;
+    readonly S_IFREG: 32768;
+    readonly S_IFDIR: 16384;
+    readonly S_IFCHR: 8192;
+    readonly S_IFBLK: 24576;
+    readonly S_IFIFO: 4096;
+    readonly S_IFLNK: 40960;
+    readonly S_IFSOCK: 49152;
+    readonly S_IRWXU: 448;
+    readonly S_IRUSR: 256;
+    readonly S_IWUSR: 128;
+    readonly S_IXUSR: 64;
+    readonly S_IRWXG: 56;
+    readonly S_IRGRP: 32;
+    readonly S_IWGRP: 16;
+    readonly S_IXGRP: 8;
+    readonly S_IRWXO: 7;
+    readonly S_IROTH: 4;
+    readonly S_IWOTH: 2;
+    readonly S_IXOTH: 1;
+};
+
+/**
+ * Node.js compatible filesystem error classes
+ */
+declare class FSError extends Error {
+    code: string;
+    errno: number;
+    syscall?: string;
+    path?: string;
+    constructor(code: string, errno: number, message: string, syscall?: string, path?: string);
+}
+declare function createENOENT(syscall: string, path: string): FSError;
+declare function createEEXIST(syscall: string, path: string): FSError;
+declare function createEISDIR(syscall: string, path: string): FSError;
+declare function createENOTDIR(syscall: string, path: string): FSError;
+declare function createENOTEMPTY(syscall: string, path: string): FSError;
+declare function createEACCES(syscall: string, path: string): FSError;
+declare function createEINVAL(syscall: string, path: string): FSError;
+declare function mapErrorCode(errorName: string, syscall: string, path: string): FSError;
+
+/**
+ * POSIX-style path utilities for OPFS
+ * Mirrors Node.js path module behavior
+ */
+declare const sep = "/";
+declare const delimiter = ":";
+declare function normalize(p: string): string;
+declare function join(...paths: string[]): string;
+declare function resolve(...paths: string[]): string;
+declare function isAbsolute(p: string): boolean;
+declare function dirname(p: string): string;
+declare function basename(p: string, ext?: string): string;
+declare function extname(p: string): string;
+declare function relative(from: string, to: string): string;
+declare function parse(p: string): {
+    root: string;
+    dir: string;
+    base: string;
+    ext: string;
+    name: string;
+};
+declare function format(pathObject: {
+    root?: string;
+    dir?: string;
+    base?: string;
+    ext?: string;
+    name?: string;
+}): string;
+declare const posix: {
+    sep: string;
+    delimiter: string;
+    normalize: typeof normalize;
+    join: typeof join;
+    resolve: typeof resolve;
+    isAbsolute: typeof isAbsolute;
+    dirname: typeof dirname;
+    basename: typeof basename;
+    extname: typeof extname;
+    relative: typeof relative;
+    parse: typeof parse;
+    format: typeof format;
+};
+
+declare const path_basename: typeof basename;
+declare const path_delimiter: typeof delimiter;
+declare const path_dirname: typeof dirname;
+declare const path_extname: typeof extname;
+declare const path_format: typeof format;
+declare const path_isAbsolute: typeof isAbsolute;
+declare const path_join: typeof join;
+declare const path_normalize: typeof normalize;
+declare const path_parse: typeof parse;
+declare const path_posix: typeof posix;
+declare const path_relative: typeof relative;
+declare const path_resolve: typeof resolve;
+declare const path_sep: typeof sep;
+declare namespace path {
+  export { path_basename as basename, posix as default, path_delimiter as delimiter, path_dirname as dirname, path_extname as extname, path_format as format, path_isAbsolute as isAbsolute, path_join as join, path_normalize as normalize, path_parse as parse, path_posix as posix, path_relative as relative, path_resolve as resolve, path_sep as sep };
+}
+
+/**
+ * OPFS-FS: Battle-tested OPFS-based Node.js fs polyfill
+ *
+ * Provides a Node.js-compatible filesystem API that works in browsers using OPFS.
+ *
+ * Features:
+ * - Synchronous API: fs.readFileSync, fs.writeFileSync, etc. (requires crossOriginIsolated)
+ * - Async Promises API: fs.promises.readFile, fs.promises.writeFile, etc.
+ * - Cross-tab safety via navigator.locks
+ *
+ * Performance Tiers:
+ * - Tier 1 (Sync): SharedArrayBuffer + Atomics - requires crossOriginIsolated (COOP/COEP headers)
+ * - Tier 2 (Async): Promises API - always available
+ *
+ * @example
+ * ```typescript
+ * import { fs } from '@componentor/fs';
+ *
+ * // Sync API (requires crossOriginIsolated)
+ * fs.writeFileSync('/hello.txt', 'Hello World!');
+ * const data = fs.readFileSync('/hello.txt', 'utf8');
+ *
+ * // Async API (always available)
+ * await fs.promises.writeFile('/async.txt', 'Async data');
+ * const content = await fs.promises.readFile('/async.txt', 'utf8');
+ * ```
+ */
+
+declare const fs: OPFSFileSystem;
+
+export { type Dirent, type Encoding, FSError, type FileSystemPromises, type MkdirOptions, OPFSFileSystem, type PathLike, type ReadOptions, type ReaddirOptions, type RmOptions, type RmdirOptions, type Stats, type WriteOptions, constants, createEACCES, createEEXIST, createEINVAL, createEISDIR, createENOENT, createENOTDIR, createENOTEMPTY, fs as default, fs, mapErrorCode, path };