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

======

Full Documentation

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. Read full documentation at: http://www.hashids.org/node-js/

Installation

1. Node it up: http://nodejs.org/download/

2. Install using npm:

   npm install -g hashids

Production Note

BE CAREFUL WHICH VERSION OF HASHIDS YOU ARE USING. Since future improvements to Hashids might alter produced hashes, it's a good idea to specify exact Hashids version in your package.json, if their consistency is important to you (if you are storing them in database):

	
	"dependencies": {
		"hashids": "0.3.0"
	}

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:

NkK9

Decrypting

Notice during decryption, same salt value is used:

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

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

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("NkK9");

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:

aBMswoO2UB3Sj

You can also pass an array:

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

Decrypting is done the same way

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

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

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:

gB0NV05e

Decrypting

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

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

numbers is now going to be:

[ 1 ]

Specifying custom hash alphabet

Here we set the alphabet to consist of valid hex characters: "0123456789abcdef"

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

var hash = hashids.encrypt(1234567);

hash is now going to be:

b332db5

MongoDB Support

MongoDB uses hex strings for their ObjectIds. You can convert them to Hashids like this:

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

var hash = hashids.encryptHex("507f191e810c19729de860ea");
var objectId = hashids.decryptHex(hash);

hash will be:

yNyaoWeKWVINWqvaM9bw

objectId will be as expected:

507f191e810c19729de860ea

The length of the hex string does not matter -- it does not have to be a MongoDB ObjectId.

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:

1Wc8cwcE

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 :

kRHnurhptKcjIDTWC3sx

Incrementing number hashes:

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

var hash1 = hashids.encrypt(1), /* NV */
	hash2 = hashids.encrypt(2), /* 6m */
	hash3 = hashids.encrypt(3), /* yD */
	hash4 = hashids.encrypt(4), /* 2l */
	hash5 = hashids.encrypt(5); /* rD */

Curses! #$%@

This code was written with the intent of placing created hashes in visible places - like the URL. Which makes it unfortunate if generated hashes accidentally formed a bad word.

Therefore, the algorithm tries to avoid generating most common English curse words. 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.3.0 - Current Stable

PRODUCED HASHES IN THIS VERSION ARE DIFFERENT THAN IN 0.1.4, DO NOT UPDATE IF YOU NEED THEM TO KEEP WORKING:

• Same algorithm as PHP version now
• Overall approximately 4x faster
• Consistent shuffle function uses slightly modified version of Fisher–Yates algorithm
• Generate large hash strings faster (where minHashLength is more than 1000 chars)
• When using minHashLength, hash character disorder has been improved
• Basic English curse words will now be avoided even with custom alphabet
• New unit tests with Jasmine
• Support for MongoDB ObjectId
• encrypt function now also accepts array of integers as input
• Passing JSLint now

0.1.4

• 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. You can use Hashids in open source projects and commercial products. Don't break the Internet. Kthxbye.