1 | /**
|
2 | * At the basic level, a key path is the string equivalent
|
3 | * of dot notation in JavaScript. Take the following object,
|
4 | * for example:
|
5 | *
|
6 | * const obj = {
|
7 | * color: {
|
8 | * name: 'cerulean',
|
9 | * code: {
|
10 | * rgb: [0, 179, 230],
|
11 | * hex: '#003BE6'
|
12 | * }
|
13 | * }
|
14 | * }
|
15 | *
|
16 | * You can access the value of the key `name` in plain
|
17 | * JavaScript by traversing the tree using object dot
|
18 | * notation, like so:
|
19 | *
|
20 | * console.log(obj.color.name);
|
21 | * // => "cerulean"
|
22 | *
|
23 | * Similarly in Electron Settings, you are reading and
|
24 | * writing to a JSON object in a file, and a key path is
|
25 | * just a string that points to a specific key within that
|
26 | * object -- essentially using object dot notation in
|
27 | * string form.
|
28 | *
|
29 | * settings.get('color.name');
|
30 | * // => "cerulean"
|
31 | *
|
32 | * Key paths need not be just strings. In fact, there are
|
33 | * perfectly valid use-cases where you might need to access
|
34 | * a key, but the name of the key is stored in some
|
35 | * variable. In this case, you can specify an array of
|
36 | * strings which can be flattened into a regular key path.
|
37 | *
|
38 | * const h = 'hue';
|
39 | * settings.get(['color', h]);
|
40 | * // => undefined
|
41 | *
|
42 | * Additionally, since Electron Settings uses Lodash's
|
43 | * {@link https://lodash.com/docs/4.17.15#get|get()}
|
44 | * function under the hood, you can even use array syntax:
|
45 | *
|
46 | * settings.get('color.code.rgb[1]');
|
47 | * // => 179
|
48 | *
|
49 | * Using key paths, you are not limited to setting only
|
50 | * top-level keys like you would be with LocalStorage. With
|
51 | * Electron Settings, you can deeply nest properties like
|
52 | * you would with any other object in JavaScript, and it
|
53 | * just feels natural.
|
54 | */
|
55 | declare type KeyPath = string | Array<string | number>;
|
56 | /**
|
57 | * `SettingsValue` types are the datatypes supported by
|
58 | * Electron Settings. Since Electron Settings reads and
|
59 | * writes to a JSON file, any value you set must be a valid
|
60 | * JSON value. This does however mean that `Date` types are
|
61 | * _not_ supported.
|
62 | *
|
63 | * Either simply store a numeric unix timestamp using
|
64 | * `Date.now()`, or convert dates back into `Date` types
|
65 | * using `new Date()`:
|
66 | *
|
67 | * await settings.set('user.lastLogin', new Date());
|
68 | *
|
69 | * const lastLogin = await settings.get('user.lastLogin');
|
70 | * const lastLoginDate = new Date(lastLogin);
|
71 | */
|
72 | declare type SettingsValue = null | boolean | string | number | SettingsObject | SettingsValue[];
|
73 | /**
|
74 | * A `SettingsObject` is an object whose property values
|
75 | * are of the type `SettingsValue`.
|
76 | */
|
77 | declare type SettingsObject = {
|
78 | [key: string]: SettingsValue;
|
79 | };
|
80 | /**
|
81 | * `Config` types contain all the configuration options for
|
82 | * Electron Settings that can be set using
|
83 | * [[configure|configure()]].
|
84 | */
|
85 | declare type Config = {
|
86 | /**
|
87 | * Whether or not to save the settings file atomically.
|
88 | */
|
89 | atomicSave: boolean;
|
90 | /**
|
91 | * The path to the settings directory. Defaults to your
|
92 | * app's user data direcory.
|
93 | */
|
94 | dir?: string;
|
95 | /**
|
96 | * A custom Electron instance to use. Great for testing!
|
97 | */
|
98 | electron?: typeof Electron;
|
99 | /**
|
100 | * The name of the settings file that will be saved to
|
101 | * the disk.
|
102 | */
|
103 | fileName: string;
|
104 | /**
|
105 | * The number of spaces to use when stringifying the data
|
106 | * before saving to disk if `prettify` is set to `true`.
|
107 | */
|
108 | numSpaces: number;
|
109 | /**
|
110 | * Whether or not to prettify the data when it's saved to
|
111 | * disk.
|
112 | */
|
113 | prettify: boolean;
|
114 | };
|
115 | /**
|
116 | * Returns the path to the settings file.
|
117 | *
|
118 | * In general, the settings file is stored in your app's
|
119 | * user data directory in a file called `settings.json`.
|
120 | * The default user data directory varies by system.
|
121 | *
|
122 | * - **macOS** - `~/Library/Application\ Support/<Your App>`
|
123 | * - **Windows** - `%APPDATA%/<Your App>`
|
124 | * - **Linux** - Either `$XDG_CONFIG_HOME/<Your App>` or
|
125 | * `~/.config/<Your App>`
|
126 | *
|
127 | * Although it is not recommended, you may change the name
|
128 | * or location of the settings file using
|
129 | * [[configure|configure()]].
|
130 | *
|
131 | * @returns The path to the settings file.
|
132 | * @example
|
133 | *
|
134 | * Get the path to the settings file.
|
135 | *
|
136 | * settings.file();
|
137 | * // => /home/nathan/.config/MyApp/settings.json
|
138 | */
|
139 | declare function file(): string;
|
140 | /**
|
141 | * Sets the configuration for Electron Settings. To reset
|
142 | * to defaults, use [[reset|reset()]].
|
143 | *
|
144 | * Defaults:
|
145 | *
|
146 | * {
|
147 | * atomicSave: true,
|
148 | * fileName: 'settings.json',
|
149 | * numSpaces: 2,
|
150 | * prettify: false
|
151 | * }
|
152 | *
|
153 | * @param customConfig The custom configuration to use.
|
154 | * @example
|
155 | *
|
156 | * Update the filename to `cool-settings.json` and prettify
|
157 | * the output.
|
158 | *
|
159 | * settings.configure({
|
160 | * fileName: 'cool-settings.json',
|
161 | * prettify: true
|
162 | * });
|
163 | */
|
164 | declare function configure(customConfig: Partial<Config>): void;
|
165 | /**
|
166 | * Resets the Electron Settings configuration to defaults.
|
167 | *
|
168 | * @example
|
169 | *
|
170 | * Reset configuration to defaults.
|
171 | *
|
172 | * settings.reset();
|
173 | */
|
174 | declare function reset(): void;
|
175 | /**
|
176 | * Checks if the given key path exists. For sync,
|
177 | * use [[hasSync|hasSync()]].
|
178 | *
|
179 | * @category Core
|
180 | * @param keyPath The key path to check.
|
181 | * @returns A promise which resolves to `true` if the
|
182 | * `keyPath` exists, else `false`.
|
183 | * @example
|
184 | *
|
185 | * Check if the value at `color.name` exists.
|
186 | *
|
187 | * // Given:
|
188 | * //
|
189 | * // {
|
190 | * // "color": {
|
191 | * // "name": "cerulean",
|
192 | * // "code": {
|
193 | * // "rgb": [0, 179, 230],
|
194 | * // "hex": "#003BE6"
|
195 | * // }
|
196 | * // }
|
197 | * // }
|
198 | *
|
199 | * const exists = await settings.has('color.name');
|
200 | * // => true
|
201 | *
|
202 | * @example
|
203 | *
|
204 | * Check if the value at `color.hue` exists.
|
205 | *
|
206 | * const h = 'hue';
|
207 | * const exists = await settings.has(['color', h]);
|
208 | * // => false
|
209 | *
|
210 | * @example
|
211 | *
|
212 | * Check if the value at `color.code.rgb[1]` exists.
|
213 | *
|
214 | * const exists = await settings.has(color.code.rgb[1]);
|
215 | * // => true
|
216 | */
|
217 | declare function has(keyPath: KeyPath): Promise<boolean>;
|
218 | /**
|
219 | * Checks if the given key path exists. For async,
|
220 | * use [[hasSync|hasSync()]].
|
221 | *
|
222 | * @category Core
|
223 | * @param keyPath The key path to check.
|
224 | * @returns `true` if the `keyPath` exists, else `false`.
|
225 | * @example
|
226 | *
|
227 | * Check if the value at `color.name` exists.
|
228 | *
|
229 | * // Given:
|
230 | * //
|
231 | * // {
|
232 | * // "color": {
|
233 | * // "name": "cerulean",
|
234 | * // "code": {
|
235 | * // "rgb": [0, 179, 230],
|
236 | * // "hex": "#003BE6"
|
237 | * // }
|
238 | * // }
|
239 | * // }
|
240 | *
|
241 | * const exists = settings.hasSync('color.name');
|
242 | * // => true
|
243 | *
|
244 | * @example
|
245 | *
|
246 | * Check if the value at `color.hue` exists.
|
247 | *
|
248 | * const h = 'hue';
|
249 | * const exists = settings.hasSync(['color', h]);
|
250 | * // => false
|
251 | *
|
252 | * @example
|
253 | *
|
254 | * Check if the value at `color.code.rgb[1]` exists.
|
255 | *
|
256 | * const exists = settings.hasSync(color.code.rgb[1]);
|
257 | * // => true
|
258 | */
|
259 | declare function hasSync(keyPath: KeyPath): boolean;
|
260 | /**
|
261 | * Gets all settings. For sync, use
|
262 | * [[getSync|getSync()]].
|
263 | *
|
264 | * @category Core
|
265 | * @returns A promise which resolves with all settings.
|
266 | * @example
|
267 | *
|
268 | * Gets all settings.
|
269 | *
|
270 | * const obj = await get();
|
271 | */
|
272 | declare function get(): Promise<SettingsObject>;
|
273 | /**
|
274 | * Gets the value at the given key path. For sync,
|
275 | * use [[getSync|getSync()]].
|
276 | *
|
277 | * @category Core
|
278 | * @param keyPath The key path of the property.
|
279 | * @returns A promise which resolves with the value at the
|
280 | * given key path.
|
281 | * @example
|
282 | *
|
283 | * Get the value at `color.name`.
|
284 | *
|
285 | * // Given:
|
286 | * //
|
287 | * // {
|
288 | * // "color": {
|
289 | * // "name": "cerulean",
|
290 | * // "code": {
|
291 | * // "rgb": [0, 179, 230],
|
292 | * // "hex": "#003BE6"
|
293 | * // }
|
294 | * // }
|
295 | * // }
|
296 | *
|
297 | * const value = await settings.get('color.name');
|
298 | * // => "cerulean"
|
299 | *
|
300 | * @example
|
301 | *
|
302 | * Get the value at `color.hue`.
|
303 | *
|
304 | * const h = 'hue';
|
305 | * const value = await settings.get(['color', h]);
|
306 | * // => undefined
|
307 | *
|
308 | * @example
|
309 | *
|
310 | * Get the value at `color.code.rgb[1]`.
|
311 | *
|
312 | * const h = 'hue';
|
313 | * const value = await settings.get('color.code.rgb[1]');
|
314 | * // => 179
|
315 | */
|
316 | declare function get(keyPath: KeyPath): Promise<SettingsValue>;
|
317 | /**
|
318 | * Gets all settings. For async, use [[get|get()]].
|
319 | *
|
320 | * @category Core
|
321 | * @returns All settings.
|
322 | * @example
|
323 | *
|
324 | * Gets all settings.
|
325 | *
|
326 | * const obj = getSync();
|
327 | */
|
328 | declare function getSync(): SettingsObject;
|
329 | /**
|
330 | * Gets the value at the given key path. For async,
|
331 | * use [[get|get()]].
|
332 | *
|
333 | * @category Core
|
334 | * @param keyPath The key path of the property.
|
335 | * @returns The value at the given key path.
|
336 | * @example
|
337 | *
|
338 | * Get the value at `color.name`.
|
339 | *
|
340 | * // Given:
|
341 | * //
|
342 | * // {
|
343 | * // "color": {
|
344 | * // "name": "cerulean",
|
345 | * // "code": {
|
346 | * // "rgb": [0, 179, 230],
|
347 | * // "hex": "#003BE6"
|
348 | * // }
|
349 | * // }
|
350 | * // }
|
351 | *
|
352 | * const value = settings.getSync('color.name');
|
353 | * // => "cerulean"
|
354 | *
|
355 | * @example
|
356 | *
|
357 | * Get the value at `color.hue`.
|
358 | *
|
359 | * const h = 'hue';
|
360 | * const value = settings.getSync(['color', h]);
|
361 | * // => undefined
|
362 | *
|
363 | * @example
|
364 | *
|
365 | * Get the value at `color.code.rgb[1]`.
|
366 | *
|
367 | * const h = 'hue';
|
368 | * const value = settings.getSync('color.code.rgb[1]');
|
369 | * // => 179
|
370 | */
|
371 | declare function getSync(keyPath: KeyPath): SettingsValue;
|
372 | /**
|
373 | * Sets all settings. For sync, use [[setSync|setSync()]].
|
374 | *
|
375 | * @category Core
|
376 | * @param obj The new settings.
|
377 | * @returns A promise which resolves when the settings have
|
378 | * been set.
|
379 | * @example
|
380 | *
|
381 | * Set all settings.
|
382 | *
|
383 | * await settings.set({ aqpw: 'nice' });
|
384 | */
|
385 | declare function set(obj: SettingsObject): Promise<void>;
|
386 | /**
|
387 | * Sets the value at the given key path. For sync,
|
388 | * use [[setSync|setSync()]].
|
389 | *
|
390 | * @category Core
|
391 | * @param keyPath The key path of the property.
|
392 | * @param value The value to set.
|
393 | * @returns A promise which resolves when the setting has
|
394 | * been set.
|
395 | * @example
|
396 | *
|
397 | * Change the value at `color.name` to `sapphire`.
|
398 | *
|
399 | * // Given:
|
400 | * //
|
401 | * // {
|
402 | * // "color": {
|
403 | * // "name": "cerulean",
|
404 | * // "code": {
|
405 | * // "rgb": [0, 179, 230],
|
406 | * // "hex": "#003BE6"
|
407 | * // }
|
408 | * // }
|
409 | * // }
|
410 | *
|
411 | * await settings.set('color.name', 'sapphire');
|
412 | *
|
413 | * @example
|
414 | *
|
415 | * Set the value of `color.hue` to `blue-ish`.
|
416 | *
|
417 | * const h = 'hue';
|
418 | * await settings.set(['color', h], 'blue-ish);
|
419 | *
|
420 | * @example
|
421 | *
|
422 | * Change the value of `color.code`.
|
423 | *
|
424 | * await settings.set('color.code', {
|
425 | * rgb: [16, 31, 134],
|
426 | * hex: '#101F86'
|
427 | * });
|
428 | */
|
429 | declare function set(keyPath: KeyPath, obj: SettingsValue): Promise<void>;
|
430 | /**
|
431 | * Sets all settings. For async, use [[set|set()]].
|
432 | *
|
433 | * @category Core
|
434 | * @param obj The new settings.
|
435 | * @example
|
436 | *
|
437 | * Set all settings.
|
438 | *
|
439 | * settings.setSync({ aqpw: 'nice' });
|
440 | */
|
441 | declare function setSync(obj: SettingsObject): void;
|
442 | /**
|
443 | * Sets the value at the given key path. For async,
|
444 | * use [[set|set()]].
|
445 | *
|
446 | * @category Core
|
447 | * @param keyPath The key path of the property.
|
448 | * @param value The value to set.
|
449 | * @example
|
450 | *
|
451 | * Change the value at `color.name` to `sapphire`.
|
452 | *
|
453 | * // Given:
|
454 | * //
|
455 | * // {
|
456 | * // "color": {
|
457 | * // "name": "cerulean",
|
458 | * // "code": {
|
459 | * // "rgb": [0, 179, 230],
|
460 | * // "hex": "#003BE6"
|
461 | * // }
|
462 | * // }
|
463 | * // }
|
464 | *
|
465 | * settings.setSync('color.name', 'sapphire');
|
466 | *
|
467 | * @example
|
468 | *
|
469 | * Set the value of `color.hue` to `blue-ish`.
|
470 | *
|
471 | * const h = 'hue';
|
472 | * settings.setSync(['color', h], 'blue-ish);
|
473 | *
|
474 | * @example
|
475 | *
|
476 | * Change the value of `color.code`.
|
477 | *
|
478 | * settings.setSync('color.code', {
|
479 | * rgb: [16, 31, 134],
|
480 | * hex: '#101F86'
|
481 | * });
|
482 | */
|
483 | declare function setSync(keyPath: KeyPath, value: SettingsValue): void;
|
484 | /**
|
485 | * Unsets all settings. For sync, use [[unsetSync|unsetSync()]].
|
486 | *
|
487 | * @category Core
|
488 | * @returns A promise which resolves when the settings have
|
489 | * been unset.
|
490 | * @example
|
491 | *
|
492 | * Unsets all settings.
|
493 | *
|
494 | * await settings.unset();
|
495 | */
|
496 | declare function unset(): Promise<void>;
|
497 | /**
|
498 | * Unsets the property at the given key path. For sync,
|
499 | * use [[unsetSync|unsetSync()]].
|
500 | *
|
501 | * @category Core
|
502 | * @param keyPath The key path of the property.
|
503 | * @returns A promise which resolves when the setting has
|
504 | * been unset.
|
505 | * @example
|
506 | *
|
507 | * Unset the property `color.name`.
|
508 | *
|
509 | * // Given:
|
510 | * //
|
511 | * // {
|
512 | * // "color": {
|
513 | * // "name": "cerulean",
|
514 | * // "code": {
|
515 | * // "rgb": [0, 179, 230],
|
516 | * // "hex": "#003BE6"
|
517 | * // }
|
518 | * // }
|
519 | * // }
|
520 | *
|
521 | * await settings.unset('color.name');
|
522 | *
|
523 | * await settings.get('color.name');
|
524 | * // => undefined
|
525 | *
|
526 | * @example
|
527 | *
|
528 | * Unset the property `color.code.rgba[1]`.
|
529 | *
|
530 | * await settings.unset('color.code.rgba[1]');
|
531 | *
|
532 | * await settings.get('color.code.rgb');
|
533 | * // => [0, null, 230]
|
534 | */
|
535 | declare function unset(keyPath: KeyPath): Promise<void>;
|
536 | /**
|
537 | * Unsets all settings. For async, use [[unset|unset()]].
|
538 | *
|
539 | * @category Core
|
540 | * @example
|
541 | *
|
542 | * Unsets all settings.
|
543 | *
|
544 | * settings.unsetSync();
|
545 | */
|
546 | declare function unsetSync(): void;
|
547 | /**
|
548 | * Unsets the property at the given key path. For async,
|
549 | * use [[unset|unset()]].
|
550 | *
|
551 | * @category Core
|
552 | * @param keyPath The key path of the property.
|
553 | * @example
|
554 | *
|
555 | * Unset the property `color.name`.
|
556 | *
|
557 | * // Given:
|
558 | * //
|
559 | * // {
|
560 | * // "color": {
|
561 | * // "name": "cerulean",
|
562 | * // "code": {
|
563 | * // "rgb": [0, 179, 230],
|
564 | * // "hex": "#003BE6"
|
565 | * // }
|
566 | * // }
|
567 | * // }
|
568 | *
|
569 | * settings.unsetSync('color.name');
|
570 | *
|
571 | * settings.getSync('color.name');
|
572 | * // => undefined
|
573 | *
|
574 | * @example
|
575 | *
|
576 | * Unset the property `color.code.rgba[1]`.
|
577 | *
|
578 | * settings.unsetSync('color.code.rgba[1]');
|
579 | *
|
580 | * settings.getSync('color.code.rgb');
|
581 | * // => [0, null, 230]
|
582 | */
|
583 | declare function unsetSync(keyPath: KeyPath): void;
|
584 | declare const _default: {
|
585 | file: typeof file;
|
586 | configure: typeof configure;
|
587 | reset: typeof reset;
|
588 | has: typeof has;
|
589 | hasSync: typeof hasSync;
|
590 | get: typeof get;
|
591 | getSync: typeof getSync;
|
592 | set: typeof set;
|
593 | setSync: typeof setSync;
|
594 | unset: typeof unset;
|
595 | unsetSync: typeof unsetSync;
|
596 | };
|
597 | export = _default;
|