@data-provider/browser-storage

    3.0.2 • Public • Published

    Build status Coverage Status Quality Gate Mutation testing badge

    NPM dependencies Renovate Last commit Last release

    NPM downloads License

    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.

    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.

    Install

    npm i @data-provider/browser-storage

    DownloadsWeekly Downloads

    235

    Version

    3.0.2

    License

    Apache-2.0

    Unpacked Size

    46.1 kB

    Total Files

    8

    Last publish

    Collaborators

    • javierbrea