quo 0.6.0 → 1.0.0.beta1

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: quo
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 1.0.0.beta1
 platform: ruby
 authors:
 - Stephen Ierodiaconou
-autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-03-19 00:00:00.000000000 Z
+date: 2025-03-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -16,40 +15,74 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6'
+        version: '7'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '8'
+        version: '9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6'
+        version: '7'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '8'
+        version: '9'
 - !ruby/object:Gem::Dependency
   name: activesupport
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6'
+        version: '7'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '8'
+        version: '9'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6'
+        version: '7'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '8'
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: literal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.6.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.6.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+- !ruby/object:Gem::Dependency
+  name: appraisal
+  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: Quo query objects are composable.
 email:
 - stevegeek@gmail.com
@@ -58,48 +91,56 @@ extensions: []
 extra_rdoc_files: []
 files:
 - ".standard.yml"
+- Appraisals
 - CHANGELOG.md
 - Gemfile
 - LICENSE.txt
 - README.md
 - Rakefile
 - Steepfile
+- gemfiles/rails_7.0.gemfile
+- gemfiles/rails_7.1.gemfile
+- gemfiles/rails_7.2.gemfile
+- gemfiles/rails_8.0.gemfile
 - lib/quo.rb
-- lib/quo/eager_query.rb
-- lib/quo/loaded_query.rb
-- lib/quo/merged_query.rb
+- lib/quo/collection_backed_query.rb
+- lib/quo/collection_results.rb
+- lib/quo/composed_query.rb
+- lib/quo/engine.rb
+- lib/quo/minitest/helpers.rb
+- lib/quo/preloadable.rb
 - lib/quo/query.rb
-- lib/quo/query_composer.rb
-- lib/quo/railtie.rb
+- lib/quo/relation_backed_query.rb
+- lib/quo/relation_backed_query_specification.rb
+- lib/quo/relation_results.rb
 - lib/quo/results.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/testing/collection_backed_fake.rb
+- lib/quo/testing/relation_backed_fake.rb
 - lib/quo/version.rb
-- lib/quo/wrapped_query.rb
 - lib/tasks/quo.rake
 - rbs_collection.yaml
-- sig/quo.rbs
-- sig/quo/eager_query.rbs
-- sig/quo/loaded_query.rbs
-- sig/quo/merged_query.rbs
-- sig/quo/query.rbs
-- sig/quo/query_composer.rbs
-- sig/quo/results.rbs
-- sig/quo/utilities/callstack.rbs
-- sig/quo/utilities/compose.rbs
-- sig/quo/utilities/sanitize.rbs
-- sig/quo/utilities/wrap.rbs
-- sig/quo/wrapped_query.rbs
+- sig/generated/quo.rbs
+- sig/generated/quo/collection_backed_query.rbs
+- sig/generated/quo/collection_results.rbs
+- sig/generated/quo/composed_query.rbs
+- sig/generated/quo/engine.rbs
+- sig/generated/quo/preloadable.rbs
+- sig/generated/quo/query.rbs
+- sig/generated/quo/relation_backed_query.rbs
+- sig/generated/quo/relation_backed_query_specification.rbs
+- sig/generated/quo/relation_results.rbs
+- sig/generated/quo/results.rbs
+- sig/generated/quo/testing/collection_backed_fake.rbs
+- sig/generated/quo/testing/relation_backed_fake.rbs
+- sig/generated/quo/version.rbs
+- sig/literal.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
@@ -107,15 +148,14 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 2.7.0
+      version: 3.1.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.3
-signing_key:
+rubygems_version: 3.6.2
 specification_version: 4
 summary: Quo is a query object gem for Rails
 test_files: []

data/lib/quo/eager_query.rb

@@ -1,51 +0,0 @@
-# frozen_string_literal: true
-
-module Quo
-  class EagerQuery < Quo::Query
-    # Optionally return the `total_count` option if it has been set.
-    # This is useful when the total count is known and not equal to size
-    # of wrapped collection.
-    def count
-      options[:total_count] || super
-    end
-
-    # Is this query object paged? (when no total count)
-    def paged?
-      options[:total_count].nil? && current_page.present?
-    end
-
-    def collection
-      raise NotImplementedError, "EagerQuery objects must define a 'collection' method"
-    end
-
-    def query
-      preload_includes(collection) if options[:includes]
-      collection
-    end
-
-    def relation?
-      false
-    end
-
-    def eager?
-      true
-    end
-
-    private
-
-    def underlying_query
-      unwrap_relation(query)
-    end
-
-    def unwrap_relation(query)
-      query.is_a?(Quo::Query) ? query.unwrap : query
-    end
-
-    def preload_includes(records, preload = nil)
-      ::ActiveRecord::Associations::Preloader.new(
-        records: records,
-        associations: preload || options[:includes]
-      ).call
-    end
-  end
-end

data/lib/quo/loaded_query.rb

@@ -1,18 +0,0 @@
-# frozen_string_literal: true
-
-module Quo
-  class LoadedQuery < Quo::EagerQuery
-    def initialize(collection, **options)
-      @collection = collection
-      super(**options)
-    end
-
-    def copy(**options)
-      self.class.new(@collection, **@options.merge(options))
-    end
-
-    private
-
-    attr_reader :collection
-  end
-end

data/lib/quo/merged_query.rb

@@ -1,36 +0,0 @@
-# frozen_string_literal: true
-
-module Quo
-  class MergedQuery < Quo::Query
-    def initialize(merged_query, left, right, **options)
-      @merged_query = merged_query
-      @left = left
-      @right = right
-      super(**options)
-    end
-
-    def query
-      @merged_query
-    end
-
-    def copy(**options)
-      self.class.new(query, left, right, **@options.merge(options))
-    end
-
-    def inspect
-      "Quo::MergedQuery[#{operand_desc(left)}, #{operand_desc(right)}]"
-    end
-
-    private
-
-    attr_reader :left, :right
-
-    def operand_desc(operand)
-      if operand.is_a? Quo::MergedQuery
-        operand.inspect
-      else
-        operand.class.name || "(anonymous)"
-      end
-    end
-  end
-end

data/lib/quo/query_composer.rb

@@ -1,78 +0,0 @@
-# frozen_string_literal: true
-
-module Quo
-  class QueryComposer
-    def initialize(left, right, joins = nil)
-      @left = left
-      @right = right
-      @unwrapped_left = unwrap_relation(left)
-      @unwrapped_right = unwrap_relation(right)
-      @left_relation = @unwrapped_left.is_a?(::ActiveRecord::Relation)
-      @right_relation = @unwrapped_right.is_a?(::ActiveRecord::Relation)
-      @joins = joins
-    end
-
-    def compose
-      Quo::MergedQuery.new(
-        merge_left_and_right,
-        left,
-        right,
-        **merged_options
-      )
-    end
-
-    private
-
-    attr_reader :left, :right, :joins, :unwrapped_left, :unwrapped_right
-
-    def left_relation?
-      @left_relation
-    end
-
-    def right_relation?
-      @right_relation
-    end
-
-    def merge_left_and_right
-      # FIXME: Skipping type checks here, as not sure how to make this type check with RBS
-      __skip__ = if both_relations?
-        apply_joins(unwrapped_left, joins).merge(unwrapped_right)
-      elsif left_relation_right_enumerable?
-        unwrapped_left.to_a + unwrapped_right
-      elsif left_enumerable_right_relation? && unwrapped_left.respond_to?(:+)
-        unwrapped_left + unwrapped_right.to_a
-      elsif unwrapped_left.respond_to?(:+)
-        unwrapped_left + unwrapped_right
-      else
-        raise ArgumentError, "Cannot merge #{left.class} with #{right.class}"
-      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 unwrap_relation(query)
-      query.is_a?(Quo::Query) ? query.unwrap : query
-    end
-
-    def apply_joins(left_rel, joins)
-      joins.present? ? left_rel.joins(joins) : left_rel
-    end
-
-    def both_relations?
-      left_relation? && right_relation?
-    end
-
-    def left_relation_right_enumerable?
-      left_relation? && !right_relation?
-    end
-
-    def left_enumerable_right_relation?
-      !left_relation? && right_relation?
-    end
-  end
-end

data/lib/quo/railtie.rb

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

data/lib/quo/utilities/callstack.rb

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

data/lib/quo/utilities/compose.rb

@@ -1,18 +0,0 @@
-# frozen_string_literal: true
-
-module Quo
-  module Utilities
-    # 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.
-    module Compose
-      def compose(query1, query2, joins: nil)
-        Quo::QueryComposer.new(query1, query2, joins).compose
-      end
-
-      def composable_with?(query)
-        query.is_a?(Quo::Query) || query.is_a?(ActiveRecord::Relation)
-      end
-    end
-  end
-end

data/lib/quo/utilities/sanitize.rb

@@ -1,19 +0,0 @@
-# frozen_string_literal: true
-
-module Quo
-  module Utilities
-    module Sanitize
-      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

@@ -1,23 +0,0 @@
-# frozen_string_literal: true
-
-module Quo
-  module Utilities
-    # Wrap a ActiveRecord::Relation or data collection in a Query.
-    #
-    # If the passed in object is already a Query object then just return it or copy it if new options are passed in.
-    # Otherwise if a Relation wrap it in a new Query object or else in an EagerQuery .
-    module Wrap
-      def wrap(query_rel_or_data, **options)
-        if query_rel_or_data.is_a? Quo::Query
-          return options.present? ? query_rel_or_data.copy(**options) : query_rel_or_data
-        end
-
-        if query_rel_or_data.is_a? ActiveRecord::Relation
-          Quo::WrappedQuery.new(query_rel_or_data, **options)
-        else
-          Quo::LoadedQuery.new(query_rel_or_data, **options)
-        end
-      end
-    end
-  end
-end

data/lib/quo/wrapped_query.rb

@@ -1,18 +0,0 @@
-# frozen_string_literal: true
-
-module Quo
-  class WrappedQuery < Quo::Query
-    def initialize(wrapped_query, **options)
-      @wrapped_query = wrapped_query
-      super(**options)
-    end
-
-    def copy(**options)
-      self.class.new(query, **@options.merge(options))
-    end
-
-    def query
-      @wrapped_query
-    end
-  end
-end

data/sig/quo/eager_query.rbs

@@ -1,15 +0,0 @@
-module Quo
-  class EagerQuery < Quo::Query
-    def collection: () -> loadedQueryOrEnumerable
-    def query: () -> loadedQueryOrEnumerable
-
-    def relation?: () -> false
-    def eager?: () -> true
-
-    private
-
-    def preload_includes: (untyped records, ?untyped? preload) -> untyped
-    def underlying_query: () -> enumerable
-    def unwrap_relation: (loadedQueryOrEnumerable collection) -> enumerable
-  end
-end

data/sig/quo/loaded_query.rbs

@@ -1,7 +0,0 @@
-module Quo
-  class LoadedQuery < Quo::EagerQuery
-    @collection: enumerable
-
-    def initialize: (enumerable, **untyped options) -> void
-  end
-end

data/sig/quo/merged_query.rbs

@@ -1,19 +0,0 @@
-module Quo
-  class MergedQuery < Quo::Query
-    def self.build_from_options: (queryOptions) -> MergedQuery
-
-    def initialize: (relOrEnumerable merged, composable left, composable right, **untyped options) -> void
-
-    @merged_query: relOrEnumerable
-
-    def query: () -> relOrEnumerable
-
-    def inspect: () -> ::String
-
-    private
-
-    attr_reader left: composable
-    attr_reader right: composable
-    def operand_desc: (composable operand) -> String
-  end
-end

data/sig/quo/query.rbs

@@ -1,83 +0,0 @@
-module Quo
-  class Query
-    include Quo::Utilities::Callstack
-    extend Quo::Utilities::Compose
-    extend Quo::Utilities::Sanitize
-    extend Quo::Utilities::Wrap
-
-    @underlying_query: ActiveRecord::Relation
-
-    def self.call: (**untyped options) -> untyped
-    def self.call!: (**untyped options) -> untyped
-
-    @scope: ActiveRecord::Relation | nil
-
-    attr_reader current_page: Integer?
-    attr_reader page_size: Integer?
-    attr_reader options: Hash[untyped, untyped]
-
-    def initialize: (**untyped options) -> void
-    def query: () -> queryOrRel
-    def compose: (composable right, ?joins: untyped?) -> Quo::MergedQuery
-    alias + compose
-
-    def copy: (**untyped options) -> Quo::Query
-
-    def limit: (untyped limit) -> Quo::Query
-    def order: (untyped options) -> Quo::Query
-    def group: (*untyped options) -> Quo::Query
-    def includes: (*untyped options) -> Quo::Query
-    def preload: (*untyped options) -> Quo::Query
-    def select: (*untyped options) -> Quo::Query
-
-    def sum: (?untyped column_name) -> Numeric
-    def average: (untyped column_name) -> Numeric
-    def minimum: (untyped column_name) -> Numeric
-    def maximum: (untyped column_name) -> Numeric
-    def count: () -> Integer
-
-    alias total_count count
-
-    alias size count
-    def page_count: () -> Integer
-    def first: (?Integer? limit) -> untyped
-    def first!: (?Integer? limit) -> untyped
-    def last: (?Integer? limit) -> untyped
-    def to_a: () -> Array[untyped]
-    def to_eager: (?::Hash[untyped, untyped] more_opts) -> Quo::EagerQuery
-    alias load to_eager
-    def results: () -> Quo::Results
-
-    # Set a block used to transform data after query fetching
-    def transform: () ?{ () -> untyped } -> self
-
-    def exists?: () -> bool
-    def none?: () -> bool
-    alias empty? none?
-    def relation?: () -> bool
-    def eager?: () -> bool
-    def paged?: () -> bool
-
-    def model: () -> (untyped | nil)
-    def klass: () -> (untyped | nil)
-
-    def transform?: () -> bool
-    def to_sql: () -> (String | nil)
-    def unwrap: () -> ActiveRecord::Relation
-
-    private
-
-    def formatted_queries?: () -> bool
-    def trim_query: (String sql) -> String
-    def format_query: (String sql_str) -> String
-    def transformer: () -> (nil | ^(untyped, ?Integer) -> untyped)
-    def offset: () -> Integer
-    def configured_query: () -> ActiveRecord::Relation
-    def sanitised_page_size: () -> Integer
-    def query_with_logging: () -> ActiveRecord::Relation
-    def underlying_query: () -> ActiveRecord::Relation
-    def unwrap_relation: (queryOrRel query) -> ActiveRecord::Relation
-    def test_eager: (composable rel) -> bool
-    def test_relation: (composable rel) -> bool
-  end
-end

data/sig/quo/query_composer.rbs

@@ -1,32 +0,0 @@
-module Quo
-  class QueryComposer
-    @left_relation: bool
-    @right_relation: bool
-
-    def initialize: (composable left, composable right, ?untyped? joins) -> void
-    def compose: () -> Quo::MergedQuery
-
-    private
-
-    attr_reader left: composable
-    attr_reader right: composable
-    attr_reader joins: untyped
-
-    attr_reader unwrapped_left: relOrEnumerable
-    attr_reader unwrapped_right: relOrEnumerable
-
-    def left_relation?: -> bool
-
-    def merge_left_and_right: () -> relOrEnumerable
-    def merged_options: () -> ::Hash[untyped, untyped]
-
-    def right_relation?: -> bool
-
-    def unwrap_relation: (composable) -> relOrEnumerable
-    def relation_type?: (relOrEnumerable) -> bool
-    def apply_joins: (ActiveRecord::Relation left_rel, untyped joins) -> ActiveRecord::Relation
-    def both_relations?: () -> bool
-    def left_relation_right_enumerable?: () -> bool
-    def left_enumerable_right_relation?: () -> bool
-  end
-end

data/sig/quo/results.rbs

@@ -1,22 +0,0 @@
-module Quo
-  class Results
-    extend Forwardable
-
-    include Quo::Utilities::Callstack
-
-    def initialize: (Quo::Query query, ?transformer: (^(untyped, ?Integer) -> untyped)?) -> void
-
-    @query: Quo::Query
-
-    def group_by: () { (untyped, *untyped) -> untyped } -> Hash[untyped, Array[untyped]]
-
-    def respond_to_missing?: (Symbol name, ?bool include_private) -> bool
-
-    private
-
-    attr_reader transformer: (^(untyped, ?Integer) -> untyped)?
-    attr_reader unwrapped: relOrEnumerable
-
-    def transform_results: (untyped) -> untyped
-  end
-end

data/sig/quo/utilities/callstack.rbs

@@ -1,7 +0,0 @@
-module Quo
-  module Utilities
-    module Callstack
-      def debug_callstack: () -> void
-    end
-  end
-end