Improved component caching

README.md

@@ -27,6 +27,7 @@ Rapscallion is a React VirtualDOM renderer for the server.  Its notable features
   - [`Renderer#includeDataReactAttrs`](#rendererincludedatareactattrs)
   - [`Renderer#tuneAsynchronicity`](#renderertuneasynchronicity)
   - [`Renderer#checksum`](#rendererchecksum)
+  - [`setCacheStrategy`](#setcachestrategy)
   - [`template`](#template)
 - [Caching](#caching)
 - [Benchmarks](#benchmarks)
@@ -134,8 +135,39 @@ The renderer's `checksum` method will give you access to the checksum that has b
 For an example of how to attach this value to the DOM on the client side, see the example in the [template](#template) section below.
 
 
+### `setCacheStrategy`
+
+`setCacheStrategy({ get: ..., set: ... */ }) -> undefined`
+
+The default cache strategy provided by Rapscallion is a naive one.  It is synchronous and in-memory, with no cache invalidation or TTL for cache entries.
+
+However, `setCacheStrategy` is provided to allow you to integrate your own caching solutions.  The function expects an options argument with two keys:
+
+- `get` should accept a single argument, the key, and return a Promise resolving to a cached value.  If no cached value is found, the Promise should resolve to `null`.
+- `set` should accept two arguments, a key and its value, and return a Promise that resolves when the `set` operation has completed.
+
+All values, both those returned from `get` and passed to `set`, will be Arrays with both string and integer elements.  Keep that in mind if you need to serialize the data for your cache backend.
+
+**Example:**
+
+```javascript
+const { setCacheStrategy } = require("rapscallion");
+const redis = require("redis");
+
+const client = redis.createClient();
+const redisGet = Promise.promisify(redisClient.get, { context: redisClient });
+const redisSet = Promise.promisify(redisClient.set, { context: redisClient });
+setCacheStrategy({
+  get: key => redisGet(key).then(val => val && JSON.parse(val) || null),
+  set: (key, val) => redisSet(key, JSON.stringify(val))
+});
+```
+
+For more information on how to cache your component HTML, read through the [caching section](#caching) below.
+
 -----
 
+
 ### `template`
 
 ``template`TEMPLATE LITERAL` -> Renderer``

package.json

@@ -52,6 +52,7 @@
   },
   "dependencies": {
     "adler-32": "^1.0.0",
+    "bluebird": "^3.4.7",
     "he": "^1.1.1",
     "lodash": "^4.17.4"
   }

spec/cache.js

@@ -1,10 +1,10 @@
 import { default as React, Component } from "react";
 
-import { render } from "../src";
+import { render, setCacheStrategy, Promise } from "../src";
+import { useDefaultCacheStrategy } from "../src/sequence/cache";
 
 
-
-describe("caching", () => {
+const runAllTests = () => {
   describe("for stateful components", () => {
     const staticDivKey = `div:static:${Math.random()}`;
     const staticChildKey = `child:static:${Math.random()}`;
@@ -112,4 +112,28 @@ describe("caching", () => {
         });
     });
   });
+};
+
+describe("naive caching", () => {
+  runAllTests();
+});
+
+describe("async caching", () => {
+  beforeEach(() => {
+    const asyncCache = Object.create(null);
+
+    setCacheStrategy({
+      get: key => Promise.resolve(asyncCache[key] && JSON.parse(asyncCache[key]) || null),
+      set: (key, val) => {
+        asyncCache[key] = JSON.stringify(val);
+        return Promise.resolve();
+      }
+    });
+  });
+
+  afterEach(() => {
+    useDefaultCacheStrategy();
+  });
+
+  runAllTests();
 });

src/consumers/common.js

@@ -1,9 +1,13 @@
 const adler32 = require("adler-32");
+const Promise = require("bluebird");
 
 const { EXHAUSTED } = require("../sequence");
 const { REACT_ID } = require("../symbols");
 
 
+const INCOMPLETE = Symbol();
+
+
 /**
  * Given a batch size, request values from the source sequence and push them
  * onto the provided "pushable" (a Node stream or an array).  Once the number
@@ -15,17 +19,23 @@ const { REACT_ID } = require("../symbols");
  *                                       returning control call to the caller.
  * @param      {Array|Stream}            pushable   Destination for all segments.
  *
- * @return     {boolean}                 Indicates whether there are more values to
+ * @return     {boolean|Promise}         Indicates whether there are more values to
  *                                       be retrieved, or if this the last batch.
  */
 function pullBatch (sequence, batchSize, pushable) {
   let iter = batchSize;
   while (iter--) {
     const next = sequence.next();
-    if (next === EXHAUSTED) { return true; }
+    if (
+      next === EXHAUSTED ||
+      next instanceof Promise
+    ) {
+      return next;
+    }
+
     pushable.push(next);
   }
-  return false;
+  return INCOMPLETE;
 }
 
 
@@ -60,5 +70,6 @@ function getChecksumWrapper (pushable) {
 module.exports = {
   pullBatch,
   getReactIdPushable,
-  getChecksumWrapper
+  getChecksumWrapper,
+  INCOMPLETE
 };

src/consumers/node-stream.js

@@ -1,5 +1,7 @@
+const Promise = require("bluebird");
 const { Readable } = require("stream");
 
+const { EXHAUSTED } = require("../sequence");
 const { pullBatch, getReactIdPushable, getChecksumWrapper } = require("./common");
 
 
@@ -15,12 +17,27 @@ const { pullBatch, getReactIdPushable, getChecksumWrapper } = require("./common"
  * @return     {Readable}                  A readable Node stream.
  */
 function toNodeStream (sequence, batchSize, dataReactAttrs) {
-  const stream = new Readable({
-    read () {
-      const isLast = pullBatch(sequence, batchSize, reactIdPushable);
-      if (isLast) { this.push(null); }
+  let sourceIsReady = true;
+
+  const read = () => {
+    // If source is not ready, defer any reads until the promise resolves.
+    if (!sourceIsReady) { return; }
+
+    const result = pullBatch(sequence, batchSize, reactIdPushable);
+
+    if (result === EXHAUSTED) {
+      stream.push(null);
+    } else if (result instanceof Promise) {
+      sourceIsReady = false;
+      result.then(next => {
+        sourceIsReady = true;
+        reactIdPushable.push(next);
+        read();
+      });
     }
-  });
+  };
+
+  const stream = new Readable({ read });
 
   const checksumWrapper = getChecksumWrapper(stream);
   const reactIdPushable = getReactIdPushable(checksumWrapper, 1, dataReactAttrs);

src/consumers/promise.js

@@ -1,5 +1,13 @@
 /* global setImmediate */
-const { pullBatch, getReactIdPushable, getChecksumWrapper } = require("./common");
+const Promise = require("bluebird");
+
+const { EXHAUSTED } = require("../sequence");
+const {
+  pullBatch,
+  getReactIdPushable,
+  getChecksumWrapper,
+  INCOMPLETE
+} = require("./common");
 
 
 const TAG_END = /\/?>/;
@@ -14,11 +22,16 @@ function asyncBatch (
   dataReactAttrs,
   resolve
 ) {
-  const isLast = pullBatch(sequence, batchSize, pushable);
-  if (isLast) {
-    resolve();
-  } else {
+  const result = pullBatch(sequence, batchSize, pushable);
+  if (result === INCOMPLETE) {
     setImmediate(asyncBatch, sequence, batchSize, pushable, dataReactAttrs, resolve);
+  } else if (result === EXHAUSTED) {
+    resolve();
+  } else if (result instanceof Promise) {
+    result.then(next => {
+      pushable.push(next);
+      setImmediate(asyncBatch, sequence, batchSize, pushable, dataReactAttrs, resolve);
+    });
   }
 }
 

src/index.js

@@ -1,8 +1,13 @@
+const Promise = require("bluebird");
+
 const Renderer = require("./renderer");
 const template = require("./template");
+const { setCacheStrategy } = require("./sequence/cache");
 
 
 module.exports = {
   render: jsx => new Renderer(jsx),
-  template
+  template,
+  setCacheStrategy,
+  Promise
 };

src/sequence/cache/index.js

@@ -0,0 +1,30 @@
+const { isFunction } = require("lodash");
+
+const defaultStrategy = require("./strategies/default");
+const asyncStrategy = require("./strategies/async");
+
+
+let cacheStrategy = defaultStrategy();
+
+
+function getCachedSequence (sequence, node, sequenceFactory) {
+  return cacheStrategy(sequence, node, sequenceFactory);
+}
+
+function setCacheStrategy (opts) {
+  if (!isFunction(opts && opts.get) || !isFunction(opts && opts.set)) {
+    throw new Error("Async cache strategy must be provided `get` and `set` options.");
+  }
+  cacheStrategy = asyncStrategy(opts);
+}
+
+function useDefaultCacheStrategy () {
+  cacheStrategy = defaultStrategy();
+}
+
+
+module.exports = {
+  getCachedSequence,
+  setCacheStrategy,
+  useDefaultCacheStrategy
+};

src/sequence/cache.js → src/sequence/cache/sequence-cache.js

@@ -1,13 +1,7 @@
-const { assign, omit, values } = require("lodash");
+const { values, noop } = require("lodash");
 
-const {
-  BaseSequence,
-  sequence: makeNewSequence,
-  EXHAUSTED
-} = require("./sequence");
-const compress = require("./compress");
-
-const cache = Object.create(null);
+const { EXHAUSTED, BaseSequence } = require("../sequence");
+const compress = require("../compress");
 
 
 /**
@@ -25,11 +19,12 @@ class ForkedSequence extends BaseSequence {
  * An object that forks an input source sequence into multiple output sequences.
  */
 class SequenceCache {
-  constructor (source) {
+  constructor (source, onCompress) {
     this.source = source;
     this.sourceCursor = 0;
     this.buffer = [];
     this.compressedBuffer = null;
+    this.onCompress = onCompress || noop;
 
     this.forks = 0;
     this.forkCursors = Object.create(null);
@@ -41,9 +36,7 @@ class SequenceCache {
    * @return     {Sequence}    The forked sequence.
    */
   fork () {
-    if (this.compressedBuffer) {
-      return this.forkCompressed();
-    }
+    if (this.compressedBuffer) { return this.forkCompressed(); }
 
     const forkIdx = this.forks++;
     this.forkCursors[forkIdx] = 0;
@@ -132,45 +125,12 @@ class SequenceCache {
     this.sourceCursor = null;
     this.forks = null;
     this.forkCursors = null;
+    this.onCompress(this);
   }
 }
 
-/**
- * Checks whether a node is cacheable.
- *
- * If it is not cachable, return the sequence that would've been created without
- * caching being involved.
- *
- * If the node _is_ cacheable, return either a fork of a previously-cached
- * sequence (with the same key), or a new fork if an identical node was not
- * previously cached.
- *
- * @param      {Sequence}   sequence         The non-cached sequence.
- * @param      {VDOM}       node             VDOM node to render and/or cache.
- * @param      {Function}   sequenceFactory  Function that returns a sequence for the node.
- *
- * @return     {Sequence}    The non-cached or cached sequence.
- */
-function getCachedSequence (sequence, node, sequenceFactory) {
-  const cacheKey = node.props && node.props.cacheKey;
-  if (!cacheKey) {
-    return sequenceFactory(sequence, node);
-  }
-
-  let cacheEntry = cache[cacheKey];
-
-  if (!cacheEntry) {
-    const _node = assign({}, node, {
-      props: omit(node.props, ["cacheKey"])
-    });
-
-    const sequenceToCache = makeNewSequence();
-    sequenceFactory(sequenceToCache, _node);
-    cacheEntry = cache[cacheKey] = new SequenceCache(sequenceToCache);
-  }
-
-  return cacheEntry.fork();
-}
-
 
-module.exports = getCachedSequence;
+module.exports = {
+  SequenceCache,
+  ForkedSequence
+};