encoded_id-rails 1.0.0.rc6 → 1.0.0

data/context/encoded_id.md

@@ -14,6 +14,25 @@
 - **Performance Optimized**: Uses an optimized HashIds implementation for better performance
 - **Profanity Protection**: Built-in blocklist support to prevent offensive words in generated IDs
 - **Customizable**: Configurable alphabets, lengths, and formatting options
+- **Blocklist Modes**: Three modes for controlling blocklist checking performance
+
+## Quick Reference
+
+```ruby
+# Sqids encoder (default, no salt required)
+coder = EncodedId::ReversibleId.sqids(min_length: 10)
+id = coder.encode(123)          # => "p5w9-z27j-k8"
+nums = coder.decode(id)         # => [123]
+
+# Hashids encoder (requires salt)
+coder = EncodedId::ReversibleId.hashid(salt: "my-salt", min_length: 8)
+id = coder.encode([78, 45])     # => "z2j7-0dmw"
+nums = coder.decode(id)         # => [78, 45]
+
+# UUID encoding (experimental)
+hex_id = coder.encode_hex("9a566b8b-8618-42ab-8db7-a5a0276401fd")
+uuid = coder.decode_hex(hex_id).first
+```
 
 ## Core API
 
@@ -21,30 +40,65 @@
 
 The main class for encoding and decoding IDs.
 
-#### Constructor
+#### Factory Methods (Recommended)
+
+Factory methods provide the cleanest way to create encoders:
 
 ```ruby
-EncodedId::ReversibleId.new(
-  salt:,                         # Required: String salt (min 4 chars)
-  length: 8,                     # Minimum length of encoded string
+# Sqids encoder (default, no salt required)
+coder = EncodedId::ReversibleId.sqids(
+  min_length: 10,
+  blocklist: ["bad", "words"]
+)
+
+# Hashids encoder (requires salt)
+coder = EncodedId::ReversibleId.hashid(
+  salt: "my-salt",
+  min_length: 8,
+  blocklist: ["bad", "words"]
+)
+```
+
+Both factory methods accept all configuration options described below.
+
+#### Constructor (Alternative)
+
+You can also use the constructor with explicit configuration objects:
+
+```ruby
+# Using Sqids configuration
+config = EncodedId::Encoders::SqidsConfiguration.new(
+  min_length: 8,                 # Minimum length of encoded string
   split_at: 4,                   # Split encoded string every X characters
   split_with: "-",               # Character to split with
   alphabet: EncodedId::Alphabet.modified_crockford,
   hex_digit_encoding_group_size: 4,
   max_length: 128,               # Maximum length limit
   max_inputs_per_id: 32,         # Maximum IDs to encode together
-  encoder: :hashids,             # :hashids or :sqids
-  blocklist: nil                 # Words to prevent in IDs
+  blocklist: nil,                # Words to prevent in IDs
+  blocklist_mode: :length_threshold,  # :always, :length_threshold, or :raise_if_likely
+  blocklist_max_length: 32       # Max length for :length_threshold mode
+)
+coder = EncodedId::ReversibleId.new(config)
+
+# Using Hashids configuration (requires salt)
+config = EncodedId::Encoders::HashidConfiguration.new(
+  salt: "my-salt",               # Required for Hashids (min 4 chars)
+  min_length: 8,
+  # ... other options same as above
 )
+coder = EncodedId::ReversibleId.new(config)
 ```
 
+**Note**: As of v1.0.0, the default encoder is `:sqids`. For backwards compatibility with pre-v1 versions, use `ReversibleId.hashid()`.
+
 #### Key Methods
 
 ##### encode(values)
 Encodes one or more integer IDs into an obfuscated string.
 
 ```ruby
-coder = EncodedId::ReversibleId.new(salt: "my-salt")
+coder = EncodedId::ReversibleId.sqids
 
 # Single ID
 coder.encode(123) # => "p5w9-z27j"
@@ -53,17 +107,22 @@ coder.encode(123) # => "p5w9-z27j"
 coder.encode([78, 45]) # => "z2j7-0dmw"
 ```
 
-##### decode(encoded_id, downcase: true)
+##### decode(encoded_id, downcase: false)
 Decodes an encoded string back to original IDs.
 
 ```ruby
 coder.decode("p5w9-z27j") # => [123]
 coder.decode("z2j7-0dmw") # => [78, 45]
 
-# Handles confused characters
-coder.decode("p5w9-z27J") # => [123]
+# Case-sensitive by default (v1.0.0+)
+coder.decode("p5w9-z27J") # => [] (case doesn't match)
+
+# For case-insensitive matching (pre-v1 behavior)
+coder.decode("p5w9-z27J", downcase: true) # => [123]
 ```
 
+**Note**: As of v1.0.0, decoding is case-sensitive by default (`downcase: false`). Set `downcase: true` for backwards compatibility.
+
 ##### encode_hex(hex_strings) (Experimental)
 Encodes hexadecimal strings (like UUIDs).
 
@@ -73,19 +132,19 @@ coder.encode_hex("9a566b8b-8618-42ab-8db7-a5a0276401fd")
 # => "5jjy-c8d9-hxp2-qsve-rgh9-rxnt-7nb5-tve7-bf84-vr"
 
 # With larger group size for shorter output
-coder = EncodedId::ReversibleId.new(
-  salt: "my-salt", 
-  hex_digit_encoding_group_size: 32
-)
+coder = EncodedId::ReversibleId.sqids(hex_digit_encoding_group_size: 32)
 coder.encode_hex("9a566b8b-8618-42ab-8db7-a5a0276401fd")
 # => "vr7m-qra8-m5y6-dkgj-5rqr-q44e-gp4a-52"
 ```
 
-##### decode_hex(encoded_id, downcase: true) (Experimental)
+##### decode_hex(encoded_id, downcase: false) (Experimental)
 Decodes back to hexadecimal strings.
 
 ```ruby
 coder.decode_hex("w72a-y0az") # => ["10f8c"]
+
+# For case-insensitive decoding (pre-v1 behavior)
+coder.decode_hex("W72A-Y0AZ", downcase: true) # => ["10f8c"]
 ```
 
 ### EncodedId::Alphabet
@@ -116,62 +175,127 @@ alphabet = EncodedId::Alphabet.new(
 
 # Greek alphabet example
 alphabet = EncodedId::Alphabet.new("αβγδεζηθικλμνξοπρστυφχψω")
-coder = EncodedId::ReversibleId.new(salt: "my-salt", alphabet: alphabet)
+coder = EncodedId::ReversibleId.sqids(alphabet: alphabet)
 coder.encode(123) # => "θεαψ-ζκυο"
 ```
 
+### EncodedId::Blocklist
+
+Class for managing profanity/word blocklists.
+
+#### Predefined Blocklists
+
+```ruby
+# Empty blocklist (no filtering)
+EncodedId::Blocklist.empty
+
+# Minimal blocklist (~50 common profane words)
+EncodedId::Blocklist.minimal
+
+# Full Sqids default blocklist (comprehensive)
+EncodedId::Blocklist.sqids_blocklist
+
+# Use in configuration
+coder = EncodedId::ReversibleId.sqids(
+  blocklist: EncodedId::Blocklist.minimal
+)
+```
+
+#### Custom Blocklists
+
+```ruby
+# From array
+blocklist = EncodedId::Blocklist.new(["bad", "offensive", "words"])
+
+# Merge blocklists
+combined = EncodedId::Blocklist.minimal.merge(
+  EncodedId::Blocklist.new(["custom", "words"])
+)
+
+# Filter for specific alphabet (automatic with configuration)
+filtered = blocklist.filter_for_alphabet(EncodedId::Alphabet.modified_crockford)
+```
+
+**Note**: Blocklists are automatically filtered to only include words possible with your configured alphabet. This optimization improves performance.
+
 ## Configuration Options
 
 ### Basic Options
 
-- **salt**: Required secret salt (minimum 4 characters). Changing the salt changes all encoded IDs
-- **length**: Minimum length of encoded string (default: 8)
+- **min_length**: Minimum length of encoded string (default: 8)
 - **max_length**: Maximum allowed length (default: 128) to prevent DoS attacks
 - **max_inputs_per_id**: Maximum IDs encodable together (default: 32)
+- **hex_digit_encoding_group_size**: Group size for hex encoding (default: 4)
 
 ### Encoder Selection
 
 ```ruby
-# Default HashIds encoder
-coder = EncodedId::ReversibleId.new(salt: "my-salt")
+# Sqids encoder (default, no salt required)
+coder = EncodedId::ReversibleId.sqids
 
-# Sqids encoder (requires 'sqids' gem)
-coder = EncodedId::ReversibleId.new(salt: "my-salt", encoder: :sqids)
+# Hashids encoder (requires salt - minimum 4 characters)
+coder = EncodedId::ReversibleId.hashid(salt: "my-salt-minimum-4-chars")
 ```
 
-**Important**: HashIds and Sqids produce different encodings and are not compatible.
+**Important**:
+- As of v1.0.0, `:sqids` is the default encoder
+- **Sqids**: No salt required, automatically avoids blocklisted words via iteration
+- **Hashids**: Salt required (min 4 chars), raises exception if blocklisted word appears
+- HashIds and Sqids produce different encodings and are **not compatible**
+- Do NOT change encoders after going to production with existing encoded IDs
 
-### Formatting Options
+### Blocklist Configuration
+
+#### Blocklist Modes
+
+Control how blocklist checking behaves to balance performance and safety:
 
 ```ruby
-# Custom splitting
-coder = EncodedId::ReversibleId.new(
-  salt: "my-salt",
-  split_at: 3,      # Group every 3 chars
-  split_with: "."   # Use dots
+# :length_threshold (default) - Check blocklist only until encoded length reaches blocklist_max_length
+# Best for most use cases - prevents performance issues with very long IDs
+coder = EncodedId::ReversibleId.sqids(
+  blocklist: EncodedId::Blocklist.minimal,
+  blocklist_mode: :length_threshold,
+  blocklist_max_length: 32  # Stop checking after 32 characters
 )
-coder.encode(123) # => "p5w.9z2.7j"
 
-# No splitting
-coder = EncodedId::ReversibleId.new(
+# :always - Always check blocklist regardless of encoded length
+# Can be slow for long IDs or large blocklists
+coder = EncodedId::ReversibleId.hashid(
   salt: "my-salt",
-  split_at: nil
+  blocklist: ["bad", "words"],
+  blocklist_mode: :always
 )
-coder.encode(123) # => "p5w9z27j"
+
+# :raise_if_likely - Raise error at configuration time if settings likely cause blocklist collisions
+# Prevents configurations that would cause performance issues
+coder = EncodedId::ReversibleId.sqids(
+  min_length: 8,
+  blocklist: ["bad", "words"],
+  blocklist_mode: :raise_if_likely
+)
+# Raises InvalidConfigurationError if min_length > blocklist_max_length
 ```
 
-### Blocklist Configuration
+**Blocklist Behavior by Encoder**:
+- **Sqids**: Iteratively regenerates to avoid blocklisted words (may impact encoding performance)
+- **Hashids**: Raises `EncodedId::BlocklistError` if a blocklisted word appears
+
+**Recommendation**: Use `:length_threshold` mode (default) for best balance of performance and safety.
+
+### Formatting Options
 
 ```ruby
-# Prevent specific words
-coder = EncodedId::ReversibleId.new(
-  salt: "my-salt",
-  blocklist: ["bad", "offensive", "words"]
+# Custom splitting
+coder = EncodedId::ReversibleId.sqids(
+  split_at: 3,      # Group every 3 chars
+  split_with: "."   # Use dots
 )
+coder.encode(123) # => "p5w.9z2.7j"
 
-# Behavior differs by encoder:
-# - HashIds: Raises error if blocklisted word appears
-# - Sqids: Automatically avoids generating blocklisted words
+# No splitting
+coder = EncodedId::ReversibleId.sqids(split_at: nil)
+coder.encode(123) # => "p5w9z27j"
 ```
 
 ## Exception Handling
@@ -183,14 +307,15 @@ coder = EncodedId::ReversibleId.new(
 | `EncodedId::EncodedIdFormatError` | Invalid encoded ID format |
 | `EncodedId::EncodedIdLengthError` | Encoded ID exceeds max_length |
 | `EncodedId::InvalidInputError` | Invalid input (negative integers, too many inputs) |
-| `EncodedId::SaltError` | Invalid salt (too short) |
+| `EncodedId::SaltError` | Invalid salt (too short, only for Hashids) |
+| `EncodedId::BlocklistError` | Generated ID contains blocklisted word (Hashids only) |
 
 ## Usage Examples
 
 ### Basic Usage
 ```ruby
-# Initialize
-coder = EncodedId::ReversibleId.new(salt: "my-secret-salt")
+# Initialize with Sqids (no salt needed)
+coder = EncodedId::ReversibleId.sqids
 
 # Encode/decode cycle
 encoded = coder.encode(123)        # => "p5w9-z27j"
@@ -205,44 +330,79 @@ encoded = coder.encode([78, 45, 92])  # => "z2j7-0dmw-kf8p"
 decoded = coder.decode(encoded)        # => [78, 45, 92]
 ```
 
-### Custom Configuration
+### With Hashids and Blocklist
 ```ruby
-# Highly customized instance
-coder = EncodedId::ReversibleId.new(
+coder = EncodedId::ReversibleId.hashid(
   salt: "my-app-salt",
-  encoder: :sqids,
-  length: 12,
+  min_length: 12,
+  blocklist: EncodedId::Blocklist.minimal,
+  blocklist_mode: :length_threshold
+)
+
+encoded = coder.encode(123)
+# Raises BlocklistError if result contains blocklisted word
+```
+
+### Custom Configuration
+```ruby
+# Highly customized Sqids instance
+coder = EncodedId::ReversibleId.sqids(
+  min_length: 12,
   split_at: 3,
   split_with: ".",
   alphabet: EncodedId::Alphabet.new("0123456789ABCDEF"),
-  blocklist: ["BAD", "FAKE"]
+  blocklist: ["BAD", "FAKE"],
+  blocklist_mode: :length_threshold,
+  blocklist_max_length: 32
 )
 ```
 
 ### Hex Encoding (UUIDs)
 ```ruby
 # For encoding UUIDs efficiently
-coder = EncodedId::ReversibleId.new(
-  salt: "my-salt",
-  hex_digit_encoding_group_size: 32
-)
+coder = EncodedId::ReversibleId.sqids(hex_digit_encoding_group_size: 32)
 
 uuid = "550e8400-e29b-41d4-a716-446655440000"
 encoded = coder.encode_hex(uuid)
-decoded = coder.decode_hex(encoded).first # => original UUID
+decoded = coder.decode_hex(encoded).first # => original UUID (without hyphens)
 ```
 
 ## Performance Considerations
 
-1. **Algorithm Choice**: 
+1. **Algorithm Choice**:
    - HashIds: Faster encoding, especially with blocklists
-   - Sqids: Faster decoding
+   - Sqids: Faster decoding, automatically avoids blocklisted words
+
+2. **Blocklist Impact**:
+   - Large blocklists slow encoding, especially with Sqids (which iterates to avoid words)
+   - Hashids may raise exceptions requiring retry logic
+   - Use `blocklist_mode: :length_threshold` for best performance
+   - `:always` mode can significantly impact encoding speed for long IDs
+   - Blocklists are automatically filtered for your alphabet, improving performance
+
+3. **Blocklist Mode Performance**:
+   - `:length_threshold` (default): Only checks blocklist for IDs ≤ `blocklist_max_length` (default: 32)
+   - `:always`: Checks all IDs regardless of length (can be slow)
+   - `:raise_if_likely`: Validates configuration at initialization to prevent performance issues
+
+4. **Length vs Performance**: Longer minimum lengths may require more computation
+
+5. **Memory Usage**: The gem uses optimized implementations to minimize memory allocation
 
-2. **Blocklist Impact**: Large blocklists can slow down encoding, especially with Sqids
+## Version Compatibility
 
-3. **Length vs Performance**: Longer minimum lengths may require more computation
+**v1.0.0 Breaking Changes:**
 
-4. **Memory Usage**: The gem uses optimized implementations to minimize memory allocation
+1. **Default encoder**: Changed from `:hashids` to `:sqids`
+2. **Case sensitivity**: `decode` is now case-sensitive by default (`downcase: false`)
+   - Pre-v1: `decode("ABC")` and `decode("abc")` were equivalent
+   - v1.0.0+: These produce different results unless `downcase: true`
+3. **Salt requirement**: Sqids (default) doesn't require salt; Hashids still requires salt
+4. **Migration**: For backwards compatibility with pre-v1:
+   ```ruby
+   coder = EncodedId::ReversibleId.hashid(salt: "your-salt")
+   decoded = coder.decode(id, downcase: true)
+   ```
 
 ## Security Notes
 
@@ -252,32 +412,26 @@ Use encoded IDs for:
 - Hiding sequential database IDs
 - Creating user-friendly URLs
 - Preventing ID enumeration attacks
+- Obscuring business metrics (user counts, order volumes)
 
 Do NOT use for:
 - Secure tokens
 - Authentication
 - Sensitive data protection
+- Cryptographic purposes
 
 ## Installation
 
 ```ruby
 # Gemfile
 gem 'encoded_id'
-
-# Or install directly
-gem install encoded_id
-```
-
-For Sqids support:
-```ruby
-gem 'encoded_id'
-gem 'sqids'
 ```
 
 ## Best Practices
 
-1. **Salt Management**: Use a strong, unique salt and store it securely (e.g., environment variables)
-2. **Consistent Configuration**: Once in production, don't change salt or encoder
-3. **Error Handling**: Always handle potential exceptions when decoding user input
-4. **Length Limits**: Set appropriate max_length to prevent DoS attacks
-5. **Validation**: Validate decoded IDs before using them in database queries
+1. **Consistent Configuration**: Once in production, don't change salt, encoder, or alphabet
+2. **Error Handling**: Always handle potential exceptions when decoding user input
+3. **Length Limits**: Set appropriate max_length to prevent DoS attacks
+4. **Validation**: Validate decoded IDs before using them in database queries
+5. **Blocklist Mode**: Use `:length_threshold` (default) for production - best performance/safety balance
+6. **Factory Methods**: Prefer `ReversibleId.sqids()` and `ReversibleId.hashid()` over constructor

data/lib/encoded_id/rails/active_record_finders.rb

@@ -18,14 +18,27 @@ module EncodedId
         if columns_hash["id"]&.type == :string
           ::Rails.logger.warn("EncodedId::Rails::ActiveRecordFinders has been included in #{name}, but this model uses string-based IDs. This may cause conflicts with encoded ID handling.")
         end
+
+        unless columns_hash.key?("id")
+          ::Rails.logger.warn("EncodedId::Rails::ActiveRecordFinders has been included in #{name}, but this model has no 'id' column. The finders will not work as expected.")
+        end
+
+        if primary_key && primary_key != "id" && columns_hash.key?("id")
+          ::Rails.logger.warn("EncodedId::Rails::ActiveRecordFinders has been included in #{name}, but the primary key is '#{primary_key}', not 'id'. This may cause unexpected behavior with find methods.")
+        end
+
+        # Use prepend so our methods take precedence over ActiveRecord's dynamic finders
+        singleton_class.prepend(ClassMethodsPrepend)
       end
 
-      module ClassMethods
+      # Class methods for overriding ActiveRecord's finder methods to decode encoded IDs.
+      module ClassMethodsPrepend
         # @rbs (*untyped args) -> untyped
         def find(*args)
-          return super unless args.size == 1 && args.first.is_a?(String)
+          first_arg = args.first
+          return super unless args.size == 1 && first_arg.is_a?(String)
 
-          decoded_ids = decode_encoded_id(args.first)
+          decoded_ids = decode_encoded_id(first_arg)
 
           if decoded_ids.blank?
             raise ::ActiveRecord::RecordNotFound

data/lib/encoded_id/rails/annotated_id.rb

@@ -2,28 +2,25 @@
 
 # rbs_inline: enabled
 
-require "cgi"
-
 module EncodedId
   module Rails
-    class AnnotatedId
-      # @rbs @annotation: String
-      # @rbs @id_part: String
-      # @rbs @separator: String
-
+    # Represents an encoded ID with an annotation prefix (e.g., "user_ABC123").
+    class AnnotatedId < CompositeIdBase
       # @rbs (annotation: String, id_part: String, ?separator: String) -> void
       def initialize(annotation:, id_part:, separator: "_")
-        @annotation = annotation
-        @id_part = id_part
-        @separator = separator
+        super(first_part: annotation, id_part: id_part, separator: separator)
       end
 
       # @rbs return: String
       def annotated_id
-        unless @id_part.present? && @annotation.present?
-          raise ::StandardError, "The model does not provide a valid ID and/or annotation"
-        end
-        "#{@annotation.to_s.parameterize}#{CGI.escape(@separator)}#{@id_part}"
+        build_composite_id
+      end
+
+      private
+
+      # @rbs return: String
+      def invalid_id_error_message
+        "The model does not return a valid ID and/or annotation"
       end
     end
   end

data/lib/encoded_id/rails/annotated_id_parser.rb

@@ -4,6 +4,7 @@
 
 module EncodedId
   module Rails
+    # Parses an annotated ID into its annotation and ID components.
     class AnnotatedIdParser
       # @rbs @annotation: String?
       # @rbs @id: String

data/lib/encoded_id/rails/coder.rb

@@ -4,24 +4,32 @@
 
 module EncodedId
   module Rails
+    # Encodes and decodes IDs using the configured encoder and settings.
     class Coder
-      # @rbs @salt: String
+      # @rbs @salt: String?
       # @rbs @id_length: Integer
       # @rbs @character_group_size: Integer
       # @rbs @separator: String
       # @rbs @alphabet: ::EncodedId::Alphabet
-      # @rbs @encoder: (Symbol | ::EncodedId::Encoders::Base)
+      # @rbs @encoder: Symbol
       # @rbs @blocklist: ::EncodedId::Blocklist?
+      # @rbs @blocklist_mode: Symbol
+      # @rbs @blocklist_max_length: Integer
+      # @rbs @downcase_on_decode: bool
 
-      # @rbs (salt: String, id_length: Integer, character_group_size: Integer, separator: String, alphabet: ::EncodedId::Alphabet, ?encoder: Symbol?, ?blocklist: ::EncodedId::Blocklist?) -> void
-      def initialize(salt:, id_length:, character_group_size:, separator:, alphabet:, encoder: nil, blocklist: nil)
+      # @rbs (salt: String?, id_length: Integer, character_group_size: Integer, separator: String, alphabet: ::EncodedId::Alphabet, ?encoder: Symbol?, ?blocklist: ::EncodedId::Blocklist?, ?blocklist_mode: Symbol?, ?blocklist_max_length: Integer?, ?downcase_on_decode: bool?) -> void
+      def initialize(salt:, id_length:, character_group_size:, separator:, alphabet:, encoder: nil, blocklist: nil, blocklist_mode: nil, blocklist_max_length: nil, downcase_on_decode: nil)
         @salt = salt
         @id_length = id_length
         @character_group_size = character_group_size
         @separator = separator
         @alphabet = alphabet
-        @encoder = encoder || EncodedId::Rails.configuration.encoder
-        @blocklist = blocklist || EncodedId::Rails.configuration.blocklist
+        config = EncodedId::Rails.configuration
+        @encoder = encoder || config.encoder
+        @blocklist = blocklist || config.blocklist
+        @blocklist_mode = blocklist_mode || config.blocklist_mode
+        @blocklist_max_length = blocklist_max_length || config.blocklist_max_length
+        @downcase_on_decode = downcase_on_decode.nil? ? config.downcase_on_decode : downcase_on_decode
       end
 
       # @rbs (Integer | Array[Integer] id) -> String
@@ -29,26 +37,45 @@ module EncodedId
         coder.encode(id)
       end
 
-      # @rbs (String encoded_id) -> Array[Integer]?
+      # @rbs (String encoded_id) -> Array[Integer]
       def decode(encoded_id)
-        coder.decode(encoded_id)
+        coder.decode(encoded_id, downcase: @downcase_on_decode)
       rescue EncodedId::EncodedIdFormatError, EncodedId::InvalidInputError
-        nil
+        []
       end
 
       private
 
       # @rbs return: ::EncodedId::ReversibleId
       def coder
-        ::EncodedId::ReversibleId.new(
-          salt: @salt,
-          length: @id_length,
-          split_at: @character_group_size,
-          split_with: @separator,
-          alphabet: @alphabet,
-          encoder: @encoder,
-          blocklist: @blocklist
-        )
+        # Build the appropriate configuration based on encoder type
+        config = case @encoder
+        when :hashids
+          ::EncodedId::Encoders::HashidConfiguration.new(
+            salt: @salt || raise(ArgumentError, "Salt is required for hashids encoder"),
+            min_length: @id_length,
+            split_at: @character_group_size,
+            split_with: @separator,
+            alphabet: @alphabet,
+            blocklist: @blocklist,
+            blocklist_mode: @blocklist_mode,
+            blocklist_max_length: @blocklist_max_length
+          )
+        when :sqids
+          ::EncodedId::Encoders::SqidsConfiguration.new(
+            min_length: @id_length,
+            split_at: @character_group_size,
+            split_with: @separator,
+            alphabet: @alphabet,
+            blocklist: @blocklist,
+            blocklist_mode: @blocklist_mode,
+            blocklist_max_length: @blocklist_max_length
+          )
+        else
+          raise ArgumentError, "Unknown encoder type: #{@encoder}"
+        end
+
+        ::EncodedId::ReversibleId.new(config)
       end
     end
   end

data/lib/encoded_id/rails/composite_id_base.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+require "cgi"
+
+module EncodedId
+  module Rails
+    # Base class for composite IDs (slugged and annotated)
+    class CompositeIdBase
+      # @rbs @first_part: String
+      # @rbs @id_part: String
+      # @rbs @separator: String
+
+      # @rbs (first_part: String, id_part: String, separator: String) -> void
+      def initialize(first_part:, id_part:, separator:)
+        @first_part = first_part
+        @id_part = id_part
+        @separator = separator
+      end
+
+      private
+
+      # @rbs return: String
+      def build_composite_id
+        unless @id_part.present? && @first_part.present?
+          raise ::StandardError, invalid_id_error_message
+        end
+        "#{@first_part.to_s.parameterize}#{CGI.escape(@separator)}#{@id_part}"
+      end
+
+      # Default error message. Subclasses can override for more specific messages.
+      # @rbs return: String
+      def invalid_id_error_message
+        "The model does not return a valid ID and/or prefix"
+      end
+    end
+  end
+end