@baseplate-dev/sync/dist/output/generator-task-output.d.ts

Library for syncing Baseplate descriptions

import type { GeneratorInfo, GeneratorTask, GeneratorTaskEntry } from '#src/generators/index.js';
import type { TemplateInfo } from '#src/templates/metadata/index.js';
import type { BuilderAction } from './builder-action.js';
import type { GeneratorOutputFormatter } from './formatter.js';
import type { PostWriteCommand, PostWriteCommandOptions } from './post-write-commands/types.js';
import type { StringMergeAlgorithm } from './string-merge-algorithms/types.js';
/**
 * Options for writing a file
 */
export interface WriteFileOptions {
    /**
     * Alternate full IDs for the file (used if migrating file from one generator to another)
     * Note: This must be the full ID of the file (i.e. `<package>/<generator-name>/<file-id>`)
     */
    alternateFullIds?: string[];
    /**
     * Whether to skip formatting the file
     */
    skipFormatting?: boolean;
    /**
     * Never overwrite the file (e.g. for placeholder images)
     */
    shouldNeverOverwrite?: boolean;
    /**
     * Skip writing the file. Useful if you need to write metadata for
     * generated files but don't want to write the file itself.
     */
    skipWriting?: boolean;
    /**
     * Merge algorithms to use for the file
     */
    mergeAlgorithms?: StringMergeAlgorithm[];
    /**
     * Info about the template that was used to generate the file. Written to the `.templates-info.json` file.
     *
     * This will always be written if template extractino is enabled. However, the instanceData key is required
     * in order to enable template extraction for that file.
     */
    templateInfo?: TemplateInfo;
}
/**
 * Data for a file to be written
 */
export interface FileData {
    /**
     * A unique identifier for the file within that generator (used to track renaming/moving of the file)
     */
    id: string;
    /**
     * The contents of the file
     */
    contents: string | Buffer;
    /**
     * The options for how to write the file
     */
    options?: WriteFileOptions;
}
/**
 * The output of a generator task
 */
export interface GeneratorTaskOutput {
    /**
     * A map of file paths to the file data
     */
    files: Map<string, FileData>;
    /**
     * The commands to run after the files are written
     */
    postWriteCommands: PostWriteCommand[];
    /**
     * The formatters that will be applied to all files depending on their extension
     */
    globalFormatters: GeneratorOutputFormatter[];
}
export interface GeneratorOutputMetadata {
    generatorTaskEntries: {
        id: string;
        generatorName: string;
        taskName: string;
        instanceName?: string;
    }[];
    generatorProviderRelationships: {
        providerTaskId: string;
        consumerTaskId: string;
        providerName: string;
        isOutput: boolean;
        isReadOnly: boolean;
    }[];
}
/**
 * The output of a generator task that includes metadata about the generator steps
 */
export interface GeneratorOutput extends GeneratorTaskOutput {
    metadata?: GeneratorOutputMetadata;
}
export interface TemplateMetadataOptions {
    /**
     * Whether to include template metadata in the output
     */
    includeTemplateMetadata: boolean;
    /**
     * Whether to generate metadata for a given file
     */
    shouldGenerateMetadata: (context: {
        /**
         * The ID of the file
         */
        fileId: string;
        /**
         * The path of the file
         */
        filePath: string;
        /**
         * The name of the generator
         */
        generatorName: string;
        /**
         * Whether the file is an instance of a template or a singleton
         *
         * This usually means that the file may be generated by multiple instances of the generator
         * and we only want to generate metadata for one instance of the file.
         */
        isInstance: boolean;
    }) => boolean;
}
export interface GeneratorTaskOutputBuilderContext {
    /**
     * The info of the current generator
     */
    generatorInfo: GeneratorInfo;
    /**
     * The id of the current generator
     */
    generatorId: string;
    /**
     * Options for template metadata
     */
    templateMetadataOptions?: TemplateMetadataOptions;
}
/**
 * Builder for the output of a generator task that collects the files and
 * commands that need to be run
 */
export declare class GeneratorTaskOutputBuilder {
    /**
     * The output of the generator
     */
    output: GeneratorTaskOutput;
    /**
     * The info of the current generator
     */
    generatorInfo: GeneratorInfo;
    /**
     * The id of the current generator
     */
    generatorId: string;
    /**
     * The dynamic tasks that have been added to the output
     */
    dynamicTasks: GeneratorTaskEntry[];
    /**
     * Options for template metadata
     */
    metadataOptions: TemplateMetadataOptions;
    constructor(context: GeneratorTaskOutputBuilderContext);
    /**
     * Reads a template file from the generator base directory
     *
     * @param templatePath The path to the template file relative to the templates directory
     * @returns The contents of the template file
     */
    readTemplate(templatePath: string): Promise<string>;
    /**
     * Writes a file to the output
     *
     * @param payload The payload for the file to write
     */
    writeFile({ id, destination: filePath, contents, options, generatorName, templateInfo, }: {
        id: string;
        generatorName?: string;
        destination: string;
        contents: string | Buffer;
        options?: Omit<WriteFileOptions, 'templateInfo'>;
        /**
         * Template info for the file. This should always be written if template info is present. However,
         * if not adding metadata to the file, instanceData should be undefined.
         */
        templateInfo?: TemplateInfo;
    }): void;
    /**
     * Adds a post write command to the output
     *
     * @param command The command to run
     * @param commandType The type of the command
     * @param options The options for the command
     */
    addPostWriteCommand(command: string, options?: PostWriteCommandOptions): void;
    /**
     * Applies one or more actions to the builder
     *
     * @param actions The actions to apply
     */
    apply(...actions: BuilderAction[]): Promise<void>;
    /**
     * Adds a formatter to the output that will be applied to all files depending on their extension
     *
     * @param formatter The formatter to add
     */
    addGlobalFormatter(formatter: GeneratorOutputFormatter): void;
    /**
     * Adds a dynamic task to the output
     *
     * @param name The name of the task
     * @param task The task to add
     */
    addDynamicTask(name: string, task: Omit<GeneratorTask, 'exports' | 'outputs'>): void;
}
//# sourceMappingURL=generator-task-output.d.ts.map