@objectstack/core 4.0.4 → 4.1.0

package/src/fallbacks/memory-cache.ts

@@ -1,34 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-/**
- * In-memory Map-backed cache fallback.
- *
- * Implements the ICacheService contract with basic get/set/delete/has/clear
- * and TTL expiry.  Used by ObjectKernel as an automatic fallback when no
- * real cache plugin (e.g. Redis) is registered.
- */
-export function createMemoryCache() {
-  const store = new Map<string, { value: unknown; expires?: number }>();
-  let hits = 0;
-  let misses = 0;
-  return {
-    _fallback: true, _serviceName: 'cache',
-    async get<T = unknown>(key: string): Promise<T | undefined> {
-      const entry = store.get(key);
-      if (!entry || (entry.expires && Date.now() > entry.expires)) {
-        store.delete(key);
-        misses++;
-        return undefined;
-      }
-      hits++;
-      return entry.value as T;
-    },
-    async set<T = unknown>(key: string, value: T, ttl?: number): Promise<void> {
-      store.set(key, { value, expires: ttl ? Date.now() + ttl * 1000 : undefined });
-    },
-    async delete(key: string): Promise<boolean> { return store.delete(key); },
-    async has(key: string): Promise<boolean> { return store.has(key); },
-    async clear(): Promise<void> { store.clear(); },
-    async stats() { return { hits, misses, keyCount: store.size }; },
-  };
-}

package/src/fallbacks/memory-i18n.ts

@@ -1,112 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-/**
- * Resolve a locale code against available locales with fallback.
- *
- * Fallback chain:
- *   1. Exact match (e.g. `zh-CN` → `zh-CN`)
- *   2. Case-insensitive match (e.g. `zh-cn` → `zh-CN`)
- *   3. Base language match (e.g. `zh-CN` → `zh`)
- *   4. Variant expansion (e.g. `zh` → `zh-CN`)
- *
- * Returns the matched locale code, or `undefined` when no match is found.
- */
-export function resolveLocale(requestedLocale: string, availableLocales: string[]): string | undefined {
-  if (availableLocales.length === 0) return undefined;
-
-  // 1. Exact match
-  if (availableLocales.includes(requestedLocale)) return requestedLocale;
-
-  // 2. Case-insensitive match
-  const lower = requestedLocale.toLowerCase();
-  const caseMatch = availableLocales.find(l => l.toLowerCase() === lower);
-  if (caseMatch) return caseMatch;
-
-  // 3. Base language match (zh-CN → zh)
-  const baseLang = requestedLocale.split('-')[0].toLowerCase();
-  const baseMatch = availableLocales.find(l => l.toLowerCase() === baseLang);
-  if (baseMatch) return baseMatch;
-
-  // 4. Variant expansion (zh → zh-CN, zh-TW, etc. — first match wins)
-  const variantMatch = availableLocales.find(l => l.split('-')[0].toLowerCase() === baseLang);
-  if (variantMatch) return variantMatch;
-
-  return undefined;
-}
-
-/**
- * In-memory i18n service fallback.
- *
- * Implements the II18nService contract with basic translate/load/getLocales
- * operations.  Used by ObjectKernel as an automatic fallback when no real
- * i18n plugin (e.g. I18nServicePlugin) is registered.
- *
- * Supports runtime translation loading, locale management, and
- * locale code fallback (e.g. `zh` → `zh-CN`).
- * Does not load files from disk — operates purely in-memory.
- */
-export function createMemoryI18n() {
-  const translations = new Map<string, Record<string, unknown>>();
-  let defaultLocale = 'en';
-
-  /**
-   * Resolve a dot-notation key from a nested object.
-   */
-  function resolveKey(data: Record<string, unknown>, key: string): string | undefined {
-    const parts = key.split('.');
-    let current: unknown = data;
-    for (const part of parts) {
-      if (current == null || typeof current !== 'object') return undefined;
-      current = (current as Record<string, unknown>)[part];
-    }
-    return typeof current === 'string' ? current : undefined;
-  }
-
-  /**
-   * Find translation data for a locale, with fallback resolution.
-   */
-  function resolveTranslations(locale: string): Record<string, unknown> | undefined {
-    // Exact match
-    if (translations.has(locale)) return translations.get(locale);
-
-    // Locale fallback (zh → zh-CN, en-us → en-US, etc.)
-    const resolved = resolveLocale(locale, [...translations.keys()]);
-    if (resolved) return translations.get(resolved);
-
-    return undefined;
-  }
-
-  return {
-    _fallback: true, _serviceName: 'i18n',
-
-    t(key: string, locale: string, params?: Record<string, unknown>): string {
-      const data = resolveTranslations(locale) ?? translations.get(defaultLocale);
-      const value = data ? resolveKey(data, key) : undefined;
-      if (value == null) return key;
-      if (!params) return value;
-      // Interpolation format: {{paramName}} — matches FileI18nAdapter convention
-      return value.replace(/\{\{(\w+)\}\}/g, (_, name) => String(params[name] ?? `{{${name}}}`));
-    },
-
-    getTranslations(locale: string): Record<string, unknown> {
-      return resolveTranslations(locale) ?? {};
-    },
-
-    loadTranslations(locale: string, data: Record<string, unknown>): void {
-      const existing = translations.get(locale) ?? {};
-      translations.set(locale, { ...existing, ...data });
-    },
-
-    getLocales(): string[] {
-      return [...translations.keys()];
-    },
-
-    getDefaultLocale(): string {
-      return defaultLocale;
-    },
-
-    setDefaultLocale(locale: string): void {
-      defaultLocale = locale;
-    },
-  };
-}

package/src/fallbacks/memory-job.ts

@@ -1,23 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-/**
- * In-memory job scheduler fallback.
- *
- * Implements the IJobService contract with basic schedule/cancel/trigger
- * operations.  Used by ObjectKernel as an automatic fallback when no real
- * job plugin (e.g. Agenda / BullMQ) is registered.
- */
-export function createMemoryJob() {
-  const jobs = new Map<string, any>();
-  return {
-    _fallback: true, _serviceName: 'job',
-    async schedule(name: string, schedule: any, handler: any): Promise<void> { jobs.set(name, { schedule, handler }); },
-    async cancel(name: string): Promise<void> { jobs.delete(name); },
-    async trigger(name: string, data?: unknown): Promise<void> {
-      const job = jobs.get(name);
-      if (job?.handler) await job.handler({ jobId: name, data });
-    },
-    async getExecutions(): Promise<any[]> { return []; },
-    async listJobs(): Promise<string[]> { return [...jobs.keys()]; },
-  };
-}

package/src/fallbacks/memory-metadata.ts

@@ -1,50 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-/**
- * In-memory metadata service fallback.
- *
- * Implements the IMetadataService contract with a simple Map-of-Maps store.
- * Used by ObjectKernel as an automatic fallback when no real metadata plugin
- * (e.g. MetadataPlugin with file-system persistence) is registered.
- */
-export function createMemoryMetadata() {
-  // type -> name -> data
-  const store = new Map<string, Map<string, any>>();
-
-  function getTypeMap(type: string): Map<string, any> {
-    let map = store.get(type);
-    if (!map) {
-      map = new Map();
-      store.set(type, map);
-    }
-    return map;
-  }
-
-  return {
-    _fallback: true, _serviceName: 'metadata',
-    async register(type: string, name: string, data: any): Promise<void> {
-      getTypeMap(type).set(name, data);
-    },
-    async get(type: string, name: string): Promise<any> {
-      return getTypeMap(type).get(name);
-    },
-    async list(type: string): Promise<any[]> {
-      return Array.from(getTypeMap(type).values());
-    },
-    async unregister(type: string, name: string): Promise<void> {
-      getTypeMap(type).delete(name);
-    },
-    async exists(type: string, name: string): Promise<boolean> {
-      return getTypeMap(type).has(name);
-    },
-    async listNames(type: string): Promise<string[]> {
-      return Array.from(getTypeMap(type).keys());
-    },
-    async getObject(name: string): Promise<any> {
-      return getTypeMap('object').get(name);
-    },
-    async listObjects(): Promise<any[]> {
-      return Array.from(getTypeMap('object').values());
-    },
-  };
-}

package/src/fallbacks/memory-queue.ts

@@ -1,28 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-/**
- * In-memory publish/subscribe queue fallback.
- *
- * Implements the IQueueService contract with synchronous in-process delivery.
- * Used by ObjectKernel as an automatic fallback when no real queue plugin
- * (e.g. BullMQ / RabbitMQ) is registered.
- */
-export function createMemoryQueue() {
-  const handlers = new Map<string, Function[]>();
-  let msgId = 0;
-  return {
-    _fallback: true, _serviceName: 'queue',
-    async publish<T = unknown>(queue: string, data: T): Promise<string> {
-      const id = `fallback-msg-${++msgId}`;
-      const fns = handlers.get(queue) ?? [];
-      for (const fn of fns) fn({ id, data, attempts: 1, timestamp: Date.now() });
-      return id;
-    },
-    async subscribe(queue: string, handler: (msg: any) => Promise<void>): Promise<void> {
-      handlers.set(queue, [...(handlers.get(queue) ?? []), handler]);
-    },
-    async unsubscribe(queue: string): Promise<void> { handlers.delete(queue); },
-    async getQueueSize(): Promise<number> { return 0; },
-    async purge(queue: string): Promise<void> { handlers.delete(queue); },
-  };
-}

package/src/health-monitor.test.ts

@@ -1,81 +0,0 @@
-import { describe, it, expect, beforeEach } from 'vitest';
-import { PluginHealthMonitor } from './health-monitor.js';
-import { createLogger } from './logger.js';
-import type { PluginHealthCheck } from '@objectstack/spec/kernel';
-
-describe('PluginHealthMonitor', () => {
-  let monitor: PluginHealthMonitor;
-  let logger: ReturnType<typeof createLogger>;
-
-  beforeEach(() => {
-    logger = createLogger({ level: 'silent' });
-    monitor = new PluginHealthMonitor(logger);
-  });
-
-  it('should register plugin for health monitoring', () => {
-    const config: PluginHealthCheck = {
-      interval: 5000,
-      timeout: 1000,
-      failureThreshold: 3,
-      successThreshold: 1,
-      autoRestart: false,
-      maxRestartAttempts: 3,
-      restartBackoff: 'exponential',
-    };
-
-    monitor.registerPlugin('test-plugin', config);
-    expect(monitor.getHealthStatus('test-plugin')).toBe('unknown');
-  });
-
-  it('should report healthy status initially', () => {
-    const config: PluginHealthCheck = {
-      interval: 5000,
-      timeout: 1000,
-      failureThreshold: 3,
-      successThreshold: 1,
-      autoRestart: false,
-      maxRestartAttempts: 3,
-      restartBackoff: 'fixed',
-    };
-
-    monitor.registerPlugin('test-plugin', config);
-    expect(monitor.getHealthStatus('test-plugin')).toBe('unknown');
-  });
-
-  it('should get all health statuses', () => {
-    const config: PluginHealthCheck = {
-      interval: 5000,
-      timeout: 1000,
-      failureThreshold: 3,
-      successThreshold: 1,
-      autoRestart: false,
-      maxRestartAttempts: 3,
-      restartBackoff: 'linear',
-    };
-
-    monitor.registerPlugin('plugin1', config);
-    monitor.registerPlugin('plugin2', config);
-    
-    const statuses = monitor.getAllHealthStatuses();
-    expect(statuses.size).toBe(2);
-    expect(statuses.has('plugin1')).toBe(true);
-    expect(statuses.has('plugin2')).toBe(true);
-  });
-
-  it('should shutdown cleanly', () => {
-    const config: PluginHealthCheck = {
-      interval: 5000,
-      timeout: 1000,
-      failureThreshold: 3,
-      successThreshold: 1,
-      autoRestart: false,
-      maxRestartAttempts: 3,
-      restartBackoff: 'exponential',
-    };
-
-    monitor.registerPlugin('test-plugin', config);
-    monitor.shutdown();
-    
-    expect(monitor.getAllHealthStatuses().size).toBe(0);
-  });
-});

package/src/health-monitor.ts

@@ -1,318 +0,0 @@
-// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
-
-import type { 
-  PluginHealthStatus, 
-  PluginHealthCheck, 
-  PluginHealthReport 
-} from '@objectstack/spec/kernel';
-import type { ObjectLogger } from './logger.js';
-import type { Plugin } from './types.js';
-
-/**
- * Plugin Health Monitor
- * 
- * Monitors plugin health status and performs automatic recovery actions.
- * Implements the advanced lifecycle health monitoring protocol.
- */
-export class PluginHealthMonitor {
-  private logger: ObjectLogger;
-  private healthChecks = new Map<string, PluginHealthCheck>();
-  private healthStatus = new Map<string, PluginHealthStatus>();
-  private healthReports = new Map<string, PluginHealthReport>();
-  private checkIntervals = new Map<string, NodeJS.Timeout>();
-  private failureCounters = new Map<string, number>();
-  private successCounters = new Map<string, number>();
-  private restartAttempts = new Map<string, number>();
-
-  constructor(logger: ObjectLogger) {
-    this.logger = logger.child({ component: 'HealthMonitor' });
-  }
-
-  /**
-   * Register a plugin for health monitoring
-   */
-  registerPlugin(pluginName: string, config: PluginHealthCheck): void {
-    this.healthChecks.set(pluginName, config);
-    this.healthStatus.set(pluginName, 'unknown');
-    this.failureCounters.set(pluginName, 0);
-    this.successCounters.set(pluginName, 0);
-    this.restartAttempts.set(pluginName, 0);
-
-    this.logger.info('Plugin registered for health monitoring', { 
-      plugin: pluginName,
-      interval: config.interval 
-    });
-  }
-
-  /**
-   * Start monitoring a plugin
-   */
-  startMonitoring(pluginName: string, plugin: Plugin): void {
-    const config = this.healthChecks.get(pluginName);
-    if (!config) {
-      this.logger.warn('Cannot start monitoring - plugin not registered', { plugin: pluginName });
-      return;
-    }
-
-    // Clear any existing interval
-    this.stopMonitoring(pluginName);
-
-    // Set up periodic health checks
-    const interval = setInterval(() => {
-      this.performHealthCheck(pluginName, plugin, config).catch(error => {
-        this.logger.error('Health check failed with error', { 
-          plugin: pluginName, 
-          error 
-        });
-      });
-    }, config.interval);
-
-    this.checkIntervals.set(pluginName, interval);
-    this.logger.info('Health monitoring started', { plugin: pluginName });
-
-    // Perform initial health check
-    this.performHealthCheck(pluginName, plugin, config).catch(error => {
-      this.logger.error('Initial health check failed', { 
-        plugin: pluginName, 
-        error 
-      });
-    });
-  }
-
-  /**
-   * Stop monitoring a plugin
-   */
-  stopMonitoring(pluginName: string): void {
-    const interval = this.checkIntervals.get(pluginName);
-    if (interval) {
-      clearInterval(interval);
-      this.checkIntervals.delete(pluginName);
-      this.logger.info('Health monitoring stopped', { plugin: pluginName });
-    }
-  }
-
-  /**
-   * Perform a health check on a plugin
-   */
-  private async performHealthCheck(
-    pluginName: string,
-    plugin: Plugin,
-    config: PluginHealthCheck
-  ): Promise<void> {
-    const startTime = Date.now();
-    let status: PluginHealthStatus = 'healthy';
-    let message: string | undefined;
-    const checks: Array<{ name: string; status: 'passed' | 'failed' | 'warning'; message?: string }> = [];
-
-    try {
-      // Check if plugin has a custom health check method
-      if (config.checkMethod && typeof (plugin as any)[config.checkMethod] === 'function') {
-        const checkResult = await Promise.race([
-          (plugin as any)[config.checkMethod](),
-          this.timeout(config.timeout, `Health check timeout after ${config.timeout}ms`)
-        ]);
-
-        if (checkResult === false || (checkResult && checkResult.status === 'unhealthy')) {
-          status = 'unhealthy';
-          message = checkResult?.message || 'Custom health check failed';
-          checks.push({ name: config.checkMethod, status: 'failed', message });
-        } else {
-          checks.push({ name: config.checkMethod, status: 'passed' });
-        }
-      } else {
-        // Default health check - just verify plugin is loaded
-        checks.push({ name: 'plugin-loaded', status: 'passed' });
-      }
-
-      // Update counters based on result
-      if (status === 'healthy') {
-        this.successCounters.set(pluginName, (this.successCounters.get(pluginName) || 0) + 1);
-        this.failureCounters.set(pluginName, 0);
-
-        // Recover from unhealthy state if we have enough successes
-        const currentStatus = this.healthStatus.get(pluginName);
-        if (currentStatus === 'unhealthy' || currentStatus === 'degraded') {
-          const successCount = this.successCounters.get(pluginName) || 0;
-          if (successCount >= config.successThreshold) {
-            this.healthStatus.set(pluginName, 'healthy');
-            this.logger.info('Plugin recovered to healthy state', { plugin: pluginName });
-          } else {
-            this.healthStatus.set(pluginName, 'recovering');
-          }
-        } else {
-          this.healthStatus.set(pluginName, 'healthy');
-        }
-      } else {
-        this.failureCounters.set(pluginName, (this.failureCounters.get(pluginName) || 0) + 1);
-        this.successCounters.set(pluginName, 0);
-
-        const failureCount = this.failureCounters.get(pluginName) || 0;
-        if (failureCount >= config.failureThreshold) {
-          this.healthStatus.set(pluginName, 'unhealthy');
-          this.logger.warn('Plugin marked as unhealthy', { 
-            plugin: pluginName, 
-            failures: failureCount 
-          });
-
-          // Attempt auto-restart if configured
-          if (config.autoRestart) {
-            await this.attemptRestart(pluginName, plugin, config);
-          }
-        } else {
-          this.healthStatus.set(pluginName, 'degraded');
-        }
-      }
-    } catch (error) {
-      status = 'failed';
-      message = error instanceof Error ? error.message : 'Unknown error';
-      this.failureCounters.set(pluginName, (this.failureCounters.get(pluginName) || 0) + 1);
-      this.healthStatus.set(pluginName, 'failed');
-      
-      checks.push({ 
-        name: 'health-check', 
-        status: 'failed', 
-        message: message 
-      });
-
-      this.logger.error('Health check exception', { 
-        plugin: pluginName, 
-        error 
-      });
-    }
-
-    // Create health report
-    const report: PluginHealthReport = {
-      status: this.healthStatus.get(pluginName) || 'unknown',
-      timestamp: new Date().toISOString(),
-      message,
-      metrics: {
-        uptime: Date.now() - startTime,
-      },
-      checks: checks.length > 0 ? checks : undefined,
-    };
-
-    this.healthReports.set(pluginName, report);
-  }
-
-  /**
-   * Attempt to restart a plugin
-   */
-  private async attemptRestart(
-    pluginName: string,
-    plugin: Plugin,
-    config: PluginHealthCheck
-  ): Promise<void> {
-    const attempts = this.restartAttempts.get(pluginName) || 0;
-    
-    if (attempts >= config.maxRestartAttempts) {
-      this.logger.error('Max restart attempts reached, giving up', { 
-        plugin: pluginName, 
-        attempts 
-      });
-      this.healthStatus.set(pluginName, 'failed');
-      return;
-    }
-
-    this.restartAttempts.set(pluginName, attempts + 1);
-    
-    // Calculate backoff delay
-    const delay = this.calculateBackoff(attempts, config.restartBackoff);
-    
-    this.logger.info('Scheduling plugin restart', { 
-      plugin: pluginName, 
-      attempt: attempts + 1, 
-      delay 
-    });
-
-    await new Promise(resolve => setTimeout(resolve, delay));
-
-    try {
-      // Call destroy and init to restart
-      if (plugin.destroy) {
-        await plugin.destroy();
-      }
-      
-      // Note: Full restart would require kernel context
-      // This is a simplified version - actual implementation would need kernel integration
-      this.logger.info('Plugin restarted', { plugin: pluginName });
-      
-      // Reset counters on successful restart
-      this.failureCounters.set(pluginName, 0);
-      this.successCounters.set(pluginName, 0);
-      this.healthStatus.set(pluginName, 'recovering');
-    } catch (error) {
-      this.logger.error('Plugin restart failed', { 
-        plugin: pluginName, 
-        error 
-      });
-      this.healthStatus.set(pluginName, 'failed');
-    }
-  }
-
-  /**
-   * Calculate backoff delay for restarts
-   */
-  private calculateBackoff(attempt: number, strategy: 'fixed' | 'linear' | 'exponential'): number {
-    const baseDelay = 1000; // 1 second base
-
-    switch (strategy) {
-      case 'fixed':
-        return baseDelay;
-      case 'linear':
-        return baseDelay * (attempt + 1);
-      case 'exponential':
-        return baseDelay * Math.pow(2, attempt);
-      default:
-        return baseDelay;
-    }
-  }
-
-  /**
-   * Get current health status of a plugin
-   */
-  getHealthStatus(pluginName: string): PluginHealthStatus | undefined {
-    return this.healthStatus.get(pluginName);
-  }
-
-  /**
-   * Get latest health report for a plugin
-   */
-  getHealthReport(pluginName: string): PluginHealthReport | undefined {
-    return this.healthReports.get(pluginName);
-  }
-
-  /**
-   * Get all health statuses
-   */
-  getAllHealthStatuses(): Map<string, PluginHealthStatus> {
-    return new Map(this.healthStatus);
-  }
-
-  /**
-   * Shutdown health monitor
-   */
-  shutdown(): void {
-    // Stop all monitoring intervals
-    for (const pluginName of this.checkIntervals.keys()) {
-      this.stopMonitoring(pluginName);
-    }
-    
-    this.healthChecks.clear();
-    this.healthStatus.clear();
-    this.healthReports.clear();
-    this.failureCounters.clear();
-    this.successCounters.clear();
-    this.restartAttempts.clear();
-    
-    this.logger.info('Health monitor shutdown complete');
-  }
-
-  /**
-   * Timeout helper
-   */
-  private timeout<T>(ms: number, message: string): Promise<T> {
-    return new Promise((_, reject) => {
-      setTimeout(() => reject(new Error(message)), ms);
-    });
-  }
-}