neat_ids 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 408232bf986163d716c24d7d03891a3dec78f8da54c95eabf057b759c009308b
+  data.tar.gz: 3c88987f733c6293133bdb7247a93f68c2a58e14e416b5f9a57593a6660298ba
+SHA512:
+  metadata.gz: 14202c84dbecce2b0c1a4d81f23469ede039cb90e58223d04876c143bdcc464bb920b2a41fa57aa7b7623223b9f655644a050b8ecb9dc3d1b10fe28b5af712bb
+  data.tar.gz: 6f13feb0c9cb862c767dc20d2cec62b8a54a79bf21dd1c22f934e1d42120d5452f4d73de402030c3c8ae78f282ce80f63dea3d295a0f73b0fd1349095f07c1ff

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2021 Chris Oliver
+
+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,118 @@
+# NeatIds
+Generate neat, Stripe-style prefixed IDs for your models with [Sqids](https://sqids.org/ruby). Works with numeric OR UUID-esque primary keys!
+
+Heavily inspired by [`prefixed_ids`](https://github.com/excid3/prefixed_ids)
+
+## Usage
+How to use my plugin.
+
+## Installation
+Add this line to your application's Gemfile:
+
+```ruby
+gem "neat_ids"
+```
+
+And then execute:
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+```bash
+$ gem install neat_ids
+```
+
+Add `has_neat_id :my_prefix` to your models (before you define any associations!!) to autogenerate Neat IDs.
+
+```ruby
+class User < ApplicationRecord
+  has_neat_id :user
+end
+```
+
+### Neat ID Param
+
+By default, Neat IDs overrides `to_param` in the model to use Neat IDs.
+
+To get the Neat ID for a record:
+
+```ruby
+@user.to_param
+#=> "user_12345abcd"
+```
+
+If `to_param` override is disabled:
+
+```ruby
+@user.neat_id
+#=> "user_12345abcd"
+```
+
+#### Query by Neat ID
+
+By default, neat_ids overrides `find` and `to_param` to seamlessly URLs automatically.
+
+```ruby
+User.first.to_param
+#=> "user_5vJjbzXq9KrLEMm32iAnOP0xGDYk6dpe"
+
+User.find("user_5vJjbzXq9KrLEMm32iAnOP0xGDYk6dpe")
+#=> #<User>
+```
+
+> [!NOTE]
+> `find` still finds records by primary key. For example, `User.find(1)` still works.
+
+You can also use `find_by_neat_id` or `find_by_neat_id!` when the `find` override is disabled:
+
+```ruby
+User.find_by_neat_id("user_5vJjbzXq9KrLEMm32iAnOP0xGDYk6dpe") # Returns a User or nil
+User.find_by_neat_id!("user_5vJjbzXq9KrLEMm32iAnOP0xGDYk6dpe") # Raises an exception if not found
+```
+
+To disable `find` and `to_param` overrides, pass the following options:
+
+```ruby
+class User < ApplicationRecord
+  has_neat_id :user, override_find: false, override_param: false
+end
+```
+
+> [!NOTE]
+> If you're aiming to masking primary key ID for security reasons, make sure to use `find_by_neat_id`.
+
+### Find Any Model By Neat ID
+
+Imagine you have a Neat ID but you don't know which model it belongs to:
+
+```ruby
+NeatIds.find("user_5vJjbzXq9KrLEMm3")
+#=> #<User>
+
+NeatIds.find("acct_2iAnOP0xGDYk6dpe")
+#=> #<Account>
+```
+
+This works similarly to GlobalIDs.
+
+### Customizing Neat IDs
+
+You can customize the prefix, length, and attribute name for NeatIds.
+
+```ruby
+class Account < ApplicationRecord
+  has_neat_id :acct, minimum_length: 32, override_find: false, override_param: false, fallback: false
+end
+```
+
+By default, `find` will accept both Neat IDs and regular IDs. Setting `fallback: false` will disable finding by regular IDs and will only allow Neat IDs.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/braddoeswebdev/neat_ids. 
+
+Contributors are expected to adhere to the [code of conduct](https://github.com/braddoeswebdev/neat_ids/blob/master/CODE_OF_CONDUCT.md).
+
+## License
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,18 @@
+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"
+
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
+  t.verbose = false
+end
+
+task default: :test

data/lib/neat_ids/engine.rb

@@ -0,0 +1,9 @@
+module NeatIds
+  class Engine < ::Rails::Engine
+    initializer "neat_ids.model" do
+      ActiveSupport.on_load(:active_record) do
+        include NeatIds::Rails
+      end
+    end
+  end
+end

data/lib/neat_ids/neat_id.rb

@@ -0,0 +1,59 @@
+module NeatIds
+  class NeatId
+    attr_reader :sqids, :prefix
+
+    TOKEN = 123
+
+    def initialize(model, prefix, min_length: NeatIds.minimum_length, alphabet: NeatIds.alphabet, delimiter: NeatIds.delimiter, **options)
+      @prefix = prefix.to_s
+      @delimiter = delimiter.to_s
+      @sqids = Sqids.new( min_length: min_length, alphabet: alphabet)
+    end
+
+    def encode(id)
+      return if id.nil?
+      if uuid?(id)
+        nums = uuid_to_ints(id)
+        return @prefix + @delimiter + @sqids.encode([TOKEN] + nums)
+      end
+      @prefix + @delimiter + @sqids.encode([TOKEN] + Array.wrap(id))
+    end
+
+    def decode(id, fallback: false)
+      fallback_value = fallback ? id : nil
+      _, id_without_prefix = NeatIds.split_id(id, @delimiter)
+      decoded_hashid = @sqids.decode(id_without_prefix)
+
+      if !valid?(decoded_hashid)
+        fallback_value
+      else
+        _, *ids = decoded_hashid
+        if ids.size == 4 && ids.all? { |n| n.is_a?(Integer) && n >= 0 && n <= 0xFFFFFFFF }
+          ints_to_uuid(ids)
+        else
+          (ids.size == 1) ? ids.first : ids
+        end
+      end
+    end
+
+    private
+
+    def valid?(decoded_hashid)
+      decoded_hashid.size >= 2 && decoded_hashid.first == TOKEN
+    end
+
+    def uuid?(id)
+      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/)
+    end
+
+    def uuid_to_ints(uuid)
+      hex = uuid.delete('-')
+      [0, 8, 16, 24].map { |i| hex[i, 8].to_i(16) }
+    end
+
+    def ints_to_uuid(ints)
+      hex = ints.map { |n| n.to_s(16).rjust(8, '0') }.join
+      "#{hex[0,8]}-#{hex[8,4]}-#{hex[12,4]}-#{hex[16,4]}-#{hex[20,12]}"
+    end
+  end
+end

data/lib/neat_ids/version.rb

@@ -0,0 +1,3 @@
+module NeatIds
+  VERSION = "1.0.0"
+end

data/lib/neat_ids.rb

@@ -0,0 +1,133 @@
+require "neat_ids/version"
+require "neat_ids/engine"
+
+require "sqids"
+
+module NeatIds
+  class Error < StandardError; end
+
+  autoload :NeatId, "neat_ids/neat_id"
+
+  mattr_accessor :delimiter, default: "_"
+  mattr_accessor :alphabet, default: "abcdefghijklmnopqrstuvwxyz1234567890"
+  mattr_accessor :minimum_length, default: 24
+
+  mattr_accessor :models, default: {}
+
+  def self.find(neat_id)
+    prefix, _ = split_id(neat_id)
+    models.fetch(prefix).find_by_neat_id(neat_id)
+  rescue KeyError
+    raise Error, "Unable to find model with prefix `#{prefix}`. Available prefixes are: #{models.keys.join(", ")}"
+  end
+
+  # Splits a prefixed ID into its prefix and ID
+  def self.split_id(neat_id, delimiter = NeatIds.delimiter)
+    prefix, _, id = neat_id.to_s.rpartition(delimiter)
+    [prefix, id]
+  end
+
+  def self.register_prefix(prefix, model:)
+    if (existing_model = NeatIds.models[prefix]) && existing_model != model
+      raise Error, "Prefix #{prefix} already defined for model #{model}"
+    end
+
+    NeatIds.models[prefix] = model
+  end
+
+  # Adds `has_neat_id` method
+  module Rails
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :_neat_id
+      class_attribute :_neat_id_fallback
+    end
+
+    class_methods do
+      def has_neat_id(prefix, override_find: true, override_param: true, fallback: true, **options)
+        include Attribute
+        include Finder if override_find
+        include ToParam if override_param
+        self._neat_id = NeatId.new(self, prefix, **options)
+        self._neat_id_fallback = fallback
+
+        # Register with NeatIds to support NeatIds#find
+        NeatIds.register_prefix(prefix.to_s, model: self)
+      end
+    end
+  end
+
+  # Included when a module uses `has_neat_id`
+  module Attribute
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def find_by_neat_id(id)
+        find_by(id: _neat_id.decode(id))
+      end
+
+      def find_by_neat_id!(id)
+        find_by!(id: _neat_id.decode(id))
+      end
+
+      def neat_id(id)
+        _neat_id.encode(id)
+      end
+
+      def neat_ids(ids)
+        ids.map { |id| neat_id(id) }
+      end
+
+      def decode_neat_id(id)
+        _neat_id.decode(id)
+      end
+
+      def decode_neat_ids(ids)
+        ids.map { |id| decode_neat_id(id) }
+      end
+    end
+
+    def neat_id
+      _neat_id.encode(id)
+    end
+  end
+
+  module Finder
+    extend ActiveSupport::Concern
+
+    class_methods do
+      def find(*ids)
+        # Skip if model doesn't use prefixed ids
+        return super if _neat_id.blank?
+
+        neat_ids = ids.flatten.map do |id|
+          neat_id = _neat_id.decode(id, fallback: _neat_id_fallback)
+          raise Error, "#{id} is not a valid neat_id" if !_neat_id_fallback && neat_id.nil?
+          neat_id
+        end
+        neat_ids = [neat_ids] if ids.first.is_a?(Array)
+
+        super(*neat_ids)
+      end
+
+      def relation
+        super.tap { |r| r.extend ClassMethods }
+      end
+
+      def has_many(*args, &block)
+        options = args.extract_options!
+        options[:extend] = Array(options[:extend]).push(ClassMethods)
+        super(*args, **options, &block)
+      end
+    end
+  end
+
+  module ToParam
+    extend ActiveSupport::Concern
+
+    def to_param
+      _neat_id.encode(id)
+    end
+  end
+end

metadata

@@ -0,0 +1,78 @@
+--- !ruby/object:Gem::Specification
+name: neat_ids
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Brad Thompson
+bindir: bin
+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.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 6.0.0
+- !ruby/object:Gem::Dependency
+  name: sqids
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+description: Neat IDs generates IDs with friendly prefixes for your models
+email:
+- bkt@brad-thompson.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- lib/neat_ids.rb
+- lib/neat_ids/engine.rb
+- lib/neat_ids/neat_id.rb
+- lib/neat_ids/version.rb
+homepage: https://github.com/braddoeswebdev/neat_ids
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/braddoeswebdev/neat_ids
+  source_code_uri: https://github.com/braddoeswebdev/neat_ids
+  changelog_uri: https://github.com/braddoeswebdev/neat_ids
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.7
+specification_version: 4
+summary: Neat IDs generates IDs with friendly prefixes for your models
+test_files: []