lru-cache.node.txt

             
   LRU-CACHE  
             



VERSION ==>                       #10.0.1
                                  #Node.js or browser

ALTERNATIVES ==>                  #  - node-lru-cache (preferred if needs features):
                                  #     - most high-profile
                                  #     - per-item space, TTL, bounced TTL, iteration, onRemove handler
                                  #     - slowest
                                  #     - Node only
                                  #  - quick-lru (preferred if needs simple):
                                  #     - browser/Node
                                  #     - TTL, iteration
                                  #  - flru:
                                  #     - fast
                                  #     - browser/Node
                                  #  - tiny-lru:
                                  #     - TTL
                                  #     - browser/Node

new LRUCache([NUM|OPTS])          #LRU cache
                                  #Recentness is updated by get|set|pop|del|reset|[r]forEach|purgeStale|dump|load() but not by
                                  #peek|has|keys|values|size|itemCount()

OPTS.max                          #NUM (def: 0). Max items
OPTS.maxSize                      #NUM (def: 0). Max space
                                  #If on limit, when adding a new item, least recent will be deleted
OPTS.maxEntrySize                 #NUM (def: 0). Max space per item
                                  #If on limit, item will not be added
OPTS.sizeCalculation              #FUNC(VAL, 'KEY')->NUM. Number of spaces taken by VAL
                                  #Def: 1

OPTS.ttl                          #TTL_NUM (def: null, in ms). TTL per item
OPTS.ttlAutopurge                 #BOOL. If false (def), items are lazily deleted (i.e. only when retrieved)
                                  #If true, run every OPTS.ttlResolution NUMms instead (def: 1)
OPTS.updateAgeOnGet|Has           #BOOL (def: false). Update TTL on get|has()
OPTS.noUpdateTTL                  #BOOL (def: false). Do not update TTL on set() if key already exists
OPTS.allowStale                   #BOOL. If false (def): item over maxAge is deleted then returned as undefined
                                  #If true: item over maxAge is returned then deleted

OPTS.dispose[After]               #FUNC('KEY', VAL, STR).
                                  #Called when KEY is either:
                                  #  - replaced (not initially set) providing OPTS.noDisposeOnSet false (def)
                                  #  - deleted
                                  #Called before replacement|deletion, i.e. can put in back on next tick
                                  #  - after it if disposeAfter()
                                  #STR is 'evict', 'set' or 'delete'

OPTS.fetchMethod                  #FUNC('KEY', VAL, OBJ)->>VAL2
                                  #See fetch()
                                  #VAL is value if stale and OPTS.allowStale true
                                  #Called only once per fetch()
                                  #OBJ: options OPTS, signal ABORT_SIGNAL, context VAL
OPTS.noDeleteOnStaleGet           #BOOL (def: false). State values are not removed on get()
OPTS.noDeleteOnFetchRejection     #BOOL (def: false). When fetchMethod() throws, stale values are not removed
OPTS.allowStaleOnFetchRejection   #BOOL (def: false). When fetchMethod() throws, return stale value, and do no remove it
OPTS.ignoreFetchAbort             #BOOL (def: false). When fetchMethod() aborts (due to `signal`), let resolved|rejected value update the cache
OPTS.allowStateOnFetchAbort       #BOOL (def: false). When fetchMethod() aborts (due to `signal`), return stale value right away

'KEY'                             #Can be any VAL, using === equality
LRUCACHE.get('KEY'[, OPTS])
 ->VAL|undefined                  #OPTS: updateAgeOnGet|allowStale
LRUCACHE.peek('KEY')
 ->VAL|undefined                  #OPTS: allowStale
LRUCACHE.set('KEY', VAL[, OPTS])  #Returns false if item is bigger than OPTS.max
 ->BOOL                           #OPTS:
                                  #  - size|sizeCalculation|ttl|noDisposeOnSet
                                  #  - start (def: now) for the start time for ttl
LRUCACHE.pop()->VAL               #Returns most recent item, and delete it
LRUCACHE.delete('KEY')->BOOL      #Same as LRUCACHE.set('KEY', undefined) since undefined values are never stored
LRUCACHE.clear()                  #

LRUCACHE.has('KEY')->BOOL         #
LRUCACHE.keys()->'KEY'_ARR        #
LRUCACHE.values()->VAL_ARR        #
LRUCACHE.entries()
 ->['KEY', VAL]_ARR               #
LRUCACHE.rkeys|rvalues|rentries() #Same but in reverse order
LRUCACHE.size                     #NUM (in items)
LRUCACHE.calculatedSize           #NUM (in space)
LRUCACHE.[r]forEach               #Most recently used items first
 (FUNC(VAL, 'KEY', LRUCACHE)      #Def CONTEXT is LRUCACHE
 [, CONTEXT])                     #'r' is in reverse order
LRUCACHE.find
 (FUNC(VAL, 'KEY', LRUCACHE)
 ->BOOL[, OPTS])                  #OPTS: same as get()

LRUCACHE.getRemainingTTL('KEY')
 ->NUM                            #0 if not cached. Infinity if no TTL.
LRUCACHE.purgeStale()             #Remove all stale items (instead of waiting for lazy deletion)

LRUCACHE.dump()->ARR              #Save state to ARR of ['KEY', OBJ] with OBJ: value VAL, start TIMESTAMP_NUM, size NUM, ttl NUM
LRUCACHE.load(ARR)                #Restore state from ARR

LRUCACHE.fetch('KEY'[, OPTS])     #Like get() except when not available, calls fetchMethod() to populate it
 ->PROMISE_VAL|undefined          #OPTS:
                                  #  - updateAgeOnGet|allowStale|size|sizeCalculation|ttl|noDisposeOnSet|context
                                  #  - forceRefresh BOOL (def: false): re-fetch items even if not stale
                                  #  - signal ABORT_SIGNAL

OPTS.status                       #OBJ filled with some metadata about internal state (not documented here)
                                  #Can be used on LRUCACHE.get|set|has|fetch()