[#245] Allow :key and :query together in cache_evict

Author: cabol

CHANGELOG.md

@@ -19,9 +19,13 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   `:query` option for bulk eviction based on adapter-specific queries.
   For example: `@decorate cache_evict(query: my_query)`. The query can be
   provided directly or as a function that returns the query at runtime.
-  When present, the `:query` option overrides the `:key` option.
+  Additionally, both `:query` and `:key` options can be used together to
+  evict specific entries and entries matching a query pattern in a single
+  operation. When both are provided, query-based eviction executes first,
+  followed by key-based eviction.
   For more information, see:
   [#243](https://github.com/elixir-nebulex/nebulex/issues/243).
+  [#245](https://github.com/elixir-nebulex/nebulex/issues/245).
 - [Nebulex.Caching.Decorator] Add support for evicting external references in
   `cache_evict` decorator. For more information, see:
   [#244](https://github.com/elixir-nebulex/nebulex/issues/244)

lib/nebulex/caching/decorators.ex

@@ -1170,6 +1170,17 @@ if Code.ensure_loaded?(Decorator.Define) do
           def delete_all do
             # your logic (maybe write/delete data to the SoR)
           end
+
+          @decorate cache_evict(key: user_id, query: &__MODULE__.query_for_user_sessions/1)
+          def logout_user(user_id) do
+            # Evicts both the user entry and all their session entries
+            # your logic (maybe write/delete data to the SoR)
+          end
+
+          def query_for_user_sessions(%{args: [user_id]}) do
+            # Return a query that matches user sessions
+            # (implementation depends on your adapter)
+          end
         end
 
     ## Eviction with a query
@@ -1178,6 +1189,14 @@ if Code.ensure_loaded?(Decorator.Define) do
     returns a query at runtime) to evict multiple cache entries based on
     specific criteria. The query must be supported by the cache adapter.
 
+    > #### Query syntax varies by adapter {: .warning}
+    >
+    > The query syntax and format depend on the cache adapter being used.
+    > The examples in this section assume you are using the
+    > `Nebulex.Adapters.Local` adapter, which uses ETS match specifications.
+    > If you're using a different adapter (e.g., Redis, Partitioned, etc.),
+    > consult that adapter's documentation for the appropriate query format.
+
     To explain how this works, let's use an example. Imagine you have a function
     `delete_objects_by_tag` that receives a `tag` as an argument and deletes
     all records matching the given tag from the system of record (SoR). You want
@@ -1188,12 +1207,12 @@ if Code.ensure_loaded?(Decorator.Define) do
     receives the decorator context and returns the required query to evict all
     cached entries matching the given tag.
 
-        @decorate cache_evict(query: &__MODULE__.query_for_tag/1)
+        @decorate cache_evict(query: &query_for_tag/1)
         def delete_objects_by_tag(tag) do
           # your logic to delete data from the SoR
         end
 
-        def query_for_tag(%{args: [tag]} = _context) do
+        defp query_for_tag(%{args: [tag]} = _context) do
           # Assuming we are using the `Nebulex.Adapters.Local` adapter and the
           # cached entry value is a map with a `tag` field, the match spec
           # would look like this:
@@ -1212,12 +1231,12 @@ if Code.ensure_loaded?(Decorator.Define) do
 
     If you need to evict all cached entries associated with a specific user:
 
-        @decorate cache_evict(query: &__MODULE__.query_for_user/1)
+        @decorate cache_evict(query: &query_for_user/1)
         def delete_user_data(user_id) do
           # your logic to delete user data from the SoR
         end
 
-        def query_for_user(%{args: [user_id]} = _context) do
+        defp query_for_user(%{args: [user_id]} = _context) do
           [
             {
               {:entry, :"$1", %{user_id: :"$2"}, :_, :_},
@@ -1231,12 +1250,12 @@ if Code.ensure_loaded?(Decorator.Define) do
 
     You can build more complex queries that match multiple conditions:
 
-        @decorate cache_evict(query: &__MODULE__.query_for_category_and_status/1)
+        @decorate cache_evict(query: &query_for_category_and_status/1)
         def delete_products(category, status) do
           # your logic to delete products from the SoR
         end
 
-        def query_for_category_and_status(%{args: [category, status]} = _context) do
+        defp query_for_category_and_status(%{args: [category, status]}) do
           [
             {
               {:entry, :"$1", %{category: :"$2", status: :"$3"}, :_, :_},
@@ -1266,6 +1285,60 @@ if Code.ensure_loaded?(Decorator.Define) do
     However, using a function is recommended for better readability and
     maintainability, especially when the query depends on function arguments.
 
+    ### Combining `:key` and `:query`
+
+    You can use both `:key` and `:query` options together to evict both specific
+    entries and entries matching a query pattern. When both options are provided,
+    the decorator executes the eviction in the following order:
+
+    1. **Query-based eviction** - First, entries matching the query are evicted.
+    2. **Key-based eviction** - Then, the specific key(s) are evicted.
+
+    This is useful when you need to evict a primary entry along with related
+    entries. For example, when logging out a user, you might want to evict the
+    user's cache entry and all their active session entries (the examples below
+    assume you are using the `Nebulex.Adapters.Local` adapter):
+
+        @decorate cache_evict(key: user_id, query: &query_for_user_sessions/1)
+        def logout_user(user_id) do
+          # Evicts the user entry and all session entries for this user
+          UserSessions.delete_all_for_user(user_id)
+        end
+
+        defp query_for_user_sessions(%{args: [user_id]} = _context) do
+          # Return a query that matches all session entries for the given user
+          [
+            {
+              {:entry, :"$1", %{user_id: :"$2", type: "session"}, :_, :_},
+              [{:"=:=", :"$2", user_id}],
+              [true]
+            }
+          ]
+        end
+
+    Another common use case is evicting multiple specific keys along with a
+    query:
+
+        @decorate cache_evict(
+          key: {:in, [category.id, category.slug]},
+          query: &query_for_category_products/1
+        )
+        def delete_category(category) do
+          # Evicts both category cache entries (by id and slug) and all
+          # product entries within that category
+          Products.delete_all_for_category(category.id)
+        end
+
+        defp query_for_category_products(%{args: [category]} = _context) do
+          [
+            {
+              {:entry, :"$1", %{category_id: :"$2"}, :_, :_},
+              [{:"=:=", :"$2", category.id}],
+              [true]
+            }
+          ]
+        end
+
     ### Best Practices
 
     - **Keep query logic in separate functions** for reusability and cleaner
@@ -1276,6 +1349,8 @@ if Code.ensure_loaded?(Decorator.Define) do
       maintainability.
     - **Consider performance implications** when querying large datasets, as
       some queries may require full cache scans.
+    - **Use both `:key` and `:query` when evicting hierarchical data** where
+      you need to remove both a parent entry and its related child entries.
 
     ## Eviction of external references
 
@@ -1290,14 +1365,16 @@ if Code.ensure_loaded?(Decorator.Define) do
 
     [ext-refs]: #cacheable/3-external-referenced-keys
 
-        @decorate cache_evict(key: {:in, [user.id, keyref(user.email, cache: AnotherCache)]})
+        @decorate cache_evict(
+                    key: {:in, [user.id, keyref(user.email, cache: ExtCache)]}
+                  )
         def delete_user(user) do
           # your logic to delete data from the SoR
         end
 
-    Assuming there is a reference under the key `user.email` in `AnotherCache`,
-    the decorator will remove the cached value under the key `user.id` and the
-    reference under the key `user.email` from `AnotherCache`.
+    Assuming there is a reference under the key `user.email` in `ExtCache`,
+    the decorator will remove the cached value under the key `user.id` and
+    the reference under the key `user.email` from `ExtCache`.
     """
     @doc group: "Decorator API"
     def cache_evict(attrs \\ [], block, context) do
@@ -1607,9 +1684,10 @@ if Code.ensure_loaded?(Decorator.Define) do
       all_entries? = get_boolean(attrs, :all_entries)
 
       key =
-        case Keyword.fetch(attrs, :query) do
-          {:ok, q} -> {:"$nbx_query", q}
-          :error -> keygen
+        case {Keyword.fetch(attrs, :query), Keyword.fetch(attrs, :key)} do
+          {{:ok, q}, {:ok, _k}} -> quote(do: {:"$nbx_query", unquote(q), unquote(keygen)})
+          {{:ok, q}, :error} -> quote(do: {:"$nbx_query", unquote(q)})
+          _else -> keygen
         end
 
       quote do
@@ -1800,6 +1878,12 @@ if Code.ensure_loaded?(Decorator.Define) do
       run_cmd(cache, :delete_all, [[q]], on_error)
     end
 
+    defp do_evict(false, cache, {:query, q, k}, on_error) do
+      _ = run_cmd(cache, :delete_all, [[{:query, q}]], on_error)
+
+      do_evict(false, cache, k, on_error)
+    end
+
     defp do_evict(false, cache, key, on_error) do
       run_cmd(cache, :delete, [key, []], on_error)
     end
@@ -1922,10 +2006,30 @@ if Code.ensure_loaded?(Decorator.Define) do
     @spec eval_key(any(), context()) :: any()
     def eval_key(key, ctx)
 
-    def eval_key(key, ctx) when is_function(key, 1), do: key.(ctx)
-    def eval_key(key, _ctx) when is_function(key, 0), do: key.()
-    def eval_key({:"$nbx_query", q}, ctx), do: {:query, eval_key(q, ctx)}
-    def eval_key(key, _ctx), do: key
+    # cache_evict: only a query is provided
+    def eval_key({:"$nbx_query", q}, ctx) do
+      {:query, eval_key(q, ctx)}
+    end
+
+    # cache_evict: a query and a key are provided
+    def eval_key({:"$nbx_query", q, k}, ctx) do
+      {:query, eval_key(q, ctx), eval_key(k, ctx)}
+    end
+
+    # The key is a function that expects the context
+    def eval_key(key, ctx) when is_function(key, 1) do
+      key.(ctx)
+    end
+
+    # The key is a function that expects no arguments
+    def eval_key(key, _ctx) when is_function(key, 0) do
+      key.()
+    end
+
+    # The key is a term
+    def eval_key(key, _ctx) do
+      key
+    end
 
     @doc """
     Convenience function for running a cache command.

lib/nebulex/caching/options.ex

@@ -234,9 +234,16 @@ defmodule Nebulex.Caching.Options do
       type_doc: "`t:query/0`",
       required: false,
       doc: """
-      The query to use for evicting cache entries. When present, this option
-      overrides the `:key` option and allows you to evict multiple entries
-      based on specific criteria.
+      The query to use for evicting cache entries based on specific criteria.
+      This option allows you to evict multiple entries that match the query.
+
+      When both `:query` and `:key` are provided, the decorator will:
+      1. First execute the query-based eviction to remove matching entries.
+      2. Then execute the key-based eviction to remove the specified key(s).
+
+      This is useful when you need to evict both a specific entry and related
+      entries. For example, when deleting a user, you might want to evict both
+      the user's cache entry and all their session entries.
 
       The `:query` option accepts the following values:
 

mix.lock

@@ -3,7 +3,7 @@
   "benchee_html": {:hex, :benchee_html, "1.0.1", "1e247c0886c3fdb0d3f4b184b653a8d6fb96e4ad0d0389267fe4f36968772e24", [:mix], [{:benchee, ">= 0.99.0 and < 2.0.0", [hex: :benchee, repo: "hexpm", optional: false]}, {:benchee_json, "~> 1.0", [hex: :benchee_json, repo: "hexpm", optional: false]}], "hexpm", "b00a181af7152431901e08f3fc9f7197ed43ff50421a8347b0c80bf45d5b3fef"},
   "benchee_json": {:hex, :benchee_json, "1.0.0", "cc661f4454d5995c08fe10dd1f2f72f229c8f0fb1c96f6b327a8c8fc96a91fe5", [:mix], [{:benchee, ">= 0.99.0 and < 2.0.0", [hex: :benchee, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: false]}], "hexpm", "da05d813f9123505f870344d68fb7c86a4f0f9074df7d7b7e2bb011a63ec231c"},
   "bunt": {:hex, :bunt, "1.0.0", "081c2c665f086849e6d57900292b3a161727ab40431219529f13c4ddcf3e7a44", [:mix], [], "hexpm", "dc5f86aa08a5f6fa6b8096f0735c4e76d54ae5c9fa2c143e5a1fc7c1cd9bb6b5"},
-  "credo": {:hex, :credo, "1.7.12", "9e3c20463de4b5f3f23721527fcaf16722ec815e70ff6c60b86412c695d426c1", [:mix], [{:bunt, "~> 0.2.1 or ~> 1.0", [hex: :bunt, repo: "hexpm", optional: false]}, {:file_system, "~> 0.2 or ~> 1.0", [hex: :file_system, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: false]}], "hexpm", "8493d45c656c5427d9c729235b99d498bd133421f3e0a683e5c1b561471291e5"},
+  "credo": {:hex, :credo, "1.7.13", "126a0697df6b7b71cd18c81bc92335297839a806b6f62b61d417500d1070ff4e", [:mix], [{:bunt, "~> 0.2.1 or ~> 1.0", [hex: :bunt, repo: "hexpm", optional: false]}, {:file_system, "~> 0.2 or ~> 1.0", [hex: :file_system, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: false]}], "hexpm", "47641e6d2bbff1e241e87695b29f617f1a8f912adea34296fb10ecc3d7e9e84f"},
   "decimal": {:hex, :decimal, "2.3.0", "3ad6255aa77b4a3c4f818171b12d237500e63525c2fd056699967a3e7ea20f62", [:mix], [], "hexpm", "a4d66355cb29cb47c3cf30e71329e58361cfcb37c34235ef3bf1d7bf3773aeac"},
   "decorator": {:hex, :decorator, "1.4.0", "a57ac32c823ea7e4e67f5af56412d12b33274661bb7640ec7fc882f8d23ac419", [:mix], [], "hexpm", "0a07cedd9083da875c7418dea95b78361197cf2bf3211d743f6f7ce39656597f"},
   "deep_merge": {:hex, :deep_merge, "1.0.0", "b4aa1a0d1acac393bdf38b2291af38cb1d4a52806cf7a4906f718e1feb5ee961", [:mix], [], "hexpm", "ce708e5f094b9cd4e8f2be4f00d2f4250c4095be93f8cd6d018c753894885430"},
@@ -23,7 +23,7 @@
   "mimic": {:hex, :mimic, "2.1.1", "29008b71c842b652b065d6f9a24e05d84a2fac7181c34627e1ef5229659702e1", [:mix], [{:ham, "~> 0.3", [hex: :ham, repo: "hexpm", optional: false]}], "hexpm", "a3c330c8840feb29ab43b2375ac023073b936429e5320dd5ca1c95a7322a0da7"},
   "nimble_options": {:hex, :nimble_options, "1.1.1", "e3a492d54d85fc3fd7c5baf411d9d2852922f66e69476317787a7b2bb000a61b", [:mix], [], "hexpm", "821b2470ca9442c4b6984882fe9bb0389371b8ddec4d45a9504f00a66f650b44"},
   "nimble_parsec": {:hex, :nimble_parsec, "1.4.2", "8efba0122db06df95bfaa78f791344a89352ba04baedd3849593bfce4d0dc1c6", [:mix], [], "hexpm", "4b21398942dda052b403bbe1da991ccd03a053668d147d53fb8c4e0efe09c973"},
-  "sobelow": {:hex, :sobelow, "0.14.0", "dd82aae8f72503f924fe9dd97ffe4ca694d2f17ec463dcfd365987c9752af6ee", [:mix], [{:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: false]}], "hexpm", "7ecf91e298acfd9b24f5d761f19e8f6e6ac585b9387fb6301023f1f2cd5eed5f"},
+  "sobelow": {:hex, :sobelow, "0.14.1", "2f81e8632f15574cba2402bcddff5497b413c01e6f094bc0ab94e83c2f74db81", [:mix], [{:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: false]}], "hexpm", "8fac9a2bd90fdc4b15d6fca6e1608efb7f7c600fa75800813b794ee9364c87f2"},
   "statistex": {:hex, :statistex, "1.1.0", "7fec1eb2f580a0d2c1a05ed27396a084ab064a40cfc84246dbfb0c72a5c761e5", [:mix], [], "hexpm", "f5950ea26ad43246ba2cce54324ac394a4e7408fdcf98b8e230f503a0cba9cf5"},
   "stream_data": {:hex, :stream_data, "1.2.0", "58dd3f9e88afe27dc38bef26fce0c84a9e7a96772b2925c7b32cd2435697a52b", [:mix], [], "hexpm", "eb5c546ee3466920314643edf68943a5b14b32d1da9fe01698dc92b73f89a9ed"},
   "telemetry": {:hex, :telemetry, "1.3.0", "fedebbae410d715cf8e7062c96a1ef32ec22e764197f70cda73d82778d61e7a2", [:rebar3], [], "hexpm", "7015fc8919dbe63764f4b4b87a95b7c0996bd539e0d499be6ec9d7f3875b79e6"},