From be0f70fbf2a9f9fcfd5f889bae408c7c408dbea6 Mon Sep 17 00:00:00 2001 From: Leonard Thieu Date: Thu, 15 Jun 2017 12:21:49 -0400 Subject: [PATCH] [electron-settings/v2] Expose types. --- .../v2/electron-settings-tests.ts | 16 +- types/electron-settings/v2/index.d.ts | 337 +++++++++--------- 2 files changed, 189 insertions(+), 164 deletions(-) diff --git a/types/electron-settings/v2/electron-settings-tests.ts b/types/electron-settings/v2/electron-settings-tests.ts index 38e37e6ba0..0eb746559e 100644 --- a/types/electron-settings/v2/electron-settings-tests.ts +++ b/types/electron-settings/v2/electron-settings-tests.ts @@ -1,4 +1,5 @@ -import * as settings from 'electron-settings'; +import settings = require('electron-settings'); +import Observer = require('electron-settings/lib/observer'); function test_configure() { settings.configure({ @@ -59,6 +60,7 @@ async function test_clear() { function test_clearSync() { settings.clearSync() === undefined; } + async function test_applyDefaults() { await settings.applyDefaults({ overwrite: true }) === undefined; } @@ -100,3 +102,15 @@ function test_on_write() { console.log(); }) === settings; } + +function test_settings_type_annotation(s: typeof settings) { + s.getSettingsFilePath(); +} + +function test_observer_type_annotation(observer: Observer) { + observer.dispose(); +} + +function test_options_type_annotation(options: ElectronSettings.Options) { + options.atomicSaving; +} diff --git a/types/electron-settings/v2/index.d.ts b/types/electron-settings/v2/index.d.ts index ead5250015..5d932bbcf3 100644 --- a/types/electron-settings/v2/index.d.ts +++ b/types/electron-settings/v2/index.d.ts @@ -6,191 +6,194 @@ /// -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; +declare module 'electron-settings' { + import { EventEmitter } from 'events'; + import Observer = require('electron-settings/lib/observer'); /** - * 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. + * The Settings class. */ - defaults(defaults: any): void; + class Settings extends EventEmitter { + /** + * Globally configures default options. + * + * @throws if options is not an object. + */ + configure(options: ElectronSettings.Options.Param): 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; + /** + * 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; - /** - * The synchronous version of has(). - * - * @see has - */ - hasSync(keyPath: string): boolean; + /** + * 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; - /** - * 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 has(). + * + * @see has + */ + hasSync(keyPath: string): boolean; - /** - * The synchronous version of get(). - * - * @see get - */ - getSync(keyPath?: string): any; + /** + * 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; - /** - * 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 get(). + * + * @see get + */ + getSync(keyPath?: string): any; - /** - * The synchronous version of set(). - * - * @see set - */ - setSync(keyPath: string, value: any, options?: ElectronSettings.Options | object): void; + /** + * 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.Param): Promise; - /** - * 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 set(). + * + * @see set + */ + setSync(keyPath: string, value: any, options?: ElectronSettings.Options.Param): void; - /** - * The synchronous version of delete(). - * - * @see delete - */ - deleteSync(keyPath: string, 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.Param): Promise; - /** - * 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 delete(). + * + * @see delete + */ + deleteSync(keyPath: string, options?: ElectronSettings.Options.Param): void; - /** - * The synchronous version of clear(). - * - * @see clear - */ - clearSync(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.Param): Promise; - /** - * 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 clear(). + * + * @see clear + */ + clearSync(options?: ElectronSettings.Options.Param): void; - /** - * The synchronous version of applyDefaults(). - * - * @see applyDefaults - */ - applyDefaultsSync(options?: ElectronSettings.ApplyDefaultsOptions | 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.Param): Promise; - /** - * 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 applyDefaults(). + * + * @see applyDefaults + */ + applyDefaultsSync(options?: ElectronSettings.ApplyDefaultsOptions.Param): void; - /** - * The synchronous version of resetToDefaults(). - * - * @see resetToDefaults - */ - resetToDefaultsSync(options?: ElectronSettings.Options | 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.Param): Promise; - /** - * 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; + /** + * The synchronous version of resetToDefaults(). + * + * @see resetToDefaults + */ + resetToDefaultsSync(options?: ElectronSettings.Options.Param): void; - /** - * 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; + /** + * 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): Observer; - /** - * 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; + /** + * 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; + } + + const SettingsInstance: Settings; + export = SettingsInstance; } -declare const SettingsInstance: Settings; -export = SettingsInstance; - -declare namespace ElectronSettings { +declare module 'electron-settings/lib/observer' { /** * The Observer class. */ @@ -202,9 +205,15 @@ declare namespace ElectronSettings { dispose(): void; } + export = Observer; +} + +declare namespace ElectronSettings { interface Options extends Pick { } namespace Options { + type Param = Options | object; + interface _Impl { /** * Whether electron-settings should create a tmp file during save to ensure data-write consistency. @@ -224,6 +233,8 @@ declare namespace ElectronSettings { interface ApplyDefaultsOptions extends Pick { } namespace ApplyDefaultsOptions { + type Param = ApplyDefaultsOptions | object; + interface _Impl extends Options._Impl { /** * Overwrite pre-existing settings with their respective default values.