Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/splattael/hashids.cr
A Crystal shard to generate YouTube-like hashes from one or many numbers. Use hashids when you do not want to expose your database ids to the user.
https://github.com/splattael/hashids.cr
alphabet decoding encoding hashids salt shard
Last synced: about 2 months ago
JSON representation
A Crystal shard to generate YouTube-like hashes from one or many numbers. Use hashids when you do not want to expose your database ids to the user.
- Host: GitHub
- URL: https://github.com/splattael/hashids.cr
- Owner: splattael
- License: mit
- Created: 2016-07-27T14:14:28.000Z (about 8 years ago)
- Default Branch: master
- Last Pushed: 2020-05-24T14:55:05.000Z (over 4 years ago)
- Last Synced: 2024-06-21T18:10:57.444Z (3 months ago)
- Topics: alphabet, decoding, encoding, hashids, salt, shard
- Language: Crystal
- Homepage: https://www.hashids.org/crystal/
- Size: 30.3 KB
- Stars: 52
- Watchers: 4
- Forks: 7
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
- awesome-crystal - hashids.cr - A library to generate YouTube-like ids from one or many numbers (Data Generators)
- awesome-crystal - hashids.cr - A library to generate YouTube-like ids from one or many numbers (Data Generators)
- awesome-crystal - hashids.cr - A library to generate YouTube-like ids from one or many numbers (Data Generators)
README
# Hashids
[![Build Status](https://travis-ci.org/splattael/hashids.cr.svg)](https://travis-ci.org/splattael/hashids.cr)
[![Shard version](https://img.shields.io/badge/hashids.cr-v0.3.0-orange.svg)](https://crystalshards.xyz/?filter=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](https://github.com/peterhellberg/hashids.rb).
The tests were adopted from the original [JavaScript implementation](https://github.com/ivanakimov/hashids.js).## Installation
Add this to your application's `shard.yml`:
```yaml
dependencies:
hashids:
github: splattael/hashids.cr
version: 0.3.0
```## Usage
```crystal
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.```crystal
hashids = Hashids.new(salt: "this is my salt")
hash = hashids.encode([12345]) # => NkK9
```### Decoding
Notice during decoding, same salt value is used:
```crystal
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:
```crystal
hashids = Hashids.new(salt: "this is my pepper")
numbers = hashids.decode("NkK9") # => []
```### Encoding several numbers
```crystal
hashids = Hashids.new(salt: "this is my salt")
hash = hashids.encode([683, 94108, 123, 5]) # => aBMswoO2UB3Sj
```### Decoding is done the same way
```crystal
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).```crystal
hashids = Hashids.new(salt: "this is my salt", min_length: 8)
hash = hashids.encode([1]) # => gB0NV05e
```### Decoding with minimum hash length
```crystal
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"
```crystal
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:
```crystal
hashids = Hashids.new(salt: "this is my salt")
hash = hashids.encode([5, 5, 5, 5]) # => 1Wc8cwcE
```Same with incremented numbers:
```crystal
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:
```crystal
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
```crystal
hashids = Hashids.new(salt: "this is my salt")
hash = hashids.encode_hex("DEADBEEF") # => kRNrpKlJ
```### Decoding to a HEX string
```crystal
hashids = Hashids.new(salt: "this is my salt")
hex_str = hashids.decode_hex("kRNrpKlJ") # => "deadbeef"
```## Development
```shell
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](https://github.com/splattael) Peter Leitzen - creator, maintainer
- [veelenga](https://github.com/veelenga) V. Elenhaupt - contributor
- [bdtomlin](https://github.com/bdtomlin) Bryan Tomlin - contributor