loxer

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

★ 15 Open GitHub ↗

A middleware logger that helps you make informational beauitiful logs exactly when you need them and in a way that it would be unnessecary to delete them.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

![Loxer_Logo](https://raw.githubusercontent.com/pcprinz/loxer/master/assets/Logo.png)

# Loxer ![GitHub release (latest by date)](https://img.shields.io/github/v/release/pcprinz/loxer) ![GitHub Release Date](https://img.shields.io/github/release-date/pcprinz/loxer) ![GitHub branch checks state](https://img.shields.io/github/checks-status/pcprinz/loxer/master?label=build) ![npm bundle size](https://img.shields.io/bundlephobia/min/loxer) ![GitHub](https://img.shields.io/github/license/pcprinz/loxer)

**Loxer** is a middleware logger that allows you to:

- distribute logs to different output streams (dev / prod / log / error)
- write logs at a level (`error` / `warn` / `info` / `debug`)
- categorize logs in modules (each logging up to its own threshold)
- connect logs to each other to "boxes"
- improve error logs (with more information)
- get significantly better visualization of the logs
- visualize the data flow (including time measurement)
- full Typescript support
- rich output of values (props) for debugging purposes

With Loxer, logs never have to be deleted again, as they hardly use any resources when switched off. Logs and error records can easily be forwarded to crash reporting systems such as Firebase. This makes it possible to get error reports that are just as good in the production environment as in the development environment. Furthermore, errors in concurrent functional processes can be detected more easily.

## Documentation

The **[API Reference](https://pcprinz.github.io/loxer/index.html)** provides a complete overview of all the features of the package. Furthermore, the complete source code is documented with js-doc and typed with typscript, which guarantees full IDE support.

The **[Documentation](https://github.com/pcprinz/loxer/blob/master/documentation/index.md)** contains detailed instructions on how to use the package.

The **[Performance Tests](https://github.com/pcprinz/loxer/blob/master/documentation/Performance.md)** documents how small the influence of the package is on the performance of an application.

## Usage

Write logs in an intuitive way:

```typescript
// initialize it somewhere (once) -> singleton
Loxer.init();

// simple log
Loxer.log('my message');

// highlight logs
Loxer.highlight().log('my message');

// use different levels
Loxer.error('that is serious');
Loxer.warn('still working, but something is wrong');
Loxer.info('an alias for .log(...)');
Loxer.debug('just informative');

// set modules
Loxer.module('AUTH').log('user logged in');

// use boxes
const lox = Loxer.open('opening log');
Loxer.of(lox).add('appended log');
Loxer.of(lox).error('appended error');
Loxer.of(lox).close('closing log');

// combine everything like you want
Loxer.module('AUTH').highlight().debug('highlighted debug log for module Authentication');

// use shortcuts for the methods - every level opens a box too
const lox2 = Loxer.h().m('AUTH').debug.open('highlighted debug box for module Authentication');
```

For a complete guide on how to use everything, definitely take a look at the **[Documentation](https://github.com/pcprinz/loxer/blob/master/documentation/index.md)**

## Plain-function tracing

Loxer can open and close a trace box automatically around a named plain function during the build.
This requires Loxer 3, Babel 8, and Node 22.18 or newer for the tracing plugin.

```sh
pnpm add loxer
pnpm add -D @babel/core @babel/preset-typescript babel-plugin-loxer-trace
```

```js
// babel.config.mjs
export default {
  presets: ['@babel/preset-typescript'],
  plugins: ['babel-plugin-loxer-trace'],
};
```

Initialize Loxer with every module that a trace or log uses, then import `trace` from
`loxer/trace` and put its marker immediately after the named function binding:

```ts
import { Loxer } from 'loxer';
import { trace } from 'loxer/trace';

Loxer.init({
  modules: {
    ORDER: { color: '#00ff99', fullName: 'Order', devLevel: 'info', prodLevel: 'error' },
  },
});

function submitOrder(orderId: string) {
  Loxer.m('ORDER').log(`Submitting ${orderId}`);
  return orderId;
}

trace.info(submitOrder, { moduleId: 'ORDER', openMessage: 'parent.fn(args)' });
```

`openMessage` defaults to `parent.fn`; `closeMessage` defaults to `fn`. The payload templates are
`fn(args)`, `parent.fn(args)`, `fn(types)`, `parent.fn(types)`, `fn(result)`, and
`parent.fn(result)`.

To trace several functions the same way, pass an array literal of them and the options they share:

```ts
trace.info([submitOrder, cancelOrder], { moduleId: 'ORDER', openMessage: 'parent.fn(args)' });
```

`trace.info()` is a build-time marker, not a runtime wrapper. Every module that executes a marker must
pass through the Babel plugin; otherwise the marker throws to signal a missing build configuration.

For Vite, add the adapter and register it as a normal Vite plugin:

```sh
pnpm add -D vite-plugin-loxer-trace
```

```ts
// vite.config.ts
import { defineConfig } from 'vite';
import loxerTrace from 'vite-plugin-loxer-trace';

export default defineConfig({
  plugins: [loxerTrace()],
});
```

See the [plain-function tracing guide](https://github.com/pcprinz/loxer/blob/master/documentation/index.md#plain-function-tracing)
and the [Babel plugin README](https://github.com/pcprinz/loxer/blob/master/packages/babel-plugin-loxer-trace/README.md)
for supported function shapes, options, and transform details.

### Context-aware trace points

`trace.point` writes one contextual log inside a named function without opening another box. It is a
build-time marker, so its module must pass through the same Babel or Vite plugin as `trace.info()`.

```ts
function submitOrder(orderId: string) {
  trace.point.ORDER.info('fn', 'Submitting order', orderId);
  trace.point.info(({ parentFn }) => `${parentFn('saved')}`, orderId);
}
```

Point terminals are `error`, `warn`, `log`, `info`, and `debug`. Use `fn` or `parent.fn` as the first
argument to prefix a message with the inferred name; a callback receives `fn` and `parentFn` printers.
Values after the message are props. Point errors are normal error-level logs on the log stream; use
`Loxer.error()` for an error event. An untransformed point throws a missing-transform error.

## Preview Example

Consider the following log output (without the log date):

![plain_console](https://raw.githubusercontent.com/pcprinz/loxer/master/assets/docs_images/plainOutput.png)

As you can see the logs might tell something considering you know where they come from and what they do, but obviously they seem to be pretty uninformative.

Let's see what Loxer can do about this:

![plain_console](https://raw.githubusercontent.com/pcprinz/loxer/master/assets/docs_images/goodOutput.png)

The log messages are exactly the same, but with a litte configuration you can see what is happening in the application. Even if you are not familiar with the code you can follow the implemented data flow by just one sight.

> Watch this [comparison with a slider](https://cdn.knightlab.com/libs/juxtapose/latest/embed/index.html?uid=9e14a828-2f7d-11ec-abb7-b9a7ff2ee17c)

## Installation

`npm i --save loxer`, `pnpm add loxer`, or `yarn add loxer` thats it.

## Deps

none - Loxer ships with zero runtime dependencies.

loxer

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README