Cocoar.Capabilities 1.0.0

High-performance capability composition for .NET

A high-performance, low-allocation capability composition library for .NET that implements the Capability Composition pattern for building extensible, type-safe systems.

🚀 Features

• 🎯 Type-Safe Composition - Attach multiple capabilities to any object with full type safety
• ⚡ High Performance - Zero-allocation lookups and minimal overhead
• 🔒 Immutable Compositions - Thread-safe by design with immutable capability collections
• 🎨 Flexible Registration - Support for multiple contract types per capability
• 📦 Primary Capabilities - Enforce single "primary" capability per subject
• 🔄 Recomposition - Modify existing compositions safely
• 🎭 Custom Ordering - Control capability resolution order with flexible ordering strategies
• 🗂️ Registry Support - Optional registries for managing compositions across your application

📦 Installation

dotnet add package Cocoar.Capabilities

🎓 Quick Start

using Cocoar.Capabilities;

// Create a scope to manage capabilities
using var scope = new CapabilityScope();

// Define your subject
var document = new Document("README.md");

// Compose capabilities
var composition = scope.For(document)
    .Add(new EditCapability())
    .Add(new PrintCapability())
    .Add(new ShareCapability())
    .Build();

// Retrieve and use capabilities
var capabilities = composition.GetAll<EditCapability>();
foreach (var cap in capabilities)
{
    cap.Edit(document);
}

Primary Capabilities

Enforce a single "primary" capability per subject:

public record UserPrimaryCapability(string UserId, string Name) : IPrimaryCapability;

var composition = scope.For(user)
    .Add(new UserPrimaryCapability("user123", "John Doe"))
    .Add(new AdminCapability("Level2"))
    .Build();

// Retrieve the primary capability
var primary = composition.GetPrimary();
Console.WriteLine($"User: {primary.Name}");

Multiple Contracts

Register a single capability under multiple contract types:

var composition = scope.For(myObject)
    .AddAs<(IValidator, IFormatter)>(new DataProcessor())
    .Build();

// Access via either contract
var validator = composition.GetFirstOrDefault<IValidator>();
var formatter = composition.GetFirstOrDefault<IFormatter>();

📚 Documentation

• Examples - Detailed examples and use cases
• API Reference - Complete API documentation

🎯 Key Concepts

• CapabilityScope - Entry point for all capability operations
• Composer - Fluent builder for creating compositions
• Composition - Immutable collection of capabilities attached to a subject
• Primary Capability - Single "main" capability per subject (via IPrimaryCapability)
• Registry - Optional centralized management of compositions

Contributing & Versioning

• SemVer (additive MINOR, breaking MAJOR)
• PRs & issues welcome
• Licensed under Apache License 2.0 (explicit patent grant & attribution via NOTICE)

License & Trademark

This project is licensed under the Apache License, Version 2.0. See NOTICE for attribution.

"Cocoar" and related marks are trademarks of COCOAR e.U. Use of the name in forks or derivatives should preserve attribution and avoid implying official endorsement. See TRADEMARKS for permitted and restricted uses.