From 1041051cf3df843461428e2b6f49beebf366d968 Mon Sep 17 00:00:00 2001 From: Leonard Thieu Date: Thu, 1 Jun 2017 02:27:46 -0400 Subject: [PATCH] Add type definitions for electron-settings v2. (#16854) --- .../v2/electron-settings-tests.ts | 102 ++++++++ types/electron-settings/v2/index.d.ts | 241 ++++++++++++++++++ types/electron-settings/v2/tsconfig.json | 27 ++ types/electron-settings/v2/tslint.json | 6 + 4 files changed, 376 insertions(+) create mode 100644 types/electron-settings/v2/electron-settings-tests.ts create mode 100644 types/electron-settings/v2/index.d.ts create mode 100644 types/electron-settings/v2/tsconfig.json create mode 100644 types/electron-settings/v2/tslint.json diff --git a/types/electron-settings/v2/electron-settings-tests.ts b/types/electron-settings/v2/electron-settings-tests.ts new file mode 100644 index 0000000000..38e37e6ba0 --- /dev/null +++ b/types/electron-settings/v2/electron-settings-tests.ts @@ -0,0 +1,102 @@ +import * as settings from 'electron-settings'; + +function test_configure() { + settings.configure({ + atomicSaving: false, + prettify: true + }) === undefined; +} + +function test_defaults() { + settings.defaults({ + a: 1, + b: '', + c: false, + d: { + d1: 'd1', + d2: true + }, + e: ['e1', 'e2'] + }) === undefined; +} + +async function test_has() { + await settings.has('a') === true; +} + +function test_hasSync() { + settings.hasSync('a') === true; +} + +async function test_get() { + await settings.get('b') === ''; +} + +function test_getSync() { + settings.getSync('b') === ''; +} + +async function test_set() { + await settings.set('c', true) === undefined; +} + +function test_setSync() { + settings.setSync('c', true) === undefined; +} + +async function test_delete() { + await settings.delete('d') === undefined; +} + +function test_deleteSync() { + settings.deleteSync('d') === undefined; +} + +async function test_clear() { + await settings.clear() === undefined; +} + +function test_clearSync() { + settings.clearSync() === undefined; +} +async function test_applyDefaults() { + await settings.applyDefaults({ overwrite: true }) === undefined; +} + +function test_applyDefaultsSync() { + settings.applyDefaultsSync({ overwrite: true }) === undefined; +} + +async function test_resetToDefaults() { + await settings.resetToDefaults() === undefined; +} + +function test_resetToDefaultsSync() { + settings.resetToDefaultsSync() === undefined; +} + +function test_observe() { + const observer = settings.observe('b', evt => { + if (evt.oldValue !== evt.newValue) { + console.log(evt.newValue); + } + }); + + observer.dispose(); +} + +function test_getSettingsFilePath() { + settings.getSettingsFilePath() === __filename; +} + +function test_on_create() { + settings.on('create', pathToSettings => { + pathToSettings === __dirname; + }) === settings; +} + +function test_on_write() { + settings.on('write', () => { + console.log(); + }) === settings; +} diff --git a/types/electron-settings/v2/index.d.ts b/types/electron-settings/v2/index.d.ts new file mode 100644 index 0000000000..ead5250015 --- /dev/null +++ b/types/electron-settings/v2/index.d.ts @@ -0,0 +1,241 @@ +// Type definitions for electron-settings 2.2 +// Project: https://github.com/nathanbuchar/electron-settings +// Definitions by: Leonard Thieu +// Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped +// TypeScript Version: 2.2 + +/// + +import * as EventEmitter from 'events'; + +/** + * The Settings class. + */ +declare class Settings extends EventEmitter { + /** + * Globally configures default options. + * + * @throws if options is not an object. + */ + configure(options: ElectronSettings.Options | object): void; + + /** + * Globally configures default settings. + * + * If the settings file has not been created yet, these defaults will be applied, + * but only if settings.defaults is called before making any other calls that + * interact with the file system, such as has(), get(), or set(). + * + * @param defaults The defaults object. + * @throws if defaults is not an object. + */ + defaults(defaults: any): void; + + /** + * Returns a promise whose first argument is a boolean indicating if the key path exists within the settings object. + * For synchronous operation, use hasSync(). + * + * @param keyPath The path to the key that we wish to check exists within the settings object. + * @throws if key path is not a string. + * @see hasSync + */ + has(keyPath: string): Promise; + + /** + * The synchronous version of has(). + * + * @see has + */ + hasSync(keyPath: string): boolean; + + /** + * Returns a promise whose first argument is the value at the chosen key path. + * If no key path is chosen, the entire settings object will be returned instead. + * For synchronous operation, use getSync(). + * + * @param keyPath The path to the key that we wish to get the value of. + * @see getSync + */ + get(keyPath?: string): Promise; + + /** + * The synchronous version of get(). + * + * @see get + */ + getSync(keyPath?: string): any; + + /** + * Sets the value of the key at the chosen key path. + * For synchronous operation, use setSync(). + * + * @param keyPath The path to the key whose value we wish to set. This key need not already exist. + * @param value The value to set the key at the chosen key path to. This must be a data type supported by JSON: object, array, string, number, boolean, or null. + * @param options + * @throws if key path is not a string. + * @throws if options is not an object. + * @see setSync + */ + set(keyPath: string, value: any, options?: ElectronSettings.Options | object): Promise; + + /** + * The synchronous version of set(). + * + * @see set + */ + setSync(keyPath: string, value: any, options?: ElectronSettings.Options | object): void; + + /** + * Deletes the key and value at the chosen key path. + * + * @param keyPath The path to the key we wish to unset. + * @param options + * @throws if keyPath is not a string. + * @throws if options is not an object. + * @see deleteSync + */ + delete(keyPath: string, options?: ElectronSettings.Options | object): Promise; + + /** + * The synchronous version of delete(). + * + * @see delete + */ + deleteSync(keyPath: string, options?: ElectronSettings.Options | object): void; + + /** + * Clears the entire settings object. + * For synchronous operation, use clearSync(). + * + * @throws if options is not an object. + * @see clearSync + */ + clear(options?: ElectronSettings.Options | object): Promise; + + /** + * The synchronous version of clear(). + * + * @see clear + */ + clearSync(options?: ElectronSettings.Options | object): void; + + /** + * Applies defaults to the current settings object (deep). + * Settings that already exist will not be overwritten, but keys that exist within the defaults + * that don't exist within the setting object will be added. + * To configure defaults, use defaults(). + * For synchronous operation, use applyDefaultsSync(). + * + * @throws if options is not an object. + * @see defaults + * @see applyDefaultsSync + */ + applyDefaults(options?: ElectronSettings.ApplyDefaultsOptions | object): Promise; + + /** + * The synchronous version of applyDefaults(). + * + * @see applyDefaults + */ + applyDefaultsSync(options?: ElectronSettings.ApplyDefaultsOptions | object): void; + + /** + * Resets all settings to defaults. + * To configure defaults, use defaults(). + * For synchronous operation, use resetToDefaultsSync(). + * + * @throws if options is not an object. + * @see defaults + * @see resetToDefaultsSync + */ + resetToDefaults(options?: ElectronSettings.Options | object): Promise; + + /** + * The synchronous version of resetToDefaults(). + * + * @see resetToDefaults + */ + resetToDefaultsSync(options?: ElectronSettings.Options | object): void; + + /** + * Observes the chosen key path for changes and calls the handler if the value changes. + * Returns an Observer instance which has a dispose method. + * To unsubscribe, simply call dispose() on the returned key path observer. + * + * @param keyPath The path to the key that we wish to observe. + * @param handler The callback that will be invoked if the value at the chosen key path changes. + * @throws if key path is not a string. + * @throws if handler is not a function. + */ + observe(keyPath: string, handler: (evt: ElectronSettings.ChangeEvent) => void): ElectronSettings.Observer; + + /** + * Returns the path to the config file. Typically found in your application's user data directory: + * ~/Library/Application Support/YourApp on MacOS. + * %APPDATA%/YourApp on Windows. + * $XDG_CONFIG_HOME/YourApp or ~/.config/YourApp on Linux. + */ + getSettingsFilePath(): string; + + /** + * Emitted when the settings file has been created. + */ + on(event: 'create', listener: (pathToSettings: string) => void): this; + /** + * Emitted when the settings have been written to disk. + */ + on(event: 'write', listener: () => void): this; +} + +declare const SettingsInstance: Settings; +export = SettingsInstance; + +declare namespace ElectronSettings { + /** + * The Observer class. + */ + class Observer { + /** + * Disposes of the key path observer by unbinding the event listener and + * nullifying all internal references. + */ + dispose(): void; + } + + interface Options extends Pick { } + + namespace Options { + interface _Impl { + /** + * Whether electron-settings should create a tmp file during save to ensure data-write consistency. + * + * @default true + */ + atomicSaving: boolean; + /** + * Prettify the JSON output. + * + * @default false + */ + prettify: boolean; + } + } + + interface ApplyDefaultsOptions extends Pick { } + + namespace ApplyDefaultsOptions { + interface _Impl extends Options._Impl { + /** + * Overwrite pre-existing settings with their respective default values. + * + * @default false + */ + overwrite: boolean; + } + } + + interface ChangeEvent { + oldValue: any; + newValue: any; + } +} diff --git a/types/electron-settings/v2/tsconfig.json b/types/electron-settings/v2/tsconfig.json new file mode 100644 index 0000000000..3a5b7b152c --- /dev/null +++ b/types/electron-settings/v2/tsconfig.json @@ -0,0 +1,27 @@ +{ + "compilerOptions": { + "module": "commonjs", + "lib": [ + "es6" + ], + "noImplicitAny": true, + "noImplicitThis": true, + "strictNullChecks": true, + "baseUrl": "../../", + "typeRoots": [ + "../../" + ], + "paths": { + "electron-settings": [ + "electron-settings/v2" + ] + }, + "types": [], + "noEmit": true, + "forceConsistentCasingInFileNames": true + }, + "files": [ + "index.d.ts", + "electron-settings-tests.ts" + ] +} diff --git a/types/electron-settings/v2/tslint.json b/types/electron-settings/v2/tslint.json new file mode 100644 index 0000000000..4f44991c3c --- /dev/null +++ b/types/electron-settings/v2/tslint.json @@ -0,0 +1,6 @@ +{ + "extends": "dtslint/dt.json", + "rules": { + "no-empty-interface": false + } +}