@objectstack/core 0.6.1 → 0.7.2

package/examples/enhanced-kernel-example.ts

@@ -0,0 +1,309 @@
+/**
+ * Enhanced ObjectKernel Example
+ * 
+ * Demonstrates advanced plugin features:
+ * - Version compatibility
+ * - Service factories with lifecycle management
+ * - Plugin timeout control
+ * - Startup failure rollback
+ * - Health checks
+ * - Performance metrics
+ * - Graceful shutdown
+ */
+
+import { 
+  EnhancedObjectKernel, 
+  PluginMetadata, 
+  ServiceLifecycle,
+  PluginContext 
+} from '../index.js';
+
+// ============================================================================
+// Example 1: Database Plugin with Health Checks
+// ============================================================================
+
+const databasePlugin: PluginMetadata = {
+  name: 'database',
+  version: '1.0.0',
+  startupTimeout: 10000, // 10 second timeout
+  
+  async init(ctx: PluginContext) {
+    ctx.logger.info('Initializing database plugin');
+    
+    // Register database service using factory
+    // This creates a singleton that's initialized once
+    const db = {
+      connected: false,
+      async connect() {
+        ctx.logger.info('Connecting to database...');
+        await new Promise(resolve => setTimeout(resolve, 100)); // Simulate connection
+        this.connected = true;
+        ctx.logger.info('Database connected');
+      },
+      async disconnect() {
+        ctx.logger.info('Disconnecting from database...');
+        this.connected = false;
+      },
+      async query(sql: string) {
+        if (!this.connected) {
+          throw new Error('Database not connected');
+        }
+        return { rows: [] };
+      }
+    };
+    
+    ctx.registerService('db', db);
+  },
+  
+  async start(ctx: PluginContext) {
+    const db = ctx.getService<any>('db');
+    await db.connect();
+  },
+  
+  async destroy() {
+    // Cleanup on shutdown
+    console.log('Cleaning up database connection');
+  },
+  
+  async healthCheck() {
+    // Health check returns status
+    return {
+      healthy: true,
+      message: 'Database is operational',
+      details: {
+        connections: 5,
+        responseTime: 45
+      }
+    };
+  }
+};
+
+// ============================================================================
+// Example 2: API Plugin with Dependencies
+// ============================================================================
+
+const apiPlugin: PluginMetadata = {
+  name: 'api',
+  version: '2.1.0',
+  dependencies: ['database'], // Requires database plugin to be loaded first
+  
+  async init(ctx: PluginContext) {
+    ctx.logger.info('Initializing API plugin');
+    
+    // Access database service (guaranteed to exist due to dependencies)
+    const db = ctx.getService<any>('db');
+    
+    const api = {
+      async getUsers() {
+        return await db.query('SELECT * FROM users');
+      },
+      async createUser(data: any) {
+        return await db.query('INSERT INTO users VALUES ...', data);
+      }
+    };
+    
+    ctx.registerService('api', api);
+  },
+  
+  async healthCheck() {
+    return {
+      healthy: true,
+      message: 'API is ready',
+      details: {
+        routes: 15,
+        activeRequests: 3
+      }
+    };
+  }
+};
+
+// ============================================================================
+// Example 3: Cache Plugin with Scoped Services
+// ============================================================================
+
+const cachePlugin: PluginMetadata = {
+  name: 'cache',
+  version: '1.2.3',
+  
+  async init(ctx: PluginContext) {
+    ctx.logger.info('Initializing cache plugin');
+    
+    // Simple in-memory cache
+    const cache = new Map<string, any>();
+    
+    ctx.registerService('cache', {
+      get(key: string) {
+        return cache.get(key);
+      },
+      set(key: string, value: any) {
+        cache.set(key, value);
+      },
+      clear() {
+        cache.clear();
+      }
+    });
+  },
+  
+  async healthCheck() {
+    return {
+      healthy: true,
+      message: 'Cache is operational'
+    };
+  }
+};
+
+// ============================================================================
+// Example 4: Using Service Factories
+// ============================================================================
+
+async function setupServiceFactories(kernel: EnhancedObjectKernel) {
+  // Singleton: Created once, shared across all requests
+  kernel.registerServiceFactory(
+    'logger-service',
+    (ctx) => {
+      return {
+        log: (message: string) => {
+          ctx.logger.info(message);
+        }
+      };
+    },
+    ServiceLifecycle.SINGLETON
+  );
+  
+  // Transient: New instance on every request
+  kernel.registerServiceFactory(
+    'request-id',
+    () => {
+      return `req-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+    },
+    ServiceLifecycle.TRANSIENT
+  );
+  
+  // Scoped: One instance per scope (e.g., per HTTP request)
+  kernel.registerServiceFactory(
+    'user-session',
+    () => {
+      return {
+        id: Math.random().toString(36),
+        data: new Map<string, any>()
+      };
+    },
+    ServiceLifecycle.SCOPED
+  );
+}
+
+// ============================================================================
+// Main Application
+// ============================================================================
+
+async function main() {
+  console.log('🚀 Starting Enhanced ObjectKernel Example\n');
+  
+  // Create enhanced kernel with configuration
+  const kernel = new EnhancedObjectKernel({
+    logger: {
+      level: 'info',
+      format: 'pretty'
+    },
+    defaultStartupTimeout: 30000,  // 30 seconds
+    gracefulShutdown: true,
+    shutdownTimeout: 60000,        // 60 seconds
+    rollbackOnFailure: true,       // Rollback on failure
+  });
+  
+  // Setup service factories
+  await setupServiceFactories(kernel);
+  
+  // Register plugins
+  await kernel.use(databasePlugin);
+  await kernel.use(cachePlugin);
+  await kernel.use(apiPlugin);
+  
+  console.log('📦 Plugins registered\n');
+  
+  // Bootstrap kernel
+  console.log('⚡ Bootstrapping kernel...\n');
+  await kernel.bootstrap();
+  
+  console.log('\n✅ Kernel started successfully!\n');
+  
+  // Show plugin metrics
+  console.log('📊 Plugin Startup Metrics:');
+  const metrics = kernel.getPluginMetrics();
+  for (const [name, time] of metrics) {
+    console.log(`   ${name}: ${time}ms`);
+  }
+  console.log('');
+  
+  // Check plugin health
+  console.log('🏥 Plugin Health Status:');
+  const healthStatuses = await kernel.checkAllPluginsHealth();
+  for (const [name, health] of healthStatuses) {
+    const status = health.healthy ? '✅' : '❌';
+    console.log(`   ${status} ${name}: ${health.message}`);
+    if (health.details) {
+      console.log(`      Details:`, health.details);
+    }
+  }
+  console.log('');
+  
+  // Use services
+  console.log('🔧 Using services:');
+  const db = kernel.getService<any>('db');
+  console.log('   Database connected:', db.connected);
+  
+  const cache = kernel.getService<any>('cache');
+  cache.set('user:1', { name: 'John Doe' });
+  console.log('   Cached user:', cache.get('user:1'));
+  
+  const api = kernel.getService<any>('api');
+  console.log('   API ready:', !!api);
+  console.log('');
+  
+  // Test service factories
+  console.log('🏭 Testing Service Factories:');
+  
+  // Singleton - same instance
+  const logger1 = await kernel.getServiceAsync('logger-service');
+  const logger2 = await kernel.getServiceAsync('logger-service');
+  console.log('   Singleton test:', logger1 === logger2 ? 'PASS ✅' : 'FAIL ❌');
+  
+  // Transient - different instances
+  const id1 = await kernel.getServiceAsync('request-id');
+  const id2 = await kernel.getServiceAsync('request-id');
+  console.log('   Transient test:', id1 !== id2 ? 'PASS ✅' : 'FAIL ❌');
+  console.log('   Generated IDs:', id1, 'and', id2);
+  
+  // Scoped - same within scope, different across scopes
+  const session1a = await kernel.getServiceAsync('user-session', 'request-1');
+  const session1b = await kernel.getServiceAsync('user-session', 'request-1');
+  const session2 = await kernel.getServiceAsync('user-session', 'request-2');
+  console.log('   Scoped (same scope):', session1a === session1b ? 'PASS ✅' : 'FAIL ❌');
+  console.log('   Scoped (diff scope):', session1a !== session2 ? 'PASS ✅' : 'FAIL ❌');
+  console.log('');
+  
+  // Register custom shutdown handler
+  kernel.onShutdown(async () => {
+    console.log('🧹 Running custom cleanup...');
+  });
+  
+  // Simulate running for a bit
+  console.log('⏳ Running for 2 seconds...\n');
+  await new Promise(resolve => setTimeout(resolve, 2000));
+  
+  // Graceful shutdown
+  console.log('🛑 Initiating graceful shutdown...\n');
+  await kernel.shutdown();
+  
+  console.log('\n✅ Shutdown complete!\n');
+}
+
+// Run the example
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch(error => {
+    console.error('❌ Error:', error);
+    process.exit(1);
+  });
+}
+
+export { main };

package/package.json

@@ -1,17 +1,32 @@
 {
   "name": "@objectstack/core",
-  "version": "0.6.1",
+  "version": "0.7.2",
   "description": "Microkernel Core for ObjectStack",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "devDependencies": {
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "vitest": "^1.0.0",
+    "@types/node": "^20.0.0"
   },
   "dependencies": {
-    "@objectstack/spec": "0.6.1"
+    "pino": "^8.17.0",
+    "pino-pretty": "^10.3.0",
+    "zod": "^3.22.0",
+    "@objectstack/spec": "0.7.2"
+  },
+  "peerDependencies": {
+    "pino": "^8.0.0"
+  },
+  "peerDependenciesMeta": {
+    "pino": {
+      "optional": true
+    }
   },
   "scripts": {
-    "build": "tsc"
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
 }

package/src/contracts/data-engine.ts

@@ -1,5 +1,14 @@
-import { QueryAST } from '@objectstack/spec/data';
-import { DriverOptions } from '@objectstack/spec/system';
+import { 
+  DataEngineQueryOptions, 
+  DataEngineInsertOptions, 
+  DataEngineUpdateOptions, 
+  DataEngineDeleteOptions,
+  DataEngineAggregateOptions, 
+  DataEngineCountOptions,
+  DataEngineRequest, // Added Request type for batch
+  QueryAST,
+  DriverOptions
+} from '@objectstack/spec/data';
 
 /**
  * IDataEngine - Standard Data Engine Interface
@@ -7,32 +16,33 @@ import { DriverOptions } from '@objectstack/spec/system';
  * Abstract interface for data persistence capabilities.
  * Following the Dependency Inversion Principle - plugins depend on this interface,
  * not on concrete database implementations.
+ * 
+ * Aligned with 'src/data/data-engine.zod.ts' in @objectstack/spec.
  */
 
-export interface DataEngineFilter {
-  [key: string]: any;
-}
-
-export interface DataEngineQueryOptions {
-  /** Filter conditions */
-  filter?: DataEngineFilter;
-  /** Fields to select */
-  select?: string[];
-  /** Sort order */
-  sort?: Record<string, 1 | -1 | 'asc' | 'desc'>;
-  /** Limit number of results */
-  limit?: number;
-  /** Skip number of results */
-  skip?: number;
-  /** Maximum number of results */
-  top?: number;
-}
-
 export interface IDataEngine {
-  insert(objectName: string, data: any): Promise<any>;
   find(objectName: string, query?: DataEngineQueryOptions): Promise<any[]>;
-  update(objectName: string, id: any, data: any): Promise<any>;
-  delete(objectName: string, id: any): Promise<boolean>;
+  findOne(objectName: string, query?: DataEngineQueryOptions): Promise<any>;
+  insert(objectName: string, data: any | any[], options?: DataEngineInsertOptions): Promise<any>;
+  update(objectName: string, data: any, options?: DataEngineUpdateOptions): Promise<any>;
+  delete(objectName: string, options?: DataEngineDeleteOptions): Promise<any>;
+  count(objectName: string, query?: DataEngineCountOptions): Promise<number>;
+  aggregate(objectName: string, query: DataEngineAggregateOptions): Promise<any[]>;
+  
+  /**
+   * Vector Search (AI/RAG)
+   */
+  vectorFind?(objectName: string, vector: number[], options?: { filter?: any, limit?: number, select?: string[], threshold?: number }): Promise<any[]>;
+
+  /**
+   * Batch Operations (Transactional)
+   */
+  batch?(requests: DataEngineRequest[], options?: { transaction?: boolean }): Promise<any[]>;
+
+  /**
+   * Execute raw command (Escape hatch)
+   */
+  execute?(command: any, options?: Record<string, any>): Promise<any>;
 }
 
 export interface DriverInterface {
@@ -47,6 +57,18 @@ export interface DriverInterface {
   update(object: string, id: any, data: any, options?: DriverOptions): Promise<any>;
   delete(object: string, id: any, options?: DriverOptions): Promise<any>;
   
+  /**
+   * Bulk & Batch Operations
+   */
+  bulkCreate?(object: string, data: any[], options?: DriverOptions): Promise<any>;
+  updateMany?(object: string, query: QueryAST, data: any, options?: DriverOptions): Promise<any>;
+  deleteMany?(object: string, query: QueryAST, options?: DriverOptions): Promise<any>;
+
   count?(object: string, query: QueryAST, options?: DriverOptions): Promise<number>;
+  
+  /**
+   * Raw Execution
+   */
+  execute?(command: any, params?: any, options?: DriverOptions): Promise<any>;
 }
 

package/src/contracts/logger.ts

@@ -0,0 +1,70 @@
+/**
+ * Logger Contract
+ * 
+ * Defines the interface for logging in ObjectStack.
+ * Compatible with both browser console and structured logging systems.
+ */
+export interface Logger {
+    /**
+     * Log a debug message
+     * @param message - The message to log
+     * @param meta - Optional metadata to include
+     */
+    debug(message: string, meta?: Record<string, any>): void;
+
+    /**
+     * Log an informational message
+     * @param message - The message to log
+     * @param meta - Optional metadata to include
+     */
+    info(message: string, meta?: Record<string, any>): void;
+
+    /**
+     * Log a warning message
+     * @param message - The message to log
+     * @param meta - Optional metadata to include
+     */
+    warn(message: string, meta?: Record<string, any>): void;
+
+    /**
+     * Log an error message
+     * @param message - The message to log
+     * @param error - Optional error object
+     * @param meta - Optional metadata to include
+     */
+    error(message: string, error?: Error, meta?: Record<string, any>): void;
+
+    /**
+     * Log a fatal error message
+     * @param message - The message to log
+     * @param error - Optional error object
+     * @param meta - Optional metadata to include
+     */
+    fatal?(message: string, error?: Error, meta?: Record<string, any>): void;
+
+    /**
+     * Create a child logger with additional context
+     * @param context - Context to add to all logs from this child
+     */
+    child?(context: Record<string, any>): Logger;
+
+    /**
+     * Set trace context for distributed tracing
+     * @param traceId - Trace identifier
+     * @param spanId - Span identifier
+     */
+    withTrace?(traceId: string, spanId?: string): Logger;
+
+    /**
+     * Compatibility method for console.log usage
+     * @param message - The message to log
+     * @param args - Additional arguments
+     */
+    log?(message: string, ...args: any[]): void;
+
+    /**
+     * Cleanup resources (close file streams, etc.)
+     * Should be called when the logger is no longer needed
+     */
+    destroy?(): Promise<void>;
+}