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 tiny Node.js JavaScript class to generate YouTube-like hashes from one or many ids.

Contents

• README.md - documentation and examples
• LICENSE
• package.json
• index.js
• src/
  • hashids.coffee - hashids class written in CoffeeScript
• lib/
  • hashids.js - compiled hashids in JavaScript

What's it for?

Generating unique hashes is beneficial when you do not want to expose your database ids in the URL. It's even more helpful when you do not have to look up in the database what record belongs to what hash.

Instead of storing these hashes in the database and selecting by them, you could encode primary ids and select by those - which is faster. Providing a unique salt value to the constructor will make your hashes unique also.

Hashes look similar to what YouTube, Bitly, and other popular websites have: p9, pZsCB, qKuBQuxc. They are case-sensitive, include alphanumeric characters and a dash.

What's different?

With this class you could encode several ids into one hash. If you have several objects to keep track of, you could use for example userId, univesityId and classId -- passing all three ids at the same time and getting back one hash.

There is no limit to how many ids you can encode into one hash. The more ids you provide and the bigger the numbers, the longer your hash will be.

Installation

1. Get Node.js if you haven't already: http://nodejs.org/#download

2. Install npm (package manager for Node).

3. Install hashids:

   npm install -g hashids

Sample Usage

All integers are expected to be positive.

Encoding:

To encode a single number:

	var hashids = require('hashids');
	var hashids = new hashids('this is my salt');
	
	var hash = hashids.encode(12345);

var hash is now going to be:

7OR

To encode multiple numbers into one hash:

	var hashids = require('hashids');
	var hashids = new hashids('this is my salt');
	
	var hash = hashids.encode(683, 94108, 123, 5);

var hash is now going to be:

nEfOM6s2oIz

Decoding:

Hash decoding is done using the same salt value that you have used during encoding:

	var hashids = require('hashids');
	var hashids = new hashids('this is my salt');
	
	var hash1 = hashids.decode('7OR');
	console.log(hash1);
	
	var hash2 = hashids.decode('nEFOM6s7wI6');
	console.log(hash2);

Output will be:

	[ 12345 ]
	[ 683, 94108, 762, 4 ]

Security

The primary purpose of this hash function is to make ids look different. It's not meant or tested to be used primarily as a security algorithm.

Having said that, this class does try to make these hashes un-guessable and unique.

Let's for example look at the following code:

	var hashids = require('hashids');
	var hashids = new hashids('this is my salt');
	
	var hash = hashids.encode(5, 5, 5, 5);

var hash will be:

jie1ws6

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

Same with incremented numbers:

	var hashids = require('hashids');
	var hashids = new hashids('this is my salt');
	
	var hash = hashids.encode(1, 2, 3, 4, 5, 6, 7, 8, 9, 10);

var hash will be :

6utsaI616snh0SdFthj

Bonus

Since these hashes are most likely to be used in user-visible places, like the url -- no matter the salt value, they will not make up basic curse words by design, like the f-bomb or "#2".