Package Exports

@mongez/cache
@mongez/cache/cjs/index.js
@mongez/cache/esm/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@mongez/cache) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

Mongez Cache

This cache package handles various ways to store data in the browser.

The current cache system implements Local Storage Cache.

By default there is a Cache Manager that manages the caching behind the scenes.

Installation

yarn add @mongez/cache

npm i @mongez/cache

Usage

First off, let's define our cache configurations so we can use cache later without setting it every time.

Setting Cache Configurations

import { PlainLocalStorageDriver, setCacheConfigurations } from "@mongez/cache";

setCacheConfigurations({
  driver: new PlainLocalStorageDriver(),
});

Storing value in the cache

import cache from "@mongez/cache";

// this will store in the local storage in the browser key `name` and its corresponding value `Hasan`
cache.set("name", "Hasan");

We can also store arrays or objects.

import cache from "@mongez/cache";

// store array
cache.set("letters", ["a", "b", "c", "d", "e", "f"]);

// store object
cache.set("user", {
  id: 1,
  name: "Hasan",
});

Getting Value from storage

import cache from "@mongez/cache";

console.log(cache.get("name")); // Hasan

If the key doesn't exist we can return a default value instead.

import cache from "@mongez/cache";

console.log(cache.get("some-not-stored-key", "Welcome")); // Welcome

If no default value passed and the key does not exist, then null will be returned.

Getting stored arrays or objects:

import cache from "@mongez/cache";

console.log(cache.get("letters")); // [ 'a', 'b', 'c', 'd', 'e', 'f']
console.log(cache.get("user")); // { id: 1, name: 'Hasan'}

Setting Key Prefix

We can also define a prefix key that prefixes all of our keys.

It's recommended to define a prefix key to your app, so similar keys don't override each other especially if you're working on localhost.

import { PlainLocalStorageDriver, setCacheConfigurations } from "@mongez/cache";

setCacheConfigurations({
  driver: new PlainLocalStorageDriver(),
  key: "store-",
});

// this will store in the local storage in the browser key `store-name` and its corresponding value `Hasan`
cache.set("name", "Hasan");

console.log(cache.get("name")); // Hasan

Removing key from storage

import cache from "@mongez/cache";

cache.remove("name");

console.log(cache.get("name")); // null

Cache Drivers List

The following list implements Cache Driver Interface.

Plain Local Storage Driver

The plain local storage implements Local Storage of the browser.

The driver name is: PlainLocalStorageDriver

import {
  PlainLocalStorageDriver,
  setCacheConfigurations,
} from "@mongez/cache";

setCacheConfigurations({
  driver: new PlainLocalStorageDriver(),
});

cache.set("name", "Hasan");

console.log(cache.get("name")); // Hasan

Encrypted Local Storage Driver

Works exactly same as Plain Local Storage Driver except that values are encrypted when stored in the storage.

To make this work, make sure that you've set encryption key in Encryption Configuration, the @mongez/encryption package is a dependency to this package so you don't have to install it again.

import { setEncryptionConfigurations } from "@mongez/encryption";
import {
  EncryptedLocalStorageDriver,
  setCacheConfigurations,
} from "@mongez/cache";

// make sure to set the encryption key at some point in your application

setEncryptionConfigurations({
  key: "app-key",
});

setCacheConfigurations({
  driver: new EncryptedLocalStorageDriver(),
});

// The value will be stored as encrypted value something like store-name: asdfgtrhy54rewqsdaftrgyujiy67t54re3wqsd
cache.set("name", "Hasan");

console.log(cache.get("name")); // Hasan

Plain Session Storage Driver

Added in v1.1

The plain session storage implements Session Storage of the browser.

The driver name is: PlainSessionStorageDriver

import {
  PlainSessionStorageDriver,
  setCacheConfigurations,
} from "@mongez/cache";

setCacheConfigurations({
  driver: new PlainSessionStorageDriver(),
});

cache.set("name", "Hasan");

console.log(cache.get("name")); // Hasan

Encrypted Session Storage Driver

Added in v1.1

Works exactly same as Plain session Storage Driver except that values are encrypted when stored in the storage.

To make this work, make sure that you've set encryption key in Encryption Configuration, the @mongez/encryption package is a dependency to this package so you don't have to install it again.

import { setEncryptionConfigurations } from "@mongez/encryption";
import {
  EncryptedSessionStorageDriver,
  setCacheConfigurations,
} from "@mongez/cache";

// make sure to set the encryption key at some point in your application

setEncryptionConfigurations({
  key: "app-key",
});

setCacheConfigurations({
  driver: new EncryptedLocalStorageDriver(),
});

// The value will be stored as encrypted value something like store-name: asdfgtrhy54rewqsdaftrgyujiy67t54re3wqsd
cache.set("name", "Hasan");

console.log(cache.get("name")); // Hasan

Runtime Driver

Added in v1.1

If you just want to cache the data in the runtime (memory), use RunTimeDriver instead.

import cache, { RunTimeDriver, setCacheConfigurations } from "@mongez/cache";

setCacheConfigurations({
  driver: new RunTimeDriver(),
});

cache.set("name", "Hasan");

console.log(cache.get("name")); // Hasan

Expire Time

Added in v1.1

You can set an expire time for each key, the key will be removed from the storage after the expire time.

import cache from "@mongez/cache";

cache.set("name", "Hasan", 60 * 5); // expires in 5 minutes

// after one minute
cache.get('name'); // Hasan

// after 5 minutes
cache.get('name'); // null

This will store the key name with value Hasan and it will be removed after 5 minutes.

By default the cache value will be cached for ever, You can override the default expire time from the configuration.

import { setCacheConfigurations } from "@mongez/cache";

setCacheConfigurations({
  expireTime: 60 * 5, // 5 minutes
});

The default value of expire time is Infinity which means the value will be cached for ever.

Cache Manager

By default the cache manager is shipped with a new instance from CacheManager class, so you don't have to create it again, however, you can make a new instance of it by importing it directly.

import {
  PlainLocaleStorageDriver,
  CacheManager,
  CacheManagerInterface,
} from "@mongez/cache";

const cache: CacheManagerInterface = new CacheManager();

cache.setDriver(PlainLocaleStorageDriver).setPrefixKey("my-key");

// start using it.

Using Storage Driver Directly

You may also use any driver directly, the cache manager is just a facade to the storage driver

import { PlainLocaleStorageDriver, CacheDriverInterface } from "@mongez/cache";

const cacheDriver: CacheDriverInterface = new PlainLocaleStorageDriver();

cacheDriver.set("name", "Hasan"); // Hasan is stored in locale storage
//

Cache Driver Interface

type CacheDriverInterface = {
  /**
   * Set cache into storage
   */
  set(key: string, value: any, expiresAfter?: number): void;

  /**
   * Get value from cache engine, if key does not exist return default value
   */
  get(key: string, defaultValue: any): any;

  /**
   * Determine whether the cache engine has the given key
   */
  has(key: string): boolean;

  /**
   * Remove the given key from the cache storage
   */
  remove(key: string): void;

  /**
   * Set prefix key
   */
  setPrefixKey(key: string): void;

  /**
   * Get prefix key
   */
  getPrefixKey(): string;
};

Cache Manager Interface

 interface CacheManagerInterface extends CacheDriverInterface {
  /**
   * Set driver engine
   */
  setDriver(driver: CacheDriverInterface): void;
  /**
   * Get driver engine
   */
  getDriver(): CacheDriverInterface;
}

Getting Cache Configurations

Added in v1.1

You can get the current cache configurations by importing getCacheConfigurations function.

import { getCacheConfigurations } from "@mongez/cache";

const configurations = getCacheConfigurations();

Or if you want to get just one value use getCacheConfig(key: string) instead.

import { getCacheConfig } from "@mongez/cache";

const expiresAfter = getCacheConfig("expiresAfter");

Change Log

Version 1.1.0 (04 Nov 2022)
- Added Runtime Cache Driver.
- Added Plain Session Cache Driver.
- Added Encrypted Session Cache Driver.
- Added Expire Time.
- Added Getting Cache Configurations.

TODO

Add Unit Tests.
Add encryptKey feature to encrypt the key itself.