Rise Logger

Professional, extensible, and strongly typed logging toolkit with transports, filters, and formatters you can compose for any observability stack.

Table of contents

• Why Rise Logger
• Installation
• Quick start
• Configuration reference
• Contexts and metadata
• Formatters and transports
• Filters and sampling
• Measuring async work
• API surface
• NPM scripts
• Further reading

Why Rise Logger

• Typed from the ground up - LogRecord, LoggerOptions, and helper types keep your codebase honest.
• Extensible pipeline - swap in any Formatter, Transport, or LogFilter without rewriting the logger core.
• Context aware - automatically propagate environment, service, tenant, and arbitrary tags to every emit.
• Async safe - transports run concurrently with optional flush() and dispose() hooks.
• Batteries included - console, file, and in memory transports paired with JSON and human readable formatters.

Installation

# npm
npm install @nullonrise/rise-logger

# yarn
yarn add @nullonrise/rise-logger

# pnpm
pnpm add @nullonrise/rise-logger

The package ships ESM output plus .d.ts declaration files under dist/.

Quick start

import {
  createLogger,
  ConsoleTransport,
  FileTransport,
  HumanReadableFormatter,
  JsonFormatter
} from 'rise-logger';

const logger = createLogger({
  level: 'debug',
  context: { service: 'billing-api', environment: process.env.NODE_ENV },
  defaultMetadata: { version: '1.4.2' },
  transports: [
    new ConsoleTransport({ formatter: new HumanReadableFormatter() }),
    new FileTransport({
      filePath: '/var/log/billing-api.log',
      formatter: new JsonFormatter({ space: 2 })
    })
  ]
});

logger.info('Server booted', { port: 8080 });

Configuration reference

LoggerOptions you can pass to createLogger or new Logger():

| Option | Type | Default | Description | | --- | --- | --- | --- | | level | LogLevel | info | Minimum level that will be emitted. | | context | LoggerContext | undefined | Shared service level context applied to every record. | | formatter | Formatter | undefined | Formatter applied before transports execute. You can still provide transport specific formatters. | | transports | Transport[] | [] | Destinations that receive records. Add or remove at runtime via logger.addTransport. | | filters | LogFilter[] | [] | Functions that can drop or mutate log records before they are formatted. | | defaultMetadata | Record<string, unknown> | {} | Metadata merged with per call metadata, ideal for version, region, or runtime info. | | correlationIdProvider | () => string | undefined | Lazy provider used when a call does not include correlationId. Useful for async context propagation. |

Contexts and metadata

const baseLogger = createLogger({
  context: { service: 'checkout', environment: 'prod', tags: { region: 'us-east-1' } },
  defaultMetadata: { release: '2024.11.0' }
});

const workerLogger = baseLogger.child({
  context: { subsystem: 'worker', tags: { queue: 'orders' } },
  defaultMetadata: { retries: 0 }
});

workerLogger.info('Dequeued task', { taskId: 'abc-123' });

Contexts from parent and child loggers are merged so you can safely layer subsystems without losing the top level metadata.

Formatters and transports

Rise Logger separates formatting from output. Provided components:

Formatters

• JsonFormatter - emits compact or pretty JSON depending on the space option.
• HumanReadableFormatter - prints ANSI colored single line entries ideal for local development.

Transports

• ConsoleTransport - writes to any Console implementation.
• FileTransport - appends newline separated entries to disk, optionally auto creating directories.
• MemoryTransport - keeps an in memory snapshot perfect for tests.

Combine them however you need:

const logger = createLogger()
  .addTransport(new ConsoleTransport({ formatter: new HumanReadableFormatter({ colorize: true }) }))
  .addTransport(new FileTransport({ filePath: './logs/app.log' }));

Filters and sampling

Filters are predicates that can cancel a record before it reaches transports. They can run sync or async.

logger.addFilter(async (record) => {
  if (record.level === 'debug' && Math.random() < 0.9) {
    return false; // sample 10% of debug logs
  }
  return true;
});

Use them for sampling, structured PII scrubbing, or routing to specialized transports.

Measuring async work

await logger.measure('info', 'ProcessOrder', async () => {
  await processOrder();
}, { orderId: 42 });

measure automatically records duration and emits an error entry if the promise rejects.

API surface

• Logger - core orchestrator with log, child, flush, dispose, and helpers per log level.
• createLogger(options) - convenience factory that returns a ready logger.
• createConsoleLogger(options) - factory that ensures a console transport exists.
• ConsoleTransport, FileTransport, MemoryTransport - built in destinations.
• JsonFormatter, HumanReadableFormatter - built in stringifiers.
• Types: LogLevel, LogRecord, LoggerOptions, Formatter, Transport, LogFilter, LoggerContext.

See the dedicated DOCUMENTATION.md for deep dives, extension guidelines, and diagrams.

NPM scripts

• npm run build - compile TypeScript to dist/ with declaration and source maps.
• npm run lint - type check the project without emitting code.
• npm run clean - remove the build output directory.

Further reading

• examples/basic.ts - small runnable scenario.
• DOCUMENTATION.md - architecture notes, troubleshooting, and advanced recipes.

Released under the MIT License.