encoded_id-rails 1.0.0.beta1 → 1.0.0.beta2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6279bf9520a50983edc402bdc6a94fd4888c7c77f3c50484841535962ce50cc0
-  data.tar.gz: 4fdbddfc863dbe9acd25c4ad51551aef70c0c4972a5d18d29a134a848d73e5e7
+  metadata.gz: 0a92cfd619fa254d0996950214c14aa115d6c62327e4ec2a6715dc9d7d898ebf
+  data.tar.gz: 27b448535392de1e1e21c37b82c324e4b5aecdc5225d4c7b2757a1ce8d5d18a9
 SHA512:
-  metadata.gz: '0784b0541785da4f291f8a303674c72598622016693efb060adc3a8cd75fd68b1299b755e381777ecf45616e3217e05f9fe9eefccf53dce2d6fb3e118bd1313e'
-  data.tar.gz: 01fba9fb0fb764cfac1953997da5637915b55badd90e586f01c60eda9ab4182d4a2fe9be531e420fbe95172442d4e2e12346c8422e06f26c86541a9000648ab2
+  metadata.gz: 1ad6f6555bbdb19650f16220dedc81c733f847931a6eea27e28e69c9050f6542d28b8295a6ef3395c95bfe5480c22cc7e1ea224dc687616634ad34da58a71ddf
+  data.tar.gz: 53d42d543a9c86fd2ab3842bad841e7aff95cdc57059bbade5529183df3fa3ee426525d1100174d22821644c5f3915b0bef4e4c252ea56d4c08352bc662aa00f

data/CHANGELOG.md

@@ -1,6 +1,6 @@
 ## [Unreleased]
 
-## [1.0.0.beta1] - 2023-08-07
+## [1.0.0] - (in beta)
 
 ### Breaking changes
 

data/README.md

@@ -1,8 +1,29 @@
 # 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.
+
+## 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)
+- 🔖 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
+  - build in profanity limitation
+
+The gem provides:
+
+- 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
 
 ```ruby
 class User < ApplicationRecord
@@ -34,43 +55,25 @@ user == User.find_by_encoded_id("bob-smith--usr_p5w9-z27j") # => true
 users = User.find_all_by_encoded_id("7aq60zqw") # => [#<User id: 78>, #<User id: 45>]
 ```
 
-# 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)
-- 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
-  - build in profanity limitation
-
-The gem provides:
-
-- 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 gem?
+## 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:
@@ -360,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/lib/encoded_id/rails/configuration.rb

@@ -4,15 +4,9 @@ module EncodedId
   module Rails
     # Configuration class for initializer
     class Configuration
-      attr_accessor :salt,
-        :character_group_size,
-        :group_separator,
-        :alphabet,
-        :id_length,
-        :slug_value_method_name,
-        :slugged_id_separator,
-        :annotation_method_name, # Set to nil to disable annotated IDs
-        :annotated_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
@@ -24,6 +18,33 @@ module EncodedId
         @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
 end

data/lib/encoded_id/rails/version.rb

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

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: encoded_id-rails
 version: !ruby/object:Gem::Version
-  version: 1.0.0.beta1
+  version: 1.0.0.beta2
 platform: ruby
 authors:
 - Stephen Ierodiaconou
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-08-07 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: 1.0.0.rc1
+        version: 1.0.0.rc3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.0.0.rc1
+        version: 1.0.0.rc3
 description: ActiveRecord concern to use EncodedID to turn IDs into reversible and
   human friendly obfuscated strings.
 email:
@@ -123,7 +123,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: 1.3.1
 requirements: []
-rubygems_version: 3.4.10
+rubygems_version: 3.4.20
 signing_key:
 specification_version: 4
 summary: Use `encoded_id` with ActiveRecord models