Mastak

An npm module for in-memory automated API caching.
Built with TypeScript.

About • Installation • Initialization • Types • Usage • Contribution • Authors • License

About

An npm module to automate the regular processing and caching of responses from APIs. With a caching mechanism inspired by node-cache, this module has all the standard interface methods to interact with the in-memory cache.
Mastak makes requests using node-fetch and processes the response based on the resProcessor() function provided by the user. Each key gets a timeout(ttl) and an updateInterval(if autoUpdate is true).

Installation

$ npm install mastak --save

Initialization

const Mastak = require("mastak");
const cache = new Mastak();

To import the module in TypeScript, esModuleInterop needs to be set to true in your tsconfig.json.

Options

• stdTTL: (default: 0) - the standard timeout(in seconds) for each element of the cache, 0 = infinite.
• autoUpdate: (default: true) - boolean flag that states if each element in the cache has to be regularly updated or not.
• updateInterval: (default: 3600(1 hr in secs)) - the standard interval(in seconds) at which each element in the cache has to be updated.
• checkPeriod: (default: 600(10 min in secs)) - the regular interval(in seconds) at which the internal checkData() method will check each element for timeout and autoUpdate.

Example

const Mastak = require("mastak");
const cache = new Mastak({
  stdTTL: 1800,
  updateInterval: 7200,
});

Types

There are 3 types/interfaces that a user has to take into account when using Mastak, i.e. Request, CacheInput & CacheUnit.
Request & CacheInput define the format of input that is expected from the user while CacheUnit defines the format in which an API and its value is stored within the cache.

Request

Request defines the data needed to form a valid request that can be sent using node-fetch.

interface Request {
  url: string; // url for the api
  method: string; // http method to be used
  body?: {
    [key: string]: any; // body for the request
  };
  headers?: {
    [key: string]: string; // headers
  };
}

CacheInput

CacheInput defines all the data that needs to be input to set or update an API.

interface CacheInput {
  request: Request;
  resProcessor?: any; // a function that processes the response recieved
  updateInterval?: number; // the interval over which the API needs to be updated
  ttl?: number; // the timeout for the API
}

CacheUnit

CacheUnit defines the format in which an API is stored in the cache. It extends CacheInput i.e. it inherits all its properties.

interface CacheUnit extends CacheInput {
  setTime: number; // the time at which this API/CacheUnit was set
  lastUpdate: number; // the time at which the value was last updated
  value: any; // the processed response from the API
}

? - field is not required.

Take a look at src/types/main.interfaces.ts to see all the defined interfaces.

Usage

set()

Set an API or CacheUnit in the cache with the key provided.
Returns a promise that resolves with the entire CacheUnit stored against a key or rejects an error.

Mastak.set((key: string), (api: CacheInput));

Example

const request = {
  url: "https://jsonplaceholder.typicode.com/posts",
  method: "POST",
  body: {
    title: "foo",
    body: "bar",
    userId: 1,
  },
  headers: {
    "Content-type": "application/json; charset=UTF-8",
  },
};

const api = {
  request: request,
  ttl: 1800,
};

const foo = async () => {
  try {
    let response = await cache.set("JSONPlaceholder", api);
    console.log("set()", response);
  } catch (err) {
    console.warn(err.message);
  }
};

foo();

Output

set() { setTime: 1621113414640,
lastUpdate: 1621113414640,
value: { title: 'foo', body: 'bar', userId: 1, id: 101 },
request:
{ url: 'https://jsonplaceholder.typicode.com/posts',
method: 'POST',
body: { title: 'foo', body: 'bar', userId: 1 },
headers: { 'Content-type': 'application/json; charset=UTF-8' } } }

---

get()

Get the currently stored value for an API with the key.
Returns the "value" for the CacheUnit or throws a BadKey error.

Mastak.get((key: string));

Example

try {
  let response = await cache.get("JSONPlaceholder");
  console.log("get()", response);
} catch (err) {
  console.warn(err.message);
}

Output

get() { title: 'foo', body: 'bar', userId: 1, id: 101 }

---

update()

Update the data of a CacheUnit and update its value if updateNow argument is true.
Returns a promise that resolves with the updated CacheUnit or rejects an error.

Mastak.update((key: string), (api: CacheInput), (updateNow: boolean));

Example

const request2 = {
  url: "https://jsonplaceholder.typicode.com/posts/2",
  method: "PATCH",
  body: {
    title: "foo",
  },
};

const resProcessor2 = (data) => {
  return data.userId;
};

const api2 = {
  request: request2,
  resProcessor: resProcessor2,
};

const foo = async () => {
  try {
    response = await cache.update("JSONPlaceholder", api2, true);
    console.log("update()", response);
  } catch (err) {
    console.warn(err.message);
  }
};

foo();

Output

update() { setTime: 1621113648549,
lastUpdate: 1621113649233,
value: 1,
request:
{ url: 'https://jsonplaceholder.typicode.com/posts/2',
    method: 'PATCH',
    body: { title: 'foo' } },
resProcessor: [Function: something2] }

---

delete()

Delete a CacheUnit with the key.
Returns boolean - true if successful or throws a BadKey error

Mastak.delete((key: string));

Example

try {
  let response = await cache.delete("JSONPlaceholder");
  console.log("delete()", response);
} catch (err) {
  console.warn(err.message);
}

Output

delete() true

---

setMulti()

Set multiple APIs or CacheUnits in the cache with arrays of keys and CacheInputs.
Returns a promise that resolves with an array of proccessed CacheUnits or rejects an error.

Mastak.setMulti((keys: Array<string>), (apis: Array<CacheInput>));

Example

const request = {
  url: "https://jsonplaceholder.typicode.com/posts",
  method: "POST",
  body: {
    title: "foo",
    body: "bar",
    userId: 1,
  },
  headers: {
    "Content-type": "application/json; charset=UTF-8",
  },
};

const request2 = {
  url: "https://jsonplaceholder.typicode.com/posts/2",
  method: "PATCH",
  body: {
    title: "foo",
  },
};

const resProcessor2 = (data) => {
  return data.userId;
};

const api: CacheInput = {
  request: request,
  ttl: 1800,
};

const api2 = {
  request: request2,
  resProcessor: resProcessor2,
};

const foo = async () => {
  try {
    let response = await cache.setMulti(
      ["JSONPlaceholder", "JSONPlaceholder2"],
      [api, api2]
    );
    console.log("setMulti()", response);
  } catch (err) {
    console.warn(err.message);
  }
};

foo();

Output

setMulti()[
  ({
    setTime: 1621113734595,
    lastUpdate: 1621113734595,
    value: { title: "foo", body: "bar", userId: 1, id: 101 },
    request: {
      url: "https://jsonplaceholder.typicode.com/posts",
      method: "POST",
      body: [Object],
      headers: [Object],
    },
  },
  {
    setTime: 1621113735169,
    lastUpdate: 1621113735169,
    value: 1,
    request: {
      url: "https://jsonplaceholder.typicode.com/posts/2",
      method: "PATCH",
      body: [Object],
    },
    resProcessor: [(Function: something2)],
  })
];

---

getMulti()

Get current value of multiple CacheUnits with an array of keys.
Returns an array of values or throws a BadKey error.

Mastak.getMulti((keys: Array<string>));

Example

try {
  let response = cache.getMulti(["JSONPlaceholder", "JSONPlaceholder2"]);
  console.log("getMulti()", response);
} catch (err) {
  console.warn(err.message);
}

Output

getMulti() { JSONPlaceholder: { title: 'foo', body: 'bar', userId: 1, id: 101 },
  JSONPlaceholder2: 1 }

---

has()

Checks if the cache contains a key or not.
Returns boolean - true or false

Mastak.has((key: string));

Example

let response = cache.has("JSONPlaceholder");
console.log("has()", response);

Output

has() true

---

keys()

Get all the keys currently stored in the cache.
Returns an array of strings(keys).

Mastak.keys();

Example

let response = cache.keys();
console.log("keys()", response);

Output

keys()[("JSONPlaceholder", "JSONPlaceholder2")];

---

deleteMulti()

Delete multiple CacheUnits with an array of keys.
Returns boolean - true if successful or throws a BadKey error.

Mastak.deleteMulti((keys: Array<string>));

Example

try {
  let response = cache.deleteMulti(["JSONPlaceholder", "JSONPlaceholder2"]);
  console.log("deleteMulti()", response);
} catch (err) {
  console.warn(err.message);
}

Output

deleteMulti() true

---

take()

Delete a CacheUnit and return its value.
Returns the deleted CacheUnit or throws a BadKey error.

Mastak.take((key: string));

Example

try {
  let response = cache.take("JSONPlaceholder");
  console.log("take()", response);
} catch (err) {
  console.warn(err.message);
}

Output

take() { setTime: 1621113915875,
lastUpdate: 1621113915875,
value: { title: 'foo', body: 'bar', userId: 1, id: 101 },
request:
{ url: 'https://jsonplaceholder.typicode.com/posts',
    method: 'POST',
    body: { title: 'foo', body: 'bar', userId: 1 },
    headers: { 'Content-type': 'application/json; charset=UTF-8' } } }

---

flush()

Delete all the data in the cache.
Returns boolean - true.

Mastak.flush();

Example

let response = cache.flush();
console.log("flush()", response);

Output

flush() true

---

Contribution

Fork the repository and open a pull request to contribute. Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Authors

• Araekiel

License

MIT License

Copyright (c) 2021 Kumar Shashwat

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.