google-cloud-firestore 2.3.0 → 2.6.0

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

@@ -18,6 +18,7 @@ require "google/cloud/firestore/document_snapshot"
 require "google/cloud/firestore/collection_reference"
 require "google/cloud/firestore/document_listener"
 require "google/cloud/firestore/document_reference/list"
+require "google/cloud/firestore/resource_path"
 
 module Google
   module Cloud
@@ -90,11 +91,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
@@ -459,6 +460,12 @@ module Google
 
         # @!endgroup
 
+        # @private
+        def <=> other
+          return nil unless other.is_a? self.class
+          ResourcePath.from_path(path) <=> ResourcePath.from_path(other.path)
+        end
+
         ##
         # @private New DocumentReference object from a path.
         def self.from_path path, client

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
 
@@ -110,7 +109,7 @@ module Google
           #
           # @return [Enumerator]
           #
-          # @example Iterating each document reference by passing a block:
+          # @example Iterating each document reference by passing a block or proc:
           #   require "google/cloud/firestore"
           #
           #   firestore = Google::Cloud::Firestore.new
@@ -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/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/field_value.rb

@@ -27,9 +27,14 @@ module Google
       #
       #   firestore = Google::Cloud::Firestore.new
       #
-      #   user_snap = firestore.doc("users/frank").get
+      #   # Get a document reference
+      #   nyc_ref = firestore.doc "cities/NYC"
       #
-      #   # TODO
+      #   # Set the population to increment by 1.
+      #   increment_value = Google::Cloud::Firestore::FieldValue.increment 1
+      #
+      #   nyc_ref.update({ name: "New York City",
+      #                    population: increment_value })
       #
       class FieldValue
         ##

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

@@ -17,6 +17,7 @@ require "google/cloud/firestore/v1"
 require "google/cloud/firestore/document_snapshot"
 require "google/cloud/firestore/query_listener"
 require "google/cloud/firestore/convert"
+require "json"
 
 module Google
   module Cloud
@@ -74,6 +75,16 @@ module Google
         # @private The firestore client object.
         attr_accessor :client
 
+        ##
+        # @private Creates a new Query.
+        def initialize query, parent_path, client, limit_type: nil
+          query ||= StructuredQuery.new
+          @query = query
+          @parent_path = parent_path
+          @limit_type = limit_type
+          @client = client
+        end
+
         ##
         # Restricts documents matching the query to return only data for the
         # provided fields.
@@ -216,6 +227,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.
         #
@@ -959,16 +973,71 @@ module Google
         end
         alias on_snapshot listen
 
+        ##
+        # Serializes the instance to a JSON text string. See also {Query.from_json}.
+        #
+        # @return [String] A JSON text string.
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #   query = firestore.col(:cities).select(:population)
+        #
+        #   json = query.to_json
+        #
+        #   new_query = Google::Cloud::Firestore::Query.from_json json, firestore
+        #
+        #   new_query.get do |city|
+        #     puts "#{city.document_id} has #{city[:population]} residents."
+        #   end
+        #
+        def to_json options = nil
+          query_json = Google::Cloud::Firestore::V1::StructuredQuery.encode_json query
+          {
+            "query" => JSON.parse(query_json),
+            "parent_path" => parent_path,
+            "limit_type" => limit_type
+          }.to_json options
+        end
+
+        ##
+        # Deserializes a JSON text string serialized from this class and returns it as a new instance. See also
+        # {#to_json}.
+        #
+        # @param [String] json A JSON text string serialized using {#to_json}.
+        # @param [Google::Cloud::Firestore::Client] client A connected client instance.
+        #
+        # @return [Query] A new query equal to the original query used to create the JSON text string.
+        #
+        # @example
+        #   require "google/cloud/firestore"
+        #
+        #   firestore = Google::Cloud::Firestore.new
+        #   query = firestore.col(:cities).select(:population)
+        #
+        #   json = query.to_json
+        #
+        #   new_query = Google::Cloud::Firestore::Query.from_json json, firestore
+        #
+        #   new_query.get do |city|
+        #     puts "#{city.document_id} has #{city[:population]} residents."
+        #   end
+        #
+        def self.from_json json, client
+          raise ArgumentError, "client is required" unless client
+
+          json = JSON.parse json
+          query_json = json["query"]
+          raise ArgumentError, "Field 'query' is required" unless query_json
+          query = Google::Cloud::Firestore::V1::StructuredQuery.decode_json query_json.to_json
+          start query, json["parent_path"], client, limit_type: json["limit_type"]&.to_sym
+        end
+
         ##
         # @private Start a new Query.
         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
+          new query, parent_path, client, limit_type: limit_type
         end
 
         protected
@@ -993,28 +1062,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 +1097,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(
@@ -1092,11 +1160,14 @@ module Google
             return snapshot_to_cursor values.first, query
           end
 
+          # The *values param in start_at, start_after, etc. will wrap an array argument in an array, so unwrap it here.
+          values = values.first if values.count == 1 && values.first.is_a?(Array)
+
           # pair values with their field_paths to ensure correct formatting
           order_field_paths = order_by_field_paths query
           if values.count > order_field_paths.count
             # raise if too many values provided for the cursor
-            raise ArgumentError, "too many values"
+            raise ArgumentError, "There cannot be more cursor values than order by fields"
           end
 
           values = values.zip(order_field_paths).map do |value, field_path|
@@ -1128,7 +1199,6 @@ module Google
               snapshot[field_path]
             end
           end
-
           values_to_cursor values, query
         end
 

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

@@ -0,0 +1,80 @@
+# Copyright 2021 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
+      ##
+      # # QueryPartition
+      #
+      # Represents a split point that can be used in a query as a starting and/or end point for the query results.
+      #
+      # The cursors returned by {#start_at} and {#end_before} can only be used in a query that matches the constraint of
+      # the query that produced this partition.
+      #
+      # See {CollectionGroup#partitions} and {Query}.
+      #
+      # @!attribute [r] start_at
+      #   The cursor values that define the first result for this partition, or `nil` if this is the first partition.
+      #   Returns an array of values that represent a position, in the order they appear in the order by clause of the
+      #   query. Can contain fewer values than specified in the order by clause. Will be used in the query returned by
+      #   {#to_query}.
+      #   @return [Array<Object>, nil] Typically, the values are {DocumentReference} objects.
+      # @!attribute [r] end_before
+      #   The cursor values that define the first result after this partition, or `nil` if this is the last partition.
+      #   Returns an array of values that represent a position, in the order they appear in the order by clause of the
+      #   query.  Can contain fewer values than specified in the order by clause. Will be used in the query returned by
+      #   {#to_query}.
+      #   @return [Array<Object>, nil] Typically, the values are {DocumentReference} objects.
+      #
+      # @example
+      #   require "google/cloud/firestore"
+      #
+      #   firestore = Google::Cloud::Firestore.new
+      #
+      #   col_group = firestore.col_group "cities"
+      #
+      #   partitions = col_group.partitions 3
+      #
+      #   queries = partitions.map(&:to_query)
+      #
+      class QueryPartition
+        attr_reader :start_at
+        attr_reader :end_before
+
+        ##
+        # @private New QueryPartition from query and Cursor
+        def initialize query, start_at, end_before
+          @query = query
+          @start_at = start_at
+          @end_before = end_before
+        end
+
+        ##
+        # Creates a new query that only returns the documents for this partition, using the cursor values from
+        # {#start_at} and {#end_before}.
+        #
+        # @return [Query] The query for the partition.
+        #
+        def to_query
+          base_query = @query
+          base_query = base_query.start_at start_at if start_at
+          base_query = base_query.end_before end_before if end_before
+          base_query
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,58 @@
+# Copyright 2021 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
+      ##
+      # @private
+      #
+      # Represents a resource path to the Firestore API.
+      #
+      class ResourcePath
+        include Comparable
+
+        RESOURCE_PATH_RE = %r{^projects/([^/]*)/databases/([^/]*)(?:/documents/)?([\s\S]*)$}.freeze
+
+        attr_reader :project_id
+        attr_reader :database_id
+        attr_reader :segments
+
+        ##
+        # Creates a resource path object.
+        #
+        # @param [Array<String>] segments One or more strings representing the resource path.
+        #
+        # @return [ResourcePath] The resource path object.
+        #
+        def initialize project_id, database_id, segments
+          @project_id = project_id
+          @database_id = database_id
+          @segments = segments.split "/"
+        end
+
+        def <=> other
+          return nil unless other.is_a? ResourcePath
+          [project_id, database_id, segments] <=> [other.project_id, other.database_id, other.segments]
+        end
+
+        def self.from_path path
+          data = RESOURCE_PATH_RE.match path
+          new data[1], data[2], data[3]
+        end
+      end
+    end
+  end
+end