EasyMessages

Tired of writing the same error messages over and over? EasyMessages gives you 100+ pre-built, standardized messages with a fluent API that just works.

---

🎯 The Problem

// ❌ Inconsistent, scattered, hard to maintain
return BadRequest(new { message = "Invalid credentials" });
return Unauthorized(new { error = "Not authorized" });
return NotFound("User not found");

✨ The Solution

// ✅ Standardized, fluent, discoverable, consistent
Msg.Auth.LoginFailed().ToJson();
Msg.Auth.Unauthorized().ToApiResponse();
Msg.Crud.NotFound("User").ToApiResponse();

---

🚀 Quick Start

Console Application

using RecurPixel.EasyMessages;

// Works immediately - no setup needed!
Msg.Auth.LoginFailed().ToConsole(useColors: true);

var json = Msg.Crud.Created("User").ToJson();
Console.WriteLine(json);

ASP.NET Core Web API

// No setup needed — just install RecurPixel.EasyMessages

[HttpPost("login")]
public IActionResult Login(LoginDto dto)
{
    if (!_authService.ValidateCredentials(dto))
    {
        var msg = Msg.Auth.LoginFailed();
        return StatusCode(msg.HttpStatusCode ?? 401, msg.ToJsonObject());
    }
    var success = Msg.Auth.LoginSuccessful()
        .WithData(new { token = _authService.GenerateToken(dto) });
    return StatusCode(success.HttpStatusCode ?? 200, success.ToJsonObject());
}

---

⚡ Features at a Glance

• ✅ 100+ Pre-built Messages - Authentication, CRUD, Validation, System errors
• ✅ Type-Safe - IntelliSense-driven API, compile-time safety
• ✅ Multiple Formats - JSON, XML, Console, Plain Text
• ✅ Zero Configuration - Works immediately out of the box
• ✅ Fluent API - Chainable methods for clean, readable code
• ✅ ILogger Integration - .Log(logger) chains into any ILogger
• ✅ Extensible - Custom messages, formatters, interceptors
• ✅ High Performance - Optimized for .NET 5-10, minimal overhead

---

📦 Package

Package	Version	Description
RecurPixel.EasyMessages		Works in console apps, background jobs, web APIs, and class libraries

dotnet add package RecurPixel.EasyMessages --version 1.0.0

---

📚 Documentation

📖 Complete Documentation

Quick Links

• 🚀 Getting Started in 5 Minutes
• 📖 Core Concepts
• 🌐 ASP.NET Core Integration
• 📝 Configuration Guide
• 💡 Examples
• 📚 API Reference

---

💡 Why EasyMessages?

Before EasyMessages

// Manual, inconsistent, scattered across codebase
public IActionResult Login(LoginDto dto)
{
    if (!_authService.ValidateCredentials(dto))
    {
        _logger.LogWarning("Login failed for user {Email}", dto.Email);
        return Unauthorized(new
        {
            success = false,
            message = "Invalid credentials",
            timestamp = DateTime.UtcNow
        });
    }

    var token = _authService.GenerateToken(dto);
    _logger.LogInformation("User {Email} logged in", dto.Email);
    return Ok(new
    {
        success = true,
        message = "Login successful",
        data = new { token },
        timestamp = DateTime.UtcNow
    });
}

With EasyMessages

// Clean, consistent, discoverable
public IActionResult Login(LoginDto dto)
{
    if (!_authService.ValidateCredentials(dto))
    {
        var msg = Msg.Auth.LoginFailed().Log(_logger);
        return StatusCode(msg.HttpStatusCode ?? 401, msg.ToJsonObject());
    }

    var success = Msg.Auth.LoginSuccessful()
        .WithData(new { token = _authService.GenerateToken(dto) })
        .Log(_logger);
    return StatusCode(success.HttpStatusCode ?? 200, success.ToJsonObject());
}

---

⚡ Performance

EasyMessages is optimized for .NET 5-10 with minimal overhead:

Benchmark Highlights (BenchmarkDotNet)

Operation	.NET 8.0	.NET 10.0	Memory
Baseline: Convert to API response	111.0 ns	106.0 ns (4.5% faster)	256 B
Simple message with parameters	1,630 ns	1,592 ns (2.4% faster)	560 B
Add single metadata	176.9 ns	169.4 ns (4.2% faster)	320 B
Chained operations	2,170 ns	2,120 ns (2.3% faster)	1.5 KB

Key Findings:

• ✅ Ultra-fast conversions: ~106ns for API response (9.4M ops/sec on .NET 10)
• ✅ .NET 10 is 2-4.5% faster across all operations
• ✅ Low memory overhead: 256B-1.5KB per operation
• ✅ Predictable performance with low standard deviation

Real-World Performance

✅ Registry lookups: 10,000 operations in ~10-20ms (100-200ns each)
✅ JSON formatting: 1,000 operations in ~3ms (3μs each)
✅ API conversion: 1,000,000 operations in ~119ms (119ns each)

Optimizations

• Span<T> and Memory<T> for zero-allocation string operations
• ArrayPool<T> for temporary buffers
• ValueStringBuilder for efficient string concatenation
• Lazy initialization patterns
• Object pooling for frequently used instances

📊 Detailed Benchmarks & Performance Analysis

---

🎯 Design Philosophy

1. Zero Configuration

Works immediately without setup. Configuration is optional, not required.

2. Fail Fast, Fail Clear

Exceptions are descriptive with helpful context for quick debugging.

3. Immutable by Design

Thread-safe operations with predictable, reliable behavior.

4. Extensible Architecture

Easy to add custom messages, formatters, interceptors, and stores.

---

📖 Message Categories

Category	Prefix	Count	Examples
Authentication	AUTH_*	10	Login failed, Unauthorized, Token expired
CRUD Operations	CRUD_*	15	Created, Updated, Deleted, Not found
Validation	VAL_*	12	Required field, Invalid format, Out of range
System	SYS_*	8	Error, Processing, Maintenance
Database	DB_*	5	Connection failed, Query timeout
Files	FILE_*	10	Uploaded, Invalid type, Size exceeded
Network	NET_*	8	Timeout, Service unavailable
Custom	*	∞	Your own messages

Total: 100+ built-in messages

---

🔧 Configuration Example

// ASP.NET Core - appsettings.json
{
  "EasyMessages": {
    "Logging": {
      "AutoLog": true,
      "MinimumLogLevel": "Warning"
    },
    "Storage": {
      "CustomMessagesPath": "messages/custom.json"
    },
    "Localization": {
      "DefaultLocale": "en-US",
      "EnableLocalization": true
    }
  }
}

// Program.cs - Use configuration presets
builder.Services.AddEasyMessages(builder.Configuration, options =>
{
    // Or configure manually
    options.Logging.AutoLog = true;
    options.Storage.CustomMessagesPath = "custom.json";
});

// Or use presets for common scenarios
builder.Services.AddEasyMessages(
    builder.Configuration,
    EasyMessagesPresets.Production // or Development, Testing, Staging, Api
);

📝 Complete Configuration Guide

---

🚦 Roadmap

• v0.1.0-beta - Core functionality, 100+ messages
• v1.0.0 - Production-ready, stable API, ILogger integration (Current)
• v1.x - Additional integrations (Serilog, FluentValidation, etc.)

---

✨ Status: Stable (v1.0.0)

APIs are stable and under semantic versioning. Ready for production use.

What's included:

• ✅ 100+ built-in messages across 10 categories
• ✅ JSON, XML, Console, PlainText formatters
• ✅ ILogger integration (.Log(logger))
• ✅ Parameter substitution, custom messages, interceptors
• ✅ Tested on .NET 8, 9, 10

📢 Report Issues | Give Feedback

---

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

• 🐛 Report Bugs
• 💡 Request Features
• 📖 Improve Documentation

---

📄 License

EasyMessages is licensed under the MIT License.

---

🙏 Acknowledgments

Built with ❤️ by RecurPixel

Special thanks to:

• Early beta testers
• The .NET community
• Everyone who provides feedback

---

⭐ Show Your Support

If you find EasyMessages useful:

• ⭐ Star the repository
• 🐛 Report bugs
• 💡 Suggest features
• 📢 Share with others

# Get started now!
dotnet add package RecurPixel.EasyMessages --version 1.0.0

---

Your feedback will shape the future of EasyMessages! 🚀