Add core runtime features to @objectstack/runtime (metadata, hooks, actions)

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

Author: Copilot

packages/objectstack/runtime/src/actions.ts

@@ -0,0 +1,114 @@
+/**
+ * @objectstack/runtime
+ * Action System - Custom action management
+ * 
+ * Provides a system for registering and executing custom actions on objects
+ */
+
+/**
+ * Action Context
+ * Context passed to action handlers
+ */
+export interface ActionContext {
+    /** Object name */
+    objectName: string;
+    /** Action name */
+    actionName: string;
+    /** Input data */
+    data?: any;
+    /** Record IDs (for record-level actions) */
+    ids?: string[];
+    /** User context */
+    user?: any;
+    /** Additional metadata */
+    metadata?: any;
+    [key: string]: any;
+}
+
+/**
+ * Action Handler
+ * Function signature for action handlers
+ */
+export type ActionHandler = (ctx: ActionContext) => any | Promise<any>;
+
+/**
+ * Action Entry
+ * Internal representation of a registered action
+ */
+export interface ActionEntry {
+    handler: ActionHandler;
+    packageName?: string;
+}
+
+/**
+ * Action Manager
+ * Manages registration and execution of custom actions
+ */
+export class ActionManager {
+    private actions: Map<string, ActionEntry> = new Map();
+
+    /**
+     * Register an action
+     * @param objectName - Object name
+     * @param actionName - Action name
+     * @param handler - Action handler function
+     * @param packageName - Package name for tracking
+     */
+    register(
+        objectName: string,
+        actionName: string,
+        handler: ActionHandler,
+        packageName?: string
+    ): void {
+        const key = `${objectName}:${actionName}`;
+        this.actions.set(key, { handler, packageName });
+    }
+
+    /**
+     * Execute an action
+     * @param objectName - Object name
+     * @param actionName - Action name
+     * @param ctx - Action context
+     * @returns Action result
+     */
+    async execute(
+        objectName: string,
+        actionName: string,
+        ctx: ActionContext
+    ): Promise<any> {
+        const key = `${objectName}:${actionName}`;
+        const entry = this.actions.get(key);
+        
+        if (!entry) {
+            throw new Error(`Action '${actionName}' not found for object '${objectName}'`);
+        }
+        
+        return await entry.handler(ctx);
+    }
+
+    /**
+     * Check if an action exists
+     */
+    has(objectName: string, actionName: string): boolean {
+        const key = `${objectName}:${actionName}`;
+        return this.actions.has(key);
+    }
+
+    /**
+     * Remove actions from a package
+     */
+    removePackage(packageName: string): void {
+        for (const [key, entry] of this.actions.entries()) {
+            if (entry.packageName === packageName) {
+                this.actions.delete(key);
+            }
+        }
+    }
+
+    /**
+     * Clear all actions
+     */
+    clear(): void {
+        this.actions.clear();
+    }
+}

packages/objectstack/runtime/src/hooks.ts

@@ -0,0 +1,114 @@
+/**
+ * @objectstack/runtime
+ * Hook System - Event lifecycle management
+ * 
+ * Provides a generic hook system for lifecycle events (before/after CRUD operations)
+ */
+
+export type HookName = 
+    | 'beforeFind'
+    | 'afterFind'
+    | 'beforeCreate'
+    | 'afterCreate'
+    | 'beforeUpdate'
+    | 'afterUpdate'
+    | 'beforeDelete'
+    | 'afterDelete'
+    | 'beforeValidate'
+    | 'afterValidate';
+
+/**
+ * Hook Context
+ * Context passed to hook handlers
+ */
+export interface HookContext {
+    /** Object name */
+    objectName: string;
+    /** Current data */
+    data?: any;
+    /** Original data (for updates) */
+    originalData?: any;
+    /** User context */
+    user?: any;
+    /** Additional metadata */
+    metadata?: any;
+    [key: string]: any;
+}
+
+/**
+ * Hook Handler
+ * Function signature for hook handlers
+ */
+export type HookHandler = (ctx: HookContext) => void | Promise<void>;
+
+/**
+ * Hook Entry
+ * Internal representation of a registered hook
+ */
+export interface HookEntry {
+    objectName: string;
+    handler: HookHandler;
+    packageName?: string;
+}
+
+/**
+ * Hook Manager
+ * Manages registration and execution of hooks
+ */
+export class HookManager {
+    private hooks: Map<HookName, HookEntry[]> = new Map();
+
+    /**
+     * Register a hook
+     */
+    register(
+        event: HookName,
+        objectName: string,
+        handler: HookHandler,
+        packageName?: string
+    ): void {
+        if (!this.hooks.has(event)) {
+            this.hooks.set(event, []);
+        }
+        
+        const entries = this.hooks.get(event)!;
+        entries.push({ objectName, handler, packageName });
+    }
+
+    /**
+     * Trigger hooks for an event
+     */
+    async trigger(
+        event: HookName,
+        objectName: string,
+        ctx: HookContext
+    ): Promise<void> {
+        const entries = this.hooks.get(event) || [];
+        
+        for (const entry of entries) {
+            // Match on wildcard '*' or specific object name
+            if (entry.objectName === '*' || entry.objectName === objectName) {
+                await entry.handler(ctx);
+            }
+        }
+    }
+
+    /**
+     * Remove hooks from a package
+     */
+    removePackage(packageName: string): void {
+        for (const [event, entries] of this.hooks.entries()) {
+            this.hooks.set(
+                event,
+                entries.filter(e => e.packageName !== packageName)
+            );
+        }
+    }
+
+    /**
+     * Clear all hooks
+     */
+    clear(): void {
+        this.hooks.clear();
+    }
+}

packages/objectstack/runtime/src/index.ts

@@ -5,6 +5,16 @@
  * This package defines the runtime types for the ObjectStack ecosystem.
  */
 
+// Import core modules for use in kernel
+import { MetadataRegistry } from './metadata';
+import { HookManager } from './hooks';
+import { ActionManager } from './actions';
+
+// Export core runtime modules
+export * from './metadata';
+export * from './hooks';
+export * from './actions';
+
 /**
  * Runtime Context
  * Provides access to the ObjectStack kernel during plugin execution
@@ -38,19 +48,52 @@ export interface RuntimePlugin {
 export class ObjectStackKernel {
     /** Query interface (QL) */
     public ql: unknown = null;
+    
+    /** Metadata registry */
+    public metadata: MetadataRegistry;
+    
+    /** Hook manager */
+    public hooks: HookManager;
+    
+    /** Action manager */
+    public actions: ActionManager;
+    
+    /** Registered plugins */
+    private plugins: RuntimePlugin[] = [];
 
     constructor(plugins: RuntimePlugin[] = []) {
-        // Stub implementation
+        this.plugins = plugins;
+        this.metadata = new MetadataRegistry();
+        this.hooks = new HookManager();
+        this.actions = new ActionManager();
     }
 
     /** Start the kernel */
     async start(): Promise<void> {
-        // Stub implementation
+        // Install all plugins
+        for (const plugin of this.plugins) {
+            if (plugin.install) {
+                await plugin.install({ engine: this });
+            }
+        }
+        
+        // Start all plugins
+        for (const plugin of this.plugins) {
+            if (plugin.onStart) {
+                await plugin.onStart({ engine: this });
+            }
+        }
     }
 
     /** Stop the kernel */
     async stop(): Promise<void> {
-        // Stub implementation
+        // Stop all plugins in reverse order
+        for (let i = this.plugins.length - 1; i >= 0; i--) {
+            const plugin = this.plugins[i];
+            if (plugin.onStop) {
+                await plugin.onStop({ engine: this });
+            }
+        }
     }
 
     /** Seed initial data */