Auto-pluralize routes

Author: ejsmith

docs/guide/configuration.md

@@ -177,7 +177,7 @@ The following properties on `MediatorConfigurationAttribute` control endpoint ge
 **`EndpointRoutePrefix`** (`string?`)
 
 - **Default:** `"api"`
-- **Effect:** Sets a global route prefix that all category groups nest under. Categories auto-derive their route from their name (e.g., `[HandlerEndpointGroup("Products")]` → `products`), composing with the global prefix to produce `/api/products`.
+- **Effect:** Sets a global route prefix that all category groups nest under. Categories auto-derive their route from their name (e.g., `[HandlerEndpointGroup("Products")]` → `products`), composing with the global prefix to produce `/api/products`. Convention-based entity routes are auto-pluralized (e.g., `GetProduct` → `/products/{productId}`).
 - **Important:** Category-level `RoutePrefix` values without a leading `/` are **relative** to this global prefix. Don't include `api` in your category prefixes when using the default global prefix, or you'll get `/api/api/...`. Use a leading `/` on a category prefix to make it absolute (bypasses the global prefix).
 - **To disable:** Set `EndpointRoutePrefix = ""` to remove the global prefix entirely, then use full paths in category prefixes.
 

docs/guide/endpoints.md

@@ -30,17 +30,17 @@ app.Run();
 That's it. You now have:
 
 ```text
-POST   /api/product          → CreateProduct
-GET    /api/product/{productId}  → GetProduct
-GET    /api/product           → GetProducts
-PUT    /api/product/{productId}  → UpdateProduct
-DELETE /api/product/{productId}  → DeleteProduct
+POST   /api/products              → CreateProduct
+GET    /api/products/{productId}  → GetProduct
+GET    /api/products              → GetProducts
+PUT    /api/products/{productId}  → UpdateProduct
+DELETE /api/products/{productId}  → DeleteProduct
 ```
 
 No attributes required. The source generator infers everything from your message names and properties:
 
 - **HTTP method** — from the message name prefix (`Get*` → GET, `Create*` → POST, `Update*` → PUT, `Delete*` → DELETE, etc.)
-- **Route** — from the class name (minus the `Handler`/`Consumer` suffix) and message properties (names ending in `Id` become route parameters)
+- **Route** — from the message name (minus the verb prefix), **auto-pluralized** to follow REST conventions, with message properties (names ending in `Id` become route parameters)
 - **Parameter binding** — ID properties go in the route, other properties become query parameters (GET/DELETE) or body (POST/PUT/PATCH)
 - **OpenAPI metadata** — operation names, status codes, and even error responses are auto-detected from your `Result` factory calls
 - **Result mapping** — `Result<T>` return values are automatically converted to the correct HTTP status codes
@@ -317,6 +317,30 @@ public class ProductHandler
 | `"products"` (relative) | `"/status"` (absolute) | `/status` |
 | `"/v2/products"` (absolute) | `"{productId}"` (relative) | `/v2/products/{productId}` |
 
+### Route Pluralization
+
+Entity names in convention-based routes are **automatically pluralized** to follow REST conventions. The entity name is extracted from the message name by removing the verb prefix (e.g., `GetProduct` → `Product`), then pluralized before being converted to kebab-case.
+
+| Message Name | Entity | Pluralized Route |
+| ------------ | ------ | ---------------- |
+| `GetProduct` | Product | `/products/{productId}` |
+| `GetProducts` | Products | `/products` (already plural) |
+| `CreateTodo` | Todo | `/todos` |
+| `GetCategory` | Category | `/categories/{categoryId}` |
+| `GetPerson` | Person | `/people/{personId}` |
+| `GetHealth` | Health | `/health` (uncountable) |
+
+**Irregular nouns** are handled automatically: `Person` → `People`, `Child` → `Children`, `Index` → `Indices`, `Criterion` → `Criteria`, etc.
+
+**Uncountable nouns** are not pluralized: `Health`, `Status`, `Data`, `Info`, `Auth`, `Config`, `Feedback`, `Metadata`, `Settings`, `Media`, `Cache`, `Analytics`, `Telemetry`, `Search`, `Content`, `Access`.
+
+To override auto-pluralization, use an explicit route:
+
+```csharp
+[HandlerEndpoint(Route = "/custom-path/{id}")]
+public Result<Item> Handle(GetItem query) { ... }
+```
+
 ### Route Parameters
 
 Properties named `Id` or ending with `Id` automatically become route parameters:

docs/guide/getting-started.md

@@ -100,8 +100,8 @@ app.MapMediatorEndpoints();
 
 This generates:
 
-- `POST /api/todo` → `TodoHandler.Handle(CreateTodo)`
-- `GET /api/todo/{id}` → `TodoHandler.Handle(GetTodo)`
+- `POST /api/todos` → `TodoHandler.Handle(CreateTodo)`
+- `GET /api/todos/{id}` → `TodoHandler.Handle(GetTodo)`
 
 <!-- -->
 

src/Foundatio.Mediator/HandlerAnalyzer.cs

@@ -811,8 +811,8 @@ private static string GenerateRoute(
         // Otherwise, we need to include the entity name in the route
         if (string.IsNullOrEmpty(categoryRoutePrefix))
         {
-            // No category prefix - include entity name in route
-            var kebabEntity = entityName.ToKebabCase();
+            // No category prefix - include pluralized entity name in route
+            var kebabEntity = entityName.SimplePluralize().ToKebabCase();
             if (!string.IsNullOrEmpty(kebabEntity))
             {
                 parts.Add(kebabEntity);
@@ -844,7 +844,7 @@ private static string GenerateRoute(
             else
             {
                 // Entity doesn't match category — include it to avoid ambiguity
-                parts.Add(actionVerb + "-" + entityName.ToKebabCase());
+                parts.Add(actionVerb + "-" + entityName.SimplePluralize().ToKebabCase());
             }
         }
 

src/Foundatio.Mediator/Utility/Helpers.cs

@@ -123,4 +123,69 @@ public static string ToKebabCase(this string name)
         }
         return result.ToString();
     }
+
+    private static readonly HashSet<string> _uncountableNouns = new(StringComparer.OrdinalIgnoreCase)
+    {
+        "Health", "Status", "Data", "Info", "Auth", "Config", "Feedback",
+        "Metadata", "Settings", "Media", "Cache", "Analytics", "Telemetry",
+        "Search", "Content", "Access"
+    };
+
+    private static readonly Dictionary<string, string> _irregularNouns = new(StringComparer.OrdinalIgnoreCase)
+    {
+        ["Person"] = "People",
+        ["Child"] = "Children",
+        ["Man"] = "Men",
+        ["Woman"] = "Women",
+        ["Mouse"] = "Mice",
+        ["Goose"] = "Geese",
+        ["Tooth"] = "Teeth",
+        ["Foot"] = "Feet",
+        ["Ox"] = "Oxen",
+        ["Index"] = "Indices",
+        ["Matrix"] = "Matrices",
+        ["Vertex"] = "Vertices",
+        ["Criterion"] = "Criteria",
+        ["Datum"] = "Data",
+        ["Curriculum"] = "Curricula"
+    };
+
+    /// <summary>
+    /// Simple English pluralization for route generation.
+    /// Handles common suffix rules, irregular nouns, and uncountable nouns.
+    /// </summary>
+    public static string SimplePluralize(this string name)
+    {
+        if (String.IsNullOrEmpty(name))
+            return name;
+
+        if (_uncountableNouns.Contains(name))
+            return name;
+
+        if (_irregularNouns.TryGetValue(name, out var irregular))
+            return irregular;
+
+        // Already ends with 's' — assume already plural
+        if (name.EndsWith("s", StringComparison.OrdinalIgnoreCase))
+            return name;
+
+        // Consonant + y → ies (e.g., Category → Categories)
+        if (name.EndsWith("y", StringComparison.OrdinalIgnoreCase) && name.Length >= 2)
+        {
+            var preceding = name[name.Length - 2];
+            if (!"aeiouAEIOU".Contains(preceding))
+                return name.Substring(0, name.Length - 1) + "ies";
+        }
+
+        // s, x, z, ch, sh → es
+        if (name.EndsWith("x", StringComparison.OrdinalIgnoreCase) ||
+            name.EndsWith("z", StringComparison.OrdinalIgnoreCase) ||
+            name.EndsWith("ch", StringComparison.OrdinalIgnoreCase) ||
+            name.EndsWith("sh", StringComparison.OrdinalIgnoreCase))
+        {
+            return name + "es";
+        }
+
+        return name + "s";
+    }
 }

tests/Foundatio.Mediator.Tests/BasicHandlerGenerationTests.EndpointGeneration.verified.txt

@@ -166,8 +166,8 @@ public static partial class Tests_MediatorEndpoints
         // Default endpoints
         var defaultGroup = rootGroup.MapGroup("");
 
-        // GET /widget/{id} - GetWidget
-        defaultGroup.MapGet("/widget/{id}", (string id, Foundatio.Mediator.IMediator mediator, System.Threading.CancellationToken cancellationToken) =>
+        // GET /widgets/{id} - GetWidget
+        defaultGroup.MapGet("/widgets/{id}", (string id, Foundatio.Mediator.IMediator mediator, System.Threading.CancellationToken cancellationToken) =>
         {
             var message = new GetWidget(Id: id);
             var result = global::Foundatio.Mediator.Generated.WidgetHandler_GetWidget_Handler.Handle(mediator, message, cancellationToken);
@@ -184,7 +184,7 @@ public static partial class Tests_MediatorEndpoints
         {
             System.Action<string> writeLog = System.Console.WriteLine;
             writeLog("Foundatio.Mediator mapped 1 endpoint(s):");
-            writeLog("  GET  /api/widget/{id}  → WidgetHandler.Handle(GetWidget) (convention)");
+            writeLog("  GET  /api/widgets/{id}  → WidgetHandler.Handle(GetWidget) (convention)");
         }
         else
         {
@@ -448,4 +448,4 @@ public static class WidgetHandler_GetWidget_Handler
 
     }
   ]
-}
+}

tests/Foundatio.Mediator.Tests/EndpointGenerationTests.cs

@@ -871,8 +871,8 @@ public class OrderHandler
         // Should be POST (action verb "Approve" implies write operation)
         Assert.Contains("MapPost", endpointSource);
         // Route should include entity name, ID route param, and action verb suffix
-        // ApproveOrder(string OrderId) → POST /order/{orderId}/approve
-        Assert.Contains("/order/{orderId}/approve", endpointSource);
+        // ApproveOrder(string OrderId) → POST /orders/{orderId}/approve
+        Assert.Contains("/orders/{orderId}/approve", endpointSource);
         // All properties covered by route — no body binding
         Assert.DoesNotContain("FromBody", endpointSource);
     }
@@ -1687,5 +1687,174 @@ public class ProductHandler
         Assert.NotNull(endpointSource);
         Assert.Contains(".WithSummary(\"GetProductDetails\")", endpointSource);
     }
+
+    [Fact]
+    public void SingularAndPluralMessages_ProduceSamePluralRoute()
+    {
+        // GetTodo and GetTodos should both generate routes under /todos
+        var source = """
+            using Foundatio.Mediator;
+
+            [assembly: MediatorConfiguration(EndpointDiscovery = EndpointDiscovery.All)]
+
+            public record GetTodo(string Id);
+            public record GetTodos();
+
+            public class TodoHandler
+            {
+                public string Handle(GetTodo query) => "one";
+                public string[] Handle(GetTodos query) => [];
+            }
+            """;
+
+        var refs = GetAspNetCoreReferences();
+        if (refs.Length == 0) return;
+
+        var (_, _, trees) = RunGenerator(source, [Gen], additionalReferences: refs);
+        var endpointSource = trees.FirstOrDefault(t => t.HintName == "_MediatorEndpoints.g.cs").Source;
+
+        Assert.NotNull(endpointSource);
+        // GetTodo should pluralize to /todos/{id}
+        Assert.Contains("/todos/{id}", endpointSource);
+        // GetTodos is already plural → /todos
+        Assert.Contains("MapGet(\"/todos\"", endpointSource);
+    }
+
+    [Fact]
+    public void UncountableNoun_RouteNotPluralized()
+    {
+        var source = """
+            using Foundatio.Mediator;
+
+            [assembly: MediatorConfiguration(EndpointDiscovery = EndpointDiscovery.All)]
+
+            public record GetHealth();
+
+            public class HealthHandler
+            {
+                public string Handle(GetHealth query) => "ok";
+            }
+            """;
+
+        var refs = GetAspNetCoreReferences();
+        if (refs.Length == 0) return;
+
+        var (_, _, trees) = RunGenerator(source, [Gen], additionalReferences: refs);
+        var endpointSource = trees.FirstOrDefault(t => t.HintName == "_MediatorEndpoints.g.cs").Source;
+
+        Assert.NotNull(endpointSource);
+        // Health is uncountable — should stay /health, not /healths
+        Assert.Contains("\"/health\"", endpointSource);
+        Assert.DoesNotContain("healths", endpointSource);
+    }
+
+    [Fact]
+    public void IrregularNoun_RoutePluralizesCorrectly()
+    {
+        var source = """
+            using Foundatio.Mediator;
+
+            [assembly: MediatorConfiguration(EndpointDiscovery = EndpointDiscovery.All)]
+
+            public record GetPerson(string Id);
+
+            public class PersonHandler
+            {
+                public string Handle(GetPerson query) => "person";
+            }
+            """;
+
+        var refs = GetAspNetCoreReferences();
+        if (refs.Length == 0) return;
+
+        var (_, _, trees) = RunGenerator(source, [Gen], additionalReferences: refs);
+        var endpointSource = trees.FirstOrDefault(t => t.HintName == "_MediatorEndpoints.g.cs").Source;
+
+        Assert.NotNull(endpointSource);
+        // Person → People (irregular)
+        Assert.Contains("/people/{id}", endpointSource);
+        Assert.DoesNotContain("/persons", endpointSource);
+    }
+
+    [Fact]
+    public void ConsonantY_PluralizesToIes()
+    {
+        var source = """
+            using Foundatio.Mediator;
+
+            [assembly: MediatorConfiguration(EndpointDiscovery = EndpointDiscovery.All)]
+
+            public record GetCategory(string Id);
+
+            public class CategoryHandler
+            {
+                public string Handle(GetCategory query) => "cat";
+            }
+            """;
+
+        var refs = GetAspNetCoreReferences();
+        if (refs.Length == 0) return;
+
+        var (_, _, trees) = RunGenerator(source, [Gen], additionalReferences: refs);
+        var endpointSource = trees.FirstOrDefault(t => t.HintName == "_MediatorEndpoints.g.cs").Source;
+
+        Assert.NotNull(endpointSource);
+        // Category → Categories (consonant + y → ies)
+        Assert.Contains("/categories/{id}", endpointSource);
+    }
+
+    [Fact]
+    public void VowelY_PluralizesWithS()
+    {
+        var source = """
+            using Foundatio.Mediator;
+
+            [assembly: MediatorConfiguration(EndpointDiscovery = EndpointDiscovery.All)]
+
+            public record GetKey(string Id);
+
+            public class KeyHandler
+            {
+                public string Handle(GetKey query) => "key";
+            }
+            """;
+
+        var refs = GetAspNetCoreReferences();
+        if (refs.Length == 0) return;
+
+        var (_, _, trees) = RunGenerator(source, [Gen], additionalReferences: refs);
+        var endpointSource = trees.FirstOrDefault(t => t.HintName == "_MediatorEndpoints.g.cs").Source;
+
+        Assert.NotNull(endpointSource);
+        // Key → Keys (vowel + y → just s)
+        Assert.Contains("/keys/{id}", endpointSource);
+    }
+
+    [Fact]
+    public void SibilantEnding_PluralizesWithEs()
+    {
+        var source = """
+            using Foundatio.Mediator;
+
+            [assembly: MediatorConfiguration(EndpointDiscovery = EndpointDiscovery.All)]
+
+            public record GetBatch(string Id);
+
+            public class BatchHandler
+            {
+                public string Handle(GetBatch query) => "batch";
+            }
+            """;
+
+        var refs = GetAspNetCoreReferences();
+        if (refs.Length == 0) return;
+
+        var (_, _, trees) = RunGenerator(source, [Gen], additionalReferences: refs);
+        var endpointSource = trees.FirstOrDefault(t => t.HintName == "_MediatorEndpoints.g.cs").Source;
+
+        Assert.NotNull(endpointSource);
+        // Batch → Batches (ch → es)
+        Assert.Contains("/batches/{id}", endpointSource);
+    }
 }