fix: ProjectTo nullable-to-non-nullable coalescing

EnsureTypeCompatibility now detects Nullable<T> -> T (and Nullable<T>
-> U for different value types) and wraps with Expression.Coalesce
instead of Expression.Convert. This generates COALESCE(column, 0) in
SQL, preventing "Nullable object must have a value" at materialization.

Covers double?, int?, bool?, DateTime?, and all other value types.
In-memory ConvertValue path already handled this correctly.

Author: rolandbanks

CHANGELOG.md

@@ -6,6 +6,12 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/), and this
 
 ## [Unreleased]
 
+## [10.0.20] - 2026-03-31
+
+### Fixed
+
+- `ProjectTo` now coalesces `Nullable<T>` source properties to `default(T)` when projecting to non-nullable destination properties (e.g. `double?` -> `double`), generating `COALESCE` in SQL instead of throwing `InvalidOperationException: Nullable object must have a value`
+
 ## [10.0.19] - 2026-03-31
 
 ### Added

PanoramicData.Mapper.Test/Models/TestModels.cs

@@ -692,4 +692,22 @@ public class StringScoreDestination
 	public int Id { get; set; }
 	public string Score { get; set; } = string.Empty;
 	public string Name { get; set; } = string.Empty;
+}
+
+// --- ProjectTo nullable-to-non-nullable models ---
+
+public class NullablePortEntity
+{
+	public int Id { get; set; }
+	public double? TrafficSentKbps { get; set; }
+	public int? ClientCount { get; set; }
+	public bool? IsOnline { get; set; }
+}
+
+public class NonNullablePortDto
+{
+	public int Id { get; set; }
+	public double TrafficSentKbps { get; set; }
+	public int ClientCount { get; set; }
+	public bool IsOnline { get; set; }
 }

PanoramicData.Mapper.Test/ProjectToTests.cs

@@ -146,18 +146,77 @@ private class NullableDoubleToStringProfile : Profile
 	{
 		public NullableDoubleToStringProfile() => CreateMap<NullableDoubleEntity, StringScoreDestination>();
 	}
+
+	[Fact]
+	public void ProjectTo_NullableToNonNullable_WithValues_ProjectsCorrectly()
+	{
+		var config = new MapperConfiguration(cfg =>
+			cfg.AddProfile(new NullablePortProfile()));
+
+		using var context = CreateContext();
+		context.NullablePorts.Add(new NullablePortEntity
+		{
+			Id = 1,
+			TrafficSentKbps = 123.45,
+			ClientCount = 10,
+			IsOnline = true
+		});
+		context.SaveChanges();
+
+		var projected = context.NullablePorts
+			.ProjectTo<NonNullablePortDto>(config)
+			.ToList();
+
+		projected.Should().ContainSingle();
+		projected[0].TrafficSentKbps.Should().Be(123.45);
+		projected[0].ClientCount.Should().Be(10);
+		projected[0].IsOnline.Should().BeTrue();
+	}
+
+	[Fact]
+	public void ProjectTo_NullableToNonNullable_WithNulls_DefaultsToZeroOrFalse()
+	{
+		var config = new MapperConfiguration(cfg =>
+			cfg.AddProfile(new NullablePortProfile()));
+
+		using var context = CreateContext();
+		context.NullablePorts.Add(new NullablePortEntity
+		{
+			Id = 1,
+			TrafficSentKbps = null,
+			ClientCount = null,
+			IsOnline = null
+		});
+		context.SaveChanges();
+
+		var projected = context.NullablePorts
+			.ProjectTo<NonNullablePortDto>(config)
+			.ToList();
+
+		projected.Should().ContainSingle();
+		projected[0].TrafficSentKbps.Should().Be(0.0);
+		projected[0].ClientCount.Should().Be(0);
+		projected[0].IsOnline.Should().BeFalse();
+	}
+
+	private class NullablePortProfile : Profile
+	{
+		public NullablePortProfile() => CreateMap<NullablePortEntity, NonNullablePortDto>();
+	}
 }
 
 public class TestDbContext(DbContextOptions<TestDbContext> options) : DbContext(options)
 {
 	public DbSet<SimpleSource> Sources { get; set; } = null!;
 	public DbSet<PersonSource> Persons { get; set; } = null!;
 	public DbSet<NullableDoubleEntity> NullableDoubles { get; set; } = null!;
+	public DbSet<NullablePortEntity> NullablePorts { get; set; } = null!;
 
 	protected override void OnModelCreating(ModelBuilder modelBuilder)
 	{
 		modelBuilder.Entity<SimpleSource>().HasKey(e => e.Id);
 		modelBuilder.Entity<PersonSource>().HasKey(e => e.FirstName);
 		modelBuilder.Entity<NullableDoubleEntity>().HasKey(e => e.Id);
+		modelBuilder.Entity<NullablePortEntity>().HasKey(e => e.Id);
 	}
 }

PanoramicData.Mapper/Extensions/QueryableExtensions.cs

@@ -134,6 +134,27 @@ private static Expression EnsureTypeCompatibility(Expression expression, Type ta
 			return Expression.Call(expression, nameof(object.ToString), Type.EmptyTypes);
 		}
 
+		// Nullable<T> -> non-nullable value type: coalesce to default(T) so EF Core
+		// generates COALESCE in SQL instead of throwing on NULL materialization
+		if (sourceCore != sourceType && targetCore == targetType && targetType.IsValueType)
+		{
+			var coalesced = Expression.Coalesce(expression, Expression.Default(sourceCore));
+			if (sourceCore == targetType)
+			{
+				return coalesced;
+			}
+
+			// Different value type (e.g. int? -> double): coalesce then convert
+			try
+			{
+				return Expression.Convert(coalesced, targetType);
+			}
+			catch (InvalidOperationException)
+			{
+				return Expression.Default(targetType);
+			}
+		}
+
 		// Nullable<T> -> T or T -> Nullable<T> where T is the same core type
 		// or numeric/enum conversions where Expression.Convert has a CLR operator
 		try

PanoramicData.Mapper/PanoramicData.Mapper.csproj

@@ -26,7 +26,7 @@
 	<GeneratePackageOnBuild>true</GeneratePackageOnBuild>
 	<PackageTags>Mapper;AutoMapper;ObjectMapping;PanoramicData;Convention;Mapping;Projection;EFCore;DependencyInjection</PackageTags>
 	<PackageReadmeFile>README.md</PackageReadmeFile>
-	<PackageReleaseNotes>10.0.19: Added implicit self-mapping (T -> T) and implicit type conversions (numeric, enum, string, nullable) for convention-mapped properties. Fixed ProjectTo coercion error for Nullable to string projections; fixed ConvertValue throwing on incompatible string-to-numeric/enum convention matches. See https://github.com/panoramicdata/PanoramicData.Mapper/blob/main/CHANGELOG.md for details.</PackageReleaseNotes>
+	<PackageReleaseNotes>10.0.20: Fixed ProjectTo nullable-to-non-nullable coalescing (double? -> double now generates COALESCE in SQL). 10.0.19: Added implicit self-mapping (T -> T) and implicit type conversions (numeric, enum, string, nullable) for convention-mapped properties. Fixed ProjectTo coercion error for Nullable to string projections; fixed ConvertValue throwing on incompatible string-to-numeric/enum convention matches. See https://github.com/panoramicdata/PanoramicData.Mapper/blob/main/CHANGELOG.md for details.</PackageReleaseNotes>
 </PropertyGroup>
 
 <ItemGroup>