@vivtel/logger

Comprehensive logger for modern JavaScript/TypeScript apps with:

• Multiple log levels (debug, info, log, warn, error)
• Structured metadata and automatic context (session, correlation, user)
• Pluggable transports (console, remote HTTP)
• Optional sensitive‑data redaction
• React integration (provider + hooks)
• Decorators for DI / AOP style logging
• Activity logger for long‑running CLI / server tasks

Installation

pnpm add @vivtel/logger
# or
npm install @vivtel/logger
# or
yarn add @vivtel/logger

Peer dependencies:

• react (optional, only required if you use the React APIs)
• @vivtel/metadata (optional, only required if you use the decorators)

Core usage

Creating a logger

import { Logger } from '@vivtel/logger';

const logger = new Logger('app');

logger.info('Application started');
logger.error('Something went wrong', { code: 500 });

By default, the logger uses the built‑in console transport with pretty, colored output.

You can also pass options:

import { Logger } from '@vivtel/logger';
import { createRedactor } from '@vivtel/logger';

const logger = new Logger({
  namespace: 'api',
  defaultConsole: true,
  redactor: createRedactor({
    sensitiveKeys: ['customSecret'],
  }),
  sampleRate: 0.1, // sample 10% of debug logs
});

Log levels and metadata

All log methods share the same flexible signature:

logger.log('Simple message');
logger.info('Message with metadata', { userId: '123' });
logger.warn('Value:', 42, true, { source: 'job-runner' });
logger.error('Failed to fetch', { url }, new Error('Network error'));

You can create child loggers and bind context:

const baseLogger = new Logger('app');

const requestLogger = baseLogger
  .withContext({ requestId: 'req-123' })
  .withContext({ userId: 'user-456' });

requestLogger.info('Processing request');
// -> logs with { requestId: 'req-123', userId: 'user-456' }

const child = baseLogger.child('auth');
child.info('User logged in'); // namespace: "app:auth"

Context & correlation

Logger instances automatically pull context from a global ContextStore:

• sessionId – sticky per tab/session
• correlationId – for grouping logs by request / workflow
• userId – set after authentication
• arbitrary metadata

You can manage this explicitly via the useLogContext hook in React (see below) or via the contextStore APIs.

import { contextStore } from '@vivtel/logger';

contextStore.setCorrelationId('req-123');
contextStore.setUserId('user-1');
contextStore.setMetadata({ feature: 'checkout' });

// All subsequent logs will include this context

React integration

Provider

import { LoggerProvider } from '@vivtel/logger';

function App() {
  return (
    <LoggerProvider>
      <MyComponent />
    </LoggerProvider>
  );
}

You can also pass a custom Logger instance:

import { LoggerProvider, Logger } from '@vivtel/logger';

const logger = new Logger('web');

function App() {
  return (
    <LoggerProvider logger={logger}>
      <MyComponent />
    </LoggerProvider>
  );
}

useLogger

import { useLogger } from '@vivtel/logger';

function UserProfile() {
  const logger = useLogger('UserProfile');

  useEffect(() => {
    logger.info('User profile mounted');
  }, [logger]);

  return <div>User profile</div>;
}

useLogContext

import { useLogContext } from '@vivtel/logger';

function AuthManager() {
  const {
    setUserId,
    getSessionId,
    setMetadata,
    setCorrelationId,
    clearCorrelationId,
  } = useLogContext();

  const login = (user: { id: string }) => {
    setUserId(user.id);
    setMetadata({ feature: 'auth' });
  };

  const startRequest = () => {
    const id = crypto.randomUUID();
    setCorrelationId(id);
    console.log('Session:', getSessionId());
  };

  const endRequest = () => {
    clearCorrelationId();
  };

  // ...
}

Transports & formatters

Console

import { Logger } from '@vivtel/logger';
import { ConsoleTransport } from '@vivtel/logger/transports';

const logger = new Logger('app');
logger.transports = [
  new ConsoleTransport({
    minLevel: 'debug',
    colors: true,
  }),
];

Remote HTTP

import { Logger } from '@vivtel/logger';
import { RemoteTransport } from '@vivtel/logger/transports';

const logger = new Logger('app');

logger.addTransport(
  new RemoteTransport({
    endpoint: 'https://api.example.com/logs',
    batchSize: 10,
    flushInterval: 5000,
    maxBufferSize: 1000,
    dropPolicy: 'drop-oldest',
    headers: { Authorization: 'Bearer token' },
  }),
);

Formatters are separated from transports and can be used independently:

• PrettyFormatter – colored, multi‑line, browser‑friendly
• JsonFormatter – structured JSON output
• CliFormatter – compact, single‑line CLI format

Decorators (optional)

Decorators use @vivtel/metadata under the hood to store metadata only. You still need a DI/AOP layer to actually wire loggers.

@InjectLogger

import { InjectLogger, Logger } from '@vivtel/logger';

class UserService {
  @InjectLogger('Users')
  private logger!: Logger;

  async create() {
    this.logger.info('Creating user');
  }
}

@Log

import { Log } from '@vivtel/logger';

class PaymentService {
  @Log({ level: 'info', timing: true })
  async processPayment() {
    // Metadata is attached for your interceptor to consume
  }
}

@LogError

import { LogError } from '@vivtel/logger';

class NotificationService {
  @LogError({ level: 'warn', message: 'Email send failed' })
  async sendEmail() {
    // Error handling is configured via metadata
  }
}

Activity logger (CLI / server)

The package exposes an activity logger for long‑running tasks via the @vivtel/logger/activity entry point.

import activityManager from '@vivtel/logger/activity';

const id = activityManager.activity('Processing users');

activityManager.progress(id, 'Fetching data...');

try {
  // do work
  activityManager.success(id, 'Complete!');
} catch (error) {
  activityManager.failure(id, 'Failed');
}

In development it uses ora spinners; in other environments it falls back to plain console output with colored labels.

TypeScript

The library is written in TypeScript and ships fully typed:

• LogLevel, LogEntry, LogMetadata, transport and formatter interfaces
• Strongly‑typed options for logger configuration, decorators, and transports

Types are available via the main entrypoint:

import type { LogLevel, LogEntry, LogMetadata } from '@vivtel/logger';

License

MIT