ts-proto 1.114.5 → 1.115.0

package/CHANGELOG.md

@@ -1,3 +1,24 @@
+# [1.115.0](https://github.com/stephenh/ts-proto/compare/v1.114.7...v1.115.0) (2022-06-02)
+
+
+### Features
+
+* added option 'useJsonWireFormat' ([#576](https://github.com/stephenh/ts-proto/issues/576)) ([a71b145](https://github.com/stephenh/ts-proto/commit/a71b145c81136b8d8e3681b6753146d3ceeff179)), closes [#571](https://github.com/stephenh/ts-proto/issues/571)
+
+## [1.114.7](https://github.com/stephenh/ts-proto/compare/v1.114.6...v1.114.7) (2022-05-28)
+
+
+### Bug Fixes
+
+* Fix version number for Buf plugin. ([dc1fb7e](https://github.com/stephenh/ts-proto/commit/dc1fb7e766ed4115d026e7ff0e9a9480c1e42380))
+
+## [1.114.6](https://github.com/stephenh/ts-proto/compare/v1.114.5...v1.114.6) (2022-05-28)
+
+
+### Bug Fixes
+
+* Bump node in ts-proto.Dockerfile. ([42f3cea](https://github.com/stephenh/ts-proto/commit/42f3ceac5323056b1b845b51919ecddaa32bf258))
+
 ## [1.114.5](https://github.com/stephenh/ts-proto/compare/v1.114.4...v1.114.5) (2022-05-28)
 
 

package/README.markdown

@@ -104,7 +104,7 @@ You can also use the official plugin published to the Buf Registry.
 ```yaml
 version: v1
 plugins:
-  - remote: buf.build/roundrock-io/plugins/ts-proto
+  - remote: buf.build/stephenh/plugins/ts-proto
     out: ../gen/ts
 ```
 
@@ -274,34 +274,36 @@ Generated code will be placed in the Gradle build directory.
 
   Currently `browser` doesn't have any specific behavior other than being "not `node`". It probably will soon/at some point.
 
-- With `--ts_proto_opt=useOptionals=true`, non-scalar fields are declared as optional TypeScript properties, e.g. `field?: Message` instead of the default `field: Message | undefined`.
+- With `--ts_proto_opt=useOptionals=messages` (for message fields) or `--ts_proto_opt=useOptionals=all` (for message and scalar fields), fields are declared as optional keys, e.g. `field?: Message` instead of the default `field: Message | undefined`.
 
-  ts-proto defaults to `useOptionals=false`, e.g. `field: Message | undefined`, because it is the most safe for use cases like:
+  ts-proto defaults to `useOptionals=none` because it:
+  
+  1. Prevents typos when initializing messages, and
+  2. Provides the most consistent API to readers
+  3. Ensures production messages are properly initialized with all fields. 
 
-  ```typescript
-  interface SomeMessage {
-    firstName: string | undefined;
-    lastName: string | undefined;
-  }
-
-  const data = { firstName: 'a', lastTypo: 'b' };
-
-  // This would compile if `lastName` was `lastName?`, even though the
-  // `lastTypo` key above means that `lastName` is not assigned.
-  const message: SomeMessage = {
-    ...data,
-  };
-  ```
+  For typo prevention, optional fields make it easy for extra fields to slip into a message (until we get [Exact Types](https://github.com/microsoft/TypeScript/issues/12936)),  i.e.:
 
-  However, the type-safety of `useOptionals=false` is admittedly tedious if you have many inherently-unused fields, so you can use `useOptionals=true` if that trade-off makes sense for your project.
+   ```typescript
+   interface SomeMessage {
+     firstName: string | undefined;
+     lastName: string | undefined;
+   }
+   // Declared with a typo
+   const data = { firstName: 'a', lastTypo: 'b' };
+   // With useOptionals=none, this correctly fails to compile; if `lastName` was optional, it would not
+   const message: SomeMessage = { ...data };
+   ```
+  
+   For a consistent API, if `SomeMessage.lastName` is optional `lastName?`, then readers have to check _two_ empty conditions: a) is `lastName` `undefined` (b/c it was created in-memory and left unset), or b) is `lastName` empty string (b/c we read `SomeMessage` off the wire and correctly set `lastName` to empty string)?
 
-  You can also use the generated `SomeMessage.fromPartial` methods to opt into the optionality on a per-call-site basis. The `fromPartial` allows the creator/writer to have default values applied (i.e. `undefined` --> `0`), and the return value will still be the non-optional type that provides a consistent view (i.e. always `0`) to clients.
+   For ensuring proper initialization, if later `SomeMessage.middleInitial` is added, but it's marked as optional `middleInitial?`, you may have many call sites in production code that _should_ now be passing `middleInitial` to create a valid `SomeMessage`, but are not.
 
-  Eventually if TypeScript supports [Exact Types](https://github.com/microsoft/TypeScript/issues/12936), that should allow ts-proto to switch to `useOptionals=true` as the default/only behavior, have the generated `Message.encode`/`Message.toPartial`/etc. methods accept `Exact<T>` versions of the message types, and the result would be both safe + succinct.
+   So, between typo-prevention, reader inconsistency, and proper initialization, ts-proto recommends using `useOptionals=none` as the "most safe" option.
 
-  Also see the comment in [this issue](https://github.com/stephenh/ts-proto/issues/120#issuecomment-678375833) which explains the nuance behind making all fields optional (currently `useOptionals` only makes message fields optional), specifically that a message created with `const message: Message = { ...key not set... }` (so `key` is `undefined`) vs. `const message = Message.decode(...key not set...)` (so `key` is the default value) would look different to clients.
+   All that said, this approach does require writers/creators to set every field (although `fromPartial` is meant to address this), so if you still want to have optional fields, you can set `useOptionals=messages` or `useOptionals=all`.
 
-  Note that RPC methods, like `service.ping({ key: ... })`, accept `DeepPartial` versions of the request messages, because of the same rationale that it makes it easy for the writer call-site to get default values for free, and because the "reader" is the internal ts-proto serialization code, it can apply the defaults as necessary.
+   (See [this issue](https://github.com/stephenh/ts-proto/issues/120#issuecomment-678375833) and [this issue](https://github.com/stephenh/ts-proto/issues/397#issuecomment-977259118) for discussions on `useOptional`.)
 
 - With `--ts_proto_opt=exportCommonSymbols=false`, utility types like `DeepPartial` won't be `export`d.
 
@@ -404,6 +406,11 @@ Generated code will be placed in the Gradle build directory.
 
   Note that, as indicated, this means Object.keys will not include set-by-default fields, so if you have code that iterates over messages keys in a generic fashion, it will have to also iterate over keys inherited from the prototype.
 
+- With `--ts_proto_opt=useJsonWireFormat=true`, the generated code will reflect the JSON representation of Protobuf messages.
+
+  Requires `onlyTypes=true`. Implies `useDate=string` and `stringEnums=true`. This option is to generate types that can be directly used with marshalling/unmarshalling Protobuf messages serialized as JSON.  
+  You may also want to set `useOptionals=all`, as gRPC gateways are not required to send default value for scalar values.
+
 ### Only Types
 
 If you're looking for `ts-proto` to generate only types for your Protobuf types then passing all three of `outputEncodeMethods`, `outputJsonMethods`, and `outputClientImpl` as `false` is probably what you want, i.e.:

package/build/enums.js

@@ -20,15 +20,16 @@ function generateEnum(ctx, fullName, enumDesc, sourceInfo) {
         chunks.push(ts_poet_1.code `export ${options.constEnums ? 'const ' : ''}enum ${ts_poet_1.def(fullName)} {`);
     }
     const delimiter = options.enumsAsLiterals ? ':' : '=';
+    const stringEnums = options.stringEnums || (options.onlyTypes && options.useJsonWireFormat);
     enumDesc.value.forEach((valueDesc, index) => {
         var _a;
         const info = sourceInfo.lookup(sourceInfo_1.Fields.enum.value, index);
         utils_1.maybeAddComment(info, chunks, (_a = valueDesc.options) === null || _a === void 0 ? void 0 : _a.deprecated, `${valueDesc.name} - `);
-        chunks.push(ts_poet_1.code `${valueDesc.name} ${delimiter} ${options.stringEnums ? `"${valueDesc.name}"` : valueDesc.number.toString()},`);
+        chunks.push(ts_poet_1.code `${valueDesc.name} ${delimiter} ${stringEnums ? `"${valueDesc.name}"` : valueDesc.number.toString()},`);
     });
     if (options.unrecognizedEnum)
         chunks.push(ts_poet_1.code `
-      ${UNRECOGNIZED_ENUM_NAME} ${delimiter} ${options.stringEnums ? `"${UNRECOGNIZED_ENUM_NAME}"` : UNRECOGNIZED_ENUM_VALUE.toString()},`);
+      ${UNRECOGNIZED_ENUM_NAME} ${delimiter} ${stringEnums ? `"${UNRECOGNIZED_ENUM_NAME}"` : UNRECOGNIZED_ENUM_VALUE.toString()},`);
     if (options.enumsAsLiterals) {
         chunks.push(ts_poet_1.code `} as const`);
         chunks.push(ts_poet_1.code `\n`);
@@ -37,7 +38,7 @@ function generateEnum(ctx, fullName, enumDesc, sourceInfo) {
     else {
         chunks.push(ts_poet_1.code `}`);
     }
-    if (options.outputJsonMethods || (options.stringEnums && options.outputEncodeMethods)) {
+    if (options.outputJsonMethods || (stringEnums && options.outputEncodeMethods)) {
         chunks.push(ts_poet_1.code `\n`);
         chunks.push(generateEnumFromJson(ctx, fullName, enumDesc));
     }
@@ -45,7 +46,7 @@ function generateEnum(ctx, fullName, enumDesc, sourceInfo) {
         chunks.push(ts_poet_1.code `\n`);
         chunks.push(generateEnumToJson(ctx, fullName, enumDesc));
     }
-    if (options.stringEnums && options.outputEncodeMethods) {
+    if (stringEnums && options.outputEncodeMethods) {
         chunks.push(ts_poet_1.code `\n`);
         chunks.push(generateEnumToNumber(ctx, fullName, enumDesc));
     }

package/build/options.js

@@ -67,6 +67,7 @@ function defaultOptions() {
         useExactTypes: true,
         unknownFields: false,
         usePrototypeForDefaults: false,
+        useJsonWireFormat: false,
     };
 }
 exports.defaultOptions = defaultOptions;

package/build/types.js

@@ -436,6 +436,7 @@ function isEmptyType(typeName) {
 }
 exports.isEmptyType = isEmptyType;
 function valueTypeName(ctx, typeName) {
+    const useJsonWireFormat = ctx.options.onlyTypes && ctx.options.useJsonWireFormat;
     switch (typeName) {
         case '.google.protobuf.StringValue':
             return ts_poet_1.code `string`;
@@ -451,7 +452,7 @@ function valueTypeName(ctx, typeName) {
         case '.google.protobuf.BoolValue':
             return ts_poet_1.code `boolean`;
         case '.google.protobuf.BytesValue':
-            return ctx.options.env === options_1.EnvOption.NODE ? ts_poet_1.code `Buffer` : ts_poet_1.code `Uint8Array`;
+            return ctx.options.env === options_1.EnvOption.NODE ? ts_poet_1.code `Buffer` : useJsonWireFormat ? ts_poet_1.code `string` : ts_poet_1.code `Uint8Array`;
         case '.google.protobuf.ListValue':
             return ts_poet_1.code `Array<any>`;
         case '.google.protobuf.Value':
@@ -459,7 +460,11 @@ function valueTypeName(ctx, typeName) {
         case '.google.protobuf.Struct':
             return ts_poet_1.code `{[key: string]: any}`;
         case '.google.protobuf.FieldMask':
-            return ts_poet_1.code `string[]`;
+            return useJsonWireFormat ? ts_poet_1.code `string` : ts_poet_1.code `string[]`;
+        case '.google.protobuf.Duration':
+            return useJsonWireFormat ? ts_poet_1.code `string` : undefined;
+        case '.google.protobuf.Timestamp':
+            return useJsonWireFormat ? ts_poet_1.code `string` : undefined;
         default:
             return undefined;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-proto",
-  "version": "1.114.5",
+  "version": "1.115.0",
   "description": "",
   "main": "build/plugin.js",
   "repository": "github:stephenh/ts-proto",