encoded_id-rails 0.6.2 → 1.0.0.beta2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f6c56ae6571c9793eb8b20d4cb2d9bfbbc3e1ebf1c313b774c42640ea68d6584
-  data.tar.gz: 58b5fbf9eb0e79fc152f23a2055f7c9ec2131dd5000342f0fe3d2e40f796f712
+  metadata.gz: 0a92cfd619fa254d0996950214c14aa115d6c62327e4ec2a6715dc9d7d898ebf
+  data.tar.gz: 27b448535392de1e1e21c37b82c324e4b5aecdc5225d4c7b2757a1ce8d5d18a9
 SHA512:
-  metadata.gz: cf5668fbf5100a23b4b4019392ac2f1a0325af3288427c96909183fa3e3a2111689d3f349d187b88ecd456e02a4796256c8d3f81e288dd65464e5ba623e83a48
-  data.tar.gz: b6191f0ee41f5732e0706b20b44ce74627d1ff9a5683447b57abe8ffe0ea351d9bee39df4e1b4f755654722547b814d572689c2d1cdf73b22a697962a5eac2d0
+  metadata.gz: 1ad6f6555bbdb19650f16220dedc81c733f847931a6eea27e28e69c9050f6542d28b8295a6ef3395c95bfe5480c22cc7e1ea224dc687616634ad34da58a71ddf
+  data.tar.gz: 53d42d543a9c86fd2ab3842bad841e7aff95cdc57059bbade5529183df3fa3ee426525d1100174d22821644c5f3915b0bef4e4c252ea56d4c08352bc662aa00f

data/CHANGELOG.md

@@ -1,5 +1,28 @@
 ## [Unreleased]
 
+## [1.0.0] - (in beta)
+
+### Breaking changes
+
+- `#encoded_id` now defaults to returning an 'annotated' ID, one in which a prefix is added to the encoded ID to indicate 
+  the 'type' of the record the ID represents. This can be disabled. IDs generated by older versions of this gem will 
+  decode correctly. But not that IDs generated by this version onwards will not decode correctly by older versions of this 
+  gem so make sure to disable annotation if you need to support older versions of this gem.
+- `#name_for_encoded_id_slug` no longer provides a default implementation, it is up to the user to define this method,
+  or configure the gem to use a different method name.
+- `#slugged_encoded_id` no longer takes a `with:` parameter. To specify the name of the method to call to generate the
+  slug, use the `slug_value_method_name` configuration option.
+
+### Added
+
+- `#encoded_id_hash` has been added to return only the encoded ID without an annotation prefix. If annotation is disabled, 
+  this method is basically an alias to `#encoded_id`.
+- `.find_all_by_encoded_id` has been added to return all records matching the given encoded ID. This will return all
+  matching records whose IDs are encoded in the encoded_id. Missing records are ignored.
+- `.find_all_by_encoded_id!` like `.find_all_by_encoded_id` but raises an `ActiveRecord::RecordNotFound` exception if
+  *any* of the records are not found.
+
+
 ## [0.6.2] - 2023-02-09
 
 - Fix `encoded_id` memoization clearing when record is duplicated

data/Gemfile

@@ -10,9 +10,9 @@ group :development, :test do
 
   gem "minitest", "~> 5.0"
 
-  gem "standard", "~> 1.3"
+  gem "standard", "~> 1.30"
 
-  gem "steep", "~> 1.2"
+  gem "steep", "~> 1.5"
 
   gem "sqlite3", "~> 1.5"
 end

data/README.md

@@ -1,30 +1,19 @@
 # EncodedId::Rails (`encoded_id-rails`)
 
-[EncodedId](https://github.com/stevegeek/encoded_id) for Rails and `ActiveRecord` models.
+`EncodedId::Rails` lets you turn numeric or hex **IDs into reversible and human friendly obfuscated strings**. The gem brings [EncodedId](https://github.com/stevegeek/encoded_id) to Rails and `ActiveRecord` models.
 
-EncodedID lets you turn numeric or hex IDs into reversible and human friendly obfuscated strings.
+You can use it in routes for example, to go from something like `/users/725` to `/users/bob-smith--usr_p5w9-z27j` with miminal effort.
 
-```ruby
-class User < ApplicationRecord
-  include EncodedId::Model
-
-  def name_for_encoded_id_slug
-    full_name
-  end
-end
-
-user = User.find_by_encoded_id("p5w9-z27j") # => #<User id: 78>
-user.encoded_id                             # => "p5w9-z27j"
-user.slugged_encoded_id                     # => "bob-smith--p5w9-z27j"
-```
+## Features
 
-# Features
+Under the hood it uses hashIds, but it offers more features.
 
-- encoded IDs are reversible (see [`encoded_id`](https://github.com/stevegeek/encoded_id))
-- supports slugged IDs (eg `my-cool-product-name--p5w9-z27j`) that are URL friendly (assuming your alphabet is too)
-- encoded string can be split into groups of letters to improve human-readability (eg `abcd-efgh`)
-- supports multiple IDs encoded in one encoded string (eg imagine the encoded ID `7aq60zqw` might decode to two IDs `[78, 45]`)
-- supports custom alphabets for the encoded string (at least 16 characters needed)
+- 🔄 encoded IDs are reversible (see [`encoded_id`](https://github.com/stevegeek/encoded_id))
+- 💅 supports slugged IDs (eg `my-cool-product-name--p5w9-z27j`) that are URL friendly (assuming your alphabet is too)
+- 🔖 supports annotated IDs to help identify the model the encoded ID belongs to (eg for a `User` the encoded ID might be `user_p5w9-z27j`) 
+- 👓 encoded string can be split into groups of letters to improve human-readability (eg `abcd-efgh`)
+- 👥 supports multiple IDs encoded in one encoded string (eg imagine the encoded ID `7aq60zqw` might decode to two IDs `[78, 45]`)
+- 🔡 supports custom alphabets for the encoded string (at least 16 characters needed)
   - by default uses a variation of the Crockford reduced character set (https://www.crockford.com/base32.html) 
   - easily confused characters (eg i and j, 0 and O, 1 and I etc) are mapped to counterpart characters, to 
     help avoid common readability mistakes when reading/sharing
@@ -36,24 +25,55 @@ The gem provides:
   or query by encoded IDs
 - sensible defaults to allow you to get started out of the box
 
-### Coming in future (?)
+```ruby
+class User < ApplicationRecord
+  include EncodedId::Model
+
+  # An optional slug for the encoded ID string. This is prepended to the encoded ID string, and is solely 
+  # to make the ID human friendly, or useful in URLs. It is not required for finding records by encoded ID.
+  def name_for_encoded_id_slug
+    full_name
+  end
+  
+  # An optional prefix on the encoded ID string to help identify the model it belongs to.
+  # Default is to use model's parameterized name, but can be overridden, or disabled.
+  # Note it is not required for finding records by encoded ID.
+  def annotation_for_encoded_id
+    "usr"
+  end
+end
+
+# You can find by the encoded ID
+user = User.find_by_encoded_id("p5w9-z27j") # => #<User id: 78>
+user.encoded_id                             # => "usr_p5w9-z27j"
+user.slugged_encoded_id                     # => "bob-smith--usr_p5w9-z27j"
 
-- support for UUIDs for IDs (which will be encoded as an array of integers)
+# You can find by a slugged & annotated encoded ID
+user == User.find_by_encoded_id("bob-smith--usr_p5w9-z27j") # => true
 
-# Why this gem?
+# Encoded IDs can encode multiple IDs at the same time
+users = User.find_all_by_encoded_id("7aq60zqw") # => [#<User id: 78>, #<User id: 45>]
+```
+
+## Why this gem?
 
 With this gem you can easily obfuscate your IDs in your URLs, and still be able to find records by using
 the encoded IDs. The encoded IDs are meant to be somewhat human friendly, to make communication easier
 when sharing encoded IDs with other people. 
 
 * Hashids are reversible, no need to persist the generated Id
-* we don't override any AR methods. `encoded_id`s are intentionally not interchangeable with normal record `id`s 
+* we don't override any AR methods. `encoded_id`s are intentionally **not interchangeable** with normal record `id`s 
   (ie you can't use `.find` to find by encoded ID or record ID, you must be explicit)
 * we support slugged IDs (eg `my-amazing-product--p5w9-z27j`)
 * we support multiple model IDs encoded in one `EncodedId` (eg `7aq6-0zqw` might decode to `[78, 45]`)
 * the gem is configurable
 * encoded IDs can be stable across environments, or not (you can set the salt to different values per environment)
 
+
+## Coming in future (?)
+
+- support for UUIDs for IDs (which will be encoded as an array of integers)
+
 ## Installation
 
 Install the gem and add to the application's Gemfile by executing:
@@ -135,6 +155,8 @@ user = User.find_by_encoded_id("p5w9-z27j")  # => #<User id: 78>
 user.encoded_id  # => "p5w9-z27j"
 ```
 
+Note when an encoded ID string contains multiple IDs, this method will return the record for the first ID.
+
 ### `.find_by_encoded_id!`
 
 Like `.find!` but accepts an encoded ID string instead of an ID. Raises `ActiveRecord::RecordNotFound` if no record is found.
@@ -146,6 +168,18 @@ user = User.find_by_encoded_id!("p5w9-z27j")  # => #<User id: 78>
 user = User.find_by_encoded_id!("encoded-id-that-is-not-found")  # => ActiveRecord::RecordNotFound
 ```
 
+Note when an encoded ID string contains multiple IDs, this method will return the record for the first ID.
+
+### `.find_all_by_encoded_id`
+
+Like `.find_by_encoded_id` but when an encoded ID string contains multiple IDs, 
+this method will return an array of records.
+
+### `.find_all_by_encoded_id!`
+
+Like `.find_by_encoded_id!` but when an encoded ID string contains multiple IDs, 
+this method will return an array of records.
+
 ### `.where_encoded_id`
 
 A helper for creating relations. Decodes the encoded ID string before passing it to `.where`.
@@ -198,44 +232,90 @@ end
 User.encoded_id_salt  # => "my-user-model-salt"
 ```
 
+### `#encoded_id_hash`
+
+Returns only the encoded 'hashId' part of the encoded ID for the record:
+
+```ruby
+user = User.create(name: "Bob Smith")
+user.encoded_id  # => "p5w9-z27j"
+```
+
+
 ### `#encoded_id`
 
-Use the `encoded_id` instance method to get the encoded ID for the record:
+Returns the encoded ID for the record, with an annotation (if it is enabled):
 
 ```ruby
 user = User.create(name: "Bob Smith")
+user.encoded_id  # => "user_p5w9-z27j"
+```
+
+By default, the annotation comes from the underscored model name. However, you can change this by either:
+
+- overriding `#annotation_for_encoded_id` on the model
+- overriding `#annotation_for_encoded_id` on all models via your `ApplicationRecord`
+- change the method called to get the annotation via setting the `annotation_method_name` config options in your initializer
+- disable the annotation via setting the `annotation_method_name` config options in your initializer to `nil`
+
+
+Examples: 
+
+```ruby
+EncodedId::Rails.configuration.annotation_method_name = :name
+user.encoded_id  # => "bob_smith_p5w9-z27j"
+```
+
+```ruby
+EncodedId::Rails.configuration.annotation_method_name = nil
 user.encoded_id  # => "p5w9-z27j"
 ```
 
+```ruby
+class User < ApplicationRecord
+  include EncodedId::Model
+  
+  def annotation_for_encoded_id
+    "foo"
+  end
+end
+
+user = User.create(name: "Bob Smith")
+user.encoded_id  # => "foo_p5w9-z27j"
+```
+
+Note that you can also configure the annotation separator via the `annotated_id_separator` config option in your initializer,
+but it must be set to a string that only contains character that are not part of the alphabet used to encode the ID.
+
+```ruby
+EncodedId::Rails.configuration.annotated_id_separator = "^^"
+user.encoded_id  # => "foo^^p5w9-z27j"
+```
 
 ### `#slugged_encoded_id`
 
 Use the `slugged_encoded_id` instance method to get the slugged version of the encoded ID for the record. 
-Calls `#name_for_encoded_id_slug` on the record to get the slug part of the encoded ID:
 
 ```ruby
 user = User.create(name: "Bob Smith")
 user.slugged_encoded_id  # => "bob-smith--p5w9-z27j"
 ```
 
-### `#name_for_encoded_id_slug`
-
-Use `#name_for_encoded_id_slug` to specify what will be used to create the slug part of the encoded ID. 
-By default it calls `#name` on the instance, or if the instance does not respond to 
-`name` (or the value returned is blank) then uses the Model name.
+Calls `#name_for_encoded_id_slug` on the record to get the slug part of the encoded ID.
+By default, `#name_for_encoded_id_slug` raises, and must be overridden, or configured via the `slug_value_method_name` config option in your initializer:
 
 ```ruby
 class User < ApplicationRecord
   include EncodedId::Model
 
-  # If User has an attribute `name`, that will be used for the slug, 
-  # otherwise `user` will be used as determined by the class name.
+  # Assuming user has a name attribute
+  def name_for_encoded_id_slug
+    name
+  end
 end
 
 user = User.create(name: "Bob Smith")
 user.slugged_encoded_id  # => "bob-smith--p5w9-z27j"
-user2 = User.create(name: "")
-user2.slugged_encoded_id  # => "user--i74r-bn28"
 ```
 
 You can optionally override this method to define your own slug:
@@ -253,6 +333,21 @@ user = User.create(superhero_name: "Super Dev")
 user.slugged_encoded_id  # => "super-dev--37nw-8nh7"
 ```
 
+Configure the method called by setting the `slug_value_method_name` config option in your initializer:
+
+```ruby
+EncodedId::Rails.configuration.slug_value_method_name = :name
+user.slugged_encoded_id  # => "bob-smith--p5w9-z27j"
+```
+
+Note that you can also configure the slug separator via the `slugged_id_separator` config option in your initializer,
+but it must be set to a string that only contains character that are not part of the alphabet used to encode the ID.
+
+```ruby
+EncodedId::Rails.configuration.annotated_id_separator = "***"
+user.encoded_id  # => "bob-smith***p5w9-z27j"
+```
+
 ## To use on all models
 
 Simply add the mixin to your `ApplicationRecord`:
@@ -268,6 +363,34 @@ end
 
 However, I recommend you only use it on the models that need it.
 
+## Example usage for a route and controller
+
+```ruby
+# Route
+resources :users, param: :encoded_id, only: [:show]
+```
+
+```ruby
+# Model
+class User < ApplicationRecord
+  include EncodedId::Model
+  include EncodedId::PathParam
+end
+```
+
+```ruby
+# Controller
+class UsersController < ApplicationController
+  def show
+    @user = User.find_by_encoded_id!(params[:encoded_id])
+  end
+end
+```
+
+```erb 
+<%= link_to "User", user_path %>
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.

data/Steepfile

@@ -1,6 +1,4 @@
 target :lib do
   check "lib/encoded_id"
   signature "sig"
-
-  library "encoded_id"
 end

data/lib/encoded_id/rails/annotated_id.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "cgi"
+
+module EncodedId
+  module Rails
+    class AnnotatedId
+      def initialize(annotation:, id_part:, separator: "_")
+        @annotation = annotation
+        @id_part = id_part
+        @separator = separator
+      end
+
+      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}"
+      end
+    end
+  end
+end

data/lib/encoded_id/rails/annotated_id_parser.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module EncodedId
+  module Rails
+    class AnnotatedIdParser
+      def initialize(annotated_id, separator: "_")
+        if separator && annotated_id.include?(separator)
+          parts = annotated_id.split(separator)
+          @id = parts.last
+          @annotation = parts[0..-2]&.join(separator)
+        else
+          @id = annotated_id
+        end
+      end
+
+      attr_reader :annotation, :id
+    end
+  end
+end

data/lib/encoded_id/rails/configuration.rb

@@ -4,19 +4,46 @@ module EncodedId
   module Rails
     # Configuration class for initializer
     class Configuration
-      attr_accessor :salt,
-        :character_group_size,
-        :group_separator,
-        :alphabet,
-        :id_length,
-        :slugged_id_separator
+      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
 
       def initialize
         @character_group_size = 4
         @group_separator = "-"
         @alphabet = ::EncodedId::Alphabet.modified_crockford
         @id_length = 8
+        @slug_value_method_name = :name_for_encoded_id_slug
         @slugged_id_separator = "--"
+        @annotation_method_name = :annotation_for_encoded_id
+        @annotated_id_separator = "_"
+      end
+
+      # Perform validation vs alphabet on these assignments
+
+      def group_separator=(value)
+        unless valid_separator?(value, alphabet)
+          raise ArgumentError, "Group separator characters must not be part of the alphabet"
+        end
+        @group_separator = value
+      end
+
+      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
+        @slugged_id_separator = value
+      end
+
+      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
+        @annotated_id_separator = value
+      end
+
+      def valid_separator?(separator, characters)
+        separator.chars.none? { |v| characters.include?(v) }
       end
     end
   end

data/lib/encoded_id/rails/encoder_methods.rb

@@ -10,7 +10,8 @@ module EncodedId
 
       def decode_encoded_id(slugged_encoded_id, options = {})
         return if slugged_encoded_id.blank?
-        encoded_id = encoded_id_parser(slugged_encoded_id).id
+        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
         return if !encoded_id || encoded_id.blank?
         encoded_id_coder(options).decode(encoded_id)
       end
@@ -21,10 +22,6 @@ module EncodedId
         EncodedId::Rails::Salt.new(self, EncodedId::Rails.configuration.salt).generate!
       end
 
-      def encoded_id_parser(slugged_encoded_id)
-        SluggedIdParser.new(slugged_encoded_id, separator: EncodedId::Rails.configuration.slugged_id_separator)
-      end
-
       def encoded_id_coder(options = {})
         config = EncodedId::Rails.configuration
         EncodedId::Rails::Coder.new(

data/lib/encoded_id/rails/finder_methods.rb

@@ -4,24 +4,38 @@ module EncodedId
   module Rails
     module FinderMethods
       # Find by encoded ID and optionally ensure record ID is the same as constraint (can be slugged)
-      def find_by_encoded_id(slugged_encoded_id, with_id: nil)
-        decoded_id = decode_encoded_id(slugged_encoded_id)
-        return if decoded_id.blank?
-        record = find_by(id: decoded_id)
+      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?
+        record = find_by(id: decoded_id.first)
         return unless record
         return if with_id && with_id != record.send(:id)
         record
       end
 
-      def find_by_encoded_id!(slugged_encoded_id, with_id: nil)
-        decoded_id = decode_encoded_id(slugged_encoded_id)
-        raise ActiveRecord::RecordNotFound if decoded_id.blank?
-        record = find_by(id: decoded_id)
+      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?
+        record = find_by(id: decoded_id.first)
         if !record || (with_id && with_id != record.send(:id))
           raise ActiveRecord::RecordNotFound
         end
         record
       end
+
+      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
+
+      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?
+        records = where(id: decoded_ids).to_a
+        raise ActiveRecord::RecordNotFound if records.blank? || records.size != decoded_ids.size
+        records
+      end
     end
   end
 end

data/lib/encoded_id/rails/model.rb

@@ -12,35 +12,51 @@ module EncodedId
         base.extend(QueryMethods)
       end
 
+      def encoded_id_hash
+        return unless id
+        return @encoded_id_hash if defined?(@encoded_id_hash) && !id_changed?
+        self.class.encode_encoded_id(id)
+      end
+
       def encoded_id
         return unless id
         return @encoded_id if defined?(@encoded_id) && !id_changed?
-        @encoded_id = self.class.encode_encoded_id(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
+        @encoded_id = EncodedId::Rails::AnnotatedId.new(id_part: encoded, annotation: send(annotated_by.to_s), separator: separator).annotated_id
       end
 
-      def slugged_encoded_id(with: :name_for_encoded_id_slug)
+      def slugged_encoded_id
         return unless id
         return @slugged_encoded_id if defined?(@slugged_encoded_id) && !id_changed?
-        @slugged_encoded_id = EncodedId::Rails::SluggedId.new(
-          self,
-          slug_method: with,
-          id_method: :encoded_id,
-          separator: EncodedId::Rails.configuration.slugged_id_separator
-        ).slugged_id
+        with = EncodedId::Rails.configuration.slug_value_method_name
+        separator = EncodedId::Rails.configuration.slugged_id_separator
+        encoded = encoded_id
+        return unless encoded
+        @slugged_encoded_id = EncodedId::Rails::SluggedId.new(id_part: encoded, slug_part: send(with.to_s), separator: separator).slugged_id
+      end
+
+      # By default the annotation is the model name (it will be parameterized)
+      def annotation_for_encoded_id
+        name = self.class.name
+        raise StandardError, "The default annotation requires the model class to have a name" if name.nil?
+        name.underscore
       end
 
-      # By default slug created from class name, but can be overridden
+      # 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
-        class_name = self.class.name
-        raise StandardError, "Class must have a `name`, cannot create a slug" if !class_name || class_name.blank?
-        class_name.underscore
+        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
       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.send(:remove_instance_variable, :@slugged_encoded_id) if new_record.instance_variable_defined?(:@slugged_encoded_id)
         end
       end
     end

data/lib/encoded_id/rails/path_param.rb

@@ -7,7 +7,7 @@ module EncodedId
   module Rails
     module PathParam
       def to_param
-        encoded_id
+        encoded_id || raise(StandardError, "Cannot create path param for #{self.class.name} without an encoded id")
       end
     end
   end

data/lib/encoded_id/rails/slugged_id.rb

@@ -5,20 +5,17 @@ require "cgi"
 module EncodedId
   module Rails
     class SluggedId
-      def initialize(from_object, slug_method: :name_for_encoded_id_slug, id_method: :id, separator: "--")
-        @from_object = from_object
-        @slug_method = slug_method
-        @id_method = id_method
+      def initialize(slug_part:, id_part:, separator: "--")
+        @slug_part = slug_part
+        @id_part = id_part
         @separator = separator
       end
 
       def slugged_id
-        slug_part = @from_object.send(@slug_method)
-        id_part = @from_object.send(@id_method)
-        unless id_part.present? && slug_part.present?
-          raise ::StandardError, "The model does not return a valid ID (:#{@id_method}) and/or slug (:#{@slug_method})"
+        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}"
+        "#{@slug_part.to_s.parameterize}#{CGI.escape(@separator)}#{@id_part}"
       end
     end
   end

data/lib/encoded_id/rails/slugged_path_param.rb

@@ -7,7 +7,7 @@ module EncodedId
   module Rails
     module SluggedPathParam
       def to_param
-        slugged_encoded_id
+        slugged_encoded_id || raise(StandardError, "Cannot create path param for #{self.class.name} without an encoded id")
       end
     end
   end

data/lib/encoded_id/rails/version.rb

@@ -2,6 +2,6 @@
 
 module EncodedId
   module Rails
-    VERSION = "0.6.2"
+    VERSION = "1.0.0.beta2"
   end
 end

data/lib/encoded_id/rails.rb

@@ -5,6 +5,8 @@ require_relative "rails/configuration"
 require_relative "rails/coder"
 require_relative "rails/slugged_id"
 require_relative "rails/slugged_id_parser"
+require_relative "rails/annotated_id"
+require_relative "rails/annotated_id_parser"
 require_relative "rails/salt"
 require_relative "rails/encoder_methods"
 require_relative "rails/query_methods"

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

@@ -41,4 +41,30 @@ EncodedId::Rails.configure do |config|
   # 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 = "_"
 end

data/rbs_collection.yaml

@@ -9,8 +9,6 @@ sources:
 path: .gem_rbs_collection
 
 gems:
-  - name: encoded_id-rails
-    ignore: true
   - name: cgi
   # Skip loading rbs gem's RBS.
   # It's unnecessary if you don't use rbs as a library.

data/sig/encoded_id/rails.rbs

@@ -8,7 +8,10 @@ module EncodedId
       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 slugged_id_separator: ::String
+      attr_accessor annotation_method_name: ::Symbol
+      attr_accessor annotated_id_separator: ::String
 
       def initialize: () -> void
     end
@@ -43,28 +46,41 @@ module EncodedId
     end
 
     class SluggedId
-      def initialize: (untyped from_object, ?slug_method: ::Symbol, ?id_method: ::Symbol, ?separator: ::String)-> void
-
-      @from_object: untyped
-      @slug_method: ::Symbol
-      @id_method: ::Symbol
+      def initialize: (slug_part: ::String, id_part: ::String, ?separator: ::String)-> void
+      @slug_part: ::String
+      @id_part: ::String
       @separator: ::String
 
       def slugged_id: -> ::String
     end
 
+    class AnnotatedId
+      def initialize: (annotation: ::String, id_part: ::String, ?separator: ::String)-> void
+      @annotation: ::String
+      @id_part: ::String
+      @separator: ::String
+
+      def annotated_id: -> ::String
+    end
+
     class SluggedIdParser
       def initialize: (::String slugged_id, ?separator: ::String) -> void
 
       attr_reader slug: ::String?
-      attr_reader id: ::String?
+      attr_reader id: ::String
+    end
+
+    class AnnotatedIdParser
+      def initialize: (::String annotated_id, ?separator: ::String) -> void
+
+      attr_reader annotation: ::String?
+      attr_reader id: ::String
     end
 
     module EncoderMethods
-      def encode_encoded_id: (untyped id, ?::Hash[::Symbol, untyped] options) -> ::String
+      def encode_encoded_id: (::Array[::Integer] | ::Integer id, ?::Hash[::Symbol, untyped] options) -> ::String
       def decode_encoded_id: (::String slugged_encoded_id, ?::Hash[::Symbol, untyped] options) -> ::Array[::Integer]?
       def encoded_id_salt: () -> ::String
-      def encoded_id_parser: (::String slugged_encoded_id) -> ::EncodedId::Rails::SluggedIdParser
       def encoded_id_coder: (?::Hash[::Symbol, untyped] options) -> ::EncodedId::Rails::Coder
     end
 
@@ -72,9 +88,11 @@ module EncodedId
       def find_by: (*untyped) -> (nil | untyped)
     end
 
-    module FinderMethods : EncoderMethods, _ActiveRecordFinderMethod
-      def find_by_encoded_id: (::String slugged_encoded_id, ?with_id: ::Symbol?) -> untyped?
-      def find_by_encoded_id!: (::String slugged_encoded_id, ?with_id: ::Symbol?) -> untyped
+    module FinderMethods : EncoderMethods, _ActiveRecordFinderMethod, _ActiveRecordQueryMethod
+      def find_by_encoded_id: (::String encoded_id, ?with_id: ::Symbol?) -> untyped?
+      def find_by_encoded_id!: (::String encoded_id, ?with_id: ::Symbol?) -> untyped
+      def find_all_by_encoded_id: (::String encoded_id) -> untyped?
+      def find_all_by_encoded_id!: (::String encoded_id) -> untyped
     end
 
     interface _ActiveRecordQueryMethod
@@ -86,9 +104,12 @@ module EncodedId
     end
 
     module Model : ActiveRecord::Base
+      # From ActiveRecord
       extend ActiveRecord::FinderMethods
       extend ActiveRecord::QueryMethods
+      def id_changed?: -> bool
 
+      # From EncodedId::Rails::Model
       extend EncoderMethods
       extend FinderMethods
       extend QueryMethods
@@ -96,13 +117,15 @@ module EncodedId
       @encoded_id: ::String
       @slugged_encoded_id: ::String
 
-      def encoded_id: () -> ::String
-      def slugged_encoded_id: (?with: ::Symbol) -> ::String
-      def name_for_encoded_id_slug: () -> ::String
+      def encoded_id_hash: -> ::String?
+      def encoded_id: -> ::String?
+      def slugged_encoded_id: -> ::String?
+      def name_for_encoded_id_slug: -> ::String
+      def annotation_for_encoded_id: -> ::String
     end
 
     interface _ActiveRecordToParam
-      def to_param: () -> ::String
+      def to_param: -> ::String
     end
 
     module PathParam : Model, _ActiveRecordToParam

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: encoded_id-rails
 version: !ruby/object:Gem::Version
-  version: 0.6.2
+  version: 1.0.0.beta2
 platform: ruby
 authors:
 - Stephen Ierodiaconou
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-02-09 00:00:00.000000000 Z
+date: 2023-10-23 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -56,14 +56,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.4'
+        version: 1.0.0.rc3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.4'
+        version: 1.0.0.rc3
 description: ActiveRecord concern to use EncodedID to turn IDs into reversible and
   human friendly obfuscated strings.
 email:
@@ -82,6 +82,8 @@ files:
 - gemfiles/rails_6.0.gemfile
 - gemfiles/rails_7.0.gemfile
 - lib/encoded_id/rails.rb
+- lib/encoded_id/rails/annotated_id.rb
+- lib/encoded_id/rails/annotated_id_parser.rb
 - lib/encoded_id/rails/coder.rb
 - lib/encoded_id/rails/configuration.rb
 - lib/encoded_id/rails/encoder_methods.rb
@@ -117,11 +119,11 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: 2.6.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
-  - - ">="
+  - - ">"
     - !ruby/object:Gem::Version
-      version: '0'
+      version: 1.3.1
 requirements: []
-rubygems_version: 3.3.26
+rubygems_version: 3.4.20
 signing_key:
 specification_version: 4
 summary: Use `encoded_id` with ActiveRecord models