poly 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 56f2e1989d5977256fd93964e07d62d3a26b696bc469baf3ddf477141eb7f383
+  data.tar.gz: 33239362e770c93e2871754f9697763c893960af1e0238aac59ddfd94a8b7399
+SHA512:
+  metadata.gz: 190707ca692b512d914adcd3b5cfbdfab79a14730ce14043a6c361642ebb6b193941ae75909e24a6405b9f96c23b746b61d9b66daa77255cb0a9241cc3b3be5a
+  data.tar.gz: 6ae262801aaab5a09416080fb36df87a9ee65918698ab08bc12e1e2b6c612c9d9bee288a396842bc89c6b165e6515d8b50f84009f5670b5111a2c1ff2be1735e

data/CHANGELOG.md

@@ -0,0 +1,57 @@
+# 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.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.0] - 2026-02-18
+
+### Added
+
+- `Poly::Migration` — helpers for declaring polymorphic resource/role/owner columns and indexes
+  consistently across `create_table`, `change_table`, and `add_column`-style migrations.
+  Helpers: `poly_resource`, `poly_role`, `poly_owner`, `poly_resource_index`, `poly_owner_index`.
+- `Poly::Owners` — stamps `owner_type`/`owner_id` (or custom columns) before validation.
+  Supports proc/method/object owner resolution, `allow_nil`, and `immutable` options.
+  Validates that the named association is a polymorphic `belongs_to` and that the owner
+  is a persisted `ActiveRecord::Base` instance.
+- `poly_role immutable: true` option — raises on update if the role has already been set,
+  preventing role changes after create.
+- `poly_resource_index` and `poly_owner_index` migration helpers for consistent index naming
+  and uniqueness declarations on polymorphic column pairs.
+
+### Changed
+
+- `Poly::Label` renamed to `Poly::Role`; the role column (e.g. `commentable_role`) replaces
+  the former label column (`commentable_label`).
+- `poly_role` now enforces lowercase alphanumeric/underscore format (`/\A[a-z0-9_]+\z/`)
+  and normalises values (strip + downcase) before validation and in `for_role` queries.
+- Ruby requirement raised to `>= 3.2.0`.
+
+### Removed
+
+- `Poly::Label` — fully replaced by `Poly::Role`. Update column names and any
+  `for_label` / `poly_label` references to `for_role` / `poly_role` accordingly.
+
+## [0.2.0] - 2024
+
+### Added
+
+- `Poly::Role` (originally shipped as `Poly::Label`) — role validation, normalization,
+  and `for_role` scope for polymorphic associations.
+
+## [0.1.0] - 2024
+
+### Added
+
+- `Poly::Joins` — type-safe polymorphic `INNER JOIN` generation via `define_polymorphic_joins!`.
+  Creates methods like `joins_commentable(ClassName)` that validate the reverse
+  `has_many`/`has_one` association before building the join SQL.
+
+[Unreleased]: https://github.com/leewhittaker/poly/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/leewhittaker/poly/compare/v0.2.0...v1.0.0
+[0.2.0]: https://github.com/leewhittaker/poly/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/leewhittaker/poly/releases/tag/v0.1.0

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Lee Whittaker
+
+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,234 @@
+# Poly
+
+Type-safe joins, role identity, and owner identity for polymorphic `belongs_to` associations in Rails.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'poly'
+```
+
+Then run `bundle install`.
+
+## Requirements
+
+- Ruby >= 3.2
+- ActiveRecord >= 7.1
+
+## Usage
+
+### Poly::Joins
+
+Generates type-safe `INNER JOIN` methods for polymorphic associations. Include the module in a model that has a polymorphic `belongs_to`, and it will define a `joins_<association>` class method for each one.
+
+```ruby
+class Comment < ApplicationRecord
+  belongs_to :commentable, polymorphic: true
+
+  include Poly::Joins
+end
+
+class Post < ApplicationRecord
+  has_many :comments, as: :commentable
+end
+
+class User < ApplicationRecord
+  has_many :comments, as: :commentable
+end
+```
+
+Now you can join through the polymorphic association by passing the target class:
+
+```ruby
+# Join comments to the posts table
+Comment.joins_commentable(Post)
+# => SELECT "comments".* FROM "comments"
+#    INNER JOIN "posts"
+#    ON "comments"."commentable_id" = "posts"."id"
+#    AND "comments"."commentable_type" = 'Post'
+
+# Chainable with other scopes
+Comment.joins_commentable(Post).where(posts: { title: 'Hello' })
+
+# Join to a different target type
+Comment.joins_commentable(User).where(users: { name: 'Lee' })
+```
+
+**Safety:** The target class must declare the reverse association (`has_many` or `has_one` with `as: :commentable`). If it doesn't, a `PolymorphicJoinError` is raised:
+
+```ruby
+Comment.joins_commentable(Unrelated)
+# => PolymorphicJoinError: Unrelated must declare has_one/has_many as: :commentable
+```
+
+### Poly::Role
+
+Adds a validated role column to a polymorphic association. This is useful when a single polymorphic relationship needs to distinguish between different roles or categories.
+
+Your table needs a `<association>_role` string column:
+
+```ruby
+create_table :taggings do |t|
+  t.references :taggable, polymorphic: true, null: false
+  t.string :taggable_role, null: false
+  t.timestamps
+end
+
+# Index: composite on (taggable_type, taggable_id, taggable_role) if uniqueness is required
+add_index :taggings, [:taggable_type, :taggable_id, :taggable_role], unique: true
+```
+
+Then include the module and declare the role-enabled association:
+
+```ruby
+class Tagging < ApplicationRecord
+  belongs_to :taggable, polymorphic: true
+
+  include Poly::Role
+
+  poly_role :taggable
+  # optionally:
+  # poly_role :taggable, max_length: 128
+  # poly_role :taggable, immutable: true
+end
+```
+
+This gives you:
+
+- **Normalization** — roles are stripped and downcased before validation and before `for_role` queries
+- **Validation** — roles must match `/\A[a-z0-9_]+\z/` and be at most 64 characters (configurable via `max_length:`)
+- **Scope** — `for_role` queries by role, normalizing the input automatically
+- **Immutability** — `immutable: true` adds an `on: :update` validation that prevents role changes after create
+
+```ruby
+tagging = Tagging.new(taggable: post, taggable_role: '  Primary  ')
+tagging.valid?
+tagging.taggable_role # => "primary"
+
+Tagging.for_role('  PRIMARY  ')
+# => normalizes to 'primary' before querying
+```
+
+### Poly::Owners
+
+Stamps `owner_type`/`owner_id` columns before validation. Useful for recording data ownership at write time without coupling the model to tenancy or policy logic.
+
+Your table needs `owner_type` and `owner_id` columns (in addition to your polymorphic resource columns):
+
+```ruby
+create_table :coins do |t|
+  t.references :ledger, null: false
+  t.references :resource, polymorphic: true, null: false
+  t.string :resource_role, null: false
+  t.string :owner_type
+  t.integer :owner_id
+  t.timestamps
+end
+
+# Index: always composite — never index owner_type and owner_id separately
+add_index :coins, [:owner_type, :owner_id]
+```
+
+Then declare how the owner should be resolved:
+
+```ruby
+class Coin < ApplicationRecord
+  belongs_to :ledger
+  belongs_to :resource, polymorphic: true
+
+  include Poly::Owners
+
+  poly_owner :resource, owner: -> { ledger&.account }
+  # optionally:
+  # poly_owner :resource, owner: -> { ledger&.account }, allow_nil: false
+  # poly_owner :resource, owner: -> { ledger&.account }, immutable: true
+end
+```
+
+**`owner` resolution** — can be a `Proc` (evaluated in instance context), a `Symbol`/`String` (method name called on the record), or a direct `ActiveRecord::Base` instance. The owner must be persisted; an `ArgumentError` is raised otherwise.
+
+**Options:**
+
+| Option | Default | Description |
+|---|---|---|
+| `type_column:` | `:owner_type` | Column to store the owner class name |
+| `id_column:` | `:owner_id` | Column to store the owner id |
+| `allow_nil:` | `true` | When `false`, raises if the owner resolves to `nil` |
+| `immutable:` | `false` | When `true`, prevents owner changes after create via `on: :update` validation |
+
+### Poly::Migration
+
+Adds migration helpers so polymorphic resource/role/owner columns are declared consistently.
+
+Use it in your migration base class:
+
+```ruby
+class ApplicationMigration < ActiveRecord::Migration[7.1]
+  include Poly::Migration
+end
+```
+
+Supported styles:
+
+- `create_table` / `change_table` via a table builder (`t`)
+- direct existing-table operations via `add_column` style (pass table name)
+
+#### Create Table / Change Table
+
+```ruby
+class CreateCoins < ApplicationMigration
+  def change
+    create_table :coins do |t|
+      poly_resource t, :resource, null: false
+      poly_role t, :resource, null: false
+      poly_owner t, null: false
+      t.timestamps
+    end
+
+    poly_resource_index :coins, :resource
+    poly_owner_index :coins
+  end
+end
+```
+
+#### Existing Table (add_column style)
+
+```ruby
+class AddPolyColumnsToCoins < ApplicationMigration
+  def change
+    poly_resource :coins, :resource, null: false
+    poly_role :coins, :resource, null: false
+    poly_owner :coins, null: false
+
+    poly_resource_index :coins, :resource
+    poly_owner_index :coins
+  end
+end
+```
+
+#### Helper Reference
+
+| Helper | Purpose |
+|---|---|
+| `poly_resource(table_or_builder, name, null: true, id_type: :string)` | Adds `<name>_type` and `<name>_id` |
+| `poly_role(table_or_builder, name, null: true)` | Adds `<name>_role` |
+| `poly_owner(table_or_builder, type_column: :owner_type, id_column: :owner_id, id_type: :string, null: true)` | Adds owner type/id columns |
+| `poly_resource_index(table, name, unique: false)` | Adds index on `<name>_type`, `<name>_id` |
+| `poly_owner_index(table, type_column: :owner_type, id_column: :owner_id, unique: false)` | Adds index on owner columns |
+
+`id_type` defaults to `:string` so owner/resource IDs can store bigint, UUID, ULID, or other identifier formats consistently.
+
+## Development
+
+```bash
+bundle install              # Install dependencies
+bundle exec rspec           # Run tests
+bundle exec rubocop         # Lint
+COVERAGE=true bundle exec rspec  # Run tests with coverage report
+```
+
+## License
+
+Released under the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

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

data/lib/poly/joins.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Poly::Joins
+  extend ActiveSupport::Concern
+
+  included do
+    define_polymorphic_joins!
+  end
+
+  class_methods do
+    def define_polymorphic_joins!
+      reflect_on_all_associations(:belongs_to).each do |assoc|
+        next unless assoc.options[:polymorphic]
+
+        reflection = assoc
+        assoc_name = reflection.name
+        method_name = :"joins_#{assoc_name}"
+
+        next if singleton_class.method_defined?(method_name)
+
+        define_singleton_method(method_name) do |klass|
+          raise PolymorphicJoinError, 'Expected an ActiveRecord model' unless klass <= ActiveRecord::Base
+
+          base_klass = klass.base_class
+
+          unless join_allowed?(klass, as: assoc_name)
+            raise PolymorphicJoinError,
+                  "Polymorphic join requires #{base_klass} to declare: " \
+                  "has_many :#{name.underscore.pluralize}, as: :#{assoc_name}"
+          end
+
+          source = arel_table
+          target = base_klass.arel_table
+
+          joins(
+            source.join(target)
+                  .on(source["#{assoc_name}_id"].eq(target[:id])
+                    .and(source["#{assoc_name}_type"].eq(base_klass.name)))
+                  .join_sources
+          )
+        end
+      end
+    end
+
+    private
+
+    def join_allowed?(klass, as:)
+      klass.reflect_on_all_associations.any? do |assoc|
+        next false unless assoc.options[:as] == as
+        next false unless %i[has_many has_one].include? assoc.macro
+
+        assoc.klass == self
+      end
+    end
+  end
+end
+
+class PolymorphicJoinError < StandardError; end

data/lib/poly/migration.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Poly::Migration
+  # Table-builder helper (create_table/change_table):
+  #   poly_resource t, :resource
+  # Direct helper (add_column style):
+  #   poly_resource :coins, :resource
+  def poly_resource(table_or_builder, name, null: true, id_type: :string)
+    if table_builder?(table_or_builder)
+      table_or_builder.references name, polymorphic: true, null: null, type: id_type
+    else
+      add_column table_or_builder, :"#{name}_type", :string, null: null
+      add_column table_or_builder, :"#{name}_id", id_type, null: null
+    end
+  end
+
+  # Table-builder helper (create_table/change_table):
+  #   poly_role t, :resource
+  # Direct helper (add_column style):
+  #   poly_role :coins, :resource
+  def poly_role(table_or_builder, name, null: true)
+    if table_builder?(table_or_builder)
+      table_or_builder.string :"#{name}_role", null: null
+    else
+      add_column table_or_builder, :"#{name}_role", :string, null: null
+    end
+  end
+
+  # Table-builder helper (create_table/change_table):
+  #   poly_owner t
+  # Direct helper (add_column style):
+  #   poly_owner :coins
+  def poly_owner(table_or_builder, type_column: :owner_type, id_column: :owner_id, id_type: :string, null: true)
+    if table_builder?(table_or_builder)
+      table_or_builder.string type_column, null: null
+      table_or_builder.public_send(id_type, id_column, null: null)
+    else
+      add_column table_or_builder, type_column, :string, null: null
+      add_column table_or_builder, id_column, id_type, null: null
+    end
+  end
+
+  def poly_resource_index(table, name, unique: false)
+    add_index table, [:"#{name}_type", :"#{name}_id"], unique: unique
+  end
+
+  def poly_owner_index(table, type_column: :owner_type, id_column: :owner_id, unique: false)
+    add_index table, [type_column, id_column], unique: unique
+  end
+
+  private
+
+  def table_builder?(value)
+    value.respond_to?(:references)
+  end
+end

data/lib/poly/owners.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module Poly::Owners
+  extend ActiveSupport::Concern
+
+  class_methods do
+    # Declares owner columns populated before validation.
+    #   poly_owner :resource, owner: -> { ledger.account }
+    #   poly_owner :resource, owner: :account
+    def poly_owner(assoc_name, owner:, type_column: :owner_type, id_column: :owner_id,
+                   allow_nil: true, immutable: false)
+      raise ArgumentError, 'owner is required' if owner.nil?
+
+      assoc = reflect_on_association(assoc_name.to_sym)
+      unless assoc&.macro == :belongs_to && assoc.options[:polymorphic]
+        raise ArgumentError, "#{name} must declare belongs_to :#{assoc_name}, polymorphic: true"
+      end
+
+      before_validation { Poly::Owners.apply_owner(self, owner, type_column, id_column, allow_nil: allow_nil) }
+      poly_owner_immutability!(type_column, id_column) if immutable
+    end
+
+    private
+
+    def poly_owner_immutability!(type_column, id_column)
+      validate(on: :update) do
+        if will_save_change_to_attribute?(type_column) || will_save_change_to_attribute?(id_column)
+          errors.add(:base, 'owner cannot be changed once set')
+        end
+      end
+    end
+  end
+
+  def self.apply_owner(record, owner, type_column, id_column, allow_nil: true)
+    resolved = resolve_owner(record, owner)
+    if resolved.nil?
+      assign_nil_owner(record, type_column, id_column, allow_nil: allow_nil)
+    elsif resolved.is_a?(ActiveRecord::Base)
+      raise ArgumentError, 'owner must be persisted' unless resolved.persisted?
+
+      record.public_send(:"#{type_column}=", resolved.class.base_class.name)
+      record.public_send(:"#{id_column}=", resolved.id)
+    else
+      raise ArgumentError, "owner must resolve to an ActiveRecord::Base, got #{resolved.class}"
+    end
+  end
+
+  def self.assign_nil_owner(record, type_column, id_column, allow_nil:)
+    raise ArgumentError, 'owner resolved to nil' unless allow_nil
+
+    record.public_send(:"#{type_column}=", nil)
+    record.public_send(:"#{id_column}=", nil)
+  end
+
+  def self.resolve_owner(record, owner)
+    case owner
+    when Proc
+      record.instance_exec(&owner)
+    when Symbol, String
+      record.public_send(owner)
+    else
+      owner
+    end
+  end
+end

data/lib/poly/role.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module Poly::Role
+  extend ActiveSupport::Concern
+
+  class_methods do
+    # Declares a role column on a polymorphic belongs_to.
+    #   poly_role :schedulable    -> expects schedulable_role column
+    #   poly_role :resource       -> expects resource_role column
+    def poly_role(assoc_name, max_length: 64, immutable: false)
+      role_col = :"#{assoc_name}_role"
+
+      validates role_col,
+                presence: true,
+                format: { with: /\A[a-z0-9_]+\z/ },
+                length: { maximum: max_length }
+
+      before_validation { public_send(:"#{role_col}=", public_send(role_col).to_s.strip.downcase.presence) }
+
+      scope :for_role, ->(role) { where(role_col => role.to_s.strip.downcase) }
+      poly_role_immutability!(role_col) if immutable
+    end
+
+    private
+
+    def poly_role_immutability!(role_col)
+      validate(on: :update) do
+        errors.add(role_col, 'cannot be changed once set') if will_save_change_to_attribute?(role_col)
+      end
+    end
+  end
+end

data/lib/poly/version.rb

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

data/lib/poly.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+require 'active_support/concern'
+require 'poly/version'
+require 'poly/joins'
+require 'poly/role'
+require 'poly/owners'
+require 'poly/migration'
+
+module Poly
+end

metadata

@@ -0,0 +1,85 @@
+--- !ruby/object:Gem::Specification
+name: poly
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Lee Whittaker
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-02-19 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+description: Type-safe joins and role identity for polymorphic belongs_to associations.
+email:
+- lee@whittakertech.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- Rakefile
+- lib/poly.rb
+- lib/poly/joins.rb
+- lib/poly/migration.rb
+- lib/poly/owners.rb
+- lib/poly/role.rb
+- lib/poly/version.rb
+homepage: https://github.com/leewhittaker/poly
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/leewhittaker/poly
+  source_code_uri: https://github.com/leewhittaker/poly
+  changelog_uri: https://github.com/leewhittaker/poly/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.19
+signing_key:
+specification_version: 4
+summary: Polymorphic association utilities for ActiveRecord
+test_files: []