[#6] Add helper for managing cache reference entries

Author: cabol

CHANGELOG.md

@@ -39,6 +39,17 @@
   the developer experience when working with the queryable API, especially for
   tag-based queries. Example: `match_spec value: v, tag: t, where: t == :group_a, select: v`.
   [#5](https://github.com/elixir-nebulex/nebulex_local/issues/5).
+- [Nebulex.Adapters.Local] Added `keyref_match_spec/2` helper function to
+  `Nebulex.Adapters.Local.QueryHelper` for managing cache reference entries
+  (keyrefs). This helper simplifies finding and cleaning up reference entries
+  created when using the `:references` option with `Nebulex.Caching` decorators.
+  Users can now easily invalidate all cached representations of an entity with a
+  simple function call, without needing to know the internal keyref structure
+  `{:"$nbx_keyref_spec", cache, key, ttl}`. Example:
+  `keyref_match_spec(:user_123) |> MyCache.delete_all!(query: ...)`. This works
+  seamlessly with `get_all/1`, `count_all/1`, and `delete_all/1` operations, and
+  supports optional cache filtering.
+  [#6](https://github.com/elixir-nebulex/nebulex_local/issues/6).
 
 ### Backwards incompatible changes
 

lib/nebulex/adapters/local.ex

@@ -413,6 +413,79 @@ defmodule Nebulex.Adapters.Local do
       MyApp.Cache.get_all!(query: MyApp.CacheQueries.user_entries(123))
       MyApp.Cache.delete_all!(query: MyApp.CacheQueries.expiring_soon())
 
+  ### Working with cache references
+
+  When using the `:references` option with `Nebulex.Caching` decorators (like
+  `@decorate cacheable/3`), Nebulex creates reference entries to track
+  dependencies between cached values. The `keyref_match_spec/2` helper makes it
+  easy to find and clean up these reference entries.
+
+  The function builds a match spec that finds all cache keys (reference keys)
+  that point to a specific referenced key. This is useful for:
+
+    * Invalidating all entries that depend on a specific key
+    * Counting how many references point to a key
+    * Getting a list of dependent cache keys
+
+  #### Examples
+
+      import Nebulex.Adapters.Local.QueryHelper
+
+      # Delete all references to a specific key (any cache)
+      ms = keyref_match_spec(:user_123)
+      MyCache.delete_all!(query: ms)
+
+      # Delete references in a specific cache only
+      ms = keyref_match_spec(:user_123, cache: MyApp.UserCache)
+      MyCache.delete_all!(query: ms)
+
+      # Count how many cache entries reference a key
+      ms = keyref_match_spec(:product_456)
+      count = MyCache.count_all!(query: ms)
+
+      # Get all cache keys that reference a specific key
+      ms = keyref_match_spec(:user_123)
+      reference_keys = MyCache.get_all!(query: ms)
+
+  #### Example: Invalidating cached method results
+
+  When using the `:references` option with caching decorators, you can easily
+  invalidate all cached results that depend on a specific entity:
+
+      defmodule MyApp.UserAccounts do
+          use Nebulex.Caching, cache: MyApp.Cache
+          use Nebulex.Adapters.Local.QueryHelper
+
+          @decorate cacheable(key: id)
+          def get_user_account(id) do
+            # your logic ...
+          end
+
+          @decorate cacheable(key: email, references: &(&1 && &1.id))
+          def get_user_account_by_email(email) do
+            # your logic ...
+          end
+
+          @decorate cacheable(key: token, references: &(&1 && &1.id))
+          def get_user_account_by_token(token) do
+            # your logic ...
+          end
+
+          @decorate cache_evict(key: user.id, query: &__MODULE__.keyref_query/1)
+          def update_user_account(user, attrs) do
+            # your logic ...
+          end
+
+          def keyref_query(%{args: [user | _]} = _context) do
+            keyref_match_spec(user.id)
+          end
+        end
+      end
+
+  See `Nebulex.Adapters.Local.QueryHelper.keyref_match_spec/2` for more details.
+
+  ---
+
   See `Nebulex.Adapters.Local.QueryHelper` for complete documentation.
 
   ## Tagging entries

lib/nebulex/adapters/local/query_helper.ex

@@ -84,6 +84,10 @@ if Code.ensure_loaded?(Ex2ms) do
     it.
     """
 
+    import Ex2ms
+
+    ## API
+
     @doc """
     Imports the query helper macros and `Ex2ms` for building match specifications.
 
@@ -245,5 +249,77 @@ if Code.ensure_loaded?(Ex2ms) do
       # Return as a tuple AST node
       {:{}, [], elements}
     end
+
+    @doc """
+    Builds a match spec for finding cache reference entries (keyrefs).
+
+    This is useful for invalidating all reference keys that point to a specific
+    referenced key. Cache references are created using the `keyref/2` function
+    in Nebulex caching decorators.
+
+    The match spec returns the reference key (the cache key that points to the
+    referenced key). This works seamlessly with `get_all/1`, `delete_all/1`, and
+    `count_all/1` operations.
+
+    ## Parameters
+
+      * `referenced_key` - The key that references point to (required).
+      * `opts` - Optional keyword list:
+        * `:cache` - Filter references to a specific cache (optional). When not
+          provided, matches references in any cache (including `nil` for local
+          references).
+
+    ## Examples
+
+        # Delete all reference entries pointing to a specific key (any cache)
+        ms = keyref_match_spec(:user_123)
+        MyCache.delete_all!(query: ms)
+
+        # Delete reference entries pointing to a key in a specific cache
+        ms = keyref_match_spec(:user_123, cache: MyApp.UserCache)
+        MyCache.delete_all!(query: ms)
+
+        # Count how many references point to a key
+        ms = keyref_match_spec(:product_456)
+        MyCache.count_all!(query: ms)
+
+        # Get all cache keys that are references to a specific key
+        ms = keyref_match_spec(:user_123)
+        reference_keys = MyCache.get_all!(query: ms)
+
+    ## Background
+
+    When using the `:references` option with caching decorators, Nebulex stores
+    reference entries as keyref records with the structure:
+    `{:"$nbx_keyref_spec", cache, key, ttl}`. This function helps you query and
+    clean up these reference entries.
+
+    ## See also
+
+      * `Nebulex.Caching` - For information about cache references and the
+        `:references` option.
+
+    """
+    @spec keyref_match_spec(term(), keyword()) :: :ets.match_spec()
+    def keyref_match_spec(referenced_key, opts \\ []) do
+      {cache_filter, _opts} = Keyword.pop(opts, :cache)
+
+      # Always return the reference key (the cache key that points to the referenced key)
+      # This works for get_all (returns the keys), and the adapter overrides it for
+      # delete_all/count_all to return true as needed
+      if cache_filter do
+        fun do
+          {:entry, k, {:"$nbx_keyref_spec", c, ref_k, _t}, _, _, _}
+          when ref_k == ^referenced_key and c == ^cache_filter ->
+            k
+        end
+      else
+        fun do
+          {:entry, k, {:"$nbx_keyref_spec", _c, ref_k, _t}, _, _, _}
+          when ref_k == ^referenced_key ->
+            k
+        end
+      end
+    end
   end
 end

test/nebulex/adapters/local/query_helper_test.exs

@@ -295,4 +295,93 @@ defmodule Nebulex.Adapters.Local.QueryHelperTest do
       assert Enum.sort(result) == [{4, 100}, {5, 200}]
     end
   end
+
+  describe "keyref_match_spec/2" do
+    test "returns a valid match spec" do
+      ms = keyref_match_spec(:user_123)
+
+      # Should return a valid ETS match spec (list of tuples)
+      assert is_list(ms)
+      assert length(ms) == 1
+      assert {_pattern, _guards, _select} = hd(ms)
+    end
+
+    test "returns a valid match spec with cache filter" do
+      ms = keyref_match_spec(:user_123, cache: MyApp.Cache)
+
+      assert is_list(ms)
+      assert length(ms) == 1
+    end
+  end
+
+  describe "keyref_match_spec/2 integration with ETS" do
+    setup do
+      table_name = :"test_keyref_table_#{:erlang.unique_integer([:positive])}"
+      table = :ets.new(table_name, [:set, :public, :named_table, keypos: 2])
+
+      # Insert some regular entries
+      true = :ets.insert(table, {:entry, :key1, "value1", 1000, 2000, nil})
+      true = :ets.insert(table, {:entry, :key2, "value2", 1100, 2100, nil})
+
+      # Insert keyref entries (cache references)
+      # Reference to :user_123 in nil cache (local reference)
+      true =
+        :ets.insert(
+          table,
+          {:entry, :ref1, {:"$nbx_keyref_spec", nil, :user_123, nil}, 1200, :infinity, nil}
+        )
+
+      # Reference to :user_123 in MyApp.Cache
+      true =
+        :ets.insert(
+          table,
+          {:entry, :ref2, {:"$nbx_keyref_spec", MyApp.Cache, :user_123, nil}, 1300, :infinity, nil}
+        )
+
+      # Reference to :user_456 in MyApp.Cache
+      true =
+        :ets.insert(
+          table,
+          {:entry, :ref3, {:"$nbx_keyref_spec", MyApp.Cache, :user_456, nil}, 1400, :infinity, nil}
+        )
+
+      # Reference to :user_123 in AnotherCache
+      true =
+        :ets.insert(
+          table,
+          {:entry, :ref4, {:"$nbx_keyref_spec", AnotherCache, :user_123, nil}, 1500, :infinity, nil}
+        )
+
+      on_exit(fn ->
+        if :ets.whereis(table_name) != :undefined do
+          :ets.delete(table)
+        end
+      end)
+
+      %{table: table}
+    end
+
+    test "gets all reference keys pointing to a specific key (any cache)", %{table: table} do
+      ms = keyref_match_spec(:user_123)
+      result = :ets.select(table, ms) |> Enum.sort()
+
+      # Should return the keys of all reference entries
+      assert result == [:ref1, :ref2, :ref4]
+    end
+
+    test "gets reference keys for a specific cache", %{table: table} do
+      ms = keyref_match_spec(:user_123, cache: MyApp.Cache)
+      result = :ets.select(table, ms)
+
+      # Should return only :ref2 (reference to :user_123 in MyApp.Cache)
+      assert result == [:ref2]
+    end
+
+    test "returns empty when no references exist", %{table: table} do
+      ms = keyref_match_spec(:nonexistent_key)
+      result = :ets.select(table, ms)
+
+      assert result == []
+    end
+  end
 end

test/shared/local_test_case.exs

@@ -480,6 +480,19 @@ defmodule Nebulex.Adapters.LocalTest do
         ms = match_spec value: v, tag: t, where: is_binary(v) and t == :strings
         assert cache.count_all!(query: ms) == 2
       end
+
+      test "QueryHelper: query a map as a value", %{cache: cache} do
+        assert cache.put_all([a: %{x: 1}, b: %{x: 2}], tag: :maps) == :ok
+
+        var = 1
+        ms = match_spec value: %{x: x}, tag: t, where: x == ^var and t == :maps, select: x
+
+        assert cache.get_all!(query: ms) == [1]
+
+        ms = match_spec value: %{x: x}, tag: t, where: t == :maps, select: x
+
+        assert cache.get_all!(query: ms) |> Enum.sort() == [1, 2]
+      end
     end
 
     describe "older generation hitted on" do