@dangao/bun-server 1.12.1 → 2.0.0

package/src/conversation/stores/database-store.ts

@@ -0,0 +1,125 @@
+import type { ConversationStore, Conversation } from '../types';
+import type { AiMessage } from '../../ai/types';
+
+export interface DatabaseConversationStoreConfig {
+  /** DatabaseService instance from DatabaseModule */
+  database: DatabaseServiceLike;
+  /** Table name for conversations (default: 'conversations') */
+  tableName?: string;
+}
+
+/**
+ * Minimal interface matching DatabaseService from DatabaseModule
+ */
+export interface DatabaseServiceLike {
+  query<T = unknown>(sql: string, params?: unknown[]): Promise<T[]>;
+  execute(sql: string, params?: unknown[]): Promise<void>;
+}
+
+/**
+ * Database-backed conversation store — suitable for durable storage with full history.
+ *
+ * Creates tables automatically on first use. Requires DatabaseModule to be configured.
+ *
+ * Schema:
+ * ```sql
+ * CREATE TABLE conversations (
+ *   id TEXT PRIMARY KEY,
+ *   messages TEXT NOT NULL,  -- JSON array
+ *   metadata TEXT NOT NULL,  -- JSON object
+ *   created_at TEXT NOT NULL,
+ *   updated_at TEXT NOT NULL
+ * );
+ * ```
+ */
+export class DatabaseConversationStore implements ConversationStore {
+  private readonly db: DatabaseServiceLike;
+  private readonly tableName: string;
+  private initialized = false;
+
+  public constructor(config: DatabaseConversationStoreConfig) {
+    this.db = config.database;
+    this.tableName = config.tableName ?? 'conversations';
+  }
+
+  public async create(metadata: Record<string, unknown> = {}): Promise<Conversation> {
+    await this.ensureTable();
+    const id = crypto.randomUUID();
+    const now = new Date().toISOString();
+    await this.db.execute(
+      `INSERT INTO ${this.tableName} (id, messages, metadata, created_at, updated_at) VALUES (?, ?, ?, ?, ?)`,
+      [id, '[]', JSON.stringify(metadata), now, now],
+    );
+    return { id, messages: [], metadata, createdAt: new Date(now), updatedAt: new Date(now) };
+  }
+
+  public async get(id: string): Promise<Conversation | null> {
+    await this.ensureTable();
+    const rows = await this.db.query<Record<string, string>>(
+      `SELECT * FROM ${this.tableName} WHERE id = ?`,
+      [id],
+    );
+    if (!rows.length) return null;
+    return this.rowToConversation(rows[0]!);
+  }
+
+  public async appendMessage(id: string, message: AiMessage): Promise<void> {
+    await this.ensureTable();
+    const conv = await this.get(id);
+    if (!conv) throw new Error(`Conversation "${id}" not found`);
+    const messages = [...conv.messages, message];
+    const now = new Date().toISOString();
+    await this.db.execute(
+      `UPDATE ${this.tableName} SET messages = ?, updated_at = ? WHERE id = ?`,
+      [JSON.stringify(messages), now, id],
+    );
+  }
+
+  public async trim(id: string, maxMessages: number): Promise<void> {
+    await this.ensureTable();
+    const conv = await this.get(id);
+    if (!conv || conv.messages.length <= maxMessages) return;
+    const trimmed = conv.messages.slice(-maxMessages);
+    const now = new Date().toISOString();
+    await this.db.execute(
+      `UPDATE ${this.tableName} SET messages = ?, updated_at = ? WHERE id = ?`,
+      [JSON.stringify(trimmed), now, id],
+    );
+  }
+
+  public async delete(id: string): Promise<boolean> {
+    await this.ensureTable();
+    await this.db.execute(`DELETE FROM ${this.tableName} WHERE id = ?`, [id]);
+    return true;
+  }
+
+  public async list(): Promise<string[]> {
+    await this.ensureTable();
+    const rows = await this.db.query<{ id: string }>(`SELECT id FROM ${this.tableName}`);
+    return rows.map((r) => r.id);
+  }
+
+  private async ensureTable(): Promise<void> {
+    if (this.initialized) return;
+    await this.db.execute(`
+      CREATE TABLE IF NOT EXISTS ${this.tableName} (
+        id TEXT PRIMARY KEY,
+        messages TEXT NOT NULL DEFAULT '[]',
+        metadata TEXT NOT NULL DEFAULT '{}',
+        created_at TEXT NOT NULL,
+        updated_at TEXT NOT NULL
+      )
+    `);
+    this.initialized = true;
+  }
+
+  private rowToConversation(row: Record<string, string>): Conversation {
+    return {
+      id: row['id']!,
+      messages: JSON.parse(row['messages']!) as AiMessage[],
+      metadata: JSON.parse(row['metadata']!) as Record<string, unknown>,
+      createdAt: new Date(row['created_at']!),
+      updatedAt: new Date(row['updated_at']!),
+    };
+  }
+}

package/src/conversation/stores/memory-store.ts

@@ -0,0 +1,57 @@
+import type { ConversationStore, Conversation } from '../types';
+import type { AiMessage } from '../../ai/types';
+
+/**
+ * In-memory conversation store — suitable for development and single-instance deployments.
+ */
+export class MemoryConversationStore implements ConversationStore {
+  private readonly conversations = new Map<string, Conversation>();
+
+  public async create(metadata: Record<string, unknown> = {}): Promise<Conversation> {
+    const id = crypto.randomUUID();
+    const conversation: Conversation = {
+      id,
+      messages: [],
+      metadata,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    };
+    this.conversations.set(id, conversation);
+    return { ...conversation, messages: [] };
+  }
+
+  public async get(id: string): Promise<Conversation | null> {
+    const conv = this.conversations.get(id);
+    if (!conv) return null;
+    return { ...conv, messages: [...conv.messages] };
+  }
+
+  public async appendMessage(id: string, message: AiMessage): Promise<void> {
+    const conv = this.conversations.get(id);
+    if (!conv) throw new Error(`Conversation "${id}" not found`);
+    conv.messages.push(message);
+    conv.updatedAt = new Date();
+  }
+
+  public async trim(id: string, maxMessages: number): Promise<void> {
+    const conv = this.conversations.get(id);
+    if (!conv) return;
+    if (conv.messages.length > maxMessages) {
+      conv.messages = conv.messages.slice(-maxMessages);
+      conv.updatedAt = new Date();
+    }
+  }
+
+  public async delete(id: string): Promise<boolean> {
+    return this.conversations.delete(id);
+  }
+
+  public async list(): Promise<string[]> {
+    return Array.from(this.conversations.keys());
+  }
+
+  /** Number of stored conversations (for testing) */
+  public get size(): number {
+    return this.conversations.size;
+  }
+}

package/src/conversation/stores/redis-store.ts

@@ -0,0 +1,101 @@
+import type { ConversationStore, Conversation } from '../types';
+import type { AiMessage } from '../../ai/types';
+
+export interface RedisConversationStoreConfig {
+  /** Redis client that supports get/set/del/keys commands */
+  client: RedisClient;
+  /** Key prefix (default: 'conv:') */
+  keyPrefix?: string;
+  /** TTL in seconds for conversation keys (default: 86400 = 24h) */
+  ttl?: number;
+}
+
+/**
+ * Minimal Redis client interface — compatible with ioredis and node-redis
+ */
+export interface RedisClient {
+  get(key: string): Promise<string | null>;
+  set(key: string, value: string, ...args: unknown[]): Promise<unknown>;
+  del(key: string): Promise<unknown>;
+  keys(pattern: string): Promise<string[]>;
+}
+
+/**
+ * Redis-backed conversation store — suitable for multi-instance production deployments.
+ *
+ * Requires an external Redis client to be injected. Compatible with ioredis / node-redis.
+ */
+export class RedisConversationStore implements ConversationStore {
+  private readonly client: RedisClient;
+  private readonly keyPrefix: string;
+  private readonly ttl: number;
+
+  public constructor(config: RedisConversationStoreConfig) {
+    this.client = config.client;
+    this.keyPrefix = config.keyPrefix ?? 'conv:';
+    this.ttl = config.ttl ?? 86400;
+  }
+
+  public async create(metadata: Record<string, unknown> = {}): Promise<Conversation> {
+    const id = crypto.randomUUID();
+    const conversation: Conversation = {
+      id,
+      messages: [],
+      metadata,
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    };
+    await this.save(conversation);
+    return conversation;
+  }
+
+  public async get(id: string): Promise<Conversation | null> {
+    const raw = await this.client.get(this.key(id));
+    if (!raw) return null;
+    const parsed = JSON.parse(raw) as Conversation;
+    parsed.createdAt = new Date(parsed.createdAt);
+    parsed.updatedAt = new Date(parsed.updatedAt);
+    return parsed;
+  }
+
+  public async appendMessage(id: string, message: AiMessage): Promise<void> {
+    const conv = await this.get(id);
+    if (!conv) throw new Error(`Conversation "${id}" not found`);
+    conv.messages.push(message);
+    conv.updatedAt = new Date();
+    await this.save(conv);
+  }
+
+  public async trim(id: string, maxMessages: number): Promise<void> {
+    const conv = await this.get(id);
+    if (!conv) return;
+    if (conv.messages.length > maxMessages) {
+      conv.messages = conv.messages.slice(-maxMessages);
+      conv.updatedAt = new Date();
+      await this.save(conv);
+    }
+  }
+
+  public async delete(id: string): Promise<boolean> {
+    const result = await this.client.del(this.key(id));
+    return Number(result) > 0;
+  }
+
+  public async list(): Promise<string[]> {
+    const keys = await this.client.keys(`${this.keyPrefix}*`);
+    return keys.map((k) => k.slice(this.keyPrefix.length));
+  }
+
+  private key(id: string): string {
+    return `${this.keyPrefix}${id}`;
+  }
+
+  private async save(conversation: Conversation): Promise<void> {
+    await this.client.set(
+      this.key(conversation.id),
+      JSON.stringify(conversation),
+      'EX',
+      this.ttl,
+    );
+  }
+}

package/src/conversation/types.ts

@@ -0,0 +1,68 @@
+import type { AiMessage } from '../ai/types';
+
+/**
+ * A conversation session
+ */
+export interface Conversation {
+  id: string;
+  messages: AiMessage[];
+  metadata: Record<string, unknown>;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/**
+ * Abstract conversation storage interface
+ */
+export interface ConversationStore {
+  /**
+   * Create a new conversation
+   */
+  create(metadata?: Record<string, unknown>): Promise<Conversation>;
+  /**
+   * Retrieve an existing conversation
+   */
+  get(id: string): Promise<Conversation | null>;
+  /**
+   * Append a message to a conversation
+   */
+  appendMessage(id: string, message: AiMessage): Promise<void>;
+  /**
+   * Trim messages to maxMessages (keeping the most recent)
+   */
+  trim(id: string, maxMessages: number): Promise<void>;
+  /**
+   * Delete a conversation
+   */
+  delete(id: string): Promise<boolean>;
+  /**
+   * List all conversation IDs
+   */
+  list(): Promise<string[]>;
+}
+
+/**
+ * Summarizer callback — produce a summary string from conversation history
+ */
+export type ConversationSummarizer = (messages: AiMessage[]) => Promise<string>;
+
+/**
+ * ConversationModule configuration
+ */
+export interface ConversationModuleOptions {
+  store?: ConversationStore;
+  /** Maximum messages before auto-trim (default: 100) */
+  maxMessages?: number;
+  /** Enable auto-trim when maxMessages is reached (default: true) */
+  autoTrim?: boolean;
+  /**
+   * When message count exceeds summaryThreshold, call summarizer and
+   * replace old messages with a summary message.
+   */
+  summaryThreshold?: number;
+  /** Summarizer callback — inject AiService here to avoid circular deps */
+  summarizer?: ConversationSummarizer;
+}
+
+export const CONVERSATION_SERVICE_TOKEN = Symbol('@dangao/bun-server:conversation:service');
+export const CONVERSATION_OPTIONS_TOKEN = Symbol('@dangao/bun-server:conversation:options');

package/src/embedding/embedding-module.ts

@@ -0,0 +1,52 @@
+import { Module, MODULE_METADATA_KEY } from '../di/module';
+import type { ModuleProvider } from '../di/module';
+import { EmbeddingService } from './service';
+import {
+  EMBEDDING_SERVICE_TOKEN,
+  EMBEDDING_OPTIONS_TOKEN,
+  type EmbeddingModuleOptions,
+} from './types';
+
+@Module({ providers: [] })
+export class EmbeddingModule {
+  /**
+   * Configure the embedding module.
+   *
+   * @example
+   * ```typescript
+   * EmbeddingModule.forRoot({
+   *   provider: {
+   *     name: 'openai',
+   *     provider: OpenAIEmbeddingProvider,
+   *     config: { apiKey: process.env.OPENAI_API_KEY! },
+   *   },
+   * });
+   * ```
+   */
+  public static forRoot(options: EmbeddingModuleOptions): typeof EmbeddingModule {
+    const service = new EmbeddingService(options);
+
+    const providers: ModuleProvider[] = [
+      { provide: EMBEDDING_OPTIONS_TOKEN, useValue: options },
+      { provide: EMBEDDING_SERVICE_TOKEN, useValue: service },
+      EmbeddingService,
+    ];
+
+    const existing = Reflect.getMetadata(MODULE_METADATA_KEY, EmbeddingModule) || {};
+    Reflect.defineMetadata(MODULE_METADATA_KEY, {
+      ...existing,
+      providers: [...(existing.providers || []), ...providers],
+      exports: [
+        ...(existing.exports || []),
+        EMBEDDING_SERVICE_TOKEN,
+        EmbeddingService,
+      ],
+    }, EmbeddingModule);
+
+    return EmbeddingModule;
+  }
+
+  public static reset(): void {
+    Reflect.deleteMetadata(MODULE_METADATA_KEY, EmbeddingModule);
+  }
+}

package/src/embedding/index.ts

@@ -0,0 +1,5 @@
+export * from './types';
+export * from './service';
+export * from './embedding-module';
+export * from './providers/openai-embedding-provider';
+export * from './providers/ollama-embedding-provider';

package/src/embedding/providers/ollama-embedding-provider.ts

@@ -0,0 +1,39 @@
+import type { EmbeddingProvider } from '../types';
+import { AiProviderError } from '../../ai/errors';
+
+export interface OllamaEmbeddingProviderConfig {
+  baseUrl?: string;
+  /** Default: nomic-embed-text */
+  model?: string;
+  /** Dimensions depend on model. Default 768 for nomic-embed-text */
+  dimensions?: number;
+}
+
+export class OllamaEmbeddingProvider implements EmbeddingProvider {
+  public readonly name = 'ollama';
+  public readonly dimensions: number;
+  private readonly baseUrl: string;
+  private readonly model: string;
+
+  public constructor(config: OllamaEmbeddingProviderConfig = {}) {
+    this.baseUrl = (config.baseUrl ?? 'http://localhost:11434').replace(/\/$/, '');
+    this.model = config.model ?? 'nomic-embed-text';
+    this.dimensions = config.dimensions ?? 768;
+  }
+
+  public async embed(text: string): Promise<number[]> {
+    const res = await fetch(`${this.baseUrl}/api/embed`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ model: this.model, input: text }),
+    });
+
+    if (!res.ok) throw new AiProviderError(await res.text(), 'ollama-embedding', res.status);
+    const data = await res.json() as { embeddings: number[][] };
+    return data.embeddings[0]!;
+  }
+
+  public async embedBatch(texts: string[]): Promise<number[][]> {
+    return Promise.all(texts.map((t) => this.embed(t)));
+  }
+}

package/src/embedding/providers/openai-embedding-provider.ts

@@ -0,0 +1,47 @@
+import type { EmbeddingProvider } from '../types';
+import { AiProviderError, AiRateLimitError } from '../../ai/errors';
+
+export interface OpenAIEmbeddingProviderConfig {
+  apiKey: string;
+  /** Default: text-embedding-3-small */
+  model?: string;
+  baseUrl?: string;
+}
+
+export class OpenAIEmbeddingProvider implements EmbeddingProvider {
+  public readonly name = 'openai';
+  public readonly dimensions: number;
+  private readonly apiKey: string;
+  private readonly model: string;
+  private readonly baseUrl: string;
+
+  public constructor(config: OpenAIEmbeddingProviderConfig) {
+    this.apiKey = config.apiKey;
+    this.model = config.model ?? 'text-embedding-3-small';
+    this.baseUrl = (config.baseUrl ?? 'https://api.openai.com/v1').replace(/\/$/, '');
+    // text-embedding-3-small: 1536, text-embedding-3-large: 3072
+    this.dimensions = this.model.includes('large') ? 3072 : 1536;
+  }
+
+  public async embed(text: string): Promise<number[]> {
+    const results = await this.embedBatch([text]);
+    return results[0]!;
+  }
+
+  public async embedBatch(texts: string[]): Promise<number[][]> {
+    const res = await fetch(`${this.baseUrl}/embeddings`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${this.apiKey}`,
+      },
+      body: JSON.stringify({ input: texts, model: this.model }),
+    });
+
+    if (res.status === 429) throw new AiRateLimitError('openai-embedding');
+    if (!res.ok) throw new AiProviderError(await res.text(), 'openai-embedding', res.status);
+
+    const data = await res.json() as { data: Array<{ embedding: number[] }> };
+    return data.data.map((d) => d.embedding);
+  }
+}

package/src/embedding/service.ts

@@ -0,0 +1,55 @@
+import { Injectable } from '../di/decorators';
+import { Inject } from '../di/decorators';
+import type { EmbeddingProvider, EmbeddingModuleOptions } from './types';
+import { EMBEDDING_OPTIONS_TOKEN } from './types';
+
+/**
+ * Embedding service — generates vector embeddings for text using the configured provider.
+ */
+@Injectable()
+export class EmbeddingService {
+  private readonly provider: EmbeddingProvider;
+  private readonly batchSize: number;
+
+  public constructor(
+    @Inject(EMBEDDING_OPTIONS_TOKEN) options: EmbeddingModuleOptions,
+  ) {
+    this.provider = new options.provider.provider(options.provider.config);
+    this.batchSize = options.batchSize ?? 100;
+  }
+
+  /**
+   * Generate an embedding vector for a single text
+   */
+  public async embed(text: string): Promise<number[]> {
+    return this.provider.embed(text);
+  }
+
+  /**
+   * Generate embedding vectors for multiple texts.
+   * Automatically batches requests to stay within provider limits.
+   */
+  public async embedBatch(texts: string[]): Promise<number[][]> {
+    const results: number[][] = [];
+    for (let i = 0; i < texts.length; i += this.batchSize) {
+      const batch = texts.slice(i, i + this.batchSize);
+      const embeddings = await this.provider.embedBatch(batch);
+      results.push(...embeddings);
+    }
+    return results;
+  }
+
+  /**
+   * Number of dimensions in embeddings produced by this provider
+   */
+  public get dimensions(): number {
+    return this.provider.dimensions;
+  }
+
+  /**
+   * Provider name
+   */
+  public get providerName(): string {
+    return this.provider.name;
+  }
+}

package/src/embedding/types.ts

@@ -0,0 +1,27 @@
+/**
+ * Abstract embedding provider interface
+ */
+export interface EmbeddingProvider {
+  /** Generate embedding vector for a single text */
+  embed(text: string): Promise<number[]>;
+  /** Generate embedding vectors for multiple texts (batch) */
+  embedBatch(texts: string[]): Promise<number[][]>;
+  /** Embedding dimensions */
+  readonly dimensions: number;
+  readonly name: string;
+}
+
+export interface EmbeddingProviderConfig<T = unknown> {
+  name: string;
+  provider: new (config: T) => EmbeddingProvider;
+  config: T;
+}
+
+export interface EmbeddingModuleOptions {
+  provider: EmbeddingProviderConfig;
+  /** Max texts per batch request (default: 100) */
+  batchSize?: number;
+}
+
+export const EMBEDDING_SERVICE_TOKEN = Symbol('@dangao/bun-server:embedding:service');
+export const EMBEDDING_OPTIONS_TOKEN = Symbol('@dangao/bun-server:embedding:options');

package/src/index.ts

@@ -562,3 +562,13 @@ export {
   type RegisteredListener,
 } from './events';
 
+// ── AI Modules (v2.0.0) ──────────────────────────────────────────────────────
+
+export * from './ai';
+export * from './conversation';
+export * from './prompt';
+export * from './embedding';
+export * from './vector-store';
+export * from './rag';
+export * from './mcp';
+export * from './ai-guard';

package/src/mcp/decorators.ts

@@ -0,0 +1,60 @@
+import type { McpToolDefinition, McpResourceDefinition } from './types';
+import { MCP_TOOL_METADATA_KEY, MCP_RESOURCE_METADATA_KEY } from './types';
+
+/**
+ * Mark a method as an MCP tool.
+ *
+ * @example
+ * ```typescript
+ * \@McpTool({
+ *   name: 'get_weather',
+ *   description: 'Get current weather for a city',
+ *   inputSchema: {
+ *     type: 'object',
+ *     properties: { city: { type: 'string' } },
+ *     required: ['city'],
+ *   },
+ * })
+ * public async getWeather({ city }: { city: string }) {
+ *   return { temperature: 22, city };
+ * }
+ * ```
+ */
+export function McpTool(definition: McpToolDefinition): MethodDecorator {
+  return (target, propertyKey) => {
+    Reflect.defineMetadata(MCP_TOOL_METADATA_KEY, definition, target, propertyKey);
+  };
+}
+
+/**
+ * Mark a method as an MCP resource provider.
+ *
+ * @example
+ * ```typescript
+ * \@McpResource({
+ *   uri: 'user://{id}',
+ *   name: 'User Profile',
+ *   mimeType: 'application/json',
+ * })
+ * public async getUserResource(\@McpParam('id') id: string) {
+ *   return this.userService.find(id);
+ * }
+ * ```
+ */
+export function McpResource(definition: McpResourceDefinition): MethodDecorator {
+  return (target, propertyKey) => {
+    Reflect.defineMetadata(MCP_RESOURCE_METADATA_KEY, definition, target, propertyKey);
+  };
+}
+
+/**
+ * Extract a named parameter from MCP tool input arguments.
+ */
+export function McpParam(name: string): ParameterDecorator {
+  return (target, propertyKey, parameterIndex) => {
+    const existing: Array<{ index: number; name: string }> =
+      Reflect.getMetadata('mcp:params', target, propertyKey!) ?? [];
+    existing.push({ index: parameterIndex, name });
+    Reflect.defineMetadata('mcp:params', existing, target, propertyKey!);
+  };
+}

package/src/mcp/index.ts

@@ -0,0 +1,5 @@
+export * from './types';
+export * from './decorators';
+export * from './registry';
+export * from './server';
+export * from './mcp-module';