Observable Event Logging Library for JavaScript/TypeScript

Documentation | Demo | API Reference

Satori is a powerful observability library that provides structured logging with advanced features like state watching, causal linking, filtering, rate limiting, and persistence.

Features

| Feature | Description | | --------- | ------------- | | Structured Logging | Log events with levels, scopes, tags, and state | | State Watching | Automatically log when values change | | Causal Linking | Track cause-and-effect relationships between events | | Tags and Filtering | Categorize and query events with powerful filters | | Rate Limiting | Protection against log floods with drop/sample/buffer strategies | | Deduplication | Prevent duplicate events within time windows | | Circuit Breaker | Error recovery and protection for watchers | | Persistence | Store events in memory, localStorage, or IndexedDB | | Self-Monitoring | Track metrics about the logging system itself | | Multi-Runtime | Works in browser, Node.js, Deno, Bun, and edge runtimes |

Quick Start

import { createSatori } from '@nisoku/satori-log';

// Create a Satori instance
const satori = createSatori({
  logLevel: 'info',
  rateLimiting: { enabled: true, maxEventsPerSecond: 100 }
});

// Create a scoped logger
const logger = satori.createLogger('myApp');

// Log events
logger.info('Application started');
logger.warn('Config not found, using defaults');
logger.error('Failed to connect', { state: { error: 'timeout' } });

// Watch for changes
const store = { count: 0 };
logger.watch(() => store.count, 'counter');
store.count++;  // Automatically logs the change!

// Subscribe to events
satori.bus.subscribe((event) => {
  console.log(`[${event.level}] ${event.scope}: ${event.message}`);
});

Installation

npm install @nisoku/satori-log

Satori is available on NPM!

Documentation

| Section | Description | | --------- | ------------- | | Quick Start | Get up and running in 5 minutes | | Configuration | Complete configuration options | | State Watching | Automatic change detection | | Causal Linking | Event relationship tracking | | Filtering | Query and filter events | | Advanced Features | Rate limiting, deduplication, circuit breaker | | API Reference | Complete API documentation | | Filter Functions | Filter API reference | | Examples | Real-world usage patterns |

Demo

Open the live demo in a browser to see Satori in action with an interactive playground.

The demo showcases all major features:

• Logging at different levels
• State watching with counters
• Rate limiting under burst load
• Deduplication of repeated messages
• Causal event chains
• Real-time metrics

Development

Install dependencies

cd Build && npm install

Run tests

cd Build && npm test

Run tests in watch mode

cd Build && npm run test:watch

Type check

cd Build && npm run typecheck

Build

cd Build && npm run build

Build docs

cd ../Docs && npm run build

Project Structure

Satori/
  assets/           # Shared icons and images
  Build/            # Source code and build config
    src/            # TypeScript source
  Demo/             # Interactive demo
  Docs/             # Documentation (docmd)

Contributing

We love contributors! Feel free to open up PRs or issues for any ideas or bugs you find!

License

MIT