@geekmidas/telescope 0.0.1

package/src/logger/__tests__/pino.spec.ts

@@ -0,0 +1,217 @@
+import pino from 'pino';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { Telescope } from '../../Telescope';
+import { InMemoryStorage } from '../../storage/memory';
+import { createPinoDestination, createPinoTransport } from '../pino';
+
+describe('Pino Transport', () => {
+  let telescope: Telescope;
+  let storage: InMemoryStorage;
+
+  beforeEach(() => {
+    storage = new InMemoryStorage();
+    telescope = new Telescope({ storage });
+  });
+
+  afterEach(() => {
+    telescope.destroy();
+  });
+
+  // Helper to create transport with fast flush for tests
+  const createTestTransport = (
+    opts: Parameters<typeof createPinoTransport>[0],
+  ) => createPinoTransport({ flushIntervalMs: 50, ...opts });
+
+  describe('createPinoTransport', () => {
+    it('should parse and forward JSON log lines', async () => {
+      const transport = createTestTransport({ telescope });
+      const logger = pino({ level: 'debug' }, transport);
+
+      logger.info({ userId: '123' }, 'Test message');
+
+      // Wait for flush interval
+      await new Promise((r) => setTimeout(r, 100));
+
+      const logs = await telescope.getLogs();
+      expect(logs).toHaveLength(1);
+      expect(logs[0].level).toBe('info');
+      expect(logs[0].message).toBe('Test message');
+      expect(logs[0].context).toMatchObject({ userId: '123' });
+    });
+
+    it('should map Pino log levels correctly', async () => {
+      const transport = createTestTransport({ telescope });
+      const logger = pino({ level: 'trace' }, transport);
+
+      logger.trace('Trace message');
+      logger.debug('Debug message');
+      logger.info('Info message');
+      logger.warn('Warn message');
+      logger.error('Error message');
+      logger.fatal('Fatal message');
+
+      await new Promise((r) => setTimeout(r, 150));
+
+      const logs = await telescope.getLogs();
+      expect(logs).toHaveLength(6);
+
+      const logLevels = logs.map((l) => l.level);
+      expect(logLevels.filter((l) => l === 'debug')).toHaveLength(2); // trace + debug
+      expect(logLevels).toContain('info');
+      expect(logLevels).toContain('warn');
+      expect(logLevels.filter((l) => l === 'error')).toHaveLength(2); // error + fatal
+    });
+
+    it('should extract requestId from log data', async () => {
+      const transport = createTestTransport({ telescope });
+      const logger = pino({ level: 'debug' }, transport);
+
+      logger.info({ requestId: 'req-abc123' }, 'Request log');
+
+      await new Promise((r) => setTimeout(r, 100));
+
+      const logs = await telescope.getLogs();
+      expect(logs[0].requestId).toBe('req-abc123');
+      // requestId should not be in context
+      expect(logs[0].context).not.toHaveProperty('requestId');
+    });
+
+    it('should use static requestId option', async () => {
+      const transport = createTestTransport({
+        telescope,
+        requestId: 'static-req-id',
+      });
+      const logger = pino({ level: 'debug' }, transport);
+
+      logger.info('Log with static ID');
+
+      await new Promise((r) => setTimeout(r, 100));
+
+      const logs = await telescope.getLogs();
+      expect(logs[0].requestId).toBe('static-req-id');
+    });
+
+    it('should use requestId function option', async () => {
+      const transport = createTestTransport({
+        telescope,
+        requestId: (data) => data.traceId as string | undefined,
+      });
+      const logger = pino({ level: 'debug' }, transport);
+
+      logger.info({ traceId: 'trace-xyz' }, 'Log with extracted ID');
+
+      await new Promise((r) => setTimeout(r, 100));
+
+      const logs = await telescope.getLogs();
+      expect(logs[0].requestId).toBe('trace-xyz');
+    });
+
+    it('should handle empty message', async () => {
+      const transport = createTestTransport({ telescope });
+      const logger = pino({ level: 'debug' }, transport);
+
+      logger.info({ data: 'some data' });
+
+      await new Promise((r) => setTimeout(r, 100));
+
+      const logs = await telescope.getLogs();
+      expect(logs[0].message).toBe('');
+    });
+
+    it('should strip Pino metadata from context', async () => {
+      const transport = createTestTransport({ telescope });
+      const logger = pino({ level: 'debug' }, transport);
+
+      logger.info({ customField: 'value' }, 'Test');
+
+      await new Promise((r) => setTimeout(r, 100));
+
+      const logs = await telescope.getLogs();
+      const context = logs[0].context;
+
+      expect(context).not.toHaveProperty('level');
+      expect(context).not.toHaveProperty('msg');
+      expect(context).not.toHaveProperty('time');
+      expect(context).not.toHaveProperty('pid');
+      expect(context).not.toHaveProperty('hostname');
+      expect(context).toMatchObject({ customField: 'value' });
+    });
+
+    it('should return a writable stream', () => {
+      const transport = createPinoTransport({ telescope });
+
+      expect(typeof transport.write).toBe('function');
+      expect(typeof transport.end).toBe('function');
+    });
+
+    it('should batch logs and flush at batchSize', async () => {
+      const transport = createPinoTransport({
+        telescope,
+        batchSize: 3,
+        flushIntervalMs: 5000, // Long interval to test batch size trigger
+      });
+      const logger = pino({ level: 'debug' }, transport);
+
+      // Write 2 logs - should not flush yet
+      logger.info('Log 1');
+      logger.info('Log 2');
+
+      await new Promise((r) => setTimeout(r, 50));
+      let logs = await telescope.getLogs();
+      expect(logs).toHaveLength(0); // Not flushed yet
+
+      // Write 3rd log - should trigger flush
+      logger.info('Log 3');
+
+      await new Promise((r) => setTimeout(r, 100));
+      logs = await telescope.getLogs();
+      expect(logs).toHaveLength(3);
+    });
+
+    it('should flush on close', async () => {
+      const transport = createPinoTransport({
+        telescope,
+        batchSize: 100,
+        flushIntervalMs: 10000, // Long interval
+      });
+      const logger = pino({ level: 'debug' }, transport);
+
+      logger.info('Will be flushed on close');
+
+      // End the stream to trigger close
+      transport.end();
+
+      await new Promise((r) => setTimeout(r, 100));
+
+      const logs = await telescope.getLogs();
+      expect(logs).toHaveLength(1);
+      expect(logs[0].message).toBe('Will be flushed on close');
+    });
+  });
+
+  describe('createPinoDestination', () => {
+    it('should be an alias for createPinoTransport', () => {
+      const transport = createPinoTransport({ telescope });
+      const destination = createPinoDestination({ telescope });
+
+      expect(typeof transport.write).toBe('function');
+      expect(typeof destination.write).toBe('function');
+    });
+
+    it('should work the same as createPinoTransport', async () => {
+      const destination = createPinoDestination({
+        telescope,
+        flushIntervalMs: 50,
+      });
+      const logger = pino({ level: 'debug' }, destination);
+
+      logger.info('Destination test');
+
+      await new Promise((r) => setTimeout(r, 100));
+
+      const logs = await telescope.getLogs();
+      expect(logs).toHaveLength(1);
+      expect(logs[0].message).toBe('Destination test');
+    });
+  });
+});

package/src/logger/console.ts

@@ -0,0 +1,230 @@
+import type { Telescope } from '../Telescope';
+
+/**
+ * Logger interface matching @geekmidas/logger
+ */
+export interface Logger {
+  debug: LogFn;
+  info: LogFn;
+  warn: LogFn;
+  error: LogFn;
+  fatal: LogFn;
+  trace: LogFn;
+  child: (obj: object) => Logger;
+}
+
+export type LogFn = {
+  <T extends object>(obj: T, msg?: string, ...args: any[]): void;
+  (msg: string): void;
+};
+
+export interface TelescopeLoggerOptions {
+  /**
+   * The Telescope instance to send logs to
+   */
+  telescope: Telescope;
+  /**
+   * Optional underlying logger to also forward logs to.
+   * If not provided, logs will only go to Telescope.
+   */
+  logger?: Logger;
+  /**
+   * Request ID to associate logs with a specific request.
+   */
+  requestId?: string;
+  /**
+   * Initial context data to include in all log messages
+   */
+  context?: Record<string, unknown>;
+}
+
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+/**
+ * A logger that sends logs to both Telescope and an optional underlying logger.
+ * Implements the Logger interface from @geekmidas/logger.
+ *
+ * @example
+ * ```typescript
+ * import { Telescope, InMemoryStorage } from '@geekmidas/telescope';
+ * import { TelescopeLogger } from '@geekmidas/telescope/logger/console';
+ * import { ConsoleLogger } from '@geekmidas/logger/console';
+ *
+ * const telescope = new Telescope({ storage: new InMemoryStorage() });
+ *
+ * // With underlying logger (logs to both console and Telescope)
+ * const logger = new TelescopeLogger({
+ *   telescope,
+ *   logger: new ConsoleLogger({ app: 'myApp' }),
+ * });
+ *
+ * // Without underlying logger (logs only to Telescope)
+ * const telescopeOnly = new TelescopeLogger({ telescope });
+ *
+ * // Usage
+ * logger.info({ userId: '123' }, 'User logged in');
+ * logger.error({ error: 'Something failed' }, 'Operation failed');
+ * ```
+ */
+export class TelescopeLogger implements Logger {
+  private telescope: Telescope;
+  private logger?: Logger;
+  private requestId?: string;
+  private context: Record<string, unknown>;
+
+  constructor(options: TelescopeLoggerOptions) {
+    this.telescope = options.telescope;
+    this.logger = options.logger;
+    this.requestId = options.requestId;
+    this.context = options.context ?? {};
+  }
+
+  private createLogFn(level: LogLevel): LogFn {
+    const fn = <T extends object>(
+      objOrMsg: T | string,
+      msg?: string,
+      ...args: any[]
+    ): void => {
+      let context: Record<string, unknown>;
+      let message: string;
+
+      if (typeof objOrMsg === 'string') {
+        context = { ...this.context };
+        message = objOrMsg;
+      } else {
+        context = { ...this.context, ...objOrMsg };
+        message = msg ?? '';
+      }
+
+      // Forward to underlying logger if present
+      if (this.logger) {
+        if (typeof objOrMsg === 'string') {
+          this.logger[level](objOrMsg);
+        } else {
+          this.logger[level](objOrMsg as any, msg, ...args);
+        }
+      }
+
+      // Send to Telescope (fire and forget)
+      this.telescope[level](message, context, this.requestId).catch(() => {});
+    };
+
+    return fn as LogFn;
+  }
+
+  debug: LogFn = this.createLogFn('debug');
+  info: LogFn = this.createLogFn('info');
+  warn: LogFn = this.createLogFn('warn');
+  error: LogFn = this.createLogFn('error');
+
+  // Map fatal and trace to error and debug for Telescope
+  fatal: LogFn = ((
+    objOrMsg: object | string,
+    msg?: string,
+    ...args: any[]
+  ): void => {
+    // Forward to underlying logger if present
+    if (this.logger) {
+      if (typeof objOrMsg === 'string') {
+        this.logger.fatal(objOrMsg);
+      } else {
+        this.logger.fatal(objOrMsg as any, msg, ...args);
+      }
+    }
+
+    // Send to Telescope as error level
+    let context: Record<string, unknown>;
+    let message: string;
+
+    if (typeof objOrMsg === 'string') {
+      context = { ...this.context, level: 'fatal' };
+      message = objOrMsg;
+    } else {
+      context = { ...this.context, ...objOrMsg, level: 'fatal' };
+      message = msg ?? '';
+    }
+
+    this.telescope.error(message, context, this.requestId).catch(() => {});
+  }) as LogFn;
+
+  trace: LogFn = ((
+    objOrMsg: object | string,
+    msg?: string,
+    ...args: any[]
+  ): void => {
+    // Forward to underlying logger if present
+    if (this.logger) {
+      if (typeof objOrMsg === 'string') {
+        this.logger.trace(objOrMsg);
+      } else {
+        this.logger.trace(objOrMsg as any, msg, ...args);
+      }
+    }
+
+    // Send to Telescope as debug level
+    let context: Record<string, unknown>;
+    let message: string;
+
+    if (typeof objOrMsg === 'string') {
+      context = { ...this.context, level: 'trace' };
+      message = objOrMsg;
+    } else {
+      context = { ...this.context, ...objOrMsg, level: 'trace' };
+      message = msg ?? '';
+    }
+
+    this.telescope.debug(message, context, this.requestId).catch(() => {});
+  }) as LogFn;
+
+  /**
+   * Creates a child logger with additional context.
+   * The child logger inherits all context from the parent.
+   */
+  child(obj: object): Logger {
+    return new TelescopeLogger({
+      telescope: this.telescope,
+      logger: this.logger?.child(obj),
+      requestId: this.requestId,
+      context: { ...this.context, ...obj },
+    });
+  }
+
+  /**
+   * Create a child logger bound to a specific request ID.
+   * Useful for correlating logs with HTTP requests.
+   */
+  withRequestId(requestId: string): TelescopeLogger {
+    return new TelescopeLogger({
+      telescope: this.telescope,
+      logger: this.logger,
+      requestId,
+      context: this.context,
+    });
+  }
+}
+
+/**
+ * Create a logger that sends logs to Telescope.
+ * Convenience function for creating a TelescopeLogger.
+ *
+ * @example
+ * ```typescript
+ * import { createTelescopeLogger } from '@geekmidas/telescope/logger/console';
+ * import { ConsoleLogger } from '@geekmidas/logger/console';
+ *
+ * const telescope = new Telescope({ storage: new InMemoryStorage() });
+ * const baseLogger = new ConsoleLogger({ app: 'myApp' });
+ *
+ * const logger = createTelescopeLogger(telescope, baseLogger);
+ * logger.info({ action: 'startup' }, 'Application started');
+ * ```
+ */
+export function createTelescopeLogger(
+  telescope: Telescope,
+  logger?: Logger,
+  context?: Record<string, unknown>,
+): TelescopeLogger {
+  return new TelescopeLogger({ telescope, logger, context });
+}
+
+export type { Telescope };

package/src/logger/pino.ts

@@ -0,0 +1,191 @@
+import build from 'pino-abstract-transport';
+import type { Telescope } from '../Telescope';
+
+/**
+ * Pino log object structure after parsing
+ */
+export interface PinoLogObject {
+  level: number;
+  time: number;
+  pid?: number;
+  hostname?: string;
+  msg?: string;
+  [key: string]: unknown;
+}
+
+export interface TelescopePinoTransportOptions {
+  /**
+   * The Telescope instance to send logs to
+   */
+  telescope: Telescope;
+  /**
+   * Request ID to associate logs with a specific request.
+   * Can be a static string or a function that extracts the ID from log data.
+   */
+  requestId?: string | ((data: PinoLogObject) => string | undefined);
+  /**
+   * Batch size before flushing to Telescope (default: 100)
+   */
+  batchSize?: number;
+  /**
+   * Flush interval in milliseconds (default: 1000ms)
+   */
+  flushIntervalMs?: number;
+}
+
+type TelescopeLogLevel = 'debug' | 'info' | 'warn' | 'error';
+
+interface LogBatch {
+  level: TelescopeLogLevel;
+  message: string;
+  context: Record<string, unknown>;
+  requestId?: string;
+}
+
+/**
+ * Map Pino numeric levels to Telescope log levels
+ */
+function mapPinoLevel(level: number): TelescopeLogLevel {
+  // Pino levels: trace=10, debug=20, info=30, warn=40, error=50, fatal=60
+  if (level <= 20) return 'debug'; // trace, debug
+  if (level <= 30) return 'info';
+  if (level <= 40) return 'warn';
+  return 'error'; // error, fatal
+}
+
+/**
+ * Create a Pino transport that sends logs to Telescope.
+ *
+ * Uses pino-abstract-transport for proper async iteration and backpressure handling.
+ * Logs are batched for performance and flushed either when the batch is full
+ * or after the flush interval.
+ *
+ * @example
+ * ```typescript
+ * import pino from 'pino';
+ * import { Telescope, InMemoryStorage } from '@geekmidas/telescope';
+ * import { createPinoTransport } from '@geekmidas/telescope/logger/pino';
+ *
+ * const telescope = new Telescope({ storage: new InMemoryStorage() });
+ *
+ * // Use with pino.multistream to log to both stdout and Telescope
+ * const logger = pino(
+ *   { level: 'debug' },
+ *   pino.multistream([
+ *     { stream: process.stdout },
+ *     { stream: createPinoTransport({ telescope }) }
+ *   ])
+ * );
+ *
+ * logger.info({ userId: '123' }, 'User logged in');
+ * ```
+ */
+export function createPinoTransport(options: TelescopePinoTransportOptions) {
+  const {
+    telescope,
+    requestId,
+    batchSize = 100,
+    flushIntervalMs = 1000,
+  } = options;
+
+  const batch: LogBatch[] = [];
+  let flushTimer: ReturnType<typeof setTimeout> | null = null;
+
+  async function flush(): Promise<void> {
+    if (batch.length === 0) return;
+
+    const toFlush = batch.splice(0, batch.length);
+
+    // Use batch insert for better performance
+    try {
+      await telescope.log(toFlush);
+    } catch {
+      // Silently ignore errors to not break logging
+    }
+  }
+
+  function scheduleFlush(): void {
+    if (flushTimer === null) {
+      flushTimer = setTimeout(() => {
+        flushTimer = null;
+        flush().catch(() => {
+          // Silently ignore flush errors
+        });
+      }, flushIntervalMs);
+    }
+  }
+
+  function clearFlushTimer(): void {
+    if (flushTimer !== null) {
+      clearTimeout(flushTimer);
+      flushTimer = null;
+    }
+  }
+
+  return build(
+    async (source) => {
+      for await (const obj of source) {
+        const data = obj as PinoLogObject;
+        const { level, msg, time, pid, hostname, ...context } = data;
+
+        const telescopeLevel = mapPinoLevel(level);
+
+        // Extract request ID
+        let reqId: string | undefined;
+        if (typeof requestId === 'function') {
+          reqId = requestId(data);
+        } else if (typeof requestId === 'string') {
+          reqId = requestId;
+        } else if (typeof context.requestId === 'string') {
+          reqId = context.requestId;
+          delete context.requestId;
+        }
+
+        batch.push({
+          level: telescopeLevel,
+          message: msg || '',
+          context,
+          requestId: reqId,
+        });
+
+        if (batch.length >= batchSize) {
+          clearFlushTimer();
+          await flush();
+        } else {
+          scheduleFlush();
+        }
+      }
+    },
+    {
+      async close() {
+        clearFlushTimer();
+        await flush();
+      },
+    },
+  );
+}
+
+/**
+ * Create a Pino destination that sends logs to Telescope.
+ * Alias for createPinoTransport for API compatibility.
+ *
+ * @example
+ * ```typescript
+ * import pino from 'pino';
+ * import { createPinoDestination } from '@geekmidas/telescope/logger/pino';
+ *
+ * const telescope = new Telescope({ storage: new InMemoryStorage() });
+ *
+ * // Use with pino.multistream to log to both stdout and Telescope
+ * const logger = pino(
+ *   { level: 'debug' },
+ *   pino.multistream([
+ *     { stream: process.stdout },
+ *     { stream: createPinoDestination({ telescope }) }
+ *   ])
+ * );
+ * ```
+ */
+export const createPinoDestination = createPinoTransport;
+
+export type { Telescope };