83 lines
2.9 KiB
Markdown
83 lines
2.9 KiB
Markdown
|
# 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)
|