• Stars
    star
    1,022
  • Rank 45,039 (Top 0.9 %)
  • Language
    Java
  • License
    MIT License
  • Created over 10 years ago
  • Updated about 1 year ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Hashids algorithm v1.0.0 implementation in Java

Hashids.java Version Stories in Ready CircleCI

A small Java 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 (long) 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 (long) integers need to be greater than or equal to zero.

Usage

Add the dependency

hashids is available in Maven Central. If you are using Maven, add the following dependency to your pom.xml's dependencies:

<dependency>
  <groupId>org.hashids</groupId>
  <artifactId>hashids</artifactId>
  <version>1.0.3</version>
</dependency>

Alternatively, if you use gradle or are on android, add the following to your app's build.gradle file under dependencies:

compile 'org.hashids:hashids:1.0.3'

Import the package

import org.hashids;

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.

Hashids hashids = new Hashids("this is my salt");
String hash = hashids.encode(12345L);

hash is now going to be:

NkK9

Decoding

Notice during decoding, same salt value is used:

Hashids hashids = new Hashids("this is my salt");
long[] numbers = hashids.decode("NkK9");

numbers is now going to be:

[ 12345 ]

Decoding with different salt

Decoding will not work if salt is changed:

Hashids hashids = new Hashids("this is my pepper");
long[] numbers = hashids.decode("NkK9");

numbers is now going to be:

[]

Encoding several numbers

Hashids hashids = new Hashids("this is my salt");
String hash = hashids.encode(683L, 94108L, 123L, 5L);

hash is now going to be:

aBMswoO2UB3Sj

Decoding is done the same way

Hashids hashids = new Hashids("this is my salt");
long[] numbers = hashids.decode("aBMswoO2UB3Sj");

numbers is now going to be:

[ 683, 94108, 123, 5 ]

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

Hashids hashids = new Hashids("this is my salt", 8);
String hash = hashids.encode(1L);

hash is now going to be:

gB0NV05e

Decoding

Hashids hashids = new Hashids("this is my salt", 8);
long[] numbers = hashids.decode("gB0NV05e");

numbers is now going to be:

[ 1 ]

Specifying custom hash alphabet

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

Hashids hashids = new Hashids("this is my salt", 0, "0123456789abcdef");
String hash = hashids.encode(1234567L);

hash is now going to be:

b332db5

Encoding and decoding "MongoDB" ids

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

Hashids hashids = new Hashids("This is my salt");
String hash = hashids.encodeHex("507f1f77bcf86cd799439011"); // goMYDnAezwurPKWKKxL2
String 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 long values. That means that you cannot use decodeHex to extract a hex representation of a long 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

Hashids hashids = new Hashids("this is my salt");
String hash = hashids.encode(5L, 5L, 5L, 5L);

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

1Wc8cwcE

Same with incremented numbers:

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

hash will be :

kRHnurhptKcjIDTWC3sx

Incrementing number hashes:

Hashids hashids = new Hashids("this is my salt");
String hash1 = hashids.encode(1L); /* NV */
String hash2 = hashids.encode(2L); /* 6m */
String hash3 = hashids.encode(3L); /* yD */
String hash4 = hashids.encode(4L); /* 2l */
String hash5 = hashids.encode(5L); /* 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 java implementation uses Long, 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.

Contributors

Contact

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

License

MIT License. See the LICENSE file.

More Repositories

1

yomo

🦖 Stateful Serverless Framework for Geo-distributed Edge AI Infra. with function calling support, write once, run on any model.
Go
1,645
star
2

react-cursor-chat

<CursorChat /> React Component helps bring Figma's Cursor Chat to your web applications in less than 3 minutes, making real-time collaboration anywhere.
TypeScript
132
star
3

yomo-wasmedge-tensorflow

This application demonstrates how to launch high-performance "serverless" functions from the YoMo framework to process streaming data. The functions are embedded in a WebAssembly VM, WasmEdge, for safety, security, portability, and manageability.
Go
63
star
4

metaverse-workplace-vercel-frontend

Open-source Metaverse Workplace (Virtual Office) with YoMo, Macrometa, Agora.io, Next.js and other Geo-distributed System Tech Stacks.
TypeScript
50
star
5

y3-codec-golang

Golang implementation of Y3 Codec, a fast than real-time TLV based binary codec with low CPU usage
Go
46
star
6

yomo-vhq-backend

An Open-source Virtual HQ Presence Server by Geo-Distributed Cloud Architecture.
Go
17
star
7

y3-codec

🧮 a faster than real-time TLV based binary codec with low CPU usage, reveal advantages of next generation networking like 5G
17
star
8

webtransport-polyfill

WebTransport implementation to fallback to WebSocket if browser does not support it
TypeScript
14
star
9

presencejs

Edge Infra for realtime web applications, geo-distributed architecture.
Go
14
star
10

yomo-flow-ssvm-example

SSVM 🙌 YoMo: This example demonstrates writing yomo-flow interop with WebAssembly by SSVM
Go
10
star
11

yomo-source-mqtt-broker-starter

Receive MQTT messages and convert them to the YoMo protocol for transmission to YoMo Streaming Function.
Go
10
star
12

metaverse-workplace-cloudflare-frontend

🏡 Metaverse Workplace with fully Geo-distributed edge architecture
TypeScript
10
star
13

cli

Command-line tools for YoMo.
Go
6
star
14

presence.js.org

MDX
5
star
15

debs-2014

Source code of https://blog.yomo.run/posts/debs2014-grand-challenge-by-yomo
Go
4
star
16

yomo-sink-faunadb-example

FaunaDB 🙌 YoMo: This example demonstrates how to integrate FaunaDB as yomo-sink
Go
4
star
17

yomo-source-mqtt-starter

MQTT-API-Compatible YoMo server, receive MQTT data and transfer data over QUIC, implement real-time IoT analytics by YoMo
Go
4
star
18

yomo-sink-redpanda-example

Connect to Redpanda with Yomo
Go
4
star
19

yomo-presence-backend

The open-source presence server (WebSocket & WebTransport) for @yomo/presencejs ⚡️ made realtime web applications edge-aware by YoMo
Go
4
star
20

yomo-sink-tdengine-example

TDEngine 🙌 YoMo
Go
3
star
21

y3

Golang implementation of Y3 Codec, a fast than real-time TLV based binary codec with low CPU usage
Go
3
star
22

yomo-docs

YoMo Documentation Website
JavaScript
3
star
23

example-noise

Noise Sensor Case
2
star
24

yomo-cluing-shake

Go
2
star
25

yomo-sink-macrometa-example

Connect to Macrometa.com with YoMo
Go
2
star
26

yomo-grafana-datasource

YoMo + Grafana
TypeScript
2
star
27

webtransport

WebTransport server in Golang
2
star
28

GreptimeDB-YoMo

High-performance data ingestion for GreptimeDB using QUIC by YoMo
Go
2
star
29

y3-playground

JavaScript
1
star
30

yomo-sink-tidb-example

Connect to TiDB with Yomo
Go
1
star
31

yomo-source-noise-example

Serverless of YoMo-Source in Noise example
Go
1
star
32

yomo-sink-socketio-server-example

The example of socket.io for yomo-sink which can be used to show the real-time data on a web page.
Go
1
star