feat: option to declare schema as const #1096
Conversation
cmd-johnson
force-pushed
the
feature/meta-typings-as-const
branch
from
aedb4e5 to
77b580d
Compare
cmd-johnson
force-pushed
the
feature/meta-typings-as-const
branch
from
77b580d to
ba318c7
Compare
|
Looks like the previous CI errors were because the |
There was a problem hiding this comment.
Just one musing question about the config flag, but otherwise looks great; thanks @cmd-johnson !
README.markdown
Outdated
| @@ -456,6 +456,8 @@ Generated code will be placed in the Gradle build directory. | |||
|
|
|||
| - With `--ts_proto_opt=outputSchema=true`, meta typings will be generated that can later be used in other code generators. If outputSchema is instead specified to be `no-file-descriptor` then we do not include the file descriptor in the generated schema. This is useful if you are trying to minimize the size of the generated schema. | |||
|
|
|||
| - With `--ts_proto_opt=outputSchemaAsConst=true`, the `protoMetadata` export of `outputSchema=true` is declared using `as const` and `satisfies` (supported by TypeScript since [4.9](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-9.html#the-satisfies-operator)), providing more detailed type information. | |||
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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!
There was a problem hiding this comment.
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
| // chaining if we didn't use `as const` to declare the `protoMetadata` | ||
| // export. | ||
|
|
||
| expect(protoMetadata.options.enums.TestEnum.values.VALUE_A.string_value).toBe("A"); |
There was a problem hiding this comment.
Ah nice! Great test, and I see what you're wanting to achieve
|
Looks great, thanks @jonaskello ! |
# [2.1.0](v2.0.4...v2.1.0) (2024-09-04) ### Features * option to declare schema as const ([#1096](#1096)) ([4cc1a1e](4cc1a1e))
|
🎉 This issue has been resolved in version 2.1.0 🎉 The release is available on: Your semantic-release bot 📦🚀 |
This PR adds a new option that allows us to get additional type information for the
protoMetadataexport when usingoutputSchema=true.Background
Using the
outputSchema=trueoption, ts-proto outputs aprotoMetadataexport 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 asexport const protoMetadata = { ... } as const satisfies ProtoMetadata.This retains the full value of
protoMetadataon 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
fileDescriptorfield, I had to remove the call toFileDescriptorProto.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 throughFileDescriptorProto.fromPartial(fileDesc)and I think this results in the exact same value, making thefromPartialcall in the generated code basically a no-op. You might want to double-check this before merging because this change isn't hidden behind theoutputSchemaAsConstoption.Considerations
satisfiesoperatorThe
satisfies ProtoMetadatapart of the declaration isn't strictly necessary as the exported value should match theProtoMetadatainterface anyway.However, it can act as a hint to developers that the export conforms to the
ProtoMetadatatype 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
satisfiesoperator is only supported since TypeScript 4.9, so code generated using this option will not work on older TS versions.type complexity
When declaring
protoMetadataas 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
.tsfiles are compiled to.jsand.d.tsfiles.