ts-proto 1.114.7 → 1.115.2

package/CHANGELOG.md

@@ -1,3 +1,24 @@
+## [1.115.2](https://github.com/stephenh/ts-proto/compare/v1.115.1...v1.115.2) (2022-06-03)
+
+
+### Bug Fixes
+
+* simplify handling useJsonWireFormat=true and fix onlyTypes=true ([#583](https://github.com/stephenh/ts-proto/issues/583)) ([6e7f938](https://github.com/stephenh/ts-proto/commit/6e7f9387d144f506ded982604f32981ac5e327de))
+
+## [1.115.1](https://github.com/stephenh/ts-proto/compare/v1.115.0...v1.115.1) (2022-06-02)
+
+
+### Bug Fixes
+
+* Bump protobufjs. ([#585](https://github.com/stephenh/ts-proto/issues/585)) ([ba6b85d](https://github.com/stephenh/ts-proto/commit/ba6b85d9d5b7ce191dce898c462cf164a6b1e308))
+
+# [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)
 
 

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' };
+  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.:
 
-  // This would compile if `lastName` was `lastName?`, even though the
-  // `lastTypo` key above means that `lastName` is not assigned.
-  const message: SomeMessage = {
-    ...data,
-  };
-  ```
+   ```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)?
 
-  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.
+   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.
 
-  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.
+   So, between typo-prevention, reader inconsistency, and proper initialization, ts-proto recommends using `useOptionals=none` as the "most safe" option.
 
-  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.
+   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`.
 
-  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.
-
-  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.
 
@@ -394,7 +396,7 @@ Generated code will be placed in the Gradle build directory.
 
 - With `--ts_proto_opt=onlyTypes=true`, only types will be emitted, and imports for `long` and `protobufjs/minimal` will be excluded.
 
-  Note: _This is a combination_ of `outputJsonMethods=false,outputEncodeMethods=false,outputClientImpl=false,nestJs=false`
+  This is the same as setting `outputJsonMethods=false,outputEncodeMethods=false,outputClientImpl=false,nestJs=false`
 
 - With `--ts_proto_opt=usePrototypeForDefaults=true`, the generated code will wrap new objects with `Object.create`.
 
@@ -404,11 +406,10 @@ 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.
 
-### 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.:
+- With `--ts_proto_opt=useJsonWireFormat=true`, the generated code will reflect the JSON representation of Protobuf messages.
 
-`--ts_proto_opt=onlyTypes=true`.
+  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.
 
 ### NestJS Support
 

package/build/options.js

@@ -67,6 +67,7 @@ function defaultOptions() {
         useExactTypes: true,
         unknownFields: false,
         usePrototypeForDefaults: false,
+        useJsonWireFormat: false,
     };
 }
 exports.defaultOptions = defaultOptions;
@@ -87,8 +88,17 @@ function optionsFromParameter(parameter) {
         }
         Object.assign(options, parsed);
     }
-    // We should promote onlyTypes to its own documented flag, but just an alias for now
-    if (!options.outputJsonMethods && !options.outputEncodeMethods && !options.outputClientImpl && !options.nestJs) {
+    // onlyTypes=true implies outputJsonMethods=false,outputEncodeMethods=false,outputClientImpl=false,nestJs=false
+    if (options.onlyTypes) {
+        options.outputJsonMethods = false;
+        options.outputEncodeMethods = false;
+        options.outputClientImpl = false;
+        options.nestJs = false;
+    }
+    else if (!options.outputJsonMethods &&
+        !options.outputEncodeMethods &&
+        !options.outputClientImpl &&
+        !options.nestJs) {
         options.onlyTypes = true;
     }
     // Treat forceLong=true as LONG
@@ -123,6 +133,17 @@ function optionsFromParameter(parameter) {
     else if (typeof options.snakeToCamel === 'string') {
         options.snakeToCamel = [options.snakeToCamel];
     }
+    if (options.useJsonWireFormat) {
+        if (!options.onlyTypes) {
+            // useJsonWireFormat requires onlyTypes=true
+            options.useJsonWireFormat = false;
+        }
+        else {
+            // useJsonWireFormat implies stringEnums=true and useDate=string
+            options.stringEnums = true;
+            options.useDate = DateOption.STRING;
+        }
+    }
     return options;
 }
 exports.optionsFromParameter = optionsFromParameter;

package/build/types.js

@@ -451,7 +451,11 @@ 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`
+                : ctx.options.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 +463,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 ctx.options.useJsonWireFormat ? ts_poet_1.code `string` : ts_poet_1.code `string[]`;
+        case '.google.protobuf.Duration':
+            return ctx.options.useJsonWireFormat ? ts_poet_1.code `string` : undefined;
+        case '.google.protobuf.Timestamp':
+            return ctx.options.useJsonWireFormat ? ts_poet_1.code `string` : undefined;
         default:
             return undefined;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-proto",
-  "version": "1.114.7",
+  "version": "1.115.2",
   "description": "",
   "main": "build/plugin.js",
   "repository": "github:stephenh/ts-proto",
@@ -65,8 +65,8 @@
     "@types/object-hash": "^1.3.0",
     "dataloader": "^1.4.0",
     "object-hash": "^1.3.1",
-    "protobufjs": "^6.8.8",
-    "ts-poet": "^4.11.0",
+    "protobufjs": "^6.11.3",
+    "ts-poet": "^t 4.11.0",
     "ts-proto-descriptors": "1.6.0"
   }
 }