metka 2.3.4 → 3.0.1

data/lib/metka/model.rb

@@ -1,88 +1,167 @@
 # frozen_string_literal: true
 
-require 'arel'
+require "arel"
 
 module Metka
-  OR = Arel::Nodes::Or
-  AND = Arel::Nodes::And
-
   def self.Model(column: nil, columns: nil, **options)
-    columns = [column, *columns].uniq.compact
-    raise ArgumentError, 'Columns not specified' unless columns.present?
+    columns = [ column, *columns ].uniq.compact
+    raise ArgumentError, "Columns not specified" unless columns.present?
 
     Metka::Model.new(columns: columns, **options)
   end
 
   class Model < Module
+    TAGGED_WITH_OPTIONS = %i[any exclude join_operator on].freeze
+
     def initialize(columns:, **options)
       @columns = columns.dup.freeze
       @options = options.dup.freeze
+
+      unknown = index_tables.keys - @columns
+      if unknown.any?
+        raise ArgumentError, "index_tables declared for unknown columns #{unknown.inspect}, expected #{@columns.inspect}"
+      end
     end
 
     def included(base)
-      columns = @columns
-      parser = ->(tags) {
-        @options[:parser] ? @options[:parser].call(tags) : Metka.config.parser.instance.call(tags)
-      }
+      define_column_scopes(base)
+      define_tagged_with_scope(base)
+      define_index_tables(base)
+      define_tag_clouds(base)
+      define_tag_list_accessors(base)
+    end
 
-      # @param model [ActiveRecord::Base] model on which to execute search
-      # @param tags [Object] list of tags, representation depends on parser used
-      # @param options [Hash] options
-      #   @option :join_operator [Metka::AND, Metka::OR]
-      #   @option :on [Array<String>] list of column names to include in query
-      # @returns ViewPost::ActiveRecord_Relation
-      tagged_with_lambda = ->(model, tags, **options) {
-        cols = options.delete(:on)
-        parsed_tag_list = parser.call(tags)
+    private
 
-        return model if parsed_tag_list.empty?
+    def define_column_scopes(base)
+      @columns.each do |column|
+        base.scope "with_all_#{column}", ->(tags) { tagged_with(tags, on: [ column ]) }
+        base.scope "with_any_#{column}", ->(tags) { tagged_with(tags, on: [ column ], any: true) }
+        base.scope "without_all_#{column}", ->(tags) { tagged_with(tags, on: [ column ], exclude: true) }
+        base.scope "without_any_#{column}", ->(tags) { tagged_with(tags, on: [ column ], any: true, exclude: true) }
+      end
+    end
 
-        request = ::Metka::QueryBuilder.new.call(model, cols, parsed_tag_list, options)
-        model.where(request)
-      }
+    # @param tags [Object] list of tags, representation depends on the parser used
+    # @param options [Hash] options
+    #   @option :any [Boolean] match any of the tags instead of all of them
+    #   @option :exclude [Boolean] negate the match
+    #   @option :join_operator [Metka::AND, Metka::OR] how to combine multiple columns
+    #   @option :on [Array<String>] column names to search
+    # @return [ActiveRecord::Relation]
+    def define_tagged_with_scope(base)
+      return if base.respond_to?(:tagged_with)
+
+      columns = @columns.map(&:to_s)
+      parser = tag_parser
+      allowed = TAGGED_WITH_OPTIONS
+
+      # legacy_options carries the positional hash callers could pass before
+      # these became keywords. Ruby 3 will not convert one into keywords, so
+      # accepting it explicitly keeps `tagged_with(tags, options)` working.
+      base.scope :tagged_with, ->(tags = "", legacy_options = nil, **options) {
+        options = legacy_options.to_h.symbolize_keys.merge(options)
+        unknown = options.keys - allowed
+        if unknown.any?
+          raise ArgumentError, "Unknown tagged_with options #{unknown.inspect}, expected #{allowed.inspect}"
+        end
 
-      base.class_eval do
-        columns.each do |column|
-          scope "with_all_#{column}", ->(tags) { tagged_with(tags, on: [column]) }
-          scope "with_any_#{column}", ->(tags) { tagged_with(tags, on: [column], any: true) }
-          scope "without_all_#{column}", ->(tags) { tagged_with(tags, on: [column], exclude: true) }
-          scope "without_any_#{column}", ->(tags) { tagged_with(tags, on: [column], any: true, exclude: true) }
+        # :on lands in raw SQL as identifiers, so it is checked against the
+        # declared columns rather than interpolated on trust — same contract
+        # as metka_cloud.
+        on = Array(options[:on] || columns).map(&:to_s)
+        unknown_columns = on - columns
+        if unknown_columns.any?
+          raise ArgumentError, "Unknown tag columns #{unknown_columns.inspect}, expected #{columns.inspect}"
         end
 
-        unless respond_to?(:tagged_with)
-          scope :tagged_with, ->(tags = '', options = {}) {
-            options[:join_operator] ||= ::Metka::OR
-            options = {any: false}.merge(options)
-            options[:on] ||= columns
+        tag_list = parser.call(tags)
+        next self if tag_list.empty?
 
-            tagged_with_lambda.call(self, tags, **options)
-          }
-        end
-      end
+        where(::Metka::QueryBuilder.instance.call(self, on, tag_list, {
+          any: options.fetch(:any, false),
+          exclude: options[:exclude],
+          join_operator: options[:join_operator] || ::Metka::OR
+        }))
+      }
+    end
+
+    # The index strategy (`rails g metka:strategies:index`) maintains a
+    # (tag_name, record_id) side table per tagged column. Declaring it here
+    # via `index_tables: { "tags" => "posts_tags_index" }` lets the SQLite
+    # query path answer from that table instead of scanning json_each.
+    def define_index_tables(base)
+      tables = index_tables
 
-      base.define_singleton_method :metka_cloud do |*columns|
-        return [] if columns.blank?
+      base.define_singleton_method(:metka_index_table) { |column| tables[column.to_s] }
+    end
+
+    def define_tag_clouds(base)
+      taggable = @columns
+
+      # metka_cloud is public and its arguments land in raw SQL, so they are
+      # checked against the declared columns rather than interpolated on trust.
+      base.define_singleton_method :metka_cloud do |*cloud_columns|
+        return [] if cloud_columns.blank?
+
+        cloud_columns = cloud_columns.map(&:to_s)
+        unknown = cloud_columns - taggable
+        if unknown.any?
+          raise ArgumentError, "Unknown tag columns #{unknown.inspect}, expected #{taggable.inspect}"
+        end
 
-        prepared_unnest = columns.map { |column| "#{table_name}.#{column}" }.join(' || ')
-        subquery = all.select("UNNEST(#{prepared_unnest}) AS tag_name")
+        quoted = cloud_columns.map { |column|
+          connection.quote_table_name("#{table_name}.#{column}")
+        }
+
+        subquery =
+          if connection.adapter_name.match?(/sqlite/i)
+            # SQLite has no UNNEST; json_each unpacks each JSON array as a
+            # lateral cross join. Arrays cannot be concatenated the way
+            # PostgreSQL concatenates them, so multiple columns become one
+            # SELECT per column glued with UNION ALL — a NULL column joins to
+            # zero rows either way, matching UNNEST of a NULL array.
+            parts = quoted.map { |column|
+              all.select("json_each.value AS tag_name").joins("CROSS JOIN json_each(#{column})").to_sql
+            }
+            Arel.sql("(#{parts.join(" UNION ALL ")}) subquery")
+          else
+            all.select("UNNEST(#{quoted.join(" || ")}) AS tag_name")
+          end
+
+        unscoped.from(subquery).group(:tag_name).pluck(:tag_name, Arel.sql("COUNT(*) AS taggings_count"))
+      end
 
-        unscoped.from(subquery).group(:tag_name).pluck(:tag_name, Arel.sql('COUNT(*) AS taggings_count'))
+      @columns.each do |column|
+        base.define_singleton_method(:"#{column.singularize}_cloud") { metka_cloud(column) }
       end
+    end
+
+    def define_tag_list_accessors(base)
+      parser = tag_parser
 
-      columns.each do |column|
-        base.define_method(column.singularize + '_list=') do |v|
-          write_attribute(column, parser.call(v).to_a)
+      @columns.each do |column|
+        base.define_method(:"#{column.singularize}_list=") do |tags|
+          write_attribute(column, parser.call(tags).to_a)
           write_attribute(column, nil) if send(column).empty?
         end
 
-        base.define_method(column.singularize + '_list') do
+        base.define_method(:"#{column.singularize}_list") do
           parser.call(send(column))
         end
-
-        base.define_singleton_method :"#{column.singularize}_cloud" do
-          metka_cloud(column)
-        end
       end
     end
+
+    def index_tables
+      (@options[:index_tables] || {}).transform_keys(&:to_s).transform_values(&:to_s).freeze
+    end
+
+    # Metka.config.parser is looked up on every call so that reconfiguring it
+    # after a model has been included still takes effect.
+    def tag_parser
+      custom = @options[:parser]
+
+      ->(tags) { (custom || Metka.config.parser.instance).call(tags) }
+    end
   end
 end

data/lib/metka/query_builder.rb

@@ -1,70 +1,66 @@
 # frozen_string_literal: true
 
-require 'arel'
-require_relative 'query_builder/base_query'
-require_relative 'query_builder/any_tags_query'
-require_relative 'query_builder/all_tags_query'
+require "arel"
+require_relative "tags_query"
 
 module Metka
   class QueryBuilder
-    def call(model, columns, tags, options)
-      strategy = options_to_strategy(options)
-
-      query = join(options[:join_operator]) {
-        columns.map do |column|
-          build_query(strategy, model, column, tags)
-        end
-      }
-
-      if options[:exclude].present?
-        Arel::Nodes::Not.new(query)
-      else
-        query
-      end
+    # Stateless, so one frozen instance serves every tagged_with call.
+    def self.instance
+      @instance ||= new.freeze
     end
 
-    private
+    STRATEGIES = {
+      all: TagsQuery.new(match: :all).freeze,
+      any: TagsQuery.new(match: :any).freeze
+    }.freeze
 
-    def options_to_strategy(options)
-      if options[:any].present?
-        AnyTagsQuery
-      else
-        AllTagsQuery
-      end
-    end
+    JOINERS = {
+      and: ->(nodes) { Arel::Nodes::And.new(nodes) },
+      or: ->(nodes) { nodes.reduce(:or) }
+    }.freeze
+
+    # Metka::AND and Metka::OR used to be these Arel classes. Callers that
+    # passed them literally still work.
+    LEGACY_OPERATORS = {
+      Arel::Nodes::And => :and,
+      Arel::Nodes::Or => :or
+    }.freeze
 
-    def join(operator, &block)
-      nodes = block.call
+    def call(model, columns, tags, options)
+      strategy = STRATEGIES.fetch(options[:any].present? ? :any : :all)
+      nodes = columns.map { |column| strategy.call(model, column, tags) }
+      query = join(nodes, using: options[:join_operator])
 
-      if operator == ::Metka::AND
-        join_and(nodes)
-      elsif operator == ::Metka::OR
-        join_or(nodes)
-      end
+      options[:exclude].present? ? exclude(query) : query
     end
 
-    # @param nodes [Array<Arel::Nodes::Node>, Arel::Nodes::Node]
-    # @return [Arel::Nodes::Node]
-    def join_or(nodes)
-      node_base_klass = defined?(::Arel::Nodes::Node) ? ::Arel::Nodes::Node : ::Arel::Node
+    private
 
-      case nodes
-      when node_base_klass
-        nodes
-      when Array
-        l, *r = nodes
-        return l if r.empty?
+    def join(nodes, using:)
+      raise ArgumentError, "No tag columns to search" if nodes.empty?
 
-        l.or(join_or(r))
-      end
+      JOINERS.fetch(normalize(using)) {
+        raise ArgumentError,
+          "Unknown join_operator #{using.inspect}, expected #{JOINERS.keys.map(&:inspect).join(" or ")}"
+      }.call(nodes)
     end
 
-    def join_and(queries)
-      Arel::Nodes::And.new(queries)
+    def normalize(operator)
+      LEGACY_OPERATORS.fetch(operator, operator)
     end
 
-    def build_query(strategy, model, column, tags)
-      strategy.instance.call(model, column, tags)
+    # A NULL tag column makes its comparison NULL, and NOT NULL is NULL, so the
+    # row silently drops out of the WHERE entirely. Coalescing to FALSE first
+    # reads a NULL column as "this row does not carry the tag", which is what
+    # excluding actually asks.
+    #
+    # Only the exclude path is wrapped. Coalescing the columns themselves would
+    # fix it too, but costs the GIN index on every positive query.
+    def exclude(query)
+      Arel::Nodes::Not.new(
+        Arel::Nodes::NamedFunction.new("COALESCE", [ query, Arel.sql("FALSE") ])
+      )
     end
   end
 end

data/lib/metka/tag_list.rb

@@ -1,15 +1,23 @@
 # frozen_string_literal: true
 
-require 'set'
+require "set"
 
 module Metka
+  # The parsed form of a tag string: an ordered, de-duplicated set of tags.
+  #
+  #   Metka::GenericParser.instance.call("ruby, rails, ruby").to_s
+  #   #=> "ruby, rails"
   class TagList < Set
-    # def add(o)
-    #   if o.respond_to?(:each)
-    #     o.each { |e| Metka.config.parser.call(e) }
-    #   else
-    #     super(Metka.config.parser.call(o))
-    #   end
-    # end
+    # Set#to_s is an alias of #inspect, so a tag list rendered itself as
+    # "#<Set: {\"ruby\"}>". This is a user-facing value, so render it the way
+    # it was written.
+    #
+    # Joins on the configured delimiter, so it round-trips through the parser.
+    # A parser subclass that overrides #delimiter privately — as the dummy
+    # app's CustomParser does — is not visible from here, so a tag list it
+    # produced renders with the configured delimiter rather than that parser's.
+    def to_s
+      to_a.join("#{Metka.delimiter} ")
+    end
   end
 end

data/lib/metka/tags_query.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Metka
+  class TagsQuery
+    # PostgreSQL array operators; also the source of truth for valid match
+    # modes, so an unknown mode raises KeyError on either adapter.
+    OPERATORS = { all: "@>", any: "&&" }.freeze
+
+    def initialize(match: :all)
+      OPERATORS.fetch(match)
+      @match = match
+    end
+
+    def call(model, column_name, tag_list)
+      if model.connection.adapter_name.match?(/sqlite/i)
+        sqlite(model, column_name, tag_list)
+      else
+        postgresql(model, column_name, tag_list)
+      end
+    end
+
+    private
+
+    # Always the operator form, even for one tag: `tag = ANY(column)` cannot
+    # use a GIN index on the column, while `column @> ARRAY[tag]` can.
+    def postgresql(model, column_name, tag_list)
+      Arel::Nodes::InfixOperation.new(
+        OPERATORS.fetch(@match),
+        model.arel_table[column_name],
+        literal("ARRAY[?]::varchar[]", tag_list.to_a)
+      )
+    end
+
+    # SQLite has no array type or containment operators; tags live in a JSON
+    # array and json_each unpacks it into rows an EXISTS can probe. There is
+    # no index that can serve these predicates — SQLite tag queries are table
+    # scans, unless the model declares an index table for the column.
+    #
+    # json_each(NULL) yields no rows, so EXISTS over an untagged column is
+    # FALSE rather than NULL and the exclude path needs no NULL guard here.
+    def sqlite(model, column_name, tag_list)
+      if model.respond_to?(:metka_index_table) && (index_table = model.metka_index_table(column_name))
+        return sqlite_indexed(model, index_table, tag_list)
+      end
+
+      column = model.connection.quote_table_name("#{model.table_name}.#{column_name}")
+
+      sql =
+        if @match == :all
+          tag_list.to_a.map { |tag|
+            sanitize("EXISTS (SELECT 1 FROM json_each(#{column}) WHERE value = ?)", tag)
+          }.join(" AND ")
+        else
+          sanitize("EXISTS (SELECT 1 FROM json_each(#{column}) WHERE value IN (?))", tag_list.to_a)
+        end
+
+      # Grouping keeps the AND-joined predicates one node, so the query
+      # builder can OR and negate it like the PostgreSQL operator form.
+      Arel::Nodes::Grouping.new(Arel::Nodes::SqlLiteral.new(sql))
+    end
+
+    # The index strategy's side table: (tag_name, record_id) pairs whose
+    # WITHOUT ROWID primary key doubles as a covering index, maintained by
+    # the triggers `rails g metka:strategies:index` installs. "all" becomes
+    # an INTERSECT of per-tag index seeks, "any" a single IN probe. A row
+    # with a NULL tag column has no index entries, so the membership test is
+    # FALSE (never NULL) and the exclude path keeps working unchanged.
+    def sqlite_indexed(model, index_table, tag_list)
+      index = model.connection.quote_table_name(index_table)
+      id = model.connection.quote_table_name("#{model.table_name}.#{model.primary_key}")
+
+      sql =
+        if @match == :all
+          seeks = tag_list.to_a.map { |tag|
+            sanitize("SELECT record_id FROM #{index} WHERE tag_name = ?", tag)
+          }
+          "#{id} IN (#{seeks.join(" INTERSECT ")})"
+        else
+          sanitize("#{id} IN (SELECT record_id FROM #{index} WHERE tag_name IN (?))", tag_list.to_a)
+        end
+
+      Arel::Nodes::Grouping.new(Arel::Nodes::SqlLiteral.new(sql))
+    end
+
+    def sanitize(template, value)
+      ActiveRecord::Base.sanitize_sql_for_conditions([ template, value ])
+    end
+
+    def literal(template, value)
+      Arel::Nodes::SqlLiteral.new(sanitize(template, value))
+    end
+  end
+end

data/lib/metka/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Metka
-  VERSION = '2.3.4'
+  VERSION = "3.0.1"
 end

data/lib/metka.rb

@@ -1,20 +1,34 @@
 # frozen_string_literal: true
 
-require 'metka/version'
+require "metka/version"
 
-require 'active_support/core_ext/module'
-require 'dry-configurable'
+require "active_support/core_ext/module"
 
 module Metka
-  require 'metka/tag_list'
-  require 'metka/generic_parser'
-  require 'metka/query_builder'
-  require 'metka/model'
+  # How multiple tag columns combine in a tagged_with query. These are the
+  # public vocabulary, so they are plain symbols — Arel is an implementation
+  # detail of the query builder and does not belong in a caller's code.
+  AND = :and
+  OR = :or
+
+  require "metka/tag_list"
+  require "metka/generic_parser"
+  require "metka/query_builder"
+  require "metka/model"
 
   class Error < StandardError; end
 
-  extend Dry::Configurable
+  mattr_accessor :parser, default: Metka::GenericParser
+  mattr_accessor :delimiter, default: ","
+
+  # These two settings came from dry-configurable, which reached them through
+  # Metka.config. Nothing else in the gem needed that gem, so it is gone and
+  # the entry points it provided forward to the module itself.
+  def self.config
+    self
+  end
 
-  setting :parser, default: Metka::GenericParser
-  setting :delimiter, default: ',', reader: true
+  def self.configure
+    yield self
+  end
 end