sharpessentials.functions 1.2.20

SharpEssentials

SharpEssentials is the ultimate C# utility library for .NET developers, helping you write cleaner, more efficient code with zero dependencies.

Table of Contents

• Features

• Installation

• Getting Started

• Usage Examples

• Async Toolkit Usage

• Roslyn Analyzer

• Why Choose SharpEssentials?

• Documentation

• Contributing

• Support & Community

• License

Features

Core Utilities

• Argument Validation: ThrowIfNull, ThrowIfEmpty, ThrowIfInvalid
• Type Helpers: Safe casting, null coalescing, enum parsing
• Exception Handling: Retry policies, exception unwrapping

Collections & LINQ

• Batch, DistinctBy, ToDictionarySafe
• ForEachWithIndex, Shuffle, Paginate

Functional Programming

• Option<T>, Result<T>, Either<L, R>
• Pattern matching extensions

String Operations

• Truncation, formatting, validation
• Levenshtein distance, phonetic matching

DateTime Helpers

Async Utilities

• SafeAwait() — await com ConfigureAwait(false) de forma segura

• Encadeamento .Then(...) para fluidez e legibilidade

• FireAndForgetSafe() com captura segura de exceções

• Rastreamento de contexto com AsyncTrackingContext

• Extensões para liberação manual de memória e descarte seguro

• Analisador Roslyn SNX001 — detecta await sem ConfigureAwait(false)

• Business day calculations

• Timezone conversions

• Human-readable intervals ("2 hours ago")

Installation

Use your preferred .NET package manager:

# NuGet Package Manager
Install-Package SharpEssentials

# .NET CLI
dotnet add package SharpEssentials

# Paket CLI
paket add SharpEssentials

Compatibility: .NET 8.0+

Getting Started

using SharpEssentials;

// Validate arguments
order.ThrowIfNull(nameof(order));

// Batch operations
var batches = Enumerable.Range(1, 1000).Batch(100);

// Functional result handling
var result = Result.Try(ParseConfigFile);
result.Match(
    success: config => Save(config),
    failure: ex => Log.Error(ex)
);

Usage Examples

Retry Policy with Exponential Backoff

var data = await RetryPolicy
    .WithExponentialBackoff(3, TimeSpan.FromSeconds(1))
    .ExecuteAsync(() => FetchRemoteDataAsync());

String Helpers

var clean = " HELLO world ".TrimAll(); // "HELLO world"
var similarity = "color".SimilarityTo("colour"); // 0.91

Why Choose SharpEssentials?

• Battle-tested in production
• Consistent, intuitive API
• Detailed XML docs with examples

Documentation

• 📖 Full API Reference
• 🌐 GitHub Wiki
• 🎬 Video Tutorials

Contributing

We welcome your contributions! Please:

1. Fork the repo
2. Create a feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m "Add AmazingFeature")
4. Push to branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

git clone https://github.com/yourname/SharpEssentials.git
cd SharpEssentials
dotnet restore
dotnet build
dotnet test

Support & Community

• 📚 FAQ
• 🐛 Report Issues
• 💬 Join our Discord
• 📢 Follow us on Twitter and LinkedIn

License

Distributed under the MIT License. See LICENSE for details.

Thank you for choosing SharpEssentials! 🎉 Happy coding! 💻🚀

Async Toolkit Usage

SafeAwait

Use em todos os await dentro de serviços, repositórios, bibliotecas e APIs:

await _myService.ExecuteAsync().SafeAwait();

Encadeamento com .Then(...)

Permite uma escrita fluida e segura:

await _myRepo.GetDataAsync()
    .Then(data => _processor.Process(data))
    .Then(() => _logger.LogAsync("Finalizado"));

Fire-and-Forget seguro

Ideal para tarefas paralelas sem travar o thread principal:

_log.LogAsync("Background Start").FireAndForgetSafe(ex => Console.WriteLine($"Erro: {ex.Message}"));

Rastreamento com AsyncTrackingContext

Log com ContextId para cada requisição/processamento assíncrono:

using var ctx = AsyncTrackingContext.Start("SyncProducts");
_logger.LogInformation("[CTX:{ContextId}] Início", ctx.ContextId);

// ...
_logger.LogInformation("[CTX:{ContextId}] Fim", ctx.ContextId);

Liberação explícita de memória

var stream = new MemoryStream();
stream.ForceGC(); // Descarta e força GC

object? obj = new ExpensiveResource();
obj.DisposeAndCollect(); // Se for IDisposable, será descartado e coletado

Roslyn Analyzer

Incluímos um analisador estático que avisa sempre que um await estiver sem .ConfigureAwait(false):

Diagnóstico

SNX001: Use ConfigureAwait(false) para evitar problemas de contexto e deadlocks

Exemplo errado

await ProcessAsync(); // ⚠️ Gera alerta SNX001

Correto

await ProcessAsync().ConfigureAwait(false); // ✅

Como ativar

Adicione como referência de analisador em seu .csproj:

<ItemGroup>
  <ProjectReference Include="..\SharpEssentials.Analyzer\SharpEssentials.Analyzer.csproj" OutputItemType="Analyzer" ReferenceOutputAssembly="false" />
</ItemGroup>