encoded_id-rails 1.0.0.beta3 → 1.0.0.rc6

data/lib/encoded_id/rails/active_record_finders.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module EncodedId
+  module Rails
+    # This module overrides standard ActiveRecord finder methods to automatically decode encoded IDs.
+    # Important: This module should NOT be used with models that use string-based primary keys (e.g., UUIDs)
+    # as it will cause conflicts between string IDs and encoded IDs.
+    module ActiveRecordFinders
+      extend ActiveSupport::Concern
+
+      # @rbs!
+      #   include ::ActiveRecord::FinderMethods
+      #   extend ::ActiveRecord::QueryMethods
+
+      included do
+        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
+      end
+
+      module ClassMethods
+        # @rbs (*untyped args) -> untyped
+        def find(*args)
+          return super unless args.size == 1 && args.first.is_a?(String)
+
+          decoded_ids = decode_encoded_id(args.first)
+
+          if decoded_ids.blank?
+            raise ::ActiveRecord::RecordNotFound
+          elsif decoded_ids.size == 1
+            super(decoded_ids.first)
+          else
+            super(decoded_ids)
+          end
+        end
+
+        # Override find_by_id to handle encoded IDs
+        # @rbs (untyped id) -> untyped
+        def find_by_id(id)
+          if id.is_a?(String)
+            decoded_ids = decode_encoded_id(id)
+            return nil if decoded_ids.blank?
+            return super(decoded_ids.first)
+          end
+          super
+        end
+      end
+    end
+  end
+end

data/lib/encoded_id/rails/annotated_id.rb

@@ -1,16 +1,24 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 require "cgi"
 
 module EncodedId
   module Rails
     class AnnotatedId
+      # @rbs @annotation: String
+      # @rbs @id_part: String
+      # @rbs @separator: String
+
+      # @rbs (annotation: String, id_part: String, ?separator: String) -> void
       def initialize(annotation:, id_part:, separator: "_")
         @annotation = 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"

data/lib/encoded_id/rails/annotated_id_parser.rb

@@ -1,8 +1,14 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 module EncodedId
   module Rails
     class AnnotatedIdParser
+      # @rbs @annotation: String?
+      # @rbs @id: String
+
+      # @rbs (String annotated_id, ?separator: String) -> void
       def initialize(annotated_id, separator: "_")
         if separator && annotated_id.include?(separator)
           parts = annotated_id.split(separator)
@@ -13,7 +19,8 @@ module EncodedId
         end
       end
 
-      attr_reader :annotation, :id
+      attr_reader :annotation #: String?
+      attr_reader :id #: String
     end
   end
 end

data/lib/encoded_id/rails/coder.rb

@@ -1,20 +1,35 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 module EncodedId
   module Rails
     class Coder
-      def initialize(salt:, id_length:, character_group_size:, separator:, alphabet:)
+      # @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 @blocklist: ::EncodedId::Blocklist?
+
+      # @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)
         @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
       end
 
+      # @rbs (Integer | Array[Integer] id) -> String
       def encode(id)
         coder.encode(id)
       end
 
+      # @rbs (String encoded_id) -> Array[Integer]?
       def decode(encoded_id)
         coder.decode(encoded_id)
       rescue EncodedId::EncodedIdFormatError, EncodedId::InvalidInputError
@@ -23,13 +38,16 @@ module EncodedId
 
       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
+          alphabet: @alphabet,
+          encoder: @encoder,
+          blocklist: @blocklist
         )
       end
     end

data/lib/encoded_id/rails/configuration.rb

@@ -1,13 +1,38 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 module EncodedId
   module Rails
     # Configuration class for initializer
     class Configuration
-      attr_accessor :salt, :character_group_size, :alphabet, :id_length
-      attr_accessor :slug_value_method_name, :annotation_method_name
-      attr_reader :group_separator, :slugged_id_separator, :annotated_id_separator
+      # @rbs @salt: String
+      # @rbs @character_group_size: Integer
+      # @rbs @alphabet: ::EncodedId::Alphabet
+      # @rbs @id_length: Integer
+      # @rbs @slug_value_method_name: Symbol
+      # @rbs @annotation_method_name: Symbol
+      # @rbs @model_to_param_returns_encoded_id: bool
+      # @rbs @blocklist: ::EncodedId::Blocklist
+      # @rbs @group_separator: String
+      # @rbs @slugged_id_separator: String
+      # @rbs @annotated_id_separator: String
+      # @rbs @encoder: Symbol
+
+      attr_accessor :salt #: String
+      attr_accessor :character_group_size #: Integer
+      attr_accessor :alphabet #: ::EncodedId::Alphabet
+      attr_accessor :id_length #: Integer
+      attr_accessor :slug_value_method_name #: Symbol
+      attr_accessor :annotation_method_name #: Symbol
+      attr_accessor :model_to_param_returns_encoded_id #: bool
+      attr_accessor :blocklist #: ::EncodedId::Blocklist
+      attr_reader :group_separator #: String
+      attr_reader :slugged_id_separator #: String
+      attr_reader :annotated_id_separator #: String
+      attr_reader :encoder #: Symbol
 
+      # @rbs () -> void
       def initialize
         @character_group_size = 4
         @group_separator = "-"
@@ -17,10 +42,22 @@ module EncodedId
         @slugged_id_separator = "--"
         @annotation_method_name = :annotation_for_encoded_id
         @annotated_id_separator = "_"
+        @model_to_param_returns_encoded_id = false
+        @encoder = :hashids
+        @blocklist = ::EncodedId::Blocklist.empty
+      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(", ")}"
+        end
+        @encoder = value
       end
 
       # Perform validation vs alphabet on these assignments
 
+      # @rbs (String value) -> String
       def group_separator=(value)
         unless valid_separator?(value, alphabet)
           raise ArgumentError, "Group separator characters must not be part of the alphabet"
@@ -28,6 +65,7 @@ module EncodedId
         @group_separator = value
       end
 
+      # @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"
@@ -35,6 +73,7 @@ module EncodedId
         @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"
@@ -42,6 +81,9 @@ module EncodedId
         @annotated_id_separator = value
       end
 
+      private
+
+      # @rbs (String separator, ::EncodedId::Alphabet characters) -> bool
       def valid_separator?(separator, characters)
         separator.chars.none? { |v| characters.include?(v) }
       end

data/lib/encoded_id/rails/encoder_methods.rb

@@ -1,13 +1,17 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 module EncodedId
   module Rails
     module EncoderMethods
+      # @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?
         encoded_id_coder(options).encode(ids)
       end
 
+      # @rbs (String slugged_encoded_id, ?Hash[Symbol, untyped] options) -> Array[Integer]?
       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)
@@ -18,11 +22,13 @@ module EncodedId
       end
 
       # This can be overridden in the model to provide a custom salt
+      # @rbs return: String
       def encoded_id_salt
         # @type self: Class
         EncodedId::Rails::Salt.new(self, EncodedId::Rails.configuration.salt).generate!
       end
 
+      # @rbs (?Hash[Symbol, untyped] options) -> EncodedId::Rails::Coder
       def encoded_id_coder(options = {})
         config = EncodedId::Rails.configuration
         EncodedId::Rails::Coder.new(
@@ -30,7 +36,9 @@ module EncodedId
           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
+          separator: options.key?(:separator) ? options[:separator] : config.group_separator,
+          encoder: options[:encoder] || config.encoder,
+          blocklist: options[:blocklist] || config.blocklist
         )
       end
     end

data/lib/encoded_id/rails/finder_methods.rb

@@ -1,9 +1,16 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 module EncodedId
   module Rails
     module FinderMethods
+      # @rbs!
+      #   include ::EncodedId::Rails::EncoderMethods
+      #   include ActiveRecordFinders
+
       # Find by encoded ID and optionally ensure record ID is the same as constraint (can be slugged)
+      # @rbs (String encoded_id, ?with_id: Symbol?) -> untyped
       def find_by_encoded_id(encoded_id, with_id: nil)
         decoded_id = decode_encoded_id(encoded_id)
         return if decoded_id.nil? || decoded_id.blank?
@@ -13,6 +20,7 @@ module EncodedId
         record
       end
 
+      # @rbs (String encoded_id, ?with_id: Symbol?) -> untyped
       def find_by_encoded_id!(encoded_id, with_id: nil)
         decoded_id = decode_encoded_id(encoded_id)
         raise ActiveRecord::RecordNotFound if decoded_id.nil? || decoded_id.blank?
@@ -23,12 +31,14 @@ module EncodedId
         record
       end
 
+      # @rbs (String encoded_id) -> Array[untyped]?
       def find_all_by_encoded_id(encoded_id)
         decoded_ids = decode_encoded_id(encoded_id)
         return if decoded_ids.blank?
         where(id: decoded_ids).to_a
       end
 
+      # @rbs (String encoded_id) -> Array[untyped]
       def find_all_by_encoded_id!(encoded_id)
         decoded_ids = decode_encoded_id(encoded_id)
         raise ActiveRecord::RecordNotFound if decoded_ids.nil? || decoded_ids.blank?

data/lib/encoded_id/rails/model.rb

@@ -1,43 +1,101 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 require "active_record"
 require "encoded_id"
 
 module EncodedId
   module Rails
     module Model
+      # @rbs!
+      #   extend ::EncodedId::Rails::EncoderMethods
+      #   extend ::EncodedId::Rails::FinderMethods
+      #   extend ::EncodedId::Rails::QueryMethods
+      #
+      #
+      #   # Model attributes that must exist, plus related AR methods
+      #   def id: () -> Integer?
+
+      # @rbs @encoded_id_hash: String?
+      # @rbs @encoded_id: String?
+      # @rbs @slugged_encoded_id: String?
+      # @rbs @encoded_id_memoized_with_id: untyped
+
+      # @rbs (untyped base) -> void
       def self.included(base)
         base.extend(EncoderMethods)
         base.extend(FinderMethods)
         base.extend(QueryMethods)
+
+        # Automatically include PathParam if configured to do so
+        if EncodedId::Rails.configuration.model_to_param_returns_encoded_id
+          base.include(EncodedId::Rails::PathParam)
+        end
+      end
+
+      attr_accessor :encoded_id_memoized_with_id #: untyped
+
+      # @rbs () -> void
+      def clear_encoded_id_cache!
+        [:@encoded_id_hash, :@encoded_id, :@slugged_encoded_id].each do |var|
+          remove_instance_variable(var) if instance_variable_defined?(var)
+        end
+        self.encoded_id_memoized_with_id = nil
       end
 
+      # @rbs () -> void
+      def check_and_clear_memoization
+        clear_encoded_id_cache! if encoded_id_memoized_with_id && encoded_id_memoized_with_id != id
+      end
+
+      # @rbs () -> String?
       def encoded_id_hash
         return unless id
-        return @encoded_id_hash if defined?(@encoded_id_hash) && !id_changed?
-        self.class.encode_encoded_id(id)
+        check_and_clear_memoization
+        return @encoded_id_hash if defined?(@encoded_id_hash)
+
+        self.encoded_id_memoized_with_id = id
+        @encoded_id_hash = self.class.encode_encoded_id(id)
       end
 
+      # @rbs () -> String?
       def encoded_id
         return unless id
-        return @encoded_id if defined?(@encoded_id) && !id_changed?
+        check_and_clear_memoization
+        return @encoded_id if defined?(@encoded_id)
+
         encoded = encoded_id_hash
         annotated_by = EncodedId::Rails.configuration.annotation_method_name
         return @encoded_id = encoded unless annotated_by && encoded
+
         separator = EncodedId::Rails.configuration.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
 
+      # @rbs () -> String?
       def slugged_encoded_id
         return unless id
-        return @slugged_encoded_id if defined?(@slugged_encoded_id) && !id_changed?
+        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
         encoded = encoded_id
         return unless encoded
+
+        self.encoded_id_memoized_with_id = id
         @slugged_encoded_id = EncodedId::Rails::SluggedId.new(id_part: encoded, slug_part: send(with.to_s), separator: separator).slugged_id
       end
 
+      # @rbs (?untyped? options) -> untyped
+      def reload(options = nil)
+        result = super
+        clear_encoded_id_cache!
+        result
+      end
+
       # By default the annotation is the model name (it will be parameterized)
       def annotation_for_encoded_id
         name = self.class.name
@@ -45,18 +103,17 @@ module EncodedId
         name.underscore
       end
 
-      # By default trying to generate a slug without defining how will raise.
+      # By default, trying to generate a slug without defining how will raise.
       # You either override this method per model, pass an alternate method name to
       # #slugged_encoded_id or setup an alias to another model method in your ApplicationRecord class
       def name_for_encoded_id_slug
         raise StandardError, "You must define a method to generate the slug for the encoded ID of #{self.class.name}"
       end
 
-      # When duplicating an ActiveRecord object, we want to reset the memoized encoded_id
+      # When duplicating an ActiveRecord object, we want to reset the memoized encoded IDs
       def dup
         super.tap do |new_record|
-          new_record.send(:remove_instance_variable, :@encoded_id) if new_record.instance_variable_defined?(:@encoded_id)
-          new_record.send(:remove_instance_variable, :@slugged_encoded_id) if new_record.instance_variable_defined?(:@slugged_encoded_id)
+          new_record.clear_encoded_id_cache!
         end
       end
     end

data/lib/encoded_id/rails/path_param.rb

@@ -1,11 +1,18 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 require "active_record"
 require "encoded_id"
 
 module EncodedId
   module Rails
     module PathParam
+      # Method provided by model
+      # @rbs!
+      #   def encoded_id: () -> String?
+
+      # @rbs () -> String
       def to_param
         encoded_id || raise(StandardError, "Cannot create path param for #{self.class.name} without an encoded id")
       end

data/lib/encoded_id/rails/persists.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module EncodedId
+  module Rails
+    module Persists
+      # @rbs (untyped base) -> void
+      def self.included(base)
+        base.extend ClassMethods
+
+        base.validates :normalized_encoded_id, uniqueness: true, allow_nil: true
+        base.validates :prefixed_encoded_id, uniqueness: true, allow_nil: true
+
+        base.before_validation :prevent_update_of_normalized_encoded_id!, if: :normalized_encoded_id_changed?
+        base.before_validation :prevent_update_of_prefixed_encoded_id!, if: :prefixed_encoded_id_changed?
+
+        base.after_create :set_normalized_encoded_id!
+        base.before_save :update_normalized_encoded_id!, if: :should_update_normalized_encoded_id?
+
+        base.after_commit :check_encoded_id_persisted!, on: [:create, :update]
+      end
+
+      module ClassMethods
+        # Encoder methods come from ::EncodedId::Rails::Model but thats not working with this pattern of defining class
+        # methods.
+        # @rbs!
+        #   include ::EncodedId::Rails::EncoderMethods
+
+        # @rbs (Integer id) -> String
+        def encode_normalized_encoded_id(id)
+          encode_encoded_id(id, character_group_size: nil)
+        end
+      end
+
+      # Method provided by model
+      # @rbs!
+      #   include ::ActiveRecord::Persistence
+      #
+      #   include ::EncodedId::Rails::Model
+      #
+      #   extend ClassMethods
+      #
+      #   # Model attributes that must exist, plus related AR methods
+      #   def id: () -> Integer?
+      #   def id_changed?: () -> bool
+      #   def prefixed_encoded_id: () -> String?
+      #   def prefixed_encoded_id=: (String?) -> String?
+      #   def normalized_encoded_id: () -> String?
+      #   def normalized_encoded_id=: (String?) -> String?
+      #   def clear_prefixed_encoded_id_change: () -> void
+      #   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.
+      # @rbs () -> untyped
+      def dup
+        copy = super
+        copy.prefixed_encoded_id = nil
+        copy.clear_prefixed_encoded_id_change
+        copy.normalized_encoded_id = nil
+        copy.clear_normalized_encoded_id_change
+        copy
+      end
+
+      # @rbs () -> Integer
+      def resolved_id
+        validate_id_for_encoded_id!
+
+        id #: Integer
+      end
+
+      # @rbs () -> void
+      def set_normalized_encoded_id!
+        update_columns(normalized_encoded_id: self.class.encode_normalized_encoded_id(resolved_id), prefixed_encoded_id: encoded_id)
+      end
+
+      # @rbs () -> void
+      def update_normalized_encoded_id!
+        self.normalized_encoded_id = self.class.encode_normalized_encoded_id(resolved_id)
+        self.prefixed_encoded_id = encoded_id
+      end
+
+      # @rbs () -> void
+      def check_encoded_id_persisted!
+        validate_id_for_encoded_id!
+
+        encoded_from_current_id = self.class.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}"
+        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}"
+      end
+
+      # @rbs () -> bool
+      def should_update_normalized_encoded_id?
+        id_changed? || (normalized_encoded_id.blank? && persisted?)
+      end
+
+      # @rbs () -> void
+      def validate_id_for_encoded_id!
+        raise StandardError, "You cannot set the normalized ID of a record which is not persisted" if id.blank?
+      end
+
+      # @rbs () -> void
+      def prevent_update_of_normalized_encoded_id!
+        raise ActiveRecord::ReadonlyAttributeError, "You cannot update the normalized encoded ID '#{normalized_encoded_id}' of a record #{self.class.name} #{id}, if you need to refresh it use set_normalized_encoded_id!"
+      end
+
+      # @rbs () -> void
+      def prevent_update_of_prefixed_encoded_id!
+        raise ActiveRecord::ReadonlyAttributeError, "You cannot update the prefixed encoded ID '#{prefixed_encoded_id}' of a record #{self.class.name} #{id}, if you need to refresh it use set_normalized_encoded_id!"
+      end
+    end
+  end
+end

data/lib/encoded_id/rails/query_methods.rb

@@ -1,12 +1,28 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 module EncodedId
   module Rails
     module QueryMethods
-      def where_encoded_id(slugged_encoded_id)
-        decoded_id = decode_encoded_id(slugged_encoded_id)
-        raise ActiveRecord::RecordNotFound if decoded_id.nil?
-        where(id: decoded_id)
+      # Methods provided by other mixins/ActiveRecord
+      # @rbs!
+      #   def decode_encoded_id: (String) -> Array[Integer]?
+      #   def where: (**untyped) -> untyped
+
+      # @rbs (*String slugged_encoded_ids) -> untyped
+      def where_encoded_id(*slugged_encoded_ids)
+        slugged_encoded_ids = slugged_encoded_ids.flatten
+
+        raise ::ActiveRecord::RecordNotFound if slugged_encoded_ids.empty?
+
+        decoded_ids = slugged_encoded_ids.flat_map do |slugged_encoded_id|
+          decode_encoded_id(slugged_encoded_id).tap do |decoded_id|
+            raise ::ActiveRecord::RecordNotFound if decoded_id.nil?
+          end
+        end
+
+        where(id: decoded_ids)
       end
     end
   end

data/lib/encoded_id/rails/railtie.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# rbs_inline: enabled
+
+module EncodedId
+  module Rails
+    # Railtie for Rails integration
+    class Railtie < ::Rails::Railtie
+      # initializer "encoded_id.rails.initialize" do
+      # end
+    end
+  end
+end

data/lib/encoded_id/rails/salt.rb

@@ -1,13 +1,20 @@
 # frozen_string_literal: true
 
+# rbs_inline: enabled
+
 module EncodedId
   module Rails
     class Salt
+      # @rbs @klass: Class
+      # @rbs @salt: String
+
+      # @rbs (Class klass, String salt) -> void
       def initialize(klass, salt)
         @klass = klass
         @salt = salt
       end
 
+      # @rbs return: String
       def generate!
         unless @klass.respond_to?(:name) && @klass.name.present?
           raise ::StandardError, "The class must have a `name` to ensure encode id uniqueness. " \