Merge pull request #4 from DutchCodingCompany/feature/bolt_logger

⚡ Bolt logger

Author: Guldem

docs/bolt_logger.md

@@ -0,0 +1,67 @@
+# ⚡️ BoltLogger!
+_**Super charge your logging and zap logs like Zeus with the BoltLogger.**_
+
+## 🚀 Features
+ - Built on top of the `logging` package. Meaning package that use the `logging` package will also be visible in the BoltLogger.
+ - Easy to use and setup.
+ - Supports multiple charges (log outputs).
+ - Supports multiple log levels.
+ - Has extension methods for easy logging, with include reference to the calling class.
+
+## 🛠 Setup
+To use the `BoltLogger`, you need to charge the logger with a `BoltCharge`.
+
+```dart
+BoltLogger.charge(DebugConsoleCharge());
+```
+
+Available charges:
+ - `DebugConsoleCharge`: Logs output to the console.
+ - `FileCharge`: Logs output to a file.
+ - `MemoryCharge`: Keeps track of logs in memory.
+
+## 📝 Zapping! (Usage)
+The `BoltLogger` aims to be easy to use. Once `BoltLogger` is charged you can start zapping logs! By zapping we mean literally calling `zap`.
+
+Logging a message in `BoltLogger` is as simple as calling the `zap` method.
+
+```dart
+class MyAwesomeClass{
+  void doSomething() {
+   zap('This is a message');
+  }
+}
+```
+
+`BoltLogger` offer `zap` as a extension on `Object` meaning you can call `zap` on or in any object. 
+Because it's an extension we can automatically include the `runtimeType` of the object that called `zap` as tag for the log message.
+
+Just as Zeus when zapping your not only limited to only zap `String`s, you can zap any object. For example: Exceptions, Errors, StackTrace. BoltLogger will take care of the objects accordingly.
+
+Beside zapping messages you can also provide a custom `tag` and `level` to the `zap` method.
+
+`BoltLogger` also offers a `shock` to zap logs with at a `Level.SERVERE` level.
+
+If the extension methods are not available you can call `BoltLogger.zap` directly.
+
+## 📦 Example
+```dart
+
+class MyAwesomeClass{
+  void doSomething() {
+    zap('This is a message');
+  }
+  
+  void doSomethingElse() {
+    shock(Exception('Shocking!'));
+  }
+}
+
+void main() {
+  BoltLogger.charge(DebugConsoleCharge());
+  
+  final myAwesomeClass = MyAwesomeClass();
+  myAwesomeClass.doSomething();
+  myAwesomeClass.doSomethingElse();
+}
+```

lib/common/dcc_logger.dart

@@ -3,12 +3,14 @@ import 'package:intl/intl.dart';
 import 'package:logging/logging.dart';
 
 /// A logger that can be used to log messages.
+@Deprecated('Use BoltLogger instead')
 class DCCLogger {
   static Logger? _logger;
   static final DateFormat _formatter = DateFormat(DateFormat.HOUR24_MINUTE);
 
   /// Initialise the logger. This needs to be called before using the logger.
   /// Using this is done in the main.dart file.
+  @Deprecated('Use BoltLogger.charge instead')
   static void initialise([
     String? name,
     String? tag,
@@ -65,6 +67,7 @@ class DCCLogger {
   /// DCCLogger.info('test bericht', tag: 'test');
   /// ```
   /// prints: [[13:46]] [[INFO]] DCC: <test> test bericht
+  @Deprecated('Use BoltLogger.zap instead')
   static void info(
     String message, {
     Object? error,
@@ -82,6 +85,7 @@ class DCCLogger {
   /// DCCLogger.severe('test bericht', tag: 'test');
   /// ```
   /// prints: [[13:46]] [[SEVERE]] DCC: <test> test bericht
+  @Deprecated('Use BoltLogger.shock instead')
   static void severe(
     String message, {
     Object? error,

lib/dcc_toolkit.dart

@@ -2,8 +2,8 @@
 library dcc_toolkit;
 
 export 'chopper/chopper.dart';
-export 'common/dcc_logger.dart';
 export 'common/dimensions.dart';
 export 'common/extensions/build_context.dart';
 export 'common/extensions/color.dart';
 export 'common/result/result.dart';
+export 'logger/bolt_logger.dart';

lib/logger/bolt_logger.dart

@@ -0,0 +1,138 @@
+import 'dart:async';
+
+import 'package:dcc_toolkit/logger/charges/bolt_charge.dart';
+import 'package:dcc_toolkit/logger/zap_event.dart';
+import 'package:logging/logging.dart';
+
+export 'package:dcc_toolkit/logger/charges/bolt_charge.dart';
+export 'package:dcc_toolkit/logger/extensions/stacktrace.dart';
+export 'package:dcc_toolkit/logger/extensions/zap_extension.dart';
+export 'package:dcc_toolkit/logger/ui/bolt_logger_view.dart';
+export 'package:dcc_toolkit/logger/zap_event.dart';
+
+/// {@template bolt_logger}
+/// Super charge your logging and zap logs like Zeus with the BoltLogger.
+/// {@endtemplate}
+class BoltLogger {
+  /// {@macro bolt_logger}
+  factory BoltLogger() => _instance;
+
+  BoltLogger._();
+
+  static final _instance = BoltLogger._();
+
+  // Is cancelled in discharge
+  //ignore: cancel_subscriptions
+  StreamSubscription<LogRecord>? _subscription;
+
+  final Map<String, BoltCharge> _outputs = {};
+
+  /// Add [BoltCharge] charges to the logger. This will start the logger if it is not already running.
+  /// Without any charges, the logger will not output any logs.
+  ///
+  /// Available charges:
+  /// - [DebugConsoleCharge]
+  /// - [MemoryCharge]
+  /// - [FileCharge]
+  ///
+  /// For example to add a [DebugConsoleCharge] charge, use the following code snippet:
+  /// ```dart
+  /// BoltLogger.charge([DebugConsoleCharge()]);
+  /// ```
+  static void charge(List<BoltCharge> charges) {
+    for (final charge in charges) {
+      _instance._outputs.putIfAbsent(charge.name, () => charge);
+    }
+    _instance._subscribeIfNeeded();
+  }
+
+  /// Look up registered charge by name.
+  static BoltCharge? getCharge(String name) {
+    return _instance._outputs[name];
+  }
+
+  void _subscribeIfNeeded() {
+    Logger.root.level = Level.ALL;
+    _subscription ??= Logger.root.onRecord.listen((record) {
+      for (final output in _outputs.values) {
+        output.logOutput(ZapEvent.fromRecord(record));
+      }
+    });
+  }
+
+  /// Discharge the logger and all charges.
+  static void discharge() {
+    _instance._subscription?.cancel();
+    _instance._subscription = null;
+    for (final output in _instance._outputs.values) {
+      output.discharge();
+    }
+    _instance._outputs.clear();
+  }
+
+  /// {@template zap}
+  /// Zap a log message with optional [tag] and [level].
+  ///
+  /// For example to zap a message:
+  /// ```dart
+  /// BoltLogger.zap('Electricity is in the air!');
+  /// ```
+  ///
+  /// The [message] can also be an [Exception]/[Error], [StackTrace] or a [List] to zap all 3 types ([Object]?, [Exception]/[Error], [StackTrace]). These will be passed to the logger.
+  ///
+  /// ```dart
+  /// BoltLogger.zap(['Electricity is in the air!', myException, stackTrace]);
+  /// ```
+  ///
+  /// {@endtemplate}
+  static void zap(
+    Object? message, {
+    String? tag,
+    Level level = Level.INFO,
+  }) {
+    Object? msg;
+    Object? error;
+    StackTrace? stacktrace;
+
+    void zapMap(Object? value) {
+      if (value is Exception || value is Error && error == null) {
+        error = value;
+      } else if (value is StackTrace && stacktrace == null) {
+        stacktrace = value;
+      } else if (msg == null) {
+        msg = value;
+      } else {
+        final errorMessage =
+            'When zapping a list it can only contain one of each Exception/Error, StackTrace or Object?: $message';
+        assert(false, errorMessage);
+        error = AssertionError([errorMessage]);
+        msg = '';
+        stacktrace = StackTrace.empty;
+      }
+    }
+
+    if (message is List) {
+      for (final Object? value in message) {
+        zapMap(value);
+      }
+    } else {
+      zapMap(message);
+    }
+
+    Logger(tag ?? 'BoltLogger').log(level, msg, error, stacktrace);
+  }
+
+  /// {@template shock}
+  /// Shock is a zap intensified! It zaps a log message default [level] of [Level.SEVERE].
+  ///
+  /// {@macro zap}
+  ///
+  /// {@endtemplate}
+  static void shock(
+    Object? message, {
+    String? tag,
+    Level level = Level.SEVERE,
+  }) {
+    zap(message, tag: tag, level: level);
+  }
+}

lib/logger/charges/bolt_charge.dart

@@ -0,0 +1,17 @@
+import 'package:dcc_toolkit/logger/bolt_logger.dart';
+
+export 'package:dcc_toolkit/logger/charges/debug_console_charge.dart';
+export 'package:dcc_toolkit/logger/charges/file_charge.dart';
+export 'package:dcc_toolkit/logger/charges/memory_charge.dart';
+
+/// Interface for creating [BoltCharge]s to power the [BoltLogger]
+abstract interface class BoltCharge {
+  /// The name of the charge.
+  abstract final String name;
+
+  /// Log the output of the [ZapEvent].
+  void logOutput(ZapEvent event);
+
+  /// Discharge the charge.
+  void discharge();
+}

lib/logger/charges/debug_console_charge.dart

@@ -0,0 +1,41 @@
+import 'package:dcc_toolkit/logger/charges/bolt_charge.dart';
+import 'package:dcc_toolkit/logger/util/ansi_support.dart'
+    if (dart.library.io) 'package:dcc_toolkit/logger/util/ansi_support_io.dart'
+    if (dart.library.html) 'package:dcc_toolkit/logger/util/ansi_support_web.dart';
+import 'package:dcc_toolkit/logger/zap_event.dart';
+import 'package:flutter/foundation.dart';
+import 'package:logging/logging.dart';
+
+/// {@template debug_console_charge}
+/// A [BoltCharge] that logs output to the console with ANSI color support.
+/// {@endtemplate}
+class DebugConsoleCharge implements BoltCharge {
+  /// {@macro debug_console_charge}
+  const DebugConsoleCharge();
+  @override
+  String get name => 'DebugConsoleCharge';
+
+  @override
+  void logOutput(ZapEvent event) {
+    if (!kDebugMode) return;
+    _paintLines(event).forEach(debugPrint);
+  }
+
+  List<String> _paintLines(ZapEvent event) {
+    final shouldPaint = supportsAnsiEscapes &&
+        (event.origin.level.value >= Level.SEVERE.value ||
+            event.origin.stackTrace != null ||
+            event.origin.error != null);
+
+    return shouldPaint
+        ? event.lines.map((line) => '$_red$line$_reset').toList()
+        : event.lines;
+  }
+
+  @override
+  void discharge() {}
+}
+
+const _esc = '\x1B[';
+const _reset = '${_esc}0m';
+const _red = '${_esc}38;5;1m';

lib/logger/charges/file_charge.dart

@@ -0,0 +1,72 @@
+import 'dart:async';
+import 'dart:io';
+
+import 'package:dcc_toolkit/logger/charges/bolt_charge.dart';
+import 'package:dcc_toolkit/logger/zap_event.dart';
+import 'package:intl/intl.dart';
+
+/// {@template file_charge}
+/// A [BoltCharge] that logs output to a file.
+///
+/// The [FileCharge] will write logs to a file in the specified [path].
+/// Logs are written to the file in batches, this is done when it reaches the [bufferSize] or every [writeDelay].
+///
+/// {@endtemplate}
+class FileCharge implements BoltCharge {
+  /// {@macro file_charge}
+  FileCharge(
+    this.path, {
+    this.bufferSize = 1000,
+    this.writeDelay = const Duration(seconds: 5),
+  }) {
+    final fileName = '${DateFormat('yyyy-MM-dd').format(DateTime.now())}.log';
+    _file = File('$path/$fileName');
+
+    Timer.periodic(writeDelay, (_) => _flush());
+  }
+  @override
+  String get name => 'FileCharge';
+
+  /// The size of the buffer (in lines) before writing to the file.
+  final int bufferSize;
+
+  /// The path to the directory where the log files will be written.
+  final String path;
+
+  /// The delay between writing to the file.
+  final Duration writeDelay;
+  File? _file;
+  final List<ZapEvent> _buffer = [];
+  IOSink? _sink;
+  Timer? _timer;
+
+  @override
+  void logOutput(ZapEvent event) {
+    _buffer.add(event);
+
+    if (_buffer.length >= bufferSize) {
+      _flush();
+    }
+  }
+
+  void _flush() {
+    if (_buffer.isEmpty) return;
+
+    _sink ??= _file?.openWrite(mode: FileMode.append);
+
+    for (final event in _buffer) {
+      _sink?.writeAll(event.lines, '\n');
+      _sink?.writeln();
+    }
+    _buffer.clear();
+  }
+
+  @override
+  void discharge() {
+    _timer?.cancel();
+    _timer = null;
+    _flush();
+    _sink?.close();
+    _sink = null;
+  }
+}