nikolay-govorov/nanoid

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

Nano ID

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

use nanoid::nanoid;

fn main() {
   let id = nanoid!(); //=> "Yo1Tr9F3iF-LFHX9i9GvA"
}

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

Compact. It uses a larger alphabet than UUID (A-Za-z0-9_-) and has a similar number of unique IDs in just 21 symbols instead of 36.

Usage

Install

[dependencies]
nanoid = "0.4.0"

Simple

The main module uses URL-friendly symbols (A-Za-z0-9_-) and returns an ID with 21 characters.

use nanoid::nanoid;

fn main() {
   let id = nanoid!(); //=> "Yo1Tr9F3iF-LFHX9i9GvA"
}

Symbols -,.() are not encoded in the URL. If used at the end of a link they could be identified as a punctuation symbol.

Custom length

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

use nanoid::nanoid;

fn main() {
   let id = nanoid!(10); //=> "IRFa-VaY2b"
}

Custom Alphabet or Length

If you want to change the ID's alphabet or length, you can simply pass the custom alphabet to the nanoid!() macro as the second parameter:

use nanoid::nanoid;

fn main() {
    let alphabet: [char; 16] = [
        '1', '2', '3', '4', '5', '6', '7', '8', '9', '0', 'a', 'b', 'c', 'd', 'e', 'f'
    ];

   let id = nanoid!(10, &alphabet); //=> "4f90d13a42"
}

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

Custom Random Bytes Generator

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

use nanoid::nanoid;

fn random_byte () -> u8 { 0 }

fn main() {
    fn random (size: usize) -> Vec<u8> {
        let mut bytes: Vec<u8> = vec![0; size];

        for i in 0..size {
            bytes[i] = random_byte();
        }

        bytes
    }

    nanoid!(10, &['a', 'b', 'c', 'd', 'e', 'f'], random); //=> "fbaefaadeb"
}

random function must accept the array size and return an vector with random numbers.

If you want to use the same URL-friendly symbols with format, you can get the default alphabet from the url module:

use nanoid::nanoid;

fn random (size: usize) -> Vec<u8> {
    let result: Vec<u8> = vec![0; size];

    result
}

fn main() {
    nanoid!(10, &nanoid::alphabet::SAFE, random); //=> "93ce_Ltuub"
}

Other Programming Languages

• JS
• C#
• Crystal
• Go
• Elixir
• Haskell
• Java
• Nim
• PHP
• Python
• Ruby

nanoid's Issues

nanoid::format silently truncates the dictionary

nanoid::format silently truncates the dictionary it's given as input, to the largest power of 2 that's below dictionary.len() (modulo floating-point imprecision):

• it picks symbols from alphabet as alphabet[byte];
• byte has mask applied with bitwise-and;
• mask is the largest power of two below dictionary.len();
• hence, byte is between 0 and that power of two.

This causes the resulting value to have lower entropy than expected (i.e. lower guarantees on its uniqueness), when the alphabet's size is not a power of two (with the effect being more pronounced as the difference between the size and the next power of two grows smaller).

Note that the default alphabet has size 64 = 2⁶, so callers using it are not affected.

Whether to consider using the Github CI?

Everyone can see the test + bench result more directly

Support Regex as character set

Is it possible to use characters from a Regex?
Typing each and every custom character takes a while.

0.3.0 release

Would you please make another crate release with the recent api changes?

Plans to replace ~ to -

Hi.

The official nanoid uses the characters A-Za-z0-9_-. So, to you have plan use them too?

It would be nice to change the ~ to -, it is more "user friendly" to share the generated IDs as tokens.

Dictionary list

For JS version there is nanoid-dictionary - a set of additional dictionaries. Perhaps we should add them to the Rust version?

API 2.0

Let’s update the library to be compatible with the latest Nano ID 2.0:

• Replace ~ to - in default alphabet
• Add non-secure fast generator
• Async API?

Wrong IDs in the documentation

Hi.

I've noticed the following ID present in the documentation:

Uakgb_J5m9g~0JDMbcJqLJ

however, it is wrong, since it contains 22 characters, but the documentation says ... returns an ID with 21 characters. 🤔

Unique String ?

In your description, you talk about a unique string ID.
But I cannot find any code which guarantees that the string is unique.

Am I misunderstanding the description or am I missing the relevant code?
If there is no guarantee that the string is unique, maybe the word unique in the description should be removed.

Documentation is inconsistent with regards to the default alphabet.

The documentation at https://docs.rs/nanoid/latest/nanoid/ claims that the default alphabet is A-Za-z0-9_~. This is stated several times in the text, and there is a code example which claims it may generate a string with a tilde:

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

use nanoid::nanoid;

fn main() {
   let id = nanoid!(10); //=> "IRFa~VaY2b"
}

However, tilde (~) is not URL-safe.

nanoid::alphabet::SAFE, which the documentation claims is the default alphabet, contains the hyphen in place of the tilde. Presumably this is correct, and the documentation text is wrong.

smartstring feature is non-additve

From the cargo reference:

... features should be additive. That is, enabling a feature should not disable functionality, and it should usually be safe to enable any combination of features. A feature should not introduce a SemVer-incompatible change.

However, the smartstring feature in nanoid doesn't comply with that.

Consider the case where a project has two dependencies that use nanoid. One uses SmartString, the other doesn't. When the full project is built, the smartstring feature will be enabled, and the library that doesn't use smartstring will fail to compile.

Updated deps

Can you please update the dependencies, especially to rand 0.8 and publish an update to crates.io?

Unresolved import `nanoid::nanoid`?

Hi, rust newbie here. I just created a new project to try out nanoid, but it says error[E0432]: unresolved import 'nanoid::nanoid'.

Cargo.toml:

[package]
name = "nanoid_test"
version = "0.1.0"
authors = ["Exr0n <[email protected]>"]
edition = "2018"

# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html

[dependencies]
nanoid = "0.1.3"

src/main.rs:

extern crate nanoid;
use nanoid::nanoid;

fn main() {
    println!("Hello, world!");
}

$ cargo run --verbose:

       Fresh libc v0.2.69
       Fresh rand v0.4.6
       Fresh nanoid v0.1.3
   Compiling nanoid_test v0.1.0 (/Users/exr0n/Desktop/snap/nanoid_test)
     Running `rustc --crate-name nanoid_test --edition=2018 src/main.rs --error-format=json --json=diagnostic-rendered-ansi --crate-type bin --emit=dep-info,link -C debuginfo=2 -C metadata=e6ce498e3c0aac20 -C extra-filename=-e6ce498e3c0aac20 --out-dir /Users/exr0n/Desktop/snap/nanoid_test/target/debug/deps -C incremental=/Users/exr0n/Desktop/snap/nanoid_test/target/debug/incremental -L dependency=/Users/exr0n/Desktop/snap/nanoid_test/target/debug/deps --extern nanoid=/Users/exr0n/Desktop/snap/nanoid_test/target/debug/deps/libnanoid-8c29b7d0393c4491.rlib`
error[E0432]: unresolved import `nanoid::nanoid`
 --> src/main.rs:2:5
  |
2 | use nanoid::nanoid;
  |     ^^^^^^^^^^^^^^ no `nanoid` in the root

error: aborting due to previous error

For more information about this error, try `rustc --explain E0432`.
error: could not compile `nanoid_test`.

Caused by:
  process didn't exit successfully: `rustc --crate-name nanoid_test --edition=2018 src/main.rs --error-format=json --json=diagnostic-rendered-ansi --crate-type bin --emit=dep-info,link -C debuginfo=2 -C metadata=e6ce498e3c0aac20 -C extra-filename=-e6ce498e3c0aac20 --out-dir /Users/exr0n/Desktop/snap/nanoid_test/target/debug/deps -C incremental=/Users/exr0n/Desktop/snap/nanoid_test/target/debug/incremental -L dependency=/Users/exr0n/Desktop/snap/nanoid_test/target/debug/deps --extern nanoid=/Users/exr0n/Desktop/snap/nanoid_test/target/debug/deps/libnanoid-8c29b7d0393c4491.rlib` (exit code: 1)

It seems like rustc knows where to find the nanoid crate, but for some reason can't use it while compiling? I can use other crates like chrono fine, so I have no clue what's going on.