google-cloud-firestore 1.4.4 → 2.4.0

data/lib/google/cloud/firestore/query.rb

@@ -63,7 +63,11 @@ module Google
         attr_accessor :parent_path
 
         ##
-        # @private The Google::Firestore::V1::StructuredQuery object.
+        # @private The type for limit queries.
+        attr_reader :limit_type
+
+        ##
+        # @private The Google::Cloud::Firestore::V1::StructuredQuery object.
         attr_accessor :query
 
         ##
@@ -118,7 +122,7 @@ module Google
             new_query.select.fields << field_ref
           end
 
-          Query.start new_query, parent_path, client
+          Query.start new_query, parent_path, client, limit_type: limit_type
         end
 
         ##
@@ -154,7 +158,7 @@ module Google
 
           new_query.from.last.all_descendants = true
 
-          Query.start new_query, parent_path, client
+          Query.start new_query, parent_path, client, limit_type: limit_type
         end
 
         ##
@@ -190,7 +194,7 @@ module Google
 
           new_query.from.last.all_descendants = false
 
-          Query.start new_query, parent_path, client
+          Query.start new_query, parent_path, client, limit_type: limit_type
         end
 
         ##
@@ -212,6 +216,9 @@ module Google
         #   * greater than: `>`, `gt`
         #   * greater than or equal: `>=`, `gte`
         #   * equal: `=`, `==`, `eq`, `eql`, `is`
+        #   * not equal: `!=`
+        #   * in: `in`
+        #   * not in: `not-in`, `not_in`
         #   * array contains: `array-contains`, `array_contains`
         # @param [Object] value A value the field is compared to.
         #
@@ -246,7 +253,7 @@ module Google
           new_filter = filter field.formatted_string, operator, value
           add_filters_to_query new_query, new_filter
 
-          Query.start new_query, parent_path, client
+          Query.start new_query, parent_path, client, limit_type: limit_type
         end
 
         ##
@@ -298,9 +305,8 @@ module Google
         #   end
         #
         def order field, direction = :asc
-          if query_has_cursors?
-            raise "cannot call order after calling " \
-                  "start_at, start_after, end_before, or end_at"
+          if query_has_cursors? || limit_type == :last
+            raise "cannot call order after calling limit_to_last, start_at, start_after, end_before, or end_at"
           end
 
           new_query = @query.dup
@@ -315,7 +321,7 @@ module Google
             direction: order_direction(direction)
           )
 
-          Query.start new_query, parent_path, client
+          Query.start new_query, parent_path, client, limit_type: limit_type
         end
         alias order_by order
 
@@ -348,12 +354,13 @@ module Google
 
           new_query.offset = num
 
-          Query.start new_query, parent_path, client
+          Query.start new_query, parent_path, client, limit_type: limit_type
         end
 
         ##
-        # Limits a query to return a fixed number of results. If the current
-        # query already has a limit set, this will overwrite it.
+        # Limits a query to return only the first matching documents.
+        #
+        # If the current query already has a limit set, this will overwrite it.
         #
         # @param [Integer] num The maximum number of results to return.
         #
@@ -368,19 +375,83 @@ module Google
         #   cities_col = firestore.col "cities"
         #
         #   # Create a query
-        #   query = cities_col.offset(10).limit(5)
+        #   query = cities_col.order(:name, :desc).offset(10).limit(5)
         #
         #   query.get do |city|
         #     puts "#{city.document_id} has #{city[:population]} residents."
         #   end
         #
         def limit num
+          if limit_type == :last
+            raise "cannot call limit after calling limit_to_last"
+          end
+
           new_query = @query.dup
           new_query ||= StructuredQuery.new
 
           new_query.limit = Google::Protobuf::Int32Value.new value: num
 
-          Query.start new_query, parent_path, client
+          Query.start new_query, parent_path, client, limit_type: :first
+        end
+
+        ##
+        # Limits a query to return only the last matching documents.
+        #
+        # You must specify at least one "order by" clause for limitToLast queries.
+        # (See {#order}.)
+        #
+        # Results for `limit_to_last` queries are only available once all documents
+        # are received. Hence, `limit_to_last` queries cannot be streamed using
+        # {#listen}.
+        #
+        # @param [Integer] num The maximum number of results to return.
+        #
+        # @return [Query] New query with `limit_to_last` called on it.
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   # Get a collection reference
+        #   cities_col = firestore.col "cities"
+        #
+        #   # Create a query
+        #   query = cities_col.order(:name, :desc).limit_to_last(5)
+        #
+        #   query.get do |city|
+        #     puts "#{city.document_id} has #{city[:population]} residents."
+        #   end
+        #
+        def limit_to_last num
+          new_query = @query.dup
+
+          if new_query.nil? || new_query.order_by.nil? || new_query.order_by.empty?
+            raise "specify at least one order clause before calling limit_to_last"
+          end
+
+          if limit_type != :last # Don't reverse order_by more than once.
+            # Reverse the order_by directions since we want the last results.
+            new_query.order_by.each do |order|
+              order.direction = order.direction.to_sym == :DESCENDING ? :ASCENDING : :DESCENDING
+            end
+
+            # Swap the cursors to match the reversed query ordering.
+            new_end_at = new_query.start_at.dup
+            new_start_at = new_query.end_at.dup
+            if new_end_at
+              new_end_at.before = !new_end_at.before
+              new_query.end_at = new_end_at
+            end
+            if new_start_at
+              new_start_at.before = !new_start_at.before
+              new_query.start_at = new_start_at
+            end
+          end
+
+          new_query.limit = Google::Protobuf::Int32Value.new value: num
+
+          Query.start new_query, parent_path, client, limit_type: :last
         end
 
         ##
@@ -477,6 +548,10 @@ module Google
         def start_at *values
           raise ArgumentError, "must provide values" if values.empty?
 
+          if limit_type == :last
+            raise "cannot call start_at after calling limit_to_last"
+          end
+
           new_query = @query.dup
           new_query ||= StructuredQuery.new
 
@@ -484,7 +559,7 @@ module Google
           cursor.before = true
           new_query.start_at = cursor
 
-          Query.start new_query, parent_path, client
+          Query.start new_query, parent_path, client, limit_type: limit_type
         end
 
         ##
@@ -581,6 +656,11 @@ module Google
         def start_after *values
           raise ArgumentError, "must provide values" if values.empty?
 
+          if limit_type == :last
+            raise "cannot call start_after after calling limit_to_last"
+          end
+
+
           new_query = @query.dup
           new_query ||= StructuredQuery.new
 
@@ -588,7 +668,7 @@ module Google
           cursor.before = false
           new_query.start_at = cursor
 
-          Query.start new_query, parent_path, client
+          Query.start new_query, parent_path, client, limit_type: limit_type
         end
 
         ##
@@ -685,6 +765,11 @@ module Google
         def end_before *values
           raise ArgumentError, "must provide values" if values.empty?
 
+          if limit_type == :last
+            raise "cannot call end_before after calling limit_to_last"
+          end
+
+
           new_query = @query.dup
           new_query ||= StructuredQuery.new
 
@@ -692,7 +777,7 @@ module Google
           cursor.before = true
           new_query.end_at = cursor
 
-          Query.start new_query, parent_path, client
+          Query.start new_query, parent_path, client, limit_type: limit_type
         end
 
         ##
@@ -789,6 +874,11 @@ module Google
         def end_at *values
           raise ArgumentError, "must provide values" if values.empty?
 
+          if limit_type == :last
+            raise "cannot call end_at after calling limit_to_last"
+          end
+
+
           new_query = @query.dup
           new_query ||= StructuredQuery.new
 
@@ -796,7 +886,7 @@ module Google
           cursor.before = false
           new_query.end_at = cursor
 
-          Query.start new_query, parent_path, client
+          Query.start new_query, parent_path, client, limit_type: limit_type
         end
 
         ##
@@ -828,6 +918,10 @@ module Google
           return enum_for :get unless block_given?
 
           results = service.run_query parent_path, @query
+
+          # Reverse the results for Query#limit_to_last queries since that method reversed the order_by directions.
+          results = results.to_a.reverse if limit_type == :last
+
           results.each do |result|
             next if result.document.nil?
             yield DocumentSnapshot.from_query_result result, client
@@ -870,11 +964,12 @@ module Google
 
         ##
         # @private Start a new Query.
-        def self.start query, parent_path, client
+        def self.start query, parent_path, client, limit_type: nil
           query ||= StructuredQuery.new
           Query.new.tap do |q|
             q.instance_variable_set :@query, query
             q.instance_variable_set :@parent_path, parent_path
+            q.instance_variable_set :@limit_type, limit_type
             q.instance_variable_set :@client, client
           end
         end
@@ -883,7 +978,7 @@ module Google
 
         ##
         # @private
-        StructuredQuery = Google::Firestore::V1::StructuredQuery
+        StructuredQuery = Google::Cloud::Firestore::V1::StructuredQuery
 
         ##
         # @private
@@ -901,23 +996,20 @@ module Google
           "eq"                 => :EQUAL,
           "eql"                => :EQUAL,
           "is"                 => :EQUAL,
+          "!="                 => :NOT_EQUAL,
           "array_contains"     => :ARRAY_CONTAINS,
           "array-contains"     => :ARRAY_CONTAINS,
           "include"            => :ARRAY_CONTAINS,
           "include?"           => :ARRAY_CONTAINS,
           "has"                => :ARRAY_CONTAINS,
           "in"                 => :IN,
+          "not_in"             => :NOT_IN,
+          "not-in"             => :NOT_IN,
           "array_contains_any" => :ARRAY_CONTAINS_ANY,
           "array-contains-any" => :ARRAY_CONTAINS_ANY
         }.freeze
         ##
         # @private
-        EQUALITY_FILTERS = %i[
-          EQUAL
-          ARRAY_CONTAINS
-        ].freeze
-        ##
-        # @private
         INEQUALITY_FILTERS = %i[
           LESS_THAN
           LESS_THAN_OR_EQUAL
@@ -945,12 +1037,13 @@ module Google
           raise ArgumentError, "unknown operator #{op}" if operator.nil?
 
           if value_unary? value
-            if operator != :EQUAL
-              raise ArgumentError,
-                    "can only check equality for #{value} values"
-            end
-
-            operator = value_nan?(value) ? :IS_NAN : :IS_NULL
+            operator = if operator == :EQUAL
+                         value_nan?(value) ? :IS_NAN : :IS_NULL
+                       elsif operator == :NOT_EQUAL
+                         value_nan?(value) ? :IS_NOT_NAN : :IS_NOT_NULL
+                       else
+                         raise ArgumentError, "can only perform '==' and '!=' comparisons on #{value} values"
+                       end
 
             return StructuredQuery::Filter.new(
               unary_filter: StructuredQuery::UnaryFilter.new(
@@ -987,7 +1080,7 @@ module Google
         end
 
         def order_direction direction
-          return :DESCENDING if direction.to_s.downcase.start_with? "d".freeze
+          return :DESCENDING if direction.to_s.downcase.start_with? "d"
           :ASCENDING
         end
 
@@ -1014,7 +1107,7 @@ module Google
             Convert.raw_to_value value
           end
 
-          Google::Firestore::V1::Cursor.new values: values
+          Google::Cloud::Firestore::V1::Cursor.new values: values
         end
 
         def snapshot_to_cursor snapshot, query

data/lib/google/cloud/firestore/query_listener.rb

@@ -41,17 +41,21 @@ module Google
       #   listener.stop
       #
       class QueryListener
+        include MonitorMixin
         ##
         # @private
         # Creates the watch stream and listener object.
         def initialize query, &callback
+          super() # to init MonitorMixin
+
           @query = query
           raise ArgumentError if @query.nil?
 
           @callback = callback
           raise ArgumentError if @callback.nil?
+          @error_callbacks = []
 
-          @listener = Watch::Listener.for_query query, &callback
+          @listener = Watch::Listener.for_query self, query, &callback
         end
 
         ##
@@ -112,6 +116,83 @@ module Google
         def stopped?
           @listener.stopped?
         end
+
+        ##
+        # Register to be notified of errors when raised.
+        #
+        # If an unhandled error has occurred the listener will attempt to
+        # recover from the error and resume listening.
+        #
+        # Multiple error handlers can be added.
+        #
+        # @yield [callback] The block to be called when an error is raised.
+        # @yieldparam [Exception] error The error raised.
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   # Create a query
+        #   query = firestore.col(:cities).order(:population, :desc)
+        #
+        #   listener = query.listen do |snapshot|
+        #     puts "The query snapshot has #{snapshot.docs.count} documents "
+        #     puts "and has #{snapshot.changes.count} changes."
+        #   end
+        #
+        #   # Register to be notified when unhandled errors occur.
+        #   listener.on_error do |error|
+        #     puts error
+        #   end
+        #
+        #   # When ready, stop the listen operation and close the stream.
+        #   listener.stop
+        #
+        def on_error &block
+          raise ArgumentError, "on_error must be called with a block" unless block_given?
+          synchronize { @error_callbacks << block }
+        end
+
+        ##
+        # The most recent unhandled error to occur while listening for changes.
+        #
+        # If an unhandled error has occurred the listener will attempt to
+        # recover from the error and resume listening.
+        #
+        # @return [Exception, nil] error The most recent error raised.
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   # Create a query
+        #   query = firestore.col(:cities).order(:population, :desc)
+        #
+        #   listener = query.listen do |snapshot|
+        #     puts "The query snapshot has #{snapshot.docs.count} documents "
+        #     puts "and has #{snapshot.changes.count} changes."
+        #   end
+        #
+        #   # If an error was raised, it can be retrieved here:
+        #   listener.last_error #=> nil
+        #
+        #   # When ready, stop the listen operation and close the stream.
+        #   listener.stop
+        #
+        def last_error
+          synchronize { @last_error }
+        end
+
+        # @private Pass the error to user-provided error callbacks.
+        def error! error
+          error_callbacks = synchronize do
+            @last_error = error
+            @error_callbacks.dup
+          end
+          error_callbacks.each { |error_callback| error_callback.call error }
+        end
       end
     end
   end