@dovenv/examples/dist/main.d.mts

Tools for Examples files/directories for dovenv

import { Config as Config$1, CommandUtils } from '@dovenv/core';
import * as zod_v4_core from 'zod/v4/core';
import * as zod from 'zod';
import { Prettify, getPaths, ValidateInfer } from '@dovenv/core/utils';

declare const TYPE: {
    readonly CONFIG: "config";
    readonly PATH: "path";
    readonly JSDOC: "jsdoc";
    readonly MULTIPLE: "multiple";
    readonly CUSTOM: "custom";
};

declare const consts_TYPE: typeof TYPE;
declare namespace consts {
  export {
    consts_TYPE as TYPE,
  };
}

declare const schema: zod.ZodRecord<zod.ZodString, zod.ZodObject<{
    title: zod.ZodOptional<zod.ZodString>;
    desc: zod.ZodOptional<zod.ZodString>;
    outro: zod.ZodOptional<zod.ZodString>;
    data: zod.ZodRecord<zod.ZodString, zod.ZodObject<{
        input: zod.ZodString;
        title: zod.ZodOptional<zod.ZodString>;
        type: zod.ZodOptional<zod.ZodString>;
        desc: zod.ZodOptional<zod.ZodString>;
        outro: zod.ZodOptional<zod.ZodString>;
    }, zod_v4_core.$strip>>;
}, zod_v4_core.$strip>>;

type ExampleProps = {
    [key in string]: {
        /**
         * Title of the example (optional).
         */
        title?: string;
        /**
         * General description of the example (optional).
         */
        desc?: string;
        /**
         * Outro or conclusion of the example (optional).
         */
        outro?: string;
        /**
         * Additional data of the example.
         * Each element must comply with the structure defined in `infoSchema`.
         */
        data: {
            [key in string]: {
                /**
                 * Main input for the data.
                 */
                input: string;
                /**
                 * Title of the data (optional).
                 */
                title?: string;
                /**
                 * Type of the data (optional).
                 */
                type?: string;
                /**
                 * Description of the data (optional).
                 */
                desc?: string;
                /**
                 * Outro or conclusion of the data (optional).
                 */
                outro?: string;
            };
        };
    };
};
type ExampleConfig = ExampleProps extends ValidateInfer<typeof schema> ? ExampleProps : never;
type Shared = {
    /** Write a output if you want */
    output?: string;
    /**
     * H1 for markdown.
     *
     * @default 'Examples'
     */
    title?: string | false;
    /**
     * Description.
     *
     * @default 'Examples'
     */
    desc?: string;
};
type ExampleConfigFileProps = Prettify<Shared & {
    /** Override your config input. */
    config?: ExampleConfig;
    /**
     * Input of your config (path or config object).
     *
     * Path formats: JSON, YAML, TOML JS etc.
     */
    input: string | ExampleConfig;
}>;
type ExampleType = typeof TYPE[keyof typeof TYPE];
type ExamplePathProps = Prettify<Shared & {
    /** Input pattern. */
    input: string[];
    /** Options for input patterns */
    opts?: Parameters<typeof getPaths>[1];
}>;
type ExampleJsdocProps = ExamplePathProps;
type ExampleMultipleProps = Prettify<Shared & {
    [TYPE.JSDOC]?: Omit<ExampleJsdocProps, 'output'>;
    [TYPE.CONFIG]?: Omit<ExampleConfigFileProps, 'output'>;
    [TYPE.PATH]?: Omit<ExamplePathProps, 'output'>;
}>;
type ExampleCustomProps = {
    fn: (data: {
        /** Dovenv configration */
        config: Config$1;
        /** "Example" functions to run */
        run: {
            [TYPE.JSDOC]: (data: ExampleJsdocProps) => Promise<string>;
            [TYPE.CONFIG]: (data: ExampleConfigFileProps) => Promise<string>;
            [TYPE.PATH]: (data: ExamplePathProps) => Promise<string>;
            [TYPE.MULTIPLE]: (data: ExampleMultipleProps) => Promise<string>;
        };
    }) => Promise<unknown>;
};
type Set<T extends ExampleType, V extends object> = ({
    /**
     * Type of configuration
     */
    type: T;
} & V);
type ConfigValue = Prettify<Set<typeof TYPE.PATH, ExamplePathProps> | Set<typeof TYPE.CONFIG, ExampleConfigFileProps> | Set<typeof TYPE.JSDOC, ExampleJsdocProps> | Set<typeof TYPE.MULTIPLE, ExampleMultipleProps> | Set<typeof TYPE.CUSTOM, ExampleCustomProps>>;
type Config = {
    [key in string]: ConfigValue;
};

declare class Examples {
    #private;
    const: typeof consts;
    protected utils: CommandUtils;
    opts: Config | undefined;
    constructor(data: {
        opts?: Config;
        utils: CommandUtils;
    });
    fromConfig(data: ExampleConfigFileProps): Promise<string>;
    fromPath(data: ExamplePathProps): Promise<string>;
    /**
     * Process jsdoc examples.
     *
     * @param data - Example data.
     * @returns    Resolved example content.
     * @see https://github.com/jsdoc2md/jsdoc-api/blob/master/docs/api.md
     */
    fromJsdoc(data: ExampleJsdocProps): Promise<string>;
    /**
     * Process multiple examples.
     *
     * @param data - Example data.
     * @returns    Resolved example content.
     */
    fromMultiple(data: ExampleMultipleProps): Promise<string>;
    /**
     * Processes custom example data using provided handlers.
     *
     * This method allows dynamic processing of example data based on the type
     * by binding specific handler functions for each type. The function received
     * in the data parameter is invoked with an object containing these handlers.
     *
     * @param data - Object containing the function to execute with the handlers.
     * @returns    A promise that resolves to the result of the executed function.
     */
    fromCustom(data: ExampleCustomProps): Promise<unknown>;
    /**
     * Get a custom Example content template.
     *
     * Perfect method to be used outside an `Dovenv` environment.
     *
     * @param data - Configuration object.
     * @returns    A promise that resolves to the processed content as a string.
     */
    get(data: Config[number]): Promise<any>;
    /**
     * Process examples from the configuration object.
     *
     * @param pattern - An array of examples names to process. If not provided, all examples will be processed.
     * @returns       A promise that resolves to an object containing the content of each processed example.
     */
    run(pattern?: string[]): Promise<{} | undefined>;
}

/**
 * A plugin for `dovenv` providing tools for managing example paths.
 *
 * @param   {Config}       [conf] - Configuration for the plugin.
 * @returns {DovenvConfig}        - The plugin configuration with custom examples.
 */
declare const examplesPlugin: (conf?: Config) => Config$1;

export { Examples, examplesPlugin as default, examplesPlugin };
export type { Config, ExampleConfigFileProps, ExampleCustomProps, ExampleJsdocProps, ExampleMultipleProps, ExamplePathProps };