@dovenv/convert
Version:
Convert utils for dovenv
328 lines (313 loc) • 10.2 kB
TypeScript
import { Config as Config$1, CommandUtils } from '@dovenv/core';
import { getStringsFrom, Prettify, ObjectValues } from '@dovenv/core/utils';
import jsdoc2md from 'jsdoc-to-markdown';
import * as typedoc from 'typedoc';
import { TypeDocOptions } from 'typedoc';
import { PluginOptions } from 'typedoc-plugin-markdown';
type ConvertPropsSuper = {
/**
* Input patterns.
*
* Accepts glob patterns, urls, and strings.
*
* @example [
* 'https://pigeonposse.com',
* './docs/*.md',
* 'Just a simple string'
* ]
* @example './my/file'
* @example 'https://pigeonposse.com'
* @example 'my content string data'
*/
input: string[] | string;
/**
* Output path.
*/
output?: string;
};
type ConvertResponse = {
/**
* Id of the path.
*/
id: string;
/**
* Content of the path.
*/
content: string;
}[];
type ConvertSuperInterface = {
run: () => Promise<ConvertResponse>;
};
declare class ConvertSuper<Props extends ConvertPropsSuper> {
props: Props;
constructor(props: Props);
protected _getContent(input: string[] | string, opts?: Parameters<typeof getStringsFrom>[1]): Promise<({
type: "url";
path: string;
id: string;
content: string;
} | {
type: "text";
id: string;
content: string;
path?: undefined;
})[]>;
protected _forEachContent(input: string[] | string, cb: (data: Awaited<ReturnType<typeof getStringsFrom>>[number]) => Promise<void>, opts?: Parameters<typeof getStringsFrom>[1]): Promise<void[]>;
protected _writeOutput(out: string, id: string, content: string): Promise<void>;
protected _getOutput(): Promise<{
dir: string;
rmTempIfExist: () => Promise<void>;
}>;
}
type Html2MarkdownProps = ConvertPropsSuper;
type Markdown2HtmlProps = ConvertPropsSuper;
declare class Html2Markdown extends ConvertSuper<Html2MarkdownProps> {
props: ConvertPropsSuper;
constructor(props: Html2MarkdownProps);
run(): Promise<ConvertResponse>;
}
declare class Markdown2Html extends ConvertSuper<Markdown2HtmlProps> implements ConvertSuperInterface {
props: ConvertPropsSuper;
constructor(props: Markdown2HtmlProps);
run(): Promise<ConvertResponse>;
}
type Jsdoc2MarkdownProps = ConvertPropsSuper & {
opts?: jsdoc2md.RenderOptions | jsdoc2md.JsdocOptions;
};
declare class Jsdoc2Markdown extends ConvertSuper<Jsdoc2MarkdownProps> implements ConvertSuperInterface {
props: Jsdoc2MarkdownProps;
constructor(props: Jsdoc2MarkdownProps);
run(): Promise<ConvertResponse>;
}
type Openapi2MarkdownProps = ConvertPropsSuper & {
/**
* Openapi options.
*/
opts?: {
/**
* Sort titles by atoz.
*/
sort?: boolean;
};
};
declare class Openapi2Markdown extends ConvertSuper<Openapi2MarkdownProps> implements ConvertSuperInterface {
props: Openapi2MarkdownProps;
constructor(props: Openapi2MarkdownProps);
run(): Promise<ConvertResponse>;
}
type TypedocOpts = Partial<Omit<TypeDocOptions, 'entryPoints' | 'tsconfig' | 'plugin' | 'out'>>;
type PluginOpts = Partial<PluginOptions>;
type EmptyObject = {};
type TypescriptSharedProps<Opts extends Record<string, unknown> = EmptyObject> = Prettify<ConvertPropsSuper & {
/**
* Options.
*
* @see https://dovenv.pigeonposse.com/guide/plugin/convert
*/
opts?: Prettify<{
/**
* __Cuaton tsconfig path__.
*
* Used for getting the ts config of the output.
*
* @default
* join( process.cwd(), "tsconfig.ts" )
*/
tsconfigPath?: string;
/**
* __Package.json path__.
*
* This path is used to extract specific properties from the `package.json` file.
*
* @default
* join( process.cwd(), "package.json" )
*/
packageJsonPath?: string;
/**
* Name of your project.
*/
name?: string;
/**
* Hooks.
*/
hooks?: {
before?: () => Promise<string> | string;
after?: () => Promise<string> | string;
};
/**
* Transform function.
*/
transform?: (content: string) => Promise<string>;
/**
* Typedoc options.
*
* @see https://typedoc.org/options/
*/
typedoc?: TypedocOpts;
} & Opts>;
}>;
type Typescript2HtmlProps = TypescriptSharedProps;
type Typescript2MarkdownProps = TypescriptSharedProps<{
/**
* Typedoc markdown options.
*
* @see @see https://typedoc-plugin-markdown.org/docs/options
*/
typedocMarkdown?: PluginOpts;
}>;
declare class TypescriptSuper<Props extends TypescriptSharedProps> extends ConvertSuper<Props> {
constructor(props: Props);
protected getTsConfigPath(): Promise<string | undefined>;
protected getPackageJsonPath(): Promise<string | undefined>;
runTypedoc<C extends Record<string, unknown>>(customConf?: C): Promise<{
id: string;
content: string;
}[]>;
}
declare class Typescript2Html extends TypescriptSuper<Typescript2HtmlProps> implements ConvertSuperInterface {
constructor(props: Typescript2HtmlProps);
run(): Promise<{
id: string;
content: string;
}[]>;
}
declare class Typescript2Markdown extends TypescriptSuper<Typescript2MarkdownProps> implements ConvertSuperInterface {
props: {
input: string[] | string;
output?: string | undefined;
opts?: {
tsconfigPath?: string | undefined;
packageJsonPath?: string | undefined;
name?: string | undefined;
hooks?: {
before?: () => Promise<string> | string;
after?: () => Promise<string> | string;
} | undefined;
transform?: ((content: string) => Promise<string>) | undefined;
typedoc?: Partial<Omit<typedoc.TypeDocOptions, "tsconfig" | "plugin" | "entryPoints" | "out">> | undefined;
typedocMarkdown?: Partial<PluginOptions> | undefined;
} | undefined;
};
constructor(props: Typescript2MarkdownProps);
run(): Promise<{
id: string;
content: string;
}[]>;
}
declare const methods: {
readonly ts2md: "ts2md";
readonly ts2html: "ts2html";
readonly jsdoc2md: "jsdoc2md";
readonly html2md: "html2md";
readonly md2html: "md2html";
readonly openapi2md: "openapi2md";
readonly custom: "custom";
};
type ConvertConfig = {
[methods.openapi2md]: Openapi2Markdown;
[methods.jsdoc2md]: Jsdoc2Markdown;
[methods.html2md]: Html2Markdown;
[methods.md2html]: Markdown2Html;
[methods.ts2md]: Typescript2Markdown;
[methods.ts2html]: Typescript2Html;
[methods.custom]: {
props: {
/**
* Function to run your conversion.
*/
fn: (data: {
config: Config$1;
run: Prettify<Omit<ConvertInterface, 'custom'>>;
}) => Promise<void>;
};
run: () => Promise<void>;
};
};
type ConvertInterface = {
[key in ObjectValues<typeof methods>]: (params: ConvertConfig[key]['props']) => ReturnType<ConvertConfig[key]['run']>;
};
type ConfigValue = {
[key in keyof ConvertConfig]: {
/**
* Type of conversion.
*/
type: key;
} & ConvertConfig[key]['props'];
}[keyof ConvertConfig];
type Config = {
[key in string]: ConfigValue;
};
/**
* Convertion class.
*
* @example
* // convert ts files to markdown
* const convert = new Convert()
* await convert.ts2md({input: 'src/main.ts', output: 'README.md' })
*/
declare class Convert implements ConvertInterface {
config: Config$1;
openapi2md(params: ConvertConfig[typeof methods.openapi2md]['props']): Promise<ConvertResponse>;
ts2md(params: ConvertConfig[typeof methods.ts2md]['props']): Promise<{
id: string;
content: string;
}[]>;
ts2html(params: ConvertConfig[typeof methods.ts2html]['props']): Promise<{
id: string;
content: string;
}[]>;
html2md(params: ConvertConfig[typeof methods.html2md]['props']): Promise<ConvertResponse>;
md2html(params: ConvertConfig[typeof methods.md2html]['props']): Promise<ConvertResponse>;
jsdoc2md(params: ConvertConfig[typeof methods.jsdoc2md]['props']): Promise<ConvertResponse>;
custom(params: ConvertConfig[typeof methods.custom]['props']): Promise<void>;
}
declare class MultipleConvert {
#private;
convert: Convert;
utils: CommandUtils;
opts: Config | undefined;
constructor({ opts, utils, }: {
opts?: Config;
utils: CommandUtils;
});
run(pattern?: string[]): Promise<{
[x: string]: void | ConvertResponse | {
id: string;
content: string;
}[] | {
id: string;
content: string;
}[];
} | undefined>;
}
/**
* A plugin for `dovenv` to convert files from one format to another.
*
* @param {Config} [conf] - Configuration for the plugin.
* @returns {DovenvConfig} - The plugin.
* @example
* import { defineConfig } from '@dovenv/core'
* import { convertPlugin } from '@dovenv/convert'
* export default defineConfig(
* convertPlugin( {
* exampleJSDOC: {
* type: 'jsdoc2md',
* input: 'examples/recourses/main.js',
* output: 'build/jsdoc',
* },
* exampleTS: {
* type: 'ts2md',
* input: 'examples/recourses/main.ts',
* output: 'build/ts',
* },
* exampleHTML: {
* type: 'md2html',
* input: 'https://raw.githubusercontent.com/pigeonposse/backan/refs/heads/main/README.md',
* output: 'build/html',
* },
* } ),
* )
*/
declare const convertPlugin: (conf?: Config) => Config$1;
export { Convert, Html2Markdown, Jsdoc2Markdown, Markdown2Html, MultipleConvert, Openapi2Markdown, Typescript2Markdown, convertPlugin, convertPlugin as default };
export type { Config };