@bufbuild/protoc-gen-es 2.0.0-beta.2 → 2.0.0

package/README.md

@@ -1,11 +1,13 @@
 # @bufbuild/protoc-gen-es
 
-The code generator plugin for Protocol Buffers for ECMAScript. Learn more about the project at [github.com/bufbuild/protobuf-es](https://github.com/bufbuild/protobuf-es).
+The code generator plugin for Protocol Buffers for ECMAScript. Learn more about the project at
+[github.com/bufbuild/protobuf-es](https://github.com/bufbuild/protobuf-es).
 
 ## Installation
 
-`protoc-gen-es` generates base types - messages and enumerations - from your Protocol Buffer
-schema. The generated code requires the runtime library [@bufbuild/protobuf](https://www.npmjs.com/package/@bufbuild/protobuf). It is compatible with Protocol Buffer compilers like [buf](https://github.com/bufbuild/buf) and [protoc](https://github.com/protocolbuffers/protobuf/releases).
+`protoc-gen-es` generates base types—messages and enumerations—from your Protocol Buffer
+schema. The generated code requires the runtime library [@bufbuild/protobuf](https://www.npmjs.com/package/@bufbuild/protobuf).
+It's compatible with Protocol Buffer compilers like [buf](https://github.com/bufbuild/buf) and [protoc](https://github.com/protocolbuffers/protobuf/releases).
 
 To install the plugin and the runtime library, run:
 
@@ -14,8 +16,8 @@ npm install --save-dev @bufbuild/protoc-gen-es
 npm install @bufbuild/protobuf
 ```
 
-We use peer dependencies to ensure that code generator and runtime library are
-compatible with each other. Note that npm installs them automatically, but yarn
+We use peer dependencies to ensure that the code generator and runtime library are
+compatible with each other. Note that npm installs them automatically, but Yarn
 and pnpm do not.
 
 ## Generating code
@@ -26,31 +28,30 @@ and pnpm do not.
 npm install --save-dev @bufbuild/buf
 ```
 
-Add a new configuration file `buf.gen.yaml`:
+Add a new `buf.gen.yaml` configuration file:
 
 ```yaml
-# buf.gen.yaml defines a local generation template.
-# For details, see https://docs.buf.build/configuration/v1/buf-gen-yaml
-version: v1
+# Learn more: https://buf.build/docs/configuration/v2/buf-gen-yaml
+version: v2
 plugins:
   # This will invoke protoc-gen-es and write output to src/gen
-  - plugin: es
+  - local: protoc-gen-es
     out: src/gen
     opt:
       # Add more plugin options here
       - target=ts
 ```
 
-To generate code for all protobuf files within your project, simply run:
+To generate code for all Protobuf files within your project, run:
 
 ```bash
 npx buf generate
 ```
 
-Note that `buf` can generate from various [inputs](https://docs.buf.build/reference/inputs),
-not just local protobuf files.
+Note that `buf` can generate from various [inputs](https://buf.build/docs/reference/inputs),
+not just local Protobuf files.
 
-### With protoc
+### With `protoc`
 
 ```bash
 PATH=$PATH:$(pwd)/node_modules/.bin \
@@ -60,13 +61,13 @@ PATH=$PATH:$(pwd)/node_modules/.bin \
   a.proto b.proto c.proto
 ```
 
-Note that we are adding `node_modules/.bin` to the `$PATH`, so that the protocol
-buffer compiler can find them. This happens automatically with npm scripts.
+Note that `node_modules/.bin` needs to be added to the `$PATH` so that the Protobuf compiler can find the plugin. This
+happens automatically with npm scripts.
 
-Since yarn v2 and above does not use a `node_modules` directory, you need to
-change the variable a bit:
+If you use Yarn, versions v2 and above don't use a `node_modules` directory, so you need to change the variable a
+bit:
 
-```bash
+```shellsession
 PATH=$(dirname $(yarn bin protoc-gen-es)):$PATH
 ```
 
@@ -74,69 +75,50 @@ PATH=$(dirname $(yarn bin protoc-gen-es)):$PATH
 
 ### `target`
 
-This option controls whether the plugin generates JavaScript, TypeScript,
-or TypeScript declaration files.
-
-Possible values:
+This option controls whether the plugin generates JavaScript, TypeScript, or TypeScript declaration files. Possible
+values:
 
-- `target=js` - generates a `_pb.js` file for every `.proto` input file.
-- `target=ts` - generates a `_pb.ts` file for every `.proto` input file.
-- `target=dts` - generates a `_pb.d.ts` file for every `.proto` input file.
+- `target=js`: Generates a `_pb.js` file for every `.proto` input file.
+- `target=ts`: Generates a `_pb.ts` file for every `.proto` input file.
+- `target=dts`: Generates a `_pb.d.ts` file for every `.proto` input file.
 
-Multiple values can be given by separating them with `+`, for example
-`target=js+dts`.
+You can pass multiple values by separating them with `+`—for example, `target=js+dts`.
 
-By default, we generate JavaScript and TypeScript declaration files, which
-produces the smallest code size and is the most compatible with various
-bundler configurations. If you prefer to generate TypeScript, use `target=ts`.
+By default, it generates JavaScript and TypeScript declaration files, which produces the smallest code size and is the
+most compatible with various bundler configurations. If you prefer to generate TypeScript, use `target=ts`.
 
 ### `import_extension`
 
-By default, [protoc-gen-es](https://www.npmjs.com/package/@bufbuild/protoc-gen-es)
-(and all other plugins based on [@bufbuild/protoplugin](https://www.npmjs.com/package/@bufbuild/protoplugin))
-does not add a file extensions to import paths.
-
-Some environments require an import extension. For example, using [ECMAScript modules in Node.js](https://www.typescriptlang.org/docs/handbook/esm-node.html) requires the `.js` extension, and Deno requires `.ts`. With this plugin option, you can add `.js`/`.ts` extensions
-in import paths with the given value. For example, set
+By default, `protoc-gen-es` doesn't add file extensions to import paths. However, some
+environments require an import extension. For example, using ECMAScript modules in Node.js
+requires the `.js` extension, and Deno requires `.ts`. With this plugin option, you can add `.js`/`.ts` extensions in
+import paths with the given value. Possible values:
 
-- `import_extension=.js` to add the `.js` extension.
-- `import_extension=.ts` to add the `.ts` extension.
-- `import_extension=none` to not add an extension. (Default)
+- `import_extension=none`: Doesn't add an extension. (Default)
+- `import_extension=js`: Adds the `.js` extension.
+- `import_extension=ts`. Adds the `.ts` extension.
 
 ### `js_import_style`
 
-By default, [protoc-gen-es](https://www.npmjs.com/package/@bufbuild/protoc-gen-es)
-(and all other plugins based on [@bufbuild/protoplugin](https://www.npmjs.com/package/@bufbuild/protoplugin))
-generate ECMAScript `import` and `export` statements. For use cases where
-CommonJS is difficult to avoid, this option can be used to generate CommonJS
-`require()` calls.
+By default, `protoc-gen-es` generates ECMAScript `import` and `export` statements. For use cases where CommonJS is
+difficult to avoid, this option can be used to generate CommonJS `require()` calls. Possible values:
 
-Possible values:
-
-- `js_import_style=module` generate ECMAScript `import` / `export` statements -
-  the default behavior.
-- `js_import_style=legacy_commonjs` generate CommonJS `require()` calls.
+- `js_import_style=module`: Generates ECMAScript `import`/`export` statements. (Default)
+- `js_import_style=legacy_commonjs`: Generates CommonJS `require()` calls.
 
 ### `keep_empty_files=true`
 
-By default, [protoc-gen-es](https://www.npmjs.com/package/@bufbuild/protoc-gen-es)
-(and all other plugins based on [@bufbuild/protoplugin](https://www.npmjs.com/package/@bufbuild/protoplugin))
-omit empty files from the plugin output. This option disables pruning of
-empty files, to allow for smooth interoperation with Bazel and similar
-tooling that requires all output files to be declared ahead of time.
-Unless you use Bazel, it is very unlikely that you need this option.
+By default, `protoc-gen-es` omits empty files from the plugin output. This option disables pruning of empty files to
+allow for smooth interoperation with Bazel and similar tooling that requires all output files to be declared ahead of
+time. Unless you use Bazel, you probably don't need this option.
 
 ### `ts_nocheck=true`
 
-[protoc-gen-es](https://www.npmjs.com/package/@bufbuild/protoc-gen-es) generates
-valid TypeScript for current versions of the TypeScript compiler with standard
-settings.
-
-In case you use compiler settings that yield an error for generated code, you
-can set the plugin option `ts_nocheck=true`. This will generate an annotation at
+`protoc-gen-es` generates valid TypeScript for current versions of the TypeScript compiler with standard settings.
+If you use compiler settings that yield an error for generated code, setting this option generates an annotation at
 the top of each file to skip type checks: `// @ts-nocheck`.
 
 ### `json_types=true`
 
-Generates JSON types for every Protobuf message and enumeration. Calling `toJson()`
-will automatically return the JSON type if available.
+Generates JSON types for every Protobuf message and enumeration. Calling `toJson()` automatically returns the JSON type
+if available. Learn more about [JSON types](https://github.com/bufbuild/protobuf-es/blob/main/MANUAL.md#json-types).

package/dist/cjs/package.json

@@ -1,8 +1,15 @@
 {
     "name": "@bufbuild/protoc-gen-es",
-    "version": "2.0.0-beta.2",
-    "description": "Protocol Buffers code generator for ECMAScript",
+    "version": "2.0.0",
     "license": "Apache-2.0",
+    "description": "Protocol Buffers code generator for ECMAScript",
+    "keywords": [
+        "protobuf",
+        "schema",
+        "typescript",
+        "ecmascript",
+        "protoc-plugin"
+    ],
     "repository": {
         "type": "git",
         "url": "https://github.com/bufbuild/protobuf-es.git",
@@ -23,11 +30,11 @@
     },
     "preferUnplugged": true,
     "dependencies": {
-        "@bufbuild/protobuf": "^2.0.0-beta.2",
-        "@bufbuild/protoplugin": "2.0.0-beta.2"
+        "@bufbuild/protobuf": "^2.0.0",
+        "@bufbuild/protoplugin": "2.0.0"
     },
     "peerDependencies": {
-        "@bufbuild/protobuf": "2.0.0-beta.2"
+        "@bufbuild/protobuf": "2.0.0"
     },
     "peerDependenciesMeta": {
         "@bufbuild/protobuf": {

package/dist/cjs/src/protoc-gen-es-plugin.js

@@ -54,10 +54,10 @@ function generateTs(schema) {
     for (const file of schema.files) {
         const f = schema.generateFile(file.name + "_pb.ts");
         f.preamble(file);
-        const { GenDescFile } = f.runtime.codegen;
+        const { GenFile } = f.runtime.codegen;
         const fileDesc = f.importSchema(file);
         generateDescDoc(f, file);
-        f.print(f.export("const", fileDesc.name), ": ", GenDescFile, " = ", pure);
+        f.print(f.export("const", fileDesc.name), ": ", GenFile, " = ", pure);
         f.print("  ", getFileDescCall(f, file, schema), ";");
         f.print();
         for (const desc of schema.typesInFile(file)) {
@@ -70,13 +70,13 @@ function generateTs(schema) {
                     generateDescDoc(f, desc);
                     const name = f.importSchema(desc).name;
                     const Shape = f.importShape(desc);
-                    const { GenDescMessage, messageDesc } = f.runtime.codegen;
+                    const { GenMessage, messageDesc } = f.runtime.codegen;
                     if (schema.options.jsonTypes) {
                         const JsonType = f.importJson(desc);
-                        f.print(f.export("const", name), ": ", GenDescMessage, "<", Shape, ", ", JsonType, ">", " = ", pure);
+                        f.print(f.export("const", name), ": ", GenMessage, "<", Shape, ", ", JsonType, ">", " = ", pure);
                     }
                     else {
-                        f.print(f.export("const", name), ": ", GenDescMessage, "<", Shape, ">", " = ", pure);
+                        f.print(f.export("const", name), ": ", GenMessage, "<", Shape, ">", " = ", pure);
                     }
                     const call = (0, util_1.functionCall)(messageDesc, [fileDesc, ...(0, codegenv1_1.pathInFileDesc)(desc)]);
                     f.print("  ", call, ";");
@@ -91,13 +91,13 @@ function generateTs(schema) {
                     generateDescDoc(f, desc);
                     const name = f.importSchema(desc).name;
                     const Shape = f.importShape(desc);
-                    const { GenDescEnum, enumDesc } = f.runtime.codegen;
+                    const { GenEnum, enumDesc } = f.runtime.codegen;
                     if (schema.options.jsonTypes) {
                         const JsonType = f.importJson(desc);
-                        f.print(f.export("const", name), ": ", GenDescEnum, "<", Shape, ", ", JsonType, ">", " = ", pure);
+                        f.print(f.export("const", name), ": ", GenEnum, "<", Shape, ", ", JsonType, ">", " = ", pure);
                     }
                     else {
-                        f.print(f.export("const", name), ": ", GenDescEnum, "<", Shape, ">", " = ", pure);
+                        f.print(f.export("const", name), ": ", GenEnum, "<", Shape, ">", " = ", pure);
                     }
                     const call = (0, util_1.functionCall)(enumDesc, [fileDesc, ...(0, codegenv1_1.pathInFileDesc)(desc)]);
                     f.print("  ", call, ";");
@@ -105,23 +105,23 @@ function generateTs(schema) {
                     break;
                 }
                 case "extension": {
-                    const { GenDescExtension, extDesc } = f.runtime.codegen;
+                    const { GenExtension, extDesc } = f.runtime.codegen;
                     const name = f.importSchema(desc).name;
                     const E = f.importShape(desc.extendee);
                     const V = (0, util_1.fieldTypeScriptType)(desc, f.runtime).typing;
                     const call = (0, util_1.functionCall)(extDesc, [fileDesc, ...(0, codegenv1_1.pathInFileDesc)(desc)]);
                     f.print(f.jsDoc(desc));
-                    f.print(f.export("const", name), ": ", GenDescExtension, "<", E, ", ", V, ">", " = ", pure);
+                    f.print(f.export("const", name), ": ", GenExtension, "<", E, ", ", V, ">", " = ", pure);
                     f.print("  ", call, ";");
                     f.print();
                     break;
                 }
                 case "service": {
-                    const { GenDescService, serviceDesc } = f.runtime.codegen;
+                    const { GenService, serviceDesc } = f.runtime.codegen;
                     const name = f.importSchema(desc).name;
                     const call = (0, util_1.functionCall)(serviceDesc, [fileDesc, ...(0, codegenv1_1.pathInFileDesc)(desc)]);
                     f.print(f.jsDoc(desc));
-                    f.print(f.export("const", name), ": ", GenDescService, "<", getServiceShapeExpr(f, desc), "> = ", pure);
+                    f.print(f.export("const", name), ": ", GenService, "<", getServiceShapeExpr(f, desc), "> = ", pure);
                     f.print("  ", call, ";");
                     f.print();
                     break;
@@ -203,10 +203,10 @@ function generateDts(schema) {
     for (const file of schema.files) {
         const f = schema.generateFile(file.name + "_pb.d.ts");
         f.preamble(file);
-        const { GenDescFile } = f.runtime.codegen;
+        const { GenFile } = f.runtime.codegen;
         const fileDesc = f.importSchema(file);
         generateDescDoc(f, file);
-        f.print(f.export("declare const", fileDesc.name), ": ", GenDescFile, ";");
+        f.print(f.export("declare const", fileDesc.name), ": ", GenFile, ";");
         f.print();
         for (const desc of schema.typesInFile(file)) {
             switch (desc.kind) {
@@ -217,14 +217,14 @@ function generateDts(schema) {
                     }
                     const name = f.importSchema(desc).name;
                     const Shape = f.importShape(desc);
-                    const { GenDescMessage } = f.runtime.codegen;
+                    const { GenMessage } = f.runtime.codegen;
                     generateDescDoc(f, desc);
                     if (schema.options.jsonTypes) {
                         const JsonType = f.importJson(desc);
-                        f.print(f.export("declare const", name), ": ", GenDescMessage, "<", Shape, ", ", JsonType, ">", ";");
+                        f.print(f.export("declare const", name), ": ", GenMessage, "<", Shape, ", ", JsonType, ">", ";");
                     }
                     else {
-                        f.print(f.export("declare const", name), ": ", GenDescMessage, "<", Shape, ">", ";");
+                        f.print(f.export("declare const", name), ": ", GenMessage, "<", Shape, ">", ";");
                     }
                     f.print();
                     break;
@@ -237,32 +237,32 @@ function generateDts(schema) {
                     generateDescDoc(f, desc);
                     const name = f.importSchema(desc).name;
                     const Shape = f.importShape(desc);
-                    const { GenDescEnum } = f.runtime.codegen;
+                    const { GenEnum } = f.runtime.codegen;
                     if (schema.options.jsonTypes) {
                         const JsonType = f.importJson(desc);
-                        f.print(f.export("declare const", name), ": ", GenDescEnum, "<", Shape, ", ", JsonType, ">;");
+                        f.print(f.export("declare const", name), ": ", GenEnum, "<", Shape, ", ", JsonType, ">;");
                     }
                     else {
-                        f.print(f.export("declare const", name), ": ", GenDescEnum, "<", Shape, ">;");
+                        f.print(f.export("declare const", name), ": ", GenEnum, "<", Shape, ">;");
                     }
                     f.print();
                     break;
                 }
                 case "extension": {
-                    const { GenDescExtension } = f.runtime.codegen;
+                    const { GenExtension } = f.runtime.codegen;
                     const name = f.importSchema(desc).name;
                     const E = f.importShape(desc.extendee);
                     const V = (0, util_1.fieldTypeScriptType)(desc, f.runtime).typing;
                     f.print(f.jsDoc(desc));
-                    f.print(f.export("declare const", name), ": ", GenDescExtension, "<", E, ", ", V, ">;");
+                    f.print(f.export("declare const", name), ": ", GenExtension, "<", E, ", ", V, ">;");
                     f.print();
                     break;
                 }
                 case "service": {
-                    const { GenDescService } = f.runtime.codegen;
+                    const { GenService } = f.runtime.codegen;
                     const name = f.importSchema(desc).name;
                     f.print(f.jsDoc(desc));
-                    f.print(f.export("declare const", name), ": ", GenDescService, "<", getServiceShapeExpr(f, desc), ">;");
+                    f.print(f.export("declare const", name), ": ", GenService, "<", getServiceShapeExpr(f, desc), ">;");
                     f.print();
                     break;
                 }
@@ -316,27 +316,23 @@ function getFileDescCall(f, file, schema) {
         }));
         return (0, util_1.functionCall)(fileDesc, [
             f.string(info.base64()),
-            (0, util_1.arrayLiteral)(deps),
+            f.array(deps),
         ]);
     }
     return (0, util_1.functionCall)(fileDesc, [f.string(info.base64())]);
 }
 // prettier-ignore
 function getServiceShapeExpr(f, service) {
-    const p = [];
-    function print(...printables) {
-        p.push(...printables, "\n");
-    }
-    print("{");
+    const p = ["{\n"];
     for (const method of service.methods) {
-        print(f.jsDoc(method, "  "));
-        print("  ", method.localName, ": {");
-        print("    methodKind: ", f.string(method.methodKind), ";");
-        print("    input: typeof ", f.importSchema(method.input, true), ";");
-        print("    output: typeof ", f.importSchema(method.output, true), ";");
-        print("  },");
+        p.push(f.jsDoc(method, "  "), "\n");
+        p.push("  ", method.localName, ": {\n");
+        p.push("    methodKind: ", f.string(method.methodKind), ";\n");
+        p.push("    input: typeof ", f.importSchema(method.input, true), ";\n");
+        p.push("    output: typeof ", f.importSchema(method.output, true), ";\n");
+        p.push("  },\n");
     }
-    print("}");
+    p.push("}");
     return p;
 }
 // prettier-ignore

package/dist/cjs/src/util.d.ts

@@ -6,4 +6,3 @@ export declare function fieldTypeScriptType(field: DescField | DescExtension, im
 };
 export declare function fieldJsonType(field: DescField | DescExtension): Printable;
 export declare function functionCall(fn: Printable, args: Printable[], typeParams?: Printable[]): Printable;
-export declare function arrayLiteral(elements: Printable[]): Printable;

package/dist/cjs/src/util.js

@@ -13,7 +13,9 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.arrayLiteral = exports.functionCall = exports.fieldJsonType = exports.fieldTypeScriptType = void 0;
+exports.fieldTypeScriptType = fieldTypeScriptType;
+exports.fieldJsonType = fieldJsonType;
+exports.functionCall = functionCall;
 const protobuf_1 = require("@bufbuild/protobuf");
 const codegenv1_1 = require("@bufbuild/protobuf/codegenv1");
 const wkt_1 = require("@bufbuild/protobuf/wkt");
@@ -91,7 +93,6 @@ function fieldTypeScriptType(field, imports) {
     }
     return { typing, optional };
 }
-exports.fieldTypeScriptType = fieldTypeScriptType;
 function messageFieldTypeScriptType(field, imports) {
     var _a;
     if ((0, wkt_1.isWrapperDesc)(field.message) &&
@@ -186,7 +187,6 @@ function fieldJsonType(field) {
         }
     }
 }
-exports.fieldJsonType = fieldJsonType;
 function functionCall(fn, args, typeParams) {
     let tp = [];
     if (typeParams !== undefined && typeParams.length > 0) {
@@ -194,11 +194,6 @@ function functionCall(fn, args, typeParams) {
     }
     return [fn, ...tp, "(", commaSeparate(args), ")"];
 }
-exports.functionCall = functionCall;
-function arrayLiteral(elements) {
-    return ["[", commaSeparate(elements), "]"];
-}
-exports.arrayLiteral = arrayLiteral;
 function commaSeparate(elements) {
     const r = [];
     for (let i = 0; i < elements.length; i++) {

package/package.json

@@ -1,8 +1,15 @@
 {
   "name": "@bufbuild/protoc-gen-es",
-  "version": "2.0.0-beta.2",
-  "description": "Protocol Buffers code generator for ECMAScript",
+  "version": "2.0.0",
   "license": "Apache-2.0",
+  "description": "Protocol Buffers code generator for ECMAScript",
+  "keywords": [
+    "protobuf",
+    "schema",
+    "typescript",
+    "ecmascript",
+    "protoc-plugin"
+  ],
   "repository": {
     "type": "git",
     "url": "https://github.com/bufbuild/protobuf-es.git",
@@ -23,11 +30,11 @@
   },
   "preferUnplugged": true,
   "dependencies": {
-    "@bufbuild/protobuf": "^2.0.0-beta.2",
-    "@bufbuild/protoplugin": "2.0.0-beta.2"
+    "@bufbuild/protobuf": "^2.0.0",
+    "@bufbuild/protoplugin": "2.0.0"
   },
   "peerDependencies": {
-    "@bufbuild/protobuf": "2.0.0-beta.2"
+    "@bufbuild/protobuf": "2.0.0"
   },
   "peerDependenciesMeta": {
     "@bufbuild/protobuf": {