Overall enhancements

Author: cabol

README.md

@@ -15,7 +15,7 @@ Add `:nebulex_local` to your list of dependencies in `mix.exs`:
 ```elixir
 def deps do
   [
-    {:nebulex_local, "~> 3.0.0-rc.1"}
+    {:nebulex_local, "~> 3.0.0-rc.2"}
   ]
 end
 ```

lib/nebulex/adapters/local.ex

@@ -23,7 +23,8 @@ defmodule Nebulex.Adapters.Local do
     * Expiration - A status based on TTL (Time To Live) option. To maintain
       cache performance, expired entries may not be immediately removed or
       evicted, they are expired or evicted on-demand, when the key is read.
-    * Eviction - [Generational Garbage Collection][gc].
+    * Eviction - Generational Garbage Collection
+      (see `Nebulex.Adapters.Local.Generation`).
     * Sharding - For intensive workloads, the Cache may also be partitioned
       (by using `:shards` backend and specifying the `:partitions` option).
     * Support for transactions via Erlang global name registration facility.
@@ -32,8 +33,6 @@ defmodule Nebulex.Adapters.Local do
     * Automatic retry logic for handling race conditions during garbage
       collection (see [Concurrency and resilience](#module-concurrency-and-resilience)).
 
-  [gc]: http://hexdocs.pm/nebulex/3.0.0-rc.1/Nebulex.Adapters.Local.Generation.html
-
   ## Concurrency and resilience
 
   The local adapter implements automatic retry logic to handle race conditions
@@ -482,11 +481,7 @@ defmodule Nebulex.Adapters.Local do
         end
       end
 
-  See `Nebulex.Adapters.Local.QueryHelper.keyref_match_spec/2` for more details.
-
-  ---
-
-  See `Nebulex.Adapters.Local.QueryHelper` for complete documentation.
+  > See `Nebulex.Adapters.Local.QueryHelper` for complete documentation.
 
   ## Tagging entries
 
@@ -509,10 +504,13 @@ defmodule Nebulex.Adapters.Local do
       MyCache.put("user:123:profile", user_data, tag: :user_123)
 
       # Tag multiple entries at once
-      MyCache.put_all([
-        {"session:abc:data", session_data},
-        {"session:abc:prefs", preferences}
-      ], tag: :session_abc)
+      MyCache.put_all(
+        [
+          {"session:abc:data", session_data},
+          {"session:abc:prefs", preferences},
+        ],
+        tag: :session_abc
+      )
 
       # Different tags for different entry groups
       MyCache.put_all([a: 1, b: 2, c: 3], tag: :group_a)
@@ -604,6 +602,147 @@ defmodule Nebulex.Adapters.Local do
   Tags can be any Elixir term (atoms, tuples, strings, etc.), giving you
   flexibility in how you organize your cache entries.
 
+  ## Using Caching Decorators with QueryHelper
+
+  The `Nebulex.Caching` decorators (`@decorate`) integrate seamlessly with
+  QueryHelper and tagging for powerful cache management patterns. This section
+  shows practical examples of combining decorators with QueryHelper and tags.
+
+  ### Entry Tagging with Decorators
+
+  You can tag entries automatically when using `@decorate cacheable` and
+  `@decorate cache_put` by specifying the `:tag` option:
+
+      defmodule MyApp.UserCache do
+        use Nebulex.Caching, cache: MyApp.Cache
+        use Nebulex.Adapters.Local.QueryHelper
+
+        # Cache user data with automatic tagging
+        @decorate cacheable(key: user_id, opts: [tag: :users])
+        def get_user(user_id) do
+          # fetch user from database
+          {:ok, user}
+        end
+
+        # Cache user permissions with automatic tagging
+        @decorate cacheable(key: user_id, opts: [tag: :permissions])
+        def get_user_permissions(user_id) do
+          # fetch permissions from database
+          {:ok, permissions}
+        end
+
+        # Store session data with automatic tagging
+        @decorate cache_put(key: session_id, opts: [tag: :sessions])
+        def create_session(session_id, data) do
+          data
+        end
+      end
+
+  ### Selective Cache Invalidation with Tags
+
+  Use the `@decorate cache_evict` decorator with QueryHelper to invalidate
+  entries by tag. This is useful for clearing related cached data:
+
+      defmodule MyApp.UserCache do
+        use Nebulex.Caching, cache: MyApp.Cache
+        use Nebulex.Adapters.Local.QueryHelper
+
+        # ... cacheable functions as above ...
+
+        # Evict all cached data for a specific user
+        @decorate cache_evict(query: &evict_user_query/1)
+        def invalidate_user(user_id) do
+          :ok
+        end
+
+        defp evict_user_query(context) do
+          # Return a QueryHelper match spec to evict entries by tag
+          match_spec tag: t, where: t == :users, select: true
+        end
+      end
+
+  ### Cache Reference Invalidation with keyref_match_spec
+
+  When using the `:references` option to track cache dependencies, you can
+  use `keyref_match_spec` with `cache_evict` to invalidate all dependent
+  entries:
+
+      defmodule MyApp.UserAccounts do
+        use Nebulex.Caching, cache: MyApp.Cache
+        use Nebulex.Adapters.Local.QueryHelper
+
+        # Cache user account by ID
+        @decorate cacheable(key: user_id)
+        def get_user_account(user_id) do
+          fetch_user(user_id)
+        end
+
+        # Cache user account by email, referencing the user ID
+        @decorate cacheable(key: email, references: &(&1 && &1.id))
+        def get_user_account_by_email(email) do
+          user = fetch_user_by_email(email)
+          {:ok, user}
+        end
+
+        # Cache user account by token, also referencing the user ID
+        @decorate cacheable(key: token, references: &(&1 && &1.id))
+        def get_user_account_by_token(token) do
+          user = fetch_user_by_token(token)
+          {:ok, user}
+        end
+
+        # Evict all cache entries referencing a specific user
+        # This invalidates all lookups (by id, email, token) in one operation
+        @decorate cache_evict(key: user_id, query: &invalidate_refs/1)
+        def update_user_account(user_id, attrs) do
+          :ok
+        end
+
+        defp invalidate_refs(%{args: [user_id | _]} = _context) do
+          keyref_match_spec(user_id)
+        end
+      end
+
+  ### Practical Pattern: Clearing All Session Data
+
+  Here's a complete example showing how to manage user sessions with automatic
+  tagging and selective eviction:
+
+      defmodule MyApp.Sessions do
+        use Nebulex.Caching, cache: MyApp.Cache
+        use Nebulex.Adapters.Local.QueryHelper
+
+        # Store session data with automatic tagging by user ID
+        @decorate cache_put(key: session_id, opts: [tag: {:session, user_id}])
+        def store_session(user_id, session_id, data) do
+          data
+        end
+
+        # Evict all sessions for a specific user when they log out
+        @decorate cache_evict(query: &evict_user_sessions_query/1)
+        def logout_user(user_id) do
+          :ok
+        end
+
+        defp evict_user_sessions_query(%{args: [user_id]} = _context) do
+          match_spec tag: t, where: t == {:session, user_id}
+        end
+
+        # Clear all sessions across all users (e.g., during maintenance)
+        @decorate cache_evict(query: &evict_all_sessions_query/1)
+        def clear_all_sessions do
+          :ok
+        end
+
+        defp evict_all_sessions_query(_context) do
+          # Match all entries with a session tag (pattern {:session, _})
+          match_spec tag: t, where: is_tuple(t) and elem(t, 0) == :session
+        end
+      end
+
+  > The combination of decorators, QueryHelper, and tagging provides a clean,
+  > declarative way to manage cache lifecycles with minimal boilerplate.
+
   ## Transaction API
 
   This adapter inherits the default implementation provided by

lib/nebulex/adapters/local/query_helper.ex

@@ -240,10 +240,7 @@ if Code.ensure_loaded?(Ex2ms) do
 
       # Build the tuple elements
       elements = [
-        :entry
-        | Enum.map(ordered_fields, fn field ->
-            Map.get(field_map, field, {:_, [], Elixir})
-          end)
+        :entry | Enum.map(ordered_fields, &Map.get(field_map, &1, {:_, [], Elixir}))
       ]
 
       # Return as a tuple AST node

mix.exs

@@ -2,9 +2,9 @@ defmodule NebulexAdaptersLocal.MixProject do
   use Mix.Project
 
   @source_url "http://github.com/elixir-nebulex/nebulex_local"
-  @version "3.0.0-rc.1"
-  # @nbx_tag "3.0.0-rc.1"
-  # @nbx_vsn "3.0.0-rc.1"
+  @version "3.0.0-rc.2"
+  # @nbx_tag "3.0.0-rc.2"
+  # @nbx_vsn "3.0.0-rc.2"
 
   def project do
     [
@@ -56,6 +56,7 @@ defmodule NebulexAdaptersLocal.MixProject do
       {:sobelow, "~> 0.14", only: [:dev, :test], runtime: false},
       {:stream_data, "~> 1.2", only: [:dev, :test]},
       {:mimic, "~> 2.1", only: :test},
+      {:decorator, "~> 1.4", only: :test},
 
       # Benchmark Test
       {:benchee, "~> 1.4", only: [:dev, :test]},

mix.lock

@@ -1,15 +1,16 @@
 %{
-  "benchee": {:hex, :benchee, "1.4.0", "9f1f96a30ac80bab94faad644b39a9031d5632e517416a8ab0a6b0ac4df124ce", [:mix], [{:deep_merge, "~> 1.0", [hex: :deep_merge, repo: "hexpm", optional: false]}, {:statistex, "~> 1.0", [hex: :statistex, repo: "hexpm", optional: false]}, {:table, "~> 0.1.0", [hex: :table, repo: "hexpm", optional: true]}], "hexpm", "299cd10dd8ce51c9ea3ddb74bb150f93d25e968f93e4c1fa31698a8e4fa5d715"},
+  "benchee": {:hex, :benchee, "1.5.0", "4d812c31d54b0ec0167e91278e7de3f596324a78a096fd3d0bea68bb0c513b10", [:mix], [{:deep_merge, "~> 1.0", [hex: :deep_merge, repo: "hexpm", optional: false]}, {:statistex, "~> 1.1", [hex: :statistex, repo: "hexpm", optional: false]}, {:table, "~> 0.1.0", [hex: :table, repo: "hexpm", optional: true]}], "hexpm", "5b075393aea81b8ae74eadd1c28b1d87e8a63696c649d8293db7c4df3eb67535"},
   "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.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"},
+  "decorator": {:hex, :decorator, "1.4.0", "a57ac32c823ea7e4e67f5af56412d12b33274661bb7640ec7fc882f8d23ac419", [:mix], [], "hexpm", "0a07cedd9083da875c7418dea95b78361197cf2bf3211d743f6f7ce39656597f"},
   "deep_merge": {:hex, :deep_merge, "1.0.0", "b4aa1a0d1acac393bdf38b2291af38cb1d4a52806cf7a4906f718e1feb5ee961", [:mix], [], "hexpm", "ce708e5f094b9cd4e8f2be4f00d2f4250c4095be93f8cd6d018c753894885430"},
   "dialyxir": {:hex, :dialyxir, "1.4.6", "7cca478334bf8307e968664343cbdb432ee95b4b68a9cba95bdabb0ad5bdfd9a", [:mix], [{:erlex, ">= 0.2.7", [hex: :erlex, repo: "hexpm", optional: false]}], "hexpm", "8cf5615c5cd4c2da6c501faae642839c8405b49f8aa057ad4ae401cb808ef64d"},
   "earmark_parser": {:hex, :earmark_parser, "1.4.44", "f20830dd6b5c77afe2b063777ddbbff09f9759396500cdbe7523efd58d7a339c", [:mix], [], "hexpm", "4778ac752b4701a5599215f7030989c989ffdc4f6df457c5f36938cc2d2a2750"},
   "erlex": {:hex, :erlex, "0.2.7", "810e8725f96ab74d17aac676e748627a07bc87eb950d2b83acd29dc047a30595", [:mix], [], "hexpm", "3ed95f79d1a844c3f6bf0cea61e0d5612a42ce56da9c03f01df538685365efb0"},
   "ex2ms": {:hex, :ex2ms, "1.7.0", "45b9f523d0b777667ded60070d82d871a37e294f0b6c5b8eca86771f00f82ee1", [:mix], [], "hexpm", "2589eee51f81f1b1caa6d08c990b1ad409215fe6f64c73f73c67d36ed10be827"},
-  "ex_doc": {:hex, :ex_doc, "0.38.4", "ab48dff7a8af84226bf23baddcdda329f467255d924380a0cf0cee97bb9a9ede", [:mix], [{:earmark_parser, "~> 1.4.44", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_c, ">= 0.1.0", [hex: :makeup_c, repo: "hexpm", optional: true]}, {:makeup_elixir, "~> 0.14 or ~> 1.0", [hex: :makeup_elixir, repo: "hexpm", optional: false]}, {:makeup_erlang, "~> 0.1 or ~> 1.0", [hex: :makeup_erlang, repo: "hexpm", optional: false]}, {:makeup_html, ">= 0.1.0", [hex: :makeup_html, repo: "hexpm", optional: true]}], "hexpm", "f7b62346408a83911c2580154e35613eb314e0278aeea72ed7fedef9c1f165b2"},
+  "ex_doc": {:hex, :ex_doc, "0.39.1", "e19d356a1ba1e8f8cfc79ce1c3f83884b6abfcb79329d435d4bbb3e97ccc286e", [:mix], [{:earmark_parser, "~> 1.4.44", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_c, ">= 0.1.0", [hex: :makeup_c, repo: "hexpm", optional: true]}, {:makeup_elixir, "~> 0.14 or ~> 1.0", [hex: :makeup_elixir, repo: "hexpm", optional: false]}, {:makeup_erlang, "~> 0.1 or ~> 1.0", [hex: :makeup_erlang, repo: "hexpm", optional: false]}, {:makeup_html, ">= 0.1.0", [hex: :makeup_html, repo: "hexpm", optional: true]}], "hexpm", "8abf0ed3e3ca87c0847dfc4168ceab5bedfe881692f1b7c45f4a11b232806865"},
   "excoveralls": {:hex, :excoveralls, "0.18.5", "e229d0a65982613332ec30f07940038fe451a2e5b29bce2a5022165f0c9b157e", [:mix], [{:castore, "~> 1.0", [hex: :castore, repo: "hexpm", optional: true]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: false]}], "hexpm", "523fe8a15603f86d64852aab2abe8ddbd78e68579c8525ae765facc5eae01562"},
   "file_system": {:hex, :file_system, "1.1.1", "31864f4685b0148f25bd3fbef2b1228457c0c89024ad67f7a81a3ffbc0bbad3a", [:mix], [], "hexpm", "7a15ff97dfe526aeefb090a7a9d3d03aa907e100e262a0f8f7746b78f8f87a5d"},
   "ham": {:hex, :ham, "0.3.2", "02ae195f49970ef667faf9d01bc454fb80909a83d6c775bcac724ca567aeb7b3", [:mix], [], "hexpm", "b71cc684c0e5a3d32b5f94b186770551509e93a9ae44ca1c1a313700f2f6a69a"},
@@ -18,7 +19,7 @@
   "makeup_elixir": {:hex, :makeup_elixir, "1.0.1", "e928a4f984e795e41e3abd27bfc09f51db16ab8ba1aebdba2b3a575437efafc2", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.2.3 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "7284900d412a3e5cfd97fdaed4f5ed389b8f2b4cb49efc0eb3bd10e2febf9507"},
   "makeup_erlang": {:hex, :makeup_erlang, "1.0.2", "03e1804074b3aa64d5fad7aa64601ed0fb395337b982d9bcf04029d68d51b6a7", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "af33ff7ef368d5893e4a267933e7744e46ce3cf1f61e2dccf53a111ed3aa3727"},
   "mimic": {:hex, :mimic, "2.1.1", "29008b71c842b652b065d6f9a24e05d84a2fac7181c34627e1ef5229659702e1", [:mix], [{:ham, "~> 0.3", [hex: :ham, repo: "hexpm", optional: false]}], "hexpm", "a3c330c8840feb29ab43b2375ac023073b936429e5320dd5ca1c95a7322a0da7"},
-  "nebulex": {:git, "https://github.com/elixir-nebulex/nebulex.git", "4ecbc0ebebfb16d2135f457237eadf2d47c90b38", [branch: "main"]},
+  "nebulex": {:git, "https://github.com/elixir-nebulex/nebulex.git", "9f201516c5f66065481fae4a5793233b6c64d7eb", [branch: "main"]},
   "nimble_options": {:hex, :nimble_options, "1.1.1", "e3a492d54d85fc3fd7c5baf411d9d2852922f66e69476317787a7b2bb000a61b", [:mix], [], "hexpm", "821b2470ca9442c4b6984882fe9bb0389371b8ddec4d45a9504f00a66f650b44"},
   "nimble_parsec": {:hex, :nimble_parsec, "1.4.2", "8efba0122db06df95bfaa78f791344a89352ba04baedd3849593bfce4d0dc1c6", [:mix], [], "hexpm", "4b21398942dda052b403bbe1da991ccd03a053668d147d53fb8c4e0efe09c973"},
   "shards": {:hex, :shards, "1.1.1", "8b42323457d185b26b15d05187784ce6c5d1e181b35c46fca36c45f661defe02", [:make, :rebar3], [], "hexpm", "169a045dae6668cda15fbf86d31bf433d0dbbaec42c8c23ca4f8f2d405ea8eda"},

test/nebulex/adapters/local/query_helper_test.exs

@@ -188,9 +188,10 @@ defmodule Nebulex.Adapters.Local.QueryHelperTest do
       true = :ets.insert(table, {:entry, 3, "value3", 1200, :infinity, :tag_a})
       true = :ets.insert(table, {:entry, 4, 100, 1300, 2300, :tag_c})
       true = :ets.insert(table, {:entry, 5, 200, 1400, 2400, :tag_c})
+      true = :ets.insert(table, {:entry, {:key, 6}, 300, 1500, 2500, :tag_d})
 
       # Verify all entries were inserted
-      5 = :ets.info(table, :size)
+      assert :ets.info(table, :size) == 6
 
       on_exit(fn ->
         if :ets.whereis(table_name) != :undefined do
@@ -217,7 +218,7 @@ defmodule Nebulex.Adapters.Local.QueryHelperTest do
     test "selects entries with value guard", %{table: table} do
       ms = match_spec key: k, value: v, where: is_integer(v) and v > 100, select: {k, v}
 
-      assert :ets.select(table, ms) == [{5, 200}]
+      assert :ets.select(table, ms) |> Enum.sort() == [{5, 200}, {{:key, 6}, 300}] |> Enum.sort()
     end
 
     test "selects entries with exp guard", %{table: table} do
@@ -245,7 +246,8 @@ defmodule Nebulex.Adapters.Local.QueryHelperTest do
       assert Enum.sort(result) ==
                Enum.sort([
                  {:entry, 4, 100, 1300, 2300, :tag_c},
-                 {:entry, 5, 200, 1400, 2400, :tag_c}
+                 {:entry, 5, 200, 1400, 2400, :tag_c},
+                 {:entry, {:key, 6}, 300, 1500, 2500, :tag_d}
                ])
     end
 
@@ -265,14 +267,14 @@ defmodule Nebulex.Adapters.Local.QueryHelperTest do
       # Verify the entry was deleted
       assert :ets.lookup(table, 2) == []
       # Other entries should still exist
-      assert :ets.info(table, :size) == 4
+      assert :ets.info(table, :size) == 5
     end
 
     test "matches without guards", %{table: table} do
       ms = match_spec key: k, value: v, select: k
       result = :ets.select(table, ms)
 
-      assert Enum.sort(result) == [1, 2, 3, 4, 5]
+      assert Enum.sort(result) |> Enum.sort() == [1, 2, 3, 4, 5, {:key, 6}] |> Enum.sort()
     end
 
     test "matches with only specific field binding", %{table: table} do
@@ -294,6 +296,12 @@ defmodule Nebulex.Adapters.Local.QueryHelperTest do
 
       assert Enum.sort(result) == [{4, 100}, {5, 200}]
     end
+
+    test "selects entries with key as tuple", %{table: table} do
+      ms = match_spec key: k, value: v, where: k == {:key, 6}, select: {k, v}
+
+      assert :ets.select(table, ms) == [{{:key, 6}, 300}]
+    end
   end
 
   describe "keyref_match_spec/2" do