Awesome
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
- Comparison with UUID
- Tools
- Security
- Usage
- CLI
- API
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:
- Nano ID uses a bigger alphabet, so a similar number of random bits are packed in just 21 symbols instead of 36.
- Nano ID code is 4 times less than
uuid/v4
package: 127 bytes instead of 435. - 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 withnanoid/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"
}