improvement: add always_include_linkage param to resources (#362)

Author: 3h15

.formatter.exs

@@ -1,4 +1,5 @@
 spark_locals_without_parens = [
+  always_include_linkage: 1,
   authorize?: 1,
   base: 1,
   base_route: 1,

documentation/dsls/DSL-AshJsonApi.Resource.md

@@ -62,6 +62,7 @@ end
 | Name | Type | Default | Docs |
 |------|------|---------|------|
 | [`type`](#json_api-type){: #json_api-type } | `String.t` |  | The resource identifier type of this resource in JSON:API |
+| [`always_include_linkage`](#json_api-always_include_linkage){: #json_api-always_include_linkage } | `list(atom)` | `[]` | A list of relationships that should always have their linkage included in the resource |
 | [`includes`](#json_api-includes){: #json_api-includes } | `any \| list(any)` | `[]` | A keyword list of all paths that are includable from this resource |
 | [`include_nil_values?`](#json_api-include_nil_values?){: #json_api-include_nil_values? } | `any` |  | Whether or not to include properties for values that are nil in the JSON output |
 | [`default_fields`](#json_api-default_fields){: #json_api-default_fields } | `list(atom)` |  | The fields to include in the object if the `fields` query parameter does not specify. Defaults to all public |

lib/ash_json_api/includes/includer.ex

@@ -38,6 +38,12 @@ defmodule AshJsonApi.Includes.Includer do
     includes_keyword
     |> Enum.reduce({preloaded, includes_map}, fn
       {relationship, further}, {preloaded_without_linkage, includes_map} ->
+        linkage_only? =
+          case further do
+            %{__linkage_only__: true} -> true
+            _ -> false
+          end
+
         {related, includes_map} =
           preloaded
           |> Enum.flat_map(fn record ->
@@ -61,22 +67,26 @@ defmodule AshJsonApi.Includes.Includer do
           )
 
         includes_map =
-          related
-          |> List.wrap()
-          |> Enum.reduce(includes_map, fn related_item, includes_map ->
-            type = AshJsonApi.Resource.Info.type(related_item)
-            id = AshJsonApi.Resource.encode_primary_key(related_item)
-
-            case Map.fetch(includes_map, {type, id}) do
-              {:ok, _} ->
-                Map.update!(includes_map, {type, id}, fn existing ->
-                  merge_linkages(existing, related_item)
-                end)
-
-              :error ->
-                Map.put(includes_map, {type, id}, Map.put_new(related_item, :__linkage__, %{}))
-            end
-          end)
+          if linkage_only? do
+            includes_map
+          else
+            related
+            |> List.wrap()
+            |> Enum.reduce(includes_map, fn related_item, includes_map ->
+              type = AshJsonApi.Resource.Info.type(related_item)
+              id = AshJsonApi.Resource.encode_primary_key(related_item)
+
+              case Map.fetch(includes_map, {type, id}) do
+                {:ok, _} ->
+                  Map.update!(includes_map, {type, id}, fn existing ->
+                    merge_linkages(existing, related_item)
+                  end)
+
+                :error ->
+                  Map.put(includes_map, {type, id}, Map.put_new(related_item, :__linkage__, %{}))
+              end
+            end)
+          end
 
         {preloaded_with_linkage, includes_map}
     end)

lib/ash_json_api/request.ex

@@ -680,11 +680,28 @@ defmodule AshJsonApi.Request do
     )
   end
 
-  defp set_include_queries(includes, fields, field_inputs, filters, sorts, resource, path \\ []) do
+  defp set_include_queries(includes, fields, field_inputs, filters, sorts, resource, path \\ [])
+
+  defp set_include_queries(:linkage_only, _, _, _, _, _, _), do: []
+
+  defp set_include_queries(includes, fields, field_inputs, filters, sorts, resource, path) do
+    includes =
+      Enum.reduce(
+        AshJsonApi.Resource.Info.always_include_linkage(resource),
+        includes,
+        fn key, includes ->
+          if Keyword.has_key?(includes, key) do
+            includes
+          else
+            Keyword.put(includes, key, :linkage_only)
+          end
+        end
+      )
+
     Enum.map(includes, fn {key, nested} ->
       related = public_related(resource, key)
 
-      nested =
+      nested_queries =
         set_include_queries(nested, fields, field_inputs, filters, sorts, related, path ++ [key])
 
       related_field_inputs = Map.get(field_inputs, related, %{})
@@ -704,12 +721,13 @@ defmodule AshJsonApi.Request do
             value -> {field, value}
           end
         end)
-        |> Kernel.++(nested)
+        |> Kernel.++(nested_queries)
 
       new_query =
         related
         |> Ash.Query.new()
         |> Ash.Query.load(load)
+        |> Map.put(:__linkage_only__, nested == :linkage_only)
 
       filtered_query =
         case Map.fetch(filters, path ++ [key]) do

lib/ash_json_api/resource/info.ex

@@ -15,6 +15,10 @@ defmodule AshJsonApi.Resource.Info do
     Extension.get_opt(resource, [:json_api], :derive_sort, true, false)
   end
 
+  def always_include_linkage(resource) do
+    Extension.get_opt(resource, [:json_api], :always_include_linkage, [], false)
+  end
+
   def includes(resource) do
     Extension.get_opt(resource, [:json_api], :includes, [], false)
   end

lib/ash_json_api/resource/resource.ex

@@ -494,6 +494,12 @@ defmodule AshJsonApi.Resource do
         type: :string,
         doc: "The resource identifier type of this resource in JSON:API"
       ],
+      always_include_linkage: [
+        type: {:list, :atom},
+        doc:
+          "A list of relationships that should always have their linkage included in the resource",
+        default: []
+      ],
       includes: [
         type: {:wrap_list, :any},
         default: [],