UNPKG

@bufbuild/protoplugin

Version:

Helps to create your own Protocol Buffers code generators.

141 lines (140 loc) 6.13 kB
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;