npm package: @nullonrise/rise-logger
Description: An extensible, professional-grade logging toolkit with built-in transports, formatters, and strong TypeScript types.
Author: NullOnRise
Latest version: 1.0.0

# 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](#why-rise-logger)
- [Installation](#installation)
- [Quick start](#quick-start)
- [Configuration reference](#configuration-reference)
- [Contexts and metadata](#contexts-and-metadata)
- [Formatters and transports](#formatters-and-transports)
- [Filters and sampling](#filters-and-sampling)
- [Measuring async work](#measuring-async-work)
- [API surface](#api-surface)
- [NPM scripts](#npm-scripts)
- [Further reading](#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

```bash
# 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

```ts
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

```ts
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:

```ts
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.

```ts
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

```ts
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](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`](examples/basic.ts) - small runnable scenario.
- [`DOCUMENTATION.md`](DOCUMENTATION.md) - architecture notes, troubleshooting, and advanced recipes.

Released under the MIT License.