feat: option to declare schema as const

[cmd-johnson]

This PR adds a new option that allows us to get additional type information for the protoMetadata export when using outputSchema=true.

Background

Using the outputSchema=true option, ts-proto outputs a protoMetadata export for all proto files.

This metadata object can be useful for rudimentary reflection and required if we want to access value options.
Unfortunately there is no compile time type safety for these values, because the export is declared as ProtoMetadata, losing a lot of useful type information.

Proposed Solution

When setting the option outputSchemaAsConst=true, do the following:

Instead of doing export const protoMetadata: ProtoMetadata = { ... }, export it as export const protoMetadata = { ... } as const satisfies ProtoMetadata.

This retains the full value of protoMetadata on the type level.
This additional type information can then be used to write type safe reflection methods, like for accessing the values of value options declared in proto files (see the included tests for some basic examples).

In order to provide type safety for the fileDescriptor field, I had to remove the call to FileDescriptorProto.fromPartial(...). As far as I can tell this call doesn't do much in practice, because the data passed to it at code generation time was already passed through FileDescriptorProto.fromPartial(fileDesc) and I think this results in the exact same value, making the fromPartial call in the generated code basically a no-op. You might want to double-check this before merging because this change isn't hidden behind the outputSchemaAsConst option.

Considerations

satisfies operator

The satisfies ProtoMetadata part of the declaration isn't strictly necessary as the exported value should match the ProtoMetadata interface anyway.
However, it can act as a hint to developers that the export conforms to the ProtoMetadata type instead of being completely independent.
It also acts as a kind of sanity check when type checking, making sure the generated type matches our expectations.

The satisfies operator is only supported since TypeScript 4.9, so code generated using this option will not work on older TS versions.

type complexity

When declaring protoMetadata as const, the type definition blows up a lot, because the whole value is now also encoded on the type level.
This allows for advanced use cases (like typesafe reflecton), but could potentially slow down the compiler when dealing with large schemas.
It also increases type declaration file sizes when the typescript files when the resulting .ts files are compiled to .js and .d.ts files.

[cmd-johnson]

Looks like the previous CI errors were because the tsconfig.proto.json used for validating the integration test types extends @tsconfig/strictest/tsconfig.json. This enables the exactOptionalPropertyTypes option, which in turn results in a few instances of generated code failing type checking because they assigned undefined in places were an object property was declared as propName?: T (namely in service and enum options).

[stephenh]

Just one musing question about the config flag, but otherwise looks great; thanks @cmd-johnson !

[stephenh]

Hi @cmd-johnson ! Wdyt of making outputSchema a tristate, like outputSchema=const would enable this behavior, vs. a net-new flag? We've done that with a few other flags and it's seemed nice so far.

[cmd-johnson]

That's what I wanted to do at first, but outputSchema already can be true or no-file-descriptor, which would mean that adding an as const option would also require adding a no-file-descriptor-as-const option or make the option's type an array of a new OutputSchema enum (similar to how outputServices works) and I didn't want to update all usages of no-file-descriptor 😅.

If you'd rather go that route than adding another parameter, I can make those changes. I'd prefer going the enum array route in that case, because it scales better if more options get added to the outputSchema flag at some point in the future.

[stephenh]

Ah yep! I was wondering if we'd run into that.

The enum array of outputSchema=no-file-descriptor,const,etc approach would be great, since you don't mind; thanks!

[cmd-johnson]

Done!
I've made it so you can combine the flags by specifying it multiple times, which is the way the outputServices flag works:

--ts_proto_opt=outputSchema=const,outputSchema=no-file-descriptor

[stephenh]

Ah nice! Great test, and I see what you're wanting to achieve

[stephenh]

Looks great, thanks @jonaskello !

[stephenh]

🎉 This issue has been resolved in version 2.1.0 🎉

The release is available on:

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

Your semantic-release bot 📦🚀