@bufbuild/protoplugin 0.2.0 → 0.3.0

package/README.md

@@ -1,38 +1,32 @@
 # @bufbuild/protoplugin
 
-This package helps to create your own code generator plugin.
+This package helps to create your own code generator plugin using the 
+Protobuf-ES plugin framework.
 
-## Protocol Buffers for ECMAScript
+Protobuf-ES is a complete implementation of [Protocol Buffers](https://developers.google.com/protocol-buffers) in TypeScript, suitable for web browsers and Node.js.  
 
-A complete implementation of [Protocol Buffers](https://developers.google.com/protocol-buffers)
-in TypeScript, suitable for web browsers and Node.js.  
-Learn more at [github.com/bufbuild/protobuf-es](https://github.com/bufbuild/protobuf-es).
+In addition to a full Protobuf runtime library, it also provides a code generator
+`protoc-gen-es`, which utilizes a plugin framework to generate base types from
+your Protobuf schema.  It is fully compatible with both Buf and protoc compilers.
 
+And now, you can write your own Protobuf-ES compatible plugins using this same
+plugin framework with the `@bufbuild/protoplugin` package.
 
-It is a complete implementation of [Protocol Buffers](https://developers.google.com/protocol-buffers)
-in TypeScript, suitable for web browsers and Node.js.
+With `@bufbuild/protoplugin`, you can generate your own TypeScript code tailored 
+to your project or needs.  You also have various options for producing 
+JavaScript and TypeScript declaration files:
 
-For example, the following definition:
+- Exercise full control by writing your own JavaScript and declaration file
+generators in addition to TypeScript.
 
-```protobuf
-message Person {
-  string name = 1;
-  int32 id = 2;  // Unique ID number for this person.
-  string email = 3;
-}
-```
+- Generate TypeScript files only and let the framework generate JavaScript and
+declaration files automatically using our internal TypeScript compiler.
 
-Is compiled to an ECMAScript class that can be used like this:
+- Generate TypeScript files only and bring your own TypeScript compiler, using
+it to generate JavaScript and declaration files with your own version of 
+TypeScript and your own compiler options.
 
-```typescript
-let pete = new Person({
-  name: "pete",
-  id: 123
-});
+With `protoplugin`, you have all the tools at your disposal to produce ECMAScript-compliant
+code.  
 
-let bytes = pete.toBinary();
-pete = Person.fromBinary(bytes);
-pete = Person.fromJsonString('{"name": "pete", "id": 123}');
-```
-
-Learn more at [github.com/bufbuild/protobuf-es](https://github.com/bufbuild/protobuf-es).
+Get started now with our [plugin documentation](https://github.com/bufbuild/protobuf-es/blob/main/docs/writing_plugins.md). 

package/dist/cjs/ecmascript/custom-options.js

@@ -20,8 +20,8 @@ const protobuf_1 = require("@bufbuild/protobuf");
  *
  * If no option is found, returns undefined.
  */
-function findCustomScalarOption(desc, id, scalarType) {
-    const reader = createBinaryReader(desc, id);
+function findCustomScalarOption(desc, extensionNumber, scalarType) {
+    const reader = createBinaryReader(desc, extensionNumber);
     if (reader) {
         switch (scalarType) {
             case protobuf_1.ScalarType.INT32:
@@ -63,15 +63,18 @@ function findCustomScalarOption(desc, id, scalarType) {
 }
 exports.findCustomScalarOption = findCustomScalarOption;
 /**
- * Returns the value of a custom message option for the given descriptor and ID.
- * The msgType param is then used to deserialize the message for returning to the caller.
+ * Returns the value of a custom message option for the given descriptor and
+ * extension number.
+ * The msgType param is then used to deserialize the message for returning to
+ * the caller.
  *
  * If no options are found, returns undefined.
  *
- * If the message option is unable to be read or deserialized, an error will be thrown.
+ * If the message option is unable to be read or deserialized, an error will
+ * be thrown.
  */
-function findCustomMessageOption(desc, id, msgType) {
-    const reader = createBinaryReader(desc, id);
+function findCustomMessageOption(desc, extensionNumber, msgType) {
+    const reader = createBinaryReader(desc, extensionNumber);
     if (reader) {
         try {
             const data = reader.bytes();
@@ -86,23 +89,24 @@ function findCustomMessageOption(desc, id, msgType) {
 }
 exports.findCustomMessageOption = findCustomMessageOption;
 /**
- * Returns the value of a custom enum option for the given descriptor and ID.
+ * Returns the value of a custom enum option for the given descriptor and
+ * extension number.
  *
  * If no options are found, returns undefined.
  */
-function findCustomEnumOption(desc, id) {
-    return findCustomScalarOption(desc, id, protobuf_1.ScalarType.INT32);
+function findCustomEnumOption(desc, extensionNumber) {
+    return findCustomScalarOption(desc, extensionNumber, protobuf_1.ScalarType.INT32);
 }
 exports.findCustomEnumOption = findCustomEnumOption;
 /**
- * Returns a binary reader for the given descriptor and field ID.
+ * Returns a binary reader for the given descriptor and extension number.
  */
-function createBinaryReader(desc, id) {
+function createBinaryReader(desc, extensionNumber) {
     const opt = desc.proto.options;
     let reader = undefined;
     if (opt !== undefined) {
         const unknownFields = protobuf_1.proto3.bin.listUnknownFields(opt);
-        const field = unknownFields.find((f) => f.no === id);
+        const field = unknownFields.find((f) => f.no === extensionNumber);
         if (field) {
             reader = new protobuf_1.BinaryReader(field.data);
         }

package/dist/cjs/ecmascript/gencommon.js

@@ -48,7 +48,7 @@ function makeFilePreamble(file, pluginName, pluginVersion, parameter, tsNoCheck)
     builder.push(`syntax ${file.syntax})\n`);
     builder.push("/* eslint-disable */\n");
     if (tsNoCheck) {
-        builder.push("/* @ts-nocheck */\n");
+        builder.push("// @ts-nocheck\n");
     }
     builder.push("\n");
     writeLeadingComments(file.getPackageComments());

package/dist/cjs/ecmascript/generated-file.js

@@ -24,8 +24,21 @@ function createGeneratedFile(name, importPath, createTypeImport, runtimeImports,
         preamble(file) {
             preamble = (0, gencommon_js_1.makeFilePreamble)(file, preambleSettings.pluginName, preambleSettings.pluginVersion, preambleSettings.parameter, preambleSettings.tsNocheck);
         },
-        print(...any) {
-            printableToEl(any, el, createTypeImport, runtimeImports);
+        print(printableOrFragments, ...rest) {
+            let printables;
+            if (printableOrFragments != null &&
+                Object.prototype.hasOwnProperty.call(printableOrFragments, "raw")) {
+                // If called with a tagged template literal
+                printables = buildPrintablesFromFragments(printableOrFragments, rest);
+            }
+            else {
+                // If called with just an array of Printables
+                printables =
+                    printableOrFragments != null
+                        ? [printableOrFragments, ...rest]
+                        : rest;
+            }
+            printableToEl(printables, el, createTypeImport, runtimeImports);
             el.push("\n");
         },
         export(name) {
@@ -56,7 +69,7 @@ function elToContent(el, importerPath) {
     const c = [];
     const symbolToIdentifier = processImports(el, importerPath, (typeOnly, from, names) => {
         const p = names.map(({ name, alias }) => alias == undefined ? name : `${name} as ${alias}`);
-        const what = `{${p.join(", ")}}`;
+        const what = `{ ${p.join(", ")} }`;
         if (typeOnly) {
             c.push(`import type ${what} from ${(0, gencommon_js_1.literalString)(from)};\n`);
         }
@@ -119,6 +132,16 @@ function printableToEl(printables, el, createTypeImport, runtimeImports) {
         }
     }
 }
+function buildPrintablesFromFragments(fragments, values) {
+    const printables = [];
+    fragments.forEach((fragment, i) => {
+        printables.push(fragment);
+        if (fragments.length - 1 !== i) {
+            printables.push(values[i]);
+        }
+    });
+    return printables;
+}
 function processImports(el, importerPath, makeImportStatement) {
     // identifiers to use in the output
     const symbolToIdentifier = new Map();

package/dist/cjs/ecmascript/index.js

@@ -13,14 +13,14 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.findCustomEnumOption = exports.findCustomMessageOption = exports.findCustomScalarOption = exports.literalString = exports.makeJsDoc = exports.getFieldTyping = exports.getFieldIntrinsicDefaultValue = exports.getFieldExplicitDefaultValue = exports.createJsDocBlock = exports.localName = void 0;
+exports.findCustomEnumOption = exports.findCustomMessageOption = exports.findCustomScalarOption = exports.literalString = exports.makeJsDoc = exports.getFieldTyping = exports.getFieldIntrinsicDefaultValue = exports.getFieldExplicitDefaultValue = exports.createJsDocBlock = exports.reifyWkt = exports.localName = void 0;
 const protobuf_1 = require("@bufbuild/protobuf");
 var target_js_1 = require("./target.js");
 var schema_js_1 = require("./schema.js");
 var runtime_imports_js_1 = require("./runtime-imports.js");
 var generated_file_js_1 = require("./generated-file.js");
 var import_symbol_js_1 = require("./import-symbol.js");
-exports.localName = protobuf_1.codegenInfo.localName;
+exports.localName = protobuf_1.codegenInfo.localName, exports.reifyWkt = protobuf_1.codegenInfo.reifyWkt;
 var gencommon_js_1 = require("./gencommon.js");
 Object.defineProperty(exports, "createJsDocBlock", { enumerable: true, get: function () { return gencommon_js_1.createJsDocBlock; } });
 Object.defineProperty(exports, "getFieldExplicitDefaultValue", { enumerable: true, get: function () { return gencommon_js_1.getFieldExplicitDefaultValue; } });

package/dist/cjs/ecmascript/runtime-imports.js

@@ -36,6 +36,7 @@ function createRuntimeImports(bootstrapWkt) {
         ScalarType: infoToSymbol("ScalarType", bootstrapWkt),
         MethodKind: infoToSymbol("MethodKind", bootstrapWkt),
         MethodIdempotency: infoToSymbol("MethodIdempotency", bootstrapWkt),
+        IMessageTypeRegistry: infoToSymbol("IMessageTypeRegistry", bootstrapWkt),
     };
 }
 exports.createRuntimeImports = createRuntimeImports;

package/dist/esm/ecmascript/custom-options.js

@@ -17,8 +17,8 @@ import { proto3, BinaryReader, ScalarType, } from "@bufbuild/protobuf";
  *
  * If no option is found, returns undefined.
  */
-export function findCustomScalarOption(desc, id, scalarType) {
-    const reader = createBinaryReader(desc, id);
+export function findCustomScalarOption(desc, extensionNumber, scalarType) {
+    const reader = createBinaryReader(desc, extensionNumber);
     if (reader) {
         switch (scalarType) {
             case ScalarType.INT32:
@@ -59,15 +59,18 @@ export function findCustomScalarOption(desc, id, scalarType) {
     return undefined;
 }
 /**
- * Returns the value of a custom message option for the given descriptor and ID.
- * The msgType param is then used to deserialize the message for returning to the caller.
+ * Returns the value of a custom message option for the given descriptor and
+ * extension number.
+ * The msgType param is then used to deserialize the message for returning to
+ * the caller.
  *
  * If no options are found, returns undefined.
  *
- * If the message option is unable to be read or deserialized, an error will be thrown.
+ * If the message option is unable to be read or deserialized, an error will
+ * be thrown.
  */
-export function findCustomMessageOption(desc, id, msgType) {
-    const reader = createBinaryReader(desc, id);
+export function findCustomMessageOption(desc, extensionNumber, msgType) {
+    const reader = createBinaryReader(desc, extensionNumber);
     if (reader) {
         try {
             const data = reader.bytes();
@@ -81,22 +84,23 @@ export function findCustomMessageOption(desc, id, msgType) {
     return undefined;
 }
 /**
- * Returns the value of a custom enum option for the given descriptor and ID.
+ * Returns the value of a custom enum option for the given descriptor and
+ * extension number.
  *
  * If no options are found, returns undefined.
  */
-export function findCustomEnumOption(desc, id) {
-    return findCustomScalarOption(desc, id, ScalarType.INT32);
+export function findCustomEnumOption(desc, extensionNumber) {
+    return findCustomScalarOption(desc, extensionNumber, ScalarType.INT32);
 }
 /**
- * Returns a binary reader for the given descriptor and field ID.
+ * Returns a binary reader for the given descriptor and extension number.
  */
-function createBinaryReader(desc, id) {
+function createBinaryReader(desc, extensionNumber) {
     const opt = desc.proto.options;
     let reader = undefined;
     if (opt !== undefined) {
         const unknownFields = proto3.bin.listUnknownFields(opt);
-        const field = unknownFields.find((f) => f.no === id);
+        const field = unknownFields.find((f) => f.no === extensionNumber);
         if (field) {
             reader = new BinaryReader(field.data);
         }

package/dist/esm/ecmascript/gencommon.js

@@ -45,7 +45,7 @@ export function makeFilePreamble(file, pluginName, pluginVersion, parameter, tsN
     builder.push(`syntax ${file.syntax})\n`);
     builder.push("/* eslint-disable */\n");
     if (tsNoCheck) {
-        builder.push("/* @ts-nocheck */\n");
+        builder.push("// @ts-nocheck\n");
     }
     builder.push("\n");
     writeLeadingComments(file.getPackageComments());

package/dist/esm/ecmascript/generated-file.js

@@ -21,8 +21,21 @@ export function createGeneratedFile(name, importPath, createTypeImport, runtimeI
         preamble(file) {
             preamble = makeFilePreamble(file, preambleSettings.pluginName, preambleSettings.pluginVersion, preambleSettings.parameter, preambleSettings.tsNocheck);
         },
-        print(...any) {
-            printableToEl(any, el, createTypeImport, runtimeImports);
+        print(printableOrFragments, ...rest) {
+            let printables;
+            if (printableOrFragments != null &&
+                Object.prototype.hasOwnProperty.call(printableOrFragments, "raw")) {
+                // If called with a tagged template literal
+                printables = buildPrintablesFromFragments(printableOrFragments, rest);
+            }
+            else {
+                // If called with just an array of Printables
+                printables =
+                    printableOrFragments != null
+                        ? [printableOrFragments, ...rest]
+                        : rest;
+            }
+            printableToEl(printables, el, createTypeImport, runtimeImports);
             el.push("\n");
         },
         export(name) {
@@ -52,7 +65,7 @@ function elToContent(el, importerPath) {
     const c = [];
     const symbolToIdentifier = processImports(el, importerPath, (typeOnly, from, names) => {
         const p = names.map(({ name, alias }) => alias == undefined ? name : `${name} as ${alias}`);
-        const what = `{${p.join(", ")}}`;
+        const what = `{ ${p.join(", ")} }`;
         if (typeOnly) {
             c.push(`import type ${what} from ${literalString(from)};\n`);
         }
@@ -115,6 +128,16 @@ function printableToEl(printables, el, createTypeImport, runtimeImports) {
         }
     }
 }
+function buildPrintablesFromFragments(fragments, values) {
+    const printables = [];
+    fragments.forEach((fragment, i) => {
+        printables.push(fragment);
+        if (fragments.length - 1 !== i) {
+            printables.push(values[i]);
+        }
+    });
+    return printables;
+}
 function processImports(el, importerPath, makeImportStatement) {
     // identifiers to use in the output
     const symbolToIdentifier = new Map();

package/dist/esm/ecmascript/index.js

@@ -17,6 +17,6 @@ export {} from "./schema.js";
 export {} from "./runtime-imports.js";
 export {} from "./generated-file.js";
 export {} from "./import-symbol.js";
-export const { localName } = codegenInfo;
+export const { localName, reifyWkt } = codegenInfo;
 export { createJsDocBlock, getFieldExplicitDefaultValue, getFieldIntrinsicDefaultValue, getFieldTyping, makeJsDoc, literalString, } from "./gencommon.js";
 export { findCustomScalarOption, findCustomMessageOption, findCustomEnumOption, } from "./custom-options.js";

package/dist/esm/ecmascript/runtime-imports.js

@@ -33,6 +33,7 @@ export function createRuntimeImports(bootstrapWkt) {
         ScalarType: infoToSymbol("ScalarType", bootstrapWkt),
         MethodKind: infoToSymbol("MethodKind", bootstrapWkt),
         MethodIdempotency: infoToSymbol("MethodIdempotency", bootstrapWkt),
+        IMessageTypeRegistry: infoToSymbol("IMessageTypeRegistry", bootstrapWkt),
     };
 }
 function infoToSymbol(name, bootstrapWkt) {

package/dist/types/ecmascript/custom-options.d.ts

@@ -5,22 +5,26 @@ import { Message, MessageType, ScalarType } from "@bufbuild/protobuf";
  *
  * If no option is found, returns undefined.
  */
-export declare function findCustomScalarOption<T extends ScalarType>(desc: AnyDesc, id: number, scalarType: T): ScalarValue<T> | undefined;
+export declare function findCustomScalarOption<T extends ScalarType>(desc: AnyDesc, extensionNumber: number, scalarType: T): ScalarValue<T> | undefined;
 /**
- * Returns the value of a custom message option for the given descriptor and ID.
- * The msgType param is then used to deserialize the message for returning to the caller.
+ * Returns the value of a custom message option for the given descriptor and
+ * extension number.
+ * The msgType param is then used to deserialize the message for returning to
+ * the caller.
  *
  * If no options are found, returns undefined.
  *
- * If the message option is unable to be read or deserialized, an error will be thrown.
+ * If the message option is unable to be read or deserialized, an error will
+ * be thrown.
  */
-export declare function findCustomMessageOption<T extends Message<T>>(desc: AnyDesc, id: number, msgType: MessageType<T>): T | undefined;
+export declare function findCustomMessageOption<T extends Message<T>>(desc: AnyDesc, extensionNumber: number, msgType: MessageType<T>): T | undefined;
 /**
- * Returns the value of a custom enum option for the given descriptor and ID.
+ * Returns the value of a custom enum option for the given descriptor and
+ * extension number.
  *
  * If no options are found, returns undefined.
  */
-export declare function findCustomEnumOption(desc: AnyDesc, id: number): number | undefined;
+export declare function findCustomEnumOption(desc: AnyDesc, extensionNumber: number): number | undefined;
 /**
  * ScalarValue is a conditional type that pairs a ScalarType value with its concrete type.
  */

package/dist/types/ecmascript/generated-file.d.ts

@@ -36,7 +36,13 @@ export interface GeneratedFile {
      * - ImportSymbol: Adds an import statement and prints the name of the symbol.
      * - DescMessage or DescEnum: Imports the type if necessary, and prints the name.
      */
-    print(...any: Printable[]): void;
+    print(...printables: Printable[]): void;
+    /**
+     * Add a line of code to the file with tagged template literal and
+     * an optional array of Printables.
+     * See print(Printable[]) for behavior when printing Printable items.
+     */
+    print(fragments: TemplateStringsArray, ...printables: Printable[]): void;
     /**
      * Reserves an identifier in this file.
      */

package/dist/types/ecmascript/index.d.ts

@@ -3,6 +3,6 @@ export { Schema } from "./schema.js";
 export { RuntimeImports } from "./runtime-imports.js";
 export { GeneratedFile, FileInfo, Printable } from "./generated-file.js";
 export { ImportSymbol } from "./import-symbol.js";
-export declare const localName: typeof import("@bufbuild/protobuf/dist/types/private/names.js").localName;
+export declare const localName: typeof import("@bufbuild/protobuf/dist/types/private/names.js").localName, reifyWkt: typeof import("@bufbuild/protobuf/dist/types/private/reify-wkt.js").reifyWkt;
 export { createJsDocBlock, getFieldExplicitDefaultValue, getFieldIntrinsicDefaultValue, getFieldTyping, makeJsDoc, literalString, } from "./gencommon.js";
 export { findCustomScalarOption, findCustomMessageOption, findCustomEnumOption, } from "./custom-options.js";

package/dist/types/ecmascript/runtime-imports.d.ts

@@ -17,5 +17,6 @@ export interface RuntimeImports {
     ScalarType: ImportSymbol;
     MethodKind: ImportSymbol;
     MethodIdempotency: ImportSymbol;
+    IMessageTypeRegistry: ImportSymbol;
 }
 export declare function createRuntimeImports(bootstrapWkt: boolean): RuntimeImports;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bufbuild/protoplugin",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "license": "(Apache-2.0 AND BSD-3-Clause)",
   "description": "Helps to create your own Protocol Buffers code generators.",
   "repository": {
@@ -35,7 +35,7 @@
     }
   },
   "dependencies": {
-    "@bufbuild/protobuf": "0.2.0",
+    "@bufbuild/protobuf": "0.3.0",
     "@typescript/vfs": "^1.4.0",
     "typescript": "4.5.2"
   },