Nano ID

A port of nanoid to Deno

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

import { nanoid } from "https://deno.land/x/nanoid/mod.ts"
nanoid() //=> "lQLTBJKVRCuc"

Table of Contents

1. Comparison with UUID
2. Tools
3. Security
4. Usage
   1. JS
   2. Other Programming Languages
5. CLI
   1. Installation
   2. Usage
6. API
   1. Async
   2. Custom Alphabet or Length
   3. Custom Random Bytes Generator

Comparison with UUID

Nano ID is quite comparable to UUID v4 (random-based). It has a similar number of random bits in the ID (126 in Nano ID and 122 in UUID), so it has a similar collision probability:

For there to be a one in a billion chance of duplication, 103 trillion version 4 IDs must be generated.

There are three main differences between Nano ID and UUID v4:

1. Nano ID uses a bigger alphabet, so a similar number of random bits are packed in just 21 symbols instead of 36.
2. Nano ID code is 4 times less than uuid/v4 package: 127 bytes instead of 435.
3. Because of memory allocation tricks, Nano ID is 16% faster than UUID.

Tools

• ID size calculator to choice smaller ID size depends on your case.
• nanoid-dictionary with popular alphabets to use with nanoid/generate.

Security

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

Unpredictability

Instead of using the unsafe Math.random(), Nano ID uses the Web Crypto API. These modules use unpredictable hardware random generator.

Usage

JS

The main module uses URL-friendly symbols (A-Za-z0-9_-) and returns an ID with 21 characters (to have a collision probability similar to UUID v4).

import { nanoid } from "https://deno.land/x/nanoid/mod.ts"
nanoid() //=> "lQLTBJKVRCuc"

If you want to reduce ID length (and increase collisions probability), you can pass the length as an argument.

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

Don’t forget to check the safety of your ID length in our ID collision probability calculator.

Other Programming Languages

Nano ID was ported to many languages. You can use these ports to have the same ID generators on client and server side.

• Node.js
• C#
• Clojure and ClojureScript
• Crystal
• Dart
• Go
• Elixir
• Haskell
• Java
• Nim
• PHP
• Python with dictionaries
• Ruby
• Rust
• Swift

Also, CLI tool is available to generate IDs from a command line.

$ deno run https://deno.land/x/nanoid/cli.ts

CLI

Installation

$ deno install --name nanoid https://deno.land/x/nanoid/cli.ts

Usage

  Usage:   nanoid
  Version: v2.0.0

  Description:

    A CLI for generating cryptographically-secure random IDs.

  Options:

    -h, --help                         - Show this help.                                                             
    -V, --version                      - Show the version number for this program.                                   
    -s, --size      <size:number>      - The desired length of IDs to be generated.                                  
    -a, --alphabet  <alphabet:string>  - The alphabet that IDs should be generated with.                             
    -n, --number    <n:number>         - The number of IDs to generate, if you would like more than one  (Default: 1)

  Commands:

    completions  - Generate shell completions.

API

Async

To generate hardware random bytes, CPU will collect electromagnetic noise. During the collection, CPU doesn’t work.

If we will use asynchronous API for random generator, another code could be executed during the entropy collection.

import { nanoid } from "https://deno.land/x/nanoid/async.ts";

async function createUser () {
  user.id = await nanoid();
}

Custom Alphabet or Length

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

import { customAlphabet } from "https://deno.land/x/nanoid/customAlphabet.ts";
const nanoid = customAlphabet('1234567890abcdef', 10)
nanoid()  // => "4f90d13a42"

Alphabet must contain 256 symbols or less. Otherwise, the generator will not be secure.

Asynchronous API is also available:

import { customAlphabet } from "https://deno.land/x/nanoid/async.ts";
const nanoid = await customAlphabet('1234567890abcdef', 10);
async function createUser() {
  let id = nanoid();
}

Custom Random Bytes Generator

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

import { customRandom } from "https://deno.land/x/nanoid/customRandom.ts";

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

const nanoid = customRandom(random, "abcdef", 10);
nanoid(); // => "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 the default alphabet from the url file.

import { customRandom } from "https://deno.land/x/nanoid/customRandom.ts";
import { urlAlphabet } from "https://deno.land/x/nanoid/urlAlphabet.ts";

const nanoid = customRandom(random, chars, 10);
nanoid(); // => "93ce_Ltuub"

Asynchronous API is also available:

import { customRandom } from 'https://deno.land/x/nanoid/async.ts';
import { urlAlphabet } from "https://deno.land/x/nanoid/urlAlphabet.ts";

function random (size) {
  return Promise.resolve(/*…*/)
}
const nanoid = await customRandom(random, url, 10);
async function createUser () {
  let id = nanoid(); // => "93ce_Ltuub"
}