pluckr 0.1.0

data/lib/pluckr/relation.rb

@@ -0,0 +1,414 @@
+# frozen_string_literal: true
+
+module Pluckr
+  # Immutable, chainable wrapper around the root ActiveRecord relation.
+  #
+  # Root filtering/ordering/pagination is delegated to ActiveRecord - Pluckr
+  # only adds its projections and joins when the query is compiled.
+  class Relation
+    include Enumerable
+
+    attr_reader :query_class, :relation
+
+    def initialize(query_class, relation)
+      @query_class = query_class
+      @relation = relation
+      freeze
+    end
+
+    # `where` with no arguments returns a chain, so `where.not(...)` works like
+    # it does on an ActiveRecord relation.
+    def where(*args, **options, &block)
+      return WhereChain.new(self) if args.empty? && options.empty? && block.nil?
+
+      spawn(relation.where(*args, **options, &block))
+    end
+
+    def order(...)
+      spawn(relation.order(...))
+    end
+
+    def limit(value)
+      spawn(relation.limit(value))
+    end
+
+    def offset(value)
+      spawn(relation.offset(value))
+    end
+
+    def to_sql
+      query_class.compiler.apply(relation).to_sql
+    end
+
+    # One statement, one round trip, plain result objects.
+    def fetch
+      builder = query_class.result_builder
+      rows = Pluckr.select_all(query_class.compiler.connection, to_sql, name: query_class.name)
+      rows.map { |row| builder.build(row) }
+    end
+    alias to_a fetch
+
+    def each(&block)
+      fetch.each(&block)
+    end
+
+    # Enumerable would answer these by building every result object first, which
+    # is the opposite of the point. They are questions about the root rows, so
+    # ActiveRecord answers them with `COUNT(*)`/`SELECT 1`, without Pluckr's
+    # projections.
+    # A block (or an Enumerable pattern) is a question about the results, so it
+    # goes back to Enumerable - exactly where ActiveRecord sends it.
+    def count(*args)
+      return super if block_given?
+
+      relation.count(*args)
+    end
+    alias size count
+
+    def exists?(...)
+      relation.exists?(...)
+    end
+
+    def any?(*args)
+      return super if args.any? || block_given?
+
+      exists?
+    end
+
+    def none?(*args)
+      return super if args.any? || block_given?
+
+      !exists?
+    end
+
+    def empty?
+      !exists?
+    end
+
+    def explain(...)
+      query_class.compiler.apply(relation).explain(...)
+    end
+
+    # ActiveRecord orders by primary key when the relation has no order of its
+    # own, so that `first` means something. Same here.
+    def first(limit = nil)
+      results = ordered_by_primary_key.limit(within_limit(limit || 1)).fetch
+
+      limit ? results : results.first
+    end
+
+    def first!
+      first || raise(ActiveRecord::RecordNotFound, "Couldn't find #{model.name}")
+    end
+
+    # The other end of the same order, read in one `LIMIT` rather than by
+    # hydrating the chain and dropping all but the tail. A chain that already
+    # pages is the exception ActiveRecord makes too: its own `limit` cannot be
+    # replaced by ours, so the page is read and the tail taken from it.
+    def last(limit = nil)
+      return last_of_page(limit) if paginated?(relation)
+
+      results = spawn(ordered_by_primary_key.relation.reverse_order).limit(limit || 1).fetch
+
+      limit ? results.reverse : results.first
+    end
+
+    def last!
+      last || raise(ActiveRecord::RecordNotFound, "Couldn't find #{model.name}")
+    end
+
+    # Enumerable's `take` would read the whole chain to keep the front of it.
+    def take(limit = nil)
+      results = self.limit(limit || 1).fetch
+
+      limit ? results : results.first
+    end
+
+    def take!
+      take || raise(ActiveRecord::RecordNotFound, "Couldn't find #{model.name}")
+    end
+
+    # Two rows is all it takes to answer either question - unless the chain
+    # already limits itself to fewer, in which case that limit is the answer.
+    def one?(*args)
+      return super if args.any? || block_given?
+
+      limited_count == 1
+    end
+
+    def many?(*args)
+      return super if args.any? || block_given?
+
+      limited_count > 1
+    end
+
+    # `find` is the primary key lookup; a block is Enumerable's `find`, which is
+    # where ActiveRecord sends it too. Several ids (or an array of them) come
+    # back as an array, in the order they were asked for.
+    def find(*args, &block)
+      return super if block
+      raise ArgumentError, "wrong number of arguments (given 0, expected 1+)" if args.empty?
+
+      key = single_primary_key
+      ids = args.size == 1 ? args.first : args
+      return for_ids(ids, key) if ids.is_a?(Array)
+      raise ActiveRecord::RecordNotFound, "Couldn't find #{model.name} without an ID" if ids.nil?
+
+      where(key => ids).first || raise(not_found(key, ids))
+    end
+
+    # The arity is ActiveRecord's: at least one condition, or `ArgumentError`.
+    def find_by(arg, *args)
+      where(arg, *args).first
+    end
+
+    def find_by!(arg, *args)
+      find_by(arg, *args) ||
+        raise(ActiveRecord::RecordNotFound,
+              "Couldn't find #{model.name} with #{[arg, *args].map(&:inspect).join(", ")}")
+    end
+
+    # Reads the whole chain in pages, so an export does not build every result
+    # object at once. Like ActiveRecord's, the batches are ordered by primary
+    # key and any order of your own is ignored - unlike ActiveRecord's, the page
+    # after the first is a keyset seek (`id > last`), never an OFFSET.
+    def find_each(batch_size: 1_000, &block)
+      assert_batchable!(batch_size)
+      return to_enum(:find_each, batch_size: batch_size) unless block_given?
+
+      in_batches(of: batch_size) { |results| results.each(&block) }
+    end
+
+    def in_batches(of: 1_000)
+      assert_batchable!(of)
+      return to_enum(:in_batches, of: of) unless block_given?
+
+      key = single_primary_key
+      output = primary_key_output(key)
+      scope = spawn(relation.reorder(key => :asc))
+      cursor = nil
+
+      loop do
+        page = cursor ? scope.where(model.arel_table[key].gt(cursor)) : scope
+        results = page.limit(of).fetch
+        break if results.empty?
+
+        yield results
+        break if results.size < of
+
+        cursor = results.last.public_send(output)
+      end
+    end
+
+    # See Query.for. An unloaded Relation is filtered in SQL (subquery), never
+    # loaded into Ruby; a loaded one already has its records, so they are used.
+    # A paginated one is resolved to primary keys first - see
+    # for_paginated_relation.
+    def for(records)
+      key = single_primary_key
+
+      if records.is_a?(self.class)
+        raise ConfigurationError, "`for` expects #{model.name} records, not another Pluckr query; use `fetch`"
+      end
+
+      return for_relation(records, key) if records.is_a?(ActiveRecord::Relation) && !records.loaded?
+      return for_many(records.to_a, key) if records.is_a?(Enumerable)
+
+      for_one(records, key)
+    end
+
+    def inspect
+      "#<Pluckr::Relation #{query_class.name} #{to_sql}>"
+    end
+
+    def spawn(new_relation)
+      self.class.new(query_class, new_relation)
+    end
+
+    # Mirrors ActiveRecord::QueryMethods::WhereChain for the operations Pluckr
+    # supports on the root relation.
+    class WhereChain
+      def initialize(pluckr_relation)
+        @pluckr_relation = pluckr_relation
+      end
+
+      def not(...)
+        @pluckr_relation.spawn(@pluckr_relation.relation.where.not(...))
+      end
+    end
+
+    private
+
+    def model
+      query_class.source_model
+    end
+
+    # Reading the front of a page cannot reach past its end, the way
+    # ActiveRecord's `find_nth_with_limit` clamps.
+    def within_limit(wanted)
+      relation.limit_value ? [relation.limit_value, wanted].min : wanted
+    end
+
+    # Both mirror ActiveRecord: a `limit` of the caller's own is never widened
+    # to make an answer easier to reach.
+    def limited_count
+      relation.limit_value ? relation.count : relation.limit(2).count
+    end
+
+    def last_of_page(limit)
+      results = ordered_by_primary_key.fetch
+
+      limit ? results.last(limit) : results.last
+    end
+
+    # Qualified, because `one` nodes join tables that have an `id` too, and per
+    # column, because a primary key can be composite.
+    def ordered_by_primary_key
+      return self unless relation.order_values.empty?
+
+      order(*Array(model.primary_key).map { |key| model.arel_table[key].asc })
+    end
+
+    def single_primary_key
+      key = model.primary_key
+      if key.is_a?(Array)
+        raise ConfigurationError,
+              "#{model.name} has a composite primary key, which Pluckr cannot look a row up by; " \
+              "use `where(...)` with `fetch`/`first` instead"
+      end
+
+      key
+    end
+
+    def for_one(record, key)
+      assert_record!(record)
+      find(record[key])
+    end
+
+    def for_many(records, key)
+      records.each { |record| assert_record!(record) }
+      for_ids(records.map { |record| record[key] }, key)
+    end
+
+    # Records the caller handed over must all come back - a missing one is a
+    # deleted record, and silence would hide it. A relation is a set of
+    # conditions instead, so rows the query itself filters out are simply not
+    # part of the answer, exactly as they are not for an unpaginated one.
+    def for_ids(ids, key, strict: true)
+      return [] if ids.empty?
+
+      index = index_by_primary_key(where(key => ids).fetch, key)
+      return ids.filter_map { |id| index[id] } unless strict
+
+      ids.map { |id| index[id] || raise(not_found(key, id)) }
+    end
+
+    # A relation only contributes its conditions here: `select`/`order` and the
+    # preloading of rows Pluckr never instantiates are dropped, and `lock` is
+    # not carried into a read model. What cannot be dropped without changing
+    # which rows come back has to be loaded by the caller instead.
+    UNUSED_RELATION_VALUES = %i[select includes eager_load preload order lock].freeze
+
+    # A paginated relation keeps its order, so it cannot lose it to a subquery -
+    # nor to the joins that order may depend on. Only the projection and the
+    # lock go; `pluck` ignores a preload it does not need.
+    PAGINATED_RELATION_VALUES = %i[select lock].freeze
+
+    def for_relation(records, key)
+      unless records.klass <= model
+        raise ConfigurationError,
+              "`for` expects a relation for #{model.name}, got #{records.klass}"
+      end
+
+      assert_subqueryable!(records)
+      return for_paginated_relation(records, key) if paginated?(records)
+      scope = records.except(*UNUSED_RELATION_VALUES)
+      # `offset(0)` skips nothing, but ActiveRecord still emits a LIMIT for it,
+      # and MySQL cannot subquery a LIMIT at all.
+      scope = scope.except(:offset) if scope.offset_value&.zero?
+
+      where(key => scope.select(key)).fetch
+    end
+
+    def paginated?(records)
+      records.limit_value || records.offset_value.to_i.positive?
+    end
+
+    # Which rows a page holds depends on the order the subquery cannot carry -
+    # and MySQL rejects `IN (SELECT ... LIMIT ...)` outright. So the page is
+    # resolved to primary keys first: one extra, narrow statement, and the page
+    # and its order are the relation's own. See `page_keys` for the one shape
+    # that has to be loaded to be paged at all.
+    def for_paginated_relation(records, key)
+      scope = records.except(*PAGINATED_RELATION_VALUES)
+
+      for_ids(page_keys(scope, key), key, strict: false)
+    end
+
+    # A relation that joins to preload counts its `LIMIT` in parent rows, and
+    # only ActiveRecord knows how to page that - `pluck` would join first and
+    # cut the page mid fan-out, handing back duplicates and too many of them.
+    # So that page is resolved the way ActiveRecord resolves it, by loading it;
+    # the caller asked for preloaded records anyway. Every other relation keeps
+    # the cheap read: keys only, nothing instantiated.
+    def page_keys(scope, key)
+      return scope.pluck(key) unless scope.eager_loading? || scope.includes_values.any?
+
+      scope.map { |record| record[key] }
+    end
+
+    # A grouped relation selects the primary key it does not group by, which is
+    # not valid SQL - as a subquery or plucked.
+    def assert_subqueryable!(records)
+      return if records.group_values.empty?
+
+      raise ConfigurationError,
+            "`for` cannot subquery a relation with group/having; pass the records themselves: " \
+            "`for(relation.to_a)`"
+    end
+
+    # Batching owns the ordering and the paging, so a chain that already pages
+    # would silently get a different answer than `fetch` gives. A page size that
+    # is not a positive integer reads nothing at all, or reads everything.
+    def assert_batchable!(size)
+      unless size.is_a?(Integer) && size.positive?
+        raise ArgumentError, "page size must be a positive integer, got #{size.inspect}"
+      end
+
+      return unless paginated?(relation)
+
+      raise ConfigurationError,
+            "`find_each`/`in_batches` page the whole chain themselves; " \
+            "drop the `limit`/`offset` or use `fetch`"
+    end
+
+    def not_found(key, id)
+      ActiveRecord::RecordNotFound.new(
+        "Couldn't find #{model.name} with '#{key}'=#{id}", model.name, key, id
+      )
+    end
+
+    def index_by_primary_key(results, key)
+      output = primary_key_output(key)
+      results.to_h { |row| [row[output], row] }
+    end
+
+    # Bulk `.for` reorders rows to match the input and batching seeks past the
+    # last one read; both need the primary key on the result.
+    def primary_key_output(key)
+      field = query_class.pluckr_schema.fields.find { |node| node.column.to_s == key.to_s }
+      return field.output if field
+
+      raise ConfigurationError,
+            "#{query_class.name} needs `field :#{key}` (or `field :#{key}, as: ...`) " \
+            "to align several results with the rows they came from"
+    end
+
+    def assert_record!(record)
+      return if record.is_a?(model)
+
+      got = record.is_a?(ActiveRecord::Base) ? record.class.name : record.inspect
+      raise ConfigurationError, "`for` expects #{model.name} records, got #{got}"
+    end
+  end
+end

data/lib/pluckr/result/builder.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Pluckr
+  module Result
+    # Turns one flat database row into nested result objects.
+    #
+    # Result classes and per-column casters are built once per schema level when
+    # the builder is created, so hydration itself is hash lookups plus a cast.
+    class Builder
+      BOOLEAN = ActiveModel::Type::Boolean.new
+      INTEGER = ActiveModel::Type::Integer.new
+      # AVG of an integer column is not an integer; ActiveRecord answers a
+      # BigDecimal here and so does Pluckr.
+      DECIMAL = ActiveRecord::Type::Decimal.new
+
+      # Casts one column of a row. `default` covers SQL returning NULL where the
+      # equivalent ActiveRecord call would not: SUM over no rows is NULL in SQL
+      # and 0 in `relation.sum(:column)`.
+      Caster = Struct.new(:type, :default) do
+        def call(value)
+          return default if value.nil?
+
+          type ? type.deserialize(value) : value
+        end
+      end
+
+      def initialize(schema, label: "Pluckr::Result")
+        @schema = schema
+        @classes = {}
+        @casters = {}
+        prepare(schema, label)
+      end
+
+      # @param row [Hash] flat row keyed by SQL alias
+      def build(row)
+        hydrate(@schema, [], row)
+      end
+
+      private
+
+      def prepare(scope, label)
+        @classes[scope] = Object.build_class(scope.outputs, label)
+        @casters[scope] = scope.nodes.to_h { |node| [node.output, caster_for(node, scope.model)] }
+
+        scope.ones.each do |node|
+          prepare(node.scope, "#{label}.#{node.output}")
+        end
+      end
+
+      # SQLite and MySQL hand back 1/0 where PostgreSQL hands back true/false,
+      # and raw SQL carries no column type, so Pluckr casts values itself.
+      def caster_for(node, model)
+        case node
+        when Schema::Field then Caster.new(model.type_for_attribute(node.column))
+        when Schema::Exists then Caster.new(BOOLEAN)
+        when Schema::Aggregate then aggregate_caster(node)
+        end
+      end
+
+      def aggregate_caster(node)
+        case node.operation
+        when :count then Caster.new(INTEGER)
+        when :exists then Caster.new(BOOLEAN)
+        when :avg then Caster.new(DECIMAL) # nil for no rows, like `relation.average`
+        else
+          type = node.target_model.type_for_attribute(node.column)
+          # `sum` answers 0 for no rows, like ActiveRecord; `min`/`max` stay nil,
+          # because no row means no minimum.
+          Caster.new(type, node.operation == :sum ? type.cast(0) : nil)
+        end
+      end
+
+      def hydrate(scope, path, row)
+        casters = @casters[scope]
+        attributes = {}
+
+        scope.nodes.each do |node|
+          attributes[node.output] =
+            if node.is_a?(Schema::One)
+              hydrate_one(node, path, row)
+            else
+              casters[node.output].call(row[Aliases.output(path, node.output)])
+            end
+        end
+
+        @classes[scope].new(attributes)
+      end
+
+      def hydrate_one(node, path, row)
+        child_path = path + [node.output.to_s]
+        # No presence marker -> no associated row at all (as opposed to a row
+        # whose selected columns happen to be NULL).
+        return nil if row[Aliases.presence(child_path)].nil?
+
+        hydrate(node.scope, child_path, row)
+      end
+
+    end
+  end
+end

data/lib/pluckr/result/object.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Pluckr
+  module Result
+    # Immutable, ActiveRecord-free value object.
+    #
+    # One subclass is generated per schema level, with a plain reader per
+    # selected output. Internal aliases and presence markers never reach here.
+    class Object
+      # @param outputs [Array<Symbol>] readers this level exposes
+      # @param label [String] shown by #inspect
+      def self.build_class(outputs, label)
+        Class.new(self) do
+          define_singleton_method(:pluckr_outputs) { outputs }
+          define_singleton_method(:pluckr_label) { label }
+
+          outputs.each do |output|
+            define_method(output) { @attributes[output] }
+          end
+        end
+      end
+
+      def self.pluckr_outputs
+        []
+      end
+
+      def self.pluckr_label
+        "Pluckr::Result"
+      end
+
+      def initialize(attributes)
+        @attributes = attributes.freeze
+        freeze
+      end
+
+      def [](key)
+        @attributes[key.to_sym]
+      end
+
+      def to_h
+        @attributes.transform_values do |value|
+          value.is_a?(Object) ? value.to_h : value
+        end
+      end
+      alias to_hash to_h
+
+      # Without this, ActiveSupport serialises the object's ivars and
+      # `render json: result` emits {"attributes": {...}}. `to_json` is left to
+      # ActiveSupport, which routes it back here with the caller's options.
+      def as_json(options = nil)
+        to_h.as_json(options)
+      end
+
+      def keys
+        @attributes.keys
+      end
+
+      def ==(other)
+        other.class == self.class && other.to_h == to_h
+      end
+      alias eql? ==
+
+      def hash
+        [self.class, to_h].hash
+      end
+
+      def inspect
+        pairs = @attributes.map { |key, value| "#{key}=#{value.inspect}" }
+        "#<#{self.class.pluckr_label} #{pairs.join(", ")}>"
+      end
+      alias to_s inspect
+
+      def pretty_print(pp)
+        pp.text(inspect)
+      end
+    end
+  end
+end

data/lib/pluckr/schema/aggregate.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Pluckr
+  module Schema
+    # Two flavours share this node:
+    #
+    #   count :videos                      # correlated: association is set
+    #   count :users, from: User           # independent: model is set
+    #
+    # Both compile to a scalar subquery in the SELECT list, never to a JOIN +
+    # GROUP BY, so root rows are never multiplied.
+    class Aggregate < Node
+      include Conditions
+
+      OPERATIONS = %i[count sum avg min max exists].freeze
+
+      attr_reader :operation, :association, :model, :relation, :column, :where, :scope
+
+      def initialize(output:, operation:, association: nil, model: nil, relation: nil,
+                     column: nil, where: nil, scope: nil)
+        super(output: output)
+        @operation = operation.to_sym
+        unless OPERATIONS.include?(@operation)
+          raise ConfigurationError, "unsupported aggregate operation `#{operation}`"
+        end
+
+        @association = association
+        @model = model
+        @relation = relation
+        @column = column&.to_sym
+        @where = where.respond_to?(:call) ? where : where&.dup&.freeze
+        @scope = scope
+        freeze
+      end
+
+      # Independent aggregates are not rooted in the source record.
+      def independent?
+        !model.nil? || !relation.nil?
+      end
+
+      def correlated?
+        !association.nil?
+      end
+
+      # True when the subquery must be built from an ActiveRecord relation
+      # rather than straight Arel.
+      def relation_scoped?
+        !scope.nil? || !where.nil?
+      end
+
+
+      # Target model for column validation / table resolution.
+      def target_model
+        model || relation&.klass || association.klass
+      end
+    end
+  end
+end

data/lib/pluckr/schema/conditions.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Pluckr
+  module Schema
+    # `where:` on an aggregate or existence node.
+    #
+    # A Hash is validated once, when the schema is defined, and is therefore
+    # frozen at load time - `where: { created_at: 1.week.ago.. }` would keep
+    # asking about the week before boot, forever.
+    #
+    # A callable is invoked on every compilation instead, so runtime values stay
+    # runtime values:
+    #
+    #   count :recent_orders, from: Order, where: -> { { created_at: 1.week.ago.. } }
+    module Conditions
+      def dynamic_where?
+        where.respond_to?(:call)
+      end
+
+      # @return [Hash, nil] the conditions to apply to this compilation
+      def resolved_where
+        return where unless dynamic_where?
+
+        conditions = where.call
+
+        unless conditions.is_a?(Hash)
+          raise ConfigurationError,
+                "`#{output}`: a `where:` lambda must return a Hash of column => value, " \
+                "got #{conditions.inspect}"
+        end
+
+        conditions.each_key { |key| validate_column!(key) }
+        conditions
+      end
+
+      private
+
+      def validate_column!(name)
+        return if target_model.column_names.include?(name.to_s)
+
+        raise UnknownField, "#{target_model.name} does not have column `#{name}`"
+      end
+    end
+  end
+end