quo 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 5abae18b00be2197c2d35ed322af099766deaaa13f77f14fe53f597f2ed544b2
+  data.tar.gz: 95e1b9e161ad9e4d6fb627194cc6b408878945aa08c43ef498bbbfa0ea5c3dd3
+SHA512:
+  metadata.gz: 9c6ce18b7bb3de2243561ad14da26117e7053a0c04255dc94b8408d942a1382e2c4eb2c6071c22f52d1a7cef9bf9fceeeb7746788f921c0c1c6a9896fa2f4717
+  data.tar.gz: 063f2dd88dcd09bd1b3778b8c6bc77b09a000daae113425fc3c7152c058c2e836cb5630fa58ef060fb099179eddf6119592e25e51cb7ad0380791cd7468a1cac

data/.standard.yml

@@ -0,0 +1,3 @@
+# For available configuration options, see:
+#   https://github.com/testdouble/standard
+ruby_version: 2.6

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2022-11-18
+
+- Initial release

data/Gemfile

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in quo.gemspec
+gemspec
+
+gem "sqlite3"
+
+gem "rails", ">= 6"
+
+gem "rake", "~> 13.0"
+
+gem "minitest", "~> 5.0"
+
+gem "standard", "~> 1.3"

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 Stephen Ierodiaconou
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,350 @@
+# Quo
+
+Quo query objects can help you abstract ActiveRecord DB queries into reusable and composable objects with a chainable
+interface.
+
+The query object can also abstract over any array-like collection meaning that it is possible for example to cache the
+data from a query and reuse it.
+
+The core implementation provides the following functionality:
+
+* wrap around an underlying ActiveRecord or array-like collection
+* optionally provides paging behaviour to ActiveRecord based queries
+* provides a number of utility methods that operate on the underlying collection (eg `exists?`)
+* provides a `+` (`compose`) method which merges two query object instances (see section below for details!)
+* can specify a mapping or transform method to `transform` to perform on results
+* in development outputs the callstack that led to the execution of the query
+* acts as a callable which executes the underlying query with `.first`
+* can return an `Enumerable` of results
+
+## Creating a Quo query object
+
+The query object must inherit from `Quo::Query` and provide an implementation for the `query` method.
+
+The `query` method must return either:
+
+- an `ActiveRecord::Relation`
+- an Array (an 'eager loaded' query) 
+- or another `Quo::Query` instance.
+
+Remember that the query object should be useful in composition with other query objects. Thus it should not directly 
+specify things that are not directly needed to fetch the right data for the given context. 
+
+For example the ordering of the results is mostly something that is specified when the query object is used, not as
+part of the query itself (as then it would always enforce the ordering on other queries it was composed with).
+
+## Passing options to queries
+
+If any parameters are need in `query`, these are provided when instantiating the query object using the `options` hash.
+
+It is also possible to pass special configuration options to the constructor options hash. 
+
+Specifically when the underlying collection is a ActiveRecord relation then:
+
+* `order`: the `order` condition for the relation (eg `:desc`)
+* `includes`: the `includes` condition for the relation (eg `account: {user: :profile}`)
+* `group`: the `group` condition for the relation
+* `page`: the current page number to fetch
+* `page_size`: the number of elements to fetch in the page
+
+Note that the above options have no bearing on the query if it is backed by an array-like collection and that some
+options can be configured using the following methods.
+
+## Configuring queries
+
+Note that it is possible to configure a query using chainable methods similar to ActiveRecord:
+
+* limit
+* order
+* group
+* includes
+* left_outer_joins
+* preload
+* joins
+
+Note that these return a new Quo Query and do not mutate the original instance.
+
+## Composition of queries (merging or combining them)
+
+Quo query objects are composeability. In `ActiveRecord::Relation` this is acheived using `merge`
+and so under the hood `Quo::Query` uses that when composing relations. However since Queries can also abstract over
+array-like collections (ie enumerable and define a `+` method) compose also handles concating them together.
+
+Composing can be done with either 
+
+- `Quo::Query.compose(left, right)` 
+- or `left.compose(right)` 
+- or more simply with `left + right`
+
+The composition methods also accept an optional parameter to pass to ActiveRecord relation merges for the `joins`. 
+This allows you to compose together Query objects which return relations which are of different models but still merge 
+them correctly with the appropriate joins. Note with the alias you cant neatly specify optional parameters for joins
+on relations.
+
+Note that the compose process creates a new query object instance, which is a instance of a `Quo::MergedQuery`.
+
+Consider the following cases:
+
+1. compose two query objects which return `ActiveRecord::Relation`s
+2. compose two query objects, one of which returns a `ActiveRecord::Relation`, and the other an array-like
+3. compose two query objects which return array-likes
+
+In case (1) the compose process uses `ActiveRecords::Relation`'s `merge` method to create another query object
+wrapped around a new 'composed' `ActiveRecords::Relation`.
+
+In case (2) the query object with a `ActiveRecords::Relation` inside is executed, and the result is then concatenated
+to the array-like with `+`
+
+In case (3) the values contained with each 'eager' query object are concatenated with `+`
+
+*Note that*
+
+with `left.compose(right)`, `left` must obviously be an instance of a `Quo::Query`, and `right` can be either a
+query object or and `ActiveRecord::Relation`. However `Quo::Query.compose(left, right)` also accepts
+`ActiveRecord::Relation`s for left.
+
+### Examples
+
+```ruby
+class CompanyToBeApproved < Quo::Query
+  def query
+    Registration
+      .left_joins(:approval)
+      .where(approvals: {completed_at: nil})
+  end
+end
+
+class CompanyInUsState < Quo::Query
+  def query
+    Registration
+      .joins(company: :address)
+      .where(addresses: {state: options[:state]})
+  end
+end
+
+query1 = CompanyToBeApproved.new
+query2 = CompanyInUsState.new(state: "California")
+
+# Compose
+composed = query1 + query2 # or Quo::Query.compose(query1, query2) or query1.compose(query2)
+composed.first
+```
+
+This effectively executes:
+
+```ruby
+Registration
+  .left_joins(:approval)
+  .joins(company: :address)
+  .where(approvals: {completed_at: nil})
+  .where(addresses: {state: options[:state]})
+```
+
+It is also possible to compose with an `ActiveRecord::Relation`. This can be useful in a Query object itself to help
+build up the `query` relation. For example:
+
+```ruby
+class RegistrationToBeApproved < Quo::Query
+  def query
+    done = Registration.where(step: "complete")
+    approved = CompanyToBeApproved.new
+    done + approved
+  end
+end
+```
+
+Also you can use joins:
+
+```ruby
+class TagByName < Quo::Query
+  def query
+    Tag.where(name: options[:name])
+  end
+end
+
+class CategoryByName < Quo::Query
+  def query
+    Category.where(name: options[:name])
+  end
+end
+
+tags = TagByName.new(name: "Intel")
+for_category = CategoryByName.new(name: "CPUs")
+tags.compose(for_category, :category) # perform join on tag association `category`
+
+# equivalent to Tag.joins(:category).where(name: "Intel").where(categories: {name: "CPUs"})
+```
+
+Eager loaded queries can also be composed (see below sections for more details).
+
+### Quo::MergedQuery
+
+The new instance of `Quo::MergedQuery` from a compose process, retains references to the original entities that were
+composed. These are then used to create a more useful output from `to_s`, so that it is easier to understand what the
+merged query is actually made up of:
+
+```ruby
+q = FooQuery.new + BarQuery.new
+puts q
+# > "Quo::MergedQuery[FooQuery, BarQuery]"
+```
+
+## Query Objects & Pagination
+
+Specify extra options to enable pagination:
+
+* `page`: the current page number to fetch
+* `page_size`: the number of elements to fetch in the page
+
+## 'Eager loaded' Quo::Query objects
+
+When a query object returns an `Array` from `query` it is assumed as 'eager loaded', ie that the query has actually
+already been executed and the array contains the return values. This can also be used to encapsulate data that doesn't
+actually come from an ActiveRecord query.
+
+For example, the Query below executes the query inside on the first call and memoises the resulting data. Note
+however that this then means that this Query is not reusuable to `merge` with other ActiveRecord queries. If it is
+`compose`d with other Query objects then it will be seen as an array-like, and concatenated to whatever it is being
+joined to.
+
+```ruby
+class CachedTags < Quo::Query
+  def query
+    @tags ||= Tag.where(active: true).to_a
+  end
+end
+
+q = CachedTags.new(active: false)
+q.eager? # is it 'eager'? Yes it is!
+q.count # array size
+```
+
+### `Quo::EagerQuery` objects
+
+`Quo::EagerQuery` is a subclass of `Quo::Query` which takes a data value on instantiation and returns it on calls to `query`
+
+```ruby
+q = Quo::EagerQuery.new(collection: [1, 2, 3])
+q.eager? # is it 'eager'? Yes it is!
+q.count # '3'
+```
+
+This is useful to create eager loaded Queries without needing to create a explicit subclass of your own.
+
+`Quo::EagerQuery` also uses `total_count` option value as the specified 'total count', useful when the data is
+actually just a page of the data and not the total count.
+
+Example of an EagerQuery used to wrap a page of enumerable data:
+
+```ruby
+Quo::EagerQuery.new(collection: my_data, total_count: 100, page: current_page)
+```
+
+### Composition
+
+Examples of composition of eager loaded queries
+
+```ruby
+class CachedTags < Quo::Query
+  def query
+    @tags ||= Tag.where(active: true).to_a
+  end
+end
+
+composed = CachedTags.new(active: false) + [1, 2]
+composed.last
+# => 2
+composed.first
+# => #<Tag id: ...>
+
+Quo::EagerQuery.new([3, 4]).compose(Quo::EagerQuery.new(collection: [1, 2])).last
+# => 2
+Quo::Query.compose([1, 2], [3, 4]).last
+# => 4
+```
+
+## Transforming results
+
+Sometimes you want to specify a block to execute on each result for any method that returns results, such as `first`,
+`last` and `each`.
+
+This can be specified using the `transform(&block)` instance method. For example:
+
+```ruby
+TagsQuery.new(
+  active: [true, false],
+  page: 1,
+  page_size: 30,
+).transform { |tag| TagPresenter.new(tag) }
+ .first
+# => #<TagPresenter ...>
+```
+
+## Tests & stubbing
+
+Tests for Query objects themselves should exercise the actual underlying query. But in other code stubbing the query
+maybe desirable.
+
+The spec helper method `stub_query(query_class, {results: ..., with: ...})` can do this for you.
+
+It stubs `.new` on the Query object and returns instances of `EagerQuery` instead with the given `results`. 
+The `with` option is passed to the Query object on initialisation and used when setting up the method stub on the 
+query class.
+
+For example:
+
+```ruby
+stub_query(TagQuery, with: {name: "Something"}, results: [t1, t2])
+expect(TagQuery.new(name: "Something").first).to eql t1
+```
+
+*Note that*
+
+This returns an instance of EagerQuery, so will not work for cases were the actual type of the query instance is
+important or where you are doing a composition of queries backed by relations!
+
+If `compose` will be used then `Quo::Query.compose` needs to be stubbed. Something might be possible to make this
+nicer in future.
+
+## Other reading
+
+See:
+* [Includes vs preload vs eager_load](http://blog.scoutapp.com/articles/2017/01/24/activerecord-includes-vs-joins-vs-preload-vs-eager_load-when-and-where)
+* [Objects on Rails](http://objectsonrails.com/#sec-14)
+
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+    $ bundle add quo
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+    $ gem install quo
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/stevegeek/quo.
+
+## Inspired by `rectify`
+
+Note this implementation is loosely based on that in the `Rectify` gem; https://github.com/andypike/rectify.
+
+See https://github.com/andypike/rectify#query-objects for more information.
+
+Thanks to Andy Pike for the inspiration.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+end
+
+require "standard/rake"
+
+task default: %i[test standard]

data/lib/quo/eager_query.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Quo
+  class EagerQuery < Quo::Query
+    def initialize(**options)
+      @collection = Array.wrap(options[:collection])
+      super(**options.except(:collection))
+    end
+
+    # Optionally return the `total_count` option
+    def count
+      options[:total_count] || super
+    end
+    alias_method :total_count, :count
+    alias_method :size, :count
+
+    # Is this query object paged? (when no total count)
+    def paged?
+      options[:total_count].nil? && current_page.present?
+    end
+
+    # Return the underlying collection
+    def query
+      preload_includes(collection) if options[:includes]
+      collection
+    end
+
+    def relation?
+      false
+    end
+
+    def eager?
+      true
+    end
+
+    protected
+
+    attr_reader :collection
+
+    def preload_includes(records, preload = nil)
+      ::ActiveRecord::Associations::Preloader.new(
+        records: records,
+        associations: preload || options[:includes]
+      )
+    end
+  end
+end

data/lib/quo/enumerator.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require "forwardable"
+require_relative "./utilities/callstack"
+
+module Quo
+  class Enumerator
+    extend Forwardable
+    include Quo::Utilities::Callstack
+
+    def initialize(query, transformer: nil)
+      @query = query
+      @unwrapped = query.unwrap
+      @transformer = transformer
+    end
+
+    def_delegators :unwrapped,
+      :include?,
+      :member?,
+      :all?,
+      :any?,
+      :none?,
+      :one?,
+      :tally,
+      :count,
+      :group_by,
+      :partition,
+      :slice_before,
+      :slice_after,
+      :slice_when,
+      :chunk,
+      :chunk_while,
+      :sum,
+      :zip
+
+    # Delegate other enumerable methods to underlying collection but also transform
+    def method_missing(method, *args, &block)
+      if unwrapped.respond_to?(method)
+        debug_callstack
+        if block
+          unwrapped.send(method, *args) do |*block_args|
+            x = block_args.first
+            transformed = transformer.present? ? transformer.call(x) : x
+            block.call(transformed, *block_args[1..])
+          end
+        else
+          raw = unwrapped.send(method, *args)
+          return raw if raw.is_a?(Quo::Enumerator) || raw.is_a?(::Enumerator)
+          transform_results(raw)
+        end
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(method, include_private = false)
+      Enumerable.instance_methods.include?(method) || super
+    end
+
+    private
+
+    attr_reader :transformer, :unwrapped
+
+    def transform_results(results)
+      return results unless transformer.present?
+
+      if results.is_a?(Enumerable)
+        results.map.with_index { |item, i| transformer.call(item, i) }
+      else
+        transformer.call(results)
+      end
+    end
+  end
+end

data/lib/quo/merged_query.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Quo
+  class MergedQuery < Quo::Query
+    def initialize(options, source_queries = [])
+      @source_queries = source_queries
+      super(**options)
+    end
+
+    def query
+      @scope
+    end
+
+    def to_s
+      left = operand_desc(source_queries_left)
+      right = operand_desc(source_queries_right)
+      "Quo::MergedQuery[#{left}, #{right}]"
+    end
+
+    private
+
+    def source_queries_left
+      source_queries&.first
+    end
+
+    def source_queries_right
+      source_queries&.last
+    end
+
+    attr_reader :source_queries
+
+    def operand_desc(operand)
+      return unless operand
+      if operand.is_a? Quo::MergedQuery
+        operand.to_s
+      else
+        operand.class.name
+      end
+    end
+  end
+end

data/lib/quo/query.rb

@@ -0,0 +1,276 @@
+# frozen_string_literal: true
+
+require_relative "./utilities/callstack"
+require_relative "./utilities/compose"
+require_relative "./utilities/sanitize"
+require_relative "./utilities/wrap"
+
+module Quo
+  class Query
+    include Quo::Utilities::Callstack
+
+    extend Quo::Utilities::Compose
+    extend Quo::Utilities::Sanitize
+    extend Quo::Utilities::Wrap
+
+    class << self
+      # Execute the query and return the first item
+      def call(**options)
+        new(**options).first
+      end
+
+      # Execute the query and return the first item, or raise an error if no item is found
+      def call!(**options)
+        new(**options).first!
+      end
+    end
+
+    attr_reader :current_page, :page_size, :options
+
+    def initialize(**options)
+      @options = options
+      @current_page = options[:page]&.to_i || options[:current_page]&.to_i
+      @page_size = options[:page_size]&.to_i || 20
+      @scope = unwrap_relation(options[:scope])
+    end
+
+    # Returns a active record query, or a Quo::Query instance
+    # You must provide an implementation of this of pass the 'scope' option on instantiation
+    def query
+      return @scope unless @scope.nil?
+      raise NotImplementedError, "Query objects must define a 'query' method"
+    end
+
+    # Combine (compose) this query object with another composeable entity, see notes for `.compose` above.
+    # Compose is aliased as `+`. Can optionally take `joins()` parameters to perform a joins before the merge
+    def compose(right, joins = nil)
+      Quo::QueryComposer.new(self, right, joins).compose
+    end
+
+    alias_method :+, :compose
+
+    def copy(**options)
+      self.class.new(**@options.merge(options))
+    end
+
+    # Methods to prepare the query
+    def limit(limit)
+      copy(limit: limit)
+    end
+
+    def order(options)
+      copy(order: options)
+    end
+
+    def group(*options)
+      copy(group: options)
+    end
+
+    def includes(*options)
+      copy(includes: options)
+    end
+
+    def preload(*options)
+      copy(preload: options)
+    end
+
+    def select(*options)
+      copy(select: options)
+    end
+
+    # The following methods actually execute the underlying query
+
+    # Delegate SQL calculation methods to the underlying query
+    delegate :sum, :average, :minimum, :maximum, to: :query_with_logging
+
+    # Gets the count of all results ignoring the current page and page size (if set)
+    delegate :count, to: :underlying_query
+    alias_method :total_count, :count
+    alias_method :size, :count
+
+    # Gets the actual count of elements in the page of results (assuming paging is being used, otherwise the count of
+    # all results)
+    def page_count
+      query_with_logging.count
+    end
+
+    # Delegate methods that let us get the model class (available on AR relations)
+    delegate :model, :klass, to: :underlying_query
+
+    # Get first elements
+    def first(*args)
+      if transform?
+        res = query_with_logging.first(*args)
+        if res.is_a? Array
+          res.map.with_index { |r, i| transformer.call(r, i) }
+        elsif !res.nil?
+          transformer.call(query_with_logging.first(*args))
+        end
+      else
+        query_with_logging.first(*args)
+      end
+    end
+
+    def first!(*args)
+      item = first(*args)
+      raise ActiveRecord::RecordNotFound, "No item could be found!" unless item
+      item
+    end
+
+    # Get last elements
+    def last(*args)
+      if transform?
+        res = query_with_logging.last(*args)
+        if res.is_a? Array
+          res.map.with_index { |r, i| transformer.call(r, i) }
+        elsif !res.nil?
+          transformer.call(query_with_logging.last(*args))
+        end
+      else
+        query_with_logging.last(*args)
+      end
+    end
+
+    # Convert to array
+    def to_a
+      arr = query_with_logging.to_a
+      transform? ? arr.map.with_index { |r, i| transformer.call(r, i) } : arr
+    end
+
+    # Convert to EagerQuery, and load all data
+    def to_eager(more_opts = {})
+      Quo::EagerQuery.new(collection: to_a, **options.merge(more_opts))
+    end
+    alias_method :load, :to_eager
+
+    # Return an enumerable
+    def enumerator
+      Quo::Enumerator.new(self, transformer: transformer)
+    end
+
+    # Some convenience methods for iterating over the results
+    delegate :each, :map, :flat_map, :reduce, :reject, :filter, to: :enumerator
+
+    # Set a block used to transform data after query fetching
+    def transform(&block)
+      @options[:__transformer] = block
+      self
+    end
+
+    # Are there any results for this query?
+    def exists?
+      return query_with_logging.exists? if relation?
+      query_with_logging.present?
+    end
+
+    # Are there no results for this query?
+    def none?
+      !exists?
+    end
+    alias_method :empty?, :none?
+
+    # Is this query object a relation under the hood? (ie not eager loaded)
+    def relation?
+      test_relation(configured_query)
+    end
+
+    # Is this query object eager loaded data under the hood? (ie not a relation)
+    def eager?
+      test_eager(configured_query)
+    end
+
+    # Is this query object paged? (ie is paging enabled)
+    def paged?
+      current_page.present?
+    end
+
+    # Is this query object transforming results?
+    def transform?
+      transformer.present?
+    end
+
+    # Return the SQL string for this query if its a relation type query object
+    def to_sql
+      configured_query.to_sql if relation?
+    end
+
+    # Unwrap the underlying query
+    def unwrap
+      configured_query
+    end
+
+    delegate :distinct, to: :configured_query
+
+    protected
+
+    def formatted_queries?
+      Quo.configuration&.formatted_query_log
+    end
+
+    # 'trim' a query, ie remove comments and remove newlines
+    # This will remove dashes from inside strings too
+    def trim_query(sql)
+      sql.gsub(/--[^\n'"]*\n/m, " ").tr("\n", " ").strip
+    end
+
+    def format_query(sql_str)
+      formatted_queries? ? sql_str : trim_query(sql_str)
+    end
+
+    def transformer
+      options[:__transformer]
+    end
+
+    def offset
+      per_page = sanitised_page_size
+      page = current_page.positive? ? current_page : 1
+      per_page * (page - 1)
+    end
+
+    # The configured query is the underlying query with paging
+    def configured_query
+      q = underlying_query
+      return q unless paged? && q.is_a?(ActiveRecord::Relation)
+      q.offset(offset).limit(sanitised_page_size)
+    end
+
+    def sanitised_page_size
+      (page_size.present? && page_size.positive?) ? [page_size.to_i, 200].min : 20
+    end
+
+    def query_with_logging
+      debug_callstack
+      configured_query
+    end
+
+    # The underlying query is essentially the configured query with optional extras setup
+    def underlying_query
+      @underlying_query ||=
+        begin
+          rel = unwrap_relation(query)
+          unless test_eager(rel)
+            rel = rel.group(@options[:group]) if @options[:group].present?
+            rel = rel.order(@options[:order]) if @options[:order].present?
+            rel = rel.limit(@options[:limit]) if @options[:limit].present?
+            rel = rel.preload(@options[:preload]) if @options[:preload].present?
+            rel = rel.includes(@options[:includes]) if @options[:includes].present?
+            rel = rel.joins(@options[:joins]) if @options[:joins].present?
+            rel = rel.select(@options[:select]) if @options[:select].present?
+          end
+          rel
+        end
+    end
+
+    def unwrap_relation(query)
+      query.is_a?(Quo::Query) ? query.unwrap : query
+    end
+
+    def test_eager(rel)
+      rel.is_a?(Enumerable) && !test_relation(rel)
+    end
+
+    def test_relation(rel)
+      rel.is_a?(ActiveRecord::Relation)
+    end
+  end
+end

data/lib/quo/query_composer.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module Quo
+  class QueryComposer
+    def initialize(left, right, joins = nil)
+      @left = left
+      @right = right
+      @joins = joins
+    end
+
+    def compose
+      combined = merge
+      Quo::MergedQuery.new(
+        merged_options.merge({scope: combined, source_queries: [left, right]})
+      )
+    end
+
+    private
+
+    attr_reader :left, :right, :joins
+
+    def merge
+      left_rel, right_rel = unwrap_relations
+      left_type, right_type = relation_types?
+      if both_relations?(left_type, right_type)
+        apply_joins(left_rel, joins).merge(right_rel)
+      elsif left_relation_right_eager?(left_type, right_type)
+        left_rel.to_a + right_rel
+      elsif left_eager_right_relation?(left_rel, left_type, right_type)
+        left_rel + right_rel.to_a
+      elsif both_eager_loaded?(left_rel, left_type, right_type)
+        left_rel + right_rel
+      else
+        raise_error
+      end
+    end
+
+    def merged_options
+      return left.options.merge(right.options) if left.is_a?(Quo::Query) && right.is_a?(Quo::Query)
+      return left.options if left.is_a?(Quo::Query)
+      return right.options if right.is_a?(Quo::Query)
+      {}
+    end
+
+    def relation_types?
+      [left, right].map do |query|
+        if query.is_a?(Quo::Query)
+          query.relation?
+        else
+          query.is_a?(ActiveRecord::Relation)
+        end
+      end
+    end
+
+    def apply_joins(left_rel, joins)
+      joins.present? ? left_rel.joins(joins.to_sym) : left_rel
+    end
+
+    def both_relations?(left_rel_type, right_rel_type)
+      left_rel_type && right_rel_type
+    end
+
+    def left_relation_right_eager?(left_rel_type, right_rel_type)
+      left_rel_type && !right_rel_type
+    end
+
+    def left_eager_right_relation?(left_rel, left_rel_type, right_rel_type)
+      !left_rel_type && right_rel_type && left_rel.respond_to?(:+)
+    end
+
+    def both_eager_loaded?(left_rel, left_rel_type, right_rel_type)
+      !left_rel_type && !right_rel_type && left_rel.respond_to?(:+)
+    end
+
+    def unwrap_relations
+      [left, right].map { |query| query.is_a?(Quo::Query) ? query.unwrap : query }
+    end
+
+    def raise_error
+      raise ArgumentError, "Unable to composite queries #{left.class.name} and " \
+            "#{right.class.name}. You cannot compose queries where #query " \
+            "returns an ActiveRecord::Relation in one and an Enumerable in the other."
+    end
+  end
+end

data/lib/quo/railtie.rb

@@ -0,0 +1,7 @@
+module Quo
+  class Railtie < ::Rails::Railtie
+    # rake_tasks do
+    #   load "tasks/quo.rake"
+    # end
+  end
+end

data/lib/quo/rspec/helpers.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Quo
+  module Rspec
+    module Helpers
+      def stub_query(query_class, options = {})
+        results = options.fetch(:results, [])
+        with = options[:with]
+        unless with.nil?
+          return(
+            allow(query_class).to receive(:new)
+                                    .with(with) { ::Quo::EagerQuery.new(collection: results) }
+          )
+        end
+        allow(query_class).to receive(:new) { ::Quo::EagerQuery.new(collection: results) }
+      end
+    end
+  end
+end

data/lib/quo/utilities/callstack.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Quo
+  module Utilities
+    module Callstack
+      def debug_callstack
+        return unless Quo.configuration&.query_show_callstack_size&.positive? && Rails.env.development?
+        max_stack = Quo.configuration.query_show_callstack_size
+        working_dir = Dir.pwd
+        exclude = %r{/(gems/|rubies/|query\.rb)}
+        stack = Kernel.caller.grep_v(exclude).map { |l| l.gsub(working_dir + "/", "") }
+        trace_message = stack[0..max_stack].join("\n               &> ")
+        message = "\n[Query stack]: -> #{trace_message}\n"
+        message += " (truncated to #{max_stack} most recent)" if stack.size > max_stack
+        Quo.configuration.logger&.info(message)
+      end
+    end
+  end
+end

data/lib/quo/utilities/compose.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Quo
+  module Utilities
+    module Compose
+      # Combine two query-like or composeable entities:
+      # These can be Quo::Query, Quo::MergedQuery, Quo::EagerQuery and ActiveRecord::Relations.
+      # See the `README.md` docs for more details.
+      def compose(query1, query2, joins = nil)
+        Quo::QueryComposer.new(query1, query2, joins).compose
+      end
+
+      # Determines if the object `query` is something which can be composed with query objects
+      def composable_with?(query)
+        query.is_a?(Quo::Query) || query.is_a?(ActiveRecord::Relation)
+      end
+    end
+  end
+end

data/lib/quo/utilities/sanitize.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Quo
+  module Utilities
+    module Sanitize
+      # ActiveRecord::Sanitization wrappers
+      def sanitize_sql_for_conditions(conditions)
+        ActiveRecord::Base.sanitize_sql_for_conditions(conditions)
+      end
+
+      def sanitize_sql_string(string)
+        sanitize_sql_for_conditions(["'%s'", string])
+      end
+
+      def sanitize_sql_parameter(value)
+        sanitize_sql_for_conditions(["?", value])
+      end
+    end
+  end
+end

data/lib/quo/utilities/wrap.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Quo
+  module Utilities
+    module Wrap
+      # Wrap a relation in a Query. If the passed in object is already a query object then just return it
+      def wrap(query_rel_or_data, **options)
+        if query_rel_or_data.is_a?(Quo::Query) && options.present?
+          return query_rel_or_data.copy(**options)
+        end
+        return query_rel_or_data if query_rel_or_data.is_a? Quo::Query
+        if query_rel_or_data.is_a? ActiveRecord::Relation
+          return new(**options.merge(scope: query_rel_or_data))
+        end
+        Quo::EagerQuery.new(**options.merge(collection: query_rel_or_data))
+      end
+    end
+  end
+end

data/lib/quo/version.rb

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

data/lib/quo.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "quo/version"
+require_relative "quo/query"
+require_relative "quo/eager_query"
+require_relative "quo/merged_query"
+require_relative "quo/query_composer"
+require_relative "quo/enumerator"
+
+module Quo
+  class << self
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration) if block_given?
+      configuration
+    end
+  end
+
+  class Configuration
+    attr_accessor :formatted_query_log, :query_show_callstack_size, :logger
+
+    def initialize
+      @formatted_query_log = true
+      @query_show_callstack_size = 10
+      @logger = nil
+    end
+  end
+end

data/sig/quo.rbs

@@ -0,0 +1,4 @@
+module Quo
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,79 @@
+--- !ruby/object:Gem::Specification
+name: quo
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Stephen Ierodiaconou
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2022-11-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6'
+description: Quo query objects are composable.
+email:
+- stevegeek@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".standard.yml"
+- CHANGELOG.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/quo.rb
+- lib/quo/eager_query.rb
+- lib/quo/enumerator.rb
+- lib/quo/merged_query.rb
+- lib/quo/query.rb
+- lib/quo/query_composer.rb
+- lib/quo/railtie.rb
+- lib/quo/rspec/helpers.rb
+- lib/quo/utilities/callstack.rb
+- lib/quo/utilities/compose.rb
+- lib/quo/utilities/sanitize.rb
+- lib/quo/utilities/wrap.rb
+- lib/quo/version.rb
+- sig/quo.rbs
+homepage: https://github.com/stevegeek/quo
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/stevegeek/quo
+  source_code_uri: https://github.com/stevegeek/quo
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.7.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.7
+signing_key:
+specification_version: 4
+summary: Quo is a query object gem for Rails
+test_files: []