1 | /// <reference types="node" />
|
2 | import { Stats as fsStats } from 'fs';
|
3 | import { Logger } from '../logger';
|
4 | import { Messages } from '../messages';
|
5 | import { BaseConfigStore, ConfigContents } from './configStore';
|
6 | /**
|
7 | * Represents a json config file used to manage settings and state. Global config
|
8 | * files are stored in the home directory hidden state folder (.sfdx) and local config
|
9 | * files are stored in the project path, either in the hidden state folder or wherever
|
10 | * specified.
|
11 | *
|
12 | * ```
|
13 | * class MyConfig extends ConfigFile {
|
14 | * public static getFileName(): string {
|
15 | * return 'myConfigFilename.json';
|
16 | * }
|
17 | * }
|
18 | * const myConfig = await MyConfig.create({
|
19 | * isGlobal: true
|
20 | * });
|
21 | * myConfig.set('mykey', 'myvalue');
|
22 | * await myConfig.write();
|
23 | * ```
|
24 | */
|
25 | export declare class ConfigFile<T extends ConfigFile.Options> extends BaseConfigStore<T> {
|
26 | protected hasRead: boolean;
|
27 | protected logger: Logger;
|
28 | protected messages: Messages;
|
29 | private path;
|
30 | /**
|
31 | * Create an instance of a config file without reading the file. Call `read` or `readSync`
|
32 | * after creating the ConfigFile OR instantiate with {@link ConfigFile.create} instead.
|
33 | *
|
34 | * @param options The options for the class instance
|
35 | * @ignore
|
36 | */
|
37 | constructor(options: T);
|
38 | /**
|
39 | * Returns the config's filename.
|
40 | */
|
41 | static getFileName(): string;
|
42 | /**
|
43 | * Returns the default options for the config file.
|
44 | *
|
45 | * @param isGlobal If the file should be stored globally or locally.
|
46 | * @param filename The name of the config file.
|
47 | */
|
48 | static getDefaultOptions(isGlobal?: boolean, filename?: string): ConfigFile.Options;
|
49 | /**
|
50 | * Helper used to determine what the local and global folder point to. Returns the file path of the root folder.
|
51 | *
|
52 | * @param isGlobal True if the config should be global. False for local.
|
53 | */
|
54 | static resolveRootFolder(isGlobal: boolean): Promise<string>;
|
55 | /**
|
56 | * Helper used to determine what the local and global folder point to. Returns the file path of the root folder.
|
57 | *
|
58 | * @param isGlobal True if the config should be global. False for local.
|
59 | */
|
60 | static resolveRootFolderSync(isGlobal: boolean): string;
|
61 | /**
|
62 | * Determines if the config file is read/write accessible. Returns `true` if the user has capabilities specified
|
63 | * by perm.
|
64 | *
|
65 | * @param {number} perm The permission.
|
66 | *
|
67 | * **See** {//nodejs.org/dist/latest/docs/api/fs.html#fs_fs_access_path_mode_callback}
https: |
68 | */
|
69 | access(perm?: number): Promise<boolean>;
|
70 | /**
|
71 | * Determines if the config file is read/write accessible. Returns `true` if the user has capabilities specified
|
72 | * by perm.
|
73 | *
|
74 | * @param {number} perm The permission.
|
75 | *
|
76 | * **See** {@link https://nodejs.org/dist/latest/docs/api/fs.html#fs_fs_access_path_mode_callback}
|
77 | */
|
78 | accessSync(perm?: number): boolean;
|
79 | /**
|
80 | * Read the config file and set the config contents. Returns the config contents of the config file. As an
|
81 | * optimization, files are only read once per process and updated in memory and via `write()`. To force
|
82 | * a read from the filesystem pass `force=true`.
|
83 | * **Throws** *{@link SfdxError}{ name: 'UnexpectedJsonFileFormat' }* There was a problem reading or parsing the file.
|
84 | *
|
85 | * @param [throwOnNotFound = false] Optionally indicate if a throw should occur on file read.
|
86 | * @param [force = true] Optionally force the file to be read from disk even when already read within the process.
|
87 | */
|
88 | read(throwOnNotFound?: boolean, force?: boolean): Promise<ConfigContents>;
|
89 | /**
|
90 | * Read the config file and set the config contents. Returns the config contents of the config file. As an
|
91 | * optimization, files are only read once per process and updated in memory and via `write()`. To force
|
92 | * a read from the filesystem pass `force=true`.
|
93 | * **Throws** *{@link SfdxError}{ name: 'UnexpectedJsonFileFormat' }* There was a problem reading or parsing the file.
|
94 | *
|
95 | * @param [throwOnNotFound = false] Optionally indicate if a throw should occur on file read.
|
96 | * @param [force = true] Optionally force the file to be read from disk even when already read within the process.
|
97 | */
|
98 | readSync(throwOnNotFound?: boolean, force?: boolean): ConfigContents;
|
99 | /**
|
100 | * Write the config file with new contents. If no new contents are provided it will write the existing config
|
101 | * contents that were set from {@link ConfigFile.read}, or an empty file if {@link ConfigFile.read} was not called.
|
102 | *
|
103 | * @param newContents The new contents of the file.
|
104 | */
|
105 | write(newContents?: ConfigContents): Promise<ConfigContents>;
|
106 | /**
|
107 | * Write the config file with new contents. If no new contents are provided it will write the existing config
|
108 | * contents that were set from {@link ConfigFile.read}, or an empty file if {@link ConfigFile.read} was not called.
|
109 | *
|
110 | * @param newContents The new contents of the file.
|
111 | */
|
112 | writeSync(newContents?: ConfigContents): ConfigContents;
|
113 | /**
|
114 | * Check to see if the config file exists. Returns `true` if the config file exists and has access, false otherwise.
|
115 | */
|
116 | exists(): Promise<boolean>;
|
117 | /**
|
118 | * Check to see if the config file exists. Returns `true` if the config file exists and has access, false otherwise.
|
119 | */
|
120 | existsSync(): boolean;
|
121 | /**
|
122 | * Get the stats of the file. Returns the stats of the file.
|
123 | *
|
124 | * {@link fs.stat}
|
125 | */
|
126 | stat(): Promise<fsStats>;
|
127 | /**
|
128 | * Get the stats of the file. Returns the stats of the file.
|
129 | *
|
130 | * {@link fs.stat}
|
131 | */
|
132 | statSync(): fsStats;
|
133 | /**
|
134 | * Delete the config file if it exists.
|
135 | *
|
136 | * **Throws** *`Error`{ name: 'TargetFileNotFound' }* If the {@link ConfigFile.getFilename} file is not found.
|
137 | * {@link fs.unlink}
|
138 | */
|
139 | unlink(): Promise<void>;
|
140 | /**
|
141 | * Delete the config file if it exists.
|
142 | *
|
143 | * **Throws** *`Error`{ name: 'TargetFileNotFound' }* If the {@link ConfigFile.getFilename} file is not found.
|
144 | * {@link fs.unlink}
|
145 | */
|
146 | unlinkSync(): void;
|
147 | /**
|
148 | * Returns the absolute path to the config file.
|
149 | *
|
150 | * The first time getPath is called, the path is resolved and becomes immutable. This allows implementers to
|
151 | * override options properties, like filePath, on the init method for async creation. If that is required for
|
152 | * creation, the config files can not be synchronously created.
|
153 | */
|
154 | getPath(): string;
|
155 | /**
|
156 | * Returns `true` if this config is using the global path, `false` otherwise.
|
157 | */
|
158 | isGlobal(): boolean;
|
159 | /**
|
160 | * Used to initialize asynchronous components.
|
161 | *
|
162 | * **Throws** *`Error`{ code: 'ENOENT' }* If the {@link ConfigFile.getFilename} file is not found when
|
163 | * options.throwOnNotFound is true.
|
164 | */
|
165 | protected init(): Promise<void>;
|
166 | }
|
167 | export declare namespace ConfigFile {
|
168 | /**
|
169 | * The interface for Config options.
|
170 | */
|
171 | interface Options extends BaseConfigStore.Options {
|
172 | /**
|
173 | * The root folder where the config file is stored.
|
174 | */
|
175 | rootFolder?: string;
|
176 | /**
|
177 | * The file name.
|
178 | */
|
179 | filename?: string;
|
180 | /**
|
181 | * If the file is in the global or project directory.
|
182 | */
|
183 | isGlobal?: boolean;
|
184 | /**
|
185 | * If the file is in the state folder or no (.sfdx).
|
186 | */
|
187 | isState?: boolean;
|
188 | /**
|
189 | * The full file path where the config file is stored.
|
190 | */
|
191 | filePath?: string;
|
192 | /**
|
193 | * Indicates if init should throw if the corresponding config file is not found.
|
194 | */
|
195 | throwOnNotFound?: boolean;
|
196 | }
|
197 | }
|