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

// First, get the module into your extension code
const Cache = require('vscode-cache');

// Extension activation method
let activate = (extensionContext) => {

  // Instantiate the cache by passing your `ExtensionContext` object into it
  let myCache = new Cache(extensionContext);

  // Save an item to the cache by specifying a key and value
  myCache.put('userName', 'John Doe')
    .then(() => {

      // Does the cache have userName?
      console.log(myCache.has('userName')); // returns true

      // Fetch the userName from the cache
      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.

// Save something in the cache for 5 seconds
myCache.put('searchResults', results, 5)
  .then(()=> {

    // Does the cache still have it?
    console.log(myCache.has('searchResults')); // returns true

    // Does the cache still have it 10 seconds later?
    setTimeout(() => {

      console.log(myCache.has('searchResults')); // returns false

    }, 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.

// Does the cache contain this value?
myCache.has('foo'); // returns false

// Fetch the value of foo, but give it a default value of "bar"
let foo = myCache.get('foo', 'bar');

console.log(foo); // returns bar

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.

// Create a cache for some API
let apiCache = new Cache(extensionContext, 'api');

// Create some sort of database cache
let databaseCache = new Cache(extensionContext, 'database');

// Store a value into the api cache using the key 'foo'
apiCache.put('foo', apiResults);

// Store a different value into the database cache using the key 'foo'
databaseCache.put('foo', databaseResults);

// Because there are two caches, you can use the same keys in each without overriding values

Cache

Kind: global class

• Cache
  • new Cache(context, [namespace])
  • .put(key, value, [expiration]) ⇒ Thenable
  • .get(key, [defaultValue]) ⇒ any
  • .has(key) ⇒ boolean
  • .forget(key) ⇒ Thenable | false
  • .keys() ⇒ Array.<string>
  • .all() ⇒ object
  • .flush() ⇒ Thenable
  • .expiration(key) ⇒ number
  • .isExpired(item) ⇒ boolean

---

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

---

cache.keys() ⇒ Array.<string>

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

Param	Type	Description
item	object	Cached item object

---