Add per-column sort direction support in composite indexes

- Introduced `DbOrder.Asc`/`DbOrder.Desc` to specify sort order for individual columns in composite indexes.
- Updated `ResolvedIndexPart` and `IndexPartDefinition` to track sort direction.
- Enhanced MigrationsModelDiffer to set `CreateIndexOperation.IsDescending`.
- Preserved legacy `PropertyPaths` for all-ascending indexes to avoid migration snapshot churn.
- Updated documentation and added tests for new functionality.
- Incremented package version to 3.1.0.

Author: CaffeinatedCoder

CLAUDE.md

@@ -49,6 +49,30 @@ Shared NuGet metadata and the package version live in `Directory.Build.props`.
 
 5. **PostgreSQL satellite** (`NpgsqlComplexIndexMigrationsModelDiffer.cs`) — Extends the core differ, validates Npgsql-specific annotations, and normalizes JSON element annotations before passing operations upstream.
 
+### Two integration seams: design-time vs. runtime
+
+There are two distinct hook points, and it matters which one a feature uses:
+
+- **Design-time** (`IDesignTimeServices` via the `.targets`-injected attribute) replaces `IMigrationsModelDiffer`. This runs during `dotnet ef migrations add` and is auto-wired — consumers do nothing.
+- **Runtime** (`IMigrationsSqlGenerator`) converts operations to SQL when migrations are *applied*. This is **not** auto-wired; consumers opt in with `optionsBuilder.UseNpgsqlComplexIndexes()` (a `ReplaceService` helper).
+
+Most index metadata (GIN/operators/include/etc.) flows as *real Npgsql annotation keys* (`Npgsql:IndexMethod`, …) on the `CreateIndexOperation`, so Npgsql's own runtime SQL generator renders it — this package never touches SQL generation for those. Expression indexes are the exception (see below).
+
+### Expression indexes (`HasExpressionIndex`)
+
+Expression indexes are **provider-specific** and deliberately live in the satellite, not core: PostgreSQL/SQLite render `CREATE INDEX … ((expr))` natively, but SQL Server has no functional-index DDL (it models the same intent via persisted computed columns). Exposing the API in provider-agnostic core would be a false promise — a SQL Server consumer could call it and get a `CreateIndexOperation` with empty `Columns` that the stock generator can't render. So:
+
+- The **entry point** `HasExpressionIndex` (on `EntityTypeBuilder<TEntity>`) lives in `EFCore.ComplexIndexes.PostgreSQL` (`NpgsqlExpressionIndexExtensions.cs`), as does its `ExpressionIndexBuilder`.
+- Core owns only the inert **plumbing**: the `IIndexExpression` seam (`SqlIndexExpression` ships today; a future LINQ add-on plugs in here), `IndexPartDefinition`/`ResolvedIndexPart`/`IndexPartsSerializer`, `CompositeIndexDefinition.Parts`, the differ's part-handling, and the `ComplexIndexStorage` helper satellites call to dedup-and-store definitions. None of it activates unless a satellite populates it.
+
+Each column-list entry is a "part"; an index is an ordered list of parts. Strings are emitted verbatim (no property→column resolution).
+
+`CreateIndexOperation.Columns` is a `string[]` of quoted identifiers with no slot for an expression, so:
+- The differ stamps the ordered, resolved parts onto the operation as the `CustomIndex:IndexParts` annotation (`ResolvedIndexPart` + `IndexPartsSerializer`), **only when a part is an expression** (column-only indexes are untouched).
+- `NpgsqlComplexIndexSqlGenerator` (extends `NpgsqlMigrationsSqlGenerator`) overrides `Generate(CreateIndexOperation, …)`: if that annotation is present it renders the full `CREATE INDEX` itself (column parts quoted, expression parts wrapped in parens, reusing the forwarded Npgsql annotations for `USING`/`INCLUDE`/`NULLS NOT DISTINCT`/etc.); otherwise it delegates to `base`. This requires the runtime `UseNpgsqlComplexIndexes()` wiring.
+
+`CompositeIndexDefinition` carries the ordered parts additively via `Parts` (with `EffectiveParts` falling back to the legacy `PropertyPaths` field) so migration snapshots written before expression support still deserialize.
+
 ### Key extension points
 
 - **Adding a new provider**: Subclass `CustomMigrationsModelDiffer`, implement `IDesignTimeServices` to replace the differ, and ship a `.targets` file that injects the attribute. See the PostgreSQL project for the exact pattern.
@@ -57,3 +81,7 @@ Shared NuGet metadata and the package version live in `Directory.Build.props`.
 ### Expression path extraction
 
 `ComplexIndexExtensions` parses anonymous-type lambda expressions (`x => new { x.Name, x.Address.City }`) by recursively walking `MemberExpression` chains to produce dotted property paths. These paths are then matched against the EF Core metadata model to resolve column names.
+
+### Per-column sort direction (`DbOrder.Asc`/`DbOrder.Desc`)
+
+`DbOrder.Asc`/`Desc` are identity marker functions; `ExtractSinglePart` peels them (and `Convert` boxing) off the expression in any order to record a `Descending` flag per part. Unlike expression indexes, descending columns are **provider-agnostic and need no satellite work**: the differ maps direction onto the native `CreateIndexOperation.IsDescending` (`bool[]`), which every relational provider renders. The differ leaves `IsDescending` **null** when all parts are ascending, so existing ascending indexes don't churn. To avoid snapshot churn, `HasComplexCompositeIndex` keeps writing the legacy `PropertyPaths` form when every column is ascending and only switches to the ordered `Parts` form when a descending column is present. Note: wrapping a member in `DbOrder.Desc(...)` makes it a method call, so C# requires naming it in the anonymous type (`new { x.A, B = DbOrder.Desc(x.B) }`).

Directory.Build.props

@@ -1,6 +1,6 @@
 <Project>
     <PropertyGroup>
-        <Version>3.0.0</Version>
+        <Version>3.1.0</Version>
         <Authors>CaffeinatedCoder</Authors>
         <PackageLicenseExpression>MIT</PackageLicenseExpression>
         <GenerateDocumentationFile>true</GenerateDocumentationFile>

EFCore.ComplexIndexes.Tests/CompositeIndexSerializerTests.cs

@@ -57,6 +57,29 @@ public void Roundtrips_parts()
         Assert.IsTrue(deserialized[0].EffectiveParts[1].IsExpression);
     }
 
+    [TestMethod(DisplayName = "Roundtrips per-column descending direction")]
+    public void Roundtrips_descending_direction()
+    {
+        var definitions = new List<CompositeIndexDefinition>
+                          {
+                              new()
+                              {
+                                  Parts =
+                                  [
+                                      new IndexPartDefinition { PropertyPath = "Name" },
+                                      new IndexPartDefinition { PropertyPath = "Created", Descending = true }
+                                  ]
+                              }
+                          };
+
+        var json         = CompositeIndexSerializer.Serialize(definitions);
+        var deserialized = CompositeIndexSerializer.Deserialize(json);
+
+        Assert.AreEqual(definitions[0], deserialized[0]);
+        Assert.IsFalse(deserialized[0].EffectiveParts[0].Descending);
+        Assert.IsTrue(deserialized[0].EffectiveParts[1].Descending);
+    }
+
     [TestMethod(DisplayName = "Legacy paths-only JSON still deserializes via EffectiveParts")]
     public void Legacy_paths_json_deserializes()
     {

EFCore.ComplexIndexes.Tests/MigrationModelDifferTests.cs

@@ -360,6 +360,47 @@ protected override void OnModelCreating(ModelBuilder modelBuilder)
         }
     }
 
+    // Composite index with a descending column
+    private class ContextWithDescendingComposite(
+        DbContextOptions<ContextWithDescendingComposite> options) : DbContext(options)
+    {
+        public DbSet<PersonV1> People => Set<PersonV1>();
+
+        protected override void OnModelCreating(ModelBuilder modelBuilder)
+        {
+            modelBuilder.Entity<PersonV1>(builder =>
+            {
+                builder.ToTable("person");
+                builder.HasKey(x => x.Id);
+                builder.Property(x => x.Name).HasColumnName("name");
+                builder.ComplexProperty(x => x.EmailAddress, c => { c.Property(x => x.Value).HasColumnName("email_address"); });
+                builder.HasComplexCompositeIndex(x => new { x.Name, Email = DbOrder.Desc(x.EmailAddress.Value) });
+            });
+        }
+    }
+
+    [TestMethod(DisplayName = "Composite index sets per-column descending order")]
+    public void Composite_index_sets_descending_order()
+    {
+        var target     = BuildRelationalModel<ContextWithDescendingComposite>();
+        var operations = GetDifferences(source: null, target: target);
+
+        var createIndex = Assert.ContainsSingle(operations.OfType<CreateIndexOperation>());
+        Assert.IsTrue(createIndex.Columns.SequenceEqual(["name", "email_address"]));
+        Assert.IsNotNull(createIndex.IsDescending);
+        Assert.IsTrue(createIndex.IsDescending!.SequenceEqual([false, true]));
+    }
+
+    [TestMethod(DisplayName = "All-ascending composite leaves IsDescending null")]
+    public void Ascending_composite_leaves_isdescending_null()
+    {
+        var target     = BuildRelationalModel<ContextV3>();
+        var operations = GetDifferences(source: null, target: target);
+
+        var createIndex = Assert.ContainsSingle(operations.OfType<CreateIndexOperation>());
+        Assert.IsNull(createIndex.IsDescending);
+    }
+
     // V4: expression index on a regular column
     private class ContextWithExpressionIndex(
         DbContextOptions<ContextWithExpressionIndex> options) : DbContext(options)

EFCore.ComplexIndexes.Tests/PathExtractionTests.cs

@@ -62,6 +62,29 @@ public void Extracts_deeply_nested_complex_property()
         Assert.IsTrue(expectedPaths.SequenceEqual(paths));
     }
 
+    [TestMethod(DisplayName = "Extracts per-column direction from DbOrder markers")]
+    public void Extracts_direction_from_dborder_markers()
+    {
+        var parts = ComplexIndexExtensions
+           .ExtractIndexParts<Person, object>(x => new { x.FirstName, Email = DbOrder.Desc(x.EmailAddress.Value) });
+
+        Assert.AreEqual("FirstName", parts[0].PropertyPath);
+        Assert.IsFalse(parts[0].Descending);
+
+        Assert.AreEqual("EmailAddress.Value", parts[1].PropertyPath);
+        Assert.IsTrue(parts[1].Descending);
+    }
+
+    [TestMethod(DisplayName = "DbOrder markers do not affect extracted paths")]
+    public void DbOrder_markers_do_not_affect_paths()
+    {
+        var paths = ComplexIndexExtensions
+           .ExtractPropertyPaths<Person, object>(x => new { x.FirstName, Email = DbOrder.Desc(x.EmailAddress.Value) });
+
+        List<string> expectedPaths = ["FirstName", "EmailAddress.Value"];
+        Assert.IsTrue(expectedPaths.SequenceEqual(paths));
+    }
+
     [TestMethod(DisplayName = "Throws for non anonymous type")]
     public void Throws_for_non_anonymous_type()
     {