Phase 1 complete: Type alignment - extend runtime types for ObjectQL compatibility

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

Author: Copilot

packages/foundation/core/src/app.ts

@@ -108,26 +108,30 @@ export class ObjectQL implements IObjectQL {
 
     on(event: HookName, objectName: string, handler: HookHandler, packageName?: string) {
         // Delegate to kernel hook manager
-        // Note: Type casting needed due to type incompatibility between ObjectQL HookName (includes beforeCount)
-        // and runtime HookName. This is safe as the kernel will accept all hook types.
-        this.kernel.hooks.register(event as any, objectName, handler as any, packageName);
+        // We wrap the handler to bridge ObjectQL's rich context types with runtime's base types
+        // The runtime HookContext supports all fields via index signature, so this is safe
+        const wrappedHandler = handler as unknown as import('@objectstack/runtime').HookHandler;
+        this.kernel.hooks.register(event, objectName, wrappedHandler, packageName);
     }
 
     async triggerHook(event: HookName, objectName: string, ctx: HookContext) {
         // Delegate to kernel hook manager
-        await this.kernel.hooks.trigger(event as any, objectName, ctx as any);
+        // Runtime HookContext supports ObjectQL-specific fields via index signature
+        await this.kernel.hooks.trigger(event, objectName, ctx);
     }
 
     registerAction(objectName: string, actionName: string, handler: ActionHandler, packageName?: string) {
         // Delegate to kernel action manager
-        // Note: Type casting needed due to type incompatibility between ObjectQL ActionHandler
-        // (includes input/api fields) and runtime ActionHandler. This is safe as runtime is more permissive.
-        this.kernel.actions.register(objectName, actionName, handler as any, packageName);
+        // We wrap the handler to bridge ObjectQL's rich context types with runtime's base types
+        // The runtime ActionContext supports all fields via index signature, so this is safe
+        const wrappedHandler = handler as unknown as import('@objectstack/runtime').ActionHandler;
+        this.kernel.actions.register(objectName, actionName, wrappedHandler, packageName);
     }
 
     async executeAction(objectName: string, actionName: string, ctx: ActionContext) {
         // Delegate to kernel action manager
-        return await this.kernel.actions.execute(objectName, actionName, ctx as any);
+        // Runtime ActionContext supports ObjectQL-specific fields via index signature
+        return await this.kernel.actions.execute(objectName, actionName, ctx);
     }
 
     createContext(options: ObjectQLContextOptions): ObjectQLContext {

packages/objectstack/runtime/src/actions.ts

@@ -19,20 +19,61 @@ export class RuntimeError extends Error {
 /**
  * Action Context
  * Context passed to action handlers
+ * 
+ * Extended to support ObjectQL's rich context requirements including:
+ * - Database API access for performing operations
+ * - User session information
+ * - Validated input parameters
+ * - Record ID for record-level actions
  */
 export interface ActionContext {
     /** Object name */
     objectName: string;
+    
     /** Action name */
     actionName: string;
-    /** Input data */
+    
+    /** Input data (legacy field, prefer 'input' for ObjectQL) */
     data?: any;
-    /** Record IDs (for record-level actions) */
+    
+    /** Record IDs (for record-level actions, legacy array form) */
     ids?: string[];
+    
     /** User context */
-    user?: any;
+    user?: {
+        id: string | number;
+        [key: string]: any;
+    };
+    
     /** Additional metadata */
     metadata?: any;
+    
+    /** 
+     * The ID of the record being acted upon (ObjectQL extension)
+     * Only available if type is 'record'
+     */
+    id?: string | number;
+    
+    /**
+     * The validated input arguments (ObjectQL extension)
+     * Prefer this over 'data' for typed action inputs
+     */
+    input?: any;
+    
+    /**
+     * Database Access API (ObjectQL extension)
+     * Same interface as used in hooks
+     */
+    api?: {
+        find(objectName: string, query?: any): Promise<any[]>;
+        findOne(objectName: string, id: string | number): Promise<any>;
+        count(objectName: string, query?: any): Promise<number>;
+        create(objectName: string, data: any): Promise<any>;
+        update(objectName: string, id: string | number, data: any): Promise<any>;
+        delete(objectName: string, id: string | number): Promise<any>;
+    };
+    
+    /** Allow additional properties for extensibility */
     [key: string]: any;
 }
 

packages/objectstack/runtime/src/hooks.ts

@@ -8,6 +8,8 @@
 export type HookName = 
     | 'beforeFind'
     | 'afterFind'
+    | 'beforeCount'
+    | 'afterCount'
     | 'beforeCreate'
     | 'afterCreate'
     | 'beforeUpdate'
@@ -17,21 +19,75 @@ export type HookName =
     | 'beforeValidate'
     | 'afterValidate';
 
+/**
+ * HookAPI - Minimal API surface exposed to hooks for performing side-effects or checks
+ * Allows hooks to perform database operations without circular dependencies
+ */
+export interface HookAPI {
+    find(objectName: string, query?: any): Promise<any[]>;
+    findOne(objectName: string, id: string | number): Promise<any>;
+    count(objectName: string, query?: any): Promise<number>;
+    create(objectName: string, data: any): Promise<any>;
+    update(objectName: string, id: string | number, data: any): Promise<any>;
+    delete(objectName: string, id: string | number): Promise<any>;
+}
+
 /**
  * Hook Context
  * Context passed to hook handlers
+ * 
+ * Extended to support ObjectQL's rich context requirements including:
+ * - Database API access for cross-object operations
+ * - User session information
+ * - Shared state between before/after hooks
+ * - Operation type tracking
+ * - Query/result data for retrieval operations
+ * - Record data for mutation operations
  */
 export interface HookContext {
     /** Object name */
     objectName: string;
-    /** Current data */
+    
+    /** Current data (for create/update operations) */
     data?: any;
+    
     /** Original data (for updates) */
     originalData?: any;
+    
     /** User context */
-    user?: any;
+    user?: {
+        id: string | number;
+        [key: string]: any;
+    };
+    
     /** Additional metadata */
     metadata?: any;
+    
+    /** The triggering operation (ObjectQL extension) */
+    operation?: 'find' | 'count' | 'create' | 'update' | 'delete';
+    
+    /** Access to the database/engine to perform extra queries (ObjectQL extension) */
+    api?: HookAPI;
+    
+    /** 
+     * Shared state for passing data between matching 'before' and 'after' hooks (ObjectQL extension)
+     * e.g. Calculate a diff in 'beforeUpdate' and read it in 'afterUpdate'
+     */
+    state?: Record<string, any>;
+    
+    /** The query criteria being executed (for retrieval operations, ObjectQL extension) */
+    query?: any;
+    
+    /** The result of the query/operation (available in 'after' hooks, ObjectQL extension) */
+    result?: any;
+    
+    /** The record ID (for update/delete operations, ObjectQL extension) */
+    id?: string | number;
+    
+    /** The existing record fetched from DB before operation (ObjectQL extension) */
+    previousData?: any;
+    
+    /** Allow additional properties for extensibility */
     [key: string]: any;
 }