https://github.com/robinbobin/react-native-preferences
A persistent unencrypted storage for application preferences.
https://github.com/robinbobin/react-native-preferences
async-storage react-native
Last synced: 4 months ago
JSON representation
A persistent unencrypted storage for application preferences.
- Host: GitHub
- URL: https://github.com/robinbobin/react-native-preferences
- Owner: RobinBobin
- Created: 2021-03-21T11:34:04.000Z (about 5 years ago)
- Default Branch: master
- Last Pushed: 2024-12-24T03:46:01.000Z (over 1 year ago)
- Last Synced: 2025-05-30T00:06:34.897Z (about 1 year ago)
- Topics: async-storage, react-native
- Language: TypeScript
- Homepage:
- Size: 323 KB
- Stars: 1
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
A persistent unencrypted storage for application preferences.
1. [Installation](#installation)
2. [Usage](#usage)
3. [Version history](#versionhistory)
### [Installation](#cinstallation)
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`](https://www.npmjs.com/package/@react-native-async-storage/async-storage/v/1.14.1) 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.
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](#preferences)
2. [Preference](#preference)
3. [BooleanPreference](#booleanpreference)
4. [JsonPreference](#jsonpreference)
5. [NumberPreference](#numberpreference)
6. [StringPreference](#stringpreference)
7. [usePreferences()](#usepreferences)
#### [Preferences](#cpreferences)
An instance of this class stores all the preferences. See [`usePreferences()`](#usepreferences).
- [areLoaded](#preferences)
A boolean property, returning `true` if the properties have been loaded and `false` otherwise.
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()](#preferences)
Loads the preferences. This function is invoked internally by [`usePreferences()`](#usepreferences).
#### [Preference](#cpreference)
This class serves as the base class for the classes that manage preference values ([`NumberPreference`](#numberpreference), [`StringPreference`](#stringpreference), etc). It shouldn't be instantiated directly.
- [constructor()](#preference)
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()](#preference)
Checks the validity of the passed value. If the value is deemed invalid, a `TypeError` is thrown.
- [name](#preference)
A string property, returning this preference name.
- [parse()](#preference)
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`.
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()](#preference)
Returns a string representation of the preference value.
- [toString()](#preference)
Returns a human-readable representation of this preference.
A getter / setter for the preference value. When setting a value, its validity is checked with [`assertValidity()`](#preferenceassertvalidity).
#### [BooleanPreference](#cbooleanpreference)
A class to manage boolean values. The default value is `false`, if not specified.
#### [JsonPreference](#cjsonpreference)
A class to manage object values (`{}`). The default value is an empty object, if not specified. Please, don't forget to call [`save()`](#preferencesave) when changing the object:
preferences.json.value.delay = 10;
preferences.json.save();
#### [NumberPreference](#cnumberpreference)
A class to manage number values. The default value is zero, if not specified.
#### [StringPreference](#cstringpreference)
A class to manage string values. The default value is an empty string, if not specified.
#### [usePreferences()](#cusepreferences)
This function does the following:
1. Creates an instance of [`Preferences`](#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`](#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](#cversionhistory)
| Version number | Changes |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| v1.4.0 | [`usePreferences()`](#usePreferences): `onLoad()` can return a clean-up function, invoked **instead of** `onUnload()`. |
| v1.3.0 | [`BooleanPreference`](#booleanpreference) added. |
| v1.2.0 | 1. [`usePreferences()`](#usepreferences): `onUnload` added.
2. Default values for [`JsonPreference`](#jsonpreference), [`NumberPreference`](#numberpreference) and [`StringPreference`](#stringpreference). |
| v1.1.0 | 1. [`JsonPreference`](#jsonpreference) added.
2. [`Preference.save()`](#preferencesave) added. |
| v1.0.3 | Initial release. |
> Written with [StackEdit](https://stackedit.io/).