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