quo 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5abae18b00be2197c2d35ed322af099766deaaa13f77f14fe53f597f2ed544b2
-  data.tar.gz: 95e1b9e161ad9e4d6fb627194cc6b408878945aa08c43ef498bbbfa0ea5c3dd3
+  metadata.gz: 3278d72f55569eb93fb569185467cd4b327ffd157e249c8538d4a643c652443c
+  data.tar.gz: e936c5fd0de429b941e110c273cb12ff302079095ab0f3d7d38023718b80b5e3
 SHA512:
-  metadata.gz: 9c6ce18b7bb3de2243561ad14da26117e7053a0c04255dc94b8408d942a1382e2c4eb2c6071c22f52d1a7cef9bf9fceeeb7746788f921c0c1c6a9896fa2f4717
-  data.tar.gz: 063f2dd88dcd09bd1b3778b8c6bc77b09a000daae113425fc3c7152c058c2e836cb5630fa58ef060fb099179eddf6119592e25e51cb7ad0380791cd7468a1cac
+  metadata.gz: 4adcb23af540cf2db462bd21640aef4497c1f2509a1ac6968a5a15b1cd2004d7db9935638ba5496eb57ffc655ad515688fc9468a191d17b32735da1a7c652705
+  data.tar.gz: f99119cdf52a97e956317a530e9074e12b07816405f6dd5fd80f74665dd34c0294368ed6d6a7d88f8147484486f52606462864663357e430ca2eebc36b7372d7

data/Gemfile

@@ -5,12 +5,16 @@ source "https://rubygems.org"
 # Specify your gem's dependencies in quo.gemspec
 gemspec
 
-gem "sqlite3"
+group :development, :test do
+  gem "sqlite3"
 
-gem "rails", ">= 6"
+  gem "rails", ">= 6", "< 8"
 
-gem "rake", "~> 13.0"
+  gem "rake", "~> 13.0"
 
-gem "minitest", "~> 5.0"
+  gem "minitest", "~> 5.0"
 
-gem "standard", "~> 1.3"
+  gem "standard", "~> 1.3"
+
+  gem "steep", "~> 1.2"
+end

data/README.md

@@ -148,9 +148,14 @@ class RegistrationToBeApproved < Quo::Query
   def query
     done = Registration.where(step: "complete")
     approved = CompanyToBeApproved.new
-    done + approved
+    # Here we use `.compose` utility method to wrap our Relation in a Query and 
+    # then compose with the other Query
+    Quo::Query.compose(done, approved)
   end
 end
+
+# A Relation can be composed directly to a Quo::Query
+query = RegistrationToBeApproved.new + Registration.where(blocked: false)
 ```
 
 Also you can use joins:

data/Steepfile

@@ -0,0 +1,34 @@
+# D = Steep::Diagnostic
+#
+# target :lib do
+#   signature "sig"
+#
+#   check "lib"                       # Directory name
+#   check "Gemfile"                   # File name
+#   check "app/models/**/*.rb"        # Glob
+#   # ignore "lib/templates/*.rb"
+#
+#   # library "pathname", "set"       # Standard libraries
+#   # library "strong_json"           # Gems
+#
+#   # configure_code_diagnostics(D::Ruby.strict)       # `strict` diagnostics setting
+#   # configure_code_diagnostics(D::Ruby.lenient)      # `lenient` diagnostics setting
+#   # configure_code_diagnostics do |hash|             # You can setup everything yourself
+#   #   hash[D::Ruby::NoMethod] = :information
+#   # end
+# end
+
+# target :test do
+#   signature "sig", "sig-private"
+#
+#   check "test"
+#
+#   # library "pathname", "set"       # Standard libraries
+# end
+
+target :lib do
+  check "lib/quo"
+  signature "sig"
+
+  library "forwardable"
+end

data/lib/quo/eager_query.rb

@@ -7,7 +7,9 @@ module Quo
       super(**options.except(:collection))
     end
 
-    # Optionally return the `total_count` option
+    # 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
@@ -19,7 +21,6 @@ module Quo
       options[:total_count].nil? && current_page.present?
     end
 
-    # Return the underlying collection
     def query
       preload_includes(collection) if options[:includes]
       collection
@@ -33,7 +34,7 @@ module Quo
       true
     end
 
-    protected
+    private
 
     attr_reader :collection
 

data/lib/quo/enumerator.rb

@@ -53,8 +53,8 @@ module Quo
       end
     end
 
-    def respond_to_missing?(method, include_private = false)
-      Enumerable.instance_methods.include?(method) || super
+    def respond_to_missing?(name, include_private = false)
+      Enumerable.instance_methods.include?(name)
     end
 
     private

data/lib/quo/query.rb

@@ -14,12 +14,10 @@ module Quo
     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
@@ -43,7 +41,7 @@ module Quo
 
     # 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)
+    def compose(right, joins: nil)
       Quo::QueryComposer.new(self, right, joins).compose
     end
 
@@ -201,7 +199,7 @@ module Quo
 
     delegate :distinct, to: :configured_query
 
-    protected
+    private
 
     def formatted_queries?
       Quo.configuration&.formatted_query_log
@@ -254,7 +252,6 @@ module Quo
             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

data/lib/quo/query_composer.rb

@@ -20,15 +20,18 @@ module Quo
     attr_reader :left, :right, :joins
 
     def merge
-      left_rel, right_rel = unwrap_relations
-      left_type, right_type = relation_types?
+      left_rel = unwrap_relation(left)
+      right_rel = unwrap_relation(right)
+      left_type = relation_type?(left)
+      right_type = relation_type?(right)
+
       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)
+      elsif left_eager_right_relation?(left_type, right_type) && left_rel.respond_to?(:+)
         left_rel + right_rel.to_a
-      elsif both_eager_loaded?(left_rel, left_type, right_type)
+      elsif both_eager_loaded?(left_type, right_type) && left_rel.respond_to?(:+)
         left_rel + right_rel
       else
         raise_error
@@ -42,18 +45,20 @@ module Quo
       {}
     end
 
-    def relation_types?
-      [left, right].map do |query|
-        if query.is_a?(Quo::Query)
-          query.relation?
-        else
-          query.is_a?(ActiveRecord::Relation)
-        end
+    def unwrap_relation(query)
+      query.is_a?(Quo::Query) ? query.unwrap : query
+    end
+
+    def relation_type?(query)
+      if query.is_a?(::Quo::Query)
+        query.relation?
+      else
+        query.is_a?(::ActiveRecord::Relation)
       end
     end
 
     def apply_joins(left_rel, joins)
-      joins.present? ? left_rel.joins(joins.to_sym) : left_rel
+      joins.present? ? left_rel.joins(joins) : left_rel
     end
 
     def both_relations?(left_rel_type, right_rel_type)
@@ -64,16 +69,12 @@ module Quo
       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?(:+)
+    def left_eager_right_relation?(left_rel_type, right_rel_type)
+      !left_rel_type && right_rel_type
     end
 
-    def unwrap_relations
-      [left, right].map { |query| query.is_a?(Quo::Query) ? query.unwrap : query }
+    def both_eager_loaded?(left_rel_type, right_rel_type)
+      !left_rel_type && !right_rel_type
     end
 
     def raise_error

data/lib/quo/railtie.rb

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

data/lib/quo/utilities/compose.rb

@@ -2,15 +2,14 @@
 
 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
-      # 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)
+      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

data/lib/quo/utilities/sanitize.rb

@@ -3,7 +3,6 @@
 module Quo
   module Utilities
     module Sanitize
-      # ActiveRecord::Sanitization wrappers
       def sanitize_sql_for_conditions(conditions)
         ActiveRecord::Base.sanitize_sql_for_conditions(conditions)
       end

data/lib/quo/utilities/wrap.rb

@@ -2,17 +2,21 @@
 
 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
-      # 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)
+        if query_rel_or_data.is_a? Quo::Query
+          return options.present? ? query_rel_or_data.copy(**options) : query_rel_or_data
         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))
+          new(**options.merge(scope: query_rel_or_data))
+        else
+          Quo::EagerQuery.new(**options.merge(collection: query_rel_or_data))
         end
-        Quo::EagerQuery.new(**options.merge(collection: query_rel_or_data))
       end
     end
   end

data/lib/quo/version.rb

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

data/lib/quo.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "quo/version"
+require_relative "quo/railtie" if defined?(Rails)
 require_relative "quo/query"
 require_relative "quo/eager_query"
 require_relative "quo/merged_query"

data/lib/tasks/quo.rake

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+desc "List all the query objects in the app"
+namespace :quo do
+  task list: :environment do
+    # In development classes are lazily loaded, so can't use Quo::Query.descendants.
+    # Instead we search all *_query.rb files
+    Dir["#{Rails.root}/**/*_query.rb"].each do |file|
+      source_code = File.read(file)
+      result = source_code.match(/class\s+([A-Za-z0-9_:]+)\s*<\s*(::)?Quo::Query/)
+      puts (result && result[1]) ? "\n\n> #{result[1]}" : "Class name could not be determined"
+      puts "\n"
+      comments = source_code.match(/((#[^\n]+\n)*)[^\n]+lass/)
+      puts (comments && comments[1].present?) ? comments[1] : "No description for class found"
+      puts "\n"
+      puts "Found in:"
+      puts "    - #{file}"
+    end
+  end
+end

data/rbs_collection.yaml

@@ -0,0 +1,26 @@
+# Download sources
+sources:
+  - name: ruby/gem_rbs_collection
+    remote: https://github.com/ruby/gem_rbs_collection.git
+    revision: main
+    repo_dir: gems
+
+# A directory to install the downloaded RBSs
+path: .gem_rbs_collection
+
+gems:
+  - name: quo
+    ignore: true
+  - name: forwardable
+  # Skip loading rbs gem's RBS.
+  # It's unnecessary if you don't use rbs as a library.
+  - name: rbs
+    ignore: true
+  - name: rake
+    ignore: true
+  - name: minitest
+    ignore: true
+  - name: standard
+    ignore: true
+  - name: steep
+    ignore: true

data/sig/quo.rbs

@@ -1,4 +1,205 @@
 module Quo
   VERSION: String
-  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+
+  interface _Enumerable
+    def each: { (untyped) -> void } -> untyped
+  end
+
+  interface _Collection
+    include _Enumerable
+    def is_a?: (Class) -> bool
+    def class: -> Class
+    def +: (untyped) -> _Collection
+  end
+
+  type query = Quo::MergedQuery | Quo::EagerQuery | Quo::Query
+  type merge_composable = query | ActiveRecord::Relation
+  type enumerable = _Collection
+  type query_like = ActiveRecord::Relation | enumerable
+  type composable = query | query_like
+
+  module Utilities
+    module Callstack
+      def debug_callstack: () -> void
+    end
+
+    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: (composable query1, composable query2, ?joins: untyped?) -> Quo::MergedQuery
+
+      # Determines if the object `query` is something which can be composed with query objects
+      def composable_with?: (merge_composable query) -> bool
+    end
+
+    module Sanitize
+      def sanitize_sql_for_conditions: (untyped conditions) -> (untyped | nil)
+
+      def sanitize_sql_string: (untyped string) -> (untyped | nil)
+
+      def sanitize_sql_parameter: (untyped value) -> (untyped | nil)
+    end
+
+    interface _Wrapable
+      def new: (**untyped options) -> query
+    end
+
+    module Wrap : _Wrapable
+      def wrap: (composable query_rel_or_data, **untyped options) -> query
+    end
+
+  end
+
+  class Enumerator
+    extend Forwardable
+
+    include Quo::Utilities::Callstack
+
+    def initialize: (Quo::Query query, ?transformer: ^(untyped, ?Integer) -> untyped) -> void
+
+    @query: Quo::Query
+
+    def respond_to_missing?: (Symbol name, ?bool include_private) -> bool
+
+    private
+
+    attr_reader transformer: ^(untyped, ?Integer) -> untyped
+    attr_reader unwrapped: ActiveRecord::Relation
+
+    def transform_results: (untyped) -> untyped
+  end
+
+
+  class Query
+    include Quo::Utilities::Callstack
+    extend Quo::Utilities::Compose
+    extend Quo::Utilities::Sanitize
+    extend Quo::Utilities::Wrap
+
+    def self.call: (**untyped options) -> untyped
+    def self.call!: (**untyped options) -> untyped
+    def self.description: (?String) -> (String | nil)
+    self.@description: String | nil
+
+    @scope: ActiveRecord::Relation | nil
+
+    attr_reader current_page: (Integer | nil)
+    attr_reader page_size: (Integer | nil)
+    attr_reader options: Hash[untyped, untyped]
+
+    def initialize: (**untyped options) -> void
+    def query: () -> composable
+    def compose: (composable right, ?joins: untyped?) -> Quo::MergedQuery
+    alias + compose
+
+    def copy: (**untyped options) -> query
+
+    def limit: (untyped limit) -> query
+    def order: (untyped options) -> query
+    def group: (*untyped options) -> query
+    def includes: (*untyped options) -> query
+    def preload: (*untyped options) -> query
+    def select: (*untyped options) -> 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: (*untyped args) -> untyped
+    def first!: (*untyped args) -> untyped
+    def last: (*untyped args) -> untyped
+    def to_a: () -> Array[untyped]
+    def to_eager: (?::Hash[untyped, untyped] more_opts) -> Quo::EagerQuery
+    alias load to_eager
+    def enumerator: () -> Quo::Enumerator
+
+    # 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: () -> query_like
+
+    private
+
+    def formatted_queries?: () -> bool
+    def trim_query: (String sql) -> String
+    def format_query: (String sql_str) -> String
+    def transformer: () -> (nil | ^(untyped) -> 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: (composable query) -> ActiveRecord::Relation
+    def test_eager: (composable rel) -> bool
+    def test_relation: (composable rel) -> bool
+  end
+
+  class MergedQuery < Quo::Query
+    def initialize: (untyped options, ?untyped source_queries) -> void
+
+    def query: () -> composable
+
+    def to_s: () -> ::String
+
+    private
+
+    def source_queries_left: () -> composable
+    def source_queries_right: () -> composable
+    attr_reader source_queries: Array[composable]
+    def operand_desc: (untyped operand) -> (nil | String)
+  end
+
+  class EagerQuery < Quo::Query
+    def initialize: (**untyped options) -> void
+    def query: () -> enumerable
+    def relation?: () -> false
+    def eager?: () -> true
+    attr_reader collection: enumerable
+
+    private
+
+    def preload_includes: (untyped records, ?untyped? preload) -> untyped
+  end
+
+  class QueryComposer
+    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
+
+    def merge: () -> (ActiveRecord::Relation | Array[untyped] | void)
+    def merged_options: () -> ::Hash[untyped, untyped]
+    def unwrap_relation: (composable) -> query_like
+    def relation_type?: (composable) -> bool
+    def apply_joins: (ActiveRecord::Relation left_rel, untyped joins) -> ActiveRecord::Relation
+    def both_relations?: (bool left_rel_type, bool right_rel_type) -> bool
+    def left_relation_right_eager?: (bool left_rel_type, bool right_rel_type) -> bool
+    def left_eager_right_relation?: (bool left_rel_type, bool right_rel_type) -> bool
+    def both_eager_loaded?: (bool left_rel_type, bool right_rel_type) -> bool
+
+    def raise_error: () -> void
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: quo
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Stephen Ierodiaconou
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2022-11-22 00:00:00.000000000 Z
+date: 2022-12-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -17,6 +17,9 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -24,6 +27,29 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8'
 description: Quo query objects are composable.
 email:
 - stevegeek@gmail.com
@@ -37,6 +63,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- Steepfile
 - lib/quo.rb
 - lib/quo/eager_query.rb
 - lib/quo/enumerator.rb
@@ -50,6 +77,8 @@ files:
 - lib/quo/utilities/sanitize.rb
 - lib/quo/utilities/wrap.rb
 - lib/quo/version.rb
+- lib/tasks/quo.rake
+- rbs_collection.yaml
 - sig/quo.rbs
 homepage: https://github.com/stevegeek/quo
 licenses:
@@ -72,7 +101,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
+rubygems_version: 3.3.26
 signing_key:
 specification_version: 4
 summary: Quo is a query object gem for Rails