elixir-nebulex/nebulex

This system is Nebulex, a caching library for Elixir that provides a modular framework for building and managing cache adapters. It supports declarative caching via function decorators, key-value and queryable operations, and atomic transactions, while offering built-in observability through Telemetry integration. The library includes utilities for code generation, static analysis, and performance benchmarking to assist developers in implementing and maintaining robust caching solutions.

16 changes.

This period marks the release of Nebulex v3, featuring a comprehensive architectural overhaul that replaces the legacy Mix.Config DSL with NimbleOptions and introduces first-class Telemetry integration for monitoring. The update refactors the core cache API to support transactions, queryable operations, and a new metadata-based adapter model, while removing deprecated distributed node picking and local generation mechanisms. Testing infrastructure was significantly modernized with new mock adapters and shared test macros to validate the expanded feature set.

10 changes.

This period focused on introducing declarative caching via function decorators and enhancing observability through structured event tracking and telemetry handlers. The work also included scaffolding CLI tools for cache generation and significantly expanding test coverage across core components, benchmarks, and the new decorator system.

A new \Nebulex.Adapters.Nil\ adapter has been added to allow users to completely disable caching. This adapter ignores all write operations and returns \nil\ for all reads, making it useful for testing scenarios where cache interference needs to be avoided without flushing entries. The adapter implements the standard adapter behaviors (\KV\, \Queryable\, \Transaction\) and supports runtime hooks for pre/post operations.

lib/nebulex/adapters · high confidence

The \Nebulex.Event.CacheEntryEvent\ module is now available, providing a structured representation for cache entry events. This struct captures details such as the cache module, event type (inserted, updated, deleted, or expired), the target key or query, and the triggering command. It also supports optional metadata, including \:extra\_metadata\ passed via telemetry, allowing users to inspect and react to specific cache operations with richer context.

lib/nebulex/event · high confidence

Nebulex now supports a declarative caching style using Elixir function decorators (\@decorate\), allowing developers to annotate functions with \cacheable\, \cache\_evict\, and \cache\_put\ to automatically manage cache population and eviction. This change introduces a new \Nebulex.Caching.Decorators\ module along with supporting \Context\ and \Runtime\ modules to handle decorator state, key generation, and cache operations. Users can configure default caches, key generators, and error handling behaviors globally via \use Nebulex.Caching\ or per-decorator, and the system supports advanced features like dynamic cache resolution, match functions for conditional caching, and transactional wrapping of cache operations.

lib/nebulex/caching · high confidence

Users can now run \mix nbx\ to view Nebulex help information and available tasks, and use \mix nbx.gen.cache\ to scaffold a new cache module and its configuration. The generator creates a cache file in \lib/\ and updates the application's config file (supporting both \import Config\ and \use Mix.Config\ styles), while providing instructions on adding the cache to the supervision tree.

lib/mix/tasks · high confidence

This change introduces two new Telemetry handlers in the \lib/nebulex/telemetry\ directory: \CacheEntryHandler\ and \CacheStatsCounterHandler\. The \CacheEntryHandler\ allows users to register listeners for specific cache entry events (such as inserts, updates, deletes, and takes), providing detailed metadata including command type, target keys, and extra metadata. The \CacheStatsCounterHandler\ attaches to cache stats counters to automatically aggregate metrics like hits, misses, writes, updates, and deletions based on command outcomes. These handlers enable fine-grained observability into cache operations and performance statistics.

lib/nebulex/telemetry · high confidence

The project now includes configuration files for the Credo linter (.credo.exs) and the Doctor documentation checker (.doctor.exs). These files enforce code style, readability, and documentation coverage standards, with Doctor configured to require 100% module documentation coverage and ignore specific internal helper modules.

(repo-wide) · high confidence

This release upgrades Nebulex to v3, introducing first-class support for Telemetry events to monitor cache lifecycle and command execution, including a new stats counter handler. The adapter API is refactored to use a metadata-based initialization model (\init/1\) and a unified command dispatcher, replacing the previous direct callback structure. The caching DSL is modernized with new decorator macros (\defcacheable\, \defevict\, \defupdatable\) and support for dynamic cache configuration and key references. Additionally, the library adds a \Nebulex.Adapters.Nil\ adapter for disabling caching, a \Mix.Nebulex\ utility module for Mix tasks, and comprehensive stats tracking (hits, misses, evictions, etc.) via Erlang counters.

lib/nebulex · high confidence

This release refactors the core cache implementation into a modular structure, introducing a new Queryable API (\get\_all\, \count\_all\, \delete\_all\, \stream\) that allows filtering and selecting data from the cache. It adds built-in Telemetry support for monitoring cache events, configurable via \:telemetry\ and \:telemetry\_prefix\ options, and introduces a \:bypass\_mode\ for testing. The cache now supports transactions via \Nebulex.Cache.Transaction\ and includes new helper macros like \defcacheapi\ for defining API functions. Configuration is now validated at compile and runtime using \NimbleOptions\, and the supervisor logic has been updated to handle dynamic cache registration and metadata management.

lib/nebulex/cache · high confidence

The \lib/nebulex/adapter\ directory now includes five new behavior modules that define the contract for adapter implementations. \Nebulex.Adapter.KV\ specifies core key-value operations like fetch, put, delete, and counter updates. \Nebulex.Adapter.Queryable\ defines the API for bulk operations such as get\_all, count\_all, delete\_all, and streaming. \Nebulex.Adapter.Info\ standardizes how adapters report cache statistics and server details. \Nebulex.Adapter.Observable\ provides a registry for cache event listeners, with a default Telemetry-based implementation. Finally, \Nebulex.Adapter.Transaction\ specifies the interface for running atomic transactions within the cache. These modules collectively establish the foundational interfaces that adapters must implement to support these features.

lib/nebulex/adapter · high confidence

The \Nebulex.Adapters.Dist.NodePicker\ module has been removed, eliminating the ability to implement custom node selection logic for distributed caching within this library version. Additionally, the main \Nebulex\ module documentation has been significantly expanded to reflect the v3 architecture, explicitly stating that adapters are now separate packages (e.g., \:nebulex\_local\) and must be added as dependencies, and updating configuration examples to use new options like \max\_size\ and \allocated\_memory\ instead of the previous \n\_shards\ and \write\_concurrency\ settings.

lib · high confidence

The project has removed the legacy \config/config.exs\, \config/dev.exs\, and \config/test.exs\ files that previously relied on \Mix.Config\ and \import\_config\. This change eliminates the manual configuration for the Nebulex caching library (including settings for local, distributed, and garbage-collected caches) from the environment-specific config files, indicating a migration away from the deprecated Mix.Config DSL.

config · high confidence

The \Nebulex.Adapters.Local.Generation\ and \Nebulex.Adapters.Local.Metadata\ modules have been removed from the local adapter implementation. This deletion eliminates the previous GenServer-based garbage collection mechanism and the ETS-backed metadata storage used to manage cache generations, indicating a structural change to how the local adapter handles cache lifecycle and generation tracking.

lib/nebulex/adapters/local · high confidence

Add Benchee-based benchmark suite for cache operations; Added Dialyzer tests for caching decorators; Added shared test suite for cache operations; Added test coverage for Nebulex core components; Added tests for cache entry listener detachment in nameless caches; Added tests for cache info, stats, registry, and supervisor configuration; Added tests for the Nebulex Mix task umbrella project validation; Added tests for the new Nil adapter and removed obsolete distributed/local adapter tests; Added tests for the new nbx.gen.cache Mix task; Refactor test support infrastructure with new test adapters and helpers; Refactored shared cache test suite into a reusable macro; Removal of local adapter generation test suite; Updated test infrastructure with mocks and telemetry support.

This release updates the project to version 3.0.4, raising the minimum supported Elixir version from 1.3 to 1.12. The dependency list has been significantly modernized: the legacy \ex\_shards\ dependency is replaced by \nimble\_options\ as a required dependency, while \decorator\ and \telemetry\ are now optional. Development and testing tooling has been upgraded to include \credo\ (1.7), \sobelow\ for security auditing, \mimic\ for mocking, and \benchee\ (1.5) for benchmarking, replacing older versions of \dialyxir\, \excoveralls\, and \ex\_doc\. The \mix.lock\ file reflects these changes, locking specific versions for all transitive dependencies.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 71 → 79 (+8.2)
• Rubric changed (rubric-2026.08.19 → rubric-2026.09.15) — scores are not directly comparable.

• Code Health 99 → 99 (+0.5)
• Architecture 100 → 94 (-6.3)
• Maturity 63 → 67 (+3.9)
• Readiness 68 → 84 (+15.6)
• Security 78 → 100 (+22.2)

• Coverage not included — suite not readable by the collector
• Dependency hygiene not measured — no supported dependency manifest was read
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• Medium CVE: EEF-[CVE redacted] (mix.lock)
• No exposed public API
• Off-boarding risk: anonymized user #1
• Test reliability not included
• The About section links out to a subset of the referenced external docs (e.g., [cache_patterns][cache_patterns], [cache_topologies]), but it does not mention where to find full references for declarative decorators, distributed topologies, or the non-negotiable list. (README.md)

• Dependency advisory scan runs only on code events
• Documentation: no installation or build instructions (README.md)
• Documentation: no usage examples (README.md)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• High: security finding (details withheld)
• Workflow token permissions not restricted

• 6 commits — 5 feature/other, 1 fixes

• (root) — 5 commits
• lib/nebulex — 1 commit

• fix: fix(telemetry): detach cache entry listener for nameless caches (#257)
• change: chore(deps): add mix_audit and run deps.audit in precommit and CI
• change: chore(deps): update deps and .tool-versions
• change: chore(deps): update deps and .tool-versions
• change: chore(deps): update dev/test deps and .tool-versions
• change: chore(mix): rename mix test.ci alias to mix precommit

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

elixir-nebulex/nebulex was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.