Merge pull request #55 from EFNext/fix/docs

Various documentation tweaks

Author: koenbeuk

README.md

@@ -25,7 +25,7 @@ error CS8072: An expression tree lambda may not contain a null propagating opera
 
 Expression trees (`Expression<Func<...>>`) only support a restricted subset of C# — no `?.`, no switch expressions, no pattern matching. So you end up writing ugly ternary chains instead of the clean code you'd write anywhere else. ([Why hasn't this been fixed?](https://efnext.github.io/ExpressiveSharp/guide/expression-tree-problem.html))
 
-**2. Computed properties are opaque to LINQ providers.** You define `public string FullName => FirstName + " " + LastName` and use it in a query — but EF Core can't see inside the property getter. It either throws a runtime translation error, or worse, silently fetches the entire entity to evaluate `FullName` on the client (overfetching). The only workaround is to duplicate the logic as an inline expression in every query that needs it.
+**2. Computed properties are opaque to LINQ providers.** You define `public string FullName => $"{FirstName} {LastName}"` and use it in a query — but EF Core can't see inside the property getter. It either throws a runtime translation error, or worse, silently fetches the entire entity to evaluate `FullName` on the client (overfetching). The only workaround is to duplicate the logic as an inline expression in every query that needs it.
 
 ExpressiveSharp fixes this. Write natural C# and the source generator builds the expression tree at compile time:
 

docs/advanced/custom-transformers.md

@@ -1,6 +1,6 @@
 # Custom Transformers
 
-Expression transformers adapt expression trees for specific consumers at runtime. ExpressiveSharp includes four built-in transformers for EF Core compatibility, and you can create your own for custom LINQ providers or specialized rewriting needs.
+Expression transformers adapt expression trees for specific consumers at runtime. ExpressiveSharp includes six built-in transformers for EF Core compatibility, and you can create your own for custom LINQ providers or specialized rewriting needs.
 
 ## The `IExpressionTreeTransformer` Interface
 
@@ -122,9 +122,11 @@ When `UseExpressives()` is configured for EF Core, the transformer pipeline runs
 
 1. **Per-member transformers** (from `[Expressive(Transformers = ...)]`) -- applied during expression resolution, before the tree is substituted into the query.
 2. **Built-in EF Core transformers** -- applied as part of `ExpandExpressives()`:
+   - `ReplaceThrowWithDefault` (skip with `o => o.PreserveThrowExpressions()`)
    - `ConvertLoopsToLinq`
    - `RemoveNullConditionalPatterns`
    - `FlattenTupleComparisons`
+   - `FlattenConcatArrayCalls`
    - `FlattenBlockExpressions`
 3. **Plugin-contributed transformers** (from `IExpressivePlugin.GetTransformers()`) -- applied after the built-in transformers.
 
@@ -166,12 +168,14 @@ The `RelationalExtensions` package uses this exact pattern to register the `Rewr
 
 | Transformer | Purpose | When to use manually |
 |---|---|---|
+| `ReplaceThrowWithDefault` | Replaces `throw` expressions with `default(T)` of the same type | Providers that cannot translate `Throw` (skipped via `PreserveThrowExpressions()`) |
 | `RemoveNullConditionalPatterns` | Strips `x != null ? x.Prop : default` ternaries | Databases that handle null propagation natively |
 | `FlattenBlockExpressions` | Inlines block-local variables, removes `Expression.Block` | LINQ providers that do not support block expressions |
 | `FlattenTupleComparisons` | Replaces `ValueTuple` field access with underlying arguments | Providers that cannot translate `ValueTuple` construction |
+| `FlattenConcatArrayCalls` | Rewrites `string.Concat(string[])` into 2/3/4-arg overloads | Providers that cannot translate `NewArrayInit` of non-constants |
 | `ConvertLoopsToLinq` | Rewrites `LoopExpression` to LINQ method calls | Providers that cannot translate loop expressions |
 
-All four are applied automatically by `UseExpressives()`. You only need to use them manually if you are working with a non-EF-Core LINQ provider or calling `ExpandExpressives()` directly.
+All six are applied automatically by `UseExpressives()`. You only need to use them manually if you are working with a non-EF-Core LINQ provider or calling `ExpandExpressives()` directly.
 
 ## Testing Transformers
 

docs/advanced/how-it-works.md

@@ -54,9 +54,11 @@ Understanding the internals of ExpressiveSharp helps you use it effectively and
 |           v                                               |
 |  +-----------------------------------------------------+ |
 |  | Transformer Pipeline                                 | |
+|  | - ReplaceThrowWithDefault                            | |
 |  | - ConvertLoopsToLinq                                 | |
 |  | - RemoveNullConditionalPatterns                      | |
 |  | - FlattenTupleComparisons                            | |
+|  | - FlattenConcatArrayCalls                            | |
 |  | - FlattenBlockExpressions                            | |
 |  | - (Plugin-contributed transformers)                  | |
 |  +-----------------------------------------------------+ |
@@ -164,13 +166,15 @@ This means `[Expressive]` members can reference other `[Expressive]` members fre
 
 ### Transformer Pipeline
 
-After expansion, transformers adapt the expression tree for the target LINQ provider. When `UseExpressives()` is active, four built-in transformers run automatically:
+After expansion, transformers adapt the expression tree for the target LINQ provider. When `UseExpressives()` is active, six built-in transformers run automatically:
 
 | Transformer | Purpose |
 |---|---|
+| `ReplaceThrowWithDefault` | Replaces `throw` expressions with `default(T)` so providers that can't translate `Throw` still see a node of the same type (skip with `o => o.PreserveThrowExpressions()`) |
 | `ConvertLoopsToLinq` | Rewrites `LoopExpression` (from `foreach`/`for`) into LINQ method calls (`Sum`, `Count`, `Any`, `All`) |
 | `RemoveNullConditionalPatterns` | Strips null-check ternaries (`x != null ? x.Prop : default` becomes `x.Prop`) for SQL null propagation |
 | `FlattenTupleComparisons` | Replaces `ValueTuple` field access with underlying arguments for direct comparison |
+| `FlattenConcatArrayCalls` | Rewrites `string.Concat(string[])` (used by 5+-part interpolations) into 2/3/4-arg `string.Concat` calls EF Core can translate |
 | `FlattenBlockExpressions` | Inlines block-local variables and removes `Expression.Block` nodes |
 
 Plugins can contribute additional transformers via `IExpressivePlugin.GetTransformers()`.

docs/advanced/limitations.md

@@ -17,7 +17,7 @@ public string FullName { get; set; }
 
 // Expression-bodied property -- works
 [Expressive]
-public string FullName => FirstName + " " + LastName;
+public string FullName => $"{FirstName} {LastName}";
 ```
 
 ## Block Body Restrictions
@@ -96,9 +96,9 @@ When targeting EF Core, the body of an `[Expressive]` member can only use operat
 [Expressive]
 public string FilePath => Path.Combine(Directory, FileName);
 
-// Works -- string concatenation is translated by EF Core
+// Works -- string interpolation is translated by EF Core
 [Expressive]
-public string FilePath => Directory + "/" + FileName;
+public string FilePath => $"{Directory}/{FileName}";
 ```
 
 ::: info Using ExpressiveFor for Unsupported Methods

docs/guide/expressive-constructors.md

@@ -11,7 +11,7 @@ db.Orders
     .Select(o => new OrderSummaryDto
     {
         Id = o.Id,
-        Description = "Order #" + o.Id,
+        Description = $"Order #{o.Id}",
         Total = o.Items.Sum(i => i.UnitPrice * i.Quantity),
     })
 ---setup---
@@ -26,7 +26,7 @@ public class OrderSummaryDto
 With an `[Expressive]` constructor, you define the projection once and use it everywhere:
 
 ::: expressive-sample
-db.Orders.Select(o => new OrderSummaryDto(o.Id, "Order #" + o.Id, o.Total()))
+db.Orders.Select(o => new OrderSummaryDto(o.Id, $"Order #{o.Id}", o.Total()))
 ---setup---
 public class OrderSummaryDto
 {

docs/guide/expressive-queryable.md

@@ -59,15 +59,11 @@ Most common `Queryable` methods are supported:
 
 **Comparer overloads** (`IEqualityComparer<T>`, `IComparer<T>`) are also supported.
 
-### .NET 10+ Additional Methods
+### .NET 9 / .NET 10 Additional Methods
 
-On .NET 10 and later, these additional methods are available:
+On .NET 9 and later: `CountBy`, `AggregateBy`, `Index`.
 
-- `LeftJoin`
-- `RightJoin`
-- `CountBy`
-- `AggregateBy`
-- `Index`
+On .NET 10 and later (in addition to the above): `LeftJoin`, `RightJoin`.
 
 ## Pattern Matching and Switch Expressions
 

docs/guide/integrations/ef-core.md

@@ -36,6 +36,7 @@ services.AddDbContext<MyDbContext>(options =>
 1. **Expands `[Expressive]` member references** — walks query expression trees and replaces opaque property/method accesses with the generated expression trees
 2. **Marks `[Expressive]` properties as unmapped** — adds a model convention that tells EF Core to ignore these properties in the database model (no corresponding column)
 3. **Applies database-friendly transformers** (in this order):
+   - `ReplaceThrowWithDefault` — replaces `throw` expressions with `default(T)` so `Coalesce`/`Condition` shapes survive (skip with `o => o.PreserveThrowExpressions()`)
    - `ConvertLoopsToLinq` — converts loop expressions to LINQ method calls
    - `RemoveNullConditionalPatterns` — strips null-check ternaries for SQL providers
    - `FlattenTupleComparisons` — rewrites tuple field access to direct comparisons
@@ -207,7 +208,7 @@ The built-in `RelationalExtensions` package (for window functions) uses this plu
 |---------|-------------|
 | [`ExpressiveSharp`](https://www.nuget.org/packages/ExpressiveSharp/) | Core runtime — `[Expressive]` attribute, source generator, expression expansion, transformers |
 | [`ExpressiveSharp.EntityFrameworkCore`](https://www.nuget.org/packages/ExpressiveSharp.EntityFrameworkCore/) | EF Core integration — `UseExpressives()`, `ExpressiveDbSet<T>`, Include/ThenInclude, async methods, analyzers and code fixes |
-| [`ExpressiveSharp.EntityFrameworkCore.RelationalExtensions`](https://www.nuget.org/packages/ExpressiveSharp.EntityFrameworkCore.RelationalExtensions/) | Relational extensions — `ExecuteUpdate`/`ExecuteUpdateAsync` with modern syntax, SQL window functions (ROW_NUMBER, RANK, DENSE_RANK, NTILE) |
+| [`ExpressiveSharp.EntityFrameworkCore.RelationalExtensions`](https://www.nuget.org/packages/ExpressiveSharp.EntityFrameworkCore.RelationalExtensions/) | Relational extensions — `ExecuteUpdate`/`ExecuteUpdateAsync` with modern syntax, SQL window functions (ranking, aggregate, navigation) |
 
 ::: info
 The `ExpressiveSharp.EntityFrameworkCore` package bundles Roslyn analyzers and code fixes from `ExpressiveSharp.EntityFrameworkCore.CodeFixers`. These provide compile-time diagnostics and IDE quick-fix actions for common issues like missing `[Expressive]` attributes.

docs/guide/integrations/mongodb.md

@@ -45,7 +45,7 @@ No custom MQL is emitted — MongoDB's own translator does all the heavy lifting
 
 ## `[Expressive]` Properties Are Unmapped from BSON
 
-ExpressiveSharp provides a MongoDB `IClassMapConvention` that unmaps every `[Expressive]`-decorated property from the BSON class map, so the property's backing field is not persisted to documents. This matters most for [synthesized properties](../../reference/expressive-for#synthesizing-a-property-with-synthesize-true), which have a writable `init` accessor and would otherwise be serialized as a real BSON field.
+ExpressiveSharp provides a MongoDB `IClassMapConvention` that unmaps every `[Expressive]`-decorated property from the BSON class map, so the property's backing field is not persisted to documents. This matters most for [synthesized properties](../../reference/expressive-property), which have a writable `init` accessor and would otherwise be serialized as a real BSON field.
 
 ::: warning Ordering constraint
 MongoDB builds and caches a class map the first time you call `IMongoDatabase.GetCollection<T>()` for a given `T`. A convention registered *after* that call does not apply to the cached map. If any of your document types use `[Expressive]`, register the convention before the first `GetCollection<T>` call:

docs/guide/introduction.md

@@ -28,7 +28,7 @@ Expression trees (`Expression<Func<...>>`) only support a restricted subset of C
 
 ### 2. Computed properties are opaque to LINQ providers
 
-You define `public string FullName => FirstName + " " + LastName` and use it in a query, but the provider cannot see inside the property getter. It either throws a runtime translation error, or worse, silently fetches the entire entity to evaluate `FullName` on the client (overfetching). The only workaround is to duplicate the logic as an inline expression in every query that needs it.
+You define `public string FullName => $"{FirstName} {LastName}"` and use it in a query, but the provider cannot see inside the property getter. It either throws a runtime translation error, or worse, silently fetches the entire entity to evaluate `FullName` on the client (overfetching). The only workaround is to duplicate the logic as an inline expression in every query that needs it.
 
 ## How ExpressiveSharp Works
 
@@ -101,13 +101,13 @@ Mark computed properties and methods with `[Expressive]` to generate companion e
 
 ## Requirements
 
-| | .NET 8.0 | .NET 10.0 |
-|---|---|---|
-| **ExpressiveSharp** | C# 12 | C# 14 |
-| **ExpressiveSharp.Abstractions** | C# 12 | C# 14 |
-| **ExpressiveSharp.EntityFrameworkCore** | EF Core 8.x | EF Core 10.x |
-| **ExpressiveSharp.MongoDB** | MongoDB.Driver 3.x | MongoDB.Driver 3.x |
-| **ExpressiveSharp.EntityFrameworkCore.RelationalExtensions** | EF Core 8.x | EF Core 10.x |
+| | .NET 8.0 | .NET 9.0 | .NET 10.0 |
+|---|---|---|---|
+| **ExpressiveSharp** | C# 12 | C# 13 | C# 14 |
+| **ExpressiveSharp.Abstractions** | C# 12 | C# 13 | C# 14 |
+| **ExpressiveSharp.EntityFrameworkCore** | EF Core 8.x | EF Core 9.x | EF Core 10.x |
+| **ExpressiveSharp.MongoDB** | MongoDB.Driver 3.x | MongoDB.Driver 3.x | MongoDB.Driver 3.x |
+| **ExpressiveSharp.EntityFrameworkCore.RelationalExtensions** | EF Core 8.x | EF Core 9.x | EF Core 10.x |
 
 ## Next Steps
 

docs/guide/migration-from-projectables.md

@@ -90,7 +90,7 @@ options.UseSqlServer(connectionString)
        .UseExpressives(opts => opts.AddPlugin(new MyPlugin()));
 ```
 
-`UseExpressives()` automatically registers four transformers as global defaults (`ConvertLoopsToLinq`, `RemoveNullConditionalPatterns`, `FlattenTupleComparisons`, `FlattenBlockExpressions`), sets up the query compiler decorator, and configures model conventions.
+`UseExpressives()` automatically registers six transformers as global defaults (`ReplaceThrowWithDefault`, `ConvertLoopsToLinq`, `RemoveNullConditionalPatterns`, `FlattenTupleComparisons`, `FlattenConcatArrayCalls`, `FlattenBlockExpressions`), sets up the query compiler decorator, and configures model conventions. `ReplaceThrowWithDefault` can be opted out via `o => o.PreserveThrowExpressions()`.
 
 ### Null-Conditional Handling
 
@@ -144,13 +144,13 @@ Pick based on whether you want the generator to declare the target property for
 // Before (Projectables)
 [Projectable(UseMemberBody = nameof(FullNameProjection))]
 public string FullName { get; init; }
-private string FullNameProjection => LastName + ", " + FirstName;
+private string FullNameProjection => $"{LastName}, {FirstName}";
 
 // After (ExpressiveSharp) -- partial class, stub only; FullName is generated
 public partial class Customer
 {
     [ExpressiveProperty("FullName")]
-    private string FullNameExpression => LastName + ", " + FirstName;
+    private string FullNameExpression => $"{LastName}, {FirstName}";
 }
 ```
 
@@ -172,15 +172,15 @@ public string FullName => $"{FirstName} {LastName}".Trim().ToUpper();
 
 [Projectable(UseMemberBody = nameof(FullNameProjection))]
 public string FullName => ...;
-private string FullNameProjection => FirstName + " " + LastName;
+private string FullNameProjection => $"{FirstName} {LastName}";
 
 // After (ExpressiveSharp)
 using ExpressiveSharp.Mapping;
 
 public string FullName => $"{FirstName} {LastName}".Trim().ToUpper();
 
 [ExpressiveFor(nameof(FullName))]
-private string FullNameExpression => FirstName + " " + LastName;
+private string FullNameExpression => $"{FirstName} {LastName}";
 ```
 
 **Scenario 2: External/third-party type methods**
@@ -253,7 +253,7 @@ The `InterceptorsNamespaces` MSBuild property needed for method interceptors is
 
 9. **Package consolidation** -- Remove all old packages and install `ExpressiveSharp.EntityFrameworkCore`.
 
-10. **Target framework** -- ExpressiveSharp targets .NET 8.0 and .NET 10.0. If you are on .NET 6 or 7, you will need to upgrade.
+10. **Target framework** -- ExpressiveSharp targets .NET 8.0, .NET 9.0, and .NET 10.0. If you are on .NET 6 or 7, you will need to upgrade.
 
 ## Feature Comparison
 
@@ -277,7 +277,7 @@ The `InterceptorsNamespaces` MSBuild property needed for method interceptors is
 | EF Core specific | Yes | No -- works standalone |
 | Compatibility modes | Full / Limited | Full only (simpler) |
 | Code generation approach | Syntax tree rewriting | Semantic (IOperation) analysis |
-| Target frameworks | .NET 6+ | .NET 8 / .NET 10 |
+| Target frameworks | .NET 6+ | .NET 8 / .NET 9 / .NET 10 |
 
 ## New Features Available After Migration