Update README and add benchmark

README.md

@@ -1,4 +1,92 @@
 # babel-plugin-transform-lodash-get
 Babel plugin to statically optimize lodash/get
 
-TODO: Add description
+## Motivation
+`lodash/get` is a quick and dirty way to follow a path in an object and avoid an `Uncaught TypeError: Cannot read property of undefined`, but it's quite inefficient because it does a lot of things at runtime which can usually be done at compile-time. This is especially true with the string version, which involves a regular expression evaluation to determine the path to take. Here are some benchmark results (see `misc/bench.js`) that demonstrate what this plugin accomplishes:
+
+```
+get array x 5,598,764 ops/sec ±0.82% (92 runs sampled)
+get string x 1,649,393 ops/sec ±1.00% (92 runs sampled)
+transformed strict x 105,823,559 ops/sec ±0.89% (89 runs sampled)
+transformed loose x 199,549,365 ops/sec ±1.44% (89 runs sampled)
+native (no check) x 859,787,262 ops/sec ±0.63% (92 runs sampled)
+native (caught) x 219,053 ops/sec ±0.97% (79 runs sampled)
+
+strict
+------
+1790.12% faster than get array
+6315.91% faster than get string
+87.69% slower than native (no check)
+48209.65% faster than native (caught)
+
+loose
+------
+3464.17% faster than get array
+11998.35% faster than get string
+76.79% slower than native (no check)
+90996.54% faster than native (caught)
+```
+
+You can run this benchmark on your own setup as follows:
+```
+npm run bench
+```
+
+## Example
+
+### In
+```javascript
+get(obj, 'products.foo.items[0].baz.items[0].foobar', 'gg')
+```
+
+### Out
+```javascript
+let _gg;
+let _obj;
+(_gg = 'gg', (_obj = obj) && (_obj = _obj.products) && (_obj = _obj.foo) && (_obj = _obj.items) && (_obj = _obj[0]) && (_obj = _obj.baz) && (_obj = _obj.items) && (_obj = _obj[0])) ? (_obj = _obj.foobar) === void 0 ? _gg : _obj : _gg;
+```
+
+## `loose` mode
+
+The strict transformation (the default) generates code that always evaluates to exactly what `lodash/get` would produce, but if you favour better performance and smaller transformed code at the expense of sometimes getting a different falsy value than `undefined` when the key is not found in the object, then you can use the `loose` mode to produce the following for the above example:
+
+### Out
+```javascript
+let _obj;
+(_obj = obj) && (_obj = _obj.products) && (_obj = _obj.foo) && (_obj = _obj.items) && (_obj = _obj[0]) && (_obj = _obj.baz) && (_obj = _obj.items) && (_obj = _obj[0]) && _obj.foobar || 'gg';
+```
+
+## What it doesn't do
+If the second argument of to a `lodash/get` call is not a string or an array but something else (like a variable, function call, object lookup), it cannot be statically optimized, obviously because this plugin cannot predict what would end up there at runtime. In these cases, the plugin would leave it as it is and move on to the next.
+
+Also, this plugin doesn't (yet) remove unused imports/requires of `lodash` after transform from files; you may have to use other babel plugins to deal with this.
+
+## Options
+Apart from the aforementioned `loose` mode, this plugin also supports an additonal `patterns` option, which defaults to `['get', '_.get']`, which lets you add custom patterns to match, but this is not recommended.
+
+## Usage
+### Via `.babelrc` (Recommended)
+**.babelrc**
+Without options
+```json
+{
+  "plugins": ["transform-lodash-get"]
+}
+```
+With options
+```json
+{
+  "plugins": [["transform-lodash-get", { loose: true, patterns: ['foo', '_.foo'] }]]
+}
+```
+### Via CLI
+```
+babel --plugins transform-lodash-get script.js
+```
+
+### Via Node API
+```javascript
+require("@babel/core").transform("code", {
+  plugins: ["transform-lodash-get"]
+});
+```

misc/bench.js

@@ -0,0 +1,66 @@
+/* eslint-disable no-console */
+const Benchmark = require('benchmark')
+const get = require('lodash/get')
+
+const suite = new Benchmark.Suite
+
+const obj = { products: { foo: { items: [{ bar: { items: [{ foobar: 'abc' }] } }] } } }
+
+suite.add('get array', () => {
+  get(obj, ['products', 'foo', 'items', '0', 'baz', 'items', '0', 'foobar'], 'gg')
+  get(obj, ['products', 'foo', 'items', '0', 'bar', 'items', '0', 'foobar'], 'gg')
+})
+  .add('get string', () => {
+    get(obj, 'products.foo.items[0].baz.items[0].foobar', 'gg')
+    get(obj, 'products.foo.items[0].bar.items[0].foobar', 'gg')
+  })
+  .add('transformed strict', () => {
+    let _gg
+    let _obj;
+    (_gg = 'gg', (_obj = obj) && (_obj = _obj.products) && (_obj = _obj.foo) && (_obj = _obj.items) && (_obj = _obj[0]) && (_obj = _obj.baz) && (_obj = _obj.items) && (_obj = _obj[0])) ? (_obj = _obj.foobar) === void 0 ? _gg : _obj : _gg;
+    (_gg = 'gg', (_obj = obj) && (_obj = _obj.products) && (_obj = _obj.foo) && (_obj = _obj.items) && (_obj = _obj[0]) && (_obj = _obj.bar) && (_obj = _obj.items) && (_obj = _obj[0])) ? (_obj = _obj.foobar) === void 0 ? _gg : _obj : _gg
+  })
+  .add('transformed loose', () => {
+    let _obj;
+    (_obj = obj) && (_obj = _obj.products) && (_obj = _obj.foo) && (_obj = _obj.items) && (_obj = _obj[0]) && (_obj = _obj.baz) && (_obj = _obj.items) && (_obj = _obj[0]) && _obj.foobar || 'gg';
+    (_obj = obj) && (_obj = _obj.products) && (_obj = _obj.foo) && (_obj = _obj.items) && (_obj = _obj[0]) && (_obj = _obj.baz) && (_obj = _obj.items) && (_obj = _obj[0]) && _obj.foobar || 'gg'
+  })
+  .add('native (no check)', () => {
+    obj.products.foo.items[0].bar.items[0].foobar
+    obj.products.foo.items[0].bar.items[0].foobar
+  })
+  .add('native (caught)', () => {
+    try {
+      obj.products.foo.items[0].baz.items[0].foobar
+    } catch (e) {/* */ }
+    try {
+      obj.products.foo.items[0].bar.items[0].foobar
+    } catch (e) {/* */ }
+  })
+  .on('cycle', event => {
+    console.log(String(event.target))
+  })
+  .on('complete', function () {
+    const strict = this[2]
+    const loose = this[3]
+
+    const [s, l] = [0, 1, 4, 5].reduce((acc, i) => {
+      const cur = this[i]
+      const { hz, name } = cur;
+      [strict, loose].forEach((item, j) => {
+        acc[j].push((hz > item.hz ? `${((1 - item.hz / hz) * 100).toFixed(2)}% slower` : `${((item.hz / hz - 1) * 100).toFixed(2)}% faster`) + ` than ${name}`)
+      })
+      return acc
+    }, [[], []])
+
+    console.log(`
+strict
+------
+${s.join('\n')}
+
+loose
+------
+${l.join('\n')}
+`)
+  })
+  .run()

package.json

@@ -6,7 +6,8 @@
   "scripts": {
     "start": "node src/index.js",
     "lint": "eslint src/*.js test/*.js",
-    "test": "nyc --reporter=html --reporter=text ava"
+    "test": "nyc --reporter=html --reporter=text ava",
+    "bench": "node misc/bench.js"
   },
   "author": "Ambareesh Balaji <ambareeshbalaji@gmail.com>",
   "license": "ISC",