@qikdev/sdk 1.0.12 → 1.0.13

package/src/api/qik.cache.js

@@ -7,10 +7,17 @@ var caches = {};
 
 
 /**
- * @classdesc A static service that provides tools for caching api requests and other information
+ * @classdesc Named in-memory caches shared by the whole page (LRU: the least recently used entries are dropped
+ * when a cache is full). The SDK keeps the content glossary in one; you can create your own to remember
+ * expensive lookups. Nothing is persisted: caches are lost on reload, and all of them are cleared on
+ * logout and organisation switch.
  * @alias cache
  * @class
  * @hideconstructor
+ * @example
+ * const cache = sdk.cache.get('my-lookups', { max: 100 });
+ * cache.set('answer', 42);
+ * cache.get('answer'); // 42
  */
 var QikCache = {
 
@@ -18,8 +25,12 @@ var QikCache = {
 
     
     /**
-     * A helper function to reset all caches, useful if changing organisation or logging in or out as another user     
-     * @alias cache.reset    
+     * Empties every cache created with sdk.cache.get (the caches themselves stay available, just empty).
+     * sdk.auth.logout() and sdk.auth.changeOrganisation() call this for you.
+     * @alias cache.reset
+     * @returns {undefined}
+     * @example
+     * sdk.cache.reset();
      */
     reset() {
         Object.entries(caches).forEach(([key, cache]) => {
@@ -34,10 +45,21 @@ var QikCache = {
     ///////////////////////////////////////////////////
 
     /**
-     * A helper function to retrieve a specific cache  
-     * @alias cache.get    
-     * @param  {string} key The key for the cache you want to retrieve
-     * @return {LRUCache} The cache store for the specified key
+     * Returns the cache with this name, creating it the first time. Later calls with the same name return the
+     * same cache, whatever options they pass.
+     * @alias cache.get
+     * @param {String} key The cache's name.
+     * @param {Object} [options] lru-cache options, used only when the cache is created. Default { max: 5 } (five entries).
+     * @param {Number} [options.max] Maximum number of entries.
+     * @param {Number} [options.ttl] Milliseconds before an entry expires.
+     * @returns {LRUCache} An lru-cache instance: get(key), set(key, value), has(key), delete(key), clear().
+     * @example
+     * const cache = sdk.cache.get('people', { max: 500, ttl: 60000 });
+     * let person = cache.get(id);
+     * if (!person) {
+     *     person = await sdk.content.get(id);
+     *     cache.set(id, person);
+     * }
      */
     get(key, options) {
         options = options || {max:5};