LogTape 0.6.0 released: What's new?

LogTape, a zero-dependency structured logging library for JavaScript and TypeScript, has released v0.6.0. What has changed?

Overriding parent logger's sinks

One of LogTape's features is inheritance of sinks through hierarchical categories. For example, if you set up two loggers like this:

import { configure, getConsoleSink, getFileSink } from "@logtape/logtape";

await configure({
  sinks: {
    console: getConsoleSink(),
    file:    getFileSink("app.log"),
  },
  loggers: [
    { category: ["app"],           level: "debug", sinks: ["file"] },
    { category: ["app", "module"], level: "debug", sinks: ["console"] },
  ],
});

Logs written to the ["app"] logger will only be saved to the app.log file, but logs written to the ["app", "module"] logger will be saved to both the app.log file and output to the console. This is because the ["app", "module"] logger inherits the sinks from its parent category ["app"].

However, sometimes you might not want this behavior. Starting from LogTape 0.6.0, you can now override the parent logger's sinks. For example, if you enable the parentSinks: "override" option for the child logger like this:

await configure({
  sinks: { /* omitted; same as above */ },
  loggers: [
    { category: ["app"],           level: "debug", sinks: ["file"] },
    { category: ["app", "module"], level: "debug", sinks: ["console"], parentSinks: "override" },
  ],
});

Logs written to the ["app"] logger will only be saved to the app.log file, and logs written to the ["app", "module"] logger will only be output to the console. This is because the child logger ["app", "module"] has overridden the sinks of the ["app"] logger.

Of course, the default value is parentSinks: "inherit", so if you don't specify the option, it will behave as before.

If you're curious about the background of this feature addition, please refer to GitHub issue #15.

Allow leading/trailing spaces for placeholders in message templates

In previous versions, if you logged like this:

logger.info("Hello, { name }!", { name: "Alice" });

Contrary to expectations, a log of Hello, undefined! would be created. This was because the placeholder { name } included space characters, so it looked for a property " name " instead of "name". In other words, you had to either remove the spaces from the placeholder like this:

logger.info("Hello, {name}!", { name: "Alice" });

Or add the same spaces to the actual property name like this:

logger.info("Hello, { name }!", { " name ": "Alice" });

While this wasn't strictly a bug, it was behavior prone to mistakes depending on coding habits.

However, starting from LogTape 0.6.0, even if there are spaces at the beginning and end of the placeholder, it will look for a property name without spaces. For example, if you log like this:

logger.info("Hello, { name }!", { name: "Alice" });

As expected, a log of Hello, Alice! will be created.

However, if there is a property that exactly matches including the space characters, that will be prioritized. For example, if you log like this:

logger.info("Hello, { name }!", { name: "Alice", " name ": "Bob" });

Hello, Bob! will be logged instead of Hello, Alice!.

If you're curious about the background of this feature addition, please refer to GitHub issue #16.

LogRecord.rawMessage property

LogRecord is a data type that represents a log before it is output and formatted by LogTape.

While the LogRecord.message property already existed, this property contained the result after the placeholders in the message template had been replaced with actual property values. This was sufficient in most cases, but when the log output destination (sink) is another logging system, you might want to output the original message template and property values separately, allowing the receiving logging system to replace the placeholders in the message template with property values directly.

The LogRecord.rawMessage added in LogTape 0.6.0 is a property for exactly this purpose, containing the original state of the message template with placeholders unreplaced. For example, if you log like this:

logger.info("Hello, {name}!", { name: "Alice" });

While LogRecord.message will contain the value ["Hello, ", "Alice", "!"], LogRecord.rawMessage will contain the value "Hello, {name}!".

If you're curious about the background of this feature addition, please refer to GitHub issue #17.

Customizable built-in text formatters

A text formatter is an interface that determines how each log will be formatted into text in stream sinks, file sinks, etc. The actual type definition is quite simple:

export type TextFormatter = (record: LogRecord) => string;

However, it can be cumbersome to define a text formatter directly every time, so LogTape has built-in defaultTextFormatter and ansiColorFormatter that you can use. Until now, because no additional configuration was possible, you had to accept the predetermined format as is. For example, if you didn't like that log levels like "warning" were output as three-letter abbreviations like WRN, you had to implement TextFormatter from scratch.

However, starting from LogTape 0.6.0, you can customize various formatting settings to your liking through the getDefaultTextFormatter() and getAnsiColorFormatter() functions without having to implement TextFormatter from scratch.

For example, if you want to represent log levels like "warning" as a single uppercase letter W, you can configure it like this:

const myFormatter = getDefaultTextFormatter({ level: "L" });

Or if you want to omit the date and timezone from the timestamp and only show the time, you can configure it like this:

const myFormatter = getDefaultTextFormatter({ timestamp: "time" });

For descriptions of more formatting options, please refer to the related documentation.

If you're curious about the background of this feature addition, please refer to GitHub issue #13.

Get it from JSR and npm

LogTape 0.6.0 is already available on JSR and npm, so get it now!

deno add @logtape/logtape@0.6.0  # Deno
npm  add @logtape/logtape@0.6.0  # npm
pnpm add @logtape/logtape@0.6.0  # pnpm
yarn add @logtape/logtape@0.6.0  # Yarn
bun  add @logtape/logtape@0.6.0  # Bun

Happy logging!