Add lazy log builders for every level (#44)

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: passsy

examples/simple/bin/lazy_messages.dart

@@ -0,0 +1,46 @@
+/// Example: Lazy message and lazy log construction.
+///
+/// Run with: dart run bin/lazy_messages.dart
+import 'dart:convert';
+
+import 'package:chirp/chirp.dart';
+
+void main() {
+  // Configure logger with warning as minimum level.
+  // trace and debug messages will be filtered out.
+  Chirp.root =
+      ChirpLogger().setMinLogLevel(ChirpLogLevel.warning).addConsoleWriter();
+
+  final hugeMap = {
+    'users': List.generate(1000, (i) => {'id': i, 'name': 'User $i'}),
+  };
+
+  // Without lazy: jsonEncode() runs even though trace is filtered out.
+  Chirp.trace('User data: ${jsonEncode(hugeMap)}');
+
+  // Lazy message: the lambda is never called because trace is filtered.
+  Chirp.trace(() => 'User data: ${jsonEncode(hugeMap)}');
+
+  // traceLazy / warningLazy / etc.: defer EVERY argument (message, data,
+  // error, …) until the logger has decided to actually emit. Use this when
+  // expensive work is in the structured `data` map, not just the message.
+  Chirp.traceLazy(
+    (log) => log('User data', data: {'snapshot': jsonEncode(hugeMap)}),
+  );
+
+  // Works at every level.
+  Chirp.warningLazy(
+    (log) => log('Rendered users', data: {'count': hugeMap.length}),
+  );
+  Chirp.errorLazy((log) => log('This error is logged'));
+
+  // Plain strings and lazy messages still work as before.
+  Chirp.warning('Plain string warning');
+  Chirp.warning(() => 'Lazy string warning');
+}
+
+// Output (only warning and above are shown):
+// ... [warning] Rendered users {count: 1}
+// ... [error] This error is logged
+// ... [warning] Plain string warning
+// ... [warning] Lazy string warning

packages/chirp/CHANGELOG.md

@@ -1,3 +1,18 @@
+## Unreleased
+
+- **New** Lazy message construction — pass `() => 'expensive $message'` to any log method.
+  The lambda is only called when the log level passes the filter, avoiding unnecessary string allocations.
+- **New** Lazy log builders — `traceLazy`, `debugLazy`, `infoLazy`, `noticeLazy`, `successLazy`, `warningLazy`, `errorLazy`, `criticalLazy`, `wtfLazy`, and `logLazy` (with a `level:` argument) — defer the entire log call (message, `data`, `error`, `stackTrace`, `formatOptions`) until the level filter passes.
+  Useful when expensive work lives in the structured `data` map, not just the message string.
+  ```dart
+  Chirp.warningLazy(
+    (log) => log('snapshot', data: {'state': renderState()}),
+  );
+  ```
+  Matching `Chirp.*Lazy` static forwarders are exposed on the global logger.
+  Caller resolution lands on the `xxxLazy(...)` invocation line, not the inner `(log) => ...` lambda body, so eager and lazy calls report consistent source locations.
+  Adds the `ChirpLogFn` typedef for the inner `log` callback.
+
 ## 0.8.0
 
 ### New Features

packages/chirp/README.md

@@ -467,6 +467,56 @@ Chirp.root = ChirpLogger().addConsoleWriter();
 Chirp.root.addWriter(myWriter);
 ```
 
+### Lazy Logging
+
+Defer expensive log construction until the logger has decided to actually emit.
+Two flavors, picked by what's expensive.
+
+#### Lazy Messages
+
+Pass a lambda instead of a string to defer expensive message construction.
+The lambda is only called when the log level passes the filter — avoiding unnecessary allocations when the logger is "off":
+
+```dart
+// Always builds the string, even if trace is filtered out
+logger.trace('User data: ${jsonEncode(hugeMap)}');
+
+// Lambda only called when trace level is active
+logger.trace(() => 'User data: ${jsonEncode(hugeMap)}');
+```
+
+This is especially useful for `trace` and `debug` messages that are typically disabled in production but contain expensive-to-build strings.
+
+#### Lazy Builders
+
+When the expensive work lives in `data`, `error`, `stackTrace`, or any other named argument — not just the message — use the `xxxLazy` variant.
+The builder is invoked only when the level passes, so every argument it constructs is paid for only on records that will actually be emitted.
+
+```dart
+// Defers EVERY argument (message, data, error, ...) until the logger emits
+Chirp.warningLazy(
+  (log) => log('snapshot', data: {'state': renderState(), 'metrics': dump()}),
+);
+
+// Works for every level
+Chirp.errorLazy((log) => log('failed', error: e, stackTrace: st));
+
+// logLazy takes a level: argument
+Chirp.logLazy(
+  (log) => log('msg', data: {'state': render()}),
+  level: ChirpLogLevel.debug,
+);
+```
+
+The inner `log` callback has the same shape as the eager method (typedef `ChirpLogFn`), so call sites read identically — minus the wasted work when the log will be discarded.
+
+Caller resolution is handled automatically: the `xxxLazy(...)` invocation line is reported, not the inner `(log) => ...` lambda body, so source locations look the same whether the call is eager or lazy.
+
+Available variants: `traceLazy`, `debugLazy`, `infoLazy`, `noticeLazy`, `successLazy`, `warningLazy`, `errorLazy`, `criticalLazy`, `wtfLazy`, plus the generic `logLazy` on both `ChirpLogger` instances and the global `Chirp` static API.
+
+Lazy builders cost one closure allocation per call when the level passes; the level-filtered hot path stays as cheap as the eager methods.
+Reach for `xxxLazy` when constructing `data` (or other arguments) is expensive; reach for the lazy-message form when only the message is.
+
 ### Filtering
 
 Chirp provides two ways to filter logs:
@@ -893,6 +943,7 @@ See [`examples/simple/bin/`](https://github.com/passsy/chirp/tree/main/examples/
 | [`instance_tracking.dart`](https://github.com/passsy/chirp/blob/main/examples/simple/bin/instance_tracking.dart) | The `.chirp` extension |
 | [`multiple_writers.dart`](https://github.com/passsy/chirp/blob/main/examples/simple/bin/multiple_writers.dart) | Console + JSON output |
 | [`file_writer.dart`](https://github.com/passsy/chirp/blob/main/examples/simple/bin/file_writer.dart) | File logging with rotation |
+| [`lazy_messages.dart`](https://github.com/passsy/chirp/blob/main/examples/simple/bin/lazy_messages.dart) | Lazy message construction for performance |
 | [`interceptors.dart`](https://github.com/passsy/chirp/blob/main/examples/simple/bin/interceptors.dart) | Filtering and transforming logs |
 | [`library.dart`](https://github.com/passsy/chirp/blob/main/examples/simple/bin/library.dart) / [`app.dart`](https://github.com/passsy/chirp/blob/main/examples/simple/bin/app.dart) | Library logger adoption |
 | [`main.dart`](https://github.com/passsy/chirp/blob/main/examples/simple/bin/main.dart) | Span transformers (advanced) |

packages/chirp/lib/chirp.dart

@@ -31,7 +31,7 @@ export 'package:chirp/src/ansi/console_color.dart'
 export 'package:chirp/src/core/chirp_formatter.dart'
     show ChirpFormatter, MessageBuffer;
 export 'package:chirp/src/core/chirp_interceptor.dart' show ChirpInterceptor;
-export 'package:chirp/src/core/chirp_logger.dart' show ChirpLogger;
+export 'package:chirp/src/core/chirp_logger.dart' show ChirpLogFn, ChirpLogger;
 export 'package:chirp/src/core/chirp_root.dart'
     show Chirp, ChirpInstanceLogger, ChirpLoggerConsoleWriterExt, LogRecordExt;
 export 'package:chirp/src/core/chirp_writer.dart' show ChirpWriter;