There's no particular reason. I though partial updates were more frequent than complete overrides but I may have been wrong.

I realise that the fact that the syntax is the reverse of the v0 one is confusing though ($set used to be for partial updates), but reversing it would be a breaking change and so, while I'm in favour of the change, I will not implement it right away, but rather toward the end of the year.

Would a $partial helper fit your needs? Like this:

await PokemonEntity.build(UpdateItemCommand)
	.item({
		pokemonId: 'Pikachu',
		trainer: 'Ash',
		data: $partial({
			moves: $set(['Thunderbolt', 'Quick Attack']),
		}),
	})
	.send();

Note that this $partial helper could be part of the v1 as it is not a breaking change in itself and could help you migrate (just make sure to leave no ambiguous updates, always use $set or $partial).

I think it would be a good idea to give us a means to NOT update partially.

We have one use case where we update a VERY large object with many nested lists, maps or records. Usually we can get away with calling a serialize function to export a JSON representation and spread that value into an Update Command's item argument. However, sometimes it won't work if the value is an empty list.

For instance, we were able to use something like this:

await this.entity.build(UpdateItemCommand).item({
  ...myData,
  pkVal,
  id,
})
.send();

Where pkVal and id are our PK and SK values (respectively). I know that we might be able to use PutItemCommand in place of that, but this is an update with some GSIs that have already been calculated and set, which would require a query first to get the aforementioned GSI.

However, to get around the shortcomings of the partial-by-default issue, we have to use something like the following:

await this.entity.build(UpdateItemCommand).item({
  ...myData,
  pkVal,
  id,
  dat1: $set(myData.dat1),
  dat2: $set(myData.dat2),
  // ...etc
})
.send();

Allowing us to utilize $set-by-default using a configuration would be nice.