plain_query 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bd8f5297c612866609495705363e33a5b04d43acfc4169b6db99ac7fd831a58c
-  data.tar.gz: 7a8adf2c33adbd013d68e1989970385834861e6c3d474d88785f94bb473501c9
+  metadata.gz: 9fff1e9e16625d80a9f3f62e6c3cffcda79974c4bfcd41a8a2717165cb3f35f9
+  data.tar.gz: 282cf0017c3d7b4ab771f17c67f3340a5a6d7cab1315ce821d7ffbb5e5040694
 SHA512:
-  metadata.gz: 95163e316ad68b4c3dd0141030ccc5e58c6de3514aca0658bcb556d4494d42cdd6260a62f4e8e58206e3a804ed3f7ac26eb976c3272c8b5ad700cecf7ea16399
-  data.tar.gz: 31f79976ab181c103bd62823c0be4e4978da81925beb9a885515970cd0301a5a1f86dd280b079d7660af771c0d4c33032d8924edf1ec68b987b91787ed444c78
+  metadata.gz: 30e9043ea80059f42b536998decf73e7b672a54da0724a139dab572f41460118b1635f0ad00f30ef22d8c4825b1abf8d29cd49edc4cd6761fae4bd4787371f57
+  data.tar.gz: f66cdc23a9feb4143ef6bb7cba086872bc9c47be6ab2073795c3f40921affb56c432100ad4c82d6624e712d3704b3df93a8561a3ef971bddaaa19635638a989f

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,15 +32,15 @@ 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_activity, if: -> { options[:only_active] }
   query_step :filter_by_phone_presence
   query_step :order_by_name
 
@@ -67,11 +67,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.
@@ -87,7 +87,7 @@ query_step STEP_NAME, CONDITION_OF_EXECUTION
 `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.
+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.
 
 ### Using in Active Record model scope.
 First of all you need to set correct model name inside query object.
@@ -95,18 +95,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
+include PlainQuery::Base(model: User)
 ```
 
 ```rb
-class User < ActiveRecord::Base
-  scope :active_clients, ActiveClientsQuery
-end
-```
-
-```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 +115,12 @@ class ActiveClientsQuery < PlainQuery
 end
 ```
 
+```rb
+class User < ActiveRecord::Base
+  scope :active_clients, ActiveClientsQuery
+end
+```
+
 And then you can use scope from model:
 
 ```rb
@@ -137,8 +137,6 @@ end
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/plain_query. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
-
 1. Fork it
 2. Create your feature branch (git checkout -b my-new-feature)
 3. Commit your changes (git commit -am 'Add some feature')

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 = 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.0"
+# frozen_string_literal: true
+
+module PlainQuery
+  VERSION = '0.2.0'.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.0
+  version: 0.2.0
 platform: ruby
 authors:
 - gl-pv
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2022-09-10 00:00:00.000000000 Z
+date: 2022-09-17 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,75 +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, model class.
-    if relation.nil?
-      raise(RelationRequired, 'Queries require a base relation defined')
-    elsif !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)
-      if !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 condition.is_a?(String) || condition.is_a?(Symbol)
-      !!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