@novacooo/ezlog

🪵 Lightweight, no-nonsense logger for personal projects.

Simple, colorful, and flexible logging with zero dependencies. Perfect for quick projects where you need more than console.log but don't want the complexity of enterprise loggers.

✨ Features

• 🎨 Colorful output with 5 log levels
• 🕐 Flexible time formats (HH:mm:ss, ISO, custom)
• 🎯 Log level filtering (show only what matters)
• 🎭 Custom formatters (JSON, compact, or build your own)
• 📦 Zero dependencies (pure TypeScript)
• 🪶 Tiny bundle size
• 🔧 TypeScript-first with full type safety

📦 Installation

npm install @novacooo/ezlog

🚀 Quick Start

import { createLogger } from '@novacooo/ezlog';

const logger = createLogger();

logger.debug('Debugging application state');
logger.info('Server started on port 3000');
logger.warn('Connection timeout after 5s');
logger.error('Failed to connect to database');
logger.fatal('Out of memory - shutting down');

Output:

[12:34:56] DEBUG Debugging application state
[12:34:56] INFO  Server started on port 3000
[12:34:56] WARN  Connection timeout after 5s
[12:34:56] ERROR Failed to connect to database
[12:34:56] FATAL Out of memory - shutting down

📚 Usage

Basic Logging

import { createLogger } from '@novacooo/ezlog';

const logger = createLogger();

// Log with multiple arguments
logger.info('User logged in:', { userId: 123, email: '[email protected]' });

// Log with any data type
logger.debug('Request headers:', headers);
logger.error('API error:', error);
logger.warn('Retry attempt:', attemptNumber, 'of', maxRetries);

Configuration

import { createLogger, LogLevel, TimeFormat } from '@novacooo/ezlog';

const logger = createLogger({
  minLevel: LogLevel.DEBUG, // Show all logs
  timeFormat: TimeFormat.HH_SSS, // Include milliseconds
});

Log Levels

Control which logs are displayed using minLevel:

| Level | Value | Description | | ------- | ----- | ---------------------------------------- | | DEBUG | 0 | Detailed debug information | | INFO | 1 | General informational messages (default) | | WARN | 2 | Warning messages | | ERROR | 3 | Error messages | | FATAL | 4 | Critical errors |

// Show only warnings and errors
const logger = createLogger({ minLevel: 'warn' });

logger.debug('Not visible'); // ❌ Hidden
logger.info('Not visible'); // ❌ Hidden
logger.warn('Visible'); // ✅ Shown
logger.error('Visible'); // ✅ Shown

Time Formats

Choose how timestamps are displayed:

import { createLogger, TimeFormat } from '@novacooo/ezlog';

// HH:mm:ss (default)
const logger1 = createLogger({ timeFormat: TimeFormat.HH });
// [12:34:56] INFO Message

// HH:mm:ss.SSS (with milliseconds)
const logger2 = createLogger({ timeFormat: TimeFormat.HH_SSS });
// [12:34:56.789] INFO Message

// ISO 8601
const logger3 = createLogger({ timeFormat: TimeFormat.ISO });
// [2025-10-07T12:34:56.789Z] INFO Message

🎨 Custom Formatters

Built-in Formatters

Default Formatter (colorful with timestamp):

import { createLogger, defaultFormatter } from '@novacooo/ezlog';

const logger = createLogger({ formatter: defaultFormatter });
logger.info('Hello World');
// [12:34:56] INFO  Hello World

JSON Formatter (for production/structured logging):

import { createLogger, jsonFormatter } from '@novacooo/ezlog';

const logger = createLogger({ formatter: jsonFormatter });
logger.info('User action', { userId: 123, action: 'login' });
// {"timestamp":"2025-10-07T12:34:56.789Z","level":"info","message":"User action {\"userId\":123,\"action\":\"login\"}"}

Compact Formatter (minimal output):

import { createLogger, compactFormatter } from '@novacooo/ezlog';

const logger = createLogger({ formatter: compactFormatter });
logger.warn('Warning message');
// [WARN] Warning message

Custom Formatter Functions

Create your own formatter for complete control:

import { createLogger, type FormatterFunction } from '@novacooo/ezlog';

// Emoji formatter
const emojiFormatter: FormatterFunction = (level, ctx, ...args) => {
  const emojis = { debug: '🐛', info: 'ℹ️', warn: '⚠️', error: '❌', fatal: '💀' };
  return [emojis[level], ...args];
};

const logger = createLogger({ formatter: emojiFormatter });
logger.info('Hello!');
// ℹ️ Hello!

// Prefix formatter
const prefixFormatter: FormatterFunction = (level, ctx, ...args) => {
  return [`[MyApp]`, `[${level.toUpperCase()}]`, ...args];
};

const logger2 = createLogger({ formatter: prefixFormatter });
logger2.error('Something failed');
// [MyApp] [ERROR] Something failed

💡 Real-World Examples

API Logging

const logger = createLogger({ minLevel: 'info' });

app.use((req, res, next) => {
  logger.info(`${req.method} ${req.path} ${res.statusCode} - ${responseTime}ms`);
  next();
});

Application Lifecycle

const logger = createLogger({ minLevel: 'debug' });

logger.info('Initializing application...');
logger.debug('Loading configuration from .env');
logger.debug('Connecting to database...');
logger.info('Database connected ✓');
logger.info('Server listening on port 3000 ✓');

Error Handling

const logger = createLogger();

try {
  await riskyOperation();
} catch (error) {
  logger.error('Operation failed:', error);
}

Production Logging (JSON)

const logger = createLogger({
  minLevel: process.env.NODE_ENV === 'production' ? 'warn' : 'debug',
  formatter: process.env.NODE_ENV === 'production' ? jsonFormatter : defaultFormatter,
});

logger.info('App started');
logger.error('Payment processing failed', { orderId, amount, reason });

🔧 API Reference

createLogger(options?)

Creates a new logger instance.

Options:

• minLevel?: LogLevel | number - Minimum log level to display (default: 'info')
• timeFormat?: TimeFormat - Timestamp format (default: 'HH:mm:ss')
• formatter?: FormatterFunction - Custom formatter function (default: defaultFormatter)

Returns: Logger instance with methods: debug, info, warn, error, fatal

FormatterFunction

Type for custom formatter functions:

type FormatterFunction = (logLevel: LogLevel, ctx: LoggerContext, ...args: any[]) => any[];

Parameters:

• logLevel - Current log level
• ctx - Logger context (includes minLevel, timeFormat, formatter)
• ...args - Arguments passed to the log method

Returns: Array of values to pass to console.*

🤔 Why ezlog?

• Simple: One function call, no configuration files, no complexity
• Fast: Zero dependencies, minimal overhead
• Flexible: Use built-in formatters or create your own
• TypeScript: Full type safety out of the box
• Modern: ESM + CJS, works everywhere

📄 License

MIT © Jacek Nowak

🔗 Links

• GitHub
• npm
• Issues

Made with ❤️ for developers who want simple, beautiful logs without the bloat.