UNPKG

3.43 kBTypeScriptView Raw
1import { ReadStream, WriteStream } from 'fs';
2import { Disposable } from '../../../index';
3import { Directory } from './directory';
4
5/** Represents an individual file that can be watched, read from, and written to. */
6export class File {
7 // Construction
8 /** Configures a new File instance, no files are accessed. */
9 constructor(filePath: string, symlink?: boolean);
10
11 /**
12 * Creates the file on disk that corresponds to ::getPath() if no such file
13 * already exists.
14 */
15 create(): Promise<boolean>;
16
17 // Event Subscription
18 /** Invoke the given callback when the file's contents change. */
19 onDidChange(callback: () => void): Disposable;
20
21 /** Invoke the given callback when the file's path changes. */
22 onDidRename(callback: () => void): Disposable;
23
24 /** Invoke the given callback when the file is deleted. */
25 onDidDelete(callback: () => void): Disposable;
26
27 /**
28 * Invoke the given callback when there is an error with the watch. When
29 * your callback has been invoked, the file will have unsubscribed from the
30 * file watches.
31 */
32 onWillThrowWatchError(callback: (event: PathWatchErrorThrownEvent) => void): Disposable;
33
34 // File Metadata
35 /** Returns a boolean, always true. */
36 isFile(): this is File;
37
38 /** Returns a boolean, always false. */
39 isDirectory(): this is Directory;
40
41 /** Returns a boolean indicating whether or not this is a symbolic link. */
42 isSymbolicLink(): boolean;
43
44 /**
45 * Returns a promise that resolves to a boolean, true if the file exists,
46 * false otherwise.
47 */
48 exists(): Promise<boolean>;
49
50 /** Returns a boolean, true if the file exists, false otherwise. */
51 existsSync(): boolean;
52
53 /** Get the SHA-1 digest of this file. */
54 getDigest(): Promise<string>;
55
56 /** Get the SHA-1 digest of this file. */
57 getDigestSync(): string;
58
59 /** Sets the file's character set encoding name. */
60 setEncoding(encoding: string): void;
61
62 /** Returns the string encoding name for this file (default: "utf8"). */
63 getEncoding(): string;
64
65 // Managing Paths
66 /** Returns the string path for the file. */
67 getPath(): string;
68
69 /** Returns this file's completely resolved string path. */
70 getRealPathSync(): string;
71
72 /**
73 * Returns a promise that resolves to the file's completely resolved
74 * string path.
75 */
76 getRealPath(): Promise<string>;
77
78 /** Return the string filename without any directory information. */
79 getBaseName(): string;
80
81 // Traversing
82 /** Return the Directory that contains this file. */
83 getParent(): Directory;
84
85 // Reading and Writing
86 /** Reads the contents of the file. */
87 read(flushCache?: boolean): Promise<string | null>;
88
89 /** Returns a stream to read the content of the file. */
90 createReadStream(): ReadStream;
91
92 /** Overwrites the file with the given text. */
93 write(text: string): Promise<undefined>;
94
95 /** Returns a stream to write content to the file. */
96 createWriteStream(): WriteStream;
97
98 /** Overwrites the file with the given text. */
99 writeSync(text: string): undefined;
100}
101
102export interface PathWatchErrorThrownEvent {
103 /** The error object. */
104 error: Error;
105
106 /**
107 * Call this function to indicate you have handled the error.
108 * The error will not be thrown if this function is called.
109 */
110 handle(): void;
111}