Add capability contract interfaces (IHttpServer and IDataEngine)

Co-authored-by: hotlong <50353452+hotlong@users.noreply.github.com>

Author: Copilot

packages/runtime/src/index.ts

@@ -15,3 +15,7 @@ export { ObjectStackRuntimeProtocol } from './protocol.js';
 // Export Types
 export * from './types.js';
 
+// Export Interfaces (Capability Contracts)
+export * from './interfaces/http-server.js';
+export * from './interfaces/data-engine.js';
+

packages/runtime/src/interfaces/data-engine.ts

@@ -0,0 +1,122 @@
+/**
+ * IDataEngine - Standard Data Engine Interface
+ * 
+ * Abstract interface for data persistence capabilities.
+ * This allows plugins to interact with data engines without knowing
+ * the underlying implementation (SQL, MongoDB, Memory, etc.).
+ * 
+ * Follows Dependency Inversion Principle - plugins depend on this interface,
+ * not on concrete database implementations.
+ */
+
+/**
+ * Query filter conditions
+ */
+export interface QueryFilter {
+    [field: string]: any;
+}
+
+/**
+ * Query options for find operations
+ */
+export interface QueryOptions {
+    /** Filter conditions */
+    filter?: QueryFilter;
+    /** Fields to select */
+    select?: string[];
+    /** Sort order */
+    sort?: Record<string, 1 | -1 | 'asc' | 'desc'>;
+    /** Limit number of results */
+    limit?: number;
+    /** Skip number of results (for pagination) */
+    skip?: number;
+    /** Maximum number of results (alternative to limit) */
+    top?: number;
+}
+
+/**
+ * IDataEngine - Data persistence capability interface
+ * 
+ * Defines the contract for data engine implementations.
+ * Concrete implementations (ObjectQL, Prisma, TypeORM) should implement this interface.
+ */
+export interface IDataEngine {
+    /**
+     * Insert a new record
+     * 
+     * @param objectName - Name of the object/table (e.g., 'user', 'order')
+     * @param data - Data to insert
+     * @returns Promise resolving to the created record (including generated ID)
+     * 
+     * @example
+     * ```ts
+     * const user = await engine.insert('user', {
+     *   name: 'John Doe',
+     *   email: 'john@example.com'
+     * });
+     * console.log(user.id); // Auto-generated ID
+     * ```
+     */
+    insert(objectName: string, data: any): Promise<any>;
+    
+    /**
+     * Find records matching a query
+     * 
+     * @param objectName - Name of the object/table
+     * @param query - Query conditions (optional)
+     * @returns Promise resolving to an array of matching records
+     * 
+     * @example
+     * ```ts
+     * // Find all users
+     * const allUsers = await engine.find('user');
+     * 
+     * // Find with filter
+     * const activeUsers = await engine.find('user', {
+     *   filter: { status: 'active' }
+     * });
+     * 
+     * // Find with limit and sort
+     * const recentUsers = await engine.find('user', {
+     *   sort: { createdAt: -1 },
+     *   limit: 10
+     * });
+     * ```
+     */
+    find(objectName: string, query?: QueryOptions): Promise<any[]>;
+    
+    /**
+     * Update a record by ID
+     * 
+     * @param objectName - Name of the object/table
+     * @param id - Record ID
+     * @param data - Updated data (partial update)
+     * @returns Promise resolving to the updated record
+     * 
+     * @example
+     * ```ts
+     * const updatedUser = await engine.update('user', '123', {
+     *   name: 'Jane Doe',
+     *   email: 'jane@example.com'
+     * });
+     * ```
+     */
+    update(objectName: string, id: any, data: any): Promise<any>;
+    
+    /**
+     * Delete a record by ID
+     * 
+     * @param objectName - Name of the object/table
+     * @param id - Record ID
+     * @returns Promise resolving to true if deleted, false otherwise
+     * 
+     * @example
+     * ```ts
+     * const deleted = await engine.delete('user', '123');
+     * if (deleted) {
+     *   console.log('User deleted successfully');
+     * }
+     * ```
+     */
+    delete(objectName: string, id: any): Promise<boolean>;
+}

packages/runtime/src/interfaces/http-server.ts

@@ -0,0 +1,140 @@
+/**
+ * IHttpServer - Standard HTTP Server Interface
+ * 
+ * Abstract interface for HTTP server capabilities.
+ * This allows plugins to interact with HTTP servers without knowing
+ * the underlying implementation (Express, Fastify, Hono, etc.).
+ * 
+ * Follows Dependency Inversion Principle - plugins depend on this interface,
+ * not on concrete HTTP framework implementations.
+ */
+
+/**
+ * Generic HTTP Request type
+ * Abstraction over framework-specific request objects
+ */
+export interface IHttpRequest {
+    /** Request path parameters */
+    params: Record<string, string>;
+    /** Request query parameters */
+    query: Record<string, string | string[]>;
+    /** Request body */
+    body?: any;
+    /** Request headers */
+    headers: Record<string, string | string[]>;
+    /** HTTP method */
+    method: string;
+    /** Request path */
+    path: string;
+}
+
+/**
+ * Generic HTTP Response type
+ * Abstraction over framework-specific response objects
+ */
+export interface IHttpResponse {
+    /**
+     * Send a JSON response
+     * @param data - Data to send
+     */
+    json(data: any): void | Promise<void>;
+    
+    /**
+     * Send a text/html response
+     * @param data - Data to send
+     */
+    send(data: string): void | Promise<void>;
+    
+    /**
+     * Set HTTP status code
+     * @param code - HTTP status code
+     */
+    status(code: number): IHttpResponse;
+    
+    /**
+     * Set response header
+     * @param name - Header name
+     * @param value - Header value
+     */
+    header(name: string, value: string): IHttpResponse;
+}
+
+/**
+ * Route handler function
+ */
+export type RouteHandler = (
+    req: IHttpRequest,
+    res: IHttpResponse
+) => void | Promise<void>;
+
+/**
+ * Middleware function
+ */
+export type Middleware = (
+    req: IHttpRequest,
+    res: IHttpResponse,
+    next: () => void | Promise<void>
+) => void | Promise<void>;
+
+/**
+ * IHttpServer - HTTP Server capability interface
+ * 
+ * Defines the contract for HTTP server implementations.
+ * Concrete implementations (Express, Fastify, Hono) should implement this interface.
+ */
+export interface 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>;
+}