Skip to content

About

Hashids algorithm v1.0.0 implementation in Java

Resources

Stars

0 stars

Watchers

0 watching

Forks

 
 

Repository files navigation

Hashids.ts Stories in Ready CircleCI

A small TypeScript class to generate YouTube-like hashes from one or many numbers.

Ported from javascript hashids.js by Ivan Akimov

What is it?

hashids (Hash ID's) creates short, unique, decodable 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 decodable.
  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 encode + decode on the fly.

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

Usage

Add the dependency

hashids is available on npm. Add it to your project with:

npm install hashids

Or, with yarn:

yarn add hashids

Import the package

import { Hashids } from 'hashids';

A note on bigint

Numbers are bigint, not number. The original Java implementation's numeric type is long, and the API is contractually required to reject 9007199254740993 — a value a JavaScript number cannot even represent. Write integer literals with the n suffix: 12345n.

Encoding 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.

const hashids = new Hashids('this is my salt');
const hash = hashids.encode(12345n);

hash is now going to be:

NkK9

Decoding

Notice during decoding, same salt value is used:

const hashids = new Hashids('this is my salt');
const numbers = hashids.decode('NkK9');

numbers is now going to be:

[ 12345n ]

Decoding with different salt

Decoding will not work if salt is changed:

const hashids = new Hashids('this is my pepper');
const numbers = hashids.decode('NkK9');

numbers is now going to be:

[]

Encoding several numbers

const hashids = new Hashids('this is my salt');
const hash = hashids.encode(683n, 94108n, 123n, 5n);

hash is now going to be:

aBMswoO2UB3Sj

The numbers may also be passed as a single array, which is what the original's long... varargs allow and what you need for large batches:

const hash = hashids.encode([683n, 94108n, 123n, 5n]);

Decoding is done the same way

const hashids = new Hashids('this is my salt');
const numbers = hashids.decode('aBMswoO2UB3Sj');

numbers is now going to be:

[ 683n, 94108n, 123n, 5n ]

Encoding and specifying minimum hash length

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

const hashids = new Hashids('this is my salt', 8);
const hash = hashids.encode(1n);

hash is now going to be:

gB0NV05e

Decoding

const hashids = new Hashids('this is my salt', 8);
const numbers = hashids.decode('gB0NV05e');

numbers is now going to be:

[ 1n ]

Specifying custom hash alphabet

Here we set the alphabet to consist of only six letters: "0123456789abcdef"

const hashids = new Hashids('this is my salt', 0, '0123456789abcdef');
const hash = hashids.encode(1234567n);

hash is now going to be:

b332db5

Encoding and decoding "MongoDB" ids

In addition to encoding and decoding numeric values Hashids provides functionality for encoding and decoding ids in a hex notation such as object ids generated by MongoDB.

const hashids = new Hashids('This is my salt');
const hash = hashids.encodeHex('507f1f77bcf86cd799439011'); // goMYDnAezwurPKWKKxL2
const objectId = hashids.decodeHex(hash); // 507f1f77bcf86cd799439011

Note that the algorithm used for encoding and decoding hex values is not compatible with the algorthm for encoding and decoding numeric values. That means that you cannot use decodeHex to extract a hex representation of an id that was encoded with encode.

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

const hashids = new Hashids('this is my salt');
const hash = hashids.encode(5n, 5n, 5n, 5n);

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

1Wc8cwcE

Same with incremented numbers:

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

hash will be :

kRHnurhptKcjIDTWC3sx

Incrementing number hashes:

const hashids = new Hashids('this is my salt');
const hash1 = hashids.encode(1n); /* NV */
const hash2 = hashids.encode(2n); /* 6m */
const hash3 = hashids.encode(3n); /* yD */
const hash4 = hashids.encode(4n); /* 2l */
const hash5 = hashids.encode(5n); /* rD */

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

Limitations

The original and reference implementation is the JS (Hashids Website) version. JS number limitation is (2^53 - 1). Our implementation uses bigint, but is limited to the same limits JS is, for the sake of compatibility. If a bigger number is provided, an IllegalArgumentException will be thrown.

Development

npm install
npm run build       # tsc, strictest settings
npm run typecheck   # tsc --noEmit over src and test
npm run lint        # eslint, type-checked rules
npm test            # vitest
npm run verify      # lint + typecheck + tests with coverage

Contributors

Contact

Follow me C.C.(@fanweixiao), @IvanAkimov, @0x3333.

License

MIT License. See the LICENSE file.

About

Hashids algorithm v1.0.0 implementation in Java

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages