@dangao/bun-server 1.12.0 → 2.0.0

package/src/prompt/service.ts

@@ -0,0 +1,93 @@
+import { Injectable } from '../di/decorators';
+import { Inject } from '../di/decorators';
+import type {
+  PromptStore,
+  PromptTemplate,
+  CreatePromptTemplateInput,
+  UpdatePromptTemplateInput,
+  PromptModuleOptions,
+} from './types';
+import { PROMPT_OPTIONS_TOKEN, renderTemplate } from './types';
+import { HttpException } from '../error/http-exception';
+
+/**
+ * Manages prompt templates: CRUD operations, versioning, and variable rendering.
+ */
+@Injectable()
+export class PromptService {
+  private readonly store: PromptStore;
+
+  public constructor(
+    @Inject(PROMPT_OPTIONS_TOKEN) options: PromptModuleOptions,
+  ) {
+    this.store = options.store!;
+  }
+
+  /**
+   * Get a template by ID
+   */
+  public async get(id: string): Promise<PromptTemplate> {
+    const template = await this.store.get(id);
+    if (!template) throw new HttpException(404, `Prompt template "${id}" not found`);
+    return template;
+  }
+
+  /**
+   * Get a specific version of a template
+   */
+  public async getVersion(id: string, version: number): Promise<PromptTemplate> {
+    const template = await this.store.getVersion(id, version);
+    if (!template) throw new HttpException(404, `Prompt template "${id}" version ${version} not found`);
+    return template;
+  }
+
+  /**
+   * List all templates
+   */
+  public async list(): Promise<PromptTemplate[]> {
+    return this.store.list();
+  }
+
+  /**
+   * Create a new template
+   */
+  public async create(input: CreatePromptTemplateInput): Promise<PromptTemplate> {
+    return this.store.create(input);
+  }
+
+  /**
+   * Update a template (creates a new version)
+   */
+  public async update(id: string, input: UpdatePromptTemplateInput): Promise<PromptTemplate> {
+    return this.store.update(id, input);
+  }
+
+  /**
+   * Delete a template
+   */
+  public async delete(id: string): Promise<boolean> {
+    return this.store.delete(id);
+  }
+
+  /**
+   * Render a template by replacing {{varName}} with provided values
+   *
+   * @example
+   * ```typescript
+   * const rendered = await promptService.render('greet-user', { name: 'Alice', app: 'MyApp' });
+   * // "Hello, Alice! Welcome to MyApp."
+   * ```
+   */
+  public async render(id: string, vars: Record<string, string>): Promise<string> {
+    const template = await this.get(id);
+    return renderTemplate(template.content, vars);
+  }
+
+  /**
+   * Render a specific version of a template
+   */
+  public async renderVersion(id: string, version: number, vars: Record<string, string>): Promise<string> {
+    const template = await this.getVersion(id, version);
+    return renderTemplate(template.content, vars);
+  }
+}

package/src/prompt/stores/file-store.ts

@@ -0,0 +1,135 @@
+import type {
+  PromptStore,
+  PromptTemplate,
+  CreatePromptTemplateInput,
+  UpdatePromptTemplateInput,
+} from '../types';
+import { extractVariables } from '../types';
+import { InMemoryPromptStore } from './memory-store';
+
+export interface FilePromptStoreConfig {
+  /** Directory containing JSON prompt files (default: './.prompts') */
+  promptsDir?: string;
+}
+
+/**
+ * File-backed prompt store — loads templates from JSON files at startup
+ * and persists changes back to disk.
+ *
+ * Each template is stored as a separate JSON file: `{promptsDir}/{id}.json`
+ *
+ * File format:
+ * ```json
+ * {
+ *   "id": "greet-user",
+ *   "name": "Greet User",
+ *   "content": "Hello, {{name}}! Welcome to {{app}}.",
+ *   "description": "Greeting template"
+ * }
+ * ```
+ */
+export class FilePromptStore implements PromptStore {
+  private readonly promptsDir: string;
+  private readonly memory: InMemoryPromptStore;
+  private loaded = false;
+
+  public constructor(config: FilePromptStoreConfig = {}) {
+    this.promptsDir = config.promptsDir ?? './.prompts';
+    this.memory = new InMemoryPromptStore();
+  }
+
+  public async get(id: string): Promise<PromptTemplate | null> {
+    await this.ensureLoaded();
+    return this.memory.get(id);
+  }
+
+  public async getVersion(id: string, version: number): Promise<PromptTemplate | null> {
+    await this.ensureLoaded();
+    return this.memory.getVersion(id, version);
+  }
+
+  public async list(): Promise<PromptTemplate[]> {
+    await this.ensureLoaded();
+    return this.memory.list();
+  }
+
+  public async create(input: CreatePromptTemplateInput): Promise<PromptTemplate> {
+    await this.ensureLoaded();
+    const template = await this.memory.create(input);
+    await this.writeFile(template);
+    return template;
+  }
+
+  public async update(id: string, input: UpdatePromptTemplateInput): Promise<PromptTemplate> {
+    await this.ensureLoaded();
+    const template = await this.memory.update(id, input);
+    await this.writeFile(template);
+    return template;
+  }
+
+  public async delete(id: string): Promise<boolean> {
+    await this.ensureLoaded();
+    const deleted = await this.memory.delete(id);
+    if (deleted) {
+      try {
+        const path = `${this.promptsDir}/${id}.json`;
+        await Bun.file(path).exists() && Bun.write(path, ''); // Soft delete (empty file)
+      } catch {
+        // ignore
+      }
+    }
+    return deleted;
+  }
+
+  private async ensureLoaded(): Promise<void> {
+    if (this.loaded) return;
+    this.loaded = true;
+
+    try {
+      const glob = new Bun.Glob('*.json');
+      const files = Array.from(glob.scanSync(this.promptsDir));
+
+      for (const file of files) {
+        try {
+          const content = await Bun.file(`${this.promptsDir}/${file}`).text();
+          if (!content.trim()) continue;
+
+          const data = JSON.parse(content) as {
+            id?: string;
+            name: string;
+            content: string;
+            description?: string;
+          };
+
+          const id = data.id ?? file.replace(/\.json$/, '');
+          await this.memory.create({ id, ...data }).catch(() => {
+            // Template already exists — skip
+          });
+        } catch {
+          // Skip malformed files
+        }
+      }
+    } catch {
+      // Directory doesn't exist — start empty
+    }
+  }
+
+  private async writeFile(template: PromptTemplate): Promise<void> {
+    try {
+      const content = JSON.stringify(
+        {
+          id: template.id,
+          name: template.name,
+          content: template.content,
+          description: template.description,
+          variables: extractVariables(template.content),
+        },
+        null,
+        2,
+      );
+      await Bun.write(`${this.promptsDir}/${template.id}.json`, content);
+    } catch {
+      // Ignore write errors (e.g., read-only filesystem)
+    }
+  }
+}

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

@@ -0,0 +1,82 @@
+import type {
+  PromptStore,
+  PromptTemplate,
+  CreatePromptTemplateInput,
+  UpdatePromptTemplateInput,
+} from '../types';
+import { extractVariables } from '../types';
+
+/**
+ * In-memory prompt store. Supports versioning via a separate history map.
+ */
+export class InMemoryPromptStore implements PromptStore {
+  private readonly templates = new Map<string, PromptTemplate>();
+  /** id → version → template snapshot */
+  private readonly history = new Map<string, Map<number, PromptTemplate>>();
+
+  public async get(id: string): Promise<PromptTemplate | null> {
+    return this.templates.get(id) ?? null;
+  }
+
+  public async getVersion(id: string, version: number): Promise<PromptTemplate | null> {
+    return this.history.get(id)?.get(version) ?? null;
+  }
+
+  public async list(): Promise<PromptTemplate[]> {
+    return Array.from(this.templates.values());
+  }
+
+  public async create(input: CreatePromptTemplateInput): Promise<PromptTemplate> {
+    const id = input.id ?? crypto.randomUUID();
+    if (this.templates.has(id)) {
+      throw new Error(`Prompt template "${id}" already exists`);
+    }
+    const now = new Date();
+    const template: PromptTemplate = {
+      id,
+      name: input.name,
+      content: input.content,
+      version: 1,
+      variables: extractVariables(input.content),
+      description: input.description,
+      createdAt: now,
+      updatedAt: now,
+    };
+    this.templates.set(id, template);
+    this.saveVersion(template);
+    return { ...template };
+  }
+
+  public async update(id: string, input: UpdatePromptTemplateInput): Promise<PromptTemplate> {
+    const existing = this.templates.get(id);
+    if (!existing) throw new Error(`Prompt template "${id}" not found`);
+
+    const now = new Date();
+    const content = input.content ?? existing.content;
+    const updated: PromptTemplate = {
+      ...existing,
+      name: input.name ?? existing.name,
+      content,
+      description: input.description ?? existing.description,
+      version: existing.version + 1,
+      variables: extractVariables(content),
+      updatedAt: now,
+    };
+    this.templates.set(id, updated);
+    this.saveVersion(updated);
+    return { ...updated };
+  }
+
+  public async delete(id: string): Promise<boolean> {
+    const existed = this.templates.delete(id);
+    this.history.delete(id);
+    return existed;
+  }
+
+  private saveVersion(template: PromptTemplate): void {
+    if (!this.history.has(template.id)) {
+      this.history.set(template.id, new Map());
+    }
+    this.history.get(template.id)!.set(template.version, { ...template });
+  }
+}

package/src/prompt/types.ts

@@ -0,0 +1,84 @@
+/**
+ * A versioned prompt template with variable interpolation
+ */
+export interface PromptTemplate {
+  id: string;
+  name: string;
+  /** Template content with {{variable}} placeholders */
+  content: string;
+  /** Current version number (starts at 1, increments on each update) */
+  version: number;
+  /** Declared variable names (auto-extracted from content) */
+  variables: string[];
+  /** Optional description */
+  description?: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/**
+ * Input for creating a prompt template
+ */
+export interface CreatePromptTemplateInput {
+  id?: string;
+  name: string;
+  content: string;
+  description?: string;
+}
+
+/**
+ * Input for updating a prompt template (creates new version)
+ */
+export interface UpdatePromptTemplateInput {
+  name?: string;
+  content?: string;
+  description?: string;
+}
+
+/**
+ * Abstract prompt store interface
+ */
+export interface PromptStore {
+  get(id: string): Promise<PromptTemplate | null>;
+  getVersion(id: string, version: number): Promise<PromptTemplate | null>;
+  list(): Promise<PromptTemplate[]>;
+  create(input: CreatePromptTemplateInput): Promise<PromptTemplate>;
+  update(id: string, input: UpdatePromptTemplateInput): Promise<PromptTemplate>;
+  delete(id: string): Promise<boolean>;
+}
+
+/**
+ * PromptModule configuration
+ */
+export interface PromptModuleOptions {
+  store?: PromptStore;
+  /**
+   * Preload templates on module init
+   * (only used by FilePromptStore, which loads from promptsDir)
+   */
+  promptsDir?: string;
+}
+
+export const PROMPT_SERVICE_TOKEN = Symbol('@dangao/bun-server:prompt:service');
+export const PROMPT_OPTIONS_TOKEN = Symbol('@dangao/bun-server:prompt:options');
+
+/**
+ * Extract variable names from template content
+ * Matches {{varName}} patterns
+ */
+export function extractVariables(content: string): string[] {
+  const regex = /\{\{(\w+)\}\}/g;
+  const vars = new Set<string>();
+  let match: RegExpExecArray | null;
+  while ((match = regex.exec(content)) !== null) {
+    vars.add(match[1]!);
+  }
+  return Array.from(vars);
+}
+
+/**
+ * Render a template by replacing {{varName}} with provided values
+ */
+export function renderTemplate(content: string, vars: Record<string, string>): string {
+  return content.replace(/\{\{(\w+)\}\}/g, (_, key: string) => vars[key] ?? `{{${key}}}`);
+}

package/src/rag/chunkers/markdown-chunker.ts

@@ -0,0 +1,40 @@
+import type { DocumentChunker, DocumentChunk } from '../types';
+
+/**
+ * Splits Markdown text into semantic chunks by heading boundaries.
+ * Falls back to text chunking for sections that are too large.
+ */
+export class MarkdownChunker implements DocumentChunker {
+  private readonly maxChunkSize: number;
+
+  public constructor(maxChunkSize = 1024) {
+    this.maxChunkSize = maxChunkSize;
+  }
+
+  public chunk(text: string): DocumentChunk[] {
+    const chunks: DocumentChunk[] = [];
+    // Split on headings (## or ###)
+    const sections = text.split(/(?=^#{1,3} )/m).filter((s) => s.trim());
+
+    for (const section of sections) {
+      if (section.length <= this.maxChunkSize) {
+        chunks.push({ content: section.trim() });
+      } else {
+        // Split large sections into paragraphs
+        const paragraphs = section.split(/\n\n+/).filter((p) => p.trim());
+        let current = '';
+        for (const para of paragraphs) {
+          if ((current + '\n\n' + para).length > this.maxChunkSize && current) {
+            chunks.push({ content: current.trim() });
+            current = para;
+          } else {
+            current = current ? current + '\n\n' + para : para;
+          }
+        }
+        if (current.trim()) chunks.push({ content: current.trim() });
+      }
+    }
+
+    return chunks.length > 0 ? chunks : [{ content: text.trim() }];
+  }
+}

package/src/rag/chunkers/text-chunker.ts

@@ -0,0 +1,30 @@
+import type { DocumentChunker, DocumentChunk } from '../types';
+
+/**
+ * Splits plain text into overlapping chunks of fixed character size.
+ */
+export class TextChunker implements DocumentChunker {
+  private readonly chunkSize: number;
+  private readonly chunkOverlap: number;
+
+  public constructor(chunkSize = 512, chunkOverlap = 50) {
+    this.chunkSize = chunkSize;
+    this.chunkOverlap = chunkOverlap;
+  }
+
+  public chunk(text: string): DocumentChunk[] {
+    const chunks: DocumentChunk[] = [];
+    const step = this.chunkSize - this.chunkOverlap;
+
+    for (let start = 0; start < text.length; start += step) {
+      const end = Math.min(start + this.chunkSize, text.length);
+      const content = text.slice(start, end).trim();
+      if (content.length > 0) {
+        chunks.push({ content });
+      }
+      if (end >= text.length) break;
+    }
+
+    return chunks;
+  }
+}

package/src/rag/decorators.ts

@@ -0,0 +1,26 @@
+/**
+ * Metadata key for @Rag() decorator
+ */
+export const RAG_METADATA_KEY = '@dangao/bun-server:rag:collection';
+
+/**
+ * Mark a controller method to auto-retrieve RAG context before execution.
+ * The retrieved context is available via `@Inject(RAG_SERVICE_TOKEN)` in the service layer.
+ *
+ * @param collection - VectorStore collection to search (uses default if omitted)
+ *
+ * @example
+ * ```typescript
+ * \@POST('/ask')
+ * \@Rag({ collection: 'product-docs' })
+ * public async ask(\@Body() body: { question: string }) {
+ *   // RAG context is automatically fetched before this method
+ *   // Access via RagService.retrieve() in your service
+ * }
+ * ```
+ */
+export function Rag(options: { collection?: string } = {}): MethodDecorator {
+  return (target, propertyKey) => {
+    Reflect.defineMetadata(RAG_METADATA_KEY, options, target, propertyKey);
+  };
+}

package/src/rag/index.ts

@@ -0,0 +1,6 @@
+export * from './types';
+export * from './service';
+export * from './decorators';
+export * from './rag-module';
+export * from './chunkers/text-chunker';
+export * from './chunkers/markdown-chunker';

package/src/rag/rag-module.ts

@@ -0,0 +1,78 @@
+import { Module, MODULE_METADATA_KEY } from '../di/module';
+import type { ModuleProvider } from '../di/module';
+import type { Container } from '../di/container';
+import { RagService } from './service';
+import { RAG_SERVICE_TOKEN, RAG_OPTIONS_TOKEN, type RagModuleOptions } from './types';
+import { EMBEDDING_SERVICE_TOKEN } from '../embedding/types';
+import { VECTOR_STORE_TOKEN } from '../vector-store/types';
+import { EmbeddingModule } from '../embedding/embedding-module';
+import { VectorStoreModule } from '../vector-store/vector-store-module';
+
+@Module({
+  imports: [EmbeddingModule, VectorStoreModule],
+  providers: [],
+})
+export class RagModule {
+  /**
+   * Configure the RAG module.
+   *
+   * **Requires** `EmbeddingModule` and `VectorStoreModule` to be imported first.
+   *
+   * @example
+   * ```typescript
+   * EmbeddingModule.forRoot({ provider: { ... } });
+   * VectorStoreModule.forRoot({});
+   * RagModule.forRoot({ collection: 'docs', chunkSize: 512, topK: 5 });
+   *
+   * \@Module({
+   *   imports: [EmbeddingModule, VectorStoreModule, RagModule],
+   * })
+   * class AppModule {}
+   * ```
+   */
+  public static forRoot(options: RagModuleOptions = {}): typeof RagModule {
+    const resolvedOptions: RagModuleOptions = {
+      collection: 'rag',
+      chunkSize: 512,
+      chunkOverlap: 50,
+      topK: 5,
+      minScore: 0.5,
+      ...options,
+    };
+
+    const providers: ModuleProvider[] = [
+      { provide: RAG_OPTIONS_TOKEN, useValue: resolvedOptions },
+      {
+        provide: RAG_SERVICE_TOKEN,
+        useFactory: (container: Container) => {
+          const embeddingService = container.resolve(EMBEDDING_SERVICE_TOKEN);
+          const vectorStore = container.resolve(VECTOR_STORE_TOKEN);
+          return new RagService(resolvedOptions, embeddingService as never, vectorStore as never);
+        },
+      },
+      RagService,
+    ];
+
+    const existing = Reflect.getMetadata(MODULE_METADATA_KEY, RagModule) || {};
+    Reflect.defineMetadata(MODULE_METADATA_KEY, {
+      ...existing,
+      imports: [
+        ...(existing.imports || []),
+        EmbeddingModule,
+        VectorStoreModule,
+      ],
+      providers: [...(existing.providers || []), ...providers],
+      exports: [
+        ...(existing.exports || []),
+        RAG_SERVICE_TOKEN,
+        RagService,
+      ],
+    }, RagModule);
+
+    return RagModule;
+  }
+
+  public static reset(): void {
+    Reflect.deleteMetadata(MODULE_METADATA_KEY, RagModule);
+  }
+}