quo 0.6.0 → 1.0.0.alpha1

data/sig/generated/quo/composed_query.rbs

@@ -0,0 +1,83 @@
+# Generated from lib/quo/composed_query.rb with RBS::Inline
+
+module Quo
+  module ComposedQuery
+    # Combine two Query classes into a new composed query class
+    # Combine two query-like or composeable entities:
+    # These can be Quo::Query, Quo::ComposedQuery, Quo::CollectionBackedQuery and ActiveRecord::Relations.
+    # See the `README.md` docs for more details.
+    # @rbs chosen_superclass: singleton(Quo::RelationBackedQuery | Quo::CollectionBackedQuery)
+    # @rbs left_query_class: singleton(Quo::Query | ::ActiveRecord::Relation)
+    # @rbs right_query_class: singleton(Quo::Query | ::ActiveRecord::Relation)
+    # @rbs joins: untyped
+    # @rbs return: singleton(Quo::ComposedQuery)
+    def composer: (untyped chosen_superclass, untyped left_query_class, untyped right_query_class, ?joins: untyped) -> singleton(Quo::ComposedQuery)
+
+    include Quo::ComposedQuery
+
+    attr_reader _composing_joins: untyped
+
+    attr_reader _left_query: untyped
+
+    attr_reader _right_query: untyped
+
+    def self.inspect: () -> untyped
+
+    # @rbs operand: Quo::ComposedQuery | Quo::Query | ::ActiveRecord::Relation
+    # @rbs return: String
+    def self.quo_operand_desc: (Quo::ComposedQuery | Quo::Query | ::ActiveRecord::Relation operand) -> String
+
+    # We can also merge instance of prepared queries
+    # @rbs left_instance: Quo::Query | ::ActiveRecord::Relation
+    # @rbs right_instance: Quo::Query | ::ActiveRecord::Relation
+    # @rbs joins: untyped
+    # @rbs return: Quo::ComposedQuery
+    def merge_instances: (Quo::Query | ::ActiveRecord::Relation left_instance, Quo::Query | ::ActiveRecord::Relation right_instance, ?joins: untyped) -> Quo::ComposedQuery
+
+    # @rbs override
+    def query: ...
+
+    # @rbs override
+    def inspect: ...
+
+    private
+
+    # @rbs return: Hash[Symbol, untyped]
+    def child_options: (untyped query_class) -> Hash[Symbol, untyped]
+
+    # @rbs return: Array[Symbol]
+    def property_names: (untyped query_class) -> Array[Symbol]
+
+    # @rbs return: Quo::Query | ::ActiveRecord::Relation
+    def left: () -> (Quo::Query | ::ActiveRecord::Relation)
+
+    # @rbs return: Quo::Query | ::ActiveRecord::Relation
+    def right: () -> (Quo::Query | ::ActiveRecord::Relation)
+
+    # @rbs return: ActiveRecord::Relation | CollectionBackedQuery
+    def merge_left_and_right: () -> (ActiveRecord::Relation | CollectionBackedQuery)
+
+    # @rbs left_rel: ActiveRecord::Relation
+    # @rbs return: ActiveRecord::Relation
+    def apply_joins: (ActiveRecord::Relation left_rel) -> ActiveRecord::Relation
+
+    # @rbs rel: untyped
+    # @rbs return: bool
+    def is_relation?: (untyped rel) -> bool
+
+    # @rbs left: untyped
+    # @rbs right: untyped
+    # @rbs return: bool
+    def both_relations?: (untyped left, untyped right) -> bool
+
+    # @rbs left: untyped
+    # @rbs right: untyped
+    # @rbs return: bool
+    def left_relation_right_enumerable?: (untyped left, untyped right) -> bool
+
+    # @rbs left: untyped
+    # @rbs right: untyped
+    # @rbs return: bool
+    def left_enumerable_right_relation?: (untyped left, untyped right) -> bool
+  end
+end

data/sig/generated/quo/engine.rbs

@@ -0,0 +1,6 @@
+# Generated from lib/quo/engine.rb with RBS::Inline
+
+module Quo
+  class Engine < ::Rails::Engine
+  end
+end

data/sig/generated/quo/preloadable.rbs

@@ -0,0 +1,29 @@
+# Generated from lib/quo/preloadable.rb with RBS::Inline
+
+module Quo
+  module Preloadable
+    def self.included: (untyped base) -> untyped
+
+    # This implementation of `query` calls `collection` and preloads the includes.
+    # @rbs return: Object & Enumerable[untyped]
+    def query: () -> (Object & Enumerable[untyped])
+
+    # For use with collections of ActiveRecord models.
+    # Configures ActiveRecord::Associations::Preloader to load associations of models in the collection
+    # @rbs *options: untyped
+    # @rbs return: Quo::Query
+    def preload: (*untyped options) -> Quo::Query
+
+    # Alias for `preload`
+    # @rbs *options: untyped
+    # @rbs return: Quo::Query
+    def includes: (*untyped options) -> Quo::Query
+
+    private
+
+    @_rel_preload: untyped?
+
+    # @rbs (untyped records, ?untyped? preload) -> untyped
+    def preload_includes: (untyped records, ?untyped? preload) -> untyped
+  end
+end

data/sig/generated/quo/query.rbs

@@ -0,0 +1,98 @@
+# Generated from lib/quo/query.rb with RBS::Inline
+
+module Quo
+  class Query < Literal::Struct
+    include Literal::Types
+
+    def self.inspect: () -> untyped
+
+    def self.to_s: () -> untyped
+
+    def inspect: () -> untyped
+
+    def to_s: () -> untyped
+
+    # TODO: put this in a module with the composer and merge_instances methods
+    # Compose is aliased as `+`. Can optionally take `joins` parameters to add joins on merged relation.
+    # @rbs right: Quo::Query | ActiveRecord::Relation | Object & Enumerable[untyped]
+    # @rbs joins: Symbol | Hash[Symbol, untyped] | Array[Symbol | Hash[Symbol, untyped]]
+    # @rbs return: Quo::Query & Quo::ComposedQuery
+    def self.compose: (Quo::Query | ActiveRecord::Relation | Object & Enumerable[untyped] right, ?joins: Symbol | Hash[Symbol, untyped] | Array[Symbol | Hash[Symbol, untyped]]) -> (Quo::Query & Quo::ComposedQuery)
+
+    COERCE_TO_INT: untyped
+
+    attr_accessor page(): Integer?
+
+    attr_accessor page_size(): Integer?
+
+    @current_page: Integer?
+
+    def next_page_query: () -> Quo::Query
+
+    def previous_page_query: () -> Quo::Query
+
+    def offset: () -> Integer
+
+    # Returns a active record query, or a Quo::Query instance
+    def query: () -> (Quo::Query | ::ActiveRecord::Relation)
+
+    # @rbs **overrides: untyped
+    # @rbs return: Quo::Query
+    def copy: (**untyped overrides) -> Quo::Query
+
+    # Compose is aliased as `+`. Can optionally take `joins` parameters to add joins on merged relation.
+    # @rbs right: Quo::Query | ::ActiveRecord::Relation
+    # @rbs joins: untyped
+    # @rbs return: Quo::ComposedQuery
+    def merge: (Quo::Query | ::ActiveRecord::Relation right, ?joins: untyped) -> Quo::ComposedQuery
+
+    @__transformer: nil | ^(untyped, ?Integer) -> untyped
+
+    # Set a block used to transform data after query fetching
+    # @rbs block: ^(untyped, ?Integer) -> untyped
+    # @rbs return: self
+    def transform: () ?{ (?) -> untyped } -> self
+
+    # Is this query object a ActiveRecord relation under the hood?
+    def relation?: () -> bool
+
+    # Is this query object loaded data/collection under the hood? (ie not a AR relation)
+    def collection?: () -> bool
+
+    # Is this query object paged? (ie is paging enabled)
+    def paged?: () -> bool
+
+    # Is this query object transforming results?
+    def transform?: () -> bool
+
+    # Unwrap the paginated query
+    def unwrap: () -> ActiveRecord::Relation
+
+    # Unwrap the un-paginated query
+    def unwrap_unpaginated: () -> ActiveRecord::Relation
+
+    private
+
+    def transformer: () -> untyped
+
+    def validated_query: () -> untyped
+
+    # The underlying query is essentially the configured query with optional extras setup
+    def underlying_query: () -> void
+
+    # The configured query is the underlying query with paging
+    def configured_query: () -> void
+
+    def sanitised_page_size: () -> Integer
+
+    # @rbs rel: untyped
+    # @rbs return: bool
+    def is_collection?: (untyped rel) -> bool
+
+    # @rbs rel: untyped
+    # @rbs return: bool
+    def test_relation: (untyped rel) -> bool
+
+    def quo_unwrap_unpaginated_query: (untyped q) -> untyped
+  end
+end

data/sig/generated/quo/relation_backed_query.rbs

@@ -0,0 +1,90 @@
+# Generated from lib/quo/relation_backed_query.rb with RBS::Inline
+
+module Quo
+  class RelationBackedQuery < Query
+    # @rbs query: ActiveRecord::Relation | Quo::Query
+    # @rbs props: Hash[Symbol, untyped]
+    # @rbs &block: () -> ActiveRecord::Relation | Quo::Query | Object & Enumerable[untyped]
+    # @rbs return: Quo::RelationBackedQuery
+    def self.wrap: (?ActiveRecord::Relation | Quo::Query query, ?props: Hash[Symbol, untyped]) ?{ (?) -> untyped } -> Quo::RelationBackedQuery
+
+    # @rbs conditions: untyped?
+    # @rbs return: String
+    def self.sanitize_sql_for_conditions: (untyped? conditions) -> String
+
+    # @rbs string: String
+    # @rbs return: String
+    def self.sanitize_sql_string: (String string) -> String
+
+    # @rbs value: untyped
+    # @rbs return: String
+    def self.sanitize_sql_parameter: (untyped value) -> String
+
+    @_rel_group: untyped?
+
+    @_rel_distinct: bool?
+
+    @_rel_order: untyped?
+
+    @_rel_limit: untyped?
+
+    @_rel_preload: untyped?
+
+    @_rel_includes: untyped?
+
+    @_rel_select: untyped?
+
+    # SQL 'SELECT' configuration, calls to underlying AR relation
+    # @rbs *options: untyped
+    # @rbs return: Quo::Query
+    def select: (*untyped options) -> Quo::Query
+
+    # SQL 'LIMIT' configuration, calls to underlying AR relation
+    # @rbs limit: untyped
+    # @rbs return: Quo::Query
+    def limit: (untyped limit) -> Quo::Query
+
+    # SQL 'ORDER BY' configuration, calls to underlying AR relation
+    # @rbs options: untyped
+    # @rbs return: Quo::Query
+    def order: (untyped options) -> Quo::Query
+
+    # SQL 'GROUP BY' configuration, calls to underlying AR relation
+    # @rbs *options: untyped
+    # @rbs return: Quo::Query
+    def group: (*untyped options) -> Quo::Query
+
+    # Configures underlying AR relation to include associations
+    # @rbs *options: untyped
+    # @rbs return: Quo::Query
+    def includes: (*untyped options) -> Quo::Query
+
+    # Configures underlying AR relation to preload associations
+    # @rbs *options: untyped
+    # @rbs return: Quo::Query
+    def preload: (*untyped options) -> Quo::Query
+
+    # Calls to underlying AR distinct method
+    # @rbs enabled: bool
+    # @rbs return: Quo::Query
+    def distinct: (?bool enabled) -> Quo::Query
+
+    # @rbs return: Quo::CollectionBackedQuery
+    def to_collection: (?total_count: untyped) -> Quo::CollectionBackedQuery
+
+    def results: () -> Quo::Results
+
+    # Return the SQL string for this query if its a relation type query object
+    def to_sql: () -> String
+
+    private
+
+    def validated_query: () -> untyped
+
+    # The underlying query is essentially the configured query with optional extras setup
+    def underlying_query: () -> ActiveRecord::Relation
+
+    # The configured query is the underlying query with paging
+    def configured_query: () -> ActiveRecord::Relation
+  end
+end

data/sig/generated/quo/relation_results.rbs

@@ -0,0 +1,38 @@
+# Generated from lib/quo/relation_results.rb with RBS::Inline
+
+module Quo
+  class RelationResults < Results
+    # @rbs query: Quo::Query
+    # @rbs transformer: (^(untyped, ?Integer) -> untyped)?
+    # @rbs return: void
+    def initialize: (Quo::Query query, ?transformer: (^(untyped, ?Integer) -> untyped)?) -> void
+
+    # Are there any results for this query?
+    def exists?: () -> bool
+
+    # Gets the count of all results ignoring the current page and page size (if set).
+    def total_count: () -> Integer
+
+    # 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: () -> Integer
+
+    private
+
+    @query: Quo::RelationBackedQuery
+
+    @configured_query: ActiveRecord::Relation
+
+    # Note we reselect the query as this prevents query errors if the SELECT clause is not compatible with COUNT
+    # (SQLException: wrong number of arguments to function COUNT()). We do this in two ways, either with the primary key
+    # or with Arel.star. The primary key is the most compatible way to count, but if the query does not have a primary
+    # we fallback. The fallback "*" wont work in certain situations though, specifically if we have a limit() on the query
+    # which Arel constructs as a subquery. In this case we will get a SQL error as the generated SQL contains
+    # `SELECT COUNT(count_column) FROM (SELECT * AS count_column FROM ...) subquery_for_count` where the error is:
+    # `ActiveRecord::StatementInvalid: SQLite3::SQLException: near "AS": syntax error`
+    # Either way DB engines know how to count efficiently.
+    # @rbs query: ActiveRecord::Relation
+    # @rbs return: Integer
+    def count_query: (ActiveRecord::Relation query) -> Integer
+  end
+end

data/sig/generated/quo/results.rbs

@@ -0,0 +1,39 @@
+# Generated from lib/quo/results.rb with RBS::Inline
+
+module Quo
+  class Results
+    def empty?: () -> bool
+
+    # Alias for total_count
+    def count: () -> Integer
+
+    # Alias for total_count
+    def size: () -> Integer
+
+    # Alias for page_count
+    def page_size: () -> Integer
+
+    # @rbs &block: (untyped, *untyped) -> untyped
+    # @rbs return: Hash[untyped, Array[untyped]]
+    def group_by: () { (untyped, *untyped) -> untyped } -> Hash[untyped, Array[untyped]]
+
+    # Delegate other enumerable methods to underlying collection but also transform
+    # @rbs override
+    def method_missing: ...
+
+    # @rbs name: Symbol
+    # @rbs include_private: bool
+    # @rbs return: bool
+    def respond_to_missing?: (Symbol name, ?bool include_private) -> bool
+
+    def transform?: () -> bool
+
+    private
+
+    @transformer: (^(untyped, ?Integer) -> untyped)?
+
+    # @rbs results: untyped
+    # @rbs return: untyped
+    def transform_results: (untyped results) -> untyped
+  end
+end

data/sig/generated/quo/version.rbs

@@ -0,0 +1,5 @@
+# Generated from lib/quo/version.rb with RBS::Inline
+
+module Quo
+  VERSION: ::String
+end

data/sig/generated/quo.rbs

@@ -0,0 +1,9 @@
+# Generated from lib/quo.rb with RBS::Inline
+
+module Quo
+  extend ActiveSupport::Autoload
+
+  def self.relation_backed_query_base_class: () -> Quo::RelationBackedQuery
+
+  def self.collection_backed_query_base_class: () -> Quo::CollectionBackedQuery
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: quo
 version: !ruby/object:Gem::Version
-  version: 0.6.0
+  version: 1.0.0.alpha1
 platform: ruby
 authors:
 - Stephen Ierodiaconou
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2024-03-19 00:00:00.000000000 Z
+date: 2024-10-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -16,7 +16,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6'
+        version: '7'
     - - "<"
       - !ruby/object:Gem::Version
         version: '8'
@@ -26,7 +26,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6'
+        version: '7'
     - - "<"
       - !ruby/object:Gem::Version
         version: '8'
@@ -36,7 +36,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6'
+        version: '7'
     - - "<"
       - !ruby/object:Gem::Version
         version: '8'
@@ -46,10 +46,44 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '6'
+        version: '7'
     - - "<"
       - !ruby/object:Gem::Version
         version: '8'
+- !ruby/object:Gem::Dependency
+  name: literal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.2.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,41 +92,44 @@ 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
 - 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_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_results.rbs
+- sig/generated/quo/results.rbs
+- sig/generated/quo/version.rbs
 homepage: https://github.com/stevegeek/quo
 licenses:
 - MIT
@@ -107,14 +144,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
+rubygems_version: 3.5.11
 signing_key:
 specification_version: 4
 summary: Quo is a query object gem for Rails

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