diff --git a/README.md b/README.md index 9195aa8..5f2e58d 100644 --- a/README.md +++ b/README.md @@ -11,9 +11,15 @@ A javascript library for easing working with numeric values that have units asso ## Use in node (or with browserify / webpack etc) -* `npm install unit-value` -* `import UnitValue from 'unit-value';` -* `const uv = new UnitValue(10, "px");` +`npm install unit-value` + +```js +const UnitValue = require("unit-value"); +const uv = new UnitValue(10, "px"); +console.log(uv.add(25).toString()); // prints "35px" +``` + +There is a small sample node script that can be run with `npm run sample`. ## Use in the browser @@ -22,10 +28,49 @@ Currently there's no standalone build for browser use. This will probably be added in future, but there may be some namespacing changes to make for that. Also I feel the library is significantly more useful inside modules than in the browser. +## Examples + +The API Reference Docs give a good sense of what is possible with the library, but here are some examples + +### Perform math on CSS values without separating the units and adding them back after + +```js +element1.style.width = "100px"; +element2.style.width = UnitValue.parse(element1.style.width) // turn the existing css value string into a UnitValue + .subtract(30) // make it slightly smaller + .toString(); // returns "70px" +``` + +### Perform math using regular javascript operators, while using the friendly string for UI display + +```js +const period = new UnitValue(10, "s"); // amount of time in seconds +myUI.timePeriod = period.toString(); // "10s" + +// convert to milliseconds to have a repeating action every 10s +const periodMs = period * 1000; // the js * operator uses `valueOf()` for the UnitValue object, and works normally +setInterval(() => console.log("hello"), periodMs); +``` + +### Perform unit conversions, changing the units string at the same time as doing the calculation + +```js +const length_us = "5 inches"; +const length_international = UnitValue.parse(length_us) // create a UnitValue from the original value + .multiply(2.54, "cm") // apply the conversion math and change the resulting units + .toString(); // return a string again - "2.54cm" +``` + # Build `npm run lib` will run the source through Babel, producing a lib directory which can be consumed in a node.js environment (this is what the npm package is). +# Test + +The library is fully test covered by `mocha`, with `chai` expect assertions. `nyc` assesses and reports on code coverage. + +Tests can be run with `npm test` but the library will need to be built first. + # Documentation The code is documented with jsdoc comments. @@ -44,6 +89,10 @@ Contributions are welcome. Just raise a PR. PR's are more likely to be considered in response to issues. -The repo (and npm scripts) uses `eslint` and `prettier`, as well as providing a basic `editorconfig`, so it's pretty hard to not follow a consistent style (since prettier formats on commit). +The repo (and npm scripts) uses `eslint` and `prettier`, as well as providing a basic `editorconfig`, so it's pretty hard to _not_ follow a consistent style (since prettier formats on commit). + +`npm lint` will run the linter, but it's recommended to use an editor that supports eslint, and prefereably prettier too. I use [Visual Studio Code](https://code.visualstudio.com). + +PRs should contain unit tests. Refer to the existing tests for style expectations. Preferably code coverage will be at 100% before a PR is accepted, unless there is a good reason for reduced coverage. -Travis builds must pass on PR's, and these run eslint, so the linter will also keep code to the intended quality. +Travis builds must pass on PR's, and these run eslint and unit tests, so the linter will also keep code to the intended quality, and tests must pass. diff --git a/docs/UnitValue.html b/docs/UnitValue.html index bbcfadc..09a3093 100644 --- a/docs/UnitValue.html +++ b/docs/UnitValue.html @@ -3090,7 +3090,7 @@
Example

diff --git a/docs/external-parse-unit.html b/docs/external-parse-unit.html index f805c25..7e5e73f 100644 --- a/docs/external-parse-unit.html +++ b/docs/external-parse-unit.html @@ -140,7 +140,7 @@


diff --git a/docs/externals.js.html b/docs/externals.js.html index dc83e76..831ec86 100644 --- a/docs/externals.js.html +++ b/docs/externals.js.html @@ -59,7 +59,7 @@

externals.js


diff --git a/docs/index.html b/docs/index.html index d44b377..e79df1c 100644 --- a/docs/index.html +++ b/docs/index.html @@ -51,23 +51,40 @@

Home

Classes