@objectstack/core 0.6.1 → 0.7.1

package/dist/enhanced-kernel.test.js

@@ -0,0 +1,412 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { EnhancedObjectKernel } from './enhanced-kernel';
+import { ServiceLifecycle } from './plugin-loader';
+describe('EnhancedObjectKernel', () => {
+    let kernel;
+    beforeEach(() => {
+        kernel = new EnhancedObjectKernel({
+            logger: { level: 'error' }, // Suppress logs in tests
+            gracefulShutdown: false, // Disable for tests
+        });
+    });
+    describe('Plugin Registration and Loading', () => {
+        it('should register a plugin with version', async () => {
+            const plugin = {
+                name: 'versioned-plugin',
+                version: '1.2.3',
+                init: async () => { },
+            };
+            await kernel.use(plugin);
+            await kernel.bootstrap();
+            expect(kernel.isRunning()).toBe(true);
+            await kernel.shutdown();
+        });
+        it('should validate plugin during registration', async () => {
+            const invalidPlugin = {
+                name: '',
+                init: async () => { },
+            };
+            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('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: 'slow-init',
+                version: '1.0.0',
+                init: 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('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 () => {
+                    await new Promise(resolve => setTimeout(resolve, 10));
+                },
+                startupTimeout: 1000,
+            };
+            await kernel.use(plugin);
+            await kernel.bootstrap();
+            expect(kernel.isRunning()).toBe(true);
+            await kernel.shutdown();
+        });
+    });
+    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 EnhancedObjectKernel({
+                logger: { level: 'error' },
+                rollbackOnFailure: false,
+                gracefulShutdown: false,
+            });
+            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: '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 () => {
+                    plugin1Destroyed = true;
+                },
+            };
+            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');
+        });
+        it('should trigger shutdown hook', async () => {
+            let hookCalled = false;
+            const plugin = {
+                name: 'hook-plugin',
+                version: '1.0.0',
+                init: async (ctx) => {
+                    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;
+            });
+            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');
+                },
+            };
+            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/index.d.ts

@@ -1,5 +1,14 @@
+/**
+ * @objectstack/core
+ *
+ * Core runtime for ObjectStack microkernel architecture.
+ * Provides plugin system, dependency injection, and lifecycle management.
+ */
+export * from './kernel-base.js';
 export * from './kernel.js';
 export * from './types.js';
-export * from './contracts/http-server.js';
-export * from './contracts/data-engine.js';
+export * from './logger.js';
+export * from './plugin-loader.js';
+export * from './enhanced-kernel.js';
+export type { Logger, IHttpServer, IHttpRequest, IHttpResponse, RouteHandler, Middleware, IDataEngine, DriverInterface } from '@objectstack/spec/contracts';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,4BAA4B,CAAC;AAC3C,cAAc,4BAA4B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,kBAAkB,CAAC;AACjC,cAAc,aAAa,CAAC;AAC5B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,sBAAsB,CAAC;AAGrC,YAAY,EACR,MAAM,EACN,WAAW,EACX,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,UAAU,EACV,WAAW,EACX,eAAe,EAClB,MAAM,6BAA6B,CAAC"}

package/dist/index.js

@@ -1,4 +1,12 @@
+/**
+ * @objectstack/core
+ *
+ * Core runtime for ObjectStack microkernel architecture.
+ * Provides plugin system, dependency injection, and lifecycle management.
+ */
+export * from './kernel-base.js';
 export * from './kernel.js';
 export * from './types.js';
-export * from './contracts/http-server.js';
-export * from './contracts/data-engine.js';
+export * from './logger.js';
+export * from './plugin-loader.js';
+export * from './enhanced-kernel.js';

package/dist/kernel-base.d.ts

@@ -0,0 +1,84 @@
+import type { Plugin, PluginContext } from './types.js';
+import type { Logger } from '@objectstack/spec/contracts';
+import type { IServiceRegistry } from '@objectstack/spec/contracts';
+/**
+ * Kernel state machine
+ */
+export type KernelState = 'idle' | 'initializing' | 'running' | 'stopping' | 'stopped';
+/**
+ * ObjectKernelBase - Abstract Base Class for Microkernel
+ *
+ * Provides common functionality for both ObjectKernel and EnhancedObjectKernel:
+ * - Plugin management (Map storage)
+ * - Dependency resolution (topological sort)
+ * - Hook/Event system
+ * - Context creation
+ * - State validation
+ *
+ * This eliminates ~120 lines of duplicate code between the two implementations.
+ */
+export declare abstract class ObjectKernelBase {
+    protected plugins: Map<string, Plugin>;
+    protected services: IServiceRegistry | Map<string, any>;
+    protected hooks: Map<string, Array<(...args: any[]) => void | Promise<void>>>;
+    protected state: KernelState;
+    protected logger: Logger;
+    protected context: PluginContext;
+    constructor(logger: Logger);
+    /**
+     * Validate kernel state
+     * @param requiredState - Required state for the operation
+     * @throws Error if current state doesn't match
+     */
+    protected validateState(requiredState: KernelState): void;
+    /**
+     * Validate kernel is in idle state (for plugin registration)
+     */
+    protected validateIdle(): void;
+    /**
+     * Create the plugin context
+     * Subclasses can override to customize context creation
+     */
+    protected createContext(): PluginContext;
+    /**
+     * Resolve plugin dependencies using topological sort
+     * @returns Ordered list of plugins (dependencies first)
+     */
+    protected resolveDependencies(): Plugin[];
+    /**
+     * Run plugin init phase
+     * @param plugin - Plugin to initialize
+     */
+    protected runPluginInit(plugin: Plugin): Promise<void>;
+    /**
+     * Run plugin start phase
+     * @param plugin - Plugin to start
+     */
+    protected runPluginStart(plugin: Plugin): Promise<void>;
+    /**
+     * Run plugin destroy phase
+     * @param plugin - Plugin to destroy
+     */
+    protected runPluginDestroy(plugin: Plugin): Promise<void>;
+    /**
+     * Trigger a hook with all registered handlers
+     * @param name - Hook name
+     * @param args - Arguments to pass to handlers
+     */
+    protected triggerHook(name: string, ...args: any[]): Promise<void>;
+    /**
+     * Get current kernel state
+     */
+    getState(): KernelState;
+    /**
+     * Get all registered plugins
+     */
+    getPlugins(): Map<string, Plugin>;
+    /**
+     * Abstract methods to be implemented by subclasses
+     */
+    abstract use(plugin: Plugin): this | Promise<this>;
+    abstract bootstrap(): Promise<void>;
+    abstract destroy(): Promise<void>;
+}
+//# sourceMappingURL=kernel-base.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"kernel-base.d.ts","sourceRoot":"","sources":["../src/kernel-base.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,6BAA6B,CAAC;AAC1D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAEpE;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,cAAc,GAAG,SAAS,GAAG,UAAU,GAAG,SAAS,CAAC;AAEvF;;;;;;;;;;;GAWG;AACH,8BAAsB,gBAAgB;IAClC,SAAS,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAa;IACnD,SAAS,CAAC,QAAQ,EAAE,gBAAgB,GAAG,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,CAAa;IACpE,SAAS,CAAC,KAAK,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAa;IAC1F,SAAS,CAAC,KAAK,EAAE,WAAW,CAAU;IACtC,SAAS,CAAC,MAAM,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,OAAO,EAAG,aAAa,CAAC;gBAEtB,MAAM,EAAE,MAAM;IAI1B;;;;OAIG;IACH,SAAS,CAAC,aAAa,CAAC,aAAa,EAAE,WAAW,GAAG,IAAI;IAQzD;;OAEG;IACH,SAAS,CAAC,YAAY,IAAI,IAAI;IAM9B;;;OAGG;IACH,SAAS,CAAC,aAAa,IAAI,aAAa;IAoDxC;;;OAGG;IACH,SAAS,CAAC,mBAAmB,IAAI,MAAM,EAAE;IA2CzC;;;OAGG;cACa,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAa5D;;;OAGG;cACa,cAAc,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAe7D;;;OAGG;cACa,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAe/D;;;;OAIG;cACa,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;IAiBxE;;OAEG;IACH,QAAQ,IAAI,WAAW;IAIvB;;OAEG;IACH,UAAU,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC;IAIjC;;OAEG;IACH,QAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAClD,QAAQ,CAAC,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IACnC,QAAQ,CAAC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;CACpC"}