diff options
Diffstat (limited to 'node_modules/yeast/README.md')
| -rw-r--r-- | node_modules/yeast/README.md | 82 |
1 files changed, 82 insertions, 0 deletions
diff --git a/node_modules/yeast/README.md b/node_modules/yeast/README.md new file mode 100644 index 0000000..0b0af0d --- /dev/null +++ b/node_modules/yeast/README.md @@ -0,0 +1,82 @@ +# yeast + +[](http://unshift.io)[](http://browsenpm.org/package/yeast)[](https://travis-ci.org/unshiftio/yeast)[](https://david-dm.org/unshiftio/yeast)[](https://coveralls.io/r/unshiftio/yeast?branch=master)[](https://webchat.freenode.net/?channels=unshift) + +[](https://saucelabs.com/u/yeast) + +Yeast is a unique id generator. It has been primarily designed to generate a +unique id which can be used for cache busting. A common practice for this is +to use a timestamp, but there are couple of downsides when using timestamps. + +1. The timestamp is already 13 chars long. This might not matter for 1 request + but if you make hundreds of them this quickly adds up in bandwidth and + processing time. +2. It's not unique enough. If you generate two stamps right after each other, + they would be identical because the timing accuracy is limited to + milliseconds. + +Yeast solves both of these issues by: + +1. Compressing the generated timestamp using a custom `encode()` function that + returns a string representation of the number. +2. Seeding the id in case of collision (when the id is identical to the previous + one). + +To keep the strings unique it will use the `.` char to separate the generated +stamp from the seed. + +## Installation + +The module is intended to be used in browsers as well as in Node.js and is +therefore released in the npm registry and can be installed using: + +``` +npm install --save yeast +``` + +## Usage + +All the examples assume that this library is initialized as follow: + +```js +'use strict'; + +var yeast = require('yeast'); +``` + +To generate an id just call the `yeast` function. + +```js +console.log(yeast(), yeast(), yeast()); // outputs: KyxidwN KyxidwN.0 KyxidwN.1 + +setTimeout(function () { + console.log(yeast()); // outputs: KyxidwO +}); +``` + +### yeast.encode(num) + +An helper function that returns a string representing the specified number. The +returned string contains only URL safe characters. + +```js +yeast.encode(+new Date()); // outputs: Kyxjuo1 +``` + +### yeast.decode(str) + +An helper function that returns the integer value specified by the given string. +This function can be used to retrieve the timestamp from a `yeast` id. + +```js +var id = yeast(); // holds the value: Kyxl1OU + +yeast.decode(id); // outputs: 1439816226334 +``` + +That's all folks. If you have ideas on how we can further compress the ids +please open an issue! + +## License + +[MIT](LICENSE) |