@xbyorange/mercury-memory

Mercury Memory

Overview

This package provides a Mercury origin for handling memory objects.

• 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-memory --save

Api

new Memory(defaultValue[, options || uuid][, options])

• Arguments
  • defaultValue - <Object>. Object to be stored. Default value is assigned too at the same time.
  • uuid - <String>. Unique id to assign to returned Mercury instance. Useful when using mercury sources handler. To be deprecated in next releases. Options object should be passed as second argument instead of uuid.
  • 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.
    • uuid - <String> Unique id to assign to returned Mercury instance. Useful when using mercury sources handler.
    • tags - <String> or <Array of Strings> Tags to assign to the instance. Useful when using mercury sources handler. A "memory" tag will be always added to provided tags by default.

Methods

query

memory.query(key)

• Arguments
  • key - <String> Key of the memory 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.

Default value

The default value of a "queried" instance will be the complete defaultValue object until the "queriesDefaultValue" option is set as true, in which case the default value will be the value of the key corresponding to the query:

import { Memory } from "@xbyorange/mercury-memory";

const fooMemory = new Memory({
  foo: "foo-value",
  var: "var-value"
});

console.log(fooMemory.query("foo").read.value) // {foo: "foo-value", var: "var-value"}

const fooMemory2 = new Memory({
  foo: "foo-value",
  var: "var-value"
}, {
  queriesDefaultValue: true
});

console.log(fooMemory.query("foo").read.value) // "foo"

Examples

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

import { Memory } from "@xbyorange/mercury-memory";

const sessionDetails = new Memory({
  userId: null,
  isLogedIn: false
});

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

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

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

import { Memory } from "@xbyorange/mercury-memory";
import { Api } from "@xbyorange/mercury-api";

const currentAuthor = new Memory({
  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
await currentAuthorBooks.read();

Contributing

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