encoded_id 1.0.0.rc6 → 1.0.0.rc7

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]
 

data/lib/encoded_id/encoders/my_sqids.rb

@@ -20,17 +20,14 @@ class MySqids
   # @rbs @min_length: Integer
   # @rbs @blocklist: (Array[String] | Set[String])
 
-  # @rbs self.@DEFAULT_ALPHABET: String
   DEFAULT_ALPHABET = "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789"
 
   # Default minimum length of 0 means no padding is applied to generated IDs
-  # @rbs self.@DEFAULT_MIN_LENGTH: Integer
   DEFAULT_MIN_LENGTH = 0
   # rubocop:disable Metrics/CollectionLiteralLength, Layout/LineLength
   # Default blocklist containing words that should not appear in generated IDs
   # The blocklist prevents offensive or inappropriate words from appearing in IDs by
   # regenerating IDs that contain these patterns.
-  # @rbs self.@DEFAULT_BLOCKLIST: Array[String]
   DEFAULT_BLOCKLIST = %w[0rgasm 1d10t 1d1ot 1di0t 1diot 1eccacu10 1eccacu1o 1eccacul0
     1eccaculo 1mbec11e 1mbec1le 1mbeci1e 1mbecile a11upat0 a11upato a1lupat0 a1lupato aand ah01e ah0le aho1e ahole al1upat0 al1upato allupat0 allupato ana1 ana1e anal anale anus arrapat0 arrapato arsch arse ass b00b b00be b01ata b0ceta b0iata b0ob b0obe b0sta b1tch b1te b1tte ba1atkar balatkar bastard0 bastardo batt0na battona bitch bite bitte bo0b bo0be bo1ata boceta boiata boob boobe bosta bran1age bran1er bran1ette bran1eur bran1euse branlage branler branlette branleur branleuse c0ck c0g110ne c0g11one c0g1i0ne c0g1ione c0gl10ne c0gl1one c0gli0ne c0glione c0na c0nnard c0nnasse c0nne c0u111es c0u11les c0u1l1es c0u1lles c0ui11es c0ui1les c0uil1es c0uilles c11t c11t0 c11to c1it c1it0 c1ito cabr0n cabra0 cabrao cabron caca cacca cacete cagante cagar cagare cagna cara1h0 cara1ho caracu10 caracu1o caracul0 caraculo caralh0 caralho cazz0 cazz1mma cazzata cazzimma cazzo ch00t1a ch00t1ya ch00tia ch00tiya ch0d ch0ot1a ch0ot1ya ch0otia ch0otiya ch1asse ch1avata ch1er ch1ng0 ch1ngadaz0s ch1ngadazos ch1ngader1ta ch1ngaderita ch1ngar ch1ngo ch1ngues ch1nk chatte chiasse chiavata chier ching0 chingadaz0s chingadazos chingader1ta chingaderita chingar chingo chingues chink cho0t1a cho0t1ya cho0tia cho0tiya chod choot1a choot1ya chootia chootiya cl1t cl1t0 cl1to clit clit0 clito cock cog110ne cog11one cog1i0ne cog1ione cogl10ne cogl1one cogli0ne coglione cona connard connasse conne cou111es cou11les cou1l1es cou1lles coui11es coui1les couil1es couilles cracker crap cu10 cu1att0ne cu1attone cu1er0 cu1ero cu1o cul0 culatt0ne culattone culer0 culero culo cum cunt d11d0 d11do d1ck d1ld0 d1ldo damn de1ch deich depp di1d0 di1do dick dild0 dildo dyke encu1e encule enema enf01re enf0ire enfo1re enfoire estup1d0 estup1do estupid0 estupido etr0n etron f0da f0der f0ttere f0tters1 f0ttersi f0tze f0utre f1ca f1cker f1ga fag fica ficker figa foda foder fottere fotters1 fottersi fotze foutre fr0c10 fr0c1o fr0ci0 fr0cio fr0sc10 fr0sc1o fr0sci0 fr0scio froc10 froc1o froci0 frocio frosc10 frosc1o frosci0 froscio fuck g00 g0o g0u1ne g0uine gandu go0 goo gou1ne gouine gr0gnasse grognasse haram1 harami haramzade hund1n hundin id10t id1ot idi0t idiot imbec11e imbec1le imbeci1e imbecile j1zz jerk jizz k1ke kam1ne kamine kike leccacu10 leccacu1o leccacul0 leccaculo m1erda m1gn0tta m1gnotta m1nch1a m1nchia m1st mam0n mamahuev0 mamahuevo mamon masturbat10n masturbat1on masturbate masturbati0n masturbation merd0s0 merd0so merda merde merdos0 merdoso mierda mign0tta mignotta minch1a minchia mist musch1 muschi n1gger neger negr0 negre negro nerch1a nerchia nigger orgasm p00p p011a p01la p0l1a p0lla p0mp1n0 p0mp1no p0mpin0 p0mpino p0op p0rca p0rn p0rra p0uff1asse p0uffiasse p1p1 p1pi p1r1a p1rla p1sc10 p1sc1o p1sci0 p1scio p1sser pa11e pa1le pal1e palle pane1e1r0 pane1e1ro pane1eir0 pane1eiro panele1r0 panele1ro paneleir0 paneleiro patakha pec0r1na pec0rina pecor1na pecorina pen1s pendej0 pendejo penis pip1 pipi pir1a pirla pisc10 pisc1o pisci0 piscio pisser po0p po11a po1la pol1a polla pomp1n0 pomp1no pompin0 pompino poop porca porn porra pouff1asse pouffiasse pr1ck prick pussy put1za puta puta1n putain pute putiza puttana queca r0mp1ba11e r0mp1ba1le r0mp1bal1e r0mp1balle r0mpiba11e r0mpiba1le r0mpibal1e r0mpiballe rand1 randi rape recch10ne recch1one recchi0ne recchione retard romp1ba11e romp1ba1le romp1bal1e romp1balle rompiba11e rompiba1le rompibal1e rompiballe ruff1an0 ruff1ano ruffian0 ruffiano s1ut sa10pe sa1aud sa1ope sacanagem sal0pe salaud salope saugnapf sb0rr0ne sb0rra sb0rrone sbattere sbatters1 sbattersi sborr0ne sborra sborrone sc0pare sc0pata sch1ampe sche1se sche1sse scheise scheisse schlampe schwachs1nn1g schwachs1nnig schwachsinn1g schwachsinnig schwanz scopare scopata sexy sh1t shit slut sp0mp1nare sp0mpinare spomp1nare spompinare str0nz0 str0nza str0nzo stronz0 stronza stronzo stup1d stupid succh1am1 succh1ami succhiam1 succhiami sucker t0pa tapette test1c1e test1cle testic1e testicle tette topa tr01a tr0ia tr0mbare tr1ng1er tr1ngler tring1er tringler tro1a troia trombare turd twat vaffancu10 vaffancu1o vaffancul0 vaffanculo vag1na vagina verdammt verga w1chsen wank wichsen x0ch0ta x0chota xana xoch0ta xochota z0cc01a z0cc0la z0cco1a z0ccola z1z1 z1zi ziz1 zizi zocc01a zocc0la zocco1a zoccola].freeze
   # rubocop:enable Metrics/CollectionLiteralLength, Layout/LineLength
@@ -83,23 +80,15 @@ class MySqids
         "Minimum length has to be between 0 and #{min_length_limit}"
     end
 
-    # Filter the blocklist to only include words that:
-    # 1. Are at least 3 characters long
-    # 2. Only contain characters that exist in the alphabet (case-insensitive)
-    # This ensures we don't try to block words that could never appear in generated IDs
     filtered_blocklist = if options[:blocklist].nil? && options[:alphabet].nil?
-      # If using default blocklist and alphabet, skip filtering since we know it's valid
       blocklist
     else
       downcased_alphabet = alphabet.map(&:downcase)
-      # Only keep words that can be formed from the alphabet
       blocklist.select do |word|
         word.length >= 3 && (word.downcase.chars - downcased_alphabet).empty?
       end.to_set(&:downcase)
     end
 
-    # Store the alphabet as an array of integer codepoints after shuffling
-    # Shuffling ensures the alphabet order is unique to this instance
     @alphabet = shuffle(alphabet.map(&:ord))
     @min_length = min_length
     @blocklist = filtered_blocklist
@@ -128,7 +117,10 @@ class MySqids
     return "" if numbers.empty?
 
     # Validate that all numbers are within the acceptable range
-    in_range_numbers = numbers.filter_map { |n| i = n.to_i; i if i.between?(0, MAX_INT) }
+    in_range_numbers = numbers.filter_map { |n|
+      i = n.to_i
+      i if i.between?(0, MAX_INT)
+    }
     unless in_range_numbers.length == numbers.length
       raise ArgumentError,
         "Encoding supports numbers between 0 and #{MAX_INT}"
@@ -161,8 +153,7 @@ class MySqids
 
     return ret if id.empty?
 
-    # Convert string to array of character codepoints for processing
-    id = id.chars.map(&:ord)
+    id = id.codepoints
 
     # Validate that all characters in the ID exist in our alphabet
     # If any character is invalid, return empty array
@@ -291,7 +282,6 @@ class MySqids
     offset = (offset + increment) % alphabet_length
 
     prefix = @alphabet[offset]
-    # Now working with modified alphabet
     alphabet = rotate_and_reverse_alphabet(@alphabet, offset)
     id = [prefix]
 
@@ -352,7 +342,6 @@ class MySqids
     while true # rubocop:disable Style/InfiniteLoop
       new_char_index = (result % alphabet_length) + 1
       new_char = alphabet[new_char_index]
-      # id is an array, we want to insert the new char at the start_index position.
       id.insert(start_index, new_char)
       result /= alphabet_length
       break if result <= 0

data/lib/encoded_id/encoders/sqids.rb

@@ -4,27 +4,44 @@
 
 module EncodedId
   module Encoders
-    class Sqids < Base
+    # Encoder implementation using the Sqids algorithm for encoding/decoding IDs.
+    class Sqids
       # @rbs @sqids: untyped
+      # @rbs @min_hash_length: Integer
+      # @rbs @alphabet: Alphabet
+      # @rbs @blocklist: Blocklist
+      # @rbs @blocklist_mode: Symbol
+      # @rbs @blocklist_max_length: Integer
 
-      # @rbs (String salt, ?Integer min_hash_length, ?Alphabet alphabet, ?Blocklist blocklist) -> void
-      def initialize(salt, min_hash_length = 0, alphabet = Alphabet.alphanum, blocklist = Blocklist.empty)
-        super
-        @sqids = ::MySqids.new(
+      # @rbs (?Integer min_hash_length, ?Alphabet alphabet, ?Blocklist blocklist, ?Symbol blocklist_mode, ?Integer blocklist_max_length) -> void
+      def initialize(min_hash_length = 0, alphabet = Alphabet.alphanum, blocklist = Blocklist.empty, blocklist_mode = :length_threshold, blocklist_max_length = 32)
+        @min_hash_length = min_hash_length
+        @alphabet = alphabet
+        @blocklist = blocklist
+        @blocklist_mode = blocklist_mode
+        @blocklist_max_length = blocklist_max_length
+
+        @sqids = ::SqidsWithBlocklistMode.new(
           {
             min_length: min_hash_length,
             alphabet: alphabet.characters,
-            blocklist: blocklist
+            blocklist: blocklist,
+            blocklist_mode: blocklist_mode,
+            blocklist_max_length: blocklist_max_length
           }
         )
-      rescue TypeError, ArgumentError => e
-        raise InvalidInputError, "unable to create sqids instance: #{e.message}"
+      rescue TypeError, ArgumentError => error
+        raise InvalidInputError, "unable to create sqids instance: #{error.message}"
       end
 
+      attr_reader :min_hash_length #: Integer
+      attr_reader :alphabet #: Alphabet
+      attr_reader :blocklist #: Blocklist
+
       # @rbs (Array[Integer] numbers) -> String
       def encode(numbers)
-        numbers.all? { |n| Integer(n) } # raises if conversion fails
-        return "" if numbers.empty? || numbers.any? { |n| n < 0 }
+        numbers.all? { Integer(_1) } # raises if conversion fails
+        return "" if numbers.empty? || numbers.any?(&:negative?)
 
         @sqids.encode(numbers)
       end

data/lib/encoded_id/encoders/sqids_configuration.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module EncodedId
+  module Encoders
+    # Configuration for Sqids encoder
+    # Sqids does not use a salt - it shuffles the alphabet deterministically
+    class SqidsConfiguration < BaseConfiguration
+      # @rbs () -> Symbol
+      def encoder_type
+        :sqids
+      end
+
+      # Create the Sqids encoder instance
+      # @rbs () -> Sqids
+      def create_encoder
+        Sqids.new(min_length, alphabet, blocklist, blocklist_mode, blocklist_max_length)
+      end
+    end
+  end
+end

data/lib/encoded_id/encoders/sqids_with_blocklist_mode.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+# Extension of MySqids (vendored Sqids) that adds blocklist mode support.
+# This subclass overrides blocklist checking to support different modes
+# without modifying the vendored library.
+# In the future, the base class can be changed from MySqids to ::Sqids::Sqids
+# once we use the official gem.
+class SqidsWithBlocklistMode < MySqids
+  # @rbs @blocklist_mode: Symbol
+  # @rbs @blocklist_max_length: Integer
+
+  # @rbs (?Hash[Symbol, untyped] options) -> void
+  def initialize(options = {})
+    @blocklist_mode = options[:blocklist_mode] || :length_threshold
+    @blocklist_max_length = options[:blocklist_max_length] || 32
+
+    # Remove our custom options before passing to parent
+    parent_options = options.dup
+    parent_options.delete(:blocklist_mode)
+    parent_options.delete(:blocklist_max_length)
+
+    super(parent_options)
+  end
+
+  private
+
+  # Override blocked_id? to implement blocklist mode logic
+  # @rbs (String id) -> bool
+  def blocked_id?(id)
+    return false unless check_blocklist?(id)
+
+    super
+  end
+
+  # Determines if blocklist checking should be performed based on mode and ID length
+  # @rbs (String id) -> bool
+  def check_blocklist?(id)
+    return false if @blocklist.empty?
+
+    case @blocklist_mode
+    when :always
+      true
+    when :length_threshold
+      id.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
+end

data/lib/encoded_id/hex_representation.rb

@@ -37,7 +37,6 @@ module EncodedId
       hex_digit_encoding_group_size
     end
 
-    # Convert hex strings to integer representations
     # @rbs (encodeableHexValue hexs) -> Array[Integer]
     def integer_representation(hexs)
       inputs = Array(hexs).map(&:to_s)
@@ -48,12 +47,10 @@ module EncodedId
         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
     # @rbs (Array[Integer] integers) -> Array[String]
     def integers_to_hex_strings(integers)
       hex_strings = [] #: Array[String]
@@ -66,12 +63,12 @@ module EncodedId
           hex_string = []
           add_leading = false
         else
+          # Add leading zeros to maintain group size for all groups except the first
           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
@@ -96,12 +93,12 @@ module EncodedId
     # @rbs (String hex_string_cleaned) -> Array[Integer]
     def convert_to_integer_groups(hex_string_cleaned)
       groups = [] #: Array[Array[String]]
-      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)
+      hex_string_cleaned.chars.reverse.each_with_index do |char, index|
+        group_id = index / @hex_digit_encoding_group_size
+        group = (groups[group_id] ||= [])
+        group.unshift(char)
       end
-      groups.map { |c| c.join.to_i(16) }
+      groups.map { _1.join.to_i(16) }
     end
   end
 end

data/lib/encoded_id/reversible_id.rb

@@ -10,53 +10,77 @@ module EncodedId
   #   type encodeableValue = Array[String | Integer] | String | Integer
 
   class ReversibleId
-    # @rbs VALID_ENCODERS: Array[Symbol]
-    VALID_ENCODERS = [:hashids, :sqids].freeze
-    # @rbs DEFAULT_ENCODER: Symbol
-    DEFAULT_ENCODER = :hashids
-
-    # @rbs @alphabet: Alphabet
-    # @rbs @salt: String
-    # @rbs @length: Integer
-    # @rbs @split_at: Integer?
-    # @rbs @split_with: String?
+    # @rbs @config: Encoders::BaseConfiguration
     # @rbs @hex_represention_encoder: HexRepresentation
-    # @rbs @max_length: Integer?
-    # @rbs @max_inputs_per_id: Integer
-    # @rbs @blocklist: Blocklist
-    # @rbs @encoder: Encoders::Base
-
-    # @rbs (salt: String, ?length: Integer, ?split_at: Integer?, ?split_with: String?, ?alphabet: Alphabet, ?hex_digit_encoding_group_size: Integer, ?max_length: Integer?, ?max_inputs_per_id: Integer, ?encoder: Symbol | Encoders::Base, ?blocklist: Blocklist | Array[String] | Set[String] | nil) -> void
-    def initialize(salt:, length: 8, split_at: 4, split_with: "-", alphabet: Alphabet.modified_crockford, hex_digit_encoding_group_size: 4, max_length: 128, max_inputs_per_id: 32, encoder: DEFAULT_ENCODER, blocklist: Blocklist.empty)
-      @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)
-      @max_length = validate_max_length(max_length)
-      @max_inputs_per_id = validate_max_input(max_inputs_per_id)
-      @blocklist = validate_blocklist(blocklist)
-      @encoder = create_encoder(validate_encoder(encoder))
-    end
-
-    # Accessors for introspection
-    attr_reader :salt #: String
-    attr_reader :length #: Integer
-    attr_reader :alphabet #: Alphabet
-    attr_reader :split_at #: Integer?
-    attr_reader :split_with #: String?
-    attr_reader :hex_represention_encoder #: HexRepresentation
-    attr_reader :max_length #: Integer?
-    attr_reader :blocklist #: Blocklist
-    attr_reader :encoder #: Encoders::Base
+    # @rbs @encoder: untyped
+
+    # Factory method to create a Hashid-based reversible ID
+    # @rbs (salt: String, **untyped options) -> ReversibleId
+    def self.hashid(salt:, **options)
+      new(Encoders::HashidConfiguration.new(salt: salt, **options))
+    end
+
+    # Factory method to create a Sqids-based reversible ID (default)
+    # @rbs (**untyped options) -> ReversibleId
+    def self.sqids(**options)
+      new(Encoders::SqidsConfiguration.new(**options))
+    end
+
+    # Initialize with a configuration object
+    # Defaults to Sqids configuration if called with no arguments
+    # @rbs (?Encoders::BaseConfiguration? config) -> void
+    def initialize(config = nil)
+      @config = config || Encoders::SqidsConfiguration.new
+
+      unless @config.is_a?(Encoders::BaseConfiguration)
+        raise InvalidConfigurationError, "config must be an instance of Encoders::BaseConfiguration (or nil for default Sqids)"
+      end
+
+      @hex_represention_encoder = HexRepresentation.new(@config.hex_digit_encoding_group_size)
+      @encoder = create_encoder
+    end
+
+    # @rbs () -> String?
+    def salt
+      config = @config
+      return config.salt if config.is_a?(Encoders::HashidConfiguration)
+      nil
+    end
+
+    def min_length
+      @config.min_length
+    end
+
+    def alphabet
+      @config.alphabet
+    end
+
+    def split_at
+      @config.split_at
+    end
+
+    def split_with
+      @config.split_with
+    end
+
+    attr_reader :hex_represention_encoder
+
+    def max_length
+      @config.max_length
+    end
+
+    def blocklist
+      @config.blocklist
+    end
+
+    attr_reader :encoder #: untyped
 
     # Encode the input values into a hash
     # @rbs (encodeableValue values) -> String
     def encode(values)
       inputs = prepare_input(values)
       encoded_id = encoder.encode(inputs)
-      encoded_id = humanize_length(encoded_id) if split_with && split_at
+      encoded_id = humanize_length(encoded_id) if @config.split_with && @config.split_at
 
       raise EncodedIdLengthError if max_length_exceeded?(encoded_id)
 
@@ -66,155 +90,78 @@ module EncodedId
     # Encode hex strings into a hash
     # @rbs (encodeableHexValue hexs) -> String
     def encode_hex(hexs)
-      encode(hex_represention_encoder.hex_as_integers(hexs))
+      encode(@hex_represention_encoder.hex_as_integers(hexs))
     end
 
     # Decode the hash to original array
     # @rbs (String str, ?downcase: bool) -> Array[Integer]
-    def decode(str, downcase: true)
+    def decode(str, downcase: false)
       raise EncodedIdFormatError, "Max length of input exceeded" if max_length_exceeded?(str)
 
       encoder.decode(convert_to_hash(str, downcase))
-    rescue InvalidInputError => e
-      raise EncodedIdFormatError, e.message
+    rescue InvalidInputError => error
+      raise EncodedIdFormatError, error.message
     end
 
     # Decode hex strings from a hash
     # @rbs (String str, ?downcase: bool) -> Array[String]
-    def decode_hex(str, downcase: true)
+    def decode_hex(str, downcase: false)
       integers = encoder.decode(convert_to_hash(str, downcase))
-      hex_represention_encoder.integers_as_hex(integers)
+      @hex_represention_encoder.integers_as_hex(integers)
     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 (String salt) -> String
-    def validate_salt(salt)
-      return salt if salt.is_a?(String) && salt.size > 3
-      raise InvalidConfigurationError, "Salt must be a string and longer than 3 characters"
-    end
-
-    # Target length of the encoded string (the minimum but not maximum length)
-    # @rbs (Integer length) -> Integer
-    def validate_length(length)
-      return length if valid_integer_option?(length)
-      raise InvalidConfigurationError, "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"
-    end
-
-    # @rbs (Integer max_inputs_per_id) -> Integer
-    def validate_max_input(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
-
-    # Split the encoded string into groups of this size
-    # @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 and 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 (encodeableValue value) -> Array[Integer]
     def prepare_input(value)
       inputs = value.is_a?(Array) ? value.map(&:to_i) : [value.to_i]
       raise ::EncodedId::InvalidInputError, "Cannot encode an empty array" if inputs.empty?
       raise ::EncodedId::InvalidInputError, "Integer IDs to be encoded can only be positive" if inputs.any?(&:negative?)
-
-      raise ::EncodedId::InvalidInputError, "%d integer IDs provided, maximum amount of IDs is %d" % [inputs.length, @max_inputs_per_id] if inputs.length > @max_inputs_per_id
+      raise ::EncodedId::InvalidInputError, "%d integer IDs provided, maximum amount of IDs is %d" % [inputs.length, @config.max_inputs_per_id] if inputs.length > @config.max_inputs_per_id
 
       inputs
     end
 
-    # @rbs (Symbol | Encoders::Base encoder) -> Encoders::Base
-    def create_encoder(encoder)
-      # If an encoder instance was provided, return it directly
-      return @encoder if defined?(@encoder) && @encoder.is_a?(Encoders::Base)
-      return encoder if encoder.is_a?(Encoders::Base)
-
-      case encoder
-      when :sqids
-        if defined?(Encoders::Sqids)
-          Encoders::Sqids.new(salt, length, alphabet, @blocklist)
-        else
-          raise InvalidConfigurationError, "Sqids encoder requested but the sqids gem is not available. Please add 'gem \"sqids\"' to your Gemfile."
-        end
-      when :hashids
-        Encoders::HashId.new(salt, length, alphabet, @blocklist)
-      else
-        raise InvalidConfigurationError, "The encoder name is not supported '#{encoder}'"
-      end
-    end
-
-    # @rbs (Symbol | Encoders::Base encoder) -> (Symbol | Encoders::Base)
-    def validate_encoder(encoder)
-      # Accept either a valid symbol or an Encoders::Base instance
-      return encoder if VALID_ENCODERS.include?(encoder) || encoder.is_a?(Encoders::Base)
-      raise InvalidConfigurationError, "Encoder must be one of: #{VALID_ENCODERS.join(", ")} or an instance of EncodedId::Encoders::Base"
-    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 an instance of Blocklist, a Set, or an Array of strings"
+    # @rbs () -> untyped
+    def create_encoder
+      @config.create_encoder
     end
 
+    # Splits long encoded strings into groups for readability
+    # e.g., "ABCDEFGH" with split_at=4, split_with="-" becomes "ABCD-EFGH"
     # @rbs (String hash) -> String
     def humanize_length(hash)
       len = hash.length
-      at = split_at #: Integer
-      with = split_with #: String
+      at = @config.split_at #: Integer
+      with = @config.split_with #: String
       return hash if len <= at
 
       separator_count = (len - 1) / at
       result = hash.dup
       insert_offset = 0
-      (1..separator_count).each do |i|
-        insert_pos = i * at + insert_offset
+      (1..separator_count).each do |separator_index|
+        insert_pos = separator_index * at + insert_offset
         result.insert(insert_pos, with)
         insert_offset += with.length
       end
       result
     end
 
+    # Reverses humanize_length transformation: removes separators and optionally downcases
     # @rbs (String str, bool downcase) -> String
     def convert_to_hash(str, downcase)
-      str = str.gsub(split_with, "") if split_with
+      str = str.gsub(@config.split_with, "") if @config.split_with
       str = str.downcase if downcase
       map_equivalent_characters(str)
     end
 
+    # Maps equivalent characters based on alphabet configuration (e.g., 'O' -> '0', 'I' -> '1')
     # @rbs (String str) -> String
     def map_equivalent_characters(str)
-      return str unless alphabet.equivalences
+      equivalences = @config.alphabet.equivalences
+      return str unless equivalences
 
-      alphabet.equivalences.reduce(str) do |cleaned, ceq|
+      equivalences.reduce(str) do |cleaned, ceq|
         from, to = ceq
         cleaned.tr(from, to)
       end
@@ -222,9 +169,9 @@ module EncodedId
 
     # @rbs (String str) -> bool
     def max_length_exceeded?(str)
-      return false if max_length.nil?
+      return false if @config.max_length.nil?
 
-      str.length > max_length
+      str.length > @config.max_length
     end
   end
 end

data/lib/encoded_id/version.rb

@@ -3,6 +3,5 @@
 # rbs_inline: enabled
 
 module EncodedId
-  # @rbs VERSION: String
-  VERSION = "1.0.0.rc6"
+  VERSION = "1.0.0.rc7"
 end

data/lib/encoded_id.rb

@@ -8,29 +8,26 @@ require_relative "encoded_id/hex_representation"
 require_relative "encoded_id/blocklist"
 
 # Load the encoder framework
-require_relative "encoded_id/encoders/base"
-require_relative "encoded_id/encoders/hash_id_salt"
-require_relative "encoded_id/encoders/hash_id_consistent_shuffle"
-require_relative "encoded_id/encoders/hash_id_ordinal_alphabet_separator_guards"
-require_relative "encoded_id/encoders/hash_id"
-
-# Only load Sqids encoder if the gem is available
-begin
-  require "sqids"
-  require_relative "encoded_id/encoders/my_sqids"
-  require_relative "encoded_id/encoders/sqids"
-rescue LoadError
-  # Sqids gem not available, encoder will not be loaded
-end
+require_relative "encoded_id/encoders/hashid_salt"
+require_relative "encoded_id/encoders/hashid_consistent_shuffle"
+require_relative "encoded_id/encoders/hashid_ordinal_alphabet_separator_guards"
+require_relative "encoded_id/encoders/hashid"
+
+require "sqids"
+# TODO: move back to only using gem once upstreamed our changes
+require_relative "encoded_id/encoders/my_sqids"
+require_relative "encoded_id/encoders/sqids_with_blocklist_mode"
+
+require_relative "encoded_id/encoders/sqids"
+
+# Load configuration classes
+require_relative "encoded_id/encoders/base_configuration"
+require_relative "encoded_id/encoders/hashid_configuration"
+require_relative "encoded_id/encoders/sqids_configuration"
 
 require_relative "encoded_id/reversible_id"
 
 # @rbs!
-#   class Integer
-#     MAX: Integer
-#   end
-#
-#   # Optional Sqids gem support
 #   module Sqids
 #     DEFAULT_BLOCKLIST: Array[String]
 #   end