Initial version.

Author: ctrlplusb

README.md

@@ -1,31 +1,89 @@
-> This is my personal starter kit for npm libraries.
+# react-tree-walker 🌲
 
-# Your Library Name
+Walk a React element tree, executing a provided visitor function against each element.
 
-A one liner description of your library.
-
-___BADGES: EDIT THESE TO USE THE URLS FOR EACH SERVICE CONFIGURED FOR YOUR OWN LIBRARY, THEN REMOVE THIS MESSAGE___
-
-[![npm](https://img.shields.io/npm/v/npm-library-starter.svg?style=flat-square)](http://npm.im/npm-library-starter)
-[![MIT License](https://img.shields.io/npm/l/npm-library-starter.svg?style=flat-square)](http://opensource.org/licenses/MIT)
-[![Travis](https://img.shields.io/travis/ctrlplusb/npm-library-starter.svg?style=flat-square)](https://travis-ci.org/ctrlplusb/npm-library-starter)
-[![Codecov](https://img.shields.io/codecov/c/github/ctrlplusb/npm-library-starter.svg?style=flat-square)](https://codecov.io/github/ctrlplusb/npm-library-starter)
+[![npm](https://img.shields.io/npm/v/react-tree-walker.svg?style=flat-square)](http://npm.im/react-tree-walker)
+[![MIT License](https://img.shields.io/npm/l/react-tree-walker.svg?style=flat-square)](http://opensource.org/licenses/MIT)
+[![Travis](https://img.shields.io/travis/ctrlplusb/react-tree-walker.svg?style=flat-square)](https://travis-ci.org/ctrlplusb/react-tree-walker)
+[![Codecov](https://img.shields.io/codecov/c/github/ctrlplusb/react-tree-walker.svg?style=flat-square)](https://codecov.io/github/ctrlplusb/react-tree-walker)
 
 ## TOCs
 
   - [Introduction](#introduction)
+  - [Example](#example)
   - [FAQs](#faqs)
 
 ## Introduction
 
-An introduction to your library...
+This is a port/generalisation of the implementation within the awesome [`react-apollo`](https://github.com/apollostack/react-apollo) project. I've come to find many use-cases in my own projects and want to avoid code duplication.
 
-## FAQs
+It's quite useful for performing pre-rendering parses on your React element tree to do things like data prefetching.
+
+# Example
+
+In the below example we walk the tree and execute the `getValue` function on every element instance that has the function available.  We then push the value into a values array.
+
+```jsx
+import reactTreeWalker from 'react-tree-walker';
+
+class Foo extends React.Component {
+  constructor(props) {
+    super(props);
+    this.getValue = this.getValue.bind(this);
+  }
 
-___A common question around your library?___
+  getValue() {
+    return this.props.value;
+  }
 
-The answer to the question.
+  render() {
+    return <div>{this.props.children}</div>;
+  }
+}
 
-___A common question around your library?___
+const app = (
+  <div>
+    <h1>Hello World!</h1>
+    <Foo value={1} />
+    <Foo value={2}>
+      <Foo value={4}>
+        <Foo value={5} />
+      </Foo>
+    </Foo>
+    <Foo value={3} />
+  </div>
+);
+
+const values = [];
+
+/**
+ * Visitor to be executed on each element being walked.
+ *
+ * @param  element - The current element being walked.
+ * @param  instance - If the current element is a Component or PureComponent
+ *                    then this will hold the reference to the created
+ *                    instance. For any other element type this will be null.
+ * @param  context - The current "React Context". Any provided childContexTypes
+ *                   will be passed down the tree.
+ *
+ * @return `undefined` if you want to continue walking down the current branch,
+ *         or return `false` if you wish to stop the traversal down the
+ *         current branch.  Stopping the traversal can be quite handy if
+ *         you want to resolve a Promise for example.  You can wait for the
+ *         Promise to resolve and then execute a function to continue
+ *         traversal of the branch where you left off.
+ */
+function visitor(element, instance, context) {
+  if (instance && typeof instance.getValue) {
+    values.push(instance.getValue());
+  }
+};
+
+reactTreeWalker(tree, visitor);
+
+console.log(values); // [1, 2, 4, 5, 3];
+```
+
+## FAQs
 
-The answer to the question.
+> Let me know if you have any...