ts-proto 1.169.1 → 1.171.0

package/README.markdown

@@ -547,6 +547,58 @@ Generated code will be placed in the Gradle build directory.
 
 - With `--ts_proto_opt=comments=false`, comments won't be copied from the proto files to the generated code.
 
+- With `--ts_proto_opt=useNullAsOptional=true`, `undefined` values will be converted to `null`, and if you use `optional` label in your `.proto` file, the field will have `undefined` type as well. for example:
+
+```protobuf
+message ProfileInfo {
+    int32 id = 1;
+    string bio = 2;
+    string phone = 3;
+}
+
+message Department {
+    int32 id = 1;
+    string name = 2;
+}
+
+message User {
+    int32 id = 1;
+    string username = 2;
+    /*
+     ProfileInfo will be optional in typescript, the type will be ProfileInfo | null | undefined
+     this is needed in cases where you don't wanna provide any value for the profile.
+    */
+    optional ProfileInfo profile = 3;
+
+    /*
+      Department only accepts a Department type or null, so this means you have to pass it null if there is no value available.
+    */
+    Department  department = 4;
+}
+```
+
+the generated interfaces will be:
+
+```typescript
+export interface ProfileInfo {
+  id: number;
+  bio: string;
+  phone: string;
+}
+
+export interface Department {
+  id: number;
+  name: string;
+}
+
+export interface User {
+  id: number;
+  username: string;
+  profile?: ProfileInfo | null | undefined; // check this one
+  department: Department | null; // check this one
+}
+```
+
 ### NestJS Support
 
 We have a great way of working together with [nestjs](https://docs.nestjs.com/microservices/grpc). `ts-proto` generates `interfaces` and `decorators` for you controller, client. For more information see the [nestjs readme](NESTJS.markdown).
@@ -724,6 +776,28 @@ As this will automatically enforce only one of `field_a` or `field_b` "being set
 
 In ts-proto's currently-unscheduled 2.x release, `oneof=unions` will become the default behavior.
 
+## OneOf Type Helpers
+
+The following helper types may make it easier to work with the types generated from `oneof=unions`:
+
+```ts
+/** Extracts all the case names from a oneOf field. */
+type OneOfCases<T> = T extends { $case: infer U extends string } ? U : never;
+
+/** Extracts a union of all the value types from a oneOf field */
+type OneOfValues<T> = T extends { $case: infer U extends string; [key: string]: unknown }
+  ? T[U]
+  : never;
+
+/** Extracts the specific type of a oneOf case based on its field name */
+type OneOfCase<T, K extends OneOfCases<T>> = T extends {
+  $case: infer U extends K;
+  [key: string]: unknown;
+}
+  ? T[U]
+  : never;
+```
+
 # Default values and unset fields
 
 In core Protobuf (and so also `ts-proto`), values that are _unset_ or equal to the default value are not sent over the wire.

package/build/main.js

@@ -715,7 +715,7 @@ function generateOneofProperty(ctx, messageDesc, oneofIndex, sourceInfo) {
         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) `${mbReadonly}${name}?: ${unionType} | undefined,`;
+    return (0, ts_poet_1.code) `${mbReadonly}${name}?: ${unionType} | ${(0, utils_1.nullOrUndefined)(options)},`;
     /*
     // 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
@@ -751,7 +751,7 @@ function generateBaseInstanceFactory(ctx, fullName, messageDesc, fullTypeName) {
                 const name = options.useJsonName
                     ? (0, utils_1.getFieldName)(field, options)
                     : (0, case_1.maybeSnakeToCamel)(messageDesc.oneofDecl[oneofIndex].name, ctx.options);
-                fields.push((0, ts_poet_1.code) `${(0, utils_1.safeAccessor)(name)}: undefined`);
+                fields.push((0, ts_poet_1.code) `${(0, utils_1.safeAccessor)(name)}: ${(0, utils_1.nullOrUndefined)(options)}`);
             }
             continue;
         }
@@ -761,7 +761,7 @@ function generateBaseInstanceFactory(ctx, fullName, messageDesc, fullTypeName) {
         }
         const fieldKey = (0, utils_1.safeAccessor)((0, utils_1.getFieldName)(field, options));
         const val = (0, types_1.isWithinOneOf)(field)
-            ? "undefined"
+            ? (0, utils_1.nullOrUndefined)(options)
             : (0, types_1.isMapType)(ctx, messageDesc, field)
                 ? (0, types_1.shouldGenerateJSMapType)(ctx, messageDesc, field)
                     ? "new Map()"
@@ -895,7 +895,7 @@ function generateDecode(ctx, fullName, messageDesc) {
         const initializerNecessary = !options.initializeFieldsAsUndefined &&
             (0, types_1.isOptionalProperty)(field, messageDesc.options, options, currentFile.isProto3Syntax);
         if ((0, types_1.isRepeated)(field)) {
-            const maybeNonNullAssertion = ctx.options.useOptionals === "all" ? "!" : "";
+            const maybeNonNullAssertion = ctx.options.useOptionals === "all" || ctx.options.useOptionals === "deprecatedOnly" ? "!" : "";
             const mapType = (0, types_1.detectMapType)(ctx, messageDesc, field);
             if (mapType) {
                 // We need a unique const within the `cast` statement
@@ -910,14 +910,14 @@ function generateDecode(ctx, fullName, messageDesc) {
                 }
                 const initializerSnippet = initializerNecessary
                     ? `
-            if (${messageProperty} === undefined) {
+            if (${messageProperty} === undefined ${(0, utils_1.withOrMaybeCheckIsNull)(options, messageProperty)}) {
               ${messageProperty} = ${generateMapType ? "new Map()" : "{}"};
             }`
                     : "";
                 chunks.push((0, ts_poet_1.code) `
           ${tagCheck}
           const ${varName} = ${readSnippet};
-          if (${varName}.value !== undefined) {
+          if (${varName}.value !== undefined ${(0, utils_1.withAndMaybeCheckIsNotNull)(options, `${varName}.value`)}) {
             ${initializerSnippet}
             ${valueSetterSnippet};
           }
@@ -926,7 +926,7 @@ function generateDecode(ctx, fullName, messageDesc) {
             else {
                 const initializerSnippet = initializerNecessary
                     ? `
-            if (${messageProperty} === undefined) {
+            if (${messageProperty} === undefined ${(0, utils_1.withOrMaybeCheckIsNull)(options, messageProperty)}) {
               ${messageProperty} = [];
             }`
                     : "";
@@ -992,7 +992,7 @@ function generateDecode(ctx, fullName, messageDesc) {
         let maybeNonNullAssertion = options.initializeFieldsAsUndefined ? "!" : "";
         if (!options.initializeFieldsAsUndefined) {
             unknownFieldsInitializerSnippet = `
-        if (message._unknownFields === undefined) {
+        if (message._unknownFields === undefined ${(0, utils_1.withOrMaybeCheckIsNull)(options, `message._unknownFields`)}) {
           message._unknownFields = {};
         }
       `;
@@ -1005,7 +1005,7 @@ function generateDecode(ctx, fullName, messageDesc) {
       ${unknownFieldsInitializerSnippet}
       const list = message._unknownFields${maybeNonNullAssertion}[tag];
 
-      if (list === undefined) {
+      if (list === undefined ${(0, utils_1.withOrMaybeCheckIsNull)(options, `message._unknownFields`)}) {
         message._unknownFields${maybeNonNullAssertion}[tag] = [buf];
       } else {
         list.push(buf);
@@ -1123,7 +1123,7 @@ function generateEncode(ctx, fullName, messageDesc) {
                 const maybeTypeField = (0, options_1.addTypeToMessages)(options) ? `$type: '${field.typeName.slice(1)}',` : "";
                 const entryWriteSnippet = (0, types_1.isValueType)(ctx, valueType)
                     ? (0, ts_poet_1.code) `
-              if (value !== undefined) {
+              if (value !== undefined ${(0, utils_1.withOrMaybeCheckIsNotNull)(options, `value`)}) {
                 ${writeSnippet(`{ ${maybeTypeField} key: key as any, value }`)};
               }
             `
@@ -1234,7 +1234,7 @@ function generateEncode(ctx, fullName, messageDesc) {
                 }
                 if (isOptional) {
                     chunks.push((0, ts_poet_1.code) `
-            if (${messageProperty} !== undefined && ${messageProperty}.length !== 0) {
+            if (${messageProperty} !== undefined ${(0, utils_1.withAndMaybeCheckIsNotNull)(options, messageProperty)} && ${messageProperty}.length !== 0) {
               ${listWriteSnippet}
             }
           `);
@@ -1264,14 +1264,14 @@ function generateEncode(ctx, fullName, messageDesc) {
         else if ((0, types_1.isWithinOneOf)(field)) {
             // Oneofs don't have a default value check b/c they need to denote which-oneof presence
             chunks.push((0, ts_poet_1.code) `
-        if (${messageProperty} !== undefined) {
+        if (${messageProperty} !== undefined ${(0, utils_1.withAndMaybeCheckIsNotNull)(options, messageProperty)}) {
           ${writeSnippet(`${messageProperty}`)};
         }
       `);
         }
         else if ((0, types_1.isMessage)(field)) {
             chunks.push((0, ts_poet_1.code) `
-        if (${messageProperty} !== undefined) {
+        if (${messageProperty} !== undefined ${(0, utils_1.withAndMaybeCheckIsNotNull)(options, messageProperty)}) {
           ${writeSnippet(`${messageProperty}`)};
         }
       `);
@@ -1697,7 +1697,7 @@ function generateFromJson(ctx, fullName, fullTypeName, messageDesc) {
                 const fieldType = (0, types_1.toTypeName)(ctx, messageDesc, field);
                 const i = convertFromObjectKey(ctx, messageDesc, field, "key");
                 if ((0, types_1.shouldGenerateJSMapType)(ctx, messageDesc, field)) {
-                    const fallback = noDefaultValue ? "undefined" : "new Map()";
+                    const fallback = noDefaultValue ? (0, utils_1.nullOrUndefined)(options) : "new Map()";
                     chunks.push((0, ts_poet_1.code) `
             ${fieldKey}: ${ctx.utils.isObject}(${jsonProperty})
               ? Object.entries(${jsonProperty}).reduce<${fieldType}>((acc, [key, value]) => {
@@ -1708,7 +1708,7 @@ function generateFromJson(ctx, fullName, fullTypeName, messageDesc) {
           `);
                 }
                 else {
-                    const fallback = noDefaultValue ? "undefined" : "{}";
+                    const fallback = noDefaultValue ? (0, utils_1.nullOrUndefined)(options) : "{}";
                     chunks.push((0, ts_poet_1.code) `
             ${fieldKey}: ${ctx.utils.isObject}(${jsonProperty})
               ? Object.entries(${jsonProperty}).reduce<${fieldType}>((acc, [key, value]) => {
@@ -1720,7 +1720,7 @@ function generateFromJson(ctx, fullName, fullTypeName, messageDesc) {
                 }
             }
             else {
-                const fallback = noDefaultValue ? "undefined" : "[]";
+                const fallback = noDefaultValue ? (0, utils_1.nullOrUndefined)(options) : "[]";
                 const readValueSnippet = readSnippet("e");
                 if (readValueSnippet.toString() === (0, ts_poet_1.code) `e`.toString()) {
                     chunks.push((0, ts_poet_1.code) `${fieldKey}: ${ctx.utils.globalThis}.Array.isArray(${jsonPropertyOptional}) ? [...${jsonProperty}] : [],`);
@@ -1745,29 +1745,29 @@ function generateFromJson(ctx, fullName, fullTypeName, messageDesc) {
             const ternaryThen = (0, ts_poet_1.code) `{ $case: '${fieldName}', ${fieldKey}: ${readSnippet(`${jsonProperty}`)}`;
             chunks.push((0, ts_poet_1.code) `${ternaryIf} ? ${ternaryThen}} : `);
             if (field === lastCase) {
-                chunks.push((0, ts_poet_1.code) `undefined,`);
+                chunks.push((0, ts_poet_1.code) `${(0, utils_1.nullOrUndefined)(options)},`);
             }
         }
         else if ((0, types_1.isAnyValueType)(field)) {
             chunks.push((0, ts_poet_1.code) `${fieldKey}: ${ctx.utils.isSet}(${jsonPropertyOptional})
         ? ${readSnippet(`${jsonProperty}`)}
-        : undefined,
+        : ${(0, utils_1.nullOrUndefined)(options)},
       `);
         }
         else if ((0, types_1.isStructType)(field)) {
             chunks.push((0, ts_poet_1.code) `${fieldKey}: ${ctx.utils.isObject}(${jsonProperty})
           ? ${readSnippet(`${jsonProperty}`)}
-          : undefined,`);
+          : ${(0, utils_1.nullOrUndefined)(options)},`);
         }
         else if ((0, types_1.isListValueType)(field)) {
             chunks.push((0, ts_poet_1.code) `
         ${fieldKey}: ${ctx.utils.globalThis}.Array.isArray(${jsonProperty})
           ? ${readSnippet(`${jsonProperty}`)}
-          : undefined,
+          : ${(0, utils_1.nullOrUndefined)(options)},
       `);
         }
         else {
-            const fallback = (0, types_1.isWithinOneOf)(field) || noDefaultValue ? "undefined" : (0, types_1.defaultValue)(ctx, field);
+            const fallback = (0, types_1.isWithinOneOf)(field) || noDefaultValue ? (0, utils_1.nullOrUndefined)(options) : (0, types_1.defaultValue)(ctx, field);
             chunks.push((0, ts_poet_1.code) `
         ${fieldKey}: ${ctx.utils.isSet}(${jsonProperty})
           ? ${readSnippet(`${jsonProperty}`)}
@@ -1780,9 +1780,9 @@ function generateFromJson(ctx, fullName, fullTypeName, messageDesc) {
     chunks.push((0, ts_poet_1.code) `}`);
     return (0, ts_poet_1.joinCode)(chunks, { on: "\n" });
 }
-function generateCanonicalToJson(fullName, fullProtobufTypeName, { useOptionals }) {
+function generateCanonicalToJson(fullName, fullProtobufTypeName, { useOptionals, useNullAsOptional }) {
     if ((0, types_1.isFieldMaskTypeName)(fullProtobufTypeName)) {
-        const returnType = useOptionals === "all" ? "string | undefined" : "string";
+        const returnType = useOptionals === "all" ? `string | ${(0, utils_1.nullOrUndefined)({ useNullAsOptional })}` : "string";
         const pathModifier = useOptionals === "all" ? "?" : "";
         return (0, ts_poet_1.code) `
     toJSON(message: ${fullName}): ${returnType} {
@@ -1954,7 +1954,7 @@ function generateToJson(ctx, fullName, fullProtobufTypeName, messageDesc) {
             let emitDefaultValuesForJson = ctx.options.emitDefaultValues.includes("json-methods");
             const check = ((0, types_1.isScalar)(field) || (0, types_1.isEnum)(field)) && !((0, types_1.isWithinOneOf)(field) || emitDefaultValuesForJson)
                 ? (0, types_1.notDefaultCheck)(ctx, field, messageDesc.options, `${messageProperty}`)
-                : `${messageProperty} !== undefined`;
+                : `${messageProperty} !== undefined ${(0, utils_1.withAndMaybeCheckIsNotNull)(options, messageProperty)}`;
             chunks.push((0, ts_poet_1.code) `
         if (${check}) {
           ${jsonProperty} = ${readSnippet(`${messageProperty}`)};

package/build/options.js

@@ -100,6 +100,7 @@ function defaultOptions() {
         comments: true,
         disableProto2Optionals: false,
         disableProto2DefaultValues: false,
+        useNullAsOptional: false,
     };
 }
 exports.defaultOptions = defaultOptions;

package/build/types.js

@@ -235,7 +235,7 @@ function defaultValue(ctx, field) {
         case ts_proto_descriptors_1.FieldDescriptorProto_Type.TYPE_MESSAGE:
         case ts_proto_descriptors_1.FieldDescriptorProto_Type.TYPE_GROUP:
         default:
-            return "undefined";
+            return (0, utils_1.nullOrUndefined)(options);
     }
 }
 exports.defaultValue = defaultValue;
@@ -243,7 +243,9 @@ exports.defaultValue = defaultValue;
 function notDefaultCheck(ctx, field, messageOptions, place) {
     const { typeMap, options, currentFile } = ctx;
     const isOptional = isOptionalProperty(field, messageOptions, options, currentFile.isProto3Syntax);
-    const maybeNotUndefinedAnd = isOptional ? `${place} !== undefined && ` : "";
+    const maybeNotUndefinedAnd = isOptional
+        ? `${place} !== undefined ${(0, utils_1.withAndMaybeCheckIsNotNull)(options, place)} &&`
+        : "";
     switch (field.type) {
         case ts_proto_descriptors_1.FieldDescriptorProto_Type.TYPE_DOUBLE:
         case ts_proto_descriptors_1.FieldDescriptorProto_Type.TYPE_FLOAT:
@@ -330,15 +332,20 @@ function isScalar(field) {
 }
 exports.isScalar = isScalar;
 // When useOptionals='messages', non-scalar fields are translated into optional
-// properties. When useOptionals='all', all fields are translated into
+// properties.
+// When useOptionals='all', all fields are translated into
+// optional properties, with the exception of map Entry key/values, which must
+// always be present.
+// When useOptionals='deprecatedOnly', all deprecated fields are translated into
 // optional properties, with the exception of map Entry key/values, which must
 // always be present.
 // OneOf fields are always optional, whenever oneof=unions option not in use.
 function isOptionalProperty(field, messageOptions, options, isProto3Syntax) {
     const optionalMessages = options.useOptionals === true || options.useOptionals === "messages" || options.useOptionals === "all";
     const optionalAll = options.useOptionals === "all";
+    const deprecatedOnly = options.useOptionals === "deprecatedOnly" && field.options && field.options.deprecated;
     return ((optionalMessages && isMessage(field) && !isRepeated(field)) ||
-        (optionalAll && !(messageOptions === null || messageOptions === void 0 ? void 0 : messageOptions.mapEntry)) ||
+        ((optionalAll || deprecatedOnly) && !(messageOptions === null || messageOptions === void 0 ? void 0 : messageOptions.mapEntry)) ||
         // file is proto2, we have enabled proto2 optionals, and the field itself is optional
         (!isProto3Syntax &&
             field.label === ts_proto_descriptors_1.FieldDescriptorProto_Label.LABEL_OPTIONAL &&
@@ -547,7 +554,7 @@ function messageToTypeName(ctx, protoType, typeOptions = {}) {
         if ((_a = typeOptions.repeated) !== null && _a !== void 0 ? _a : false) {
             return valueType;
         }
-        return (0, ts_poet_1.code) `${valueType} | undefined`;
+        return (0, ts_poet_1.code) `${valueType} | ${(0, utils_1.nullOrUndefined)(options)}`;
     }
     // Look for other special prototypes like Timestamp that aren't technically wrapper types
     if (!typeOptions.keepValueType && protoType === ".google.protobuf.Timestamp") {
@@ -579,7 +586,7 @@ exports.getEnumMethod = getEnumMethod;
 function toTypeName(ctx, messageDesc, field, ensureOptional = false) {
     function finalize(type, isOptional) {
         if (isOptional) {
-            return (0, ts_poet_1.code) `${type} | undefined`;
+            return (0, ts_poet_1.code) `${type} | ${(0, utils_1.nullOrUndefined)(ctx.options, field.proto3Optional)}`;
         }
         return type;
     }

package/build/utils.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.arrowFunction = exports.tryCatchBlock = exports.impProto = exports.impFile = exports.getPropertyAccessor = exports.safeAccessor = exports.getFieldName = exports.getFieldJsonName = exports.FormattedMethodDescriptor = exports.assertInstanceOf = exports.maybePrefixPackage = exports.prefixDisableLinter = exports.maybeAddComment = exports.upperFirst = exports.lowerFirst = exports.singular = exports.fail = exports.readToBuffer = exports.generateIndexFiles = exports.protoFilesToGenerate = void 0;
+exports.withAndMaybeCheckIsNull = exports.withAndMaybeCheckIsNotNull = exports.withOrMaybeCheckIsNull = exports.withOrMaybeCheckIsNotNull = exports.maybeCheckIsNull = exports.maybeCheckIsNotNull = exports.nullOrUndefined = exports.arrowFunction = exports.tryCatchBlock = exports.impProto = exports.impFile = exports.getPropertyAccessor = exports.safeAccessor = exports.getFieldName = exports.getFieldJsonName = exports.FormattedMethodDescriptor = exports.assertInstanceOf = exports.maybePrefixPackage = exports.prefixDisableLinter = exports.maybeAddComment = exports.upperFirst = exports.lowerFirst = exports.singular = exports.fail = exports.readToBuffer = exports.generateIndexFiles = exports.protoFilesToGenerate = void 0;
 const path = require("path");
 const ts_poet_1 = require("ts-poet");
 const options_1 = require("./options");
@@ -261,3 +261,31 @@ function arrowFunction(params, body, isOneLine = true) {
     return (0, ts_poet_1.code) `(${params}) => { ${body} }`;
 }
 exports.arrowFunction = arrowFunction;
+function nullOrUndefined(options, hasProto3Optional = false) {
+    return options.useNullAsOptional ? `null ${hasProto3Optional ? "| undefined" : ""}` : "undefined";
+}
+exports.nullOrUndefined = nullOrUndefined;
+function maybeCheckIsNotNull(options, typeName, prefix) {
+    return options.useNullAsOptional ? ` ${prefix} ${typeName} !== null` : "";
+}
+exports.maybeCheckIsNotNull = maybeCheckIsNotNull;
+function maybeCheckIsNull(options, typeName, prefix) {
+    return options.useNullAsOptional ? ` ${prefix} ${typeName} === null` : "";
+}
+exports.maybeCheckIsNull = maybeCheckIsNull;
+function withOrMaybeCheckIsNotNull(options, typeName) {
+    return maybeCheckIsNotNull(options, typeName, "||");
+}
+exports.withOrMaybeCheckIsNotNull = withOrMaybeCheckIsNotNull;
+function withOrMaybeCheckIsNull(options, typeName) {
+    return maybeCheckIsNull(options, typeName, "||");
+}
+exports.withOrMaybeCheckIsNull = withOrMaybeCheckIsNull;
+function withAndMaybeCheckIsNotNull(options, typeName) {
+    return maybeCheckIsNotNull(options, typeName, "&&");
+}
+exports.withAndMaybeCheckIsNotNull = withAndMaybeCheckIsNotNull;
+function withAndMaybeCheckIsNull(options, typeName) {
+    return maybeCheckIsNotNull(options, typeName, "&&");
+}
+exports.withAndMaybeCheckIsNull = withAndMaybeCheckIsNull;

package/package.json

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