Hashids

A small Crystal shard to generate YouTube-like ids from one or many numbers. Use hashids when you do not want to expose your database ids to the user.

https://hashids.org/crystal/

What is it?

hashids (Hash IDs) creates short, unique, decodable hashes from unsigned integers.

See https://hashids.org for more information.

The is a port of Ruby's implementation. The tests were adopted from the original JavaScript implementation.

Installation

Add this to your application's shard.yml:

dependencies:
  hashids:
    github: splattael/hashids.cr
    version: 0.3.0

Usage

require "hashids"

hashids = Hashids.new
hashids.encode([1]) # => "jR"

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(salt: "this is my salt")
hash = hashids.encode([12345]) # => NkK9

Decoding

Notice during decoding, same salt value is used:

hashids = Hashids.new(salt: "this is my salt")
numbers = hashids.decode("NkK9") # => [12345]

Decoding with different salt

Decoding will not work if salt is changed:

hashids = Hashids.new(salt: "this is my pepper")
numbers = hashids.decode("NkK9") # => []

Encoding several numbers

hashids = Hashids.new(salt: "this is my salt")
hash = hashids.encode([683, 94108, 123, 5]) # => aBMswoO2UB3Sj

Decoding is done the same way

hashids = Hashids.new(salt: "this is my salt")
numbers = hashids.decode("aBMswoO2UB3Sj") # => [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(salt: "this is my salt", min_length: 8)
hash = hashids.encode([1]) # => gB0NV05e

Decoding with minimum hash length

hashids = Hashids.new(salt: "this is my salt", min_length: 8)
numbers = hashids.decode("gB0NV05e") # => [1]

Specifying custom hash alphabet

Here we set the alphabet to consist of: "abcdefghijkABCDEFGHIJK12345"

hashids = Hashids.new(salt: "this is my salt", alphabet: "abcdefghijkABCDEFGHIJK12345")
hash = hashids.encode([1, 2, 3, 4, 5]) # => dEc4iEHeF3

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

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

hashids = Hashids.new(salt: "this is my salt")
hash = hashids.encode([5, 5, 5, 5]) # => 1Wc8cwcE

Same with incremented numbers:

hashids = Hashids.new(salt: "this is my salt")
hash = hashids.encode([1, 2, 3, 4, 5, 6, 7, 8, 9, 10]) # => kRHnurhptKcjIDTWC3sx

Incrementing number ids:

hashids = Hashids.new(salt: "this is my salt")

hashids.encode([1]) #=> NV
hashids.encode([2]) #=> 6m
hashids.encode([3]) #=> yD
hashids.encode([4]) #=> 2l
hashids.encode([5]) #=> rD

Encoding using a HEX string

hashids = Hashids.new(salt: "this is my salt")
hash = hashids.encode_hex("DEADBEEF") # => kRNrpKlJ

Decoding to a HEX string

hashids = Hashids.new(salt: "this is my salt")
hex_str = hashids.decode_hex("kRNrpKlJ") # => "deadbeef"

Development

make spec

Contributing

1. Fork it ( https://github.com/splattael/hashids/fork )
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Release

• Make sure make spec is green
• Commit all changes
• Bump version in src/hashids/version.cr
• Adjust version in README.md and shard.yml
• Add entries in CHANGELOG.md
• make release

Contributors

• splattael Peter Leitzen - creator, maintainer
• veelenga V. Elenhaupt - contributor
• bdtomlin Bryan Tomlin - contributor