@theia/filesystem 1.77.0-next.6 → 1.77.0-next.63

package/lib/node/nodejs-watcher/node-directory-watcher.d.ts

@@ -0,0 +1,175 @@
+import { CancellationToken } from '@theia/core/lib/common/cancellation';
+import { WatcherHost } from './watcher-host';
+import { FileSystemWatcherServiceClient } from '../../common/filesystem-watcher-protocol';
+import { AbstractFileSystemWatcher, AbstractWatcherProvider, ResolvedWatchOptions, WatcherLogger, WatchRequest } from '../filesystem-watcher';
+import { DirectoryWatchRequest, ResolvedChange, WatchRequestRouter } from './watch-request-router';
+export interface NodeDirectoryWatcherTimings {
+    /** Aggregation window before raw events are resolved against the file system. */
+    readonly changeDelay: number;
+    /** Grace period before a deletion is confirmed, so an atomic save is not reported as one. */
+    readonly deleteDelay: number;
+    /** Poll interval for a path that does not exist yet. */
+    readonly existencePollDelay: number;
+    /** How long an unreferenced watcher is kept, so a reconnecting frontend can reuse it. */
+    readonly deferredDisposalTimeout: number;
+}
+export declare namespace NodeDirectoryWatcherTimings {
+    /** Every delay drives a `setTimeout`, where anything below 1ms silently becomes 1ms. */
+    function validate(timings: NodeDirectoryWatcherTimings): void;
+}
+export declare const DEFAULT_WATCHER_TIMINGS: NodeDirectoryWatcherTimings;
+interface PendingEvent {
+    eventType: string;
+    fileName: string | undefined;
+}
+/** What the events of one batch share: one directory read, and one timer for the deletions they defer. */
+interface EventBatch {
+    /** The child's name on disk, which can differ from `fileName` in case, or `undefined` if there is none. */
+    storedName(fileName: string): Promise<string | undefined>;
+    scheduleDelete(fileName: string): void;
+}
+/**
+ * Watches one directory level with Node's `fs.watch`.
+ *
+ * One instance serves every non-recursive request resolving to the same directory, for the directory itself
+ * or for a single file in it. Sharing saves more than handles: on macOS libuv keeps one `FSEventStream` per
+ * event loop and rebuilds it whenever a handle opens or closes, losing every other watcher's events.
+ */
+export declare class NodeDirectoryWatcher extends AbstractFileSystemWatcher {
+    protected readonly client: FileSystemWatcherServiceClient;
+    protected readonly timings: NodeDirectoryWatcherTimings;
+    protected readonly host: WatcherHost;
+    protected watchedDirectory: string;
+    /** The path polled and resolved on each start: the target, or its directory once it turned out to be a file. */
+    protected watchPath: string;
+    private handle;
+    /** The identity of the directory the handle is bound to, read before it opened. */
+    private identity;
+    /** Direct children of {@link watchedDirectory}, kept in sync to classify changes and to diff a rescan. */
+    protected children: Set<string>;
+    /** Set once a start recorded the children. Until then, what clients saw of them is unknown. */
+    private started;
+    /** The directory that {@link children} list, which a re-key can move {@link watchedDirectory} away from. */
+    private childrenDirectory;
+    /** The children clients last saw. Kept until a restart reports its diff, so a superseded restart passes it on. */
+    private restartBaseline;
+    /** Set once the watched path is found missing, until a start finds it. Changes wait for that start meanwhile. */
+    private watchedPathMissing;
+    /** The directory last announced through {@link onDidResolveDirectory}, which the provider keys the watcher by. */
+    private announcedDirectory;
+    protected readonly router: WatchRequestRouter;
+    private readonly pendingEvents;
+    private readonly pendingDeletes;
+    private changeQueue;
+    /** Names from `rename` events that arrive while {@link readChildren} runs, else `undefined`. */
+    private renamedDuringRead;
+    /** Collects raw events for one `changeDelay` window, counted from the first. */
+    private readonly scheduleFlush;
+    /** Cancels the start attempt in flight, so a superseded one opens no handle. */
+    private attempt;
+    private disposalTimer;
+    private openFailed;
+    private readonly directoryResolvedEmitter;
+    /** Fires when {@link directory} changes, for example when a missing target appears as a file. */
+    readonly onDidResolveDirectory: import("@theia/core").Event<void>;
+    /** Resolves once the watcher is up, or once it got disposed while starting. Never rejects. */
+    readonly whenStarted: Promise<void>;
+    constructor(target: string, options: WatcherLogger, client: FileSystemWatcherServiceClient, timings?: NodeDirectoryWatcherTimings, host?: WatcherHost);
+    /** The directory the handle is on, settled once {@link whenStarted} resolved. */
+    get directory(): string;
+    /** Drains the requests, so that they can be moved to the watcher serving their directory. */
+    takeRequests(): Map<number, DirectoryWatchRequest>;
+    /**
+     * Serves requests that a re-key moved here. After the work queued before them runs, each hears where its path
+     * differs from what it takes it for.
+     */
+    adoptRequests(requests: Map<number, DirectoryWatchRequest>): void;
+    protected createRouter(): WatchRequestRouter;
+    addRequest(watcherId: number, request: DirectoryWatchRequest): void;
+    removeRequest(watcherId: number): void;
+    dispose(): void;
+    /** Waits for the target, then opens the handle before reading the children, so no change is missed. */
+    protected start(token: CancellationToken): Promise<void>;
+    /** Polls until the target exists as a directory to watch and a handle is open. */
+    protected openWhenAvailable(token: CancellationToken): Promise<void>;
+    /** Records the watched path as missing, and tells each request that takes its path for existing. */
+    private reportLoss;
+    /** Tells each request where its own path differs from what the watcher last found, whenever it joined. */
+    private reconcile;
+    /**
+     * Reads the children. A child renamed during the read keeps its membership in `known`, as the read can list it
+     * or not, and its own event reports it. Only a `rename` announces a creation or a deletion.
+     */
+    private readChildren;
+    /**
+     * Resolves the target to the directory to watch. Requests made while the target was missing are resolved
+     * here too, and narrowed to the file if the target is one.
+     * @returns `false` if the path is a file that the watcher cannot follow to its parent.
+     */
+    protected resolveWatchedDirectory(): Promise<boolean>;
+    protected openHandle(): boolean;
+    private closeHandle;
+    protected handleEvent(eventType: string, fileName: string | null): void;
+    private flush;
+    /** Serializes the async parts of change handling so later events cannot overtake earlier ones. */
+    private enqueue;
+    protected processEvents(events: PendingEvent[]): Promise<ResolvedChange[]>;
+    /**
+     * @returns `true` if an event names the watched directory itself rather than a child. macOS reports such an
+     * event for any change inside, so {@link isWatchedDirectoryGone} decides whether the directory is gone. A
+     * new child with the same name is not in {@link children} yet, so the disk rules it out.
+     */
+    protected namesWatchedDirectory(fileName: string, batch: EventBatch): Promise<boolean>;
+    /** The change this rename resolves to, or `undefined` when it is deferred to the delete timer. */
+    protected resolveRename(fileName: string, batch: EventBatch): Promise<ResolvedChange | undefined>;
+    /** Records a child found on disk: an update if it was known, an addition if not. */
+    private recordPresent;
+    /** A new {@link EventBatch}. Where names ignore case, its lookups share one directory read. */
+    protected createBatch(): EventBatch;
+    /**
+     * A deletion is confirmed rather than reported right away: tools that save atomically delete and recreate
+     * the file, which would otherwise surface as a deletion followed by an addition. The deletions of one batch
+     * share a timer, created on first use, so that they are confirmed with one directory read as well.
+     */
+    private deleteScheduler;
+    /** Leaves the shared timer running: it confirms only the names still waiting on it. */
+    private cancelDelete;
+    private clearPendingDeletes;
+    /**
+     * Confirms the deletions of `scheduled` still waiting on `timer`. A deletion cancelled meanwhile is no longer on
+     * it. Only the names this timer scheduled are checked, so each confirmation costs its own batch, not every pending one.
+     */
+    protected confirmDeletes(timer: NodeJS.Timeout, scheduled: readonly string[]): Promise<ResolvedChange[]>;
+    protected confirmDelete(fileName: string, storedName: EventBatch['storedName']): Promise<ResolvedChange[]>;
+    /**
+     * Compares identity rather than mere existence: a directory that is deleted and recreated leaves the handle
+     * bound to the old inode, where it would never report anything again.
+     */
+    protected isWatchedDirectoryGone(): Promise<boolean>;
+    /** Closes the handle and starts over, reporting the watched paths as deleted if the directory is gone. */
+    protected restart(error?: unknown): void;
+    /** Deletions come first, so a case-only rename resolves to an update for a request for the file. */
+    protected diff(previous: Set<string>, current: Set<string>): ResolvedChange[];
+}
+/** Serves non-recursive requests. Those resolving to the same directory share one watcher, file or folder alike. */
+export declare class DirectoryWatcherProvider extends AbstractWatcherProvider {
+    protected readonly options: WatcherLogger;
+    protected readonly client: FileSystemWatcherServiceClient;
+    protected readonly timings?: NodeDirectoryWatcherTimings | undefined;
+    /** Shared, so every watcher this provider makes resolves paths the same way. */
+    protected readonly host: WatcherHost;
+    constructor(options: WatcherLogger, client: FileSystemWatcherServiceClient, timings?: NodeDirectoryWatcherTimings | undefined, 
+    /** Shared, so every watcher this provider makes resolves paths the same way. */
+    host?: WatcherHost);
+    canHandle(options: ResolvedWatchOptions): boolean;
+    watch(watcherId: number, request: WatchRequest): Promise<void>;
+    /** While the path does not exist, `directory` is a guess, so re-key the watcher once it resolves. */
+    protected createRekeyingWatcher(directory: string): NodeDirectoryWatcher;
+    /** Moves a watcher to the key of the directory it resolved to, or hands its requests to the one there. */
+    protected rekeyWatcher(watcher: NodeDirectoryWatcher): void;
+    /** Excludes are left out: one level has nothing to prune, so they apply per request. */
+    protected watcherKey(directory: string): string;
+    protected createWatcher(directory: string): NodeDirectoryWatcher;
+}
+export {};
+//# sourceMappingURL=node-directory-watcher.d.ts.map

package/lib/node/nodejs-watcher/node-directory-watcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-directory-watcher.d.ts","sourceRoot":"","sources":["../../../src/node/nodejs-watcher/node-directory-watcher.ts"],"names":[],"mappings":"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"}