A small TypeScript class to generate YouTube-like hashes from one or many numbers.
Ported from javascript hashids.js by Ivan Akimov
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:
- Hashes must be unique and decodable.
- They should be able to contain more than one integer (so you can use them in complex or clustered systems).
- You should be able to specify minimum hash length.
- 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.
hashids is available on npm. Add it to your project with:
npm install hashids
Or, with yarn:
yarn add hashids
import { Hashids } from 'hashids';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.
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
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 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:
[]
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]);const hashids = new Hashids('this is my salt');
const numbers = hashids.decode('aBMswoO2UB3Sj');numbers is now going to be:
[ 683n, 94108n, 123n, 5n ]
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
const hashids = new Hashids('this is my salt', 8);
const numbers = hashids.decode('gB0NV05e');numbers is now going to be:
[ 1n ]
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
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); // 507f1f77bcf86cd799439011Note 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.
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:
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
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 */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
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.
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
Follow me C.C.(@fanweixiao), @IvanAkimov, @0x3333.
MIT License. See the LICENSE file.
