@geekmidas/telescope 0.0.1

package/src/storage/memory.ts

@@ -0,0 +1,168 @@
+import type {
+  ExceptionEntry,
+  LogEntry,
+  QueryOptions,
+  RequestEntry,
+  TelescopeStats,
+  TelescopeStorage,
+} from '../types';
+
+export interface InMemoryStorageOptions {
+  /** Maximum number of entries to keep per type (default: 1000) */
+  maxEntries?: number;
+}
+
+/**
+ * In-memory storage for Telescope data.
+ * Ideal for development and testing.
+ * Data is lost when the process restarts.
+ */
+export class InMemoryStorage implements TelescopeStorage {
+  private requests: RequestEntry[] = [];
+  private exceptions: ExceptionEntry[] = [];
+  private logs: LogEntry[] = [];
+  private maxEntries: number;
+
+  constructor(options?: InMemoryStorageOptions) {
+    this.maxEntries = options?.maxEntries ?? 1000;
+  }
+
+  // Requests
+
+  async saveRequest(entry: RequestEntry): Promise<void> {
+    this.requests.unshift(entry);
+    this.enforceLimit('requests');
+  }
+
+  async saveRequests(entries: RequestEntry[]): Promise<void> {
+    this.requests.unshift(...entries);
+    this.enforceLimit('requests');
+  }
+
+  async getRequests(options?: QueryOptions): Promise<RequestEntry[]> {
+    return this.filterEntries(this.requests, options);
+  }
+
+  async getRequest(id: string): Promise<RequestEntry | null> {
+    return this.requests.find((r) => r.id === id) ?? null;
+  }
+
+  // Exceptions
+
+  async saveException(entry: ExceptionEntry): Promise<void> {
+    this.exceptions.unshift(entry);
+    this.enforceLimit('exceptions');
+  }
+
+  async saveExceptions(entries: ExceptionEntry[]): Promise<void> {
+    this.exceptions.unshift(...entries);
+    this.enforceLimit('exceptions');
+  }
+
+  async getExceptions(options?: QueryOptions): Promise<ExceptionEntry[]> {
+    return this.filterEntries(this.exceptions, options);
+  }
+
+  async getException(id: string): Promise<ExceptionEntry | null> {
+    return this.exceptions.find((e) => e.id === id) ?? null;
+  }
+
+  // Logs
+
+  async saveLog(entry: LogEntry): Promise<void> {
+    this.logs.unshift(entry);
+    this.enforceLimit('logs');
+  }
+
+  async saveLogs(entries: LogEntry[]): Promise<void> {
+    this.logs.unshift(...entries);
+    this.enforceLimit('logs');
+  }
+
+  async getLogs(options?: QueryOptions): Promise<LogEntry[]> {
+    return this.filterEntries(this.logs, options);
+  }
+
+  // Cleanup
+
+  async prune(olderThan: Date): Promise<number> {
+    const beforeCount =
+      this.requests.length + this.exceptions.length + this.logs.length;
+
+    this.requests = this.requests.filter((r) => r.timestamp >= olderThan);
+    this.exceptions = this.exceptions.filter((e) => e.timestamp >= olderThan);
+    this.logs = this.logs.filter((l) => l.timestamp >= olderThan);
+
+    const afterCount =
+      this.requests.length + this.exceptions.length + this.logs.length;
+    return beforeCount - afterCount;
+  }
+
+  // Stats
+
+  async getStats(): Promise<TelescopeStats> {
+    const allTimestamps = [
+      ...this.requests.map((r) => r.timestamp),
+      ...this.exceptions.map((e) => e.timestamp),
+      ...this.logs.map((l) => l.timestamp),
+    ].sort((a, b) => a.getTime() - b.getTime());
+
+    return {
+      requests: this.requests.length,
+      exceptions: this.exceptions.length,
+      logs: this.logs.length,
+      oldestEntry: allTimestamps[0],
+      newestEntry: allTimestamps[allTimestamps.length - 1],
+    };
+  }
+
+  // Clear all data (useful for testing)
+
+  clear(): void {
+    this.requests = [];
+    this.exceptions = [];
+    this.logs = [];
+  }
+
+  // Private helpers
+
+  private enforceLimit(type: 'requests' | 'exceptions' | 'logs'): void {
+    if (this[type].length > this.maxEntries) {
+      this[type] = this[type].slice(0, this.maxEntries);
+    }
+  }
+
+  private filterEntries<T extends { timestamp: Date; tags?: string[] }>(
+    entries: T[],
+    options?: QueryOptions,
+  ): T[] {
+    let result = entries;
+
+    if (options?.after) {
+      result = result.filter((e) => e.timestamp >= options.after!);
+    }
+
+    if (options?.before) {
+      result = result.filter((e) => e.timestamp <= options.before!);
+    }
+
+    if (options?.tags && options.tags.length > 0) {
+      result = result.filter(
+        (e) => e.tags && options.tags!.some((t) => e.tags!.includes(t)),
+      );
+    }
+
+    if (options?.search) {
+      const searchLower = options.search.toLowerCase();
+      result = result.filter((e) => {
+        const str = JSON.stringify(e).toLowerCase();
+        return str.includes(searchLower);
+      });
+    }
+
+    const offset = options?.offset ?? 0;
+    const limit = options?.limit ?? 50;
+
+    return result.slice(offset, offset + limit);
+  }
+}

package/src/types.ts

@@ -0,0 +1,188 @@
+/**
+ * Stack frame from a parsed error stack trace
+ */
+export interface StackFrame {
+  file: string;
+  line: number;
+  column: number;
+  function: string;
+  /** Whether this frame is from application code (vs node_modules) */
+  isApp: boolean;
+}
+
+/**
+ * Source code context around an error
+ */
+export interface SourceContext {
+  file: string;
+  line: number;
+  column: number;
+  lines: Array<{ num: number; code: string; highlight: boolean }>;
+}
+
+/**
+ * Recorded HTTP request entry
+ */
+export interface RequestEntry {
+  id: string;
+  method: string;
+  path: string;
+  url: string;
+  headers: Record<string, string>;
+  body?: unknown;
+  query?: Record<string, string>;
+  status: number;
+  responseHeaders: Record<string, string>;
+  responseBody?: unknown;
+  duration: number;
+  timestamp: Date;
+  ip?: string;
+  userId?: string;
+  tags?: string[];
+}
+
+/**
+ * Recorded exception entry
+ */
+export interface ExceptionEntry {
+  id: string;
+  name: string;
+  message: string;
+  stack: StackFrame[];
+  source?: SourceContext;
+  requestId?: string;
+  timestamp: Date;
+  handled: boolean;
+  tags?: string[];
+}
+
+/**
+ * Recorded log entry
+ */
+export interface LogEntry {
+  id: string;
+  level: 'debug' | 'info' | 'warn' | 'error';
+  message: string;
+  context?: Record<string, unknown>;
+  requestId?: string;
+  timestamp: Date;
+}
+
+/**
+ * Query options for retrieving entries
+ */
+export interface QueryOptions {
+  limit?: number;
+  offset?: number;
+  before?: Date;
+  after?: Date;
+  search?: string;
+  tags?: string[];
+}
+
+/**
+ * Storage interface for Telescope data
+ * Implementations can use memory, database, or any other backend
+ */
+export interface TelescopeStorage {
+  // Requests
+  saveRequest(entry: RequestEntry): Promise<void>;
+  saveRequests?(entries: RequestEntry[]): Promise<void>;
+  getRequests(options?: QueryOptions): Promise<RequestEntry[]>;
+  getRequest(id: string): Promise<RequestEntry | null>;
+
+  // Exceptions
+  saveException(entry: ExceptionEntry): Promise<void>;
+  saveExceptions?(entries: ExceptionEntry[]): Promise<void>;
+  getExceptions(options?: QueryOptions): Promise<ExceptionEntry[]>;
+  getException(id: string): Promise<ExceptionEntry | null>;
+
+  // Logs
+  saveLog(entry: LogEntry): Promise<void>;
+  saveLogs?(entries: LogEntry[]): Promise<void>;
+  getLogs(options?: QueryOptions): Promise<LogEntry[]>;
+
+  // Cleanup
+  prune(olderThan: Date): Promise<number>;
+
+  // Stats
+  getStats(): Promise<TelescopeStats>;
+}
+
+/**
+ * Statistics about stored entries
+ */
+export interface TelescopeStats {
+  requests: number;
+  exceptions: number;
+  logs: number;
+  oldestEntry?: Date;
+  newestEntry?: Date;
+}
+
+/**
+ * Configuration options for Telescope
+ */
+export interface TelescopeOptions {
+  /** Storage backend for persisting data */
+  storage: TelescopeStorage;
+  /** Whether telescope is enabled (default: true) */
+  enabled?: boolean;
+  /** Dashboard path (default: '/__telescope') */
+  path?: string;
+  /** Whether to record request/response bodies (default: true) */
+  recordBody?: boolean;
+  /** Maximum body size to record in bytes (default: 64KB) */
+  maxBodySize?: number;
+  /** URL patterns to ignore (default: []) */
+  ignorePatterns?: string[];
+  /** Auto-prune entries older than this many hours (default: undefined - no auto-prune) */
+  pruneAfterHours?: number;
+}
+
+/**
+ * Normalized telescope options with defaults applied
+ */
+export interface NormalizedTelescopeOptions {
+  storage: TelescopeStorage;
+  enabled: boolean;
+  path: string;
+  recordBody: boolean;
+  maxBodySize: number;
+  ignorePatterns: string[];
+  pruneAfterHours?: number;
+}
+
+/**
+ * WebSocket event types
+ */
+export type TelescopeEventType =
+  | 'request'
+  | 'exception'
+  | 'log'
+  | 'stats'
+  | 'connected';
+
+/**
+ * WebSocket event payload
+ */
+export interface TelescopeEvent<T = unknown> {
+  type: TelescopeEventType;
+  payload: T;
+  timestamp: number;
+}
+
+/**
+ * Context stored during request processing
+ */
+export interface RequestContext {
+  id: string;
+  startTime: number;
+  method: string;
+  path: string;
+  url: string;
+  headers: Record<string, string>;
+  query: Record<string, string>;
+  body?: unknown;
+  ip?: string;
+}