@bufbuild/protoplugin 1.3.1 → 1.3.2

package/dist/{types → cjs}/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, reifyWkt: typeof import("@bufbuild/protobuf/dist/types/private/reify-wkt.js").reifyWkt;
+export declare const localName: typeof import("@bufbuild/protobuf/dist/cjs/private/names.js").localName, reifyWkt: typeof import("@bufbuild/protobuf/dist/cjs/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/esm/create-es-plugin.d.ts

@@ -0,0 +1,64 @@
+import { Schema } from "./ecmascript/schema.js";
+import type { FileInfo } from "./ecmascript/generated-file.js";
+import type { Plugin } from "./plugin.js";
+interface PluginInit {
+    /**
+     * Name of this code generator plugin.
+     */
+    name: string;
+    /**
+     * Version of this code generator plugin.
+     */
+    version: string;
+    /**
+     * A optional parsing function which can be used to customize parameter
+     * parsing of the plugin.
+     */
+    parseOption?: PluginOptionParseFn;
+    /**
+     * A function which will generate TypeScript files based on proto input.
+     * This function will be invoked by the plugin framework when the plugin runs.
+     *
+     * Note that this is required to be provided for plugin initialization.
+     */
+    generateTs: (schema: Schema, target: "ts") => void;
+    /**
+     * A optional function which will generate JavaScript files based on proto
+     * input.  This function will be invoked by the  plugin framework when the
+     * plugin runs.
+     *
+     * If this function is not provided, the plugin framework will then check if
+     * a transpile function is provided.  If so, it will be invoked to transpile
+     * JavaScript files.  If not, the plugin framework will transpile the files
+     * itself.
+     */
+    generateJs?: (schema: Schema, target: "js") => void;
+    /**
+     * A optional function which will generate TypeScript declaration files
+     * based on proto input.  This function will be invoked by the plugin
+     * framework when the plugin runs.
+     *
+     * If this function is not provided, the plugin framework will then check if
+     * a transpile function is provided.  If so, it will be invoked to transpile
+     * declaration files.  If not, the plugin framework will transpile the files
+     * itself.
+     */
+    generateDts?: (schema: Schema, target: "dts") => void;
+    /**
+     * A optional function which will transpile a given set of files.
+     *
+     * This funcion 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.
+     */
+    transpile?: (files: FileInfo[], transpileJs: boolean, transpileDts: boolean) => FileInfo[];
+}
+type PluginOptionParseFn = (key: string, value: string | undefined) => void;
+/**
+ * Create a new code generator plugin for ECMAScript.
+ * The plugin can generate JavaScript, TypeScript, or TypeScript declaration
+ * files.
+ */
+export declare function createEcmaScriptPlugin(init: PluginInit): Plugin;
+export {};

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

@@ -0,0 +1,32 @@
+import type { AnyDesc } from "@bufbuild/protobuf";
+import { Message, MessageType, ScalarType } from "@bufbuild/protobuf";
+/**
+ * Returns the value of a custom option with a scalar type.
+ *
+ * If no option is found, returns 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
+ * 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.
+ */
+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
+ * extension number.
+ *
+ * If no options are found, returns 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.
+ */
+type ScalarValue<T> = T extends ScalarType.STRING ? string : T extends ScalarType.INT32 ? number : T extends ScalarType.UINT32 ? number : T extends ScalarType.UINT32 ? number : T extends ScalarType.SINT32 ? number : T extends ScalarType.FIXED32 ? number : T extends ScalarType.SFIXED32 ? number : T extends ScalarType.FLOAT ? number : T extends ScalarType.DOUBLE ? number : T extends ScalarType.INT64 ? bigint | string : T extends ScalarType.SINT64 ? bigint | string : T extends ScalarType.SFIXED64 ? bigint | string : T extends ScalarType.UINT64 ? bigint | string : T extends ScalarType.FIXED64 ? bigint | string : T extends ScalarType.BOOL ? boolean : T extends ScalarType.BYTES ? Uint8Array : never;
+export {};

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

@@ -0,0 +1,21 @@
+import { DescEnum, DescEnumValue, DescField, DescFile, DescMessage, DescMethod, DescOneof, DescService, ScalarType } from "@bufbuild/protobuf";
+import type { GeneratedFile, Printable } from "./generated-file.js";
+import type { ImportSymbol } from "./import-symbol.js";
+export declare function makeFilePreamble(file: DescFile, pluginName: string, pluginVersion: string, parameter: string, tsNoCheck: boolean): string;
+export declare function createJsDocBlock(text: string, indentation?: string): Printable;
+export declare function makeJsDoc(desc: DescEnum | DescEnumValue | DescMessage | DescOneof | DescField | DescService | DescMethod, indentation?: string): Printable;
+/**
+ * Returns an expression for the TypeScript typing of a field,
+ * and whether the property should be optional.
+ */
+export declare function getFieldTyping(field: DescField, file: GeneratedFile): {
+    typing: Printable;
+    optional: boolean;
+};
+export declare function scalarTypeScriptType(type: ScalarType): Printable;
+export declare function literalString(value: string): string;
+export declare function getFieldExplicitDefaultValue(field: DescField, protoInt64Symbol: ImportSymbol): Printable | undefined;
+export declare function getFieldIntrinsicDefaultValue(field: DescField): {
+    defaultValue: Printable | undefined;
+    typingInferrable: boolean;
+};

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

@@ -0,0 +1,81 @@
+import type { DescEnum, DescFile, DescMessage } from "@bufbuild/protobuf";
+import type { ImportSymbol } from "./import-symbol.js";
+import type { RuntimeImports } from "./runtime-imports.js";
+/**
+ * All types that can be passed to GeneratedFile.print()
+ */
+export type Printable = string | number | boolean | bigint | Uint8Array | ImportSymbol | DescMessage | DescEnum | Printable[];
+/**
+ * FileInfo represents an intermediate type using for transpiling TypeScript internally.
+ */
+export interface FileInfo {
+    name: string;
+    content: string;
+    preamble?: string | undefined;
+}
+/**
+ * Represents a JavaScript, TypeScript, or TypeScript declaration file.
+ */
+export interface GeneratedFile {
+    /**
+     * Create a standard preamble the includes comments at the top of the
+     * protobuf source file (like a license header), as well as information
+     * about the code generator and its version.
+     *
+     * The preamble is always placed at the very top of the generated file,
+     * above import statements.
+     *
+     * A file with a preamble but no other content is still considered empty,
+     * and will not be generated unless the plugin option keep_empty_files=true
+     * is set.
+     */
+    preamble(file: DescFile): void;
+    /**
+     * Add a line of code to the file.
+     *
+     * - string: Prints the string verbatim.
+     * - number or boolean: Prints a literal.
+     * - bigint: Prints an expression using protoInt64.parse().
+     * - Uint8Array: Prints an expression that re-created the array.
+     * - 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(...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.
+     */
+    export(name: string): ImportSymbol;
+    /**
+     * Import a message or enumeration generated by protoc-gen-es.
+     */
+    import(type: DescMessage | DescEnum): ImportSymbol;
+    /**
+     * Import any symbol from a file or package.
+     *
+     * The import path can point to a package, for example `@foo/bar/baz.js`, or
+     * to a file, for example `./bar/baz.js`.
+     *
+     * Note that while paths to a file begin with a `./`, they must be
+     * relative to the project root. The import path is automatically made
+     * relative to the current file.
+     */
+    import(name: string, from: string): ImportSymbol;
+}
+export interface GenerateFileToFileInfo {
+    getFileInfo(): FileInfo | undefined;
+}
+type CreateTypeImportFn = (desc: DescMessage | DescEnum) => ImportSymbol;
+type RewriteImportPathFn = (path: string) => string;
+export declare function createGeneratedFile(name: string, importPath: string, rewriteImportPath: RewriteImportPathFn, createTypeImport: CreateTypeImportFn, runtimeImports: RuntimeImports, preambleSettings: {
+    pluginName: string;
+    pluginVersion: string;
+    pluginParameter: string;
+    tsNocheck: boolean;
+}, keepEmpty: boolean): GeneratedFile & GenerateFileToFileInfo;
+export {};

package/dist/esm/ecmascript/import-path.d.ts

@@ -0,0 +1,65 @@
+import { DescFile } from "@bufbuild/protobuf";
+/**
+ * A configuration for rewriting import paths, a feature mainly used for
+ * remote code generation in the BSR npm registry, which makes it possible
+ * to serve the output of a BSR module and a plugin in an individual package.
+ *
+ * All plugins based on @bufbuild/protoplugin support the option
+ * "rewrite_imports", which is parsed into this type. The option can be given
+ * multiple times, in the form of `rewrite_imports=<pattern>:<target>`.
+ *
+ * The pattern is a very reduced subset of glob:
+ * - `*` matches zero or more characters except `/`.
+ * - `**` matches zero or more path elements, where an element is one or more
+ *   characters with a trailing `/`.
+ *
+ * The target is typically a npm package name, for example `@scope/pkg`.
+ *
+ * If any generated file imports from a path matching one of the patterns, the
+ * import path is rewritten to the corresponding target, by prepending the
+ * target to the import path (after replacing any leading ./ or ../ from the
+ * import path with / first).
+ *
+ * Note that the pattern is matched against the import path before it is made
+ * relative to the file importing it. The first matching pattern wins.
+ *
+ * For example, the pattern `./foo/**\/*_pb.js` (escaped for block comment!)
+ * matches:
+ * - ./foo/bar_pb.js
+ * - ./foo/bar/baz_pb.js
+ *
+ * But neither of:
+ * - ./bar_pb.js
+ * - ./foo/bar_xx.js
+ *
+ * With the target `@scope/pkg`, the import path `./foo/bar_pb.js` is
+ * transformed to `@scope/pkg/foo/bar_pb.js`.
+ */
+export type RewriteImports = {
+    pattern: string;
+    target: string;
+}[];
+/**
+ * Apply import rewrites to the given import path, and change all .js extensions
+ * to the given import extension.
+ */
+export declare function rewriteImportPath(importPath: string, rewriteImports: RewriteImports, importExtension: string): string;
+/**
+ * Returns the import path for files generated by the base type generator
+ * protoc-gen-es.
+ */
+export declare function makeImportPath(file: DescFile, bootstrapWkt: boolean, filesToGenerate: DescFile[]): string;
+export declare const relativePathRE: RegExp;
+/**
+ * Derives an ECMAScript module import path from a file path. For example,
+ * the path `foo/bar.ts` is transformed into `./foo/bar.js`.
+ */
+export declare function deriveImportPath(filename: string): string;
+/**
+ * Makes an import path relative to the file importing it. For example,
+ * consider the following files:
+ * - foo/foo.js
+ * - baz.js
+ * If foo.js wants to import baz.js, we return ../baz.js
+ */
+export declare function makeImportPathRelative(importer: string, importPath: string): string;

package/dist/esm/ecmascript/import-symbol.d.ts

@@ -0,0 +1,39 @@
+/**
+ * An import symbol represents an ECMAScript import.
+ */
+export type ImportSymbol = {
+    readonly kind: "es_symbol";
+    /**
+     * The name to import.
+     */
+    readonly name: string;
+    /**
+     * The import path.
+     *
+     * The path can point to a package, for example `@foo/bar/baz.js`, or
+     * to a file, for example `./bar/baz.js`.
+     *
+     * Note that while paths to a file begin with a `./`, they must be
+     * relative to the project root.
+     */
+    readonly from: string;
+    /**
+     * Whether this is a type-only import - an import that only exists in
+     * TypeScript.
+     */
+    readonly typeOnly: boolean;
+    /**
+     * Create a copy of this import, and make it type-only for TypeScript.
+     */
+    toTypeOnly(): ImportSymbol;
+    /**
+     * The unique ID based on name and from, disregarding typeOnly.
+     */
+    readonly id: EsSymbolId;
+};
+/**
+ * Create a new import symbol.
+ */
+export declare function createImportSymbol(name: string, from: string, typeOnly?: boolean): ImportSymbol;
+type EsSymbolId = string;
+export {};

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

@@ -0,0 +1,8 @@
+export { Target } from "./target.js";
+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/cjs/private/names.js").localName, reifyWkt: typeof import("@bufbuild/protobuf/dist/cjs/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/esm/ecmascript/runtime-imports.d.ts

@@ -0,0 +1,23 @@
+import type { ImportSymbol } from "./import-symbol.js";
+export interface RuntimeImports {
+    proto2: ImportSymbol;
+    proto3: ImportSymbol;
+    Message: ImportSymbol;
+    PartialMessage: ImportSymbol;
+    PlainMessage: ImportSymbol;
+    FieldList: ImportSymbol;
+    MessageType: ImportSymbol;
+    BinaryReadOptions: ImportSymbol;
+    BinaryWriteOptions: ImportSymbol;
+    JsonReadOptions: ImportSymbol;
+    JsonWriteOptions: ImportSymbol;
+    JsonValue: ImportSymbol;
+    JsonObject: ImportSymbol;
+    protoDouble: ImportSymbol;
+    protoInt64: ImportSymbol;
+    ScalarType: ImportSymbol;
+    MethodKind: ImportSymbol;
+    MethodIdempotency: ImportSymbol;
+    IMessageTypeRegistry: ImportSymbol;
+}
+export declare function createRuntimeImports(bootstrapWkt: boolean): RuntimeImports;

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

@@ -0,0 +1,43 @@
+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";
+/**
+ * Schema describes the files and types that the plugin is requested to
+ * generate.
+ */
+export interface Schema {
+    /**
+     * The files we are asked to generate.
+     */
+    readonly files: readonly DescFile[];
+    /**
+     * All files contained in the code generator request.
+     */
+    readonly allFiles: readonly DescFile[];
+    /**
+     * 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;
+    /**
+     * The original google.protobuf.compiler.CodeGeneratorRequest.
+     */
+    readonly proto: CodeGeneratorRequest;
+}
+interface SchemaController {
+    schema: Schema;
+    getFileInfo: () => FileInfo[];
+}
+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 {};

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

@@ -0,0 +1,4 @@
+/**
+ * Represents possible values of the plugin option `target`.
+ */
+export type Target = "js" | "ts" | "dts";

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

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

package/dist/esm/error.d.ts

@@ -0,0 +1,4 @@
+export declare class PluginOptionError extends Error {
+    constructor(option: string, reason?: unknown);
+}
+export declare function reasonToString(reason: unknown): string;

package/dist/esm/index.d.ts

@@ -0,0 +1,4 @@
+export { Plugin } from "./plugin.js";
+export { Schema } from "./ecmascript/schema.js";
+export { runNodeJs } from "./run-node.js";
+export { createEcmaScriptPlugin } from "./create-es-plugin.js";

package/dist/esm/plugin.d.ts

@@ -0,0 +1,18 @@
+import type { CodeGeneratorRequest, CodeGeneratorResponse } from "@bufbuild/protobuf";
+/**
+ * Represents any code generator plugin.
+ */
+export interface Plugin {
+    /**
+     * Name of this code generator plugin.
+     */
+    name: string;
+    /**
+     * Version of this code generator plugin.
+     */
+    version: string;
+    /**
+     * Run this plugin for the given request.
+     */
+    run(request: CodeGeneratorRequest): CodeGeneratorResponse;
+}

package/dist/esm/run-node.d.ts

@@ -0,0 +1,12 @@
+import type { Plugin } from "./plugin.js";
+/**
+ * Run a plugin with Node.js.
+ *
+ * ```
+ * #!/usr/bin/env node
+ * const {runNodeJs} = require("@bufbuild/protoplugin");
+ * const {myPlugin} = require("./protoc-gen-x-plugin.js");
+ * runNodeJs(myPlugin);
+ * ```
+ */
+export declare function runNodeJs(plugin: Plugin): void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bufbuild/protoplugin",
-  "version": "1.3.1",
+  "version": "1.3.2",
   "license": "(Apache-2.0 AND BSD-3-Clause)",
   "description": "Helps to create your own Protocol Buffers code generators.",
   "repository": {
@@ -10,32 +10,45 @@
   },
   "sideEffects": false,
   "scripts": {
-    "clean": "rm -rf ./dist/cjs/* ./dist/esm/* ./dist/types/*",
-    "build": "npm run build:cjs && npm run build:esm+types",
-    "build:cjs": "../../node_modules/typescript/bin/tsc --project tsconfig.json --module commonjs --outDir ./dist/cjs && echo >./dist/cjs/package.json '{\"type\":\"commonjs\"}'",
-    "build:esm+types": "../../node_modules/typescript/bin/tsc --project tsconfig.json --module ES2015 --outDir ./dist/esm --declaration --declarationDir ./dist/types"
+    "clean": "rm -rf ./dist/cjs/* ./dist/esm/*",
+    "build": "npm run build:cjs && npm run build:esm",
+    "build:cjs": "../../node_modules/typescript/bin/tsc --project tsconfig.json --module commonjs --outDir ./dist/cjs --declaration --declarationDir ./dist/cjs && echo >./dist/cjs/package.json '{\"type\":\"commonjs\"}'",
+    "build:esm": "../../node_modules/typescript/bin/tsc --project tsconfig.json --module ES2015 --outDir ./dist/esm --declaration --declarationDir ./dist/esm",
+    "attw": "attw --pack"
   },
+  "main": "./dist/cjs/index.js",
   "type": "module",
   "exports": {
     ".": {
-      "import": "./dist/esm/index.js",
-      "require": "./dist/cjs/index.js"
+      "import": {
+        "types": "./dist/esm/index.d.ts",
+        "default": "./dist/esm/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/index.d.ts",
+        "default": "./dist/cjs/index.js"
+      }
     },
     "./ecmascript": {
-      "import": "./dist/esm/ecmascript/index.js",
-      "require": "./dist/cjs/ecmascript/index.js"
+      "import": {
+        "types": "./dist/esm/ecmascript/index.d.ts",
+        "default": "./dist/esm/ecmascript/index.js"
+      },
+      "require": {
+        "types": "./dist/cjs/ecmascript/index.d.ts",
+        "default": "./dist/cjs/ecmascript/index.js"
+      }
     }
   },
-  "types": "./dist/types/index.d.ts",
   "typesVersions": {
     "*": {
       "ecmascript": [
-        "./dist/types/ecmascript/index.d.ts"
+        "./dist/cjs/ecmascript/index.d.ts"
       ]
     }
   },
   "dependencies": {
-    "@bufbuild/protobuf": "1.3.1",
+    "@bufbuild/protobuf": "1.3.2",
     "@typescript/vfs": "^1.4.0",
     "typescript": "4.5.2"
   },