Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

More info on using the generated definitions? #291

Closed
boan-anbo opened this issue Oct 10, 2022 · 2 comments
Closed

More info on using the generated definitions? #291

boan-anbo opened this issue Oct 10, 2022 · 2 comments
Labels
enhancement New feature or request

Comments

@boan-anbo
Copy link

boan-anbo commented Oct 10, 2022

Been using connect-web for some time, it's sooo good compared to the past JS/TS generators I've used. Thanks so much for the work!

I was wondering if the documentation could add a few words on how best to use the generated definitions.

For example, what are the intended uses for PartialMessage<T> and PlainMessage<T>? What's the best practice for class conversions and initialization? I ask because, for example, the default constructor's parameter PartialMessage has insufficient IDE support and shows no auto-complete when initializing. The FieldList helps with type-checking but it's not too clear if it's intended for the users or for internal use.

The documentation already covered how to convert to/from JSON and binary; a few more documentation examples on which interface/class/functions to use for type-checking during conversions to/from other user types will be very much appreciated!

@boan-anbo boan-anbo added the enhancement New feature or request label Oct 10, 2022
@timostamm
Copy link
Member

Hey @boan-anbo,

I think something is off with your IDE. The TypeScript language service should absolutely be able to provide auto-complete and suggestions:

Screen Shot 2022-10-10 at 13 08 20

Maybe you need to update TypeScript, or some part of your IDE? This should definitely work!

Thanks for your questions regarding initialization! If you want to create a new instance of a message, you should always use new, and pass the properties where you want to provide a value. This makes sure that other properties - for example map fields, repeated fields and scalar fields - always have their default value. You can find more information here and here.

We use PartialMessage<T> for the initializer object of constructors - it simply makes all properties optional. In your code, you should only use PartialMessage<T> if you provide an API for other users, and want to give them the most flexibility for passing in data.

PlainMessage<T> is an exact representation of just the fields of a message, without any of its methods. You can find more information here. This type can be useful in you business logic, if you don't care about the class methods for serialization, and don't need instanceof. Note that we are going to improve this part soon, see bufbuild/protobuf-es#230 (comment).

I am sorry our connect.build documentation wasn't more helpful. I think we do have some hopefully helpful documentation on protobuf-es, but we definitely need to integrate it better with connect.build. I've bumped the priority of our internal ticket for this. Thanks for your input!

@timostamm
Copy link
Member

Closing this. Please feel free to reopen in case I was missing something!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request
Projects
None yet
Development

No branches or pull requests

2 participants