@sidequest/dashboard/dist/index.d.ts

@sidequest/dashboard is the web dashboard for Sidequest, a distributed background job queue system.

import { DashboardConfig } from './config.js';

/**
 * A dashboard server for monitoring and managing Sidequest jobs and queues.
 *
 * The SidequestDashboard class provides a web-based interface for viewing job status,
 * queue information, and other Sidequest-related data. It sets up an Express.js server
 * with EJS templating, optional basic authentication, and connects to a configurable backend.
 *
 * @example
 * ```typescript
 * const dashboard = new SidequestDashboard();
 * await dashboard.start({
 *   port: 3000,
 *   enabled: true,
 *   auth: {
 *     user: 'admin',
 *     password: 'secret'
 *   },
 *   backendConfig: {
 *     driver: '@sidequest/sqlite-backend'
 *   }
 * });
 * ```
 */
declare class SidequestDashboard {
    /**
     * The Express application instance used by the dashboard server.
     * This property is optional and may be undefined if the server has not been initialized.
     */
    private app?;
    /**
     * Optional dashboard configuration object that defines the behavior and appearance
     * of the dashboard component. If not provided, default configuration will be used.
     */
    private config?;
    /**
     * The HTTP server instance used by the dashboard application.
     * This server handles incoming requests and serves the dashboard interface.
     * Will be undefined until the server is started.
     */
    private server?;
    /**
     * Backend instance used for server communication and data operations.
     * When undefined, indicates that no backend connection has been established.
     */
    private backend?;
    constructor();
    /**
     * Starts the dashboard server with the provided configuration.
     *
     * @param config - Optional dashboard configuration object. If not provided, default values will be used.
     * @returns A promise that resolves when the server setup is complete.
     *
     * @remarks
     * - If the server is already running, a warning is logged and the method returns early
     * - If the dashboard is disabled in config, a debug message is logged and the method returns early
     * - The method sets up the Express app, backend driver, middlewares, authentication, EJS templating, routes, and starts listening
     *
     * @example
     * ```typescript
     * await dashboard.start({
     *   enabled: true,
     *   port: 3000,
     *   backendConfig: { driver: "@sidequest/sqlite-backend" }
     * });
     * ```
     */
    start(config?: DashboardConfig): Promise<void>;
    /**
     * Sets up middleware for the Express application.
     *
     * Configures HTTP request logging using Morgan middleware when debug logging is enabled.
     * The middleware uses the "combined" format for comprehensive request logging.
     *
     * @remarks
     * - Only adds Morgan logging middleware when debug mode is active
     * - Uses Apache combined log format for detailed request information
     * - Logs are handled through the Dashboard logger instance
     */
    setupMiddlewares(): void;
    /**
     * Sets up basic authentication for the dashboard application.
     *
     * If authentication configuration is provided, this method configures
     * HTTP Basic Authentication middleware using the specified username and password.
     * The middleware will challenge unauthorized requests with a 401 response.
     *
     * @remarks
     * - Only sets up authentication if `this.config.auth` is defined
     * - Uses a single user/password combination from the configuration
     * - Enables challenge mode to prompt for credentials in browsers
     *
     * @example
     * ```typescript
     * // Assuming config.auth = { user: "admin", password: "secret" }
     * dashboard.setupAuth(); // Sets up basic auth for user "admin"
     * ```
     */
    setupAuth(): void;
    /**
     * Sets up EJS templating engine for the dashboard application.
     * This method configures the Express application to use EJS as the view engine,
     * sets the views directory, and specifies the layout file.
     *
     * @remarks
     * - Uses `express-ejs-layouts` for layout support
     * - Sets the views directory to the `views` folder within the package
     * - Serves static files from the `public` directory
     * - Ensures that the EJS engine is ready to render views with layouts
     */
    setupEJS(): void;
    /**
     * Sets up the main application routes for the dashboard.
     *
     * This method initializes and attaches the dashboard, jobs, and queues routers
     * to the Express application instance. It also logs the setup process for debugging purposes.
     *
     * @remarks
     * - Assumes that `this.app` and `this.backend` are initialized.
     * - Uses the routers created by `createDashboardRouter`, `createJobsRouter`, and `createQueuesRouter`.
     */
    setupRoutes(): void;
    /**
     * Starts the dashboard server on the configured port.
     * Logs the startup process and handles any errors that occur during server initialization.
     *
     * @remarks
     * If no port is specified in the configuration, the default port 8678 is used.
     *
     * @returns void
     */
    listen(): void;
    /**
     * Closes the dashboard by shutting down the backend and server,
     * and cleaning up associated resources.
     *
     * - Awaits the closure of the backend if it exists.
     * - Closes the server and logs a message when stopped.
     * - Resets backend, server, config, and app properties to `undefined`.
     * - Logs a debug message indicating resources have been cleaned up.
     *
     * @returns {Promise<void>} Resolves when all resources have been closed and cleaned up.
     */
    close(): Promise<void>;
}

export { DashboardConfig, SidequestDashboard };