@nlabs/arkhamjs-middleware-logger

> Powerful Logging Middleware for ArkhamJS - Comprehensive action and state logging with customizable output formats, filtering, and performance insights.


🚀 Features

- 📝 Comprehensive Logging - Log actions, state changes, and performance metrics
- 🎨 Customizable Output - Beautiful console formatting with colors and grouping
- 🔍 Action Filtering - Filter specific actions or action types
- ⚡ Performance Tracking - Measure action execution time and state update performance
- 🌲 Tree-shakable - Only include what you need in production
- 🔧 Configurable - Extensive options for customization
- 📱 Browser Support - Works in Chrome, Firefox, Safari, and Edge

📦 Installation

``bash
npm install @nlabs/arkhamjs-middleware-logger
`

🎯 Quick Start

$3

`typescript
import { Flux } from '@nlabs/arkhamjs';
import { Logger } from '@nlabs/arkhamjs-middleware-logger';

// Initialize Flux with logger middleware
Flux.init({
name: 'my-app',
stores: [UserStore, CartStore],
middleware: [
Logger() // Enable basic logging
]
});

// Dispatch actions and see beautiful logs
Flux.dispatch({ type: 'ADD_USER', user: { name: 'John' } });
`

$3

`
🚀 ArkhamJS Logger - Action Dispatched
┌─────────────────────────────────────────────────────────────┐
│ Action: ADD_USER │
│ Timestamp: 2024-01-15T10:30:45.123Z │
│ Duration: 2.5ms │
├─────────────────────────────────────────────────────────────┤
│ Payload: │
│ { │
│ "user": { │
│ "name": "John" │
│ } │
│ } │
├─────────────────────────────────────────────────────────────┤
│ State Changes: │
│ • user.list: [] → [{"name":"John"}] │
│ • user.count: 0 → 1 │
└─────────────────────────────────────────────────────────────┘
`

🔧 Configuration Options

$3

`typescript
import { Logger } from '@nlabs/arkhamjs-middleware-logger';

Flux.init({
name: 'my-app',
stores: [UserStore],
middleware: [
Logger({
// Enable/disable features
logActions: true, // Log dispatched actions
logState: true, // Log state changes
logPerformance: true, // Log performance metrics

// Filtering options
filterActions: ['ADD_USER', 'UPDATE_USER'], // Only log specific actions
excludeActions: ['TICK', 'MOUSE_MOVE'], // Exclude specific actions

// Output options
groupActions: true, // Group related logs
showTimestamp: true, // Show timestamps
showDuration: true, // Show action duration

// Styling
colors: true, // Enable colored output
compact: false, // Compact mode for less verbose output

// Performance thresholds
slowActionThreshold: 100, // Warn for actions taking >100ms

// Custom formatting
formatAction: (action) => 🎯 ${action.type},
formatState: (path, oldValue, newValue) =>
${path}: ${JSON.stringify(oldValue)} → ${JSON.stringify(newValue)}
})
]
});
`

$3

`typescript
import { Logger } from '@nlabs/arkhamjs-middleware-logger';

const isDevelopment = process.env.NODE_ENV === 'development';

Flux.init({
name: 'my-app',
stores: [UserStore],
middleware: [
// Only enable logging in development
...(isDevelopment ? [Logger()] : [])
]
});
`

$3

`typescript
import { Logger } from '@nlabs/arkhamjs-middleware-logger';

interface UserAction {
type: string;
user?: { premium?: boolean };
}

Flux.init({
name: 'my-app',
stores: [UserStore],
middleware: [
Logger({
// Filter by action type pattern
filterActions: (action: UserAction) => action.type.startsWith('USER_'),

// Filter by action payload
filterActions: (action: UserAction) => action.user && action.user.premium,

// Filter state changes
filterState: (path: string, oldValue: any, newValue: any): boolean => {
// Only log significant changes
return JSON.stringify(oldValue) !== JSON.stringify(newValue);
},

// Custom action grouping
groupBy: (action: UserAction): string => {
if (action.type.startsWith('USER_')) return 'User Actions';
if (action.type.startsWith('CART_')) return 'Cart Actions';
return 'Other Actions';
}
})
]
});
`

🎨 Custom Logging Formats

$3

`typescript
import { Logger } from '@nlabs/arkhamjs-middleware-logger';

interface Action {
type: string;
}

Flux.init({
name: 'my-app',
stores: [UserStore],
middleware: [
Logger({
formatAction: (action: Action): string => {
const icons: Record = {
'ADD_USER': '👤',
'UPDATE_USER': '✏️',
'DELETE_USER': '🗑️',
'CART_ADD': '🛒',
'CART_REMOVE': '❌'
};

const icon = icons[action.type] || '📝';
return ${icon} ${action.type};
}
})
]
});
`

$3

`typescript
import { Logger } from '@nlabs/arkhamjs-middleware-logger';

Flux.init({
name: 'my-app',
stores: [UserStore],
middleware: [
Logger({
formatState: (path: string, oldValue: any, newValue: any): string => {
const formatValue = (value: any): string => {
if (Array.isArray(value)) return [${value.length} items];
if (typeof value === 'object' && value !== null) return '{...}';
return String(value);
};

return ${path}: ${formatValue(oldValue)} → ${formatValue(newValue)};
}
})
]
});
`

🎯 Advanced Usage

$3

`typescript
import { Logger } from '@nlabs/arkhamjs-middleware-logger';

Flux.init({
name: 'my-app',
stores: [UserStore],
middleware: [
Logger({
logPerformance: true,
slowActionThreshold: 50, // Warn for actions >50ms

// Custom performance formatter
formatPerformance: (duration: number, action: any): string => {
if (duration > 100) return 🐌 Slow action: ${action.type} (${duration}ms);
if (duration > 50) return ⚠️ Medium action: ${action.type} (${duration}ms);
return ⚡ Fast action: ${action.type} (${duration}ms);
}
})
]
});
`

$3

`typescript
import { Logger } from '@nlabs/arkhamjs-middleware-logger';

const createLogger = (options: any) => {
const isDevelopment = process.env.NODE_ENV === 'development';
const isTest = process.env.NODE_ENV === 'test';

if (isTest) {
return Logger({
logActions: false,
logState: false,
logPerformance: false
});
}

if (isDevelopment) {
return Logger({
...options,
colors: true,
groupActions: true
});
}

return Logger({
...options,
colors: false,
groupActions: false,
compact: true
});
};

Flux.init({
name: 'my-app',
stores: [UserStore],
middleware: [createLogger()]
});
`

$3

`typescript
import { Logger } from '@nlabs/arkhamjs-middleware-logger';

Flux.init({
name: 'my-app',
stores: [UserStore],
middleware: [
Logger({
// Custom log handler for external logging services
onActionLogged: (action: any, duration: number) => {
// Send to external logging service
analytics.track('action_dispatched', {
action: action.type,
duration,
timestamp: Date.now()
});
},

onStateChanged: (path: string, oldValue: any, newValue: any) => {
// Track state changes
analytics.track('state_changed', {
path,
oldValue,
newValue
});
}
})
]
});
`

🔧 API Reference

$3

`typescript
interface LoggerOptions {
// Basic settings
logActions?: boolean;
logState?: boolean;
logPerformance?: boolean;

// Filtering
filterActions?: string[] | ((action: any) => boolean);
excludeActions?: string[] | ((action: any) => boolean);
filterState?: (path: string, oldValue: any, newValue: any) => boolean;

// Output formatting
groupActions?: boolean;
showTimestamp?: boolean;
showDuration?: boolean;
colors?: boolean;
compact?: boolean;

// Performance
slowActionThreshold?: number;

// Custom formatters
formatAction?: (action: any) => string;
formatState?: (path: string, oldValue: any, newValue: any) => string;
formatPerformance?: (duration: number, action: any) => string;

// Custom handlers
onActionLogged?: (action: any, duration: number) => void;
onStateChanged?: (path: string, oldValue: any, newValue: any) => void;

// Grouping
groupBy?: (action: any) => string;
}
`

🎯 Use Cases

$3

`typescript
import { Logger } from '@nlabs/arkhamjs-middleware-logger';

// Development setup with full logging
const devLogger = Logger({
logActions: true,
logState: true,
logPerformance: true,
colors: true,
groupActions: true,
showTimestamp: true,
showDuration: true
});

Flux.init({
name: 'my-app',
stores: [UserStore],
middleware: [devLogger]
});
`

$3

`typescript
import { Logger } from '@nlabs/arkhamjs-middleware-logger';

// Production setup with minimal logging
const prodLogger = Logger({
logActions: false,
logState: false,
logPerformance: true,
colors: false,
compact: true,
slowActionThreshold: 100,

onActionLogged: (action, duration) => {
if (duration > 100) {
// Send slow action alerts
errorReporting.captureMessage(Slow action: ${action.type}, {
level: 'warning',
extra: { action, duration }
});
}
}
});

Flux.init({
name: 'my-app',
stores: [UserStore],
middleware: [prodLogger]
});
`

$3

`typescript
import { Logger } from '@nlabs/arkhamjs-middleware-logger';

// Testing setup with no logging
const testLogger = Logger({
logActions: false,
logState: false,
logPerformance: false
});

Flux.init({
name: 'test-app',
stores: [UserStore],
middleware: [testLogger]
});
``

🔗 Related Packages

- @nlabs/arkhamjs - Core Flux framework
- @nlabs/arkhamjs-middleware-devtools - Chrome DevTools integration
- @nlabs/arkhamjs-utils-react - React hooks and utilities

📚 Documentation

- ArkhamJS Documentation - Complete API reference
- Middleware Guide - Middleware development guide
- Debugging Guide - Debugging best practices

🤝 Community & Support

- 💬 Discord Community - Chat with other developers
- 🐛 GitHub Issues - Report bugs and request features
- 📝 Examples - Complete working examples

📄 License

MIT License - see LICENSE file for details.

---

Start debugging your ArkhamJS applications with powerful logging today! 🚀