couchbase 3.0.0.alpha.2 → 3.0.0

data/lib/couchbase/collection.rb

@@ -22,7 +22,7 @@ module Couchbase
     attr_reader :scope_name
     attr_reader :name
 
-    alias_method :inspect, :to_s
+    alias inspect to_s
 
     # @param [Couchbase::Backend] backend
     # @param [String] bucket_name name of the bucket
@@ -49,12 +49,21 @@ module Couchbase
     #
     # @return [GetResult]
     def get(id, options = GetOptions.new)
-      resp = @backend.document_get(bucket_name, "#{@scope_name}.#{@name}", id)
+      resp = if options.need_projected_get?
+               @backend.document_get_projected(bucket_name, "#{@scope_name}.#{@name}", id,
+                                               options.timeout,
+                                               options.with_expiry,
+                                               options.projections,
+                                               options.preserve_array_indexes)
+             else
+               @backend.document_get(bucket_name, "#{@scope_name}.#{@name}", id, options.timeout)
+             end
       GetResult.new do |res|
         res.transcoder = options.transcoder
         res.cas = resp[:cas]
         res.flags = resp[:flags]
         res.encoded = resp[:content]
+        res.expiry = resp[:expiry] if resp.key?(:expiry)
       end
     end
 
@@ -66,7 +75,7 @@ module Couchbase
     #
     # @return [GetResult]
     def get_and_lock(id, lock_time, options = GetAndLockOptions.new)
-      resp = @backend.document_get_and_lock(bucket_name, "#{@scope_name}.#{@name}", id, lock_time)
+      resp = @backend.document_get_and_lock(bucket_name, "#{@scope_name}.#{@name}", id, options.timeout, lock_time)
       GetResult.new do |res|
         res.transcoder = options.transcoder
         res.cas = resp[:cas]
@@ -75,15 +84,15 @@ module Couchbase
       end
     end
 
-    # Fetches a full document and resets its expiration time to the expiration duration provided
+    # Fetches a full document and resets its expiration time to the duration provided
     #
     # @param [String] id the document id which is used to uniquely identify it.
-    # @param [Integer] expiration the new expiration time for the document
+    # @param [Integer] expiry the new expiration time for the document
     # @param [GetAndTouchOptions] options request customization
     #
     # @return [GetResult]
-    def get_and_touch(id, expiration, options = GetAndTouchOptions.new)
-      resp = @backend.document_get_and_touch(bucket_name, "#{@scope_name}.#{@name}", id, expiration)
+    def get_and_touch(id, expiry, options = GetAndTouchOptions.new)
+      resp = @backend.document_get_and_touch(bucket_name, "#{@scope_name}.#{@name}", id, options.timeout, expiry)
       GetResult.new do |res|
         res.transcoder = options.transcoder
         res.cas = resp[:cas]
@@ -115,7 +124,7 @@ module Couchbase
     #
     # @return [ExistsResult]
     def exists(id, options = ExistsOptions.new)
-      resp = @backend.document_exists(bucket_name, "#{@scope_name}.#{@name}", id)
+      resp = @backend.document_exists(bucket_name, "#{@scope_name}.#{@name}", id, options.timeout)
       ExistsResult.new do |res|
         res.status = resp[:status]
         res.partition_id = resp[:partition_id]
@@ -130,8 +139,8 @@ module Couchbase
     #
     # @return [MutationResult]
     def remove(id, options = RemoveOptions.new)
-      resp = @backend.document_remove(bucket_name, "#{@scope_name}.#{@name}", id, {
-          durability_level: options.durability_level
+      resp = @backend.document_remove(bucket_name, "#{@scope_name}.#{@name}", id, options.timeout, {
+        durability_level: options.durability_level,
       })
       MutationResult.new do |res|
         res.cas = resp[:cas]
@@ -148,9 +157,9 @@ module Couchbase
     # @return [MutationResult]
     def insert(id, content, options = InsertOptions.new)
       blob, flags = options.transcoder.encode(content)
-      resp = @backend.document_insert(bucket_name, "#{@scope_name}.#{@name}", id, blob, flags, {
-          durability_level: options.durability_level,
-          expiration: options.expiration,
+      resp = @backend.document_insert(bucket_name, "#{@scope_name}.#{@name}", id, options.timeout, blob, flags, {
+        durability_level: options.durability_level,
+        expiry: options.expiry,
       })
       MutationResult.new do |res|
         res.cas = resp[:cas]
@@ -167,9 +176,9 @@ module Couchbase
     # @return [MutationResult]
     def upsert(id, content, options = UpsertOptions.new)
       blob, flags = options.transcoder.encode(content)
-      resp = @backend.document_upsert(bucket_name, "#{@scope_name}.#{@name}", id, blob, flags, {
-          durability_level: options.durability_level,
-          expiration: options.expiration,
+      resp = @backend.document_upsert(bucket_name, "#{@scope_name}.#{@name}", id, options.timeout, blob, flags, {
+        durability_level: options.durability_level,
+        expiry: options.expiry,
       })
       MutationResult.new do |res|
         res.cas = resp[:cas]
@@ -186,10 +195,10 @@ module Couchbase
     # @return [MutationResult]
     def replace(id, content, options = ReplaceOptions.new)
       blob, flags = options.transcoder.encode(content)
-      resp = @backend.document_replace(bucket_name, "#{@scope_name}.#{@name}", id, blob, flags, {
-          durability_level: options.durability_level,
-          expiration: options.expiration,
-          cas: options.cas,
+      resp = @backend.document_replace(bucket_name, "#{@scope_name}.#{@name}", id, options.timeout, blob, flags, {
+        durability_level: options.durability_level,
+        expiry: options.expiry,
+        cas: options.cas,
       })
       MutationResult.new do |res|
         res.cas = resp[:cas]
@@ -200,12 +209,12 @@ module Couchbase
     # Update the expiration of the document with the given id
     #
     # @param [String] id the document id which is used to uniquely identify it.
-    # @param [Integer] expiration new expiration time for the document
+    # @param [Integer] expiry new expiration time for the document
     # @param [TouchOptions] options request customization
     #
     # @return [MutationResult]
-    def touch(id, expiration, options = TouchOptions.new)
-      resp = @backend.document_touch(bucket_name, "#{@scope_name}.#{@name}", id, expiration)
+    def touch(id, expiry, options = TouchOptions.new)
+      resp = @backend.document_touch(bucket_name, "#{@scope_name}.#{@name}", id, options.timeout, expiry)
       MutationResult.new do |res|
         res.cas = resp[:cas]
       end
@@ -219,7 +228,7 @@ module Couchbase
     #
     # @raise [Error::DocumentNotFound]
     def unlock(id, cas, options = UnlockOptions.new)
-      @backend.document_unlock(bucket_name, "#{@scope_name}.#{@name}", id, cas)
+      @backend.document_unlock(bucket_name, "#{@scope_name}.#{@name}", id, options.timeout, cas)
     end
 
     # Performs lookups to document fragments
@@ -231,8 +240,14 @@ module Couchbase
     # @return [LookupInResult]
     def lookup_in(id, specs, options = LookupInOptions.new)
       resp = @backend.document_lookup_in(
-          bucket_name, "#{@scope_name}.#{@name}", id, options.access_deleted,
-          specs.map { |s| {opcode: s.type, xattr: s.xattr?, path: s.path} }
+        bucket_name, "#{@scope_name}.#{@name}", id, options.timeout, options.access_deleted,
+        specs.map do |s|
+          {
+            opcode: s.type,
+            xattr: s.xattr?,
+            path: s.path,
+          }
+        end
       )
       LookupInResult.new do |res|
         res.transcoder = options.transcoder
@@ -240,10 +255,12 @@ module Couchbase
         res.encoded = resp[:fields].map do |field|
           SubDocumentField.new do |f|
             f.exists = field[:exists]
+            f.index = field[:index]
             f.path = field[:path]
             f.status = field[:status]
+            f.error = field[:error]
             f.value = field[:value]
-            f.type = field[:opcode]
+            f.type = field[:type]
           end
         end
       end
@@ -258,13 +275,26 @@ module Couchbase
     # @return [MutateInResult]
     def mutate_in(id, specs, options = MutateInOptions.new)
       resp = @backend.document_mutate_in(
-          bucket_name, "#{@scope_name}.#{@name}", id, options.access_deleted,
-          specs.map { |s| {opcode: s.type, path: s.path, param: s.param,
-                           xattr: s.xattr?, expand_macros: s.expand_macros?, create_parents: s.create_parents?} }, {
-              durability_level: options.durability_level
+        bucket_name, "#{@scope_name}.#{@name}", id, options.timeout,
+        specs.map do |s|
+          {
+            opcode: s.type,
+            path: s.path,
+            param: s.param,
+            xattr: s.xattr?,
+            expand_macros: s.expand_macros?,
+            create_path: s.create_path?,
           }
+        end,
+        {
+          durability_level: options.durability_level,
+          store_semantics: options.store_semantics,
+          access_deleted: options.access_deleted,
+          cas: options.cas,
+          expiry: options.expiry,
+        }
       )
-      MutateInResult.new do |res|
+      result = MutateInResult.new do |res|
         res.transcoder = options.transcoder
         res.cas = resp[:cas]
         res.mutation_token = extract_mutation_token(resp)
@@ -274,11 +304,15 @@ module Couchbase
             f.exists = field[:exists]
             f.path = field[:path]
             f.status = field[:status]
+            f.error = field[:error]
             f.value = field[:value]
-            f.type = field[:opcode]
+            f.type = field[:type]
           end
         end
       end
+      raise result.first_error unless result.success?
+
+      result
     end
 
     private

data/lib/couchbase/collection_options.rb

@@ -28,7 +28,11 @@ module Couchbase
 
       # @yieldparam [GetOptions] self
       def initialize
+        super
         @transcoder = JsonTranscoder.new
+        @preserve_array_indexes = false
+        @with_expiry = nil
+        @projections = nil
         yield self if block_given?
       end
 
@@ -40,7 +44,21 @@ module Couchbase
       # @param [String, Array<String>] paths a path that should be loaded if present.
       def project(*paths)
         @projections ||= []
-        @projections |= paths # union with current 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
+
+      # @api private
+      # @return [Boolean]
+      def need_projected_get?
+        @with_expiry || !@projections.nil?
       end
     end
 
@@ -50,6 +68,7 @@ module Couchbase
 
       # @yieldparam [GetAndLockOptions] self
       def initialize
+        super
         @transcoder = JsonTranscoder.new
         yield self if block_given?
       end
@@ -61,6 +80,7 @@ module Couchbase
 
       # @yieldparam [GetAndTouchOptions] self
       def initialize
+        super
         @transcoder = JsonTranscoder.new
         yield self if block_given?
       end
@@ -71,9 +91,10 @@ module Couchbase
       attr_accessor :cas
 
       # @return [Integer] the expiration if fetched and present
-      attr_accessor :expiration
+      attr_accessor :expiry
 
       # @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)
@@ -91,6 +112,7 @@ module Couchbase
       end
 
       # @return [Integer] The flags from the operation
+      # @api private
       attr_accessor :flags
 
       # @return [JsonTranscoder] The default transcoder which should be used
@@ -103,6 +125,7 @@ module Couchbase
 
       # @yieldparam [GetAllReplicasOptions] self
       def initialize
+        super
         yield self if block_given?
       end
     end
@@ -113,6 +136,7 @@ module Couchbase
 
       # @yieldparam [GetAnyReplicaOptions] self
       def initialize
+        super
         yield self if block_given?
       end
     end
@@ -120,12 +144,13 @@ module Couchbase
     class GetReplicaResult < GetResult
       # @return [Boolean] true if this result came from a replica
       attr_accessor :is_replica
-      alias_method :replica?, :is_replica
+      alias replica? is_replica
     end
 
     class ExistsOptions < CommonOptions
       # @yieldparam [ExistsOptions] self
       def initialize
+        super
         yield self if block_given?
       end
     end
@@ -162,6 +187,7 @@ module Couchbase
 
       # @yieldparam [RemoveOptions]
       def initialize
+        super
         @durability_level = :none
         yield self if block_given?
       end
@@ -169,7 +195,7 @@ module Couchbase
 
     class InsertOptions < CommonOptions
       # @return [Integer] expiration time to associate with the document
-      attr_accessor :expiration
+      attr_accessor :expiry
 
       # @return [Proc] transcoder used for encoding
       attr_accessor :transcoder
@@ -179,6 +205,7 @@ module Couchbase
 
       # @yieldparam [InsertOptions]
       def initialize
+        super
         @transcoder = JsonTranscoder.new
         @durability_level = :none
         yield self if block_given?
@@ -187,7 +214,7 @@ module Couchbase
 
     class UpsertOptions < CommonOptions
       # @return [Integer] expiration time to associate with the document
-      attr_accessor :expiration
+      attr_accessor :expiry
 
       # @return [JsonTranscoder] transcoder used for encoding
       attr_accessor :transcoder
@@ -197,6 +224,7 @@ module Couchbase
 
       # @yieldparam [UpsertOptions]
       def initialize
+        super
         @transcoder = JsonTranscoder.new
         @durability_level = :none
         yield self if block_given?
@@ -205,7 +233,7 @@ module Couchbase
 
     class ReplaceOptions < CommonOptions
       # @return [Integer] expiration time to associate with the document
-      attr_accessor :expiration
+      attr_accessor :expiry
 
       # @return [JsonTranscoder] transcoder used for encoding
       attr_accessor :transcoder
@@ -218,6 +246,7 @@ module Couchbase
 
       # @yieldparam [ReplaceOptions]
       def initialize
+        super
         @transcoder = JsonTranscoder.new
         @durability_level = :none
         yield self if block_given?
@@ -240,6 +269,7 @@ module Couchbase
     class TouchOptions < CommonOptions
       # @yieldparam [TouchOptions] self
       def initialize
+        super
         yield self if block_given?
       end
     end
@@ -247,6 +277,7 @@ module Couchbase
     class UnlockOptions < CommonOptions
       # @yieldparam [UnlockOptions] self
       def initialize
+        super
         yield self if block_given?
       end
     end
@@ -260,6 +291,7 @@ module Couchbase
 
       # @yieldparam [LookupInOptions] self
       def initialize
+        super
         @transcoder = JsonTranscoder.new
         yield self if block_given?
       end
@@ -275,7 +307,7 @@ module Couchbase
       #
       # @return [Object] the decoded
       def content(index, transcoder = self.transcoder)
-        transcoder.decode(encoded[index].value, :json)
+        transcoder.decode(get_field_at_index(index).value, :json)
       end
 
       # Allows to check if a value at the given index exists
@@ -284,7 +316,7 @@ module Couchbase
       #
       # @return [Boolean] true if a value is present at the index, false otherwise
       def exists?(index)
-        encoded[index].exists
+        !encoded[index].nil? && encoded[index].exists
       end
 
       # @return [Array<SubDocumentField>] holds the encoded subdocument responses
@@ -297,11 +329,22 @@ module Couchbase
 
       # @return [JsonTranscoder] The default transcoder which should be used
       attr_accessor :transcoder
+
+      private
+
+      def get_field_at_index(index)
+        raise Error::PathInvalid, "Index is out of bounds: #{index}" unless index >= 0 && index < encoded.size
+
+        field = encoded[index]
+        raise field.error unless field.success?
+
+        field
+      end
     end
 
     class MutateInOptions < CommonOptions
       # @return [Integer] expiration time to associate with the document
-      attr_accessor :expiration
+      attr_accessor :expiry
 
       # Describes how the outer document store semantics on subdoc should act
       #
@@ -326,6 +369,7 @@ module Couchbase
 
       # @yieldparam [MutateInOptions]
       def initialize
+        super
         @durability_level = :none
         @store_semantics = :replace
         @transcoder = JsonTranscoder.new
@@ -342,38 +386,64 @@ module Couchbase
       #
       # @return [Object] the decoded
       def content(index, transcoder = self.transcoder)
-        transcoder.decode(encoded[index].value, :json)
+        field = get_field_at_index(index)
+        if field.type == :counter
+          field.value
+        else
+          transcoder.decode(field.value, :json)
+        end
       end
 
       # @yieldparam [MutateInResult] self
       def initialize
+        super
         yield self if block_given?
       end
 
+      # @api private
       def success?
-        !!first_error_index
+        first_error_index.nil?
+      end
+
+      # @api private
+      def first_error
+        encoded[first_error_index].error unless success?
       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
+      # @api private
       attr_accessor :first_error_index
 
       # @return [JsonTranscoder] The default transcoder which should be used
       attr_accessor :transcoder
+
+      private
+
+      def get_field_at_index(index)
+        raise Error::PathInvalid, "Index is out of bounds: #{index}" unless index >= 0 && index < encoded.size
+
+        field = encoded[index]
+        raise field.error unless field.success?
+
+        field
+      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
 
@@ -401,7 +471,8 @@ module Couchbase
       #
       # [+: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_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
@@ -421,10 +492,19 @@ module Couchbase
       # @return [Symbol]
       attr_accessor :status
 
+      # @return [nil, Exception]
+      attr_accessor :error
+
       # @yieldparam [SubDocumentField] self
       def initialize
+        @status = :unknown
         yield self if block_given?
       end
+
+      # @return [Boolean] true if the path does not have associated error
+      def success?
+        status == :success
+      end
     end
   end
 end