diff --git a/log/examples_test.go b/log/examples_test.go index fc604fa..36d4070 100644 --- a/log/examples_test.go +++ b/log/examples_test.go @@ -47,7 +47,7 @@ func ExampleModule() { // level=ERROR msg=error } -func ExampleModule_withAttr() { +func ExampleWith() { loggerOption := slog.HandlerOptions{ AddSource: false, // Remove code position from the output for predictable test output. ReplaceAttr: removeTimeAttr, diff --git a/log/log.go b/log/log.go index 805e91d..7a85d4c 100644 --- a/log/log.go +++ b/log/log.go @@ -1,3 +1,6 @@ +// Package log is a module injecting a `*slog.Logger` instance. +// It provides a group of functions to log with the injected instance. +// See [examples_test.go](./examples_test.go) for the usage. package log import ( @@ -9,18 +12,23 @@ import ( ) var ( + // Module for injecting `*slog.Logger` Module = module.New[*slog.Logger]() + // TextLogger provides a instance with `slog.TextHandler` logging to `os.Stderr` TextLogger = Module.ProvideWithFunc(func(ctx context.Context) (*slog.Logger, error) { handler := slog.NewTextHandler(os.Stderr, nil) return slog.New(handler), nil }) + + // JSONLogger provides a instance with `slog.JSONHandler` logging to `os.Stderr` JSONLogger = Module.ProvideWithFunc(func(ctx context.Context) (*slog.Logger, error) { handler := slog.NewJSONHandler(os.Stderr, nil) return slog.New(handler), nil }) ) +// With creates a new `context.Context` with new attrs. It's similar to [`slog.Logger.With()`](https://pkg.go.dev/log/slog#Logger.With). func With(ctx context.Context, args ...any) context.Context { if len(args) == 0 { return ctx @@ -36,6 +44,8 @@ func With(ctx context.Context, args ...any) context.Context { return Module.With(ctx, logger) } +// DEBUG logs with the injected instance at DEBUG level. +// If no injected `*slog.Logger`, the function does nothing. func DEBUG(ctx context.Context, msg string, args ...any) { logger := Module.Value(ctx) if logger == nil { @@ -45,6 +55,8 @@ func DEBUG(ctx context.Context, msg string, args ...any) { logger.DebugContext(ctx, msg, args...) } +// INFO logs with the injected instance at INFO level. +// If no injected `*slog.Logger`, the function does nothing. func INFO(ctx context.Context, msg string, args ...any) { logger := Module.Value(ctx) if logger == nil { @@ -54,6 +66,8 @@ func INFO(ctx context.Context, msg string, args ...any) { logger.InfoContext(ctx, msg, args...) } +// WARN logs with the injected instance at WARN level. +// If no injected `*slog.Logger`, the function does nothing. func WARN(ctx context.Context, msg string, args ...any) { logger := Module.Value(ctx) if logger == nil { @@ -63,6 +77,8 @@ func WARN(ctx context.Context, msg string, args ...any) { logger.WarnContext(ctx, msg, args...) } +// ERROR logs with the injected instance at ERROR level. +// If no injected `*slog.Logger`, the function does nothing. func ERROR(ctx context.Context, msg string, args ...any) { logger := Module.Value(ctx) if logger == nil { diff --git a/module.go b/module.go index 9e2ac97..a9f5aef 100644 --- a/module.go +++ b/module.go @@ -1,5 +1,5 @@ // Package module provides a way to do dependency injection, with type-safe, without performance penalty. -// See [examples](#example-Module) for the basic usage. +// See [examples_test.go](./examples_test.go) for the basic usage. package module import (