couchbase 3.0.0.alpha.4-x86_64-linux → 3.5.0-x86_64-linux

data/lib/couchbase/collection_options.rb

@@ -1,4 +1,4 @@
-#    Copyright 2020 Couchbase, Inc.
+#  Copyright 2020-2021 Couchbase, Inc.
 #
 #  Licensed under the Apache License, Version 2.0 (the "License");
 #  you may not use this file except in compliance with the License.
@@ -12,85 +12,39 @@
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
 
+require "rubygems/deprecate"
+
 require "couchbase/json_transcoder"
-require "couchbase/common_options"
+require "couchbase/raw_string_transcoder"
+require "couchbase/raw_json_transcoder"
+require "couchbase/raw_binary_transcoder"
 require "couchbase/subdoc"
 require "couchbase/mutation_state"
 
 module Couchbase
   class Collection
-    class GetOptions < CommonOptions
-      # @return [Boolean] if the expiration should also fetched with get
-      attr_accessor :with_expiration
-
-      # @return [JsonTranscoder] transcoder used for decoding
-      attr_accessor :transcoder
-
-      # @yieldparam [GetOptions] self
-      def initialize
-        @transcoder = JsonTranscoder.new
-        @preserve_array_indexes = false
-        @with_expiration = nil
-        @projections = nil
-        yield self if block_given?
-      end
-
-      # Allows to specify a custom list paths to fetch from the document instead of the whole.
-      #
-      # Note that a maximum of 16 individual paths can be projected at a time due to a server limitation. If you need
-      # more than that, think about fetching less-generic paths or the full document straight away.
-      #
-      # @param [String, Array<String>] paths a path that should be loaded if present.
-      def project(*paths)
-        @projections ||= []
-        @projections |= paths.flatten # union with current projections
-      end
-
-      # @api private
-      # @return [Boolean] whether to use sparse arrays (default false)
-      attr_accessor :preserve_array_indexes
-
-      # @api private
-      # @return [Array<String>] list of paths to project
-      attr_accessor :projections
+    class GetResult
+      extend Gem::Deprecate
 
-      # @api private
-      # @return [Boolean]
-      def need_projected_get?
-        @with_expiration || !@projections.nil?
-      end
-    end
+      # @return [Integer] holds the CAS value of the fetched document
+      attr_accessor :cas
 
-    class GetAndLockOptions < CommonOptions
-      # @return [JsonTranscoder] transcoder used for decoding
-      attr_accessor :transcoder
+      # @return [Integer] the expiration if fetched and present
+      attr_writer :expiry
 
-      # @yieldparam [GetAndLockOptions] self
-      def initialize
-        @transcoder = JsonTranscoder.new
-        yield self if block_given?
-      end
-    end
+      # @return [Error::CouchbaseError, nil] error associated with the result, or nil (used in {Collection#get_multi})
+      attr_accessor :error
 
-    class GetAndTouchOptions < CommonOptions
-      # @return [JsonTranscoder] transcoder used for decoding
-      attr_accessor :transcoder
+      # @return [String, nil] identifier of the document (used for {Collection#get_multi})
+      attr_accessor :id
 
-      # @yieldparam [GetAndTouchOptions] self
-      def initialize
-        @transcoder = JsonTranscoder.new
-        yield self if block_given?
+      # @return [Boolean] true if error was not associated with the result (useful for multi-operations)
+      def success?
+        !error
       end
-    end
-
-    class GetResult
-      # @return [Integer] holds the CAS value of the fetched document
-      attr_accessor :cas
-
-      # @return [Integer] the expiration if fetched and present
-      attr_accessor :expiration
 
       # @return [String] The encoded content when loading the document
+      # @api private
       attr_accessor :encoded
 
       # Decodes the content of the document using given (or default transcoder)
@@ -99,146 +53,79 @@ module Couchbase
       #
       # @return [Object]
       def content(transcoder = self.transcoder)
-        transcoder.decode(@encoded, @flags)
+        transcoder ? transcoder.decode(@encoded, @flags) : @encoded
+      end
+
+      # @return [Time] time when the document will expire
+      def expiry_time
+        Time.at(@expiry) if @expiry
       end
 
       # @yieldparam [GetResult] self
       def initialize
+        @expiry = nil
+        @error = nil
+        @id = nil
         yield self if block_given?
       end
 
       # @return [Integer] The flags from the operation
+      # @api private
       attr_accessor :flags
 
       # @return [JsonTranscoder] The default transcoder which should be used
       attr_accessor :transcoder
-    end
 
-    class GetAllReplicasOptions < CommonOptions
-      # @return [JsonTranscoder] transcoder used for decoding
-      attr_accessor :transcoder
-
-      # @yieldparam [GetAllReplicasOptions] self
-      def initialize
-        yield self if block_given?
+      # @deprecated Use {#expiry_time}
+      # @return [Integer] the expiration if fetched and present
+      def expiry # rubocop:disable Style/TrivialAccessors will be removed in next major release
+        @expiry
       end
-    end
 
-    class GetAnyReplicaOptions < CommonOptions
-      # @return [JsonTranscoder] transcoder used for decoding
-      attr_accessor :transcoder
-
-      # @yieldparam [GetAnyReplicaOptions] self
-      def initialize
-        yield self if block_given?
-      end
+      deprecate :expiry, :expiry_time, 2021, 1
     end
 
     class GetReplicaResult < GetResult
       # @return [Boolean] true if this result came from a replica
       attr_accessor :is_replica
-      alias_method :replica?, :is_replica
-    end
-
-    class ExistsOptions < CommonOptions
-      # @yieldparam [ExistsOptions] self
-      def initialize
-        yield self if block_given?
-      end
+      alias replica? is_replica
     end
 
     class ExistsResult
       # @return [Integer] holds the CAS value of the fetched document
       attr_accessor :cas
 
-      # @api private
-      # @return [:found, :not_found, :persisted, :logically_deleted]
-      attr_accessor :status
+      # @return [Boolean] true if the document was deleted
+      attr_accessor :deleted
 
-      def exists?
-        status == :found || status == :persisted
-      end
+      # @return [Boolean] true if the document exists
+      attr_accessor :exists
+      alias exists? exists
 
       # @yieldparam [ExistsResult]
       def initialize
-        @durability_level = :none
         yield self if block_given?
       end
 
-      # @api private
-      # @return [Integer] holds the index of the partition, to which the given key is mapped
-      attr_accessor :partition_id
-    end
-
-    class RemoveOptions < CommonOptions
-      # @return [Integer] Specifies a CAS value that will be taken into account on the server side for optimistic concurrency
-      attr_accessor :cas
-
-      # @return [:none, :majority, :majority_and_persist_to_active, :persist_to_majority] level of durability
-      attr_accessor :durability_level
-
-      # @yieldparam [RemoveOptions]
-      def initialize
-        @durability_level = :none
-        yield self if block_given?
-      end
-    end
-
-    class InsertOptions < CommonOptions
-      # @return [Integer] expiration time to associate with the document
-      attr_accessor :expiration
-
-      # @return [Proc] transcoder used for encoding
-      attr_accessor :transcoder
-
-      # @return [:none, :majority, :majority_and_persist_to_active, :persist_to_majority] level of durability
-      attr_accessor :durability_level
-
-      # @yieldparam [InsertOptions]
-      def initialize
-        @transcoder = JsonTranscoder.new
-        @durability_level = :none
-        yield self if block_given?
-      end
-    end
-
-    class UpsertOptions < CommonOptions
-      # @return [Integer] expiration time to associate with the document
-      attr_accessor :expiration
-
-      # @return [JsonTranscoder] transcoder used for encoding
-      attr_accessor :transcoder
-
-      # @return [:none, :majority, :majority_and_persist_to_active, :persist_to_majority] level of durability
-      attr_accessor :durability_level
+      # @return [Integer] the expiration if fetched and present
+      attr_writer :expiry
 
-      # @yieldparam [UpsertOptions]
-      def initialize
-        @transcoder = JsonTranscoder.new
-        @durability_level = :none
-        yield self if block_given?
+      # @return [Time] time when the document will expire
+      def expiry_time
+        Time.at(@expiry) if @expiry
       end
-    end
-
-    class ReplaceOptions < CommonOptions
-      # @return [Integer] expiration time to associate with the document
-      attr_accessor :expiration
 
-      # @return [JsonTranscoder] transcoder used for encoding
-      attr_accessor :transcoder
-
-      # @return [Integer] Specifies a CAS value that will be taken into account on the server side for optimistic concurrency
-      attr_accessor :cas
+      # @api private
+      # @return [Integer] flags
+      attr_accessor :flags
 
-      # @return [:none, :majority, :majority_and_persist_to_active, :persist_to_majority] level of durability
-      attr_accessor :durability_level
+      # @api private
+      # @return [Integer] sequence_number
+      attr_accessor :sequence_number
 
-      # @yieldparam [ReplaceOptions]
-      def initialize
-        @transcoder = JsonTranscoder.new
-        @durability_level = :none
-        yield self if block_given?
-      end
+      # @api private
+      # @return [Integer] datatype
+      attr_accessor :datatype
     end
 
     class MutationResult
@@ -248,36 +135,23 @@ module Couchbase
       # @return [MutationToken] if returned, holds the mutation token of the document after the mutation
       attr_accessor :mutation_token
 
-      # @yieldparam [MutationResult] self
-      def initialize
-        yield self if block_given?
-      end
-    end
+      # @return [Error::CouchbaseError, nil] error or nil (used in multi-operations like {Collection#upsert_multi},
+      #   {Collection#remove_multi})
+      attr_accessor :error
 
-    class TouchOptions < CommonOptions
-      # @yieldparam [TouchOptions] self
-      def initialize
-        yield self if block_given?
-      end
-    end
+      # @return [String, nil] identifier of the document (used in multi-operations like {Collection#upsert_multi},
+      #   {Collection#remove_multi})
+      attr_accessor :id
 
-    class UnlockOptions < CommonOptions
-      # @yieldparam [UnlockOptions] self
-      def initialize
-        yield self if block_given?
+      # @return [Boolean] true if error was not associated with the result (useful for multi-operations)
+      def success?
+        !error
       end
-    end
-
-    class LookupInOptions < CommonOptions
-      # @return [Boolean] For internal use only: allows access to deleted documents that are in 'tombstone' form
-      attr_accessor :access_deleted
-
-      # @return [JsonTranscoder] transcoder used for decoding
-      attr_accessor :transcoder
 
-      # @yieldparam [LookupInOptions] self
+      # @yieldparam [MutationResult] self
       def initialize
-        @transcoder = JsonTranscoder.new
+        @error = nil
+        @id = nil
         yield self if block_given?
       end
     end
@@ -286,22 +160,39 @@ module Couchbase
       # @return [Integer] holds the CAS value of the fetched document
       attr_accessor :cas
 
-      # Decodes the content at the given index
+      # Decodes the content at the given index (or path)
       #
-      # @param [Integer] index the index of the subdocument value to decode
+      # @param [Integer, String] path_or_index the index (or path) of the subdocument value to decode
       #
       # @return [Object] the decoded
-      def content(index, transcoder = self.transcoder)
-        transcoder.decode(encoded[index].value, :json)
+      def content(path_or_index, transcoder = self.transcoder)
+        field = get_field_at_index(path_or_index)
+
+        raise field.error unless field.error.nil?
+
+        transcoder.decode(field.value, :json)
       end
 
       # Allows to check if a value at the given index exists
       #
-      # @param [Integer] index the index of the subdocument value to check
+      # @param [Integer, String] path_or_index the index (or path) of the subdocument value to check
       #
       # @return [Boolean] true if a value is present at the index, false otherwise
-      def exists?(index)
-        encoded[index].exists
+      def exists?(path_or_index)
+        field =
+          case path_or_index
+          when String
+            encoded.find { |f| f.path == path_or_index }
+          else
+            return false unless path_or_index >= 0 && path_or_index < encoded.size
+
+            encoded[path_or_index]
+          end
+        return false unless field
+
+        raise field.error unless field.error.nil? || field.error.is_a?(Error::PathNotFound)
+
+        field.exists
       end
 
       # @return [Array<SubDocumentField>] holds the encoded subdocument responses
@@ -309,139 +200,200 @@ module Couchbase
 
       # @yieldparam [LookupInResult] self
       def initialize
+        @deleted = false
         yield self if block_given?
       end
 
       # @return [JsonTranscoder] The default transcoder which should be used
       attr_accessor :transcoder
-    end
-
-    class MutateInOptions < CommonOptions
-      # @return [Integer] expiration time to associate with the document
-      attr_accessor :expiration
 
-      # Describes how the outer document store semantics on subdoc should act
+      # @api private
       #
-      # * +:replace+: replace the document, fail if it does not exist. This is the default
-      # * +:upsert+: replace the document or create if it does not exist
-      # * +:insert+: create the document, fail if it exists
+      # @see MutateInOptions#create_as_deleted
       #
-      # @return [:replace, :upsert, :insert]
-      attr_accessor :store_semantics
+      # @return [Boolean] true if the document is a tombstone (created in deleted state)
+      def deleted?
+        @deleted
+      end
 
-      # @return [Integer] Specifies a CAS value that will be taken into account on the server side for optimistic concurrency
-      attr_accessor :cas
+      # @api private
+      attr_accessor :deleted
+
+      private
 
-      # @return [Boolean] For internal use only: allows access to deleted documents that are in 'tombstone' form
-      attr_accessor :access_deleted
+      def get_field_at_index(path_or_index)
+        case path_or_index
+        when String
+          encoded.find { |field| field.path == path_or_index } or raise Error::PathInvalid, "Path is not found: #{path_or_index}"
+        else
+          raise Error::PathInvalid, "Index is out of bounds: #{path_or_index}" unless path_or_index >= 0 && path_or_index < encoded.size
 
-      # @return [Boolean] For internal use only: allows creating documents in 'tombstone' form
-      attr_accessor :create_as_deleted
+          encoded[path_or_index]
+        end
+      end
+    end
 
-      # @return [:none, :majority, :majority_and_persist_to_active, :persist_to_majority] level of durability
-      attr_accessor :durability_level
+    class LookupInReplicaResult < LookupInResult
+      # @return [Boolean] true if the document was read from a replica node
+      attr_accessor :is_replica
+      alias replica? is_replica
 
-      # @yieldparam [MutateInOptions]
+      # @yieldparam [LookupInReplicaResult] self
       def initialize
-        @durability_level = :none
-        @store_semantics = :replace
-        @transcoder = JsonTranscoder.new
+        super
         yield self if block_given?
       end
-
-      attr_accessor :transcoder
     end
 
     class MutateInResult < MutationResult
       # Decodes the content at the given index
       #
-      # @param [Integer] index the index of the subdocument value to decode
+      # @param [Integer, String] path_or_index the index (or path) of the subdocument value to decode
       #
       # @return [Object] the decoded
-      def content(index, transcoder = self.transcoder)
-        transcoder.decode(encoded[index].value, :json)
+      def content(path_or_index, transcoder = self.transcoder)
+        field = get_field_at_index(path_or_index)
+        transcoder.decode(field.value, :json)
       end
 
       # @yieldparam [MutateInResult] self
       def initialize
+        super
         yield self if block_given?
       end
 
-      def success?
-        !!first_error_index
-      end
-
       # @return [Array<SubDocumentField>] holds the encoded subdocument responses
+      # @api private
       attr_accessor :encoded
 
-      # @return [Integer, nil] index of first operation entry that generated an error
-      attr_accessor :first_error_index
-
       # @return [JsonTranscoder] The default transcoder which should be used
       attr_accessor :transcoder
+
+      # @api private
+      #
+      # @see MutateInOptions#create_as_deleted
+      #
+      # @return [Boolean] true if the document is a tombstone (created in deleted state)
+      def deleted?
+        @deleted
+      end
+
+      # @api private
+      attr_accessor :deleted
+
+      private
+
+      def get_field_at_index(path_or_index)
+        case path_or_index
+        when String
+          encoded.find { |field| field.path == path_or_index } or raise Error::PathInvalid, "Path is not found: #{path_or_index}"
+        else
+          raise Error::PathInvalid, "Index is out of bounds: #{path_or_index}" unless path_or_index >= 0 && path_or_index < encoded.size
+
+          encoded[path_or_index]
+        end
+      end
     end
 
-# @api private
+    # @api private
     class SubDocumentField
-      attr_accessor :error
-
       # @return [Boolean] true if the path exists in the document
       attr_accessor :exists
 
       # @return [String] value
       attr_accessor :value
 
+      # @return [Integer] index
+      attr_accessor :index
+
       # @return [String] path
       attr_accessor :path
 
-      # Operation type
-      #
-      # * +:set_doc+
-      # * +:counter+
-      # * +:replace+
-      # * +:dict_add+
-      # * +:dict_upsert+
-      # * +:array_push_first+
-      # * +:array_push_last+
-      # * +:array_add_unique+
-      # * +:array_insert+
-      # * +:delete+
-      # * +:get+
-      # * +:exists+
-      # * +:count+
-      # * +:get_doc+
-      #
-      # @return [Symbol]
-      attr_accessor :type
-
-      # Status of the subdocument path operation.
-      #
-      # [+:success+] Indicates a successful response in general.
-      # [+:path_not_found+] The provided path does not exist in the document
-      # [+:path_mismatch+] One of path components treats a non-dictionary as a dictionary, or a non-array as an array, or value the path points to is not a number
-      # [+:path_invalid+] The path's syntax was incorrect
-      # [+:path_too_big+] The path provided is too large: either the string is too long, or it contains too many components
-      # [+:value_cannot_insert+] The value provided will invalidate the JSON if inserted
-      # [+:doc_not_json+] The existing document is not valid JSON
-      # [+:num_range+] The existing number is out of the valid range for arithmetic operations
-      # [+:delta_invalid+] The operation would result in a number outside the valid range
-      # [+:path_exists+] The requested operation requires the path to not already exist, but it exists
-      # [+:value_too_deep+] Inserting the value would cause the document to be too deep
-      # [+:invalid_combo+] An invalid combination of commands was specified
-      # [+:xattr_invalid_flag_combo+] An invalid combination of operations, using macros when not using extended attributes
-      # [+:xattr_invalid_key_combo+] Only single xattr key may be accessed at the same time
-      # [+:xattr_unknown_macro+] The server has no knowledge of the requested macro
-      # [+:xattr_unknown_vattr+] Unknown virtual attribute.
-      # [+:xattr_cannot_modify_vattr+] Cannot modify this virtual attribute.
-      # [+:unknown+] Unknown error.
-      #
-      # @return [Symbol]
-      attr_accessor :status
+      # @return [CouchbaseError] error
+      attr_accessor :error
 
       # @yieldparam [SubDocumentField] self
       def initialize
         yield self if block_given?
       end
     end
+
+    class ScanResult
+      # @return [String] identifier of the document
+      attr_accessor :id
+
+      # @return [Boolean] whether only ids are returned from this scan
+      attr_accessor :id_only
+
+      # @return [Integer, nil] holds the CAS value of the fetched document
+      attr_accessor :cas
+
+      # @return [Integer, nil] the expiration if fetched and present
+      attr_accessor :expiry
+
+      # @return [JsonTranscoder, RawBinaryTranscoder, RawJsonTranscoder, RawStringTranscoder, #decode] The default
+      #   transcoder which should be used
+      attr_accessor :transcoder
+
+      def initialize(id:, id_only:, cas: nil, expiry: nil, encoded: nil, flags: nil, transcoder: JsonTranscoder.new)
+        @id = id
+        @id_only = id_only
+        @cas = cas
+        @expiry = expiry
+        @encoded = encoded
+        @flags = flags
+        @transcoder = transcoder
+
+        yield self if block_given?
+      end
+
+      # Decodes the content of the document using given (or default transcoder)
+      #
+      # @param [JsonTranscoder, RawJsonTranscoder, RawBinaryTranscoder, RawStringTranscoder] transcoder custom transcoder
+      #
+      # @return [Object, nil]
+      def content(transcoder = self.transcoder)
+        return nil if @encoded.nil?
+
+        transcoder ? transcoder.decode(@encoded, @flags) : @encoded
+      end
+    end
+
+    class ScanResults
+      include Enumerable
+
+      def initialize(core_scan_result:, transcoder:)
+        @core_scan_result = core_scan_result
+        @transcoder = transcoder
+      end
+
+      def each
+        return enum_for(:each) unless block_given?
+
+        loop do
+          resp = @core_scan_result.next_item
+
+          break if resp.nil?
+
+          if resp[:id_only]
+            yield ScanResult.new(
+              id: resp[:id],
+              id_only: resp[:id_only],
+              transcoder: @transcoder
+            )
+          else
+            yield ScanResult.new(
+              id: resp[:id],
+              id_only: resp[:id_only],
+              cas: resp[:cas],
+              expiry: resp[:expiry],
+              encoded: resp[:encoded],
+              flags: resp[:flags],
+              transcoder: @transcoder
+            )
+          end
+        end
+      end
+    end
   end
 end