@agentxjs/core 1.9.1-dev

package/src/mq/README.md

@@ -0,0 +1,166 @@
+# @agentxjs/core/mq
+
+MessageQueue - Reliable message delivery with persistence guarantee.
+
+## Overview
+
+The mq module provides standard interfaces for message queue implementations. It defines platform-agnostic contracts that can be implemented by different providers:
+
+- **Node.js**: SQLite persistence
+- **Cloudflare Workers**: Durable Objects Storage
+- **Browser**: IndexedDB
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                      MessageQueue                            │
+│                                                              │
+│   publish() ─────► Storage ─────► recover()                 │
+│       │              │                                       │
+│       ▼              │                                       │
+│   RxJS Subject ──────┼────► subscribe()                     │
+│                      │                                       │
+│   ack() ◄────────────┴────► getOffset()                     │
+│                                                              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Key Concepts
+
+### At-Least-Once Delivery
+
+Messages are guaranteed to be delivered at least once through:
+
+1. **Persistence**: Messages are stored before broadcast
+2. **Offset Tracking**: Consumer position is persisted via `ack()`
+3. **Recovery**: Missed messages can be fetched via `recover()`
+
+### Real-time + Recovery
+
+```typescript
+// 1. Subscribe for real-time messages
+queue.subscribe("session-123", (entry) => {
+  console.log("Received:", entry.event);
+  // After processing, acknowledge
+  await queue.ack("client-1", "session-123", entry.offset);
+});
+
+// 2. On reconnect, recover missed messages
+const lastOffset = await queue.getOffset("client-1", "session-123");
+const missed = await queue.recover("session-123", lastOffset);
+for (const entry of missed) {
+  console.log("Missed:", entry.event);
+}
+```
+
+## Interfaces
+
+### MessageQueue
+
+```typescript
+interface MessageQueue {
+  // Publish message (async for cross-platform support)
+  publish(topic: string, event: unknown): Promise<string>;
+
+  // Subscribe to real-time messages (in-memory pub/sub)
+  subscribe(topic: string, handler: (entry: QueueEntry) => void): Unsubscribe;
+
+  // Acknowledge consumption (persist consumer offset)
+  ack(consumerId: string, topic: string, offset: string): Promise<void>;
+
+  // Get consumer's current offset
+  getOffset(consumerId: string, topic: string): Promise<string | null>;
+
+  // Recover historical messages
+  recover(topic: string, afterOffset?: string, limit?: number): Promise<QueueEntry[]>;
+
+  // Close and release resources
+  close(): Promise<void>;
+}
+```
+
+### QueueEntry
+
+```typescript
+interface QueueEntry {
+  readonly offset: string; // Unique, monotonically increasing
+  readonly topic: string; // Topic identifier
+  readonly event: unknown; // Message payload
+  readonly timestamp: number; // Unix milliseconds
+}
+```
+
+### MessageQueueProvider
+
+```typescript
+interface MessageQueueProvider {
+  createQueue(config?: QueueConfig): Promise<MessageQueue>;
+}
+```
+
+## Usage with Provider
+
+```typescript
+// Node.js
+import { createNodeProvider } from "@agentxjs/node";
+
+const provider = createNodeProvider({
+  sqlitePath: "./data/queue.db",
+});
+const queue = await provider.createQueue({ retentionMs: 86400000 });
+
+// Cloudflare Workers
+import { createCloudflareProvider } from "@agentxjs/cloudflare";
+
+const provider = createCloudflareProvider(env);
+const queue = await provider.createQueue();
+```
+
+## OffsetGenerator
+
+Utility for generating monotonically increasing offsets:
+
+```typescript
+import { OffsetGenerator } from "@agentxjs/core/mq";
+
+const generator = new OffsetGenerator();
+
+const offset1 = generator.generate(); // "lq5x4g2-0000"
+const offset2 = generator.generate(); // "lq5x4g2-0001"
+
+// Compare offsets
+OffsetGenerator.compare(offset1, offset2); // -1 (offset1 < offset2)
+```
+
+### Offset Format
+
+```
+{timestamp_base36}-{sequence_padded}
+     lq5x4g2      -     0001
+
+- timestamp: Base36 encoded Unix milliseconds
+- sequence: Zero-padded counter for same-millisecond uniqueness
+```
+
+## Difference from EventBus
+
+|             | EventBus             | MessageQueue      |
+| ----------- | -------------------- | ----------------- |
+| Scope       | Process-internal     | Cross-process     |
+| Persistence | None                 | Platform-specific |
+| Delivery    | Best-effort          | At-least-once     |
+| Recovery    | No                   | Yes (via offset)  |
+| Use case    | Component decoupling | Reliable delivery |
+
+## Platform Independence
+
+This module defines **interfaces only** - no platform-specific code:
+
+- No `node:*` imports
+- No `bun:*` imports
+- No SQLite, IndexedDB, or Durable Objects
+
+Implementations are provided by platform packages (`@agentxjs/node`, `@agentxjs/cloudflare`).
+
+## License
+
+MIT

package/src/mq/__tests__/OffsetGenerator.test.ts

@@ -0,0 +1,121 @@
+/**
+ * OffsetGenerator.test.ts - Unit tests for OffsetGenerator
+ */
+
+import { describe, it, expect, beforeEach } from "bun:test";
+import { OffsetGenerator } from "../OffsetGenerator";
+
+describe("OffsetGenerator", () => {
+  let generator: OffsetGenerator;
+
+  beforeEach(() => {
+    generator = new OffsetGenerator();
+  });
+
+  describe("generate", () => {
+    it("should generate an offset string", () => {
+      const offset = generator.generate();
+
+      expect(typeof offset).toBe("string");
+      expect(offset.length).toBeGreaterThan(0);
+    });
+
+    it("should generate offsets in expected format", () => {
+      const offset = generator.generate();
+
+      // Format: {timestamp_base36}-{sequence_padded}
+      const parts = offset.split("-");
+      expect(parts).toHaveLength(2);
+
+      // First part should be base36 timestamp
+      const timestamp = parseInt(parts[0], 36);
+      expect(timestamp).toBeGreaterThan(0);
+
+      // Second part should be zero-padded sequence
+      expect(parts[1]).toMatch(/^\d{4}$/);
+    });
+
+    it("should generate monotonically increasing offsets", () => {
+      const offsets: string[] = [];
+
+      for (let i = 0; i < 100; i++) {
+        offsets.push(generator.generate());
+      }
+
+      // Each offset should be greater than the previous
+      for (let i = 1; i < offsets.length; i++) {
+        expect(OffsetGenerator.compare(offsets[i], offsets[i - 1])).toBeGreaterThan(0);
+      }
+    });
+
+    it("should handle multiple offsets in same millisecond", () => {
+      // Generate many offsets rapidly (likely same millisecond)
+      const offsets = new Set<string>();
+
+      for (let i = 0; i < 1000; i++) {
+        offsets.add(generator.generate());
+      }
+
+      // All offsets should be unique
+      expect(offsets.size).toBe(1000);
+    });
+  });
+
+  describe("compare", () => {
+    it("should return negative when a < b", () => {
+      const a = generator.generate();
+      const b = generator.generate();
+
+      expect(OffsetGenerator.compare(a, b)).toBeLessThan(0);
+    });
+
+    it("should return positive when a > b", () => {
+      const a = generator.generate();
+      const b = generator.generate();
+
+      expect(OffsetGenerator.compare(b, a)).toBeGreaterThan(0);
+    });
+
+    it("should return 0 when a == b", () => {
+      const offset = generator.generate();
+
+      expect(OffsetGenerator.compare(offset, offset)).toBe(0);
+    });
+
+    it("should compare by timestamp first", () => {
+      // Create offsets with different timestamps
+      const earlier = "lq5x4g1-0005"; // Earlier timestamp, higher sequence
+      const later = "lq5x4g2-0001"; // Later timestamp, lower sequence
+
+      expect(OffsetGenerator.compare(earlier, later)).toBeLessThan(0);
+      expect(OffsetGenerator.compare(later, earlier)).toBeGreaterThan(0);
+    });
+
+    it("should compare by sequence when timestamps equal", () => {
+      const low = "lq5x4g2-0001";
+      const high = "lq5x4g2-0005";
+
+      expect(OffsetGenerator.compare(low, high)).toBeLessThan(0);
+      expect(OffsetGenerator.compare(high, low)).toBeGreaterThan(0);
+    });
+  });
+
+  describe("ordering consistency", () => {
+    it("should be usable for sorting", () => {
+      const offsets: string[] = [];
+
+      for (let i = 0; i < 50; i++) {
+        offsets.push(generator.generate());
+      }
+
+      // Shuffle
+      const shuffled = [...offsets].sort(() => Math.random() - 0.5);
+
+      // Sort using compare
+      const sorted = shuffled.sort(OffsetGenerator.compare);
+
+      // Should match original order
+      expect(sorted).toEqual(offsets);
+    });
+  });
+});

package/src/mq/index.ts

@@ -0,0 +1,18 @@
+/**
+ * MessageQueue Module
+ *
+ * Provides standard interfaces for reliable message delivery:
+ * - MessageQueue: Core queue interface
+ * - MessageQueueProvider: Factory for platform-specific implementations
+ * - OffsetGenerator: Utility for generating monotonic offsets
+ */
+
+export type {
+  QueueEntry,
+  QueueConfig,
+  Unsubscribe,
+  MessageQueue,
+  MessageQueueProvider,
+} from "./types";
+
+export { OffsetGenerator } from "./OffsetGenerator";

package/src/mq/types.ts

@@ -0,0 +1,172 @@
+/**
+ * MessageQueue - Reliable message delivery with persistence guarantee
+ *
+ * Standard interface for message queue implementations:
+ * - In-memory pub/sub for real-time delivery (RxJS)
+ * - Persistence for recovery guarantee (platform-specific)
+ * - Consumer offset tracking for at-least-once delivery
+ *
+ * Platform implementations:
+ * - Node.js: SQLite
+ * - Cloudflare Workers: Durable Objects Storage
+ * - Browser: IndexedDB
+ */
+
+// ============================================================================
+// Queue Entry
+// ============================================================================
+
+/**
+ * QueueEntry - A single entry in the message queue
+ */
+export interface QueueEntry {
+  /**
+   * Unique offset for this entry (monotonically increasing)
+   * Format: "{timestamp_base36}-{sequence}"
+   * Example: "lq5x4g2-0001"
+   */
+  readonly offset: string;
+
+  /**
+   * Topic this entry belongs to (e.g., sessionId, agentId)
+   */
+  readonly topic: string;
+
+  /**
+   * The actual event payload
+   */
+  readonly event: unknown;
+
+  /**
+   * Timestamp when the event was published (Unix milliseconds)
+   */
+  readonly timestamp: number;
+}
+
+// ============================================================================
+// Queue Configuration
+// ============================================================================
+
+/**
+ * QueueConfig - Platform-agnostic configuration
+ *
+ * Platform-specific options (path, namespace, etc.) are handled by Provider.
+ */
+export interface QueueConfig {
+  /**
+   * Message retention timeout (milliseconds)
+   * Messages older than this may be deleted during cleanup
+   * @default 86400000 (24 hours)
+   */
+  retentionMs?: number;
+
+  /**
+   * Maximum entries per topic (optional)
+   * When exceeded, oldest entries may be removed
+   */
+  maxEntriesPerTopic?: number;
+}
+
+// ============================================================================
+// Unsubscribe
+// ============================================================================
+
+/**
+ * Unsubscribe function - call to stop receiving messages
+ */
+export type Unsubscribe = () => void;
+
+// ============================================================================
+// MessageQueue Interface
+// ============================================================================
+
+/**
+ * MessageQueue - Standard interface for message queue
+ *
+ * All methods that involve storage are async to support all platforms.
+ */
+export interface MessageQueue {
+  /**
+   * Publish an event to a topic
+   *
+   * - Persists to storage (async)
+   * - Broadcasts to all subscribers (in-memory, sync)
+   *
+   * @param topic - Topic identifier (e.g., sessionId)
+   * @param event - Event payload
+   * @returns Offset of the published entry
+   */
+  publish(topic: string, event: unknown): Promise<string>;
+
+  /**
+   * Subscribe to real-time events on a topic
+   *
+   * Receives events published after subscription (in-memory pub/sub).
+   * For historical events, use recover() first.
+   *
+   * @param topic - Topic identifier
+   * @param handler - Callback for each event entry
+   * @returns Unsubscribe function
+   */
+  subscribe(topic: string, handler: (entry: QueueEntry) => void): Unsubscribe;
+
+  /**
+   * Acknowledge consumption (update consumer offset)
+   *
+   * Call this after successfully processing an event.
+   * The offset is persisted for recovery.
+   *
+   * @param consumerId - Consumer identifier (e.g., connectionId)
+   * @param topic - Topic identifier
+   * @param offset - Offset of the consumed entry
+   */
+  ack(consumerId: string, topic: string, offset: string): Promise<void>;
+
+  /**
+   * Get consumer's current offset
+   *
+   * @param consumerId - Consumer identifier
+   * @param topic - Topic identifier
+   * @returns Offset or null if consumer not found
+   */
+  getOffset(consumerId: string, topic: string): Promise<string | null>;
+
+  /**
+   * Recover historical events from persistence
+   *
+   * Used for reconnection recovery - fetches events after an offset.
+   *
+   * @param topic - Topic identifier
+   * @param afterOffset - Start offset (exclusive), omit for all history
+   * @param limit - Maximum entries to return (default: 1000)
+   * @returns Array of event entries
+   */
+  recover(topic: string, afterOffset?: string, limit?: number): Promise<QueueEntry[]>;
+
+  /**
+   * Close the message queue and release resources
+   */
+  close(): Promise<void>;
+}
+
+// ============================================================================
+// MessageQueue Provider
+// ============================================================================
+
+/**
+ * MessageQueueProvider - Factory for creating MessageQueue instances
+ *
+ * Each platform implements its own provider:
+ * - SqliteMessageQueueProvider (Node.js)
+ * - DurableMessageQueueProvider (Cloudflare Workers)
+ * - IndexedDBMessageQueueProvider (Browser)
+ */
+export interface MessageQueueProvider {
+  /**
+   * Create a MessageQueue instance
+   *
+   * @param config - Platform-agnostic configuration
+   * @returns MessageQueue instance
+   */
+  createQueue(config?: QueueConfig): Promise<MessageQueue>;
+}