diff --git a/packages/config/lib/index.d.ts b/packages/config/lib/index.d.ts index 979fad96..3f3baf46 100644 --- a/packages/config/lib/index.d.ts +++ b/packages/config/lib/index.d.ts @@ -32,22 +32,51 @@ export namespace Config { export interface Statics {} /** - * An Interface representing a Remote Config value + * An Interface representing a Remote Config value. */ export interface ConfigValue { /** - * Where the value was retrieved from + * Where the value was retrieved from. + * + * - `remote`: If the value was retrieved from the server. + * - `default`: If the value was set as a default value. + * - `static`: If no value was found and a static default value was returned instead. + * + * #### Example + * + * ```js + * const configValue = await config().getValue('beta_enabled'); + * console.log('Value source: ', configValue.source); + * ``` */ source: 'remote' | 'default' | 'static'; /** - * The value + * The returned value. + * + * #### Example + * + * ```js + * const configValue = await config().getValue('beta_enabled'); + * console.log('Value: ', configValue.value); + * ``` */ value: undefined | number | boolean | string; } /** - * An Interface representing multiple Config Values + * An Interface representing multiple Config Values. + * + * #### Example + * + * ```js + * const values = await config().getValuesByKeysPrefix('feature_'); + * + * values.forEach(($) => { + * console.log('Source: ', $.source); + * console.log('Value: ', $.value); + * }); + * ``` */ export interface ConfigValues { [key: string]: ConfigValue; @@ -55,22 +84,63 @@ export namespace Config { /** * An Interface representing settable config settings. + * + * #### Example + * + * The example below makes use of the React Native `__DEV__` global JavaScript variable which + * is exposed. + * + * ```js + * await config().setConfigSettings({ + * isDeveloperModeEnabled: __DEV__, + * }); + * ``` */ export interface ConfigSettingsWrite { + /** + * If enabled, default behaviour such as caching is disabled for a better debugging + * experience. + */ isDeveloperModeEnabled: boolean; } /** * An Interface representing readable config settings. + * + * #### Example + * + * ```js + * const settings = await config().getConfigSettings(); + * console.log('Last fetched time: ', settings.lastFetchTime); + * console.log('Developer mode enabled': settings.isDeveloperModeEnabled); + * console.log('Last fetch status: ', settings.lastFetchStatus); + * ``` */ export interface ConfigSettingsRead { + /** + * The number of milliseconds since the last Remote Config fetch was performed. + */ lastFetchTime: number; + /** + * Whether developer mode is enabled. This is set manually via {@link config#setConfigSettings} + */ isDeveloperModeEnabled: boolean; + /** + * The status of the latest Remote Config fetch action. + */ lastFetchStatus: 'success' | 'failure' | 'no_fetch_yet' | 'throttled'; } /** * An Interface representing a Config Defaults object. + * + * #### Example + * + * ```js + * await config().setDefaults({ + * experiment_enabled: false, + * }); + * ``` */ export interface ConfigDefaults { [key: string]: number | string | boolean; @@ -80,12 +150,33 @@ export namespace Config { /** * Moves fetched data to the apps active config. * Resolves with a boolean value of whether the fetched config was moved successfully. + * + * #### Example + * + * ```js + * // Fetch values + * await config().fetch(); + * const activated = await config().activateFetched(); + * + * if (activated) { + * console.log('Fetched values successfully activated.'); + * } else { + * console.log('Fetched values failed to activate.'); + * } + * ``` */ activateFetched(): Promise; /** * Fetches the remote config data from Firebase, as defined in the dashboard. If duration is defined (seconds), data will be locally cached for this duration. * + * #### Example + * + * ```js + * // Fetch and cache for 5 minutes + * await config().fetch(300); + * ``` + * * @param cacheExpirationSeconds Duration in seconds to cache the data for. To skip cache, use a duration of 0. */ fetch(cacheExpirationSeconds?: number): Promise; @@ -95,18 +186,44 @@ export namespace Config { * * Once fetching is complete this method immediately calls activateFetched and returns a boolean value of the activation status. * + * #### Example + * + * ```js + * // Fetch, cache for 5 minutes and activate + * const activated = await config().fetchAndActivate(300); + * + * if (activated) { + * console.log('Fetched values successfully activated.'); + * } else { + * console.log('Fetched values failed to activate.'); + * } + * ``` + * * @param cacheExpirationSeconds Duration in seconds to cache the data for. To skip cache use a duration of 0. */ fetchAndActivate(cacheExpirationSeconds?: number): Promise; /** * Retrieve the configuration settings and status for Remote Config. + * + * ### Example + * + * ```js + * const settings = await config().getConfigSettings(); + * console.log('Developer mode enabled: ', settings.isDeveloperModeEnabled); + * ``` */ getConfigSettings(): Promise; /** * Returns all keys matching the prefix as an array. If no prefix is defined all keys are returned. * + * #### Example + * + * ```js + * const keys = await config().getKeysByPrefix('feature_'); + * ``` + * * @param prefix A prefix value to match keys by. Leave blank to retrieve all keys. */ getKeysByPrefix(prefix?: string): Promise; @@ -114,6 +231,17 @@ export namespace Config { /** * Returns all config values for the keys matching the prefix provided. In no prefix is provided all values are returned. * + * #### Example + * + * ```js + * const values = await config().getValuesByKeysPrefix('feature_'); + * + * values.forEach(($) => { + * console.log('Source: ', $.source); + * console.log('Value: ', $.value); + * }); + * ``` + * * @param prefix A prefix value to match values by. Leave blank to retrieve all values. */ getValuesByKeysPrefix(prefix?: string): Promise; @@ -121,6 +249,14 @@ export namespace Config { /** * Gets a ConfigValue by key. * + * #### Example + * + * ```js + * const configValue = await config().getValue('experiment'); + * console.log('Source: ', configValue.source); + * console.log('Value: ', configValue.value); + * ``` + * * @param key A key used to retrieve a specific value. */ getValue(key: string): Promise; @@ -128,6 +264,14 @@ export namespace Config { /** * Set the Remote Config settings, specifically the `isDeveloperModeEnabled` flag. * + * #### Example + * + * ```js + * await config().setConfigSettings({ + * isDeveloperModeEnabled: __DEV__, + * }); + * ``` + * * @param configSettings A ConfigSettingsWrite instance used to set Remote Config settings. */ setConfigSettings(configSettings: ConfigSettingsWrite): Promise; @@ -136,6 +280,14 @@ export namespace Config { * Sets default values for the app to use when accessing values. * Any data fetched and activated will override any default values. Any values in the defaults but not on Firebase will be untouched. * + * #### Example + * + * ```js + * await config().setDefaults({ + * experiment_enabled: false, + * }); + * ``` + * * @param defaults A ConfigDefaults instance used to set default values. */ setDefaults(defaults: ConfigDefaults): Promise; @@ -144,7 +296,9 @@ export namespace Config { * Sets the default values from a resource file. * On iOS this is a plist file and on Android this is an XML defaultsMap file. * - * @link /guides/todo + * ```js + * // TODO @ehesp + * ``` * * @param resourceName The plist/xml file name with no extension. */ diff --git a/packages/config/lib/index.js.flow b/packages/config/lib/index.js.flow index d89701e5..05f5048e 100644 --- a/packages/config/lib/index.js.flow +++ b/packages/config/lib/index.js.flow @@ -25,18 +25,47 @@ export interface Statics {} */ export interface ConfigValue { /** - * Where the value was retrieved from + * Where the value was retrieved from. + * + * - `remote`: If the value was retrieved from the server. + * - `default`: If the value was set as a default value. + * - `static`: If no value was found and a static default value was returned instead. + * + * #### Example + * + * ```js + * const configValue = await config().getValue('beta_enabled'); + * console.log('Value source: ', configValue.source); + * ``` */ source: 'remote' | 'default' | 'static'; /** - * The value + * The returned value. + * + * #### Example + * + * ```js + * const configValue = await config().getValue('beta_enabled'); + * console.log('Value: ', configValue.value); + * ``` */ value: undefined | number | boolean | string; } /** - * An Interface representing multiple Config Values + * An Interface representing multiple Config Values. + * + * #### Example + * + * ```js + * const values = await config().getValuesByKeysPrefix('feature_'); + * + * values.forEach(($) => { + * console.log('Source: ', $.source); + * console.log('Value: ', $.value); + * }); + * ``` */ export interface ConfigValues { [key: string]: ConfigValue; @@ -44,22 +73,63 @@ export interface ConfigValues { /** * An Interface representing settable config settings. + * + * #### Example + * + * The example below makes use of the React Native `__DEV__` global JavaScript variable which + * is exposed. + * + * ```js + * await config().setConfigSettings({ + * isDeveloperModeEnabled: __DEV__, + * }); + * ``` */ export interface ConfigSettingsWrite { + /** + * If enabled, default behaviour such as caching is disabled for a better debugging + * experience. + */ isDeveloperModeEnabled: boolean; } /** * An Interface representing readable config settings. + * + * #### Example + * + * ```js + * const settings = await config().getConfigSettings(); + * console.log('Last fetched time: ', settings.lastFetchTime); + * console.log('Developer mode enabled': settings.isDeveloperModeEnabled); + * console.log('Last fetch status: ', settings.lastFetchStatus); + * ``` */ export interface ConfigSettingsRead { + /** + * The number of milliseconds since the last Remote Config fetch was performed. + */ lastFetchTime: number; + /** + * Whether developer mode is enabled. This is set manually via {@link config#setConfigSettings} + */ isDeveloperModeEnabled: boolean; + /** + * The status of the latest Remote Config fetch action. + */ lastFetchStatus: 'success' | 'failure' | 'no_fetch_yet' | 'throttled'; } /** * An Interface representing a Config Defaults object. + * + * #### Example + * + * ```js + * await config().setDefaults({ + * experiment_enabled: false, + * }); + * ``` */ export interface ConfigDefaults { [key: string]: number | string | boolean; @@ -69,12 +139,33 @@ export interface Module extends ReactNativeFirebaseModule { /** * Moves fetched data to the apps active config. * Resolves with a boolean value of whether the fetched config was moved successfully. + * + * #### Example + * + * ```js + * // Fetch values + * await config().fetch(); + * const activated = await config().activateFetched(); + * + * if (activated) { + * console.log('Fetched values successfully activated.'); + * } else { + * console.log('Fetched values failed to activate.'); + * } + * ``` */ activateFetched(): Promise; /** * Fetches the remote config data from Firebase, as defined in the dashboard. If duration is defined (seconds), data will be locally cached for this duration. * + * #### Example + * + * ```js + * // Fetch and cache for 5 minutes + * await config().fetch(300); + * ``` + * * @param cacheExpirationSeconds Duration in seconds to cache the data for. To skip cache, use a duration of 0. */ fetch(cacheExpirationSeconds?: number): Promise; @@ -84,18 +175,44 @@ export interface Module extends ReactNativeFirebaseModule { * * Once fetching is complete this method immediately calls activateFetched and returns a boolean value of the activation status. * + * #### Example + * + * ```js + * // Fetch, cache for 5 minutes and activate + * const activated = await config().fetchAndActivate(300); + * + * if (activated) { + * console.log('Fetched values successfully activated.'); + * } else { + * console.log('Fetched values failed to activate.'); + * } + * ``` + * * @param cacheExpirationSeconds Duration in seconds to cache the data for. To skip cache use a duration of 0. */ fetchAndActivate(cacheExpirationSeconds?: number): Promise; /** * Retrieve the configuration settings and status for Remote Config. + * + * ### Example + * + * ```js + * const settings = await config().getConfigSettings(); + * console.log('Developer mode enabled: ', settings.isDeveloperModeEnabled); + * ``` */ getConfigSettings(): Promise; /** * Returns all keys matching the prefix as an array. If no prefix is defined all keys are returned. * + * #### Example + * + * ```js + * const keys = await config().getKeysByPrefix('feature_'); + * ``` + * * @param prefix A prefix value to match keys by. Leave blank to retrieve all keys. */ getKeysByPrefix(prefix?: string): Promise; @@ -103,6 +220,17 @@ export interface Module extends ReactNativeFirebaseModule { /** * Returns all config values for the keys matching the prefix provided. In no prefix is provided all values are returned. * + * #### Example + * + * ```js + * const values = await config().getValuesByKeysPrefix('feature_'); + * + * values.forEach(($) => { + * console.log('Source: ', $.source); + * console.log('Value: ', $.value); + * }); + * ``` + * * @param prefix A prefix value to match values by. Leave blank to retrieve all values. */ getValuesByKeysPrefix(prefix?: string): Promise; @@ -110,6 +238,14 @@ export interface Module extends ReactNativeFirebaseModule { /** * Gets a ConfigValue by key. * + * #### Example + * + * ```js + * const configValue = await config().getValue('experiment'); + * console.log('Source: ', configValue.source); + * console.log('Value: ', configValue.value); + * ``` + * * @param key A key used to retrieve a specific value. */ getValue(key: string): Promise; @@ -117,6 +253,14 @@ export interface Module extends ReactNativeFirebaseModule { /** * Set the Remote Config settings, specifically the `isDeveloperModeEnabled` flag. * + * #### Example + * + * ```js + * await config().setConfigSettings({ + * isDeveloperModeEnabled: __DEV__, + * }); + * ``` + * * @param configSettings A ConfigSettingsWrite instance used to set Remote Config settings. */ setConfigSettings(configSettings: ConfigSettingsWrite): Promise; @@ -125,6 +269,14 @@ export interface Module extends ReactNativeFirebaseModule { * Sets default values for the app to use when accessing values. * Any data fetched and activated will override any default values. Any values in the defaults but not on Firebase will be untouched. * + * #### Example + * + * ```js + * await config().setDefaults({ + * experiment_enabled: false, + * }); + * ``` + * * @param defaults A ConfigDefaults instance used to set default values. */ setDefaults(defaults: ConfigDefaults): Promise; @@ -133,7 +285,9 @@ export interface Module extends ReactNativeFirebaseModule { * Sets the default values from a resource file. * On iOS this is a plist file and on Android this is an XML defaultsMap file. * - * @link /guides/todo + * ```js + * // TODO @ehesp + * ``` * * @param resourceName The plist/xml file name with no extension. */