quicache
    TypeScript icon, indicating that this package has built-in type declarations

    3.0.0 • Public • Published

    quiCache

    An in-memory key-value cache for Javascript and Typescript applications

    Install

    Yarn

    yarn add quiCache

    NPM

    npm i --save quiCache

    Introduction

    QuiCache is an in-memory caching solution for Javascript and Typescript applications. It relies only on the date-fns package, meaning that it should be compatible with every major JS environment out there.

    QuiCache provides a key-value structure for data to be stored in. When adding data to the cache, you specify the key, and the data as arguments to setCacheData(), and quiCache handles everything else. When reading data from the cache, simply provide the key to getCacheData().

    API / Documentation

    See the docs folder for full details. Usage examples can be found at the bottom of the readme.

    Version 3.0

    Version 3 now provides support for Typescript generics.

    This means that data returned from the following methods will infer type data:

    • onCacheDataAdd
    • onCacheDataAccessed
    • onCacheDataDelete
    • onCacheDataExpired
    • onCacheDataAlreadyExists
    • getCacheData
    • setCacheData
    • getAllCachedData
    • deleteCacheData

    Due to this, when creating a cache instance with new QuiCache(), you must also define the data type you're returning if you're fully typing it:

    interface IMyDataInterface {
      aString: string;
      aNumber: number;
      aBoolean: boolean;
    }
    
    const MyCache: ICacheManager<IMyDataInterface> = new QuiCache({
      cacheName: "MyCache",
      cacheMaxAgeInSeconds: 30
    });
    

    You can still create and manage your cache in the same way if you're not specifying the type ICacheManager, but type data may not be returned.

    This change doesn't prevent your ability to store data of any type in an individual cache field, but merely enhances the developer experience if you use 1 cache for data which follows a specific interface.

    No other changes beyond those in 2.0 are required to be compatible with QuiCache 3.0.

    Version 2.0

    Version 2 has completely overhauled the library, and is mostly incompatible with prior versions (due to changes to the constructor method and several methods being removed).

    The changes made should drastically simplify working with the library and provide a nicer developer experience.

    • A new method, deleteCacheData(), has been added to allow deletion of any cached data by providing it's field name / key
    • The concept of expired and non-expired data no longer exists - Cache data now automatically deletes when it expires
    • New optional callbacks in the constructor method have been aded: onCacheDataAdd, onCacheDataDelete, onCacheDataExpired, onCacheDataAlreadyExists
    • Version 2.1.2 has added some new optional callback:
      • onCacheDataAccessed - this will trigger when a field is accessed in the cache
      • onCacheDataDoesNotAlreadyExist - this will trigger if the specified field is not found in the cache when calling setCacheData, deleteCacheData
    • Enabling and disabling debug has been removed due to addition of callbacks
    • You can now provide a name to your cache, which can be useful for the callbacks
    • Methods to allow changing the cache age and name have been added
    • As of version 2.0.2 map is now used for storing data (instead of an object), meaning it is possible to set keys/fields of any type (instead of just string)
      • At this time, only strings and numbers are accepted as keys, but supporting all primitive types is planned for a future release

    Further notes on version 2.0

    • The constructor now expects an object with params/arguments
    • You can only specify a cache maximum age value in seconds (e.g. 120 = 2 minutes), and it is no longer possible to specify the unit of time
    • If a key already exists in the cache, it's data will not be overwritten when calling setCacheData()
    • It is possible to update the cache max age after creation by calling setCacheMaxAge() and passing a value
      • Values which were added to the cache before this method is called are not affected and will be removed at the end of the originally intended expiry time

    Interfaces

    The following interfaces and enums are exported from quicache to assist in development;

    ICacheManagerDataCache
    ICacheManager
    

    Example

    import quicache, { ICacheManager } from "quicache";
    
    // Create an interface for your data
    interface IMyInterface {
      aString: string;
      aBoolean: boolean;
      aNumber: number;
      anOptionalString?: string;
    }
    
    // Initialize the cache with your interface
    const myCache: ICacheManager<IMyInterface> = new quicache({
      cacheName: "MyCache",
      cacheMaxAgeInSeconds: 30,
      onCacheDataExpired: (data) =>
        console.log(`Field ${data.field} expired in cache ${data.cacheName}`),
      onCacheDataAdd: (data) =>
        console.log(`Field ${data.field} added to cache ${data.cacheName}`),
      onCacheDataAlreadyExists: (data) => {
        console.log(
          `Field ${data.field} already exists in cache ${data.cacheName}, and expires in ${data.expires} seconds`
        );
      },
    });
    
    const cacheKey = "testData";
    
    // If the data doesn't exist in the cache, we'll create it
    if (!myCache.cacheDataExists(cacheKey)) {
      try {
        const dataToSetInCache = {
          aString: "ABC",
          aBoolean: true,
          aNumber: 123,
        };
    
        // setCacheData returns the timestamp and data that it inserts into the cache
        return myCache.setCacheData(cacheKey, dataToSetInCache).data;
      } catch (err) {
        return err;
      }
    } else {
      // Data exists in cache, so we'll return it
      // getCacheData returns the timestamp and data
      const cachedata = myCache.getCacheData(cacheKey);
      return cachedata.data;
    }

    Author(s)

    👤 Scott Pritchard (Github, Twitter)

    Install

    npm i quicache

    DownloadsWeekly Downloads

    15

    Version

    3.0.0

    License

    MIT

    Unpacked Size

    524 kB

    Total Files

    36

    Last publish

    Collaborators

    • chronsyn