advanced-logger

What is it?

It is an extendable isomorphic log sending library written in TypeScript for javascript application in nodejs and browsers.

It can be extended with custom strategy ("when to send logs") and service ("where to send logs").

It does not restrict you with conventions, for example, existence of "logSeverity", "ErrorId" or "message" fields in log.

It supports any format of logs via custom serializer.

Features

• :scream_cat: It works in browsers and nodejs
• :articulated_lorry: It is able to send single logs and bundles of them to an external logger
• It supports different log sending strategies:
  1. :alarm_clock: interval (for example, every 10 seconds)
  2. :loudspeaker: on request (only when you ask)
  3. :alarm_clock: :heavy_plus_sign: :loudspeaker: mixed ("interval" + "on request") (will be done soon)
  4. :steam_locomotive: :railway_car: :railway_car: :railway_car: on bundle size (for example, sends bundles of 100 logs)
  5. :toilet: instant (received 1 log -> sent 1 log)
• :busts_in_silhouette: It is able to group duplicated logs in certain time interval (for rapid fire of the same logs)
• :octopus: It is not afraid of circular links in log objects
• :building_construction: It supports custom format for logs (custom serializer)
• :dart: It supports different remote logger endpoints (SumoLogic, Loggly and Elasticsearch). Who is the next? ᕙ(ಠ.ಠ)ᕗ

Runtime environment support :running_woman:

The package ships dual ESM (dist/index.mjs) and CommonJS (dist/index.cjs) builds plus a self-contained browser IIFE global (dist/index.global.js), with type declarations (dist/index.d.ts). HTTP uses the platform's native fetch and all other dependencies are bundled in, so the package has no runtime dependencies.

:robot: NodeJS - developed and tested on Node.js 24 (see .mise.toml); requires Node.js 18+ for global fetch.

:globe_with_meridians: Browser - all latest browsers (native fetch + ES2015).

Documentation

Complete documentation and examples can be found here:

Advanced Logger's Homepage

NPM package link

Simplest usage

Now, the boring part :nerd_face:

Installation

The library has no peer dependencies - it uses the runtime's native fetch.

As a dependency in a npm project:

npm i --save advanced-logger

// ESM (recommended)
import {AdvancedLogger, service, strategy, TransformationEnum} from 'advanced-logger';

// CommonJS
const {AdvancedLogger, service, strategy} = require('advanced-logger');

The API is exported as top-level named exports. In browsers via script tag, the same API is exposed on window.advancedLogger (see below).

As script tags with CDN:

<script src="https://cdn.jsdelivr.net/npm/advanced-logger@latest/dist/index.global.js"></script>

Configuration

Lets initiate a logger that sends all logs instantly to Sumologic service.

const {AdvancedLogger, service, strategy} = window.advancedLogger;

const defaultLogConfig = {
    UserAgent: window.userAgent,
    Channel: "my-company",
    BuildVersion: 123,
    Platform: "browser",
    Severity: "DEBUG",
    Data: "",
    Timestamp: "",
    Message: "",
    Category: ""
};

const serviceConfig = {
    url: "https://www.google.nl",
    sourceName: "advancedLoggerTest",
    host: "advanced-logger",
    sourceCategory: "MY/SUMO/namespace",
    method: "POST"
};

const config = {serviceConfig, defaultLogConfig};

const logger = new AdvancedLogger({
    service: new service.SumologicService(config),
    strategy: new strategy.InstantStrategy()
});

logger.log({test: "instant log u1"}); // sends log message :rocket:
logger.log({test: "instant log u2"}); // sends log message :rocket:
logger.log({test: "instant log u3"}); // sends log message :rocket:

Development

Requires Node.js 24+ (see .mise.toml / .nvmrc).

mise install          # optional: install Node via mise
npm ci
npm run type-check
npm test              # unit tests (import from src/, mock http)
npm run test:integration  # build dev bundles + Node/browser runtime tests
npm run test:all      # unit + runtime
npm run build
npm run coverage      # unit tests with coverage (CI on master)

The library is bundled with tsup (see tsup.config.ts) into ESM, CJS, type declarations, and a browser IIFE global.

Jest 30 runs two projects (see jest.config.js):

| Project | What it checks | |---------|----------------| | unit | Source-level specs under __tests__/ | | runtime | Built artifacts: Node via dist/index.cjs, browser IIFE via jsdom + window.advancedLogger |

CI runs unit tests, full build, then runtime integration on every branch.

Contributor notes for AI-assisted work: AGENTS.md.

Upgrading between breaking changes

3.x to 4.x

Version 4 modernizes the build (dual ESM/CJS via tsup) and removes axios in favor of the platform's native fetch. There are four breaking changes:

1. No more advancedLogger namespace wrapper. import/require now return the API as top-level named exports.
2. axios removed. The library uses native fetch; drop axios from your dependencies and from any browser <script> tags. Requires Node.js 18+ (Node 24 recommended) or a modern browser.
3. Non-2xx responses now reject. fetch does not reject on HTTP error statuses, so the library throws on non-2xx to preserve the retry-on-failure behavior axios provided. Wrap sendAllLogs() accordingly if you handle errors.
4. CDN script path changed to dist/index.global.js.

The browser window.advancedLogger global (script-tag usage) is unchanged.

Migration

Uninstall axios (it is no longer needed):

npm uninstall axios

Node / bundlers — drop the .advancedLogger wrapper:

// Before (3.x)
const {AdvancedLogger, service, strategy} = require('advanced-logger').advancedLogger;

// After (4.x) — CommonJS
const {AdvancedLogger, service, strategy} = require('advanced-logger');

// After (4.x) — ESM (recommended)
import {AdvancedLogger, service, strategy, TransformationEnum} from 'advanced-logger';

Browser script tags — remove axios and update the bundle URL:

<!-- Before (3.x) -->
<script src="https://cdn.jsdelivr.net/npm/axios@latest/dist/axios.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/advanced-logger@latest/dist/browser/advanced-logger.browser.min.js"></script>

<!-- After (4.x) -->
<script src="https://cdn.jsdelivr.net/npm/advanced-logger@latest/dist/index.global.js"></script>

The window.advancedLogger global stays the same, so code using it needs no changes:

const {AdvancedLogger, service, strategy} = window.advancedLogger;

2.x to 3.x

• Install axios to your project or just keep using it if it is already installed
• Logger is compiled to ES2015 JS target. If your project requires support of old browsers and nodejs, please, make sure that you transpile and add necessary pollyfills to the build