README.md

Mercury Browser Storage

Overview

This package provides Mercury browser localStorage and sessionStorage origins. It "wraps" localStorage and sessionStorage with a Mercury interface, providing:

• Mercury queries based on object keys.
• Reactivity to CRUD actions. When a "create", "update" or "delete" method is called over an instance, the cache clean events are dispatched.

Install

npm i @xbyorange/mercury-browser-storage --save

Api

• SessionStorage - <Class> new SessionStorage(namespace[, defaultValue[, options]]) - Class for instancing mercury objects persisted in the browser sessionStorage.
  • Arguments
    • namespace - <String>. Namespace to be used in the sessionStorage object, in which the origin data will be persisted.
    • defaultValue - <Any> Default value until the first async read is resolved.
    • options - <Object> containing properties:
      • queriesDefaultValue - <Boolean> If true, the default value of queried sources will be the value of the "key" in the query. If not defined, the default value of queried sources will be the full defaultValue object.
      • tags - <String> or <Array of Strings> Tags to assign to the instance. Useful when using mercury sources handler. Tags "browser-storage" and "session-storage" will be always added to provided tags by default.
• LocalStorage - <Class> new LocalStorage(namespace[, defaultValue[, options]]) - Class for instancing mercury objects persisted in the browser localStorage.
  • Arguments
    • namespace - <String>. Namespace to be used in the localStorage object, in which the origin data will be persisted.
    • defaultValue - <Any> Default value until the first async read is resolved.
    • options - <Object> containing properties:
      • queriesDefaultValue - <Boolean> If true, the default value of queried sources will be the value of the "key" in the query. If not defined, the default value of queried sources will be the full defaultValue object.
      • tags - <String> or <Array of Strings> Tags to assign to the instance. Useful when using mercury sources handler. Tags "browser-storage" and "local-storage" will be always added to provided tags by default.

Common Methods

query

mercuryLocalStorage.query(key)

• Arguments
  • key - <String> Key of the storage object to be read, updated, created or deleted.

Cache

All cache will be cleaned when the update, delete or create methods are executed for any specific query.

Examples

Next example will be easier to understand if you are already familiarized with the mercury syntax.

import { SessionStorage } from "@xbyorange/mercury-browser-storage";

const sessionDetails = new SessionStorage("user", {
  id: null,
  isLogedIn: false
});

const userId = await sessionDetails.query("id").read();

sessionDetails.query("isLogedIn").update(true);

Use Mercury Browser Storage objects in combination with Api Origins, and take advantage of the built-in reactivity. Use the storage objects to query the api origins, and, when you update the storage object, the API object caches will be cleaned as a consequence:

import { LocalStorage } from "@xbyorange/mercury-browser-storage";
import { Api } from "@xbyorange/mercury-api";

const currentAuthor = new LocalStorage("current-author", {
  id: null
});
const booksCollection = new Api("http://api.library.com/books");

const currentAuthorBooks = new Selector(
  { 
    source: currentAuthor,
    query: () => "id"
  },
  {
    source: booksCollection,
    query: (query, previousResults) => {
      if(!previousResults[0]) {
        return;
      }
      return {
        queryString: {
          authorId: previousResults[0]
        }
      };
    }
  },
  (currentAuthorId, booksResults) => booksResults
);

// Api request to "http://api.library.com/books". Return all books
await currentAuthorBooks.read();

// Api request is not repeated, as query has no changed.
await currentAuthorBooks.read();

currentAuthor.query("id").update("foo-author-id");

// Api request now is sent to "http://api.library.com/books?authorId=foo-author-id". Return author books
// As current author is stored in localStorage, the next time the page is loaded, the queryString applied to the api will be the same
await currentAuthorBooks.read();

Usage with frameworks

React

Please refer to the react-mercury documentation to see how simple is the data-binding between React Components and Mercury Browser Storage.

Connect a source to all components that need it. Mercury will rerender automatically connected components when data in sources is updated.

Contributing

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