import type { Pluggable } from "unified";
import type {
BuildEndContext,
DevServerContext,
DocuConfig,
PageContext,
PageMeta,
PluginBuilder,
} from "./plugin";
type Awaitable = T | Promise;
interface OnLoadHandler {
filter: RegExp;
namespace?: string;
fn: (args: {
path: string;
content: string;
}) => Awaitable<{ contents?: string; loader?: "js" | "ts" | "mdx" } | void>;
}
export class BuildPluginBuilder implements PluginBuilder {
readonly config: DocuConfig;
private _handleRequest: Array<
(req: Request, context: DevServerContext) => Awaitable
> = [];
private _injectBody: Array<(context: PageContext) => string | string[]> = [];
private _injectHead: Array<(context: PageContext) => string | string[]> = [];
private _onEnd: Array<
(config: DocuConfig, pages: PageMeta[], context: BuildEndContext) => Awaitable
> = [];
private _onLoad: OnLoadHandler[] = [];
private _onStart: Array<(config: DocuConfig) => Awaitable> = [];
private _rehypePlugins: Array<() => Pluggable[]> = [];
private _remarkPlugins: Array<() => Pluggable[]> = [];
private _transformFrontmatter: Array<
(
frontmatter: Record,
context: Pick
) => Awaitable | void>
> = [];
private _transformHtml: Array<(html: string, context: PageContext) => Awaitable> = [];
constructor(config: DocuConfig) {
this.config = config;
}
/**
* Collect and deduplicate all `` injection snippets from registered plugins.
* Each callback is executed in registration order; plugin errors are wrapped
* with a descriptive message.
*
* @param context - Current page context passed to each injectBody callback.
* @returns Deduplicated array of HTML strings to inject before ``.
* @throws Error if any injectBody callback throws — wraps original error as cause.
*/
collectBody(context: PageContext): string[] {
const items: string[] = [];
for (const cb of this._injectBody) {
try {
const result = cb(context);
if (result) {
this.collectItems(items, result, "injectBody");
}
} catch (err) {
throw new Error(
`[plugin] injectBody callback failed: ${err instanceof Error ? err.message : String(err)}`,
{ cause: err }
);
}
}
return [...new Set(items)];
}
/**
* Collect and deduplicate all `` injection snippets from registered plugins.
* Each callback is executed in registration order; plugin errors are wrapped
* with a descriptive message.
*
* @param context - Current page context passed to each injectHead callback.
* @returns Deduplicated array of HTML strings to inject before ``.
* @throws Error if any injectHead callback throws — wraps original error as cause.
*/
collectHead(context: PageContext): string[] {
const items: string[] = [];
for (const cb of this._injectHead) {
try {
const result = cb(context);
if (result) {
this.collectItems(items, result, "injectHead");
}
} catch (err) {
throw new Error(
`[plugin] injectHead callback failed: ${err instanceof Error ? err.message : String(err)}`,
{ cause: err }
);
}
}
return [...new Set(items)];
}
/**
* Collect all rehype plugin arrays from registered rehypePlugins callbacks.
* Results from all plugins are flattened into a single array.
*
* @returns Flattened array of rehype plugin instances applied after default set.
* @throws Error if any rehypePlugins callback throws — wraps original error as cause.
*/
collectRehypePlugins(): Pluggable[] {
const plugins: Pluggable[] = [];
for (const cb of this._rehypePlugins) {
try {
plugins.push(...cb());
} catch (err) {
throw new Error(
`[plugin] rehypePlugins callback failed: ${err instanceof Error ? err.message : String(err)}`,
{ cause: err }
);
}
}
return plugins;
}
/**
* Collect all remark plugin arrays from registered remarkPlugins callbacks.
* Results from all plugins are flattened into a single array.
*
* @returns Flattened array of remark plugin instances applied after default set.
* @throws Error if any remarkPlugins callback throws — wraps original error as cause.
*/
collectRemarkPlugins(): Pluggable[] {
const plugins: Pluggable[] = [];
for (const cb of this._remarkPlugins) {
try {
plugins.push(...cb());
} catch (err) {
throw new Error(
`[plugin] remarkPlugins callback failed: ${err instanceof Error ? err.message : String(err)}`,
{ cause: err }
);
}
}
return plugins;
}
/**
* Register a callback to intercept incoming requests during development.
* The **first** callback to return a `Response` short-circuits all subsequent handlers.
* Errors inside callbacks are caught and logged — execution continues to next handler.
*
* @param callback - Receives the Request and dev server context. Return Response or void.
*
* @example
* build.handleRequest((req, ctx) => {
* if (new URL(req.url).pathname === "/api/status") {
* return new Response(JSON.stringify({ ok: true }), {
* headers: { "Content-Type": "application/json" },
* });
* }
* });
*/
handleRequest(
callback: (req: Request, context: DevServerContext) => Awaitable
): void {
this._handleRequest.push(callback);
}
/**
* Register a callback that returns HTML strings to inject before ` `.
* Results from all plugins are merged, deduplicated, and served via `collectBody()`.
*
* @param callback - Returns a single HTML string or an array. Called once per page.
*
* @example
* build.injectBody(() => `