Space - GitLite

KO | EN

gitlite — search

#python #react #llm #golang #go #rust #java #windows #awesome #cli #vue #pytorch #security #mcp

Space

(★ 176)

High-performance, source-generator powered mediator and messaging framework for .NET.

File Explorer

Download Latest Version (.zip)

- - benchmarks.yml
  - dev-ci.yml
  - pages.yml
  - prod-ci.yml
  - validation-build.yml
- copilot-instructions.md
- FUNDING.yml
- Contribution.md
- DeveloperRecommendations.md
- GlobalPipelines.md
- Handlers.md
- index.html
- KnownIssues.md
- Modules.md
- MultiProjectSetup.md
- Notifications.md
- Pipelines.md
- PlannedImprovements.md
- ProjectDoc.en.md
- ProjectDoc.txt
- Versioning.md
- VoidLikeHandlers.md
- - BaseConfig.cs
  - GlobalUsings.cs
  - icon.png
  - ISpace.cs
  - Nothing.cs
  - README.md
  - Space.Abstraction.csproj
  - SpaceOptions.cs
- - Constants.cs
  - GlobalUsings.cs
  - icon.png
  - README.md
  - ServiceCollectionExtensions.cs
  - Space.cs
  - Space.DependencyInjection.csproj
  - SpaceExtensions.cs
- - Constants.cs
  - icon.png
  - SourceGenConstants.cs
  - Space.SourceGenerator.csproj
  - SpaceSourceGenerator.cs
- - Program.cs
  - Space.Benchmarks.csproj
- - Program.cs
  - Space.TestConsole.csproj
- - MSTestSettings.cs
  - Space.Tests.csproj
.gitattributes
.gitignore
dotnet-install.sh
LICENSE.txt
README.md
SpaceSolution.sln

# Installation Guide

1. Get the code

git clone https://github.com/salihcantekin/Space

Downloads the entire project code from GitHub to your computer.

cd Space

Moves into the project folder you just downloaded.

2. .NET

Medium Recommended

Prerequisites

Git Needed to download the project code from GitHub.
.NET SDK The SDK required for the dotnet command.

dotnet add package Space.Abstraction

Type this command into your terminal and run it.

dotnet add package Space.DependencyInjection

Type this command into your terminal and run it.

dotnet add package Space.Modules.InMemoryCache

Type this command into your terminal and run it.

✅ After dotnet run, check the message or address shown in the terminal.

Pulled directly from this repo's README.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Space

High-performance, source-generator powered mediator / messaging framework for .NET. Eliminates runtime reflection, minimizes boilerplate, and provides an extensible module + pipeline model for cross-cutting concerns (e.g., caching, auditing).

**Links:** [Project Website](https://salihcantekin.github.io/Space/) · [GitHub](https://github.com/salihcantekin/Space) · [NuGet: Space.Abstraction](https://www.nuget.org/packages/Space.Abstraction)

---
## Status & Packages

| CI | Branch | Status |
|----|--------|--------|
| Prod (Stable Publish) | `master` | ![Prod CI](https://github.com/salihcantekin/Space/actions/workflows/prod-ci.yml/badge.svg) |
| Dev (Preview Publish) | `dev` | ![Dev CI](https://github.com/salihcantekin/Space/actions/workflows/dev-ci.yml/badge.svg) |
| Validation (PR / Feature) | PRs -> `dev` / `master` | ![Validation Build](https://github.com/salihcantekin/Space/actions/workflows/validation-build.yml/badge.svg) |

### NuGet Packages

| Package | Stable | Preview | Downloads | Description |
|---------|--------|---------|-----------|-------------|
| Space.Abstraction | ![NuGet](https://img.shields.io/nuget/v/Space.Abstraction.svg) | ![NuGet (pre)](https://img.shields.io/nuget/vpre/Space.Abstraction.svg) | ![Downloads](https://img.shields.io/nuget/dt/Space.Abstraction.svg) | Core abstractions + Source Generator analyzer (attributes, contexts, contracts) |
| Space.DependencyInjection | ![NuGet](https://img.shields.io/nuget/v/Space.DependencyInjection.svg) | ![NuGet (pre)](https://img.shields.io/nuget/vpre/Space.DependencyInjection.svg) | ![Downloads](https://img.shields.io/nuget/dt/Space.DependencyInjection.svg) | DI extensions & runtime implementations (ISpace) |
| [Space.Modules.InMemoryCache](https://github.com/salihcantekin/Space.Modules.InMemoryCache) | ![NuGet](https://img.shields.io/nuget/v/Space.Modules.InMemoryCache.svg) | ![NuGet (pre)](https://img.shields.io/nuget/vpre/Space.Modules.InMemoryCache.svg) | ![Downloads](https://img.shields.io/nuget/dt/Space.Modules.InMemoryCache.svg) | In-memory caching module + attribute integration |

### Breaking Change (Packaging)
Old behavior: `Space.DependencyInjection` implicitly brought abstractions + source generator.
New behavior: Source generator analyzer ships with `Space.Abstraction`. You must reference BOTH packages for full DI usage.

Migration:
1. Add `Space.Abstraction` to all projects that use Space attributes.
2. Add `Space.DependencyInjection` only where you need `ISpace` and registration extensions.
3. Remove any direct `Space.SourceGenerator` references; they are now unnecessary.

### Install (Minimal DI Usage)
```bash
dotnet add package Space.Abstraction

dotnet add package Space.DependencyInjection
```
Optional module:
```bash
dotnet add package Space.Modules.InMemoryCache
```
If you only need compile-time generation (e.g., custom runtime) reference just `Space.Abstraction`.

---
## Quick Start
```csharp
using Microsoft.Extensions.DependencyInjection;
using Space.Abstraction;
using Space.Abstraction.Attributes;
using Space.Abstraction.Context;
using Space.Abstraction.Contracts;

var services = new ServiceCollection();
services.AddSpace(opt =>
{
    opt.NotificationDispatchType = NotificationDispatchType.Parallel; // or Sequential
});

services.AddSpaceInMemoryCache(); // if caching module needed

var provider = services.BuildServiceProvider();
var space = provider.GetRequiredService<ISpace>();

public sealed record UserLoginRequest(string UserName) : IRequest<UserLoginResponse>;
public sealed record UserLoginResponse(bool Success);

public class UserHandlers
{
    [Handle]
    public ValueTask<UserLoginResponse> Login(HandlerContext<UserLoginRequest> ctx)
        => ValueTask.FromResult(new UserLoginResponse(true));
}

// Interface-based (optional, for method signature hint only - [Handle] attribute is still required)
public class UserHandlersInterface : IHandler<UserLoginRequest, UserLoginResponse>
{
    [Handle]
    public ValueTask<UserLoginResponse> Handle(HandlerContext<UserLoginRequest> ctx)
        => ValueTask.FromResult(new UserLoginResponse(true));
}

var response1 = await space.Send<UserLoginResponse>(new UserLoginRequest("demo"));
var response2 = await space.Send<UserLoginRequest, UserLoginResponse>(new UserLoginRequest("demo"));
```

### Named Handlers
```csharp
public class PricingHandlers
{
    [Handle(Name = "Default")] public ValueTask<PriceResult> GetDefault(HandlerContext<PriceQuery> ctx) => ...;
    [Handle(Name = "Discounted")] public ValueTask<PriceResult> GetDiscounted(HandlerContext<PriceQuery> ctx) => ...;
}
var discounted = await space.Send<PriceResult>(new PriceQuery(...), name: "Discounted");
```

### Pipelines
```csharp
public class LoggingPipeline
{
    [Pipeline(Order = 100)]
    public async ValueTask<UserLoginResponse> Log(PipelineContext<UserLoginRequest> ctx, PipelineDelegate<UserLoginRequest, UserLoginResponse> next)
    {
        var result = await next(ctx);
        return result;
    }
}
```

### Global Pipelines

Global pipelines automatically apply to **all handlers** with matching request/response types - ideal for cross-cutting concerns like logging, validation, and exception handling.

```csharp
public class GlobalLoggingPipeline
{
    [GlobalPipeline(Order = 10, ExecutionStage = GlobalPipelineExecutionStage.BeforeHandler)]
    public async ValueTask<TResponse> Log<TRequest, TResponse>(
        PipelineContext<TRequest> ctx,
        PipelineDelegate<TRequest, TResponse> next)
    {
        Console.WriteLine($"Handling {typeof(TRequest).Name}");
        var response = await next(ctx);
        Console.WriteLine($"Completed {typeof(TRequest).Name}");
        return response;
    }
}
```

**Key Features:**
- **Automatic application**: No need to attach to each handler individually
- **Execution stages**: Control when pipelines run relative to handler-specific pipelines
  - `BeforeHandler` (default): Outermost layer, runs first
  - `BeforeHandlerInner`: After handler pipelines, before handler
  - `AfterHandlerInner`: After handler, before handler pipelines unwind
  - `AfterHandler`: Outermost post-handler layer
- **Zero overhead**: When no global pipelines are registered, no performance impact
- **Type-safe**: Validated at compile time by the source generator

For complete documentation including execution flow, best practices, and common patterns, see [GlobalPipelines.md](docs/GlobalPipelines.md).

### Notifications
```csharp
public sealed record UserLoggedIn(string UserName);
public class LoginNotifications
{
    [Notification]
    public ValueTask Log(NotificationContext<UserLoggedIn> ctx) => ValueTask.CompletedTask;
}
await space.Publish(new UserLoggedIn("demo"));
```

### Caching Module Example
```csharp
public class UserQueries
{
    [Handle]
    [CacheModule(Duration = 60)]
    public ValueTask<UserProfile?> GetUser(HandlerContext<UserId> ctx) => ...;
}
```
`[CacheModule]` (from Space.Modules.InMemoryCache) inserts caching logic before user pipelines.

---
## Multi-Project Setup

Space supports handlers, pipelines, notifications, and modules across multiple projects through a **root aggregator** model. This enables modular solutions where feature libraries can contain their own handlers without manual DI wiring.

### Configuration

Set exactly **one** project as the root aggregator (typically your host/composition root):

```xml
<PropertyGroup>
  <SpaceGenerateRootAggregator>true</SpaceGenerateRootAggregator>
</PropertyGroup>
```

All other handler libraries should either omit this property or set it to `false`:

```xml
<PropertyGroup>
  <SpaceGenerateRootAggregator>false</SpaceGenerateRootAggregator>
</PropertyGroup>
```

### How It Works

- **Root project** generates `DependencyInjectionExtensions.g.cs` with automatic assembly discovery
- **Satellite libraries** generate lightweight `SpaceAssemblyRegistration_<Assembly>.g.cs` files
- At runtime, the root automatically discovers and registers handlers from all referenced assemblies

### Example Structure
```
/MySolution
  src/AppHost/               (root: SpaceGenerateRootAggregator=true)
  src/Features/Users/        (satellite: handlers, pipelines)
  src/Features/Billing/      (satellite: handlers, modules)
  src/Infrastructure/        (satellite: notifications)
```

For complete details, migration guidance, and troubleshooting, see [MultiProjectSetup.md](docs/MultiProjectSetup.md).

---
## Key Features
- Zero runtime reflection for discovery (Roslyn source generator)
- Minimal boilerplate: annotate methods directly with `[Handle]`, `[Pipeline]`, `[Notification]`
- Named handlers (multiple strategies for same request/response)
- Orderable pipelines + early system module execution
- **Global pipelines** for cross-cutting concerns (logging, validation, exception handling)
- Extensible module model (e.g., cache) before user pipelines
- High-performance async signatures (`ValueTask`)
- Parallel or sequential notification dispatch
- Multi-project root aggregator property `<SpaceGenerateRootAggregator>`
- Multi-targeting (netstandard2.0 + modern .NET)

---
## Performance Philosophy
Space front-loads cost at build time to reduce runtime overhead:
- Compile-time metadata (registrations, maps)
- No reflection-based runtime scanning
- Low allocation pathways (current & planned pooling)

Benchmarks compare against other mediator libraries in `tests/Space.Benchmarks`.

---
## Documentation
Primary docs in `docs/`:

| Topic | Link |
|-------|------|
| Project Overview | [ProjectDoc.en.md](docs/ProjectDoc.en.md) |
| Handlers | [Handlers](docs/Handlers.md) |
| Pipelines | [Pipelines](docs/Pipelines.md) |
| Global Pipelines | [GlobalPipelines](docs/GlobalPipelines.md) |
| Notifications | [Notifications](docs/Notifications.md) |
| Modules | [Modules](docs/Modules.md) |
| Multi-Project Setup | [MultiProjectSetup](docs/MultiProjectSetup.md) |
| Developer Recommendations | [DeveloperRecommendations](docs/DeveloperRecommendations.md) |
| Known Issues | [KnownIssues](docs/KnownIssues.md) |
| Planned Improvements | [PlannedImprovements](docs/PlannedImprovements.md) |

Per-package:
- [Space.Abstraction](src/Space.Abstraction/README.md)
- [Space.DependencyInjection](src/Space.DependencyInjection/README.md)

---
## Roadmap & Issues
See GitHub Issues for:
- Planned improvements (attribute parameters, global defaults, Options pattern)
- Known issues (initial Lazy `ISpace` null, module scoping bugs)

Contributions welcome via issues & PRs.

---
## Versioning & Releases
- `master`: tagged semantic versions (`vX.Y.Z`) ? stable NuGet
- `dev`: preview releases (`X.Y.Z-preview`)
- Feature branches: validation build only

---
## License
MIT.

---
## Disclaimer
APIs may evolve while early preview features stabilize. Track releases for changes.

---
# Space (Short)

Space is a high-performance, source-generator powered mediator/messaging framework for .NET.

- Docs: see the `docs/` folder
- Contribution guide for modules: see [docs/Contribution.md](docs/Contribution.md)

## Quick links
- Handlers: docs/Handlers.md
- Pipelines: docs/Pipelines.md
- Global Pipelines: docs/GlobalPipelines.md
- Notifications: docs/Notifications.md
- Known Issues: docs/KnownIssues.md
- Developer Recommendations: docs/DeveloperRecommendations.md

## Build
See `.github/copilot-instructions.md` for environment and common commands.