hashids

What is hashids?

The hashids npm package is a small JavaScript library that generates short, unique, non-sequential ids from numbers. It is useful for creating URL-friendly ids, obfuscating database ids, and more.

What are hashids's main functionalities?

Encoding Numbers

This feature allows you to encode a single number into a unique, short string. This is useful for creating URL-friendly ids.

const Hashids = require('hashids/cjs');
const hashids = new Hashids();
const id = hashids.encode(12345);
console.log(id); // e.g., 'NkK9'

Decoding Numbers

This feature allows you to decode a previously encoded string back into the original number. This is useful for retrieving the original id from a URL-friendly id.

const Hashids = require('hashids/cjs');
const hashids = new Hashids();
const numbers = hashids.decode('NkK9');
console.log(numbers); // [12345]

Encoding Multiple Numbers

This feature allows you to encode multiple numbers into a single unique string. This can be useful for combining multiple ids into one.

const Hashids = require('hashids/cjs');
const hashids = new Hashids();
const id = hashids.encode(1, 2, 3);
console.log(id); // e.g., 'laHquq'

Decoding Multiple Numbers

This feature allows you to decode a previously encoded string back into the original set of numbers. This is useful for retrieving multiple ids from a single URL-friendly id.

const Hashids = require('hashids/cjs');
const hashids = new Hashids();
const numbers = hashids.decode('laHquq');
console.log(numbers); // [1, 2, 3]

Custom Alphabet

This feature allows you to specify a custom alphabet for encoding. This can be useful for ensuring that the generated ids meet specific requirements or constraints.

const Hashids = require('hashids/cjs');
const hashids = new Hashids('', 0, 'abcdefghijklmnopqrstuvwxyz');
const id = hashids.encode(12345);
console.log(id); // e.g., 'dplb'

Other packages similar to hashids

shortid

The shortid package generates short, unique, non-sequential ids. It is similar to hashids in that it creates URL-friendly ids, but it does not provide the ability to encode and decode numbers.

nanoid

The nanoid package is a tiny, secure, URL-friendly, unique string ID generator. It is similar to hashids in that it creates short, unique ids, but it focuses on security and performance rather than encoding and decoding numbers.

uuid

The uuid package generates RFC-compliant UUIDs (Universally Unique Identifiers). It is different from hashids in that it generates longer, globally unique ids, and does not provide the ability to encode and decode numbers.

README

hashids

A small Node.js class to generate YouTube-like hashes from one or many numbers. Use hashids when you do not want to expose your database ids to the user.

http://www.hashids.org/node-js/

What is it?

hashids (Hash ID's) creates short, unique, decryptable hashes from unsigned integers.

It was designed for websites to use in URL shortening, tracking stuff, or making pages private (or at least unguessable).

This algorithm tries to satisfy the following requirements:

1. Hashes must be unique and decryptable.
2. They should be able to contain more than one integer (so you can use them in complex or clustered systems).
3. You should be able to specify minimum hash length.
4. Hashes should not contain basic English curse words (since they are meant to appear in public places - like the URL).

Instead of showing items as 1, 2, or 3, you could show them as U6dc, u87U, and HMou. You don't have to store these hashes in the database, but can encrypt + decrypt on the fly.

All integers need to be greater than or equal to zero.

Installation

1. Grab Node.js and install if you haven't already: http://nodejs.org/download/

2. Install using npm:

   npm install hashids

Usage

Encrypting one number

You can pass a unique salt value so your hashes differ from everyone else's. I use "this is my salt" as an example.

var Hashids = require("hashids"),
	hashids = new Hashids("this is my salt");

var hash = hashids.encrypt(12345);

hash is now going to be:

ryBo

Decrypting

Notice during decryption, same salt value is used:

var Hashids = require("hashids"),
	hashids = new Hashids("this is my salt");

var numbers = hashids.decrypt("ryBo");

numbers is now going to be:

[ 12345 ]

Decrypting with different salt

Decryption will not work if salt is changed:

var Hashids = require("hashids"),
	hashids = new Hashids("this is my pepper");

var numbers = hashids.decrypt("ryBo");

numbers is now going to be:

[]

Encrypting several numbers

var Hashids = require("hashids"),
	hashids = new Hashids("this is my salt");

var hash = hashids.encrypt(683, 94108, 123, 5);

hash is now going to be:

zBphL54nuMyu5

Decrypting is done the same way

var Hashids = require("hashids"),
	hashids = new Hashids("this is my salt");

var numbers = hashids.decrypt("zBphL54nuMyu5");

numbers is now going to be:

[ 683, 94108, 123, 5 ]

Encrypting and specifying minimum hash length

Here we encrypt integer 1, and set the minimum hash length to 8 (by default it's 0 -- meaning hashes will be the shortest possible length).

var Hashids = require("hashids"),
	hashids = new Hashids("this is my salt", 8);

var hash = hashids.encrypt(1);

hash is now going to be:

b9iLXiAa

Decrypting

var Hashids = require("hashids"),
	hashids = new Hashids("this is my salt", 8);

var numbers = hashids.decrypt("b9iLXiAa");

numbers is now going to be:

[ 1 ]

Specifying custom hash alphabet

Here we set the alphabet to consist of only four letters: "abcd"

var Hashids = require("hashids"),
	hashids = new Hashids("this is my salt", 0, "abcd");

var hash = hashids.encrypt(1, 2, 3, 4, 5);

hash is now going to be:

adcdacddcdaacdad

Randomness

The primary purpose of hashids is to obfuscate ids. It's not meant or tested to be used for security purposes or compression. Having said that, this algorithm does try to make these hashes unguessable and unpredictable:

Repeating numbers

var Hashids = require("hashids"),
	hashids = new Hashids("this is my salt");

var hash = hashids.encrypt(5, 5, 5, 5);

You don't see any repeating patterns that might show there's 4 identical numbers in the hash:

GLh5SMs9

Same with incremented numbers:

var Hashids = require("hashids"),
	hashids = new Hashids("this is my salt");

var hash = hashids.encrypt(1, 2, 3, 4, 5, 6, 7, 8, 9, 10);

hash will be :

zEUzfySGIpuyhpF6HaC7

Incrementing number hashes:

var Hashids = require("hashids"),
	hashids = new Hashids("this is my salt");

var hash1 = hashids.encrypt(1), /* LX */
	hash2 = hashids.encrypt(2), /* ed */
	hash3 = hashids.encrypt(3), /* o9 */
	hash4 = hashids.encrypt(4), /* 4n */
	hash5 = hashids.encrypt(5); /* a5 */

Speed

Even though speed is an important factor of every hashing algorithm, primary goal here was encoding several numbers at once and making the hash unique and random.

With Node 0.8.8, on a 2.7 GHz Intel Core i7 with 16GB of RAM, it takes roughly 0.08 seconds to:

1. Encrypt 1000 hashes consisting of 1 integer hashids.encrypt(12);
2. And decrypt these 1000 hashes back into integers hashids.decrypt(hash); while ensuring they are valid

If we do the same with 3 integers, for example: hashids.encrypt(10, 11, 12); -- the number jumps up to 0.13 seconds on the same machine.

Sidenote: The numbers tested with were relatively small -- if you increase them, the speed will obviously decrease.

What you could do to speed it up

Usually people either encrypt or decrypt one hash per request, so the algorithm should already be fast enough for that. However, there are still several things you could do:

1. If you are generating a lot of hashes at once, wrap this class in your own so you can cache hashes.
2. Use MongoDB or Redis.
3. You could also decrease the length of your alphabet. Your hashes will become longer, but calculating them will be faster.

Bad hashes

I wrote this class with the intent of placing these hashes in visible places - like the URL. If I create a unique hash for each user, it would be unfortunate if the hash ended up accidentally being a bad word. Imagine auto-creating a URL with hash for your user that looks like this - http://example.com/user/a**hole

Therefore, this algorithm tries to avoid generating most common English curse words with the default alphabet. This is done by never placing the following letters next to each other:

c, C, s, S, f, F, h, H, u, U, i, I, t, T

Changelog

0.1.4 - Current Stable

• Global var leak for hashSplit (thanks to @BryanDonovan)
• Class capitalization (thanks to @BryanDonovan)

0.1.3

Warning: If you are using 0.1.2 or below, updating to this version will change your hashes.

• Updated default alphabet (thanks to @speps)
• Constructor removes duplicate characters for default alphabet as well (thanks to @speps)

0.1.2

Warning: If you are using 0.1.1 or below, updating to this version will change your hashes.

• Minimum hash length can now be specified
• Added more randomness to hashes
• Added unit tests
• Added example files
• Changed warnings that can be thrown
• Renamed encode/decode to encrypt/decrypt
• Consistent shuffle does not depend on md5 anymore
• Speed improvements

0.1.1

• Speed improvements
• Bug fixes

0.1.0

• First commit

Contact

Follow me @IvanAkimov

Or http://ivanakimov.com

License

MIT License. See the LICENSE file.