react-tree-walker - npm Package Compare versions

Comparing version 3.0.0 to 4.0.0

package.json

 {
   "name": "react-tree-walker",
-  "version": "3.0.0",
+  "version": "4.0.0",
   "description":
@@ -17,8 +17,7 @@ "Walk a React element tree, executing a provided function against each node.",
   "scripts": {
-    "precommit": "lint-staged && npm run test",
-    "build": "babel-node ./tools/scripts/build.js",
-    "check": "npm run lint && npm run test",
+    "build": "node ./tools/scripts/build.js",
     "clean":
       "rimraf ./commonjs && rimraf ./umd && rimraf ./coverage && rimraf ./umd",
     "lint": "eslint src",
+    "precommit": "lint-staged && npm run test",
     "prepublish": "npm run build",
@@ -39,8 +38,9 @@ "test": "jest",
     "babel-loader": "^7.1.2",
+    "babel-plugin-external-helpers": "^6.22.0",
     "babel-polyfill": "^6.26.0",
     "babel-preset-env": "^1.6.0",
-    "babel-preset-latest": "6.24.1",
     "babel-preset-react": "6.24.1",
     "babel-preset-stage-3": "6.24.1",
     "babel-register": "^6.26.0",
+    "change-case": "^3.0.2",
     "codecov": "^2.3.0",
@@ -61,2 +61,3 @@ "cross-env": "^5.0.5",
     "lint-staged": "^4.2.3",
+    "preact": "^8.2.7",
     "prettier": "^1.7.4",
@@ -71,6 +72,5 @@ "pretty-bytes": "4.0.2",
     "rimraf": "^2.6.2",
-    "sinon": "^4.0.1",
-    "webpack": "^3.6.0",
-    "webpack-dev-middleware": "^1.12.0",
-    "webpack-hot-middleware": "^2.19.1"
+    "rollup": "^0.56.5",
+    "rollup-plugin-babel": "^3.0.3",
+    "rollup-plugin-uglify": "^3.0.0"
   },
@@ -84,5 +84,2 @@ "jest": {
   },
-  "lint-staged": {
-    "src/**/*.js": ["prettier --write", "git add"]
-  },
   "eslintConfig": {
@@ -102,2 +99,3 @@ "root": true,
       "import/no-extraneous-dependencies": 0,
+      "no-nested-ternary": 0,
       "no-underscore-dangle": 0,
@@ -124,3 +122,6 @@ "react/no-array-index-key": 0,
     "trailingComma": "all"
+  },
+  "lint-staged": {
+    "*.js": ["prettier --write \"src/**/*.js\"", "git add"]
   }
 }

README.md

 # react-tree-walker 🌲
 
-Walk a React element tree, executing a provided visitor function against each element.
+Walk a React (or Preact) element tree, executing a "visitor" function against each element.
 
@@ -12,34 +12,36 @@ [![npm](https://img.shields.io/npm/v/react-tree-walker.svg?style=flat-square)](http://npm.im/react-tree-walker)
 
-  - [Introduction](#introduction)
-  - [Example](#example)
-  - [FAQs](#faqs)
+* [Introduction](#introduction)
+* [Illustrative Example](#illustrative-example)
+* [Order of Execution](#order-of-execution)
+* [API](#api)
 
 ## Introduction
 
-Originally inspired/lifted from the awesome [`react-apollo`](https://github.com/apollostack/react-apollo) project.
+Inspired/lifted from the awesome [`react-apollo`](https://github.com/apollostack/react-apollo) project. 😗
 
-This modified version expands upon the design, making it `Promise` based, allowing the visitor to return a `Promise`, which would subsequently delay the tree walking until the `Promise` is resolved.  The tree is still walked in a depth-first fashion.
+This modified version expands upon the design, making it `Promise` based, allowing the visitor to return a `Promise`, which would subsequently delay the tree walking until the `Promise` is resolved. The tree is still walked in a depth-first fashion.
 
-With this you could, for example, perform pre-rendering parses on your React element tree to do things like data prefetching. 🤛
+With this you could, for example, perform pre-rendering parses on your React element tree to do things like data prefetching. Which can be especially helpful when dealing with declarative APIs such as the one provided by React Router 4.
 
-# Example
+# Illustrative 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.
+In the below example we will create a visitor that will walk a React application, looking for any "class" component that has a `getData` method on it. We will then execute the `getData` function, storing the results into an array.
 
 ```jsx
-import reactTreeWalker from 'react-tree-walker';
+import reactTreeWalker from 'react-tree-walker'
 
-class Foo extends React.Component {
+class DataFetcher extends React.Component {
   constructor(props) {
-    super(props);
-    this.getData = this.getData.bind(this);
+    super(props)
+    this.getData = this.getData.bind(this)
   }
 
   getData() {
-    // Return a promise or a sync value
-    return Promise.resolve(this.props.value);
+    // Supports promises! You could call an API for example to fetch some
+    // data, or do whatever "bootstrapping" you desire.
+    return Promise.resove(this.props.id)
   }
 
   render() {
-    return <div>{this.props.children}</div>;
+    return <div>{this.props.children}</div>
   }
@@ -51,38 +53,23 @@ }
     <h1>Hello World!</h1>
-    <Foo value={1} />
-    <Foo value={2}>
-      <Foo value={4}>
-        <Foo value={5} />
-      </Foo>
-    </Foo>
-    <Foo value={3} />
+    <DataFetcher id={1} />
+    <DataFetcher id={2}>
+      <DataFetcher id={3}>
+        <DataFetcher id={4} />
+      </DataFetcher>
+    </DataFetcher>
+    <DataFetcher id={5} />
   </div>
-);
+)
 
-const values = [];
+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 childContextTypes
- *                   will be passed down the tree.
- *
- * @return Anything other than `false` to continue walking down the current branch
- *         OR
- *         `false` if you wish to stop the traversal down the current branch,
- *         OR
- *         `Promise<true|false>` a promise that resolves to either true/false
- */
-function visitor(element, instance, context) {
+// You provide this! See the API docs below for full details.
+function visitor(element, instance) {
   if (instance && typeof instance.getData) {
-    return instance.getData()
-      .then((value) => {
-        values.push(value);
-        // Return "false" to indicate that we do not want to traverse "4"'s children
-        return value !== 4
-      })
+    return instance.getData().then(value => {
+      values.push(value)
+      // Return "false" to indicate that we do not want to visit "3"'s children,
+      // therefore we do not expect "4" to make it into our values array.
+      return value !== 3
+    })
   }
@@ -93,11 +80,148 @@ }
   .then(() => {
-    console.log(values); // [1, 2, 4, 3];
+    console.log(values) // [1, 2, 3, 5];
+    // Now is a good time to call React's renderToString whilst exposing
+    // whatever values you built up to your app.
   })
   // since v3.0.0 you need to do your own error handling!
-  .catch(err => console.error(err));
+  .catch(err => console.error(err))
+```
 
+Not a particularly useful piece of code, but hopefully it is illustrative enough as to indicate the posibilities. One could use this to warm a cache or a `redux` state, subsequently performing a `renderToString` execution with all the required data in place.
+
+## Order of Execution
+
+`react-tree-walker` walks your React application in a depth-first fashion, i.e. from the top down, visiting each child until their are no more children available before moving on to the next element. We can illustrate this behaviour using the below example:
+
+```jsx
+<div>
+  <h1>Foo</h1>
+  <section>
+    <p>One</p>
+    <p>Two</p>
+  </section>
+  <Footer />
+</div>
 ```
 
-## FAQs
+In this example the order of elements being visited would be:
 
-> Let me know if you have any...
+    div -> h1 -> "Foo" -> section -> p -> "One" -> p -> "Two" -> Footer
+
+Whilst your application is being walked its behaviour will be much the same as if it were being rendered on the server - i.e. the `componentWillMount` lifecycle will be executed for any "class" components, and context provided by any components will be passed down and become available to child components.
+
+Despite emulating a server side render, the tree walking process is far cheaper as it doesn't actually perform any rendering of the element tree to a string. It simply interogates your app building up an object/element tree. The really expensive cycles will likely be the API calls that you make. 😀
+
+That being said you do have a bail-out ability allowing you to suspend the traversal down a branch of the tree. To do so you simply need to return `false` from your visitor function, or if returning a `Promise` ensure that the `Promise` resolves a `false` for the same behaviour.
+
+## API
+
+The API is very simple at the moment, only exposing a single function, which you can import as follows
+
+---
+
+### **reactTreeWalker**
+
+The default export of the library. The function that performs the magic.
+
+```
+const reactTreeWalker = require('react-tree-walker')
+```
+
+_or_
+
+```
+import reactTreeWalker from 'react-tree-walker'
+```
+
+**Paramaters**
+
+* **tree** (React/Preact element, _required_)
+
+  The react application you wish to walk.
+
+  e.g. `<div>Hello world</div>`
+
+* **visitor** (`Function`, _required_)
+
+  The function you wish to execute against _each_ element that is walked on the `tree`.
+
+  See its [API docs](#visitor) below.
+
+* **context** (`Object`, _optional_)
+
+  Any root context you wish to provide to your application.
+
+  e.g. `{ myContextItem: 'foo' }`
+
+* **options** (`Object`, _optional_)
+
+  Additional options/configuration. It currently supports the following values:
+
+  * _componentWillUnmount_: Enable this to have the `componentWillUnmount` lifecycle event be executed whilst walking your tree. Defaults to `false`. This was added as an experimental additional flag to help with applications where they have critical disposal logic being executed within the `componentWillUnmount` lifecycle event.
+
+**Returns**
+
+A `Promise` that resolves when the tree walking is completed.
+
+---
+
+### **visitor**
+
+The function that you create and provide to `reactTreeWalker`.
+
+It should encapsulates the logic you wish to execute against each element.
+
+**Parameters**
+
+* **element** (React/Preact element, _required_)
+
+  The current element being walked.
+
+* **instance** (Component Instance, _optional_)
+
+  If the current element being walked is a "class" Component then this will contain the instance of the Component - allowing you to interface with its methods etc.
+
+* **context** (`Object`, _required_)
+
+  The React context that is available to the current element. `react-tree-walker` emulates React in exposing context down the tree.
+
+* **childContext** (`Object`, _optional_)
+
+  If the current element being walked is a "class" Component and it exposes additional "child" context (via the `getChildContext` method) then this will contain the context that is being provided by the component instance.
+
+**Returns**
+
+If you return `false` then the children of the current element will not be visited.
+
+e.g.
+
+```javascript
+function visitor(element) {
+  if (element.type === 'menu') {
+    // We will not traverse the children for any <menu /> nodes
+    return 'false'
+  }
+}
+```
+
+You can also return a `Promise` which will cause the tree walking to wait for the `Promise` to be resolved before attempting to visit the children for the current element.
+
+```javascript
+function visitor(element, instance) {
+  // This will make every visit take 1 second to execution.
+  return new Promise(resolve => setTimeout(resolve, 1000))
+}
+```
+
+You can make the Promise resolve a `false` to indicate that you do not want the children of the current element to be visited.
+
+```javascript
+function visitor(element, instance) {
+  // Only the first element will be executed, and it will take 1 second to complete.
+  return (
+    new Promise(resolve => setTimeout(resolve, 1000))
+      // This prevents any walking down the current elements children
+      .then(() => false)
+  )
+}
+```

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

Major refactor

Supply chain risk

Package has recently undergone a major refactor. It may be unstable or indicate significant internal changes. Use caution when updating to versions that include significant changes.

Found 1 instance in 1 package

Environment variable access

Supply chain risk

Package accesses environment variables, which may be a sign of credential stuffing or data theft.

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

Minified code

Quality

This package contains minified code. This may be harmless in some cases where minified code is included in packaged libraries, however packages on npm should not minify code.

Found 1 instance in 1 package

Improved metrics

Number of low quality alerts

0

decreased by-100%

Number of lines in readme file

225

increased by122.77%

Worsened metrics

Total package byte prevSize

14059

decreased by-52.1%

Dev dependency count

41

increased by2.5%

Number of package files

6

decreased by-14.29%

Lines of code

47

decreased by-89.37%

Number of low supply chain risk alerts

3

increased by50%

Number of medium supply chain risk alerts

1

increased byInfinity%

No dependency changes