https://github.com/vseplet/luminous
Extremely configurable logger for Deno and Node.js
https://github.com/vseplet/luminous
deno formatter log log4j logger logging logs transport ts typescript
Last synced: 3 months ago
JSON representation
Extremely configurable logger for Deno and Node.js
- Host: GitHub
- URL: https://github.com/vseplet/luminous
- Owner: vseplet
- License: mit
- Created: 2023-01-27T22:28:05.000Z (over 3 years ago)
- Default Branch: main
- Last Pushed: 2026-01-04T08:23:36.000Z (6 months ago)
- Last Synced: 2026-02-25T04:04:01.454Z (4 months ago)
- Topics: deno, formatter, log, log4j, logger, logging, logs, transport, ts, typescript
- Language: TypeScript
- Homepage: https://jsr.io/@vseplet/luminous
- Size: 163 KB
- Stars: 2
- Watchers: 1
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# luminous
[](https://jsr.io/@vseplet/luminous)
[](https://github.com/vseplet/luminous/pulse)
[](https://github.com/vseplet/luminous/commits/main)
## 👋 👋 ATTENTION!
> This package is under development and will be frequently updated. The author
> would appreciate any help, advice, and pull requests! Thank you for your
> understanding 😊
Luminous is a extremely configurable logger for Deno written in TypeScript. It
provides a simple and flexible way to log events and messages in Deno
applications with various levels of severity. With Luminous, developers can
configure the logger to meet their specific needs and customize the logging
format to suit their preferences.
### Usage
```ts
import luminous from "jsr:@vseplet/luminous@1.0.6";
const log = new luminous.Logger();
log.trc`Hello, World!`;
```
## Examples
- different logs by logging levels: [simple.ts](./examples/simple.ts)
```bash
deno task exmaple:simple
```
- inheritance of options when creating new loggers:
[hierarchy.ts](./examples/hierarchy.ts), run:
```bash
deno task exmaple:hierarchy
```
## Contents
- [luminous](#luminous)
- [👋 👋 ATTENTION!](#--attention)
- [Usage](#usage)
- [Examples](#examples)
- [Contents](#contents)
- [Levels](#levels)
- [Logger Options](#logger-options)
- [Transports](#transports)
- [Formatters](#formatters)
- [DONATE](#donate)
- [LICENCE](#licence)
## Levels
Luminous provides eight different logging levels that enable developers to log
events and messages with different levels of severity. Each level is designed to
serve a specific purpose and can help developers troubleshoot issues and debug
complex problems.
0 TRACE:
```ts
log.trc`This is TRACE log message`;
// 01:58:35 [TRC] default: This is TRACE log message
```
The TRACE level is the lowest level of severity in Luminous. This level is used
to log the most detailed information about an application's execution, such as
method calls, function parameters, and variable values. The TRACE level is
useful for debugging complex issues and identifying the root cause of a problem.
1 DEBUG:
```ts
log.dbg`This is DEBUG log message`;
// 01:58:35 [DBG] default: This is DEBUG log message
```
The DEBUG level is used to log debugging information that is useful for
developers during application development. This level can include information
about application flow, execution paths, and other relevant details that can
help developers identify and fix bugs.
2 VERBOSE:
```ts
log.vrb`This is VERBOSE log message`;
// 01:58:35 [VRB] default: This is VERBOSE log message
```
The VERBOSE level is used to log detailed information that is not critical to
the application's operation but can be useful for developers during debugging.
This level includes information about application state, network activity, and
other detailed events.
3 INFO:
```ts
log.inf`This is INFO log message`;
// 01:58:35 [INF] default: This is INFO log message
```
The INFO level is used to log information about the application's operation.
This level includes messages that indicate when the application starts or stops,
when it performs significant operations, or when it encounters events that may
be of interest to developers or system administrators.
4 USER:
```ts
log.usr`This is USER log message`;
// 01:58:35 [USR] default: This is USER log message
```
The USER level is used to log events that are relevant to end-users, such as
login attempts, user actions, and other user-related events. This level is
useful for tracking user behavior and identifying usability issues.
5 WARN:
```ts
log.wrn`This is WARN log message`;
// 01:58:35 [WRN] default: This is WARN log message
```
The WARN level is used to log warnings about potential issues that may affect
the application's operation. This level includes messages about deprecated APIs,
invalid configuration settings, or other issues that may cause unexpected
behavior.
6 ERROR:
```ts
log.err`This is ERROR log message`;
// 01:58:35 [ERR] default: This is ERROR log message
```
The ERROR level is used to log errors that occur during application execution
but are recoverable. This level includes messages about exceptions, timeouts, or
other errors that may require attention but do not necessarily require the
application to stop.
7 FATAL:
```ts
log.ftl`This is FATAL log message`;
// 01:58:35 [FTL] default: This is FATAL log message
```
The FATAL level is used to log critical errors that require immediate attention
and may cause the application to stop. This level includes messages about
unrecoverable errors, such as out-of-memory errors, disk failures, or other
catastrophic events.
## Logger Options
[LoggerOptions](./src/Logger.ts) in Luminous are a set of configurable settings
that enable developers to customize the behavior and functionality of the logger
to meet their specific needs. The [OptionsBuilder](./src/OptionsBuilder.ts)
class in Luminous is a utility class that provides a fluent API for building and
configuring logger options. It allows developers to create and customize
LoggerOptions objects in a flexible and intuitive way, by providing a set of
methods for setting various options. For example:
```ts
const loggerOptions = new luminous.OptionsBuilder()
.setName("Main")
.build();
const logger = new luminous.Logger(loggerOptions);
logger.inf`Hello, World!`;
```
## Transports
The [AbstractTransport](./src/Transport.ts) is the base class for all transports
in Luminous. A transport is responsible for sending formatted log messages to
their final destination, which could be the console, a file, a database, or any
other endpoint. At the moment, Luminous has a
[TerminalTransport](./src/transports/Terminal.ts). For example:
```ts
// Create a new instance of TerminalTransport to send logs to the terminal.
const transport = new luminous.transports.TermianlTransport(),
// Create a new OptionsBuilder instance to configure the logger options.
const loggerOptions = new luminous.OptionsBuilder()
.setName('Main') // Set the name of the logger to 'Main'.
.addTransport(
new luminous.formatters.TextFormatter(),
transport,
) // Add the TextFormatter and TerminalTransport to the logger.
.build(); // Build the final logger options object.
// Create a new logger instance with the configured options.
const logger = new luminous.Logger(loggerOptions);
// Log an information message.
logger.inf(`Hello, World!`);
// 01:58:35 [INF] Main: Hello, World!
```
## Formatters
In Luminous, a [AbstractFormatter](./src/Formatter.ts) is a class that is
responsible for formatting log messages into a human-readable string format. The
[IDataForFormatting](./src/Formatter.ts) interface defines the data that is
passed to the formatter, which includes the name of the logger, the severity
level of the log message, the message itself, and any additional metadata that
may be attached to the message. Currently, Luminous has two basic forrmaters:
[TextFormatter](./src/formatters/TextFormatter.ts) and
[JsonFormatter](./src/formatters/JsonFormatter.ts). For example:
```ts
// Create a new TextFormatter instance that formats log messages as text with metadata and a custom timestamp pattern.
const textFormatter = new luminous.formatters.TextFormatter({
showMetadata: true,
timestampPattern: "yyyy-MM-dd HH:mm:ss",
});
// Create a new OptionsBuilder instance to configure the logger options.
const loggerOptions = new luminous.OptionsBuilder()
.setName("Main") // Set the name of the logger to 'Main'.
.addTransport(
textFormatter,
new luminous.transports.TerminalTransport(),
) // Add the TextFormatter and TerminalTransport to the logger.
.build(); // Build the final logger options object.
// Create a new logger instance with the configured options.
const logger = new luminous.Logger(loggerOptions);
// Log an information message with metadata.
logger.inf(`Hello, World!`, { meta0: "0", meta1: "1" });
// 2023-02-26 01:58:35 [INF] Main: Hello, World! {
// meta0: "0"
// mrta1: "1"
// }
```
## DONATE
🫶 You can support me and my work in the following ways:
**TON**:
`EQBiaSPuG33CuKXHClwsVvA-SazmLmtiTfXV7dQnqJdIlGgI`
**USDT (TRC 20)**
`(TRC20): TGPWzEiQjMYHjZx4fb3SDSumiSXdmjE4ZR`
**BTC**:
`bc1qq37svf4h8sg5qjsv99n9jf3r45dtd5yf5mdpc5`
**ETH**:
`0xAdc58F26cA3dCc01256cF1BeF6221f4bcaa3c660`
**SOL**:
`BckFFoxZw36ABbNS8Fc66LCdzJhu4ZwQANRdq49XmqKw`
## LICENCE
[LGPL-2.1](https://github.com/sevapp/luminous/blob/main/LICENSE)