@bufbuild/protoc-gen-es 1.9.0 → 2.0.0-alpha.2

package/README.md

@@ -4,7 +4,7 @@ The code generator plugin for Protocol Buffers for ECMAScript.  Learn more about
 
 ## Installation
 
-`protoc-gen-es` generates base types - messages and enumerations - from your Protocol Buffer 
+`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).
 
 To install the plugin and the runtime library, run:
@@ -15,7 +15,7 @@ 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 
+compatible with each other. Note that npm installs them automatically, but yarn
 and pnpm do not.
 
 
@@ -37,7 +37,7 @@ plugins:
   # This will invoke protoc-gen-es and write output to src/gen
   - plugin: es
     out: src/gen
-    opt: 
+    opt:
       # Add more plugin options here
       - target=ts
 ```
@@ -49,7 +49,7 @@ npx buf generate
 ```
 
 Note that `buf` can generate from various [inputs](https://docs.buf.build/reference/inputs),
-not just local protobuf files. 
+not just local protobuf files.
 
 
 ### With protoc
@@ -65,7 +65,7 @@ PATH=$PATH:$(pwd)/node_modules/.bin \
 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.
 
-Since yarn v2 and above does not use a `node_modules` directory, you need to 
+Since yarn v2 and above does not use a `node_modules` directory, you need to
 change the variable a bit:
 
 ```bash
@@ -88,33 +88,32 @@ Multiple values can be given 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 
+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=.js`
+### `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))
-uses a `.js` file extensions in import paths, even in TypeScript files.
+does not add a file extensions to import paths.
 
-This is unintuitive, but necessary for [ECMAScript modules in Node.js](https://www.typescriptlang.org/docs/handbook/esm-node.html).
-Unfortunately, not all bundlers and tools have caught up yet, and Deno
-requires `.ts`. With this plugin option, you can replace `.js` extensions
+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
 
-- `import_extension=none` to remove the `.js` extension.
-- `import_extension=.ts` to replace the `.js` extension with `.ts`.
+- `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)
 
 ### `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 
+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.
 
 Possible values:
-- `js_import_style=module` generate ECMAScript `import` / `export` statements - 
+- `js_import_style=module` generate ECMAScript `import` / `export` statements -
   the default behavior.
 - `js_import_style=legacy_commonjs` generate CommonJS `require()` calls.
 
@@ -127,13 +126,12 @@ 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.
 
-### `ts_nocheck=false`
+### `ts_nocheck=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))
-generate an annotation at the top of each file: `// @ts-nocheck`.
+[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.
 
-We generate the annotation to support a wide range of compiler configurations and
-future changes to the language. But there can be situations where the annotation
-shadows an underlying problem, for example an unresolvable import. To remove 
-the annotation and to enable type checks, set the plugin option `ts_nocheck=false`.
+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
+the top of each file to skip type checks: `// @ts-nocheck`.

package/dist/cjs/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@bufbuild/protoc-gen-es",
-    "version": "1.9.0",
+    "version": "2.0.0-alpha.2",
     "description": "Protocol Buffers code generator for ECMAScript",
     "license": "Apache-2.0",
     "repository": {
@@ -20,15 +20,19 @@
     },
     "preferUnplugged": true,
     "dependencies": {
-        "@bufbuild/protobuf": "^1.9.0",
-        "@bufbuild/protoplugin": "1.9.0"
+        "@bufbuild/protobuf": "^2.0.0-alpha.2",
+        "@bufbuild/protoplugin": "2.0.0-alpha.2"
     },
     "peerDependencies": {
-        "@bufbuild/protobuf": "1.9.0"
+        "@bufbuild/protobuf": "2.0.0-alpha.2"
     },
     "peerDependenciesMeta": {
         "@bufbuild/protobuf": {
             "optional": true
         }
-    }
+    },
+    "files": [
+        "dist/**",
+        "bin/**"
+    ]
 }

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

@@ -14,15 +14,329 @@
 // limitations under the License.
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.protocGenEs = void 0;
+const reflect_1 = require("@bufbuild/protobuf/reflect");
+const codegenv1_1 = require("@bufbuild/protobuf/codegenv1");
 const protoplugin_1 = require("@bufbuild/protoplugin");
-const typescript_js_1 = require("./typescript.js");
-const javascript_js_1 = require("./javascript.js");
-const declaration_js_1 = require("./declaration.js");
+const util_1 = require("./util");
 const package_json_1 = require("../package.json");
 exports.protocGenEs = (0, protoplugin_1.createEcmaScriptPlugin)({
     name: "protoc-gen-es",
     version: `v${String(package_json_1.version)}`,
-    generateTs: typescript_js_1.generateTs,
-    generateJs: javascript_js_1.generateJs,
-    generateDts: declaration_js_1.generateDts,
+    generateTs,
+    generateJs,
+    generateDts,
 });
+// This annotation informs bundlers that the succeeding function call is free of
+// side effects. This means the symbol can be removed from the module during
+// tree-shaking if it is unused.
+// See https://github.com/bufbuild/protobuf-es/pull/470
+const pure = "/*@__PURE__*/";
+// prettier-ignore
+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 fileDesc = f.importDesc(file);
+        generateDescDoc(f, file);
+        f.print(f.exportDecl("const", fileDesc.name), ": ", GenDescFile, " = ", pure);
+        f.print("  ", getFileDescCall(f, file, schema), ";");
+        f.print();
+        for (const desc of schema.typesInFile(file)) {
+            switch (desc.kind) {
+                case "message": {
+                    generateMessageShape(f, desc, "ts");
+                    const { GenDescMessage, messageDesc } = f.runtime.codegen;
+                    const MessageShape = f.importShape(desc);
+                    const name = f.importDesc(desc).name;
+                    generateDescDoc(f, desc);
+                    const call = (0, util_1.functionCall)(messageDesc, [fileDesc, ...(0, codegenv1_1.pathInFileDesc)(desc)]);
+                    f.print(f.exportDecl("const", name), ": ", GenDescMessage, "<", MessageShape, ">", " = ", pure);
+                    f.print("  ", call, ";");
+                    f.print();
+                    break;
+                }
+                case "enum": {
+                    generateEnumShape(f, desc);
+                    const { GenDescEnum, enumDesc } = f.runtime.codegen;
+                    const EnumShape = f.importShape(desc);
+                    generateDescDoc(f, desc);
+                    const name = f.importDesc(desc).name;
+                    const call = (0, util_1.functionCall)(enumDesc, [fileDesc, ...(0, codegenv1_1.pathInFileDesc)(desc)]);
+                    f.print(f.exportDecl("const", name), ": ", GenDescEnum, "<", EnumShape, ">", " = ", pure);
+                    f.print("  ", call, ";");
+                    f.print();
+                    break;
+                }
+                case "extension": {
+                    const { GenDescExtension, extDesc } = f.runtime.codegen;
+                    const name = f.importDesc(desc).name;
+                    const E = f.importShape(desc.extendee);
+                    const V = (0, util_1.fieldTypeScriptType)(desc).typing;
+                    const call = (0, util_1.functionCall)(extDesc, [fileDesc, ...(0, codegenv1_1.pathInFileDesc)(desc)]);
+                    f.print(f.jsDoc(desc));
+                    f.print(f.exportDecl("const", name), ": ", GenDescExtension, "<", E, ", ", V, ">", " = ", pure);
+                    f.print("  ", call, ";");
+                    f.print();
+                    break;
+                }
+                case "service": {
+                    const { GenDescService, serviceDesc } = f.runtime.codegen;
+                    const name = f.importDesc(desc).name;
+                    const call = (0, util_1.functionCall)(serviceDesc, [fileDesc, ...(0, codegenv1_1.pathInFileDesc)(desc)]);
+                    f.print(f.jsDoc(desc));
+                    f.print(f.exportDecl("const", name), ": ", GenDescService, "<", getServiceShapeExpr(f, desc), "> = ", pure);
+                    f.print("  ", call, ";");
+                    f.print();
+                    break;
+                }
+            }
+        }
+    }
+}
+// prettier-ignore
+function generateJs(schema) {
+    for (const file of schema.files) {
+        const f = schema.generateFile(file.name + "_pb.js");
+        f.preamble(file);
+        const fileDesc = f.importDesc(file);
+        generateDescDoc(f, file);
+        f.print(f.exportDecl("const", fileDesc.name), " = ", pure);
+        f.print("  ", getFileDescCall(f, file, schema), ";");
+        f.print();
+        for (const desc of schema.typesInFile(file)) {
+            switch (desc.kind) {
+                case "message": {
+                    const { messageDesc } = f.runtime.codegen;
+                    const name = f.importDesc(desc).name;
+                    generateDescDoc(f, desc);
+                    const call = (0, util_1.functionCall)(messageDesc, [fileDesc, ...(0, codegenv1_1.pathInFileDesc)(desc)]);
+                    f.print(f.exportDecl("const", name), " = ", pure);
+                    f.print("  ", call, ";");
+                    f.print();
+                    break;
+                }
+                case "enum": {
+                    // generate descriptor
+                    {
+                        const { enumDesc } = f.runtime.codegen;
+                        generateDescDoc(f, desc);
+                        const name = f.importDesc(desc).name;
+                        const call = (0, util_1.functionCall)(enumDesc, [fileDesc, ...(0, codegenv1_1.pathInFileDesc)(desc)]);
+                        f.print(f.exportDecl("const", name), " = ", pure);
+                        f.print("  ", call, ";");
+                        f.print();
+                    }
+                    // declare TypeScript enum
+                    {
+                        f.print(f.jsDoc(desc));
+                        const { tsEnum } = f.runtime.codegen;
+                        const call = (0, util_1.functionCall)(tsEnum, [f.importDesc(desc)]);
+                        f.print(f.exportDecl("const", f.importShape(desc).name), " = ", pure);
+                        f.print("  ", call, ";");
+                        f.print();
+                    }
+                    break;
+                }
+                case "extension": {
+                    const { extDesc } = f.runtime.codegen;
+                    const name = f.importDesc(desc).name;
+                    const call = (0, util_1.functionCall)(extDesc, [fileDesc, ...(0, codegenv1_1.pathInFileDesc)(desc)]);
+                    f.print(f.jsDoc(desc));
+                    f.print(f.exportDecl("const", name), " = ", pure);
+                    f.print("  ", call, ";");
+                    f.print();
+                    break;
+                }
+                case "service": {
+                    const { serviceDesc } = f.runtime.codegen;
+                    const name = f.importDesc(desc).name;
+                    f.print(f.jsDoc(desc));
+                    const call = (0, util_1.functionCall)(serviceDesc, [fileDesc, ...(0, codegenv1_1.pathInFileDesc)(desc)]);
+                    f.print(f.exportDecl("const", name), " = ", pure);
+                    f.print("  ", call, ";");
+                    f.print();
+                    break;
+                }
+            }
+        }
+    }
+}
+// prettier-ignore
+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 fileDesc = f.importDesc(file);
+        generateDescDoc(f, file);
+        f.print(f.exportDecl("declare const", fileDesc.name), ": ", GenDescFile, ";");
+        f.print();
+        for (const desc of schema.typesInFile(file)) {
+            switch (desc.kind) {
+                case "message": {
+                    generateMessageShape(f, desc, "dts");
+                    const { GenDescMessage } = f.runtime.codegen;
+                    const MessageShape = f.importShape(desc);
+                    const name = f.importDesc(desc).name;
+                    generateDescDoc(f, desc);
+                    f.print(f.exportDecl("declare const", name), ": ", GenDescMessage, "<", MessageShape, ">", ";");
+                    f.print();
+                    break;
+                }
+                case "enum": {
+                    generateEnumShape(f, desc);
+                    const { GenDescEnum } = f.runtime.codegen;
+                    const EnumShape = f.importShape(desc);
+                    generateDescDoc(f, desc);
+                    const name = f.importDesc(desc).name;
+                    f.print(f.exportDecl("declare const", name), ": ", GenDescEnum, "<", EnumShape, ">;");
+                    f.print();
+                    break;
+                }
+                case "extension": {
+                    const { GenDescExtension } = f.runtime.codegen;
+                    const name = f.importDesc(desc).name;
+                    const E = f.importShape(desc.extendee);
+                    const V = (0, util_1.fieldTypeScriptType)(desc).typing;
+                    f.print(f.jsDoc(desc));
+                    f.print(f.exportDecl("declare const", name), ": ", GenDescExtension, "<", E, ", ", V, ">;");
+                    f.print();
+                    break;
+                }
+                case "service": {
+                    const { GenDescService } = f.runtime.codegen;
+                    const name = f.importDesc(desc).name;
+                    f.print(f.jsDoc(desc));
+                    f.print(f.exportDecl("declare const", name), ": ", GenDescService, "<", getServiceShapeExpr(f, desc), ">;");
+                    f.print();
+                    break;
+                }
+            }
+        }
+    }
+}
+function generateDescDoc(f, desc) {
+    let lines;
+    switch (desc.kind) {
+        case "file":
+            lines = [`Describes the ${desc.toString()}.`];
+            break;
+        case "message":
+            lines = [
+                `Describes the ${desc.toString()}.`,
+                `Use \`create(${f.importDesc(desc).name})\` to create a new message.`,
+            ];
+            break;
+        case "enum":
+            lines = [`Describes the ${desc.toString()}.`];
+            break;
+    }
+    const deprecated = desc.deprecated || (0, reflect_1.parentTypes)(desc).some((d) => d.deprecated);
+    if (deprecated) {
+        lines.push("@deprecated");
+    }
+    f.print({
+        kind: "es_jsdoc",
+        text: lines.join("\n"),
+    });
+}
+// prettier-ignore
+function getFileDescCall(f, file, schema) {
+    // Schema provides files with source retention options. Since we do not want to
+    // embed source retention options in generated code, we use FileDescriptorProto
+    // messages from CodeGeneratorRequest.proto_file instead.
+    const sourceFile = file.proto;
+    const runtimeFile = schema.proto.protoFile.find(f => f.name == sourceFile.name);
+    const info = (0, codegenv1_1.embedFileDesc)(runtimeFile !== null && runtimeFile !== void 0 ? runtimeFile : sourceFile);
+    if (info.bootable && !f.runtime.create.from.startsWith("@bufbuild/protobuf")) {
+        // google/protobuf/descriptor.proto is embedded as a plain object when
+        // bootstrapping to avoid recursion
+        return (0, util_1.functionCall)(f.runtime.codegen.boot, [JSON.stringify(info.boot())]);
+    }
+    const { fileDesc } = f.runtime.codegen;
+    if (file.dependencies.length > 0) {
+        const deps = file.dependencies.map((f) => ({
+            kind: "es_desc_ref",
+            desc: f,
+        }));
+        return (0, util_1.functionCall)(fileDesc, [
+            f.string(info.base64()),
+            (0, util_1.arrayLiteral)(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("{");
+    for (const method of service.methods) {
+        print(f.jsDoc(method, "  "));
+        print("  ", method.localName, ": {");
+        print("    kind: ", f.string(method.methodKind), ";");
+        print("    I: ", f.importShape(method.input), ";");
+        print("    O: ", f.importShape(method.output), ";");
+        print("  },");
+    }
+    print("}");
+    return p;
+}
+// prettier-ignore
+function generateEnumShape(f, enumeration) {
+    f.print(f.jsDoc(enumeration));
+    f.print(f.exportDecl("enum", f.importShape(enumeration).name), " {");
+    for (const value of enumeration.values) {
+        if (enumeration.values.indexOf(value) > 0) {
+            f.print();
+        }
+        f.print(f.jsDoc(value, "  "));
+        f.print("  ", value.localName, " = ", value.number, ",");
+    }
+    f.print("}");
+    f.print();
+}
+// prettier-ignore
+function generateMessageShape(f, message, target) {
+    const { Message } = f.runtime;
+    const declaration = target == "ts" ? "type" : "declare type";
+    f.print(f.jsDoc(message));
+    f.print(f.exportDecl(declaration, f.importShape(message).name), " = ", Message, "<", f.string(message.typeName), "> & {");
+    for (const member of message.members) {
+        switch (member.kind) {
+            case "oneof":
+                f.print(f.jsDoc(member, "  "));
+                f.print("  ", member.localName, ": {");
+                for (const field of member.fields) {
+                    if (member.fields.indexOf(field) > 0) {
+                        f.print(`  } | {`);
+                    }
+                    f.print(f.jsDoc(field, "    "));
+                    const { typing } = (0, util_1.fieldTypeScriptType)(field);
+                    f.print(`    value: `, typing, `;`);
+                    f.print(`    case: "`, field.localName, `";`);
+                }
+                f.print(`  } | { case: undefined; value?: undefined };`);
+                break;
+            default: {
+                f.print(f.jsDoc(member, "  "));
+                const { typing, optional } = (0, util_1.fieldTypeScriptType)(member);
+                if (optional) {
+                    f.print("  ", member.localName, "?: ", typing, ";");
+                }
+                else {
+                    f.print("  ", member.localName, ": ", typing, ";");
+                }
+                break;
+            }
+        }
+        if (message.members.indexOf(member) < message.members.length - 1) {
+            f.print();
+        }
+    }
+    f.print("};");
+    f.print();
+}