cache-point - npm Package Compare versions

Comparing version 0.3.0 to 0.3.1

lib/cache-point.js

@@ -7,6 +7,32 @@ 'use strict'
 /**
+ * A memoisation solution intended to cache the output of expensive operations, speeding up future invocations with the same input.
  * @module cache-point
  * @example
  * const Cache = require('cache-point')
- * const cache = new Cache({ dir: '~/.cache' })
+ * const cache = new Cache({ dir: 'tmp/example' })
+ *
+ * // endure a 3s wait for the result
+ * function expensiveOperation (input) {
+ *   return new Promise((resolve, reject) => {
+ *     setTimeout(() => {
+ *       const output = 'result'
+ *       cache.write(input, output)
+ *       resolve(output)
+ *     }, 3000)
+ *   })
+ * }
+ *
+ * // check the cache for output generated with this input.
+ * // cache.read() will resolve on hit, reject on miss.
+ * function getData (input) {
+ *   return cache
+ *     .read(input)
+ *     .catch(() => expensiveOperation(input))
+ * }
+ *
+ * // The first invocation will take 3s, the rest instantaneous.
+ * getData('some input')
+ *   .then(console.log)
+ *
+ * // outputs: 'result'
  */
@@ -30,3 +56,3 @@
     /**
-     * Cache directory
+     * Current cache directory. Can be changed at any time.
      * @type {string}
@@ -47,4 +73,4 @@ */
   /**
-   * Cache hit resolves, miss rejects.
-   * @param {*} - One or more values to index the data, e.g. a request object or set of function args.
+   * A cache hit resolves with the stored value, a miss rejects.
+   * @param {*} - One or more values to uniquely identify the data. Can be any value, or an array of values of any type.
    * @returns {Promise}
@@ -64,4 +90,4 @@ */
   /**
-   * Cache hit returns data, miss returns null.
-   * @param {*} - One or more values to index the data, e.g. a request object or set of function args.
+   * A cache hit returns the stored value, a miss returns `null`.
+   * @param {*} - One or more values to uniquely identify the data. Can be any value, or an array of values of any type.
    * @returns {string?}
@@ -80,3 +106,3 @@ */
   /**
-   * Write some data to the cache with a key.
+   * Write some data to the cache. Returns a promise which resolves when the write is complete.
    * @param {*} - One or more values to index the data, e.g. a request object or set of function args.
@@ -100,3 +126,2 @@ * @param {*} - the data to store
    * @param {*} - the data to store
-   * @returns {Promise}
    */
@@ -109,3 +134,3 @@ writeSync (keys, content) {
   /**
-   * Converts a key value into a hex checksum.
+   * Used internally to convert a key value into a hex checksum. Override if for some reason you need a different hashing strategy. 
    * @param {*} - One or more values to index the data, e.g. a request object or set of function args.
@@ -122,3 +147,3 @@ * @returns {string}
   /**
-   * Clears the cache.
+   * Clears the cache. Returns a promise which resolves once the cache is clear.
    * @returns {Promise}
@@ -140,3 +165,3 @@ */
   /**
-   * Cleans and removes the cache.
+   * Clears and removes the cache directory. Returns a promise which resolves once the remove is complete.
    * @returns {Promise}
@@ -143,0 +168,0 @@ */

package.json

 {
   "name": "cache-point",
   "author": "Lloyd Brookes <[e-mail]>",
-  "version": "0.3.0",
-  "description": "cache-point",
+  "version": "0.3.1",
+  "description": "Simple, filesystem-backed memoisation cache.",
   "repository": "https://github.com/75lb/cache-point.git",
   "license": "MIT",
   "main": "index",
-  "keywords": [],
+  "keywords": [
+    "memoisation",
+    "memoization",
+    "cache",
+    "file",
+    "store"
+  ],
   "engines": {
@@ -11,0 +17,0 @@ "node": ">=0.10.0"

README.md

@@ -10,6 +10,33 @@ [![view on npm](http://img.shields.io/npm/v/cache-point.svg)](https://www.npmjs.org/package/cache-point)
 ## cache-point
+A memoisation solution intended to cache the output of expensive operations, speeding up future invocations with the same input.
+
 **Example**  
 ```js
 const Cache = require('cache-point')
-const cache = new Cache({ dir: '~/.cache' })
+const cache = new Cache({ dir: 'tmp/example' })
+
+// endure a 3s wait for the result
+function expensiveOperation (input) {
+  return new Promise((resolve, reject) => {
+    setTimeout(() => {
+      const output = 'result'
+      cache.write(input, output)
+      resolve(output)
+    }, 3000)
+  })
+}
+
+// check the cache for output generated with this input.
+// cache.read() will resolve on hit, reject on miss.
+function getData (input) {
+  return cache
+    .read(input)
+    .catch(() => expensiveOperation(input))
+}
+
+// The first invocation will take 3s, the rest instantaneous.
+getData('some input')
+  .then(console.log)
+
+// outputs: 'result'
 ```
@@ -22,5 +49,7 @@
         * [.read(keys)](#module_cache-point--Cache+read) ⇒ <code>Promise</code>
+        * [.readSync(keys)](#module_cache-point--Cache+readSync) ⇒ <code>string</code>
         * [.write(keys, content)](#module_cache-point--Cache+write) ⇒ <code>Promise</code>
+        * [.writeSync(keys, content)](#module_cache-point--Cache+writeSync)
         * [.getChecksum(keys)](#module_cache-point--Cache+getChecksum) ⇒ <code>string</code>
-        * [.clean()](#module_cache-point--Cache+clean) ⇒ <code>Promise</code>
+        * [.clear()](#module_cache-point--Cache+clear) ⇒ <code>Promise</code>
         * [.remove()](#module_cache-point--Cache+remove) ⇒ <code>Promise</code>
@@ -44,3 +73,3 @@
 #### cache.dir : <code>string</code>
-Cache directory
+Current cache directory. Can be changed at any time.
 
@@ -51,3 +80,3 @@ **Kind**: instance property of <code>[Cache](#exp_module_cache-point--Cache)</code>
 #### cache.read(keys) ⇒ <code>Promise</code>
-Cache hit resolves, miss rejects.
+A cache hit resolves with the stored value, a miss rejects.
 
@@ -58,7 +87,30 @@ **Kind**: instance method of <code>[Cache](#exp_module_cache-point--Cache)</code>
 | --- | --- | --- |
-| keys | <code>\*</code> | One or more values to index the data, e.g. a request object or set of function args. |
+| keys | <code>\*</code> | One or more values to uniquely identify the data. Can be any value, or an array of values of any type. |
 
+<a name="module_cache-point--Cache+readSync"></a>
+
+#### cache.readSync(keys) ⇒ <code>string</code>
+A cache hit returns the stored value, a miss returns `null`.
+
+**Kind**: instance method of <code>[Cache](#exp_module_cache-point--Cache)</code>  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| keys | <code>\*</code> | One or more values to uniquely identify the data. Can be any value, or an array of values of any type. |
+
 <a name="module_cache-point--Cache+write"></a>
 
 #### cache.write(keys, content) ⇒ <code>Promise</code>
+Write some data to the cache. Returns a promise which resolves when the write is complete.
+
+**Kind**: instance method of <code>[Cache](#exp_module_cache-point--Cache)</code>  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| keys | <code>\*</code> | One or more values to index the data, e.g. a request object or set of function args. |
+| content | <code>\*</code> | the data to store |
+
+<a name="module_cache-point--Cache+writeSync"></a>
+
+#### cache.writeSync(keys, content)
 Write some data to the cache with a key.
@@ -76,3 +128,3 @@
 #### cache.getChecksum(keys) ⇒ <code>string</code>
-Converts a key value into a hex checksum.
+Used internally to convert a key value into a hex checksum. Override if for some reason you need a different hashing strategy.
 
@@ -85,6 +137,6 @@ **Kind**: instance method of <code>[Cache](#exp_module_cache-point--Cache)</code>
 
-<a name="module_cache-point--Cache+clean"></a>
+<a name="module_cache-point--Cache+clear"></a>
 
-#### cache.clean() ⇒ <code>Promise</code>
-Cleans the cache.
+#### cache.clear() ⇒ <code>Promise</code>
+Clears the cache. Returns a promise which resolves once the cache is clear.
 
@@ -95,3 +147,3 @@ **Kind**: instance method of <code>[Cache](#exp_module_cache-point--Cache)</code>
 #### cache.remove() ⇒ <code>Promise</code>
-Cleans and removes the cache.
+Clears and removes the cache directory. Returns a promise which resolves once the remove is complete.
 
@@ -98,0 +150,0 @@ **Kind**: instance method of <code>[Cache](#exp_module_cache-point--Cache)</code>

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

21182

increased by23.24%

Number of package files

15

increased by15.38%

Lines of code

424

increased by12.77%

Number of lines in readme file

147

increased by54.74%

No dependency changes