macrometa-cache

Low latency persistent global side cache library to cache objects and responses utilizing Macrometa GDN.

Installation

$ npm install macrometa-cache

Usage

import mmcache from "macrometa-cache"; // Browser
// OR
const mmcache = require('macrometa-cache'); // Node


// Initialize
const cache = new mmcache({
  url: "https://gdn.paas.macrometa.io",
  apiKey: "XXXX",
  name: "sampleCache"
});
await cache.create(); // This step is required to create cache in GDN.
// OR

const cache = new mmcache({
  url: "https://gdn.paas.macrometa.io",
  apiKey: "XXXX",
  ttl: 120
});
await cache.create("sampleCache");


// Set the value
cache.set('cacheKey', { foo: 'bar' }, 120, function (error, data) {

  if (error) throw data.errorMessage;

  // get the value
  cache.get('cacheKey', function (error, data) {

    if (error) throw data.errorMessage;

    console.log(data.value); //-> { foo: "bar" }

    // delete entry
    cache.delete('cacheKey', function (error, data){

      if (error) throw data.errorMessage;

      console.log('value deleted');
    });

  });
});

API

mmcache(options)

options is a dictionary of variables to connect to GDN and default values for KV collection.

• url (String) GDN url. Default is https://gdn.paas.macrometa.io
• apiKey (String) api key.
• agent (String | Function) Agent to be used. Default is fetch.
• fabricName (String) (optional) Name of the fabric. Default is _system.
• name (String) (optional) Name of the cache to be created. Default is mmcache.
• ttl (Number) (optional) Time to live in seconds. -1 means no expiration. Default is 3600 seconds.
• absolutePath (Boolean) (optional) If absolute path needs to be used. Default is false.
• headers (Object) (optional) If extra headers need to be provided.

const options = {
  url: "https://gdn.paas.macrometa.io",
  apiKey: "XXXX",
  agent: httpRequest,
  name: "sampleCache",
  fabricName: "_system",
  ttl: 3600
};

const cache = new mmcache(options);

cache.create([name], [callback]): Promise

Creates a global KV collection with given name. if not provided it creates with name given in options or with default name mmcache.

💡 Note: This step is must after initializing mmcache to create cache in GDN. Skip this step if cache is already created.

• name: String (optional)

  Name of the KV collection

const cache = new mmcache({
  url: "https://gdn.paas.macrometa.io",
  apiKey: "XXXX",
  name: "sampleCache"
});

await cache.create();
//OR

cache.create((error, data) => {
  if (error) throw data.errorMessage;
});
// OR

cache.create("myCache", (error, data) => {
  if (error) throw data.errorMessage;
});

cache.set(key, value, [ttl], [callback]): Promise

Cache data or update an existing record.

• key: String

  Unique key identifying the cache entry

• value: Any

  Value to be Cached.

• ttl: Number Time to live in seconds (optional)

  • If ttl is not specified, then this method uses the ttl specified in the mmcache() constructor.
  • If no ttl is specified in the mmcache() constructor then default ttl value of 3600 seconds (1 hour) will be used.
  • -1 means no expiration.

const cache = new mmcache({
  url: "https://gdn.paas.macrometa.io",
  apiKey: "XXXX",
  name: "sampleCache"
});

await cache.create();

cache.set('cacheKey', { foo: 'bar' }, 120, function (error, data) {

  if (error) throw data.errorMessage;

  // do something
});
// OR

cache.set('cacheKey', { foo: 'bar' }, function (error, data) { // Without ttl

  if (error) throw data.errorMessage;

  // do something
});

cache.get(key, [callback]): Promise

Returns cached value of given key.

• key: String

  Unique key identifying the cache entry

const cache = new mmcache({
  url: "https://gdn.paas.macrometa.io",
  apiKey: "XXXX",
  name: "sampleCache"
});

await cache.create();

cache.get('cacheKey', function (error, data) {

  if (error) throw data.errorMessage;

  console.log(data.value); //-> { foo: "bar" }
});

cache.delete(key, [callback]): Promise

Delete cached entry.

• key: String

  Unique key identifying the cache entry

const cache = new mmcache({
  url: "https://gdn.paas.macrometa.io",
  apiKey: "XXXX",
  name: "sampleCache"
});

await cache.create();

cache.delete('cacheKey', function (error, data){

  if (error) throw data.errorMessage;

  console.log('value deleted');
});

cache.clear([callback]): Promise

Clears all cached data. Returns number of cleared records.

💡 Note: The cache itself is not deleted here.

const cache = new mmcache({
  url: "https://gdn.paas.macrometa.io",
  apiKey: "XXXX",
  name: "sampleCache"
});

await cache.create();

cache.clear((error, data) => {

  if (error) throw data.errorMessage;

  console.log(data.count); // number of cleared records.
});

cache.deleteCache([callback]): Promise

Deletes the persistent cache.

const cache = new mmcache({
  url: "https://gdn.paas.macrometa.io",
  apiKey: "XXXX",
  name: "sampleCache"
});

await cache.create();

cache.deleteCache((error, data) => {

  if (error) throw data.errorMessage;

  console.log('cache deleted');
});

cache.size([callback]): Promise

Returns number of cached records.

const cache = new mmcache({
  url: "https://gdn.paas.macrometa.io",
  apiKey: "XXXX",
  name: "sampleCache"
});

await cache.create();

cache.size((error, data) => {

  if (error) throw data.errorMessage;

  console.log(data.count); // number of cached records.
});

cache.allKeys([opts], [callback]): Promise

Returns list of all keys in a given cache.

• opts: Object (optional) is a JS object that can contain any of the following keys:

  • offset: String

    This option can be used to simulate paging. Default 0

  • limit: String

    This option can be used to simulate paging. Limit the result. Default 100, max 100

  • order: String

    Order the results asc or desc. Default asc

const cache = new mmcache({
  url: "https://gdn.paas.macrometa.io",
  apiKey: "XXXX",
  name: "sampleCache"
});

await cache.create();

cache.allKeys({offset: 100, limit: 4, order: "desc"}, (error, data) => {

  if (error) throw data.errorMessage;

  console.log(data); // returns 4 records after 100 with descending order
});

cache.setResponse(inputs, [callback]): Promise

Cache api response or update an existing record.

• inputs: Object is a JS object that can contain any of the following keys:

  • url: String

    Api url string.

  • data: Any

    response to be cached.

  • ttl: Number (optional)

    time to live in seconds. -1 means no expiration.

  • params: Object (optional)

    Any extra params or request body

const cache = new mmcache({
  url: "https://gdn.paas.macrometa.io",
  apiKey: "XXXX",
  name: "sampleCache"
});

await cache.create();

cache.setResponse({ url: "http://dummy.restapiexample.com/api/v1/update?qs=123", data: { foo: 'bar' }, ttl: 3600}, (error, data) => {
  
  if (error) throw data.errorMessage;

  // do something
});

cache.getResponse(inputs, [callback]): Promise

Returns cached response.

• inputs: Object is a JS object that can contain any of the following keys:

  • url: String

    Api url string.

  • params: Object (optional)

    Any extra params or request body

const cache = new mmcache({
  url: "https://gdn.paas.macrometa.io",
  apiKey: "XXXX",
  name: "sampleCache"
});

await cache.create();

cache.getResponse({url: "http://dummy.restapiexample.com/api/v1/update?qs=123"}, (error, data) => {
    
  if (error) throw data.errorMessage;

  console.log(data.value) // { foo: 'bar' }
});