Update README

Author: Nikolay Pianikov

AGENTS.md

@@ -1642,6 +1642,85 @@ The key points are:
 - The `Dependency` (or `Ordinal`) attribute is used to mark the property for injection
 - The DI automatically injects the dependency when resolving the object graph
 
+## Nullable reference types
+
+Pure.DI preserves nullable reference type annotations when it reads dependency contracts, builds the graph, and generates composition members.
+Use nullable dependencies for values that are allowed to be absent. A nullable root or composition argument does not get a generated null check, while a non-null reference argument still does.
+A non-null binding can satisfy a nullable dependency request. This is useful for optional constructor parameters, nullable factory results, and nullable collection elements.
+>[!TIP]
+>`T?` means that the consumer can handle `null`; it does not mean that a missing binding is ignored. If no binding or auto-binding can provide the type, Pure.DI still reports the graph error.
+
+```c#
+using Shouldly;
+using Pure.DI;
+using System.Collections.Generic;
+using System.Linq;
+
+DI.Setup(nameof(Composition))
+    .Hint(Hint.Resolve, "Off")
+    .Bind<IDatabase>().To<Database>()
+    .Bind<IReportService>().To<ReportService>()
+
+    // Nullable composition argument: no generated null check
+    .Arg<string?>("defaultTitle", "title")
+
+    // Nullable root argument: no generated null check
+    .RootArg<string?>("connectionString", "connection")
+
+    // Composition root
+    .Root<IReportService>("CreateReportService");
+
+var composition = new Composition(defaultTitle: null);
+var reportService = composition.CreateReportService(connectionString: null);
+
+reportService.DefaultTitle.ShouldBeNull();
+reportService.ConnectionString.ShouldBeNull();
+reportService.OptionalDatabase.ShouldNotBeNull();
+reportService.Databases.Count.ShouldBe(1);
+
+interface IDatabase;
+
+class Database : IDatabase;
+
+interface IReportService
+{
+    string? DefaultTitle { get; }
+
+    string? ConnectionString { get; }
+
+    IDatabase? OptionalDatabase { get; }
+
+    IReadOnlyList<IDatabase?> Databases { get; }
+}
+
+class ReportService(
+    [Tag("title")] string? defaultTitle,
+    [Tag("connection")] string? connectionString,
+    IDatabase? optionalDatabase,
+    IEnumerable<IDatabase?> databases)
+    : IReportService
+{
+    public string? DefaultTitle { get; } = defaultTitle;
+
+    public string? ConnectionString { get; } = connectionString;
+
+    public IDatabase? OptionalDatabase { get; } = optionalDatabase;
+
+    public IReadOnlyList<IDatabase?> Databases { get; } = databases.ToList();
+}
+```
+
+To run the above code, the following NuGet packages must be added:
+ - [Pure.DI](https://www.nuget.org/packages/Pure.DI)
+ - [Shouldly](https://www.nuget.org/packages/Shouldly)
+
+Limitations: nullable annotations describe compile-time contracts. They are not runtime validation rules and do not replace explicit domain validation.
+Common pitfalls:
+- Using `T?` to hide a missing binding instead of modelling an optional value.
+- Forgetting tags for nullable primitive values when several values of the same type exist.
+- Assuming `IEnumerable<T?>` changes the lifetime of elements; lifetime still comes from the matched bindings.
+See also: [Composition arguments](composition-arguments.md), [Root arguments](root-arguments.md), [Injection on demand](injection-on-demand.md).
+
 ## Default values
 
 This example shows how to use default values in dependency injection when explicit injection is not possible.

AGENTS_MEDIUM.md

@@ -1642,6 +1642,85 @@ The key points are:
 - The `Dependency` (or `Ordinal`) attribute is used to mark the property for injection
 - The DI automatically injects the dependency when resolving the object graph
 
+## Nullable reference types
+
+Pure.DI preserves nullable reference type annotations when it reads dependency contracts, builds the graph, and generates composition members.
+Use nullable dependencies for values that are allowed to be absent. A nullable root or composition argument does not get a generated null check, while a non-null reference argument still does.
+A non-null binding can satisfy a nullable dependency request. This is useful for optional constructor parameters, nullable factory results, and nullable collection elements.
+>[!TIP]
+>`T?` means that the consumer can handle `null`; it does not mean that a missing binding is ignored. If no binding or auto-binding can provide the type, Pure.DI still reports the graph error.
+
+```c#
+using Shouldly;
+using Pure.DI;
+using System.Collections.Generic;
+using System.Linq;
+
+DI.Setup(nameof(Composition))
+    .Hint(Hint.Resolve, "Off")
+    .Bind<IDatabase>().To<Database>()
+    .Bind<IReportService>().To<ReportService>()
+
+    // Nullable composition argument: no generated null check
+    .Arg<string?>("defaultTitle", "title")
+
+    // Nullable root argument: no generated null check
+    .RootArg<string?>("connectionString", "connection")
+
+    // Composition root
+    .Root<IReportService>("CreateReportService");
+
+var composition = new Composition(defaultTitle: null);
+var reportService = composition.CreateReportService(connectionString: null);
+
+reportService.DefaultTitle.ShouldBeNull();
+reportService.ConnectionString.ShouldBeNull();
+reportService.OptionalDatabase.ShouldNotBeNull();
+reportService.Databases.Count.ShouldBe(1);
+
+interface IDatabase;
+
+class Database : IDatabase;
+
+interface IReportService
+{
+    string? DefaultTitle { get; }
+
+    string? ConnectionString { get; }
+
+    IDatabase? OptionalDatabase { get; }
+
+    IReadOnlyList<IDatabase?> Databases { get; }
+}
+
+class ReportService(
+    [Tag("title")] string? defaultTitle,
+    [Tag("connection")] string? connectionString,
+    IDatabase? optionalDatabase,
+    IEnumerable<IDatabase?> databases)
+    : IReportService
+{
+    public string? DefaultTitle { get; } = defaultTitle;
+
+    public string? ConnectionString { get; } = connectionString;
+
+    public IDatabase? OptionalDatabase { get; } = optionalDatabase;
+
+    public IReadOnlyList<IDatabase?> Databases { get; } = databases.ToList();
+}
+```
+
+To run the above code, the following NuGet packages must be added:
+ - [Pure.DI](https://www.nuget.org/packages/Pure.DI)
+ - [Shouldly](https://www.nuget.org/packages/Shouldly)
+
+Limitations: nullable annotations describe compile-time contracts. They are not runtime validation rules and do not replace explicit domain validation.
+Common pitfalls:
+- Using `T?` to hide a missing binding instead of modelling an optional value.
+- Forgetting tags for nullable primitive values when several values of the same type exist.
+- Assuming `IEnumerable<T?>` changes the lifetime of elements; lifetime still comes from the matched bindings.
+See also: [Composition arguments](composition-arguments.md), [Root arguments](root-arguments.md), [Injection on demand](injection-on-demand.md).
+
 ## Default values
 
 This example shows how to use default values in dependency injection when explicit injection is not possible.

README.md

@@ -306,6 +306,7 @@ dotnet run
 - [Field injection](readme/field-injection.md)
 - [Method injection](readme/method-injection.md)
 - [Property injection](readme/property-injection.md)
+- [Nullable reference types](readme/nullable-reference-types.md)
 - [Default values](readme/default-values.md)
 - [Required properties or fields](readme/required-properties-or-fields.md)
 - [Overrides](readme/overrides.md)
@@ -2146,8 +2147,8 @@ AI needs to understand the situation it’s in (context). This means knowing det
 | AI context file | Size | Tokens |
 | --------------- | ---- | ------ |
 | [AGENTS_SMALL.md](AGENTS_SMALL.md) | 62KB | 16K |
-| [AGENTS_MEDIUM.md](AGENTS_MEDIUM.md) | 108KB | 27K |
-| [AGENTS.md](AGENTS.md) | 406KB | 104K |
+| [AGENTS_MEDIUM.md](AGENTS_MEDIUM.md) | 111KB | 28K |
+| [AGENTS.md](AGENTS.md) | 409KB | 104K |
 
 For different IDEs, you can use the _AGENTS.md_ file as is by simply copying it to the root directory. For use with _JetBrains Rider_ and _Junie_, please refer to [these instructions](https://www.jetbrains.com/help/junie/customize-guidelines.html). For example, you can copy any _AGENTS.md_ file into your project (using _Pure.DI_) as _.junie/guidelines.md._
 ## How to contribute to Pure.DI

readme/async-disposable-scope.md

@@ -174,13 +174,13 @@ partial class Composition: IDisposable, IAsyncDisposable
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     get
     {
-      Func<Session> perBlockFunc596 = new Func<Session>(
+      Func<Session> perBlockFunc602 = new Func<Session>(
       [MethodImpl(MethodImplOptions.AggressiveInlining)]
       () =>
       {
         return new Session(this);
       });
-      return new Program(perBlockFunc596);
+      return new Program(perBlockFunc602);
     }
   }
 

readme/async-enumerable.md

@@ -89,14 +89,14 @@ partial class Composition
     get
     {
       [MethodImpl(MethodImplOptions.AggressiveInlining)]
-      async IAsyncEnumerable<IHealthCheck> EnumerationOf_transientIAsyncEnumerable376()
+      async IAsyncEnumerable<IHealthCheck> EnumerationOf_transientIAsyncEnumerable382()
       {
         yield return new MemoryCheck();
         yield return new ExternalServiceCheck();
         await Task.CompletedTask;
       }
 
-      return new HealthService(EnumerationOf_transientIAsyncEnumerable376());
+      return new HealthService(EnumerationOf_transientIAsyncEnumerable382());
     }
   }
 }

readme/auto-scoped.md

@@ -155,18 +155,18 @@ partial class Composition
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     get
     {
-      Func<IListeningSession> perBlockFunc604 = new Func<IListeningSession>(
+      Func<IListeningSession> perBlockFunc610 = new Func<IListeningSession>(
       [MethodImpl(MethodImplOptions.AggressiveInlining)]
       () =>
       {
-        IListeningSession transientIListeningSession605;
+        IListeningSession transientIListeningSession611;
         Composition localParentScope = this;
         // Create a child scope so scoped services (PlaybackQueue) are unique per session.
         var localScope = new Composition(localParentScope);
-        transientIListeningSession605 = localScope.Session;
-        return transientIListeningSession605;
+        transientIListeningSession611 = localScope.Session;
+        return transientIListeningSession611;
       });
-      return new MusicApp(perBlockFunc604);
+      return new MusicApp(perBlockFunc610);
     }
   }
 

readme/automapper.md

@@ -335,7 +335,7 @@ classDiagram
 	Mapper o-- "Singleton" LoggerFactory : LoggerFactory
 	Program *--  StudentService : IStudentService
 	Program o-- "Singleton" ILogger : ILogger
-	FuncᐸStudentˏPersonᐳ o-- "Singleton" PersonFormatter : IPersonFormatter
+	FuncᐸStudentˏPersonᐳ o-- "Singleton" PersonFormatter : IPersonFormatterɁ
 	FuncᐸStudentˏPersonᐳ o-- "Singleton" Mapper : IMapper
 	namespace AutoMapper {
 		class IMapper {
@@ -384,7 +384,7 @@ classDiagram
 	namespace System {
 		class FuncᐸStudentˏPersonᐳ {
 				<<delegate>>
-			+IPersonFormatter Formatter
+			+IPersonFormatterɁ Formatter
 		}
 		class IDisposable {
 			<<abstract>>

readme/bind-attribute-with-lifetime-and-tag.md

@@ -89,28 +89,28 @@ partial class Composition
   private readonly Object _lock = new Object();
 #endif
 
-  private IGpu? _singletonIGpu2147483116;
+  private IGpu? _singletonIGpu2147483112;
   private GraphicsAdapter? _singletonGraphicsAdapter62;
 
   public IRenderer Renderer
   {
     [MethodImpl(MethodImplOptions.AggressiveInlining)]
     get
     {
-      if (_singletonIGpu2147483116 is null)
+      if (_singletonIGpu2147483112 is null)
         lock (_lock)
-          if (_singletonIGpu2147483116 is null)
+          if (_singletonIGpu2147483112 is null)
           {
             if (_singletonGraphicsAdapter62 is null)
             {
               _singletonGraphicsAdapter62 = new GraphicsAdapter();
             }
 
             GraphicsAdapter localInstance_1182D1279 = _singletonGraphicsAdapter62;
-            _singletonIGpu2147483116 = localInstance_1182D1279.HighPerfGpu;
+            _singletonIGpu2147483112 = localInstance_1182D1279.HighPerfGpu;
           }
 
-      return new RayTracer(_singletonIGpu2147483116);
+      return new RayTracer(_singletonIGpu2147483112);
     }
   }
 }

readme/build-up-of-an-existing-generic-object.md

@@ -106,16 +106,16 @@ partial class Composition
   public IFacade<Guid> GetFacade(string userName)
   {
     if (userName is null) throw new ArgumentNullException(nameof(userName));
-    UserContext<Guid> transientUserContext511;
+    UserContext<Guid> transientUserContext517;
     // The "BuildUp" method injects dependencies into an existing object.
     // This is useful when the object is created externally (e.g., by a UI framework
     // or an ORM) or requires specific initialization before injection.
     UserContext<Guid> localContext = new UserContext<Guid>();
-    Guid transientGuid513 = Guid.NewGuid();
+    Guid transientGuid519 = Guid.NewGuid();
     localContext.UserName = userName;
-    localContext.SetId(transientGuid513);
-    transientUserContext511 = localContext;
-    return new Facade<Guid>(transientUserContext511);
+    localContext.SetId(transientGuid519);
+    transientUserContext517 = localContext;
+    return new Facade<Guid>(transientUserContext517);
   }
 }
 ```

readme/builder-with-arguments.md

@@ -125,7 +125,7 @@ classDiagram
 	TelemetrySystem --|> ITelemetrySystem
 	Composition ..> Satellite : Satellite Initialize(Pure.DI.UsageTests.Basics.BuilderWithArgumentsScenario.Satellite buildingInstance, System.Guid id)
 	Satellite o-- Guid : Argument "id"
-	Satellite *--  TelemetrySystem : ITelemetrySystem
+	Satellite *--  TelemetrySystem : ITelemetrySystemɁ
 	namespace Pure.DI.UsageTests.Basics.BuilderWithArgumentsScenario {
 		class Composition {
 		<<partial>>
@@ -136,7 +136,7 @@ classDiagram
 		}
 		class Satellite {
 				<<record>>
-			+ITelemetrySystem Telemetry
+			+ITelemetrySystemɁ Telemetry
 			+SetId(Guid id) : Void
 		}
 		class TelemetrySystem {