feat: add Collection.mutateIn (#29)

Author: blaugold

init-couchbase-server.sh

@@ -9,7 +9,7 @@ docker compose up -d
 
 MAX_ATTEMPTS=60
 ATTEMPTS=0
-until curl http://localhost:8091/pools/default >/dev/null 2>1; do
+until curl http://localhost:8091/pools/default >/dev/null 2>&1; do
   if [ $ATTEMPTS -eq $MAX_ATTEMPTS ]; then
     echo "Couchbase Sever is unavailable after $MAX_ATTEMPTS attempts - exiting"
     exit 1

packages/couchbase/lib/couchbase.dart

@@ -10,6 +10,7 @@ export 'src/collection.dart'
         GetOptions,
         InsertOptions,
         LookupInOptions,
+        MutateInOptions,
         RemoveOptions,
         ReplaceOptions,
         UpsertOptions;
@@ -19,6 +20,8 @@ export 'src/crud_operation.dart'
         GetResult,
         LookupInResult,
         LookupInResultEntry,
+        MutateInResult,
+        MutateInResultEntry,
         MutationResult;
 export 'src/diagnostics.dart'
     show
@@ -131,7 +134,12 @@ export 'src/general.dart'
         ServiceType,
         TranscoderOptions;
 export 'src/message.g.dart'
-    show DurabilityLevel, KeyValueStatusCode, PersistTo, ReplicateTo;
+    show
+        DurabilityLevel,
+        KeyValueStatusCode,
+        PersistTo,
+        ReplicateTo,
+        StoreSemantics;
 export 'src/mutation_state.dart' show MutationState, MutationToken;
 export 'src/query.dart'
     show
@@ -144,6 +152,7 @@ export 'src/query.dart'
         QueryStatus,
         QueryWarning;
 export 'src/scope.dart' show Scope;
-export 'src/sub_document_spec.dart' show LookupInMacro, LookupInSpec;
+export 'src/sub_document_spec.dart'
+    show LookupInMacro, LookupInSpec, MutateInMacro, MutateInSpec;
 export 'src/transcoder.dart'
     show DefaultTranscoder, EncodedDocumentData, Transcoder;

packages/couchbase/lib/src/collection.dart

@@ -180,6 +180,43 @@ class LookupInOptions extends CommonOptions {
   const LookupInOptions({super.timeout});
 }
 
+/// Options for [Collection.mutateIn].
+///
+/// {@category Key-Value}
+class MutateInOptions extends CommonDurabilityOptions {
+  const MutateInOptions({
+    this.expiry,
+    this.preserveExpiry = false,
+    this.cas,
+    this.storeSemantics = StoreSemantics.replace,
+    super.durabilityLevel,
+    super.timeout,
+  });
+
+  const MutateInOptions.legacyDurability({
+    this.expiry,
+    this.preserveExpiry = false,
+    this.cas,
+    this.storeSemantics = StoreSemantics.replace,
+    super.persistTo,
+    super.replicateTo,
+    super.timeout,
+  }) : super.legacyDurability();
+
+  /// The expiry time for this document.
+  final Duration? expiry;
+
+  /// Whether any existing expiry on the document should be preserved.
+  final bool preserveExpiry;
+
+  /// If specified, indicates that operation should be failed if the [Cas]
+  /// has changed from this value, indicating that the document has changed.
+  final Cas? cas;
+
+  /// The store semantics to use for this operation.
+  final StoreSemantics storeSemantics;
+}
+
 /// Exposes the operations which are available to be performed against a
 /// collection.
 ///
@@ -514,6 +551,87 @@ class Collection {
     );
   }
 
+  /// Performs a Mutate-In operation against a document.
+  ///
+  /// Allows atomic modification of specific fields within a document. Also
+  /// enables access to document extended-attributes.
+  ///
+  /// [key] is the key of the document to mutate.
+  ///
+  /// [specs] is a list of [MutateInSpec]s describing the operations to perform
+  Future<MutateInResult> mutateIn(
+    String key,
+    List<MutateInSpec> specs, [
+    MutateInOptions? options,
+  ]) async {
+    options ??= const MutateInOptions();
+
+    if (specs.isEmpty) {
+      throw ArgumentError.value(
+        specs,
+        'specs',
+        'must not be empty',
+      );
+    }
+
+    final id = _documentId(key);
+    final expiry = options.expiry ?? Duration.zero;
+    final cas = options.cas ?? InternalCas.zero;
+    final timeout = _mutationTimeout(options);
+    final implSpecs = List.generate(
+      specs.length,
+      (index) => specs[index].toMessage(index),
+    );
+
+    final response = options.usesLegacyDurability
+        ? await _connection.mutateInWithLegacyDurability(
+            MutateInWithLegacyDurability(
+              id: id,
+              cas: cas,
+              specs: implSpecs,
+              storeSemantics: options.storeSemantics,
+              timeout: timeout,
+              expiry: expiry.inSeconds,
+              preserveExpiry: options.preserveExpiry,
+              persistTo: options.durabilityPersistTo,
+              replicateTo: options.durabilityReplicateTo,
+              partition: 0,
+              opaque: 0,
+              accessDeleted: false,
+              createAsDeleted: false,
+            ),
+          )
+        : await _connection.mutateIn(
+            MutateInRequest(
+              id: id,
+              cas: cas,
+              specs: implSpecs,
+              storeSemantics: options.storeSemantics,
+              timeout: timeout,
+              expiry: expiry.inSeconds,
+              preserveExpiry: options.preserveExpiry,
+              durabilityLevel: options.durabilityLevel,
+              partition: 0,
+              opaque: 0,
+              accessDeleted: false,
+              createAsDeleted: false,
+            ),
+          );
+
+    final results = response.fields.map((entry) {
+      return MutateInResultEntry(
+        value:
+            entry.value.isEmpty ? null : _decodeSubDocumentValue(entry.value),
+      );
+    }).toList();
+
+    return MutateInResult(
+      content: results,
+      cas: response.cas,
+      token: response.token,
+    );
+  }
+
   DocumentId _documentId(String key) {
     return DocumentId(
       bucket: _scope.bucket.name,
@@ -618,7 +736,7 @@ class Collection {
           .decode(EncodedDocumentData(flags: flags, bytes: bytes));
       for (final projectionPath in paths) {
         final value = SubDocumentUtils.getByPath(fullDocument, projectionPath);
-        if (value != SubDocumentUtils.notFoundSentinel) {
+        if (!identical(value, SubDocumentUtils.notFoundSentinel)) {
           content =
               SubDocumentUtils.insertByPath(content, projectionPath, value);
         }

packages/couchbase/lib/src/crud_operation.dart

@@ -56,7 +56,7 @@ class MutationResult {
   final MutationToken? token;
 }
 
-/// The results of a specific sub-operation within a Lookup-In operation.
+/// The result of a specific sub-operation within a Lookup-In operation.
 ///
 /// {@category Key-Value}
 class LookupInResultEntry {
@@ -82,9 +82,44 @@ class LookupInResult {
     required this.cas,
   });
 
-  /// A list of result entries for each sub-operation performed.
+  /// The list of result entries for each sub-operation performed.
   final List<LookupInResultEntry> content;
 
   /// The cas of the document.
   final Cas cas;
 }
+
+/// The result of a specific sub-operation within a Mutate-In operation.
+///
+/// {@category Key-Value}
+class MutateInResultEntry {
+  const MutateInResultEntry({
+    this.value,
+  });
+
+  /// The resulting value after the completion of the sub-operation.
+  ///
+  /// This is only returned in the case of a counter operation
+  /// (increment/decrement) and is not  included for general operations.
+  final Object? value;
+}
+
+/// Contains the results of a Mutate-In operation.
+///
+/// {@category Key-Value}
+class MutateInResult {
+  const MutateInResult({
+    required this.content,
+    required this.cas,
+    this.token,
+  });
+
+  /// The list of result entries for each sub-operation performed.
+  final List<MutateInResultEntry> content;
+
+  /// The updated [Cas] for the document.
+  final Cas cas;
+
+  /// The token representing the mutation performed.
+  final MutationToken? token;
+}

packages/couchbase/lib/src/exception.dart

@@ -1489,6 +1489,8 @@ message_errors.ErrorCode _resolveErrorCode(Object error) {
     return error;
   } else if (error is message_errors.KeyValueErrorContext) {
     return error.code;
+  } else if (error is message_errors.SubdocumentErrorContext) {
+    return error.code;
   } else if (error is message_errors.ViewErrorContext) {
     return error.code;
   } else if (error is message_errors.QueryErrorContext) {