polyid 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: f9594d2b0303f978b926849714ba7aaad7bd57fe67789292766f0518a94d96e0
+  data.tar.gz: 49fea620c0f3ca6fbff464cd1a1c25b148dfc880c89ffd804a2ccc3149343182
+SHA512:
+  metadata.gz: 1a1d1cde22395b3bbcc487f7fa59a2ab39e8f28022659a1e34565e5a5bc353cfc0ecf72b629399bc7a89c359dec23e23515c12fdba74a392ccfca98e3079123a
+  data.tar.gz: 9f5659b41b8af35b9261642e0c84f1f9309930677bc04d96d810144e12909e73c8752a5799429dcf9b686fa8664410825bc908a72e81bfb924eeb68f9a3ad8e1

data/CHANGELOG.md

@@ -0,0 +1,2 @@
+###  0.1.0  (2026-04-10)
+- initial build

data/Gemfile

@@ -0,0 +1,3 @@
+source "https://rubygems.org"
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,111 @@
+PATH
+  remote: .
+  specs:
+    polyid (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activemodel (8.0.3)
+      activesupport (= 8.0.3)
+    activerecord (8.0.3)
+      activemodel (= 8.0.3)
+      activesupport (= 8.0.3)
+      timeout (>= 0.4.0)
+    activesupport (8.0.3)
+      base64
+      benchmark (>= 0.3)
+      bigdecimal
+      concurrent-ruby (~> 1.0, >= 1.3.1)
+      connection_pool (>= 2.2.5)
+      drb
+      i18n (>= 1.6, < 2)
+      logger (>= 1.4.2)
+      minitest (>= 5.1)
+      securerandom (>= 0.3)
+      tzinfo (~> 2.0, >= 2.0.5)
+      uri (>= 0.13.1)
+    base64 (0.3.0)
+    benchmark (0.4.1)
+    bigdecimal (3.3.1)
+    concurrent-ruby (1.3.5)
+    connection_pool (2.5.4)
+    date (3.4.1)
+    debug (1.11.0)
+      irb (~> 1.10)
+      reline (>= 0.3.8)
+    diff-lcs (1.6.2)
+    docile (1.4.0)
+    drb (2.2.3)
+    erb (5.0.1)
+    factory_bot (6.5.4)
+      activesupport (>= 6.1.0)
+    faker (3.5.2)
+      i18n (>= 1.8.11, < 2)
+    i18n (1.14.7)
+      concurrent-ruby (~> 1.0)
+    io-console (0.8.0)
+    irb (1.15.2)
+      pp (>= 0.6.0)
+      rdoc (>= 4.0.0)
+      reline (>= 0.4.2)
+    logger (1.7.0)
+    mini_portile2 (2.8.9)
+    minitest (5.26.0)
+    pp (0.6.2)
+      prettyprint
+    prettyprint (0.2.0)
+    psych (5.2.6)
+      date
+      stringio
+    rdoc (6.14.1)
+      erb
+      psych (>= 4.0.0)
+    reline (0.6.1)
+      io-console (~> 0.5)
+    rspec (3.13.1)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.4)
+      rspec-support (~> 3.13.0)
+    rspec-debugging (0.0.4)
+      rspec-expectations (>= 3)
+    rspec-expectations (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.5)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.4)
+    securerandom (0.4.1)
+    simplecov (0.22.0)
+      docile (~> 1.1)
+      simplecov-html (~> 0.11)
+      simplecov_json_formatter (~> 0.1)
+    simplecov-html (0.12.3)
+    simplecov_json_formatter (0.1.4)
+    sqlite3 (2.7.4)
+      mini_portile2 (~> 2.8.0)
+    stringio (3.1.7)
+    timeout (0.4.3)
+    tzinfo (2.0.6)
+      concurrent-ruby (~> 1.0)
+    uri (1.0.4)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  activerecord (>= 7)
+  debug (>= 1)
+  factory_bot (>= 6)
+  faker (>= 3)
+  polyid!
+  rspec (>= 3.10)
+  rspec-debugging
+  simplecov (>= 0.22)
+  sqlite3 (>= 1.4)
+
+BUNDLED WITH
+   2.5.7

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 Daniel Pepper
+
+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,68 @@
+PolyId
+======
+![Gem](https://img.shields.io/gem/dt/polyid?style=plastic)
+[![codecov](https://codecov.io/gh/dpep/polyid/branch/main/graph/badge.svg)](https://codecov.io/gh/dpep/polyid)
+
+`polyid` adds an opt-in ActiveRecord integration for models that keep both an
+auto-incrementing primary key and a UUID column. It lets you look records up by
+either identifier and caches `id <=> uuid` translations for reuse.
+
+## Usage
+
+```ruby
+require "polyid"
+
+class User < ApplicationRecord
+  polyid
+end
+
+user = User.create!(uuid: SecureRandom.uuid)
+
+User.find(user.id)
+User.find(user.uuid)
+
+User.id_for(user.uuid)
+User.uuid_for(user.id)
+
+User.ids_for([user.uuid, 123, nil])
+User.uuids_for([user.id, "8f47a7ca-8f4a-4d7b-96e6-60a0b47ddf68", nil])
+```
+
+`find` accepts IDs, UUIDs, or a mix of both:
+
+```ruby
+User.find(user.id)
+User.find(user.uuid)
+User.find(user.id, user.uuid)
+User.find([user.uuid, user.id])
+```
+
+Translation helpers preserve input order and return `nil` for misses:
+
+```ruby
+User.id_for(user.uuid)       # => 123
+User.uuid_for(user.id)       # => "..."
+```
+
+By default `polyid` uses the `uuid` column. You can point it at another column:
+
+```ruby
+class Account < ApplicationRecord
+  polyid uuid_attribute: :public_id
+end
+```
+
+The cache is warmed automatically when records are loaded and updated.
+
+
+----
+## Contributing
+
+Yes please  :)
+
+1. Fork it
+1. Create your feature branch (`git checkout -b my-feature`)
+1. Ensure the tests pass (`bundle exec rspec`)
+1. Commit your changes (`git commit -am 'awesome new feature'`)
+1. Push your branch (`git push origin my-feature`)
+1. Create a Pull Request

data/lib/polyid/cache.rb

@@ -0,0 +1,78 @@
+module PolyId
+  module Cache
+    class << self
+      def read(model_name, id: nil, uuid: nil)
+        PolyId.cache.read(key(model_name, id: id, uuid: uuid))
+      end
+
+      def read_multi(model_name, ids: [], uuids: [])
+        keys = ids.map { |id| key(model_name, id: id) } +
+          uuids.map { |uuid| key(model_name, uuid: uuid) }
+
+        cached = PolyId.cache.read_multi(*keys)
+
+        {
+          ids: ids.each_with_object({}) do |id, values|
+            cache_key = key(model_name, id: id)
+            values[id] = cached[cache_key] if cached.key?(cache_key)
+          end,
+          uuids: uuids.each_with_object({}) do |uuid, values|
+            cache_key = key(model_name, uuid: uuid)
+            values[uuid] = cached[cache_key] if cached.key?(cache_key)
+          end,
+        }
+      end
+
+      def fetch_ids(model_name, uuids:)
+        cached_ids = read_multi(model_name, uuids: uuids)[:uuids]
+        missing_uuids = uuids - cached_ids.keys
+
+        if missing_uuids.any?
+          yielded_ids = yield(missing_uuids)
+          cached_ids.merge!(yielded_ids)
+        end
+
+        cached_ids
+      end
+
+      def fetch_uuids(model_name, ids:)
+        cached_uuids = read_multi(model_name, ids: ids)[:ids]
+        missing_ids = ids - cached_uuids.keys
+
+        if missing_ids.any?
+          yielded_uuids = yield(missing_ids)
+          cached_uuids.merge!(yielded_uuids)
+        end
+
+        cached_uuids
+      end
+
+      def write(model_name, id:, uuid:)
+        PolyId.cache.write_multi(
+          key(model_name, id: id) => uuid,
+          key(model_name, uuid: uuid) => id,
+        )
+      end
+
+      def delete(model_name, id:, uuid:)
+        delete_multi(model_name, ids: [id], uuids: [uuid])
+      end
+
+      def delete_multi(model_name, ids: [], uuids: [])
+        keys = ids.map { |id| key(model_name, id: id) } +
+          uuids.map { |uuid| key(model_name, uuid: uuid) }
+
+        PolyId.cache.delete_multi(keys)
+      end
+
+      private
+
+      def key(model_name, id: nil, uuid: nil)
+        raise ArgumentError, "id or uuid required" if id.nil? && uuid.nil?
+
+        locator = id.nil? ? "uuid:#{uuid}" : "id:#{id}"
+        "polyid/#{model_name}/#{locator}"
+      end
+    end
+  end
+end

data/lib/polyid/model.rb

@@ -0,0 +1,145 @@
+module PolyId
+  module Model
+    extend ActiveSupport::Concern
+
+    included do
+      class_attribute :polyid_uuid_attribute, instance_writer: false, default: nil
+
+      after_find :polyid_warm_cache
+      after_save :polyid_refresh_cache
+      after_destroy :polyid_evict_cache
+    end
+
+    class_methods do
+      def polyid(uuid_attribute: :uuid)
+        self.polyid_uuid_attribute = uuid_attribute.to_s
+      end
+
+      def find(*ids)
+        return super unless polyid?
+
+        if ids.length == 1 && ids.first.is_a?(Array)
+          # find([1, 2])
+          super(resolve_polyids(ids.first))
+        else
+          # find(1) or find(1, 2)
+          super(*resolve_polyids(ids))
+        end
+      end
+
+      def id_for(value)
+        ids_for([value]).first
+      end
+
+      def ids_for(values)
+        values = Array(values)
+        uuids = values.select { |value| PolyId.is_uuid?(value) }
+
+        resolved_uuids = PolyId::Cache.fetch_ids(name, uuids: uuids) do |missing_uuids|
+          where(polyid_uuid_attribute => missing_uuids).each_with_object({}) do |record, resolved|
+            resolved[record.public_send(polyid_uuid_attribute)] = record.public_send(primary_key)
+          end
+        end
+
+        values.map do |value|
+          if PolyId.is_uuid?(value)
+            resolved_uuids[value]
+          else
+            value
+          end
+        end
+      end
+
+      def uuid_for(value)
+        uuids_for([value]).first
+      end
+
+      def uuids_for(values)
+        values = Array(values)
+        ids = values.reject { |value| PolyId.is_uuid?(value) || value.blank? }
+
+        resolved_ids = PolyId::Cache.fetch_uuids(name, ids: ids) do |missing_ids|
+          where(primary_key => missing_ids).each_with_object({}) do |record, resolved|
+            resolved[record.public_send(primary_key)] = record.public_send(polyid_uuid_attribute)
+          end
+        end
+
+        values.map do |value|
+          if PolyId.is_uuid?(value)
+            value
+          else
+            resolved_ids[value]
+          end
+        end
+      end
+
+      def polyid?
+        polyid_uuid_attribute.present?
+      end
+
+      private
+
+      def resolve_polyids(values)
+        uuids = values.select { |value| PolyId.is_uuid?(value) }
+        cached_ids = PolyId::Cache.fetch_ids(name, uuids: uuids) do |missing_uuids|
+          where(polyid_uuid_attribute => missing_uuids).each_with_object({}) do |record, ids|
+            ids[record.public_send(polyid_uuid_attribute)] = record.public_send(primary_key)
+          end
+        end
+
+        values.map do |value|
+          PolyId.is_uuid?(value) ? cached_ids[value] : value
+        end
+      end
+    end
+
+    private
+
+    def polyid_warm_cache
+      return unless self.class.polyid?
+
+      cache_polyid
+    end
+
+    def polyid_refresh_cache
+      return unless self.class.polyid?
+
+      if previous_uuid = polyid_previous_uuid
+        PolyId::Cache.delete_multi(
+          self.class.name,
+          ids: [public_send(self.class.primary_key)],
+          uuids: [previous_uuid],
+        )
+      end
+
+      cache_polyid
+    end
+
+    def polyid_evict_cache
+      return unless self.class.polyid?
+
+      id = public_send(self.class.primary_key)
+      uuid = public_send(self.class.polyid_uuid_attribute)
+
+      PolyId::Cache.delete_multi(
+        self.class.name,
+        ids: id.present? ? [id] : [],
+        uuids: uuid.present? ? [uuid] : [],
+      )
+    end
+
+    def polyid_previous_uuid
+      return unless saved_change_to_attribute?(self.class.polyid_uuid_attribute)
+
+      attribute_before_last_save(self.class.polyid_uuid_attribute)
+    end
+
+    def cache_polyid
+      id = public_send(self.class.primary_key)
+      uuid = public_send(self.class.polyid_uuid_attribute)
+      return if id.blank? || uuid.blank?
+
+      PolyId::Cache.write(self.class.name, id: id, uuid: uuid)
+    end
+  end
+end

data/lib/polyid/version.rb

@@ -0,0 +1,3 @@
+module PolyId
+  VERSION = Gem.loaded_specs["polyid"].version.to_s
+end

data/lib/polyid.rb

@@ -0,0 +1,29 @@
+require "active_support"
+require "active_support/cache"
+require "active_support/concern"
+require "active_support/core_ext/object/blank"
+require "active_support/core_ext/class/attribute"
+require "active_support/lazy_load_hooks"
+require "polyid/cache"
+require "polyid/model"
+require "polyid/version"
+
+module PolyId
+  UUID_PATTERN = /\A\h{8}-\h{4}-\h{4}-\h{4}-\h{12}\z/i
+
+  class << self
+    attr_writer :cache
+
+    def cache
+      @cache ||= ActiveSupport::Cache::MemoryStore.new
+    end
+
+    def is_uuid?(value)
+      value.is_a?(String) && UUID_PATTERN.match?(value)
+    end
+  end
+end
+
+ActiveSupport.on_load(:active_record) do
+  include PolyId::Model
+end

data/polyid.gemspec

@@ -0,0 +1,21 @@
+Gem::Specification.new do |s|
+  s.authors     = ["Daniel Pepper"]
+  s.description = "..."
+  s.files       = `git ls-files * ':!:spec'`.split("\n")
+  s.homepage    = "https://github.com/dpep/polyid"
+  s.license     = "MIT"
+  s.name        = File.basename(__FILE__, ".gemspec")
+  s.summary     = "PolyId"
+  s.version     = "0.1.0"
+
+  s.required_ruby_version = ">= 3.3"
+
+  s.add_development_dependency 'activerecord', '>= 7'
+  s.add_development_dependency 'debug', '>= 1'
+  s.add_development_dependency 'factory_bot', '>= 6'
+  s.add_development_dependency 'faker', '>= 3'
+  s.add_development_dependency 'rspec', '>= 3.10'
+  s.add_development_dependency 'rspec-debugging'
+  s.add_development_dependency 'simplecov', '>= 0.22'
+  s.add_development_dependency 'sqlite3', '>= 1.4'
+end

metadata

@@ -0,0 +1,160 @@
+--- !ruby/object:Gem::Specification
+name: polyid
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Daniel Pepper
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7'
+- !ruby/object:Gem::Dependency
+  name: debug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1'
+- !ruby/object:Gem::Dependency
+  name: factory_bot
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6'
+- !ruby/object:Gem::Dependency
+  name: faker
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.10'
+- !ruby/object:Gem::Dependency
+  name: rspec-debugging
+  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'
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.22'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.4'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.4'
+description: "..."
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- lib/polyid.rb
+- lib/polyid/cache.rb
+- lib/polyid/model.rb
+- lib/polyid/version.rb
+- polyid.gemspec
+homepage: https://github.com/dpep/polyid
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: PolyId
+test_files: []