encoded_id-rails 0.3.1 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b4be4ce77532e0194a29d624cb4e9ae4dd1f783ead388ba73b00abc21c27b431
-  data.tar.gz: 41a11cd3abe1a15096a1eac101e54374edd69ec813689879fa2debdce684d949
+  metadata.gz: 0aceb28e50697bb0257054c2731936a7cad5f6617d479543c63999a156c153bf
+  data.tar.gz: 59be3ddf7327f26726df0aa3120f9a70de0ac225d77291ad8e35b10b937e6264
 SHA512:
-  metadata.gz: d68f3f4cbec0a64615141ff9edc627e986fa18b5ac2d2e274e86cc149893482e1331fc8b0fb6c9e1f7dbe411790cbb0c7dfdd301ecd46f1b5da233320f461fb4
-  data.tar.gz: a879ab60759348cb5b53e9f092736debd515dca16a852af79ea53750a3b97bea0dd69151825379e578e65d024fcf375db15746a7f4f398b7746a179490077dec
+  metadata.gz: 821e8ffcb7f77bdc84160a69bbc504ec891f9b11d925e4aa5d52f1209f426d894671cc603b850ee1a408dfa255c9b00eeaed6938eb1440aec4a31af27209f484
+  data.tar.gz: a168a3da9c882a0e1c9f159cfcfeaeaf02109049aed2f2330b9a51708cee927896a911cae63833ec11955a0139af6aa9a3302a9e970a9f461024d4a870730bf2

data/Gemfile

@@ -5,12 +5,14 @@ source "https://rubygems.org"
 # Specify your gem's dependencies in encoded_id-rails.gemspec
 gemspec
 
-gem "rake", "~> 13.0"
+group :development, :test do
+  gem "rake", "~> 13.0"
 
-gem "minitest", "~> 5.0"
+  gem "minitest", "~> 5.0"
 
-gem "standard", "~> 1.3"
+  gem "standard", "~> 1.3"
 
-gem "steep", "~> 1.2"
+  gem "steep", "~> 1.2"
 
-gem "sqlite3", "~> 1.5"
+  gem "sqlite3", "~> 1.5"
+end

data/README.md

@@ -1,41 +1,58 @@
-# EncodedId::Rails
+# EncodedId::Rails (`encoded_id-rails`)
 
-EncodedId mixin for your ActiveRecord models.
+[EncodedId](https://github.com/stevegeek/encoded_id) for Rails and `ActiveRecord` models.
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/encoded_id/rails`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
+EncodedID lets you turn numeric or hex IDs into reversible and human friendly obfuscated strings.
 
 ```ruby
 class User < ApplicationRecord
   include EncodedId::WithEncodedId
   
-  def slug
+  def name_for_encoded_id_slug
     full_name.parameterize
   end
 end
 
 user = User.find_by_encoded_id("p5w9-z27j")  # => #<User id: 78>
 user.encoded_id  # => "p5w9-z27j"
-user.slugged_id  # => "bob-smith--p5w9-z27j"
+user.slugged_encoded_id  # => "bob-smith--p5w9-z27j"
 ```
+
 # 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)
+  - 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
+  - build in profanity limitation
 
+The gem provides:
 
-# Coming in future (?)
+- methods to mixin to ActiveRecord models which will allow you to encode and decode IDs, and find
+  or query by encoded IDs
+- sensible defaults to allow you to get started out of the box
+
+### Coming in future (?)
 
 - support for UUIDs for IDs (which will be encoded as an array of integers)
 
-## Why this?
+# 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 methods or mess with ActiveRecord
-* we support slugged IDs (eg 'my-amazing-product--p5w9-z27j')
-* we support multiple model IDs encoded in one `EncodedId` (eg '7aq6-0zqw' decodes to `[78, 45]`)
-* we use a reduced character set (Crockford alphabet),
-  and ids split into groups of letters, ie we aim for 'human-readability'
-* can be stable across environments, or not (you can set the salt to different values per environment)
+* 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)
 
 ## Installation
 
@@ -53,9 +70,165 @@ Then run the generator to add the initializer:
 
 ## Usage
 
-TODO: Write usage instructions here
+### Configuration
+
+The install generator will create an initializer file [`config/initializers/encoded_id.rb`](https://github.com/stevegeek/encoded_id-rails/blob/main/lib/generators/encoded_id/rails/templates/encoded_id.rb). It is documented
+and should be self-explanatory.
+
+You can configure:
+
+- a global salt needed to generate the encoded IDs (if you dont use a global salt, you can set a salt per model)
+- the size of the character groups in the encoded string (default is 4) 
+- the separator between the character groups (default is '-')
+- the alphabet used to generate the encoded string (default is a variation of the Crockford reduced character set)
+- the minimum length of the encoded ID string (default is 8 characters)
+
+### ActiveRecord model setup
+
+Include `EncodedId::WithEncodedId` in your model and optionally specify a encoded id salt (or not if using a global one):
+
+```ruby
+class User < ApplicationRecord
+  include EncodedId::WithEncodedId
+  
+  # and optionally the model's salt
+  def encoded_id_salt
+    "my-user-model-salt"
+  end
+  
+  # ...
+end
+```
+
+## Documentation
+
+### `.find_by_encoded_id`
+
+Like `.find` but accepts an encoded ID string instead of an ID. Will return `nil` if no record is found.
+
+```ruby
+user = User.find_by_encoded_id("p5w9-z27j")  # => #<User id: 78>
+user.encoded_id  # => "p5w9-z27j"
+```
 
-### Use on all models (but I recommend you don't)
+### `.find_by_encoded_id!`
+
+Like `.find!` but accepts an encoded ID string instead of an ID. Raises `ActiveRecord::RecordNotFound` if no record is found.
+
+```ruby
+user = User.find_by_encoded_id!("p5w9-z27j")  # => #<User id: 78>
+
+# raises ActiveRecord::RecordNotFound
+user = User.find_by_encoded_id!("encoded-id-that-is-not-found")  # => ActiveRecord::RecordNotFound
+```
+
+### `.where_encoded_id`
+
+A helper for creating relations. Decodes the encoded ID string before passing it to `.where`.
+
+```ruby
+encoded_id = User.encode_encoded_id([user1.id, user2.id])  # => "p5w9-z27j"
+User.where(active: true)
+  .where_encoded_id(encoded_id)
+  .map(&:name) # => ["Bob Smith", "Jane Doe"]
+```
+
+### `.encode_encoded_id`
+
+Encodes an ID or array of IDs into an encoded ID string.
+
+```ruby
+User.encode_encoded_id(78)  # => "p5w9-z27j"
+User.encode_encoded_id([78, 45])  # => "7aq6-0zqw"
+```
+
+### `.decode_encoded_id`
+
+Decodes an encoded ID string into an array of IDs.
+
+```ruby
+User.decode_encoded_id("p5w9-z27j")  # => [78]
+User.decode_encoded_id("7aq6-0zqw")  # => [78, 45]
+```
+
+### `.encoded_id_salt`
+
+Returns the salt used to generate the encoded ID string. If not defined, the global salt is used
+with `EncodedId::Rails::Salt` to generate a model specific one.
+
+```ruby
+User.encoded_id_salt  # => "User/the-salt-from-the-initializer"
+```
+
+Otherwise override this method to return a salt specific to the model.
+
+```ruby
+class User < ApplicationRecord
+  include EncodedId::WithEncodedId
+  
+  def encoded_id_salt
+    "my-user-model-salt"
+  end
+end
+User.encoded_id_salt  # => "my-user-model-salt"
+```
+
+### `#encoded_id`
+
+Use the `encoded_id` instance method to get the encoded ID for the record:
+
+```ruby
+user = User.create(name: "Bob Smith")
+user.encoded_id  # => "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.
+
+```ruby
+class User < ApplicationRecord
+  include EncodedId::WithEncodedId
+  
+  # If User has an attribute `name`, that will be used for the slug, 
+  # otherwise `user` will be used as determined by the class name.
+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:
+
+```ruby
+class User < ApplicationRecord
+  include EncodedId::WithEncodedId
+  
+  def name_for_encoded_id_slug
+    superhero_name
+  end
+end
+
+user = User.create(superhero_name: "Super Dev")
+user.slugged_encoded_id  # => "super-dev--37nw-8nh7"
+```
+
+## To use on all models
 
 Simply add the mixin to your `ApplicationRecord`:
 
@@ -76,9 +249,24 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
+### Type check
+
+First install dependencies:
+
+```bash
+rbs collection install
+```
+
+Then run:
+
+```bash
+steep check
+```
+
+
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/encoded_id-rails.
+Bug reports and pull requests are welcome on GitHub at https://github.com/stevegeek/encoded_id-rails.
 
 ## License
 

data/lib/encoded_id/rails/coder.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module EncodedId
+  module Rails
+    class Coder
+      def initialize(salt:, id_length:, character_group_size:, separator:, alphabet:)
+        @salt = salt
+        @id_length = id_length
+        @character_group_size = character_group_size
+        @separator = separator
+        @alphabet = alphabet
+      end
+
+      def encode(id)
+        coder.encode(id)
+      end
+
+      def decode(encoded_id)
+        coder.decode(encoded_id)
+      rescue EncodedId::EncodedIdFormatError
+        nil
+      end
+
+      private
+
+      def coder
+        ::EncodedId::ReversibleId.new(
+          salt: @salt,
+          length: @id_length,
+          split_at: @character_group_size,
+          split_with: @separator,
+          alphabet: @alphabet
+        )
+      end
+    end
+  end
+end

data/lib/encoded_id/rails/configuration.rb

@@ -6,13 +6,17 @@ module EncodedId
     class Configuration
       attr_accessor :salt,
         :character_group_size,
+        :group_separator,
         :alphabet,
-        :id_length
+        :id_length,
+        :slugged_id_separator
 
       def initialize
         @character_group_size = 4
+        @group_separator = "-"
         @alphabet = ::EncodedId::Alphabet.modified_crockford
         @id_length = 8
+        @slugged_id_separator = "--"
       end
     end
   end

data/lib/encoded_id/rails/salt.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module EncodedId
+  module Rails
+    class Salt
+      def initialize(klass, salt)
+        @klass = klass
+        @salt = salt
+      end
+
+      def generate!
+        unless @klass.respond_to?(:name) && @klass.name.present?
+          raise ::StandardError, "The class must have a `name` to ensure encode id uniqueness. " \
+              "Please set a name on the class or override `encoded_id_salt`."
+        end
+        raise ::StandardError, "Encoded ID salt is invalid" if !@salt || @salt.blank? || @salt.size < 4
+        "#{@klass.name}/#{@salt}"
+      end
+    end
+  end
+end

data/lib/encoded_id/rails/slugged_id.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+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
+        @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})"
+        end
+        "#{slug_part.to_s.parameterize}#{CGI.escape(@separator)}#{id_part}"
+      end
+    end
+  end
+end

data/lib/encoded_id/rails/slugged_id_parser.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module EncodedId
+  module Rails
+    class SluggedIdParser
+      def initialize(slugged_id, separator: "--")
+        if separator && slugged_id.include?(separator)
+          parts = slugged_id.split(separator)
+          @slug = parts.first
+          @id = parts.last
+        else
+          @id = slugged_id
+        end
+      end
+
+      attr_reader :slug, :id
+    end
+  end
+end

data/lib/encoded_id/rails/version.rb

@@ -2,6 +2,6 @@
 
 module EncodedId
   module Rails
-    VERSION = "0.3.1"
+    VERSION = "0.4.0"
   end
 end

data/lib/encoded_id/rails/with_encoded_id.rb

@@ -13,161 +13,60 @@ module EncodedId
       module ClassMethods
         # 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)
-          encoded_id = extract_id_part(slugged_encoded_id)
-          decoded_id = decode_encoded_id(encoded_id)
-          return nil if decoded_id.nil?
-          find_via_custom_id(decoded_id, :id, compare_to: with_id)
+          decoded_id = decode_encoded_id(slugged_encoded_id)
+          return if decoded_id.blank?
+          record = find_by(id: decoded_id)
+          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)
-          encoded_id = extract_id_part(slugged_encoded_id)
-          decoded_id = decode_encoded_id(encoded_id)
-          raise ActiveRecord::RecordNotFound if decoded_id.nil?
-          find_via_custom_id!(decoded_id, :id, compare_to: with_id)
-        end
-
-        # Find by a fixed slug value (assumed as an attribute value in the DB)
-        def find_by_fixed_slug(slug, attribute: :slug, with_id: nil)
-          find_via_custom_id(slug, attribute, compare_to: with_id)
-        end
-
-        def find_by_fixed_slug!(slug, attribute: :slug, with_id: nil)
-          find_via_custom_id!(slug, attribute, compare_to: with_id)
-        end
-
-        # Find by record ID where the ID has been slugged
-        def find_by_slugged_id(slugged_id, with_id: nil)
-          id_part = decode_slugged_ids(slugged_id)
-          unless with_id.nil?
-            return unless with_id == id_part
+          decoded_id = decode_encoded_id(slugged_encoded_id)
+          raise ActiveRecord::RecordNotFound if decoded_id.blank?
+          record = find_by(id: decoded_id)
+          if !record || (with_id && with_id != record.send(:id))
+            raise ActiveRecord::RecordNotFound
           end
-          where(id: id_part)&.first
-        end
-
-        def find_by_slugged_id!(slugged_id, with_id: nil)
-          id_part = decode_slugged_ids(slugged_id)
-          unless with_id.nil?
-            raise ActiveRecord::RecordNotFound unless with_id == id_part
-          end
-          find(id_part)
+          record
         end
 
-        # relation helpers
-
         def where_encoded_id(slugged_encoded_id)
-          decoded_id = decode_encoded_id(extract_id_part(slugged_encoded_id))
+          decoded_id = decode_encoded_id(slugged_encoded_id)
           raise ActiveRecord::RecordNotFound if decoded_id.nil?
           where(id: decoded_id)
         end
 
-        def where_fixed_slug(slug, attribute: :slug)
-          where(attribute => slug)
+        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
 
-        def where_slugged_id(slugged_id)
-          id_part = decode_slugged_ids(slugged_id)
-          raise ActiveRecord::RecordNotFound if id_part.nil?
-          where(id: id_part)
-        end
-
-        # Encode helpers
-
-        def encode_encoded_id(id, options = {})
-          raise StandardError, "You must pass an ID" if id.blank?
-          hash_id_encoder(options).encode(id)
-        end
-
-        def encode_multi_encoded_id(encoded_ids, options = {})
-          raise ::StandardError, "You must pass IDs" if encoded_ids.blank?
-          hash_id_encoder(options).encode(encoded_ids)
-        end
-
-        # Decode helpers
-
-        # Decode a encoded_id (can be slugged)
         def decode_encoded_id(slugged_encoded_id, options = {})
-          internal_decode_encoded_id(slugged_encoded_id, options)&.first
-        end
-
-        def decode_multi_encoded_id(slugged_encoded_id, options = {})
-          internal_decode_encoded_id(slugged_encoded_id, options)
-        end
-
-        # Decode a Slugged ID
-        def decode_slugged_id(slugged)
-          return if slugged.blank?
-          extract_id_part(slugged).to_i
-        end
-
-        # Decode a set of slugged IDs
-        def decode_slugged_ids(slugged)
-          return if slugged.blank?
-          extract_id_part(slugged).split("-").map(&:to_i)
+          return if slugged_encoded_id.blank?
+          encoded_id = encoded_id_parser(slugged_encoded_id).id
+          return if !encoded_id || encoded_id.blank?
+          encoded_id_coder(options).decode(encoded_id)
         end
 
         # This can be overridden in the model to provide a custom salt
         def encoded_id_salt
-          unless config && config.salt.present?
-            raise ::StandardError, "You must set a model specific encoded_id_salt or a gem wide one"
-          end
-          unless name.present?
-            raise ::StandardError, "The class must have a name to ensure encode id uniqueness. " \
-              "Please set a name on the class or override `encoded_id_salt`."
-          end
-          salt = config.salt
-          raise ::StandardError, "Encoded ID salt is invalid" if salt.blank? || salt.size < 4
-          "#{name}/#{salt}"
-        end
-
-        private
-
-        def hash_id_encoder(options)
-          ::EncodedId::ReversibleId.new(
-            salt: options[:salt].presence || encoded_id_salt,
-            length: options[:id_length] || config.id_length,
-            split_at: options[:character_group_size] || config.character_group_size,
-            alphabet: options[:alphabet] || config.alphabet
-          )
-        end
-
-        def config
-          ::EncodedId::Rails.configuration
+          EncodedId::Rails::Salt.new(self, EncodedId::Rails.configuration.salt).generate!
         end
 
-        def internal_decode_encoded_id(slugged_encoded_id, options)
-          return if slugged_encoded_id.blank?
-          encoded_id = extract_id_part(slugged_encoded_id)
-          return if encoded_id.blank?
-          hash_id_encoder(options).decode(encoded_id)
-        rescue EncodedId::EncodedIdFormatError
-          nil
+        def encoded_id_parser(slugged_encoded_id)
+          SluggedIdParser.new(slugged_encoded_id, separator: EncodedId::Rails.configuration.slugged_id_separator)
         end
 
-        def find_via_custom_id(value, attribute, compare_to: nil)
-          return if value.blank?
-          record = find_by({attribute => value})
-          return unless record
-          unless compare_to.nil?
-            return unless compare_to == record.send(attribute)
-          end
-          record
-        end
-
-        def find_via_custom_id!(value, attribute, compare_to: nil)
-          raise ::ActiveRecord::RecordNotFound if value.blank?
-          record = find_by!({attribute => value})
-          unless compare_to.nil?
-            raise ::ActiveRecord::RecordNotFound unless compare_to == record.send(attribute)
-          end
-          record
-        end
-
-        def extract_id_part(slugged_id)
-          return if slugged_id.blank?
-          has_slug = slugged_id.include?("--")
-          return slugged_id unless has_slug
-          split_slug = slugged_id.split("--")
-          split_slug.last if has_slug && split_slug.size > 1
+        def encoded_id_coder(options = {})
+          config = EncodedId::Rails.configuration
+          EncodedId::Rails::Coder.new(
+            salt: options[:salt] || encoded_id_salt,
+            id_length: options[:id_length] || config.id_length,
+            character_group_size: options[:character_group_size] || config.character_group_size,
+            alphabet: options[:alphabet] || config.alphabet,
+            separator: options[:separator] || config.group_separator
+          )
         end
       end
 
@@ -177,34 +76,24 @@ module EncodedId
         @encoded_id ||= self.class.encode_encoded_id(id)
       end
 
-      # (slug)--(hash id)
-      def slugged_encoded_id(with: :slug)
-        @slugged_encoded_id ||= generate_composite_id(with, :encoded_id)
-      end
-
-      # (name slug)--(record id(s) (separated by hyphen))
-      def slugged_id(with: :slug)
-        @slugged_id ||= generate_composite_id(with, :id)
+      def slugged_encoded_id(with: :name_for_encoded_id_slug)
+        @slugged_encoded_id ||= EncodedId::Rails::SluggedId.new(
+          self,
+          slug_method: with,
+          id_method: :encoded_id,
+          separator: EncodedId::Rails.configuration.slugged_id_separator
+        ).slugged_id
       end
 
       # By default slug calls `name` if it exists or returns class name
-      def slug
-        klass = self.class.name&.underscore
-        return klass unless respond_to? :name
-        given_name = name
-        return given_name if given_name.present?
-        klass
-      end
-
-      private
-
-      def generate_composite_id(name_method, id_method)
-        name_part = send(name_method)
-        id_part = send(id_method)
-        unless id_part.present? && name_part.present?
-          raise(::StandardError, "The model has no #{id_method} or #{name_method}")
-        end
-        "#{name_part.to_s.parameterize}--#{id_part}"
+      def name_for_encoded_id_slug
+        if respond_to? :name
+          given_name = name
+          return given_name if given_name.present?
+        end
+        class_name = self.class.name
+        raise StandardError, "No name or class name found, cannot create a slug" if !class_name || class_name.blank?
+        class_name.underscore
       end
     end
   end

data/lib/encoded_id/rails.rb

@@ -2,6 +2,10 @@
 
 require_relative "rails/version"
 require_relative "rails/configuration"
+require_relative "rails/coder"
+require_relative "rails/slugged_id"
+require_relative "rails/slugged_id_parser"
+require_relative "rails/salt"
 require_relative "rails/with_encoded_id"
 
 module EncodedId

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

@@ -18,6 +18,13 @@ EncodedId::Rails.configure do |config|
   #
   # 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, hash ids requires at least 16 unique alphabet characters.
   #

data/rbs_collection.yaml

@@ -11,6 +11,7 @@ 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.
   - name: rbs

data/sig/encoded_id/rails.rbs

@@ -1,104 +1,101 @@
 module EncodedId
   module Rails
-    # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+    VERSION: ::String
+
+    class Coder
+      def initialize: (salt: ::String, id_length: ::Integer, character_group_size: ::Integer, separator: ::String, alphabet: ::EncodedId::Alphabet) -> void
+      def encode: (::Integer | ::Array[::Integer]) -> String
+      def decode: (::String) -> (nil | ::Array[::Integer])
+
+      @salt: ::String
+      @id_length: ::Integer
+      @character_group_size: ::Integer
+      @separator: ::String
+      @alphabet: ::EncodedId::Alphabet
+
+      private
+
+      def coder: -> ::EncodedId::ReversibleId
+    end
 
     class Configuration
       attr_accessor salt: ::String
-
+      attr_accessor group_separator: ::String
       attr_accessor character_group_size: ::Integer
-
       attr_accessor alphabet: ::EncodedId::Alphabet
-
       attr_accessor id_length: ::Integer
+      attr_accessor slugged_id_separator: ::String
 
       def initialize: () -> void
     end
 
-    attr_reader self.configuration: Configuration
-
-    def self.configure: () { (Configuration config) -> void } -> void
+    class Salt
+      def initialize: (untyped klass, ::String salt) -> void
 
-    module WithEncodedId
-      # Find by encoded ID and optionally ensure record ID is the same as constraint (can be slugged)
-      def self.find_by_encoded_id: (::String slugged_encoded_id, ?with_id: ::Symbol?) -> (nil | untyped)
+      @klass: untyped
+      @salt: ::String
 
-      def self.find_by_encoded_id!: (::String slugged_encoded_id, ?with_id: ::Symbol?) -> untyped
+      def generate!: -> ::String
+    end
 
-      # Find by a fixed slug value (assumed as an attribute value in the DB)
-      def self.find_by_fixed_slug: (::String slug, ?attribute: ::Symbol, ?with_id: ::Symbol?) -> (nil | untyped)
+    class SluggedId
+      def initialize: (untyped from_object, ?slug_method: ::Symbol, ?id_method: ::Symbol, ?separator: ::String)-> void
 
-      def self.find_by_fixed_slug!: (::String slug, ?attribute: ::Symbol, ?with_id: ::Symbol?) -> untyped
+      @from_object: untyped
+      @slug_method: ::Symbol
+      @id_method: ::Symbol
+      @separator: ::String
 
-      # Find by record ID where the ID has been slugged
-      def self.find_by_slugged_id: (::String slugged_id, ?with_id: ::Symbol?) -> (nil | untyped)
+      def slugged_id: -> ::String
+    end
 
-      def self.find_by_slugged_id!: (::String slugged_id, ?with_id: ::Symbol?) -> untyped
+    class SluggedIdParser
+      def initialize: (::String slugged_id, ?separator: ::String) -> void
 
-      def self.where_encoded_id: (::String slugged_encoded_id) -> untyped
+      attr_reader slug: (nil | ::String)
+      attr_reader id: (nil | ::String)
+    end
 
-      def self.where_fixed_slug: (::String slug, ?attribute: ::Symbol) -> untyped
+    attr_reader self.configuration: Configuration
 
-      def self.where_slugged_id: (::String slugged_id) -> untyped
+    def self.configure: () { (Configuration config) -> void } -> void
 
+    module WithEncodedId
+      module ClassMethods
+        def find_by_encoded_id: (::String slugged_encoded_id, ?with_id: ::Symbol?) -> (nil | untyped)
+        def find_by_encoded_id!: (::String slugged_encoded_id, ?with_id: ::Symbol?) -> untyped
+        def where_encoded_id: (::String slugged_encoded_id) -> untyped
+        def encode_encoded_id: (untyped id, ?::Hash[::Symbol, untyped] options) -> ::String
+        def decode_encoded_id: (::String slugged_encoded_id, ?::Hash[::Symbol, untyped] options) -> (nil | ::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
+
+        # FIXME: Methods defined on AR, how to tell steep that this will be composed with AR?
+        def where: (*untyped) -> untyped
+        def find: (*untyped) -> (nil | untyped)
+        def find!: (*untyped) -> untyped
+        def find_by: (*untyped) -> (nil | untyped)
+        def find_by!: (*untyped) -> untyped
+      end
+
+      # FIXME: steep doesnt understand that methods defined in ClassMethods will be added to the class, hence
+      # the duplication here
+      def self.find_by_encoded_id: (::String slugged_encoded_id, ?with_id: ::Symbol?) -> (nil | untyped)
+      def self.find_by_encoded_id!: (::String slugged_encoded_id, ?with_id: ::Symbol?) -> untyped
+      def self.where_encoded_id: (::String slugged_encoded_id) -> untyped
       def self.encode_encoded_id: (untyped id, ?::Hash[::Symbol, untyped] options) -> ::String
-
-      def self.encode_multi_encoded_id: (::Array[untyped] encoded_ids, ?::Hash[::Symbol, untyped] options) -> ::String
-
-      # Decode a encoded_id (can be slugged)
-      def self.decode_encoded_id: (::String slugged_encoded_id, ?::Hash[::Symbol, untyped] options) -> (nil | ::Integer)
-
-      def self.decode_multi_encoded_id: (::String slugged_encoded_id, ?::Hash[::Symbol, untyped] options) -> (nil | Array[::Integer])
-
-      # Decode a Slugged ID
-      def self.decode_slugged_id: (::String slugged) -> (nil | ::Integer)
-
-      # Decode a set of slugged IDs
-      def self.decode_slugged_ids: (::String slugged) -> (nil | Array[::Integer])
-
-      # This can be overridden in the model to provide a custom salt
+      def self.decode_encoded_id: (::String slugged_encoded_id, ?::Hash[::Symbol, untyped] options) -> (nil | ::Array[::Integer])
       def self.encoded_id_salt: () -> ::String
+      def self.encoded_id_parser: (::String slugged_encoded_id) -> ::EncodedId::Rails::SluggedIdParser
+      def self.encoded_id_coder: (?::Hash[::Symbol, untyped] options) -> ::EncodedId::Rails::Coder
 
-      private
-
-      def self.hash_id_encoder: (untyped options) -> untyped
-
-      def self.config: () -> untyped
-
-      @slugged_id: ::String
       @encoded_id: ::String
       @slugged_encoded_id: ::String
 
-      def encoded_id: () -> untyped
-
-      # (slug)--(hash id)
-      def slugged_encoded_id: (?with: ::Symbol) -> untyped
-
-      # (name slug)--(record id(s) (separated by hyphen))
-      def slugged_id: (?with: ::Symbol) -> untyped
-
-      # By default slug calls `name` if it exists or returns class name
-      def slug: () -> untyped
-
-      def self.internal_decode_encoded_id: (untyped slugged_encoded_id, untyped options) -> (nil | untyped)
-
-      def self.find_via_custom_id: (untyped value, untyped attribute, ?compare_to: untyped?) -> (nil | untyped)
-
-      def self.find_via_custom_id!: (untyped value, untyped attribute, ?compare_to: untyped?) -> untyped
-
-      def self.extract_id_part: (untyped slugged_id) -> (nil | untyped)
-
-      def generate_composite_id: (untyped name_method, untyped id_method) -> ::String
-
-      # Methods defined on AR
-      def self.where: (*untyped) -> untyped
-
-      def self.find: (*untyped) -> (nil | untyped)
-
-      def self.find!: (*untyped) -> untyped
-
-      def self.find_by: (*untyped) -> (nil | untyped)
-
-      def self.find_by!: (*untyped) -> untyped
+      def encoded_id: () -> ::String
+      def slugged_encoded_id: (?with: ::Symbol) -> ::String
+      def name_for_encoded_id_slug: () -> ::String
 
       # FIXME: To make type check happy, but may not exist!
       # We call if respond_to? but type checker doesn't know that

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: encoded_id-rails
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.4.0
 platform: ruby
 authors:
 - Stephen Ierodiaconou
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-12-15 00:00:00.000000000 Z
+date: 2022-12-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -17,6 +17,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -24,6 +27,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
 - !ruby/object:Gem::Dependency
   name: activerecord
   requirement: !ruby/object:Gem::Requirement
@@ -31,6 +37,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -38,6 +47,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '6.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.0'
 - !ruby/object:Gem::Dependency
   name: encoded_id
   requirement: !ruby/object:Gem::Requirement
@@ -52,7 +64,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '0.4'
-description: Write a longer description or delete this line.
+description: ActiveRecord concern to use EncodedID to turn IDs into reversible and
+  human friendly obfuscated strings.
 email:
 - stevegeek@gmail.com
 executables: []
@@ -69,7 +82,11 @@ files:
 - gemfiles/rails_6.0.gemfile
 - gemfiles/rails_7.0.gemfile
 - lib/encoded_id/rails.rb
+- lib/encoded_id/rails/coder.rb
 - lib/encoded_id/rails/configuration.rb
+- lib/encoded_id/rails/salt.rb
+- lib/encoded_id/rails/slugged_id.rb
+- lib/encoded_id/rails/slugged_id_parser.rb
 - lib/encoded_id/rails/version.rb
 - lib/encoded_id/rails/with_encoded_id.rb
 - lib/generators/encoded_id/rails/USAGE
@@ -102,5 +119,5 @@ requirements: []
 rubygems_version: 3.3.26
 signing_key:
 specification_version: 4
-summary: Use EncodedIds with ActiveRecord models
+summary: Use `encoded_id` with ActiveRecord models
 test_files: []