Overall improvements and updates

Author: cabol

.tool-versions

@@ -1,2 +1,2 @@
-elixir 1.18.3-otp-27
-erlang 27.3.2
+elixir 1.19.4-otp-28
+erlang 28.2

README.md

@@ -5,10 +5,16 @@
 [Cachex]: http://github.com/whitfin/cachex
 
 ![CI](http://github.com/elixir-nebulex/nebulex_adapters_cachex/workflows/CI/badge.svg)
-[![Codecov](http://codecov.io/gh/elixir-nebulex/nebulex_adapters_cachex/branch/v3.0.0-dev/graph/badge.svg)](http://codecov.io/gh/elixir-nebulex/nebulex_adapters_cachex/branch/v3.0.0-dev/graph/badge.svg)
+[![Codecov](http://codecov.io/gh/elixir-nebulex/nebulex_adapters_cachex/graph/badge.svg)](http://codecov.io/gh/elixir-nebulex/nebulex_adapters_cachex/branch/graph/badge.svg)
 [![Hex Version](http://img.shields.io/hexpm/v/nebulex_adapters_cachex.svg)](http://hex.pm/packages/nebulex_adapters_cachex)
 [![Documentation](http://img.shields.io/badge/Documentation-ff69b4)](http://hexdocs.pm/nebulex_adapters_cachex)
 
+## About
+
+This adapter provides a Nebulex interface on top of [Cachex][Cachex], a powerful
+in-memory caching library for Elixir. It combines Nebulex's unified caching API
+with Cachex's rich feature set.
+
 ## Installation
 
 Add `:nebulex_adapters_cachex` to your list of dependencies in `mix.exs`:
@@ -26,7 +32,7 @@ for more information.
 
 ## Usage
 
-You can define a cache using Cachex as follows:
+Define your cache:
 
 ```elixir
 defmodule MyApp.Cache do
@@ -36,97 +42,64 @@ defmodule MyApp.Cache do
 end
 ```
 
-Where the configuration for the cache must be in your application
-environment, usually defined in your `config/config.exs`:
+Configure in your `config/config.exs`:
 
 ```elixir
 config :my_app, MyApp.Cache,
-  stats: true,
-  ...
+  stats: true
 ```
 
-If your application was generated with a supervisor (by passing `--sup`
-to `mix new`) you will have a `lib/my_app/application.ex` file containing
-the application start callback that defines and starts your supervisor.
-You just need to edit the `start/2` function to start the cache as a
-supervisor on your application's supervisor:
+Add to your application supervision tree:
 
 ```elixir
 def start(_type, _args) do
   children = [
     {MyApp.Cache, []},
+    # ... other children
   ]
 
-  ...
+  Supervisor.start_link(children, strategy: :one_for_one)
 end
 ```
 
-Since Cachex uses macros for some configuration options, you could also
-pass the options in runtime when the cache is started, either by calling
-`MyApp.Cache.start_link/1` directly, or in your app supervision tree:
+The adapter supports all Cachex options. See [Cachex.start_link/2][cachex_start_link]
+for configuration options including expiration, hooks, limits, and warmers.
 
-```elixir
-def start(_type, _args) do
-  children = [
-    {MyApp.Cache, cachex_opts()},
-  ]
-
-  ...
-end
-
-defp cachex_opts do
-  import Cachex.Spec
-
-  [
-    expiration: expiration(
-      # how often cleanup should occur
-      interval: :timer.seconds(30),
-
-      # default record expiration
-      default: :timer.seconds(60),
-
-      # whether to enable lazy checking
-      lazy: true
-    ),
-
-    ...
-  ]
-end
-```
-
-> See [Cachex.start_link/2][cachex_start_link] for more information
-  about the options.
+For more details and examples, see the [module documentation][docs].
 
 [cachex_start_link]: http://hexdocs.pm/cachex/Cachex.html#start_link/2
+[docs]: http://hexdocs.pm/nebulex_adapters_cachex/Nebulex.Adapters.Cachex.html
+
+## Distributed Caching Topologies
 
-## Distributed caching topologies
+The Cachex adapter works seamlessly with Nebulex's distributed adapters. Use it
+as a local cache in multi-level topologies or as primary storage for partitioned
+caches.
 
-Using the distributed adapters with `Cachex` as a primary storage is possible.
-  For example, let's define a multi-level cache (near cache topology), where
-  the L1 is a local cache using Cachex and the L2 is a partitioned cache.
+**Example: Multi-level cache (near cache pattern)**
 
 ```elixir
 defmodule MyApp.NearCache do
   use Nebulex.Cache,
-    otp_app: :nebulex,
+    otp_app: :my_app,
     adapter: Nebulex.Adapters.Multilevel
 
   defmodule L1 do
     use Nebulex.Cache,
-      otp_app: :nebulex,
+      otp_app: :my_app,
       adapter: Nebulex.Adapters.Cachex
   end
 
   defmodule L2 do
     use Nebulex.Cache,
-      otp_app: :nebulex,
+      otp_app: :my_app,
       adapter: Nebulex.Adapters.Partitioned,
       primary_storage_adapter: Nebulex.Adapters.Cachex
   end
 end
 ```
 
-And the configuration may look like:
+Configuration:
 
 ```elixir
 config :my_app, MyApp.NearCache,
@@ -137,16 +110,12 @@ config :my_app, MyApp.NearCache,
   ]
 ```
 
-> **NOTE:** You could also use [Nebulex.Adapters.Redis][nbx_redis_adapter]
-> for L2, it would be matter of changing the adapter for the L2 and the
-> configuration for set up Redis adapter.
-
-See [Nebulex examples](http://github.com/elixir-nebulex/nebulex_examples).
-You will find examples for all different topologies, even using other adapters
-like Redis; for all examples you just have to replace `Nebulex.Adapters.Local`
-by `Nebulex.Adapters.Cachex`.
+You can also use [Nebulex.Adapters.Redis][nbx_redis_adapter] for L2 to add
+persistence. See the [module documentation][docs] and
+[Nebulex examples][nbx_examples] for more topologies.
 
 [nbx_redis_adapter]: http://github.com/elixir-nebulex/nebulex_redis_adapter
+[nbx_examples]: http://github.com/elixir-nebulex/nebulex_examples
 
 ## Testing
 
@@ -161,7 +130,7 @@ to `nebulex`:
 export NEBULEX_PATH=nebulex
 ```
 
-Second, make sure you fetch `:nebulex` dependency directly from GtiHub
+Second, make sure you fetch `:nebulex` dependency directly from GitHub
 by running:
 
 ```
@@ -212,11 +181,11 @@ When submitting a pull request you should not update the
 [CHANGELOG.md](CHANGELOG.md), and also make sure you test your changes
 thoroughly, include unit tests alongside new or changed code.
 
-Before to submit a PR it is highly recommended to run `mix test.ci` and ensure
+Before submitting a PR it is highly recommended to run `mix test.ci` and ensure
 all checks run successfully.
 
 ## Copyright and License
 
 Copyright (c) 2020, Carlos Bolaños.
 
-Nebulex.Adapters.Cachex source code is licensed under the [MIT License](LICENSE).
+Nebulex.Adapters.Cachex source code is licensed under the [MIT License](LICENSE.md).

lib/nebulex/adapters/cachex.ex

@@ -2,12 +2,19 @@ defmodule Nebulex.Adapters.Cachex do
   @moduledoc """
   Nebulex adapter for [Cachex][cachex].
 
+  This adapter provides a Nebulex interface on top of Cachex, a powerful
+  in-memory caching library for Elixir. It combines Nebulex's unified caching
+  API with Cachex's rich feature set including transactions, hooks, expiration,
+  and statistics. Use this adapter when you need a feature-rich local cache or
+  as a building block for distributed caching topologies.
+
   [cachex]: http://hexdocs.pm/cachex/Cachex.html
 
   ## Options
 
-  Since Nebulex is just a wrapper on top of Cachex, the options are the same as
-  [Cachex.start_link/2][cachex_start_link].
+  This adapter supports all Cachex configuration options. The options are passed
+  directly to [Cachex.start_link/2][cachex_start_link], allowing you to leverage
+  Cachex's full feature set including expiration, hooks, limits, and warmers.
 
   [cachex_start_link]: https://hexdocs.pm/cachex/Cachex.html#start_link/2
 
@@ -115,15 +122,92 @@ defmodule Nebulex.Adapters.Cachex do
         ]
 
   > **NOTE:** You could also use [Nebulex.Adapters.Redis][nbx_redis_adapter] for
-    L2, it would be matter of changing the adapter for the L2 and the
-    configuration to set up Redis adapter.
+    L2, it would be a matter of changing the adapter for the L2 and the
+    configuration to set up the Redis adapter.
 
   [nbx_redis_adapter]: https://github.com/elixir-nebulex/nebulex_redis_adapter
 
   See [Nebulex examples](https://github.com/elixir-nebulex/nebulex_examples).
   You will find examples for all different topologies, even using other adapters
   like Redis; for all examples using the `Nebulex.Adapters.Local` adapter,
   you can replace it by `Nebulex.Adapters.Cachex`.
+
+  ## Query API
+
+  The adapter supports querying cached entries using Cachex's query syntax or
+  explicit key lists.
+
+  ### Pattern-based queries
+
+  Use Cachex query syntax for pattern matching:
+
+      # Get all entries
+      MyApp.Cache.get_all!()
+
+      # Count all entries
+      MyApp.Cache.count_all!()
+
+      # Delete all entries
+      MyApp.Cache.delete_all!()
+
+      # Delete expired entries
+      MyApp.Cache.delete_all!(:expired)
+
+      # Stream entries for large datasets
+      MyApp.Cache.stream!() |> Enum.take(100)
+
+  ### Explicit key queries
+
+  Query specific keys using the `in: keys` syntax:
+
+      # Get multiple keys
+      MyApp.Cache.get_all!(in: ["key1", "key2", "key3"])
+
+      # Count specific keys
+      MyApp.Cache.count_all!(in: ["key1", "key2"])
+
+      # Delete specific keys
+      MyApp.Cache.delete_all!(in: ["key1", "key2"])
+
+  ## Transactions
+
+  The adapter provides full transaction support through Cachex's locking
+  mechanism, ensuring atomic operations across multiple keys.
+
+      MyApp.Cache.transaction(
+        fn ->
+          value = MyApp.Cache.get!("counter")
+          MyApp.Cache.put!("counter", value + 1)
+          MyApp.Cache.put!("last_updated", DateTime.utc_now())
+        end,
+        keys: ["counter", "last_updated"]
+      )
+
+  Transactions automatically handle locking and isolation for the specified keys.
+
+  ## Stats and Monitoring
+
+  Enable statistics collection by setting `stats: true` in your configuration
+  (enabled by default):
+
+      config :my_app, MyApp.Cache,
+        stats: true
+
+  Retrieve statistics:
+
+      # Get all stats
+      iex> MyApp.Cache.info!(:stats)
+      %{
+        calls: %{get: 10, put: 5, delete: 2},
+        evictions: 0,
+        expirations: 1,
+        hit_rate: 80.0,
+        hits: 8,
+        misses: 2,
+        ...
+      }
+
+  See `Cachex.Stats` for detailed statistics information.
   """
 
   # Provide Cache Implementation

mix.exs

@@ -16,13 +16,7 @@ defmodule NebulexAdaptersCachex.MixProject do
 
       # Testing
       test_coverage: [tool: ExCoveralls],
-      preferred_cli_env: [
-        coveralls: :test,
-        "coveralls.detail": :test,
-        "coveralls.post": :test,
-        "coveralls.html": :test,
-        "test.ci": :test
-      ],
+      test_ignore_filters: [~r{test/(shared|support)/.*\.exs}],
 
       # Dialyzer
       dialyzer: dialyzer(),
@@ -40,6 +34,18 @@ defmodule NebulexAdaptersCachex.MixProject do
     ]
   end
 
+  def cli do
+    [
+      preferred_envs: [
+        coveralls: :test,
+        "coveralls.detail": :test,
+        "coveralls.post": :test,
+        "coveralls.html": :test,
+        "test.ci": :test
+      ]
+    ]
+  end
+
   defp deps do
     [
       nebulex_dep(),
@@ -50,16 +56,16 @@ defmodule NebulexAdaptersCachex.MixProject do
       {:excoveralls, "~> 0.18", only: :test},
       {:credo, "~> 1.7", only: [:dev, :test], runtime: false},
       {:dialyxir, "~> 1.4", only: [:dev, :test], runtime: false},
-      {:sobelow, "~> 0.13", only: [:dev, :test], runtime: false},
-      {:mimic, "~> 1.7", only: :test},
-      {:stream_data, "~> 1.1", only: [:dev, :test]},
+      {:sobelow, "~> 0.14", only: [:dev, :test], runtime: false},
+      {:mimic, "~> 2.2", only: :test},
+      {:stream_data, "~> 1.2", only: [:dev, :test]},
 
       # Benchmark Test
-      {:benchee, "~> 1.3", only: [:dev, :test]},
+      {:benchee, "~> 1.5", only: [:dev, :test]},
       {:benchee_html, "~> 1.0", only: [:dev, :test]},
 
       # Docs
-      {:ex_doc, "~> 0.36", only: [:dev, :test], runtime: false}
+      {:ex_doc, "~> 0.39", only: [:dev, :test], runtime: false}
     ]
   end