@bufbuild/protoplugin 2.0.0-alpha.4 → 2.0.0-beta.1

package/dist/esm/parameter.d.ts

@@ -1,13 +1,74 @@
 import type { Target } from "./target.js";
 import type { RewriteImports } from "./import-path.js";
-export interface ParsedParameter {
+/**
+ * Standard plugin options that every ECMAScript plugin supports.
+ */
+export interface EcmaScriptPluginOptions {
+    /**
+     * Controls whether the plugin generates JavaScript, TypeScript,
+     * or TypeScript declaration files.
+     *
+     * The default is ["js", "dts].
+     */
     targets: Target[];
+    /**
+     * Add an extension to every import, for example ".js" or ".ts".
+     *
+     * The default is "".
+     */
+    importExtension: string;
+    /**
+     * Generate `import` statements or `require()` calls.
+     *
+     * The default is "module".
+     */
+    jsImportStyle: "module" | "legacy_commonjs";
+    /**
+     * Generate an annotation at the top of each file to skip type checks:
+     * `// @ts-nocheck`.
+     *
+     * The default is false.
+     */
     tsNocheck: boolean;
-    bootstrapWkt: boolean;
+    /**
+     * Prune empty files from the output.
+     *
+     * The default is false.
+     */
     keepEmptyFiles: boolean;
+    /**
+     * @private
+     */
+    bootstrapWkt: boolean;
+    /**
+     * @private
+     */
     rewriteImports: RewriteImports;
-    importExtension: string;
-    jsImportStyle: "module" | "legacy_commonjs";
-    sanitizedParameter: string;
 }
-export declare function parseParameter(parameter: string, parseExtraOption: ((key: string, value: string) => void) | undefined): ParsedParameter;
+export interface ParsedParameter<T> {
+    parsed: T & EcmaScriptPluginOptions;
+    sanitized: string;
+}
+/**
+ * Raw options to parse.
+ *
+ * For example, if a plugin is run with the options foo=123,bar,baz=a,baz=b
+ * the raw options are:
+ *
+ * ```ts
+ * [
+ *   { key: "foo", value: "123" },
+ *   { key: "bar", value: "" },
+ *   { key: "baz", value: "a" },
+ *   { key: "baz", value: "b" },
+ * ]
+ * ```
+ *
+ * If your plugin does not recognize an option, it must throw an Error in
+ * parseOptions.
+ */
+export type RawPluginOptions = {
+    key: string;
+    value: string;
+}[];
+export declare function parseParameter<T extends object>(parameter: string, parseExtraOptions: ((rawOptions: RawPluginOptions) => T) | undefined): ParsedParameter<T>;

package/dist/esm/parameter.js

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 import { PluginOptionError } from "./error.js";
-export function parseParameter(parameter, parseExtraOption) {
+export function parseParameter(parameter, parseExtraOptions) {
     let targets = ["js", "dts"];
     let tsNocheck = false;
     let bootstrapWkt = false;
@@ -20,6 +20,8 @@ export function parseParameter(parameter, parseExtraOption) {
     const rewriteImports = [];
     let importExtension = "";
     let jsImportStyle = "module";
+    const extraParameters = [];
+    const extraParametersRaw = [];
     const rawParameters = [];
     for (const { key, value, raw } of splitParameter(parameter)) {
         // Whether this key/value plugin parameter pair should be
@@ -115,23 +117,19 @@ export function parseParameter(parameter, parseExtraOption) {
                 break;
             }
             default:
-                if (parseExtraOption === undefined) {
+                if (parseExtraOptions === undefined) {
                     throw new PluginOptionError(raw);
                 }
-                try {
-                    parseExtraOption(key, value);
-                }
-                catch (e) {
-                    throw new PluginOptionError(raw, e);
-                }
+                extraParameters.push({ key, value });
+                extraParametersRaw.push(raw);
                 break;
         }
         if (!sanitize) {
             rawParameters.push(raw);
         }
     }
-    const sanitizedParameter = rawParameters.join(",");
-    return {
+    const sanitizedParameters = rawParameters.join(",");
+    const ecmaScriptPluginOptions = {
         targets,
         tsNocheck,
         bootstrapWkt,
@@ -139,8 +137,22 @@ export function parseParameter(parameter, parseExtraOption) {
         importExtension,
         jsImportStyle,
         keepEmptyFiles,
-        sanitizedParameter,
     };
+    if (parseExtraOptions === undefined || extraParameters.length === 0) {
+        return {
+            parsed: ecmaScriptPluginOptions,
+            sanitized: sanitizedParameters,
+        };
+    }
+    try {
+        return {
+            parsed: Object.assign(ecmaScriptPluginOptions, parseExtraOptions(extraParameters)),
+            sanitized: sanitizedParameters,
+        };
+    }
+    catch (err) {
+        throw new PluginOptionError(extraParametersRaw.join(","), err);
+    }
 }
 function splitParameter(parameter) {
     if (parameter.length == 0) {

package/dist/esm/printable.d.ts

@@ -3,7 +3,7 @@ import type { ImportSymbol } from "./import-symbol.js";
 /**
  * All types that can be passed to GeneratedFile.print()
  */
-export type Printable = string | number | boolean | bigint | Uint8Array | ImportSymbol | ExportStatement | JSDocBlock | LiteralString | LiteralProtoInt64 | DescImport | ShapeImport | Printable[];
+export type Printable = string | number | boolean | bigint | Uint8Array | ImportSymbol | ExportStatement | JSDocBlock | LiteralString | LiteralProtoInt64 | DescImport | ShapeImport | JsonTypeImport | Printable[];
 export type ExportStatement = {
     kind: "es_export_stmt";
     name: string;
@@ -28,6 +28,10 @@ export type ShapeImport = {
     readonly kind: "es_shape_ref";
     desc: DescMessage | DescEnum;
 };
+export type JsonTypeImport = {
+    readonly kind: "es_json_type_ref";
+    desc: DescMessage | DescEnum;
+};
 export type JSDocBlock = {
     readonly kind: "es_jsdoc";
     text: string;

package/dist/esm/run-node.js

@@ -13,7 +13,7 @@
 // limitations under the License.
 import { isPluginOptionError, reasonToString } from "./error.js";
 import { fromBinary, toBinary } from "@bufbuild/protobuf";
-import { CodeGeneratorRequestDesc, CodeGeneratorResponseDesc, } from "@bufbuild/protobuf/wkt";
+import { CodeGeneratorRequestSchema, CodeGeneratorResponseSchema, } from "@bufbuild/protobuf/wkt";
 /**
  * Run a plugin with Node.js.
  *
@@ -38,9 +38,9 @@ export function runNodeJs(plugin) {
     }
     readBytes(process.stdin)
         .then((data) => {
-        const req = fromBinary(CodeGeneratorRequestDesc, data);
+        const req = fromBinary(CodeGeneratorRequestSchema, data);
         const res = plugin.run(req);
-        return writeBytes(process.stdout, toBinary(CodeGeneratorResponseDesc, res));
+        return writeBytes(process.stdout, toBinary(CodeGeneratorResponseSchema, res));
     })
         .then(() => process.exit(0))
         .catch((reason) => {

package/dist/esm/schema.d.ts

@@ -3,12 +3,12 @@ import type { CodeGeneratorRequest } from "@bufbuild/protobuf/wkt";
 import { Edition } from "@bufbuild/protobuf/wkt";
 import type { FileInfo, GeneratedFile } from "./generated-file.js";
 import type { Target } from "./target.js";
-import type { ParsedParameter } from "./parameter.js";
+import type { EcmaScriptPluginOptions, ParsedParameter } from "./parameter.js";
 /**
  * Schema describes the files and types that the plugin is requested to
  * generate.
  */
-export interface Schema {
+export interface Schema<Options extends object = object> {
     /**
      * The files we are asked to generate.
      */
@@ -21,6 +21,11 @@ export interface Schema {
      * The plugin option `target`. A code generator should support all targets.
      */
     readonly targets: readonly Target[];
+    /**
+     * Parsed plugin options. They include the standard options for all
+     * plugins, and options parsed by your plugin.
+     */
+    readonly options: Options & EcmaScriptPluginOptions;
     /**
      * Generate a new file with the given name.
      */
@@ -35,9 +40,9 @@ export interface Schema {
      */
     readonly proto: CodeGeneratorRequest;
 }
-interface SchemaController extends Schema {
+interface SchemaController<Options extends object> extends Schema<Options> {
     getFileInfo: () => FileInfo[];
     prepareGenerate(target: Target): void;
 }
-export declare function createSchema(request: CodeGeneratorRequest, parameter: ParsedParameter, pluginName: string, pluginVersion: string, minimumEdition: Edition, maximumEdition: Edition): SchemaController;
+export declare function createSchema<T extends object>(request: CodeGeneratorRequest, parameter: ParsedParameter<T>, pluginName: string, pluginVersion: string, minimumEdition: Edition, maximumEdition: Edition): SchemaController<T>;
 export {};

package/dist/esm/schema.js

@@ -12,42 +12,44 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 import { create, createFileRegistry } from "@bufbuild/protobuf";
-import { Edition, FileDescriptorSetDesc } from "@bufbuild/protobuf/wkt";
+import { Edition, FileDescriptorSetSchema } from "@bufbuild/protobuf/wkt";
 import { nestedTypes } from "@bufbuild/protobuf/reflect";
 import { createGeneratedFile } from "./generated-file.js";
 import { createImportSymbol } from "./import-symbol.js";
 import { deriveImportPath, rewriteImportPath } from "./import-path.js";
 import { makeFilePreamble } from "./file-preamble.js";
-import { localDescName, localShapeName, generateFilePath } from "./names.js";
+import { generatedDescName, generatedShapeName, generateFilePath, generatedJsonTypeName, } from "./names.js";
 import { createRuntimeImports } from "./runtime-imports.js";
 export function createSchema(request, parameter, pluginName, pluginVersion, minimumEdition, maximumEdition) {
     const { allFiles, filesToGenerate } = getFilesToGenerate(request, minimumEdition, maximumEdition);
     let target;
     const generatedFiles = [];
-    const runtime = createRuntimeImports(parameter.bootstrapWkt);
-    const resolveDescImport = (desc, typeOnly) => createImportSymbol(localDescName(desc), generateFilePath(desc.kind == "file" ? desc : desc.file, parameter.bootstrapWkt, filesToGenerate), typeOnly);
-    const resolveShapeImport = (desc) => createImportSymbol(localShapeName(desc), generateFilePath(desc.file, parameter.bootstrapWkt, filesToGenerate), true);
-    const createPreamble = (descFile) => makeFilePreamble(descFile, pluginName, pluginVersion, parameter.sanitizedParameter, parameter.tsNocheck);
-    const rewriteImport = (importPath) => rewriteImportPath(importPath, parameter.rewriteImports, parameter.importExtension);
+    const runtime = createRuntimeImports(parameter.parsed.bootstrapWkt);
+    const resolveDescImport = (desc, typeOnly) => createImportSymbol(generatedDescName(desc), generateFilePath(desc.kind == "file" ? desc : desc.file, parameter.parsed.bootstrapWkt, filesToGenerate), typeOnly);
+    const resolveShapeImport = (desc) => createImportSymbol(generatedShapeName(desc), generateFilePath(desc.file, parameter.parsed.bootstrapWkt, filesToGenerate), true);
+    const resolveJsonImport = (desc) => createImportSymbol(generatedJsonTypeName(desc), generateFilePath(desc.file, parameter.parsed.bootstrapWkt, filesToGenerate), true);
+    const createPreamble = (descFile) => makeFilePreamble(descFile, pluginName, pluginVersion, parameter.sanitized, parameter.parsed.tsNocheck);
+    const rewriteImport = (importPath) => rewriteImportPath(importPath, parameter.parsed.rewriteImports, parameter.parsed.importExtension);
     return {
-        targets: parameter.targets,
+        targets: parameter.parsed.targets,
         proto: request,
         files: filesToGenerate,
         allFiles: allFiles,
+        options: parameter.parsed,
         typesInFile: nestedTypes,
         generateFile(name) {
             if (target === undefined) {
                 throw new Error("prepareGenerate() must be called before generateFile()");
             }
-            const genFile = createGeneratedFile(name, deriveImportPath(name), target === "js" ? parameter.jsImportStyle : "module", // ts and dts always use import/export, only js may use commonjs
-            rewriteImport, resolveDescImport, resolveShapeImport, createPreamble, runtime);
+            const genFile = createGeneratedFile(name, deriveImportPath(name), target === "js" ? parameter.parsed.jsImportStyle : "module", // ts and dts always use import/export, only js may use commonjs
+            rewriteImport, resolveDescImport, resolveShapeImport, resolveJsonImport, createPreamble, runtime);
             generatedFiles.push(genFile);
             return genFile;
         },
         getFileInfo() {
             return generatedFiles
                 .map((f) => f.getFileInfo())
-                .filter((fi) => parameter.keepEmptyFiles || fi.content.length > 0);
+                .filter((fi) => parameter.parsed.keepEmptyFiles || fi.content.length > 0);
         },
         prepareGenerate(newTarget) {
             target = newTarget;
@@ -96,7 +98,7 @@ function getFilesToGenerate(request, minimumEdition, maximumEdition) {
         const sourceFile = request.sourceFileDescriptors.find((s) => s.name == protoFile.name);
         return sourceFile !== null && sourceFile !== void 0 ? sourceFile : protoFile;
     });
-    const registry = createFileRegistry(create(FileDescriptorSetDesc, {
+    const registry = createFileRegistry(create(FileDescriptorSetSchema, {
         file: allProtoWithSourceOptions,
     }));
     const allFiles = [];

package/dist/esm/source-code-info.js

@@ -13,13 +13,13 @@
 // limitations under the License.
 import { isFieldSet, ScalarType, } from "@bufbuild/protobuf";
 import { protoCamelCase, reflect } from "@bufbuild/protobuf/reflect";
-import { Edition, FieldDescriptorProto_Label, FieldDescriptorProto_Type, FieldDescriptorProtoDesc, FieldOptions_JSType, FieldOptionsDesc, FeatureSetDesc, SourceCodeInfo_LocationDesc, FileDescriptorProtoDesc, DescriptorProtoDesc, EnumDescriptorProtoDesc, ServiceDescriptorProtoDesc, } from "@bufbuild/protobuf/wkt";
+import { Edition, FieldDescriptorProto_Label, FieldDescriptorProto_Type, FieldDescriptorProtoSchema, FieldOptions_JSType, FieldOptionsSchema, FeatureSetSchema, SourceCodeInfo_LocationSchema, FileDescriptorProtoSchema, DescriptorProtoSchema, EnumDescriptorProtoSchema, ServiceDescriptorProtoSchema, } from "@bufbuild/protobuf/wkt";
 /**
  * Get comments on the package element in the protobuf source.
  */
 export function getPackageComments(desc) {
     return findComments(desc.proto.sourceCodeInfo, [
-        FileDescriptorProtoDesc.field.package.number,
+        FileDescriptorProtoSchema.field.package.number,
     ]);
 }
 /**
@@ -27,7 +27,7 @@ export function getPackageComments(desc) {
  */
 export function getSyntaxComments(desc) {
     return findComments(desc.proto.sourceCodeInfo, [
-        FileDescriptorProtoDesc.field.syntax.number,
+        FileDescriptorProtoSchema.field.syntax.number,
     ]);
 }
 /**
@@ -41,11 +41,11 @@ export function getComments(desc) {
             path = desc.parent
                 ? [
                     ...getComments(desc.parent).sourcePath,
-                    DescriptorProtoDesc.field.enumType.number,
+                    DescriptorProtoSchema.field.enumType.number,
                     desc.parent.proto.enumType.indexOf(desc.proto),
                 ]
                 : [
-                    FileDescriptorProtoDesc.field.enumType.number,
+                    FileDescriptorProtoSchema.field.enumType.number,
                     desc.file.proto.enumType.indexOf(desc.proto),
                 ];
             file = desc.file;
@@ -53,7 +53,7 @@ export function getComments(desc) {
         case "oneof":
             path = [
                 ...getComments(desc.parent).sourcePath,
-                DescriptorProtoDesc.field.oneofDecl.number,
+                DescriptorProtoSchema.field.oneofDecl.number,
                 desc.parent.proto.oneofDecl.indexOf(desc.proto),
             ];
             file = desc.parent.file;
@@ -62,11 +62,11 @@ export function getComments(desc) {
             path = desc.parent
                 ? [
                     ...getComments(desc.parent).sourcePath,
-                    DescriptorProtoDesc.field.nestedType.number,
+                    DescriptorProtoSchema.field.nestedType.number,
                     desc.parent.proto.nestedType.indexOf(desc.proto),
                 ]
                 : [
-                    FileDescriptorProtoDesc.field.messageType.number,
+                    FileDescriptorProtoSchema.field.messageType.number,
                     desc.file.proto.messageType.indexOf(desc.proto),
                 ];
             file = desc.file;
@@ -74,7 +74,7 @@ export function getComments(desc) {
         case "enum_value":
             path = [
                 ...getComments(desc.parent).sourcePath,
-                EnumDescriptorProtoDesc.field.value.number,
+                EnumDescriptorProtoSchema.field.value.number,
                 desc.parent.proto.value.indexOf(desc.proto),
             ];
             file = desc.parent.file;
@@ -82,7 +82,7 @@ export function getComments(desc) {
         case "field":
             path = [
                 ...getComments(desc.parent).sourcePath,
-                DescriptorProtoDesc.field.field.number,
+                DescriptorProtoSchema.field.field.number,
                 desc.parent.proto.field.indexOf(desc.proto),
             ];
             file = desc.parent.file;
@@ -91,18 +91,18 @@ export function getComments(desc) {
             path = desc.parent
                 ? [
                     ...getComments(desc.parent).sourcePath,
-                    DescriptorProtoDesc.field.extension.number,
+                    DescriptorProtoSchema.field.extension.number,
                     desc.parent.proto.extension.indexOf(desc.proto),
                 ]
                 : [
-                    FileDescriptorProtoDesc.field.extension.number,
+                    FileDescriptorProtoSchema.field.extension.number,
                     desc.file.proto.extension.indexOf(desc.proto),
                 ];
             file = desc.file;
             break;
         case "service":
             path = [
-                FileDescriptorProtoDesc.field.service.number,
+                FileDescriptorProtoSchema.field.service.number,
                 desc.file.proto.service.indexOf(desc.proto),
             ];
             file = desc.file;
@@ -110,7 +110,7 @@ export function getComments(desc) {
         case "rpc":
             path = [
                 ...getComments(desc.parent).sourcePath,
-                ServiceDescriptorProtoDesc.field.method.number,
+                ServiceDescriptorProtoSchema.field.method.number,
                 desc.parent.proto.method.indexOf(desc.proto),
             ];
             file = desc.parent.file;
@@ -127,7 +127,7 @@ export function getFeatureOptionStrings(desc) {
     const strings = [];
     const features = (_a = desc.proto.options) === null || _a === void 0 ? void 0 : _a.features;
     if (features !== undefined) {
-        const r = reflect(FeatureSetDesc, features);
+        const r = reflect(FeatureSetSchema, features);
         for (const f of r.fields) {
             if (f.fieldKind != "enum" || !r.isSet(f)) {
                 continue;
@@ -190,10 +190,10 @@ export function getDeclarationString(desc) {
     const options = [];
     const protoOptions = desc.proto.options;
     if (protoOptions !== undefined &&
-        isFieldSet(protoOptions, FieldOptionsDesc.field.packed)) {
+        isFieldSet(protoOptions, FieldOptionsSchema.field.packed)) {
         options.push(`packed = ${protoOptions.packed.toString()}`);
     }
-    if (isFieldSet(desc.proto, FieldDescriptorProtoDesc.field.defaultValue)) {
+    if (isFieldSet(desc.proto, FieldDescriptorProtoSchema.field.defaultValue)) {
         let defaultValue = desc.proto.defaultValue;
         if (desc.proto.type == FieldDescriptorProto_Type.BYTES ||
             desc.proto.type == FieldDescriptorProto_Type.STRING) {
@@ -205,11 +205,11 @@ export function getDeclarationString(desc) {
         options.push(`json_name = "${desc.jsonName}"`);
     }
     if (protoOptions !== undefined &&
-        isFieldSet(protoOptions, FieldOptionsDesc.field.jstype)) {
+        isFieldSet(protoOptions, FieldOptionsSchema.field.jstype)) {
         options.push(`jstype = ${FieldOptions_JSType[protoOptions.jstype]}`);
     }
     if (protoOptions !== undefined &&
-        isFieldSet(protoOptions, FieldOptionsDesc.field.deprecated)) {
+        isFieldSet(protoOptions, FieldOptionsSchema.field.deprecated)) {
         options.push(`deprecated = true`);
     }
     options.push(...getFeatureOptionStrings(desc));
@@ -262,10 +262,10 @@ function findComments(sourceCodeInfo, sourcePath) {
         }
         return {
             leadingDetached: location.leadingDetachedComments,
-            leading: isFieldSet(location, SourceCodeInfo_LocationDesc.field.leadingComments)
+            leading: isFieldSet(location, SourceCodeInfo_LocationSchema.field.leadingComments)
                 ? location.leadingComments
                 : undefined,
-            trailing: isFieldSet(location, SourceCodeInfo_LocationDesc.field.trailingComments)
+            trailing: isFieldSet(location, SourceCodeInfo_LocationSchema.field.trailingComments)
                 ? location.trailingComments
                 : undefined,
             sourcePath,

package/dist/esm/transpile.js

@@ -20,7 +20,7 @@ const defaultOptions = {
     strict: false,
     // modules
     module: ts.ModuleKind.ES2020,
-    moduleResolution: ts.ModuleResolutionKind.NodeJs,
+    moduleResolution: ts.ModuleResolutionKind.Node10,
     noResolve: true,
     resolveJsonModule: false,
     // emit
@@ -33,7 +33,7 @@ const defaultOptions = {
     checkJs: false,
     // Language and Environment
     lib: [],
-    moduleDetection: "force",
+    moduleDetection: ts.ModuleDetectionKind.Force,
     target: ts.ScriptTarget.ES2017,
     // Completeness
     skipLibCheck: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bufbuild/protoplugin",
-  "version": "2.0.0-alpha.4",
+  "version": "2.0.0-beta.1",
   "license": "(Apache-2.0 AND BSD-3-Clause)",
   "description": "Helps to create your own Protocol Buffers code generators.",
   "repository": {
@@ -25,9 +25,9 @@
     }
   },
   "dependencies": {
-    "@bufbuild/protobuf": "2.0.0-alpha.4",
-    "@typescript/vfs": "^1.4.0",
-    "typescript": "4.5.2"
+    "@bufbuild/protobuf": "2.0.0-beta.1",
+    "@typescript/vfs": "^1.5.2",
+    "typescript": "5.4.5"
   },
   "files": [
     "dist/**"