@robinbobin/react-native-preferences v1.4.1

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](#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()`](#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()`](#preferencesget).
  	- `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](#preferencevalue), but has to be called manually for "compound" preferences like [`JsonPreference`](#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()`](#preferenceassertvalidity).

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

Written with StackEdit.