Custom Transports

1interface Transport {
2  // Unique identifier for this transport
3  readonly name: string
4 
5  // Transport configuration
6  readonly config: TransportConfig
7 
8  // Initialize transport (called once on startup)
9  init?(): Promise<void>
10 
11  // Log a single entry
12  log(entry: LogEntry): void | Promise<void>
13 
14  // Flush any buffered entries
15  flush?(): Promise<void>
16 
17  // Cleanup resources (called on shutdown)
18  destroy?(): Promise<void>
19}

1interface Transport {
2  // Can return void (sync) or Promise<void> (async)
3  log(entry: LogEntry): void | Promise<void>
4}

1class BufferingTransport implements Transport {
2  private buffer: LogEntry[] = []
3 
4  // Sync: Just adds to buffer, no waiting
5  log(entry: LogEntry): void {
6    this.buffer.push(entry)
7  }
8}

1class ImmediateHttpTransport implements Transport {
2  // Async: Each log is sent immediately
3  async log(entry: LogEntry): Promise<void> {
4    await fetch(this.url, {
5      method: 'POST',
6      body: JSON.stringify(entry)
7    })
8  }
9}

1// Internal logger behavior (simplified):
2for (const transport of this.transports) {
3  const result = transport.log(entry)
4  // If async, the promise is NOT awaited by default
5  // Logs are fire-and-forget for performance
6}

1logger.info('Important message')
2await logger.flush()  // Waits for all transports to complete

1import { createLogger } from 'vestig'
2import type { Transport, TransportConfig, LogEntry } from 'vestig'
3 
4class ConsoleJsonTransport implements Transport {
5  readonly name = 'console-json'
6  readonly config: TransportConfig
7 
8  constructor() {
9    this.config = {
10      name: 'console-json',
11      enabled: true,
12    }
13  }
14 
15  log(entry: LogEntry): void {
16    console.log(JSON.stringify(entry))
17  }
18}
19 
20// Use the transport
21const logger = createLogger({
22  transports: [new ConsoleJsonTransport()]
23})
24 
25logger.info('Hello World')

1interface LogEntry {
2  // ISO timestamp string
3  timestamp: string       // "2025-01-01T12:00:00.000Z"
4 
5  // Log level
6  level: LogLevel         // 'trace' | 'debug' | 'info' | 'warn' | 'error'
7 
8  // The log message
9  message: string         // "User logged in"
10 
11  // Additional metadata
12  metadata?: LogMetadata  // { userId: 'user-123', ip: '10.0.0.1' }
13 
14  // Correlation context
15  context?: LogContext    // { requestId: 'req-abc', traceId: '...' }
16 
17  // Runtime environment
18  runtime: Runtime        // 'node' | 'bun' | 'deno' | 'edge' | 'browser'
19 
20  // Logger namespace
21  namespace?: string      // 'api:users'
22 
23  // Serialized error (if logged)
24  error?: SerializedError // { name: 'Error', message: '...', stack: '...' }
25}

1interface TransportConfig {
2  // Transport name (required)
3  name: string
4 
5  // Enable/disable this transport (default: true)
6  enabled?: boolean
7 
8  // Minimum log level for this transport
9  level?: LogLevel
10 
11  // Filter function for entries
12  filter?: (entry: LogEntry) => boolean
13}

1interface SlackTransportConfig {
2  webhookUrl: string
3  channel?: string
4  enabled?: boolean
5  level?: 'warn' | 'error'
6}
7 
8class SlackTransport implements Transport {
9  readonly name = 'slack'
10  readonly config: TransportConfig
11  private webhookUrl: string
12  private channel?: string
13 
14  constructor(config: SlackTransportConfig) {
15    this.webhookUrl = config.webhookUrl
16    this.channel = config.channel
17    this.config = {
18      name: 'slack',
19      enabled: config.enabled ?? true,
20      level: config.level ?? 'error', // Only errors by default
21    }
22  }
23 
24  async log(entry: LogEntry): Promise<void> {
25    const text = `[${entry.level.toUpperCase()}] ${entry.message}`
26 
27    await fetch(this.webhookUrl, {
28      method: 'POST',
29      headers: { 'Content-Type': 'application/json' },
30      body: JSON.stringify({
31        channel: this.channel,
32        text,
33        attachments: [{
34          color: entry.level === 'error' ? 'danger' : 'warning',
35          fields: [
36            { title: 'Timestamp', value: entry.timestamp },
37            { title: 'Namespace', value: entry.namespace ?? 'root' },
38          ],
39        }],
40      }),
41    })
42  }
43}

1import type { LogEntry, BatchTransportConfig } from 'vestig'
2 
3interface MyServiceConfig extends BatchTransportConfig {
4  apiKey: string
5  endpoint: string
6}
7 
8class MyServiceTransport extends BatchTransport {
9  readonly name = 'my-service'
10  private apiKey: string
11  private endpoint: string
12 
13  constructor(config: MyServiceConfig) {
14    super({
15      ...config,
16      name: 'my-service',
17      batchSize: config.batchSize ?? 50,
18      flushInterval: config.flushInterval ?? 10000,
19    })
20 
21    this.apiKey = config.apiKey
22    this.endpoint = config.endpoint
23  }
24 
25  // Implement the send method - called with batched entries
26  protected async send(entries: LogEntry[]): Promise<void> {
27    const response = await fetch(this.endpoint, {
28      method: 'POST',
29      headers: {
30        'Content-Type': 'application/json',
31        'Authorization': `Bearer ${this.apiKey}`,
32      },
33      body: JSON.stringify({ logs: entries }),
34    })
35 
36    if (!response.ok) {
37      throw new Error(`HTTP ${response.status}: ${response.statusText}`)
38    }
39  }
40}

1interface BatchTransportConfig {
2  // Maximum entries before auto-flush (default: 100)
3  batchSize?: number
4 
5  // Interval in ms between auto-flushes (default: 5000)
6  flushInterval?: number
7 
8  // Maximum retry attempts on failure (default: 3)
9  maxRetries?: number
10 
11  // Delay between retries in ms (default: 1000)
12  retryDelay?: number
13}

1class ResilientTransport extends BatchTransport {
2  readonly name = 'resilient'
3 
4  protected async send(entries: LogEntry[]): Promise<void> {
5    // Your send logic
6  }
7 
8  // Called when entries are dropped from buffer overflow
9  protected onDrop(entries: LogEntry[]): void {
10    console.warn(`Dropped ${entries.length} entries - buffer full`)
11    // Could write to fallback storage
12  }
13 
14  // Called when send fails after all retries
15  protected onSendError(error: Error, entries: LogEntry[]): void {
16    console.error(`Failed to send ${entries.length} entries:`, error)
17    // Could write to dead letter queue
18  }
19}

1const transport = new MyServiceTransport({ ... })
2const stats = transport.getStats()
3 
4console.log(stats)
5// {
6//   buffered: 45,      // Entries waiting to be sent
7//   dropped: 0,        // Entries dropped due to overflow
8//   isFlushing: false  // Currently sending a batch
9// }

1class DatabaseTransport implements Transport {
2  private connection: DatabaseConnection | null = null
3 
4  async init(): Promise<void> {
5    this.connection = await Database.connect({
6      host: 'localhost',
7      database: 'logs',
8    })
9    console.log('Database transport initialized')
10  }
11 
12  log(entry: LogEntry): void {
13    this.connection?.insert('logs', entry)
14  }
15}

1class QueueTransport implements Transport {
2  private queue: LogEntry[] = []
3 
4  log(entry: LogEntry): void {
5    this.queue.push(entry)
6  }
7 
8  async flush(): Promise<void> {
9    if (this.queue.length === 0) return
10 
11    const entries = [...this.queue]
12    this.queue = []
13 
14    await this.sendToQueue(entries)
15  }
16 
17  async sendToQueue(entries: LogEntry[]): Promise<void> {
18    // Send to message queue
19  }
20}

1class FileTransport implements Transport {
2  private fileHandle: FileHandle | null = null
3 
4  async init(): Promise<void> {
5    this.fileHandle = await fs.open('./app.log', 'a')
6  }
7 
8  log(entry: LogEntry): void {
9    this.fileHandle?.write(JSON.stringify(entry) + '\n')
10  }
11 
12  async destroy(): Promise<void> {
13    await this.flush?.()
14    await this.fileHandle?.close()
15    console.log('File transport closed')
16  }
17}

1const logger = createLogger({
2  transports: [
3    new ConsoleTransport({ level: 'debug' }),  // All levels
4    new SlackTransport({ level: 'error' }),    // Errors only
5    new FileTransport({ level: 'info' }),      // Info and above
6  ]
7})

1const transport = new HTTPTransport({
2  url: 'https://logs.example.com',
3  filter: (entry) => {
4    // Skip health check logs
5    if (entry.namespace === 'http' && entry.message.includes('/health')) {
6      return false
7    }
8 
9    // Only log entries with requestId
10    if (!entry.context?.requestId) {
11      return false
12    }
13 
14    return true
15  }
16})

1import type { LogEntry, Transport, TransportConfig } from 'vestig'
2import { BatchTransport } from 'vestig/transports/batch'
3 
4interface ElasticsearchConfig {
5  nodes: string[]
6  index: string
7  apiKey?: string
8  batchSize?: number
9  flushInterval?: number
10}
11 
12class ElasticsearchTransport extends BatchTransport {
13  readonly name = 'elasticsearch'
14  private nodes: string[]
15  private index: string
16  private apiKey?: string
17  private currentNodeIndex = 0
18 
19  constructor(config: ElasticsearchConfig) {
20    super({
21      name: 'elasticsearch',
22      batchSize: config.batchSize ?? 100,
23      flushInterval: config.flushInterval ?? 5000,
24    })
25 
26    this.nodes = config.nodes
27    this.index = config.index
28    this.apiKey = config.apiKey
29  }
30 
31  protected async send(entries: LogEntry[]): Promise<void> {
32    // Build bulk request body
33    const body = entries.flatMap(entry => [
34      { index: { _index: this.index } },
35      {
36        '@timestamp': entry.timestamp,
37        level: entry.level,
38        message: entry.message,
39        metadata: entry.metadata,
40        context: entry.context,
41        runtime: entry.runtime,
42        namespace: entry.namespace,
43        error: entry.error,
44      }
45    ])
46 
47    const node = this.getNextNode()
48    const response = await fetch(`${node}/_bulk`, {
49      method: 'POST',
50      headers: {
51        'Content-Type': 'application/x-ndjson',
52        ...(this.apiKey ? { 'Authorization': `ApiKey ${this.apiKey}` } : {}),
53      },
54      body: body.map(line => JSON.stringify(line)).join('\n') + '\n',
55    })
56 
57    if (!response.ok) {
58      throw new Error(`Elasticsearch error: ${response.status}`)
59    }
60 
61    const result = await response.json()
62    if (result.errors) {
63      throw new Error('Elasticsearch bulk indexing had errors')
64    }
65  }
66 
67  // Round-robin node selection
68  private getNextNode(): string {
69    const node = this.nodes[this.currentNodeIndex]
70    this.currentNodeIndex = (this.currentNodeIndex + 1) % this.nodes.length
71    return node
72  }
73 
74  protected onSendError(error: Error, entries: LogEntry[]): void {
75    console.error(`[elasticsearch] Failed to index ${entries.length} docs:`, error)
76    // Could fallback to file storage
77  }
78}
79 
80// Usage
81const logger = createLogger({
82  transports: [
83    new ConsoleTransport(),
84    new ElasticsearchTransport({
85      nodes: ['http://localhost:9200'],
86      index: 'app-logs',
87      batchSize: 50,
88    })
89  ]
90})

1import { describe, expect, test, mock } from 'bun:test'
2 
3describe('SlackTransport', () => {
4  test('should send error logs to Slack', async () => {
5    const fetchMock = mock(() =>
6      Promise.resolve(new Response('ok', { status: 200 }))
7    )
8    globalThis.fetch = fetchMock
9 
10    const transport = new SlackTransport({
11      webhookUrl: 'https://hooks.slack.com/xxx',
12    })
13 
14    await transport.log({
15      timestamp: new Date().toISOString(),
16      level: 'error',
17      message: 'Test error',
18      runtime: 'node',
19    })
20 
21    expect(fetchMock).toHaveBeenCalledTimes(1)
22    expect(fetchMock.mock.calls[0][0]).toBe('https://hooks.slack.com/xxx')
23  })
24})

1import type {
2  Transport,
3  TransportConfig,
4  BatchTransportConfig,
5  LogEntry,
6  LogLevel,
7  LogMetadata,
8  LogContext,
9  SerializedError,
10} from 'vestig'