nanoid 0.1.0 → 0.2.2

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Change Log
 This project adheres to [Semantic Versioning](http://semver.org/).
 
+## 0.2.2
+* Reduce `nanoid/generate` size (by Anton Khlynovskiy).
+* Speed up Node.js random generator.
+
+## 0.2.1
+* Fix documentation (by Piper Chester).
+
+## 0.2
+* Add `size` argument to `nanoid()`.
+* Improve performance by 50%.
+* Reduce library size by 26% (by Vsevolod Rodionov and Oleg Mokhov).
+
+## 0.1.1
+* Reduce library size by 5%.
+
 ## 0.1
 * Initial release.

package/README.md

@@ -1,23 +1,25 @@
 # Nano ID
 
-Very small secure URL-friendly unique ID generator.
+A tiny, secure URL-friendly unique string ID generator for JavaScript.
 
 ```js
 var nanoid = require('nanoid')
 model.id = nanoid() //=> "Uakgb_J5m9g~0JDMbcJqLJ"
 ```
 
-**Safe.** It uses cryptographically-strong random APIs
-and tests symbols distribution.
+**Safe.** It uses cryptographically strong random APIs
+and guarantees a proper distribution of symbols.
 
-**Small.** Only 258 bytes (minified and gzipped). Zero-dependency.
+**Small.** Only 179 bytes (minified and gzipped). No dependencies.
+It uses [Size Limit] to control size.
 
 **Compact.** It uses more symbols than UUID (`A-Za-z0-9_~`)
-and have same uniqueness in 22 symbols instead of 36.
+and has the same number of unique options in just 22 symbols instead of 36.
 
-Generator supports Node.js and [all browsers] from IE 11.
+The generator supports Node.js and [all browsers] starting from IE 11.
 
 [all browsers]: http://caniuse.com/#feat=getrandomvalues
+[Size Limit]:   https://github.com/ai/size-limit
 
 <a href="https://evilmartians.com/?utm_source=nanoid">
   <img src="https://evilmartians.com/badges/sponsored-by-evil-martians.svg"
@@ -26,63 +28,92 @@ Generator supports Node.js and [all browsers] from IE 11.
 
 ## Security
 
-*Good article about random generators theory:
+*See a good article about random generators theory:
 [Secure random values (in Node.js)]*
 
 ### Unpredictability
 
-Nano ID doesn’t use unsafe `Math.random()`. It use `crypto` module in Node.js
+Instead of unsafe `Math.random()` Nano ID uses `crypto` module in Node.js
 and Web Crypto API in browsers.
 
 ### Uniformity
 
-`random % alphabet` is a popular mistake in ID generator. Change to get some
-symbols will be lower and it will reduce amount of guesses in bruteforcing.
+`random % alphabet` is a popular mistake to make when coding an ID generator.
+The spread will not be even; there will be a lower chance for some symbols
+to appear compared to others—so it will reduce the number of tries
+when brute-forcing.
 
-Nano ID use [better algorithm] and test uniformity:
+Nano ID uses a [better algorithm] and tests uniformity:
 
 <img src="distribution.png" alt="Nano ID uniformity" width="340" height="135">
 
 [Secure random values (in Node.js)]: https://gist.github.com/joepie91/7105003c3b26e65efcea63f3db82dfba
 [better algorithm]: https://github.com/ai/nanoid/blob/master/format.js
 
+## Comparison with UUID
+
+Nano ID is similar to UUID v4 (random-based). It uses the same number
+of random bits in ID, so it has the same collision probability:
+
+> For there to be a one in a billion chance of duplication,
+> 103 trillion version 4 IDs must be generated.
+
+There are only 2 differences between Nano ID and UUID v4:
+
+1. Nano ID uses a bigger alphabet for ID, so the same random bits
+   are packed in just 22 symbols instead of 36.
+2. Nano ID code is 2 times smaller in size than `uuid/v4` package:
+   179 bytes instead of 435.
+
+## Benchmark
+
+```
+$ ./benchmark
+nanoid          375,840 ops/sec
+nanoid/generate 268,747 ops/sec
+uuid/v4         374,767 ops/sec
+shortid          41,260 ops/sec
+```
+
+
 ## Usage
 
 ### Normal
 
-Main module uses URL-friendly symbols (`A-Za-z0-9_~`) and return ID
-with 22 characters (to have same uniqueness as UUID).
+The main module uses URL-friendly symbols (`A-Za-z0-9_~`) and returns an ID
+with 22 characters (to have the same collisions probability as UUID v4).
 
 ```js
 var nanoid = require('nanoid')
 model.id = nanoid() //=> "Uakgb_J5m9g~0JDMbcJqLJ"
 ```
 
-Symbols `-,.()` are not encoded in URL, but in the end of link they could
-be detected as punctuation.
+Symbols `-,.()` are not encoded in URL, but in the end of a link
+they could be identified as a punctuation symbol.
+
+If you want to reduce ID length (and increase collisions probability),
+you can pass length as argument:
+
+```js
+nanoid(10) //=> "IRFa~VaY2b"
+```
 
 ### Custom Alphabet or Length
 
-If you want to change ID alphabet or length you can use low-level `generate`
-module.
+If you want to change the ID alphabet or the length
+you can use low-level `generate` module.
 
 ```js
 var generate = require('nanoid/generate')
 model.id = generate('1234567890abcdef', 10) //=> "4f90d13a42"
 ```
 
-If you want to use same URL-friendly symbols and just change length,
-you can get default alphabet from `url` module:
-
-```js
-var url = require('nanoid/url')
-model.id = generate(url, 10) //=> "Uakgb_J5m9"
-```
+Alphabet must contain less than 256 symbols.
 
 ### Custom Random Bytes Generator
 
-You can replace default safe random generators by `format` module.
-It could be useful if you need seed-based generator.
+You can replace the default safe random generator using the `format` module.
+For instance, to use seed-based generator.
 
 ```js
 var format = require('nanoid/format')
@@ -96,4 +127,20 @@ function random (size) {
 format(random, "abcdef", 10) //=> "fbaefaadeb"
 ```
 
-`random` callback must accept array size and return array of random numbers.
+`random` callback must accept the array size and return an array
+with random numbers.
+
+If you want to use the same URL-friendly symbols with `format`,
+you can get default alphabet from the `url` module:
+
+```js
+var url = require('nanoid/url')
+format(random, url, 10) //=> "93ce_Ltuub"
+```
+
+## Other Programming Languages
+
+* [Go](https://github.com/matoous/go-nanoid)
+* [PHP](https://github.com/hidehalo/nanoid-php)
+* [Python](https://github.com/puyuan/py-nanoid)
+* [Ruby](https://github.com/radeno/nanoid.rb)

package/format.js

@@ -24,22 +24,20 @@
  * @name format
  */
 module.exports = function (random, alphabet, size) {
-  var step = Math.ceil(310 / alphabet.length * size)
+  var mask = (2 << Math.log(alphabet.length - 1) / Math.LN2) - 1
+  var step = Math.ceil(1.6 * mask * size / alphabet.length)
 
-  var bytes, byte
   var id = ''
-  while (id.length !== size) {
-    bytes = random(step)
-    for (var i = 0; i < bytes.length; i++) {
-      byte = bytes[i]
-      if (byte < alphabet.length) {
+  while (true) {
+    var bytes = random(step)
+    for (var i = 0; i < step; i++) {
+      var byte = bytes[i] & mask
+      if (alphabet[byte]) {
         id += alphabet[byte]
-        if (id.length === size) break
+        if (id.length === size) return id
       }
     }
   }
-
-  return id
 }
 
 /**

package/index.js

@@ -1,10 +1,16 @@
-var generate = require('./generate')
-var url = require('./url')
+var random = require('./random')
+
+var url = '_~0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ'
 
 /**
  * Generate secure URL-friendly unique ID.
  *
- * @return {string} Random string with 22 URL-friendly symbols.
+ * By default, ID will have 22 symbols to have same collisions probability
+ * as UUID v4.
+ *
+ * @param {number} [size=22] The number of symbols in ID.
+ *
+ * @return {string} Random string.
  *
  * @example
  * var nanoid = require('nanoid')
@@ -12,6 +18,12 @@ var url = require('./url')
  *
  * @name nanoid
  */
-module.exports = function () {
-  return generate(url, 22)
+module.exports = function (size) {
+  size = size || 22
+  var id = ''
+  var bytes = random(size)
+  for (var i = 0; i < size; i++) {
+    id += url[bytes[i] & 63]
+  }
+  return id
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "nanoid",
-  "version": "0.1.0",
-  "description": "Very small secure URL-friendly unique ID generator",
+  "version": "0.2.2",
+  "description": "A tiny (179 bytes), secure URL-friendly unique string ID generator",
   "keywords": [
     "uuid",
     "random",
@@ -15,32 +15,39 @@
     "./random.js": "./random-browser.js"
   },
   "devDependencies": {
+    "benchmark": "^2.1.4",
+    "chalk": "^2.1.0",
     "docdash": "^0.4.0",
-    "eslint": "^4.4.0",
-    "eslint-config-logux": "^16.0.0",
+    "eslint": "^4.8.0",
+    "eslint-config-logux": "^16.2.0",
     "eslint-config-standard": "^10.2.1",
     "eslint-plugin-es5": "^1.1.0",
     "eslint-plugin-import": "^2.7.0",
-    "eslint-plugin-jest": "^20.0.3",
-    "eslint-plugin-node": "^5.1.1",
+    "eslint-plugin-jest": "^21.2.0",
+    "eslint-plugin-node": "^5.2.0",
     "eslint-plugin-promise": "^3.5.0",
     "eslint-plugin-security": "^1.4.0",
     "eslint-plugin-standard": "^3.0.1",
     "html-webpack-plugin": "^2.30.1",
-    "jest": "^20.0.4",
-    "jsdoc": "^3.5.4",
-    "lint-staged": "^4.0.2",
+    "jest": "^21.2.1",
+    "jsdoc": "^3.5.5",
+    "lint-staged": "^4.2.3",
+    "microtime": "^2.1.6",
     "pre-commit": "^1.2.2",
-    "size-limit": "^0.8.0",
-    "webpack-dev-server": "^2.6.1",
-    "yaspeller-ci": "^0.6.0"
+    "rimraf": "^2.6.2",
+    "shortid": "^2.2.8",
+    "size-limit": "^0.11.6",
+    "uuid": "^3.1.0",
+    "webpack-dev-server": "^2.9.1",
+    "yaspeller-ci": "^0.7.0"
   },
   "scripts": {
     "lint-staged": "lint-staged",
     "spellcheck": "yarn docs && yaspeller-ci *.md docs/*.html",
+    "clean": "rimraf docs/ coverage/",
     "docs": "jsdoc --configure .jsdocrc *.js",
     "lint": "eslint *.js test/*.js",
-    "test": "jest --coverage && yarn lint && yarn spellcheck && size-limit",
+    "test": "jest --coverage && yarn lint && size-limit && yarn spellcheck",
     "demo": "webpack-dev-server --config test/demo/webpack.config"
   },
   "jest": {
@@ -56,7 +63,11 @@
   "size-limit": [
     {
       "path": "index.js",
-      "limit": "260 B"
+      "limit": "179 B"
+    },
+    {
+      "path": "generate.js",
+      "limit": "184 B"
     }
   ],
   "lint-staged": {

package/random.js

@@ -1,5 +1 @@
-var randomBytes = require('crypto').randomBytes
-
-module.exports = function (bytes) {
-  return randomBytes(bytes)
-}
+module.exports = require('crypto').randomBytes