macrometa-realtime-cache

The official C8 cache JavaScript driver.

Usage no npm install needed!

<script type="module">
  import macrometaRealtimeCache from 'https://cdn.skypack.dev/macrometa-realtime-cache';
</script>

README

macrometa-realtime-cache

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

Installation

$ npm install macrometa-realtime-cache

Usage

import mmcache from "macrometa-realtime-cache"; // Browser
// OR
const mmcache = require("macrometa-realtime-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: "fetch",
  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.

:bulb: 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.

:bulb: 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: 120,
  },
  (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' }
  }
);

cache.onCacheUpdate(subscriptionName, [opts], [callback]):

Returns updated data with key and value in callback for defined KV collection.

:bulb: Note: Usage of this api requires websocket support.

  • subscriptionName: string (optional)

    The name of the subscription.

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

    • keepAlive: This will send noop message after every sendNoopDelay to keep connection alive if provided true. Default is false.

      :bulb: Note: noop basically a dummy message called no operation.

    • sendNoopDelay: The number of milliseconds after which noop message will be sent. default is 30000.

    • retries: The maximum amount of times to retry the operation. Default is 10. Seting this to 1 means do it once, then retry it once.

    • factor: The exponential factor to use. Default is 2.

    • minTimeout: The number of milliseconds before starting the first retry. Default is 1000.

    • maxTimeout: The maximum number of milliseconds between two retries. Default is Infinity.

    • randomize: Randomizes the timeouts by multiplying with a factor between 1 to 2. Default is false.

    • forever: Whether to retry forever, defaults to false.

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

await cache.create();

cache.onCacheUpdate("my-sub", { retries: 2 }, (error, data) => {
  if (error) throw data.errorMessage;

  console.log(data);
});