@objectstack/runtime 0.6.1 → 0.7.1

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @objectstack/runtime
 
+## 0.7.1
+
+### Patch Changes
+
+- Patch release for maintenance and stability improvements
+- Updated dependencies
+  - @objectstack/spec@0.7.1
+  - @objectstack/types@0.7.1
+  - @objectstack/core@0.7.1
+
 ## 0.6.1
 
 ### Patch Changes

package/dist/app-plugin.js

@@ -19,34 +19,62 @@ export class AppPlugin {
     async init(ctx) {
         const sys = this.bundle.manifest || this.bundle;
         const appId = sys.id || sys.name;
-        ctx.logger?.log(`[AppPlugin] Registering App Service: ${appId}`);
+        ctx.logger.info('Registering App Service', {
+            appId,
+            pluginName: this.name,
+            version: this.version
+        });
         // Register the app manifest as a service
         // ObjectQLPlugin will discover this and call ql.registerApp()
         const serviceName = `app.${appId}`;
-        ctx.registerService(serviceName, this.bundle.manifest || this.bundle);
+        // Merge manifest with the bundle to ensure objects/apps are accessible at root
+        // This supports both Legacy Manifests and new Stack Definitions
+        const servicePayload = this.bundle.manifest
+            ? { ...this.bundle.manifest, ...this.bundle }
+            : this.bundle;
+        ctx.registerService(serviceName, servicePayload);
     }
     async start(ctx) {
+        const sys = this.bundle.manifest || this.bundle;
+        const appId = sys.id || sys.name;
         // Execute Runtime Step
         // Retrieve ObjectQL engine from services
         // We cast to any/ObjectQL because ctx.getService returns unknown
         const ql = ctx.getService('objectql');
         if (!ql) {
-            ctx.logger?.warn(`[AppPlugin] ObjectQL engine service not found for app: ${this.name}`);
+            ctx.logger.warn('ObjectQL engine service not found', {
+                appName: this.name,
+                appId
+            });
             return;
         }
+        ctx.logger.debug('Retrieved ObjectQL engine service', { appId });
         const runtime = this.bundle.default || this.bundle;
         if (runtime && typeof runtime.onEnable === 'function') {
-            ctx.logger?.log(`[AppPlugin] Executing runtime.onEnable for: ${this.name}`);
+            ctx.logger.info('Executing runtime.onEnable', {
+                appName: this.name,
+                appId
+            });
             // Construct the Host Context (mirroring old ObjectQL.use logic)
             const hostContext = {
                 ...ctx,
                 ql,
-                logger: ctx.logger || console,
+                logger: ctx.logger,
                 drivers: {
-                    register: (driver) => ql.registerDriver(driver)
+                    register: (driver) => {
+                        ctx.logger.debug('Registering driver via app runtime', {
+                            driverName: driver.name,
+                            appId
+                        });
+                        ql.registerDriver(driver);
+                    }
                 },
             };
             await runtime.onEnable(hostContext);
+            ctx.logger.debug('Runtime.onEnable completed', { appId });
+        }
+        else {
+            ctx.logger.debug('No runtime.onEnable function found', { appId });
         }
     }
 }

package/dist/driver-plugin.js

@@ -22,10 +22,14 @@ export class DriverPlugin {
         // Register driver as a service instead of directly to objectql
         const serviceName = `driver.${this.driver.name || 'unknown'}`;
         ctx.registerService(serviceName, this.driver);
-        ctx.logger.log(`[DriverPlugin] Registered driver service: ${serviceName}`);
+        ctx.logger.info('Driver service registered', {
+            serviceName,
+            driverName: this.driver.name,
+            driverVersion: this.driver.version
+        });
     }
     async start(ctx) {
         // Drivers don't need start phase, initialization happens in init
-        ctx.logger.log(`[DriverPlugin] Driver ready: ${this.driver.name || 'unknown'}`);
+        ctx.logger.debug('Driver plugin started', { driverName: this.driver.name || 'unknown' });
     }
 }

package/dist/http-server.d.ts

@@ -0,0 +1,84 @@
+import { IHttpServer, RouteHandler, Middleware } from '@objectstack/core';
+/**
+ * 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
+ */
+export 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[];
+}

package/dist/http-server.js

@@ -0,0 +1,125 @@
+/**
+ * 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
+ */
+export class HttpServer {
+    /**
+     * Create an HTTP server wrapper
+     * @param server - The underlying server implementation (Hono, Express, etc.)
+     */
+    constructor(server) {
+        this.server = server;
+        this.routes = new Map();
+        this.middlewares = [];
+    }
+    /**
+     * Register a GET route handler
+     * @param path - Route path (e.g., '/api/users/:id')
+     * @param handler - Route handler function
+     */
+    get(path, handler) {
+        const key = `GET:${path}`;
+        this.routes.set(key, handler);
+        this.server.get(path, handler);
+    }
+    /**
+     * Register a POST route handler
+     * @param path - Route path
+     * @param handler - Route handler function
+     */
+    post(path, handler) {
+        const key = `POST:${path}`;
+        this.routes.set(key, handler);
+        this.server.post(path, handler);
+    }
+    /**
+     * Register a PUT route handler
+     * @param path - Route path
+     * @param handler - Route handler function
+     */
+    put(path, handler) {
+        const key = `PUT:${path}`;
+        this.routes.set(key, handler);
+        this.server.put(path, handler);
+    }
+    /**
+     * Register a DELETE route handler
+     * @param path - Route path
+     * @param handler - Route handler function
+     */
+    delete(path, handler) {
+        const key = `DELETE:${path}`;
+        this.routes.set(key, handler);
+        this.server.delete(path, handler);
+    }
+    /**
+     * Register a PATCH route handler
+     * @param path - Route path
+     * @param handler - Route handler function
+     */
+    patch(path, handler) {
+        const key = `PATCH:${path}`;
+        this.routes.set(key, handler);
+        this.server.patch(path, handler);
+    }
+    /**
+     * Register middleware
+     * @param path - Optional path to apply middleware to (if omitted, applies globally)
+     * @param handler - Middleware function
+     */
+    use(path, handler) {
+        if (typeof path === 'function') {
+            // Global middleware
+            this.middlewares.push(path);
+            this.server.use(path);
+        }
+        else if (handler) {
+            // Path-specific middleware
+            this.middlewares.push(handler);
+            this.server.use(path, handler);
+        }
+    }
+    /**
+     * Start the HTTP server
+     * @param port - Port number to listen on
+     * @returns Promise that resolves when server is ready
+     */
+    async listen(port) {
+        await this.server.listen(port);
+    }
+    /**
+     * Stop the HTTP server
+     * @returns Promise that resolves when server is stopped
+     */
+    async close() {
+        if (this.server.close) {
+            await this.server.close();
+        }
+    }
+    /**
+     * Get registered routes
+     * @returns Map of route keys to handlers
+     */
+    getRoutes() {
+        return new Map(this.routes);
+    }
+    /**
+     * Get registered middlewares
+     * @returns Array of middleware functions
+     */
+    getMiddlewares() {
+        return [...this.middlewares];
+    }
+}

package/dist/index.d.ts

@@ -1,4 +1,8 @@
 export { ObjectKernel } from '@objectstack/core';
-export { DriverPlugin } from './driver-plugin';
-export { AppPlugin } from './app-plugin';
+export { DriverPlugin } from './driver-plugin.js';
+export { AppPlugin } from './app-plugin.js';
+export { HttpServer } from './http-server.js';
+export { RestServer } from './rest-server.js';
+export { RouteManager, RouteGroupBuilder } from './route-manager.js';
+export { MiddlewareManager } from './middleware.js';
 export * from '@objectstack/core';

package/dist/index.js

@@ -1,7 +1,12 @@
 // Export Kernels
 export { ObjectKernel } from '@objectstack/core';
 // Export Plugins
-export { DriverPlugin } from './driver-plugin';
-export { AppPlugin } from './app-plugin';
+export { DriverPlugin } from './driver-plugin.js';
+export { AppPlugin } from './app-plugin.js';
+// Export HTTP Server Components
+export { HttpServer } from './http-server.js';
+export { RestServer } from './rest-server.js';
+export { RouteManager, RouteGroupBuilder } from './route-manager.js';
+export { MiddlewareManager } from './middleware.js';
 // Export Types
 export * from '@objectstack/core';

package/dist/middleware.d.ts

@@ -0,0 +1,111 @@
+import { Middleware } from '@objectstack/core';
+import { MiddlewareConfig, MiddlewareType } from '@objectstack/spec/system';
+/**
+ * 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));
+ */
+export 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 {};

package/dist/middleware.js

@@ -0,0 +1,176 @@
+/**
+ * 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));
+ */
+export class MiddlewareManager {
+    constructor() {
+        this.middlewares = new Map();
+    }
+    /**
+     * Register middleware with configuration
+     * @param config - Middleware configuration
+     * @param middleware - Middleware function
+     */
+    register(config, middleware) {
+        const entry = {
+            name: config.name,
+            type: config.type,
+            middleware,
+            order: config.order ?? 100,
+            enabled: config.enabled ?? true,
+            paths: config.paths,
+        };
+        this.middlewares.set(config.name, entry);
+    }
+    /**
+     * Unregister middleware by name
+     * @param name - Middleware name
+     */
+    unregister(name) {
+        this.middlewares.delete(name);
+    }
+    /**
+     * Enable middleware by name
+     * @param name - Middleware name
+     */
+    enable(name) {
+        const entry = this.middlewares.get(name);
+        if (entry) {
+            entry.enabled = true;
+        }
+    }
+    /**
+     * Disable middleware by name
+     * @param name - Middleware name
+     */
+    disable(name) {
+        const entry = this.middlewares.get(name);
+        if (entry) {
+            entry.enabled = false;
+        }
+    }
+    /**
+     * Get middleware entry by name
+     * @param name - Middleware name
+     */
+    get(name) {
+        return this.middlewares.get(name);
+    }
+    /**
+     * Get all middleware entries
+     */
+    getAll() {
+        return Array.from(this.middlewares.values());
+    }
+    /**
+     * Get middleware by type
+     * @param type - Middleware type
+     */
+    getByType(type) {
+        return this.getAll().filter(entry => entry.type === type);
+    }
+    /**
+     * Get middleware chain sorted by order
+     * Returns only enabled middleware
+     */
+    getMiddlewareChain() {
+        return this.getAll()
+            .filter(entry => entry.enabled)
+            .sort((a, b) => a.order - b.order)
+            .map(entry => entry.middleware);
+    }
+    /**
+     * Get middleware chain with path filtering
+     * @param path - Request path to match against
+     */
+    getMiddlewareChainForPath(path) {
+        return this.getAll()
+            .filter(entry => {
+            if (!entry.enabled)
+                return false;
+            // Check path filters
+            if (entry.paths) {
+                // Check exclude patterns
+                if (entry.paths.exclude) {
+                    const excluded = entry.paths.exclude.some(pattern => this.matchPath(path, pattern));
+                    if (excluded)
+                        return false;
+                }
+                // Check include patterns (if specified)
+                if (entry.paths.include) {
+                    const included = entry.paths.include.some(pattern => this.matchPath(path, pattern));
+                    if (!included)
+                        return false;
+                }
+            }
+            return true;
+        })
+            .sort((a, b) => a.order - b.order)
+            .map(entry => entry.middleware);
+    }
+    /**
+     * Match path against pattern (simple glob matching)
+     * @param path - Request path
+     * @param pattern - Pattern to match (supports * wildcard)
+     */
+    matchPath(path, pattern) {
+        // Convert glob pattern to regex
+        const regexPattern = pattern
+            .replace(/\*/g, '.*')
+            .replace(/\?/g, '.');
+        const regex = new RegExp(`^${regexPattern}$`);
+        return regex.test(path);
+    }
+    /**
+     * Clear all middleware
+     */
+    clear() {
+        this.middlewares.clear();
+    }
+    /**
+     * Get middleware count
+     */
+    count() {
+        return this.middlewares.size;
+    }
+    /**
+     * Create a composite middleware from the chain
+     * This can be used to apply all middleware at once
+     */
+    createCompositeMiddleware() {
+        const chain = this.getMiddlewareChain();
+        return async (req, res, next) => {
+            let index = 0;
+            const executeNext = async () => {
+                if (index >= chain.length) {
+                    await next();
+                    return;
+                }
+                const middleware = chain[index++];
+                await middleware(req, res, executeNext);
+            };
+            await executeNext();
+        };
+    }
+}