ImmediatePlatform · viceroypenguin · Jan 10, 2024 · Jan 5, 2024 · Jan 5, 2024 · Jan 5, 2024
diff --git a/.editorconfig b/.editorconfig
@@ -3,23 +3,34 @@
 root = true
 
 [*]
+charset = utf-8
+end_of_line = lf
 indent_style = tab
 insert_final_newline = true
 
 # Build scripts
 [*.{yml,yaml}]
-indent_style = spaces
 indent_size = 2
 
 # XML project files
 [*.{csproj,vbproj,vcxproj,vcxproj.filters,proj,projitems,shproj,props,targets,ruleset,config,nuspec,resx,vsixmanifest,vsct}]
+indent_style = tab
 indent_size = 2
 
+# Verify settings
+
+[*.{received,verified}.{txt,xml,json,cs}]
+indent_size = unset
+indent_style = unset
+insert_final_newline = false
+tab_width = unset
+trim_trailing_whitespace = false
+
 # Code files
 [*.cs]
 indent_size = 4
 tab_width = 4
-charset = utf-8-bom
+max_line_length = 150
 
 ## Dotnet code style settings:
 
@@ -31,10 +42,10 @@ dotnet_separate_import_directive_groups = false
 dotnet_style_require_accessibility_modifiers = for_non_interface_members:error
 
 # Avoid "this." and "Me." if not necessary
-dotnet_style_qualification_for_field = false:refactoring
-dotnet_style_qualification_for_property = false:refactoring
-dotnet_style_qualification_for_method = false:refactoring
-dotnet_style_qualification_for_event = false:refactoring
+dotnet_style_qualification_for_field = false
+dotnet_style_qualification_for_property = false
+dotnet_style_qualification_for_method = false
+dotnet_style_qualification_for_event = false
 
 # Use language keywords instead of framework type names for type references
 dotnet_style_predefined_type_for_locals_parameters_members = true:error
@@ -182,7 +193,7 @@ csharp_space_after_dot = false
 csharp_space_after_keywords_in_control_flow_statements = true
 csharp_space_after_semicolon_in_for_statement = true
 csharp_space_around_binary_operators = before_and_after
-csharp_space_around_declaration_statements = do_not_ignore
+csharp_space_around_declaration_statements = false
 csharp_space_before_colon_in_inheritance_clause = true
 csharp_space_before_comma = false
 csharp_space_before_dot = false
@@ -200,8 +211,16 @@ csharp_space_between_square_brackets = false
 
 # Blocks are allowed
 csharp_prefer_braces = when_multiline:silent
-csharp_preserve_single_line_blocks = true:silent
-csharp_preserve_single_line_statements = true:silent
+csharp_preserve_single_line_blocks = true
+csharp_preserve_single_line_statements = true
+
+# Resharper/Rider inspections
+resharper_trailing_comma_in_multiline_lists = true
+resharper_align_multiline_binary_expressions_chain = false
+resharper_align_multiline_comments = false
+resharper_align_multiline_statement_conditions = false
+resharper_indent_raw_literal_string = do_not_change
+resharper_csharp_max_line_length = 150
 
 # Style Analytics
 dotnet_analyzer_diagnostic.category-Style.severity = warning
@@ -215,6 +234,13 @@ dotnet_diagnostic.CS1712.severity = none                # CS1712: Type parameter
 # Async
 dotnet_diagnostic.CS1998.severity = error               # CS1998: Async method lacks 'await' operators and will run synchronously
 dotnet_diagnostic.CS4014.severity = error               # CS4014: Because this call is not awaited, execution of the current method continues before the call is completed
+dotnet_diagnostic.CA2007.severity = none                # CA2007: Consider calling ConfigureAwait on the awaited task
+
+# Immediate.Handlers relies on nested types
+dotnet_diagnostic.CA1034.severity = none                # CA1034: Nested types should not be visible
+
+# No need for cryptographically secure anything in this project
+dotnet_diagnostic.CA5394.severity = none                # CA5394: Random is an insecure random number generator
 
 # Dispose things need disposing
 dotnet_diagnostic.CA2000.severity = error               # CA2000: Dispose objects before losing scope
diff --git a/.gitattributes b/.gitattributes
@@ -1 +1 @@
-* text=auto eol=lf
+* text=auto
diff --git a/.gitignore b/.gitignore
@@ -13,5 +13,11 @@
 # VS Code cache/options directory
 .vscode/
 
+# Rider temporary files
+.idea/
+
 # TestResults
 [Tt]est[Rr]esults/
+
+# Verify
+*.received.*
diff --git a/Directory.Build.props b/Directory.Build.props
@@ -1,6 +1,7 @@
 <Project>
 	<PropertyGroup>
 		<LangVersion>latest</LangVersion>
+		<TargetFramework>net8.0</TargetFramework>
 
 		<Nullable>enable</Nullable>
 		<WarningsAsErrors>$(WarningsAsErrors);nullable;</WarningsAsErrors>
@@ -11,16 +12,16 @@
 		<EnforceCodeStyleInBuild>true</EnforceCodeStyleInBuild>
 
 		<GenerateDocumentationFile>true</GenerateDocumentationFile>
+		<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
+
+		<IsPackable>false</IsPackable>
 	</PropertyGroup>
 
 	<ItemGroup>
 		<PackageReference Include="PolySharp" PrivateAssets="All" />
 	</ItemGroup>
 
 	<PropertyGroup Condition="'$(GITHUB_ACTIONS)' == 'true'">
-		<!-- Don't block development work; but block CI if dev work isn't complete. -->
-		<TreatWarningsAsErrors>true</TreatWarningsAsErrors>
-
 		<ContinuousIntegrationBuild>true</ContinuousIntegrationBuild>
 		<EmbedUntrackedSources>true</EmbedUntrackedSources>
 		<CollectCoverage>true</CollectCoverage>

diff --git a/Directory.Packages.props b/Directory.Packages.props
@@ -1,20 +1,33 @@
 <Project>
-	<PropertyGroup>
-		<ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
-	</PropertyGroup>
+  <PropertyGroup>
+    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
+  </PropertyGroup>
 
-	<ItemGroup>
-		<PackageVersion Include="coverlet.collector" Version="6.0.0" />
-		<PackageVersion Include="coverlet.msbuild" Version="6.0.0" />
-		<PackageVersion Include="GitHubActionsTestLogger" Version="2.3.3" />
-		<PackageVersion Include="Microsoft.CodeAnalysis.Analyzers" Version="3.3.4" />
-		<PackageVersion Include="Microsoft.CodeAnalysis.CSharp" Version="4.8.0" />
-		<PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.8.0" />
-		<PackageVersion Include="Microsoft.SourceLink.GitHub" Version="8.0.0" />
-		<PackageVersion Include="MinVer" Version="4.3.0" />
-		<PackageVersion Include="PolySharp" Version="1.14.1" />
-		<PackageVersion Include="Scriban" Version="5.9.0" />
-		<PackageVersion Include="xunit" Version="2.6.4" />
-		<PackageVersion Include="xunit.runner.visualstudio" Version="2.5.6" />
-	</ItemGroup>
+  <ItemGroup>
+    <PackageVersion Include="Basic.Reference.Assemblies" Version="1.4.5" />
+    <PackageVersion Include="coverlet.collector" Version="6.0.0" />
+    <PackageVersion Include="coverlet.msbuild" Version="6.0.0" />
+    <PackageVersion Include="GitHubActionsTestLogger" Version="2.3.3" />
+    <PackageVersion Include="Microsoft.AspNetCore.OpenApi" Version="8.0.1" />
+    <PackageVersion Include="Microsoft.Bcl.HashCode" Version="1.1.1" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.Analyzers" Version="3.3.4" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.Common" Version="4.8.0" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.CSharp" Version="4.8.0" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.CSharp.Analyzer.Testing.XUnit" Version="1.1.1" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.CSharp.CodeFix.Testing.XUnit" Version="1.1.1" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.CSharp.Workspaces" Version="4.8.0" />
+    <PackageVersion Include="Microsoft.CodeAnalysis.Workspaces.Common" Version="4.8.0" />
+    <PackageVersion Include="Microsoft.Extensions.DependencyInjection" Version="8.0.0" />
+    <PackageVersion Include="Microsoft.Extensions.DependencyInjection.Abstractions" Version="8.0.0" />
+    <PackageVersion Include="Microsoft.NET.Test.Sdk" Version="17.8.0" />
+    <PackageVersion Include="Microsoft.SourceLink.GitHub" Version="8.0.0" />
+    <PackageVersion Include="MinVer" Version="4.3.0" />
+    <PackageVersion Include="PolySharp" Version="1.14.1" />
+    <PackageVersion Include="Scriban" Version="5.9.0" />
+    <PackageVersion Include="Swashbuckle.AspNetCore" Version="6.5.0" />
+    <PackageVersion Include="Verify.SourceGenerators" Version="2.2.0" />
+    <PackageVersion Include="Verify.Xunit" Version="22.11.4" />
+    <PackageVersion Include="xunit" Version="2.6.5" />
+    <PackageVersion Include="xunit.runner.visualstudio" Version="2.5.6" />
+  </ItemGroup>
 </Project>
diff --git a/Immediate.Handlers.sln b/Immediate.Handlers.sln
@@ -1,4 +1,4 @@
-
+
 Microsoft Visual Studio Solution File, Format Version 12.00
 # Visual Studio Version 17
 VisualStudioVersion = 17.0.31903.59
@@ -27,12 +27,20 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "Samples", "Samples", "{C484
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Immediate.Handlers", "src\Immediate.Handlers\Immediate.Handlers.csproj", "{4E9DC4CB-4833-4471-AF34-699565BCFDBE}"
 EndProject
-Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Immediate.Handlers.Utility", "src\Immediate.Handlers.Utility\Immediate.Handlers.Utility.csproj", "{789B0C8D-98ED-4712-8AB1-E4B10AD4D669}"
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Immediate.Handlers.Shared", "src\Immediate.Handlers.Shared\Immediate.Handlers.Shared.csproj", "{789B0C8D-98ED-4712-8AB1-E4B10AD4D669}"
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Immediate.Handlers.Tests", "tests\Immediate.Handlers.Tests\Immediate.Handlers.Tests.csproj", "{7E5E76EB-8087-48F6-8A87-CFABFC5CB409}"
 EndProject
 Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Normal", "samples\Normal\Normal.csproj", "{4E8FA4AC-7802-4775-AF8B-781B199EE5E6}"
 EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Immediate.Handlers.FunctionalTests", "tests\Immediate.Handlers.FunctionalTests\Immediate.Handlers.FunctionalTests.csproj", "{DB656BD6-AFA3-4285-8CD6-4EA91DB36D65}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Immediate.Handlers.CodeFixes", "src\Immediate.Handlers.CodeFixes\Immediate.Handlers.CodeFixes.csproj", "{0A786D44-F49E-46F6-A97E-9E8B75A12829}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Immediate.Handlers.Analyzers", "src\Immediate.Handlers.Analyzers\Immediate.Handlers.Analyzers.csproj", "{E9AF88B6-8719-4FDD-B99E-F060BB116073}"
+EndProject
+Project("{9A19103F-16F7-4668-BE54-9A1E7A4F7556}") = "Immediate.Handlers.Generators", "src\Immediate.Handlers.Generators\Immediate.Handlers.Generators.csproj", "{848CB147-CB80-448E-A1B1-30231A4F843C}"
+EndProject
 Global
 	GlobalSection(SolutionConfigurationPlatforms) = preSolution
 		Debug|Any CPU = Debug|Any CPU
@@ -55,6 +63,22 @@ Global
 		{4E8FA4AC-7802-4775-AF8B-781B199EE5E6}.Debug|Any CPU.Build.0 = Debug|Any CPU
 		{4E8FA4AC-7802-4775-AF8B-781B199EE5E6}.Release|Any CPU.ActiveCfg = Release|Any CPU
 		{4E8FA4AC-7802-4775-AF8B-781B199EE5E6}.Release|Any CPU.Build.0 = Release|Any CPU
+		{DB656BD6-AFA3-4285-8CD6-4EA91DB36D65}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{DB656BD6-AFA3-4285-8CD6-4EA91DB36D65}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{DB656BD6-AFA3-4285-8CD6-4EA91DB36D65}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{DB656BD6-AFA3-4285-8CD6-4EA91DB36D65}.Release|Any CPU.Build.0 = Release|Any CPU
+		{0A786D44-F49E-46F6-A97E-9E8B75A12829}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{0A786D44-F49E-46F6-A97E-9E8B75A12829}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{0A786D44-F49E-46F6-A97E-9E8B75A12829}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{0A786D44-F49E-46F6-A97E-9E8B75A12829}.Release|Any CPU.Build.0 = Release|Any CPU
+		{E9AF88B6-8719-4FDD-B99E-F060BB116073}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{E9AF88B6-8719-4FDD-B99E-F060BB116073}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{E9AF88B6-8719-4FDD-B99E-F060BB116073}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{E9AF88B6-8719-4FDD-B99E-F060BB116073}.Release|Any CPU.Build.0 = Release|Any CPU
+		{848CB147-CB80-448E-A1B1-30231A4F843C}.Debug|Any CPU.ActiveCfg = Debug|Any CPU
+		{848CB147-CB80-448E-A1B1-30231A4F843C}.Debug|Any CPU.Build.0 = Debug|Any CPU
+		{848CB147-CB80-448E-A1B1-30231A4F843C}.Release|Any CPU.ActiveCfg = Release|Any CPU
+		{848CB147-CB80-448E-A1B1-30231A4F843C}.Release|Any CPU.Build.0 = Release|Any CPU
 	EndGlobalSection
 	GlobalSection(SolutionProperties) = preSolution
 		HideSolutionNode = FALSE
@@ -65,6 +89,10 @@ Global
 		{789B0C8D-98ED-4712-8AB1-E4B10AD4D669} = {48400D35-471A-4EF4-93E4-2394D87E0012}
 		{7E5E76EB-8087-48F6-8A87-CFABFC5CB409} = {517768B6-A2B3-4ED2-8F70-E53C85A493FF}
 		{4E8FA4AC-7802-4775-AF8B-781B199EE5E6} = {C484CFC6-6DB0-48CB-A769-1A06FF40787E}
+		{DB656BD6-AFA3-4285-8CD6-4EA91DB36D65} = {517768B6-A2B3-4ED2-8F70-E53C85A493FF}
+		{0A786D44-F49E-46F6-A97E-9E8B75A12829} = {48400D35-471A-4EF4-93E4-2394D87E0012}
+		{E9AF88B6-8719-4FDD-B99E-F060BB116073} = {48400D35-471A-4EF4-93E4-2394D87E0012}
+		{848CB147-CB80-448E-A1B1-30231A4F843C} = {48400D35-471A-4EF4-93E4-2394D87E0012}
 	EndGlobalSection
 	GlobalSection(ExtensibilityGlobals) = postSolution
 		SolutionGuid = {184E3CAB-91E8-4F1A-A16B-C062F25BECC4}

diff --git a/Immediate.Handlers.sln.DotSettings b/Immediate.Handlers.sln.DotSettings
@@ -0,0 +1,3 @@
+<wpf:ResourceDictionary xml:space="preserve" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" xmlns:s="clr-namespace:System;assembly=mscorlib" xmlns:ss="urn:shemas-jetbrains-com:settings-storage-xaml" xmlns:wpf="http://schemas.microsoft.com/winfx/2006/xaml/presentation">
+	<s:String x:Key="/Default/CodeInspection/Highlighting/InspectionSeverities/=ArrangeObjectCreationWhenTypeNotEvident/@EntryIndexedValue">DO_NOT_SHOW</s:String>
+	<s:Boolean x:Key="/Default/UserDictionary/Words/=Msdi/@EntryIndexedValue">True</s:Boolean></wpf:ResourceDictionary>
diff --git a/readme.md b/readme.md
@@ -1,12 +1,139 @@
 # Immediate.Handlers
-| Name            | Status | History |
-| :---            | :---   | :---    |
-| GitHub Actions  | ![Build](https://github.com/viceroypenguin/Immediate.Handlers/actions/workflows/build.yml/badge.svg) | [![GitHub Actions Build History](https://buildstats.info/github/chart/viceroypenguin/Immediate.Handlers?branch=master&includeBuildsFromPullRequest=false)](https://github.com/viceroypenguin/Immediate.Handlers/actions) |
 
 [![NuGet](https://img.shields.io/nuget/v/Immediate.Handlers.svg?style=plastic)](https://www.nuget.org/packages/Immediate.Handlers/)
 [![GitHub release](https://img.shields.io/github/release/viceroypenguin/Immediate.Handlers.svg)](https://GitHub.com/viceroypenguin/Immediate.Handlers/releases/)
 [![GitHub license](https://img.shields.io/github/license/viceroypenguin/Immediate.Handlers.svg)](https://github.com/viceroypenguin/Immediate.Handlers/blob/master/license.txt) 
 [![GitHub issues](https://img.shields.io/github/issues/viceroypenguin/Immediate.Handlers.svg)](https://GitHub.com/viceroypenguin/Immediate.Handlers/issues/) 
 [![GitHub issues-closed](https://img.shields.io/github/issues-closed/viceroypenguin/Immediate.Handlers.svg)](https://GitHub.com/viceroypenguin/Immediate.Handlers/issues?q=is%3Aissue+is%3Aclosed) 
+[![GitHub Actions](https://github.com/viceroypenguin/Immediate.Handlers/actions/workflows/build.yml/badge.svg)](https://github.com/viceroypenguin/Immediate.Handlers/actions)
 ---
 
+Immediate.Handlers is an implementation of the mediator pattern in .NET using source-generation. All pipeline behaviors
+are determined and the call-tree built at compile-time; meaning that all dependencies are enforced via compile-time
+safety checks. Behaviors and dependencies are obtained via DI at runtime based on compile-time determined dependencies.
+
+#### Examples
+* Minimal Api: [Normal](./samples/Normal)
+
+## Installing Immediate.Handlers
+
+You can install [Immediate.Handlers with NuGet](https://www.nuget.org/packages/Immediate.Handlers):
+
+    Install-Package Immediate.Handlers
+
+Or via the .NET Core command line interface:
+
+    dotnet add package Immediate.Handlers
+
+Either commands, from Package Manager Console or .NET Core CLI, will download and install Immediate.Handlers.
+
+## Using Immediate.Handlers
+### Creating Handlers
+
+Create a Handler by adding the following code:
+
+```cs
+[Handler]
+public static class GetUsersQuery
+{
+    public record Query;
+
+    private static Task<IEnumerable<User>> HandleAsync(
+        Query _,
+        UsersService usersService,
+        CancellationToken token)
+    {
+        return usersService.GetUsers();
+    }
+}
+```
+
+This will automatically create a new class, `GetUsersQuery.Handler`, which encapsulates the following:
+* attaching any behaviors defined for all queries in the assembly
+* using a class to receive any DI services, such as `UsersService`
+
+Any consumer can now do the following:
+```cs
+public class Consumer(GetUsersQuery.Handler handler)
+{
+	public async Task Consumer(CancellationToken token)
+	{
+		var response = await handler.HandleAsync(new(), token);
+		// do something with response
+	}
+}
+```
+
+### Creating Behaviors
+
+Create a behavior by implementing the `Immediate.Handlers.Shared.Behaviors<,>` class, as so:
+```cs
+public sealed class LoggingBehavior<TRequest, TResponse>(ILogger<LoggingBehavior<TRequest, TResponse>> logger)
+	: Behavior<TRequest, TResponse>
+{
+	public override async Task<TResponse> HandleAsync(TRequest request, CancellationToken cancellationToken)
+	{
+		logger.LogInformation("LoggingBehavior.Enter");
+		var response = await Next(request, cancellationToken);
+		logger.LogInformation("LoggingBehavior.Exit");
+		return response;
+	}
+}
+```
+
+This can be registered assembly-wide using:
+```cs
+[assembly: Behaviors(
+	typeof(LoggingBehavior<,>)
+)]
+```
+
+or on an individual handler using:
+```cs
+[Handler]
+[Behavior(
+	typeof(LoggingBehavior<,>)
+)]
+public static class GetUsersQuery
+{
+	// ..
+}
+```
+
+Once added to the pipeline, the behavior will be called as part of the pipeline to handle a request.
+
+Note: adding a `[Behavior]` attribute to a handler will disregard all assembly-wide behaviors for that handler, so any
+global behaviors necessary must be independently added to the handler override behaviors list.
+
+#### Behavior Constraints
+
+A constraint can be added to a behavior by using:
+```cs
+public sealed class LoggingBehavior<TRequest, TResponse>
+	: Behavior<TRequest, TResponse>
+	where TRequest : IRequestConstraint
+	where TResponse : IResponseConstraint
+```
+
+When a pipeline is generated, all potential behaviors are evaluated against the request and response types, and if
+either type does not match a given constraint, the behavior is not added to the generated pipeline.
+
+### Registering with `IServiceCollection`
+
+Immediate.Handlers supports `Microsoft.Extensions.DependencyInjection.Abstractions` directly. 
+
+#### Registering Handlers
+
+```cs
+services.AddHandlers();
+```
+
+This registers all classes in the assembly marked with `[Handler]`.
+
+#### Registering Behaviors
+
+```cs
+services.AddBehaviors();
+```
+
+This registers all behaviors referenced in any `[Behaviors]` attribute.