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 @@
A javascript library for easing working with numeric values that have units associated with them.
-npm install unit-value
import UnitValue from 'unit-value';
const uv = new UnitValue(10, "px");
npm install unit-value
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
.
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.
-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).
The API Reference Docs give a good sense of what is possible with the library, but here are some examples
+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"
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);
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"
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).
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.
The code is documented with jsdoc comments.
The documentation for the latest stable code (master
branch) is available online at https://beforan.github.io/unit-value/.
The documentation relevant to the commit you are looking at should always be present inside /docs
, but you can always build the current docs for the code you're looking at by running npm run docs
.
Documentation is kept accurate and up-to-date through the use of a precommit hook. When you commit to git, the docs are automagically built and staged. Bear this in mind if commits appear to be taking longer than usual. If you encounter issues committing, ensure that all npm dev dependencies have been installed with npm install
, and that you have git
available in your PATH
.
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).
Travis builds must pass on PR's, and these run eslint, so the linter will also keep code to the intended quality.
+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.
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 and unit tests, so the linter will also keep code to the intended quality, and tests must pass.
@@ -80,7 +97,7 @@Contributions are welcome. Just raise a PR.