@bufbuild/protoplugin 0.2.0 → 0.2.1

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/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/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/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/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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bufbuild/protoplugin",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "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.2.1",
     "@typescript/vfs": "^1.4.0",
     "typescript": "4.5.2"
   },