update method

Future<void> update(CItem<T> item, { bool unshareWithOthers = true, })

Updates an existing item. Throws StateError if the self-key does not exist (use create for new items). Throws ArgumentError if item.owner is not this atSign.

With the default unshareWithOthers: true, any recipient copy whose atSign is NO LONGER in item.sharedWith is deleted; recipients present in both the existing set and item.sharedWith are overwritten in place. Pass false to leave any current recipient copies alone (useful when adding recipients without risking removal of existing ones during a concurrent read).

To change the value AND the recipient set in one call, mutate item.sharedWith directly before calling update — e.g. item.sharedWith..clear()..addAll(newSet); update(item).

If you only need to change recipients (no value change on the item itself), prefer updateSharedWith — it skips the self-key rewrite entirely and just diffs the recipient copies.

Typical usage: fetch an item via get / getItems, mutate its fields, then call update.

Implementation

Future<void> update(
  CItem<T> item, {
  bool unshareWithOthers = true,
}) async {
  if (item.owner != atSign) {
    throw ArgumentError('You may not update items owned by other atSigns');
  }
  if (!await _selfKeyExists(item.id)) {
    throw StateError(
      'Cannot update item "${item.id}": no such item exists in $namespace. '
      'Use create() to add a new item.',
    );
  }
  final results = await _put(item, unshareWithOthers: unshareWithOthers);
  if (results.any((r) => r is OpFailure)) {
    throw CollectionOpException(results);
  }
  await _awaitLocalEmissions();
}