1 | // TypeScript Version: 3.0
|
2 |
|
3 | /// <reference types="node" />
|
4 |
|
5 | import * as fs from "fs";
|
6 | import { EventEmitter } from "events";
|
7 |
|
8 | /**
|
9 | * The object's keys are all the directories (using absolute paths unless the `cwd` option was
|
10 | * used), and the values are arrays of the names of the items contained in each directory.
|
11 | */
|
12 | export interface WatchedPaths {
|
13 | [directory: string]: string[];
|
14 | }
|
15 |
|
16 | export class FSWatcher extends EventEmitter implements fs.FSWatcher {
|
17 | /**
|
18 | * Constructs a new FSWatcher instance with optional WatchOptions parameter.
|
19 | */
|
20 | constructor(options?: WatchOptions);
|
21 |
|
22 | /**
|
23 | * Add files, directories, or glob patterns for tracking. Takes an array of strings or just one
|
24 | * string.
|
25 | */
|
26 | add(paths: string | string[]): void;
|
27 |
|
28 | /**
|
29 | * Stop watching files, directories, or glob patterns. Takes an array of strings or just one
|
30 | * string.
|
31 | */
|
32 | unwatch(paths: string | string[]): void;
|
33 |
|
34 | /**
|
35 | * Returns an object representing all the paths on the file system being watched by this
|
36 | * `FSWatcher` instance. The object's keys are all the directories (using absolute paths unless
|
37 | * the `cwd` option was used), and the values are arrays of the names of the items contained in
|
38 | * each directory.
|
39 | */
|
40 | getWatched(): WatchedPaths;
|
41 |
|
42 | /**
|
43 | * Removes all listeners from watched files.
|
44 | */
|
45 | close(): void;
|
46 |
|
47 | on(event: 'add'|'addDir'|'change', listener: (path: string, stats?: fs.Stats) => void): this;
|
48 |
|
49 | on(event: 'all', listener: (eventName: 'add'|'addDir'|'change'|'unlink'|'unlinkDir', path: string, stats?: fs.Stats) => void): this;
|
50 |
|
51 | /**
|
52 | * Error occured
|
53 | */
|
54 | on(event: 'error', listener: (error: Error) => void): this;
|
55 |
|
56 | /**
|
57 | * Exposes the native Node `fs.FSWatcher events`
|
58 | */
|
59 | on(event: 'raw', listener: (eventName: string, path: string, details: any) => void): this;
|
60 |
|
61 | /**
|
62 | * Fires when the initial scan is complete
|
63 | */
|
64 | on(event: 'ready', listener: () => void): this;
|
65 |
|
66 | on(event: 'unlink'|'unlinkDir', listener: (path: string) => void): this;
|
67 |
|
68 | on(event: string, listener: (...args: any[]) => void): this;
|
69 | }
|
70 |
|
71 | export interface WatchOptions {
|
72 | /**
|
73 | * Indicates whether the process should continue to run as long as files are being watched. If
|
74 | * set to `false` when using `fsevents` to watch, no more events will be emitted after `ready`,
|
75 | * even if the process continues to run.
|
76 | */
|
77 | persistent?: boolean;
|
78 |
|
79 | /**
|
80 | * ([anymatch](https://github.com/es128/anymatch)-compatible definition) Defines files/paths to
|
81 | * be ignored. The whole relative or absolute path is tested, not just filename. If a function
|
82 | * with two arguments is provided, it gets called twice per path - once with a single argument
|
83 | * (the path), second time with two arguments (the path and the
|
84 | * [`fs.Stats`](http://nodejs.org/api/fs.html#fs_class_fs_stats) object of that path).
|
85 | */
|
86 | ignored?: any;
|
87 |
|
88 | /**
|
89 | * If set to `false` then `add`/`addDir` events are also emitted for matching paths while
|
90 | * instantiating the watching as chokidar discovers these file paths (before the `ready` event).
|
91 | */
|
92 | ignoreInitial?: boolean;
|
93 |
|
94 | /**
|
95 | * When `false`, only the symlinks themselves will be watched for changes instead of following
|
96 | * the link references and bubbling events through the link's path.
|
97 | */
|
98 | followSymlinks?: boolean;
|
99 |
|
100 | /**
|
101 | * The base directory from which watch `paths` are to be derived. Paths emitted with events will
|
102 | * be relative to this.
|
103 | */
|
104 | cwd?: string;
|
105 |
|
106 | /**
|
107 | * If set to true then the strings passed to .watch() and .add() are treated as literal path
|
108 | * names, even if they look like globs. Default: false.
|
109 | */
|
110 | disableGlobbing?: boolean;
|
111 |
|
112 | /**
|
113 | * Whether to use fs.watchFile (backed by polling), or fs.watch. If polling leads to high CPU
|
114 | * utilization, consider setting this to `false`. It is typically necessary to **set this to
|
115 | * `true` to successfully watch files over a network**, and it may be necessary to successfully
|
116 | * watch files in other non-standard situations. Setting to `true` explicitly on OS X overrides
|
117 | * the `useFsEvents` default.
|
118 | */
|
119 | usePolling?: boolean;
|
120 |
|
121 | /**
|
122 | * Whether to use the `fsevents` watching interface if available. When set to `true` explicitly
|
123 | * and `fsevents` is available this supercedes the `usePolling` setting. When set to `false` on
|
124 | * OS X, `usePolling: true` becomes the default.
|
125 | */
|
126 | useFsEvents?: boolean;
|
127 |
|
128 | /**
|
129 | * If relying upon the [`fs.Stats`](http://nodejs.org/api/fs.html#fs_class_fs_stats) object that
|
130 | * may get passed with `add`, `addDir`, and `change` events, set this to `true` to ensure it is
|
131 | * provided even in cases where it wasn't already available from the underlying watch events.
|
132 | */
|
133 | alwaysStat?: boolean;
|
134 |
|
135 | /**
|
136 | * If set, limits how many levels of subdirectories will be traversed.
|
137 | */
|
138 | depth?: number;
|
139 |
|
140 | /**
|
141 | * Interval of file system polling.
|
142 | */
|
143 | interval?: number;
|
144 |
|
145 | /**
|
146 | * Interval of file system polling for binary files. ([see list of binary extensions](https://gi
|
147 | * thub.com/sindresorhus/binary-extensions/blob/master/binary-extensions.json))
|
148 | */
|
149 | binaryInterval?: number;
|
150 |
|
151 | /**
|
152 | * Indicates whether to watch files that don't have read permissions if possible. If watching
|
153 | * fails due to `EPERM` or `EACCES` with this set to `true`, the errors will be suppressed
|
154 | * silently.
|
155 | */
|
156 | ignorePermissionErrors?: boolean;
|
157 |
|
158 | /**
|
159 | * `true` if `useFsEvents` and `usePolling` are `false`). Automatically filters out artifacts
|
160 | * that occur when using editors that use "atomic writes" instead of writing directly to the
|
161 | * source file. If a file is re-added within 100 ms of being deleted, Chokidar emits a `change`
|
162 | * event rather than `unlink` then `add`. If the default of 100 ms does not work well for you,
|
163 | * you can override it by setting `atomic` to a custom value, in milliseconds.
|
164 | */
|
165 | atomic?: boolean | number;
|
166 |
|
167 | /**
|
168 | * can be set to an object in order to adjust timing params:
|
169 | */
|
170 | awaitWriteFinish?: AwaitWriteFinishOptions | boolean;
|
171 | }
|
172 |
|
173 | export interface AwaitWriteFinishOptions {
|
174 | /**
|
175 | * Amount of time in milliseconds for a file size to remain constant before emitting its event.
|
176 | */
|
177 | stabilityThreshold?: number;
|
178 |
|
179 | /**
|
180 | * File size polling interval.
|
181 | */
|
182 | pollInterval?: number;
|
183 | }
|
184 |
|
185 | /**
|
186 | * produces an instance of `FSWatcher`.
|
187 | */
|
188 | export function watch(
|
189 | paths: string | string[],
|
190 | options?: WatchOptions
|
191 | ): FSWatcher;
|