encoded_id 1.0.0.rc6 → 1.0.0

data/lib/encoded_id/blocklist.rb

@@ -3,23 +3,18 @@
 # rbs_inline: enabled
 
 module EncodedId
+  # A blocklist of words that should not appear in encoded IDs.
   class Blocklist
     include Enumerable #[String]
 
     # @rbs @words: Set[String]
-
-    # Class instance variables for memoization
     # @rbs self.@empty: Blocklist
     # @rbs self.@minimal: Blocklist
 
     class << self
       # @rbs () -> Blocklist
       def sqids_blocklist
-        if defined?(::Sqids::DEFAULT_BLOCKLIST)
-          new(::Sqids::DEFAULT_BLOCKLIST)
-        else
-          empty
-        end
+        new(::Sqids::DEFAULT_BLOCKLIST)
       end
 
       # @rbs () -> Blocklist
@@ -86,5 +81,20 @@ module EncodedId
     def merge(other_blocklist)
       self.class.new(to_a + other_blocklist.to_a)
     end
+
+    # Filters the blocklist to only include words that can be formed from the given alphabet.
+    # Only keeps words where ALL characters exist in the alphabet (case-insensitive).
+    # Maintains minimum 3-character length requirement.
+    #
+    # @rbs (Alphabet | String alphabet) -> Blocklist
+    def filter_for_alphabet(alphabet)
+      alphabet_chars = Set.new(
+        alphabet.is_a?(Alphabet) ? alphabet.unique_characters : alphabet.to_s.chars
+      )
+
+      self.class.new(
+        @words.select { |word| word.length >= 3 && word.chars.to_set.subset?(alphabet_chars) }
+      )
+    end
   end
 end

data/lib/encoded_id/encoders/base_configuration.rb

@@ -0,0 +1,145 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module EncodedId
+  module Encoders
+    # Base configuration class for encoder-specific settings
+    # This provides common parameters shared across all encoders
+    class BaseConfiguration
+      attr_reader :min_length #: Integer
+      attr_reader :alphabet #: Alphabet
+      attr_reader :split_at #: Integer?
+      attr_reader :split_with #: String?
+      attr_reader :hex_digit_encoding_group_size #: Integer
+      attr_reader :max_length #: Integer?
+      attr_reader :max_inputs_per_id #: Integer
+      attr_reader :blocklist #: Blocklist
+      attr_reader :blocklist_mode #: Symbol
+      attr_reader :blocklist_max_length #: Integer
+
+      # @rbs (?min_length: Integer, ?alphabet: Alphabet, ?split_at: Integer?, ?split_with: String?, ?hex_digit_encoding_group_size: Integer, ?max_length: Integer?, ?max_inputs_per_id: Integer, ?blocklist: Blocklist | Array[String] | Set[String] | nil, ?blocklist_mode: Symbol, ?blocklist_max_length: Integer) -> void
+      def initialize(
+        min_length: 8,
+        alphabet: Alphabet.modified_crockford,
+        split_at: 4,
+        split_with: "-",
+        hex_digit_encoding_group_size: 4,
+        max_length: 128,
+        max_inputs_per_id: 32,
+        blocklist: Blocklist.empty,
+        blocklist_mode: :length_threshold,
+        blocklist_max_length: 32
+      )
+        @min_length = validate_min_length(min_length)
+        @alphabet = validate_alphabet(alphabet)
+        @split_at = validate_split_at(split_at)
+        @split_with = validate_split_with(split_with, @alphabet)
+        @hex_digit_encoding_group_size = hex_digit_encoding_group_size
+        @max_length = validate_max_length(max_length)
+        @max_inputs_per_id = validate_max_inputs_per_id(max_inputs_per_id)
+        @blocklist = validate_blocklist(blocklist)
+        @blocklist = @blocklist.filter_for_alphabet(@alphabet) unless @blocklist.empty?
+        @blocklist_mode = validate_blocklist_mode(blocklist_mode)
+        @blocklist_max_length = validate_blocklist_max_length(blocklist_max_length)
+        validate_blocklist_collision_risk
+      end
+
+      # @rbs () -> (Hashid | Sqids)
+      def create_encoder
+        raise NotImplementedError, "Subclasses must implement create_encoder"
+      end
+
+      private
+
+      # @rbs (Alphabet alphabet) -> Alphabet
+      def validate_alphabet(alphabet)
+        return alphabet if alphabet.is_a?(Alphabet)
+        raise InvalidAlphabetError, "alphabet must be an instance of Alphabet"
+      end
+
+      # @rbs (Integer min_length) -> Integer
+      def validate_min_length(min_length)
+        return min_length if valid_integer_option?(min_length)
+        raise InvalidConfigurationError, "min_length must be an integer greater than 0"
+      end
+
+      # @rbs (Integer? max_length) -> Integer?
+      def validate_max_length(max_length)
+        return max_length if valid_integer_option?(max_length) || max_length.nil?
+        raise InvalidConfigurationError, "max_length must be an integer greater than 0 or nil"
+      end
+
+      # @rbs (Integer max_inputs_per_id) -> Integer
+      def validate_max_inputs_per_id(max_inputs_per_id)
+        return max_inputs_per_id if valid_integer_option?(max_inputs_per_id)
+        raise InvalidConfigurationError, "max_inputs_per_id must be an integer greater than 0"
+      end
+
+      # @rbs (Integer? split_at) -> Integer?
+      def validate_split_at(split_at)
+        return split_at if valid_integer_option?(split_at) || split_at.nil?
+        raise InvalidConfigurationError, "split_at must be an integer greater than 0 or nil"
+      end
+
+      # @rbs (String? split_with, Alphabet alphabet) -> String?
+      def validate_split_with(split_with, alphabet)
+        return split_with if split_with.nil? || (split_with.is_a?(String) && !alphabet.characters.include?(split_with))
+        raise InvalidConfigurationError, "split_with must be a string not part of the alphabet, or nil"
+      end
+
+      # @rbs (Integer? value) -> bool
+      def valid_integer_option?(value)
+        value.is_a?(Integer) && value > 0
+      end
+
+      # @rbs (Blocklist | Array[String] | Set[String] | nil blocklist) -> Blocklist
+      def validate_blocklist(blocklist)
+        return blocklist if blocklist.is_a?(Blocklist)
+        return Blocklist.empty if blocklist.nil?
+        return Blocklist.new(blocklist) if blocklist.is_a?(Array) || blocklist.is_a?(Set)
+
+        raise InvalidConfigurationError, "blocklist must be a Blocklist, Set, or Array of strings"
+      end
+
+      # @rbs (Symbol blocklist_mode) -> Symbol
+      def validate_blocklist_mode(blocklist_mode)
+        valid_modes = [:always, :length_threshold, :raise_if_likely]
+        return blocklist_mode if valid_modes.include?(blocklist_mode)
+
+        raise InvalidConfigurationError, "blocklist_mode must be one of #{valid_modes.inspect}, got #{blocklist_mode.inspect}"
+      end
+
+      # @rbs (Integer blocklist_max_length) -> Integer
+      def validate_blocklist_max_length(blocklist_max_length)
+        return blocklist_max_length if valid_integer_option?(blocklist_max_length)
+
+        raise InvalidConfigurationError, "blocklist_max_length must be an integer greater than 0"
+      end
+
+      # Validates configuration for :raise_if_likely mode
+      # @rbs () -> void
+      def validate_blocklist_collision_risk
+        return if @blocklist.empty?
+        return unless @blocklist_mode == :raise_if_likely
+
+        # Check if min_length suggests long IDs
+        if @min_length > @blocklist_max_length
+          raise InvalidConfigurationError,
+            "blocklist_mode is :raise_if_likely and min_length (#{@min_length}) exceeds blocklist_max_length (#{@blocklist_max_length}). " \
+            "Long IDs have high collision probability with blocklists. " \
+            "Use blocklist_mode: :length_threshold or remove the blocklist."
+        end
+
+        # Check if max_inputs_per_id suggests long IDs
+        # Rough heuristic: encoding 100+ inputs typically results in long IDs
+        if @max_inputs_per_id > 100
+          raise InvalidConfigurationError,
+            "blocklist_mode is :raise_if_likely and max_inputs_per_id (#{@max_inputs_per_id}) is very high. " \
+            "Encoding many inputs typically results in long IDs with high blocklist collision probability. " \
+            "Use blocklist_mode: :length_threshold or remove the blocklist."
+        end
+      end
+    end
+  end
+end

data/lib/encoded_id/encoders/{hash_id.rb → hashid.rb}

@@ -70,14 +70,19 @@
 
 module EncodedId
   module Encoders
-    class HashId < Base
-      # @rbs @separators_and_guards: HashIdOrdinalAlphabetSeparatorGuards
+    # Implementation of HashId, optimised and adapted from the original `hashid.rb` gem
+    class Hashid
+      include HashidConsistentShuffle
+
+      # @rbs @separators_and_guards: HashidOrdinalAlphabetSeparatorGuards
       # @rbs @alphabet_ordinals: Array[Integer]
       # @rbs @separator_ordinals: Array[Integer]
       # @rbs @guard_ordinals: Array[Integer]
       # @rbs @salt_ordinals: Array[Integer]
       # @rbs @escaped_separator_selector: String
       # @rbs @escaped_guards_selector: String
+      # @rbs @blocklist_mode: Symbol
+      # @rbs @blocklist_max_length: Integer
 
       # Initialize a new HashId encoder with custom parameters.
       #
@@ -91,17 +96,22 @@ module EncodedId
       # @param min_hash_length [Integer] Minimum length of generated hashes (0 for no minimum)
       # @param alphabet [Alphabet] Character set to use for encoding
       # @param blocklist [Blocklist?] Optional list of words that shouldn't appear in hashes
+      # @param blocklist_mode [Symbol] Mode for blocklist checking (:always, :length_threshold, :raise_if_likely)
+      # @param blocklist_max_length [Integer] Maximum ID length for blocklist checking (when mode is :length_threshold)
       #
-      # @rbs (String salt, ?Integer min_hash_length, ?Alphabet alphabet, ?Blocklist? blocklist) -> void
-      def initialize(salt, min_hash_length = 0, alphabet = Alphabet.alphanum, blocklist = nil)
-        super
-
+      # @rbs (String salt, ?Integer min_hash_length, ?Alphabet alphabet, ?Blocklist? blocklist, ?Symbol blocklist_mode, ?Integer blocklist_max_length) -> void
+      def initialize(salt, min_hash_length = 0, alphabet = Alphabet.alphanum, blocklist = nil, blocklist_mode = :length_threshold, blocklist_max_length = 32)
         unless min_hash_length.is_a?(Integer) && min_hash_length >= 0
           raise ArgumentError, "The min length must be a Integer and greater than or equal to 0"
         end
         @min_hash_length = min_hash_length
+        @salt = salt
+        @alphabet = alphabet
+        @blocklist = blocklist
+        @blocklist_mode = blocklist_mode
+        @blocklist_max_length = blocklist_max_length
 
-        @separators_and_guards = HashIdOrdinalAlphabetSeparatorGuards.new(alphabet, salt)
+        @separators_and_guards = HashidOrdinalAlphabetSeparatorGuards.new(alphabet, salt)
         @alphabet_ordinals = @separators_and_guards.alphabet
         @separator_ordinals = @separators_and_guards.seps
         @guard_ordinals = @separators_and_guards.guards
@@ -117,6 +127,10 @@ module EncodedId
       attr_reader :separator_ordinals #: Array[Integer]
       attr_reader :guard_ordinals #: Array[Integer]
       attr_reader :salt_ordinals #: Array[Integer]
+      attr_reader :salt #: String
+      attr_reader :alphabet #: Alphabet
+      attr_reader :blocklist #: Blocklist?
+      attr_reader :min_hash_length #: Integer
 
       # Encode an array of non-negative integers into a hash string.
       #
@@ -134,15 +148,15 @@ module EncodedId
       #
       # @rbs (Array[Integer] numbers) -> String
       def encode(numbers)
-        numbers.all? { |n| Integer(n) } # raises if conversion fails
+        numbers.all? { |n| Integer(n) }
 
         return "" if numbers.empty? || numbers.any? { |n| n < 0 }
 
         encoded = internal_encode(numbers)
-        if blocklist && !blocklist.empty?
+        if check_blocklist?(encoded)
           blocked_word = contains_blocklisted_word?(encoded)
           if blocked_word
-            raise EncodedId::BlocklistError, "Generated ID contains blocklisted word: '#{blocked_word}'"
+            raise EncodedId::BlocklistError, "Generated ID '#{encoded}' contains blocklisted word: '#{blocked_word}'"
           end
         end
 
@@ -171,26 +185,6 @@ module EncodedId
         internal_decode(hash)
       end
 
-      # Decode a hash that was encoded from hexadecimal numbers.
-      #
-      # This is a specialized variant for hashes created from hex strings.
-      # It decodes the hash to integers, then converts each integer back to hex
-      # (skipping the leading '1' that was added during hex encoding).
-      #
-      # @param hash [String] The hash string to decode
-      # @return [String] The original hexadecimal string (uppercase)
-      #
-      # @rbs (String hash) -> String
-      def decode_hex(hash)
-        numbers = decode(hash)
-
-        ret = numbers.map do |n|
-          n.to_s(16)[1..]
-        end
-
-        ret.join.upcase
-      end
-
       private
 
       # Internal encoding implementation - converts numbers to a hash string.
@@ -251,7 +245,6 @@ module EncodedId
         lottery = current_alphabet[hash_int % alphabet_length]
 
         # This array will hold the final hash as character ordinals (codepoints).
-        # Start with the lottery character.
         # @type var hashid_code: Array[Integer]
         hashid_code = []
         hashid_code << lottery
@@ -275,7 +268,6 @@ module EncodedId
           consistent_shuffle!(current_alphabet, seasoning, alphabet_buffer, alphabet_length)
 
           # Convert this number to base-N using the current shuffled alphabet.
-          # Returns the last character added (used for separator selection).
           last_char_ord = hash_one_number(hashid_code, num, current_alphabet, alphabet_length)
 
           # Add a separator between numbers (but not after the last number).
@@ -292,28 +284,29 @@ module EncodedId
         # Guards are boundary markers chosen deterministically from the guard set.
         if hashid_code.length < @min_hash_length
           # Prepend first guard based on hash_int and the lottery character.
+          guard_count = guard_ordinals.length
           first_char = hashid_code[0] #: Integer
-          hashid_code.prepend(guard_ordinals[(hash_int + first_char) % guard_ordinals.length])
+          hashid_code.prepend(guard_ordinals[(hash_int + first_char) % guard_count])
 
           # If still too short, append second guard based on hash_int and third character.
           if hashid_code.length < @min_hash_length
             # At this point hashid_code has at least 2 elements (lottery + guard), check for 3rd
             third_char = hashid_code[2]
             hashid_code << if third_char
-              guard_ordinals[(hash_int + third_char) % guard_ordinals.length]
+              guard_ordinals[(hash_int + third_char) % guard_count]
             else
               # If no third character exists, use 0 as default
-              guard_ordinals[hash_int % guard_ordinals.length]
+              guard_ordinals[hash_int % guard_count]
             end
           end
         end
 
         # Step 4: Pad with shuffled alphabet if still below minimum length.
-        half_length = current_alphabet.length.div(2)
+        half_length = alphabet_length.div(2)
 
         while hashid_code.length < @min_hash_length
           # Shuffle the alphabet using itself as the key (creates a new permutation).
-          consistent_shuffle!(current_alphabet, current_alphabet.dup, nil, current_alphabet.length)
+          consistent_shuffle!(current_alphabet, current_alphabet.dup, nil, alphabet_length)
 
           # Wrap the hash: second_half + hash + first_half
           second_half = current_alphabet[half_length..] #: Array[Integer]
@@ -381,7 +374,6 @@ module EncodedId
 
         if (breakdown = array[i])
           # Step 2: Extract the lottery character (first char) and the rest.
-          # Check if breakdown is not empty
           lottery = breakdown[0] #: String
           remainder = breakdown[1..] || "" #: String
 
@@ -409,7 +401,6 @@ module EncodedId
 
           # Step 4: Verify by re-encoding and comparing.
           # This is critical for validity: it ensures only valid hashes decode successfully.
-          # Random strings will fail this check and return an empty array.
           if encode(ret) != hash
             # @type var ret: Array[Integer]
             ret = []
@@ -453,7 +444,6 @@ module EncodedId
           break unless num > 0
         end
 
-        # Return the last character added (used for separator selection).
         char
       end
 
@@ -496,32 +486,38 @@ module EncodedId
         num
       end
 
-      # Delegate to the consistent shuffle algorithm.
-      #
-      # This deterministic shuffle is the heart of the HashID algorithm's obfuscation.
-      # It ensures that the same salt always produces the same permutation of the alphabet.
-      #
-      # @param collection_to_shuffle [Array<Integer>] The array to shuffle (modified in place)
-      # @param salt_part_1 [Array<Integer>] First part of the salt (lottery + salt, or alphabet)
-      # @param salt_part_2 [Array<Integer>?] Second part of the salt (pre-shuffle alphabet copy)
-      # @param max_salt_length [Integer] Maximum length to use from combined salt
-      # @return [Array<Integer>] The shuffled array (same object as collection_to_shuffle)
+      # Check if the encoded string contains any blocklisted words.
       #
-      # @rbs (Array[Integer] collection_to_shuffle, Array[Integer] salt_part_1, Array[Integer]? salt_part_2, Integer max_salt_length) -> Array[Integer]
-      def consistent_shuffle!(collection_to_shuffle, salt_part_1, salt_part_2, max_salt_length)
-        HashIdConsistentShuffle.shuffle!(collection_to_shuffle, salt_part_1, salt_part_2, max_salt_length)
+      # Determines if blocklist checking should be performed based on mode and ID length
+      #
+      # @param encoded_string [String] The encoded ID to check
+      # @return [Boolean] True if blocklist should be checked
+      #
+      # @rbs (String encoded_string) -> bool
+      def check_blocklist?(encoded_string)
+        return false if !blocklist || blocklist.empty?
+
+        case @blocklist_mode
+        when :always
+          true
+        when :length_threshold
+          encoded_string.length <= @blocklist_max_length
+        when :raise_if_likely
+          # This mode raises at configuration time, so if we get here, we check
+          true
+        else
+          true
+        end
       end
 
-      # Check if the encoded string contains any blocklisted words.
-      #
       # @param encoded_string [String] The encoded hash to check
       # @return [String, false] The blocklisted word if found, false otherwise
       #
       # @rbs (String encoded_string) -> (String | false)
       def contains_blocklisted_word?(encoded_string)
-        return false unless @blocklist && !@blocklist.empty?
+        return false if !blocklist || blocklist.empty?
 
-        blocked_word = @blocklist.blocks?(encoded_string)
+        blocked_word = blocklist.blocks?(encoded_string)
         return blocked_word if blocked_word
 
         false

data/lib/encoded_id/encoders/hashid_configuration.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module EncodedId
+  module Encoders
+    # Configuration for Hashids encoder
+    # Hashids requires a salt for encoding/decoding
+    class HashidConfiguration < BaseConfiguration
+      attr_reader :salt #: String
+
+      # @rbs (salt: String, **untyped options) -> void
+      def initialize(salt:, **options)
+        @salt = validate_salt(salt)
+        super(**options)
+      end
+
+      # Create the Hashid encoder instance
+      # @rbs () -> Hashid
+      def create_encoder
+        Hashid.new(salt, min_length, alphabet, blocklist, blocklist_mode, blocklist_max_length)
+      end
+
+      private
+
+      # @rbs (String salt) -> String
+      def validate_salt(salt)
+        return salt if salt.is_a?(String) && salt.size > 3
+        raise InvalidConfigurationError, "salt must be a string longer than 3 characters"
+      end
+    end
+  end
+end

data/lib/encoded_id/encoders/{hash_id_consistent_shuffle.rb → hashid_consistent_shuffle.rb}

@@ -4,9 +4,9 @@
 
 module EncodedId
   module Encoders
-    # Implements a deterministic, salt-based shuffle algorithm for HashIDs.
+    # Implements a deterministic, salt-based shuffle algorithm for Hashids.
     #
-    # This is the core obfuscation mechanism that makes HashIDs non-sequential.
+    # This is the core obfuscation mechanism that makes Hashids non-sequential.
     # The algorithm has several critical properties:
     #
     # 1. **Deterministic**: Same input + same salt = same output (always)
@@ -43,7 +43,7 @@ module EncodedId
     # Step 3: i=1, salt[2]=67, ord_total=131 → swap positions 1 and ((67+2+131)%1=0)→ [4,2,1,3]
     # Result: [4, 2, 1, 3]
     #
-    class HashIdConsistentShuffle
+    module HashidConsistentShuffle
       # Deterministically shuffle a collection based on a salt.
       #
       # Shuffles the collection in place using a salt-based algorithm that produces
@@ -57,7 +57,7 @@ module EncodedId
       # @raise [SaltError] If salt is too short or shuffle fails
       #
       # @rbs (Array[Integer] collection_to_shuffle, Array[Integer] salt_part_1, Array[Integer]? salt_part_2, Integer max_salt_length) -> Array[Integer]
-      def self.shuffle!(collection_to_shuffle, salt_part_1, salt_part_2, max_salt_length)
+      def consistent_shuffle!(collection_to_shuffle, salt_part_1, salt_part_2, max_salt_length)
         salt_part_1_length = salt_part_1.length
 
         # Validate we have enough salt. If max_salt_length exceeds salt_part_1,

data/lib/encoded_id/encoders/{hash_id_ordinal_alphabet_separator_guards.rb → hashid_ordinal_alphabet_separator_guards.rb}

@@ -39,7 +39,9 @@ module EncodedId
     # - More efficient memory usage
     # - Direct array indexing without string allocations
     #
-    class HashIdOrdinalAlphabetSeparatorGuards
+    class HashidOrdinalAlphabetSeparatorGuards
+      include HashidConsistentShuffle
+
       # Target ratio of alphabet to separators (alphabet.length / seps.length ≈ 3.5)
       SEP_DIV = 3.5
 
@@ -75,16 +77,10 @@ module EncodedId
       #
       # @rbs (Alphabet alphabet, String salt) -> void
       def initialize(alphabet, salt)
-        # Convert alphabet and salt to arrays of ordinals (integer codepoints).
         @alphabet = alphabet.characters.chars.map(&:ord)
         @salt = salt.chars.map(&:ord)
 
-        # Partition the alphabet into separators and alphabet.
-        # This ensures they're disjoint and properly balanced.
         setup_seps
-
-        # Extract guards from either separators or alphabet.
-        # Guards are boundary markers used for minimum length padding.
         setup_guards
 
         # Pre-compute escaped versions for String#tr operations during decode.
@@ -93,7 +89,6 @@ module EncodedId
         @seps_tr_selector = escape_characters_string_for_tr(@seps.map(&:chr))
         @guards_tr_selector = escape_characters_string_for_tr(@guards.map(&:chr))
 
-        # Freeze all arrays to prevent accidental modification.
         @alphabet.freeze
         @seps.freeze
         @guards.freeze
@@ -146,39 +141,33 @@ module EncodedId
       def setup_seps
         @seps = DEFAULT_SEPS.dup
 
-        # Make alphabet and separators disjoint.
-        # For each separator:
-        # - If it exists in the alphabet, remove it from the alphabet
-        # - If it doesn't exist in the alphabet, remove it from separators
-        # This ensures separators only contains characters from the original alphabet.
-        @seps.length.times do |i|
-          if (j = @alphabet.index(@seps[i]))
-            # Separator exists in alphabet - remove it from alphabet.
-            @alphabet = pick_characters(@alphabet, j)
+        # Make alphabet and separators disjoint: keep separator if it exists in alphabet,
+        # otherwise remove it. This ensures separators only contains characters from the original alphabet.
+        @seps.length.times do |sep_index|
+          if (alphabet_index = @alphabet.index(@seps[sep_index]))
+            @alphabet = remove_character_at(@alphabet, alphabet_index)
           else
-            # Separator doesn't exist in alphabet - remove it from separators.
-            @seps = pick_characters(@seps, i)
+            @seps = remove_character_at(@seps, sep_index)
           end
         end
 
-        # Remove any space characters introduced by pick_characters.
-        # Spaces are placeholders and shouldn't appear in the final sets.
+        # Remove space placeholders introduced by remove_character_at
         @alphabet.delete(SPACE_CHAR)
         @seps.delete(SPACE_CHAR)
 
-        # Shuffle separators deterministically using the salt.
-        consistent_shuffle!(@seps, @salt, nil, @salt.length)
+        salt_length = @salt.length
+        consistent_shuffle!(@seps, @salt, nil, salt_length)
 
-        # Balance the alphabet-to-separator ratio to approximately SEP_DIV (3.5:1).
-        # This ensures we have enough separators for good distribution in multi-number hashes.
-        if @seps.length == 0 || (@alphabet.length / @seps.length.to_f) > SEP_DIV
-          # Calculate target separator count based on alphabet size.
-          seps_length = (@alphabet.length / SEP_DIV).ceil
-          seps_length = 2 if seps_length == 1 # Minimum 2 separators
+        # Balance the alphabet-to-separator ratio to approximately SEP_DIV (3.5:1)
+        alphabet_length = @alphabet.length
+        seps_count = @seps.length
+        if seps_count == 0 || (alphabet_length / seps_count.to_f) > SEP_DIV
+          seps_target_count = (alphabet_length / SEP_DIV).ceil
+          seps_target_count = 2 if seps_target_count == 1 # Minimum 2 separators
 
-          if seps_length > @seps.length
+          if seps_target_count > seps_count
             # Not enough separators - take some from the alphabet.
-            diff = seps_length - @seps.length
+            diff = seps_target_count - seps_count
 
             # These are safe: diff > 0 and @alphabet has enough elements by design
             additonal_seps = @alphabet[0, diff] #: Array[Integer]
@@ -186,13 +175,11 @@ module EncodedId
             @alphabet = @alphabet[diff..] #: Array[Integer]
           else
             # Too many separators - trim to target length.
-            @seps = @seps[0, seps_length] #: Array[Integer]
+            @seps = @seps[0, seps_target_count] #: Array[Integer]
           end
         end
 
-        # Shuffle the final alphabet deterministically using the salt.
-        # This ensures different salts produce different alphabet orderings.
-        consistent_shuffle!(@alphabet, @salt, nil, @salt.length)
+        consistent_shuffle!(@alphabet, @salt, nil, salt_length)
       end
 
       # Setup guards by extracting them from separators or alphabet.
@@ -213,10 +200,10 @@ module EncodedId
       #
       # @rbs () -> void
       def setup_guards
-        # Calculate target guard count: approximately 1/12th of alphabet length.
-        gc = (@alphabet.length / GUARD_DIV).ceil
+        alphabet_length = @alphabet.length
+        gc = (alphabet_length / GUARD_DIV).ceil
 
-        if @alphabet.length < 3
+        if alphabet_length < 3
           # Very small alphabet - take guards from separators to preserve alphabet.
           @guards = @seps[0, gc] #: Array[Integer]
           @seps = @seps[gc..] || [] #: Array[Integer]
@@ -227,7 +214,7 @@ module EncodedId
         end
       end
 
-      # Remove a character from an array by replacing it with a space.
+      # Remove a character from an array by replacing it with a space placeholder.
       #
       # This is used during the separator/alphabet disjoint operation.
       # Instead of mutating the array in place, it creates a new array with:
@@ -239,32 +226,19 @@ module EncodedId
       # This approach maintains array indices during iteration.
       #
       # Example:
-      #   pick_characters([97, 98, 99], 1) → [97, 32, 99]  # [a, space, c]
+      #   remove_character_at([97, 98, 99], 1) → [97, 32, 99]  # [a, space, c]
       #
       # @param array [Array<Integer>] The array to remove from
       # @param index [Integer] The index of the character to remove
       # @return [Array<Integer>] New array with character replaced by space
       #
       # @rbs (Array[Integer] array, Integer index) -> Array[Integer]
-      def pick_characters(array, index)
+      def remove_character_at(array, index)
         tail = array[index + 1..]
         head = array[0, index] || []
         head << SPACE_CHAR
         tail ? head + tail : head
       end
-
-      # Delegate to the consistent shuffle algorithm.
-      #
-      # @param collection_to_shuffle [Array<Integer>] The array to shuffle (modified in place)
-      # @param salt_part_1 [Array<Integer>] The salt to use for shuffling
-      # @param salt_part_2 [Array<Integer>?] Optional second salt part (unused here)
-      # @param max_salt_length [Integer] Maximum salt length to use
-      # @return [Array<Integer>] The shuffled array
-      #
-      # @rbs (Array[Integer] collection_to_shuffle, Array[Integer] salt_part_1, Array[Integer]? salt_part_2, Integer max_salt_length) -> Array[Integer]
-      def consistent_shuffle!(collection_to_shuffle, salt_part_1, salt_part_2, max_salt_length)
-        HashIdConsistentShuffle.shuffle!(collection_to_shuffle, salt_part_1, salt_part_2, max_salt_length)
-      end
     end
   end
 end

data/lib/encoded_id/encoders/{hash_id_salt.rb → hashid_salt.rb}

@@ -14,13 +14,13 @@ module EncodedId
     #
     # == Security Note:
     #
-    # The salt is the 'secret' that makes your HashIDs unique. Without knowing the
+    # The salt is the 'secret' that makes your Hashids unique. Without knowing the
     # salt, it's harder to reverse-engineer the encoding scheme
-    # or predict hash values BUT HashIDs is not a secure encryption technique. It
+    # or predict hash values BUT Hashids is not a secure encryption technique. It
     # is only to be used to obfuscate values which are not secure (you would just
     # prefer the average person cannot see them).
     #
-    class HashIdSalt
+    class HashidSalt
       # @rbs @salt: String
       # @rbs @chars: Array[String]