Added `none` query method to return zero records.

And added NullRelation class implementing the null object pattern for the `Relation` class.

1 files changed, 33 insertions, 0 deletions

diff --git a/activerecord/lib/active_record/relation/query_methods.rb b/activerecord/lib/active_record/relation/query_methods.rb
index a8ae7208fc..6a28d7b155 100644
--- a/activerecord/lib/active_record/relation/query_methods.rb
+++ b/activerecord/lib/active_record/relation/query_methods.rb
@@ -196,6 +196,39 @@ module ActiveRecord
       relation
     end
 
+    # Returns a chainable relation with zero records, specifically an
+    # instance of the NullRelation class.
+    #
+    # The returned NullRelation inherits from Relation and implements the
+    # Null Object pattern so it is an object with defined null behavior:
+    # it always returns an empty array of records and avoids any database query.
+    #
+    # Any subsequent condition chained to the returned relation will continue
+    # generating an empty relation and will not fire any query to the database.
+    #
+    # Used in cases where is needed a method or a scope that could return zero
+    # results but the response has to be chainable.
+    #
+    # For example:
+    #
+    #   @posts = current_user.visible_posts.where(:name => params[:name])
+    #   # => the visible_post method response has to be a chainable Relation
+    #
+    #   def visible_posts
+    #     case role
+    #     if 'Country Manager'
+    #       Post.where(:country => country)
+    #     if 'Reviewer'
+    #       Post.published
+    #     if 'Bad User'
+    #       Post.none # => returning [] instead breaks the previous code
+    #     end
+    #   end
+    #
+    def none
+      NullRelation.new(@klass, @table)
+    end
+
     def readonly(value = true)
       relation = clone
       relation.readonly_value = value