@mfdlabs/logging

Logger implementation that follows the MFDLABS LOGDEV Standards.

Example

TypeScript

// The logger can be imported like this:
import logger from "@mfdlabs/logging";
// Or this:
import { logger } from "@mfdlabs/logging";

// You can use the following member if you do not require another logger:
logger.singleton.log("Example message");
logger.singleton.log("Example message with formatting: %d", 123);

// If you require a custom name, or just a seperate logger:
const newLogger = new logger("custom-logger");

newLogger.log("Hello from custom logger!!!!");

Exports

The package exports the following:

/* An enum containing log levels that can be input into the logger class constructor or logger.logLevel method. */
enum LogLevel { /* ... */ };

/* The main implementation for the logger class. */
class logger { /* ... */ };

Constructor

You can either use logger.singleton or logger.noopSingleton to access the logger. If you require something different use the following constructor parameters:

Argument Name	Argument Type	Default Value	Description
name	string	Required	The name of this new logger. It cannot be the same as an already existing logger or it will throw.
logLevel	LogLevel	LogLevel.Info	The log level for this new logger. It must be a string if you are not using the LogLevel enum and must be a valid member of that enum.
logToFileSystem	boolean	true	Should the logger create log files? If this is true and EACCES or EPERM is emitted it is auto disabled. You an override the default log directory via DEFAULT_LOG_FILE_DIRECTORY.
logToConsole	boolean	true	Should the logger log to the console? This will automatically be disabled if there is no TTY found. Advised to not be used if you are running as a daemon.
cutLogPrefix	boolean	true	Should the logging prefix be cut? It is advised that this is used in production environments as it reduces the resources used by loggers.
logWithColor	boolean	true	Should the ouput be colorful? It is advised that this is disabled in production as it creates larger strings in order to make them colorful.

Properties

The following properties are available for the logger class:

Property Name	Property Type	Has Setter?	Is Static?	Description
singleton	logger	No	Yes	A static instance of the logger, it is advised you use this over creating new loggers if you don't require logs to be seperated by category.
noopSingleton	logger	No	Yes	Essentially the same as logger.singleton except this will do nothing, i.e the logLevel is None, and it doesn't log the the console or log files.
name	string	Yes	No	The name of the logger, you can change this at runtime if you wish, but it must be a unique name.
logLevel	LogLevel	Yes	No	The level of the logger, you can change this at runtime but it must be a valid LogLevel enum.
logToFileSystem	boolean	Yes	No	Is this logger writing to log files? This can be changed at runtime and will setup log files when the value is set or will teardown it's current file stream if unset.
logToConsole	boolean	Yes	No	Is this logger writing to the console? This can be changed at runtime.
cutLogPrefix	boolean	Yes	No	Is the logger's prefix being cut? This can be changed at runtime and is advised for production environments as log prefixes can get lengthy.
logWithColor	boolean	Yes	No	Is the logger's console output colorful? This can be changed at runtime and is advised to be disabled in production environments as it extends the log string with invisible characters.
fileName	string	No	No	The name of the file that the file system logger is writing to. This is only set if logger.logToFileSystem is enabled and didn't fail to create the log file.
fullyQualifiedLogFileName	string	No	No	The fully qualified name of the file that the file system logger is writing to. Essentially the same as logger.fileName except this includes the full path.
globalPrefixEntries	(() => string)[]?	Yes	Yes	A list of getters that will be prepended before the log level in the logger message for all loggers.
customPrefixEntries	(() => string)[]?	Yes	No	A list of getters that will be prepended before the log level in the logger message for the specific logger.

Methods

The following methods are made available for you to use. All "log" methods use the same set of arguments, the first being the format string, or a method that returns a string and then the next being a vararray of "any". All of the log methods are also asynchronous and be called without blocking the main thread.

logger.{logMethod}(string|() => string, ...any[]);

Method Name	Return Type	Is Asynchronous?	Is Static?	Description
tryClearLocalLog	void	No	Yes	A static method that tries to clear out the log file directory and reset all registered loggers. This is not advised as there could potentially be a logger that is writing the the directory from a non-managed app and this doesn't filter those out (TBD FUTURE). There is an environment variable that controls whether or not this method actually clears the folder or not, and this method has an argument to override that environment variable.
tryClearAllLoggers	void	No	Yes	A static method that tries to remove all tracked loggers from the current environment. This needs to set a property on loggers that determines if they're disposed or not, please PPEC when this idea becomes true. Does not dispose of the singleton and noopSingleton loggers.
log	void	Yes	No	The log method invokes an asynchronous log with the log level of Info.
warning	void	Yes	No	The warning method invokes an asynchronous log with the log level of Warning.
trace	void	Yes	No	The trace method invokes an asynchronous log with the log level of Trace.
debug	void	Yes	No	The debug method invokes an asynchronous log with the log level of Debug.
information	void	Yes	No	The information method invokes an asynchronous log with the log level of Info.
error	void	Yes	No	The error method invokes an asynchronous log with the log level of Error.

Environment variables

This logging utility utilizes @mfdlabs/environment to setup it's default singleton logger. The following environment variables are available to you to modify the default behavior:

Environment Variable Name	Environment Variable Type	Default Value	Description
PERSIST_LOCAL_LOGS	boolean	false	If you set this environment variable, the logger will persist it's log files even if a clearance is requested. This can be overridden in the logger.clearLocalLog method with the 'override' parameter.
DEFAULT_LOGGER_CUT_PREFIX	boolean	true	If true, then the logger will cut the prefix of the log message in order to read the log message more easily. This is advised to always be set in production if you use the singleton logger.
DEFAULT_LOGGER_NAME	string	"singleton-logger"	The default name of the singleton logger. When changing this you need to make sure it is a valid name or the getter for logger.singleton and logger.noopSingleton will throw!
DEFAULT_LOGGER_LOG_TO_FILE_SYSTEM	boolean	true	If true, the singleton logger will log to the file system by default.
DEFAULT_LOGGER_LOG_TO_CONSOLE	boolean	true	If true, the singleton logger will log to the console by default.
DEFAULT_LOG_LEVEL	LogLevel	Info	The default log level for the singleton logger. This is advised to be set to something low in production environments.
DEFAULT_LOG_FILE_DIRECTORY	string	null	The default log file directory, if this is unset it will place all log files in inside a folder called "logs" on your project root, or if you installed it globally it will write to a folder called "logs" in your global npm folder.