encoded_id_cr

A Crystal port of the encoded_id Ruby gem. Encode integer IDs (or hex strings like UUIDs) into short, obfuscated, reversible strings suitable for URLs.

The internal Sqids and Hashids encoders are byte-for-byte compatible with the Ruby gem's optimised implementations — IDs encoded by the Ruby version round-trip cleanly through this port and vice versa.

What's ported

Installation

Add the dependency to your shard.yml:

dependencies:
  encoded_id_cr:
    github: stevegeek/encoded_id_cr

Then run shards install. The shard is encoded_id_cr; the module it defines is EncodedId.

Library usage

require "encoded_id_cr"

# Sqids (default — no salt required)
id = EncodedId::ReversibleId.sqids
id.encode(123)                          # => "37vq-3u7t"
id.decode("37vq-3u7t")                  # => [123_i64]
id.encode([123_i64, 456_i64, 789_i64])  # => humanised "qa1u-2mqv-b…"

# Hashids (salt required)
hid = EncodedId::ReversibleId.hashid(salt: "foo")
hid.encode(12345)                       # => "9da2-a7an"
hid.decode("9da2-a7an")                 # => [12345_i64]

# Hex (UUIDs etc.)
id.encode_hex("550e8400e29b41d4a716446655440000")
id.decode_hex(encoded)                  # => ["550e8400e29b41d4a716446655440000"]

# Tolerant decoding (case-insensitive, separator-agnostic)
id.decode("37VQ3U7T", downcase: true)   # => [123_i64]
id.decode("37vq3u7t")                   # => [123_i64]

# Customise
EncodedId::ReversibleId.sqids(
  alphabet: EncodedId::Alphabet.alphanum,
  min_length: 12,
  split_at: 6,
  split_with: "_",
  max_inputs_per_id: 16,
  max_length: 64,
)

decode returns [] for a string it does not recognise. It raises EncodedIdFormatError for input longer than max_length, or for Hashids input with characters outside the alphabet.

encode raises InvalidInputError (empty, negative or too many inputs), EncodedIdLengthError (result longer than max_length) or BlocklistError (Hashids output contains a blocklisted word).

CLI

A cr_encoded_id binary is built via shards build:

shards build cr_encoded_id
# => bin/cr_encoded_id

With Crystal installed through asdf 0.18, the build cannot find the embedded libgc. Prefix the command with CRYSTAL_LIBRARY_PATH=$(asdf where crystal)/embedded/lib. script/cr applies the same workaround to one-off crystal calls.

Then:

The encoder is chosen based on whether you pass --salt: with a salt it's Hashids, without it's Sqids. Override with --encoder=sqids or --encoder=hashid.

Development

script/cr spec      # run the specs
script/cr build src/encoded_id_cr.cr -o /tmp/check    # type-check the library
shards build cr_encoded_id   # rebuild the CLI

script/cr is a thin wrapper around crystal. When Crystal comes from asdf, it adds the install's embedded libgc to CRYSTAL_LIBRARY_PATH for asdf 0.18 compatibility; otherwise it runs crystal unchanged.

Compatibility note

The Sqids/Hashids byte-compatibility is verified against published fixtures from the Ruby gem's test suite — e.g. Hashid.new(salt, 0).encode([12345]) == "NkK9", Sqids.new(8, modified_crockford).encode([123]) == "37vq3u7t". See spec/encoders/*_spec.cr for the full list.