1 | /// <reference types="node" />
|
2 | import { AnyJson, JsonMap, Optional } from '@salesforce/ts-types';
|
3 | import * as fsLib from 'graceful-fs';
|
4 | import * as mkdirpLib from 'mkdirp';
|
5 | declare type PerformFunction = (filePath: string, file?: string, dir?: string) => Promise<void>;
|
6 | declare type PerformFunctionSync = (filePath: string, file?: string, dir?: string) => void;
|
7 | export declare type WriteJsonOptions = {
|
8 | /**
|
9 | * The number of indent spaces
|
10 | */
|
11 | space?: number;
|
12 | };
|
13 | /**
|
14 | * @deprecated Use fs/promises instead
|
15 | */
|
16 | export declare const fs: typeof fsLib & {
|
17 | /**
|
18 | * The default file system mode to use when creating directories.
|
19 | */
|
20 | DEFAULT_USER_DIR_MODE: string;
|
21 | /**
|
22 | * The default file system mode to use when creating files.
|
23 | */
|
24 | DEFAULT_USER_FILE_MODE: string;
|
25 | /**
|
26 | * A convenience reference to {@link https://nodejs.org/api/fsLib.html#fs_fs_constants}
|
27 | * to reduce the need to import multiple `fs` modules.
|
28 | */
|
29 | constants: typeof fsLib.constants;
|
30 | /**
|
31 | * Promisified version of {@link https://nodejs.org/api/fsLib.html#fs_fs_readfile_path_options_callback|fsLib.readFile}.
|
32 | */
|
33 | readFile: typeof fsLib.readFile.__promisify__;
|
34 | /**
|
35 | * Promisified version of {@link https://nodejs.org/api/fsLib.html#fs_fs_readdir_path_options_callback|fsLib.readdir}.
|
36 | */
|
37 | readdir: typeof fsLib.readdir.__promisify__;
|
38 | /**
|
39 | * Promisified version of {@link https://nodejs.org/api/fsLib.html#fs_fs_writefile_file_data_options_callback|fsLib.writeFile}.
|
40 | */
|
41 | writeFile: typeof fsLib.writeFile.__promisify__;
|
42 | /**
|
43 | * Promisified version of {@link https://nodejs.org/api/fsLib.html#fs_fs_access_path_mode_callback|fsLib.access}.
|
44 | */
|
45 | access: typeof fsLib.access.__promisify__;
|
46 | /**
|
47 | * Promisified version of {@link https://nodejs.org/api/fsLib.html#fs_fs_open_path_flags_mode_callback|fsLib.open}.
|
48 | */
|
49 | open: typeof fsLib.open.__promisify__;
|
50 | /**
|
51 | * Promisified version of {@link https://nodejs.org/api/fsLib.html#fs_fs_unlink_path_callback|fsLib.unlink}.
|
52 | */
|
53 | unlink: typeof fsLib.unlink.__promisify__;
|
54 | /**
|
55 | * Promisified version of {@link https://nodejs.org/api/fsLib.html#fs_fs_readdir_path_options_callback|fsLib.rmdir}.
|
56 | */
|
57 | rmdir: typeof fsLib.rmdir.__promisify__;
|
58 | /**
|
59 | * Promisified version of {@link https://nodejs.org/api/fsLib.html#fs_fs_fstat_fd_callback|fsLib.stat}.
|
60 | */
|
61 | stat: typeof fsLib.stat.__promisify__;
|
62 | /**
|
63 | * Promisified version of {@link https://npmjs.com/package/mkdirp|mkdirp}.
|
64 | */
|
65 | mkdirp: (folderPath: string, mode?: string | object | undefined) => Promise<string | undefined>;
|
66 | mkdirpSync: typeof mkdirpLib.sync;
|
67 | /**
|
68 | * Deletes a folder recursively, removing all descending files and folders.
|
69 | *
|
70 | * **Throws** *PathIsNullOrUndefined* The path is not defined.
|
71 | * **Throws** *DirMissingOrNoAccess* The folder or any sub-folder is missing or has no access.
|
72 | *
|
73 | * @param {string} dirPath The path to remove.
|
74 | */
|
75 | remove: (dirPath: string) => Promise<void>;
|
76 | /**
|
77 | * Deletes a folder recursively, removing all descending files and folders.
|
78 | *
|
79 | * NOTE: It is recommended to call the asynchronous `remove` when possible as it will remove all files in parallel rather than serially.
|
80 | *
|
81 | * **Throws** *PathIsNullOrUndefined* The path is not defined.
|
82 | * **Throws** *DirMissingOrNoAccess* The folder or any sub-folder is missing or has no access.
|
83 | *
|
84 | * @param {string} dirPath The path to remove.
|
85 | */
|
86 | removeSync: (dirPath: string) => void;
|
87 | /**
|
88 | * Searches a file path in an ascending manner (until reaching the filesystem root) for the first occurrence a
|
89 | * specific file name. Resolves with the directory path containing the located file, or `null` if the file was
|
90 | * not found.
|
91 | *
|
92 | * @param dir The directory path in which to start the upward search.
|
93 | * @param file The file name to look for.
|
94 | */
|
95 | traverseForFile: (dir: string, file: string) => Promise<Optional<string>>;
|
96 | /**
|
97 | * Searches a file path synchronously in an ascending manner (until reaching the filesystem root) for the first occurrence a
|
98 | * specific file name. Resolves with the directory path containing the located file, or `null` if the file was
|
99 | * not found.
|
100 | *
|
101 | * @param dir The directory path in which to start the upward search.
|
102 | * @param file The file name to look for.
|
103 | */
|
104 | traverseForFileSync: (dir: string, file: string) => Optional<string>;
|
105 | /**
|
106 | * Read a file and convert it to JSON. Returns the contents of the file as a JSON object
|
107 | *
|
108 | * @param jsonPath The path of the file.
|
109 | * @param throwOnEmpty Whether to throw an error if the JSON file is empty.
|
110 | */
|
111 | readJson: (jsonPath: string, throwOnEmpty?: boolean | undefined) => Promise<AnyJson>;
|
112 | /**
|
113 | * Read a file and convert it to JSON. Returns the contents of the file as a JSON object
|
114 | *
|
115 | * @param jsonPath The path of the file.
|
116 | * @param throwOnEmpty Whether to throw an error if the JSON file is empty.
|
117 | */
|
118 | readJsonSync: (jsonPath: string, throwOnEmpty?: boolean | undefined) => AnyJson;
|
119 | /**
|
120 | * Read a file and convert it to JSON, throwing an error if the parsed contents are not a `JsonMap`.
|
121 | *
|
122 | * @param jsonPath The path of the file.
|
123 | * @param throwOnEmpty Whether to throw an error if the JSON file is empty.
|
124 | */
|
125 | readJsonMap: (jsonPath: string, throwOnEmpty?: boolean | undefined) => Promise<JsonMap>;
|
126 | /**
|
127 | * Read a file and convert it to JSON, throwing an error if the parsed contents are not a `JsonMap`.
|
128 | *
|
129 | * @param jsonPath The path of the file.
|
130 | * @param throwOnEmpty Whether to throw an error if the JSON file is empty.
|
131 | */
|
132 | readJsonMapSync: (jsonPath: string, throwOnEmpty?: boolean | undefined) => JsonMap;
|
133 | /**
|
134 | * Convert a JSON-compatible object to a `string` and write it to a file.
|
135 | *
|
136 | * @param jsonPath The path of the file to write.
|
137 | * @param data The JSON object to write.
|
138 | */
|
139 | writeJson: (jsonPath: string, data: AnyJson, options?: WriteJsonOptions) => Promise<void>;
|
140 | /**
|
141 | * Convert a JSON-compatible object to a `string` and write it to a file.
|
142 | *
|
143 | * @param jsonPath The path of the file to write.
|
144 | * @param data The JSON object to write.
|
145 | */
|
146 | writeJsonSync: (jsonPath: string, data: AnyJson, options?: WriteJsonOptions) => void;
|
147 | /**
|
148 | * Checks if a file path exists
|
149 | *
|
150 | * @param filePath the file path to check the existence of
|
151 | */
|
152 | fileExists: (filePath: string) => Promise<boolean>;
|
153 | /**
|
154 | * Checks if a file path exists
|
155 | *
|
156 | * @param filePath the file path to check the existence of
|
157 | */
|
158 | fileExistsSync: (filePath: string) => boolean;
|
159 | /**
|
160 | * Recursively act on all files or directories in a directory
|
161 | *
|
162 | * @param dir path to directory
|
163 | * @param perform function to be run on contents of dir
|
164 | * @param onType optional parameter to specify type to actOn
|
165 | * @returns void
|
166 | */
|
167 | actOn: (dir: string, perform: PerformFunction, onType?: 'file' | 'dir' | 'all') => Promise<void>;
|
168 | /**
|
169 | * Recursively act on all files or directories in a directory
|
170 | *
|
171 | * @param dir path to directory
|
172 | * @param perform function to be run on contents of dir
|
173 | * @param onType optional parameter to specify type to actOn
|
174 | * @returns void
|
175 | */
|
176 | actOnSync: (dir: string, perform: PerformFunctionSync, onType?: 'file' | 'dir' | 'all') => void;
|
177 | /**
|
178 | * Checks if files are the same
|
179 | *
|
180 | * @param file1Path the first file path to check
|
181 | * @param file2Path the second file path to check
|
182 | * @returns boolean
|
183 | */
|
184 | areFilesEqual: (file1Path: string, file2Path: string) => Promise<boolean>;
|
185 | /**
|
186 | * Checks if files are the same
|
187 | *
|
188 | * @param file1Path the first file path to check
|
189 | * @param file2Path the second file path to check
|
190 | * @returns boolean
|
191 | */
|
192 | areFilesEqualSync: (file1Path: string, file2Path: string) => boolean;
|
193 | /**
|
194 | * Creates a hash for the string that's passed in
|
195 | *
|
196 | * @param contents The string passed into the function
|
197 | * @returns string
|
198 | */
|
199 | getContentHash(contents: string | Buffer): string;
|
200 | };
|
201 | export {};
|