make_taggable 1.5.0 → 1.7.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d900a8ac37e0f88ead6c0516fd30ddee5e8cc11c893b7d64e85c090a8b59598
-  data.tar.gz: b364eef565e3a171c56558f928360de5230c445b4b210e1aab8f536f9b998c70
+  metadata.gz: '0899d63ba230419961175b79e863fe890723fd2a58bf26a53c9fd5c75c8ce382'
+  data.tar.gz: 7cd1bd0136a30e8c9a2c0136ce064b6d334f2e4a29e9c5bd357988b07f6091e3
 SHA512:
-  metadata.gz: 611fd4635e580ff5aaaee314600d2d66e7cdb70a2bd22d8988e3eb541c3d632fc25625e485880821beeec8f0bfb71677242f3d0d14ba96e98e0dd4d15038e0ae
-  data.tar.gz: b1713ea6a65eb7a8e45dfb0d4b8d41c9d72334cfb8de93ef2c1e60a21a6a4e04758acdcb7761a117b8b275f0aecb3e98d78258a8c7f8389f433836353e676958
+  metadata.gz: d64862b76207d13c1411825adf40705ec70ec78f23ac11faf58ddcbc35e76f2c698910b7a5828f1ee831ba344210bd637bf84bf44dafc4c4ced3fbc84b051ec6
+  data.tar.gz: f6a75d3805a9afa297753266351286a14d390fe5c96d8074234ded4ea6678c3e67f77b821eabb5c9db6e3775da9b02f9ac912de953b2c31bfe00819c6b91bdc0

data/CHANGELOG.md

@@ -5,6 +5,75 @@ All notable changes to this project are documented here.
 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).
 
+## [1.7.0] - 2026-08-23
+
+### Added
+
+- `tag_class` names the class tags are read, written and returned as, so an application can give
+  tags its own validations, callbacks, associations and methods:
+
+  ```ruby
+  MakeTaggable.setup { |config| config.tag_class = "MyApp::Tag" }
+  ```
+
+  It takes a **String** and refuses a constant -- a model cannot be referenced while initializers
+  run. It must be set in an initializer, before models load, because `make_taggable` builds its
+  associations when a class body runs. See [docs/configuration.md](docs/configuration.md).
+
+  This is a global setting. Giving different contexts different vocabularies is a separate thing and
+  needs a `type` column -- see [docs/contexts.md](docs/contexts.md).
+
+### Fixed
+
+- A tag list came back in whatever order the database chose. An `ORDER BY` was applied only under
+  `make_ordered_taggable`, so `record.tag_list` could return the same tags in different orders on
+  different calls or adapters, and `tag_list_was` could report an original the list had never been
+  in. Lists are now always ordered by when each tag was applied; `preserve_tag_order` keeps its
+  existing meaning for writes and for change detection.
+
+- The documentation for `find_or_create_tags_from_list_with_context` claimed overriding it keeps a
+  separate vocabulary for one context. It does not: it routes creation only, and without a `type`
+  column on the tags table nothing distinguishes a subclass's rows.
+
+## [Unreleased]
+
+### Changed
+
+- The tag name uniqueness validation scopes itself by `type` when the tags table has that column, so
+  an application using Tag subclasses for per-context vocabularies can hold `"energy"` as a `Market`
+  and as a `Genre` while still rejecting two `Market("energy")`. Without the column nothing changes.
+
+  Previously the only way through was overriding `validates_name_uniqueness?` to `false`, which
+  turned the check off entirely and left genuine duplicates to surface as
+  `ActiveRecord::RecordNotUnique` from the database rather than as an error on the record. That hook
+  is still there for anyone who wants no check at all.
+
+### Fixed
+
+- The recipe in `docs/contexts.md` for giving a context its own vocabulary did not work. It had you
+  add a `type` column and widen the unique index, then failed on the model validation with `Name has
+  already been taken` -- after a column had been added and a unique index rewritten on a production
+  table. The validation change above removes the obstacle, and the recipe is now written from a
+  tested run.
+
+## [1.6.0] - 2026-08-23
+
+### Fixed
+
+- `includes(:tags)` made reading tag lists **slower**: it cost two extra queries and saved none,
+  because `tag_list` always queried for a context's unowned tags rather than reading what had been
+  preloaded. Reading five records' lists went from 8 queries to 3, and the count no longer grows
+  with the collection. Records loaded without the preload are unaffected.
+
+- `tag_counts_on` raised `sub-select returns N columns - expected 1` on a relation built with
+  `includes`. An eager load builds its own column list, which survived the `except(:select)` used to
+  reduce the scope to primary keys.
+
+- `all_tags` and `all_tag_counts` could not be ordered by a `taggings` column --
+  `order: "taggings.created_at desc"` raised `no such column`. The derived table they join now
+  exposes the latest `created_at` for each tag, so ordering by it means "when this tag was last
+  applied".
+
 ## [1.5.0] - 2026-08-23
 
 ### Added

data/docs/configuration.md

@@ -26,6 +26,7 @@ MakeTaggable.force_lowercase = true
 | `remove_unused_tags` | `false` | Destroy a tag row when its last tagging goes |
 | `tags_counter` | `true` | Maintain the `taggings_count` counter cache |
 | `default_parser` | `MakeTaggable::DefaultParser` | Class used to parse tag input |
+| `tag_class` | `"MakeTaggable::Tag"` | Name of the class tags are read and written as |
 | `delimiter` | `","` | Delimiter, or delimiters, separating tags |
 | `tags_table` | `:tags` | Table backing `MakeTaggable::Tag` |
 | `taggings_table` | `:taggings` | Table backing `MakeTaggable::Tagging` |
@@ -71,6 +72,51 @@ tagging, at the cost of `Tag.most_used` and `Tag.least_used`, both of which read
 Changing this on an existing application leaves the existing counts frozen at their current values
 rather than resetting them.
 
+### `tag_class`
+
+The class tags are read, written and returned as. Give it a class of your own to add validations,
+callbacks, associations or methods that apply everywhere tags are used.
+
+```ruby
+# config/initializers/make_taggable.rb
+MakeTaggable.setup do |config|
+  config.tag_class = "MyApp::Tag"
+end
+```
+
+```ruby
+# app/models/my_app/tag.rb
+class MyApp::Tag < MakeTaggable::Tag
+  has_many :synonyms
+  validates :name, format: {with: /\A[a-z0-9-]+\z/}
+
+  def to_param = name
+end
+```
+
+After which every tag the library hands back is one of yours:
+
+```ruby
+book.tags.first                    # => #<MyApp::Tag ...>
+Book.all_tags.first                # => #<MyApp::Tag ...>
+Book.tag_counts_on(:genres).first  # => #<MyApp::Tag ...>
+book.tag_list = "sci-fi"           # validated by MyApp::Tag on save
+```
+
+**Two rules, both of which will bite if ignored.**
+
+*Name the class, do not reference it.* The setting takes a String. A model constant cannot be
+referenced while initializers run — Zeitwerk has not defined it yet, and eager loading in production
+would try to resolve it before the class exists. Passing a constant raises `ArgumentError`.
+
+*Set it in an initializer, before models load.* `make_taggable` builds its associations when a model
+class body runs, so the class name has to be known by then. Setting it later — in a test, a console,
+a request — leaves associations already built against the old class. Changing it needs a boot, not a
+reload.
+
+Your class should inherit from `MakeTaggable::Tag` and share the `tags` table. It is not a way to
+give different contexts different vocabularies — see [contexts.md](contexts.md).
+
 ### `default_parser`
 
 See [parsers.md](parsers.md).

data/docs/contexts.md

@@ -152,8 +152,13 @@ Dynamic contexts get none of the generated methods in the table above — there
 ## A separate vocabulary for one context
 
 Tags are shared across contexts and models by default: one `tags` row named `"ruby"` serves
-everything. To keep a context's tags separate, subclass `MakeTaggable::Tag` and override the hook
-that resolves names to records:
+everything.
+
+To change the class **globally** — to add validations or methods to every tag — set
+[`tag_class`](configuration.md) rather than anything here. What follows is for giving one context a
+vocabulary of its own, which is a different and larger thing.
+
+Subclass `MakeTaggable::Tag` and override the hook that resolves names to records:
 
 ```ruby
 class Market < MakeTaggable::Tag
@@ -177,17 +182,38 @@ end
 This only genuinely separates the vocabularies if the tags table has a `type` column. Without one,
 Active Record has nowhere to record the subclass: rows created through `Market` are saved as plain
 tags, `Market.count` returns every tag in the table, and reloading a record gives you a
-`MakeTaggable::Tag` back. Add the column to get real separation:
+`MakeTaggable::Tag` back.
+
+Two schema changes give you real separation. The `type` column, and a replacement for the unique
+index on `tags.name` — the shipped one stops two tags sharing a name at all, so a market and a genre
+could never both be called "Energy":
 
 ```ruby
 class AddTypeToTags < ActiveRecord::Migration[7.2]
   def change
     add_column MakeTaggable.tags_table, :type, :string
-    add_index MakeTaggable.tags_table, :type
+
+    remove_index MakeTaggable.tags_table, :name
+    add_index MakeTaggable.tags_table, [:name, :type], unique: true
   end
 end
 ```
 
-Note that the shipped migrations put a unique index on `tags.name`, so two tags cannot share a name
-even across subclasses. If a market and a genre both need to be called "Energy", widen that index to
-cover `[:name, :type]`.
+The name uniqueness *validation* scopes itself by `type` as soon as the column exists, so a name can
+repeat across subclasses while still being unique within one. Nothing else to configure.
+
+With that in place the vocabularies are genuinely separate:
+
+```ruby
+company = Company.create!(name: "Acme", market_list: "energy", genre_list: "energy")
+
+MakeTaggable::Tag.pluck(:name, :type)  # => [["energy", "Market"], ["energy", "Genre"]]
+Market.count                           # => 1
+Genre.count                            # => 1
+company.markets.map(&:class)           # => [Market]
+company.market_list                    # => ["energy"]
+Company.tagged_with("energy", on: :markets)   # => [Acme]
+```
+
+`tagged_with` without an `:on` still matches by name across every vocabulary, which is usually what
+you want from an unscoped search — pass `:on` when you mean one of them.

data/docs/querying.md

@@ -168,6 +168,18 @@ MakeTaggable::Tag.for_context(:skills) # used in this context, on any model
 query time. If you set `MakeTaggable.tags_counter = false` that counter is not maintained and both
 scopes will be wrong.
 
+## Reading tag lists across a collection
+
+Reading `<context>_list` on each of a set of records queries once per record. Eager load the tags to
+avoid it:
+
+```ruby
+Book.includes(:tags).each { |book| book.tag_list }   # constant queries, whatever the count
+```
+
+The lists are then read from the preload. Owned tags are still excluded from `tag_list`, as they are
+without it.
+
 ## Grouping and ordering by tagging columns
 
 `tagged_with` does not join the taggings table, so a `taggings` column is not in scope on the
@@ -181,6 +193,23 @@ Book.tagged_with("sci-fi").joins(:taggings).order("taggings.created_at desc")
 Note that joining reintroduces one row per tagging, which is exactly what `tagged_with` avoids on
 its own — add `.distinct` if you want records back rather than matches.
 
+## Counting tags for a subset of records
+
+`tag_counts_on` and `all_tags` apply to whatever scope they are called on, so narrowing the records
+narrows the counts:
+
+```ruby
+Book.where(published: true).tag_counts_on(:genres)
+Book.joins(:author).where(authors: {country: "IE"}).tag_counts_on(:genres)
+```
+
+`:order` accepts a `taggings` column, which orders by when a tag was last applied:
+
+```ruby
+Book.all_tags(order: "taggings.created_at desc")     # most recently used first
+Book.all_tag_counts(order: "count desc", limit: 10)
+```
+
 ## Performance notes
 
 - `tagged_with` tests for each tag with an `EXISTS` subquery, one per tag, and joins nothing. That

data/lib/make_taggable/tag.rb

@@ -24,7 +24,22 @@ module MakeTaggable
 
     ### VALIDATIONS:
     validates_presence_of :name
-    validates_uniqueness_of :name, if: :validates_name_uniqueness?, case_sensitive: true
+    # Two declarations, one of which runs. A tags table with a `type` column is
+    # being used for single table inheritance -- a Tag subclass per vocabulary --
+    # and there a name is expected to repeat across subclasses: "energy" as a
+    # Market and as a Genre. Scoping the check keeps it meaningful within a
+    # subclass rather than making the whole thing something to switch off.
+    #
+    # The column is looked up per validation rather than when this class loads,
+    # because the class can load before the migration that adds it has run.
+    validates_uniqueness_of :name,
+      if: -> { validates_name_uniqueness? && !self.class.tag_type_column? },
+      case_sensitive: true
+
+    validates_uniqueness_of :name,
+      scope: :type,
+      if: -> { validates_name_uniqueness? && self.class.tag_type_column? },
+      case_sensitive: true
     validates_length_of :name, maximum: 255
 
     ##
@@ -38,6 +53,18 @@ module MakeTaggable
       true
     end
 
+    ##
+    # Whether the tags table carries a `type` column, and so is being used for single table
+    # inheritance.
+    #
+    # @return [TrueClass, FalseClass]
+    #
+    # @api private
+    #
+    def self.tag_type_column?
+      column_names.include?("type")
+    end
+
     ### SCOPES:
     scope :most_used, ->(limit = 20) { order("taggings_count desc").limit(limit) }
     scope :least_used, ->(limit = 20) { order("taggings_count asc").limit(limit) }

data/lib/make_taggable/taggable/collection.rb

@@ -107,8 +107,10 @@ module MakeTaggable::Taggable
         options[:conditions] = sanitize_sql(options[:conditions]) if options[:conditions]
 
         ## Generate scope:
-        tagging_scope = MakeTaggable::Tagging.select("#{MakeTaggable::Tagging.table_name}.tag_id")
-        tag_scope = MakeTaggable::Tag.select("#{MakeTaggable::Tag.table_name}.*").order(options[:order]).limit(options[:limit])
+        tagging_scope = MakeTaggable::Tagging.select(
+          "#{MakeTaggable::Tagging.table_name}.tag_id, #{last_applied_at_projection}"
+        )
+        tag_scope = MakeTaggable.tag_model.select("#{MakeTaggable::Tag.table_name}.*").order(options[:order]).limit(options[:limit])
 
         # Joins and conditions
         tagging_conditions(options).each { |condition| tagging_scope = tagging_scope.where(condition) }
@@ -147,8 +149,10 @@ module MakeTaggable::Taggable
         options[:conditions] = sanitize_sql(options[:conditions]) if options[:conditions]
 
         ## Generate scope:
-        tagging_scope = MakeTaggable::Tagging.select("#{MakeTaggable::Tagging.table_name}.tag_id, COUNT(#{MakeTaggable::Tagging.table_name}.tag_id) AS tags_count")
-        tag_scope = MakeTaggable::Tag.select("#{MakeTaggable::Tag.table_name}.*, #{MakeTaggable::Tagging.table_name}.tags_count AS count").order(options[:order]).limit(options[:limit])
+        tagging_scope = MakeTaggable::Tagging.select(
+          "#{MakeTaggable::Tagging.table_name}.tag_id, COUNT(#{MakeTaggable::Tagging.table_name}.tag_id) AS tags_count, #{last_applied_at_projection}"
+        )
+        tag_scope = MakeTaggable.tag_model.select("#{MakeTaggable::Tag.table_name}.*, #{MakeTaggable::Tagging.table_name}.tags_count AS count").order(options[:order]).limit(options[:limit])
 
         # Current model is STI descendant, so add type checking to the join condition
         unless descends_from_active_record?
@@ -200,12 +204,38 @@ module MakeTaggable::Taggable
           scoped_ids = pluck(table_name_pkey)
           tagging_scope = tagging_scope.where("#{MakeTaggable::Tagging.table_name}.taggable_id IN (?)", scoped_ids)
         else
-          tagging_scope = tagging_scope.where("#{MakeTaggable::Tagging.table_name}.taggable_id IN(#{safe_to_sql(except(:select).select(table_name_pkey))})")
+          tagging_scope = tagging_scope.where("#{MakeTaggable::Tagging.table_name}.taggable_id IN(#{safe_to_sql(taggable_ids_scope(table_name_pkey))})")
         end
 
         tagging_scope
       end
 
+      # The current scope reduced to primary keys, for embedding in an IN clause.
+      #
+      # `except(:select)` is not enough on its own. An eager load builds its own column list rather
+      # than storing it in select_values, so it survives and the subquery comes back with a column
+      # per attribute of every table involved -- where the IN needs exactly one. Turning the eager
+      # load into a join keeps any condition on the joined table while selecting only the key.
+      def taggable_ids_scope(table_name_pkey)
+        scope = except(:select)
+        eager_loaded = scope.includes_values + scope.eager_load_values
+
+        scope = scope.except(:includes, :eager_load, :preload).left_joins(*eager_loaded) if eager_loaded.any?
+
+        scope.select(table_name_pkey)
+      end
+
+      # The tagging scope is embedded as a derived table aliased to the taggings table name, so
+      # `order: "taggings.created_at"` resolves against that rather than the real table -- which
+      # projected tag_id alone, and the column appeared not to exist.
+      #
+      # It groups by tag_id, so a tag may stand for many taggings and there is no single created_at
+      # to expose. The latest is the useful one: ordering by it means "when this tag was last
+      # applied".
+      def last_applied_at_projection
+        "MAX(#{MakeTaggable::Tagging.table_name}.created_at) AS created_at"
+      end
+
       def tagging_conditions(options)
         tagging_conditions = []
         tagging_conditions.push sanitize_sql(["#{MakeTaggable::Tagging.table_name}.created_at <= ?", options.delete(:end_at)]) if options[:end_at]

data/lib/make_taggable/taggable/core.rb

@@ -54,7 +54,7 @@ module MakeTaggable::Taggable
               after_remove: :dirtify_tag_list
 
             has_many context_tags, -> { order(taggings_order) },
-              class_name: "MakeTaggable::Tag",
+              class_name: MakeTaggable.tag_class,
               through: context_taggings,
               source: :tag
           end
@@ -408,7 +408,7 @@ module MakeTaggable::Taggable
         if cached_tag_list_on(context) && ensure_included_cache_methods! && self.class.caching_tag_list_on?(context)
           MakeTaggable.default_parser.new(cached_tag_list_on(context)).parse
         else
-          MakeTaggable::TagList.new(tags_on(context).map(&:name))
+          MakeTaggable::TagList.new(unowned_tag_names_on(context))
         end
 
       # Note what was there the first time the list is built, before anything
@@ -470,13 +470,66 @@ module MakeTaggable::Taggable
     end
 
     ##
-    # Returns all tags that are not owned of a given context
+    # The names of a context's unowned tags, read from the preloaded taggings where they are
+    # available and queried where they are not.
+    #
+    # `includes(:tags)` loads the per-context taggings association as well as the tags themselves,
+    # and those taggings carry `tagger_id` -- which is what makes them usable here, since the list
+    # excludes owned tags and the tags association alone cannot say which are owned.
+    #
+    # @param context [Symbol, String] the tagging context
+    # @return [Array<String>]
+    #
+    # @api private
+    #
+    def unowned_tag_names_on(context)
+      preloaded = preloaded_taggings_on(context)
+      return tags_on(context).map(&:name) unless preloaded
+
+      preloaded.map { |tagging| tagging.tag.name }
+    end
+
+    ##
+    # A context's taggings if they are already in memory, otherwise `nil`.
+    #
+    # Only unowned taggings are returned, in tagging order where the model preserves it, so the
+    # result matches what {#tags_on} would have queried.
+    #
+    # @param context [Symbol, String] the tagging context
+    # @return [Array<MakeTaggable::Tagging>, NilClass]
+    #
+    # @api private
+    #
+    def preloaded_taggings_on(context)
+      name = :"#{context.to_s.singularize}_taggings"
+      return unless self.class.reflect_on_association(name)
+
+      association = association(name)
+      return unless association.loaded?
+
+      taggings = association.target.reject(&:tagger_id)
+      self.class.preserve_tag_order? ? taggings.sort_by(&:id) : taggings
+    end
+
+    ##
+    ##
+    # A context's unowned tags, in the order they were applied.
+    #
+    # The order is always applied, not only under `preserve_tag_order`. Without it the database
+    # returns rows in whatever order it likes -- insertion order on SQLite, planner-dependent on
+    # PostgreSQL -- so the same list could come back differently on different calls or adapters, and
+    # `tag_list_was` could report the original in an order that never existed.
+    #
+    # `preserve_tag_order` still decides whether reordering a list counts as a change and whether
+    # saving rewrites taggings to match; this only makes reading deterministic.
+    #
+    # @param context [Symbol, String] the tagging context
+    # @return [ActiveRecord::Relation]
+    #
     def tags_on(context)
-      scope = base_tags.where(["#{MakeTaggable::Tagging.table_name}.context = ? AND #{MakeTaggable::Tagging.table_name}.tagger_id IS NULL", context.to_s])
-      # when preserving tag order, return tags in created order
-      # if we added the order to the association this would always apply
-      scope = scope.order("#{MakeTaggable::Tagging.table_name}.id") if self.class.preserve_tag_order?
-      scope
+      base_tags
+        .where(["#{MakeTaggable::Tagging.table_name}.context = ? AND #{MakeTaggable::Tagging.table_name}.tagger_id IS NULL", context.to_s])
+        .order("#{MakeTaggable::Tagging.table_name}.id")
     end
 
     ##
@@ -549,7 +602,7 @@ module MakeTaggable::Taggable
     ##
     # Find existing tags or create non-existing tags
     def load_tags(tag_list)
-      MakeTaggable::Tag.find_or_create_all_with_like_by_name(tag_list)
+      MakeTaggable.tag_model.find_or_create_all_with_like_by_name(tag_list)
     end
 
     ##
@@ -644,10 +697,15 @@ module MakeTaggable::Taggable
     ##
     # Finds or creates the tag records for a list, given the context they are being applied in.
     #
-    # Override it to keep a separate vocabulary for one context by returning tags from a
-    # {MakeTaggable::Tag} subclass.
+    # Override it to resolve one context's names through a different class -- one with its own
+    # validations or callbacks, say.
+    #
+    # This routes creation only. Reading gives back whatever {MakeTaggable.tag_class} names, and
+    # without a `type` column on the tags table there is nothing to tell a subclass's rows apart, so
+    # the vocabularies are not actually separate. See `docs/contexts.md` for the column to add if
+    # that is what you are after, and {MakeTaggable.tag_class} for changing the class globally.
     #
-    # @example A separate Tag subclass for one context
+    # @example Resolving one context's names through another class
     #   class Company < ActiveRecord::Base
     #     make_taggable :markets, :locations
     #

data/lib/make_taggable/taggable.rb

@@ -82,7 +82,7 @@ module MakeTaggable
 
         class_eval do
           has_many :taggings, as: :taggable, dependent: :destroy, class_name: "::MakeTaggable::Tagging"
-          has_many :base_tags, through: :taggings, source: :tag, class_name: "::MakeTaggable::Tag"
+          has_many :base_tags, through: :taggings, source: :tag, class_name: MakeTaggable.tag_class
 
           def self.taggable?
             true

data/lib/make_taggable/tagger.rb

@@ -46,7 +46,7 @@ module MakeTaggable
             )
 
           has_many :owned_tags, -> { distinct },
-            class_name: "::MakeTaggable::Tag",
+            class_name: MakeTaggable.tag_class,
             source: :tag,
             through: :owned_taggings
         end

data/lib/make_taggable/tagging.rb

@@ -30,7 +30,7 @@ module MakeTaggable
 
     self.table_name = MakeTaggable.taggings_table
 
-    belongs_to :tag, class_name: "::MakeTaggable::Tag", counter_cache: MakeTaggable.tags_counter
+    belongs_to :tag, class_name: MakeTaggable.tag_class, counter_cache: MakeTaggable.tags_counter
     belongs_to :taggable, polymorphic: true
 
     belongs_to :tagger, polymorphic: true, optional: true

data/lib/make_taggable/version.rb

@@ -6,5 +6,5 @@ module MakeTaggable
   #
   # @return [String]
   #
-  VERSION = "1.5.0"
+  VERSION = "1.7.0"
 end

data/lib/make_taggable.rb

@@ -127,6 +127,17 @@ module MakeTaggable
     delimiter.end_with?(" ") ? delimiter : "#{delimiter} "
   end
 
+  ##
+  # The class tags are read, written and returned as.
+  #
+  # Resolved on each call rather than memoised, so a reloaded class in development is picked up.
+  #
+  # @return [Class]
+  #
+  def self.tag_model
+    tag_class.constantize
+  end
+
   ##
   # The library's settings.
   #
@@ -168,7 +179,7 @@ module MakeTaggable
       :remove_unused_tags, :default_parser,
       :tags_counter, :tags_table,
       :taggings_table
-    attr_reader :delimiter, :strict_case_match
+    attr_reader :delimiter, :strict_case_match, :tag_class
 
     ##
     # Builds the configuration with the library's defaults.
@@ -186,6 +197,29 @@ module MakeTaggable
       @force_binary_collation = false
       @tags_table = :tags
       @taggings_table = :taggings
+      @tag_class = "MakeTaggable::Tag"
+    end
+
+    ##
+    # Sets the class tags are read, written and returned as.
+    #
+    # Must be a String. A model constant cannot be referenced while initializers run -- Zeitwerk
+    # has not defined it yet, and eager loading in production would try to resolve it before the
+    # class exists.
+    #
+    # @param class_name [String] the name of a class inheriting from {MakeTaggable::Tag}
+    # @return [String]
+    # @raise [ArgumentError] when given anything but a String
+    #
+    def tag_class=(class_name)
+      unless class_name.is_a?(String)
+        raise ArgumentError,
+          "tag_class must be a String, got #{class_name.inspect}. " \
+          "Naming the class rather than the constant is what lets it be set in an initializer, " \
+          "before Zeitwerk has defined it."
+      end
+
+      @tag_class = class_name
     end
 
     ##

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: make_taggable
 version: !ruby/object:Gem::Version
-  version: 1.5.0
+  version: 1.7.0
 platform: ruby
 authors:
 - Matthew Kennedy
@@ -33,8 +33,6 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- AATO_ISSUE_TRIAGE.md
-- AATO_UPSTREAM_COMMIT_REVIEW.md
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - CONTRIBUTING.md

data/AATO_ISSUE_TRIAGE.md

@@ -1,122 +0,0 @@
-# acts-as-taggable-on open issues — applicability to MakeTaggable
-
-All 66 open issues on `mbleigh/acts-as-taggable-on` (as of 2026-08-23) checked against
-`make_taggable` at 1.1.1. Everything marked **confirmed** was reproduced by running code
-against the gem's own SQLite harness (Ruby 4.0.1 / Active Record 8.1.3); everything marked
-**static** was read out of the source. Adapter-specific reports that need MySQL/PostgreSQL
-are listed separately as unverified.
-
-Verdict counts: 29 apply, 5 apply as feature gaps, 13 do not apply, 8 unverified,
-11 documentation issues already covered.
-
----
-
-## Applies — confirmed by reproduction
-
-### Query builder
-
-| Upstream | Symptom in MakeTaggable | Evidence |
-|---|---|---|
-| #402, #993 | `tagged_with` returns a record once per matching tagging. A record tagged `"interesting"` in two contexts comes back twice. No `DISTINCT`, no context filter. | `OtherTaggableModel.tagged_with("interesting")` → 2 rows for 1 record |
-| #701 | `:exclude` ignores `:on`. `ExcludeTagsQuery#tags_not_in_list` builds no context predicate at all. | generated SQL contains no `context` clause |
-| #630 | `tagged_with([], exclude: true)` returns nothing. `core.rb` returns `none` on an empty list before the strategy is chosen, so "exclude nothing" excludes everything. | 0 rows, should be all |
-| #1094 | `tagged_with(tags, order_by_matching_tag_count: true)` raises `ActiveRecord::UnknownAttributeReference`. `AllTagsQuery#order_conditions` passes a raw subquery string to `.order`. | raises; the `any: true` path is fine because it wraps in `Arel.sql` |
-| #692, #1109, #530 | `.count` / `.size` on an `any: true` relation emits `COUNT("table".*)`, which is invalid SQL on SQLite, MySQL and PostgreSQL. Chaining two `tagged_with` calls compounds it. | `SQLite3::SQLException: near "*"` |
-| #936 | `AnyTagsQuery#build` calls `select(all_fields)`, so a caller's own `select` is appended rather than honoured. Also what breaks #395 (`merge` overwriting the SELECT). | `SELECT "taggable_models".*, "taggable_models"."id"` |
-| #915 + our own | `ExcludeTagsQuery#tags_not_in_list` hardcodes `taggable_arel_table[:id]` instead of the model's primary key. Any model with a non-`id` primary key raises on `exclude: true`. This is strictly worse than the upstream report. | `NonStandardIdTaggableModel.tagged_with(["k"], exclude: true)` → `StatementInvalid` |
-| #277, #387 | No way to order by `taggings.created_at`. `tagged_with` hides the taggings behind SHA aliases; `all_tags(order: "taggings.created_at desc")` builds a subquery that doesn't project the column. | `no such column: taggings.created_at` |
-| #293 | `tagged_with` still emits one `INNER JOIN` per tag in the default (all-tags) mode. | 12 tags → 12 joins |
-| #1028, #657 | `QueryBase#tag_match_type` wraps the column in `LOWER()` unconditionally. On PostgreSQL the operator is already `ILIKE`, so the `LOWER()` is redundant *and* defeats `index_tags_on_name`. Same cause as the #657 cache-miss report. | static + confirmed in generated SQL |
-| #328 | SQLite's `LOWER()` is ASCII-only, so `Tag.named_any` misses case variants of non-ASCII names. | `Tag.named_any(["ünicode"])` → 0 for a tag named `"Ünicode"` |
-
-### Attribute / dirty tracking
-
-| Upstream | Symptom | Evidence |
-|---|---|---|
-| #1024, #1064, #1029 | `tag_list` is declared as an `attribute`, so it appears in `as_json` (triggering a tag query per record) but reads back `nil` from `attributes`. | 19 queries to serialize 3 records; `attributes["tag_list"] == nil` |
-| #1155 | `tag_ids = []` after `as_json` silently does nothing — the tags stay attached. | tags survive the assignment |
-| #373 | `tag_list.add(...)` / `.remove(...)` mutate the array in place without `attribute_will_change!`, so `tag_list_changed?` stays false. Only whole-list assignment is tracked. | `false` after `.add("sfw")` |
-| #1047 | `TagList#remove` compares raw objects, so `remove(:foo)` is a no-op while `remove("foo")` works. | list unchanged |
-| #1139 | `TagList` carries `@parser`, which holds a *Class*. `Psych.safe_dump` refuses it, so anything serialising a taggable to YAML (audited, ActiveJob args) blows up. | `Psych::DisallowedClass: Tried to dump unspecified class: Class` |
-
-### Saving
-
-| Upstream | Symptom | Evidence |
-|---|---|---|
-| #1176 | `strict_loading` is violated on save. `save_tags` → `tagging_contexts` → `custom_contexts` lazily loads `taggings`. | `StrictLoadingViolationError` on saving a persisted record |
-| #1128 | The same path means every save — even a no-op — issues tagging queries. | 3 queries on a save with no changes |
-| #665 | A tag over 255 characters fails `Tag`'s length validation, `create` returns it unsaved, and the taggable then fails with a misleading `Validation failed: Tag can't be blank`. | raises `RecordInvalid` |
-| #508 | `Tag.find_or_create_all_with_like_by_name` uses non-bang `create`, so validation errors added by a `Tag` subclass are swallowed and surface later as the wrong error. | static |
-| #947 | `save_tags` and `save_owned_tags` create taggings in list order, so two concurrent saves touching the same tags can deadlock on the `taggings_count` counter cache. Sorting `new_tags` by id would fix it. | static |
-| #290 | `preserve_tag_order` is one `class_attribute` for the whole model, so `make_taggable` and `make_ordered_taggable` in the same class clobber each other — the last call wins for every context. | `make_taggable :skills` + `make_ordered_taggable :books` → `preserve_tag_order?` is `true` for `:skills` |
-| #1044 | A context whose name starts with a digit raises a **`SyntaxError`** while the class body loads (we generate `def 1category_taggings`). Upstream only got an invalid-ivar error, so ours fails harder. | `SyntaxError` from `has_many` |
-
-### Ownership and caching
-
-| Upstream | Symptom | Evidence |
-|---|---|---|
-| #233 | `Tagger#tag` does not refresh `cached_<context>_list`. `save_cached_tag_list` only mirrors unowned lists, so a cached column silently drifts from `all_tags_list`. | `cached_tag_list` stayed `nil` while `all_tags_list == ["owned"]` |
-| #571 | `Tagger#tag` always parses `:with` through the default parser. There is no `parse: false`, so a tag legitimately containing a comma is split into two. | `with: ["a, b"]` → `["a", "b"]` |
-
-### Configuration
-
-| Upstream | Symptom | Evidence |
-|---|---|---|
-| #781, #945 | `force_binary_collation=` still issues an `ALTER TABLE` every time it's called. Set in an initializer, that runs on every boot — including every Sidekiq/cron process — and takes a metadata lock on the tags table. | `apply_binary_collation` still calls `ActiveRecord::Migration.execute` |
-| #769 | `force_parameterize` maps tags through `String#parameterize`, which reduces a fully non-ASCII tag to the empty string and `clean!` then drops it. | `["日本語", "ok tag"]` → `["ok-tag"]` |
-
-## Applies — feature gaps rather than bugs
-
-| Upstream | Gap |
-|---|---|
-| #91 | No eager-loading path for tag lists. `includes(:tags)` doesn't stop `tag_list` re-querying (13 queries for 5 records). |
-| #804 | `tagged_with(tags, on: [:skills, :interests])` raises `TypeError: can't quote Array`. Only one context per call. |
-| #783 | The `Tag` class is hardcoded. `find_or_create_tags_from_list_with_context` lets you create subclass rows, but the associations still return `MakeTaggable::Tag`. |
-| #909 | `all_tags` / `all_tag_counts` accept no scope on the taggable's own attributes (`assert_valid_keys` rejects `:scope`). |
-| #698 | The generated migration has no `type:` on the polymorphic references, so a UUID-keyed taggable needs the migration edited by hand. Not documented. |
-
-## Does not apply
-
-| Upstream | Why |
-|---|---|
-| #908, #914 | `Model.create!(tags: [tag])` works — the tagging saves with the default context. |
-| #1151 | Repeated single-context `make_taggable` calls define `<context>_from` correctly; `Ownership.included` re-runs on every call. |
-| #576 | Adding a tag in a second context does not delete the first context's taggings. |
-| #867 | Chaining `tagged_with` with the same tag produces one join — Active Record dedupes the identical alias. |
-| #1033 | `tagged_with(..., exclude: true)` returns the same result on a relation as on the class. |
-| #946 | `remove_unused_tags` behaves as documented; re-tagging after a removal works. |
-| #1023 | Ordered taggable + owner works. Our `order` argument is a bare `taggings.id`, which Active Record accepts. |
-| #1099 | `upsert_all` on a taggable model works. |
-| #395 | The `merge` symptom is #936's `select(all_fields)`, already listed. Not separately actionable. |
-| #300 (part) | `find_related_*.blank?` works; only `.count` is broken (listed as #300/#907). |
-| #455, #603 | Caching is documented — `docs/caching.md`. |
-| #848 | The array form of the strong parameter is documented in `docs/getting-started.md`. |
-| #981 | Docs already use `rails make_taggable_engine:install:migrations`, not `rake`. |
-| #885 | `docs/ownership.md` builds owned lists from `locations_from(user)`, not `all_tags_list`, so the cascade the issue describes can't happen. |
-| #754 | `tagged_with` parsing its argument is documented on the method. |
-
-## Unverified — needs a PostgreSQL or MySQL run
-
-| Upstream | What to check |
-|---|---|
-| #852 | `tag_counts_on` on a relation built with `includes(...).where(other_table: ...)` → "subquery has too many columns". Our `generate_tagging_scope_in_clause` does `except(:select).select(pkey)`, which may already fix it. |
-| #1026 | `find_related_*` groups by every column on PostgreSQL; a `json` column has no equality operator and breaks `GROUP BY`. `Related#group_columns` still does this. |
-| #1069 | Ambiguous column on `.count` with a joined scope. Did not reproduce on SQLite. |
-| #1100 | "no implicit conversion of nil into String" on update — no reproduction in the issue. |
-| #1103 | Ownership with `acts_as_tenant`: owned taggings created through `taggings.create!` and destroyed through a bare `Tagging.where(...)` may bypass the tenant scope. |
-| #810 | Ordering against `acts_as_nested_set` — depends on callback order in the host app. |
-| #657 | The PostgreSQL index-miss half of #1028; needs an `EXPLAIN` on a real table. |
-| #915 | The integer-vs-varchar join half (separate from the primary-key bug above). |
-
----
-
-## Suggested order of work
-
-1. **#1044** — a `SyntaxError` at class-load time. Cheapest fix (validate the context name, or reject it with a clear error) and the worst failure mode.
-2. **#915/exclude** — `ExcludeTagsQuery` hardcoding `:id`. One-line fix, silently wrong today.
-3. **#701, #630** — `:exclude` ignoring context and the empty-list short circuit. Both are wrong *answers*, not errors.
-4. **#402/#993** — duplicate rows from `tagged_with`. Needs a decision on `DISTINCT` vs. a subquery.
-5. **#692/#1109/#530, #936, #1094** — the `AnyTagsQuery` select and the `AllTagsQuery` order. `.count` not working on a documented query option is a hard edge.
-6. **#1139, #1047, #373** — small, self-contained `TagList` fixes.
-7. **#1176, #1128** — stop `save_tags` loading `taggings` when nothing was assigned.
-8. **#1024/#1064/#1029, #1155** — the `attribute :tag_list` design. The largest change; worth its own discussion.

data/AATO_UPSTREAM_COMMIT_REVIEW.md

@@ -1,74 +0,0 @@
-# Upstream commits since the fork point — what's worth pulling
-
-## Fork point
-
-`make_taggable`'s history starts at a squashed "Initial commit" (7698fe0, 2020-11-16) with no
-shared ancestry, so the base had to be recovered by matching blobs. The fork's initial tree is
-**upstream v6.5.0** (`6b38c652`, 2019-10-29) — 62 of 75 Ruby/Markdown files match that tree
-exactly, and the bundled `CHANGELOG.md` stops at the v6.5.0 release notes.
-
-Since then upstream has 93 commits (v7.0.0 → v13.0.0), of which **39 touch `lib/` or `db/`**.
-Everything below is that 39, reviewed one by one.
-
-## The important negative result
-
-**Upstream has not fixed any of the 29 confirmed bugs from the issue triage.** I checked HEAD
-(`4d58c53`) directly:
-
-- `ExcludeTagsQuery#tags_not_in_list` still hardcodes `taggable_arel_table[:id]`
-- `AnyTagsQuery#build` still calls `select(all_fields)`
-- `AllTagsQuery#order_conditions` still passes a raw string to `.order` without `Arel.sql`
-
-So there is no shortcut: that backlog is ours to fix either way. What upstream *does* have that we
-don't is a handful of small correctness fixes and three features.
-
----
-
-## Worth pulling — correctness
-
-| Upstream | What it fixes | Status here |
-|---|---|---|
-| **12f08be** (#1081, v10) | `find_or_create_all_with_like_by_name` issues a raw `ActiveRecord::Base.connection.execute "ROLLBACK"` when it hits `RecordNotUnique`. That breaks any enclosing transaction and ignores multiple-database setups. Upstream replaced it with `transaction(requires_new: true) { create(...) }`. | **We still have the raw ROLLBACK.** Highest-value pull on this list — it corrupts caller transactions, and our own spec suite runs inside a transaction. |
-| **426d960 + a0cadfb** | `remove_unused_tags` handling when the counter cache is off, and avoiding a needless `tag.reload`. | **Ours is worse than upstream's pre-fix state.** `MakeTaggable.remove_unused_tags` is gated on `&& MakeTaggable.tags_counter`, so with `tags_counter = false` the setting silently does nothing. Verified: orphan tag survives. This is upstream issue #946 arriving by a different route. |
-| **2a8acc1** (#1065) | `using_postgresql?` matches only `"PostgreSQL"`, so the PostGIS adapter falls through to the MySQL/generic path — `LIKE` instead of `ILIKE`, and the wrong `GROUP BY` strategy. | Absent. One-line fix: `%w[PostgreSQL PostGIS].include?(adapter_name)`. |
-| **38fb4d2 / b915ca8** | `Utils.connection` uses the model-level `.connection`, soft-deprecated in Rails 7.2 in favour of `lease_connection`. | Absent. Worth taking since our floor is already AR 7.2 — go straight to `lease_connection`, no fallback branch needed. Note: I did **not** observe an actual deprecation warning on AR 8.1.3, so this is hygiene, not breakage. |
-| **1df5ac3** | Upstream dropped four single-column indexes on `taggings` as redundant against the composite ones. | **Applies, and ours is worse.** Our migrations produce **12 indexes** on `taggings`. At least five are dead weight: `tag_id` (prefix of `taggings_idx`), `taggable_id` (prefix of `taggings_taggable_context_idx`), `taggable_type`, `tagger_id` (prefix of the tagger pair), and we create the tagger pair **in both column orders** (`index_taggings_on_tagger_id_and_tagger_type` *and* `index_taggings_on_tagger_type_and_tagger_id`, the latter from `t.references`). Every tagging insert pays for all of them. |
-
-## Worth pulling — features
-
-| Upstream | Feature | Note |
-|---|---|---|
-| **2014fcc** (#1082, v10) | `wild: :prefix` / `wild: :suffix` in addition to `wild: true`. | Small and self-contained, and it partly answers issue #1028: a suffix match (`foo%`) can use a plain btree index, where `%foo%` never can. |
-| **52d7dae** (#1053, v9) | `all_tag_counts(id: [...])` accepts an array of taggable ids, not just one. | Lets a caller compute tag counts for a page of records in one query instead of N. Cheap to take. |
-| **b4eed9b + 8ba7fee** (v9/v10) | A `base_class` config so `Tag` and `Tagging` inherit from the host's `ApplicationRecord` instead of `::ActiveRecord::Base` — needed for horizontally sharded / multi-database apps. 8ba7fee then changed it to a **String** because Zeitwerk won't let you reference a model constant at initializer time. | If we take this, take both commits: the String form is the correct one. Also relevant to issue #1103 (ownership + tenancy). |
-| **7e696e3 + 4a7948e + e2d211b + 5d86cce** (v8) | A `tenant` column on `taggings`, `acts_as_taggable_tenant`, `Tag.for_tenant`, `Tagging.by_tenant`. | The largest item here — a migration plus API surface. Directly addresses issue #1103. I'd treat this as a "do we want it?" product decision rather than a pull; it overlaps with what `acts_as_tenant` already does in the host app. |
-
-## Not worth pulling
-
-| Upstream | Why not |
-|---|---|
-| **47da503** (case-sensitivity third arg to `matches`) | **Already present.** Our `query_base.rb` passes `MakeTaggable.strict_case_match`. |
-| **b54771d** (`force_encoding('BINARY')` removal) | **Already present** — we fixed this independently in 1.0.0 and the CHANGELOG records it. |
-| **f18679a** (drop `mb_chars` / `unicode_downcase`) | **Already present** — our `Tag` uses `name.to_s.downcase`. |
-| **31f29c9** (caching always on) | This deletes the lazy `columns` interception that upstream themselves added in PR #911 to avoid clobbering a host's own `columns` override. Our `Cache::Columns` is the better design and we have a spec for it (`ColumnsOverrideModel`). Taking this would be a regression. |
-| **93fd6d2, a54cc54, bdb86da** (v11 `ActiveSupport::Concern` / Zeitwerk refactors) | Pure restructuring of code we have already restructured differently in 1.0.0. No behaviour change. |
-| **380c0bc** (combine migrations into one) | Upstream folded migrations 1–7 into a single idempotent `SetupActsAsTaggableOn`. Tempting, but our six-migration chain is already published and 1.1.0 just added migration 6 — collapsing them now would break `install:migrations` for existing installs for no functional gain. Take the *index trimming* from 1df5ac3 without the consolidation. |
-| **89a4d7f, 37bfebc, 4c49575, cfd6e06, 866c38f, 46c4e2d, f7bfad9, 69e6bff, b1d7651, 6fa6b55, 8548529, e0f859e, 6fbd9d1, b7122b9, 25266d6, 954e7ce** | Release commits, CI/docker chores, formatting, Ruby 2.7 / Rails 6.1 / Rails 8 compatibility we already exceed, and migration-syntax cleanups against migration files we don't share. |
-
----
-
-## Recommendation
-
-Four small commits are worth taking more or less as-is, and they're cheap:
-
-1. **12f08be** — the raw `ROLLBACK` (correctness, affects callers' transactions)
-2. **remove_unused_tags with `tags_counter = false`** (our own regression, upstream-adjacent)
-3. **2a8acc1** — PostGIS adapter detection
-4. **1df5ac3-style index trim** — but sized to our 12-index reality, as a *new* migration 7 that drops the redundant ones rather than by editing migration 5
-
-Then **2014fcc** (`wild: :prefix`/`:suffix`) and **52d7dae** (array `:id`) as easy feature wins.
-
-`base_class` and the tenant feature are both real decisions rather than pulls — worth discussing
-before either lands.
-
-None of this changes the issue triage: the 29 confirmed bugs have no upstream fix to inherit.