Getting Started with xPack Logger
The site has a separate guide for each audience:
- the Installation Guide;
- the User's Guide;
- the Contributor's Guide;
- the Maintainer's Guide.
This project provides a TypeScript Node.js ES module with a re-entrant console logger suitable for REPL/server/multi-instance use cases.
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.
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.
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: