@objectstack/core 0.9.1 → 1.0.0

package/dist/kernel.test.js

@@ -1,161 +1,414 @@
 import { describe, it, expect, beforeEach } from 'vitest';
 import { ObjectKernel } from './kernel';
-describe('ObjectKernel with Configurable Logger', () => {
+import { ServiceLifecycle } from './plugin-loader';
+describe('ObjectKernel', () => {
     let kernel;
     beforeEach(() => {
-        kernel = new ObjectKernel();
-    });
-    describe('Logger Configuration', () => {
-        it('should create kernel with default logger', () => {
-            expect(kernel).toBeDefined();
-        });
-        it('should create kernel with custom logger config', async () => {
-            const customKernel = new ObjectKernel({
-                logger: {
-                    level: 'debug',
-                    format: 'pretty',
-                    sourceLocation: true
-                }
-            });
-            expect(customKernel).toBeDefined();
-            // Cleanup
-            await customKernel.bootstrap();
-            await customKernel.shutdown();
-        });
-        it('should create kernel with file logging config', async () => {
-            const fileKernel = new ObjectKernel({
-                logger: {
-                    level: 'info',
-                    format: 'json',
-                    file: '/tmp/test-kernel.log'
-                }
-            });
-            expect(fileKernel).toBeDefined();
-            // Cleanup
-            await fileKernel.bootstrap();
-            await fileKernel.shutdown();
+        kernel = new ObjectKernel({
+            logger: { level: 'error' }, // Suppress logs in tests
+            gracefulShutdown: false, // Disable for tests
+            skipSystemValidation: true,
         });
     });
-    describe('Plugin Context Logger', () => {
-        it('should provide logger to plugins', async () => {
-            let loggerReceived = false;
-            const testPlugin = {
-                name: 'test-plugin',
-                init: async (ctx) => {
-                    if (ctx.logger) {
-                        loggerReceived = true;
-                        ctx.logger.info('Plugin initialized', { plugin: 'test-plugin' });
-                    }
-                }
+    describe('Plugin Registration and Loading', () => {
+        it('should register a plugin with version', async () => {
+            const plugin = {
+                name: 'versioned-plugin',
+                version: '1.2.3',
+                init: async () => { },
             };
-            kernel.use(testPlugin);
+            await kernel.use(plugin);
             await kernel.bootstrap();
-            expect(loggerReceived).toBe(true);
+            expect(kernel.isRunning()).toBe(true);
             await kernel.shutdown();
         });
-        it('should allow plugins to use all log levels', async () => {
-            const logCalls = [];
-            const loggingPlugin = {
-                name: 'logging-plugin',
-                init: async (ctx) => {
-                    ctx.logger.debug('Debug message');
-                    logCalls.push('debug');
-                    ctx.logger.info('Info message');
-                    logCalls.push('info');
-                    ctx.logger.warn('Warning message');
-                    logCalls.push('warn');
-                    ctx.logger.error('Error message');
-                    logCalls.push('error');
-                }
-            };
-            kernel.use(loggingPlugin);
-            await kernel.bootstrap();
-            expect(logCalls).toContain('debug');
-            expect(logCalls).toContain('info');
-            expect(logCalls).toContain('warn');
-            expect(logCalls).toContain('error');
-            await kernel.shutdown();
-        });
-        it('should support metadata in logs', async () => {
-            const metadataPlugin = {
-                name: 'metadata-plugin',
-                init: async (ctx) => {
-                    ctx.logger.info('User action', {
-                        userId: '123',
-                        action: 'create',
-                        resource: 'document'
-                    });
-                }
+        it('should validate plugin during registration', async () => {
+            const invalidPlugin = {
+                name: '',
+                init: async () => { },
             };
-            kernel.use(metadataPlugin);
+            await expect(async () => {
+                await kernel.use(invalidPlugin);
+            }).rejects.toThrow();
+        });
+        it('should reject plugin registration after bootstrap', async () => {
             await kernel.bootstrap();
+            const plugin = {
+                name: 'late-plugin',
+                init: async () => { },
+            };
+            await expect(async () => {
+                await kernel.use(plugin);
+            }).rejects.toThrow('Cannot register plugins after bootstrap');
             await kernel.shutdown();
         });
     });
-    describe('Kernel Lifecycle Logging', () => {
-        it('should log bootstrap process', async () => {
+    describe('Service Factory Registration', () => {
+        it('should register singleton service factory', async () => {
+            let callCount = 0;
+            kernel.registerServiceFactory('counter', () => {
+                callCount++;
+                return { count: callCount };
+            }, ServiceLifecycle.SINGLETON);
+            await kernel.bootstrap();
+            const service1 = await kernel.getServiceAsync('counter');
+            const service2 = await kernel.getServiceAsync('counter');
+            expect(callCount).toBe(1);
+            expect(service1).toBe(service2);
+            await kernel.shutdown();
+        });
+        it('should register transient service factory', async () => {
+            let callCount = 0;
+            kernel.registerServiceFactory('transient', () => {
+                callCount++;
+                return { count: callCount };
+            }, ServiceLifecycle.TRANSIENT);
+            await kernel.bootstrap();
+            const service1 = await kernel.getServiceAsync('transient');
+            const service2 = await kernel.getServiceAsync('transient');
+            expect(callCount).toBe(2);
+            expect(service1).not.toBe(service2);
+            await kernel.shutdown();
+        });
+        it('should register scoped service factory', async () => {
+            let callCount = 0;
+            kernel.registerServiceFactory('scoped', () => {
+                callCount++;
+                return { count: callCount };
+            }, ServiceLifecycle.SCOPED);
+            await kernel.bootstrap();
+            const service1 = await kernel.getServiceAsync('scoped', 'request-1');
+            const service2 = await kernel.getServiceAsync('scoped', 'request-1');
+            const service3 = await kernel.getServiceAsync('scoped', 'request-2');
+            expect(callCount).toBe(2); // Once per scope
+            expect(service1).toBe(service2); // Same within scope
+            expect(service1).not.toBe(service3); // Different across scopes
+            await kernel.shutdown();
+        });
+    });
+    describe('Plugin Lifecycle with Timeout', () => {
+        it('should timeout plugin init if it takes too long', async () => {
             const plugin = {
-                name: 'lifecycle-test',
+                name: 'slow-init',
+                version: '1.0.0',
                 init: async () => {
-                    // Init logic
+                    await new Promise(resolve => setTimeout(resolve, 5000)); // 5 seconds
+                },
+                startupTimeout: 100, // 100ms timeout
+            };
+            await kernel.use(plugin);
+            await expect(async () => {
+                await kernel.bootstrap();
+            }).rejects.toThrow('timeout');
+        }, 1000); // Test should complete in 1 second
+        it('should timeout plugin start if it takes too long', async () => {
+            const plugin = {
+                name: 'slow-start',
+                version: '1.0.0',
+                init: async () => { },
+                start: async () => {
+                    await new Promise(resolve => setTimeout(resolve, 5000)); // 5 seconds
+                },
+                startupTimeout: 100, // 100ms timeout
+            };
+            await kernel.use(plugin);
+            await expect(async () => {
+                await kernel.bootstrap();
+            }).rejects.toThrow();
+        }, 1000); // Test should complete in 1 second
+        it('should complete plugin startup within timeout', async () => {
+            const plugin = {
+                name: 'fast-plugin',
+                version: '1.0.0',
+                init: async () => {
+                    await new Promise(resolve => setTimeout(resolve, 10));
                 },
                 start: async () => {
-                    // Start logic
-                }
+                    await new Promise(resolve => setTimeout(resolve, 10));
+                },
+                startupTimeout: 1000,
             };
-            kernel.use(plugin);
+            await kernel.use(plugin);
             await kernel.bootstrap();
             expect(kernel.isRunning()).toBe(true);
             await kernel.shutdown();
         });
-        it('should log shutdown process', async () => {
+    });
+    describe('Startup Failure Rollback', () => {
+        it('should rollback started plugins on failure', async () => {
+            let plugin1Destroyed = false;
+            const plugin1 = {
+                name: 'plugin-1',
+                version: '1.0.0',
+                init: async () => { },
+                start: async () => { },
+                destroy: async () => {
+                    plugin1Destroyed = true;
+                },
+            };
+            const plugin2 = {
+                name: 'plugin-2',
+                version: '1.0.0',
+                init: async () => { },
+                start: async () => {
+                    throw new Error('Startup failed');
+                },
+            };
+            await kernel.use(plugin1);
+            await kernel.use(plugin2);
+            await expect(async () => {
+                await kernel.bootstrap();
+            }).rejects.toThrow('failed to start');
+            // Plugin 1 should be rolled back
+            expect(plugin1Destroyed).toBe(true);
+        });
+        it('should not rollback if disabled', async () => {
+            const noRollbackKernel = new ObjectKernel({
+                logger: { level: 'error' },
+                rollbackOnFailure: false,
+                gracefulShutdown: false,
+                skipSystemValidation: true,
+            });
+            let plugin1Destroyed = false;
+            const plugin1 = {
+                name: 'plugin-1',
+                version: '1.0.0',
+                init: async () => { },
+                start: async () => { },
+                destroy: async () => {
+                    plugin1Destroyed = true;
+                },
+            };
+            const plugin2 = {
+                name: 'plugin-2',
+                version: '1.0.0',
+                init: async () => { },
+                start: async () => {
+                    throw new Error('Startup failed');
+                },
+            };
+            await noRollbackKernel.use(plugin1);
+            await noRollbackKernel.use(plugin2);
+            // Should not throw since rollback is disabled
+            await noRollbackKernel.bootstrap();
+            // Plugin 1 should NOT be destroyed
+            expect(plugin1Destroyed).toBe(false);
+        });
+    });
+    describe('Plugin Health Checks', () => {
+        it('should check individual plugin health', async () => {
             const plugin = {
-                name: 'shutdown-test',
+                name: 'healthy-plugin',
+                version: '1.0.0',
+                init: async () => { },
+            };
+            await kernel.use(plugin);
+            await kernel.bootstrap();
+            const health = await kernel.checkPluginHealth('healthy-plugin');
+            expect(health.healthy).toBe(true);
+            expect(health.lastCheck).toBeInstanceOf(Date);
+            await kernel.shutdown();
+        });
+        it('should check all plugins health', async () => {
+            const plugin1 = {
+                name: 'plugin-1',
+                version: '1.0.0',
+                init: async () => { },
+            };
+            const plugin2 = {
+                name: 'plugin-2',
+                version: '1.0.0',
+                init: async () => { },
+            };
+            await kernel.use(plugin1);
+            await kernel.use(plugin2);
+            await kernel.bootstrap();
+            const allHealth = await kernel.checkAllPluginsHealth();
+            expect(allHealth.size).toBe(2);
+            expect(allHealth.get('plugin-1').healthy).toBe(true);
+            expect(allHealth.get('plugin-2').healthy).toBe(true);
+            await kernel.shutdown();
+        });
+    });
+    describe('Plugin Metrics', () => {
+        it('should track plugin startup times', async () => {
+            const plugin1 = {
+                name: 'plugin-1',
+                version: '1.0.0',
+                init: async () => { },
+                start: async () => {
+                    await new Promise(resolve => setTimeout(resolve, 50));
+                },
+            };
+            const plugin2 = {
+                name: 'plugin-2',
+                version: '1.0.0',
+                init: async () => { },
+                start: async () => {
+                    await new Promise(resolve => setTimeout(resolve, 30));
+                },
+            };
+            await kernel.use(plugin1);
+            await kernel.use(plugin2);
+            await kernel.bootstrap();
+            const metrics = kernel.getPluginMetrics();
+            expect(metrics.size).toBe(2);
+            expect(metrics.get('plugin-1')).toBeGreaterThan(0);
+            expect(metrics.get('plugin-2')).toBeGreaterThan(0);
+            await kernel.shutdown();
+        });
+        it('should not track metrics for plugins without start', async () => {
+            const plugin = {
+                name: 'no-start',
+                version: '1.0.0',
+                init: async () => { },
+            };
+            await kernel.use(plugin);
+            await kernel.bootstrap();
+            const metrics = kernel.getPluginMetrics();
+            expect(metrics.has('no-start')).toBe(false);
+            await kernel.shutdown();
+        });
+    });
+    describe('Graceful Shutdown', () => {
+        it('should call destroy on all plugins', async () => {
+            let plugin1Destroyed = false;
+            let plugin2Destroyed = false;
+            const plugin1 = {
+                name: 'plugin-1',
+                version: '1.0.0',
                 init: async () => { },
                 destroy: async () => {
-                    // Cleanup
-                }
+                    plugin1Destroyed = true;
+                },
             };
-            kernel.use(plugin);
+            const plugin2 = {
+                name: 'plugin-2',
+                version: '1.0.0',
+                init: async () => { },
+                destroy: async () => {
+                    plugin2Destroyed = true;
+                },
+            };
+            await kernel.use(plugin1);
+            await kernel.use(plugin2);
             await kernel.bootstrap();
             await kernel.shutdown();
+            expect(plugin1Destroyed).toBe(true);
+            expect(plugin2Destroyed).toBe(true);
+        });
+        it('should handle plugin destroy errors gracefully', async () => {
+            const plugin1 = {
+                name: 'error-destroy',
+                version: '1.0.0',
+                init: async () => { },
+                destroy: async () => {
+                    throw new Error('Destroy failed');
+                },
+            };
+            const plugin2 = {
+                name: 'normal-plugin',
+                version: '1.0.0',
+                init: async () => { },
+            };
+            await kernel.use(plugin1);
+            await kernel.use(plugin2);
+            await kernel.bootstrap();
+            // Should not throw even if one plugin fails to destroy
+            await kernel.shutdown();
             expect(kernel.getState()).toBe('stopped');
         });
-    });
-    describe('Environment Compatibility', () => {
-        it('should work in Node.js environment', async () => {
-            const nodeKernel = new ObjectKernel({
-                logger: {
-                    level: 'info',
-                    format: 'json'
-                }
-            });
+        it('should trigger shutdown hook', async () => {
+            let hookCalled = false;
             const plugin = {
-                name: 'node-test',
+                name: 'hook-plugin',
+                version: '1.0.0',
                 init: async (ctx) => {
-                    ctx.logger.info('Running in Node.js');
-                }
-            };
-            nodeKernel.use(plugin);
-            await nodeKernel.bootstrap();
-            await nodeKernel.shutdown();
-        });
-        it('should support browser-friendly logging', async () => {
-            const browserKernel = new ObjectKernel({
-                logger: {
-                    level: 'info',
-                    format: 'pretty'
-                }
+                    ctx.hook('kernel:shutdown', async () => {
+                        hookCalled = true;
+                    });
+                },
+            };
+            await kernel.use(plugin);
+            await kernel.bootstrap();
+            await kernel.shutdown();
+            expect(hookCalled).toBe(true);
+        });
+        it('should execute custom shutdown handlers', async () => {
+            let handlerCalled = false;
+            kernel.onShutdown(async () => {
+                handlerCalled = true;
             });
-            const plugin = {
-                name: 'browser-test',
-                init: async (ctx) => {
-                    ctx.logger.info('Browser-friendly format');
-                }
+            await kernel.bootstrap();
+            await kernel.shutdown();
+            expect(handlerCalled).toBe(true);
+        });
+    });
+    describe('Dependency Resolution', () => {
+        it('should resolve plugin dependencies in correct order', async () => {
+            const initOrder = [];
+            const pluginA = {
+                name: 'plugin-a',
+                version: '1.0.0',
+                dependencies: ['plugin-b'],
+                init: async () => {
+                    initOrder.push('plugin-a');
+                },
+            };
+            const pluginB = {
+                name: 'plugin-b',
+                version: '1.0.0',
+                init: async () => {
+                    initOrder.push('plugin-b');
+                },
             };
-            browserKernel.use(plugin);
-            await browserKernel.bootstrap();
-            await browserKernel.shutdown();
+            await kernel.use(pluginA);
+            await kernel.use(pluginB);
+            await kernel.bootstrap();
+            expect(initOrder).toEqual(['plugin-b', 'plugin-a']);
+            await kernel.shutdown();
+        });
+        it('should detect circular plugin dependencies', async () => {
+            const pluginA = {
+                name: 'plugin-a',
+                version: '1.0.0',
+                dependencies: ['plugin-b'],
+                init: async () => { },
+            };
+            const pluginB = {
+                name: 'plugin-b',
+                version: '1.0.0',
+                dependencies: ['plugin-a'],
+                init: async () => { },
+            };
+            await kernel.use(pluginA);
+            await kernel.use(pluginB);
+            await expect(async () => {
+                await kernel.bootstrap();
+            }).rejects.toThrow('Circular dependency');
+        });
+    });
+    describe('State Management', () => {
+        it('should track kernel state correctly', async () => {
+            expect(kernel.getState()).toBe('idle');
+            await kernel.bootstrap();
+            expect(kernel.getState()).toBe('running');
+            expect(kernel.isRunning()).toBe(true);
+            await kernel.shutdown();
+            expect(kernel.getState()).toBe('stopped');
+            expect(kernel.isRunning()).toBe(false);
+        });
+        it('should not allow double bootstrap', async () => {
+            await kernel.bootstrap();
+            await expect(async () => {
+                await kernel.bootstrap();
+            }).rejects.toThrow('already bootstrapped');
+            await kernel.shutdown();
+        });
+        it('should not allow shutdown before bootstrap', async () => {
+            await expect(async () => {
+                await kernel.shutdown();
+            }).rejects.toThrow('not running');
         });
     });
 });

package/dist/lite-kernel.d.ts

@@ -0,0 +1,55 @@
+import { Plugin } from './types.js';
+import type { LoggerConfig } from '@objectstack/spec/system';
+import { ObjectKernelBase } from './kernel-base.js';
+/**
+ * ObjectKernel - MiniKernel Architecture
+ *
+ * A highly modular, plugin-based microkernel that:
+ * - Manages plugin lifecycle (init, start, destroy)
+ * - Provides dependency injection via service registry
+ * - Implements event/hook system for inter-plugin communication
+ * - Handles dependency resolution (topological sort)
+ * - Provides configurable logging for server and browser
+ *
+ * Core philosophy:
+ * - Business logic is completely separated into plugins
+ * - Kernel only manages lifecycle, DI, and hooks
+ * - Plugins are loaded as equal building blocks
+ */
+export declare class LiteKernel extends ObjectKernelBase {
+    constructor(config?: {
+        logger?: Partial<LoggerConfig>;
+    });
+    /**
+     * Register a plugin
+     * @param plugin - Plugin instance
+     */
+    use(plugin: Plugin): this;
+    /**
+     * Bootstrap the kernel
+     * 1. Resolve dependencies (topological sort)
+     * 2. Init phase - plugins register services
+     * 3. Start phase - plugins execute business logic
+     * 4. Trigger 'kernel:ready' hook
+     */
+    bootstrap(): Promise<void>;
+    /**
+     * Shutdown the kernel
+     * Calls destroy on all plugins in reverse order
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Graceful shutdown - destroy all plugins in reverse order
+     */
+    destroy(): Promise<void>;
+    /**
+     * Get a service from the registry
+     * Convenience method for external access
+     */
+    getService<T>(name: string): T;
+    /**
+     * Check if kernel is running
+     */
+    isRunning(): boolean;
+}
+//# sourceMappingURL=lite-kernel.d.ts.map

package/dist/lite-kernel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lite-kernel.d.ts","sourceRoot":"","sources":["../src/lite-kernel.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAEpC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEpD;;;;;;;;;;;;;;GAcG;AACH,qBAAa,UAAW,SAAQ,gBAAgB;gBAChC,MAAM,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,OAAO,CAAC,YAAY,CAAC,CAAA;KAAE;IAQvD;;;OAGG;IACH,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAYzB;;;;;;OAMG;IACG,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IA8BhC;;;OAGG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;IAI/B;;OAEG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IA2B9B;;;OAGG;IACH,UAAU,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC;IAI9B;;OAEG;IACH,SAAS,IAAI,OAAO;CAGvB"}