google-cloud-firestore 2.7.2 → 2.15.0

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

@@ -86,8 +86,9 @@ module Google
           def next
             return nil unless next?
             ensure_client!
-            grpc = @client.service.list_documents @parent, @collection_id, token: token, max: @max
-            self.class.from_grpc grpc, @client, @parent, @collection_id, @max
+            grpc = @client.service.list_documents @parent, @collection_id, token: token, max: @max, \
+              read_time: @read_time
+            self.class.from_grpc grpc, @client, @parent, @collection_id, @max, read_time: @read_time
           end
 
           ##
@@ -162,7 +163,7 @@ module Google
           ##
           # @private New DocumentReference::List from a
           # Google::Cloud::Firestore::V1::ListDocumentsResponse object.
-          def self.from_grpc grpc, client, parent, collection_id, max = nil
+          def self.from_grpc grpc, client, parent, collection_id, max = nil, read_time: nil
             documents = List.new(Array(grpc.documents).map do |document|
               DocumentReference.from_path document.name, client
             end)
@@ -173,6 +174,7 @@ module Google
             documents.instance_variable_set :@token, token
             documents.instance_variable_set :@client, client
             documents.instance_variable_set :@max, max
+            documents.instance_variable_set :@read_time, read_time
             documents
           end
 

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

@@ -73,6 +73,9 @@ module Google
         ##
         # Retrieves an enumerator for the collections nested under the document snapshot.
         #
+        # @param [Time] read_time Reads documents as they were at the given time.
+        #   This may not be older than 270 seconds. Optional
+        #
         # @yield [collections] The block for accessing the collections.
         # @yieldparam [CollectionReference] collection A collection reference object.
         #
@@ -91,10 +94,24 @@ module Google
         #     puts col.collection_id
         #   end
         #
-        def cols &block
+        # @example Get collection with read time
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   read_time = Time.now
+        #
+        #   # Get a document reference
+        #   nyc_ref = firestore.doc "cities/NYC"
+        #
+        #   nyc_ref.cols(read_time: read_time).each do |col|
+        #     puts col.collection_id
+        #   end
+        #
+        def cols read_time: nil, &block
           ensure_service!
-          grpc = service.list_collections path
-          cols_enum = CollectionReferenceList.from_grpc(grpc, client, path).all
+          grpc = service.list_collections path, read_time: read_time
+          cols_enum = CollectionReferenceList.from_grpc(grpc, client, path, read_time: read_time).all
           cols_enum.each(&block) if block_given?
           cols_enum
         end

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

@@ -318,7 +318,7 @@ module Google
         ##
         # @private
         def eql? other
-          return nil unless other.is_a? DocumentSnapshot
+          return false unless other.is_a? DocumentSnapshot
           return data.eql? other.data if path == other.path
           path.eql? other.path
         end

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

@@ -0,0 +1,60 @@
+# Copyright 2023 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require "google/cloud/errors"
+
+module Google
+  module Cloud
+    module Firestore
+      ##
+      # Indicates that the an error was reported while scheduling
+      # BulkWriter operations.
+      #
+      class BulkWriterSchedulerError < Google::Cloud::Error
+        def initialize message
+          super "BulkWriterSchedulerError : #{message}"
+        end
+      end
+
+      ##
+      # Indicates that the an error was reported while committing a
+      # batch of operations.
+      #
+      class BulkCommitBatchError < Google::Cloud::Error
+        def initialize message
+          super "BulkCommitBatchError : #{message}"
+        end
+      end
+
+      ##
+      # Indicates that the an error was reported while parsing response for
+      # BulkWriterOperation.
+      #
+      class BulkWriterOperationError < Google::Cloud::Error
+        def initialize message
+          super "BulkWriterOperationError : #{message}"
+        end
+      end
+
+      ##
+      # Indicates that the an error was reported in BulkWriter.
+      #
+      class BulkWriterError < Google::Cloud::Error
+        def initialize message
+          super "BulkWriterError : #{message}"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,326 @@
+# Copyright 2023 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+
+require "google/cloud/firestore/v1"
+
+module Google
+  module Cloud
+    module Firestore
+      ##
+      # Represents the filter for structured query.
+      #
+      class Filter
+        ##
+        # @private Object of type
+        # Google::Cloud::Firestore::V1::StructuredQuery::Filter
+        attr_accessor :filter
+
+        ##
+        # Create a Filter object.
+        #
+        # @param field [FieldPath, String, Symbol] A field path to filter
+        #   results with.
+        #   If a {FieldPath} object is not provided then the field will be
+        #   treated as a dotted string, meaning the string represents individual
+        #   fields joined by ".". Fields containing `~`, `*`, `/`, `[`, `]`, and
+        #   `.` cannot be in a dotted string, and should provided using a
+        #   {FieldPath} object instead.
+        #
+        # @param operator [String, Symbol] The operation to compare the field
+        #   to. Acceptable values include:
+        #   * less than: `<`, `lt`
+        #   * less than or equal: `<=`, `lte`
+        #   * 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 value [Object] The value to compare the property to. Defaults to nil.
+        #   Possible values are:
+        #   * Integer
+        #   * Float/BigDecimal
+        #   * String
+        #   * Boolean
+        #   * Array
+        #   * Date/Time
+        #   * StringIO
+        #   * Google::Cloud::Datastore::Key
+        #   * Google::Cloud::Datastore::Entity
+        #   * nil
+        #
+        # @return [Google::Cloud::Firestore::Filter] New filter for the given condition
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #
+        #   # Create a Filter
+        #   Google::Cloud::Firestore::Filter.new(:population, :>=, 1000000)
+        #
+        def initialize field, operator, value
+          @filter = create_filter field, operator, value
+        end
+
+        ##
+        # Joins filter using AND operator.
+        #
+        # @overload where(filter)
+        #   Pass Firestore::Filter to `where` via field_or_filter argument.
+        #
+        #  @param filter [::Google::Cloud::Firestore::Filter]
+        #
+        # @overload where(field, operator, value)
+        #   Pass arguments to `where` via positional arguments.
+        #
+        #   @param field [FieldPath, String, Symbol] A field path to filter
+        #     results with.
+        #     If a {FieldPath} object is not provided then the field will be
+        #     treated as a dotted string, meaning the string represents individual
+        #     fields joined by ".". Fields containing `~`, `*`, `/`, `[`, `]`, and
+        #     `.` cannot be in a dotted string, and should provided using a
+        #     {FieldPath} object instead.
+        #
+        #   @param operator [String, Symbol] The operation to compare the field
+        #     to. Acceptable values include:
+        #     * less than: `<`, `lt`
+        #     * less than or equal: `<=`, `lte`
+        #     * 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 value [Object] The value to compare the property to. Defaults to nil.
+        #     Possible values are:
+        #     * Integer
+        #     * Float/BigDecimal
+        #     * String
+        #     * Boolean
+        #     * Array
+        #     * Date/Time
+        #     * StringIO
+        #     * Google::Cloud::Datastore::Key
+        #     * Google::Cloud::Datastore::Entity
+        #     * nil
+        #
+        # @return [Filter] New Filter object.
+        #
+        # @example Pass a Filter type object in argument
+        #   require "google/cloud/firestore"
+        #
+        #   filter_1 = Google::Cloud::Firestore.Firestore.new(:population, :>=, 1000000)
+        #   filter_2 = Google::Cloud::Firestore.Firestore.new("done", "=", "false")
+        #
+        #   filter = filter_1.and(filter_2)
+        #
+        # @example Pass filter conditions in the argument
+        #   require "google/cloud/firestore"
+        #
+        #   filter_1 = Google::Cloud::Firestore.Firestore.new(:population, :>=, 1000000)
+        #
+        #   filter = filter_1.and("done", "=", "false")
+        #
+        def and filter_or_field = nil, operator = nil, value = nil
+          combine_filters composite_filter_and, filter_or_field, operator, value
+        end
+
+        ##
+        # Joins filter using OR operator.
+        #
+        # @overload where(filter)
+        #   Pass Firestore::Filter to `where` via field_or_filter argument.
+        #
+        #  @param filter [::Google::Cloud::Firestore::Filter]
+        #
+        # @overload where(field, operator, value)
+        #   Pass arguments to `where` via positional arguments.
+        #
+        #   @param field [FieldPath, String, Symbol] A field path to filter
+        #     results with.
+        #     If a {FieldPath} object is not provided then the field will be
+        #     treated as a dotted string, meaning the string represents individual
+        #     fields joined by ".". Fields containing `~`, `*`, `/`, `[`, `]`, and
+        #     `.` cannot be in a dotted string, and should provided using a
+        #     {FieldPath} object instead.
+        #
+        #   @param operator [String, Symbol] The operation to compare the field
+        #     to. Acceptable values include:
+        #     * less than: `<`, `lt`
+        #     * less than or equal: `<=`, `lte`
+        #     * 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 value [Object] The value to compare the property to. Defaults to nil.
+        #     Possible values are:
+        #     * Integer
+        #     * Float/BigDecimal
+        #     * String
+        #     * Boolean
+        #     * Array
+        #     * Date/Time
+        #     * StringIO
+        #     * Google::Cloud::Datastore::Key
+        #     * Google::Cloud::Datastore::Entity
+        #     * nil
+        #
+        # @return [Filter] New Filter object.
+        #
+        # @example Pass a Filter type object in argument
+        #   require "google/cloud/firestore"
+        #
+        #   filter_1 = Google::Cloud::Firestore.Firestore.new(:population, :>=, 1000000)
+        #   filter_2 = Google::Cloud::Firestore.Firestore.new("done", "=", "false")
+        #
+        #   filter = filter_1.or(filter_2)
+        #
+        # @example Pass filter conditions in the argument
+        #   require "google/cloud/firestore"
+        #
+        #   filter_1 = Google::Cloud::Firestore.Firestore.new(:population, :>=, 1000000)
+        #
+        #   filter = filter_1.or("done", "=", "false")
+        #
+        def or filter_or_field = nil, operator = nil, value = nil
+          combine_filters composite_filter_or, filter_or_field, operator, value
+        end
+
+        private
+
+        ##
+        # @private
+        StructuredQuery = Google::Cloud::Firestore::V1::StructuredQuery
+
+        ##
+        # @private
+        FILTER_OPS = {
+          "<"                  => :LESS_THAN,
+          "lt"                 => :LESS_THAN,
+          "<="                 => :LESS_THAN_OR_EQUAL,
+          "lte"                => :LESS_THAN_OR_EQUAL,
+          ">"                  => :GREATER_THAN,
+          "gt"                 => :GREATER_THAN,
+          ">="                 => :GREATER_THAN_OR_EQUAL,
+          "gte"                => :GREATER_THAN_OR_EQUAL,
+          "="                  => :EQUAL,
+          "=="                 => :EQUAL,
+          "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
+        INEQUALITY_FILTERS = [
+          :LESS_THAN,
+          :LESS_THAN_OR_EQUAL,
+          :GREATER_THAN,
+          :GREATER_THAN_OR_EQUAL
+        ].freeze
+
+        def composite_filter_and
+          StructuredQuery::Filter.new(
+            composite_filter: StructuredQuery::CompositeFilter.new(op: :AND)
+          )
+        end
+
+        def composite_filter_or
+          StructuredQuery::Filter.new(
+            composite_filter: StructuredQuery::CompositeFilter.new(op: :OR)
+          )
+        end
+
+        def combine_filters new_filter, filter_or_field, operator, value
+          new_filter.composite_filter.filters << @filter
+          new_filter.composite_filter.filters << if filter_or_field.is_a? Google::Cloud::Firestore::Filter
+                                                   filter_or_field.filter
+                                                 else
+                                                   create_filter filter_or_field, operator, value
+                                                 end
+          dup.tap do |f|
+            f.filter = new_filter
+          end
+        end
+
+        def value_nil? value
+          [nil, :null, :nil].include? value
+        end
+
+        def value_nan? value
+          # Comparing NaN values raises, so check for #nan? first.
+          return true if value.respond_to?(:nan?) && value.nan?
+          [:nan].include? value
+        end
+
+        def value_unary? value
+          value_nil?(value) || value_nan?(value)
+        end
+
+        def create_filter field, op_key, value
+          return if field.nil? && op_key.nil? && value.nil?
+          field = FieldPath.parse field unless field.is_a? FieldPath
+          field = StructuredQuery::FieldReference.new field_path: field.formatted_string.to_s
+          operator = FILTER_OPS[op_key.to_s.downcase]
+          raise ArgumentError, "unknown operator #{op_key}" if operator.nil?
+
+          if value_unary? value
+            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(
+                field: field, op: operator
+              )
+            )
+          end
+
+          value = Convert.raw_to_value value
+          StructuredQuery::Filter.new(
+            field_filter: StructuredQuery::FieldFilter.new(
+              field: field, op: operator, value: value
+            )
+          )
+        end
+      end
+    end
+  end
+end

data/lib/google/cloud/firestore/promise/future.rb

@@ -0,0 +1,97 @@
+# Copyright 2023 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+module Google
+  module Cloud
+    module Firestore
+      module Promise
+        ##
+        # # Future
+        #
+        # A Future object represents a value which will become available in future.
+        # May reject with a reason instead, e.g. when the tasks raises an exception.
+        #
+        class Future
+          ##
+          # Initialize the future object
+          #
+          def initialize future
+            @future = future
+          end
+
+          # Is it in fulfilled state?
+          #
+          # @return [Boolean]
+          def fulfilled?
+            @future.fulfilled?
+          end
+
+          # Is it in rejected state?
+          #
+          # @return [Boolean]
+          def rejected?
+            @future.rejected?
+          end
+
+          ##
+          # Method waits for the timeout duration and return the value of the future if
+          # fulfilled, timeout value in case of timeout and nil in case of rejection.
+          #
+          # @param [Integer] timeout the maximum time in seconds to wait
+          # @param [Object] timeout_value a value returned by the method when it times out
+          # @return [Object, nil, timeout_value] the value of the Future when fulfilled,
+          #  timeout_value on timeout, nil on rejection.
+          def value timeout = nil, timeout_value = nil
+            @future.value timeout, timeout_value
+          end
+
+          # Returns reason of future's rejection.
+          #
+          # @return [Object, timeout_value] the reason, or timeout_value on timeout, or nil on fulfillment.
+          def reason timeout = nil, timeout_value = nil
+            @future.reason timeout, timeout_value
+          end
+
+          ##
+          # Method waits for the timeout duration and raise exception on rejection
+          #
+          # @param [Integer] timeout the maximum time in seconds to wait
+          def wait! timeout = nil
+            @future.wait! timeout
+          end
+
+          ##
+          # Chains the task to be executed synchronously after it fulfills. Does not run
+          # the task if it rejects. It will resolve though, triggering any dependent futures.
+          #
+          # @return [Future]
+          # @yield [reason, *args] to the task.
+          def then *args, &task
+            Future.new @future.then(*args, &task)
+          end
+
+          # Chains the task to be executed synchronously on executor after it rejects. Does
+          # not run the task if it fulfills. It will resolve though, triggering any
+          # dependent futures.
+          #
+          # @return [Future]
+          # @yield [reason, *args] to the task.
+          def rescue *args, &task
+            Future.new @future.rescue(*args, &task)
+          end
+        end
+      end
+    end
+  end
+end