encoded_ids 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 31d25d05fa2a21196dee435efb25c144e2cf90ee3837c8da263f49c22f1e8825
+  data.tar.gz: 54af5781a3455a70b96b5033e6dc9e58b1ea0c8cc3b64a0afc4b5dbe83fd5c35
+SHA512:
+  metadata.gz: bebf4a30fd0307ad7514e57088cca68bfab718789ef7d5d13506bd6bf312caf3d3f02442e1d87186c3fc5e3c5c9dbbf2dbf84fd71188537af41472a1048a3583
+  data.tar.gz: b83f9254cae57f08270f9c4da0db06fef2883b07641ad20d0fe6f00b6e25d60b2a3ca1737d2cd993b84ea144140de382268f29bfd5af9bfdcc3bf8738dbbdd6e

data/.rspec

@@ -0,0 +1,3 @@
+--require spec_helper
+--color
+--format documentation

data/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-02-09
+
+### Added
+- Initial stable release
+- `HashidEncodedIds` concern for integer primary keys
+- `UuidEncodedIds` concern for UUID primary keys
+- Automatic `to_param` override for Rails URL generation
+- Overridden `find` method to accept both internal and public IDs
+- `find_by_public_id` and `find_by_public_id!` class methods
+- Controller helpers: `find_by_any_id` and `find_by_any_id!`
+- Compositional prefix support with `add_public_id_segment`
+- Configurable hash length for hashids
+- Global configuration via `EncodedIds.configure`
+- Automatic Rails integration via Railtie

data/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jasper Mayone
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,254 @@
+# EncodedIds
+
+Stripe-like public IDs for Rails models. Generate API-friendly identifiers like `usr_k5qx9z` or `org_4k8xJm2pN9qW` that:
+
+- Hide sequential integer IDs from your API
+- Provide type context in the ID itself (the prefix tells you it's a user, organization, etc.)
+- Work seamlessly with Rails routing and controllers
+- Support both integer and UUID primary keys
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'encoded_ids'
+```
+
+Or install directly:
+
+```bash
+gem install encoded_ids
+```
+
+## Quick Start
+
+### For models with integer IDs (uses hashids):
+
+```ruby
+class User < ApplicationRecord
+  include EncodedIds::HashidIdentifiable
+  set_public_id_prefix :usr
+end
+
+user = User.first
+user.public_id        # => "usr_k5qx9z"
+user.to_param         # => "k5qx9z" (used in URLs - no prefix by default)
+
+# Find by public_id (with or without prefix)
+User.find("k5qx9z")                   # => <User id: 1>
+User.find("usr_k5qx9z")               # => <User id: 1>
+User.find_by_public_id("usr_k5qx9z")  # => <User id: 1>
+```
+
+### For models with UUID IDs (uses base62 encoding):
+
+```ruby
+class Organization < ApplicationRecord
+  include EncodedIds::UuidIdentifiable
+  set_public_id_prefix "org"
+end
+
+org = Organization.first
+org.public_id   # => "org_4k8xJm2pN9qW"
+org.to_param    # => "4k8xJm2pN9qW" (no prefix by default)
+
+# Find by public_id (with or without prefix)
+Organization.find("4k8xJm2pN9qW")                   # => <Organization id: "uuid...">
+Organization.find("org_4k8xJm2pN9qW")               # => <Organization id: "uuid...">
+Organization.find_by_public_id("org_4k8xJm2pN9qW")  # => <Organization id: "uuid...">
+```
+
+## Features
+
+### Automatic URL Parameter Handling
+
+The gem overrides `to_param` automatically, so Rails will use the hashid/encoded ID in all your URLs:
+
+```ruby
+link_to "View User", user_path(user)
+# => /users/k5qx9z (clean URLs without prefix by default)
+
+redirect_to @user
+# => /users/k5qx9z
+
+# You can still use the full public_id with prefix if needed:
+User.find_by_public_id("usr_k5qx9z")  # Works!
+```
+
+### Overridden `find` Method
+
+The `find` method is automatically enhanced to accept internal IDs, hashids, and full public IDs:
+
+```ruby
+# These all work:
+User.find(1)              # Regular internal ID
+User.find("k5qx9z")       # Hashid (no prefix)
+User.find("usr_k5qx9z")   # Full public ID (with prefix)
+```
+
+### Compositional Prefixes (Hashid only)
+
+For namespaced models, you can build prefixes from multiple segments:
+
+```ruby
+class Intel::Tool::PhoneNumber < ApplicationRecord
+  include EncodedIds::HashidIdentifiable
+  add_public_id_segment :int
+  add_public_id_segment :tool
+  add_public_id_segment :phn
+end
+
+phone.public_id  # => "int_tool_phn_k5qx9z"
+```
+
+### Configurable Hash Length
+
+For tables with many records, increase the minimum hash length:
+
+```ruby
+class Enrollment < ApplicationRecord
+  include EncodedIds::HashidIdentifiable
+  set_public_id_prefix :enr, min_hash_length: 12
+end
+
+enrollment.public_id  # => "enr_x5qp9z2m8n4k"
+enrollment.to_param   # => "x5qp9z2m8n4k"
+```
+
+### Route Behavior Configuration
+
+By default, `to_param` returns just the hash (no prefix) for cleaner URLs. You can change this globally or per-model:
+
+```ruby
+# Global configuration - include prefix in all URLs (Stripe style)
+EncodedIds.configure do |config|
+  config.use_prefix_in_routes = true
+end
+
+# Per-model override
+class User < ApplicationRecord
+  include EncodedIds::HashidIdentifiable
+  set_public_id_prefix :usr, use_prefix_in_routes: true
+end
+
+user.to_param  # => "usr_k5qx9z" instead of just "k5qx9z"
+```
+
+### Controller Helpers
+
+Automatically included in all controllers:
+
+```ruby
+class UsersController < ApplicationController
+  def show
+    # Accepts both internal ID and public_id
+    @user = find_by_any_id(User, params[:id])
+
+    # Or with bang method (raises RecordNotFound)
+    @user = find_by_any_id!(User, params[:id])
+  end
+end
+```
+
+## Configuration
+
+Create an initializer at `config/initializers/encoded_ids.rb`:
+
+```ruby
+EncodedIds.configure do |config|
+  # Hashid configuration (for integer IDs)
+  config.hashid_salt = Rails.application.credentials.dig(:hashid, :salt)
+  config.hashid_min_length = 8
+  config.hashid_alphabet = "abcdefghijklmnopqrstuvwxyz0123456789"
+
+  # Base62 alphabet (for UUID encoding)
+  config.base62_alphabet = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
+
+  # Separator between prefix and hash
+  config.separator = "_"
+
+  # Whether to include prefix in to_param URLs
+  # false (default) = /users/k5qx9z
+  # true = /users/usr_k5qx9z (Stripe style)
+  config.use_prefix_in_routes = false
+end
+```
+
+**Important:** For production, set a unique `hashid_salt` in your credentials:
+
+```bash
+rails credentials:edit
+```
+
+```yaml
+hashid:
+  salt: your-unique-salt-here  # Generate with: SecureRandom.hex(32)
+```
+
+## How It Works
+
+### Integer IDs (HashidIdentifiable)
+
+Uses [hashid-rails](https://github.com/jcypret/hashid-rails) to encode integer IDs into short, URL-safe strings. The encoding is:
+- Reversible (can decode back to the integer ID)
+- Obfuscated (not sequential, not easily guessable)
+- Short (configurable minimum length)
+
+### UUID IDs (UuidIdentifiable)
+
+Uses base62 encoding to shorten UUIDs from 36 characters to ~22 characters. Since UUIDs are already random and non-sequential, this just adds the prefix and shortens the representation.
+
+## API
+
+### Model Methods (both types)
+
+```ruby
+# Instance methods
+model.public_id         # Returns the full public ID
+model.to_param          # Returns the public ID (used by Rails in URLs)
+
+# Class methods
+Model.find(id)                    # Accepts both internal and public IDs
+Model.find_by_public_id(id)       # Only finds by public ID
+Model.find_by_public_id!(id)      # Like above, but raises if not found
+Model.get_public_id_prefix        # Returns the configured prefix
+```
+
+### Controller Methods
+
+```ruby
+find_by_any_id(Model, id)   # Returns record or nil
+find_by_any_id!(Model, id)  # Returns record or raises RecordNotFound
+```
+
+## Migration from Existing Code
+
+If you have existing `PublicIdentifiable` concerns in your app:
+
+1. Add `encoded_ids` to your Gemfile
+2. Replace `include PublicIdentifiable` with:
+   - `include EncodedIds::HashidIdentifiable` (for integer IDs)
+   - `include EncodedIds::UuidIdentifiable` (for UUID IDs)
+3. Update your hashid initializer to use `EncodedIds.configure`
+4. Remove your old `PublicIdentifiable` concern
+5. Controllers automatically get the helper methods
+
+## Why Public IDs?
+
+Public IDs provide several benefits:
+
+1. **Security**: Don't expose sequential integer IDs that leak information about your data volume
+2. **Type Safety**: The prefix makes it obvious what type of resource an ID refers to
+3. **API Ergonomics**: Easier to debug and understand API calls
+4. **Future-Proofing**: Can change internal IDs without breaking external APIs
+
+Inspired by Stripe's API design and the [hashid-rails](https://github.com/jcypret/hashid-rails) gem, as well as my time at Hack Club which used a base version of this extensively.
+
+## License
+
+MIT
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/jaspermayone/encoded_ids

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/encoded_ids.gemspec

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require_relative "lib/encoded_ids/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "encoded_ids"
+  spec.version = EncodedIds::VERSION
+  spec.authors = ["Jasper Mayone"]
+  spec.email = ["me@jaspermayone.com"]
+
+  spec.summary = "Stripe-like public IDs for Rails models"
+  spec.description = "Provides Stripe-style public identifiers (like usr_abc123) for Rails models using hashids or base62 encoding. Supports both integer and UUID primary keys, with automatic URL parameter handling and controller helpers."
+  spec.homepage = "https://github.com/jaspermayone/encoded_ids"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = spec.homepage
+  spec.metadata["changelog_uri"] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
+    end
+  end
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "rails", ">= 6.1"
+  spec.add_dependency "hashid-rails", "~> 1.0"
+end

data/examples/controller.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+# Example controller usage
+
+class UsersController < ApplicationController
+  # Standard Rails controller actions work automatically
+  # because to_param is overridden to use public_id
+
+  def show
+    # Method 1: Use the overridden find method
+    # Accepts both internal ID and public_id
+    @user = User.find(params[:id])
+
+    # Method 2: Explicitly use find_by_public_id
+    # @user = User.find_by_public_id(params[:id])
+
+    # Method 3: Use the controller helper (accepts both formats)
+    # @user = find_by_any_id!(User, params[:id])
+  end
+
+  def update
+    @user = User.find(params[:id])
+
+    if @user.update(user_params)
+      # Automatically redirects to /users/:public_id
+      redirect_to @user, notice: "User updated"
+    else
+      render :edit
+    end
+  end
+
+  private
+
+  def user_params
+    params.require(:user).permit(:name, :email)
+  end
+end
+
+# API controller example
+class Api::V1::UsersController < Api::V1::BaseController
+  def show
+    # Controller helper is great for APIs
+    @user = find_by_any_id!(User, params[:id])
+    render json: @user
+  end
+
+  def lookup
+    # Can mix internal and public IDs in the same endpoint
+    users = params[:ids].map { |id| find_by_any_id(User, id) }.compact
+    render json: users
+  end
+end

data/examples/initializer.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+# Example configuration for config/initializers/encoded_ids.rb
+#
+# Copy this file to your Rails app's config/initializers/ directory
+# and customize as needed.
+
+EncodedIds.configure do |config|
+  # Hashid configuration (for integer IDs)
+  # IMPORTANT: Set a unique salt in production via credentials
+  # rails credentials:edit
+  # Add: hashid: { salt: "your-unique-salt-here" }
+  config.hashid_salt = Rails.application.credentials.dig(:hashid, :salt)
+  config.hashid_min_length = 8
+  config.hashid_alphabet = "abcdefghijklmnopqrstuvwxyz0123456789"
+
+  # Base62 alphabet (for UUID encoding)
+  # Standard base62 includes both uppercase and lowercase
+  config.base62_alphabet = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
+
+  # Separator between prefix and hash
+  # Default is "_" for Stripe-style IDs like "usr_abc123"
+  # You could use "-" for "usr-abc123" or any other character
+  config.separator = "_"
+
+  # Whether to include prefix in to_param URLs
+  # false (default) = /users/k5qx9z (cleaner)
+  # true = /users/usr_k5qx9z (Stripe style - redundant with route path)
+  config.use_prefix_in_routes = false
+end

data/examples/models.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# Example model configurations
+
+# Integer primary key with simple prefix
+class User < ApplicationRecord
+  include EncodedIds::HashidEncodedIds
+  set_public_id_prefix :usr
+end
+# user.public_id => "usr_k5qx9z"
+# user.to_param => "k5qx9z" (no prefix in URLs by default)
+
+# Integer primary key with longer hash for high-volume tables
+class Event < ApplicationRecord
+  include EncodedIds::HashidEncodedIds
+  set_public_id_prefix :evt, min_hash_length: 12
+end
+# event.public_id => "evt_x5qp9z2m8n4k"
+
+# Integer primary key with compositional prefix
+class Intel::Tool::PhoneNumber < ApplicationRecord
+  include EncodedIds::HashidEncodedIds
+  add_public_id_segment :int
+  add_public_id_segment :tool
+  add_public_id_segment :phn
+end
+# phone.public_id => "int_tool_phn_k5qx9z"
+
+# UUID primary key
+class Organization < ApplicationRecord
+  include EncodedIds::UuidEncodedIds
+  set_public_id_prefix "org"
+end
+# org.public_id => "org_4k8xJm2pN9qW"
+
+# UUID primary key with different prefix
+class Team < ApplicationRecord
+  include EncodedIds::UuidEncodedIds
+  set_public_id_prefix "team"
+end
+# team.public_id => "team_7n2kLp4xMq8R"
+
+# Override per-model to include prefix in routes (Stripe style)
+class ApiKey < ApplicationRecord
+  include EncodedIds::HashidEncodedIds
+  set_public_id_prefix :key, use_prefix_in_routes: true
+end
+# api_key.public_id => "key_abc123"
+# api_key.to_param => "key_abc123" (includes prefix)

data/lib/encoded_ids/configuration.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module EncodedIds
+  class Configuration
+    # Hashid configuration
+    attr_accessor :hashid_salt, :hashid_min_length, :hashid_alphabet
+
+    # Base62 alphabet for UUID encoding
+    attr_accessor :base62_alphabet
+
+    # Separator between prefix and hash
+    attr_accessor :separator
+
+    # Whether to include the prefix in to_param URLs
+    # true = /users/usr_k5qx9z (Stripe style)
+    # false = /users/k5qx9z (cleaner)
+    attr_accessor :use_prefix_in_routes
+
+    def initialize
+      @hashid_salt = nil # Will fall back to Rails.application.secret_key_base
+      @hashid_min_length = 8
+      @hashid_alphabet = "abcdefghijklmnopqrstuvwxyz0123456789"
+      @base62_alphabet = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
+      @separator = "_"
+      @use_prefix_in_routes = false
+    end
+  end
+end

data/lib/encoded_ids/controller_helpers.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module EncodedIds
+  # Controller helpers for looking up records by either internal ID or public_id
+  #
+  # Automatically included in all controllers via Railtie
+  #
+  # Usage:
+  #   # Find or return nil
+  #   user = find_by_any_id(User, params[:user_id])
+  #
+  #   # Find or raise RecordNotFound
+  #   user = find_by_any_id!(User, params[:user_id])
+  #
+  module ControllerHelpers
+    extend ActiveSupport::Concern
+
+    # Find a record by internal ID, public_id (with prefix), or hashid/encoded UUID (without prefix)
+    def find_by_any_id(model_class, id)
+      return nil if id.blank?
+
+      # If it contains the separator, it's a full public_id with prefix
+      if id.to_s.include?(EncodedIds.configuration.separator)
+        model_class.find_by_public_id(id)
+      else
+        # Use the model's find method which handles both hashids and regular IDs
+        model_class.find(id)
+      end
+    rescue ActiveRecord::RecordNotFound
+      nil
+    end
+
+    # Find a record by either internal ID or public_id, raising if not found
+    def find_by_any_id!(model_class, id)
+      result = find_by_any_id(model_class, id)
+      raise ActiveRecord::RecordNotFound.new(nil, model_class.name) if result.nil?
+
+      result
+    end
+  end
+end

data/lib/encoded_ids/hashid_identifiable.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module EncodedIds
+  # HashidIdentifiable for models with integer primary keys using hashids
+  #
+  # Usage:
+  #   class User < ApplicationRecord
+  #     include EncodedIds::HashidIdentifiable
+  #     set_public_id_prefix :usr
+  #   end
+  #
+  #   user = User.first
+  #   user.public_id        # => "usr_k5qx9z"
+  #   User.find_by_public_id("usr_k5qx9z")  # => <User id: 1>
+  #
+  # Compositional prefixes:
+  #   class Intel::Tool::PhoneNumber < ApplicationRecord
+  #     include EncodedIds::HashidIdentifiable
+  #     add_public_id_segment :int
+  #     add_public_id_segment :tool
+  #     add_public_id_segment :phn
+  #   end
+  #
+  #   phone.public_id  # => "int_tool_phn_k5qx9z"
+  #
+  module HashidIdentifiable
+    extend ActiveSupport::Concern
+
+    included do
+      include Hashid::Rails
+      class_attribute :public_id_prefix
+      class_attribute :public_id_segments, default: []
+      class_attribute :hashid_min_length, default: 8
+      class_attribute :use_prefix_in_routes, default: nil
+    end
+
+    def public_id
+      "#{self.class.get_public_id_prefix}#{separator}#{hashid}"
+    end
+
+    # Override to_param for Rails URL generation
+    # Respects use_prefix_in_routes configuration
+    def to_param
+      use_prefix = self.class.use_prefix_in_routes.nil? ?
+        EncodedIds.configuration.use_prefix_in_routes :
+        self.class.use_prefix_in_routes
+
+      use_prefix ? public_id : hashid
+    end
+
+    def separator
+      EncodedIds.configuration.separator
+    end
+
+    module ClassMethods
+      # Simple approach: set the full prefix directly
+      def set_public_id_prefix(prefix, min_hash_length: 8, use_prefix_in_routes: nil)
+        self.public_id_prefix = prefix.to_s.downcase
+        self.hashid_min_length = min_hash_length
+        self.use_prefix_in_routes = use_prefix_in_routes
+
+        # Configure hashid-rails for this model with custom length
+        hashid_config(min_hash_length: min_hash_length)
+      end
+
+      # Compositional approach: add segments that get joined with underscores
+      def add_public_id_segment(segment)
+        self.public_id_segments = public_id_segments + [segment.to_s.downcase]
+      end
+
+      # Find by public_id, hashid, or regular id
+      def find(*args)
+        id = args.first
+
+        # If it's a public_id string (with prefix), find by public_id
+        if id.is_a?(String) && id.include?(EncodedIds.configuration.separator)
+          find_by_public_id!(id)
+        # If it's a string (just the hash without prefix), try finding by hashid
+        elsif id.is_a?(String)
+          record = find_by_hashid(id)
+          return record if record
+          # Fall back to regular find in case it's actually an integer ID passed as string
+          super
+        else
+          super
+        end
+      end
+
+      def find_by_public_id(id)
+        return nil unless id.is_a?(String)
+
+        parts = id.split(EncodedIds.configuration.separator)
+        hash = parts.pop  # last part is always the hash
+        prefix = parts.join(EncodedIds.configuration.separator)
+
+        return nil unless prefix == get_public_id_prefix
+
+        find_by_hashid(hash)
+      end
+
+      def find_by_public_id!(id)
+        obj = find_by_public_id(id)
+        raise ActiveRecord::RecordNotFound.new(nil, name) if obj.nil?
+
+        obj
+      end
+
+      def get_public_id_prefix
+        # Segments take precedence if defined
+        return public_id_segments.join(EncodedIds.configuration.separator) if public_id_segments.present?
+        return public_id_prefix.to_s.downcase if public_id_prefix.present?
+
+        raise NotImplementedError, "The #{name} model includes #{self.class.name}, but no prefix has been set. Use set_public_id_prefix or add_public_id_segment."
+      end
+    end
+  end
+end

data/lib/encoded_ids/railtie.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module EncodedIds
+  class Railtie < ::Rails::Railtie
+    initializer "encoded_ids.configure_hashid_rails" do
+      # Configure hashid-rails with gem settings
+      Hashid::Rails.configure do |config|
+        config.salt = EncodedIds.configuration.hashid_salt ||
+                      Rails.application.credentials.dig(:hashid, :salt) ||
+                      Rails.application.secret_key_base
+        config.min_hash_length = EncodedIds.configuration.hashid_min_length
+        config.alphabet = EncodedIds.configuration.hashid_alphabet
+      end
+    end
+
+    initializer "encoded_ids.include_controller_helpers" do
+      ActiveSupport.on_load(:action_controller) do
+        include EncodedIds::ControllerHelpers
+      end
+    end
+  end
+end

data/lib/encoded_ids/uuid_identifiable.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module EncodedIds
+  # UuidIdentifiable for models with UUID primary keys using base62 encoding
+  #
+  # Since UUIDs are already non-sequential and random, this focuses on:
+  # 1. Adding a type prefix for easy identification
+  # 2. Shortening the ID for better URL/API ergonomics
+  # 3. Maintaining bi-directional conversion (public_id <-> UUID)
+  #
+  # Usage:
+  #   class User < ApplicationRecord
+  #     include EncodedIds::UuidIdentifiable
+  #     set_public_id_prefix "usr"
+  #   end
+  #
+  #   user.public_id          # => "usr_4k8xJm2pN9qW"
+  #   User.find_by_public_id("usr_4k8xJm2pN9qW")  # => User instance
+  #
+  module UuidIdentifiable
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :public_id_prefix, default: nil
+      class_attribute :use_prefix_in_routes, default: nil
+    end
+
+    # Returns the full public ID with prefix
+    def public_id
+      prefix = self.class.get_public_id_prefix
+      encoded = self.class.encode_uuid(id)
+      "#{prefix}#{separator}#{encoded}"
+    end
+
+    # Returns just the encoded UUID (without prefix) for use in URLs
+    def encoded_id
+      self.class.encode_uuid(id)
+    end
+
+    # Override to_param for Rails URL generation
+    # Respects use_prefix_in_routes configuration
+    def to_param
+      use_prefix = self.class.use_prefix_in_routes.nil? ?
+        EncodedIds.configuration.use_prefix_in_routes :
+        self.class.use_prefix_in_routes
+
+      use_prefix ? public_id : encoded_id
+    end
+
+    def separator
+      EncodedIds.configuration.separator
+    end
+
+    # Alias for Rails conventions
+    alias_method :to_public_param, :public_id
+
+    class_methods do
+      # Set the prefix for this model's public IDs
+      def set_public_id_prefix(prefix, use_prefix_in_routes: nil)
+        self.public_id_prefix = prefix.to_s.freeze
+        self.use_prefix_in_routes = use_prefix_in_routes
+      end
+
+      # Get the configured prefix, with validation
+      def get_public_id_prefix
+        raise "Public ID prefix not set for #{name}. Call set_public_id_prefix in your model." if public_id_prefix.blank?
+        public_id_prefix
+      end
+
+      # Find by public_id, encoded UUID, or regular UUID
+      def find(*args)
+        id = args.first
+
+        # If it's a public_id string (with prefix), find by public_id
+        if id.is_a?(String) && id.include?(EncodedIds.configuration.separator)
+          find_by_public_id!(id)
+        # If it's a string that looks like an encoded UUID (not a standard UUID format)
+        elsif id.is_a?(String) && !id.match?(/\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i)
+          uuid = decode_to_uuid(id)
+          return find_by(id: uuid) if uuid
+          # Fall back to regular find
+          super
+        else
+          super
+        end
+      end
+
+      # Find a record by its public ID
+      def find_by_public_id(public_id)
+        return nil if public_id.blank?
+
+        prefix = get_public_id_prefix
+        separator = EncodedIds.configuration.separator
+        return nil unless public_id.to_s.start_with?("#{prefix}#{separator}")
+
+        encoded = public_id.to_s.sub("#{prefix}#{separator}", "")
+        uuid = decode_to_uuid(encoded)
+        return nil unless uuid
+
+        find_by(id: uuid)
+      end
+
+      # Find a record by its public ID, raising RecordNotFound if not found
+      def find_by_public_id!(public_id)
+        find_by_public_id(public_id) || raise(ActiveRecord::RecordNotFound, "Couldn't find #{name} with public_id=#{public_id}")
+      end
+
+      # Check if a string looks like a valid public ID for this model
+      def valid_public_id?(public_id)
+        return false if public_id.blank?
+        separator = EncodedIds.configuration.separator
+        public_id.to_s.start_with?("#{get_public_id_prefix}#{separator}")
+      end
+
+      # Encode a UUID to a shorter base62 string
+      def encode_uuid(uuid)
+        return nil if uuid.blank?
+
+        alphabet = EncodedIds.configuration.base62_alphabet
+
+        # Remove hyphens and convert to integer
+        hex = uuid.to_s.delete("-")
+        num = hex.to_i(16)
+
+        # Convert to base62
+        return "0" if num.zero?
+
+        result = ""
+        while num > 0
+          result = alphabet[num % 62] + result
+          num /= 62
+        end
+
+        result
+      end
+
+      # Decode a base62 string back to UUID format
+      def decode_to_uuid(encoded)
+        return nil if encoded.blank?
+
+        alphabet = EncodedIds.configuration.base62_alphabet
+
+        # Convert from base62 to integer
+        num = 0
+        encoded.each_char do |char|
+          index = alphabet.index(char)
+          return nil if index.nil? # Invalid character
+          num = num * 62 + index
+        end
+
+        # Convert to hex and format as UUID
+        hex = num.to_s(16).rjust(32, "0")
+        return nil if hex.length > 32 # Overflow protection
+
+        # Format as UUID: 8-4-4-4-12
+        "#{hex[0..7]}-#{hex[8..11]}-#{hex[12..15]}-#{hex[16..19]}-#{hex[20..31]}"
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/encoded_ids/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module EncodedIds
+  VERSION = "1.0.0"
+end

data/lib/encoded_ids.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "hashid/rails"
+require_relative "encoded_ids/version"
+require_relative "encoded_ids/configuration"
+require_relative "encoded_ids/hashid_identifiable"
+require_relative "encoded_ids/uuid_identifiable"
+require_relative "encoded_ids/controller_helpers"
+require_relative "encoded_ids/railtie" if defined?(Rails::Railtie)
+
+module EncodedIds
+  class << self
+    attr_writer :configuration
+
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration = Configuration.new
+    end
+  end
+end

metadata

@@ -0,0 +1,89 @@
+--- !ruby/object:Gem::Specification
+name: encoded_ids
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Jasper Mayone
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: hashid-rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Provides Stripe-style public identifiers (like usr_abc123) for Rails
+  models using hashids or base62 encoding. Supports both integer and UUID primary
+  keys, with automatic URL parameter handling and controller helpers.
+email:
+- me@jaspermayone.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- CHANGELOG.md
+- LICENSE.md
+- README.md
+- Rakefile
+- encoded_ids.gemspec
+- examples/controller.rb
+- examples/initializer.rb
+- examples/models.rb
+- lib/encoded_ids.rb
+- lib/encoded_ids/configuration.rb
+- lib/encoded_ids/controller_helpers.rb
+- lib/encoded_ids/hashid_identifiable.rb
+- lib/encoded_ids/railtie.rb
+- lib/encoded_ids/uuid_identifiable.rb
+- lib/encoded_ids/version.rb
+homepage: https://github.com/jaspermayone/encoded_ids
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/jaspermayone/encoded_ids
+  source_code_uri: https://github.com/jaspermayone/encoded_ids
+  changelog_uri: https://github.com/jaspermayone/encoded_ids/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Stripe-like public IDs for Rails models
+test_files: []