arcticicestudio/icecore-hashids

A lightweight generator for short, unique, non-sequential and decodable Hashids from non-negative numbers.

Implementation of the Hashids algorithm.

Hashids are obfuscated unique hashes of non-negative (long) integer numbers, but in contrast to cryptographic one-way hash algorithms they are can be decoded again. The algorithm can be used to either generate a hash from a single number or bundling several numbers into one to be stored as simple short UIDs. This design allows to use them for many use-cases like

URL shortening
database ID protection
shard numbers storage
invitation-, authorization- and gift codes
complex- or clustered system parameters

Numbers like 347 are converted into strings like yr8, or an array of numbers like [27, 986] into 3kTMd.

Features

The algorithm provides the following features:

Generation of short, unique, case-sensitive and non-sequential decodable hashes of natural numbers
Additional entropy through salt usage
Configurable minimum hash length and alphabet
Combining of several numbers to one hash
Deterministic hash computation given the same input and parametrization/instance configuration
Prevention of curse words through separator characters

In addition, the library provides features to

pass 0x or 0X prefixed hexadecimal numbers to the public API methods
handle exceptions instead of returning empty values when invalid parameters are passed to any public API method
disable the maximum number size limit which ensures the interoperability with the algorithm reference implementation and allows the usage of the Java Long maximum value

Please note that most features will break the interoperability with the algorithm reference implementation!

Getting Started

The project documentation contains chapters to learn about the installation and requirements, get an overview of the API and learn how to use it, and build the project and running the tests.

Contributing

Read the contributing guide to learn about the development process and how to propose enhancement suggestions and report bugs, how to submit pull requests and the project's styleguides, branch organization and versioning model.

The guide also includes information about minimal, complete, and verifiable examples and other ways to contribute to the project like improving existing issues and giving feedback on issues and pull requests.