Skip to main content

Getting Started with xPack Logger

licence GitHub Repo stars

Guides

The site has a separate guide for each audience:

This project provides a TypeScript Node.js ES module with a re-entrant console logger suitable for REPL/server/multi-instance use cases.

note

The @xpack/logger package is an ES module only, without a CommonJS build. CommonJS applications can load it with require(), in the versions of Node.js that support loading ES modules, or with a dynamic import().

The open-source project is hosted on GitHub as xpack/logger-ts and is published on npmjs.com as @xpack/logger.

Installation​

@xpack/logger is an npm package available from the npmjs.com public registry and may be installed via npm.

tip

The most straightforward method to obtain the installation command is from the website's homepage. Simply hover the mouse over the command, and a copy button will appear on the right side. Click it to copy the command.

For detailed installation instructions, please visit the Installation Guide page.

Status​

The @xpack/logger module is fully functional and stable.

This module is primarily intended to be included in projects like the xpm CLI application.

Testing​

The library is subject to continuous integration (CI) testing with every push using GitHub Actions. This ensures compatibility and stability across Ubuntu, macOS, and Windows operating systems.

Release schedule​

There are no scheduled releases; the project employs a continuous release approach, with updates deployed as development progresses.

Releases​

The list of releases is available on the Releases page.

Change log​

The release notes and the change log are in the CHANGELOG.md file of the repository.

Support and feedback​

Use GitHub Discussions for support and feedback.

For more information, see the Help Centre page.

Compatibility notices​

According to SemVer rules:

Major version X (X.y.z | X > 0) MUST be incremented if any backwards incompatible changes are introduced to the public API.

The breaking changes introduced in each major release are documented in reverse chronological order. The details are in the respective release notes.

v7.0.0​

Breaking changes​

Breaking change: the package is now an ES module only; the CommonJS build, with the ES6 wrapper of v6, was removed.

Breaking change: the minimum Node.js version is now 22.12, the first version of the 22 line that loads ES modules with require() by default (the previous versions fail with ERR_REQUIRE_ESM). ES module projects need no change. CommonJS projects can keep using require('@xpack/logger') on Node.js 22.12 or later, or use await import('@xpack/logger').

Breaking change: an invalid log level, passed to the constructor, to the level setter, or to isLevel(), now throws a RangeError (for a string that is not a level name) or a TypeError (for a value that is not a string), with a message that lists the valid names, instead of an AssertionError with the message Log level 'xyz' not supported. (or, for an empty value, the generic message The expression evaluated to a falsy value). Code that catches AssertionError to detect an invalid level must catch these errors instead; to avoid the exception, check the value first with the new Logger.isLogLevel().

Breaking change: a console without the log() or the error() function, passed to the Logger constructor, now throws a TypeError instead of an AssertionError; the messages are unchanged. Code that catches AssertionError to detect an invalid console must catch TypeError instead.

Breaking change: the Logger constructor no longer logs the line trace: Logger.constructor() when the log level is trace or all. If your tests counted the lines captured by a mock console, or compared them with the lines of the previous versions, remove this line from the expected results.

Breaking change: the static members of Logger are now constants. In TypeScript, Logger.recommendedLevel, Logger.numericLevels (and its properties), Logger.numericLevelUndefined, and Logger.numericLevelAlways are readonly, and the numeric levels have literal types; at run time the Logger class and the numericLevels object are frozen, so an assignment to any of them, or adding a member, throws a TypeError, instead of silently changing the behaviour of all the loggers in the process (for example Logger.numericLevels.debug = 0 made debug() write at the info level). Code that changes these members must stop; to change the level of a logger, set its level. A subclass must not assign to the inherited static members.

Breaking change (compile time only): the type of the level setter is now LogLevel, not LogLevel | undefined, so TypeScript code that assigns undefined to log.level no longer compiles. Such an assignment was already rejected at run time (with a TypeError since this version), so the code was wrong; to use a level that may be missing, check it with Logger.isLogLevel() first. The getter still returns LogLevel | undefined. The level and console constructor options now accept an explicit undefined, also with exactOptionalPropertyTypes, which is not a breaking change.

Breaking change (compile time only): when the type argument of Logger is given explicitly, with a type that the global console does not satisfy (for example Logger<MockConsole>), the console option is now required, since otherwise the console accessor returned an object that was not of that type. Code that omitted the console was wrong, and fails to compile now; pass the console, or drop the type argument.

Deprecations​

The accessors that check the log level have new names, isErrorEnabled, isWarnEnabled, isInfoEnabled, isVerboseEnabled, isDebugEnabled, isTraceEnabled, and isAllEnabled, which say that they tell whether the messages of a level are output, not whether the level is equal to it. The previous names, isError, isWarn, isInfo, isVerbose, isDebug, isTrace, and isAll, are deprecated (this is not a breaking change): they still work, with the same behaviour, and will be removed in the next major version.

If used, replace them:

if (log.isDebugEnabled) {
// ...
}

The TypeScript module resolution mode node10, which ignores the exports map, is still supported through the legacy main and typings fields of package.json, but it is deprecated: support for node10 will be removed in a future major release. Projects that use it, usually the ones with "module": "commonjs" and no explicit moduleResolution, should migrate to node16, nodenext, or bundler. This is not a breaking change in this version.

Logger.defaultLevel was renamed Logger.recommendedLevel, because the old name suggested that a logger created without a level gets that level, which the library never did: the logger stays in the preliminary state. The old name is kept, with the same value, and is deprecated: it will be removed in the next major version, so replace it with Logger.recommendedLevel (this is not a breaking change in this version).

The state of the logger is now private (ES private fields), so it is no longer a property of the object: Object.keys(log) and JSON.stringify(log) no longer show the internal fields. The protected members that gave the subclasses direct access to it, _console, levelNumericValue, levelName, and buffer, are deprecated: they still work, with the same behaviour, but they will be removed in the next major version, so a subclass should use the public console, level, hasLevel, and isLevel() members. The supported extension point of a subclass is the protected write() method, which is now documented, with the types NumericLogLevel and LoggerFunction of its signature. This is not a breaking change in this version.

The isSilent accessor was deprecated (this is not a breaking change). Since silent is the lowest level, it was always true, for every level, so it could not tell whether the logger is silent. It will be removed in the next major version.

If used, replace it with a comparison of the log level name:

if (log.level === 'silent') {
// ...
}

Additions​

The package.json file is now exported, so tools can read it through the package name (@xpack/logger/package.json); this is not a breaking change.

The console option of the constructor now accepts any object that has the log() and error() functions (the new exported type LoggerConsole), not only a Node.js Console, so a mock or a minimal { log, error } object no longer needs a cast. The Logger class has a new type parameter, the type of the console, which the console accessor returns; its default is the Node.js Console, so the existing code is not affected (this is not a breaking change).

The new boolean option timestamp of the constructor makes the messages of error(), warn(), debug(), and trace(), the methods that have a prefix, start with a timestamp in the local time, with milliseconds, and replaces the prefix by the kind in square brackets (for example 2026-11-11 23:32:31.358 [warning] oops, instead of warning: oops). It is off by default, so the existing output does not change (this is not a breaking change). The timestamp accessor returns its value.

The published declaration files (.d.ts) now include the TSDoc comments of the library, so editors show the documentation, and the deprecations of this version (like the strike-through of isSilent and defaultLevel); before, the comments were removed by the compiler. The compiled JavaScript files still have no comments.

v6.0.0​

The TypeScript code is compiled into CommonJS modules, with an ES6 wrapper, and can be consumed by both TypeScript and JavaScript packages.

There were also some minor internal renames, but this should not be a problem.

The function isLevel(level) was added.

v5.0.0​

For consistency reasons, hasLevel was changed from a method to an accessor.

Internally, the log level starts as undefined instead of the string 'undefined', as in previous versions.

This should not be a problem: to check if the level was set, use the accessor hasLevel.

v4.0.0​

The code was migrated to TypeScript.

The migration itself should not introduce any incompatibilities, actually it should be fairly compatible with the latest v3.x, but, for just in case, the safer path was to consider it a major release.

v3.0.0​

All isXyx functions (returning a boolean related to the log level) were changed to accessors.

v2.0.0​

The logger constructor was changed to use a generic parameters object.

If upgrading from previous versions, change the syntax from:

const log = new Logger(console, 'info')

to:

const log = new Logger({
console,
level: 'info'
})

Licence​

Unless explicitly stated otherwise, the original content is distributed under the terms of the MIT License, with all rights reserved by Liviu Ionescu.

MacStadium

Credits​

Special thanks to MacStadium for providing the Apple Silicon development infrastructure as part of their generous Free and Open Source Software programme.

Thanks to Shields IO for the badges and SVG REPO for the SVG icons.

Support the project​

If you find this project useful, you can support it in the following ways:

  • Donate: every contribution, regardless of size, helps sustain the xPack project.
  • Star the project on GitHub: a star helps other developers to find the project.
  • Follow the project on X/Twitter: new releases and other announcements are posted there.