UNPKG

8.27 kBTypeScriptView Raw
1/// <reference types="node"/>
2import {JSONSchema} from 'json-schema-typed';
3
4declare namespace Conf {
5 interface Options<T> {
6 /**
7 Config used if there are no existing config.
8
9 **Note:** The values in `defaults` will overwrite the `default` key in the `schema` option.
10 */
11 readonly defaults?: {[key: string]: T};
12
13 /**
14 [JSON Schema](https://json-schema.org) to validate your config data.
15
16 Under the hood, the JSON Schema validator [ajv](https://github.com/epoberezkin/ajv) is used to validate your config. We use [JSON Schema draft-07](http://json-schema.org/latest/json-schema-validation.html) and support all [validation keywords](https://github.com/epoberezkin/ajv/blob/master/KEYWORDS.md) and [formats](https://github.com/epoberezkin/ajv#formats).
17
18 You should define your schema as an object where each key is the name of your data's property and each value is a JSON schema used to validate that property. See more [here](https://json-schema.org/understanding-json-schema/reference/object.html#properties).
19
20 @example
21 ```
22 import Conf = require('conf');
23
24 const schema = {
25 foo: {
26 type: 'number',
27 maximum: 100,
28 minimum: 1,
29 default: 50
30 },
31 bar: {
32 type: 'string',
33 format: 'url'
34 }
35 };
36
37 const config = new Conf({schema});
38
39 console.log(config.get('foo'));
40 //=> 50
41
42 config.set('foo', '1');
43 // [Error: Config schema violation: `foo` should be number]
44 ```
45
46 **Note:** The `default` value will be overwritten by the `defaults` option if set.
47 */
48 readonly schema?: {[key: string]: JSONSchema};
49
50 /**
51 Name of the config file (without extension).
52
53 Useful if you need multiple config files for your app or module. For example, different config files between two major versions.
54
55 @default 'config'
56 */
57 readonly configName?: string;
58
59 /**
60 You only need to specify this if you don't have a `package.json` file in your project. Default: The name field in the `package.json` closest to where `conf` is imported.
61 */
62 readonly projectName?: string;
63
64 /**
65 __You most likely don't need this. Please don't use it unless you really have to.__
66
67 The only use-case I can think of is having the config located in the app directory or on some external storage. Default: System default user [config directory](https://github.com/sindresorhus/env-paths#pathsconfig).
68 */
69 readonly cwd?: string;
70
71 /**
72 Note that this is __not intended for security purposes__, since the encryption key would be easily found inside a plain-text Node.js app.
73
74 Its main use is for obscurity. If a user looks through the config directory and finds the config file, since it's just a JSON file, they may be tempted to modify it. By providing an encryption key, the file will be obfuscated, which should hopefully deter any users from doing so.
75
76 It also has the added bonus of ensuring the config file's integrity. If the file is changed in any way, the decryption will not work, in which case the store will just reset back to its default state.
77
78 When specified, the store will be encrypted using the [`aes-256-cbc`](https://en.wikipedia.org/wiki/Block_cipher_mode_of_operation) encryption algorithm.
79 */
80 readonly encryptionKey?: string | Buffer | NodeJS.TypedArray | DataView;
81
82 /**
83 Extension of the config file.
84
85 You would usually not need this, but could be useful if you want to interact with a file with a custom file extension that can be associated with your app. These might be simple save/export/preference files that are intended to be shareable or saved outside of the app.
86
87 @default 'json'
88 */
89 readonly fileExtension?: string;
90
91 /**
92 The config is cleared if reading the config file causes a `SyntaxError`. This is a good default, as the config file is not intended to be hand-edited, so it usually means the config is corrupt and there's nothing the user can do about it anyway. However, if you let the user edit the config file directly, mistakes might happen and it could be more useful to throw an error when the config is invalid instead of clearing. Disabling this option will make it throw a `SyntaxError` on invalid config instead of clearing.
93
94 @default true
95 */
96 readonly clearInvalidConfig?: boolean;
97
98 /**
99 Function to serialize the config object to a UTF-8 string when writing the config file.
100
101 You would usually not need this, but it could be useful if you want to use a format other than JSON.
102
103 @default value => JSON.stringify(value, null, '\t')
104 */
105 readonly serialize?: (value: {[key: string]: T}) => string;
106
107 /**
108 Function to deserialize the config object from a UTF-8 string when reading the config file.
109
110 You would usually not need this, but it could be useful if you want to use a format other than JSON.
111
112 @default JSON.parse
113 */
114 readonly deserialize?: (text: string) => {[key: string]: T};
115
116 /**
117 __You most likely don't need this. Please don't use it unless you really have to.__
118
119 Suffix appended to `projectName` during config file creation to avoid name conflicts with native apps.
120
121 You can pass an empty string to remove the suffix.
122
123 For example, on macOS, the config file will be stored in the `~/Library/Preferences/foo-nodejs` directory, where `foo` is the `projectName`.
124
125 @default 'nodejs'
126 */
127 readonly projectSuffix?: string;
128
129 /**
130 Access nested properties by dot notation.
131
132 @default true
133
134 @example
135 ```
136 const config = new Conf();
137
138 config.set({
139 foo: {
140 bar: {
141 foobar: '🦄'
142 }
143 }
144 });
145
146 console.log(config.get('foo.bar.foobar'));
147 //=> '🦄'
148 ```
149
150 Alternatively, you can set this option to `false` so the whole string would be treated as one key.
151
152 @example
153 ```
154 const config = new Conf({accessPropertiesByDotNotation: false});
155
156 config.set({
157 `foo.bar.foobar`: '🦄'
158 });
159
160 console.log(config.get('foo.bar.foobar'));
161 //=> '🦄'
162 ```
163
164 */
165 readonly accessPropertiesByDotNotation?: boolean;
166 }
167}
168
169/**
170Simple config handling for your app or module.
171*/
172declare class Conf<T> implements Iterable<[string, T]> {
173 store: {[key: string]: T};
174 readonly path: string;
175 readonly size: number;
176
177 /**
178 @example
179 ```
180 import Conf = require('conf');
181
182 const config = new Conf();
183
184 config.set('unicorn', '🦄');
185 console.log(config.get('unicorn'));
186 //=> '🦄'
187
188 // Use dot-notation to access nested properties
189 config.set('foo.bar', true);
190 console.log(config.get('foo'));
191 //=> {bar: true}
192
193 config.delete('unicorn');
194 console.log(config.get('unicorn'));
195 //=> undefined
196 ```
197 */
198 constructor(options?: Conf.Options<T>);
199
200 /**
201 Set an item.
202
203 @param key - You can use [dot-notation](https://github.com/sindresorhus/dot-prop) in a key to access nested properties.
204 @param value - Must be JSON serializable. Trying to set the type `undefined`, `function`, or `symbol` will result in a `TypeError`.
205 */
206 set(key: string, value: T): void;
207
208 /**
209 Set multiple items at once.
210
211 @param object - A hashmap of items to set at once.
212 */
213 set(object: {[key: string]: T}): void;
214
215 /**
216 Get an item.
217
218 @param key - The key of the item to get.
219 @param defaultValue - The default value if the item does not exist.
220 */
221 get(key: string, defaultValue?: T): T;
222
223 /**
224 Check if an item exists.
225
226 @param key - The key of the item to check.
227 */
228 has(key: string): boolean;
229
230 /**
231 Delete an item.
232
233 @param key - The key of the item to delete.
234 */
235 delete(key: string): void;
236
237 /**
238 Delete all items.
239 */
240 clear(): void;
241
242 /**
243 Watches the given `key`, calling `callback` on any changes.
244
245 @param key - The key wo watch.
246 @param callback - A callback function that is called on any changes. When a `key` is first set `oldValue` will be `undefined`, and when a key is deleted `newValue` will be `undefined`.
247 */
248 onDidChange(
249 key: string,
250 callback: (newValue: T | undefined, oldValue: T | undefined) => void
251 ): () => void;
252
253 /**
254 Watches the whole config object, calling `callback` on any changes.
255
256 @param callback - A callback function that is called on any changes. When a `key` is first set `oldValue` will be `undefined`, and when a key is deleted `newValue` will be `undefined`.
257 */
258 onDidAnyChange(
259 callback: (oldValue: {[key: string]: T} | undefined, newValue: {[key: string]: T} | undefined) => void
260 ): () => void;
261
262 [Symbol.iterator](): IterableIterator<[string, T]>;
263}
264
265export = Conf;
266
\No newline at end of file