npm package: @supercat1337/logger
Description: A simple logging utility for Node.js applications.
Author: supercat1337
Latest version: 1.0.0

# Logger

A lightweight and flexible logging library for Node.js applications, providing file-based logging with timestamp formatting and timezone support.

## Installation

```bash
npm install @supercat1337/logger
```

## Features

- 📝 Simple file-based logging with different log levels
- 🕒 Configurable timestamp formatting with timezone support
- 📁 Automatic log file path conversion utilities
- 🚀 Promise-based async logging operations
- 🔧 Customizable output directory and file extensions
- ✅ TypeScript support with full type definitions

## Quick Start

```javascript
import { Logger } from '@supercat1337/logger';

// Create a logger instance
const logger = new Logger('./app.log');

// Log messages at different levels
await logger.info('Application started');
await logger.warn('Low disk space');
await logger.error('Failed to connect to database');

// Close the logger when done
await logger.close();
```

## API Reference

### Logger Class

The main Logger class for writing log messages to files.

#### Constructor

```typescript
new Logger(filePath: string, options?: {
    useDate?: boolean;
    timeZone?: any;
})
```

- `filePath`: Path to the log file
- `options.useDate`: Whether to include timestamps in log messages (default: `true`)
- `options.timeZone`: Timezone for timestamps

#### Methods

- `log(message: string, level?: string): Promise<void>` - Write a log message with specified level
- `error(message: string): Promise<void>` - Write an error message
- `warn(message: string): Promise<void>` - Write a warning message
- `info(message: string): Promise<void>` - Write an info message
- `close(): Promise<boolean>` - Close the logger and wait for pending writes

### Utility Functions

#### `convertFilePathToLogFilePath()`

Convert a file path to a log file path by appending `.log` extension.

```typescript
convertFilePathToLogFilePath(
    filePath: string, 
    suffix?: string, 
    options?: {
        outputDir?: string;
        extension?: string;
    }
): string
```

#### Date Formatting Functions

- `formatDate(date: Date, format?: string, timeZone?: string): string` - Format a date with custom format and timezone
- `getDateString(timeZone?: string): string` - Get current date as `YYYY-MM-DD`
- `getDateTimeString(timeZone?: string): string` - Get current datetime as `YYYY-MM-DD HH:MM:SS`
- `getDateTimeStringForFileName(timeZone?: string): string` - Get datetime for filenames as `YYYY-MM-DD_HH-MM-SS`
- `getCurrentTimeZone(): string` - Get current system timezone

## Usage Examples

### Basic Logging

```javascript
import { Logger } from '@supercat1337/logger';

const logger = new Logger('./logs/app.log');

// Log with different levels
await logger.info('User logged in');
await logger.warn('API response slow');
await logger.error('Database connection failed');

// Custom log level
await logger.log('Debug message', 'debug');
```

### With Timezone Configuration

```javascript
import { Logger } from '@supercat1337/logger';

// Logger with specific timezone
const logger = new Logger('./app.log', {
    useDate: true,
    timeZone: 'America/New_York'
});

await logger.info('Log with New York timezone');
```

### File Path Conversion

```javascript
import { convertFilePathToLogFilePath } from '@supercat1337/logger';

// Convert source file path to log file path
const logPath = convertFilePathToLogFilePath('/src/app.js');
// Returns: /src/app.js.log

// With custom output directory and suffix
const customLogPath = convertFilePathToLogFilePath(
    '/src/app.js',
    'errors',
    { outputDir: '/logs', extension: '.txt' }
);
// Returns: /logs/app.errors.txt
```

### Date Formatting

```javascript
import { 
    getDateString, 
    getDateTimeString,
    formatDate 
} from '@supercat1337/logger';

// Get formatted dates
const today = getDateString(); // "2024-01-15"
const now = getDateTimeString(); // "2024-01-15 14:30:45"

// Custom formatting
const customDate = formatDate(
    new Date(), 
    'YYYY/MM/DD HH:mm:ss',
    'Europe/London'
);
```

## Error Handling

The logger handles write errors gracefully:

```javascript
try {
    await logger.error('Something went wrong');
} catch (err) {
    console.error('Failed to write log:', err);
}
```

## Closing the Logger

Always close the logger to ensure all pending writes are completed:

```javascript
// In an async context
await logger.close();

// Or with then/catch
logger.close()
    .then(() => console.log('Logger closed'))
    .catch(err => console.error('Error closing logger:', err));
```

## License

MIT