Pixiray.AI.Data.Mongodb 0.0.1

Pixiray.AI.Data.Mongodb

A high-performance .NET MongoDB repository library with flexible entity support, automatic caching, bulk operations, and comprehensive querying capabilities. Build modern applications without being forced to inherit from base entities.

✨ Features

• 🔥 Flexible Entity System - Works with POCOs, BsonDocument, and ExpandoObject
• ⚡ High Performance - Async-first with parallel operations and buffer optimization
• 🧠 Smart Caching - Automatic timestamp-based cache invalidation
• 📦 Bulk Operations - Efficient bulk insert, update, and delete operations
• 🔍 Advanced Querying - LINQ expressions with pattern matching support
• 🏗️ Dependency Injection - First-class DI support with decorator pattern
• 📊 Observability - Built-in logging, metrics, and transaction auditing
• 🔄 Unit of Work - Transaction support with automatic rollback
• 🎯 Zero Inheritance - No need to inherit from base entity classes

🚀 Quick Start

Installation

dotnet add package Pixiray.AI.Data.Mongodb

Basic Setup

using Pixiray.AI.Data.Mongodb.Extensions;

// Configure services
services.AddMongoDbRepositories("mongodb://localhost:27017", "MyDatabase", options =>
{
    options.EnableAutoTimestamps = true;
    options.HandleBsonDocuments = true;
    options.HandleExpandoObjects = true;
});

// Add caching
services.AddRepositoryCaching(TimeSpan.FromMinutes(10));

Simple Entity Example

// No inheritance required!
public class User
{
    [BsonId]
    [BsonRepresentation(BsonType.ObjectId)]
    public string Id { get; set; } = ObjectId.GenerateNewId().ToString();
    
    public string Name { get; set; } = string.Empty;
    public string Email { get; set; } = string.Empty;
    public DateTime CreatedAt { get; set; } = DateTime.UtcNow;
}

// Use in your service
public class UserService
{
    private readonly IRepository<User> _userRepository;
    
    public UserService(IRepository<User> userRepository)
    {
        _userRepository = userRepository;
    }
    
    public async Task<User> CreateUserAsync(string name, string email)
    {
        var user = new User { Name = name, Email = email };
        await _userRepository.InsertAsync(user);
        return user;
    }
    
    public async Task<User?> GetUserAsync(string id)
    {
        return await _userRepository.GetByIdAsync(id); // Cached automatically!
    }
    
    public async Task<IEnumerable<User>> SearchUsersAsync(string searchTerm)
    {
        return await _userRepository.ListAsync(u => u.Name.Contains(searchTerm));
    }
}

🎯 Entity Flexibility

Work with any entity type:

1. Simple POCOs

public class Product
{
    public string Id { get; set; }
    public string Name { get; set; }
    public decimal Price { get; set; }
}

2. BsonDocument (Dynamic)

var document = new BsonDocument
{
    ["_id"] = ObjectId.GenerateNewId(),
    ["name"] = "Dynamic Product",
    ["properties"] = new BsonDocument
    {
        ["color"] = "blue",
        ["size"] = "large"
    }
};

await _bsonRepository.InsertAsync(document);

3. ExpandoObject (Dynamic .NET)

dynamic entity = new ExpandoObject();
entity._id = ObjectId.GenerateNewId().ToString();
entity.name = "Dynamic Entity";
entity.isActive = true;

await _expandoRepository.InsertAsync(entity);

🧠 Smart Caching

The library automatically manages cache timestamps without requiring inheritance:

// First call - fetches from database and caches
var user = await userRepository.GetByIdAsync("123");

// Second call - returns from cache (much faster!)
var cachedUser = await userRepository.GetByIdAsync("123");

// Update invalidates cache automatically
user.Name = "Updated Name";
await userRepository.UpdateAsync(user);

// Next call fetches fresh data from database
var freshUser = await userRepository.GetByIdAsync("123");

📦 Bulk Operations

Efficient bulk operations for high-throughput scenarios:

// Bulk insert
var users = new List<User> { /* ... */ };
await bulkRepository.BulkInsertAsync(users);

// Bulk update
var updates = users.Select(u => new { Filter = u.Id, Update = u });
await bulkRepository.BulkUpdateAsync(updates);

// Bulk delete
var idsToDelete = new[] { "id1", "id2", "id3" };
await bulkRepository.BulkDeleteAsync(idsToDelete);

🔄 Unit of Work & Transactions

public class OrderService
{
    private readonly IUnitOfWork _unitOfWork;
    
    public async Task ProcessOrderAsync(Order order)
    {
        await _unitOfWork.BeginTransactionAsync();
        
        try
        {
            var userRepo = _unitOfWork.GetRepository<User>();
            var productRepo = _unitOfWork.GetRepository<Product>();
            var orderRepo = _unitOfWork.GetRepository<Order>();
            
            // All operations within the same transaction
            await userRepo.UpdateAsync(order.User);
            await productRepo.UpdateAsync(order.Product);
            await orderRepo.InsertAsync(order);
            
            await _unitOfWork.CommitAsync();
        }
        catch
        {
            await _unitOfWork.RollbackAsync();
            throw;
        }
    }
}

🔍 Advanced Querying

// Complex LINQ queries
var activeUsers = await repository.ListAsync(u => 
    u.IsActive && 
    u.CreatedAt > DateTime.UtcNow.AddDays(-30) &&
    u.Roles.Contains("Admin"));

// Pattern matching
var users = await repository.ListByPatternAsync("Name", "*john*", PatternType.Wildcard);

// Pagination
var (users, totalCount) = await repository.GetPagedAsync(
    filter: u => u.IsActive,
    pageNumber: 1,
    pageSize: 20,
    orderBy: u => u.CreatedAt);

📊 Configuration Options

services.AddMongoDbRepositories(connectionString, databaseName, options =>
{
    // Automatic timestamp injection
    options.EnableAutoTimestamps = true;
    options.TimestampFieldName = "__cacheTimestamp";
    
    // Entity type support
    options.HandleBsonDocuments = true;
    options.HandleExpandoObjects = true;
    
    // Backward compatibility
    options.UseTimestampedEntityFallback = true;
    options.PreserveUserTimestamps = true;
    
    // Exclude specific types from automatic timestamping
    options.ExcludedTypes.Add(typeof(AuditLog));
});

🏗️ Architecture

The library follows clean architecture principles with:

• Repository Pattern - Simple, testable data access
• Decorator Pattern - Composable features (caching, retry, logging)
• Dependency Injection - Framework-agnostic IoC support
• Async/Await - Non-blocking operations throughout
• Interface Segregation - Focused, single-responsibility interfaces

📚 Documentation

• Getting Started Guide
• Configuration Reference
• API Documentation
• Performance Guide
• Migration Guide

🧪 Testing

# Run tests
dotnet test

# Run with coverage
dotnet test --collect:"XPlat Code Coverage"

🤝 Contributing

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

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙋‍♂️ Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

🎯 Roadmap

• Redis caching support
• GraphQL integration
• More database providers
• Performance optimizations
• Additional bulk operations

Built with ❤️ by Pixiray AI