@incubrain/logger
Version:
A modern, format-agnostic logging library for Node.js and browser environments, built on top of Consola with additional features for enterprise applications.
354 lines (270 loc) ā¢ 8.46 kB
Markdown
# @incubrain/logger
A modern, format-agnostic 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
- š Format-agnostic - accepts any input style
- š Automatic error/warning logging in development mode
- š Quick file logging for debugging purposes
## Installation
```bash
# Using npm
npm install @incubrain/logger
# Using pnpm
pnpm add @incubrain/logger
# Using yarn
yarn add @incubrain/logger
```
## Quick Start
```typescript
import { logger } from "@incubrain/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 "@incubrain/logger";
const logger = await setupLogger({
enableFileLogging: true,
logFile: "app.log",
setupErrorHandlers: true,
context: {
service: "api",
version: "1.0.0",
},
});
```
## Format-Agnostic Logging
The logger accepts a wide variety of input formats, making it highly flexible for different coding styles:
```typescript
// Console-style with template literals
const file = "user-component.vue";
logger.error(`Error loading component from ${file}`, error);
// With error objects in any position
logger.error(new Error("Authentication failed"));
logger.error("Operation failed", new Error("Database error"));
logger.error("Multiple issues", error1, error2);
// With additional context data
logger.info("Processing request", { userId: "user-123", requestId: "req-456" });
logger.error("API error", error, { statusCode: 500, endpoint: "/api/users" });
// Multiple additional arguments
logger.debug(
"Component rendering",
{ name: "Button" },
{ renderTime: "5ms" },
stats
);
// Object with message property
logger.info({ message: "User logged in", userId: "user-123", source: "web" });
// Just data (creates generic message)
logger.info({ userId: "user-123", action: "login", timestamp: new Date() });
```
All these approaches work seamlessly, with the logger intelligently handling each case.
## File Logging
Enable file logging with automatic rotation:
```typescript
import { setupLogger } from "@incubrain/logger";
const logger = await setupLogger({
fileLogging: {
enabled: true,
filePath: "app", // Will create logs/app.0.log
maxFileSize: 10 * 1024 * 1024, // 10MB
maxFiles: 5,
format: "json",
},
// Explicitly configure error logging (optional in dev mode)
errorLogging: {
enabled: true, // Already true by default in dev mode
filePath: "error", // Will create logs/error.0.log
level: 1, // Capture WARN level and below (ERROR, FATAL)
},
});
```
## Automatic Error Logging in Development
In development mode, all errors and warnings are automatically logged to a dedicated file for easier debugging:
```typescript
// In development mode, this automatically logs errors to logs/error.0.log
import { setupLogger } from "@incubrain/logger";
await setupLogger(); // No additional config needed in dev mode!
// This error will be logged to both console and error.0.log
logger.error("Something went wrong", new Error("Database connection failed"));
```
## Quick File Debugging
Need to quickly log specific data to a file? Use the logToFile utility:
```typescript
import { logToFile } from "@incubrain/logger";
// Log complex data to a specific file for debugging
async function debugAuthFlow() {
const userData = await getUserInfo();
const tokenData = await getTokenInfo();
// Will be saved to logs/auth-debug.0.log
await logToFile(
"auth-debug",
{
user: userData,
token: tokenData,
timestamp: new Date(),
},
{
pretty: true, // Make it human-readable
}
);
}
```
## Log Levels
```typescript
import { LOG_LEVELS } from "@incubrain/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(LOG_LEVELS.DEBUG);
```
## Proper Cleanup
To ensure all file streams are properly closed and there are no memory leaks:
```typescript
import { cleanupLoggers } from "@incubrain/logger";
// Register shutdown handlers
process.on("SIGTERM", async () => {
logger.info("Application shutting down");
await cleanupLoggers();
process.exit(0);
});
// Or manually clean up when needed
async function shutdown() {
await cleanupLoggers();
}
```
## 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 "@incubrain/logger";
const context = getRuntimeContext();
if (context.isFileSystemAvailable) {
// Safe to use file logging
}
```
## Best Practices
1. **Use Contexts for Related Logs**
```typescript
// Instead of repeating user context in every log
logger.info("User logged in", { userId: "123" });
logger.info("Loading dashboard", { userId: "123" });
// Create a contextual logger once
const userLogger = logger.withContext({ userId: "123" });
userLogger.info("User logged in");
userLogger.info("Loading dashboard");
```
2. **Structured Logging with Context**
```typescript
// Console-style provides both readability and structured data
logger.info(`Processing order ${orderId}`, {
customer: customerId,
items: itemCount,
total: orderTotal,
});
```
3. **Error Handling Patterns**
```typescript
try {
await apiCall();
} catch (error) {
// Simple error logging
logger.error(`API call failed for ${endpoint}`, error);
// With additional context
logger.error(`API call failed for ${endpoint}`, error, {
requestId,
statusCode: error.statusCode || 500,
retryCount,
});
}
```
4. **File Logging for Critical Operations**
```typescript
// For important operations, consider dedicated file logs
import { createFileLogger } from "@incubrain/logger";
const paymentLogger = createFileLogger("payment-transactions", {
maxFiles: 30, // Keep longer history
format: "jsonsl", // Compact one-line JSON for easier parsing
});
async function processPayment(paymentData) {
try {
const result = await paymentGateway.charge(paymentData);
// Log successful transaction
await paymentLogger.info({
status: "success",
transactionId: result.id,
amount: paymentData.amount,
customer: paymentData.customerId,
});
return result;
} catch (error) {
// Log failed transaction
await paymentLogger.error({
status: "failed",
error: {
message: error.message,
code: error.code,
},
paymentData,
});
throw error;
}
}
```
## TypeScript Support
The library is written in TypeScript and provides full type definitions:
```typescript
import type {
LoggerInstance,
LogLevel,
LogContext,
FileLoggerOptions,
} from "@incubrain/logger";
const context: LogContext = {
serviceName: "auth-service",
environment: "production",
requestId: "req-123",
};
const fileOptions: FileLoggerOptions = {
maxFileSize: 10 * 1024 * 1024,
format: "json",
pretty: false,
};
```
## Architecture
```
@incubrain/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)