🍃 Breeze ID

Easily generate unique, human-first IDs


> Note: This is a fork of Breeze ID that adds browser compatibility. The original package only worked in Node.js environments. This fork automatically detects the environment and uses the Web Crypto API (crypto.getRandomValues()) in browsers and Web Workers, while maintaining full compatibility with Node.js using crypto.randomBytes(). Works seamlessly in both browser and Node.js environments!

Breeze ID is a library that generates unique IDs of any length meant to be easily communicated via speech, that contain no profanities and consist of unambigous characters that can be read easily. Breeze ID's goal is to eliminate human error and still be cryptographically secure.

Breeze ID is best used wherever your IDs:
- are exposed to end users (for example: public user IDs, error codes... Remember: no profanities!)
- need to be easily communicated via speech
- need to be URL safe
- need to be unique (you can increase the length to improve uniqueness)

But Breeze ID will perform great in any other context too. These are just its strong parts.

Install

``
npm i breezeid
`

Use

$3

`javascript
const { breezeid } = require('breezeid') // or { BreezeID }

// Get ID of default (16) length
breezeid() // => 9NU6-XQLZ-BDIH-6HKE

// Specify custom length (excluding hyphens):
breezeid(8) // => Q228-VQUR
`

$3


Works seamlessly in browsers! The package automatically detects the browser environment and uses the Web Crypto API. You can use it with a bundler (like webpack, rollup, or browserify) or load it directly in a browser with a CommonJS loader (see test.html for an example).

`javascript
const { breezeid } = require('breezeid')

// Works the same way in browsers!
breezeid() // => 9NU6-XQLZ-BDIH-6HKE
breezeid(8) // => Q228-VQUR
`

$3

For humans

Breeze ID uses an alphabet carefully designed to be easily read and said.

Here's an example ID: WQYW-3AWT-X4R2-97KC. (Notice the uppercasing. It's intentional as I find them easier to read and the alphabet was designed with them in mind, but lowercasing the IDs surely makes them look better. Go with whatever you want.)

Breeze ID automatically inserts hyphens every four characters for easier reading.

The characters used are unambigous, meaning they can't be confused between each other. For example, 1 could be confused with I, so 1 is absent from the alphabet.

Breeze ID also blocks profanities by default. It uses an efficient algorithm that at first tries to regenerate the detected profane part of an ID (this succeeds almost every time). However, if it generates another profanity, the profane part is just reversed to omit unecessary calls to the OS. This makes Breeze ID completely profanity free.

Unique

$3

You would need to generate 156 billion IDs with default settings to reach 1% probability of collision. If you were to generate 1000 IDs every hour non-stop, it would take you ~18 thousand years.

But these numbers can still be improved - if you generate Breeze IDs of 24 length, reaching 1% probability of collision while generating 1000 ids per second would take ~5 million years. If you were to care about 50% probability (which is common when testing random ID generating libraries), this would be ~43 million years.

$3


Breeze ID uses cryptographically secure random number generation:
- Node.js: Uses crypto.randomBytes() for entropy from your OS
- Browsers/Web Workers: Uses the Web Crypto API (crypto.getRandomValues()) for cryptographically secure randomness
The characters from the alphabet are then picked by the modulo` operator. There's no modulo bias introduced as the carefully picked alphabet consists of exactly 32 characters.

URL safe

Breeze ID is completely safe to use in URLs. No need for any encoding, it's built in.

Performant

Breeze ID doesn't make unnecessary calls for entropy to your OS every time you generate an ID. Instead, it asks for entropy in big batches only when it needs to.