@bufbuild/protoplugin 1.5.1 → 1.6.0

package/dist/cjs/ecmascript/index.js

@@ -13,19 +13,41 @@
 // 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 = exports.reifyWkt = void 0;
+exports.createJsDocBlock = exports.makeJsDoc = exports.literalString = exports.findCustomEnumOption = exports.findCustomMessageOption = exports.findCustomScalarOption = exports.getFieldTyping = exports.getFieldIntrinsicDefaultValue = exports.getFieldExplicitDefaultValue = exports.localName = exports.createImportSymbol = exports.reifyWkt = void 0;
 const protobuf_1 = require("@bufbuild/protobuf");
+const jsdoc_js_1 = require("./jsdoc.js");
+const gencommon_js_1 = require("./gencommon.js");
 var reify_wkt_js_1 = require("./reify-wkt.js");
 Object.defineProperty(exports, "reifyWkt", { enumerable: true, get: function () { return reify_wkt_js_1.reifyWkt; } });
+var import_symbol_js_1 = require("./import-symbol.js");
+Object.defineProperty(exports, "createImportSymbol", { enumerable: true, get: function () { return import_symbol_js_1.createImportSymbol; } });
 exports.localName = protobuf_1.codegenInfo.localName;
-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; } });
-Object.defineProperty(exports, "getFieldIntrinsicDefaultValue", { enumerable: true, get: function () { return gencommon_js_1.getFieldIntrinsicDefaultValue; } });
-Object.defineProperty(exports, "getFieldTyping", { enumerable: true, get: function () { return gencommon_js_1.getFieldTyping; } });
-Object.defineProperty(exports, "makeJsDoc", { enumerable: true, get: function () { return gencommon_js_1.makeJsDoc; } });
-Object.defineProperty(exports, "literalString", { enumerable: true, get: function () { return gencommon_js_1.literalString; } });
+var gencommon_js_2 = require("./gencommon.js");
+Object.defineProperty(exports, "getFieldExplicitDefaultValue", { enumerable: true, get: function () { return gencommon_js_2.getFieldExplicitDefaultValue; } });
+Object.defineProperty(exports, "getFieldIntrinsicDefaultValue", { enumerable: true, get: function () { return gencommon_js_2.getFieldIntrinsicDefaultValue; } });
+Object.defineProperty(exports, "getFieldTyping", { enumerable: true, get: function () { return gencommon_js_2.getFieldTyping; } });
 var custom_options_js_1 = require("./custom-options.js");
 Object.defineProperty(exports, "findCustomScalarOption", { enumerable: true, get: function () { return custom_options_js_1.findCustomScalarOption; } });
 Object.defineProperty(exports, "findCustomMessageOption", { enumerable: true, get: function () { return custom_options_js_1.findCustomMessageOption; } });
 Object.defineProperty(exports, "findCustomEnumOption", { enumerable: true, get: function () { return custom_options_js_1.findCustomEnumOption; } });
+/**
+ * @deprecated Please use GeneratedFile.string() instead
+ */
+function literalString(value) {
+    return (0, gencommon_js_1.literalString)(value);
+}
+exports.literalString = literalString;
+/**
+ * @deprecated Please use GeneratedFile.jsDoc() instead
+ */
+function makeJsDoc(desc, indentation = "") {
+    return (0, jsdoc_js_1.createJsDocBlock)(desc, indentation).toString();
+}
+exports.makeJsDoc = makeJsDoc;
+/**
+ * @deprecated Please use GeneratedFile.jsDoc() instead
+ */
+function createJsDocBlock(text, indentation = "") {
+    return (0, jsdoc_js_1.createJsDocBlock)(text, indentation).toString();
+}
+exports.createJsDocBlock = createJsDocBlock;

package/dist/cjs/ecmascript/jsdoc.d.ts

@@ -0,0 +1,8 @@
+import type { AnyDesc, DescExtension, DescFile } from "@bufbuild/protobuf";
+export type JSDocBlock = {
+    readonly kind: "es_jsdoc";
+    text: string;
+    indentation?: string;
+    toString(): string;
+};
+export declare function createJsDocBlock(textOrDesc: string | Exclude<AnyDesc, DescFile | DescExtension>, indentation?: string): JSDocBlock;

package/dist/cjs/ecmascript/jsdoc.js

@@ -0,0 +1,90 @@
+"use strict";
+// Copyright 2021-2023 Buf Technologies, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createJsDocBlock = void 0;
+function createJsDocBlock(textOrDesc, indentation) {
+    const text = typeof textOrDesc == "string" ? textOrDesc : createTextForDesc(textOrDesc);
+    return {
+        kind: "es_jsdoc",
+        text,
+        indentation,
+        toString() {
+            if (text.trim().length == 0) {
+                return "";
+            }
+            let lines = text.split("\n");
+            if (lines.length === 0) {
+                return "";
+            }
+            lines = lines.map((l) => l.split("*/").join("*\\/"));
+            lines = lines.map((l) => (l.length > 0 ? " " + l : l));
+            const i = indentation !== null && indentation !== void 0 ? indentation : "";
+            return [`${i}/**\n`, ...lines.map((l) => `${i} *${l}\n`), `${i} */`].join("");
+        },
+    };
+}
+exports.createJsDocBlock = createJsDocBlock;
+function createTextForDesc(desc) {
+    var _a, _b;
+    const comments = desc.getComments();
+    let text = "";
+    if (comments.leading !== undefined) {
+        text += comments.leading;
+        if (text.endsWith("\n")) {
+            text = text.substring(0, text.length - 1);
+        }
+    }
+    if (comments.trailing !== undefined) {
+        if (text.length > 0) {
+            text += "\n\n";
+        }
+        text += comments.trailing;
+        if (text.endsWith("\n")) {
+            text = text.substring(0, text.length - 1);
+        }
+    }
+    if (text.length > 0) {
+        text += "\n\n";
+    }
+    text = text
+        .split("\n")
+        .map((line) => (line.startsWith(" ") ? line.substring(1) : line))
+        .join("\n");
+    switch (desc.kind) {
+        case "enum_value":
+            text += `@generated from enum value: ${desc.declarationString()};`;
+            break;
+        case "field":
+            text += `@generated from field: ${desc.declarationString()};`;
+            break;
+        default:
+            text += `@generated from ${desc.toString()}`;
+            break;
+    }
+    let deprecated = desc.deprecated;
+    switch (desc.kind) {
+        case "enum":
+        case "message":
+        case "service":
+            deprecated = deprecated || ((_b = (_a = desc.file.proto.options) === null || _a === void 0 ? void 0 : _a.deprecated) !== null && _b !== void 0 ? _b : false);
+            break;
+        default:
+            break;
+    }
+    if (deprecated) {
+        text += "\n@deprecated";
+    }
+    return text;
+}

package/dist/cjs/ecmascript/parameter.d.ts

@@ -0,0 +1,13 @@
+import { Target } from "./target.js";
+import { RewriteImports } from "./import-path.js";
+export interface ParsedParameter {
+    targets: Target[];
+    tsNocheck: boolean;
+    bootstrapWkt: boolean;
+    keepEmptyFiles: boolean;
+    rewriteImports: RewriteImports;
+    importExtension: string;
+    jsImportStyle: "module" | "legacy_commonjs";
+    sanitizedParameter: string;
+}
+export declare function parseParameter(parameter: string | undefined, parseExtraOption: ((key: string, value: string) => void) | undefined): ParsedParameter;

package/dist/cjs/ecmascript/parameter.js

@@ -0,0 +1,161 @@
+"use strict";
+// Copyright 2021-2023 Buf Technologies, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseParameter = void 0;
+const error_js_1 = require("../error.js");
+function parseParameter(parameter, parseExtraOption) {
+    let targets = ["js", "dts"];
+    let tsNocheck = true;
+    let bootstrapWkt = false;
+    let keepEmptyFiles = false;
+    const rewriteImports = [];
+    let importExtension = ".js";
+    let jsImportStyle = "module";
+    const rawParameters = [];
+    for (const { key, value, raw } of splitParameter(parameter)) {
+        // Whether this key/value plugin parameter pair should be
+        // printed to the generated file preamble
+        let sanitize = false;
+        switch (key) {
+            case "target":
+                targets = [];
+                for (const rawTarget of value.split("+")) {
+                    switch (rawTarget) {
+                        case "js":
+                        case "ts":
+                        case "dts":
+                            if (targets.indexOf(rawTarget) < 0) {
+                                targets.push(rawTarget);
+                            }
+                            break;
+                        default:
+                            throw new error_js_1.PluginOptionError(raw);
+                    }
+                }
+                value.split("+");
+                break;
+            case "ts_nocheck":
+                switch (value) {
+                    case "true":
+                    case "1":
+                        tsNocheck = true;
+                        break;
+                    case "false":
+                    case "0":
+                        tsNocheck = false;
+                        break;
+                    default:
+                        throw new error_js_1.PluginOptionError(raw);
+                }
+                break;
+            case "bootstrap_wkt":
+                switch (value) {
+                    case "true":
+                    case "1":
+                        bootstrapWkt = true;
+                        break;
+                    case "false":
+                    case "0":
+                        bootstrapWkt = false;
+                        break;
+                    default:
+                        throw new error_js_1.PluginOptionError(raw);
+                }
+                break;
+            case "rewrite_imports": {
+                const parts = value.split(":");
+                if (parts.length !== 2) {
+                    throw new error_js_1.PluginOptionError(raw, "must be in the form of <pattern>:<target>");
+                }
+                const [pattern, target] = parts;
+                rewriteImports.push({ pattern, target });
+                // rewrite_imports can be noisy and is more of an implementation detail
+                // so we strip it out of the preamble
+                sanitize = true;
+                break;
+            }
+            case "import_extension": {
+                importExtension = value === "none" ? "" : value;
+                break;
+            }
+            case "js_import_style":
+                switch (value) {
+                    case "module":
+                        jsImportStyle = value;
+                        break;
+                    case "legacy_commonjs":
+                        jsImportStyle = value;
+                        break;
+                    default:
+                        throw new error_js_1.PluginOptionError(raw);
+                }
+                break;
+            case "keep_empty_files": {
+                switch (value) {
+                    case "true":
+                    case "1":
+                        keepEmptyFiles = true;
+                        break;
+                    case "false":
+                    case "0":
+                        keepEmptyFiles = false;
+                        break;
+                    default:
+                        throw new error_js_1.PluginOptionError(raw);
+                }
+                break;
+            }
+            default:
+                if (parseExtraOption === undefined) {
+                    throw new error_js_1.PluginOptionError(raw);
+                }
+                try {
+                    parseExtraOption(key, value);
+                }
+                catch (e) {
+                    throw new error_js_1.PluginOptionError(raw, e);
+                }
+                break;
+        }
+        if (!sanitize) {
+            rawParameters.push(raw);
+        }
+    }
+    const sanitizedParameter = rawParameters.join(",");
+    return {
+        targets,
+        tsNocheck,
+        bootstrapWkt,
+        rewriteImports,
+        importExtension,
+        jsImportStyle,
+        keepEmptyFiles,
+        sanitizedParameter,
+    };
+}
+exports.parseParameter = parseParameter;
+function splitParameter(parameter) {
+    if (parameter == undefined) {
+        return [];
+    }
+    return parameter.split(",").map((raw) => {
+        const i = raw.indexOf("=");
+        return {
+            key: i === -1 ? raw : raw.substring(0, i),
+            value: i === -1 ? "" : raw.substring(i + 1),
+            raw,
+        };
+    });
+}

package/dist/cjs/ecmascript/schema.d.ts

@@ -1,9 +1,8 @@
 import type { CodeGeneratorRequest, DescFile } from "@bufbuild/protobuf";
-import { CodeGeneratorResponse } from "@bufbuild/protobuf";
 import type { FileInfo, GeneratedFile } from "./generated-file.js";
 import { RuntimeImports } from "./runtime-imports.js";
 import type { Target } from "./target.js";
-import { RewriteImports } from "./import-path.js";
+import { ParsedParameter } from "./parameter";
 /**
  * Schema describes the files and types that the plugin is requested to
  * generate.
@@ -34,10 +33,9 @@ export interface Schema {
      */
     readonly proto: CodeGeneratorRequest;
 }
-interface SchemaController {
-    schema: Schema;
+interface SchemaController extends Schema {
     getFileInfo: () => FileInfo[];
+    prepareGenerate(target: Target): void;
 }
-export declare function createSchema(request: CodeGeneratorRequest, targets: Target[], tsNocheck: boolean, bootstrapWkt: boolean, rewriteImports: RewriteImports, importExtension: string, keepEmptyFiles: boolean, pluginName: string, pluginVersion: string, pluginParameter: string): SchemaController;
-export declare function toResponse(files: FileInfo[]): CodeGeneratorResponse;
+export declare function createSchema(request: CodeGeneratorRequest, parameter: ParsedParameter, pluginName: string, pluginVersion: string): SchemaController;
 export {};

package/dist/cjs/ecmascript/schema.js

@@ -13,66 +13,54 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.toResponse = exports.createSchema = void 0;
+exports.createSchema = void 0;
 const protobuf_1 = require("@bufbuild/protobuf");
 const generated_file_js_1 = require("./generated-file.js");
 const runtime_imports_js_1 = require("./runtime-imports.js");
 const import_symbol_js_1 = require("./import-symbol.js");
 const import_path_js_1 = require("./import-path.js");
-function createSchema(request, targets, tsNocheck, bootstrapWkt, rewriteImports, importExtension, keepEmptyFiles, pluginName, pluginVersion, pluginParameter) {
+function createSchema(request, parameter, pluginName, pluginVersion) {
     const descriptorSet = (0, protobuf_1.createDescriptorSet)(request.protoFile);
     const filesToGenerate = findFilesToGenerate(descriptorSet, request);
-    const runtime = (0, runtime_imports_js_1.createRuntimeImports)(bootstrapWkt);
+    const runtime = (0, runtime_imports_js_1.createRuntimeImports)(parameter.bootstrapWkt);
     const createTypeImport = (desc) => {
         const name = protobuf_1.codegenInfo.localName(desc);
-        const from = (0, import_path_js_1.makeImportPath)(desc.file, bootstrapWkt, filesToGenerate);
+        const from = (0, import_path_js_1.makeImportPath)(desc.file, parameter.bootstrapWkt, filesToGenerate);
         return (0, import_symbol_js_1.createImportSymbol)(name, from);
     };
+    let target;
     const generatedFiles = [];
-    const schema = {
-        targets,
+    return {
+        targets: parameter.targets,
         runtime,
         proto: request,
         files: filesToGenerate,
         allFiles: descriptorSet.files,
         generateFile(name) {
-            const genFile = (0, generated_file_js_1.createGeneratedFile)(name, (0, import_path_js_1.deriveImportPath)(name), (importPath) => (0, import_path_js_1.rewriteImportPath)(importPath, rewriteImports, importExtension), createTypeImport, runtime, {
+            if (target === undefined) {
+                throw new Error("prepareGenerate() must be called before generateFile()");
+            }
+            const genFile = (0, generated_file_js_1.createGeneratedFile)(name, (0, import_path_js_1.deriveImportPath)(name), target === "js" ? parameter.jsImportStyle : "module", // ts and dts always use import/export, only js may use commonjs
+            (importPath) => (0, import_path_js_1.rewriteImportPath)(importPath, parameter.rewriteImports, parameter.importExtension), createTypeImport, runtime, {
                 pluginName,
                 pluginVersion,
-                pluginParameter,
-                tsNocheck,
-            }, keepEmptyFiles);
+                pluginParameter: parameter.sanitizedParameter,
+                tsNocheck: parameter.tsNocheck,
+            });
             generatedFiles.push(genFile);
             return genFile;
         },
-    };
-    return {
-        schema,
         getFileInfo() {
-            return generatedFiles.flatMap((file) => {
-                const fileInfo = file.getFileInfo();
-                // undefined is returned if the file has no content
-                if (!fileInfo) {
-                    return [];
-                }
-                return [fileInfo];
-            });
+            return generatedFiles
+                .map((f) => f.getFileInfo())
+                .filter((fi) => parameter.keepEmptyFiles || fi.content.length > 0);
+        },
+        prepareGenerate(newTarget) {
+            target = newTarget;
         },
     };
 }
 exports.createSchema = createSchema;
-function toResponse(files) {
-    return new protobuf_1.CodeGeneratorResponse({
-        supportedFeatures: protobuf_1.protoInt64.parse(protobuf_1.CodeGeneratorResponse_Feature.PROTO3_OPTIONAL),
-        file: files.map((f) => {
-            if (f.preamble !== undefined) {
-                f.content = f.preamble + "\n" + f.content;
-            }
-            return f;
-        }),
-    });
-}
-exports.toResponse = toResponse;
 function findFilesToGenerate(descriptorSet, request) {
     const missing = request.fileToGenerate.filter((fileToGenerate) => descriptorSet.files.every((file) => fileToGenerate !== file.name + ".proto"));
     if (missing.length) {

package/dist/cjs/ecmascript/transpile.d.ts

@@ -1,2 +1,2 @@
 import type { FileInfo } from "./generated-file.js";
-export declare function transpile(files: FileInfo[], transpileJs: boolean, transpileDts: boolean): FileInfo[];
+export declare function transpile(files: FileInfo[], transpileJs: boolean, transpileDts: boolean, jsImportStyle: "module" | "legacy_commonjs"): FileInfo[];

package/dist/cjs/ecmascript/transpile.js

@@ -82,8 +82,11 @@ function createTranspiler(options, files) {
         host: host.compilerHost,
     });
 }
-function transpile(files, transpileJs, transpileDts) {
+function transpile(files, transpileJs, transpileDts, jsImportStyle) {
     const options = Object.assign(Object.assign({}, defaultOptions), { declaration: transpileDts, emitDeclarationOnly: transpileDts && !transpileJs });
+    if (jsImportStyle == "legacy_commonjs") {
+        options.module = typescript_1.default.ModuleKind.CommonJS;
+    }
     // Create the transpiler (a ts.Program object)
     const program = createTranspiler(options, files);
     const results = [];

package/dist/cjs/index.d.ts

@@ -1,4 +1,8 @@
+import { Schema as SchemaInternal } from "./ecmascript/schema.js";
 export { Plugin } from "./plugin.js";
-export { Schema } from "./ecmascript/schema.js";
 export { runNodeJs } from "./run-node.js";
 export { createEcmaScriptPlugin } from "./create-es-plugin.js";
+/**
+ * @deprecated Please use Schema from @bufbuild/protoplugin/ecmascript instead
+ */
+export type Schema = SchemaInternal;

package/dist/esm/create-es-plugin.d.ts

@@ -45,14 +45,19 @@ interface PluginInit {
      */
     generateDts?: (schema: Schema, target: "dts") => void;
     /**
-     * A optional function which will transpile a given set of files.
+     * An optional function which will transpile a given set of files.
      *
-     * This funcion is meant to be used in place of either generateJs,
+     * This function is meant to be used in place of either generateJs,
      * generateDts, or both.  However, those functions will take precedence.
      * This means that if generateJs, generateDts, and this transpile function
      * are all provided, this transpile function will be ignored.
+     *
+     * If jsImportStyle is "module" (the standard behavior), the function is
+     * expected to use ECMAScript module import and export statements when
+     * transpiling to JS. If jsImportStyle is "legacy_commonjs", the function is
+     * expected to use CommonJs require() and exports when transpiling to JS.
      */
-    transpile?: (files: FileInfo[], transpileJs: boolean, transpileDts: boolean) => FileInfo[];
+    transpile?: (files: FileInfo[], transpileJs: boolean, transpileDts: boolean, jsImportStyle: "module" | "legacy_commonjs") => FileInfo[];
 }
 /**
  * Create a new code generator plugin for ECMAScript.