ts-proto 1.134.0 → 1.135.1

package/README.markdown

@@ -115,7 +115,7 @@ plugins:
     out: ../gen/ts
     opt:
       - outputServices=...
-      - useExactTypes=...    
+      - useExactTypes=...
 ```
 
 # Goals
@@ -300,33 +300,33 @@ Generated code will be placed in the Gradle build directory.
 - 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=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. 
+  3. Ensures production messages are properly initialized with all fields.
 
-  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.:
+  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.:
 
-   ```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)?
+  ```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 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.
+  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)?
 
-   So, between typo-prevention, reader inconsistency, and proper initialization, ts-proto recommends using `useOptionals=none` as the "most safe" option.
+  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.
 
-   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`.
+  So, between typo-prevention, reader inconsistency, and proper initialization, ts-proto recommends using `useOptionals=none` as the "most safe" option.
 
-   (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`.)
+  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`.
+
+  (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.
 
@@ -346,11 +346,11 @@ Generated code will be placed in the Gradle build directory.
 
   `snakeToCamel` can also be set as a `_`-delimited list of strings (comma is reserved as the flag delimited), i.e. `--ts_proto_opt=snakeToCamel=keys_json`, where including `keys` will make message keys be camel case and including `json` will make JSON keys be camel case.
 
-   Empty string, i.e. `snakeToCamel=`, will keep both messages keys and `JSON` keys as snake case (it is the same as `snakeToCamel=false`).
+  Empty string, i.e. `snakeToCamel=`, will keep both messages keys and `JSON` keys as snake case (it is the same as `snakeToCamel=false`).
 
-   Note that to use the `json_name` attribute, you'll have to use the `json`.
+  Note that to use the `json_name` attribute, you'll have to use the `json`.
 
-   The default behavior is `keys_json`, i.e. both will be camel cased, and `json_name` will be used if set.
+  The default behavior is `keys_json`, i.e. both will be camel cased, and `json_name` will be used if set.
 
 - With `--ts_proto_opt=outputEncodeMethods=false`, the `Message.encode` and `Message.decode` methods for working with protobuf-encoded/binary data will not be output.
 
@@ -451,7 +451,7 @@ Generated code will be placed in the Gradle build directory.
 - With `--ts_proto_opt=initializeFieldsAsUndefined=false`, all optional field initializers will be omited from the generated base instances.
 
 - With `--ts_proto_opt=Mgoogle/protobuf/empty.proto=./google3/protobuf/empty`, ('M' means 'importMapping', similar to [protoc-gen-go](https://developers.google.com/protocol-buffers/docs/reference/go-generated#package)), the generated code import path for `./google/protobuf/empty.ts` will reflect the overridden value:
-  
+
   - `Mfoo/bar.proto=@myorg/some-lib` will map `foo/bar.proto` imports into `import ... from '@myorg/some-lib'`.
   - `Mfoo/bar.proto=./some/local/lib` will map `foo/bar.proto` imports into `import ... from './some/local/lib'`.
   - `Mfoo/bar.proto=some-modules/some-lib` will map `foo/bar.proto` imports into `import ... from 'some-module/some-lib'`.
@@ -464,9 +464,10 @@ Generated code will be placed in the Gradle build directory.
 
 - With `--ts_proto_opt=useReadonlyTypes=true`, the generated types will be declared as immutable using typescript's `readonly` modifer.
 
-- With `--ts_proto_opt=useSnakeTypeName=false` will remove snake casing from types. 
-  
+- With `--ts_proto_opt=useSnakeTypeName=false` will remove snake casing from types.
+
   Example Protobuf
+
   ```protobuf
   message Box {
       message Element {
@@ -480,7 +481,8 @@ Generated code will be placed in the Gradle build directory.
         }
   }
   ```
-  by default this is enabled which would generate a type of `Box_Element_Image_Alignment`. By disabling this option the type that is generated would be `BoxElementImageAlignment`. 
+
+  by default this is enabled which would generate a type of `Box_Element_Image_Alignment`. By disabling this option the type that is generated would be `BoxElementImageAlignment`.
 
 ### NestJS Support
 
@@ -630,27 +632,41 @@ ts-protoc --ts_proto_out=./output -I=./protos ./protoc/*.proto
 
 # OneOf Handling
 
-By default, `oneof` fields are modeled "flatly" in the message, i.e. `oneof either_field { string field_a; string field_b }` means that the message will have `field_a: string | undefined; field_b: string | undefined`.
+By default, ts-proto models `oneof` fields "flatly" in the message, e.g. a message like:
+
+```protobuf
+message Foo {
+  oneof either_field { string field_a = 1; string field_b = 2; }
+}
+```
+
+Will generate a `Foo` type with two fields: `field_a: string | undefined;` and `field_b: string | undefined`.
 
 With this output, you'll have to check both `if object.field_a` and `if object.field_b`, and if you set one, you'll have to remember to unset the other.
 
-We recommend using the `oneof=unions` option, which will change the output to be an Abstract Data Type/ADT like:
+Instead, we recommend using the `oneof=unions` option, which will change the output to be an Abstract Data Type/ADT like:
 
 ```typescript
 interface YourMessage {
-  eitherField: { $case: 'field_a'; field_a: string } | { $case: 'field_b'; field_b: string };
+  eitherField?: { $case: "field_a"; field_a: string } | { $case: "field_b"; field_b: string };
 }
 ```
 
 As this will automatically enforce only one of `field_a` or `field_b` "being set" at a time, because the values are stored in the `eitherField` field that can only have a single value at a time.
 
+(Note that `eitherField` is optional b/c `oneof` in Protobuf means "at most one field" is set, and does not mean one of the fields _must_ be set.)
+
 In ts-proto's currently-unscheduled 2.x release, `oneof=unions` will become the default behavior.
 
 # Default values and unset fields
 
-In core Protobuf, values that are _unset_ or equal to the default value are not sent over the wire.
-The default value of a message is `undefined`. Primitive types take their natural default value, i.e. `string` is `''`, `number` is `0`, etc.
-This behavior enables forward compatibility, as primitive fields will always have a value, even when omitted by outdated agents, but it also means _default_ and _unset_ values cannot be distinguished.
+In core Protobuf (and so also `ts-proto`), values that are _unset_ or equal to the default value are not sent over the wire.
+
+For example, the default value of a message is `undefined`. Primitive types take their natural default value, e.g. `string` is `''`, `number` is `0`, etc.
+
+Protobuf chose/enforces this behavior because it enables forward compatibility, as primitive fields will always have a value, even when omitted by outdated agents.
+
+This is good, but it also means _default_ and _unset_ values cannot be distinguished in `ts-proto` fields; it's just fundamentally how Protobuf works.
 
 If you need primitive fields where you can detect set/unset, see [Wrapper Types](#wrapper-types).
 
@@ -671,7 +687,7 @@ Foo.decode(protobufBytes); // => { bar: '' }
 ```
 
 ```typescript
-Foo.encode({ bar: '' }); // => { }, writes an empty Foo object, in protobuf binary format
+Foo.encode({ bar: "" }); // => { }, writes an empty Foo object, in protobuf binary format
 ```
 
 **fromJSON / toJSON**
@@ -680,8 +696,8 @@ Reading JSON will also initialize the default values. Since senders may either o
 
 ```typescript
 Foo.fromJSON({}); // => { bar: '' }
-Foo.fromJSON({ bar: '' }); // => { bar: '' }
-Foo.fromJSON({ bar: 'baz' }); // => { bar: 'baz' }
+Foo.fromJSON({ bar: "" }); // => { bar: '' }
+Foo.fromJSON({ bar: "baz" }); // => { bar: 'baz' }
 ```
 
 When writing JSON, `ts-proto` currently does **not** normalize message when converting to JSON, other than omitting unset fields, but it may do so in the future.
@@ -690,16 +706,16 @@ When writing JSON, `ts-proto` currently does **not** normalize message when conv
 // Current ts-proto behavior
 Foo.toJSON({}); // => { }
 Foo.toJSON({ bar: undefined }); // => { }
-Foo.toJSON({ bar: '' }); // => { bar: '' } - note: this is the default value, but it's not omitted
-Foo.toJSON({ bar: 'baz' }); // => { bar: 'baz' }
+Foo.toJSON({ bar: "" }); // => { bar: '' } - note: this is the default value, but it's not omitted
+Foo.toJSON({ bar: "baz" }); // => { bar: 'baz' }
 ```
 
 ```typescript
 // Possible future behavior, where ts-proto would normalize message
 Foo.toJSON({}); // => { }
 Foo.toJSON({ bar: undefined }); // => { }
-Foo.toJSON({ bar: '' }); // => { } - note: omitting the default value, as expected
-Foo.toJSON({ bar: 'baz' }); // => { bar: 'baz' }
+Foo.toJSON({ bar: "" }); // => { } - note: omitting the default value, as expected
+Foo.toJSON({ bar: "baz" }); // => { bar: 'baz' }
 ```
 
 - Please open an issue if you need this behavior.
@@ -755,13 +771,13 @@ interface ExampleMessage {
 When encoding a message the primitive value is converted back to its corresponding wrapper type:
 
 ```typescript
-ExampleMessage.encode({ name: 'foo' }); // => { name: { value: 'foo' } }, in binary
+ExampleMessage.encode({ name: "foo" }); // => { name: { value: 'foo' } }, in binary
 ```
 
 When calling toJSON, the value is not converted, because wrapper types are idiomatic in JSON.
 
 ```typescript
-ExampleMessage.toJSON({ name: 'foo' }); // => { name: 'foo' }
+ExampleMessage.toJSON({ name: "foo" }); // => { name: 'foo' }
 ```
 
 ## JSON Types (Struct Types)
@@ -803,7 +819,7 @@ interface ExampleMessage {
 Encoding a JSON value embedded in a message, converts it to a Struct Type:
 
 ```typescript
-ExampleMessage.encode({ anything: { name: 'hello' } });
+ExampleMessage.encode({ anything: { name: "hello" } });
 /* Outputs the following structure, encoded in protobuf binary format:
 {
   anything: Value {

package/build/case.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.camelCase = exports.capitalize = exports.camelToSnake = exports.snakeToCamel = exports.maybeSnakeToCamel = void 0;
+exports.camelCaseGrpc = exports.camelCase = exports.capitalize = exports.camelToSnake = exports.snakeToCamel = exports.maybeSnakeToCamel = void 0;
+const case_anything_1 = require("case-anything");
 /** Converts `key` to TS/JS camel-case idiom, unless overridden not to. */
 function maybeSnakeToCamel(key, options) {
     if (options.snakeToCamel.includes("keys") && key.includes("_")) {
@@ -35,3 +36,12 @@ function camelCase(s) {
     return s.substring(0, 1).toLowerCase() + s.substring(1);
 }
 exports.camelCase = camelCase;
+function camelCaseGrpc(s) {
+    /* This function uses the exact same semantics found inside the grpc
+     * nodejs library. Camel case splitting must be done by word i.e
+     * GetAPIValue must become getApiValue (notice the API becomes Api).
+     * This needs to be followed otherwise it will not succeed in the grpc nodejs module.
+     */
+    return (0, case_anything_1.camelCase)(s);
+}
+exports.camelCaseGrpc = camelCaseGrpc;

package/build/main.js

@@ -538,13 +538,14 @@ function generateInterfaceDeclaration(ctx, fullName, messageDesc, sourceInfo, fu
 function generateOneofProperty(ctx, messageDesc, oneofIndex, sourceInfo) {
     const { options } = ctx;
     const fields = messageDesc.field.filter((field) => (0, types_1.isWithinOneOf)(field) && field.oneofIndex === oneofIndex);
+    const mbReadonly = maybeReadonly(options);
     const unionType = (0, ts_poet_1.joinCode)(fields.map((f) => {
         let fieldName = (0, case_1.maybeSnakeToCamel)(f.name, options);
         let typeName = (0, types_1.toTypeName)(ctx, messageDesc, f);
-        return (0, ts_poet_1.code) `{ ${maybeReadonly(options)}$case: '${fieldName}', ${maybeReadonly(options)}${fieldName}: ${typeName} }`;
+        return (0, ts_poet_1.code) `{ ${mbReadonly}$case: '${fieldName}', ${mbReadonly}${fieldName}: ${typeName} }`;
     }), { on: " | " });
     const name = (0, case_1.maybeSnakeToCamel)(messageDesc.oneofDecl[oneofIndex].name, options);
-    return (0, ts_poet_1.code) `${maybeReadonly(options)}${name}?: ${unionType},`;
+    return (0, ts_poet_1.code) `${mbReadonly}${name}?: ${unionType},`;
     /*
     // Ideally we'd put the comments for each oneof field next to the anonymous
     // type we've created in the type union above, but ts-poet currently lacks

package/build/utils.js

@@ -138,7 +138,7 @@ class FormattedMethodDescriptor {
     static formatName(methodName, options) {
         let result = methodName;
         if (options.lowerCaseServiceMethods || options.outputServices.includes(options_1.ServiceOption.GRPC)) {
-            result = (0, case_1.camelCase)(result);
+            result = (0, case_1.camelCaseGrpc)(result);
         }
         return result;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-proto",
-  "version": "1.134.0",
+  "version": "1.135.1",
   "description": "",
   "main": "build/plugin.js",
   "repository": "github:stephenh/ts-proto",
@@ -60,10 +60,12 @@
   },
   "dependencies": {
     "@types/object-hash": "^1.3.0",
+    "case-anything": "^2.1.10",
     "dataloader": "^1.4.0",
     "object-hash": "^1.3.1",
     "protobufjs": "^6.11.3",
-    "ts-poet": "^6.1.0",
+    "ts-poet": "^6.2.0",
     "ts-proto-descriptors": "1.7.1"
-  }
+  },
+  "packageManager": "yarn@3.3.0"
 }