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/

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.

Add this to your application's shard.yml:

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

require "hashids"

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

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

Notice during decoding, same salt value is used:

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

Decoding will not work if salt is changed:

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

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

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

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

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

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

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:

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

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

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

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

make spec

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

• 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

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