encoded_id-rails 1.0.0.rc6 → 1.0.0.rc7

data/lib/encoded_id/rails/configuration.rb

@@ -6,7 +6,10 @@ module EncodedId
   module Rails
     # Configuration class for initializer
     class Configuration
-      # @rbs @salt: String
+      VALID_ENCODERS = [:hashids, :sqids].freeze
+      DEFAULT_ENCODER = :sqids
+
+      # @rbs @salt: String?
       # @rbs @character_group_size: Integer
       # @rbs @alphabet: ::EncodedId::Alphabet
       # @rbs @id_length: Integer
@@ -14,12 +17,15 @@ module EncodedId
       # @rbs @annotation_method_name: Symbol
       # @rbs @model_to_param_returns_encoded_id: bool
       # @rbs @blocklist: ::EncodedId::Blocklist
+      # @rbs @blocklist_mode: Symbol
+      # @rbs @blocklist_max_length: Integer
       # @rbs @group_separator: String
       # @rbs @slugged_id_separator: String
       # @rbs @annotated_id_separator: String
       # @rbs @encoder: Symbol
+      # @rbs @downcase_on_decode: bool
 
-      attr_accessor :salt #: String
+      attr_accessor :salt #: String?
       attr_accessor :character_group_size #: Integer
       attr_accessor :alphabet #: ::EncodedId::Alphabet
       attr_accessor :id_length #: Integer
@@ -27,6 +33,9 @@ module EncodedId
       attr_accessor :annotation_method_name #: Symbol
       attr_accessor :model_to_param_returns_encoded_id #: bool
       attr_accessor :blocklist #: ::EncodedId::Blocklist
+      attr_accessor :blocklist_mode #: Symbol
+      attr_accessor :blocklist_max_length #: Integer
+      attr_accessor :downcase_on_decode #: bool
       attr_reader :group_separator #: String
       attr_reader :slugged_id_separator #: String
       attr_reader :annotated_id_separator #: String
@@ -43,14 +52,18 @@ module EncodedId
         @annotation_method_name = :annotation_for_encoded_id
         @annotated_id_separator = "_"
         @model_to_param_returns_encoded_id = false
-        @encoder = :hashids
+        @encoder = DEFAULT_ENCODER
         @blocklist = ::EncodedId::Blocklist.empty
+        @blocklist_mode = :length_threshold
+        @blocklist_max_length = 32
+        @downcase_on_decode = false
+        @salt = nil
       end
 
       # @rbs (Symbol value) -> Symbol
       def encoder=(value)
-        unless ::EncodedId::ReversibleId::VALID_ENCODERS.include?(value)
-          raise ArgumentError, "Encoder must be one of: #{::EncodedId::ReversibleId::VALID_ENCODERS.join(", ")}"
+        unless VALID_ENCODERS.include?(value)
+          raise ArgumentError, "Encoder must be one of: #{VALID_ENCODERS.join(", ")}"
         end
         @encoder = value
       end
@@ -67,25 +80,28 @@ module EncodedId
 
       # @rbs (String value) -> String
       def slugged_id_separator=(value)
-        if value.blank? || value == group_separator || !valid_separator?(value, alphabet)
-          raise ArgumentError, "Slugged ID separator characters must not be part of the alphabet or the same as the group separator"
-        end
+        validate_id_separator!(value, "Slugged ID")
         @slugged_id_separator = value
       end
 
       # @rbs (String value) -> String
       def annotated_id_separator=(value)
-        if value.blank? || value == group_separator || !valid_separator?(value, alphabet)
-          raise ArgumentError, "Annotated ID separator characters must not be part of the alphabet or the same as the group separator"
-        end
+        validate_id_separator!(value, "Annotated ID")
         @annotated_id_separator = value
       end
 
       private
 
+      # @rbs (String value, String separator_name) -> void
+      def validate_id_separator!(value, separator_name)
+        if value.blank? || value == group_separator || !valid_separator?(value, alphabet)
+          raise ArgumentError, "#{separator_name} separator characters must not be part of the alphabet or the same as the group separator"
+        end
+      end
+
       # @rbs (String separator, ::EncodedId::Alphabet characters) -> bool
       def valid_separator?(separator, characters)
-        separator.chars.none? { |v| characters.include?(v) }
+        separator.chars.none? { characters.include?(_1) }
       end
     end
   end

data/lib/encoded_id/rails/encoder_methods.rb

@@ -4,7 +4,12 @@
 
 module EncodedId
   module Rails
+    # Provides methods for encoding and decoding IDs, extended into ActiveRecord models.
     module EncoderMethods
+      # @rbs!
+      #   interface _EncodedIdModel
+      #     def encoded_id_options: () -> Hash[Symbol, untyped]
+      #   end
       # @rbs (Array[Integer] | Integer ids, ?Hash[Symbol, untyped] options) -> String
       def encode_encoded_id(ids, options = {})
         raise StandardError, "You must pass an ID or array of IDs" if ids.blank?
@@ -15,8 +20,9 @@ module EncodedId
       def decode_encoded_id(slugged_encoded_id, options = {})
         return if slugged_encoded_id.blank?
         raise StandardError, "You must pass a string encoded ID" unless slugged_encoded_id.is_a?(String)
-        annotated_encoded_id = SluggedIdParser.new(slugged_encoded_id, separator: EncodedId::Rails.configuration.slugged_id_separator).id
-        encoded_id = AnnotatedIdParser.new(annotated_encoded_id, separator: EncodedId::Rails.configuration.annotated_id_separator).id
+        config = EncodedId::Rails.configuration
+        annotated_encoded_id = SluggedIdParser.new(slugged_encoded_id, separator: config.slugged_id_separator).id
+        encoded_id = AnnotatedIdParser.new(annotated_encoded_id, separator: config.annotated_id_separator).id
         return if !encoded_id || encoded_id.blank?
         encoded_id_coder(options).decode(encoded_id)
       end
@@ -29,16 +35,25 @@ module EncodedId
       end
 
       # @rbs (?Hash[Symbol, untyped] options) -> EncodedId::Rails::Coder
+      #   | (_EncodedIdModel self, ?Hash[Symbol, untyped] options) -> EncodedId::Rails::Coder
       def encoded_id_coder(options = {})
         config = EncodedId::Rails.configuration
+        # Merge model-level options with call-time options (call-time options take precedence)
+        # @type var model_options: Hash[Symbol, untyped]
+        model_options = respond_to?(:encoded_id_options) ? encoded_id_options : {} #: Hash[Symbol, untyped]
+        merged_options = model_options.merge(options)
+
         EncodedId::Rails::Coder.new(
-          salt: options[:salt] || encoded_id_salt,
-          id_length: options[:id_length] || config.id_length,
-          character_group_size: options.key?(:character_group_size) ? options[:character_group_size] : config.character_group_size,
-          alphabet: options[:alphabet] || config.alphabet,
-          separator: options.key?(:separator) ? options[:separator] : config.group_separator,
-          encoder: options[:encoder] || config.encoder,
-          blocklist: options[:blocklist] || config.blocklist
+          salt: merged_options[:salt] || encoded_id_salt,
+          id_length: merged_options[:id_length] || config.id_length,
+          character_group_size: merged_options.key?(:character_group_size) ? merged_options[:character_group_size] : config.character_group_size,
+          alphabet: merged_options[:alphabet] || config.alphabet,
+          separator: merged_options.key?(:separator) ? merged_options[:separator] : config.group_separator,
+          encoder: merged_options[:encoder] || config.encoder,
+          blocklist: merged_options[:blocklist] || config.blocklist,
+          blocklist_mode: merged_options[:blocklist_mode] || config.blocklist_mode,
+          blocklist_max_length: merged_options[:blocklist_max_length] || config.blocklist_max_length,
+          downcase_on_decode: merged_options.key?(:downcase_on_decode) ? merged_options[:downcase_on_decode] : config.downcase_on_decode
         )
       end
     end

data/lib/encoded_id/rails/finder_methods.rb

@@ -4,6 +4,7 @@
 
 module EncodedId
   module Rails
+    # Provides finder methods for locating records by their encoded IDs.
     module FinderMethods
       # @rbs!
       #   include ::EncodedId::Rails::EncoderMethods

data/lib/encoded_id/rails/model.rb

@@ -7,6 +7,7 @@ require "encoded_id"
 
 module EncodedId
   module Rails
+    # Main module for adding encoded ID functionality to ActiveRecord models.
     module Model
       # @rbs!
       #   extend ::EncodedId::Rails::EncoderMethods
@@ -27,13 +28,40 @@ module EncodedId
         base.extend(EncoderMethods)
         base.extend(FinderMethods)
         base.extend(QueryMethods)
+        base.extend(ClassMethods)
 
-        # Automatically include PathParam if configured to do so
+        # Conditionally include PathParam based on global configuration
         if EncodedId::Rails.configuration.model_to_param_returns_encoded_id
           base.include(EncodedId::Rails::PathParam)
         end
       end
 
+      module ClassMethods
+        # Configure encoder options for this specific model
+        # @example
+        #   class MyModel < ApplicationRecord
+        #     include EncodedId::Rails::Model
+        #     encoded_id_config encoder: :hashids
+        #   end
+        #
+        # @rbs (**untyped options) -> void
+        def encoded_id_config(**options)
+          @encoded_id_options = options
+        end
+
+        # Walks up the inheritance chain to find options if not set on this class
+        # @rbs () -> Hash[Symbol, untyped]
+        def encoded_id_options
+          return @encoded_id_options if defined?(@encoded_id_options) && @encoded_id_options
+
+          if superclass.respond_to?(:encoded_id_options)
+            superclass.encoded_id_options
+          else
+            {}
+          end
+        end
+      end
+
       attr_accessor :encoded_id_memoized_with_id #: untyped
 
       # @rbs () -> void
@@ -66,10 +94,11 @@ module EncodedId
         return @encoded_id if defined?(@encoded_id)
 
         encoded = encoded_id_hash
-        annotated_by = EncodedId::Rails.configuration.annotation_method_name
+        config = EncodedId::Rails.configuration
+        annotated_by = config.annotation_method_name
         return @encoded_id = encoded unless annotated_by && encoded
 
-        separator = EncodedId::Rails.configuration.annotated_id_separator
+        separator = config.annotated_id_separator
         self.encoded_id_memoized_with_id = id
         @encoded_id = EncodedId::Rails::AnnotatedId.new(id_part: encoded, annotation: send(annotated_by.to_s), separator: separator).annotated_id
       end
@@ -80,8 +109,9 @@ module EncodedId
         check_and_clear_memoization
         return @slugged_encoded_id if defined?(@slugged_encoded_id)
 
-        with = EncodedId::Rails.configuration.slug_value_method_name
-        separator = EncodedId::Rails.configuration.slugged_id_separator
+        config = EncodedId::Rails.configuration
+        with = config.slug_value_method_name
+        separator = config.slugged_id_separator
         encoded = encoded_id
         return unless encoded
 

data/lib/encoded_id/rails/path_param.rb

@@ -7,6 +7,7 @@ require "encoded_id"
 
 module EncodedId
   module Rails
+    # Overrides to_param to return the encoded ID for use in URLs.
     module PathParam
       # Method provided by model
       # @rbs!

data/lib/encoded_id/rails/persists.rb

@@ -4,6 +4,7 @@
 
 module EncodedId
   module Rails
+    # Provides persistence of encoded IDs to database columns with validation and callbacks.
     module Persists
       # @rbs (untyped base) -> void
       def self.included(base)
@@ -33,7 +34,6 @@ module EncodedId
         end
       end
 
-      # Method provided by model
       # @rbs!
       #   include ::ActiveRecord::Persistence
       #
@@ -52,7 +52,7 @@ module EncodedId
       #   def clear_normalized_encoded_id_change: () -> void
 
       # On duplication we need to reset the encoded ID to nil as this new record will have a new ID.
-      # We need to also prevent these changes from marking the record as dirty.
+      # We also prevent these changes from marking the record as dirty.
       # @rbs () -> untyped
       def dup
         copy = super
@@ -85,15 +85,17 @@ module EncodedId
       def check_encoded_id_persisted!
         validate_id_for_encoded_id!
 
-        encoded_from_current_id = self.class.encode_normalized_encoded_id(resolved_id)
+        klass = self.class
+        klass_name = klass.name
+        encoded_from_current_id = klass.encode_normalized_encoded_id(resolved_id)
 
         if normalized_encoded_id != encoded_from_current_id
-          raise StandardError, "The persisted encoded ID #{normalized_encoded_id} for #{self.class.name} is not the same as currently computing #{encoded_from_current_id}"
+          raise StandardError, "The persisted encoded ID #{normalized_encoded_id} for #{klass_name} is not the same as currently computing #{encoded_from_current_id}"
         end
 
         return if prefixed_encoded_id == encoded_id
 
-        raise StandardError, "The persisted prefixed encoded ID (for #{self.class.name} with id: #{id}, normalized_encoded_id: #{normalized_encoded_id}) is not correct: it is #{prefixed_encoded_id} instead of #{encoded_id}"
+        raise StandardError, "The persisted prefixed encoded ID (for #{klass_name} with id: #{id}, normalized_encoded_id: #{normalized_encoded_id}) is not correct: it is #{prefixed_encoded_id} instead of #{encoded_id}"
       end
 
       # @rbs () -> bool

data/lib/encoded_id/rails/query_methods.rb

@@ -4,6 +4,7 @@
 
 module EncodedId
   module Rails
+    # Provides query methods for finding records using encoded IDs in where clauses.
     module QueryMethods
       # Methods provided by other mixins/ActiveRecord
       # @rbs!

data/lib/encoded_id/rails/salt.rb

@@ -4,6 +4,7 @@
 
 module EncodedId
   module Rails
+    # Generates a unique salt for encoding IDs based on the model class name.
     class Salt
       # @rbs @klass: Class
       # @rbs @salt: String

data/lib/encoded_id/rails/slugged_id.rb

@@ -2,28 +2,25 @@
 
 # rbs_inline: enabled
 
-require "cgi"
-
 module EncodedId
   module Rails
-    class SluggedId
-      # @rbs @slug_part: String
-      # @rbs @id_part: String
-      # @rbs @separator: String
-
+    # Represents an encoded ID with a slug prefix (e.g., "my-post--ABC123").
+    class SluggedId < CompositeIdBase
       # @rbs (slug_part: String, id_part: String, ?separator: String) -> void
       def initialize(slug_part:, id_part:, separator: "--")
-        @slug_part = slug_part
-        @id_part = id_part
-        @separator = separator
+        super(first_part: slug_part, id_part: id_part, separator: separator)
       end
 
       # @rbs return: String
       def slugged_id
-        unless @id_part.present? && @slug_part.present?
-          raise ::StandardError, "The model does not return a valid ID and/or slug"
-        end
-        "#{@slug_part.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 slug"
       end
     end
   end

data/lib/encoded_id/rails/slugged_id_parser.rb

@@ -4,6 +4,7 @@
 
 module EncodedId
   module Rails
+    # Parses a slugged ID into its slug and ID components.
     class SluggedIdParser
       # @rbs @slug: String?
       # @rbs @id: String

data/lib/encoded_id/rails/slugged_path_param.rb

@@ -7,6 +7,7 @@ require "encoded_id"
 
 module EncodedId
   module Rails
+    # Overrides to_param to return the slugged encoded ID for use in URLs.
     module SluggedPathParam
       # Method provided by model
       # @rbs!

data/lib/encoded_id/rails.rb

@@ -4,6 +4,7 @@
 
 require_relative "rails/configuration"
 require_relative "rails/coder"
+require_relative "rails/composite_id_base"
 require_relative "rails/slugged_id"
 require_relative "rails/slugged_id_parser"
 require_relative "rails/annotated_id"
@@ -20,6 +21,7 @@ require_relative "rails/active_record_finders"
 require_relative "rails/railtie"
 
 module EncodedId
+  # Rails integration for EncodedId, providing configuration and ActiveRecord extensions.
   module Rails
     # Configuration
     # @rbs self.@configuration: EncodedId::Rails::Configuration?

data/lib/generators/encoded_id/rails/install_generator.rb

@@ -9,9 +9,43 @@ module EncodedId
       class InstallGenerator < ::Rails::Generators::Base
         source_root File.expand_path(__dir__)
 
-        desc "Creates an initializer for the gem."
+        desc "Creates an encoder-specific initializer for the gem."
+
+        class_option :encoder,
+          type: :string,
+          aliases: "-e",
+          desc: "Encoder to use (sqids or hashids)",
+          default: nil
+
+        def ask_for_encoder
+          @encoder = options[:encoder]
+
+          @encoder ||= ask("Which encoder would you like to use?",
+            limited_to: %w[sqids hashids],
+            default: "sqids")
+
+          unless %w[sqids hashids].include?(@encoder)
+            say "Invalid encoder '#{@encoder}'. Must be 'sqids' or 'hashids'.", :red
+            exit 1
+          end
+        end
+
         def copy_tasks
-          template "templates/encoded_id.rb", "config/initializers/encoded_id.rb"
+          template_name = (@encoder == "sqids") ? "sqids_encoded_id.rb" : "hashids_encoded_id.rb"
+          template "templates/#{template_name}", "config/initializers/encoded_id.rb"
+        end
+
+        def show_readme
+          say "\n" + ("=" * 70), :green
+          if @encoder == "sqids"
+            say "Sqids encoder installed!", :green
+            say "This encoder does not require a salt and generates URL-safe IDs.", :green
+          else
+            say "Hashids encoder installed!", :green
+            say "⚠️  IMPORTANT: You MUST configure a salt in config/initializers/encoded_id.rb", :yellow
+            say "Uncomment and set the 'config.salt' line before using Hashids.", :yellow
+          end
+          say ("=" * 70) + "\n", :green
         end
       end
     end

data/lib/generators/encoded_id/rails/templates/hashids_encoded_id.rb

@@ -0,0 +1,122 @@
+# frozen_string_literal: true
+
+EncodedId::Rails.configure do |config|
+  # The encoder to use for generating encoded IDs.
+  #
+  # Hashids generates short, unique, non-sequential IDs from numbers using a salt. The salt ensures that
+  # the same ID produces different encoded values. Learn more: https://hashids.org
+  #
+  config.encoder = :hashids
+
+  # The salt is used in the Hashids algorithm to generate the encoded ID. It ensures that the same ID will result in
+  # a different encoded ID. You must configure one and it must be longer that 4 characters. It can be configured on a
+  # model by model basis too.
+  #
+  config.salt = "<%= SecureRandom.hex(24) %>"
+
+  # The number of characters of the encoded ID that are grouped before the hyphen separator is inserted.
+  # `nil` disables grouping.
+  #
+  # nil -> abcdefghijklmnop
+  # 4   -> abcd-efgh-ijkl-mnop
+  # 8   -> abcdefgh-ijklmnop
+  #
+  # Default: 4
+  #
+  # config.character_group_size = 4
+
+  # The separator used between character groups in the encoded ID.
+  # `nil` disables grouping.
+  #
+  # Default: "-"
+  #
+  # config.group_separator = "-"
+
+  # The characters allowed in the encoded ID.
+  # Note, Hashids requires at least 16 unique alphabet characters.
+  #
+  # Default: a reduced character set Crockford alphabet and split groups, see https://www.crockford.com/wrmg/base32.html
+  #
+  # config.alphabet = ::EncodedId::Alphabet.new("0123456789abcdef")
+
+  # The minimum length of the encoded ID. Note that this is not a hard limit, the actual length may be longer as Hashids
+  # may expand the length as needed to encode the full input. However encoded IDs will never be shorter than this.
+  #
+  # 4 -> "abcd"
+  # 8 -> "abcd-efgh" (with character_group_size = 4)
+  #
+  # Default: 8
+  #
+  # config.id_length = 8
+
+  # The name of the method that returns the value to be used in the slug.
+  #
+  # Default: :name_for_encoded_id_slug
+  #
+  # config.slug_value_method_name = :name_for_encoded_id_slug
+
+  # The separator used between the slug and the encoded ID.
+  # `nil` disables grouping.
+  #
+  # Default: "--"
+  #
+  # config.slugged_id_separator = "--"
+
+  # The name of the method that returns the annotation to be used in the annotated ID.
+  #
+  # Default: :annotation_for_encoded_id
+  #
+  # config.annotation_method_name = :annotation_for_encoded_id
+
+  # The separator used between the annotation and the encoded ID.
+  # `nil` disables annotation.
+  #
+  # Default: "_"
+  #
+  # config.annotated_id_separator = "_"
+
+  # When true, models that include EncodedId::Rails::Model will automatically have their to_param method
+  # return the encoded ID (equivalent to also including EncodedId::Rails::PathParam).
+  # This makes any model with EncodedId::Rails::Model automatically use encoded IDs in URLs.
+  #
+  # Default: false
+  #
+  # config.model_to_param_returns_encoded_id = true
+
+  # When true, the encoded ID will be downcased before decoding. This can be used for
+  # case-insensitive matching on a compatible alphabet, but note that encoded IDs are case-sensitive by default.
+  # For backwards compatibility with pre-v1 versions, set this to true.
+  #
+  # Default: false
+  #
+  # config.downcase_on_decode = false
+
+  # A list of words that should not appear in generated encoded IDs.
+  # For the Hashids encoder, IDs containing blocklisted words will raise an error when generated.
+  # Should be an instance of EncodedId::Blocklist, or an Array or Set of strings.
+  #
+  # Default: EncodedId::Blocklist.empty
+  # Available built-in blocklists:
+  # - EncodedId::Blocklist.empty - no blocked words
+  # - EncodedId::Blocklist.minimal - common English profanity
+  #
+  # config.blocklist = EncodedId::Blocklist.minimal
+
+  # Controls when blocklist checking occurs. This can improve performance for apps generating many IDs.
+  #
+  # Options:
+  # - :length_threshold (default) - Only check IDs up to blocklist_max_length characters
+  # - :always - Check all IDs regardless of length
+  # - :raise_if_likely - Raise error if configuration likely causes performance issues
+  #
+  # Default: :length_threshold
+  #
+  # config.blocklist_mode = :length_threshold
+
+  # Maximum length threshold for blocklist checking when using :length_threshold mode.
+  # IDs longer than this will skip blocklist checking for better performance.
+  #
+  # Default: 32
+  #
+  # config.blocklist_max_length = 32
+end

data/lib/generators/encoded_id/rails/templates/{encoded_id.rb → sqids_encoded_id.rb}

@@ -1,11 +1,11 @@
 # frozen_string_literal: true
 
 EncodedId::Rails.configure do |config|
-  # The salt is used in the Hashids algorithm to generate the encoded ID. It ensures that the same ID will result in
-  # a different encoded ID. You must configure one and it must be longer that 4 characters. It can be configured on a
-  # model by model basis too.
+  # The encoder to use for generating encoded IDs.
   #
-  # config.salt = "<%= SecureRandom.hex(24) %>"
+  # Sqids generates short, unique, URL-safe IDs from numbers. Learn more: https://sqids.org
+  #
+  config.encoder = :sqids
 
   # The number of characters of the encoded ID that are grouped before the hyphen separator is inserted.
   # `nil` disables grouping.
@@ -26,13 +26,13 @@ EncodedId::Rails.configure do |config|
   # config.group_separator = "-"
 
   # The characters allowed in the encoded ID.
-  # Note, hash ids requires at least 16 unique alphabet characters.
+  # Note, Sqids requires at least 5 unique alphabet characters.
   #
   # Default: a reduced character set Crockford alphabet and split groups, see https://www.crockford.com/wrmg/base32.html
   #
   # config.alphabet = ::EncodedId::Alphabet.new("0123456789abcdef")
 
-  # The minimum length of the encoded ID. Note that this is not a hard limit, the actual length may be longer as hash IDs
+  # The minimum length of the encoded ID. Note that this is not a hard limit, the actual length may be longer as Sqids
   # may expand the length as needed to encode the full input. However encoded IDs will never be shorter than this.
   #
   # 4 -> "abcd"
@@ -76,15 +76,15 @@ EncodedId::Rails.configure do |config|
   #
   # config.model_to_param_returns_encoded_id = true
 
-  # The encoder to use for generating encoded IDs. Valid options are :hashids and :sqids.
-  # To use :sqids, you must add 'gem "sqids"' to your Gemfile.
+  # When true, the encoded ID will be downcased before decoding. This can be used for
+  # case-insensitive matching on a compatible alphabet, but note that encoded IDs are case-sensitive by default.
+  # For backwards compatibility with pre-v1 versions, set this to true.
   #
-  # Default: :hashids
+  # Default: false
   #
-  # config.encoder = :hashids
+  # config.downcase_on_decode = false
 
   # A list of words that should not appear in generated encoded IDs.
-  # For the HashIds encoder, IDs containing blocklisted words will raise an error when generated.
   # For the Sqids encoder, the algorithm will automatically avoid generating IDs containing these words.
   # Should be an instance of EncodedId::Blocklist, or an Array or Set of strings.
   #
@@ -95,4 +95,22 @@ EncodedId::Rails.configure do |config|
   # - EncodedId::Blocklist.sqids_blocklist - the default blocklist from the Sqids gem
   #
   # config.blocklist = EncodedId::Blocklist.minimal
+
+  # Controls when blocklist checking occurs. This can improve performance for apps generating many IDs.
+  #
+  # Options:
+  # - :length_threshold (default) - Only check IDs up to blocklist_max_length characters
+  # - :always - Check all IDs regardless of length
+  # - :raise_if_likely - Raise error if configuration likely causes performance issues
+  #
+  # Default: :length_threshold
+  #
+  # config.blocklist_mode = :length_threshold
+
+  # Maximum length threshold for blocklist checking when using :length_threshold mode.
+  # IDs longer than this will skip blocklist checking for better performance.
+  #
+  # Default: 32
+  #
+  # config.blocklist_max_length = 32
 end