Add support to encode/decode hex values too

Author: stevegeek

README.md

@@ -8,9 +8,9 @@ The obfuscated strings are reversible, so you can decode them back into the orig
 encoding multiple IDs at once.
 
 ```
-    reversibles = ::EncodedId::ReversibleId.new(salt: my_salt)
-    reversibles.encode([78, 45])  # "7aq6-0zqw"
-    reversibles.decode("7aq6-0zqw")  # [78, 45]
+reversibles = ::EncodedId::ReversibleId.new(salt: my_salt)
+reversibles.encode([78, 45])  # "7aq6-0zqw"
+reversibles.decode("7aq6-0zqw")  # [78, 45]
 ```
 
 Length of the ID, the alphabet used, and the number of characters per group can be configured.
@@ -19,22 +19,26 @@ The custom alphabet (at least 16 characters needed) and character group sizes is
 Easily confused characters (eg `i` and `j`, `0` and `O`, `1` and `I` etc) are mapped to counterpart characters, to help 
 common mistakes when sharing (eg customer over phone to customer service agent).
 
+Also supports UUIDs if needed
+
+```
+::EncodedId::ReversibleId.new(salt: my_salt).encode_hex("9a566b8b-8618-42ab-8db7-a5a0276401fd")
+=> "rppv-tg8a-cx8q-gu9e-zq15-jxes-4gpr-06xk-wfk8-aw"
+```
+
 ## Features
 
 Build with https://hashids.org
 
 * Hashids are reversible, no need to persist the generated Id
 * supports slugged IDs (eg 'beef-tenderloins-prime--p5w9-z27j')
 * supports multiple IDs encoded in one `EncodedId` (eg '7aq6-0zqw' decodes to `[78, 45]`)
+* supports encoding of hex strings (eg UUIDs), including mutliple IDs encoded in one `EncodedId`
 * uses a reduced character set (Crockford alphabet) & ids split into groups of letters, ie 'human-readability'
 * profanity limitation
 
 To use with **Rails** check out the `encoded_id-rails` gem.
 
-# TODO
-
-- support encoding of hex strings (eg UUIDs) (see hashids#encode_hex)
-
 ## Note on security of encoded IDs (hashids)
 
 **Encoded IDs are not secure**. It maybe possible to reverse them via brute-force. They are meant to be used in URLs as 

lib/encoded_id/reversible_id.rb

@@ -10,14 +10,17 @@ module EncodedId
   class ReversibleId
     ALPHABET = "0123456789abcdefghjkmnpqrstuvwxyz"
 
-    def initialize(salt:, length: 8, split_at: 4, alphabet: ALPHABET)
+    def initialize(salt:, length: 8, split_at: 4, alphabet: ALPHABET, hex_digit_encoding_group_size: 4)
       unique_alphabet = alphabet.chars.uniq
       raise InvalidAlphabetError, "Alphabet must be at least 16 characters" if unique_alphabet.size < 16
 
       @human_friendly_alphabet = unique_alphabet.join
       @salt = salt
       @length = length
       @split_at = split_at
+      # Number of hex digits to encode in each group, larger values will result in shorter hashes for longer inputs.
+      # Vice versa for smaller values, ie a smaller value will result in smaller hashes for small inputs.
+      @hex_digit_encoding_group_size = hex_digit_encoding_group_size
     end
 
     # Encode the input values into a hash
@@ -28,16 +31,27 @@ def encode(values)
       encoded_id
     end
 
+    # Encode hex strings into a hash
+    def encode_hex(hexs)
+      encode(integer_representation(hexs))
+    end
+
     # Decode the hash to original array
     def decode(str)
       encoded_id_generator.decode(convert_to_hash(str))
     rescue ::Hashids::InputError => e
       raise EncodedIdFormatError, e.message
     end
 
+    # Decode hex strings from a hash
+    def decode_hex(str)
+      integers = encoded_id_generator.decode(convert_to_hash(str))
+      integers_to_hex_strings(integers)
+    end
+
     private
 
-    attr_reader :salt, :length, :human_friendly_alphabet, :split_at
+    attr_reader :salt, :length, :human_friendly_alphabet, :split_at, :hex_digit_encoding_group_size
 
     def prepare_input(value)
       inputs = value.is_a?(Array) ? value.map(&:to_i) : [value.to_i]
@@ -67,5 +81,53 @@ def map_crockford_set(str)
       # only use lowercase
       str.tr("o", "0").tr("l", "1").tr("i", "j")
     end
+
+    # TODO: optimize this
+    def integer_representation(hexs)
+      inputs = hexs.is_a?(Array) ? hexs.map(&:to_s) : [hexs.to_s]
+      inputs.map! do |hex_string|
+        cleaned = hex_string.gsub(/[^0-9a-f]/i, "")
+        # Convert to groups of integers. Process least significant hex digits first
+        groups = []
+        cleaned.chars.reverse.each_with_index do |char, i|
+          group_id = i / hex_digit_encoding_group_size.to_i
+          groups[group_id] ||= []
+          groups[group_id].unshift(char)
+        end
+        groups.map { |c| c.join.to_i(16) }
+      end
+      digits_to_encode = []
+      inputs.each_with_object(digits_to_encode) do |hex_digits, digits|
+        digits.concat(hex_digits)
+        digits << hex_string_separator
+      end
+      digits_to_encode.pop unless digits_to_encode.empty? # Remove the last marker
+      digits_to_encode
+    end
+
+    # Marker to separate hex strings, must be greater than largest value encoded
+    def hex_string_separator
+      @hex_string_separator ||= 2.pow(hex_digit_encoding_group_size * 4) + 1
+    end
+
+    # TODO: optimize this
+    def integers_to_hex_strings(integers)
+      hex_strings = []
+      hex_string = []
+      add_leading = false
+      # Digits are encoded in least significant digit first order, but string is most significant first, so reverse
+      integers.reverse_each do |integer|
+        if integer == hex_string_separator # Marker to separate hex strings, so start a new one
+          hex_strings << hex_string.join
+          hex_string = []
+          add_leading = false
+        else
+          hex_string << (add_leading ? "%.#{hex_digit_encoding_group_size}x" % integer : integer.to_s(16))
+          add_leading = true
+        end
+      end
+      hex_strings << hex_string.join unless hex_string.empty? # Add the last hex string
+      hex_strings.reverse # Reverse final values to get the original order (the encoding process also reverses the encoded value order)
+    end
   end
 end

sig/encoded_id.rbs

@@ -8,18 +8,25 @@ module EncodedId
   class ReversibleId
     ALPHABET: ::String
 
-    def initialize: (salt: ::String, ?length: ::Integer, ?split_at: ::Integer, ?alphabet: untyped) -> void
+    def initialize: (salt: ::String, ?length: ::Integer, ?split_at: ::Integer, ?alphabet: ::String, ?hex_digit_encoding_group_size: ::Integer) -> void
 
     # Encode the input values into a hash
     def encode: (untyped values) -> ::String
 
+    # Encode hex strings into a hash
+    def encode_hex: (untyped hexs) -> ::String
+
     # Decode the hash to original array
-    def decode: (::String str) -> Array[::Integer]
+    def decode: (::String str) -> ::Array[::Integer]
+
+    # Decode hex strings from a hash
+    def decode_hex: (::String str) -> ::Array[::String]
 
     private
 
     @encoded_id_generator: ::Hashids
     @split_regex: ::Regexp
+    @hex_string_separator: ::Integer
 
     attr_reader salt: ::String
 
@@ -29,6 +36,8 @@ module EncodedId
 
     attr_reader split_at: ::Integer | nil
 
+    attr_reader hex_digit_encoding_group_size: ::Integer
+
     def prepare_input: (untyped value) -> ::Array[::Integer]
 
     def encoded_id_generator: () -> ::Hashids
@@ -40,5 +49,11 @@ module EncodedId
     def convert_to_hash: (::String str) -> ::String
 
     def map_crockford_set: (::String str) -> ::String
+
+    def integer_representation: (untyped hexs) -> ::Array[::Integer]
+
+    def integers_to_hex_strings: (::Array[::Integer] integers) -> ::Array[::String]
+
+    def hex_string_separator: () -> ::Integer
   end
 end

test/test_encoded_id.rb

@@ -159,6 +159,54 @@ def test_it_raises_when_hash_format_is_broken
     end
   end
 
+  def test_it_encodes_hexadecimal
+    id = "f1"
+    coded = ::EncodedId::ReversibleId.new(salt: salt).encode_hex(id)
+    assert_equal "zryg-pey4", coded
+  end
+
+  def test_it_decodes_hexadecimal
+    coded = "zryg-pey4"
+    id = ::EncodedId::ReversibleId.new(salt: salt).decode_hex(coded)
+    assert_equal ["f1"], id
+  end
+
+  def test_it_encodes_multiple_hexadecimal
+    id = ["f1", "c2", "1a"]
+    coded = ::EncodedId::ReversibleId.new(salt: salt).encode_hex(id)
+    assert_equal "a3kf-xjk9-u9zh-5bdq-hbd", coded
+  end
+
+  def test_it_decodes_multiple_hexadecimal
+    coded = "a3kf-xjk9-u9zh-5bdq-hbd"
+    id = ::EncodedId::ReversibleId.new(salt: salt).decode_hex(coded)
+    assert_equal ["f1", "c2", "1a"], id
+  end
+
+  def test_it_encodes_multiple_hexadecimal_with_different_length
+    id = ["1", "c0", "97349ffe152d0013", "f0000"]
+    coded = ::EncodedId::ReversibleId.new(salt: salt).encode_hex(id)
+    assert_equal "rmhv-gr91-vatq-2knh-mcj3-dfmp-n6sn-epms-aed5-hkt2", coded
+  end
+
+  def test_it_decodes_multiple_hexadecimal_with_different_length
+    coded = "rmhv-gr91-vatq-2knh-mcj3-dfmp-n6sn-epms-aed5-hkt2"
+    id = ::EncodedId::ReversibleId.new(salt: salt).decode_hex(coded)
+    assert_equal ["1", "c0", "97349ffe152d0013", "f0000"], id
+  end
+
+  def test_it_encodes_multiple_hexadecimal_as_uuids
+    id = ["9a566b8b-8618-42ab-8db7-a5a0276401fd", "59f3905a-e704-4714-b42e-960c82b699fe", "9c0498f3-639d-41ed-87c3-715c61e14798"]
+    coded = ::EncodedId::ReversibleId.new(salt: salt, split_at: 16).encode_hex(id)
+    assert_equal "mxxbfa8xtqxmvt3k-4dfbz3jhg9ebuem6-jtmx6r06e3qczk56-srrrxsn5v41qb5ah-zqx2sj2aau2e3jsx-59gcd96nh8mqksdm-9jcbz8b0dkeeuxpv-bh3x6pfq5en03pbx", coded
+  end
+
+  def test_it_decodes_multiple_hexadecimal_as_uuids
+    coded = "mxxbfa8xtqxmvt3k-4dfbz3jhg9ebuem6-jtmx6r06e3qczk56-srrrxsn5v41qb5ah-zqx2sj2aau2e3jsx-59gcd96nh8mqksdm-9jcbz8b0dkeeuxpv-bh3x6pfq5en03pbx"
+    id = ::EncodedId::ReversibleId.new(salt: salt).decode_hex(coded)
+    assert_equal ["9a566b8b861842ab8db7a5a0276401fd", "59f3905ae7044714b42e960c82b699fe", "9c0498f3639d41ed87c3715c61e14798"], id
+  end
+
   private
 
   def salt