@project-reporter/file-logger v0.0.1

Project Reporter - File Logger

This package contains the default implementation of the Project Reporter's file logger

Table of Contents

• Installation
• FileLogger class
  • Properties
  • Methods
• Usage Example
• More Advanced Usage
• Error Reporting
• Note
• Contributing
• Credits

Installation

Using NPM.

npm i @project-reporter/file-logger

Using Yarn.

yarn add @project-reporter/file-logger

FileLogger class

This is the main class that you going to use.

Properties

Some properties need extra work when modify, that's why each property have a setter function, so, try to avoid modifying them directly.

For the full set of properties check the Wiki page.

Methods

Set directory where to save log files.

setLogsDir(logsDir: string): FileLogger;

Set character encoding.

setEncoding(encoding: string): FileLogger;

Get log files path.

getLogsDir(): string;

Get character encoding.

getEncoding(): string;

An abstraction for the logging functions to avoid code duplication.

async log(level: LogLevel, message: string | Error, ...meta: string[]): Promise<void>;

Append info message to log file.

async info(message: string, ...meta: string[]): Promise<void>;

Append error message to log file.

async error(message: string | Error, ...meta: string[]): Promise<void>;

Append trace message to log file.

async trace(message: string, ...meta: string[]): Promise<void>;

For the full set of methods check the Wiki page.

Usage Example

Basic usage

import { FileLogger } from '@project-reporter/file-logger';

const logger = new FileLogger();

logger.info('My Message'); // appends "[<timestamp>] INFO: My Message" to "report.log" file at "<project>/logs" file.

Custom path

import { FileLogger } from '@project-reporter/file-logger';

const logger = new FileLogger();

logger.setLogsDir('path/to/save/logs');

logger.info('My Message');

Custom file name

import { FileLogger } from '@project-reporter/file-logger';

const logger = new FileLogger();

logger.setLogFileName('my-awesome-project');

logger.info('My Message');

Custom file extension

import { FileLogger } from '@project-reporter/file-logger';

const logger = new FileLogger();

logger.setLogFileExt('txt');

logger.info('My Message');

Custom encoding

import { FileLogger } from '@project-reporter/file-logger';

const logger = new FileLogger();

logger.setEncoding('UTF-16'); // UTF-8 by default.

logger.info('My Message');

Format function

import { FileLogger } from '@project-reporter/file-logger';

const logger = new FileLogger();

logger.setFormat((level, timestamp, message, ...meta) => {
  return `[${timestamp}] ${level}: ${message} ${meta.join(' ')}`;
});

logger.info('My Message');

More Advanced Usage

Evironment based logging.

import { Reporter } from '@project-reporter/core';
import { FileLogger } from '@project-reporter/file-logger';

const reporter = new Reporter();

// development only logger.
reporter.addLogger(
  new FileLogger(),
  'DEVELOPMENT_LOGGER', // this name is an identifier.
  'development' // notice that the third parameter is the name of the environemt.
);

// production only logger.
reporter.addLogger(
  new FileLogger(),
  'PRODUCTION_LOGGER', // this name is an identifier.
  'production' // notice that the third parameter is the name of the environemt.
);

reporter.info('My Message');

Multiple loggers

import { Reporter } from '@project-reporter/core';
import { FileLogger } from '@project-reporter/file-logger';

const reporter = new Reporter();

reporter.addLogger(new FileLogger().setLogFileExt('log'));

reporter.addLogger(new FileLogger().setLogFileExt('txt'));

reporter.info('My Message'); // message will be appended to both files at the same time.

JSON based logs.

import { jsonFormat } from '@project-reporter/json-format';
import { FileLogger } from '@project-reporter/file-logger';

const logger = new FileLogger()
  .setFormat(jsonFormat)
  .setLogFileName('report') // set the file name you want.
  .setLogFileExt('json');

logger.info('My Message'); // log to "report.json" file.

Yaml based logs.

import { yamlFormat } from '@project-reporter/yaml-format';
import { FileLogger } from '@project-reporter/file-logger';

const logger = new FileLogger()
  .setFormat(yamlFormat)
  .setLogFileName('report') // set the file name you want.
  .setLogFileExt('yaml');

logger.info('My Message'); // log to "report.yaml" file.

XML based logs.

import { xmlFormat } from '@project-reporter/xml-format';
import { FileLogger } from '@project-reporter/file-logger';

const logger = new FileLogger()
  .setFormat(xmlFormat)
  .setLogFileName('report') // set the file name you want.
  .setLogFileExt('xml');

logger.info('My Message'); // log to "report.xml" file.

Error Reporting

By default errors will be logged as '${error.message}\n${error.stack}'.

BUT, when using any of the custom formats JSON, Yaml, XML, etc. Errors will be parsed to a valid syntax based on the extension, including the stack trace.

For instance

import { yamlFormat } from '@project-reporter/yaml-format';
import { FileLogger } from '@project-reporter/file-logger';

const logger = new FileLogger().setFormat(yamlFormat).setLogFileExt('yaml');

logger.error(new Error('Something wrong'));

Will give you the output below

---
level: ERROR
timestamp: '2022-08-07 15:12:22'
message: 'Something wrong'
stack:
  - file: 'test.js'
    method: Object.<anonymous>
    position:
      line: 5
      column: 59
  - file: 'internal/modules/cjs/loader.js'
    method: Module._compile
    position:
      line: 689
      column: 30
  - file: 'internal/modules/cjs/loader.js'
    method: Object.Module._extensions..js
    position:
      line: 700
      column: 10
    # ...

Note

If for some reason this implementation doesn't suit your use case you can use the IFileLogger from the core package to build your own implementation.

Contributing

See Contribution Guidelines

Credits

Thanks Daniele Ricci for the package rotating-file-stream ❤️