@bufbuild/protoplugin
Version:
Helps to create your own Protocol Buffers code generators.
141 lines (140 loc) • 6.13 kB
TypeScript
import { type AnyDesc, type DescEnum, type DescExtension, type DescFile, type DescMessage, type DescService } from "@bufbuild/protobuf";
import type { ImportSymbol } from "./import-symbol.js";
import type { Printable } from "./printable.js";
import type { RuntimeImports } from "./runtime-imports.js";
/**
* 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;
/**
* Create a string literal.
*/
string(string: string): Printable;
/**
* Create an array literal.
*/
array(elements: Printable[]): Printable;
/**
* Create a JSDoc comment block with the given text. Line breaks and white-space
* stay intact.
*/
jsDoc(text: string, indentation?: string): Printable;
/**
* Create a JSDoc comment block for the given message, enumeration, or other
* descriptor. The comment block will contain the original comments from the
* protobuf source, and annotations such as `@generated from message MyMessage`.
*/
jsDoc(schema: Exclude<AnyDesc, DescFile>, indentation?: string): Printable;
/**
* Create a printable export statement. For example:
*
* ```ts
* f.print(f.export("abstract class", "MyClass"), " {}")
* ```
*
* Will generate as:
* ```ts
* export abstract class MyClass {}
* ```
*
* Using this method is preferred over a calling print() with a literal export
* statement. If the plugin option `js_import_style=legacy_commonjs` is set,
* exports will automatically be generated for CommonJS.
*/
export(declaration: string, name: string): Printable;
/**
* Import a message or enumeration generated by protoc-gen-es.
*/
importShape(schema: DescMessage | DescEnum): ImportSymbol;
/**
* Import a message or enumeration JSON type generated by protoc-gen-es.
*
* Note that protoc-gen-es only generates JSON types with the plugin option
* `json_types=true`.
*/
importJson(desc: DescMessage | DescEnum): ImportSymbol;
/**
* Import a message Valid type generated by protoc-gen-es.
*
* Note that protoc-gen-es only generates valid types with the plugin option
* `valid_types`.
*/
importValid(desc: DescMessage): ImportSymbol;
/**
* Import a descriptor generated by protoc-gen-es.
*/
importSchema(schema: DescMessage | DescEnum | DescExtension | DescService | DescFile, typeOnly?: boolean): 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, typeOnly?: boolean): ImportSymbol;
/**
* In case you need full control over exports and imports, use print() and
* formulate your own imports and exports based on this property.
*
* With the plugin option `js_import_style=legacy_commonjs`, this property
* reports "legacy_commonjs", but only if the current target is "js".
* This matches the behavior of import(), which also only generates CommonJS
* under this condition.
*/
readonly jsImportStyle: "module" | "legacy_commonjs";
/**
* Provides some symbols from the runtime library @bufbuild/protobuf.
*/
readonly runtime: RuntimeImports;
}
export interface GeneratedFileController extends GeneratedFile {
getFileInfo(): FileInfo;
}
export type ResolveDescImportFn = (desc: DescMessage | DescEnum | DescExtension | DescService | DescFile, typeOnly?: boolean) => ImportSymbol;
export type ResolveShapeImportFn = (desc: DescMessage | DescEnum) => ImportSymbol;
export type ResolveJsonImportFn = (desc: DescMessage | DescEnum) => ImportSymbol;
export type ResolveValidImportFn = (desc: DescMessage) => ImportSymbol;
export type RewriteImportFn = (path: string) => string;
export type CreatePreambleFn = (descFile: DescFile) => string;
export declare function createGeneratedFile(name: string, importPath: string, jsImportStyle: "module" | "legacy_commonjs", rewriteImport: RewriteImportFn, resolveDescImport: ResolveDescImportFn, resolveShapeImport: ResolveShapeImportFn, resolveJsonImport: ResolveJsonImportFn, resolveValidImport: ResolveValidImportFn, createPreamble: CreatePreambleFn, runtime: RuntimeImports): GeneratedFileController;