|
| 1 | +// Type definitions for @atom/watcher 1.3 |
| 2 | +// Project: https://github.com/atom/watcher |
| 3 | +// Definitions by: LoganDark <https://github.com/LoganDark> |
| 4 | +// Jan Vlnas <https://github.com/jnv> |
| 5 | +// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped |
| 6 | + |
| 7 | +import { Disposable } from 'event-kit'; |
| 8 | + |
| 9 | +export const DISABLE: unique symbol; |
| 10 | +export const STDOUT: unique symbol; |
| 11 | +export const STDERR: unique symbol; |
| 12 | + |
| 13 | +/** |
| 14 | + * May be one of: |
| 15 | + * |
| 16 | + * - A `string` specifying a path to log to a file. Be careful that you don't log to a directory that you're watching! |
| 17 | + * - The constants {@link STDERR} or {@link STDOUT} to log to the node process' standard error or output streams. |
| 18 | + * - {@link DISABLE} to disable logging. |
| 19 | + */ |
| 20 | +export type LogTarget = string | typeof DISABLE | typeof STDOUT | typeof STDERR; |
| 21 | + |
| 22 | +export interface WatcherSettings { |
| 23 | + /** |
| 24 | + * Configures the logging of events from the JavaScript layer. Defaults to {@link DISABLE}. |
| 25 | + */ |
| 26 | + jsLog: LogTarget; |
| 27 | + |
| 28 | + /** |
| 29 | + * Configures the logging of events from the main thread, in line with `libuv`'s event loop. |
| 30 | + * The default is {@link DISABLE}. |
| 31 | + */ |
| 32 | + mainLog: LogTarget; |
| 33 | + |
| 34 | + /** |
| 35 | + * Configures logging for the worker thread, which is used to interact with native operating system filesystem |
| 36 | + * watching APIs. The default is {@link DISABLE}. |
| 37 | + */ |
| 38 | + workerLog: LogTarget; |
| 39 | + |
| 40 | + /** |
| 41 | + * Configures the logging for the polling thread, which polls the filesystem when the worker thread is unable to. |
| 42 | + * The default is {@link DISABLE}. |
| 43 | + */ |
| 44 | + pollingLog: LogTarget; |
| 45 | + |
| 46 | + /** |
| 47 | + * Controls the number of recently seen stat results are cached within the worker thread. |
| 48 | + * Increasing the cache size will improve the reliability of rename correlation and the |
| 49 | + * entry kinds of deleted entries, but will consume more RAM. The default is `4096`. |
| 50 | + */ |
| 51 | + workerCacheSize: number; |
| 52 | + |
| 53 | + /** |
| 54 | + * Controls the rough number of filesystem-touching system calls (`lstat()` and `readdir()`) |
| 55 | + * performed by the polling thread on each polling cycle. Increasing the throttle will improve the timeliness |
| 56 | + * of polled events, especially when watching large directory trees, but will consume more processor cycles and |
| 57 | + * I/O bandwidth. The throttle defaults to `1000`. |
| 58 | + */ |
| 59 | + pollingThrottle: number; |
| 60 | + |
| 61 | + /** |
| 62 | + * Adjusts the time in milliseconds that the polling thread spends sleeping between polling cycles. |
| 63 | + * Decreasing the interval will improve the timeliness of polled events, but will consume more processor |
| 64 | + * cycles and I/O bandwidth. The interval defaults to `100`. |
| 65 | + */ |
| 66 | + pollingInterval: number; |
| 67 | +} |
| 68 | + |
| 69 | +export interface WatcherOptions { |
| 70 | + /** |
| 71 | + * If `true`, filesystem events that occur within subdirectories will be reported as well. |
| 72 | + * If `false`, only changes to immediate children of the provided path will be reported. |
| 73 | + * Defaults to `true`. |
| 74 | + */ |
| 75 | + recursive: boolean; |
| 76 | +} |
| 77 | + |
| 78 | +export type EntryAction = 'created' | 'modified' | 'deleted' | 'renamed'; |
| 79 | +export type EntryType = 'file' | 'directory' | 'symlink' | 'unknown'; |
| 80 | + |
| 81 | +export interface BaseEvent { |
| 82 | + /** |
| 83 | + * A string describing the filesystem action that occurred. |
| 84 | + */ |
| 85 | + action: EntryAction; |
| 86 | + |
| 87 | + /** |
| 88 | + * A string distinguishing the type of filesystem entry that was acted upon, if known. |
| 89 | + */ |
| 90 | + kind: EntryType; |
| 91 | + |
| 92 | + /** |
| 93 | + * A string containing the absolute path to the filesystem entry that was acted upon. |
| 94 | + * In the event of a rename, this is the *new* path of the entry. |
| 95 | + */ |
| 96 | + path: string; |
| 97 | +} |
| 98 | + |
| 99 | +export interface OtherEvent extends BaseEvent { |
| 100 | + action: Exclude<EntryAction, 'renamed'>; |
| 101 | +} |
| 102 | + |
| 103 | +export interface RenamedEvent extends BaseEvent { |
| 104 | + action: 'renamed'; |
| 105 | + |
| 106 | + /** |
| 107 | + * A string containing the former absolute path of a renamed filesystem entry. |
| 108 | + */ |
| 109 | + oldPath: string; |
| 110 | +} |
| 111 | + |
| 112 | +export type Event = RenamedEvent | OtherEvent; |
| 113 | +export type EventConsumer = (events: Event[]) => unknown; |
| 114 | + |
| 115 | +export class PathWatcher { |
| 116 | + private constructor(nativeWatcherRegistry: unknown, watchedPath: string, options: WatcherOptions); |
| 117 | + |
| 118 | + getOptions(): WatcherOptions; |
| 119 | + |
| 120 | + /** |
| 121 | + * Extended: Return a Promise that will resolve when the underlying native watcher is ready to begin sending |
| 122 | + * events. When testing filesystem watchers, it's important to await this promise before making filesystem changes |
| 123 | + * that you intend to assert about because there will be a delay between the instantiation of the watcher and |
| 124 | + * the activation of the underlying OS resources that feed it events. |
| 125 | + * |
| 126 | + * PathWatchers acquired through `watchPath` are already started. |
| 127 | + */ |
| 128 | + getStartPromise(): Promise<void>; |
| 129 | + |
| 130 | + /** |
| 131 | + * Invoke a callback with any errors that occur after the watcher has been installed successfully. |
| 132 | + * |
| 133 | + * The `callback` argument will be invoked with an `Error` with a stack trace that likely isn't very |
| 134 | + * helpful and a message that hopefully is. |
| 135 | + */ |
| 136 | + onDidError(callback: (err: unknown) => unknown): Disposable; |
| 137 | + |
| 138 | + /** |
| 139 | + * Release an event subscription. The event callback associated with this `PathWatcher` will not be called after |
| 140 | + * the watcher has been disposed, synchronously. Note that the native resources or polling root used to feed events |
| 141 | + * to this watcher may remain, if another active `PathWatcher` is consuming events from it, and even if they are |
| 142 | + * freed as a result of this disposal they will be freed asynchronously. |
| 143 | + * |
| 144 | + * Extended: Unsubscribe all subscribers from filesystem events. Native resources will be release asynchronously, |
| 145 | + * but this watcher will stop broadcasting events immediately. |
| 146 | + */ |
| 147 | + dispose(): void; |
| 148 | + |
| 149 | + /** |
| 150 | + * Extended: Print the directory that this watcher is watching. |
| 151 | + */ |
| 152 | + toString(): string; |
| 153 | +} |
| 154 | + |
| 155 | +/** |
| 156 | + * Invoke a callback with each batch of filesystem events that occur beneath a specified directory. |
| 157 | + * |
| 158 | + * The returned `Promise` resolves to a `PathWatcher` instance when the watcher is fully installed and events are |
| 159 | + * flowing. The `Promise` may reject if the path does not exist, is not a directory, or if an operating system error |
| 160 | + * prevented the watcher from successfully initializing, like a thread failing to launch or memory being exhausted. |
| 161 | + * |
| 162 | + * The *path* argument specifies the root directory to watch. This must be an existing directory, but may be relative, |
| 163 | + * contain symlinks, or contain `.` and `..` segments. Multiple independent calls to `watchPath()` may result in |
| 164 | + * `PathWatcher` instances backed by the same native event source or polling root, so it is relatively cheap to create |
| 165 | + * many watchers within the same directory hierarchy across your codebase. |
| 166 | + * |
| 167 | + * The callback *may* be invoked for filesystem events that occur before the promise is resolved, but it *will* be |
| 168 | + * invoked for any changes that occur after it resolves. |
| 169 | + * |
| 170 | + * *When writing tests against code that uses `watchPath`, note that you cannot easily assert that an event was not |
| 171 | + * delivered. This is especially true on MacOS, where timestamp resolution can cause you to receive events that |
| 172 | + * occurred before you even issued the `watchPath` call!* |
| 173 | + */ |
| 174 | +export function watchPath( |
| 175 | + path: string, |
| 176 | + options: Partial<WatcherOptions>, |
| 177 | + consumer: EventConsumer, |
| 178 | +): Promise<PathWatcher>; |
| 179 | + |
| 180 | +/** |
| 181 | + * Tweak package-global settings. This method may be called even after watchers have been started. The `Promise` |
| 182 | + * it returns resolves when all changed settings have taken effect. All configuration settings are optional. Omitted keys are left unchanged. |
| 183 | + */ |
| 184 | +export function configure(settings: Partial<WatcherSettings>): Promise<void>; |
0 commit comments