@sigiljs/sigil/dist/sigil/misc/sigil-plugin.d.ts

TypeScript-first Node.js HTTP framework offering schema-driven routing, modifier-based middleware, plugin extensibility, and flexible response templating

import { default as http } from 'node:http';
import { default as https } from 'node:https';
import { IncomingRequestProcessorResponse } from '../../requests/containers';
import { SigilResponse } from '../../responses';
import { Exception } from '../../responses/exceptions';
import { SigilOptions } from '../types/common.types';
import { $InternalPluginContext, $InternalRoutesListMethods, $SigilInternalPluginAPI } from '../types/internal.types';
/**
 * Constructor type for Sigil plugins.
 * @template P The SigilPlugin subclass.
 */
export type SigilPluginConstructor<P extends SigilPlugin> = new () => P;
/**
 * Base class for Sigil framework plugins.
 * Provides lifecycle hooks and internal framework context.
 *
 * @template PluginConfig Configuration type for the plugin.
 */
export declare abstract class SigilPlugin<PluginConfig extends Record<string, any> = any> {
    /**
     * Static plugin name, usually the class name.
     */
    static name: string;
    /**
     * Instance plugin name, copied from the constructor.
     */
    readonly name: string;
    /**
     * Internal routes API for registering or inspecting routes.
     */
    readonly $routes: $InternalRoutesListMethods;
    /**
     * Response template function from the framework.
     */
    protected readonly $responseTemplate: SigilOptions["responseTemplate"];
    /**
     * Configuration object passed to this plugin.
     */
    protected readonly $pluginConfig: PluginConfig;
    /**
     * Logger scoped to this plugin.
     */
    protected readonly logger: $InternalPluginContext["logger"];
    /**
     * Internal Sigil API for plugins (mount, addMiddleware, etc.).
     */
    protected readonly sigil: $SigilInternalPluginAPI;
    /**
     * Constructs the plugin with context injected by attachPluginContext.
     * @protected
     */
    protected constructor();
    /**
     * Called when a new request is received. Cannot modify the request,
     * only for side effects such as logging or telemetry.
     * @param request parsed incoming request object.
     */
    onRequestReceived(request: IncomingRequestProcessorResponse): void;
    /**
     * Called just before a response is sent.
     * Can replace the actual response by returning custom SigilResponse.
     * @param request original HTTP incoming message.
     * @param response SigilResponse or Exception being sent.
     */
    onBeforeResponseSent(request: IncomingRequestProcessorResponse | null, response: SigilResponse | Exception): void | SigilResponse | Promise<void | SigilResponse>;
    /**
     * Called when the internal HTTP/S server starts listening.
     * @param server HTTP or HTTPS server instance, or undefined in serverless mode.
     */
    onInternalServerStarted(server: http.Server | https.Server | undefined): void;
    /**
     * Called whenever the route registry is updated (e.g., mount or unmount).
     */
    onUpdateCallback(): void;
    /**
     * Called once when the plugin is first initialized.
     */
    onInitialize(): any;
    /**
     * Called before the program exits (SIGINT, etc.).
     * Can perform async cleanup.
     * @returns optional promise for async cleanup tasks.
     */
    onBeforeExit(): Promise<any> | void;
}