ecto/dist/ecto.d.ts

Modern Template Consolidation Engine for EJS, Markdown, Pug, Nunjucks, Liquid, and Handlebars

import { Cacheable, CacheableMemory } from 'cacheable';

declare class EngineMap {
    private readonly _mappings;
    set(name: string, extensions: string[]): void;
    delete(name: string): void;
    deleteExtension(name: string, extension: string): void;
    get(name: string): string[] | undefined;
    getName(extension: string): string | undefined;
}

declare class BaseEngine {
    names: string[];
    opts?: any;
    engine: any;
    rootTemplatePath?: string;
    private __extensions;
    getExtensions(): string[];
    setExtensions(extensions: string[]): void;
    deleteExtension(name: string): void;
}

type EngineInterface = {
    names: string[];
    engine: any;
    opts?: any;
    rootTemplatePath?: string;
    render(source: string, data?: Record<string, unknown>): Promise<string>;
    renderSync(source: string, data?: Record<string, unknown>): string;
};

declare class Markdown extends BaseEngine implements EngineInterface {
    constructor(options?: any);
    render(source: string, data?: Record<string, unknown>): Promise<string>;
    renderSync(source: string, data?: Record<string, unknown>): string;
}

declare class Handlebars extends BaseEngine implements EngineInterface {
    partialsPath: string[];
    constructor(options?: Record<string, unknown>);
    render(source: string, data?: Record<string, unknown>): Promise<string>;
    renderSync(source: string, data?: Record<string, unknown>): string;
    initPartials(): void;
    registerPartials(partialsPath: string): boolean;
}

declare class EJS extends BaseEngine implements EngineInterface {
    constructor(options?: Record<string, unknown>);
    render(source: string, data?: Record<string, unknown>): Promise<string>;
    renderSync(source: string, data?: Record<string, unknown>): string;
}

declare class Pug extends BaseEngine implements EngineInterface {
    constructor(options?: Record<string, unknown>);
    render(source: string, data?: Record<string, unknown>): Promise<string>;
    renderSync(source: string, data?: Record<string, unknown>): string;
}

declare class Nunjucks extends BaseEngine implements EngineInterface {
    constructor(options?: Record<string, unknown>);
    render(source: string, data?: Record<string, unknown>): Promise<string>;
    renderSync(source: string, data?: Record<string, unknown>): string;
}

declare class Liquid extends BaseEngine implements EngineInterface {
    constructor(options?: Record<string, unknown>);
    render(source: string, data?: Record<string, unknown>): Promise<string>;
    renderSync(source: string, data?: Record<string, unknown>): string;
}

type EctoOptions = {
    /**
     * The default engine to use. This can be 'ejs', 'markdown', 'pug', 'nunjucks', 'handlebars', 'liquid'
     * @default 'ejs'
     * @type {string}
     */
    defaultEngine?: string;
    /**
     * The engine options to pass to each engine
     * @type {Record<string, Record<string, unknown>>}
     * @default {}
     * @example
     * {
     * 	nunjucks: {
     * 		autoescape: true
     * 	},
     * 	markdown: {
     * 		html: true
     * 	}
     * }
     */
    engineOptions?: Record<string, Record<string, unknown>>;
    /**
     * Caching for async rendered templates. If set to true, it will use the default cacheable options.
     * If set to Cacheable instantce, it will use the provided cacheable instance.
     * @type {boolean | Cacheable}
     * @default false
     */
    cache?: boolean | Cacheable;
    /**
     * If set to true, it will cache the rendered templates synchronously when running renderSync.
     * If set to CacheableMemory instance, it will use the provided cacheable memory instance.
     * @type {boolean | CacheableMemory}
     * @default false
     */
    cacheSync?: boolean | CacheableMemory;
};
declare class Ecto {
    private readonly __mapping;
    private readonly __engines;
    private __cache;
    private __cacheSync;
    private __defaultEngine;
    private readonly __ejs;
    private readonly __markdown;
    private readonly __pug;
    private readonly __nunjucks;
    private readonly __handlebars;
    private readonly __liquid;
    /**
     * Ecto constructor
     * @param {EctoOptions} [options] - The options for the ecto engine
     */
    constructor(options?: EctoOptions);
    /**
     * Get the default engine
     * @returns {string} - the engine name such as 'ejs', 'markdown', 'pug', 'nunjucks', 'handlebars', 'liquid'
     */
    get defaultEngine(): string;
    /**
     * Set the default engine
     * @param {string} value the engine name such as 'ejs', 'markdown', 'pug', 'nunjucks', 'handlebars', 'liquid'
     */
    set defaultEngine(value: string);
    /**
     * Get the cacheable instance
     * @returns {Cacheable | undefined} - The cacheable instance or undefined if caching is disabled
     */
    get cache(): Cacheable | undefined;
    /**
     * Set the cacheable instance
     * @param {Cacheable | undefined} value - The cacheable instance to set. If set to undefined, caching will be disabled.
     */
    set cache(value: Cacheable | undefined);
    /**
     * Get the cacheable memory instance
     * @returns {CacheableMemory | undefined} - The cacheable memory instance or undefined if caching is disabled
     */
    get cacheSync(): CacheableMemory | undefined;
    /**
     * Set the cacheable memory instance
     * @param {CacheableMemory | undefined} value - The cacheable memory instance to set. If set to undefined, caching will be disabled.
     */
    set cacheSync(value: CacheableMemory | undefined);
    /**
     * Get the Engine Mappings. This is used to map file extensions to engines
     * @returns {EngineMap}
     */
    get mappings(): EngineMap;
    /**
     * Get the EJS Engine
     * @returns {EJS}
     */
    get ejs(): EJS;
    /**
     * Get the Markdown Engine
     * @returns {Markdown}
     */
    get markdown(): Markdown;
    /**
     * Get the Pug Engine
     * @returns {Pug}
     */
    get pug(): Pug;
    /**
     * Get the Nunjucks Engine
     * @returns {Nunjucks}
     */
    get nunjucks(): Nunjucks;
    /**
     * Get the Handlebars Engine
     * @returns {Handlebars}
     */
    get handlebars(): Handlebars;
    /**
     * Get the Liquid Engine
     * @returns {Liquid}
     */
    get liquid(): Liquid;
    /**
     * Async render the source with the data
     * @param {string} source - The source to render
     * @param {Record<string, unknown} data - data to render with the source
     * @param {string} [engineName] - The engine to use for rendering
     * @param {string} [rootTemplatePath] - The root path to the template if using includes / partials
     * @param {string} [filePathOutput] - The file path to write the output
     * @returns {Promise<string>}
     */
    render(source: string, data?: Record<string, unknown>, engineName?: string, rootTemplatePath?: string, filePathOutput?: string): Promise<string>;
    /**
     * Synchronously render the source with the data
     * @param {string} source - The source to render
     * @param {Record<string, unknown} data - data to render with the source
     * @param {string} [engineName] - The engine to use for rendering
     * @param {string} [rootTemplatePath] - The root path to the template if using includes / partials
     * @param {string} [filePathOutput] - The file path to write the output
     * @returns {string}
     */
    renderSync(source: string, data?: Record<string, unknown>, engineName?: string, rootTemplatePath?: string, filePathOutput?: string): string;
    /**
     * Render from a file path
     * @param {string} filePath - The file path to the source
     * @param {Record<string, unknown>} data - The data to render with the source
     * @param {string} [rootTemplatePath] - The root path to the template if using includes / partials
     * @param {string} [filePathOutput] - The file path to write the output
     * @param {string} [engineName] - The engine to use for rendering
     * @returns
     */
    renderFromFile(filePath: string, data?: Record<string, unknown>, rootTemplatePath?: string, filePathOutput?: string, engineName?: string): Promise<string>;
    /**
     * Sync render from a file path
     * @param {string} filePath - The file path to the source
     * @param {Record<string, unknown>} data - The data to render with the source
     * @param {string} [rootTemplatePath] - The root path to the template if using includes / partials
     * @param {string} [filePathOutput] - The file path to write the output
     * @param {string} [engineName] - The engine to use for rendering
     * @returns {string}
     */
    renderFromFileSync(filePath: string, data?: Record<string, unknown>, rootTemplatePath?: string, filePathOutput?: string, engineName?: string): string;
    /**
     * Ensure the file path exists or create it
     * @param {string} path
     * @returns {Promise<void>}
     */
    ensureFilePath(path: string): Promise<void>;
    /**
     * Ensure the file path exists or create it synchronously
     * @param {string} path
     * @returns {void}
     */
    ensureFilePathSync(path: string): void;
    /**
     * Get the Engine By File Path
     * @param {string} filePath
     * @returns {string} - will return the engine name such as 'ejs', 'markdown', 'pug', 'nunjucks', 'handlebars', 'liquid'
     */
    getEngineByFilePath(filePath: string): string;
    /**
     * Find the template without the extension. This will look in a directory for a file that starts with the template name
     * @param {string} path - the path to look for the template file
     * @param {string} templateName
     * @returns {Promise<string>} - the path to the template file
     */
    findTemplateWithoutExtension(path: string, templateName: string): Promise<string>;
    /**
     * Syncronously find the template without the extension. This will look in a directory for a file that starts with the template name
     * @param {string} path - the path to look for the template file
     * @param {string} templateName
     * @returns {string} - the path to the template file
     */
    findTemplateWithoutExtensionSync(path: string, templateName: string): string;
    /**
     * Is it a valid engine that is registered in ecto
     * @param engineName
     * @returns {boolean}
     */
    isValidEngine(engineName?: string): boolean;
    /**
     * Register the engine mappings
     * @returns {void}
     */
    registerEngineMappings(): void;
    /**
     * Get Render Engine by the engine name. Default is EJS
     * @param {string} engineName
     * @returns {EngineInterface}
     */
    getRenderEngine(engineName: string): EngineInterface;
    /**
     * Checks if the source has front matter
     * @param {string} source
     * @returns {boolean}
     */
    hasFrontMatter(source: string): boolean;
    /**
     * Get the Front Matter from the source
     * @param {string} source
     * @returns {Record<string, unknown>}
     */
    getFrontMatter(source: string): Record<string, unknown>;
    /**
     * Will set the front matter in the source and return the source
     * @param {string} source - The source to set the front matter
     * @param {Record<string, unknown>} data - The front matter data
     * @returns {string} - The source with the front matter
     */
    setFrontMatter(source: string, data: Record<string, unknown>): string;
    /**
     * Remove the Front Matter from the source
     * @param {string} source
     * @returns {string}
     */
    removeFrontMatter(source: string): string;
    private writeFile;
    private writeFileSync;
}

export { Ecto, type EctoOptions };