A persistent unencrypted storage for application preferences.

1. Installation
2. Usage
3. Version history

Installation

npm i @robinbobin/react-native-preferences
npm i @react-native-async-storage/async-storage@^1.14.1

My package uses @react-native-async-storage/async-storage to manage preference values, and that package needs linking. If it's specified as a dependency of @robinbobin/react-native-preferences it's not added to an app's package.json as a dependency and is not linked. Hence the need for manual installation.

Usage

Example:

import {
	StringPreference,
	usePreferences
} from  "@robinbobin/react-native-preferences";

function  App() {
	...
	const onLoad = useCallback(() => {
		console.log(preferences.pref.name, preferences.pref.value);
		preferences.pref.value = "peakaboo";
		console.log(preferences.pref.name, preferences.pref.value);
	}, []);
	
	const preferences = usePreferences([
		new StringPreference("pref", "for you")
	], onLoad);
	...
}

1. Preferences
2. Preference
3. BooleanPreference
4. JsonPreference
5. NumberPreference
6. StringPreference
7. usePreferences()

Preferences

An instance of this class stores all the preferences. See usePreferences().

• areLoaded

  A boolean property, returning true if the properties have been loaded and false otherwise.

• get()

  Gets a preference by name. Throws an Error instance if the preferences haven't been loaded yet or if there's no preference with that name.

  Generally it's easier to use the preferences.preferenceName syntax for the same purpose. This function can be used to access preferences with reserved names (names of properties / methods of this class and names starting with an underscore).

• load()

  Loads the preferences. This function is invoked internally by usePreferences().

Preference

This class serves as the base class for the classes that manage preference values (NumberPreference, StringPreference, etc). It shouldn't be instantiated directly.

• constructor()

  Takes 3 parameters:

  • name – The name of the preference. See also Preferences.get().
  • defaultValue – A default value for the preference, used only on load if no value has been stored before.
  • valueTypes – Valid value types. Can be undefined, one type or an array of types.

• assertValidity()

  Checks the validity of the passed value. If the value is deemed invalid, a TypeError is thrown.

• name

  A string property, returning this preference name.

• parse()

  Returns a value this preference can manage, being passed a string. The following must stand true:

  • The parameter must be a valid string representation of the value.
  • If the parameter is null this function must return null.

• save()

  Stores the preference value in a persistent storage. This method is invoked internally by the value setter, but has to be called manually for "compound" preferences like JsonPreference.

• stringify()

  Returns a string representation of the preference value.

• toString()

  Returns a human-readable representation of this preference.

• value

  A getter / setter for the preference value. When setting a value, its validity is checked with assertValidity().

BooleanPreference

A class to manage boolean values. The default value is false, if not specified.

JsonPreference

A class to manage object values ({}). The default value is an empty object, if not specified. Please, don't forget to call save() when changing the object:

preferences.json.value.delay = 10;
preferences.json.save();

NumberPreference

A class to manage number values. The default value is zero, if not specified.

StringPreference

A class to manage string values. The default value is an empty string, if not specified.

usePreferences()

This function does the following:

1. Creates an instance of Preferences, initializing it with the passed in preferences.
2. Loads the preferences.
3. Returns the created instance.

The return value of this function needn't be specified as a dependency of React.useCallback(), etc.

This function takes 3 parameters:

• preferences – an array of preferences (instances of classes derived from Preference).
• onLoad – a callback that is invoked when the preferences are loaded. It can return a clean-up function or a Promise, resolving to a clean-up function. In this case this clean-up function will be invoked instead of onUnload().
• onUnload – (optional) a callback that is invoked on unmount.

Version history

Version number	Changes
v1.4.0	usePreferences(): onLoad() can return a clean-up function, invoked instead of onUnload().
v1.3.0	BooleanPreference added.
v1.2.0	1. usePreferences(): onUnload added. 2. Default values for JsonPreference, NumberPreference and StringPreference.
v1.1.0	1. JsonPreference added. 2. Preference.save() added.
v1.0.3	Initial release.

Written with StackEdit.