@objectstack/runtime 0.6.0 → 0.7.1

package/src/route-manager.ts

@@ -0,0 +1,305 @@
+import { RouteHandler, IHttpServer } from '@objectstack/core';
+import { System, Shared } from '@objectstack/spec';
+
+type RouteHandlerMetadata = System.RouteHandlerMetadata;
+type HttpMethod = Shared.HttpMethod;
+
+/**
+ * Route Entry
+ * Internal representation of registered routes
+ */
+export 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);
+ * });
+ */
+export class RouteManager {
+    private server: IHttpServer;
+    private routes: Map<string, RouteEntry>;
+    
+    constructor(server: IHttpServer) {
+        this.server = server;
+        this.routes = new Map();
+    }
+    
+    /**
+     * Register a route
+     * @param entry - Route entry with method, path, handler, and metadata
+     */
+    register(entry: Omit<RouteEntry, 'handler'> & { handler: RouteHandler | string }): void {
+        // Validate handler type - string handlers not yet supported
+        if (typeof entry.handler === 'string') {
+            throw new Error(
+                `String-based route handlers are not supported yet. ` +
+                `Received handler identifier "${entry.handler}". ` +
+                `Please provide a RouteHandler function instead.`
+            );
+        }
+        
+        const handler: RouteHandler = entry.handler;
+        
+        const routeEntry: RouteEntry = {
+            method: entry.method,
+            path: entry.path,
+            handler,
+            metadata: entry.metadata,
+            security: entry.security,
+        };
+        
+        const key = this.getRouteKey(entry.method, entry.path);
+        this.routes.set(key, routeEntry);
+        
+        // Register with underlying server
+        this.registerWithServer(routeEntry);
+    }
+    
+    /**
+     * Register multiple routes
+     * @param entries - Array of route entries
+     */
+    registerMany(entries: Array<Omit<RouteEntry, 'handler'> & { handler: RouteHandler | string }>): void {
+        entries.forEach(entry => this.register(entry));
+    }
+    
+    /**
+     * Unregister a route
+     * @param method - HTTP method
+     * @param path - Route path
+     */
+    unregister(method: HttpMethod, path: string): void {
+        const key = this.getRouteKey(method, path);
+        this.routes.delete(key);
+        // Note: Most server frameworks don't support unregistering routes at runtime
+        // This just removes it from our registry
+    }
+    
+    /**
+     * Get route by method and path
+     * @param method - HTTP method
+     * @param path - Route path
+     */
+    get(method: HttpMethod, path: string): RouteEntry | undefined {
+        const key = this.getRouteKey(method, path);
+        return this.routes.get(key);
+    }
+    
+    /**
+     * Get all routes
+     */
+    getAll(): RouteEntry[] {
+        return Array.from(this.routes.values());
+    }
+    
+    /**
+     * Get routes by method
+     * @param method - HTTP method
+     */
+    getByMethod(method: HttpMethod): RouteEntry[] {
+        return this.getAll().filter(route => route.method === method);
+    }
+    
+    /**
+     * Get routes by path prefix
+     * @param prefix - Path prefix
+     */
+    getByPrefix(prefix: string): RouteEntry[] {
+        return this.getAll().filter(route => route.path.startsWith(prefix));
+    }
+    
+    /**
+     * Get routes by tag
+     * @param tag - Tag name
+     */
+    getByTag(tag: string): RouteEntry[] {
+        return this.getAll().filter(route => 
+            route.metadata?.tags?.includes(tag)
+        );
+    }
+    
+    /**
+     * 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 {
+        const builder = new RouteGroupBuilder(this, prefix);
+        configure(builder);
+    }
+    
+    /**
+     * Get route count
+     */
+    count(): number {
+        return this.routes.size;
+    }
+    
+    /**
+     * Clear all routes
+     */
+    clear(): void {
+        this.routes.clear();
+    }
+    
+    /**
+     * Get route key for storage
+     */
+    private getRouteKey(method: HttpMethod, path: string): string {
+        return `${method}:${path}`;
+    }
+    
+    /**
+     * Register route with underlying server
+     */
+    private registerWithServer(entry: RouteEntry): void {
+        const { method, path, handler } = entry;
+        
+        switch (method) {
+            case 'GET':
+                this.server.get(path, handler);
+                break;
+            case 'POST':
+                this.server.post(path, handler);
+                break;
+            case 'PUT':
+                this.server.put(path, handler);
+                break;
+            case 'DELETE':
+                this.server.delete(path, handler);
+                break;
+            case 'PATCH':
+                this.server.patch(path, handler);
+                break;
+            default:
+                throw new Error(`Unsupported HTTP method: ${method}`);
+        }
+    }
+}
+
+/**
+ * RouteGroupBuilder
+ * 
+ * Builder for creating route groups with common prefix
+ */
+export class RouteGroupBuilder {
+    private manager: RouteManager;
+    private prefix: string;
+    
+    constructor(manager: RouteManager, prefix: string) {
+        this.manager = manager;
+        this.prefix = prefix;
+    }
+    
+    /**
+     * Register GET route in group
+     */
+    get(path: string, handler: RouteHandler, metadata?: RouteHandlerMetadata['metadata']): this {
+        this.manager.register({
+            method: 'GET',
+            path: this.resolvePath(path),
+            handler,
+            metadata,
+        });
+        return this;
+    }
+    
+    /**
+     * Register POST route in group
+     */
+    post(path: string, handler: RouteHandler, metadata?: RouteHandlerMetadata['metadata']): this {
+        this.manager.register({
+            method: 'POST',
+            path: this.resolvePath(path),
+            handler,
+            metadata,
+        });
+        return this;
+    }
+    
+    /**
+     * Register PUT route in group
+     */
+    put(path: string, handler: RouteHandler, metadata?: RouteHandlerMetadata['metadata']): this {
+        this.manager.register({
+            method: 'PUT',
+            path: this.resolvePath(path),
+            handler,
+            metadata,
+        });
+        return this;
+    }
+    
+    /**
+     * Register PATCH route in group
+     */
+    patch(path: string, handler: RouteHandler, metadata?: RouteHandlerMetadata['metadata']): this {
+        this.manager.register({
+            method: 'PATCH',
+            path: this.resolvePath(path),
+            handler,
+            metadata,
+        });
+        return this;
+    }
+    
+    /**
+     * Register DELETE route in group
+     */
+    delete(path: string, handler: RouteHandler, metadata?: RouteHandlerMetadata['metadata']): this {
+        this.manager.register({
+            method: 'DELETE',
+            path: this.resolvePath(path),
+            handler,
+            metadata,
+        });
+        return this;
+    }
+    
+    /**
+     * Resolve full path with prefix
+     */
+    private resolvePath(path: string): string {
+        // Normalize slashes
+        const normalizedPrefix = this.prefix.endsWith('/') 
+            ? this.prefix.slice(0, -1) 
+            : this.prefix;
+        const normalizedPath = path.startsWith('/') 
+            ? path 
+            : '/' + path;
+        
+        return normalizedPrefix + normalizedPath;
+    }
+}

package/dist/app-manifest-plugin.d.ts

@@ -1,19 +0,0 @@
-import { Plugin, PluginContext } from '@objectstack/core';
-/**
- * AppManifestPlugin
- *
- * Adapts a static Manifest JSON into a dynamic Kernel Service.
- * This allows the ObjectQL Engine to "discover" this app during its start phase.
- *
- * Flow:
- * 1. AppPlugin registers `app.<id>` service (init phase)
- * 2. ObjectQL Engine discovers `app.*` services (start phase)
- */
-export declare class AppManifestPlugin implements Plugin {
-    name: string;
-    version?: string;
-    private manifest;
-    constructor(manifest: any);
-    init(ctx: PluginContext): Promise<void>;
-    start(ctx: PluginContext): Promise<void>;
-}

package/dist/app-manifest-plugin.js

@@ -1,33 +0,0 @@
-/**
- * AppManifestPlugin
- *
- * Adapts a static Manifest JSON into a dynamic Kernel Service.
- * This allows the ObjectQL Engine to "discover" this app during its start phase.
- *
- * Flow:
- * 1. AppPlugin registers `app.<id>` service (init phase)
- * 2. ObjectQL Engine discovers `app.*` services (start phase)
- */
-export class AppManifestPlugin {
-    constructor(manifest) {
-        this.manifest = manifest;
-        // Support both direct manifest (legacy) and Stack Definition (nested manifest)
-        const sys = manifest.manifest || manifest;
-        const appId = sys.id || sys.name || 'unnamed-app';
-        this.name = `plugin.app.${appId}`; // Unique plugin name
-        this.version = sys.version;
-    }
-    async init(ctx) {
-        // Support both direct manifest (legacy) and Stack Definition (nested manifest)
-        const sys = this.manifest.manifest || this.manifest;
-        const appId = sys.id || sys.name;
-        ctx.logger.log(`[AppManifestPlugin] Registering App Service: ${appId}`);
-        // Register the app manifest as a service
-        const serviceName = `app.${appId}`;
-        ctx.registerService(serviceName, this.manifest);
-    }
-    async start(ctx) {
-        // No logic needed here. 
-        // Logic is inverted: The Engine will pull data from this service.
-    }
-}

package/dist/test-interfaces.d.ts

@@ -1,7 +0,0 @@
-/**
- * Test file to verify capability contract interfaces
- *
- * This file demonstrates how plugins can implement the IHttpServer
- * and IDataEngine interfaces without depending on concrete implementations.
- */
-export {};

package/dist/test-interfaces.js

@@ -1,138 +0,0 @@
-/**
- * Test file to verify capability contract interfaces
- *
- * This file demonstrates how plugins can implement the IHttpServer
- * and IDataEngine interfaces without depending on concrete implementations.
- */
-/**
- * Example: Mock HTTP Server Plugin
- *
- * Shows how a plugin can implement the IHttpServer interface
- * without depending on Express, Fastify, or any specific framework.
- */
-class MockHttpServer {
-    constructor() {
-        this.routes = new Map();
-    }
-    get(path, handler) {
-        this.routes.set(`GET:${path}`, { method: 'GET', handler });
-        console.log(`✅ Registered GET ${path}`);
-    }
-    post(path, handler) {
-        this.routes.set(`POST:${path}`, { method: 'POST', handler });
-        console.log(`✅ Registered POST ${path}`);
-    }
-    put(path, handler) {
-        this.routes.set(`PUT:${path}`, { method: 'PUT', handler });
-        console.log(`✅ Registered PUT ${path}`);
-    }
-    delete(path, handler) {
-        this.routes.set(`DELETE:${path}`, { method: 'DELETE', handler });
-        console.log(`✅ Registered DELETE ${path}`);
-    }
-    patch(path, handler) {
-        this.routes.set(`PATCH:${path}`, { method: 'PATCH', handler });
-        console.log(`✅ Registered PATCH ${path}`);
-    }
-    use(path, handler) {
-        console.log(`✅ Registered middleware`);
-    }
-    async listen(port) {
-        console.log(`✅ Mock HTTP server listening on port ${port}`);
-    }
-    async close() {
-        console.log(`✅ Mock HTTP server closed`);
-    }
-}
-/**
- * Example: Mock Data Engine Plugin
- *
- * Shows how a plugin can implement the IDataEngine interface
- * without depending on ObjectQL, Prisma, or any specific database.
- */
-class MockDataEngine {
-    constructor() {
-        this.store = new Map();
-        this.idCounter = 0;
-    }
-    async insert(objectName, data) {
-        if (!this.store.has(objectName)) {
-            this.store.set(objectName, new Map());
-        }
-        const id = `${objectName}_${++this.idCounter}`;
-        const record = { id, ...data };
-        this.store.get(objectName).set(id, record);
-        console.log(`✅ Inserted into ${objectName}:`, record);
-        return record;
-    }
-    async find(objectName, query) {
-        const objectStore = this.store.get(objectName);
-        if (!objectStore) {
-            return [];
-        }
-        const results = Array.from(objectStore.values());
-        console.log(`✅ Found ${results.length} records in ${objectName}`);
-        return results;
-    }
-    async update(objectName, id, data) {
-        const objectStore = this.store.get(objectName);
-        if (!objectStore || !objectStore.has(id)) {
-            throw new Error(`Record ${id} not found in ${objectName}`);
-        }
-        const existing = objectStore.get(id);
-        const updated = { ...existing, ...data };
-        objectStore.set(id, updated);
-        console.log(`✅ Updated ${objectName}/${id}:`, updated);
-        return updated;
-    }
-    async delete(objectName, id) {
-        const objectStore = this.store.get(objectName);
-        if (!objectStore) {
-            return false;
-        }
-        const deleted = objectStore.delete(id);
-        console.log(`✅ Deleted ${objectName}/${id}: ${deleted}`);
-        return deleted;
-    }
-}
-/**
- * Test the interfaces
- */
-async function testInterfaces() {
-    console.log('\n=== Testing IHttpServer Interface ===\n');
-    const httpServer = new MockHttpServer();
-    // Register routes using the interface
-    httpServer.get('/api/users', async (req, res) => {
-        res.json({ users: [] });
-    });
-    httpServer.post('/api/users', async (req, res) => {
-        res.status(201).json({ id: 1, ...req.body });
-    });
-    await httpServer.listen(3000);
-    console.log('\n=== Testing IDataEngine Interface ===\n');
-    const dataEngine = new MockDataEngine();
-    // Use the data engine interface
-    const user1 = await dataEngine.insert('user', {
-        name: 'John Doe',
-        email: 'john@example.com'
-    });
-    const user2 = await dataEngine.insert('user', {
-        name: 'Jane Smith',
-        email: 'jane@example.com'
-    });
-    const users = await dataEngine.find('user');
-    console.log(`Found ${users.length} users after inserts`);
-    const updatedUser = await dataEngine.update('user', user1.id, {
-        name: 'John Updated'
-    });
-    console.log(`Updated user:`, updatedUser);
-    const deleted = await dataEngine.delete('user', user2.id);
-    console.log(`Delete result: ${deleted}`);
-    console.log('\n✅ All interface tests passed!\n');
-    if (httpServer.close) {
-        await httpServer.close();
-    }
-}
-// Run tests
-testInterfaces().catch(console.error);
-export {};

package/src/app-manifest-plugin.ts

@@ -1,48 +0,0 @@
-import { Plugin, PluginContext } from '@objectstack/core';
-
-/**
- * AppManifestPlugin
- * 
- * Adapts a static Manifest JSON into a dynamic Kernel Service.
- * This allows the ObjectQL Engine to "discover" this app during its start phase.
- * 
- * Flow:
- * 1. AppPlugin registers `app.<id>` service (init phase)
- * 2. ObjectQL Engine discovers `app.*` services (start phase)
- */
-export class AppManifestPlugin implements Plugin {
-    name: string;
-    version?: string;
-    
-    // Dependencies removed: This plugin produces data. It doesn't need to consume the engine to register itself.
-    // Making it dependency-free allows it to initialize BEFORE the engine if needed.
-    
-    private manifest: any;
-
-    constructor(manifest: any) {
-        this.manifest = manifest;
-        // Support both direct manifest (legacy) and Stack Definition (nested manifest)
-        const sys = manifest.manifest || manifest;
-        const appId = sys.id || sys.name || 'unnamed-app';
-        
-        this.name = `plugin.app.${appId}`; // Unique plugin name
-        this.version = sys.version;
-    }
-
-    async init(ctx: PluginContext) {
-        // Support both direct manifest (legacy) and Stack Definition (nested manifest)
-        const sys = this.manifest.manifest || this.manifest;
-        const appId = sys.id || sys.name;
-
-        ctx.logger.log(`[AppManifestPlugin] Registering App Service: ${appId}`);
-        
-        // Register the app manifest as a service
-        const serviceName = `app.${appId}`;
-        ctx.registerService(serviceName, this.manifest);
-    }
-
-    async start(ctx: PluginContext) {
-        // No logic needed here. 
-        // Logic is inverted: The Engine will pull data from this service.
-    }
-}