@minecraft/creator-tools/lib/local/NodeStorage.d.ts

Minecraft Creator Tools command line and libraries.

/**
 * NodeStorage.ts
 *
 * ARCHITECTURE DOCUMENTATION
 * ==========================
 *
 * NodeStorage is the local file system implementation of IStorage for Node.js environments.
 * It provides real-time file system watching using Node.js fs.watch() API.
 *
 * FILE SYSTEM WATCHING:
 * ---------------------
 * - startWatching(): Begins recursive watching of the storage root folder
 * - stopWatching(): Stops a specific watcher by ID
 * - stopAllWatching(): Stops all watchers on this storage
 *
 * When file changes are detected:
 * 1. fs.watch() callback fires with filename and event type
 * 2. NodeStorage determines if it's a file or folder change
 * 3. Appropriate notify*() method is called on StorageBase
 * 4. Events propagate to listeners (HttpServer, etc.)
 *
 * DEBOUNCING:
 * -----------
 * File system events can fire multiple times for a single logical change.
 * We debounce events by path, waiting 100ms after the last event before
 * processing to coalesce rapid-fire events.
 *
 * PIPELINE INTEGRATION:
 * ---------------------
 * NodeStorage (this) -> HttpServer (traps events) -> WebSocket -> HttpStorage -> MCWorld -> WorldView
 *
 * RELATED FILES:
 * --------------
 * - IStorageWatcher.ts: Watcher interface definition
 * - NodeFolder.ts: Folder implementation (also supports watching)
 * - NodeFile.ts: File implementation
 * - HttpServer.ts: Traps events and broadcasts via WebSocket
 */
import NodeFolder from "./NodeFolder";
import StorageBase from "../storage/StorageBase";
import IStorage from "../storage/IStorage";
import NodeFile from "./NodeFile";
import IFolder from "../storage/IFolder";
import { IWatchableStorage, IStorageChangeEvent } from "../storage/IStorageWatcher";
export default class NodeStorage extends StorageBase implements IStorage, IWatchableStorage {
    #private;
    rootPath: string;
    name: string;
    rootFolder: NodeFolder;
    static platformFolderDelimiter: "/" | "\\";
    /** Active file system watchers, keyed by watcher ID */
    private _watchers;
    /** Debounce timers for coalescing rapid file system events */
    private _debounceTimers;
    /** Counter for generating unique watcher IDs */
    private _watcherIdCounter;
    get folderDelimiter(): "/" | "\\";
    get isWatching(): boolean;
    get onStorageChange(): import("ste-events").IEvent<NodeStorage, IStorageChangeEvent>;
    constructor(incomingPath: string, name: string);
    joinPath(pathA: string, pathB: string): string;
    static createFromPath(path: string): Promise<NodeFile | NodeFolder>;
    static createFromPathIncludingZip(path: string): Promise<IFolder | undefined>;
    static getParentFolderPath(parentPath: string): string;
    static ensureEndsWithDelimiter(pth: string): string;
    static ensureStartsWithDelimiter(pth: string): string;
    getAvailable(): Promise<boolean>;
    /**
     * Start watching the storage for file system changes.
     * Uses Node.js fs.watch() with recursive option where supported.
     *
     * @returns A unique watcher ID that can be used to stop this watcher
     */
    startWatching(): string;
    /**
     * Stop a specific watcher by ID.
     */
    stopWatching(watcherId: string): void;
    /**
     * Stop all watchers on this storage.
     */
    stopAllWatching(): void;
    /**
     * Handle a file system watch event with debouncing.
     */
    private _handleWatchEvent;
    /**
     * Process a debounced file system event.
     */
    private _processWatchEvent;
}