google-cloud-firestore 2.0.0 → 2.4.1

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

@@ -14,11 +14,14 @@
 
 
 require "google/cloud/firestore/watch/listener"
+require "monitor"
 
 module Google
   module Cloud
     module Firestore
       ##
+      # # DocumentListener
+      #
       # An ongoing listen operation on a document reference. This is returned by
       # calling {DocumentReference#listen}.
       #
@@ -31,25 +34,28 @@ module Google
       #   nyc_ref = firestore.doc "cities/NYC"
       #
       #   listener = nyc_ref.listen do |snapshot|
-      #     puts "The population of #{snapshot[:name]} "
-      #     puts "is #{snapshot[:population]}."
+      #     puts "The population of #{snapshot[:name]} is #{snapshot[:population]}."
       #   end
       #
       #   # When ready, stop the listen operation and close the stream.
       #   listener.stop
       #
       class DocumentListener
+        include MonitorMixin
         ##
         # @private
         # Creates the watch stream and listener object.
         def initialize doc_ref, &callback
+          super() # to init MonitorMixin
+
           @doc_ref = doc_ref
           raise ArgumentError if @doc_ref.nil?
 
           @callback = callback
           raise ArgumentError if @callback.nil?
+          @error_callbacks = []
 
-          @listener = Watch::Listener.for_doc_ref doc_ref do |query_snp|
+          @listener = Watch::Listener.for_doc_ref self, doc_ref do |query_snp|
             doc_snp = query_snp.docs.find { |doc| doc.path == @doc_ref.path }
 
             if doc_snp.nil?
@@ -80,8 +86,7 @@ module Google
         #   nyc_ref = firestore.doc "cities/NYC"
         #
         #   listener = nyc_ref.listen do |snapshot|
-        #     puts "The population of #{snapshot[:name]} "
-        #     puts "is #{snapshot[:population]}."
+        #     puts "The population of #{snapshot[:name]} is #{snapshot[:population]}."
         #   end
         #
         #   # When ready, stop the listen operation and close the stream.
@@ -103,8 +108,7 @@ module Google
         #   nyc_ref = firestore.doc "cities/NYC"
         #
         #   listener = nyc_ref.listen do |snapshot|
-        #     puts "The population of #{snapshot[:name]} "
-        #     puts "is #{snapshot[:population]}."
+        #     puts "The population of #{snapshot[:name]} is #{snapshot[:population]}."
         #   end
         #
         #   # Checks if the listener is stopped.
@@ -119,6 +123,81 @@ 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
+        #
+        #   # Get a document reference
+        #   nyc_ref = firestore.doc "cities/NYC"
+        #
+        #   listener = nyc_ref.listen do |snapshot|
+        #     puts "The population of #{snapshot[:name]} is #{snapshot[:population]}."
+        #   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
+        #
+        #   # Get a document reference
+        #   nyc_ref = firestore.doc "cities/NYC"
+        #
+        #   listener = nyc_ref.listen do |snapshot|
+        #     puts "The population of #{snapshot[:name]} is #{snapshot[:population]}."
+        #   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

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

@@ -168,8 +168,7 @@ module Google
         #   nyc_ref = firestore.doc "cities/NYC"
         #
         #   listener = nyc_ref.listen do |snapshot|
-        #     puts "The population of #{snapshot[:name]} "
-        #     puts "is #{snapshot[:population]}."
+        #     puts "The population of #{snapshot[:name]} is #{snapshot[:population]}."
         #   end
         #
         #   # When ready, stop the listen operation and close the stream.

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

@@ -53,8 +53,7 @@ module Google
       #   nyc_ref = firestore.doc "cities/NYC"
       #
       #   listener = nyc_ref.listen do |snapshot|
-      #     puts "The population of #{snapshot[:name]} "
-      #     puts "is #{snapshot[:population]}."
+      #     puts "The population of #{snapshot[:name]} is #{snapshot[:population]}."
       #   end
       #
       #   # When ready, stop the listen operation and close the stream.

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

@@ -62,6 +62,10 @@ module Google
         # @private The parent path for the query.
         attr_accessor :parent_path
 
+        ##
+        # @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
@@ -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(