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

package/lib/node/filesystem-watcher.d.ts

@@ -0,0 +1,93 @@
+import { WatchOptions } from '../common/filesystem-watcher-protocol';
+/** How a watcher reports what it is doing. */
+export interface WatcherLogger {
+    verbose: boolean;
+    info: (message: string, ...args: unknown[]) => void;
+    error: (message: string, ...args: unknown[]) => void;
+}
+/** A single client request served by a {@link FileSystemWatcher}. */
+export interface WatchRequest {
+    /** Client to route the changes of this request to. */
+    readonly clientId: number;
+    /** Path as requested by the client. Change URIs are built from it, never from the real path. */
+    readonly path: string;
+    /** Exclude patterns of this request alone. */
+    readonly ignored: readonly string[];
+}
+/** A watch shared by every request that resolves to the same target. Implementations decide whether it recurses. */
+export interface FileSystemWatcher {
+    /** A disposed watcher released its resources and must not be given further requests. */
+    readonly isDisposed: boolean;
+    /** Resolves once this watcher disposed itself. Never rejects. */
+    readonly whenDisposed: Promise<void>;
+    /** Serves `request` until {@link removeRequest} is called with the same `watcherId`. */
+    addRequest(watcherId: number, request: WatchRequest): void;
+    /** Releases a request. The watcher disposes itself once it has none left. */
+    removeRequest(watcherId: number): void;
+}
+/** Handles disposal and logging for a watcher. Subclasses decide how to observe the file system. */
+export declare abstract class AbstractFileSystemWatcher implements FileSystemWatcher {
+    /** Path this watcher was asked about; the subclass decides what it resolves to. */
+    protected readonly target: string;
+    private readonly logger;
+    private static debugIdSequence;
+    private readonly debugId;
+    private readonly disposalDeferred;
+    private readonly disposal;
+    readonly whenDisposed: Promise<void>;
+    constructor(
+    /** Path this watcher was asked about; the subclass decides what it resolves to. */
+    target: string, logger: WatcherLogger);
+    get isDisposed(): boolean;
+    abstract addRequest(watcherId: number, request: WatchRequest): void;
+    abstract removeRequest(watcherId: number): void;
+    /**
+     * Marks this watcher disposed.
+     * @returns `false` if it already was, in which case the caller must not clean up again.
+     */
+    protected markDisposed(): boolean;
+    /** Logs as-is. Unlike {@link info} it is not prefixed, since these messages name their own path. */
+    protected error(message: string, ...params: unknown[]): void;
+    protected info(prefix: string, ...params: unknown[]): void;
+    protected debug(prefix: string, ...params: unknown[]): void;
+}
+export type ResolvedWatchOptions = Required<WatchOptions>;
+/** Serves either recursive or non-recursive requests, and decides which watcher serves each one. */
+export interface WatcherProvider {
+    /** @returns `true` if this provider serves requests made with these options. */
+    canHandle(options: ResolvedWatchOptions): boolean;
+    /** Serves `request` under `watcherId`, on a watcher shared with requests resolving to the same target. */
+    watch(watcherId: number, request: WatchRequest): Promise<void>;
+    /**
+     * Releases the request registered under `watcherId`.
+     * @returns `true` if this provider served the request.
+     */
+    unwatch(watcherId: number): boolean;
+}
+/** A {@link WatcherProvider} that keeps one watcher per target. Subclasses decide which key a target maps to. */
+export declare abstract class AbstractWatcherProvider implements WatcherProvider {
+    private readonly watchersByTarget;
+    /** The watcher that serves each request, by `watcherId`. */
+    private readonly watchersByRequest;
+    /** Every watcher this provider currently has open. */
+    protected get activeWatchers(): readonly FileSystemWatcher[];
+    abstract canHandle(options: ResolvedWatchOptions): boolean;
+    abstract watch(watcherId: number, request: WatchRequest): Promise<void>;
+    unwatch(watcherId: number): boolean;
+    /** The watcher serving a request, if this provider has one. */
+    protected watcherFor(watcherId: number): FileSystemWatcher | undefined;
+    /** Puts a request on a watcher and records which one, so {@link unwatch} finds it again. */
+    protected serve(watcherId: number, watcher: FileSystemWatcher, request: WatchRequest): void;
+    /** Records the watcher of a request that reached it without {@link serve}, such as through a re-key. */
+    protected assign(watcherId: number, watcher: FileSystemWatcher): void;
+    /**
+     * Returns the watcher under `watcherKey`, or creates one. A disposed watcher stays in the map until a later
+     * promise callback removes it, so it is replaced here rather than handed a new request.
+     */
+    protected getOrCreateWatcher<T extends FileSystemWatcher>(watcherKey: string, create: () => T): T;
+    /** @returns `true` if `watcher` is the one registered under `watcherKey`. */
+    protected isRegisteredAs(watcher: FileSystemWatcher, watcherKey: string): boolean;
+    /** Forgets every key a watcher is registered under, so that it can be registered under another. */
+    protected unregisterWatcher(watcher: FileSystemWatcher): void;
+}
+//# sourceMappingURL=filesystem-watcher.d.ts.map

package/lib/node/filesystem-watcher.d.ts.map

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

package/lib/node/filesystem-watcher.js

@@ -0,0 +1,134 @@
+"use strict";
+// *****************************************************************************
+// Copyright (C) 2026 Ehab Younes and others.
+//
+// This program and the accompanying materials are made available under the
+// terms of the Eclipse Public License v. 2.0 which is available at
+// http://www.eclipse.org/legal/epl-2.0.
+//
+// This Source Code may also be made available under the following Secondary
+// Licenses when the conditions for such availability set forth in the Eclipse
+// Public License v. 2.0 are satisfied: GNU General Public License, version 2
+// with the GNU Classpath Exception which is available at
+// https://www.gnu.org/software/classpath/license.html.
+//
+// SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
+// *****************************************************************************
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AbstractWatcherProvider = exports.AbstractFileSystemWatcher = void 0;
+const promise_util_1 = require("@theia/core/lib/common/promise-util");
+const cancellation_1 = require("@theia/core/lib/common/cancellation");
+/** Handles disposal and logging for a watcher. Subclasses decide how to observe the file system. */
+class AbstractFileSystemWatcher {
+    static { this.debugIdSequence = 0; }
+    constructor(
+    /** Path this watcher was asked about; the subclass decides what it resolves to. */
+    target, logger) {
+        this.target = target;
+        this.logger = logger;
+        this.debugId = AbstractFileSystemWatcher.debugIdSequence++;
+        this.disposalDeferred = new promise_util_1.Deferred();
+        this.disposal = new cancellation_1.CancellationTokenSource();
+        this.whenDisposed = this.disposalDeferred.promise;
+    }
+    get isDisposed() {
+        return this.disposal.token.isCancellationRequested;
+    }
+    /**
+     * Marks this watcher disposed.
+     * @returns `false` if it already was, in which case the caller must not clean up again.
+     */
+    markDisposed() {
+        if (this.isDisposed) {
+            return false;
+        }
+        this.disposal.cancel();
+        this.disposalDeferred.resolve();
+        return true;
+    }
+    /** Logs as-is. Unlike {@link info} it is not prefixed, since these messages name their own path. */
+    error(message, ...params) {
+        this.logger.error(message, ...params);
+    }
+    info(prefix, ...params) {
+        this.logger.info(`${prefix} ${this.constructor.name}(${this.debugId} at "${this.target}"):`, ...params);
+    }
+    debug(prefix, ...params) {
+        if (this.logger.verbose) {
+            this.info(prefix, ...params);
+        }
+    }
+}
+exports.AbstractFileSystemWatcher = AbstractFileSystemWatcher;
+/** A {@link WatcherProvider} that keeps one watcher per target. Subclasses decide which key a target maps to. */
+class AbstractWatcherProvider {
+    constructor() {
+        this.watchersByTarget = new Map();
+        /** The watcher that serves each request, by `watcherId`. */
+        this.watchersByRequest = new Map();
+    }
+    /** Every watcher this provider currently has open. */
+    get activeWatchers() {
+        return Array.from(this.watchersByTarget.values());
+    }
+    unwatch(watcherId) {
+        const watcher = this.watchersByRequest.get(watcherId);
+        if (!watcher) {
+            return false;
+        }
+        this.watchersByRequest.delete(watcherId);
+        watcher.removeRequest(watcherId);
+        return true;
+    }
+    /** The watcher serving a request, if this provider has one. */
+    watcherFor(watcherId) {
+        return this.watchersByRequest.get(watcherId);
+    }
+    /** Puts a request on a watcher and records which one, so {@link unwatch} finds it again. */
+    serve(watcherId, watcher, request) {
+        watcher.addRequest(watcherId, request);
+        this.assign(watcherId, watcher);
+    }
+    /** Records the watcher of a request that reached it without {@link serve}, such as through a re-key. */
+    assign(watcherId, watcher) {
+        this.watchersByRequest.set(watcherId, watcher);
+    }
+    /**
+     * Returns the watcher under `watcherKey`, or creates one. A disposed watcher stays in the map until a later
+     * promise callback removes it, so it is replaced here rather than handed a new request.
+     */
+    getOrCreateWatcher(watcherKey, create) {
+        const existing = this.watchersByTarget.get(watcherKey);
+        if (existing && !existing.isDisposed) {
+            return existing;
+        }
+        const watcher = create();
+        this.watchersByTarget.set(watcherKey, watcher);
+        watcher.whenDisposed.then(() => {
+            if (this.watchersByTarget.get(watcherKey) === watcher) {
+                this.watchersByTarget.delete(watcherKey);
+            }
+            // Requests it handed to another watcher already point there, so drop only the ones still on it.
+            for (const [watcherId, serving] of this.watchersByRequest) {
+                if (serving === watcher) {
+                    this.watchersByRequest.delete(watcherId);
+                }
+            }
+        });
+        return watcher;
+    }
+    /** @returns `true` if `watcher` is the one registered under `watcherKey`. */
+    isRegisteredAs(watcher, watcherKey) {
+        return this.watchersByTarget.get(watcherKey) === watcher;
+    }
+    /** Forgets every key a watcher is registered under, so that it can be registered under another. */
+    unregisterWatcher(watcher) {
+        for (const [watcherKey, registered] of this.watchersByTarget) {
+            if (registered === watcher) {
+                this.watchersByTarget.delete(watcherKey);
+            }
+        }
+    }
+}
+exports.AbstractWatcherProvider = AbstractWatcherProvider;
+//# sourceMappingURL=filesystem-watcher.js.map

package/lib/node/filesystem-watcher.js.map

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

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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"}