Merge pull request #35 from Zechiax/feature/search-facets

Add search facets to allow better filtering of search results

Author: Zechiax

Modrinth.Net.Test/FacetCollectionTests.cs

@@ -0,0 +1,42 @@
+using Modrinth.Models.Facets;
+
+namespace Modrinth.Net.Test;
+
+[TestFixture]
+public class FacetCollectionTests
+{
+    [Test]
+    public void CollectionWithOnlyOneFacet()
+    {
+        var collection = new FacetCollection();
+        collection.Add(Facet.Category("test"));
+        Assert.That(collection.ToString(), Is.EqualTo("[[\"categories:test\"]]"));
+    }
+
+    [Test]
+    public void CollectionWithMultipleFacets_OR()
+    {
+        var collection = new FacetCollection();
+        collection.Add(Facet.Category("test"), Facet.Category("test2"));
+        Assert.That(collection.ToString(), Is.EqualTo("[[\"categories:test\",\"categories:test2\"]]"));
+    }
+
+    [Test]
+    public void CollectionWithMultipleFacets_AND()
+    {
+        var collection = new FacetCollection();
+        collection.Add(Facet.Category("test"));
+        collection.Add(Facet.Category("test2"));
+        Assert.That(collection.ToString(), Is.EqualTo("[[\"categories:test\"],[\"categories:test2\"]]"));
+    }
+
+    [Test]
+    public void CollectionWithMultipleFacets_AND_OR()
+    {
+        var collection = new FacetCollection();
+        collection.Add(Facet.Category("test"));
+        collection.Add(Facet.Category("test2"), Facet.Category("test3"));
+        Assert.That(collection.ToString(),
+            Is.EqualTo("[[\"categories:test\"],[\"categories:test2\",\"categories:test3\"]]"));
+    }
+}

Modrinth.Net.Test/ModrinthApiTests/SearchTests.cs

@@ -1,4 +1,5 @@
-using Index = Modrinth.Models.Enums.Index;
+using Modrinth.Models.Facets;
+using Index = Modrinth.Models.Enums.Index;
 
 namespace Modrinth.Net.Test.ModrinthApiTests;
 
@@ -125,4 +126,18 @@ public async Task Search_WithUpdatedSort_ShouldReturnSortedByUpdatedList()
             search.Hits.Select(p => p.DateModified),
             Is.EqualTo(search.Hits.Select(p => p.DateModified).OrderByDescending(d => d)));
     }
+
+    // Search with facets
+    [Test]
+    public async Task Search_WithFacets_ShouldReturnFilteredResults()
+    {
+        var facets = new FacetCollection();
+
+        facets.Add(Facet.Category("adventure"));
+
+        var search = await _client.Project.SearchAsync("", facets: facets);
+
+        // Check that every search result has the adventure category
+        Assert.That(search.Hits.Select(p => p.Categories).All(c => c.Contains("adventure")));
+    }
 }

Modrinth.Net/Endpoints/Project/IProjectApi.cs

@@ -1,4 +1,5 @@
 using Modrinth.Models;
+using Modrinth.Models.Facets;
 using Index = Modrinth.Models.Enums.Index;
 
 namespace Modrinth.Endpoints.Project;
@@ -9,6 +10,7 @@ public interface IProjectApi
     ///     Search Modrinth for project by it's name
     /// </summary>
     /// <param name="query">The query to search for</param>
+    /// <param name="facets">Facets to filter the search by</param>
     /// <param name="index">The sorting method used for sorting search results</param>
     /// <param name="offset">The offset into the search. Skips this number of results</param>
     /// <param name="limit">The number of results returned by the search</param>
@@ -17,7 +19,8 @@ Task<SearchResponse> SearchAsync(
         string query,
         Index index = Index.Downloads,
         ulong offset = 0,
-        ulong limit = 10);
+        ulong limit = 10,
+        FacetCollection? facets = null);
 
     /// <summary>
     ///     Gets project by slug or ID

Modrinth.Net/Endpoints/Project/ProjectApi.cs

@@ -1,6 +1,7 @@
 using Flurl.Http;
 using Modrinth.Extensions;
 using Modrinth.Models;
+using Modrinth.Models.Facets;
 using Index = Modrinth.Models.Enums.Index;
 
 namespace Modrinth.Endpoints.Project;
@@ -64,13 +65,16 @@ public async Task UnfollowAsync(string slugOrId)
 
     /// <inheritdoc />
     public async Task<SearchResponse> SearchAsync(string query, Index index = Index.Downloads, ulong offset = 0,
-        ulong limit = 10)
+        ulong limit = 10, FacetCollection? facets = null)
     {
-        return await _client.Request("search")
+        var request = _client.Request("search")
             .SetQueryParam("query", query)
             .SetQueryParam("index", index.ToString().ToLower())
             .SetQueryParam("offset", offset)
-            .SetQueryParam("limit", limit)
-            .GetJsonAsync<SearchResponse>();
+            .SetQueryParam("limit", limit);
+
+        if (facets is {Count: > 0}) request = request.SetQueryParam("facets", facets.ToString());
+
+        return await request.GetJsonAsync<SearchResponse>();
     }
 }

Modrinth.Net/Extensions/ProjectTypeExtensions.cs

@@ -0,0 +1,24 @@
+using Modrinth.Models.Enums;
+
+namespace Modrinth.Extensions;
+
+public static class ProjectTypeExtensions
+{
+    /// <summary>
+    ///     Convert ProjectType to string for Modrinth API
+    /// </summary>
+    /// <param name="projectType"></param>
+    /// <returns></returns>
+    public static string ToModrinthString(this ProjectType projectType)
+    {
+        return projectType switch
+        {
+            ProjectType.Mod => "mod",
+            ProjectType.Modpack => "modpack",
+            ProjectType.Resourcepack => "resourcepack",
+            ProjectType.Shader => "shader",
+            // Return lower string, this should work for all, but it is not guaranteed
+            _ => projectType.ToString().ToLower()
+        };
+    }
+}

Modrinth.Net/Helpers/UrlCreatorHelper.cs

@@ -1,5 +1,5 @@
-using Modrinth.Models;
-using Modrinth.Models.Enums;
+using Modrinth.Extensions;
+using Modrinth.Models;
 
 namespace Modrinth.Helpers;
 
@@ -13,23 +13,6 @@ public static class UrlCreatorHelper
     /// </summary>
     public const string ModrinthUrl = "https://modrinth.com";
 
-    /// <summary>
-    ///     Returns formatted type used in Modrinth links to specific project
-    /// </summary>
-    /// <param name="projectType"></param>
-    /// <returns></returns>
-    private static string GetProjectUrlType(ProjectType projectType)
-    {
-        return projectType switch
-        {
-            ProjectType.Mod => "mod",
-            ProjectType.Modpack => "modpack",
-            ProjectType.Resourcepack => "resourcepack",
-            ProjectType.Shader => "shader",
-            // Return lower string, this should work for all, but it is not guaranteed
-            _ => projectType.ToString().ToLower()
-        };
-    }
 
     /// <summary>
     ///     Return direct link to the user on Modrinth
@@ -38,7 +21,7 @@ private static string GetProjectUrlType(ProjectType projectType)
     /// <returns></returns>
     public static string GetDirectUrl(this Project project)
     {
-        return $"{ModrinthUrl}/{GetProjectUrlType(project.ProjectType)}/{project.Id}";
+        return $"{ModrinthUrl}/{project.ProjectType.ToModrinthString()}/{project.Id}";
     }
 
     /// <summary>
@@ -58,6 +41,6 @@ public static string GetDirectUrl(this User user)
     /// <returns></returns>
     public static string GetDirectUrl(this SearchResult searchResult)
     {
-        return $"{ModrinthUrl}/{GetProjectUrlType(searchResult.ProjectType)}/{searchResult.ProjectId}";
+        return $"{ModrinthUrl}/{searchResult.ProjectType.ToModrinthString()}/{searchResult.ProjectId}";
     }
 }

Modrinth.Net/Models/Facets/Facet.cs

@@ -0,0 +1,59 @@
+using Modrinth.Extensions;
+using Modrinth.Models.Enums;
+
+namespace Modrinth.Models.Facets;
+
+public abstract class Facet
+{
+    public static Facet<string> Category(string value)
+    {
+        return new(FacetType.Categories, value);
+    }
+
+    public static Facet<string> Version(string value)
+    {
+        return new(FacetType.Versions, value);
+    }
+
+    public static Facet<string> License(string value)
+    {
+        return new(FacetType.License, value);
+    }
+
+    public static Facet<string> ProjectType(ProjectType projectType)
+    {
+        return new(FacetType.ProjectType, projectType.ToModrinthString());
+    }
+}
+
+public class Facet<T> : Facet
+{
+    public Facet(FacetType type, T value)
+    {
+        Type = type;
+        Value = value;
+    }
+
+    public FacetType Type { get; }
+    public T Value { get; }
+
+    public override string ToString()
+    {
+        return Type switch
+        {
+            FacetType.Categories => $"categories:{Value}",
+            FacetType.Versions => $"versions:{Value}",
+            FacetType.License => $"license:{Value}",
+            FacetType.ProjectType => $"project_type:{Value}",
+            _ => string.Empty
+        };
+    }
+}
+
+public enum FacetType
+{
+    Categories,
+    Versions,
+    License,
+    ProjectType
+}

Modrinth.Net/Models/Facets/FacetCollection.cs

@@ -0,0 +1,30 @@
+namespace Modrinth.Models.Facets;
+
+public class FacetCollection
+{
+    private readonly List<Facet[]> _facets = new();
+    public int Count => _facets.Count;
+
+    /// <summary>
+    ///     Adds a facets to the collection, it will be added as a new group
+    ///     Facets in a group are OR'd together
+    ///     Facets in different groups are AND'd together
+    /// </summary>
+    /// <param name="facets"></param>
+    public void Add(params Facet[] facets)
+    {
+        if (facets.Length == 0)
+            return;
+        _facets.Add(facets);
+    }
+
+    public override string ToString()
+    {
+        // Serialize the facets into a Javascript array
+        var serializedFacets = _facets.Select(
+            facets =>
+                $"[{string.Join(',', facets.Select(facet => $"\"{facet}\""))}]");
+
+        return $"[{string.Join(',', serializedFacets)}]";
+    }
+}