Gerador NanoID

O que é NanoID?

NanoID é um gerador de IDs aleatórios pequeno, rápido e seguro para URL. Por padrão produz strings de 21 caracteres usando um alfabeto de 64 caracteres (A-Za-z0-9_-), fornecendo aproximadamente 126 bits de entropia — comparável aos 122 bits do UUID v4, mas em uma string mais curta.

NanoID não incorpora um timestamp ou qualquer dado estruturado. Cada ID é puramente aleatório, gerado a partir do gerador de números aleatórios criptograficamente seguro do sistema operacional (crypto.getRandomValues() em navegadores, crypto.randomBytes() no Node.js).

NanoID vs UUID v4

NanoID e UUID v4 são ambos geradores de IDs aleatórios apoiados por um CSPRNG. Eles diferem em formato, comprimento e suporte de ecossistema:

Escolha UUID v4 quando a interoperabilidade com sistemas externos importa — bancos de dados com colunas UUID nativas, APIs esperando formato UUID, ou infraestrutura de log que analisa UUIDs. Escolha NanoID quando quiser IDs mais curtos e controlar toda a stack.

Probabilidade de Colisão por Tamanho

A probabilidade de colisão do NanoID depende do comprimento do ID e da taxa de geração. A tabela a seguir usa o alfabeto padrão de 64 caracteres:

O tamanho padrão de 21 caracteres é escolhido para corresponder à resistência a colisões do UUID v4 (~126 bits) sendo 41% mais curto. Para a maioria das aplicações, 21 caracteres é a escolha certa.

Alfabetos Personalizados

O alfabeto do NanoID é totalmente personalizável. A biblioteca aceita qualquer string de caracteres únicos como alfabeto e gera IDs usando apenas esses caracteres:

Importante: use nanoid/non-secure apenas para aplicações não sensíveis à segurança (ex.: IDs de elementos UI). Para qualquer ID que precise ser impossível de adivinhar, sempre use a importação segura padrão.

Como NanoID Gera Aleatoriedade

NanoID usa o gerador de números pseudoaleatórios criptograficamente seguro (CSPRNG) do sistema operacional. Em navegadores é crypto.getRandomValues(); no Node.js é crypto.randomFillSync(). Esta é a mesma fonte de entropia usada para chaves de sessão TLS — muito mais forte que Math.random().

Amostragem por Rejeição (Evitando Viés de Módulo)

Uma abordagem ingênua para gerar caracteres aleatórios seria: pegar um byte aleatório (0–255) e calcular byte % alphabetSize. Isso introduz o viés de módulo — alguns caracteres aparecem ligeiramente mais frequentemente que outros quando o tamanho do alfabeto não divide uniformemente 256.

NanoID elimina esse viés usando amostragem por rejeição:

1. Determine a menor máscara de potência de dois que cubra o tamanho do alfabeto (ex.: para um alfabeto de 64 chars, a máscara é 63 = 0b00111111)
2. Gere bytes aleatórios e aplique a máscara: byte & mask
3. Se o valor mascarado estiver dentro do intervalo do alfabeto, use-o. Caso contrário, descarte e tente novamente.

Isso significa que alguns bytes aleatórios são descartados, mas o resultado é uma distribuição perfeitamente uniforme sobre o alfabeto — nenhum caractere é mais provável que outro.

// Pure browser — no npm package needed
function generateNanoid(alphabet, size) {
  const mask = (2 << (31 - Math.clz32((alphabet.length - 1) | 1))) - 1
  const step = Math.ceil((1.6 * mask * size) / alphabet.length)
  let id = ''
  while (id.length < size) {
    const bytes = crypto.getRandomValues(new Uint8Array(step))
    for (const byte of bytes) {
      const idx = byte & mask
      if (idx < alphabet.length) {
        id += alphabet[idx]
        if (id.length === size) break
      }
    }
  }
  return id
}

const URL_SAFE = 'useandom-26T198340PX75pxJACKVERYMINDBUSHWOLF_GQZbfghjklqvwyzrict'
generateNanoid(URL_SAFE, 21)  // → "V1StGXR8_Z5jdHi6B-myT"

Suporte de Ambiente

Exemplos de Código

JavaScript / TypeScript

// npm i nanoid
import { nanoid } from 'nanoid'
nanoid()          // → "V1StGXR8_Z5jdHi6B-myT" (21 chars, URL-safe)
nanoid(8)         // → "Uakgb_J5" (custom size)

// Custom alphabet
import { customAlphabet } from 'nanoid'
const hexId  = customAlphabet('0123456789abcdef', 16)
hexId()       // → "4f3a1b8c9d2e0f7a"

const numId  = customAlphabet('0123456789', 8)
numId()       // → "30812894"

Navegador (CDN)

NanoID pode ser usado diretamente no navegador via importação CDN. Nenhuma etapa de build necessária para prototipagem rápida.

// Pure browser — no npm package needed
function generateNanoid(alphabet, size) {
  const mask = (2 << (31 - Math.clz32((alphabet.length - 1) | 1))) - 1
  const step = Math.ceil((1.6 * mask * size) / alphabet.length)
  let id = ''
  while (id.length < size) {
    const bytes = crypto.getRandomValues(new Uint8Array(step))
    for (const byte of bytes) {
      const idx = byte & mask
      if (idx < alphabet.length) {
        id += alphabet[idx]
        if (id.length === size) break
      }
    }
  }
  return id
}

const URL_SAFE = 'useandom-26T198340PX75pxJACKVERYMINDBUSHWOLF_GQZbfghjklqvwyzrict'
generateNanoid(URL_SAFE, 21)  // → "V1StGXR8_Z5jdHi6B-myT"

Python

# pip install nanoid
from nanoid import generate

generate()              # → "V1StGXR8_Z5jdHi6B-myT"
generate(size=8)        # → "Uakgb_J5"
generate('0123456789abcdef', 16)  # custom alphabet + size

Node.js (CommonJS)

// Node.js — stdlib only, no npm needed
const { randomFillSync } = require('crypto')

function nanoid(alphabet, size) {
  const mask = (2 << (31 - Math.clz32((alphabet.length - 1) | 1))) - 1
  const step = Math.ceil((1.6 * mask * size) / alphabet.length)
  let id = ''
  while (id.length < size) {
    const bytes = randomFillSync(Buffer.alloc(step))
    for (const byte of bytes) {
      const idx = byte & mask
      if (idx < alphabet.length) { id += alphabet[idx]; if (id.length === size) break }
    }
  }
  return id
}

Perguntas Frequentes