@objectstack/core 3.0.3 → 3.0.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@objectstack/core",
-  "version": "3.0.3",
+  "version": "3.0.5",
   "license": "Apache-2.0",
   "description": "Microkernel Core for ObjectStack",
   "type": "module",
@@ -22,7 +22,7 @@
     "pino": "^10.3.0",
     "pino-pretty": "^13.1.3",
     "zod": "^4.3.6",
-    "@objectstack/spec": "3.0.3"
+    "@objectstack/spec": "3.0.5"
   },
   "peerDependencies": {
     "pino": "^8.0.0"

package/src/fallbacks/fallbacks.test.ts

@@ -0,0 +1,158 @@
+import { describe, it, expect } from 'vitest';
+import { createMemoryCache } from './memory-cache';
+import { createMemoryQueue } from './memory-queue';
+import { createMemoryJob } from './memory-job';
+import { CORE_FALLBACK_FACTORIES } from './index';
+
+describe('CORE_FALLBACK_FACTORIES', () => {
+    it('should have exactly 3 entries: cache, queue, job', () => {
+        expect(Object.keys(CORE_FALLBACK_FACTORIES)).toEqual(['cache', 'queue', 'job']);
+    });
+
+    it('should map to factory functions', () => {
+        for (const factory of Object.values(CORE_FALLBACK_FACTORIES)) {
+            expect(typeof factory).toBe('function');
+        }
+    });
+});
+
+describe('createMemoryCache', () => {
+    it('should return an object with _fallback: true', () => {
+        const cache = createMemoryCache();
+        expect(cache._fallback).toBe(true);
+        expect(cache._serviceName).toBe('cache');
+    });
+
+    it('should set and get a value', async () => {
+        const cache = createMemoryCache();
+        await cache.set('key1', 'value1');
+        expect(await cache.get('key1')).toBe('value1');
+    });
+
+    it('should return undefined for missing key', async () => {
+        const cache = createMemoryCache();
+        expect(await cache.get('nonexistent')).toBeUndefined();
+    });
+
+    it('should delete a key', async () => {
+        const cache = createMemoryCache();
+        await cache.set('key1', 'value1');
+        expect(await cache.delete('key1')).toBe(true);
+        expect(await cache.get('key1')).toBeUndefined();
+    });
+
+    it('should check if a key exists with has()', async () => {
+        const cache = createMemoryCache();
+        expect(await cache.has('key1')).toBe(false);
+        await cache.set('key1', 'value1');
+        expect(await cache.has('key1')).toBe(true);
+    });
+
+    it('should clear all entries', async () => {
+        const cache = createMemoryCache();
+        await cache.set('a', 1);
+        await cache.set('b', 2);
+        await cache.clear();
+        expect(await cache.has('a')).toBe(false);
+        expect(await cache.has('b')).toBe(false);
+    });
+
+    it('should expire entries based on TTL', async () => {
+        const cache = createMemoryCache();
+        // Set with very short TTL (0.001 seconds = 1ms)
+        await cache.set('temp', 'data', 0.001);
+        // Wait for expiry
+        await new Promise(r => setTimeout(r, 20));
+        expect(await cache.get('temp')).toBeUndefined();
+    });
+
+    it('should track hit/miss stats', async () => {
+        const cache = createMemoryCache();
+        await cache.set('key1', 'value1');
+        await cache.get('key1');      // hit
+        await cache.get('missing');   // miss
+        const stats = await cache.stats();
+        expect(stats.hits).toBe(1);
+        expect(stats.misses).toBe(1);
+        expect(stats.keyCount).toBe(1);
+    });
+});
+
+describe('createMemoryQueue', () => {
+    it('should return an object with _fallback: true', () => {
+        const queue = createMemoryQueue();
+        expect(queue._fallback).toBe(true);
+        expect(queue._serviceName).toBe('queue');
+    });
+
+    it('should publish and deliver to subscriber synchronously', async () => {
+        const queue = createMemoryQueue();
+        const received: any[] = [];
+        await queue.subscribe('test-q', async (msg: any) => { received.push(msg); });
+        const id = await queue.publish('test-q', { hello: 'world' });
+        expect(id).toMatch(/^fallback-msg-/);
+        expect(received).toHaveLength(1);
+        expect(received[0].data).toEqual({ hello: 'world' });
+    });
+
+    it('should not deliver to unsubscribed queue', async () => {
+        const queue = createMemoryQueue();
+        const received: any[] = [];
+        await queue.subscribe('q1', async (msg: any) => { received.push(msg); });
+        await queue.unsubscribe('q1');
+        await queue.publish('q1', 'data');
+        expect(received).toHaveLength(0);
+    });
+
+    it('should return queue size of 0', async () => {
+        const queue = createMemoryQueue();
+        expect(await queue.getQueueSize()).toBe(0);
+    });
+
+    it('should purge a queue', async () => {
+        const queue = createMemoryQueue();
+        const received: any[] = [];
+        await queue.subscribe('q1', async (msg: any) => { received.push(msg); });
+        await queue.purge('q1');
+        await queue.publish('q1', 'data');
+        expect(received).toHaveLength(0);
+    });
+});
+
+describe('createMemoryJob', () => {
+    it('should return an object with _fallback: true', () => {
+        const job = createMemoryJob();
+        expect(job._fallback).toBe(true);
+        expect(job._serviceName).toBe('job');
+    });
+
+    it('should schedule and list jobs', async () => {
+        const job = createMemoryJob();
+        await job.schedule('daily-report', '0 0 * * *', async () => {});
+        expect(await job.listJobs()).toEqual(['daily-report']);
+    });
+
+    it('should cancel a job', async () => {
+        const job = createMemoryJob();
+        await job.schedule('temp-job', '* * * * *', async () => {});
+        await job.cancel('temp-job');
+        expect(await job.listJobs()).toEqual([]);
+    });
+
+    it('should trigger a job handler', async () => {
+        const job = createMemoryJob();
+        let triggered = false;
+        await job.schedule('my-job', '* * * * *', async (ctx: any) => {
+            triggered = true;
+            expect(ctx.jobId).toBe('my-job');
+            expect(ctx.data).toEqual({ key: 'val' });
+        });
+        await job.trigger('my-job', { key: 'val' });
+        expect(triggered).toBe(true);
+    });
+
+    it('should return empty executions', async () => {
+        const job = createMemoryJob();
+        expect(await job.getExecutions()).toEqual([]);
+    });
+});

package/src/fallbacks/index.ts

@@ -0,0 +1,20 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+import { createMemoryCache } from './memory-cache.js';
+import { createMemoryQueue } from './memory-queue.js';
+import { createMemoryJob } from './memory-job.js';
+
+export { createMemoryCache } from './memory-cache.js';
+export { createMemoryQueue } from './memory-queue.js';
+export { createMemoryJob } from './memory-job.js';
+
+/**
+ * Map of core-criticality service names to their in-memory fallback factories.
+ * Used by ObjectKernel.validateSystemRequirements() to auto-inject fallbacks
+ * when no real plugin provides the service.
+ */
+export const CORE_FALLBACK_FACTORIES: Record<string, () => Record<string, any>> = {
+  cache: createMemoryCache,
+  queue: createMemoryQueue,
+  job:   createMemoryJob,
+};

package/src/fallbacks/memory-cache.ts

@@ -0,0 +1,34 @@
+// 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-job.ts

@@ -0,0 +1,23 @@
+// 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-queue.ts

@@ -0,0 +1,28 @@
+// 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/index.ts

@@ -23,6 +23,9 @@ export * from './security/index.js';
 // Export environment utilities
 export * from './utils/env.js';
 
+// Export in-memory fallbacks for core-criticality services
+export * from './fallbacks/index.js';
+
 // Export Phase 2 components - Advanced lifecycle management
 export * from './health-monitor.js';
 export * from './hot-reload.js';

package/src/kernel.ts

@@ -6,6 +6,7 @@ import type { LoggerConfig } from '@objectstack/spec/system';
 import { ServiceRequirementDef } from '@objectstack/spec/system';
 import { PluginLoader, PluginMetadata, ServiceLifecycle, ServiceFactory, PluginStartupResult } from './plugin-loader.js';
 import { isNode, safeExit } from './utils/env.js';
+import { CORE_FALLBACK_FACTORIES } from './fallbacks/index.js';
 
 /**
  * Enhanced Kernel Configuration
@@ -234,8 +235,16 @@ export class ObjectKernel {
                     this.logger.error(`CRITICAL: Required service missing: ${serviceName}`);
                     missingServices.push(serviceName);
                 } else if (criticality === 'core') {
-                    this.logger.warn(`CORE: Core service missing, functionality may be degraded: ${serviceName}`);
-                    missingCoreServices.push(serviceName);
+                    // Auto-inject in-memory fallback if available
+                    const factory = CORE_FALLBACK_FACTORIES[serviceName];
+                    if (factory) {
+                        const fallback = factory();
+                        this.registerService(serviceName, fallback);
+                        this.logger.warn(`Service '${serviceName}' not provided — using in-memory fallback`);
+                    } else {
+                        this.logger.warn(`CORE: Core service missing, functionality may be degraded: ${serviceName}`);
+                        missingCoreServices.push(serviceName);
+                    }
                 } else {
                     this.logger.info(`Info: Optional service not present: ${serviceName}`);
                 }