encoded_id-rails 1.0.0.rc1 → 1.0.0.rc7

data/lib/encoded_id/rails.rb

@@ -1,8 +1,10 @@
 # frozen_string_literal: true
 
-require_relative "rails/version"
+# rbs_inline: enabled
+
 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"
@@ -15,24 +17,27 @@ require_relative "rails/path_param"
 require_relative "rails/slugged_path_param"
 require_relative "rails/model"
 require_relative "rails/persists"
+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?
+
     class << self
+      # @rbs return: EncodedId::Rails::Configuration
       def configuration
         @configuration ||= Configuration.new
       end
 
+      # @rbs () -> EncodedId::Rails::Configuration
+      #    | () { (EncodedId::Rails::Configuration) -> void } -> EncodedId::Rails::Configuration
       def configure
         yield(configuration) if block_given?
         configuration
       end
     end
   end
-
-  # Expose directly on EncodedId
-  Model = Rails::Model
-  PathParam = Rails::PathParam
-  SluggedPathParam = Rails::SluggedPathParam
 end

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/{encoded_id.rb → hashids_encoded_id.rb}

@@ -1,11 +1,18 @@
 # 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) %>"
+  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.
@@ -26,13 +33,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, 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 hash IDs
+  # 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"
@@ -68,11 +75,48 @@ EncodedId::Rails.configure do |config|
   #
   # config.annotated_id_separator = "_"
 
-  # When true, models that include EncodedId::Model will automatically have their to_param method
+  # 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::Model automatically use encoded IDs in URLs.
+  # 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/sqids_encoded_id.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+EncodedId::Rails.configure do |config|
+  # The encoder to use for generating encoded IDs.
+  #
+  # 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.
+  #
+  # 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, 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 Sqids
+  # 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 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.
+  #
+  # Default: EncodedId::Blocklist.empty
+  # Available built-in blocklists:
+  # - EncodedId::Blocklist.empty - no blocked words
+  # - EncodedId::Blocklist.minimal - common English profanity
+  # - 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

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: encoded_id-rails
 version: !ruby/object:Gem::Version
-  version: 1.0.0.rc1
+  version: 1.0.0.rc7
 platform: ruby
 authors:
 - Stephen Ierodiaconou
 bindir: exe
 cert_chain: []
-date: 1980-01-02 00:00:00.000000000 Z
+date: 2025-11-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activesupport
@@ -55,14 +55,14 @@ dependencies:
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 1.0.0.rc5
+        version: 1.0.0.rc7
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '='
       - !ruby/object:Gem::Version
-        version: 1.0.0.rc5
+        version: 1.0.0.rc7
 description: ActiveRecord concern to use EncodedID to turn IDs into reversible and
   human friendly obfuscated strings.
 email:
@@ -71,24 +71,17 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- ".devcontainer/Dockerfile"
-- ".devcontainer/compose.yml"
-- ".devcontainer/devcontainer.json"
-- ".standard.yml"
-- Appraisals
 - CHANGELOG.md
-- Gemfile
 - LICENSE.txt
 - README.md
-- Rakefile
-- Steepfile
-- gemfiles/.bundle/config
-- gemfiles/rails_7.2.gemfile
-- gemfiles/rails_8.0.gemfile
+- context/encoded_id-rails.md
+- context/encoded_id.md
 - lib/encoded_id/rails.rb
+- lib/encoded_id/rails/active_record_finders.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/composite_id_base.rb
 - lib/encoded_id/rails/configuration.rb
 - lib/encoded_id/rails/encoder_methods.rb
 - lib/encoded_id/rails/finder_methods.rb
@@ -96,25 +89,24 @@ files:
 - lib/encoded_id/rails/path_param.rb
 - lib/encoded_id/rails/persists.rb
 - lib/encoded_id/rails/query_methods.rb
+- lib/encoded_id/rails/railtie.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/slugged_path_param.rb
-- lib/encoded_id/rails/version.rb
 - lib/generators/encoded_id/rails/USAGE
 - lib/generators/encoded_id/rails/add_columns_generator.rb
 - lib/generators/encoded_id/rails/install_generator.rb
 - lib/generators/encoded_id/rails/templates/add_encoded_id_columns_migration.rb.erb
-- lib/generators/encoded_id/rails/templates/encoded_id.rb
-- rbs_collection.yaml
-- sig/encoded_id/rails.rbs
-homepage: https://github.com/stevegeek/encoded_id-rails
+- lib/generators/encoded_id/rails/templates/hashids_encoded_id.rb
+- lib/generators/encoded_id/rails/templates/sqids_encoded_id.rb
+homepage: https://github.com/stevegeek/encoded_id
 licenses:
 - MIT
 metadata:
-  homepage_uri: https://github.com/stevegeek/encoded_id-rails
-  source_code_uri: https://github.com/stevegeek/encoded_id-rails
-  changelog_uri: https://github.com/stevegeek/encoded_id-rails/blob/master/CHANGELOG.md
+  homepage_uri: https://github.com/stevegeek/encoded_id
+  source_code_uri: https://github.com/stevegeek/encoded_id
+  changelog_uri: https://github.com/stevegeek/encoded_id/blob/main/CHANGELOG.md
 rdoc_options: []
 require_paths:
 - lib
@@ -129,7 +121,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.7
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Use `encoded_id` with ActiveRecord models
 test_files: []

data/.devcontainer/Dockerfile

@@ -1,17 +0,0 @@
-# Make sure RUBY_VERSION matches the Ruby version in .ruby-version or gemspec
-ARG RUBY_VERSION=3.4.2
-FROM ghcr.io/rails/devcontainer/images/ruby:$RUBY_VERSION
-
-USER root
-
-# Install pkg-config and SQLite development libraries
-RUN apt-get update -qq && \
-    apt-get install -y pkg-config libsqlite3-dev && \
-    apt-get clean && \
-    rm -rf /var/lib/apt/lists/*
-
-USER vscode
-
-# Ensure binding is always 0.0.0.0
-# Binds the server to all IP addresses of the container, so it can be accessed from outside the container.
-ENV BINDING="0.0.0.0"

data/.devcontainer/compose.yml

@@ -1,10 +0,0 @@
-name: "encoded_id-rails"
-
-services:
-  encoded-id-rails-dev-env:
-    container_name: encoded-id-rails-dev-env
-    build:
-      context: ..
-      dockerfile: .devcontainer/Dockerfile
-    ports:
-      - "3000"

data/.devcontainer/devcontainer.json

@@ -1,12 +0,0 @@
-{
-  "name": "Encoded ID Rails Gem Development",
-  "dockerComposeFile": "compose.yml",
-  "service": "encoded-id-rails-dev-env",
-  "containerEnv": {
-    "RAILS_ENV": "development"
-  },
-  "forwardPorts": [3000],
-  "postCreateCommand": "bundle install && bundle exec appraisal install",
-  "postStartCommand": "bundle exec rake test",
-  "remoteUser": "vscode"
-}

data/.standard.yml

@@ -1,3 +0,0 @@
-# For available configuration options, see:
-#   https://github.com/testdouble/standard
-ruby_version: 2.6

data/Appraisals

@@ -1,9 +0,0 @@
-appraise "rails-7.2" do
-  gem "activesupport", "~> 7.2.0"
-  gem "activerecord", "~> 7.2.0"
-end
-
-appraise "rails-8.0" do
-  gem "activesupport", "~> 8.0.0"
-  gem "activerecord", "~> 8.0.0"
-end

data/Gemfile

@@ -1,24 +0,0 @@
-# frozen_string_literal: true
-
-source "https://rubygems.org"
-
-# Specify your gem's dependencies in encoded_id-rails.gemspec
-gemspec
-
-group :development, :test do
-  gem "rake", "~> 13.0"
-
-  gem "minitest", "~> 5.0"
-
-  gem "standard", "~> 1.30"
-
-  gem "steep", "~> 1.5"
-
-  gem "rails"
-
-  gem "sqlite3"
-
-  gem "appraisal"
-
-  gem "simplecov"
-end

data/Rakefile

@@ -1,20 +0,0 @@
-# frozen_string_literal: true
-
-require "bundler/gem_tasks"
-require "rake/testtask"
-
-Rake::TestTask.new(:test) do |t|
-  t.libs << "test"
-  t.libs << "lib"
-  t.test_files = FileList["test/**/*_test.rb"]
-end
-
-desc "Run tests with coverage"
-task :coverage do
-  ENV["COVERAGE"] = "true"
-  Rake::Task["test"].invoke
-end
-
-require "standard/rake"
-
-task default: %i[test standard]

data/Steepfile

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

data/gemfiles/.bundle/config

@@ -1,2 +0,0 @@
----
-BUNDLE_RETRY: "1"

data/gemfiles/rails_7.2.gemfile

@@ -1,19 +0,0 @@
-# This file was generated by Appraisal
-
-source "https://rubygems.org"
-
-gem "activesupport", "~> 7.2.0"
-gem "activerecord", "~> 7.2.0"
-
-group :development, :test do
-  gem "rake", "~> 13.0"
-  gem "minitest", "~> 5.0"
-  gem "standard", "~> 1.30"
-  gem "steep", "~> 1.5"
-  gem "rails"
-  gem "sqlite3"
-  gem "appraisal"
-  gem "simplecov"
-end
-
-gemspec path: "../"

data/gemfiles/rails_8.0.gemfile

@@ -1,19 +0,0 @@
-# This file was generated by Appraisal
-
-source "https://rubygems.org"
-
-gem "activesupport", "~> 8.0.0"
-gem "activerecord", "~> 8.0.0"
-
-group :development, :test do
-  gem "rake", "~> 13.0"
-  gem "minitest", "~> 5.0"
-  gem "standard", "~> 1.30"
-  gem "steep", "~> 1.5"
-  gem "rails"
-  gem "sqlite3"
-  gem "appraisal"
-  gem "simplecov"
-end
-
-gemspec path: "../"

data/lib/encoded_id/rails/version.rb

@@ -1,7 +0,0 @@
-# frozen_string_literal: true
-
-module EncodedId
-  module Rails
-    VERSION = "1.0.0.rc1"
-  end
-end

data/rbs_collection.yaml

@@ -1,24 +0,0 @@
-# Download sources
-sources:
-  - name: ruby/gem_rbs_collection
-    remote: https://github.com/ruby/gem_rbs_collection.git
-    revision: main
-    repo_dir: gems
-
-# A directory to install the downloaded RBSs
-path: .gem_rbs_collection
-
-gems:
-  - name: cgi
-  # Skip loading rbs gem's RBS.
-  # It's unnecessary if you don't use rbs as a library.
-  - name: rbs
-    ignore: true
-  - name: rake
-    ignore: true
-  - name: minitest
-    ignore: true
-  - name: standard
-    ignore: true
-  - name: steep
-    ignore: true