Secondary Cache

It can support secondary cache mechanism. the first level cache is fixed memory-resident always with the highest priority. the second level is the LRU cache.

the secondary LRU cache only available set the capacity of options or the key's expires time.

• Cache(options|capacity):

  • options object
    • fixedCapacity: the first fixed cache max capacity size, defaults to unlimit.
    • capacity: the second LRU cache max capacity size, defaults to 1024. deletes the least-recently-used items if reached the capacity. capacity > 0 to enable the secondary LRU cache.
    • maxWeight: the maximum total weight of all items in the LRU cache. defaults to 0 (no weight limit).
    • weightOf: a function(value, id) to calculate the weight of a value. defaults to returning 1 (count-based).
    • expires: the default expires time (milliscond), defaults to no expires time(<=0). it will be put into LRU Cache if has expires time
    • cleanInterval: clean up expired item with a specified interval(seconds) in the background. disable clean in the background if it's value is less than or equal 0.
  • events:
    • 'before_add': triggle on a new key before added to cache.
    • 'before_update':triggle on a key before updated to cache.
    • 'add': triggle on a new key added to cache.
    • 'update':triggle on a key updated to cache.
    • 'del': triggle on a key removed from cache.

• LRUCache(options|capacity): the LRU cache Class with expires supports.

  • options object
    • capacity: the LRU cache max capacity size, defaults to 1024. deletes the least-recently-used items if reached the capacity. capacity > 0 to enable the LRU.
    • maxWeight: the maximum total weight of all items in cache. defaults to 0 (no weight limit). When weight limit is exceeded, LRU items are evicted. If a single item's weight exceeds maxWeight, an error is thrown.
    • weightOf: a function(value, id) to calculate the weight of a value. defaults to returning 1 (count-based). Override to implement size-based limits.
    • expires: the default expires time (milliscond), defaults to no expires time(<=0). it will be put into LRU Cache if has expires time
    • cleanInterval: clean up expired item with a specified interval(seconds) in the background. disable clean in the background if it's value is less than or equal 0.
  • events:
    • 'before_add': triggle on a new key before added to cache.
    • 'before_update':triggle on a key before updated to cache.
    • 'add': triggle on a new key added to cache.
    • 'update':triggle on a key updated to cache.
    • 'del': triggle on a key removed from cache.

LRUCache API

• LRUCache(options|capacity): the LRU cache Class with expires supports.

  • constructor(options?): creates a new LRUCache instance.
    • options object:
      • capacity: the LRU cache max capacity size, defaults to 1024.
      • maxWeight: the maximum total weight of all items in cache.
      • weightOf: a function(value, id) to calculate the weight of a value.
      • expires: the default expires time (millisecond).
      • cleanInterval: clean up expired item with a specified interval(seconds).

• lruCache.set(id, value, [expires])

  • add/update a key-value pair. returns the cache instance.

• lruCache.get(id)

  • get value by id, updates "recently used"-ness.

• lruCache.peek(id)

  • get value by id, does NOT update "recently used"-ness.

• lruCache.has(id)

  • aliases: isExist, isExists
  • check if id exists in cache (and not expired).

• lruCache.delete(id)

  • alias: del
  • delete a key from cache, returns true if deleted.

• lruCache.clear()

  • clear all items, returns the cache instance.

• lruCache.free()

  • free all memory used by the cache.

• lruCache.forEach(callback[, thisArg])

  • iterate over each item. callback receives (value, id, cache).

• lruCache.reset(options|capacity)

  • clear cache and apply new options, returns the cache instance.

• lruCache.length()

  • return the number of items in cache.

• lruCache.isExpired(item)

  • check if item is expired, removes it if expired. returns boolean.

• lruCache.clearExpires()

  • delete all expired items from cache.

• lruCache.weightOf(value, id)

  • calculate weight of a value. defaults to return 1 (count-based).
  • override to implement custom weight calculation (e.g., byte size).

• lruCache.on(event, listener)

• lruCache.off(event, listener)

• lruCache.delListener(event, listener)

  • add/remove event listeners.

• lruCache.totalWeight (readonly property)

  • the total weight of all items in cache (only meaningful when maxWeight > 0).

LRUQueue API

• LRUQueue(capacity): the LRU queue class for object queue item.
  • add(id): add the id object to the queue. Returns the removed item if capacity exceeded.
  • push(id): alias of add.
  • pop(): removes and returns the least recently used item from the queue.
  • use(id): make the id object in the queue as most recently used items first.
  • hit(value): check if value exists in queue, add if not, or move to most recently used.
  • del(id): del the id object from the queue.
  • delete(id): alias of del.
  • clear(): removes all items from the queue.
  • shiftLU(): shifts the least recently used position to the first used position.
  • forEach(callback[, thisArg]): iterates over each item in the queue.
    • callback receives (item, thisArg). If thisArg is provided, it's passed as second param; otherwise the queue itself is passed.
  • Properties:
    • maxCapacity: the maximum capacity of the queue.
    • length: the current number of items in the queue.
  • note: it used the 'lu' property of the object queue item.

usage

import {Cache, LRUCache} from 'secondary-cache'

cache = new Cache()

// track storage size
cache.maxSize = 0
cache.on('before_add', function(key, value) {
  const cache = this.target
  if (cache.maxSize > MAX_SIZE) {
    cache.clear();
    cache.maxSize = 0;
  }
  cache.maxSize += sizeCalculation(value, key)
})

// clean up when objects are evicted from the cache
cache.on('del', function(key, value){
  freeFromMemory(value)
})

cache.set('key', 'value', {fixed:true}) // put it into fixed capacity storage.
cache.get('key')

cache.set('expiresKey', 'value', 1000) // expired after 1 second

// or only use LRU Cache
cache = new LRUCache(1000)

// Weight-based LRU Cache
const lruCache = new LRUCache({
  maxWeight: 1000, // total weight limit
  capacity: 0,     // unlimited by count
  weightOf: function(value, key) {
    // Calculate weight based on value size (e.g., byte length)
    return Buffer.byteLength(JSON.stringify(value), 'utf8');
  }
});
lruCache.set('key', 'some data'); // weight is calculated automatically
console.log(lruCache.totalWeight); // get total weight of all items
// If weight exceeds maxWeight, throws Error: 'Item weight X exceeds maxWeight Y'

cache.set(key, value[,options|expires])

add/update key, value to cache.

• options:
  • fixed (bool): set to first level fixed cache if true, defaults to false.
  • expires (int): expires time milliscond. defaults to never expired.

It will update the "recently used"-ness of the key if LRUCache enabled.

cache.setFixed(key, value)

add/update key,value to the first level fixed cache directly.

cache.setLRU(key, value[,expires])

add/update key,value to the secondary level LRU cache directly.

cache.get(key)

get the key from cache. it will fetch the key from the first fixed cache, fetch the key from the secondary cache if missing in the first cache.

It will update the "recently used"-ness of the key in the secondary cache if LRUCache enabled.

cache.getFixed(key)

get the key from the first level fixed cache directly.

cache.getLRU(key)

get the key from the secondary level LRU cache directly.

cache.peek(id)

get the key from cache. it will fetch the key from the first fixed cache, fetch the key from the secondary cache if missing in the first cache.

It will not update the "recently used"-ness in the secondary cache.

cache.peekLRU(id)

get the key from the secondary LRU cache directly.

It will not update the "recently used"-ness in the secondary cache.

cache.has(key)

aliases: isExist, isExists

the key whether exists in the cache.

cache.forEach(callback[, thisArg])

executes a provided function once per each value in the cache. first iterated the fixed cache , and then the LRU cache.

• callback: Function to execute for each element. callback is invoked with three arguments:
  • the element value
  • the element key
  • the cache object
• thisArg: Value to use as this when executing callback.

cache.forEachFixed(callback[, thisArg])

executes a provided function once per each value in the first level fixed cache, in insertion order.

cache.forEachLRU(callback[, thisArg])

executes a provided function once per each value in the secondary level LRU cache, in order of recent-ness (more recently used items are iterated over first) if LRU is enabled. Or in insertion order.

cache.del(key)

alias: delete

Deletes a key out of the cache (searches both fixed and LRU caches).

cache.delLRU(key)

alias: deleteLRU deletes a key from the secondary level LRU cache.

cache.delFixed(key)

alias: deleteFixed deletes a key from the first level fixed cache.

cache.reset(options|capacity)

Clear the cache entirely and apply the new options.

• options object
  • fixedCapacity: the first fixed cache max capacity size, defaults to unlimit.
  • capacity: the second LRU cache max capacity size, defaults to unlimit. deletes the least-recently-used items if reached the capacity. capacity > 0 to enable the secondary LRU cache.
  • expires: the default expires time (seconds), defaults to no expires time(<=0). it will be put into LRU Cache if has expires time

cache.clear()

Clear the cache entirely.

cache.on(event, listener)

Adds a listener for the specified event.

• event
  • 'add': triggle on a new key added to cache.
  • 'update':triggle on a key updated to cache.
  • 'del': triggle on a key removed from cache.

cache.free()

free the first fixed cache and the secondary LRU cache.

cache.setDefaultOptions(options: ICacheOptions|capacity)

Sets the default options for Cache.

cache.length()

return the number of items in the FixedCache and LRUCache.

cache.hasFixed(key)

check if key exists in the first level fixed cache.

cache.hasLRU(key)

check if key exists in the secondary level LRU cache.

cache.deleteLRU(key)

alias: delLRU delete a key from the secondary level LRU cache.

cache.deleteFixed(key)

alias: delFixed delete a key from the first level fixed cache.

cache.freeLRU()

free the secondary level LRU cache.

cache.setDefaultOptions(options|capacity)

sets the default options for the cache.

cache.setDefaultOptionsLRU(options|capacity)

sets the default options for the secondary level LRU cache.