# Gnar Edge: Precision edging for JS apps [![MIT license](http://img.shields.io/badge/license-MIT-brightgreen.svg)](http://opensource.org/licenses/MIT) [![codecov](https://codecov.io/gl/gnaar/edge/branch/master/graph/badge.svg?token=MRowdXaujg)](https://codecov.io/gl/gnaar/edge) [![pipeline status](https://gitlab.com/gnaar/edge/badges/master/pipeline.svg)](https://gitlab.com/gnaar/edge/commits/master) [![npm version](https://badge.fury.io/js/gnar-edge.svg)](https://badge.fury.io/js/gnar-edge) [![total downloads of gnar-edge](https://img.shields.io/npm/dt/gnar-edge.svg)](https://www.npmjs.com/package/gnar-edge) **Part of Project Gnar:**  [base](https://hub.docker.com/r/gnar/base)  •  [gear](https://pypi.org/project/gnar-gear)  •  [piste](https://gitlab.com/gnaar/piste)  •  [off-piste](https://gitlab.com/gnaar/off-piste)  •  [edge](https://www.npmjs.com/package/gnar-edge)  •  [powder](https://gitlab.com/gnaar/powder)  •  [genesis](https://gitlab.com/gnaar/genesis)  •  [patrol](https://gitlab.com/gnaar/patrol) **Get started with Project Gnar on**  [![Project Gnar on Medium](https://s3-us-west-2.amazonaws.com/project-gnar/medium-68x20.png)](https://medium.com/@ic3b3rg/project-gnar-d274165793b6) **Join Project Gnar on**  [![Project Gnar on Slack](https://s3-us-west-2.amazonaws.com/project-gnar/slack-69x20.png)](https://join.slack.com/t/project-gnar/shared_invite/enQtNDM1NzExNjY0NjkzLWQ3ZTQyYjgwMjkzNWYxNDJiNTQzODY0ODRiMmZiZjVkYzYyZWRkOWQzNjA0OTk3NWViNWM5YTZkMGJlOGIzOWE) **Support Project Gnar on**  [![Project Gnar on Patreon](https://s3-us-west-2.amazonaws.com/project-gnar/patreon-85x12.png)](https://patreon.com/project_gnar) **Gnar Edge is a sharp set of JS utilities:**  [base64](#base64)  •  [drain](#drain)  •  [handleChange](#handlechange)  •  [JWT](#jwt)  •  [notifications](#notifications)  •  [redux](#redux) #### Installation ```bash npm install gnar-edge ``` or ```bash yarn add gnar-edge ``` #### Packages Gnar Edge ships with three distinct types of packages: - Single optimized (45.0 KB) ES5 main package - Discreet ES5 tree-shakable packages (sizes listed below) - ES6 tree-shakable modules (recommended) Choose only one type of package to use in your application; mixing package types will needlessly increase the size of your production build. The ES5 packages are transpiled via Babel using the following [browserslist](https://www.npmjs.com/package/browserslist) setting: ```json "browserslist": [ ">0.25%", "ie >= 11" ] ``` This is a fairly conservative setting, [largely due to the inclusion of IE 11](https://caniuse.com/#compare=ie+11,edge+17,chrome+68) (scroll down), and may result in build that is larger than necessary for your specific needs. The overall browser market share of that setting can be found at [browserl.ist](http://browserl.ist/?q=%3E0.25%25%2C%20ie%20%3E%3D%2011), however the global coverage listed there is a bit misleading. Babel uses the [lowest common denominator](https://babeljs.io/docs/en/babel-preset-env/#determine-the-lowest-common-denominator-of-plugins-to-be-included-in-the-preset) of all the ES6 features in your code vs. the [target browsers' ES6 support](https://caniuse.com/#comparison) to determine which shims to include in the build. The global market share of browsers that support your code with the bundled shims is likely much higher. If you prefer to transpile Gnar Edge using a different set of target browsers, use [Gnar Edge's ES6](#es6-tree-shakable-modules) modules. Gnar Edge is written in ES6+. See the [ES6 Tree-Shakable Modules](#es6-tree-shakable-modules) section for more info. #### Main Package Chose the main package when want ES5 code and you plan to use all the Gnar Edge utilities in your app *or* when the combined size of the utilities (listed below) you choose to use exceeds 45.0 KB. The main package is smaller than the combined total of the tree-shakable packages (45.0 KB vs. 54.7 KB) due to the webpack module overhead, module overlap (i.e. `base64` and `jwt`) and overlap of the babel shims between modules. The main package may grow over time. There is a high probability that new utilities will be added to Gnar Edge in the future and all new utilities will be added to the main package. Whenever a new utility is added, Gnar Edge's major semver will be incremented (e.g. `1.x.x` -> `2.0.0`). ##### Usage The main package can be used as an [ES6 import](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import) or a [Node require](https://nodejs.org/api/modules.html#modules_modules): ```javascript import { base64, drain, handleChange, jwt, notifications } from 'gnar-edge'; ``` or ```javascript const { base64, drain, handleChange, jwt, notifications } = require('gnar-edge'); ``` In the module docs and code examples, we'll be using the ES6 format. #### ES5 Tree-Shakable Packages If you want ES5 code and you only need some of Gnar Edge's utilities, we can take advantage of Webpack's [tree shaking](https://webpack.js.org/guides/tree-shaking) to reduce the size of your production build. The tree-shakable packages are: Package | Size -- | --: gnar-edge/base64 | 2.3 KB gnar-edge/drain | 3.5 KB gnar-edge/handleChange | 2.8 KB gnar-edge/jwt | 4.2 KB gnar-edge/notifications | 35.6 KB gnar-edge/redux | 6.3 KB ##### Usage Each tree-shakable package can be used as an [ES6 import](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/import) or a [Node require](https://nodejs.org/api/modules.html#modules_modules), for example: ```javascript import base64 from 'gnar-edge/base64'; ``` or ```javascript const base64 = require('gnar-edge/base64').default; ``` In the module docs and code examples, we'll be using the ES6 format. #### ES6 Tree-Shakable Modules Gnar Edge is written in ES6+, i.e. ES6 mixed with a few features that are in the [TC39 process](https://tc39.github.io/process-document), namely the [bind operator](https://babeljs.io/blog/2015/05/14/function-bind) (`::`) and [decorators](http://babeljs.io/docs/en/babel-plugin-transform-decorators). Using Gnar Edge's ES6 modules will significantly reduce your production build size vs. using the ES5 packages, but it does require extra setup work. The ES6 modules that ship with Gnar Edge are not minified (minification / uglification should be part of your build process). The ES6 modules are: Module | Size -- | --: gnar-edge/es/base64 | 0.7 KB gnar-edge/es/drain | 2.1 KB gnar-edge/es/handleChange | 0.6 KB gnar-edge/es/jwt | 2.1 KB gnar-edge/es/notifications | 19.6 KB gnar-edge/es/redux | 3.3 KB The minified module sizes reported above are produced in the [Gnar Powder](https://gitlab.com/gnaar/powder) build. YMMV. The total gzipped size of gnar-edge (excluding drain) is 4.6 KB. This is really the most noteworthy number since it is the number of bytes that will be transmitted over the wire if your server is properly configured. To use the ES6 modules with Babel 7, follow these steps: 1. Install the following babel plugins: ```bash npm i -D \ @babel/plugin-syntax-dynamic-import \ @babel/plugin-proposal-function-bind \ @babel/plugin-proposal-export-default-from \ @babel/plugin-proposal-decorators \ @babel/plugin-proposal-class-properties ``` 1. Add these plugins to your `babel.config.js` file, e.g. ```javascript { presets: [ '@babel/preset-env', '@babel/react' ], env: { production: { presets: [ 'react-optimize' ] } }, plugins: [ 'react-hot-loader/babel', '@babel/transform-runtime', '@babel/plugin-syntax-dynamic-import', '@babel/plugin-proposal-function-bind', '@babel/plugin-proposal-export-default-from', [ '@babel/plugin-proposal-decorators', { legacy: true } ], [ '@babel/plugin-proposal-class-properties', { loose: true } ] ] } ``` Check the [Edge](https://gitlab.com/gnaar/edge) and [Powder](https://gitlab.com/gnaar/powder) repos for complete examples of `package.json` and `babel.config.js`. 1. Update your webpack module rule for javascript to *not* exclude `gnar-edge`. You will likely have a js rule that looks like: ```javascript { test: /\.jsx?$/, exclude: /node_modules/, use: 'babel-loader' } ``` Change the rule to: ```javascript { test: /\.jsx?$/, exclude: /node_modules\/(?!gnar-edge)/, use: 'babel-loader' } ``` This tells babel to transpile the gnar-edge code along with your application code. 1. If you're linting with eslint, add `"legacyDecorators": true` to `parserOptions.ecmaFeatures` in `.eslintrc`. 1. If you're testing with Jest, add or update `transformIgnorePatterns` in `package.json` to exclude `gnar-edge`, e.g. ```json "transformIgnorePatterns": [ "/node_modules/(?!gnar-edge)" ], ``` This tells Jest to transpile the gnar-edge code. 1. Use the Gnar Edge `es` modules in your app, e.g.: ```javascript import base64 from 'gnar-edge/es/base64'; ``` ## Base64 - [Code](https://gitlab.com/gnaar/edge/blob/master/src/modules/base64.js) - [Tests / Examples](https://gitlab.com/gnaar/edge/blob/master/src/modules/__tests__/base64.test.js) **Usage:** Using the [ES5 main package](#main-package): ```javascript import { base64 } from 'gnar-edge'; ``` or, using the [ES5 tree-shakable package](#es5-tree-shakable-packages): ```javascript import base64 from 'gnar-edge/base64'; ``` or, using the [ES6 tree-shakable module](#es6-tree-shakable-modules): ```javascript import base64 from 'gnar-edge/es/base64'; ``` Read the [package usage](#packages) section if you're unsure of which format to use. The `base64` package provides three simple functions for encoding and decoding base64 content: - `base64.decode` handles both traditional and [web-safe](https://docs.python.org/2/library/base64.html#base64.urlsafe_b64encode) base64 content, outputs a UTF-8 string - `base64.encode` encodes a UTF-8 string to web-safe base64 - `base64.encodeNonWebSafe` encode a UTF-8 string to traditional base64 **Examples:** ```javascript base64.encode('✓ à la mode'); // '4pyTIMOgIGxhIG1vZGU=' base64.decode('4pyTIMOgIGxhIG1vZGU='); // '✓ à la mode' base64.encode(' >'); // 'ICA-' base64.encode(' ?'); // 'ICA_' base64.encodeNonWebSafe(' >'); // 'ICA+' base64.encodeNonWebSafe(' ?'); // 'ICA/' ``` Acknowledgements - [MDN](https://developer.mozilla.org/en-US/docs/Web/API/WindowBase64/Base64_encoding_and_decoding) offers two alternative solutions for transcoding Unicode to Base64. ## Drain - [Code](https://gitlab.com/gnaar/edge/blob/master/src/modules/drain.js) - [Tests / Examples](https://gitlab.com/gnaar/edge/blob/master/src/modules/__tests__/drain.test.js) **Usage:** Using the [ES5 main package](#main-package): ```javascript import { drain } from 'gnar-edge'; ``` or, using the [ES5 tree-shakable package](#es5-tree-shakable-packages): ```javascript import drain from 'gnar-edge/drain'; ``` or, using the [ES6 tree-shakable module](#es6-tree-shakable-modules): ```javascript import drain from 'gnar-edge/es/drain'; ``` Read the [package usage](#packages) section if you're unsure of which format to use. Drain converts a generator function to a promise. It supports yields of all JS types, i.e.: - Functions / Thunks - Promises - Generator Functions - Generators - Async Functions - Arrays (recursively) - Plain (i.e. Literal) Objects (recursively) - Basic JS Types (Number, String, Boolean, Date, etc.) **Example:** ```javascript drain(function* () { let result = 1; result *= yield 2; const array = yield [3]; result *= array[0]; const object = yield { x: 4 }; result *= object.x; result *= yield new Promise(resolve => { setTimeout(() => { resolve(5); }, 10); }); result *= yield () => 6; result *= yield () => new Promise(resolve => { setTimeout(() => { resolve(7); }, 10); }); const mixedArray = yield [ 8, new Promise(resolve => { setTimeout(() => { resolve(9); }, 10); }), () => new Promise(resolve => { setTimeout(() => { resolve(10); }, 10); }) ]; mixedArray.forEach(x => { result *= x; }); const mixedObject = yield { a: 11, b: new Promise(resolve => { setTimeout(() => { resolve(12); }, 10); }), c: () => new Promise(resolve => { setTimeout(() => { resolve(13); }, 10); }) }; Object.values(mixedObject).forEach(x => { result *= x; }); function* generatorFunction1() { return yield 14; } result *= yield generatorFunction1; function* generatorFunction2(x) { return yield x; } const generator = generatorFunction2(15); result *= yield generator; result *= yield async () => { try { return await new Promise(resolve => { setTimeout(() => { resolve(16); }, 10); }); } catch (e) { throw e; } }; return result; }) .then(result => { console.log(result); /* 20922789888000, i.e. 16! */ }); ``` #### Implementation Note Drain returns a function which returns a promise. The returned function includes three convenience methods, `then`, `catch`, and `finally` which invoke the function and chain onto the resulting promise. The six basic methods of utilizing `drain` are: - as a function: ```javascript const fn = drain(function* () {}); ``` - as a promise: ```javascript const promise = drain(function* () {})(); ``` - `then` chained: ```javascript drain(function* () { return yield 'oh, yeah!'; }) .then(result => { console.log(result); }); ``` ```bash >> 'oh, yeah!' ``` - `then` chained with `error` support: ```javascript drain(function* () { throw new Error('oops'); yield 'unreachable'; }).then( result => { console.log(result); }, error => { console.log(error.message); }); ``` ```bash >> 'oops' ``` - `catch` chained: ```javascript drain(function* () { throw new Error('oops, I did it again'); yield 'unreachable'; }) .catch(error => { console.log(error.message); }); ``` ```bash >> 'oops, I did it again' ``` - `finally` chained: ```javascript drain(function* () { throw new Error('oops'); yield 'unreachable'; }) .finally(() => { console.log('always called'); }); ``` ```bash >> 'always called' ``` #### Usage with Jest Testing generator functions in Jest is simple with `drain`. **Example:** ```javascript describe('Testing a generator function', drain(function* () { const theAnswerToLifeTheUniverseAndEverything = yield 42; expect(theAnswerToLifeTheUniverseAndEverything).toBe(42); })); ``` Acknowledgements [co](https://github.com/tj/co) by [@tj](https://github.com/tj) provides similar functionality to `drain`. I initially used `co` in Project Gnar. I wrote `drain` as an enhancement to `co` to add these features: - handle basic JS types (numbers, strings, booleans, dates, etc) - handle functions and thunks without a callback (i.e. co's `done`) - fix an issue with `co.wrap` - I had to override `co.wrap` to get it to pass along the generator function in my Jest tests - provide a single dual-purpose interface, i.e. `drain` replaces both `co` and `co.wrap` - ES6 implementation - `co` is written in ES5 whereas `drain` is written in ES6 and transpiled via Babel - Simplified implementation: 43 SLOC vs. 101 ## HandleChange - [Code](https://gitlab.com/gnaar/edge/blob/master/src/modules/handleChange.js) - [Tests / Examples](https://gitlab.com/gnaar/edge/blob/master/src/modules/__tests__/handleChange.test.js) **Usage:** Using the [ES5 main package](#main-package): ```javascript import { handleChange } from 'gnar-edge'; ``` or, using the [ES5 tree-shakable package](#es5-tree-shakable-packages): ```javascript import handleChange from 'gnar-edge/handleChange'; ``` or, using the [ES6 tree-shakable module](#es6-tree-shakable-modules): ```javascript import handleChange from 'gnar-edge/es/handleChange'; ``` Read the [package usage](#packages) section if you're unsure of which format to use. The `handleChange` package provides an `onChange` event handler which updates the state of a bound React element. It accepts an optional callback and an optional set of options. - `handleChange(<< stateKeyName: String >>, << ?callback: Function >>, << ?options >>)` **options:** - `beforeSetState` [Function]: Function to call before updating the state. It works with: - `` - `` - `` - `