querii 1.0.1 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 446635ffc0f477018660c9586b56705a49e3b899
-  data.tar.gz: 5fb91f4beedc05e8d1e31f357548ce22a6f73a62
+  metadata.gz: bf2dcc2616587bd7e2f4533aa0675ac139c56fd1
+  data.tar.gz: 832407b904834d3d10adc3ef22acef6e93e41df2
 SHA512:
-  metadata.gz: 6c0b430fb59333ddff6abc66cb01fc48be087b66db5f97151851bab6750053ba60d3d3a58113e110ba23fe7171685b502ff2768f79abc4512519aecc5f9d92a8
-  data.tar.gz: 49a835f5f301a63c8db269e5f8f80bccad9b783c14b10be88f89b0662333fa8d11b680c6c2a37d16e292137613ccec268f668541d13bfd5aea6e9de7d418154e
+  metadata.gz: dc9da4056c84585c20338b699b61102874b3f95ebac86ab237b4967410bd4c4e859cea1d70e606f0c52da7b4dd8cb1c5e4306ab649fa44a0dc5500cb4e544661
+  data.tar.gz: f7dcc042f860a3575c79e8932a600dc615c6e3f25652f977de628ed38465b1af278ab3239751cb1b56faeca2a3ae106bfe3c6c2fe8d3211951fa0acb85251b18

data/README.md

@@ -6,7 +6,11 @@ Querii makes it easy to create query objects that return active record relations
 
 ## Why?
 
-Querii allows you to extract complicated query collection logic out of a ActiveRecord model to prevent littering the base model and encourage breaking up your query logic into multiple methods, constants, etc, while still returning a standard activerecord collection (now extended by your additional querii methods) that can be further acted upon.
+Querii allows you to extract complicated query collection logic out of an ActiveRecord model.
+
+This prevents littering the base model and encourages breaking up your query logic into multiple methods, constants, etc. Querii creates a singleton that returns a standard activerecord collection (now extended by your additional querii scopes) that can be further acted upon.
+
+This provides a pattern for extracting complicated common queries from your model or one off queries from a controller for easier testing and separation of concerns.
 
 ## Basic Usage
 
@@ -15,11 +19,9 @@ module Accounts
   module FancySubset
     include Querii::QueryObject
 
-    module Scopes
-      def applied(*args, **key_args)
-        where(cool: 'things', many: key_args.fetch(:hats, 2))
-      end
-    end
+    default_scope { where(cool: 'things') }
+
+    scope :filter, ->(hats: 2) { where(hats: hats) }
   end
 end
 
@@ -27,17 +29,26 @@ end
 Accounts::FancySubset.call # or .all
 
 # or more advanced chain
-Accounts::FancySubset.call(hats: 4).where(typical: 'filtered')
+Accounts::FancySubset.call.filter(hats: 4).where(typical: 'filtered')
 # ...Account::ActiveRecord_Relation < ActiveRecord::Relation
 ```
 
-Querii infers the base collection from the top level query object namespace of `Accounts` -> `Account.all`, you can override this by setting `self.default_relation = 'ClassName'` within your module. Querii defines a default `Scopes` module that will just return all but to do anything useful by default you will need to define your own `Scopes` module. During a query this module is extended onto the base `ActiveRecord::Relation` and the `applied` method is executed returning an active record collection that can further be queried by both any additional methods defined within your Querii object `Scopes` and scopes or conditions on the standard AR class.
+### Base class
 
-## More
+Querii infers the base model from the top level query object namespace. For the example above `Accounts` represents `Account`. You can easily override this by setting `self.model_name = 'ClassName'` within your query module.
 
 ### Default scope
 
-The `applied` method is entirely optional and designed for query objects that only contain a single base scope always intended to be called so you can simply do `MyQueryObj.call` or equivalently `MyQueryObj.all`. Additionally the applied method can accept and use any number of args or keyword args.
+A default scope is automatically defined for you with a collection of `.all`. You can set a customized default by calling `default_scope` and passing a block, proc, or lambda.
+
+The default scope is designed for query objects that only contain a single base scope always intended to be called so you can simply do `MyQueryObj.call` or equivalently `MyQueryObj.all`.
+
+### How it works
+Querii dynamically defines a `Scopes` module when included that contains scopes defined either via `default_scope` or `scope :name, ->{}`. This pattern is taken from AR.
+
+During a query this module is extended onto the base `ActiveRecord::Relation` and the defined default scope method is called. This returns an active record collection that can further be queried by both additional scopes defined within your Querii object and scopes or conditions on the base AR class.
+
+Scopes can also be defined as methods explicitly by opening up the scopes class within your query object.
 
 ### Passing an already filtered relation
 

data/lib/querii/query_object.rb

@@ -5,36 +5,52 @@ module Querii
 
       base.class_eval do
         # dynamically defines a base Scopes module
-        self.const_set(
-          :Scopes,
-          Module.new do
-            def applied(*args, **key_args)
-              all
-            end
-          end
-        )
+        self.const_set(:Scopes, Module.new)
+        default_scope { all }
       end
     end
 
     module ClassMethods
-      def call(*args, relation: default_relation_all, **key_args)
-        relation.extending(self::Scopes).applied(args, key_args)
+      # optionally override the default determined by top level namespace
+      attr_accessor :model_name
+
+      def call(*args, relation: base_class.all, **kargs)
+        relation.extending(self::Scopes).default(*args, **kargs)
       end
 
-      def default_relation_all
-        # .all returns current scope || all
-        relation_base.all
+      alias_method :all, :call
+
+      def scope(name, body, &block)
+        unless body.respond_to?(:call)
+          raise ArgumentError, 'The scope body needs to be callable.'
+        end
+
+        self::Scopes.send(:define_method, name) do |*args, **kargs|
+          # unfortunately empty double splatted kargs still count as arguments
+          # for a lambda's argument arity checking
+          if kargs.empty?
+            scope = all.scoping { instance_exec(*args, &body) }
+          else
+            scope = all.scoping { instance_exec(*args, **kargs, &body) }
+          end
+
+          scope || all
+        end
+      end
+
+      def default_scope(scope = nil)
+        scope = Proc.new if block_given?
+        scope(:default, scope)
       end
 
       # queries are namespaced by plural model name
       # from which we can infer query base model
-      def relation_base
-        default_relation.to_s.constantize || self.to_s.split('::').first.singularize.constantize
+      def base_class
+        klass = model_name || self.to_s.split('::').first.singularize
+        klass.to_s.constantize
       end
+      private :base_class
 
-      alias_method :all, :call
-
-      attr_accessor :default_relation
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: querii
 version: !ruby/object:Gem::Version
-  version: 1.0.1
+  version: 1.1.0
 platform: ruby
 authors:
 - Justin
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-03-15 00:00:00.000000000 Z
+date: 2017-03-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler