pluckr 0.1.0

data/lib/pluckr/schema/definition.rb

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+
+module Pluckr
+  module Schema
+    # Evaluates the `schema do ... end` block and builds a Scope of AST nodes.
+    #
+    # All validation happens here, at class-definition time, so mistakes blow up
+    # when the query is loaded rather than when it is executed.
+    class Definition
+      # @param model [Class<ActiveRecord::Base>, nil] nil for aggregate-only queries
+      def self.build(model, label: "schema", &block)
+        raise ConfigurationError, "`#{label}` requires a block" unless block
+
+        definition = new(model)
+        definition.instance_eval(&block)
+        scope = definition.to_scope
+
+        raise ConfigurationError, "`#{label}` block is empty - declare at least one node" if scope.nodes.empty?
+
+        scope
+      end
+
+      def initialize(model)
+        @model = model
+        @nodes = []
+      end
+
+      def to_scope
+        Scope.new(@model, @nodes)
+      end
+
+      # ---------------------------------------------------------------- DSL --
+
+      def field(name, as: nil)
+        require_source!("field :#{name}")
+        validate_column!(@model, name)
+        add Field.new(column: name, output: as || name)
+      end
+
+      def one(name, via: nil, &block)
+        require_source!("one :#{name}")
+        raise ConfigurationError, "`one :#{name}` requires a block" unless block
+
+        association = Reflection::Association.for(@model, via || name)
+        unless association.singular?
+          raise InvalidAssociation,
+                "`#{@model.name}##{association.name}` is a #{association.macro} association " \
+                "and cannot be used with `one`"
+        end
+
+        add One.new(
+          output: name,
+          association: association,
+          scope: Definition.build(association.klass, label: "one :#{name}", &block)
+        )
+      end
+
+      # `first :comment, via: :comments do ... end` - the earliest row of a
+      # collection, by primary key unless `order:` says otherwise.
+      def first(name, via: nil, order: nil, &block)
+        pick(:first, name, via: via, order: order, &block)
+      end
+
+      # `last :comment, via: :comments, order: :created_at do ... end`
+      def last(name, via: nil, order: nil, &block)
+        pick(:last, name, via: via, order: order, &block)
+      end
+
+      def exists(name, via: nil, as: nil, where: nil, scope: nil)
+        require_source!("exists :#{name}")
+        association = Reflection::Association.for(@model, via || name)
+        validate_where!(association.klass, where)
+        validate_scope!("exists :#{name}", scope)
+
+        add Exists.new(
+          output: as || :"#{name}_exists",
+          association: association,
+          where: where,
+          scope: scope
+        )
+      end
+
+      def count(name, from: nil, via: nil, as: nil, where: nil, column: nil, scope: nil)
+        aggregate(:count, name, from: from, via: via, as: as, where: where, column: column, scope: scope)
+      end
+
+      def sum(name, from: nil, via: nil, as: nil, where: nil, column: nil, scope: nil)
+        aggregate(:sum, name, from: from, via: via, as: as, where: where, column: column, scope: scope)
+      end
+
+      def avg(name, from: nil, via: nil, as: nil, where: nil, column: nil, scope: nil)
+        aggregate(:avg, name, from: from, via: via, as: as, where: where, column: column, scope: scope)
+      end
+      alias average avg
+
+      def min(name, from: nil, via: nil, as: nil, where: nil, column: nil, scope: nil)
+        aggregate(:min, name, from: from, via: via, as: as, where: where, column: column, scope: scope)
+      end
+
+      def max(name, from: nil, via: nil, as: nil, where: nil, column: nil, scope: nil)
+        aggregate(:max, name, from: from, via: via, as: as, where: where, column: column, scope: scope)
+      end
+
+      # ------------------------------------------------------------ internals --
+
+      private
+
+      def pick(direction, name, via:, order:, &block)
+        require_source!("#{direction} :#{name}")
+        raise ConfigurationError, "`#{direction} :#{name}` requires a block" unless block
+
+        association = Reflection::Association.for(@model, via || name)
+        scope = Definition.build(association.klass, label: "#{direction} :#{name}", &block)
+        validate_picked_scope!(direction, name, scope)
+
+        add One.new(
+          output: name,
+          association: association,
+          scope: scope,
+          pick: direction,
+          order: pick_order(direction, name, order, association.klass)
+        )
+      end
+
+      # Every column of the picked row comes from its own subquery, so nesting
+      # anything that needs a joined table cannot work here.
+      def validate_picked_scope!(direction, name, scope)
+        offender = scope.nodes.reject { |node| node.is_a?(Field) }.first
+        return unless offender
+
+        raise ConfigurationError,
+              "`#{direction} :#{name}` can only contain `field` in v0.1, " \
+              "got `#{offender.class.name.split("::").last.downcase} :#{offender.output}`"
+      end
+
+      # Normalises `order:` into [[column, direction], ...].
+      #
+      # `last` reverses it, so `last ..., order: { created_at: :asc }` is the
+      # final row of that ordering - what `relation.order(...).last` returns. The
+      # primary key always ends the list, so ties cannot make two columns come
+      # from two different rows.
+      def pick_order(direction, name, order, model)
+        entries = Array(order_entries(direction, name, order))
+        entries.each { |column, _| validate_column!(model, column) }
+        entries = entries.map { |column, dir| [column, invert(dir)] } if direction == :last
+
+        primary_key = model.primary_key&.to_sym
+        tiebreaker = direction == :last ? :desc : :asc
+        entries << [primary_key, tiebreaker] if primary_key && entries.none? { |column, _| column == primary_key }
+        entries.freeze
+      end
+
+      def invert(direction)
+        direction == :asc ? :desc : :asc
+      end
+
+      def order_entries(direction, name, order)
+        case order
+        when nil then []
+        when Symbol, String then [[order.to_sym, :asc]]
+        when Hash then order.map { |column, dir| [column.to_sym, order_direction(direction, name, dir)] }
+        when Array then order.flat_map { |entry| order_entries(direction, name, entry) }
+        else
+          raise ConfigurationError,
+                "`#{direction} :#{name}, order:` expects a column, a Hash or an Array, got #{order.inspect}"
+        end
+      end
+
+      def order_direction(direction, name, value)
+        normalized = value.to_s.downcase.to_sym
+        return normalized if %i[asc desc].include?(normalized)
+
+        raise ConfigurationError,
+              "`#{direction} :#{name}, order:` expects :asc or :desc, got #{value.inspect}"
+      end
+
+      def aggregate(operation, name, from:, via:, as:, where:, column:, scope:)
+        validate_scope!("#{operation} :#{name}", scope)
+
+        if from
+          independent_aggregate(operation, name, from: from, as: as, where: where,
+                                                 column: column, scope: scope)
+        else
+          correlated_aggregate(operation, name, via: via, as: as, where: where,
+                                                column: column, scope: scope)
+        end
+      end
+
+      def independent_aggregate(operation, name, from:, as:, where:, column:, scope:)
+        unless from.is_a?(Class) && from < ActiveRecord::Base
+          raise ConfigurationError,
+                "`#{operation} :#{name}, from:` expects an ActiveRecord model, got #{from.inspect}"
+        end
+
+        column = require_column!(operation, name, column, from)
+        validate_where!(from, where)
+
+        add Aggregate.new(
+          output: as || name,
+          operation: operation,
+          model: from,
+          column: column,
+          where: where,
+          scope: scope
+        )
+      end
+
+      def correlated_aggregate(operation, name, via:, as:, where:, column:, scope:)
+        require_source!("#{operation} :#{name}")
+
+        association = Reflection::Association.for(@model, via || name)
+        column = require_column!(operation, name, column, association.klass)
+        validate_where!(association.klass, where)
+
+        add Aggregate.new(
+          output: as || :"#{name}_#{operation}",
+          operation: operation,
+          association: association,
+          column: column,
+          where: where,
+          scope: scope
+        )
+      end
+
+      # count is the only operation that works without a column (COUNT(*)).
+      def require_column!(operation, name, column, model)
+        if column.nil?
+          return nil if operation == :count
+
+          raise ConfigurationError, "`#{operation} :#{name}` requires `column:`"
+        end
+
+        validate_column!(model, column)
+        column
+      end
+
+      def validate_column!(model, name)
+        return if model.column_names.include?(name.to_s)
+
+        raise UnknownField, "#{model.name} does not have column `#{name}`"
+      end
+
+      # A Hash is checked now; a callable can only be checked when it runs, on
+      # every compilation.
+      def validate_where!(model, where)
+        return if where.nil?
+
+        if where.respond_to?(:call)
+          return if !where.respond_to?(:arity) || where.arity <= 0
+
+          raise ConfigurationError,
+                "a `where:` callable takes no arguments and returns a Hash - use `scope:` if you " \
+                "need the relation"
+        end
+
+        unless where.is_a?(Hash)
+          raise ConfigurationError,
+                "`where:` expects a Hash of column => value or a callable returning one, " \
+                "got #{where.inspect}"
+        end
+
+        where.each_key { |key| validate_column!(model, key) }
+      end
+
+      # `scope:` takes the target model's relation and returns a narrowed one:
+      #   count :active_accounts, from: Account, scope: ->(rel) { rel.active }
+      def validate_scope!(node, scope)
+        return if scope.nil? || scope.respond_to?(:call)
+
+        raise ConfigurationError, "`#{node}, scope:` expects a callable, got #{scope.inspect}"
+      end
+
+      def require_source!(node)
+        return unless @model.nil?
+
+        raise MissingSource, "`#{node}` needs a root record - declare `source SomeModel` on the query"
+      end
+
+      def add(node)
+        if @nodes.any? { |existing| existing.output == node.output }
+          raise ConfigurationError, "duplicate output name `#{node.output}` in schema"
+        end
+
+        @nodes << node
+        node
+      end
+    end
+  end
+end

data/lib/pluckr/schema/exists.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Pluckr
+  module Schema
+    # `exists :photos` -> correlated `EXISTS (SELECT 1 FROM photos WHERE ...)`
+    class Exists < Node
+      include Conditions
+
+      attr_reader :association, :where, :scope
+
+      def initialize(output:, association:, where: nil, scope: nil)
+        super(output: output)
+        @association = association
+        @where = where.respond_to?(:call) ? where : where&.dup&.freeze
+        @scope = scope
+        freeze
+      end
+
+      def target_model
+        association.klass
+      end
+
+      def relation_scoped?
+        !scope.nil? || !where.nil?
+      end
+    end
+  end
+end

data/lib/pluckr/schema/field.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Pluckr
+  module Schema
+    # `field :email, as: :contact_email`
+    class Field < Node
+      attr_reader :column
+
+      def initialize(column:, output:)
+        super(output: output)
+        @column = column.to_sym
+        freeze
+      end
+    end
+  end
+end

data/lib/pluckr/schema/node.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Pluckr
+  module Schema
+    # Base class for every AST node.
+    #
+    # `output` is the key the node produces on the result object.
+    class Node
+      attr_reader :output
+
+      def initialize(output:)
+        @output = output.to_sym
+      end
+
+      # Nodes that map to exactly one selected column/expression.
+      def scalar?
+        true
+      end
+    end
+  end
+end

data/lib/pluckr/schema/one.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Pluckr
+  module Schema
+    # `one :plan, via: :subscription do ... end`
+    #
+    # Compiles to a LEFT OUTER JOIN plus a hidden presence marker so that
+    # "association missing" and "association present with NULL columns" stay
+    # distinguishable.
+    #
+    # `first :comment, via: :comments do ... end` and its `last` counterpart use
+    # the same node with `pick` and `order` set: one row out of a collection,
+    # compiled as correlated subqueries instead of a join.
+    class One < Node
+      attr_reader :association, :scope, :pick, :order
+
+      def initialize(output:, association:, scope:, pick: nil, order: nil)
+        super(output: output)
+        @association = association
+        @scope = scope
+        @pick = pick
+        @order = order&.freeze
+        freeze
+      end
+
+      # True when this node picks one row out of many rather than following a
+      # singular association.
+      def picked?
+        !pick.nil?
+      end
+
+      def scalar?
+        false
+      end
+    end
+  end
+end

data/lib/pluckr/schema/scope.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module Pluckr
+  module Schema
+    # A level of the AST: the nodes selected for one model (the root source, or
+    # one nested singular association).
+    class Scope
+      attr_reader :model, :nodes
+
+      def initialize(model, nodes)
+        @model = model
+        @nodes = nodes.freeze
+        freeze
+      end
+
+      def fields
+        nodes.grep(Field)
+      end
+
+      def ones
+        nodes.grep(One)
+      end
+
+      def outputs
+        nodes.map(&:output)
+      end
+
+      # True when anything here needs a root record to hang off.
+      def rooted?
+        nodes.any? { |node| !(node.is_a?(Aggregate) && node.independent?) }
+      end
+    end
+  end
+end

data/lib/pluckr/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Pluckr
+  VERSION = "0.1.0"
+end

data/lib/pluckr.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "active_record"
+require "active_support/core_ext/object/json"
+require "active_support/notifications"
+
+require "pluckr/version"
+require "pluckr/errors"
+require "pluckr/aliases"
+require "pluckr/reflection/association"
+require "pluckr/schema/node"
+require "pluckr/schema/conditions"
+require "pluckr/schema/field"
+require "pluckr/schema/one"
+require "pluckr/schema/exists"
+require "pluckr/schema/aggregate"
+require "pluckr/schema/scope"
+require "pluckr/schema/definition"
+require "pluckr/compiler/sql"
+require "pluckr/result/object"
+require "pluckr/result/builder"
+require "pluckr/relation"
+require "pluckr/batch"
+require "pluckr/query"
+
+# A declarative read-query layer for ActiveRecord.
+#
+#   DSL -> schema AST -> reflection -> SQL compiler -> flat row -> result object
+module Pluckr
+  # Every read of a read model goes through here, so one subscription covers
+  # `fetch`, `find`, `for` and `Pluckr.batch` alike. The statements Pluckr does
+  # not compile are absent by design: `count`/`exists?` and the primary keys of
+  # a paginated `.for` are ActiveRecord's own, and arrive as `sql.active_record`.
+  #
+  #   ActiveSupport::Notifications.subscribe("fetch.pluckr") do |*, payload|
+  #     payload[:name]  # => "UserSummary"
+  #     payload[:sql]   # => "SELECT ..."
+  #     payload[:rows]  # => 100
+  #   end
+  def self.select_all(connection, sql, name:, label: "#{name} Pluckr")
+    ActiveSupport::Notifications.instrument("fetch.pluckr", name: name, sql: sql) do |payload|
+      connection.select_all(sql, label).tap { |result| payload[:rows] = result.length }
+    end
+  end
+end

metadata

@@ -0,0 +1,125 @@
+--- !ruby/object:Gem::Specification
+name: pluckr
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Igor Kasyanchuk
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+- !ruby/object:Gem::Dependency
+  name: irb
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Pluckr lets you declare the shape of the data you need and compiles it
+  into a single SQL statement, returning lightweight immutable result objects instead
+  of ActiveRecord models. Works on PostgreSQL, MySQL and SQLite.
+email:
+- igorkasyanchuk@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- PROMPT.md
+- README.md
+- lib/pluckr.rb
+- lib/pluckr/aliases.rb
+- lib/pluckr/batch.rb
+- lib/pluckr/compiler/sql.rb
+- lib/pluckr/errors.rb
+- lib/pluckr/query.rb
+- lib/pluckr/reflection/association.rb
+- lib/pluckr/relation.rb
+- lib/pluckr/result/builder.rb
+- lib/pluckr/result/object.rb
+- lib/pluckr/schema/aggregate.rb
+- lib/pluckr/schema/conditions.rb
+- lib/pluckr/schema/definition.rb
+- lib/pluckr/schema/exists.rb
+- lib/pluckr/schema/field.rb
+- lib/pluckr/schema/node.rb
+- lib/pluckr/schema/one.rb
+- lib/pluckr/schema/scope.rb
+- lib/pluckr/version.rb
+homepage: https://github.com/igorkasyanchuk/pluckr
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/igorkasyanchuk/pluckr
+  source_code_uri: https://github.com/igorkasyanchuk/pluckr
+  changelog_uri: https://github.com/igorkasyanchuk/pluckr/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.2
+specification_version: 4
+summary: A declarative read-query layer for ActiveRecord.
+test_files: []