@data-provider/browser-storage

---

Data Provider localStorage and sessionStorage origins addon

It provides CRUD methods for objects stored in localStorage or sessionStorage.

Usage

Create a new provider using the LocalStorage or SessionStorage classes.

Arguments

• options (Object): Apart of common data-provider options, this plugin also accept next options:
  • id (String): Id of the provider, will be used also as the key where the provider data is stored in localStorage or sessionStorage.
  • storageFallback (Boolean): Default true. If there is an error trying to access to window.localStorage or window.sessionStorage, a mock will be used instead, and data will be persisted in memory. This could happen if localStorage is disabled by the browser, for example. If you want to handle exceptions by yourself, you can disable this behavior setting this option to false, and then all calls to read, update or delete methods will be rejected with the correspondent error, which will be stored also in the error property of the provider state.
  • initialState (Object): Same option than the one described in the data-provider API docs, except the data property, which in this case has no effect, as the initial data set in the state will be the data retrieved synchronously from the real localStorage or sessionStorage.

Example

import { LocalStorage } from "@data-provider/browser-storage";

const userPreferences = new LocalStorage({
  id: "user-preferences",
  storageFallback: false
});
// userPreferences object will be stored in localStorage `user-preferences` key.
// If localStorage is disabled, no in-memory mock will be used instead

const sessionData = new SessionStorage({
  id: "user-session"
});
// sessionData object will be stored in sessionStorate `user-session` key.

Further info

Read the Data Provider docs for further info about how to use addons.

• Home
• Get started
• Basic tutorial

Queries

When querying providers created with this addon, the query object can have one of the next properties:

• prop (String): Specific property of the object from localStorage or sessionStorage to be accessed.

Example

import { LocalStorage } from "@data-provider/browser-storage";

const userPreferences = new LocalStorage({
  id: "user-preferences"
});

userPreferences.query({ prop: "cookiesAccepted" }).update(true);
userPreferences.query({ prop: "cookiesAccepted" }).read().then(result => {
  console.log("Cookies accepted", result);
  // true
});

Custom methods

Apart of the common Data Provider methods, next ones are available:

update(data)

Updates an specific property of the stored object when the provider is queried, or the full object when not. When the object is modified, it will automatically cleans the cache of the provider and also the cache of the parent provider when it is queried (as modifying a property also modifies the full object).

Arguments

• data (Any): New data to be set. (Take into account that provided data will be stringified when saved to localStorage)

Returns

A promise that will be resolved when the localStorage is updated, or will be rejected with an error in case the operation fails.

Examples

// modify an specific property
userPreferences.query({ prop: "cookiesAccepted" }).update(true)
  .then(() => {
    console.log("Local storage updated!");
  })
  .catch(error => {
    console.log("Error updating local storage", error);
  });

// Overwrite full object
userPreferences.update({
  cookiesAccepted: true
});

delete()

Removes an specific property of the stored object when the provider is queried, or sets the full object as empty when not. When the object is modified, it will automatically cleans the cache of the provider and also the cache of the parent provider when it is queried (as deleting a property also modifies the full object).

Returns

A promise that will be resolved when the localStorage is updated, or will be rejected with an error in case the operation fails.

Examples

// removes an specific property
userPreferences.query({ prop: "cookiesAccepted" }).delete()
  .then(() => {
    console.log("Local storage updated");
  })
  .catch(error => {
    console.log("Error updating local storage", error);
  });

// Sets the full object as {}
userPreferences.delete();

Tags

Providers created with this addon will have automatically the browser-storage tag, so you can select all of them together using the providers methods as in:

import { providers } from "@data-provider/core";

providers.getByTag("browser-storage").cleanCache();

Apart of this common tag, each different type of browser-storage origin also has next tags:

• LocalStorage: "local-storage"
• SessionStorage: "session-storage"

Contributing

Contributors are welcome. Please read the contributing guidelines and code of conduct.