A tiny, secure URL-friendly unique string ID generator for JavaScript
JavaScript HTML
Switch branches/tags
Nothing to show
Latest commit 116c48d Aug 15, 2017 @ai Clean up docs

README.md

Nano ID

A tiny, secure URL-friendly unique string ID generator for JavaScript.

var nanoid = require('nanoid')
model.id = nanoid() //=> "Uakgb_J5m9g~0JDMbcJqLJ"

Safe. It uses cryptographically strong random APIs and guarantees a proper distribution of symbols.

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 has the same number of unique options in just 22 symbols instead of 36.

The generator supports Node.js and all browsers starting from IE 11.

Sponsored by Evil Martians

Security

See a good article about random generators theory: Secure random values (in Node.js)

Unpredictability

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 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 uses a better algorithm and tests uniformity:

Nano ID uniformity

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.

Usage

Normal

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).

var nanoid = require('nanoid')
model.id = nanoid() //=> "Uakgb_J5m9g~0JDMbcJqLJ"

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:

nanoid(10) //=> "IRFa~VaY2b"

Custom Alphabet or Length

If you want to change the ID alphabet or the length you can use low-level generate module.

var generate = require('nanoid/generate')
model.id = generate('1234567890abcdef', 10) //=> "4f90d13a42"

Alphabet must contain less than 256 symbols.

Custom Random Bytes Generator

You can replace the default safe random generator using the format module. For instance, to use seed-based generator.

var format = require('nanoid/format')

function random (size) {
  var result = []
  for (var i = 0; i < size; i++) result.push(randomByte())
  return result
}

format(random, "abcdef", 10) //=> "fbaefaadeb"

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:

var url = require('nanoid/url')
format(random, url, 10) //=> "93ce_Ltuub"