encoded_id 0.3.0 → 1.0.0.rc1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b69898cce6c9514fc7269f139e4280673b319cf2c879cbb925fdc5a8c03abc27
-  data.tar.gz: b0f17c21e5baa1a171df12629d27ebae511c647a66c0dc82dd8690e573c94754
+  metadata.gz: a860b12577a70042f6d17a1788cb8557f3ab5ab477441a44c3be037b70165ded
+  data.tar.gz: bd9d57c92ada9e47a1080ea5b4d04cb3069a055a213305b698f1a2c7c424297f
 SHA512:
-  metadata.gz: 133e6d70f9a3613e9009e0d5fe65dd3fdebd095c79533d7976924ed2d9589a47d4854a19d0a9f718caf864673a066f07d92b6ba5947ae043ecb170ed2aab6175
-  data.tar.gz: a5368e9bc5eb8f49438cff06c5c3fbd22d054b386d31ae194ccdea2f8ed148bc9f54492eb93da2e88893056615c6ef73dc24eaef1e22194feac2e160660f0f10
+  metadata.gz: e78405858e31da61d3361c3e42f999591e68f2053f1b58944c1f07616f5a57a599a174708eda301d52743d9dabaae8e76bf50442936401a9e943699589e0ad5c
+  data.tar.gz: a4e9ee6327f0d0e0d68eab43af5f21126e5ccef888b7478e07e14ade2a1532f618ac95ddb80e3406956ed7e505fda76c577e63368d376955024ab65df5084aa0

data/CHANGELOG.md

@@ -1,5 +1,21 @@
 ## [Unreleased]
 
+## [1.0.0] - 2023-08-06
+
+- Improved RBS definitions
+- Improved test coverage
+
+## [0.4.0] - 2022-12-04
+
+- Support custom split character which must not be in the alphabet
+- Ability to provide a custom character equivalences mapping
+
+## [0.3.0] - 2022-10-12
+
+- Fix splitting of encoded ID string
+- Checks that integer values to be encoded are positive
+- Experimental support for encoding hex strings
+
 ## [0.1.0] - 2022-10-11
 
 - Initial release

data/Gemfile

@@ -9,6 +9,6 @@ gem "rake", "~> 13.0"
 
 gem "minitest", "~> 5.0"
 
-gem "standard", "~> 1.3"
+gem "standard", "~> 1.25"
 
-gem "steep", "~> 1.2"
+gem "steep", "~> 1.5"

data/README.md

@@ -1,65 +1,76 @@
 # EncodedId
 
-Encode your numerical IDs (eg record primary keys) into obfuscated strings that can be used in URLs. 
+Encode numerical or hex IDs into obfuscated strings that can be used in URLs. 
 
-`::EncodedId::ReversibleId.new(salt: my_salt).encode(123)` => `"p5w9-z27j"`
+```ruby
+coder = ::EncodedId::ReversibleId.new(salt: my_salt)
+coder.encode(123)
+# => "p5w9-z27j"
+coder.encode_hex("10f8c")
+# => "w72a-y0az"
+```
 
-The obfuscated strings are reversible, so you can decode them back into the original numerical IDs. Also supports 
-encoding multiple IDs at once.
+The obfuscated strings are reversible (they decode them back into the original IDs). 
 
-```
-reversibles = ::EncodedId::ReversibleId.new(salt: my_salt)
-reversibles.encode([78, 45])  # "7aq6-0zqw"
-reversibles.decode("7aq6-0zqw")  # [78, 45]
-```
+Also supports encoding multiple IDs at once.
 
-Length of the ID, the alphabet used, and the number of characters per group can be configured.
+```ruby
+my_salt = "salt!"
+coder = ::EncodedId::ReversibleId.new(salt: my_salt)
 
-The custom alphabet (at least 16 characters needed) and character group sizes is to make the IDs easier to read or share.
-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).
+# One of more values can be encoded
+coder.encode([78, 45])
+# => "z2j7-0dmw"
 
-Also supports UUIDs if needed
+# The encoded string can then be reversed back into the original IDs
+coder.decode("z2j7-0dmw")
+# => [78, 45]
 
-```
-::EncodedId::ReversibleId.new(salt: my_salt).encode_hex("9a566b8b-8618-42ab-8db7-a5a0276401fd")
-=> "rppv-tg8a-cx8q-gu9e-zq15-jxes-4gpr-06xk-wfk8-aw"
+# The decoder can be resilient to easily confused characters
+coder.decode("z2j7-Odmw") # (note the capital 'o' instead of zero)
+# => [78, 45]
 ```
 
 ## Features
 
-Build with https://hashids.org
+* encoded IDs are reversible (uses with https://hashids.org))
+* supports multiple IDs encoded in one encoded string (eg `7aq6-0zqw` decodes to `[78, 45]`)
+* supports encoding of hex strings (eg UUIDs), including multiple IDs encoded in one string **(experimental)**
+* supports custom alphabets for the encoded string (at least 16 characters needed)
+  - by default uses a variation of the Crockford reduced character set (https://www.crockford.com/base32.html)
+  - easily confused characters (eg `i` and `j`, `0` and `O`, `1` and `I` etc) are mapped to counterpart characters, to help
+      avoid common readability mistakes when reading/sharing
+  - build in profanity limitation
+* encoded string can be split into groups of letters to improve human-readability
+  - eg `nft9hr834htu` as `nft9-hr83-4htu`
 
-* 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
+### Rails support `encoded_id-rails`
 
-To use with **Rails** check out the `encoded_id-rails` gem.
+To use with **Rails** check out the [`encoded_id-rails`](https://github.com/stevegeek/encoded_id-rails) gem.
 
-## Note on security of encoded IDs (hashids)
+```ruby
+class User < ApplicationRecord
+  include EncodedId::WithEncodedId
+end
+
+User.find_by_encoded_id("p5w9-z27j")
+# => #<User id: 78>
+```
+
+### 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 
 an obfuscation. The algorithm is not an encryption.
 
 Please read more on https://hashids.org/
 
-
-## Compared to alternate Gems
+## Compare to alternate Gems
 
 - https://github.com/excid3/prefixed_ids
 - https://github.com/namick/obfuscate_id
 - https://github.com/norman/friendly_id
 - https://github.com/SPBTV/with_uid
 
-## See also
-
-- https://hashids.org
-- https://www.crockford.com/wrmg/base32.html
-
-
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:
@@ -70,20 +81,189 @@ If bundler is not being used to manage dependencies, install the gem by executin
 
     $ gem install encoded_id
 
-## Usage
+## `EncodedId::ReversibleId.new`
+
+To create an instance of the encoder/decoder use `.new` with the `salt` option:
+
+```ruby
+coder = EncodedId::ReversibleId.new(
+  # The salt is required
+  salt: ...,
+  # And then the following options are optional
+  length: 8, 
+  split_at: 4, 
+  split_with: "-",
+  alphabet: EncodedId::Alphabet.modified_crockford,
+  hex_digit_encoding_group_size: 4 # Experimental
+)
+```
+
+Note the `salt` value is required and should be a string of some length (greater than 3 characters). This is used to generate the encoded string. 
+
+It will need to be the same value when decoding the string back into the original ID. If the salt is changed, the encoded
+strings will be different and possibly decode to different IDs.
+
+### Options
+
+The encoded ID is configurable. The following can be changed:
+
+- the length, eg 8 characters for `p5w9-z27j`
+- the alphabet used in it (min 16 characters)
+- and the number of characters to split the output into and the separator
 
-TODO: Write usage instructions here
+### `length`
 
-### Rails
+`length`: the minimum length of the encoded string. The default is 8 characters.
 
-To use with rails try the `encoded_id-rails` gem.
+The actual length of the encoded string can be longer if the inputs cannot be represented in the minimum length.
+
+### `alphabet`
+
+`alphabet`: the alphabet used in the encoded string. By default it uses a variation of the Crockford reduced character set (https://www.crockford.com/base32.html).
+
+`alphabet` must be an instance of `EncodedId::Alphabet`.
+
+The default alphabet is `EncodedId::Alphabet.modified_crockford`.
+
+To create a new alphabet, use `EncodedId::Alphabet.new`:
 
 ```ruby
-    class User < ApplicationRecord
-      include EncodedId::WithEncodedId
-    end
+alphabet = EncodedId::Alphabet.new("0123456789abcdef")
+```
+
+`EncodedId::Alphabet.new(characters, equivalences)`
 
-    User.find_by_encoded_id("p5w9-z27j")  # => #<User id: 78>
+**characters**
+
+`characters`: the characters of the alphabet. Can be a string or array of strings.
+
+Note that the `characters` of the alphabet must be at least 16 _unique_ characters long.
+
+
+```ruby
+alphabet = EncodedId::Alphabet.new("ςερτυθιοπλκξηγφδσαζχψωβνμ")
+coder = ::EncodedId::ReversibleId.new(salt: my_salt, alphabet: alphabet)
+coder.encode(123)
+# => "πφλχ-ψησω"
+```
+
+Note that larger alphabets can result in shorter encoded strings (but remember that `length` specifies the minimum length
+of the encoded string).
+
+**equivalences**
+
+You can optionally pass an appropriate character `equivalences` mapping. This is used to map easily confused characters 
+to their counterpart. 
+
+`equivalences`: a hash of characters keys, with their equivalent alphabet character mapped to in the values. 
+
+Note that the characters to be mapped:
+- must not be in the alphabet, 
+- must map to a character that is in the alphabet.
+
+`nil` is the default value which means no equivalences are used.
+
+```ruby
+alphabet = EncodedId::Alphabet.new("!@#$%^&*()+-={}", {"_" => "-"})
+coder = ::EncodedId::ReversibleId.new(salt: my_salt, alphabet: alphabet)
+coder.encode(123)
+# => "}*^(-^}*="
+```
+
+### `split_at` and `split_with`
+
+For readability, the encoded string can be split into groups of characters. 
+
+`split_at`: specifies the number of characters to split the encoded string into. Defaults to 4. 
+
+`split_with`: specifies the separator to use between the groups. Default is `-`.
+
+### `hex_digit_encoding_group_size`
+
+**Experimental**
+
+`hex_digit_encoding_group_size`: specifies the number of hex digits to encode in a group. Defaults to 4. Can be
+between 1 and 32.
+
+Can be used to control the size of the encoded string when encoding hex strings. Larger values will result in shorter
+encoded strings for long inputs, and shorter values will result in shorter encoded strings for smaller inputs.
+
+But note that bigger values will also result in larger markers that separate the groups so could end up increasing
+the encoded string length undesirably.
+
+See below section `Using with hex strings` for more details.
+
+## `EncodedId::ReversibleId#encode`
+
+`#encode(id)`: where `id` is an integer or array of integers to encode.
+
+```ruby
+coder.encode(123)
+# => "p5w9-z27j"
+
+# One of more values can be encoded
+coder.encode([78, 45])
+# => "z2j7-0dmw"
+```
+
+## `EncodedId::ReversibleId#decode`
+
+`#decode(encoded_id)`: where `encoded_id` is a string to decode.
+
+```ruby
+# The encoded string can then be reversed back into the original IDs
+coder.decode("z2j7-0dmw")
+# => [78, 45]
+```
+
+## Using with hex strings
+
+**Experimental** (subject to incompatible changes in future versions)
+
+```ruby
+# Hex input strings are also supported
+coder.encode_hex("10f8c")
+# => "w72a-y0az"
+```
+
+When encoding hex strings, the input is split into groups of hex digits, and each group is encoded separately as its
+integer equivalent. In other words the input is converted into an array of integers and encoded as normal with the
+`encode` method.
+
+eg with `hex_digit_encoding_group_size=1` and inpu `f1`, is split into `f` and `1`, and then encoded as `15` and `1` 
+respectively, ie `encode` is called with `[15, 1]`.
+
+To encode multiple hex inputs the encoded string contains markers to indicate the start of a new hex input. This
+marker is equal to an integer value which is 1 larger than the maximum value the hex digit encoding group size can
+represent (ie it is `2^(hex_digit_encoding_group_size * 4)`).
+
+So for a hex digit encoding group size of 4 (ie group max value is `0xFFFF`), the marker is `65536`
+
+For example with `hex_digit_encoding_group_size=1` for the inputs `f1` and `e2` encoded together, the 
+actual encoded integer array is `[15, 1, 16, 14, 2]`.
+
+### `EncodedId::ReversibleId#encode_hex`
+
+`encode_hex(hex_string)` , where `hex_string` is a string of hex digits or an array of hex strings.
+
+```ruby
+# UUIDs will result in long output strings...
+coder.encode_hex("9a566b8b-8618-42ab-8db7-a5a0276401fd")
+# => "5jjy-c8d9-hxp2-qsve-rgh9-rxnt-7nb5-tve7-bf84-vr"
+# 
+# but there is an option to help reduce this... 
+coder = ::EncodedId::ReversibleId.new(salt: my_salt, hex_digit_encoding_group_size: 32)
+coder.encode_hex("9a566b8b-8618-42ab-8db7-a5a0276401fd")
+# => "vr7m-qra8-m5y6-dkgj-5rqr-q44e-gp4a-52"
+```
+
+### `EncodedId::ReversibleId#decode_hex`
+
+`decode_hex(encoded_id)` , where the output is an array of hex strings.
+
+```ruby
+coder.decode_hex("5jjy-c8d9-hxp2-qsve-rgh9-rxnt-7nb5-tve7-bf84-vr")
+# => ["9a566b8b-8618-42ab-8db7-a5a0276401fd"]
 ```
 
 ## Development
@@ -95,9 +275,29 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git 
 commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
+### Type check
+
+First install dependencies:
+
+```bash
+rbs collection install
+```
+
+Then run:
+
+```bash
+steep check
+```
+
+
+## See also
+
+- https://hashids.org
+- https://www.crockford.com/base32.html
+
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/encoded_id.
+Bug reports and pull requests are welcome on GitHub at https://github.com/stevegeek/encoded_id.
 
 ## License
 

data/lib/encoded_id/alphabet.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module EncodedId
+  class Alphabet
+    MIN_UNIQUE_CHARACTERS = 16
+
+    class << self
+      def modified_crockford
+        new(
+          "0123456789abcdefghjkmnpqrstuvwxyz",
+          {
+            "o" => "0",
+            "i" => "j",
+            "l" => "1"
+          }
+        )
+      end
+    end
+
+    def initialize(characters, equivalences = nil)
+      raise_invalid_alphabet! unless valid_input_characters?(characters)
+      unique_characters = unique_character_alphabet(characters)
+      raise_character_set_too_small! unless sufficient_characters?(unique_characters.size)
+      raise_invalid_equivalences! unless valid_equivalences?(equivalences, unique_characters)
+
+      @characters = unique_characters.join
+      @equivalences = equivalences
+    end
+
+    attr_reader :characters, :equivalences
+
+    private
+
+    def valid_input_characters?(characters)
+      (characters.is_a?(Array) || characters.is_a?(String)) && characters.size > 0
+    end
+
+    def unique_character_alphabet(characters)
+      (characters.is_a?(Array) ? characters : characters.chars).uniq
+    end
+
+    def sufficient_characters?(size)
+      size >= MIN_UNIQUE_CHARACTERS
+    end
+
+    def valid_equivalences?(equivalences, unique_characters)
+      return true if equivalences.nil?
+      return false unless equivalences.is_a?(Hash)
+
+      (unique_characters & equivalences.keys).empty? && (equivalences.values - unique_characters).empty?
+    end
+
+    def raise_invalid_alphabet!
+      raise InvalidAlphabetError, "Alphabet must be a string or array."
+    end
+
+    def raise_character_set_too_small!
+      raise InvalidAlphabetError, "Alphabet must contain at least #{MIN_UNIQUE_CHARACTERS} unique characters."
+    end
+
+    def raise_invalid_equivalences!
+      raise InvalidConfigurationError, "Character equivalences must be a hash or nil."
+    end
+  end
+end

data/lib/encoded_id/hex_representation.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module EncodedId
+  class HexRepresentation
+    def initialize(hex_digit_encoding_group_size)
+      @hex_digit_encoding_group_size = validate_hex_digit_encoding_group_size(hex_digit_encoding_group_size)
+    end
+
+    def hex_as_integers(hexs)
+      integer_representation(hexs)
+    end
+
+    def integers_as_hex(integers)
+      integers_to_hex_strings(integers)
+    end
+
+    private
+
+    # 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.
+    def validate_hex_digit_encoding_group_size(hex_digit_encoding_group_size)
+      if !hex_digit_encoding_group_size.is_a?(Integer) || hex_digit_encoding_group_size < 1 || hex_digit_encoding_group_size > 32
+        raise InvalidConfigurationError, "hex_digit_encoding_group_size must be > 0 and <= 32"
+      end
+      hex_digit_encoding_group_size
+    end
+
+    # Convert hex strings to integer representations
+    def integer_representation(hexs)
+      inputs = Array(hexs).map(&:to_s)
+      digits_to_encode = []
+
+      inputs.map { |hex_string| hex_string_as_integer_representation(hex_string) }.each do |integer_groups|
+        digits_to_encode.concat(integer_groups)
+        digits_to_encode << hex_string_separator
+      end
+
+      # Remove the last marker
+      digits_to_encode.pop unless digits_to_encode.empty?
+      digits_to_encode
+    end
+
+    # Convert integer representations to hex strings
+    def integers_to_hex_strings(integers)
+      hex_strings = []
+      hex_string = []
+      add_leading = false
+
+      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
+
+      # Add the last hex string
+      hex_strings << hex_string.join unless hex_string.empty?
+      hex_strings.reverse
+    end
+
+    def hex_string_as_integer_representation(hex_string)
+      cleaned = remove_non_hex_characters(hex_string)
+      convert_to_integer_groups(cleaned)
+    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)
+    end
+
+    def remove_non_hex_characters(hex_string)
+      hex_string.gsub(/[^0-9a-f]/i, "")
+    end
+
+    def convert_to_integer_groups(hex_string_cleaned)
+      groups = []
+      hex_string_cleaned.chars.reverse.each_with_index do |char, i|
+        group_id = i / @hex_digit_encoding_group_size
+        groups[group_id] ||= []
+        groups[group_id].unshift(char)
+      end
+      groups.map { |c| c.join.to_i(16) }
+    end
+  end
+end

data/lib/encoded_id/reversible_id.rb

@@ -8,19 +8,13 @@ require "hashids"
 # Note hashIds already has a built in profanity limitation algorithm
 module EncodedId
   class ReversibleId
-    ALPHABET = "0123456789abcdefghjkmnpqrstuvwxyz"
-
-    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
+    def initialize(salt:, length: 8, split_at: 4, split_with: "-", alphabet: Alphabet.modified_crockford, hex_digit_encoding_group_size: 4)
+      @alphabet = validate_alphabet(alphabet)
+      @salt = validate_salt(salt)
+      @length = validate_length(length)
+      @split_at = validate_split_at(split_at)
+      @split_with = validate_split_with(split_with, alphabet)
+      @hex_represention_encoder = HexRepresentation.new(hex_digit_encoding_group_size)
     end
 
     # Encode the input values into a hash
@@ -33,7 +27,7 @@ module EncodedId
 
     # Encode hex strings into a hash
     def encode_hex(hexs)
-      encode(integer_representation(hexs))
+      encode(hex_represention_encoder.hex_as_integers(hexs))
     end
 
     # Decode the hash to original array
@@ -46,12 +40,48 @@ module EncodedId
     # Decode hex strings from a hash
     def decode_hex(str)
       integers = encoded_id_generator.decode(convert_to_hash(str))
-      integers_to_hex_strings(integers)
+      hex_represention_encoder.integers_as_hex(integers)
     end
 
     private
 
-    attr_reader :salt, :length, :human_friendly_alphabet, :split_at, :hex_digit_encoding_group_size
+    attr_reader :salt,
+      :length,
+      :alphabet,
+      :split_at,
+      :split_with,
+      :hex_represention_encoder
+
+    def validate_alphabet(alphabet)
+      raise InvalidAlphabetError, "alphabet must be an instance of Alphabet" unless alphabet.is_a?(Alphabet)
+      alphabet
+    end
+
+    def validate_salt(salt)
+      raise InvalidConfigurationError, "Salt must be a string and longer than 3 characters" unless salt.is_a?(String) && salt.size > 3
+      salt
+    end
+
+    # Target length of the encoded string (the minimum but not maximum length)
+    def validate_length(length)
+      raise InvalidConfigurationError, "Length must be an integer greater than 0" unless length.is_a?(Integer) && length > 0
+      length
+    end
+
+    # Split the encoded string into groups of this size
+    def validate_split_at(split_at)
+      unless (split_at.is_a?(Integer) && split_at > 0) || split_at.nil?
+        raise InvalidConfigurationError, "Split at must be an integer greater than 0 or nil"
+      end
+      split_at
+    end
+
+    def validate_split_with(split_with, alphabet)
+      unless split_with.is_a?(String) && !alphabet.characters.include?(split_with)
+        raise InvalidConfigurationError, "Split with must be a string and not part of the alphabet"
+      end
+      split_with
+    end
 
     def prepare_input(value)
       inputs = value.is_a?(Array) ? value.map(&:to_i) : [value.to_i]
@@ -61,7 +91,7 @@ module EncodedId
     end
 
     def encoded_id_generator
-      @encoded_id_generator ||= ::Hashids.new(salt, length, human_friendly_alphabet)
+      @encoded_id_generator ||= ::Hashids.new(salt, length, alphabet.characters)
     end
 
     def split_regex
@@ -69,65 +99,19 @@ module EncodedId
     end
 
     def humanize_length(hash)
-      hash.gsub(split_regex, '\0-')
+      hash.gsub(split_regex, "\\0#{split_with}")
     end
 
     def convert_to_hash(str)
-      map_crockford_set(str.delete("-").downcase)
-    end
-
-    def map_crockford_set(str)
-      # Crockford suggest i==1 , but I think i==j is more appropriate as we
-      # 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
+      clean = str.delete(split_with).downcase
+      alphabet.equivalences.nil? ? clean : map_equivalent_characters(clean)
+    end
+
+    def map_equivalent_characters(str)
+      alphabet.equivalences.reduce(str) do |cleaned, ceq|
+        from, to = ceq
+        cleaned.tr(from, to)
       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

data/lib/encoded_id/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module EncodedId
-  VERSION = "0.3.0"
+  VERSION = "1.0.0.rc1"
 end

data/lib/encoded_id.rb

@@ -1,12 +1,16 @@
 # frozen_string_literal: true
 
 require_relative "encoded_id/version"
+require_relative "encoded_id/alphabet"
+require_relative "encoded_id/hex_representation"
 require_relative "encoded_id/reversible_id"
 
 module EncodedId
-  class EncodedIdFormatError < ArgumentError; end
+  class InvalidConfigurationError < StandardError; end
 
   class InvalidAlphabetError < ArgumentError; end
 
+  class EncodedIdFormatError < ArgumentError; end
+
   class InvalidInputError < ArgumentError; end
 end

data/rbs_collection.yaml

@@ -9,8 +9,6 @@ sources:
 path: .gem_rbs_collection
 
 gems:
-  - name: encoded_id
-    ignore: true
   # Skip loading rbs gem's RBS.
   # It's unnecessary if you don't use rbs as a library.
   - name: rbs

data/sig/encoded_id.rbs

@@ -1,18 +1,65 @@
 module EncodedId
+  VERSION: ::String
+
+  InvalidConfigurationError: ::StandardError
   EncodedIdFormatError: ::ArgumentError
   InvalidAlphabetError: ::ArgumentError
   InvalidInputError: ::ArgumentError
 
-  class ReversibleId
-    ALPHABET: ::String
+  class Alphabet
+    MIN_UNIQUE_CHARACTERS: ::Integer
+
+    def initialize: (String, ?::Hash[::String, ::String]) -> void
+
+    attr_reader characters: String
+    attr_reader equivalences: ::Hash[::String, ::String]
+
+    def self.modified_crockford: () -> Alphabet
+
+    private
+
+    def valid_input_characters?: ((::Array[::String] | ::String) characters) -> bool
+
+    def sufficient_characters?: (::Integer size) -> bool
+
+    def unique_character_alphabet: ((::Array[::String] | ::String) characters) -> ::Array[::String]
+
+    def valid_equivalences?: (::Hash[::String, ::String] equivalences, ::Array[::String] unique_characters) -> bool
+
+    def raise_character_set_too_small!: -> untyped
+
+    def raise_invalid_alphabet!: -> void
 
-    def initialize: (salt: ::String, ?length: ::Integer, ?split_at: ::Integer, ?alphabet: ::String, ?hex_digit_encoding_group_size: ::Integer) -> void
+    def raise_invalid_equivalences!: -> void
+  end
+
+  type encodeableValue = ::Array[::String | ::Integer] | ::String | ::Integer
+  type encodeableHexValue = ::Array[::String] | ::String
+
+  class HexRepresentation
+    def initialize: (::Integer) -> void
+    def hex_as_integers: (encodeableHexValue) -> ::Array[::Integer]
+    def integers_as_hex: (::Array[::Integer]) -> ::Array[::String]
+
+    private
+
+    def validate_hex_digit_encoding_group_size: (::Integer) -> ::Integer
+    def integer_representation: (encodeableHexValue) -> ::Array[::Integer]
+    def integers_to_hex_strings: (::Array[::Integer]) -> ::Array[::String]
+    def hex_string_as_integer_representation: (::String) -> ::Array[::Integer]
+    def hex_string_separator: -> ::Integer
+    def remove_non_hex_characters: (::String) -> ::String
+    def convert_to_integer_groups: (::String) -> ::Array[::Integer]
+  end
+
+  class ReversibleId
+    def initialize: (salt: ::String, ?length: ::Integer, ?split_at: ::Integer, ?split_with: ::String, ?alphabet: Alphabet, ?hex_digit_encoding_group_size: ::Integer) -> void
 
     # Encode the input values into a hash
-    def encode: (untyped values) -> ::String
+    def encode: (encodeableValue values) -> ::String
 
     # Encode hex strings into a hash
-    def encode_hex: (untyped hexs) -> ::String
+    def encode_hex: (encodeableHexValue hexs) -> ::String
 
     # Decode the hash to original array
     def decode: (::String str) -> ::Array[::Integer]
@@ -30,11 +77,19 @@ module EncodedId
 
     attr_reader length: ::Integer
 
-    attr_reader human_friendly_alphabet: ::String
+    attr_reader alphabet: Alphabet
 
     attr_reader split_at: ::Integer | nil
+    attr_reader split_with: ::String
+
+    attr_reader hex_represention_encoder: HexRepresentation
 
-    attr_reader hex_digit_encoding_group_size: ::Integer
+    def validate_alphabet: (Alphabet) -> Alphabet
+    def validate_salt: (::String) -> ::String
+    def validate_length: (::Integer) -> ::Integer
+    def validate_split_at: (::Integer | nil) -> (::Integer | nil)
+    def validate_split_with: (::String, Alphabet) -> ::String
+    def validate_hex_digit_encoding_group_size: (::Integer) -> ::Integer
 
     def prepare_input: (untyped value) -> ::Array[::Integer]
 
@@ -46,12 +101,6 @@ 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
+    def map_equivalent_characters: (::String str) -> ::String
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: encoded_id
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 1.0.0.rc1
 platform: ruby
 authors:
 - Stephen Ierodiaconou
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-10-12 00:00:00.000000000 Z
+date: 2023-08-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: hashids
@@ -42,6 +42,8 @@ files:
 - Rakefile
 - Steepfile
 - lib/encoded_id.rb
+- lib/encoded_id/alphabet.rb
+- lib/encoded_id/hex_representation.rb
 - lib/encoded_id/reversible_id.rb
 - lib/encoded_id/version.rb
 - rbs_collection.yaml
@@ -65,11 +67,11 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 2.7.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
-rubygems_version: 3.3.7
+rubygems_version: 3.4.10
 signing_key:
 specification_version: 4
 summary: EncodedId is a gem for creating reversible obfuscated IDs from numerical