JS-Utility-Belt

Opinionated collection of JavaScript nice-to-haves.

From the experiences of building the frontends of ascribe.io, whereonthe.net, and various examples with BigchainDB.

Usage

Simply npm install -S js-utility-belt and start using import { ... } from 'js-utility-belt' (assuming you've met the dependencies!

There are a number of outputs generated by npm after installation, dependending on your needs:

• js-utility-belt/lib - Transpiled, ES5 compatible CommonJS modules (for most module bundlers) (Default)
• js-utility-belt/es6 - Transpiled, ES5 compatible ES6 modules (for newer module bundlers that understand ES6 module and can provide tree-shaking; ie. rollup, jspm, webpack@2)
• js-utility-belt/bundle - Transpiled, bundled, and minified UMD modules (for droppin' into your site)

Dependencies

If you are using either of the non-bundled versions (/es6 or /lib), you should make sure your environment either supports all ES6 features, or you have polyfilled them in (recommended: core-js/es6, and isomorphic-fetch).

This is not necessary for the bundled version as all polyfills have already been included.

Reducing import size

Importing from the base index of either of the transpiled versions (/lib or /es6) will import the entire package (even with treeshaking!). To make sure you only import what you need, you can import just the module (ie. lib/general, lib/cookie, etc...) or even just the particular function (ie. lib/general/safe_merge, lib/cookie/get_cookie) that you want.

If you have treeshaking enabled, you can safely import from the ES6 version at the module level and let treeshaking remove any unused imports from the module (making function-level imports unnecessary).

Development

Any added functions or modules should be structured to allow for selective imports by the user. With this in mind, there are two rules to follow:

• Modules: Each module should be its own folder
  • Modules should include a index.js that re-exports all contained functions
  • Modules should be re-exported through the package's index.js with an extended-export-from statement: export * as Module from './module'
• Functions: Each function should be contained in its own file, adhering to the style guide's naming scheme: the file name should be the snake_case form of the function's name.

Style guide

See the ascribe/javascript styleguide.

TODO

• [ ] Unit tests
• [ ] Add documentation on which utilities are available