signale

Signale is a highly customizable logging library used for logging, status reporting, and managing output visibility for modules and applications.

Key features include:

• 19 ready-to-use loggers.
• Fully customizable output and aesthetics.
• Built-in timestamps and support for file names, dates, and times.
• Scoped loggers and timestamps.
• Support for TypeScript and string interpolation.
• Interactive and regular modes.
• Secret and sensitive information filtering.
• Scalable logging level mechanism.
• Support for multiple writable streams.
• Global configuration via package.json with file-level or logger-level overrides.

Import signale to access a set of pre-defined loggers. These loggers allow you to categorize your logs with different visual styles and severity levels.

const signale = require('signale');

signale.success('Operation successful');
signale.debug('Hello', 'from', 'L59');
signale.pending('Write release notes for %s', '1.2.0');
signale.fatal(new Error('Unable to acquire lock'));
signale.watch('Recursively watching build directory...');
signale.complete({prefix: '[task]', message: 'Fix issue #59', suffix: '(@klaudiosinani)'});

Install the signale package using npm to start using its extensible logging capabilities.

npm install signale

To enable local configuration, call the config() method on a signale instance. Local configurations always override any settings inherited from package.json or parent instances.

Scoped loggers created via .scope() can also have their own independent configurations that override both the parent instance and package.json.

const signale = require('signale');

// Overrides package.json configuration
signale.config({
  displayFilename: true,
  displayTimestamp: true,
  displayDate: false
}); 

signale.success('Hello from the Global scope');

function foo() {
  // fooLogger inherits from signale
  const fooLogger = signale.scope('foo scope');

  // Overrides both signale and package.json
  fooLogger.config({
    displayFilename: true,
    displayTimestamp: false,
    displayDate: true
  });

  fooLogger.success('Hello from the Local scope');
}

foo();

You can install the signale library using either Yarn or NPM to add highly configurable logging capabilities to your Node.js applications.

yarn add signale
# or
npm install signale

To override global package.json settings for a specific instance or file, use the config() method. Local configurations always take precedence over global ones. Scoped loggers can also have their own independent configurations that override both the parent instance and the global settings.

const signale = require('signale');

// Overrides any existing package.json configuration
signale.config({
  displayFilename: true,
  displayTimestamp: true,
  displayDate: false
}); 

signale.success('Hello from Global Scope');

By default, Signale logs to process.stdout. You can change this globally via the stream option in the Signale constructor, or specify different streams for individual logger types within the types configuration.

const {Signale} = require('signale');

const options = {
  stream: process.stderr, // All loggers will write to stderr
  types: {
    error: {
      // Only 'error' will write to both stdout and stderr
      stream: [process.stdout, process.stderr]
    }
  }
};

const signale = new Signale(options);
signale.success('Mesazhi do të shfaqet në `process.stderr`');
signale.error('Mesazhi do të shfaqet në të dy `process.stdout` & `process.stderr`');

You can create a new Signale instance with custom loggers by defining a types object in the options argument. Each type can specify a badge, label, color (using chalk colors), and logLevel.

const {Signale} = require('signale');

const options = {
  disabled: false,
  interactive: false,
  logLevel: 'info',
  scope: 'custom',
  secrets: [],
  stream: process.stdout,
  types: {
    remind: {
      badge: '**',
      color: 'yellow',
      label: 'reminder',
      logLevel: 'info'
    },
    santa: {
      badge: '🎅',
      color: 'red',
      label: 'santa',
      logLevel: 'info'
    }
  }
};

const custom = new Signale(options);
custom.remind('Improve documentation.');
custom.santa('Hoho! You have an unused variable on L45.');

By setting interactive: true in the Signale options, you enable interactive mode. In this mode, previous messages from the same or other interactive loggers are overwritten by new messages, allowing for dynamic UI updates in the terminal (e.g., progress bars). Regular (non-interactive) loggers are not overwritten by interactive ones.

const {Signale} = require('signale');

const interactive = new Signale({interactive: true, scope: 'interactive'});

interactive.await('[%d/4] - Procesi A', 1);

setTimeout(() => {
  interactive.success('[%d/4] - Procesi A', 2);
  setTimeout(() => {
    interactive.await('[%d/4] - Procesi B', 3);
    setTimeout(() => {
      interactive.error('[%d/4] - Procesi B', 4);
      setTimeout(() => {}, 1000);
    }, 1000);
  }, 1000);
}, 1000);

By default, logs go to process.stdout. You can set a global stream for the instance, or define specific streams for individual logger types within the types configuration.

const {Signale} = require('signale');

const options = {
  stream: process.stderr, // All loggers write to stderr
  types: {
    error: {
      // Only 'error' writes to both stdout and stderr
      stream: [process.stdout, process.stderr]
    }
  }
};

const signale = new Signale(options);

Use the secrets option to automatically redact sensitive information. Any value provided in the secrets array (case-sensitive) will be replaced with the string '[secure]' in both the message body and metadata (like scope names).

New scopes created via .scope() inherit the secrets of their parent. You can also use signale.addSecrets() and signale.clearSecrets() to manage them dynamically.

const {Signale} = require('signale');

const [USERNAME, TOKEN] = ['klaudiosinani', 'token'];

const logger1 = new Signale({
  secrets: [USERNAME, TOKEN]
});

logger1.log('$ exporting USERNAME=%s', USERNAME); // Output: $ exporting USERNAME=[secure]

// logger2 inherits secrets from logger1
const logger2 = logger1.scope('parent');
logger2.log('$ exporting TOKEN=%s', TOKEN); // Output: $ exporting TOKEN=[secure]

Loggers created with scope() can have their own independent configuration, which overrides both the global signale configuration and the package.json settings.

const signale = require('signale');

// Global override
signale.config({
  displayFilename: true,
  displayTimestamp: true,
  displayDate: false
});

function foo() {
  // `fooLogger` inherits the config of `signale`
  const fooLogger = signale.scope('foo scope');

  // Overrides both `signale` and `package.json` configs
  fooLogger.config({
    displayFilename: true,
    displayTimestamp: false,
    displayDate: true
  });

  fooLogger.success('Hello from the Local scope');
}

foo();