@objectstack/spec 0.6.1 → 0.7.2

package/dist/contracts/plugin-validator.js

@@ -0,0 +1,8 @@
+"use strict";
+/**
+ * IPluginValidator - Plugin Validator Interface
+ *
+ * Abstract interface for validating plugins before registration and startup.
+ * Extracted from PluginLoader to follow Single Responsibility Principle.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/contracts/service-registry.d.ts

@@ -0,0 +1,94 @@
+/**
+ * IServiceRegistry - Service Registry Interface
+ *
+ * Abstract interface for managing service registration and lookup.
+ * This provides a single source of truth for all services in the system.
+ *
+ * Following the Dependency Inversion Principle - both kernel implementations
+ * and plugins depend on this interface, not on concrete implementations.
+ */
+export interface IServiceRegistry {
+    /**
+     * Register a service with a unique name
+     * @param name - Unique service identifier
+     * @param service - The service instance to register
+     * @throws Error if service name is already registered
+     */
+    register<T>(name: string, service: T): void;
+    /**
+     * Get a registered service by name (synchronous)
+     * @param name - Service identifier
+     * @returns The registered service
+     * @throws Error if service is not found
+     */
+    get<T>(name: string): T;
+    /**
+     * Get a registered service by name (asynchronous)
+     * Useful for lazy-loaded or async-initialized services
+     * @param name - Service identifier
+     * @param scopeId - Optional scope identifier for scoped services
+     * @returns Promise resolving to the registered service
+     * @throws Error if service is not found
+     */
+    getAsync<T>(name: string, scopeId?: string): Promise<T>;
+    /**
+     * Check if a service is registered
+     * @param name - Service identifier
+     * @returns True if service is registered, false otherwise
+     */
+    has(name: string): boolean;
+    /**
+     * Unregister a service
+     * @param name - Service identifier
+     * @returns True if service was unregistered, false if it wasn't registered
+     */
+    unregister(name: string): boolean;
+    /**
+     * Get all registered service names
+     * @returns Array of service names
+     */
+    getServiceNames?(): string[];
+    /**
+     * Clear all registered services
+     * Useful for cleanup in tests or during shutdown
+     */
+    clear?(): void;
+}
+/**
+ * BasicServiceRegistry - Simple synchronous implementation
+ * Used by ObjectKernel for basic service management
+ */
+export interface IBasicServiceRegistry extends IServiceRegistry {
+}
+/**
+ * AdvancedServiceRegistry - Enhanced implementation with additional features
+ * Used by EnhancedObjectKernel for advanced service management
+ */
+export interface IAdvancedServiceRegistry extends IServiceRegistry {
+    /**
+     * Register a factory function that creates services on-demand
+     * @param name - Service identifier
+     * @param factory - Factory function that creates the service
+     * @param singleton - If true, factory is called once and result is cached
+     */
+    registerFactory?<T>(name: string, factory: () => T | Promise<T>, singleton?: boolean): void;
+    /**
+     * Register a scoped service (per-request, per-session, etc.)
+     * @param name - Service identifier
+     * @param factory - Factory function that creates the service
+     * @param scopeType - Type of scope ('request', 'session', 'transaction', etc.)
+     */
+    registerScoped?<T>(name: string, factory: (scopeId: string) => T | Promise<T>, scopeType: string): void;
+    /**
+     * Create a new scope for scoped services
+     * @param scopeType - Type of scope
+     * @returns Scope identifier
+     */
+    createScope?(scopeType: string): string;
+    /**
+     * Dispose a scope and cleanup scoped services
+     * @param scopeId - Scope identifier
+     */
+    disposeScope?(scopeId: string): Promise<void>;
+}
+//# sourceMappingURL=service-registry.d.ts.map

package/dist/contracts/service-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service-registry.d.ts","sourceRoot":"","sources":["../../src/contracts/service-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,WAAW,gBAAgB;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,GAAG,IAAI,CAAC;IAE5C;;;;;OAKG;IACH,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAAC;IAExB;;;;;;;OAOG;IACH,QAAQ,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAExD;;;;OAIG;IACH,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAE3B;;;;OAIG;IACH,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAElC;;;OAGG;IACH,eAAe,CAAC,IAAI,MAAM,EAAE,CAAC;IAE7B;;;OAGG;IACH,KAAK,CAAC,IAAI,IAAI,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAsB,SAAQ,gBAAgB;CAE9D;AAED;;;GAGG;AACH,MAAM,WAAW,wBAAyB,SAAQ,gBAAgB;IAC9D;;;;;OAKG;IACH,eAAe,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAE5F;;;;;OAKG;IACH,cAAc,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAExG;;;;OAIG;IACH,WAAW,CAAC,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAAC;IAExC;;;OAGG;IACH,YAAY,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACjD"}

package/dist/contracts/service-registry.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * IServiceRegistry - Service Registry Interface
+ *
+ * Abstract interface for managing service registration and lookup.
+ * This provides a single source of truth for all services in the system.
+ *
+ * Following the Dependency Inversion Principle - both kernel implementations
+ * and plugins depend on this interface, not on concrete implementations.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/contracts/startup-orchestrator.d.ts

@@ -0,0 +1,122 @@
+import { Plugin } from './plugin-validator.js';
+/**
+ * IStartupOrchestrator - Startup Orchestrator Interface
+ *
+ * Abstract interface for orchestrating plugin startup with advanced features:
+ * - Timeout handling
+ * - Rollback on failure
+ * - Health checks
+ * - Startup metrics
+ *
+ * Extracted from PluginLoader to follow Single Responsibility Principle.
+ */
+/**
+ * Startup options for orchestration
+ */
+export interface StartupOptions {
+    /**
+     * Maximum time (ms) to wait for each plugin to start
+     * @default 30000 (30 seconds)
+     */
+    timeout?: number;
+    /**
+     * Whether to rollback (destroy) already-started plugins on failure
+     * @default true
+     */
+    rollbackOnFailure?: boolean;
+    /**
+     * Whether to run health checks after startup
+     * @default false
+     */
+    healthCheck?: boolean;
+    /**
+     * Whether to run plugins in parallel (if dependencies allow)
+     * @default false (sequential startup)
+     */
+    parallel?: boolean;
+    /**
+     * Custom context to pass to plugin lifecycle methods
+     */
+    context?: any;
+}
+/**
+ * Plugin startup result
+ */
+export interface PluginStartupResult {
+    /**
+     * Plugin that was started
+     */
+    plugin: Plugin;
+    /**
+     * Whether startup was successful
+     */
+    success: boolean;
+    /**
+     * Time taken to start (milliseconds)
+     */
+    duration: number;
+    /**
+     * Error if startup failed
+     */
+    error?: Error;
+    /**
+     * Health status after startup (if healthCheck enabled)
+     */
+    health?: HealthStatus;
+}
+/**
+ * Health status for a plugin
+ */
+export interface HealthStatus {
+    /**
+     * Whether the plugin is healthy
+     */
+    healthy: boolean;
+    /**
+     * Health check timestamp
+     */
+    timestamp: number;
+    /**
+     * Optional health details
+     */
+    details?: Record<string, any>;
+    /**
+     * Optional error message if unhealthy
+     */
+    message?: string;
+}
+/**
+ * IStartupOrchestrator - Plugin startup orchestration interface
+ */
+export interface IStartupOrchestrator {
+    /**
+     * Orchestrate startup of multiple plugins
+     * Handles timeout, rollback, and health checks
+     * @param plugins - Array of plugins to start (in dependency order)
+     * @param options - Startup options
+     * @returns Promise resolving to startup results for each plugin
+     */
+    orchestrateStartup(plugins: Plugin[], options: StartupOptions): Promise<PluginStartupResult[]>;
+    /**
+     * Rollback (destroy) a set of plugins
+     * Used when startup fails and rollback is enabled
+     * @param startedPlugins - Plugins that were successfully started
+     * @returns Promise that resolves when rollback is complete
+     */
+    rollback(startedPlugins: Plugin[]): Promise<void>;
+    /**
+     * Check health of a single plugin
+     * @param plugin - Plugin to check
+     * @returns Promise resolving to health status
+     */
+    checkHealth(plugin: Plugin): Promise<HealthStatus>;
+    /**
+     * Wait for a plugin to start with timeout
+     * @param plugin - Plugin to start
+     * @param context - Plugin context
+     * @param timeoutMs - Maximum time to wait (milliseconds)
+     * @returns Promise resolving when plugin starts or rejecting on timeout
+     */
+    startWithTimeout?(plugin: Plugin, context: any, timeoutMs: number): Promise<void>;
+}
+//# sourceMappingURL=startup-orchestrator.d.ts.map

package/dist/contracts/startup-orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"startup-orchestrator.d.ts","sourceRoot":"","sources":["../../src/contracts/startup-orchestrator.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAE/C;;;;;;;;;;GAUG;AAEH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC3B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAE5B;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;OAEG;IACH,OAAO,CAAC,EAAE,GAAG,CAAC;CACjB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAChC;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;OAEG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;OAEG;IACH,KAAK,CAAC,EAAE,KAAK,CAAC;IAEd;;OAEG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IACzB;;OAEG;IACH,OAAO,EAAE,OAAO,CAAC;IAEjB;;OAEG;IACH,SAAS,EAAE,MAAM,CAAC;IAElB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAE9B;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACjC;;;;;;OAMG;IACH,kBAAkB,CACd,OAAO,EAAE,MAAM,EAAE,EACjB,OAAO,EAAE,cAAc,GACxB,OAAO,CAAC,mBAAmB,EAAE,CAAC,CAAC;IAElC;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAElD;;;;OAIG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAEnD;;;;;;OAMG;IACH,gBAAgB,CAAC,CACb,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,GAAG,EACZ,SAAS,EAAE,MAAM,GAClB,OAAO,CAAC,IAAI,CAAC,CAAC;CACpB"}

package/dist/contracts/startup-orchestrator.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });