@bufbuild/protoplugin 1.9.0 → 2.0.0-alpha.1

package/dist/esm/ecmascript/printable.d.ts

@@ -0,0 +1,36 @@
+import type { DescEnum, DescExtension, DescFile, DescMessage, DescService } from "@bufbuild/protobuf";
+import { ScalarType, LongType } from "@bufbuild/protobuf/reflect";
+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 ExportStatement = {
+    kind: "es_export_stmt";
+    name: string;
+    declaration?: string;
+};
+export type LiteralProtoInt64 = {
+    readonly kind: "es_proto_int64";
+    type: ScalarType.INT64 | ScalarType.SINT64 | ScalarType.SFIXED64 | ScalarType.UINT64 | ScalarType.FIXED64;
+    longType: LongType;
+    value: bigint | string;
+};
+export type LiteralString = {
+    readonly kind: "es_string";
+    value: string;
+};
+export type DescImport = {
+    readonly kind: "es_desc_ref";
+    desc: DescMessage | DescEnum | DescExtension | DescService | DescFile;
+    typeOnly?: boolean;
+};
+export type ShapeImport = {
+    readonly kind: "es_shape_ref";
+    desc: DescMessage | DescEnum;
+};
+export type JSDocBlock = {
+    readonly kind: "es_jsdoc";
+    text: string;
+    indentation?: string;
+};

package/dist/esm/ecmascript/{opaque-printables.js → printable.js}

@@ -11,4 +11,4 @@
 // 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.
-import { LongType, ScalarType } from "@bufbuild/protobuf";
+import { ScalarType, LongType } from "@bufbuild/protobuf/reflect";

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

@@ -1,25 +1,14 @@
 import type { ImportSymbol } from "./import-symbol.js";
-export interface RuntimeImports {
-    proto2: ImportSymbol;
-    proto3: ImportSymbol;
-    Message: ImportSymbol;
-    PartialMessage: ImportSymbol;
-    PlainMessage: ImportSymbol;
-    FieldList: ImportSymbol;
-    MessageType: ImportSymbol;
-    Extension: ImportSymbol;
-    BinaryReadOptions: ImportSymbol;
-    BinaryWriteOptions: ImportSymbol;
-    JsonReadOptions: ImportSymbol;
-    JsonWriteOptions: ImportSymbol;
-    JsonValue: ImportSymbol;
-    JsonObject: ImportSymbol;
-    protoDouble: ImportSymbol;
-    protoInt64: ImportSymbol;
-    ScalarType: ImportSymbol;
-    LongType: ImportSymbol;
-    MethodKind: ImportSymbol;
-    MethodIdempotency: ImportSymbol;
-    IMessageTypeRegistry: ImportSymbol;
-}
+import { symbols } from "@bufbuild/protobuf/codegenv1";
+export type RuntimeImports = mapRecord<typeof symbols>;
 export declare function createRuntimeImports(bootstrapWkt: boolean): RuntimeImports;
+type mapRecord<T extends Record<string, unknown>> = {
+    [P in keyof T]: T[P] extends symbolInfo ? ImportSymbol : T[P] extends Record<string, unknown> ? mapRecord<T[P]> : never;
+};
+declare function mapRecord<T extends Record<string, unknown>>(record: T, bootstrapWkt: boolean): mapRecord<T>;
+type symbolInfo = {
+    readonly typeOnly: boolean;
+    readonly from: string;
+    readonly bootstrapWktFrom: string;
+};
+export {};

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

@@ -12,35 +12,34 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 import { createImportSymbol } from "./import-symbol.js";
-import { codegenInfo } from "@bufbuild/protobuf";
+import { symbols } from "@bufbuild/protobuf/codegenv1";
 export function createRuntimeImports(bootstrapWkt) {
-    // prettier-ignore
-    return {
-        proto2: infoToSymbol("proto2", bootstrapWkt),
-        proto3: infoToSymbol("proto3", bootstrapWkt),
-        Message: infoToSymbol("Message", bootstrapWkt),
-        PartialMessage: infoToSymbol("PartialMessage", bootstrapWkt),
-        PlainMessage: infoToSymbol("PlainMessage", bootstrapWkt),
-        FieldList: infoToSymbol("FieldList", bootstrapWkt),
-        MessageType: infoToSymbol("MessageType", bootstrapWkt),
-        Extension: infoToSymbol("Extension", bootstrapWkt),
-        BinaryReadOptions: infoToSymbol("BinaryReadOptions", bootstrapWkt),
-        BinaryWriteOptions: infoToSymbol("BinaryWriteOptions", bootstrapWkt),
-        JsonReadOptions: infoToSymbol("JsonReadOptions", bootstrapWkt),
-        JsonWriteOptions: infoToSymbol("JsonWriteOptions", bootstrapWkt),
-        JsonValue: infoToSymbol("JsonValue", bootstrapWkt),
-        JsonObject: infoToSymbol("JsonObject", bootstrapWkt),
-        protoDouble: infoToSymbol("protoDouble", bootstrapWkt),
-        protoInt64: infoToSymbol("protoInt64", bootstrapWkt),
-        ScalarType: infoToSymbol("ScalarType", bootstrapWkt),
-        LongType: infoToSymbol("LongType", bootstrapWkt),
-        MethodKind: infoToSymbol("MethodKind", bootstrapWkt),
-        MethodIdempotency: infoToSymbol("MethodIdempotency", bootstrapWkt),
-        IMessageTypeRegistry: infoToSymbol("IMessageTypeRegistry", bootstrapWkt),
-    };
+    return mapRecord(symbols, bootstrapWkt);
 }
-function infoToSymbol(name, bootstrapWkt) {
-    const info = codegenInfo.symbols[name];
-    const symbol = createImportSymbol(name, bootstrapWkt ? info.privateImportPath : info.publicImportPath);
-    return info.typeOnly ? symbol.toTypeOnly() : symbol;
+function mapRecord(record, bootstrapWkt) {
+    const result = Object.create(null);
+    for (const [key, value] of Object.entries(record)) {
+        if (isSymbolInfo(value)) {
+            result[key] = createImportSymbol(key, bootstrapWkt ? value.bootstrapWktFrom : value.from, value.typeOnly);
+        }
+        else {
+            result[key] = mapRecord(record[key], bootstrapWkt);
+        }
+    }
+    return result;
+}
+function isSymbolInfo(arg) {
+    if (typeof arg != "object" || arg === null) {
+        return false;
+    }
+    const wantNames = [
+        "typeOnly",
+        "from",
+        "bootstrapWktFrom",
+    ];
+    const gotNames = Object.getOwnPropertyNames(arg);
+    if (gotNames.length !== wantNames.length) {
+        return false;
+    }
+    return wantNames.every((w) => gotNames.includes(w));
 }

package/dist/esm/ecmascript/safe-identifier.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Escapes names that are reserved identifiers in ECMAScript, TypeScript.
+ *
+ * Also see safeObjectProperty() from @bufbuild/protoplugin/reflect.
+ */
+export declare function safeIdentifier(name: string): string;

package/dist/esm/ecmascript/safe-identifier.js

@@ -0,0 +1,86 @@
+// Copyright 2021-2024 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.
+/**
+ * Names that cannot be used for identifiers, such as class names,
+ * but _can_ be used for object properties.
+ */
+const reservedIdentifiers = new Set([
+    // ECMAScript 2015 keywords
+    "break",
+    "case",
+    "catch",
+    "class",
+    "const",
+    "continue",
+    "debugger",
+    "default",
+    "delete",
+    "do",
+    "else",
+    "export",
+    "extends",
+    "false",
+    "finally",
+    "for",
+    "function",
+    "if",
+    "import",
+    "in",
+    "instanceof",
+    "new",
+    "null",
+    "return",
+    "super",
+    "switch",
+    "this",
+    "throw",
+    "true",
+    "try",
+    "typeof",
+    "var",
+    "void",
+    "while",
+    "with",
+    "yield",
+    // ECMAScript 2015 future reserved keywords
+    "enum",
+    "implements",
+    "interface",
+    "let",
+    "package",
+    "private",
+    "protected",
+    "public",
+    "static",
+    // Class name cannot be 'Object' when targeting ES5 with module CommonJS
+    "Object",
+    // TypeScript keywords that cannot be used for types (as opposed to variables)
+    "bigint",
+    "number",
+    "boolean",
+    "string",
+    "object",
+    // Identifiers reserved for the runtime, so we can generate legible code
+    "globalThis",
+    "Uint8Array",
+    "Partial",
+]);
+/**
+ * Escapes names that are reserved identifiers in ECMAScript, TypeScript.
+ *
+ * Also see safeObjectProperty() from @bufbuild/protoplugin/reflect.
+ */
+export function safeIdentifier(name) {
+    return reservedIdentifiers.has(name) ? name + "$" : name;
+}

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

@@ -1,7 +1,7 @@
-import type { CodeGeneratorRequest, DescFile } from "@bufbuild/protobuf";
-import { FeatureSetDefaults } from "@bufbuild/protobuf";
+import type { DescEnum, DescExtension, DescFile, DescMessage, DescService } from "@bufbuild/protobuf";
+import type { CodeGeneratorRequest } from "@bufbuild/protobuf/wkt";
+import { Edition } from "@bufbuild/protobuf/wkt";
 import type { FileInfo, GeneratedFile } from "./generated-file.js";
-import type { RuntimeImports } from "./runtime-imports.js";
 import type { Target } from "./target.js";
 import type { ParsedParameter } from "./parameter.js";
 /**
@@ -21,14 +21,15 @@ export interface Schema {
      * The plugin option `target`. A code generator should support all targets.
      */
     readonly targets: readonly Target[];
-    /**
-     * Provides some symbols from the runtime library @bufbuild/protobuf.
-     */
-    readonly runtime: RuntimeImports;
     /**
      * Generate a new file with the given name.
      */
     generateFile(name: string): GeneratedFile;
+    /**
+     * List all types in a file (including messages, enumerations, and extensions
+     * nested in messages).
+     */
+    typesInFile(file: DescFile): Iterable<DescMessage | DescEnum | DescExtension | DescService>;
     /**
      * The original google.protobuf.compiler.CodeGeneratorRequest.
      */
@@ -38,5 +39,5 @@ interface SchemaController extends Schema {
     getFileInfo: () => FileInfo[];
     prepareGenerate(target: Target): void;
 }
-export declare function createSchema(request: CodeGeneratorRequest, parameter: ParsedParameter, pluginName: string, pluginVersion: string, featureSetDefaults: FeatureSetDefaults | undefined): SchemaController;
+export declare function createSchema(request: CodeGeneratorRequest, parameter: ParsedParameter, pluginName: string, pluginVersion: string, minimumEdition: Edition, maximumEdition: Edition): SchemaController;
 export {};

package/dist/esm/ecmascript/schema.js

@@ -11,38 +11,36 @@
 // 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.
-import { codegenInfo, createDescriptorSet, FeatureSetDefaults, } from "@bufbuild/protobuf";
+import { create } from "@bufbuild/protobuf";
+import { Edition, FileDescriptorSetDesc } from "@bufbuild/protobuf/wkt";
+import { createFileRegistry, nestedTypes } from "@bufbuild/protobuf/reflect";
 import { createGeneratedFile } from "./generated-file.js";
-import { createRuntimeImports } from "./runtime-imports.js";
 import { createImportSymbol } from "./import-symbol.js";
-import { deriveImportPath, makeImportPath, rewriteImportPath, } from "./import-path.js";
+import { deriveImportPath, rewriteImportPath } from "./import-path.js";
 import { makeFilePreamble } from "./file-preamble.js";
-export function createSchema(request, parameter, pluginName, pluginVersion, featureSetDefaults) {
-    const descriptorSet = createDescriptorSet(request.protoFile, {
-        featureSetDefaults,
-    });
-    const filesToGenerate = findFilesToGenerate(descriptorSet, request);
-    const runtime = createRuntimeImports(parameter.bootstrapWkt);
-    const createTypeImport = (desc) => {
-        const name = codegenInfo.localName(desc);
-        const from = makeImportPath(desc.file, parameter.bootstrapWkt, filesToGenerate);
-        return createImportSymbol(name, from);
-    };
-    const createPreamble = (descFile) => makeFilePreamble(descFile, pluginName, pluginVersion, parameter.sanitizedParameter, parameter.tsNocheck);
+import { localDescName, localShapeName, generateFilePath } 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);
     return {
         targets: parameter.targets,
-        runtime,
         proto: request,
         files: filesToGenerate,
-        allFiles: descriptorSet.files,
+        allFiles: allFiles,
+        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
-            (importPath) => rewriteImportPath(importPath, parameter.rewriteImports, parameter.importExtension), createTypeImport, runtime, createPreamble);
+            rewriteImport, resolveDescImport, resolveShapeImport, createPreamble, runtime);
             generatedFiles.push(genFile);
             return genFile;
         },
@@ -56,10 +54,56 @@ export function createSchema(request, parameter, pluginName, pluginVersion, feat
         },
     };
 }
-function findFilesToGenerate(descriptorSet, request) {
-    const missing = request.fileToGenerate.filter((fileToGenerate) => descriptorSet.files.every((file) => fileToGenerate !== file.name + ".proto"));
+function getFilesToGenerate(request, minimumEdition, maximumEdition) {
+    if (minimumEdition > maximumEdition) {
+        throw new Error(`configured minimumEdition ${editionToString(minimumEdition)} > maximumEdition ${editionToString(maximumEdition)} - please contact plugin author`);
+    }
+    const missing = request.fileToGenerate.filter((fileToGenerate) => !request.protoFile.find((f) => f.name === fileToGenerate));
     if (missing.length) {
-        throw `files_to_generate missing in the request: ${missing.join(", ")}`;
+        throw new Error(`files_to_generate missing in the request: ${missing.join(", ")}`);
+    }
+    for (const file of request.protoFile) {
+        if (request.fileToGenerate.includes(file.name)) {
+            let edition;
+            switch (file.syntax) {
+                case "":
+                case "proto2":
+                    edition = Edition.EDITION_PROTO2;
+                    break;
+                case "proto3":
+                    edition = Edition.EDITION_PROTO3;
+                    break;
+                case "editions":
+                    edition = file.edition;
+                    break;
+                default:
+                    edition = Edition.EDITION_UNKNOWN;
+                    break;
+            }
+            if (edition < minimumEdition) {
+                throw new Error(`${file.name}: unsupported edition ${editionToString(edition)} - the earliest supported edition is ${editionToString(minimumEdition)}`);
+            }
+            if (edition > maximumEdition) {
+                throw new Error(`${file.name}: unsupported edition ${editionToString(edition)} - the latest supported edition is ${editionToString(maximumEdition)}`);
+            }
+        }
+    }
+    const registry = createFileRegistry(create(FileDescriptorSetDesc, {
+        file: request.protoFile,
+    }));
+    const allFiles = [];
+    const filesToGenerate = [];
+    for (const file of registry.files) {
+        allFiles.push(file);
+        if (request.fileToGenerate.includes(file.proto.name)) {
+            filesToGenerate.push(file);
+        }
+    }
+    return { allFiles, filesToGenerate };
+}
+function editionToString(edition) {
+    if (edition in Edition) {
+        return Edition[edition].replace(/^EDITION_/, "");
     }
-    return descriptorSet.files.filter((file) => request.fileToGenerate.includes(file.name + ".proto"));
+    return `unknown (${edition})`;
 }

package/dist/esm/index.d.ts

@@ -1,8 +1,4 @@
-import type { Schema as SchemaInternal } from "./ecmascript/schema.js";
 export type { Plugin } from "./plugin.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;
+export { getComments, getDeclarationString, getPackageComments, getSyntaxComments, } from "./source-code-info.js";

package/dist/esm/index.js

@@ -13,3 +13,4 @@
 // limitations under the License.
 export { runNodeJs } from "./run-node.js";
 export { createEcmaScriptPlugin } from "./create-es-plugin.js";
+export { getComments, getDeclarationString, getPackageComments, getSyntaxComments, } from "./source-code-info.js";

package/dist/esm/plugin.d.ts

@@ -1,4 +1,4 @@
-import type { CodeGeneratorRequest, CodeGeneratorResponse } from "@bufbuild/protobuf";
+import type { CodeGeneratorRequest, CodeGeneratorResponse } from "@bufbuild/protobuf/wkt";
 /**
  * Represents any code generator plugin.
  */

package/dist/esm/run-node.js

@@ -11,8 +11,9 @@
 // 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.
-import { CodeGeneratorRequest } from "@bufbuild/protobuf";
 import { isPluginOptionError, reasonToString } from "./error.js";
+import { fromBinary, toBinary } from "@bufbuild/protobuf";
+import { CodeGeneratorRequestDesc, CodeGeneratorResponseDesc, } from "@bufbuild/protobuf/wkt";
 /**
  * Run a plugin with Node.js.
  *
@@ -37,9 +38,9 @@ export function runNodeJs(plugin) {
     }
     readBytes(process.stdin)
         .then((data) => {
-        const req = CodeGeneratorRequest.fromBinary(data);
+        const req = fromBinary(CodeGeneratorRequestDesc, data);
         const res = plugin.run(req);
-        return writeBytes(process.stdout, res.toBinary());
+        return writeBytes(process.stdout, toBinary(CodeGeneratorResponseDesc, res));
     })
         .then(() => process.exit(0))
         .catch((reason) => {

package/dist/esm/source-code-info.d.ts

@@ -0,0 +1,18 @@
+import type { DescField, DescEnumValue, DescExtension, DescComments, AnyDesc, DescFile } from "@bufbuild/protobuf";
+/**
+ * Get comments on the package element in the protobuf source.
+ */
+export declare function getPackageComments(desc: DescFile): DescComments;
+/**
+ * Get comments on the syntax element in the protobuf source.
+ */
+export declare function getSyntaxComments(desc: DescFile): DescComments;
+/**
+ * Get comments on the element in the protobuf source.
+ */
+export declare function getComments(desc: Exclude<AnyDesc, DescFile>): DescComments;
+/**
+ * Return a string that matches the definition of a field in the protobuf
+ * source. Does not take custom options into account.
+ */
+export declare function getDeclarationString(desc: DescField | DescExtension | DescEnumValue): string;