feat: represent field masks as string[]

[boukeversteegh]

See my comment at #510

Represent field masks as string[], instead of FieldMask:

Protobuf

syntax = "proto3";

import "google/protobuf/field_mask.proto";

message FieldMaskMessage {
  google.protobuf.FieldMask field_mask = 1;
}

Typescript

export interface FieldMaskMessage {
  fieldMask: string[] | undefined;
}

Changes

• Move canonical conversion logic from the parent message to FieldMask:
  • parent.toJSON delegates to FieldMask.toJSON(FieldMask.wrap(value))
  • parent.fromJSON delegates to FieldMask.unwrap(FieldMask.fromJSON(value))
• FieldMask.toJSON converts to canonical JSON directly, so the canonical representation can be used without a parent message
• FieldMask.fromJSON can accept both canonical form and a one-to-one JSON mapping of the underlying protobuf object {paths: ['foo', 'bar']} for servers that don't serve canonical forms.

Notes

• This change does stretch the concept of wrap/unwrap beyond its original intention (converting wrapper types). We can consider changing these names. For example: fromNativeType and toNativeType. I think this naming would work for all current cases and may be more clear, but it would be a breaking change.
• This is technically a breaking change, as the interface for messages with FieldMasks is now different. Not sure if it warrants increasing the major version, as we've only added FieldMask support very recently.

[boukeversteegh]

The package can now also be installed directly from github, to test PRs (thanks to adding the prepare script).

Install directly from branch with npm

npm install ts-proto 'github:stephenh/ts-proto#feature/field-mask-string-arrays'

Updating to specific commit

npm install ts-proto 'github:stephenh/ts-proto#7a4990c238cdcc8cc3ebe66a6a17cbd446f0e20d'

[stephenh]

Thanks for tackling this @boukeversteegh ! I've not yet done enough with the wrap / unwrap approach to 100% internalize it, so this really helped me get how it works.

I had one question about nudging around how we generate FieldMask.fromJSON but feel free to treat that as a musing/todo and just merge as-is. Thanks!

[stephenh]

I really like the map approach; that's nudging us towards a more configuration-driven vs. the current version if-driven approach.

Just wondering, I wonder we're lucky here that the JSON presentation of FieldMask is a single string value that happens to deserialize into the paths field.

I.e. maybe the key of this map should be "just FieldMask-the type" and we should look in the map, and let it just return the whole fromJson body?

Basically more how like toJSON ended up being handled (although again I definitely like the map-driven approach)...

Wdyt?

[boukeversteegh]

Indeed, I did consider doing just that. I went this way to make sure any follow up logic will also applied to fieldmasks. Admittedly, the only logic right now is the fact that we return a single JSON object (instead of constructing one field by field).

It's true that this approach only works exactly in this case, and might not work for other types (like Timestamp?).
If you feel returning the object immediately is more future proof or straightforward, I'm fine to change it.

[stephenh]

Ah cool, I'm good with the current approach!

[stephenh]

🤯

npm install ts-proto 'github:stephenh/ts-proto#feature/field-mask-string-arrays'

I didn't know that was a thing! Neat!

[stephenh]

This change does stretch the concept of wrap/unwrap beyond its original intention

Ah yeah, I'm good with the current wrap/unwrap terminology being used for technically-not-proto-official-wrapper-types...if anything I think it helped my mental model a little bit.

This is technically a breaking change, as the interface for messages with FieldMasks is now
different. Not sure if it warrants increasing the major version, as we've only added
FieldMask support very recently.

Yeah, I'm good with this being a non-breaking change. I'm reserving 2.x for "big" changes like refactoring the config args/etc (no idea when/if that will happen, but basically anything else "not as big as that", I've been doing as major version bumps).

[stephenh]

🎉 This PR is included in version 1.108.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀