npm package: @supscale/logger
Description: Structured logging library for Grafana Loki
Latest version: 0.2.1

# @supscale/logger — TypeScript

TypeScript implementation of the [@supscale/logger](../README.md) library. Ships structured logs to Grafana Loki with batching, retry, and zero runtime dependencies.

> Requires **Node.js 20+** (uses native `fetch`).

## Installation

```bash
npm install @supscale/logger
```

## Usage

```typescript
import { Logger } from '@supscale/logger';

const logger = new Logger({
    url: 'https://loki.example.com',
    apiKey: 'your-api-key',
    app: 'my-app',
});

logger.info('User signed in');
logger.warn('Disk usage above 80%');
logger.error('Payment processing failed');
```

Logs are buffered and sent in batches automatically. To flush manually:

```typescript
await logger.flush();
```

### Graceful Shutdown

Always call `shutdown()` before your process exits to ensure all buffered logs are sent:

```typescript
process.on('SIGTERM', async () => {
    await logger.shutdown();
    process.exit(0);
});
```

## Configuration

```typescript
const logger = new Logger({
    url: 'https://loki.example.com',  // Loki base URL (required)
    apiKey: 'your-api-key',           // Sent via X-Api-Key header (required)
    app: 'my-app',                    // App label in Loki (required)
    batchInterval: 5000,              // Flush interval in ms (default: 5000)
    batchSize: 100,                   // Max entries before auto-flush (default: 100)
    requestTimeout: 30000,            // HTTP request timeout in ms (default: 30000)
});
```

## API

### `new Logger(config: LoggerConfig)`

Creates a new logger instance. Starts a background timer that flushes buffered logs at the configured interval.

### `logger.debug(message: string): void`
### `logger.info(message: string): void`
### `logger.warn(message: string): void`
### `logger.error(message: string): void`
### `logger.fatal(message: string): void`

Append a log entry to the buffer. Returns immediately (non-blocking). If the buffer reaches `batchSize`, a flush is triggered automatically.

### `logger.flush(): Promise<void>`

Sends all buffered logs to Loki. Retries up to 3 times with exponential backoff on transient errors (5xx, 429, network failures).

### `logger.shutdown(): Promise<void>`

Flushes remaining logs and clears the background timer. Call this before process exit.

## Types

```typescript
type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'fatal';

interface LoggerConfig {
    url: string;
    apiKey: string;
    app: string;
    batchInterval?: number;
    batchSize?: number;
    requestTimeout?: number;
}
```

## Behavior

| Concern | Detail |
|---------|--------|
| Batching | Logs accumulate in memory, flushed every `batchInterval` ms or when `batchSize` is reached |
| Retry | Up to 3 retries with exponential backoff (1s, 2s, 4s) on 5xx, 429, or network errors |
| No retry | 4xx client errors (except 429) are not retried |
| Non-blocking | Log methods return immediately; flushes run async in the background |
| Timeout | Each HTTP request is aborted after `requestTimeout` ms (default: 30s) |
| Timer | Uses `unref()` so the flush timer doesn't prevent process exit |

## Development

```bash
# Install dependencies
npm install

# Build (ESM + CJS + type declarations)
npm run build

# Run tests
npm test

# Watch mode (rebuild on change)
npm run dev
```

## License

MIT