protobufjs 6.11.2 → 7.1.0

package/README.md

@@ -27,14 +27,6 @@ Contents
   * [Using services](#using-services)
   * [Usage with TypeScript](#usage-with-typescript)<br />
 
-* [Command line](#command-line)<br />
-  How to use the command line utility.
-
-  * [pbjs for JavaScript](#pbjs-for-javascript)
-  * [pbts for TypeScript](#pbts-for-typescript)
-  * [Reflection vs. static code](#reflection-vs-static-code)
-  * [Command line API](#command-line-api)<br />
-
 * [Additional documentation](#additional-documentation)<br />
   A list of available documentation resources.
 
@@ -60,6 +52,12 @@ $> npm install protobufjs [--save --save-prefix=~]
 var protobuf = require("protobufjs");
 ```
 
+The command line utility lives in the protobufjs-cli package and must be installed separately:
+
+```
+$> npm install protobufjs-cli [--save --save-prefix=~]
+```
+
 **Note** that this library's versioning scheme is not semver-compatible for historical reasons. For guaranteed backward compatibility, always depend on `~6.A.B` instead of `^6.A.B` (hence the `--save-prefix` above).
 
 ### Browsers
@@ -84,7 +82,7 @@ The library supports CommonJS and AMD loaders and also exports globally as `prot
 
 Where bundle size is a factor, there are additional stripped-down versions of the [full library][dist-full] (~19kb gzipped) available that exclude certain functionality:
 
-* When working with JSON descriptors (i.e. generated by [pbjs](#pbjs-for-javascript)) and/or reflection only, see the [light library][dist-light] (~16kb gzipped) that excludes the parser. CommonJS entry point is:
+* When working with JSON descriptors (i.e. generated by [pbjs](cli/README.md#pbjs-for-javascript)) and/or reflection only, see the [light library][dist-light] (~16kb gzipped) that excludes the parser. CommonJS entry point is:
 
   ```js
   var protobuf = require("protobufjs/light");
@@ -597,171 +595,6 @@ Other notes:
 
 **ProTip!** Not as pretty, but you can [use decorators in plain JavaScript](https://github.com/dcodeIO/protobuf.js/blob/master/examples/js-decorators.js) as well.
 
-Command line
-------------
-
-**Note** that moving the CLI to [its own package](./cli) is a work in progress. At the moment, it's still part of the main package.
-
-The command line interface (CLI) can be used to translate between file formats and to generate static code as well as TypeScript definitions.
-
-### pbjs for JavaScript
-
-```
-Translates between file formats and generates static code.
-
-  -t, --target     Specifies the target format. Also accepts a path to require a custom target.
-
-                   json          JSON representation
-                   json-module   JSON representation as a module
-                   proto2        Protocol Buffers, Version 2
-                   proto3        Protocol Buffers, Version 3
-                   static        Static code without reflection (non-functional on its own)
-                   static-module Static code without reflection as a module
-
-  -p, --path       Adds a directory to the include path.
-
-  -o, --out        Saves to a file instead of writing to stdout.
-
-  --sparse         Exports only those types referenced from a main file (experimental).
-
-  Module targets only:
-
-  -w, --wrap       Specifies the wrapper to use. Also accepts a path to require a custom wrapper.
-
-                   default   Default wrapper supporting both CommonJS and AMD
-                   commonjs  CommonJS wrapper
-                   amd       AMD wrapper
-                   es6       ES6 wrapper (implies --es6)
-                   closure   A closure adding to protobuf.roots where protobuf is a global
-
-  -r, --root       Specifies an alternative protobuf.roots name.
-
-  -l, --lint       Linter configuration. Defaults to protobuf.js-compatible rules:
-
-                   eslint-disable block-scoped-var, no-redeclare, no-control-regex, no-prototype-builtins
-
-  --es6            Enables ES6 syntax (const/let instead of var)
-
-  Proto sources only:
-
-  --keep-case      Keeps field casing instead of converting to camel case.
-
-  Static targets only:
-
-  --no-create      Does not generate create functions used for reflection compatibility.
-  --no-encode      Does not generate encode functions.
-  --no-decode      Does not generate decode functions.
-  --no-verify      Does not generate verify functions.
-  --no-convert     Does not generate convert functions like from/toObject
-  --no-delimited   Does not generate delimited encode/decode functions.
-  --no-beautify    Does not beautify generated code.
-  --no-comments    Does not output any JSDoc comments.
-
-  --force-long     Enforces the use of 'Long' for s-/u-/int64 and s-/fixed64 fields.
-  --force-number   Enforces the use of 'number' for s-/u-/int64 and s-/fixed64 fields.
-  --force-message  Enforces the use of message instances instead of plain objects.
-
-usage: pbjs [options] file1.proto file2.json ...  (or pipe)  other | pbjs [options] -
-```
-
-For production environments it is recommended to bundle all your .proto files to a single .json file, which minimizes the number of network requests and avoids any parser overhead (hint: works with just the **light** library):
-
-```
-$> pbjs -t json file1.proto file2.proto > bundle.json
-```
-
-Now, either include this file in your final bundle:
-
-```js
-var root = protobuf.Root.fromJSON(require("./bundle.json"));
-```
-
-or load it the usual way:
-
-```js
-protobuf.load("bundle.json", function(err, root) {
-    ...
-});
-```
-
-Generated static code, on the other hand, works with just the **minimal** library. For example
-
-```
-$> pbjs -t static-module -w commonjs -o compiled.js file1.proto file2.proto
-```
-
-will generate static code for definitions within `file1.proto` and `file2.proto` to a CommonJS module `compiled.js`.
-
-**ProTip!** Documenting your .proto files with `/** ... */`-blocks or (trailing) `/// ...` lines translates to generated static code.
-
-
-### pbts for TypeScript
-
-```
-Generates TypeScript definitions from annotated JavaScript files.
-
-  -o, --out       Saves to a file instead of writing to stdout.
-
-  -g, --global    Name of the global object in browser environments, if any.
-
-  --no-comments   Does not output any JSDoc comments.
-
-  Internal flags:
-
-  -n, --name      Wraps everything in a module of the specified name.
-
-  -m, --main      Whether building the main library without any imports.
-
-usage: pbts [options] file1.js file2.js ...  (or)  other | pbts [options] -
-```
-
-Picking up on the example above, the following not only generates static code to a CommonJS module `compiled.js` but also its respective TypeScript definitions to `compiled.d.ts`:
-
-```
-$> pbjs -t static-module -w commonjs -o compiled.js file1.proto file2.proto
-$> pbts -o compiled.d.ts compiled.js
-```
-
-Additionally, TypeScript definitions of static modules are compatible with their reflection-based counterparts (i.e. as exported by JSON modules), as long as the following conditions are met:
-
-1. Instead of using `new SomeMessage(...)`, always use `SomeMessage.create(...)` because reflection objects do not provide a constructor.
-2. Types, services and enums must start with an uppercase letter to become available as properties of the reflected types as well (i.e. to be able to use `MyMessage.MyEnum` instead of `root.lookup("MyMessage.MyEnum")`).
-
-For example, the following generates a JSON module `bundle.js` and a `bundle.d.ts`, but no static code:
-
-```
-$> pbjs -t json-module -w commonjs -o bundle.js file1.proto file2.proto
-$> pbjs -t static-module file1.proto file2.proto | pbts -o bundle.d.ts -
-```
-
-### Reflection vs. static code
-
-While using .proto files directly requires the full library respectively pure reflection/JSON the light library, pretty much all code but the relatively short descriptors is shared.
-
-Static code, on the other hand, requires just the minimal library, but generates additional source code without any reflection features. This also implies that there is a break-even point where statically generated code becomes larger than descriptor-based code once the amount of code generated exceeds the size of the full respectively light library.
-
-There is no significant difference performance-wise as the code generated statically is pretty much the same as generated at runtime and both are largely interchangeable as seen in the previous section.
-
-| Source | Library | Advantages | Tradeoffs
-|--------|---------|------------|-----------
-| .proto | full    | Easily editable<br />Interoperability with other libraries<br />No compile step | Some parsing and possibly network overhead
-| JSON   | light   | Easily editable<br />No parsing overhead<br />Single bundle (no network overhead) | protobuf.js specific<br />Has a compile step
-| static | minimal | Works where `eval` access is restricted<br />Fully documented<br />Small footprint for small protos | Can be hard to edit<br />No reflection<br />Has a compile step
-
-### Command line API
-
-Both utilities can be used programmatically by providing command line arguments and a callback to their respective `main` functions:
-
-```js
-var pbjs = require("protobufjs/cli/pbjs"); // or require("protobufjs/cli").pbjs / .pbts
-
-pbjs.main([ "--target", "json-module", "path/to/myproto.proto" ], function(err, output) {
-    if (err)
-        throw err;
-    // do something with output
-});
-```
-
 Additional documentation
 ------------------------
 

package/dist/light/protobuf.js

@@ -1,6 +1,6 @@
 /*!
- * protobuf.js v6.11.0 (c) 2016, daniel wirtz
- * compiled thu, 29 apr 2021 02:20:44 utc
+ * protobuf.js v7.1.0 (c) 2016, daniel wirtz
+ * compiled fri, 26 aug 2022 21:49:00 utc
  * licensed under the bsd-3-clause license
  * see: https://github.com/dcodeio/protobuf.js for details
  */
@@ -1134,8 +1134,14 @@ function genValuePartial_fromObject(gen, field, fieldIndex, prop) {
         if (field.resolvedType instanceof Enum) { gen
             ("switch(d%s){", prop);
             for (var values = field.resolvedType.values, keys = Object.keys(values), i = 0; i < keys.length; ++i) {
-                if (field.repeated && values[keys[i]] === field.typeDefault) gen
-                ("default:");
+                // enum unknown values passthrough
+                if (values[keys[i]] === field.typeDefault) { gen
+                    ("default:")
+                        ("if(typeof(d%s)===\"number\"){m%s=d%s;break}", prop, prop, prop);
+                    if (!field.repeated) gen // fallback to default value only for
+                                             // arrays, to avoid leaving holes.
+                        ("break");           // for non-repeated fields, just ignore
+                }
                 gen
                 ("case%j:", keys[i])
                 ("case %i:", values[keys[i]])
@@ -1182,7 +1188,7 @@ function genValuePartial_fromObject(gen, field, fieldIndex, prop) {
             case "bytes": gen
                 ("if(typeof d%s===\"string\")", prop)
                     ("util.base64.decode(d%s,m%s=util.newBuffer(util.base64.length(d%s)),0)", prop, prop, prop)
-                ("else if(d%s.length)", prop)
+                ("else if(d%s.length >= 0)", prop)
                     ("m%s=d%s", prop, prop);
                 break;
             case "string": gen
@@ -1267,7 +1273,7 @@ function genValuePartial_toObject(gen, field, fieldIndex, prop) {
     /* eslint-disable no-unexpected-multiline, block-scoped-var, no-redeclare */
     if (field.resolvedType) {
         if (field.resolvedType instanceof Enum) gen
-            ("d%s=o.enums===String?types[%i].values[m%s]:m%s", prop, fieldIndex, prop, prop);
+            ("d%s=o.enums===String?(types[%i].values[m%s]===undefined?m%s:types[%i].values[m%s]):m%s", prop, fieldIndex, prop, prop, fieldIndex, prop, prop);
         else gen
             ("d%s=types[%i].toObject(m%s,o)", prop, fieldIndex, prop);
     } else {
@@ -1439,7 +1445,7 @@ function decoder(mtype) {
         var field = mtype._fieldsArray[i].resolve(),
             type  = field.resolvedType instanceof Enum ? "int32" : field.type,
             ref   = "m" + util.safeProp(field.name); gen
-            ("case %i:", field.id);
+            ("case %i: {", field.id);
 
         // Map fields
         if (field.map) { gen
@@ -1510,8 +1516,9 @@ function decoder(mtype) {
         else gen
                 ("%s=r.%s()", ref, type);
         gen
-                ("break");
-    // Unknown fields
+                ("break")
+            ("}");
+        // Unknown fields
     } gen
             ("default:")
                 ("r.skipType(t&7)")
@@ -1656,8 +1663,9 @@ var Namespace = require(21),
  * @param {Object.<string,*>} [options] Declared options
  * @param {string} [comment] The comment for this enum
  * @param {Object.<string,string>} [comments] The value comments for this enum
+ * @param {Object.<string,Object<string,*>>|undefined} [valuesOptions] The value options for this enum
  */
-function Enum(name, values, options, comment, comments) {
+function Enum(name, values, options, comment, comments, valuesOptions) {
     ReflectionObject.call(this, name, options);
 
     if (values && typeof values !== "object")
@@ -1687,6 +1695,12 @@ function Enum(name, values, options, comment, comments) {
      */
     this.comments = comments || {};
 
+    /**
+     * Values options, if any
+     * @type {Object<string, Object<string, *>>|undefined}
+     */
+    this.valuesOptions = valuesOptions;
+
     /**
      * Reserved ranges, if any.
      * @type {Array.<number[]|string>}
@@ -1731,11 +1745,12 @@ Enum.fromJSON = function fromJSON(name, json) {
 Enum.prototype.toJSON = function toJSON(toJSONOptions) {
     var keepComments = toJSONOptions ? Boolean(toJSONOptions.keepComments) : false;
     return util.toObject([
-        "options"  , this.options,
-        "values"   , this.values,
-        "reserved" , this.reserved && this.reserved.length ? this.reserved : undefined,
-        "comment"  , keepComments ? this.comment : undefined,
-        "comments" , keepComments ? this.comments : undefined
+        "options"       , this.options,
+        "valuesOptions" , this.valuesOptions,
+        "values"        , this.values,
+        "reserved"      , this.reserved && this.reserved.length ? this.reserved : undefined,
+        "comment"       , keepComments ? this.comment : undefined,
+        "comments"      , keepComments ? this.comments : undefined
     ]);
 };
 
@@ -1744,11 +1759,12 @@ Enum.prototype.toJSON = function toJSON(toJSONOptions) {
  * @param {string} name Value name
  * @param {number} id Value id
  * @param {string} [comment] Comment, if any
+ * @param {Object.<string, *>|undefined} [options] Options, if any
  * @returns {Enum} `this`
  * @throws {TypeError} If arguments are invalid
  * @throws {Error} If there is already a value with this name or id
  */
-Enum.prototype.add = function add(name, id, comment) {
+Enum.prototype.add = function add(name, id, comment, options) {
     // utilized by the parser but not by .fromJSON
 
     if (!util.isString(name))
@@ -1773,6 +1789,12 @@ Enum.prototype.add = function add(name, id, comment) {
     } else
         this.valuesById[this.values[name] = id] = name;
 
+    if (options) {
+        if (this.valuesOptions === undefined)
+            this.valuesOptions = {};
+        this.valuesOptions[name] = options || null;
+    }
+
     this.comments[name] = comment || null;
     return this;
 };
@@ -1796,6 +1818,8 @@ Enum.prototype.remove = function remove(name) {
     delete this.valuesById[val];
     delete this.values[name];
     delete this.comments[name];
+    if (this.valuesOptions)
+        delete this.valuesOptions[name];
 
     return this;
 };
@@ -2091,6 +2115,9 @@ Field.prototype.resolve = function resolve() {
             this.typeDefault = null;
         else // instanceof Enum
             this.typeDefault = this.resolvedType.values[Object.keys(this.resolvedType.values)[0]]; // first defined
+    } else if (this.options && this.options.proto3_optional) {
+        // proto3 scalar value marked optional; should default to null
+        this.typeDefault = null;
     }
 
     // use explicitly set default value if present
@@ -2777,7 +2804,8 @@ var ReflectionObject = require(22);
 ((Namespace.prototype = Object.create(ReflectionObject.prototype)).constructor = Namespace).className = "Namespace";
 
 var Field    = require(15),
-    util     = require(33);
+    util     = require(33),
+    OneOf    = require(23);
 
 var Type,    // cyclic
     Service,
@@ -2988,7 +3016,7 @@ Namespace.prototype.getEnum = function getEnum(name) {
  */
 Namespace.prototype.add = function add(object) {
 
-    if (!(object instanceof Field && object.extend !== undefined || object instanceof Type || object instanceof Enum || object instanceof Service || object instanceof Namespace))
+    if (!(object instanceof Field && object.extend !== undefined || object instanceof Type  || object instanceof OneOf || object instanceof Enum || object instanceof Service || object instanceof Namespace))
         throw TypeError("object must be a valid nested object");
 
     if (!this.nested)
@@ -3203,7 +3231,7 @@ Namespace._configure = function(Type_, Service_, Enum_) {
     Enum    = Enum_;
 };
 
-},{"15":15,"22":22,"33":33}],22:[function(require,module,exports){
+},{"15":15,"22":22,"23":23,"33":33}],22:[function(require,module,exports){
 "use strict";
 module.exports = ReflectionObject;
 
@@ -4491,7 +4519,7 @@ module.exports = {};
 /**
  * Named roots.
  * This is where pbjs stores generated structures (the option `-r, --root` specifies a name).
- * Can also be used manually to make roots available accross modules.
+ * Can also be used manually to make roots available across modules.
  * @name roots
  * @type {Object.<string,Root>}
  * @example
@@ -5823,6 +5851,9 @@ util.decorateEnum = function decorateEnum(object) {
 util.setProperty = function setProperty(dst, path, value) {
     function setProp(dst, path, value) {
         var part = path.shift();
+        if (part === "__proto__") {
+          return dst;
+        }
         if (path.length > 0) {
             dst[part] = setProp(dst[part] || {}, path, value);
         } else {
@@ -6340,13 +6371,30 @@ function newError(name) {
             merge(this, properties);
     }
 
-    (CustomError.prototype = Object.create(Error.prototype)).constructor = CustomError;
-
-    Object.defineProperty(CustomError.prototype, "name", { get: function() { return name; } });
-
-    CustomError.prototype.toString = function toString() {
-        return this.name + ": " + this.message;
-    };
+    CustomError.prototype = Object.create(Error.prototype, {
+        constructor: {
+            value: CustomError,
+            writable: true,
+            enumerable: false,
+            configurable: true,
+        },
+        name: {
+            get() { return name; },
+            set: undefined,
+            enumerable: false,
+            // configurable: false would accurately preserve the behavior of
+            // the original, but I'm guessing that was not intentional.
+            // For an actual error subclass, this property would
+            // be configurable.
+            configurable: true,
+        },
+        toString: {
+            value() { return this.name + ": " + this.message; },
+            writable: true,
+            enumerable: false,
+            configurable: true,
+        },
+    });
 
     return CustomError;
 }
@@ -6710,7 +6758,7 @@ wrappers[".google.protobuf.Any"] = {
             if (type) {
                 // type_url does not accept leading "."
                 var type_url = object["@type"].charAt(0) === "." ?
-                    object["@type"].substr(1) : object["@type"];
+                    object["@type"].slice(1) : object["@type"];
                 // type_url prefix is optional, but path seperator is required
                 if (type_url.indexOf("/") === -1) {
                     type_url = "/" + type_url;
@@ -6748,7 +6796,7 @@ wrappers[".google.protobuf.Any"] = {
         if (!(message instanceof this.ctor) && message instanceof Message) {
             var object = message.$type.toObject(message, options);
             var messageName = message.$type.fullName[0] === "." ?
-                message.$type.fullName.substr(1) : message.$type.fullName;
+                message.$type.fullName.slice(1) : message.$type.fullName;
             // Default to type.googleapis.com prefix if no prefix is used
             if (prefix === "") {
                 prefix = googleApi;