From the NodeJS documentation, it is not clear enough whether calling file.setMetadata({contentType: 'image/png'}) would remove existing metadata fields on the field (as they are not specified) or would only change the content type.

To understand this, one must dig deeply into the NodeJS SDK to understand the exact behaviour and cross-reference it with the Cloud Storage API.

From my understanding, setMetadata is using PATCH, so any existing metadata would stay the same, correct?

--

Could we please update the documentation to make this clearer?

e.g. Set the metadata of the object. Uses PATCH method, meaning it only modifies passed fields and leaves unspecified fields unchanged.

And also mirror those function documentation to the File class method (as otherwise, the documentation will not be surfaced on the SDK API documentation page)
See: https://cloud.google.com/nodejs/docs/reference/storage/latest/storage/file#_google_cloud_storage_File_setMetadata_member_1_