Merge pull request #599 from objectstack-ai/copilot/add-service-contract-interfaces

Author: hotlong

packages/spec/src/contracts/cache-service.test.ts

@@ -0,0 +1,111 @@
+import { describe, it, expect } from 'vitest';
+import type { ICacheService, CacheStats } from './cache-service';
+
+describe('Cache Service Contract', () => {
+  it('should allow a minimal ICacheService implementation', () => {
+    const cache: ICacheService = {
+      get: async <T>(_key: string) => undefined as T | undefined,
+      set: async (_key, _value, _ttl?) => {},
+      delete: async (_key) => false,
+      has: async (_key) => false,
+      clear: async () => {},
+      stats: async () => ({ hits: 0, misses: 0, keyCount: 0 }),
+    };
+
+    expect(typeof cache.get).toBe('function');
+    expect(typeof cache.set).toBe('function');
+    expect(typeof cache.delete).toBe('function');
+    expect(typeof cache.has).toBe('function');
+    expect(typeof cache.clear).toBe('function');
+    expect(typeof cache.stats).toBe('function');
+  });
+
+  it('should perform basic cache operations', async () => {
+    const store = new Map<string, { value: unknown; ttl?: number }>();
+
+    const cache: ICacheService = {
+      get: async <T>(key: string) => {
+        const entry = store.get(key);
+        return entry ? entry.value as T : undefined;
+      },
+      set: async (key, value, ttl?) => {
+        store.set(key, { value, ttl });
+      },
+      delete: async (key) => store.delete(key),
+      has: async (key) => store.has(key),
+      clear: async () => { store.clear(); },
+      stats: async () => ({
+        hits: 0,
+        misses: 0,
+        keyCount: store.size,
+      }),
+    };
+
+    await cache.set('user:1', { name: 'Alice' }, 60);
+    expect(await cache.has('user:1')).toBe(true);
+    expect(await cache.get('user:1')).toEqual({ name: 'Alice' });
+
+    await cache.delete('user:1');
+    expect(await cache.has('user:1')).toBe(false);
+    expect(await cache.get('user:1')).toBeUndefined();
+  });
+
+  it('should return cache stats', async () => {
+    let hits = 0;
+    let misses = 0;
+    const store = new Map<string, unknown>();
+
+    const cache: ICacheService = {
+      get: async <T>(key: string) => {
+        if (store.has(key)) {
+          hits++;
+          return store.get(key) as T;
+        }
+        misses++;
+        return undefined;
+      },
+      set: async (key, value) => { store.set(key, value); },
+      delete: async (key) => store.delete(key),
+      has: async (key) => store.has(key),
+      clear: async () => { store.clear(); },
+      stats: async (): Promise<CacheStats> => ({
+        hits,
+        misses,
+        keyCount: store.size,
+        memoryUsage: 1024,
+      }),
+    };
+
+    await cache.set('a', 1);
+    await cache.get('a');
+    await cache.get('b');
+
+    const s = await cache.stats();
+    expect(s.hits).toBe(1);
+    expect(s.misses).toBe(1);
+    expect(s.keyCount).toBe(1);
+    expect(s.memoryUsage).toBe(1024);
+  });
+
+  it('should clear all entries', async () => {
+    const store = new Map<string, unknown>();
+
+    const cache: ICacheService = {
+      get: async <T>(key: string) => store.get(key) as T | undefined,
+      set: async (key, value) => { store.set(key, value); },
+      delete: async (key) => store.delete(key),
+      has: async (key) => store.has(key),
+      clear: async () => { store.clear(); },
+      stats: async () => ({ hits: 0, misses: 0, keyCount: store.size }),
+    };
+
+    await cache.set('x', 1);
+    await cache.set('y', 2);
+    await cache.clear();
+
+    expect(await cache.has('x')).toBe(false);
+    expect(await cache.has('y')).toBe(false);
+    const s = await cache.stats();
+    expect(s.keyCount).toBe(0);
+  });
+});

packages/spec/src/contracts/cache-service.ts

@@ -0,0 +1,69 @@
+// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * ICacheService - Cache Service Contract
+ * 
+ * Defines the interface for cache operations in ObjectStack.
+ * Concrete implementations (Redis, Memory, etc.) should implement this interface.
+ * 
+ * Follows Dependency Inversion Principle - plugins depend on this interface,
+ * not on concrete cache implementations.
+ * 
+ * Aligned with CoreServiceName 'cache' in core-services.zod.ts.
+ */
+
+/**
+ * Cache statistics for monitoring and observability
+ */
+export interface CacheStats {
+    /** Total number of cache hits */
+    hits: number;
+    /** Total number of cache misses */
+    misses: number;
+    /** Number of keys currently stored */
+    keyCount: number;
+    /** Memory usage in bytes (if available) */
+    memoryUsage?: number;
+}
+
+export interface ICacheService {
+    /**
+     * Get a cached value by key
+     * @param key - Cache key
+     * @returns The cached value, or undefined if not found
+     */
+    get<T = unknown>(key: string): Promise<T | undefined>;
+
+    /**
+     * Set a value in the cache
+     * @param key - Cache key
+     * @param value - Value to cache
+     * @param ttl - Optional time-to-live in seconds
+     */
+    set<T = unknown>(key: string, value: T, ttl?: number): Promise<void>;
+
+    /**
+     * Delete a cached value by key
+     * @param key - Cache key
+     * @returns True if the key was deleted, false if it did not exist
+     */
+    delete(key: string): Promise<boolean>;
+
+    /**
+     * Check if a key exists in the cache
+     * @param key - Cache key
+     * @returns True if the key exists
+     */
+    has(key: string): Promise<boolean>;
+
+    /**
+     * Clear all entries from the cache
+     */
+    clear(): Promise<void>;
+
+    /**
+     * Get cache statistics
+     * @returns Cache stats including hits, misses, and key count
+     */
+    stats(): Promise<CacheStats>;
+}

packages/spec/src/contracts/index.ts

@@ -15,3 +15,8 @@ export * from './plugin-validator.js';
 export * from './startup-orchestrator.js';
 export * from './plugin-lifecycle-events.js';
 export * from './schema-driver.js';
+export * from './cache-service.js';
+export * from './search-service.js';
+export * from './queue-service.js';
+export * from './notification-service.js';
+export * from './storage-service.js';

packages/spec/src/contracts/notification-service.test.ts

@@ -0,0 +1,142 @@
+import { describe, it, expect } from 'vitest';
+import type { INotificationService, NotificationMessage, NotificationResult } from './notification-service';
+
+describe('Notification Service Contract', () => {
+  it('should allow a minimal INotificationService implementation with required methods', () => {
+    const service: INotificationService = {
+      send: async (_message) => ({ success: true }),
+    };
+
+    expect(typeof service.send).toBe('function');
+  });
+
+  it('should allow a full implementation with optional methods', () => {
+    const service: INotificationService = {
+      send: async () => ({ success: true }),
+      sendBatch: async (messages) => messages.map(() => ({ success: true })),
+      getChannels: () => ['email', 'sms', 'push'],
+    };
+
+    expect(service.sendBatch).toBeDefined();
+    expect(service.getChannels).toBeDefined();
+  });
+
+  it('should send a notification successfully', async () => {
+    const sent: NotificationMessage[] = [];
+
+    const service: INotificationService = {
+      send: async (message): Promise<NotificationResult> => {
+        sent.push(message);
+        return { success: true, messageId: `msg-${sent.length}` };
+      },
+    };
+
+    const result = await service.send({
+      channel: 'email',
+      to: 'user@example.com',
+      subject: 'Welcome',
+      body: 'Hello, welcome to the platform!',
+    });
+
+    expect(result.success).toBe(true);
+    expect(result.messageId).toBe('msg-1');
+    expect(sent).toHaveLength(1);
+    expect(sent[0].channel).toBe('email');
+  });
+
+  it('should handle notification failures', async () => {
+    const service: INotificationService = {
+      send: async (_message): Promise<NotificationResult> => ({
+        success: false,
+        error: 'Invalid recipient',
+      }),
+    };
+
+    const result = await service.send({
+      channel: 'sms',
+      to: '',
+      body: 'Test',
+    });
+
+    expect(result.success).toBe(false);
+    expect(result.error).toBe('Invalid recipient');
+  });
+
+  it('should send to multiple recipients', async () => {
+    const delivered: string[] = [];
+
+    const service: INotificationService = {
+      send: async (message) => {
+        const recipients = Array.isArray(message.to) ? message.to : [message.to];
+        delivered.push(...recipients);
+        return { success: true };
+      },
+    };
+
+    await service.send({
+      channel: 'push',
+      to: ['user-1', 'user-2', 'user-3'],
+      body: 'New update available',
+    });
+
+    expect(delivered).toEqual(['user-1', 'user-2', 'user-3']);
+  });
+
+  it('should support batch sending', async () => {
+    const service: INotificationService = {
+      send: async () => ({ success: true }),
+      sendBatch: async (messages) =>
+        messages.map((_, i) => ({
+          success: i !== 1, // Second message fails
+          messageId: `msg-${i}`,
+          error: i === 1 ? 'Rate limited' : undefined,
+        })),
+    };
+
+    const results = await service.sendBatch!([
+      { channel: 'email', to: 'a@test.com', body: 'Hello A' },
+      { channel: 'email', to: 'b@test.com', body: 'Hello B' },
+      { channel: 'email', to: 'c@test.com', body: 'Hello C' },
+    ]);
+
+    expect(results).toHaveLength(3);
+    expect(results[0].success).toBe(true);
+    expect(results[1].success).toBe(false);
+    expect(results[1].error).toBe('Rate limited');
+    expect(results[2].success).toBe(true);
+  });
+
+  it('should list available channels', () => {
+    const service: INotificationService = {
+      send: async () => ({ success: true }),
+      getChannels: () => ['email', 'sms', 'in-app'],
+    };
+
+    const channels = service.getChannels!();
+    expect(channels).toContain('email');
+    expect(channels).toContain('sms');
+    expect(channels).toContain('in-app');
+  });
+
+  it('should support template-based notifications', async () => {
+    const sent: NotificationMessage[] = [];
+
+    const service: INotificationService = {
+      send: async (message) => {
+        sent.push(message);
+        return { success: true };
+      },
+    };
+
+    await service.send({
+      channel: 'email',
+      to: 'user@example.com',
+      body: '',
+      templateId: 'welcome-email',
+      templateData: { userName: 'Alice', activationUrl: 'https://example.com/activate' },
+    });
+
+    expect(sent[0].templateId).toBe('welcome-email');
+    expect(sent[0].templateData?.userName).toBe('Alice');
+  });
+});