sqids-rails 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2806a56ec74df13fa5efa5f6ed2800d792223c7240b65cfad3cb50eff7a02a4b
+  data.tar.gz: 9f11f7fc06b94e888187ce01c5983431ae597761157652f9677f5c06e1be35d5
+SHA512:
+  metadata.gz: 8b18b3d1ef47868206df30a4f89078464d65254e1494798d7724aade26d3d8a71bf7f15d9353bda313659f4401d246cde365895224713b34b09e092a133e5804
+  data.tar.gz: 9f184450853b55deff34b120e16fbacad516806f1c03bc7a8f88655ffb7dde094f0c68afdfaf02a18ef0c9bb20d6d2d1b483ec4e1bc9de2dc3b5654f2e8cc978

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2024 Tony Burns
+
+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,113 @@
+# sqids-rails
+
+[Sqids](https://sqids.org) (formerly [Hashids](https://github.com/hashids)) integration for [Ruby on Rails](https://rubyonrails.org).
+
+From [sqids-ruby](https://github.com/sqids/sqids-ruby):
+
+> [Sqids](https://sqids.org/ruby) _(pronounced "squids")_ is a small library that lets you generate unique IDs from numbers. It's good for link shortening, fast & URL-safe ID generation and decoding back into numbers for quicker database lookups.
+>
+> Features:
+>
+> - Encode multiple numbers - generate short IDs from one or several non-negative numbers
+> - Quick decoding - easily decode IDs back into numbers
+> - Unique IDs - generate unique IDs by shuffling the alphabet once
+> - ID padding - provide minimum length to make IDs more uniform
+> - URL safe - auto-generated IDs do not contain common profanity
+> - Randomized output - Sequential input provides nonconsecutive IDs
+> - Many implementations - Support for 40+ programming languages
+
+## Getting started
+
+Run `bundle add sqids-rails` or add this line to your application's `Gemfile`:
+
+```ruby
+gem 'sqids-rails'
+```
+
+And then execute:
+
+```shell
+bundle
+```
+
+## Usage
+
+Add auto-generated sqids columns to your ActiveRecord models with `has_sqid`:
+
+```ruby
+# Schema: users(sqid:string, long_sqid:string)
+class User < ApplicationRecord
+  include Sqids::Rails::Model
+
+  has_sqid
+  has_sqid :long_sqid, min_length: 24
+end
+
+user = User.new
+user.save
+user.sqid # => "lzNKgEb6ZuaU"
+user.sqid_long # => "4y3SVm9M2aV8Olu6p4zZoGij"
+user.regenerate_sqid
+user.regenerate_long_sqid
+```
+
+`has_sqid` follows the same behavior as ActiveRecord's built-in [has_secure_token](https://api.rubyonrails.org/classes/ActiveRecord/SecureToken/ClassMethods.html#method-i-has_secure_token)
+
+Use a custom attribute name (the default is `sqid`):
+
+```ruby
+has_sqid :uid
+```
+
+Enforce a _minimum length_ for generated IDs:
+
+```ruby
+has_sqid min_length: 24
+```
+
+Provide a custom alphabet for generated IDs:
+
+```ruby
+has_sqid alphabet: "FxnXM1kBN6cuhsAvjW3Co7l2RePyY8DwaU04Tzt9fHQrqSVKdpimLGIJOgb5ZE"
+```
+
+Prevent specific words from appearing anywhere in generated IDs:
+
+```ruby
+has_sqid blocklist: Set.new(%w[86Rf07])
+```
+
+## Roadmap
+
+- [x] `has_sqid` for auto-generating Sqid columns
+- [ ] Extensions to [ActiveRecord::FinderMethods](https://api.rubyonrails.org/classes/ActiveRecord/FinderMethods.html) and [ActiveRecord::Associations::CollectionProxy](https://api.rubyonrails.org/classes/ActiveRecord/Associations/CollectionProxy.html#method-i-find) to find records with a Sqid-encoded primary key
+
+## Contributing
+
+Bug reports and pull requests are welcome on [GitHub](https://github.com/tbhb/sqids-rails). This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/tbhb/sqids-rails/blob/main/CODE_OF_CONDUCT.md).
+
+## Acknowledgements
+
+Thanks to Ivan Akimov ([@4kimov](https://github.com/4kimov)) for creating and maintaining Sqids and [sqids-ruby](https://github.com/sqids/sqids-ruby), and Roberto Miranda ([@robertomiranda](https://github.com/robertomiranda)) for `has_secure_token`.
+
+## MIT License
+
+Copyright (c) 2024 Anthony Burns
+
+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/Rakefile

@@ -0,0 +1,8 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"

data/app/models/user.rb

@@ -0,0 +1,6 @@
+class User < ApplicationRecord
+  include Sqids::Rails::Model
+
+  has_sqid
+  has_sqid :long_sqid, min_length: 24
+end

data/db/migrate/20240705145551_create_users.rb

@@ -0,0 +1,9 @@
+class CreateUsers < ActiveRecord::Migration[7.1]
+  def change
+    create_table :users do |t|
+      t.string :sqid
+      t.string :long_sqid
+      t.timestamps
+    end
+  end
+end

data/lib/sqids/rails/engine.rb

@@ -0,0 +1,6 @@
+class Sqids
+  module Rails
+    class Engine < ::Rails::Engine
+    end
+  end
+end

data/lib/sqids/rails/model.rb

@@ -0,0 +1,107 @@
+class Sqids
+  module Rails
+    module Model
+      class AlphabetError < StandardError; end
+
+      class MinimumLengthError < StandardError; end
+
+      extend ActiveSupport::Concern
+
+      module ClassMethods
+        # Example using #has_sqid:
+        #
+        #   # Schema: User(sqid:string, long_sqid:string)
+        #   class User < ApplicationRecord
+        #     include Sqids::Rails::Model
+        #
+        #     has_sqid
+        #     has_sqid :long_sqid, min_length: 24
+        #   end
+        #
+        #   user = User.new
+        #   user.save
+        #   user.sqid # => "lzNKgEb6ZuaU"
+        #   user.sqid_long # => "4y3SVm9M2aV8Olu6p4zZoGij"
+        #   user.regenerate_sqid
+        #   user.regenerate_long_sqid
+        #
+        # +SecureRandom.random_number(Sqids.max_value)+ is used to generate the random number to encode.
+        #
+        # Note that it's still possible to generate a race condition in the database in the same way that
+        # {validates_uniqueness_of}[https://api.rubyonrails.org/classes/ActiveRecord/Validations/ClassMethods.html#method-i-validates_uniqueness_of]
+        # can. You're encouraged to add a unique index in the database to deal with this even more unlikely scenario.
+        #
+        # See the {Sqids Ruby}[https://github.com/sqids/sqids-ruby] documentation for more information on the options.
+        #
+        # === Options
+        #
+        # [:alphabet]
+        #   The alphabet to use for encoding. Default is +Sqids::Rails.alphabet+.
+        #   The minimum alphabet length is 3 characters.
+        #   The alphabet cannot contain any multibyte characters.
+        #
+        # [:blocklist]
+        #   The blocklist to use for encoding. Default is +Sqids::Rails.blocklist+.
+        #
+        # [:min_length]
+        #   The minimum length of the generated sqid, from 0-255. Default is +Sqids::Rails.min_length+. Sqids cannot
+        #   generate IDs up to a certain length, only at least a certain length.
+        #
+        # [:on]
+        #   The callback when the value is generated. When called with <tt>on: :initialize</tt>, the value is generated
+        #   in an <tt>after_initialize</tt> callback, otherwise the value will be used in a <tt>before_</tt> callback.
+        #   When not specified, +:on+ will use the value of <tt>Sqids::Rails.generate_sqid_on</tt>, which defaults to
+        #   +:initialize+.
+        def has_sqid(
+          attribute = :sqid,
+          alphabet: Sqids::Rails.alphabet,
+          blocklist: Sqids::Rails.blocklist,
+          min_length: Sqids::Rails.min_length,
+          on: Sqids::Rails.generate_sqid_on
+        )
+          if alphabet.length < 3
+            raise AlphabetError, "Sqid requires an alphabet of at least 3 characters"
+          end
+
+          if alphabet.each_char.any? { |char| char.bytesize > 1 }
+            raise AlphabetError, "Sqid alphabet cannot contain multibyte characters"
+          end
+
+          if alphabet.chars.uniq.length != alphabet.length
+            raise AlphabetError, "Sqid alphabet must contain unique characters"
+          end
+
+          if min_length < 0 || min_length > 255
+            raise MinimumLengthError, "Sqid requires a minimum length between 0 and 255 characters"
+          end
+
+          define_method(:"regenerate_#{attribute}") do
+            update!(
+              attribute => self.class.generate_unique_sqid(
+                alphabet: alphabet, blocklist: blocklist, min_length: min_length
+              )
+            )
+          end
+          set_callback(on, (on == :initialize) ? :after : :before) do
+            if new_record? && !query_attribute(attribute)
+              send(
+                :"#{attribute}=",
+                self.class.generate_unique_sqid(alphabet: alphabet, blocklist: blocklist, min_length: min_length)
+              )
+            end
+          end
+        end
+
+        def generate_unique_sqid(
+          alphabet: Sqids::Rails.alphabet, blocklist: Sqids::Rails.blocklist, min_length: Sqids::Rails.min_length
+        )
+          @sqids ||= {}
+          @sqids[[alphabet, blocklist, min_length]] ||= Sqids.new(
+            alphabet: alphabet, blocklist: blocklist, min_length: min_length
+          )
+          @sqids[[alphabet, blocklist, min_length]].encode([SecureRandom.random_number(Sqids.max_value)])
+        end
+      end
+    end
+  end
+end

data/lib/sqids/rails/version.rb

@@ -0,0 +1,5 @@
+class Sqids
+  module Rails
+    VERSION = "0.1.0"
+  end
+end

data/lib/sqids/rails.rb

@@ -0,0 +1,23 @@
+require "active_support/core_ext/module/attribute_accessors"
+
+require "sqids"
+require "sqids/rails/version"
+require "sqids/rails/engine"
+require "sqids/rails/model"
+
+class Sqids
+  module Rails
+    mattr_accessor :alphabet, default: Sqids::DEFAULT_ALPHABET
+    mattr_accessor :blocklist, default: Sqids::DEFAULT_BLOCKLIST
+    mattr_accessor :min_length, default: Sqids::DEFAULT_MIN_LENGTH
+    mattr_accessor :generate_sqid_on, default: :initialize
+
+    def self.configure
+      yield self
+    end
+
+    def self.sqids
+      @sqids ||= Sqids.new(alphabet: alphabet, blocklist: blocklist, min_length: min_length)
+    end
+  end
+end

data/lib/sqids-rails.rb

@@ -0,0 +1 @@
+require "sqids/rails"

data/lib/tasks/sqids/rails_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :sqids_rails do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,100 @@
+--- !ruby/object:Gem::Specification
+name: sqids-rails
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Tony Burns
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-07-05 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.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.1.0
+- !ruby/object:Gem::Dependency
+  name: sqids
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.2'
+- !ruby/object:Gem::Dependency
+  name: appraisal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Short, unique, and human-readable IDs for ActiveRecord models with Sqids.
+email:
+- tony@tonyburns.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE.txt
+- README.md
+- Rakefile
+- app/assets/config/sqids_rails_manifest.js
+- app/models/user.rb
+- db/migrate/20240705145551_create_users.rb
+- lib/sqids-rails.rb
+- lib/sqids/rails.rb
+- lib/sqids/rails/engine.rb
+- lib/sqids/rails/model.rb
+- lib/sqids/rails/version.rb
+- lib/tasks/sqids/rails_tasks.rake
+homepage: https://github.com/tbhb/sqids-rails
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/tbhb/sqids-rails
+  source_code_uri: https://github.com/tbhb/sqids-rails
+  changelog_uri: https://github.com/tbhb/sqids-rails/blob/main/sqids-rails/CHANGELOG.md
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.14
+signing_key:
+specification_version: 4
+summary: Short, unique, and human-readable IDs for ActiveRecord models with Sqids.
+test_files: []