@kb-labs/adapters 0.5.0

package/packages/adapters-eventbus-cache/README.md

@@ -0,0 +1,242 @@
+# @kb-labs/adapters-eventbus-cache
+
+> Part of [KB Labs](https://github.com/KirillBaranov/kb-labs) ecosystem. Works exclusively within KB Labs platform.
+
+EventBus adapter that uses platform cache (`ICache`) for persistent event storage with polling-based subscriptions.
+
+## Overview
+
+| Property | Value |
+|----------|-------|
+| **Implements** | `IEventBus` |
+| **Type** | `core` |
+| **Requires** | `cache` |
+| **Category** | EventBus |
+
+## Features
+
+- **Persistent events** - Events survive process restarts (if cache backend is persistent)
+- **Distributed** - Works across multiple processes (if cache is Redis)
+- **Automatic cleanup** - Old events removed via configurable TTL
+- **Polling-based** - Configurable polling interval for subscribers
+- **Ordered delivery** - Events delivered in timestamp order
+
+## Installation
+
+```bash
+pnpm add @kb-labs/adapters-eventbus-cache
+```
+
+## Configuration
+
+Add to your `kb.config.json`:
+
+```json
+{
+  "platform": {
+    "adapters": {
+      "cache": "@kb-labs/adapters-redis",
+      "eventBus": "@kb-labs/adapters-eventbus-cache"
+    },
+    "adapterOptions": {
+      "eventBus": {
+        "pollIntervalMs": 1000,
+        "eventTtlMs": 86400000,
+        "keyPrefix": "kb:eventbus:"
+      }
+    }
+  }
+}
+```
+
+### Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `pollIntervalMs` | `number` | `1000` | Polling interval in milliseconds |
+| `eventTtlMs` | `number` | `86400000` | Event TTL (24 hours by default) |
+| `keyPrefix` | `string` | `"eventbus:"` | Prefix for cache keys |
+
+## Usage
+
+### Via Platform (Recommended)
+
+```typescript
+import { usePlatform } from '@kb-labs/sdk';
+
+const platform = usePlatform();
+
+// Subscribe to events
+const unsubscribe = platform.eventBus.subscribe('user.created', async (event) => {
+  console.log('User created:', event);
+});
+
+// Publish event
+await platform.eventBus.publish('user.created', { id: '123', name: 'Alice' });
+
+// Cleanup on shutdown
+unsubscribe();
+```
+
+### Standalone (Testing/Development)
+
+```typescript
+import { createAdapter } from '@kb-labs/adapters-eventbus-cache';
+import { MemoryCache } from '@kb-labs/core-platform/noop';
+
+const cache = new MemoryCache();
+const eventBus = createAdapter(
+  { pollIntervalMs: 500, eventTtlMs: 3600000 },
+  { cache },
+);
+
+// Don't forget to disconnect on shutdown
+eventBus.disconnect();
+```
+
+## How It Works
+
+Events are stored in sorted sets using cache's `zadd`/`zrangebyscore` with timestamp as score:
+
+```
+┌─────────────┐     ┌─────────────────────┐     ┌─────────────┐
+│  Publisher  │────▶│  CacheEventBusAdapter│────▶│    Cache    │
+└─────────────┘     └─────────────────────┘     └─────────────┘
+                              │
+                              │ poll (interval)
+                              ▼
+                    ┌─────────────────────┐
+                    │    Subscribers      │
+                    └─────────────────────┘
+```
+
+**Storage structure:**
+```
+eventbus:user.created -> [
+  { score: 1706745600000, member: '{"id":"evt-1","topic":"user.created","data":{...},"timestamp":1706745600000}' },
+  { score: 1706745601000, member: '{"id":"evt-2","topic":"user.created","data":{...},"timestamp":1706745601000}' },
+]
+```
+
+**Subscription flow:**
+1. Subscriber registers with `lastTimestamp = Date.now()`
+2. Polling timer fires every `pollIntervalMs`
+3. Adapter queries `zrangebyscore(key, lastTimestamp + 1, now)`
+4. Events processed sequentially, `lastTimestamp` updated
+5. Old events (> TTL) cleaned up automatically
+
+## Dependencies
+
+This adapter requires the following adapters to be configured:
+
+| Dependency | Adapter Key | Description |
+|------------|-------------|-------------|
+| `cache` | `cache` | Cache backend for event storage (Redis, Memory, etc.) |
+
+> Dependencies are automatically resolved by the platform's AdapterLoader.
+
+## Adapter Manifest
+
+```typescript
+{
+  id: 'eventbus-cache',
+  name: 'Cache-backed EventBus',
+  version: '1.0.0',
+  implements: 'IEventBus',
+  requires: {
+    adapters: [{ id: 'cache', alias: 'cache' }],
+    platform: '>= 1.0.0',
+  },
+  capabilities: {
+    custom: {
+      persistence: true,
+      distributed: true,
+      ttl: true,
+      polling: true,
+    },
+  },
+}
+```
+
+## Performance Considerations
+
+- **Memory**: Depends on cache backend; events are JSON-serialized (~200-500 bytes per event)
+- **Latency**: Polling-based, so delivery latency is up to `pollIntervalMs`
+- **Throughput**: Limited by cache backend; Redis handles ~100K ops/sec
+
+**Tuning tips:**
+- Lower `pollIntervalMs` for faster delivery (more CPU/network)
+- Shorter `eventTtlMs` for lower memory usage
+- Use Redis cache for distributed deployments
+
+## FAQ
+
+<details>
+<summary><strong>Q: Can I use this adapter outside KB Labs platform?</strong></summary>
+
+No. This adapter is designed specifically for KB Labs ecosystem and depends on platform interfaces (`IEventBus`, `ICache`). Use `createAdapter()` with mock cache for standalone testing only.
+</details>
+
+<details>
+<summary><strong>Q: Why polling instead of push notifications?</strong></summary>
+
+Polling provides simpler implementation that works with any cache backend. For real-time requirements (< 100ms), consider using Redis pub/sub directly or a dedicated message broker.
+</details>
+
+<details>
+<summary><strong>Q: What happens if a subscriber is slow?</strong></summary>
+
+Events are processed sequentially per subscriber. If a handler is slow, that subscriber will lag behind. Other subscribers are not affected. Events are retained until TTL expires, so slow subscribers can catch up.
+</details>
+
+<details>
+<summary><strong>Q: Are events guaranteed to be delivered exactly once?</strong></summary>
+
+No. This is an at-least-once delivery system. If a process crashes mid-processing, events may be redelivered on restart. Design handlers to be idempotent.
+</details>
+
+<details>
+<summary><strong>Q: Can I use MemoryCache in production?</strong></summary>
+
+Not recommended. MemoryCache is single-process and loses data on restart. Use Redis for production deployments requiring persistence and distribution.
+</details>
+
+## Related Adapters
+
+| Adapter | Use Case |
+|---------|----------|
+| `@kb-labs/adapters-redis` | Cache backend for distributed EventBus |
+| `@kb-labs/core-platform/noop` | MemoryCache for testing/development |
+
+## Troubleshooting
+
+### Events not being received
+
+**Cause**: Subscriber registered after events were published; `lastTimestamp` is newer than event timestamps.
+
+**Solution**: Ensure subscribers are registered before publishers start, or adjust subscription logic.
+
+### High memory usage
+
+**Cause**: Long `eventTtlMs` with high event volume.
+
+**Solution**: Reduce `eventTtlMs` or implement event archiving.
+
+### Slow event delivery
+
+**Cause**: `pollIntervalMs` too high.
+
+**Solution**: Reduce `pollIntervalMs` (e.g., 100ms for near-real-time).
+
+```bash
+# Verify adapter is loaded
+pnpm kb plugins list
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](../../CONTRIBUTING.md) for development guidelines.
+
+## License
+
+[KB Public License v1.1](../../LICENSE) - KB Labs Team

package/packages/adapters-eventbus-cache/eslint.config.js

@@ -0,0 +1,27 @@
+/**
+ * Standard ESLint configuration template
+ *
+ * This is the canonical template for all @kb-labs packages.
+ * DO NOT modify this file locally - it is synced from @kb-labs/devkit
+ *
+ * Customization guidelines:
+ * - DevKit preset already includes all standard ignores
+ * - Only add project-specific ignores if absolutely necessary
+ * - Document why custom ignores are needed
+ *
+ * @see https://github.com/kb-labs/devkit#eslint-configuration
+ */
+import nodePreset from '@kb-labs/devkit/eslint/node.js';
+
+export default [
+  ...nodePreset,
+
+  // OPTIONAL: Add project-specific ignores only if needed
+  // DevKit preset already ignores: dist/, coverage/, node_modules/, *.d.ts, scripts/, etc.
+  // {
+  //   ignores: [
+  //     // Add ONLY project-specific patterns here
+  //     // Example: '**/*.generated.ts',
+  //   ]
+  // }
+];

package/packages/adapters-eventbus-cache/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@kb-labs/adapters-eventbus-cache",
+  "version": "0.5.0",
+  "description": "EventBus adapter using ICache for persistent event storage",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "clean": "rimraf dist",
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests",
+    "test:watch": "vitest",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint . --fix"
+  },
+  "peerDependencies": {
+    "@kb-labs/core-platform": "*"
+  },
+  "devDependencies": {
+    "@kb-labs/core-platform": "link:../../../../platform/kb-labs-core/packages/core-platform",
+    "@types/node": "^24.3.3",
+    "eslint": "^9",
+    "tsup": "^8.5.0",
+    "typescript": "^5.6.3",
+    "vitest": "^3.2.4",
+    "@kb-labs/devkit": "link:../../../kb-labs-devkit",
+    "rimraf": "^6.0.1"
+  },
+  "engines": {
+    "node": ">=20.0.0",
+    "pnpm": ">=9.0.0"
+  }
+}

package/packages/adapters-eventbus-cache/src/index.test.ts

@@ -0,0 +1,235 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { CacheEventBusAdapter, createAdapter } from './index.js';
+import type { ICache } from '@kb-labs/core-platform';
+
+/**
+ * Mock ICache implementation for testing.
+ */
+class MockCache implements ICache {
+  private store = new Map<string, unknown>();
+  private sortedSets = new Map<string, Array<{ score: number; member: string }>>();
+
+  async get<T>(key: string): Promise<T | null> {
+    return (this.store.get(key) as T) ?? null;
+  }
+
+  async set<T>(key: string, value: T, _ttl?: number): Promise<void> {
+    this.store.set(key, value);
+  }
+
+  async delete(key: string): Promise<void> {
+    this.store.delete(key);
+  }
+
+  async clear(_pattern?: string): Promise<void> {
+    this.store.clear();
+    this.sortedSets.clear();
+  }
+
+  async zadd(key: string, score: number, member: string): Promise<void> {
+    let set = this.sortedSets.get(key);
+    if (!set) {
+      set = [];
+      this.sortedSets.set(key, set);
+    }
+
+    // Remove existing member if present
+    const existingIndex = set.findIndex(m => m.member === member);
+    if (existingIndex !== -1) {
+      set.splice(existingIndex, 1);
+    }
+
+    // Add new member and sort by score
+    set.push({ score, member });
+    set.sort((a, b) => a.score - b.score);
+  }
+
+  async zrangebyscore(key: string, min: number, max: number): Promise<string[]> {
+    const set = this.sortedSets.get(key);
+    if (!set) {
+      return [];
+    }
+
+    return set
+      .filter(m => m.score >= min && m.score <= max)
+      .map(m => m.member);
+  }
+
+  async zrem(key: string, member: string): Promise<void> {
+    const set = this.sortedSets.get(key);
+    if (!set) {
+      return;
+    }
+
+    const index = set.findIndex(m => m.member === member);
+    if (index !== -1) {
+      set.splice(index, 1);
+    }
+  }
+
+  async setIfNotExists<T>(key: string, value: T, _ttl?: number): Promise<boolean> {
+    if (this.store.has(key)) {
+      return false;
+    }
+    this.store.set(key, value);
+    return true;
+  }
+}
+
+const TEST_TOPIC = 'test.topic';
+
+describe('CacheEventBusAdapter', () => {
+  let cache: MockCache;
+  let eventBus: CacheEventBusAdapter;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    cache = new MockCache();
+    eventBus = new CacheEventBusAdapter(cache, {
+      pollIntervalMs: 100,
+      eventTtlMs: 60000, // 1 minute
+      keyPrefix: 'test:eventbus:',
+    });
+  });
+
+  afterEach(() => {
+    eventBus.disconnect();
+    vi.useRealTimers();
+  });
+
+  describe('publish', () => {
+    it('should store event in cache', async () => {
+      await eventBus.publish(TEST_TOPIC, { message: 'hello' });
+
+      const events = await cache.zrangebyscore('test:eventbus:test.topic', 0, Date.now() + 1000);
+      expect(events).toHaveLength(1);
+
+      const storedEvent = JSON.parse(events[0]!);
+      expect(storedEvent.topic).toBe(TEST_TOPIC);
+      expect(storedEvent.data).toEqual({ message: 'hello' });
+      expect(storedEvent.id).toBeDefined();
+      expect(storedEvent.timestamp).toBeDefined();
+    });
+
+    it('should store multiple events in order', async () => {
+      await eventBus.publish(TEST_TOPIC, { order: 1 });
+      vi.advanceTimersByTime(10);
+      await eventBus.publish(TEST_TOPIC, { order: 2 });
+      vi.advanceTimersByTime(10);
+      await eventBus.publish(TEST_TOPIC, { order: 3 });
+
+      const events = await cache.zrangebyscore('test:eventbus:test.topic', 0, Date.now() + 1000);
+      expect(events).toHaveLength(3);
+
+      const parsed = events.map(e => JSON.parse(e));
+      expect(parsed[0].data.order).toBe(1);
+      expect(parsed[1].data.order).toBe(2);
+      expect(parsed[2].data.order).toBe(3);
+    });
+  });
+
+  describe('subscribe', () => {
+    it('should receive published events via polling', async () => {
+      const received: unknown[] = [];
+
+      eventBus.subscribe(TEST_TOPIC, async (event) => {
+        received.push(event);
+      });
+
+      // Advance time so event timestamp > subscription lastTimestamp
+      await vi.advanceTimersByTimeAsync(10);
+
+      // Publish an event
+      await eventBus.publish(TEST_TOPIC, { message: 'hello' });
+
+      // Advance timer to trigger poll
+      await vi.advanceTimersByTimeAsync(150);
+
+      expect(received).toHaveLength(1);
+      expect(received[0]).toEqual({ message: 'hello' });
+    });
+
+    it('should return unsubscribe function', () => {
+      const unsubscribe = eventBus.subscribe(TEST_TOPIC, async () => {});
+
+      expect(eventBus.subscriptionCount).toBe(1);
+
+      unsubscribe();
+
+      expect(eventBus.subscriptionCount).toBe(0);
+    });
+
+    it('should support multiple subscribers on same topic', async () => {
+      const received1: unknown[] = [];
+      const received2: unknown[] = [];
+
+      eventBus.subscribe(TEST_TOPIC, async (event) => {
+        received1.push(event);
+      });
+
+      eventBus.subscribe(TEST_TOPIC, async (event) => {
+        received2.push(event);
+      });
+
+      // Advance time so event timestamp > subscription lastTimestamp
+      await vi.advanceTimersByTimeAsync(10);
+
+      await eventBus.publish(TEST_TOPIC, { message: 'hello' });
+
+      await vi.advanceTimersByTimeAsync(150);
+
+      expect(received1).toHaveLength(1);
+      expect(received2).toHaveLength(1);
+    });
+
+    it('should not receive events from other topics', async () => {
+      const received: unknown[] = [];
+
+      eventBus.subscribe('topic.a', async (event) => {
+        received.push(event);
+      });
+
+      await eventBus.publish('topic.b', { message: 'wrong topic' });
+
+      await vi.advanceTimersByTimeAsync(150);
+
+      expect(received).toHaveLength(0);
+    });
+  });
+
+  describe('disconnect', () => {
+    it('should stop all subscriptions', () => {
+      eventBus.subscribe('topic.a', async () => {});
+      eventBus.subscribe('topic.b', async () => {});
+
+      expect(eventBus.subscriptionCount).toBe(2);
+
+      eventBus.disconnect();
+
+      expect(eventBus.subscriptionCount).toBe(0);
+    });
+  });
+
+  describe('createAdapter', () => {
+    it('should create adapter with default config', () => {
+      const adapter = createAdapter({}, { cache });
+
+      expect(adapter).toBeInstanceOf(CacheEventBusAdapter);
+      adapter.disconnect();
+    });
+
+    it('should create adapter with custom config', () => {
+      const adapter = createAdapter(
+        {
+          pollIntervalMs: 500,
+          eventTtlMs: 3600000,
+          keyPrefix: 'custom:',
+        },
+        { cache },
+      );
+
+      expect(adapter).toBeInstanceOf(CacheEventBusAdapter);
+      adapter.disconnect();
+    });
+  });
+});