google-cloud-firestore 2.1.0 → 2.5.0

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

@@ -90,11 +90,11 @@ module Google
         #     puts col.collection_id
         #   end
         #
-        def cols
+        def cols &block
           ensure_service!
           grpc = service.list_collections path
           cols_enum = CollectionReferenceList.from_grpc(grpc, client, path).all
-          cols_enum.each { |c| yield c } if block_given?
+          cols_enum.each(&block) if block_given?
           cols_enum
         end
         alias collections cols
@@ -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_reference/list.rb

@@ -86,8 +86,7 @@ module Google
           def next
             return nil unless next?
             ensure_client!
-            options = { token: token, max: @max }
-            grpc = @client.service.list_documents @parent, @collection_id, options
+            grpc = @client.service.list_documents @parent, @collection_id, token: token, max: @max
             self.class.from_grpc grpc, @client, @parent, @collection_id, @max
           end
 
@@ -143,17 +142,17 @@ module Google
           #     puts doc_ref.document_id
           #   end
           #
-          def all request_limit: nil
+          def all request_limit: nil, &block
             request_limit = request_limit.to_i if request_limit
             unless block_given?
               return enum_for :all, request_limit: request_limit
             end
             results = self
             loop do
-              results.each { |r| yield r }
+              results.each(&block)
               if request_limit
                 request_limit -= 1
-                break if request_limit < 0
+                break if request_limit.negative?
               end
               break unless results.next?
               results = results.next

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/field_path.rb

@@ -210,14 +210,14 @@ module Google
         protected
 
         START_FIELD_PATH_CHARS = /\A[a-zA-Z_]/.freeze
-        INVALID_FIELD_PATH_CHARS = %r{[\~\*\/\[\]]}.freeze
+        INVALID_FIELD_PATH_CHARS = %r{[~*/\[\]]}.freeze
 
         def escape_field_for_path field
           field = String field
 
           if INVALID_FIELD_PATH_CHARS.match(field) ||
              field["."] || field["`"] || field["\\"]
-            escaped_field = field.gsub(/[\`\\]/, "`" => "\\\`", "\\" => "\\\\")
+            escaped_field = field.gsub(/[`\\]/, "`" => "\\\`", "\\" => "\\\\")
             return "`#{escaped_field}`"
           end
 

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

@@ -216,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.
         #
@@ -993,28 +996,25 @@ 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
-          GREATER_THAN
-          GREATER_THAN_OR_EQUAL
+        INEQUALITY_FILTERS = [
+          :LESS_THAN,
+          :LESS_THAN_OR_EQUAL,
+          :GREATER_THAN,
+          :GREATER_THAN_OR_EQUAL
         ].freeze
 
         def value_nil? value
@@ -1031,18 +1031,20 @@ module Google
           value_nil?(value) || value_nan?(value)
         end
 
-        def filter name, op, value
+        def filter name, op_key, value
           field = StructuredQuery::FieldReference.new field_path: name.to_s
-          operator = FILTER_OPS[op.to_s.downcase]
-          raise ArgumentError, "unknown operator #{op}" if operator.nil?
+          operator = FILTER_OPS[op_key.to_s.downcase]
+          raise ArgumentError, "unknown operator #{op_key}" 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 = case operator
+                       when :EQUAL
+                         value_nan?(value) ? :IS_NAN : :IS_NULL
+                       when :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(

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

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

@@ -26,7 +26,10 @@ module Google
       # @private Represents the gRPC Firestore service, including all the API
       # methods.
       class Service
-        attr_accessor :project, :credentials, :timeout, :host
+        attr_accessor :project
+        attr_accessor :credentials
+        attr_accessor :timeout
+        attr_accessor :host
 
         ##
         # Creates a new Service instance.

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

@@ -131,7 +131,7 @@ module Google
           ensure_service!
 
           unless block_given?
-            return enum_for :get_all, docs, field_mask: field_mask
+            return enum_for :get_all, *docs, field_mask: field_mask
           end
 
           doc_paths = Array(docs).flatten.map do |doc_path|
@@ -321,7 +321,7 @@ module Google
 
           doc_path = coalesce_doc_path_argument doc
 
-          @writes << Convert.writes_for_create(doc_path, data)
+          @writes << Convert.write_for_create(doc_path, data)
 
           nil
         end
@@ -422,7 +422,7 @@ module Google
 
           doc_path = coalesce_doc_path_argument doc
 
-          @writes << Convert.writes_for_set(doc_path, data, merge: merge)
+          @writes << Convert.write_for_set(doc_path, data, merge: merge)
 
           nil
         end
@@ -526,8 +526,8 @@ module Google
 
           doc_path = coalesce_doc_path_argument doc
 
-          @writes << Convert.writes_for_update(doc_path, data,
-                                               update_time: update_time)
+          @writes << Convert.write_for_update(doc_path, data,
+                                              update_time: update_time)
 
           nil
         end