@objectstack/runtime 1.0.4 → 1.0.5

package/dist/index.d.ts

@@ -1,15 +1,629 @@
-export { ObjectKernel } from '@objectstack/core';
-export { Runtime } from './runtime.js';
-export type { RuntimeConfig } from './runtime.js';
-export { DriverPlugin } from './driver-plugin.js';
-export { AppPlugin } from './app-plugin.js';
-export { createApiRegistryPlugin } from './api-registry-plugin.js';
-export type { ApiRegistryConfig } from './api-registry-plugin.js';
-export { HttpServer } from './http-server.js';
-export { HttpDispatcher } from './http-dispatcher.js';
-export type { HttpProtocolContext, HttpDispatcherResult } from './http-dispatcher.js';
-export { RestServer } from './rest-server.js';
-export { RouteManager, RouteGroupBuilder } from './route-manager.js';
-export type { RouteEntry } from './route-manager.js';
-export { MiddlewareManager } from './middleware.js';
+import { Plugin, ObjectKernel, IHttpServer, ObjectKernelConfig, PluginContext, RouteHandler, Middleware } from '@objectstack/core';
 export * from '@objectstack/core';
+export { ObjectKernel } from '@objectstack/core';
+import { RestServerConfig, ObjectStackProtocol } from '@objectstack/spec/api';
+import { Shared, System } from '@objectstack/spec';
+import { z } from 'zod';
+import { MiddlewareConfig, MiddlewareType } from '@objectstack/spec/system';
+
+interface ApiRegistryConfig {
+    serverServiceName?: string;
+    protocolServiceName?: string;
+    api?: RestServerConfig;
+}
+/**
+ * ApiRegistryPlugin
+ *
+ * Responsibilities:
+ * 1. Consumes 'http.server' (or configured service)
+ * 2. Consumes 'protocol' (ObjectStackProtocol)
+ * 3. Instantiates RestServer to auto-generate routes
+ */
+declare function createApiRegistryPlugin(config?: ApiRegistryConfig): Plugin;
+
+interface RuntimeConfig {
+    /**
+     * Optional existing server instance (e.g. Hono, Express app)
+     * If provided, Runtime will use it as the 'http.server' service.
+     * If not provided, Runtime expects a server plugin (like HonoServerPlugin) to be registered manually.
+     */
+    server?: IHttpServer;
+    /**
+     * API Registry Configuration
+     */
+    api?: ApiRegistryConfig;
+    /**
+     * Kernel Configuration
+     */
+    kernel?: ObjectKernelConfig;
+}
+/**
+ * ObjectStack Runtime
+ *
+ * High-level entry point for bootstrapping an ObjectStack application.
+ * Wraps ObjectKernel and provides standard orchestration for:
+ * - HTTP Server binding
+ * - API Registry (REST Routes)
+ * - Plugin Management
+ */
+declare class Runtime {
+    readonly kernel: ObjectKernel;
+    constructor(config?: RuntimeConfig);
+    /**
+     * Register a plugin
+     */
+    use(plugin: Plugin): this;
+    /**
+     * Start the runtime
+     * 1. Initializes all plugins (init phase)
+     * 2. Starts all plugins (start phase)
+     */
+    start(): Promise<this>;
+    /**
+     * Get the kernel instance
+     */
+    getKernel(): ObjectKernel;
+}
+
+/**
+ * Driver Plugin
+ *
+ * Generic plugin wrapper for ObjectQL drivers.
+ * Registers a driver with the ObjectQL engine.
+ *
+ * Dependencies: None (Registers service for ObjectQL to discover)
+ * Services: driver.{name}
+ *
+ * @example
+ * const memoryDriver = new InMemoryDriver();
+ * const driverPlugin = new DriverPlugin(memoryDriver, 'memory');
+ * kernel.use(driverPlugin);
+ */
+declare class DriverPlugin implements Plugin {
+    name: string;
+    version: string;
+    private driver;
+    constructor(driver: any, driverName?: string);
+    init: (ctx: PluginContext) => Promise<void>;
+    start: (ctx: PluginContext) => Promise<void>;
+}
+
+/**
+ * AppPlugin
+ *
+ * Adapts a generic App Bundle (Manifest + Runtime Code) into a Kernel Plugin.
+ *
+ * Responsibilities:
+ * 1. Register App Manifest as a service (for ObjectQL discovery)
+ * 2. Execute Runtime `onEnable` hook (for code logic)
+ */
+declare class AppPlugin implements Plugin {
+    name: string;
+    version?: string;
+    private bundle;
+    constructor(bundle: any);
+    init: (ctx: PluginContext) => Promise<void>;
+    start: (ctx: PluginContext) => Promise<void>;
+}
+
+/**
+ * HttpServer - Unified HTTP Server Abstraction
+ *
+ * Provides a framework-agnostic HTTP server interface that wraps
+ * underlying server implementations (Hono, Express, Fastify, etc.)
+ *
+ * This class serves as an adapter between the IHttpServer interface
+ * and concrete server implementations, allowing plugins to register
+ * routes and middleware without depending on specific frameworks.
+ *
+ * Features:
+ * - Unified route registration API
+ * - Middleware management with ordering
+ * - Request/response lifecycle hooks
+ * - Framework-agnostic abstractions
+ */
+declare class HttpServer implements IHttpServer {
+    protected server: IHttpServer;
+    protected routes: Map<string, RouteHandler>;
+    protected middlewares: Middleware[];
+    /**
+     * Create an HTTP server wrapper
+     * @param server - The underlying server implementation (Hono, Express, etc.)
+     */
+    constructor(server: IHttpServer);
+    /**
+     * Register a GET route handler
+     * @param path - Route path (e.g., '/api/users/:id')
+     * @param handler - Route handler function
+     */
+    get(path: string, handler: RouteHandler): void;
+    /**
+     * Register a POST route handler
+     * @param path - Route path
+     * @param handler - Route handler function
+     */
+    post(path: string, handler: RouteHandler): void;
+    /**
+     * Register a PUT route handler
+     * @param path - Route path
+     * @param handler - Route handler function
+     */
+    put(path: string, handler: RouteHandler): void;
+    /**
+     * Register a DELETE route handler
+     * @param path - Route path
+     * @param handler - Route handler function
+     */
+    delete(path: string, handler: RouteHandler): void;
+    /**
+     * Register a PATCH route handler
+     * @param path - Route path
+     * @param handler - Route handler function
+     */
+    patch(path: string, handler: RouteHandler): void;
+    /**
+     * Register middleware
+     * @param path - Optional path to apply middleware to (if omitted, applies globally)
+     * @param handler - Middleware function
+     */
+    use(path: string | Middleware, handler?: Middleware): void;
+    /**
+     * Start the HTTP server
+     * @param port - Port number to listen on
+     * @returns Promise that resolves when server is ready
+     */
+    listen(port: number): Promise<void>;
+    /**
+     * Stop the HTTP server
+     * @returns Promise that resolves when server is stopped
+     */
+    close(): Promise<void>;
+    /**
+     * Get registered routes
+     * @returns Map of route keys to handlers
+     */
+    getRoutes(): Map<string, RouteHandler>;
+    /**
+     * Get registered middlewares
+     * @returns Array of middleware functions
+     */
+    getMiddlewares(): Middleware[];
+}
+
+interface HttpProtocolContext {
+    request: any;
+    response?: any;
+}
+interface HttpDispatcherResult {
+    handled: boolean;
+    response?: {
+        status: number;
+        body?: any;
+        headers?: Record<string, string>;
+    };
+    result?: any;
+}
+declare class HttpDispatcher {
+    private kernel;
+    constructor(kernel: ObjectKernel);
+    private success;
+    private error;
+    private ensureBroker;
+    /**
+     * Generates the discovery JSON response for the API root
+     */
+    getDiscoveryInfo(prefix: string): {
+        name: string;
+        version: string;
+        environment: string | undefined;
+        routes: {
+            data: string;
+            metadata: string;
+            auth: string;
+            graphql: string | undefined;
+            storage: string | undefined;
+            analytics: string | undefined;
+            hub: string | undefined;
+        };
+        features: {
+            graphql: boolean;
+            search: boolean;
+            websockets: boolean;
+            files: boolean;
+            analytics: boolean;
+            hub: boolean;
+        };
+        locale: {
+            default: string;
+            supported: string[];
+            timezone: string;
+        };
+    };
+    /**
+     * Handles GraphQL requests
+     */
+    handleGraphQL(body: {
+        query: string;
+        variables?: any;
+    }, context: HttpProtocolContext): Promise<any>;
+    /**
+     * Handles Auth requests
+     * path: sub-path after /auth/
+     */
+    handleAuth(path: string, method: string, body: any, context: HttpProtocolContext): Promise<HttpDispatcherResult>;
+    /**
+     * Handles Metadata requests
+     * Standard: /metadata/:type/:name
+     * Fallback for backward compat: /metadata (all objects), /metadata/:objectName (get object)
+     */
+    handleMetadata(path: string, context: HttpProtocolContext, method?: string, body?: any): Promise<HttpDispatcherResult>;
+    /**
+     * Handles Data requests
+     * path: sub-path after /data/ (e.g. "contacts", "contacts/123", "contacts/query")
+     */
+    handleData(path: string, method: string, body: any, query: any, context: HttpProtocolContext): Promise<HttpDispatcherResult>;
+    /**
+     * Handles Analytics requests
+     * path: sub-path after /analytics/
+     */
+    handleAnalytics(path: string, method: string, body: any, context: HttpProtocolContext): Promise<HttpDispatcherResult>;
+    /**
+     * Handles Hub requests
+     * path: sub-path after /hub/
+     */
+    handleHub(path: string, method: string, body: any, query: any, context: HttpProtocolContext): Promise<HttpDispatcherResult>;
+    /**
+     * Handles Storage requests
+     * path: sub-path after /storage/
+     */
+    handleStorage(path: string, method: string, file: any, context: HttpProtocolContext): Promise<HttpDispatcherResult>;
+    /**
+     * Handles Automation requests
+     * path: sub-path after /automation/
+     */
+    handleAutomation(path: string, method: string, body: any, context: HttpProtocolContext): Promise<HttpDispatcherResult>;
+    private getServicesMap;
+    private getService;
+    private capitalize;
+    /**
+     * Main Dispatcher Entry Point
+     * Routes the request to the appropriate handler based on path and precedence
+     */
+    dispatch(method: string, path: string, body: any, query: any, context: HttpProtocolContext): Promise<HttpDispatcherResult>;
+    /**
+     * Handles Custom API Endpoints defined in metadata
+     */
+    handleApiEndpoint(path: string, method: string, body: any, query: any, context: HttpProtocolContext): Promise<HttpDispatcherResult>;
+}
+
+type RouteHandlerMetadata = System.RouteHandlerMetadata;
+type HttpMethod = z.infer<typeof Shared.HttpMethod>;
+/**
+ * Route Entry
+ * Internal representation of registered routes
+ */
+interface RouteEntry {
+    method: HttpMethod;
+    path: string;
+    handler: RouteHandler;
+    metadata?: RouteHandlerMetadata['metadata'];
+    security?: RouteHandlerMetadata['security'];
+}
+/**
+ * RouteManager
+ *
+ * Manages route registration and organization for HTTP servers.
+ * Provides:
+ * - Route registration with metadata
+ * - Route lookup and querying
+ * - Bulk route registration
+ * - Route grouping by prefix
+ *
+ * @example
+ * const manager = new RouteManager(server);
+ *
+ * // Register individual route
+ * manager.register({
+ *   method: 'GET',
+ *   path: '/api/users/:id',
+ *   handler: getUserHandler,
+ *   metadata: {
+ *     summary: 'Get user by ID',
+ *     tags: ['users']
+ *   }
+ * });
+ *
+ * // Register route group
+ * manager.group('/api/users', (group) => {
+ *   group.get('/', listUsersHandler);
+ *   group.post('/', createUserHandler);
+ *   group.get('/:id', getUserHandler);
+ * });
+ */
+declare class RouteManager {
+    private server;
+    private routes;
+    constructor(server: IHttpServer);
+    /**
+     * Register a route
+     * @param entry - Route entry with method, path, handler, and metadata
+     */
+    register(entry: Omit<RouteEntry, 'handler'> & {
+        handler: RouteHandler | string;
+    }): void;
+    /**
+     * Register multiple routes
+     * @param entries - Array of route entries
+     */
+    registerMany(entries: Array<Omit<RouteEntry, 'handler'> & {
+        handler: RouteHandler | string;
+    }>): void;
+    /**
+     * Unregister a route
+     * @param method - HTTP method
+     * @param path - Route path
+     */
+    unregister(method: HttpMethod, path: string): void;
+    /**
+     * Get route by method and path
+     * @param method - HTTP method
+     * @param path - Route path
+     */
+    get(method: HttpMethod, path: string): RouteEntry | undefined;
+    /**
+     * Get all routes
+     */
+    getAll(): RouteEntry[];
+    /**
+     * Get routes by method
+     * @param method - HTTP method
+     */
+    getByMethod(method: HttpMethod): RouteEntry[];
+    /**
+     * Get routes by path prefix
+     * @param prefix - Path prefix
+     */
+    getByPrefix(prefix: string): RouteEntry[];
+    /**
+     * Get routes by tag
+     * @param tag - Tag name
+     */
+    getByTag(tag: string): RouteEntry[];
+    /**
+     * Create a route group with common prefix
+     * @param prefix - Common path prefix
+     * @param configure - Function to configure routes in the group
+     */
+    group(prefix: string, configure: (group: RouteGroupBuilder) => void): void;
+    /**
+     * Get route count
+     */
+    count(): number;
+    /**
+     * Clear all routes
+     */
+    clear(): void;
+    /**
+     * Get route key for storage
+     */
+    private getRouteKey;
+    /**
+     * Register route with underlying server
+     */
+    private registerWithServer;
+}
+/**
+ * RouteGroupBuilder
+ *
+ * Builder for creating route groups with common prefix
+ */
+declare class RouteGroupBuilder {
+    private manager;
+    private prefix;
+    constructor(manager: RouteManager, prefix: string);
+    /**
+     * Register GET route in group
+     */
+    get(path: string, handler: RouteHandler, metadata?: RouteHandlerMetadata['metadata']): this;
+    /**
+     * Register POST route in group
+     */
+    post(path: string, handler: RouteHandler, metadata?: RouteHandlerMetadata['metadata']): this;
+    /**
+     * Register PUT route in group
+     */
+    put(path: string, handler: RouteHandler, metadata?: RouteHandlerMetadata['metadata']): this;
+    /**
+     * Register PATCH route in group
+     */
+    patch(path: string, handler: RouteHandler, metadata?: RouteHandlerMetadata['metadata']): this;
+    /**
+     * Register DELETE route in group
+     */
+    delete(path: string, handler: RouteHandler, metadata?: RouteHandlerMetadata['metadata']): this;
+    /**
+     * Resolve full path with prefix
+     */
+    private resolvePath;
+}
+
+/**
+ * RestServer
+ *
+ * Provides automatic REST API endpoint generation for ObjectStack.
+ * Generates standard RESTful CRUD endpoints, metadata endpoints, and batch operations
+ * based on the configured protocol provider.
+ *
+ * Features:
+ * - Automatic CRUD endpoint generation (GET, POST, PUT, PATCH, DELETE)
+ * - Metadata API endpoints (/meta)
+ * - Batch operation endpoints (/batch, /createMany, /updateMany, /deleteMany)
+ * - Discovery endpoint
+ * - Configurable path prefixes and patterns
+ *
+ * @example
+ * const restServer = new RestServer(httpServer, protocolProvider, {
+ *   api: {
+ *     version: 'v1',
+ *     basePath: '/api'
+ *   },
+ *   crud: {
+ *     dataPrefix: '/data'
+ *   }
+ * });
+ *
+ * restServer.registerRoutes();
+ */
+declare class RestServer {
+    private protocol;
+    private config;
+    private routeManager;
+    constructor(server: IHttpServer, protocol: ObjectStackProtocol, config?: RestServerConfig);
+    /**
+     * Normalize configuration with defaults
+     */
+    private normalizeConfig;
+    /**
+     * Get the full API base path
+     */
+    private getApiBasePath;
+    /**
+     * Register all REST API routes
+     */
+    registerRoutes(): void;
+    /**
+     * Register discovery endpoints
+     */
+    private registerDiscoveryEndpoints;
+    /**
+     * Register metadata endpoints
+     */
+    private registerMetadataEndpoints;
+    /**
+     * Register CRUD endpoints for data operations
+     */
+    private registerCrudEndpoints;
+    /**
+     * Register batch operation endpoints
+     */
+    private registerBatchEndpoints;
+    /**
+     * Get the route manager
+     */
+    getRouteManager(): RouteManager;
+    /**
+     * Get all registered routes
+     */
+    getRoutes(): RouteEntry[];
+}
+
+/**
+ * Middleware Entry
+ * Internal representation of registered middleware
+ */
+interface MiddlewareEntry {
+    name: string;
+    type: MiddlewareType;
+    middleware: Middleware;
+    order: number;
+    enabled: boolean;
+    paths?: {
+        include?: string[];
+        exclude?: string[];
+    };
+}
+/**
+ * MiddlewareManager
+ *
+ * Manages middleware registration, ordering, and execution.
+ * Provides fine-grained control over middleware chains with:
+ * - Execution order management
+ * - Path-based filtering
+ * - Enable/disable individual middleware
+ * - Middleware categorization by type
+ *
+ * @example
+ * const manager = new MiddlewareManager();
+ *
+ * // Register middleware with configuration
+ * manager.register({
+ *   name: 'auth',
+ *   type: 'authentication',
+ *   order: 10,
+ *   paths: { exclude: ['/health', '/metrics'] }
+ * }, authMiddleware);
+ *
+ * // Get sorted middleware chain
+ * const chain = manager.getMiddlewareChain();
+ * chain.forEach(mw => server.use(mw));
+ */
+declare class MiddlewareManager {
+    private middlewares;
+    constructor();
+    /**
+     * Register middleware with configuration
+     * @param config - Middleware configuration
+     * @param middleware - Middleware function
+     */
+    register(config: MiddlewareConfig, middleware: Middleware): void;
+    /**
+     * Unregister middleware by name
+     * @param name - Middleware name
+     */
+    unregister(name: string): void;
+    /**
+     * Enable middleware by name
+     * @param name - Middleware name
+     */
+    enable(name: string): void;
+    /**
+     * Disable middleware by name
+     * @param name - Middleware name
+     */
+    disable(name: string): void;
+    /**
+     * Get middleware entry by name
+     * @param name - Middleware name
+     */
+    get(name: string): MiddlewareEntry | undefined;
+    /**
+     * Get all middleware entries
+     */
+    getAll(): MiddlewareEntry[];
+    /**
+     * Get middleware by type
+     * @param type - Middleware type
+     */
+    getByType(type: MiddlewareType): MiddlewareEntry[];
+    /**
+     * Get middleware chain sorted by order
+     * Returns only enabled middleware
+     */
+    getMiddlewareChain(): Middleware[];
+    /**
+     * Get middleware chain with path filtering
+     * @param path - Request path to match against
+     */
+    getMiddlewareChainForPath(path: string): Middleware[];
+    /**
+     * Match path against pattern (simple glob matching)
+     * @param path - Request path
+     * @param pattern - Pattern to match (supports * wildcard)
+     */
+    private matchPath;
+    /**
+     * Clear all middleware
+     */
+    clear(): void;
+    /**
+     * Get middleware count
+     */
+    count(): number;
+    /**
+     * Create a composite middleware from the chain
+     * This can be used to apply all middleware at once
+     */
+    createCompositeMiddleware(): Middleware;
+}
+
+export { type ApiRegistryConfig, AppPlugin, DriverPlugin, HttpDispatcher, type HttpDispatcherResult, type HttpProtocolContext, HttpServer, MiddlewareManager, RestServer, type RouteEntry, RouteGroupBuilder, RouteManager, Runtime, type RuntimeConfig, createApiRegistryPlugin };