npm package: @libster/loggy
Description: A clean and formatted logging library for Node.js applications with redaction and Express middleware support
Author: Your Name
Latest version: 1.0.3

# Loggy

A clean and formatted logging library for Node.js applications with automatic redaction, Express middleware support, and CLI tools.

## Features

- 🎨 **Beautiful formatting** - Colored, human-readable logs with timestamps and icons
- 🔒 **Automatic redaction** - Sensitive data like passwords and tokens are automatically redacted
- 📊 **Multiple output modes** - Pretty format for development, JSON for production
- 🚀 **Express middleware** - Built-in request logging middleware
- 🛠️ **CLI tool** - Format and clean logs from files or stdin
- 📝 **TypeScript support** - Full TypeScript definitions included
- ⚡ **Zero dependencies** - Lightweight with minimal dependencies

## Installation

### Using npm
```bash
npm install @libster/loggy
```

### Using yarn
```bash
yarn add @libster/loggy
```

### Using pnpm
```bash
pnpm add @libster/loggy
```

## Quick Start

### Basic Usage

```typescript
import { createLogger } from '@libster/loggy';

const logger = createLogger();

logger.info('User logged in', { userId: 123, username: 'john' });
logger.warn('Rate limit approaching', { requests: 95, limit: 100 });
logger.error('Database connection failed', { error: 'Connection timeout' });
```

### Output Example
```
[2025-09-12T10:15:00.000Z] INFO  ℹ️ User logged in
  Metadata: {
    "userId": 123,
    "username": "john"
  }
[2025-09-12T10:15:01.000Z] WARN  ⚠️ Rate limit approaching
  Metadata: {
    "requests": 95,
    "limit": 100
  }
[2025-09-12T10:15:02.000Z] ERROR ❌ Database connection failed
  Metadata: {
    "error": "Connection timeout"
  }
```

### With Configuration

```typescript
import { createLogger } from '@libster/loggy';

const logger = createLogger({
  mode: 'json',           // 'pretty' or 'json'
  level: 'debug',         // 'debug', 'info', 'warn', 'error'
  redact: ['password', 'token', 'secret'], // Custom redaction keys
  timestamp: true         // Include timestamps
});

logger.info('User login', { 
  user: 'john', 
  password: 'secret123'  // Will be redacted as "****"
});
```

## API Reference

### Logger Methods

#### `logger.info(message, metadata?)`
Log an info message with optional metadata.

#### `logger.warn(message, metadata?)`
Log a warning message with optional metadata.

#### `logger.error(message, metadata?, error?)`
Log an error message with optional metadata and Error object.

#### `logger.debug(message, metadata?)`
Log a debug message with optional metadata.

#### Legacy Methods
For backward compatibility, these methods are also available:
- `logger.logInfo(message, metadata?)`
- `logger.logWarn(message, metadata?)`
- `logger.logError(message, metadata?, error?)`
- `logger.logDebug(message, metadata?)`

### Configuration Options

```typescript
interface LoggerConfig {
  mode?: 'pretty' | 'json';        // Output format
  level?: 'debug' | 'info' | 'warn' | 'error';  // Minimum log level
  redact?: string[];               // Custom keys to redact
  timestamp?: boolean;             // Include timestamps
}
```

## Express Middleware

Loggy includes a built-in Express middleware for request logging:

```typescript
import express from 'express';
import { loggerMiddleware } from '@libster/loggy';

const app = express();

// Basic usage
app.use(loggerMiddleware());

// With configuration
app.use(loggerMiddleware({
  mode: 'json',
  skip: (req, res) => req.url === '/health'  // Skip health checks
}));

app.get('/users', (req, res) => {
  res.json({ users: [] });
});
```

This will log requests like:
```
[2023-12-01T10:15:00Z] INFO GET /users 200 45ms
```

### Middleware Configuration

```typescript
interface MiddlewareConfig extends LoggerConfig {
  skip?: (req: Request, res: Response) => boolean;
}
```

## CLI Tool

Loggy includes a CLI tool for formatting logs from files or stdin:

### Basic Usage

```bash
# Format logs from stdin
cat logs.json | npx @libster/loggy --pretty

# Format logs from a file
npx @libster/loggy --file logs.json --pretty

# Output as JSON
npx @libster/loggy --file logs.json --json

# Custom redaction keys
npx @libster/loggy --file logs.json --redact password,token,secret --pretty
```

### CLI Options

- `-p, --pretty` - Output in pretty format (default)
- `-j, --json` - Output in JSON format
- `-r, --redact <keys>` - Comma-separated list of keys to redact
- `-f, --file <path>` - Read from file instead of stdin
- `--no-timestamp` - Disable timestamps
- `-l, --level <level>` - Minimum log level (debug, info, warn, error)

### Examples

```bash
# Pretty format with custom redaction
cat app.log | npx @libster/loggy --pretty --redact password,api_key

# JSON format for log aggregation
npx @libster/loggy --file app.log --json --level warn

# Process multiple files
for file in logs/*.log; do
  npx @libster/loggy --file "$file" --pretty
done
```

## Automatic Redaction

Loggy automatically redacts sensitive data in your logs. By default, it redacts:

- `password`
- `token`
- `secret`
- `apikey`
- `api_key`
- `auth`
- `authorization`

### Example

```typescript
const logger = createLogger();

logger.info('User login', {
  username: 'john',
  password: 'secret123',    // Redacted as "****"
  email: 'john@example.com',
  token: 'abc123'          // Redacted as "****"
});
```

Output:
```
[2023-12-01T10:15:00Z] INFO ℹ️ User login
  Metadata: {
    "username": "john",
    "password": "****",
    "email": "john@example.com",
    "token": "****"
  }
```

### Custom Redaction

```typescript
const logger = createLogger({
  redact: ['password', 'token', 'custom_secret']
});
```

## Error Handling

Loggy provides enhanced error formatting with stack trace highlighting:

```typescript
const logger = createLogger();

try {
  throw new Error('Something went wrong');
} catch (error) {
  logger.error('Operation failed', { operation: 'user_create' }, error);
}
```

This will:
- Highlight your application code in stack traces
- Fade out Node.js internal lines
- Include error name, message, and formatted stack trace

## Output Modes

### Pretty Mode (Development)

```
[2023-12-01T10:15:00Z] INFO ℹ️ User logged in
  Metadata: {
    "userId": 123,
    "username": "john"
  }
```

### JSON Mode (Production)

```json
{"timestamp":"2023-12-01T10:15:00.000Z","level":"info","message":"User logged in","metadata":{"userId":123,"username":"john"}}
```

## Log Levels

Loggy supports four log levels with filtering:

- `debug` - Detailed information for debugging
- `info` - General information about application flow
- `warn` - Warning messages for potentially harmful situations
- `error` - Error events that might still allow the application to continue

Set the minimum log level to filter out less important messages:

```typescript
const logger = createLogger({ level: 'warn' });

logger.debug('This will not be logged');
logger.info('This will not be logged');
logger.warn('This will be logged');
logger.error('This will be logged');
```

## TypeScript Support

Loggy is written in TypeScript and includes full type definitions:

```typescript
import { createLogger, Logger, LoggerConfig } from '@libster/loggy';

const config: LoggerConfig = {
  mode: 'json',
  level: 'info'
};

const logger: Logger = createLogger(config);
```

## Examples

### Express Application

```typescript
import express from 'express';
import { createLogger, loggerMiddleware } from '@libster/loggy';

const app = express();
const logger = createLogger({ mode: 'json' });

app.use(loggerMiddleware({ mode: 'json' }));

app.get('/users/:id', (req, res) => {
  const userId = req.params.id;
  
  logger.info('Fetching user', { userId });
  
  // Your logic here
  res.json({ id: userId, name: 'John' });
});

app.listen(3000, () => {
  logger.info('Server started', { port: 3000 });
});
```

### Error Handling

```typescript
import { createLogger } from '@libster/loggy';

const logger = createLogger();

async function processUser(userId: string) {
  try {
    logger.info('Processing user', { userId });
    
    // Simulate some work
    if (Math.random() > 0.5) {
      throw new Error('Processing failed');
    }
    
    logger.info('User processed successfully', { userId });
  } catch (error) {
    logger.error('Failed to process user', { userId }, error as Error);
    throw error;
  }
}
```

### Custom Redaction

```typescript
import { createLogger } from '@libster/loggy';

const logger = createLogger({
  redact: ['password', 'ssn', 'credit_card', 'api_key']
});

logger.info('Payment processed', {
  userId: 123,
  amount: 99.99,
  credit_card: '4111-1111-1111-1111',  // Redacted
  api_key: 'sk-1234567890'             // Redacted
});
```

## Development

### Building

```bash
npm run build
```

### Testing

```bash
npm test
npm run test:coverage
```

### Linting

```bash
npm run lint
npm run lint:fix
```

### Formatting

```bash
npm run format
npm run format:check
```

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

### Development Setup

```bash
git clone https://github.com/vijoy-paul/libster-loggy.git
cd loggy
npm install
npm run build
npm test
```

## License

MIT License - see [LICENSE](LICENSE) file for details.

## Changelog

### 1.0.0
- Initial release
- Core logging functionality
- Automatic redaction
- Express middleware
- CLI tool
- TypeScript support
- Comprehensive test suite