Visual Studio Code extension value caching

This module is intended to be used only by Visual Studio Code extension authors. While it does not have any other module dependencies, it is only useful for developing VSCode extensions and serves no other real purpose outside the scope of Visual Studio Code extension development.

vscode-cache is an abstraction of the VSCode API ExtensionContext.globalState interface. The globalState object is a simple storage mechanism that extensions can use to save and retrieve values and objects persistently (even between VSCode sessions). vscode-cache is a simple and powerful interface that wraps the globalState object, adding expirations, existence checking, etc.

Why would I want to use this in my VSCode extension?

This module is ideal for extensions to store arbitrary data for long or short term. Some examples:

Cache data that you grabbed from some database instead of hitting that database server each time

Cache results from that 3rd party REST API that charges you for each connection

Save user input that you aquired via the vscode.window.showInputBox() or vscode.window.showQuickPick() methods

Installation

# npm install vscode-cache --save

Basic Usage

const Cache = require ( ' vscode-cache ' ) ; let activate = ( extensionContext ) => { let myCache = new Cache ( extensionContext ) ; myCache . put ( ' userName ' , ' John Doe ' ) . then ( ( ) => { console . log ( myCache . has ( ' userName ' ) ) ; let userName = myCache . get ( ' userName ' ) ; } ) ; } ;

Optional expirations

You can optionally pass an expiration/lifetime (in seconds) for the cached item. If the current time is passed the expiration, then the cache no longer has it.

myCache . put ( ' searchResults ' , results , 5 ) . then ( ( ) => { console . log ( myCache . has ( ' searchResults ' ) ) ; setTimeout ( ( ) => { console . log ( myCache . has ( ' searchResults ' ) ) ; } , 10000 ) ; } ) ;

Default values

You can optionally specify a default value when fetching a cache item just in case it doesn't exist or is expired.

myCache . has ( ' foo ' ) ; let foo = myCache . get ( ' foo ' , ' bar ' ) ; console . log ( foo ) ;

Custom Namespaces

You can specify an optional namespace when instantiating your cache just in case you wanted more than one cache. This keeps them separate within the globalState object. The advantage of this is that you can use the same cache keys on different caches in order to store different values.

let apiCache = new Cache ( extensionContext , ' api ' ) ; let databaseCache = new Cache ( extensionContext , ' database ' ) ; apiCache . put ( ' foo ' , apiResults ) ; databaseCache . put ( ' foo ' , databaseResults ) ;

Cache

Kind: global class

new Cache(context, [namespace])

A module for use in developing a Visual Studio Code extension. It allows an extension to cache values across sessions with optional expiration times using the ExtensionContext.globalState.

Returns: Cache - The cache object

Param Type Description context vscode.ExtensionContext The Visual Studio Code extension context [namespace] string Optional namespace for cached items. Defaults to "cache"

cache.put(key, value, [expiration]) ⇒ Thenable

Store an item in the cache, with optional expiration

Kind: instance method of Cache

Returns: Thenable - Visual Studio Code Thenable (Promise)

Param Type Description key string The unique key for the cached item value any The value to cache [expiration] number Optional expiration time in seconds

cache.get(key, [defaultValue]) ⇒ any

Get an item from the cache, or the optional default value

Kind: instance method of Cache

Returns: any - Returns the cached value or optional defaultValue

Param Type Description key string The unique key for the cached item [defaultValue] any The optional default value to return if the cached item does not exist or is expired

cache.has(key) ⇒ boolean

Checks to see if unexpired item exists in the cache

Kind: instance method of Cache

Param Type Description key string The unique key for the cached item

cache.forget(key) ⇒ Thenable | false

Removes an item from the cache

Kind: instance method of Cache

Returns: Thenable | false - Visual Studio Code Thenable (Promise) or false if key does not exist

Param Type Description key string The unique key for the cached item

Get an array of all cached item keys

Kind: instance method of Cache

cache.all() ⇒ object

Returns object of all cached items

Kind: instance method of Cache

cache.flush() ⇒ Thenable

Clears all items from the cache

Kind: instance method of Cache

Returns: Thenable - Visual Studio Code Thenable (Promise)

cache.expiration(key) ⇒ number

Gets the expiration time for the cached item

Kind: instance method of Cache

Returns: number - Unix Timestamp in seconds

Param Type Description key string The unique key for the cached item

cache.isExpired(item) ⇒ boolean

Checks to see if cached item is expired

Kind: instance method of Cache