plain_query 0.1.1 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dee05c4d00595dfab9fd6e7d5a2f154a5859a4be75ef3f73e38260b2e06ea300
-  data.tar.gz: d0e1115a8da4c3f78cb97fe3107743ca1f4aab9874260f9a26ea86e68da64594
+  metadata.gz: 70c15cb5669c0f7794a193a259ba966f97f6017fafa8db1d6b97ce63d4e2ef17
+  data.tar.gz: 37d7a7c0e1109f138a0e9860dd956002b6b68de6eb6b54cac501b62783b01bff
 SHA512:
-  metadata.gz: 676f7357d5ece333078b7434451ee1d26f4512a2e7e9ede0ddba7530fad1a32da8568679f6835da4b1058d86ff5bf4914e9c1c04d6846da291f36466e49e7b3a
-  data.tar.gz: bbb09631bb05e2ed2cbbc52346ea18fc42813a50c1f790b786a9da5d9cf6b302b5ee1b70c2335739176640e0668957dce4334be6dabffac9c495ff8f871bba1f
+  metadata.gz: d24c959954d7cf9a25fb512ab3c603c46a168891e84a120c980fda12675e398a81af9362cd1cc203b3f97342f611b7446663277ad793fb8f03fe6d01045d808c
+  data.tar.gz: 9cfb9811e1c2bd1ff8c8832481f4b1d084da6526c6562ef8547f4b48759ae669d58cabe00e1a4d97fdf9f6248e0f53d2c4c1a23c58990068bf30289e6bda1658

data/README.md

@@ -1,4 +1,4 @@
-# PlainQuery
+# PlainQuery ![transp_logo_153](https://user-images.githubusercontent.com/95882437/189980991-9417395b-ff94-4480-89a5-bb97c9aaf8ca.png)
 
 PlainQuery is a simple gem that helps you write clear and flexible query objects.
 Main task for this gem is performing complex querying on active record relation, make it intuitive.
@@ -32,26 +32,22 @@ Or install it yourself as:
 
 ## Usage
 ### Setting up a query object
-For setting up a query object you need to inherit your query class from PlainQuery.
+For setting up a query object you need to include PlainQuery::Base into your your query class.
 Then you need to describe query steps by using query_step method.
 Query steps perform in writing order.
 
 ```rb
-class UsersQuery < PlainQuery
-  model User
+class UsersQuery
+  include PlainQuery::Base(model: User)
 
   query_step :filter_by_activity, if: -> { options[:only_active] }
-  query_step :filter_by_phone_presence
+  query_step :filter_by_phone_presence, query: UsersWithPhoneQuery
   query_step :order_by_name
 
   def filter_by_activity
     relation.where(active: true)
   end
 
-  def filter_by_phone_presence
-    relation.where.not(phone: nil)
-  end
-
   def order_by_name
     relation.order(name: :asc)
   end
@@ -67,11 +63,11 @@ users = UsersQuery.call(User.all, only_active: true)
 Query object implements `#call` method with two arguments:
 
 `relation` - Base scope which will be mutated inside query object. (`User.all` in example).
-If you dont pass it - will be used default scope from model declaration inside query object.
+If you dont pass it - will be used default scope from model declaration from PlainQuery::Base module include `include PlainQuery::Base(model: User)`.
 
 `options` - Any data which will be used inside query steps or execution conditions. (`only_active: true` in example).
 
-Query object returns scope builded by query steps execution.
+Query object returns scope builded by ordered query steps execution.
 
 ### query_step
 `query_step` is a main part of query building.
@@ -81,13 +77,15 @@ It declares which query change method will be executed, condition of execution a
 It has several arguments:
 
 ```rb
-query_step STEP_NAME, CONDITION_OF_EXECUTION
+query_step STEP_NAME, EXECUTION_OPTIONS
 ```
 
 `STEP_NAME` is a name of method which will be executed.
 
-`CONDITION_OF_EXECUTION` is a method which allows or denieds execution of query step.
-Type of condition can be `if:` or `unless:`. Condition definition can be proc (lambda) or some query object method name.
+`EXECUTION_OPTIONS` is a collection of options related with step execution.
+Available two types of options:
+`Condition` - allows or denieds execution of query step. Type of condition can be `if:` or `unless:`. Condition definition can be proc (lambda) or some query object method name. Result of query object method used in condition will be used as a boolean value.
+`Nested query` - realises DI for current query object by `query` key. It can execute any class which has call method and returns relation.
 
 ### Using in Active Record model scope.
 First of all you need to set correct model name inside query object.
@@ -95,18 +93,12 @@ First of all you need to set correct model name inside query object.
 It uses for correct base scope building without passing relation to query object.
 
 ```rb
-model User
-```
-
-```rb
-class User < ActiveRecord::Base
-  scope :active_clients, ActiveClientsQuery
-end
+include PlainQuery::Base(model: User)
 ```
 
 ```rb
-class ActiveClientsQuery < PlainQuery
-  model User
+class ActiveClientsQuery
+  include PlainQuery::Base(model: User)
 
   query_step :filter_by_activity
   query_step :filter_by_role
@@ -121,6 +113,12 @@ class ActiveClientsQuery < PlainQuery
 end
 ```
 
+```rb
+class User < ActiveRecord::Base
+  scope :active_clients, ActiveClientsQuery
+end
+```
+
 And then you can use scope from model:
 
 ```rb

data/lib/plain_query/builder.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require 'plain_query/builder_options'
+require 'plain_query/class_methods'
+require 'plain_query/instance_methods'
+require 'plain_query/version'
+
+module PlainQuery
+  class Builder < Module
+    attr_reader :builder_options
+
+    def initialize(model: nil)
+      @builder_options = BuilderOptions.new(model: model)
+    end
+
+    def included(klass)
+      klass.extend(builder_options)
+      klass.extend(ClassMethods)
+      klass.include(InstanceMethods)
+    end
+  end
+end

data/lib/plain_query/builder_options.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module PlainQuery
+  class BuilderOptions < Module
+    def initialize(model: nil)
+      define_model(model)
+    end
+
+    def define_model(model)
+      module_exec(model) do |model_name|
+        define_method(:model) do
+          model_name
+        end
+      end
+    end
+  end
+end

data/lib/plain_query/class_methods.rb

@@ -0,0 +1,15 @@
+module PlainQuery
+  module ClassMethods
+    def call(relation = model&.all, options = {})
+      new(relation, options).exec_query
+    end
+
+    def steps
+      @steps ||= []
+    end
+
+    def query_step(step_name, params = {})
+      steps << [step_name, params]
+    end
+  end
+end

data/lib/plain_query/instance_methods.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module PlainQuery
+  module InstanceMethods
+    attr_reader :relation, :options
+
+    def initialize(relation, options)
+      @relation = relation
+      @options = options
+      @steps = self.class.steps
+
+      # Validates initial relation format. Allowed only ActiveRecord::Relation.
+      unless @relation.is_a?(ActiveRecord::Relation)
+        raise(StandardError, 'Queries accept only ActiveRecord::Relation as input')
+      end
+    end
+
+    def exec_query
+      @steps.each do |step_name, params|
+        # Handles if condition
+        if (params[:if] && !exec_condition(params[:if]))
+          next
+        end
+
+        # Handles unless condition
+        if (params[:unless] && exec_condition(params[:unless]))
+          next
+        end
+
+        # Executes query mutation and checks that step returns ActiveRecord::Relation
+        mutated_query = params[:query] ? params[:query].call(@relation, @options) : send(step_name)
+        unless mutated_query.is_a?(ActiveRecord::Relation)
+          raise(StandardError, 'Scope must be ActiveRecord::Relation')
+        end
+
+        @relation = mutated_query
+      end
+
+      @relation
+    end
+
+    # Executes if and unless conditions, conditions must contain object method name or proc (lambda)
+    def exec_condition(condition)
+      if [String, Symbol].member?(condition.class)
+        !!send(condition)
+      elsif condition.is_a?(Proc)
+        !!instance_exec(&condition)
+      else
+        raise(StandardError, 'Condition must be method name or proc')
+      end
+    end
+  end
+end

data/lib/plain_query/version.rb

@@ -1,3 +1,5 @@
-class PlainQuery
-  VERSION = "0.1.1"
+# frozen_string_literal: true
+
+module PlainQuery
+  VERSION = '0.2.1'.freeze
 end

data/lib/plain_query.rb

@@ -1,2 +1,32 @@
-require "plain_query/version"
-require "plain_query/logic"
+# frozen_string_literal: true
+
+require 'plain_query/builder'
+
+module PlainQuery
+  # Realises methods for scope building by execution of sequence of steps
+  # Query class defines query steps:
+  # query_step :filter_by_status, if: -> { options[:status].present? }
+  #
+  # def filter_by_status
+  #   relation.where(status: options[:status])
+  # end
+  module Base
+    def self.included(klass)
+      klass.include(PlainQuery::Base())
+    end
+  end
+  # This method allows to declare model parameter associated with this query object.
+  # Model parameter is useful for model scopes building
+  # Example:
+  # class UsersQuery
+  #   include PlainQuery::Base(model: User)
+  #   ...
+  # end
+  # class User < ActiveRecord::Base
+  #   scope :available, UsersQuery
+  # end
+  def self.Base(model: nil)
+    PlainQuery::Builder.new(model: model)
+  end
+end
+

data/plain_query.gemspec

@@ -9,8 +9,8 @@ Gem::Specification.new do |spec|
   spec.authors       = ["gl-pv"]
   spec.email         = ["gleeb812812@yandex.ru"]
 
-  spec.summary       = %q{Builds query object by declaration sequence of query building steps}
-  spec.description   = %q{PlainQuery is a simple gem that helps you write clear and flexible query objects}
+  spec.summary       = %q{PlainQuery is a simple gem that helps you write clear and flexible query objects}
+  spec.description   = %q{PlainQuery helps in decomposing your fat ActiveRecord models and keeping your code slim and readable by extracting complex SQL queries or scopes into the separated classes that are easy to write, read and use.}
   spec.homepage      = "https://github.com/gl-pv/plain_query"
   spec.license       = "MIT"
   spec.required_ruby_version = Gem::Requirement.new('>= 2.4.0')

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: plain_query
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.2.1
 platform: ruby
 authors:
 - gl-pv
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-09-12 00:00:00.000000000 Z
+date: 2022-12-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -94,8 +94,9 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 1.4.2
-description: PlainQuery is a simple gem that helps you write clear and flexible query
-  objects
+description: PlainQuery helps in decomposing your fat ActiveRecord models and keeping
+  your code slim and readable by extracting complex SQL queries or scopes into the
+  separated classes that are easy to write, read and use.
 email:
 - gleeb812812@yandex.ru
 executables: []
@@ -113,7 +114,10 @@ files:
 - bin/console
 - bin/setup
 - lib/plain_query.rb
-- lib/plain_query/logic.rb
+- lib/plain_query/builder.rb
+- lib/plain_query/builder_options.rb
+- lib/plain_query/class_methods.rb
+- lib/plain_query/instance_methods.rb
 - lib/plain_query/version.rb
 - plain_query.gemspec
 homepage: https://github.com/gl-pv/plain_query
@@ -140,5 +144,6 @@ requirements: []
 rubygems_version: 3.0.9
 signing_key: 
 specification_version: 4
-summary: Builds query object by declaration sequence of query building steps
+summary: PlainQuery is a simple gem that helps you write clear and flexible query
+  objects
 test_files: []

data/lib/plain_query/logic.rb

@@ -1,74 +0,0 @@
-# Realises methods for scope building by execution of sequence of steps
-# Query class defines query steps:
-# query_step :filter_by_status, if: -> { options[:status].present? }
-#
-# def filter_by_status
-#   relation.where(status: options[:status])
-# end
-class PlainQuery
-  attr_reader :relation, :options
-
-  def initialize(relation, options)
-    @relation = relation
-    @options = options
-    @steps = self.class.steps
-
-    # Validates initial relation format. Allowed only ActiveRecord::Relation.
-    unless relation.is_a?(ActiveRecord::Relation)
-      raise(RelationRequired, 'Queries accept only ActiveRecord::Relation as input')
-    end
-  end
-
-  def exec_query
-    @steps.each do |step_name, params|
-      # Handles if condition
-      if (params[:if] && !exec_condition(params[:if]))
-        next
-      end
-
-      # Handles unless condition
-      if (params[:unless] && exec_condition(params[:unless]))
-        next
-      end
-
-      # Executes query mutation and checks that step returns ActiveRecord::Relation
-      mutated_query = send(step_name)
-      unless mutated_query.is_a?(ActiveRecord::Relation)
-        raise(RelationIsIncorrect, 'Scope must be ActiveRecord::Relation')
-      end
-
-      @relation = mutated_query
-    end
-
-    @relation
-  end
-
-  # Executes if and unless conditions, conditions must contain object method name or proc (lambda)
-  def exec_condition(condition)
-    if [String, Symbol].member?(condition.class)
-      !!send(condition)
-    elsif condition.is_a?(Proc)
-      !!instance_exec(&condition)
-    else
-      raise(ConditionFormatIsIncorrect, 'Condition must be method name or proc')
-    end
-  end
-
-  class << self
-    def call(relation = @model&.all, options = {})
-      new(relation, options).exec_query
-    end
-
-    def query_step(step_name, params = {})
-      steps << [step_name, params]
-    end
-
-    def steps
-      @steps ||= []
-    end
-
-    def model(model)
-      @model = model
-    end
-  end
-end