digitaltwin-core/dist/components/handler.d.ts

Minimalist framework to collect and handle data in a Digital Twin project

/**
 * @fileoverview Handler component base class for HTTP endpoint providers
 *
 * Handlers are lightweight, stateless components that expose HTTP endpoints
 * for on-demand data access, computation, or utility services within the digital twin.
 */
import type { Component, Servable } from './interfaces.js';
import type { ComponentConfiguration } from './types.js';
import type { DataResponse } from './types.js';
import type { HttpMethod } from '../engine/endpoints.js';
import type { OpenAPIDocumentable, OpenAPIComponentSpec } from '../openapi/types.js';
/**
 * Runtime descriptor for an HTTP endpoint handler.
 *
 * Represents a fully resolved endpoint with its bound handler function,
 * ready for registration with the Express router.
 */
type EndpointDescriptor = {
    /** HTTP method for the endpoint */
    method: HttpMethod;
    /** URL path pattern */
    path: string;
    /** Response content type */
    responseType?: string;
    /** Bound handler function */
    handler: (...args: any[]) => Promise<DataResponse>;
};
/**
 * Abstract base class for Handler components.
 *
 * Handlers are lightweight, stateless components that expose HTTP endpoints
 * for on-demand data access, computation, or utility services. Unlike Collectors
 * and Harvesters, they don't run on schedules but respond to HTTP requests.
 *
 * Key features:
 * - Expose HTTP endpoints using the @servableEndpoint decorator
 * - Stateless operation (no database or storage dependencies by default)
 * - Suitable for real-time computations, data queries, or API proxies
 *
 * @example
 * ```typescript
 * class CalculatorHandler extends Handler {
 *   getConfiguration() {
 *     return {
 *       name: 'calculator-handler',
 *       type: 'handler',
 *       contentType: 'application/json'
 *     };
 *   }
 *
 *   @servableEndpoint({ path: '/api/calculate/sum', method: 'post' })
 *   async calculateSum(req: Request) {
 *     const { a, b } = req.body;
 *     return {
 *       status: 200,
 *       content: { result: a + b }
 *     };
 *   }
 * }
 * ```
 */
export declare abstract class Handler implements Component, Servable, OpenAPIDocumentable {
    /**
     * Returns the handler's configuration.
     *
     * Implementations must provide basic component information including
     * name, type, and default content type for responses.
     *
     * @returns Component configuration object
     *
     * @example
     * ```typescript
     * getConfiguration() {
     *   return {
     *     name: 'my-handler',
     *     type: 'handler',
     *     contentType: 'application/json'
     *   };
     * }
     * ```
     */
    abstract getConfiguration(): ComponentConfiguration;
    /**
     * Resolves and returns HTTP endpoints defined on this handler.
     *
     * Automatically discovers endpoints declared with the @servableEndpoint
     * decorator and creates bound handler functions for registration with
     * the Express router.
     *
     * @returns Array of endpoint descriptors with bound handler functions
     */
    getEndpoints(): EndpointDescriptor[];
    /**
     * Returns the OpenAPI specification for this handler's endpoints.
     *
     * Generates documentation for all endpoints declared with @servableEndpoint.
     * Can be overridden by subclasses for more detailed specifications.
     *
     * @returns {OpenAPIComponentSpec} OpenAPI paths, tags, and schemas for this handler
     */
    getOpenAPISpec(): OpenAPIComponentSpec;
}
export {};
//# sourceMappingURL=handler.d.ts.map