@incubrain/logger/README.md

A modern, type-safe logging library for Node.js and browser environments, built on top of Consola with additional features for enterprise applications.

# @ib/logger

A modern, type-safe logging library for Node.js and browser environments, built on top of Consola with additional features for enterprise applications.

## Features

- 🚀 Universal runtime support (Node.js and Browser)
- 🎨 Beautiful console output powered by Consola
- 🔄 Automatic log rotation with file transport
- 🏷 Rich context and tag support
- 📝 Structured logging
- 🔍 Configurable debug levels
- ⚡ Highly performant with buffered writes
- 🔒 Type-safe API

## Installation

```bash
# Using npm
npm install @ib/logger

# Using pnpm
pnpm add @ib/logger

# Using yarn
yarn add @ib/logger
```

## Quick Start

```typescript
import { logger } from "@ib/logger";

// Basic logging
logger.info("Application starting...");
logger.success("Database connected");
logger.error(new Error("Connection failed"));

// With context
const dbLogger = logger.withContext({
  service: "database",
  environment: "production",
});

dbLogger.info("Executing query");

// Advanced setup
import { setupLogger } from "@ib/logger";

const logger = await setupLogger({
  enableFileLogging: true,
  logFile: "app.log",
  setupErrorHandlers: true,
  context: {
    service: "api",
    version: "1.0.0",
  },
});
```

## File Logging

Enable file logging with automatic rotation:

```typescript
import { setupLogger } from "@ib/logger";

const logger = await setupLogger({
  enableFileLogging: true,
  logFile: "logs/app.log",
  maxFileSize: 10 * 1024 * 1024, // 10MB
  maxFiles: 5,
  bufferSize: 64 * 1024, // 64KB buffer
  flushInterval: 1000, // 1 second
});
```

## Log Levels

```typescript
import { LogLevels } from "@ib/logger";

// Available levels
logger.fatal("Critical error"); // 0
logger.error("Error occurred"); // 0
logger.warn("Warning message"); // 1
logger.log("Standard log"); // 2
logger.info("Info message"); // 3
logger.success("Operation completed"); // 3
logger.debug("Debug info"); // 4
logger.trace("Trace message"); // 5

// Set log level
logger.setLevel(LogLevels.debug);
```

## Environment Variables

The logger respects the following environment variables:

- `LOG_LEVEL`: Set the logging level
- `NODE_ENV`: Determines default formatting options

## Runtime Detection

The logger automatically detects the runtime environment and adjusts its behavior:

```typescript
import { getRuntimeContext } from "@ib/logger";

const context = getRuntimeContext();
if (context.isFileSystemAvailable) {
  // Safe to use file logging
}
```

## Best Practices

1. **Use Contexts**

```typescript
// Instead of
logger.info("User logged in", { userId: "123" });

// Do this
const userLogger = logger.withContext({ userId: "123" });
userLogger.info("User logged in");
```

2. **Structured Logging**

```typescript
// Instead of
logger.info(`Processing order ${orderId}`);

// Do this
logger.info("Processing order", { orderId });
```

3. **Error Handling**

```typescript
try {
  await doSomething();
} catch (error) {
  // Errors are handled specially
  logger.error(error);
}
```

## TypeScript Support

The library is written in TypeScript and provides full type definitions:

```typescript
import type { LoggerInstance, LogLevel, LogContext } from "@ib/logger";

const context: LogContext = {
  service: "auth",
  environment: "production",
};
```

## Architecture

```
@ib/logger/
├── core/        # Core logging functionality
├── runtime/     # Runtime detection and adaptation
├── transport/   # File transport and rotation
└── types/      # TypeScript definitions
```

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

## License

[MIT](LICENSE)

## Credits

Built with [Consola](https://github.com/unjs/consola)