@apexara/logger

A minimal Node.js logger with middleware support. Provides info, error, and debug logging, ANSI color output, and duplicate error suppression.

Install

npm install @apexara/logger

Quick start

import logger from '@apexara/logger';

logger.info('Server started');
logger.error('Connection failed', 'db');
logger.debug({ port: 8080 });

The module also assigns a global instance:

import '@apexara/logger';

logger.info('Using the global logger');

TypeScript 6+ global setup

With TypeScript 6 and module: "nodenext", a side-effect import only makes the global available in the importing file. To get project-wide type support for logger, add the package to types in your tsconfig.json:

{
  "compilerOptions": {
    "types": ["@apexara/logger"]
  }
}

This tells TypeScript to include the global logger declaration across all files without needing an import in each one.

API

logger.info(message, options?)

logger.info('Ready', { color: '36', tags: ['startup'] });

logger.error(message, source, options?)

logger.error('Timeout', 'payments', { color: '33', meta: { timeoutMs: 5000 } });

logger.debug(object, inspectOptions?, options?)

logger.debug({ config: { retries: 3 } }, { depth: 4 });

Call options

• color: ANSI color code as a string, e.g. '31' (red), '32' (green), '33' (yellow), '37' (white).
• tags: string array, intended for middleware.
• meta: free-form key/value data, intended for middleware.

Timestamps and formatting

• Timestamps are formatted in 24-hour time with the Europe/Sofia timezone.
• Output is ANSI-colored; disable colors by running your process without a color-capable terminal.

Middleware

Middlewares can enrich or alter log behavior. They receive a mutable LoggerOptions object and a next function.

import logger, { LoggerMiddleware } from '@apexara/logger';

const addTag: LoggerMiddleware = async (options, next) => {
  options.tags = [...(options.tags ?? []), 'api'];
  await next();
};

logger.addMiddleware(addTag);

Level-specific middleware:

logger.addInfoMidldeware(async (options, next) => {
  options.color = options.color ?? '32';
  await next();
});

logger.addDebugMidldeware(async (options, next) => {
  options.meta = { ...(options.meta ?? {}), debug: true };
  await next();
});

logger.addErrorMidldeware(async (options, next) => {
  options.color = options.color ?? '31';
  await next();
});

Example: Send emails on error

You can use an error middleware to send email notifications when errors occur:

import logger from '@apexara/logger';

logger.addErrorMidldeware(async (options, next) => {
  await next();

  if (config.env === 'dev') {
    return;
  }

  const emailData = {
    toEmail: config.devEmail,
    subject: `${config.appName} ${config.env.toUpperCase()} Error`,
    template: 'error',
    payload: {
      where: options.source,
      message: options.message,
    },
  };

  emailUtil.sendEmail(emailData, EmailType.Info, '')
    .catch(err => console.dir(err, { depth: 10 }));
});

Calling await next() first ensures the error is logged before the email is sent. You can also skip next() entirely to suppress the log output.

Note: tags and meta are not rendered by the default logger output; they are intended for middleware or external handlers.

Duplicate error suppression

Repeated error logs with the same source and message are suppressed for 60 seconds by default. A summary is printed after the interval.

logger.suppressionIntervalMs = 10_000;

Types

The package exports the following TypeScript types:

• LogType
• LoggerOptions
• LogCallOptions
• LoggerMiddleware

License

ISC