make_taggable 1.2.0 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7988c41c462a75321cf31cb13888a01d87a4dec964b13d2bb8c94876d7291d2a
-  data.tar.gz: 76c39347c15e44dd9bad00317aa4e27f4ef58aadd638507340a74fe6bd5bbbd3
+  metadata.gz: 7b11d21dbd46411b5b827d1b70cb44bcb641259804a32fa221597e56e02aa906
+  data.tar.gz: 3ebf2e595313e19cc88e28ab7541c40bae5fd1c702a09b8f60873fb68605bfcd
 SHA512:
-  metadata.gz: 89496e3b067d1c4707580b30b4ad1a1be0701e8aa03f1e7de30d2c229b4eec96afd82eec4675e89c32cf5e8f0b3ccf28d7afb0ffcf4a7ada5b9ef2169232dcc2
-  data.tar.gz: bbeef557e819249bc1d13668ec6437401dfcfbe3d995874535c86d5b86747ff46d5e0bb3383905343057c2f773c0658766eed9580f6173789e288571a516f0bb
+  metadata.gz: 543f460b5117fd847d6f2ed9a7bc694aece6306b3268912710c058cf6bb48275932d1a06ee0adf867492c175ca858cf84794db4238e52b8bad4f2f8ff71fdbc2
+  data.tar.gz: 9983b5c3084235e612097a52bda93c4bd48799e4c29a8c30b354d2ad8d24bc07db2ec99d4077956e193dfa5c175e21198f3238d912882a7015887d72438ea1a2

data/CHANGELOG.md

@@ -5,6 +5,65 @@ 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.3.0] - 2026-08-23
+
+### Changed
+
+- **`tagged_with` no longer joins the taggings table.** It tests for each tag with an `EXISTS`
+  subquery instead, which is what stops a record being returned once per matching tagging. A tag
+  applied in two contexts, or a `:wild` pattern matching two of a record's tags, returned that
+  record twice; `.count` disagreed with the number of records, and pagination pages ran short.
+
+  The consequence for callers is that a `taggings` column is no longer in scope on the relation, so
+  `tagged_with("x").order("taggings.created_at")` or a `group` on a taggings column now needs an
+  explicit `.joins(:taggings)`. See [docs/querying.md](docs/querying.md).
+
+  Matching a dozen tags now produces a dozen correlated subqueries rather than a dozen joins.
+  `:match_all` is unchanged and keeps its join.
+
+### Fixed
+
+- `tagged_with(..., any: true)` forced `SELECT taggable_models.*` onto the relation. That made
+  `.count` emit `COUNT("table".*)`, which no adapter accepts, and left a caller's own `select`
+  appended after the star rather than replacing it -- so every column came back regardless, and the
+  relation could not be used inside a `merge`. The strategy filters with an `EXISTS` subquery and
+  joins nothing, so Active Record's default select list was already right.
+
+- `:order_by_matching_tag_count` raised on the default all-tags path, and the expression behind it
+  was invalid SQL that would have ordered nothing even where it parsed. Both strategies now share
+  the correlated count the `:any` path has always used, so the option orders correctly on either.
+  It still has no effect alongside `:match_all`.
+
+- `tagged_with(..., exclude: true)` ignored `:start_at` and `:end_at`, excluding records on the
+  strength of taggings from outside the window entirely.
+
+## [1.2.1] - 2026-08-23
+
+### Fixed
+
+- `tagged_with(..., exclude: true)` raised on any model whose primary key is not `id`. The exclude
+  strategy built its `NOT IN` predicate against a hardcoded `id` column, where the other two
+  strategies already used the model's primary key.
+
+- `tagged_with(..., on: <context>, exclude: true)` ignored the context entirely, gathering taggings
+  from every context, so a record tagged in one context was excluded from a query about another.
+
+- `tagged_with([], exclude: true)` returned nothing rather than everything. Excluding no tags rules
+  nothing out, so the whole scope now stands. This restores the property that `tagged_with(list)`
+  and `tagged_with(list, exclude: true)` partition the scope between them for any list.
+
+- A tag context whose name cannot become a Ruby method name -- one starting with a digit, say --
+  raised `SyntaxError` while the model was loading, from inside Active Record's association
+  builder. Since `SyntaxError` is not a `StandardError` it slipped past application rescues.
+  Contexts are now checked as they are declared and rejected with an `ArgumentError` naming the
+  context. Non-ASCII context names keep working.
+
+### Internal
+
+- The suite's schema teardown no longer depends on the order `connection.tables` returns. MySQL
+  ignores `DROP TABLE ... CASCADE` for foreign keys, so it only worked because `taggings` happens
+  to sort before `tags`.
+
 ## [1.2.0] - 2026-08-23
 
 ### Fixed

data/docs/contexts.md

@@ -40,6 +40,23 @@ user.skill_list_change            # => [["jogging"], ["diving"]]
 user.will_save_change_to_skill_list?
 ```
 
+### Naming a context
+
+Because the context becomes part of every name in the table above, it has to be usable as a Ruby
+method and instance variable name. A context starting with a digit, or containing a hyphen or a
+space, is rejected when the model declares it:
+
+```ruby
+class Book < ActiveRecord::Base
+  make_taggable :"1categories"
+end
+# => ArgumentError: :"1categories" cannot be used as a tag context: make_taggable generates
+#    methods and instance variables from it, and "1categories_list" is not a valid Ruby name.
+```
+
+Validity is decided by asking Ruby, not by a pattern, so anything that makes a legal method name is
+allowed — non-ASCII context names included.
+
 ## Adding contexts later
 
 Calling `make_taggable` again adds contexts rather than replacing them, which is what lets a

data/docs/querying.md

@@ -28,11 +28,19 @@ empty relation rather than every record — worth knowing when the tags come fro
 | `:exclude` | Match records carrying none of the tags |
 | `:match_all` | Match records carrying only these tags and no others |
 | `:wild` | Match tags *containing* the given text, i.e. `%sci%` |
-| `:on` | Restrict to one context |
+| `:on` | Restrict to one context. Honoured by every option, `:exclude` included |
 | `:owned_by` | Restrict to tags applied by one tagger |
-| `:order_by_matching_tag_count` | With `:any`, order by how many tags matched, most first |
-| `:start_at` | Only tags applied after this time |
-| `:end_at` | Only tags applied before this time |
+| `:order_by_matching_tag_count` | Order by how many matching taggings a record has, most first. No effect with `:match_all` |
+| `:start_at` | Only tags applied after this time. Honoured by every option, `:exclude` included |
+| `:end_at` | Only tags applied before this time. Honoured by every option, `:exclude` included |
+
+An empty tag list means "nothing matches" for the matching options and "nothing is ruled out" for
+`:exclude`, so the two always partition the scope between them:
+
+```ruby
+Book.tagged_with([])                  # => none
+Book.tagged_with([], exclude: true)   # => every book
+```
 
 `:wild` combines with `:any` or `:exclude`:
 
@@ -154,10 +162,25 @@ 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.
 
+## Grouping and ordering by tagging columns
+
+`tagged_with` does not join the taggings table, so a `taggings` column is not in scope on the
+relation it returns. Join it yourself when you need one:
+
+```ruby
+Book.tagged_with("sci-fi").joins(:taggings).group("taggings.context").count
+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.
+
 ## Performance notes
 
-- `tagged_with` with several tags and no `:any` adds one join per tag. Matching a dozen tags in a
-  single call generates a dozen joins; prefer `any: true` where the semantics allow it.
+- `tagged_with` tests for each tag with an `EXISTS` subquery, one per tag, and joins nothing. That
+  is what stops a record being returned once per matching tagging. Matching a dozen tags produces a
+  dozen correlated subqueries rather than a dozen joins, which most planners handle better, but it
+  is still worth reaching for `any: true` where the semantics allow it.
 - `:order_by_matching_tag_count` adds a correlated subquery to the `ORDER BY`. It is fine for a
   page of results and expensive across a whole table.
 - `all_tag_counts` joins the taggables to count them. Reach for `all_tags` when the counts are not

data/lib/make_taggable/taggable/core.rb

@@ -123,13 +123,14 @@ module MakeTaggable::Taggable
       # @option options [TrueClass, FalseClass] :exclude match records carrying none of the tags
       # @option options [TrueClass, FalseClass] :match_all match records carrying only these tags
       # @option options [TrueClass, FalseClass] :wild match tags containing the given text
-      # @option options [TrueClass, FalseClass] :order_by_matching_tag_count with `:any`, order by
-      #   how many tags matched, most first
+      # @option options [TrueClass, FalseClass] :order_by_matching_tag_count order by how many
+      #   matching taggings a record has, most first. No effect alongside `:match_all`
       # @option options [ActiveRecord::Base] :owned_by only tags applied by this tagger
       # @option options [Symbol, String] :on only tags applied in this context
       # @option options [Time, Date] :start_at only tags applied after this time
       # @option options [Time, Date] :end_at only tags applied before this time
-      # @return [ActiveRecord::Relation] empty when no tags are given
+      # @return [ActiveRecord::Relation] empty when no tags are given, except under `:exclude`,
+      #   where excluding no tags leaves the whole scope standing
       #
       # @example Every tag
       #   User.tagged_with(["awesome", "cool"])
@@ -144,7 +145,9 @@ module MakeTaggable::Taggable
         tag_list = MakeTaggable.default_parser.new(tags).parse
         options = options.dup
 
-        return none if tag_list.empty?
+        # Asking for no tags matches nothing, but *excluding* no tags rules
+        # nothing out, so the whole scope stands.
+        return options[:exclude].present? ? all : none if tag_list.empty?
 
         ::MakeTaggable::Taggable::TaggedWithQuery.build(self, MakeTaggable::Tag, MakeTaggable::Tagging, tag_list, options)
       end

data/lib/make_taggable/taggable/tagged_with_query/all_tags_query.rb

@@ -11,63 +11,72 @@ module MakeTaggable::Taggable::TaggedWithQuery
     # @return [ActiveRecord::Relation]
     #
     def build
-      taggable_model.joins(each_tag_in_list)
+      taggable_model.joins(match_all_join)
+        .where(carries_every_tag)
         .group(by_taggable)
         .having(tags_that_matches_count)
-        .order(order_conditions)
+        .order(Arel.sql(order_conditions))
         .readonly(false)
     end
 
     private
 
-    def each_tag_in_list
-      arel_join = taggable_arel_table
-
-      tag_list.each do |tag|
-        tagging_alias = tagging_arel_table.alias(tagging_alias(tag))
-        arel_join = arel_join
-          .join(tagging_alias)
-          .on(on_conditions(tag, tagging_alias))
-      end
-
-      if options[:match_all].present?
-        arel_join = arel_join
-          .join(tagging_arel_table, Arel::Nodes::OuterJoin)
-          .on(
-            match_all_on_conditions
-          )
-      end
+    # One EXISTS test per tag, rather than one join per tag.
+    #
+    # A join multiplies the result: a record is returned once for every tagging
+    # that satisfies it, so a tag applied in two contexts, or a wild pattern
+    # matching two of a record's tags, returned that record twice. EXISTS asks
+    # the question the query is actually asking -- does this record carry the
+    # tag -- and answers it once.
+    def carries_every_tag
+      tag_list.map { |tag| taggings_for(tag).exists }.inject(:and)
+    end
 
-      arel_join.join_sources
+    def taggings_for(tag)
+      tagging_arel_table
+        .project(Arel.star)
+        .where(tag_conditions(tag))
     end
 
-    def on_conditions(tag, tagging_alias)
-      on_condition = tagging_alias[:taggable_id].eq(taggable_arel_table[taggable_model.primary_key])
-        .and(tagging_alias[:taggable_type].eq(taggable_model.base_class.name))
+    def tag_conditions(tag)
+      condition = tagging_arel_table[:taggable_id].eq(taggable_arel_table[taggable_model.primary_key])
+        .and(tagging_arel_table[:taggable_type].eq(taggable_model.base_class.name))
         .and(
-          tagging_alias[:tag_id].in(
+          tagging_arel_table[:tag_id].in(
             tag_arel_table.project(tag_arel_table[:id]).where(tag_match_type(tag))
           )
         )
 
       if options[:start_at].present?
-        on_condition = on_condition.and(tagging_alias[:created_at].gteq(options[:start_at]))
+        condition = condition.and(tagging_arel_table[:created_at].gteq(options[:start_at]))
       end
 
       if options[:end_at].present?
-        on_condition = on_condition.and(tagging_alias[:created_at].lteq(options[:end_at]))
+        condition = condition.and(tagging_arel_table[:created_at].lteq(options[:end_at]))
       end
 
       if options[:on].present?
-        on_condition = on_condition.and(tagging_alias[:context].eq(options[:on]))
+        condition = condition.and(tagging_arel_table[:context].eq(options[:on]))
       end
 
       if (owner = options[:owned_by]).present?
-        on_condition = on_condition.and(tagging_alias[:tagger_id].eq(owner.id))
-          .and(tagging_alias[:tagger_type].eq(owner.class.base_class.to_s))
+        condition = condition.and(tagging_arel_table[:tagger_id].eq(owner.id))
+          .and(tagging_arel_table[:tagger_type].eq(owner.class.base_class.to_s))
       end
 
-      on_condition
+      condition
+    end
+
+    # :match_all keeps its outer join. It counts a record's taggings and compares
+    # that to the number of tags matched, so it needs them joined -- and the
+    # GROUP BY it already carries collapses the duplicates a join would cause.
+    def match_all_join
+      return [] unless options[:match_all].present?
+
+      taggable_arel_table
+        .join(tagging_arel_table, Arel::Nodes::OuterJoin)
+        .on(match_all_on_conditions)
+        .join_sources
     end
 
     def match_all_on_conditions
@@ -107,15 +116,17 @@ module MakeTaggable::Taggable::TaggedWithQuery
 
     def order_conditions
       order_by = []
-      order_by << tagging_arel_table.project(tagging_arel_table[Arel.star].count.as("taggings_count")).order("taggings_count DESC").to_sql if options[:order_by_matching_tag_count].present? && options[:match_all].blank?
+
+      # The old expression here counted every tagging in the table, correlated
+      # to nothing, and asked for COUNT(taggings.*) while doing it -- invalid
+      # SQL that ordered nothing even where it parsed. The shared correlated
+      # count is what the :any strategy has always used.
+      if options[:order_by_matching_tag_count].present? && options[:match_all].blank?
+        order_by << matching_tag_count_order
+      end
 
       order_by << options[:order] if options[:order].present?
       order_by.join(", ")
     end
-
-    def tagging_alias(tag)
-      alias_base_name = taggable_model.base_class.name.downcase
-      adjust_taggings_alias("#{alias_base_name[0..11]}_taggings_#{MakeTaggable::Utils.sha_prefix(tag)}")
-    end
   end
 end

data/lib/make_taggable/taggable/tagged_with_query/any_tags_query.rb

@@ -11,55 +11,26 @@ module MakeTaggable::Taggable::TaggedWithQuery
     # @return [ActiveRecord::Relation]
     #
     def build
-      taggable_model.select(all_fields)
-        .where(model_has_at_least_one_tag)
+      # No select of our own. This strategy filters with an EXISTS subquery and
+      # joins nothing, so Active Record's default select list is already right.
+      # Forcing `taggable_models.*` made COUNT() invalid and left a caller's own
+      # select appended after the star rather than replacing it.
+      taggable_model
+        .where(model_has_matching_taggings)
         .order(Arel.sql(order_conditions))
         .readonly(false)
     end
 
     private
 
-    def all_fields
-      taggable_arel_table[Arel.star]
-    end
-
-    def model_has_at_least_one_tag
-      tagging_arel_table.project(Arel.star).where(at_least_one_tag).exists
-    end
-
-    def at_least_one_tag
-      exists_contition = tagging_arel_table[:taggable_id].eq(taggable_arel_table[taggable_model.primary_key])
-        .and(tagging_arel_table[:taggable_type].eq(taggable_model.base_class.name))
-        .and(
-          tagging_arel_table[:tag_id].in(
-            tag_arel_table.project(tag_arel_table[:id]).where(tags_match_type)
-          )
-        )
-
-      if options[:start_at].present?
-        exists_contition = exists_contition.and(tagging_arel_table[:created_at].gteq(options[:start_at]))
-      end
-
-      if options[:end_at].present?
-        exists_contition = exists_contition.and(tagging_arel_table[:created_at].lteq(options[:end_at]))
-      end
-
-      if options[:on].present?
-        exists_contition = exists_contition.and(tagging_arel_table[:context].eq(options[:on]))
-      end
-
-      if (owner = options[:owned_by]).present?
-        exists_contition = exists_contition.and(tagging_arel_table[:tagger_id].eq(owner.id))
-          .and(tagging_arel_table[:tagger_type].eq(owner.class.base_class.to_s))
-      end
-
-      exists_contition
+    def model_has_matching_taggings
+      tagging_arel_table.project(Arel.star).where(matching_taggings).exists
     end
 
     def order_conditions
       order_by = []
       if options[:order_by_matching_tag_count].present?
-        order_by << "(SELECT count(*) FROM #{tagging_model.table_name} WHERE #{at_least_one_tag.to_sql}) desc"
+        order_by << matching_tag_count_order
       end
 
       order_by << options[:order] if options[:order].present?

data/lib/make_taggable/taggable/tagged_with_query/exclude_tags_query.rb

@@ -20,18 +20,31 @@ module MakeTaggable::Taggable::TaggedWithQuery
     private
 
     def tags_not_in_list
-      taggable_arel_table[:id].not_in(
+      on_condition = tagging_arel_table[:tag_id].eq(tag_arel_table[:id])
+        .and(tagging_arel_table[:taggable_type].eq(taggable_model.base_class.name))
+        .and(tags_match_type)
+
+      # Every option below narrows which taggings count as "carrying the tag".
+      # Left off, the subquery gathers taggings from other contexts and other
+      # times, and excludes records on the strength of them.
+      if options[:on].present?
+        on_condition = on_condition.and(tagging_arel_table[:context].eq(options[:on]))
+      end
+
+      if options[:start_at].present?
+        on_condition = on_condition.and(tagging_arel_table[:created_at].gteq(options[:start_at]))
+      end
+
+      if options[:end_at].present?
+        on_condition = on_condition.and(tagging_arel_table[:created_at].lteq(options[:end_at]))
+      end
+
+      taggable_arel_table[taggable_model.primary_key].not_in(
         tagging_arel_table
           .project(tagging_arel_table[:taggable_id])
           .join(tag_arel_table)
-          .on(
-            tagging_arel_table[:tag_id].eq(tag_arel_table[:id])
-            .and(tagging_arel_table[:taggable_type].eq(taggable_model.base_class.name))
-            .and(tags_match_type)
-          )
+          .on(on_condition)
       )
-
-      # FIXME: missing time scope, this is also missing in the original implementation
     end
 
     def owning_to_tagger

data/lib/make_taggable/taggable/tagged_with_query/query_base.rb

@@ -61,6 +61,46 @@ module MakeTaggable::Taggable::TaggedWithQuery
       end
     end
 
+    # A condition selecting the taggings that tie a row of the taggable table to
+    # one of the tags being matched, narrowed by whichever of :on, :owned_by,
+    # :start_at and :end_at were given.
+    #
+    # It correlates to the taggable table, so it only means anything inside a
+    # subquery -- an EXISTS test, or a COUNT used for ordering.
+    def matching_taggings
+      condition = tagging_arel_table[:taggable_id].eq(taggable_arel_table[taggable_model.primary_key])
+        .and(tagging_arel_table[:taggable_type].eq(taggable_model.base_class.name))
+        .and(
+          tagging_arel_table[:tag_id].in(
+            tag_arel_table.project(tag_arel_table[:id]).where(tags_match_type)
+          )
+        )
+
+      if options[:start_at].present?
+        condition = condition.and(tagging_arel_table[:created_at].gteq(options[:start_at]))
+      end
+
+      if options[:end_at].present?
+        condition = condition.and(tagging_arel_table[:created_at].lteq(options[:end_at]))
+      end
+
+      if options[:on].present?
+        condition = condition.and(tagging_arel_table[:context].eq(options[:on]))
+      end
+
+      if (owner = options[:owned_by]).present?
+        condition = condition.and(tagging_arel_table[:tagger_id].eq(owner.id))
+          .and(tagging_arel_table[:tagger_type].eq(owner.class.base_class.to_s))
+      end
+
+      condition
+    end
+
+    # Orders by how many of the matched taggings a row has, most first.
+    def matching_tag_count_order
+      "(SELECT count(*) FROM #{tagging_model.table_name} WHERE #{matching_taggings.to_sql}) desc"
+    end
+
     def escaped_tag(tag)
       tag = tag.downcase unless MakeTaggable.strict_case_match
       MakeTaggable::Utils.escape_like(tag)

data/lib/make_taggable/taggable.rb

@@ -69,6 +69,7 @@ module MakeTaggable
     #
     def taggable_on(preserve_tag_order, *tag_types)
       tag_types = tag_types.to_a.flatten.compact.map(&:to_sym)
+      tag_types.each { |tag_type| validate_tag_context!(tag_type) }
 
       if taggable?
         self.tag_types = (self.tag_types + tag_types).uniq
@@ -97,5 +98,31 @@ module MakeTaggable
       include Ownership
       include Related
     end
+
+    # Rejects a context that cannot become the methods and instance variables the
+    # library generates from it.
+    #
+    # A context is interpolated straight into generated source -- `#{context}_list`,
+    # `#{context}_taggings`, `@#{context}_list`. A name that is not a valid identifier
+    # produces source Ruby cannot parse, and the resulting SyntaxError descends from
+    # ScriptError rather than StandardError, so it slips past an application's own
+    # rescue and takes the boot down pointing at Active Record's association builder
+    # rather than at the offending declaration.
+    #
+    # Validity is decided by asking Ruby rather than by pattern, so a context is
+    # accepted on exactly the terms the generated code needs -- non-ASCII names
+    # included, since those make perfectly good method names.
+    #
+    # @param tag_type [Symbol] the context being declared
+    # @return [void]
+    # @raise [ArgumentError] when the context cannot become an identifier
+    def validate_tag_context!(tag_type)
+      Object.new.instance_variable_defined?(:"@#{tag_type}_list")
+    rescue NameError
+      raise ArgumentError,
+        "#{tag_type.inspect} cannot be used as a tag context: " \
+        "make_taggable generates methods and instance variables from it, and " \
+        "\"#{tag_type}_list\" is not a valid Ruby name."
+    end
   end
 end

data/lib/make_taggable/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: make_taggable
 version: !ruby/object:Gem::Version
-  version: 1.2.0
+  version: 1.3.0
 platform: ruby
 authors:
 - Matthew Kennedy