typed_cache 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9beff9345d3d58fb92c4cb77467271af9f8bc1212529dd7d6d21d13fa4e285ad
-  data.tar.gz: 0aef7f30f5f5029e8667944c4b6724694f5cf8e1bae1a7358a4c0a6c0931902b
+  metadata.gz: 2cd862f92c635a4ee2fa15fa26186e56226d9dca6a132ad7de2f96fc9935ee31
+  data.tar.gz: a862c34b4e86e838e4a30bfda8149357581782d4e2c64dd6a37882724930955d
 SHA512:
-  metadata.gz: a848cd77e148388fc0624acdd2f5b5826c573fc418d13dc15ce1f7b75acf365d8860cff1ceb123bb0b3b8f374fba100e25b5d818f51b66ac3aea0f3e6c6fe745
-  data.tar.gz: 9e0929925806d7449462bb70deb7773eb19301d268cb93fc0fb321ca5ff38619c724f9e305c40e255a21a3b85e44fd80d4bed69ac97d13f4385af878a25c9f8d
+  metadata.gz: 2df948e5a9e9808c13547e940547484ad9cff0ce75085f3ee512a8ef866459dd791c7d1c85147b65dbb6ccbacea973cc412b44d3be12f7cb564c94afee452f2a
+  data.tar.gz: 57e1c99cb2c11a82e1b9add65357a8abacdc0260ea1ca66c6cd3616ac13db73439b24c25643eed5425a1a23fb62984bf2feb4ce854c1a54f1bcbd790248e0f2d

data/README.md

@@ -1,5 +1,11 @@
 # TypedCache
 
+![Gem Version](https://img.shields.io/gem/v/typed_cache?style=flat-square&logo=rubygems)
+![GitHub Release Date](https://img.shields.io/github/release-date/glossawy/typed_cache?style=flat-square&label=released&logo=semanticrelease)
+![GitHub last commit](https://img.shields.io/github/last-commit/glossawy/typed_cache?style=flat-square&logo=git)
+
+![GitHub License](https://img.shields.io/github/license/glossawy/typed_cache?style=flat-square&logo=data%3Aimage%2Fsvg%2Bxml%3Bbase64%2CPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCA2NDAgNTEyIj48IS0tIUZvbnQgQXdlc29tZSBGcmVlIDYuNy4yIGJ5IEBmb250YXdlc29tZSAtIGh0dHBzOi8vZm9udGF3ZXNvbWUuY29tIExpY2Vuc2UgLSBodHRwczovL2ZvbnRhd2Vzb21lLmNvbS9saWNlbnNlL2ZyZWUgQ29weXJpZ2h0IDIwMjUgRm9udGljb25zLCBJbmMuLS0%2BPHBhdGggZmlsbD0iI2ZmZmZmZiIgZD0iTTM4NCAzMmwxMjggMGMxNy43IDAgMzIgMTQuMyAzMiAzMnMtMTQuMyAzMi0zMiAzMkwzOTguNCA5NmMtNS4yIDI1LjgtMjIuOSA0Ny4xLTQ2LjQgNTcuM0wzNTIgNDQ4bDE2MCAwYzE3LjcgMCAzMiAxNC4zIDMyIDMycy0xNC4zIDMyLTMyIDMybC0xOTIgMC0xOTIgMGMtMTcuNyAwLTMyLTE0LjMtMzItMzJzMTQuMy0zMiAzMi0zMmwxNjAgMCAwLTI5NC43Yy0yMy41LTEwLjMtNDEuMi0zMS42LTQ2LjQtNTcuM0wxMjggOTZjLTE3LjcgMC0zMi0xNC4zLTMyLTMyczE0LjMtMzIgMzItMzJsMTI4IDBjMTQuNi0xOS40IDM3LjgtMzIgNjQtMzJzNDkuNCAxMi42IDY0IDMyem01NS42IDI4OGwxNDQuOSAwTDUxMiAxOTUuOCA0MzkuNiAzMjB6TTUxMiA0MTZjLTYyLjkgMC0xMTUuMi0zNC0xMjYtNzguOWMtMi42LTExIDEtMjIuMyA2LjctMzIuMWw5NS4yLTE2My4yYzUtOC42IDE0LjItMTMuOCAyNC4xLTEzLjhzMTkuMSA1LjMgMjQuMSAxMy44bDk1LjIgMTYzLjJjNS43IDkuOCA5LjMgMjEuMSA2LjcgMzIuMUM2MjcuMiAzODIgNTc0LjkgNDE2IDUxMiA0MTZ6TTEyNi44IDE5NS44TDU0LjQgMzIwbDE0NC45IDBMMTI2LjggMTk1Ljh6TS45IDMzNy4xYy0yLjYtMTEgMS0yMi4zIDYuNy0zMi4xbDk1LjItMTYzLjJjNS04LjYgMTQuMi0xMy44IDI0LjEtMTMuOHMxOS4xIDUuMyAyNC4xIDEzLjhsOTUuMiAxNjMuMmM1LjcgOS44IDkuMyAyMS4xIDYuNyAzMi4xQzI0MiAzODIgMTg5LjcgNDE2IDEyNi44IDQxNlMxMS43IDM4MiAuOSAzMzcuMXoiLz48L3N2Zz4%3D)
+
 TypedCache is a lightweight, type-safe façade around your favourite Ruby cache
 stores. It adds three things on top of the raw back-end implementation:
 
@@ -35,26 +41,33 @@ If there are issues with unsigned gems, use `MediumSecurity` instead.
 ```ruby
 require "typed_cache"
 
-# Build an in-memory cache with ActiveSupport-style instrumentation
+# 1. Build a store
 store = TypedCache.builder
-            .with_backend(:memory, shared: true)
-            .with_instrumentation      # or .with_decorator(:instrumented)
-            .build                     # => Either[Error, Store]
-            .value
-
-users_key   = store.namespace.key("users")   # => CacheKey
-snapshot    = store.set(users_key, [1, 2, 3]) # => Either[Error, Snapshot]
-puts snapshot.value           # => [1, 2, 3]
+  .with_backend(:memory, shared: true)
+  .with_instrumentation(:rails) # e.g. using ActiveSupport
+  .build
+  .value # unwrap Either for brevity
+
+# 2. Get a reference to a key
+user_ref = store.ref("users:123") # => CacheRef
+
+# 3. Fetch and compute if absent
+user_snapshot = user_ref.fetch do
+  puts "Cache miss! Computing..."
+  { id: 123, name: "Jane" }
+end.value # => Snapshot
+
+puts "Found: #{user_snapshot.value} (from_cache?=#{user_snapshot.from_cache?})"
 ```
 
 ## Builder API
 
-| Step                          | Purpose                                                        |
-| ----------------------------- | -------------------------------------------------------------- |
-| `with_backend(:name, **opts)` | Mandatory. Configure the concrete **Backend** and its options. |
-| `with_decorator(:key)`        | Optional. Add a decorator by registry key.                     |
-| `with_instrumentation`        | Convenience alias for `with_decorator(:instrumented)`.         |
-| `build`                       | Returns `Either[Error, Store]`.                                |
+| Step                            | Purpose                                                        |
+| ------------------------------- | -------------------------------------------------------------- |
+| `with_backend(:name, **opts)`   | Mandatory. Configure the concrete **Backend** and its options. |
+| `with_decorator(:key)`          | Optional. Add a decorator by registry key.                     |
+| `with_instrumentation(:source)` | Optional. Add instrumentation, e.g. `:rails` or `:dry`.        |
+| `build`                         | Returns `Either[Error, Store]`.                                |
 
 ### Back-ends vs Decorators
 
@@ -112,16 +125,100 @@ result.fold(
 )
 ```
 
+## The `CacheRef` API
+
+While you can call `get`, `set`, and `fetch` directly on the `store`, the more powerful way to work with TypedCache is via the `CacheRef` object. It provides a rich, monadic API for a single cache key.
+
+You get a `CacheRef` by calling `store.ref(key)`:
+
+```ruby
+user_ref = store.ref("users:123") # => #<TypedCache::CacheRef ...>
+```
+
+Now you can operate on it:
+
+```ruby
+# Fetch a value, computing it if it's missing
+snapshot_either = user_ref.fetch do
+  { id: 123, name: "Jane Doe" }
+end
+
+# The result is always an Either[Error, Snapshot]
+snapshot_either.fold(
+  ->(err)      { warn "Something went wrong: #{err.message}" },
+  ->(snapshot) { puts "Got value: #{snapshot.value} (from cache: #{snapshot.from_cache?})" }
+)
+
+# You can also map over values
+name_either = user_ref.map { |user| user[:name] }
+puts "User name is: #{name_either.value.value}" # unwrap Either, then Snapshot
+```
+
+The `CacheRef` API encourages a functional style and makes composing cache operations safe and predictable.
+
 ## Instrumentation
 
-Decorators publish ActiveSupport notifications when
-`TypedCache.config.instrumentation.enabled = true`:
+TypedCache can publish events about cache operations using different instrumenters. To enable it, use the `with_instrumentation` method on the builder, specifying an instrumentation backend:
 
+```ruby
+# For ActiveSupport::Notifications (e.g. in Rails)
+store = TypedCache.builder
+  .with_backend(:memory)
+  .with_instrumentation(:rails)
+  .build.value
+
+# For Dry::Monitor
+store = TypedCache.builder
+  .with_backend(:memory)
+  .with_instrumentation(:dry)
+  .build.value
 ```
-<operation>.<namespace>  # e.g. get.typed_cache
+
+Events are published to a topic like `typed_cache.<operation>` (e.g., `typed_cache.get`). The topic namespace can be configured.
+
+Payload keys include: `:namespace, :key, :operation, :duration`, and `cache_hit`.
+
+You can subscribe to these events like so:
+
+```ruby
+# Example for ActiveSupport
+ActiveSupport::Notifications.subscribe("typed_cache.get") do |name, start, finish, id, payload|
+
+# Or you can subscribe via the store object itself
+instrumenter = store.instrumenter
+instrumenter.subscribe("get") do |event|
+  payload = event.payload
+  puts "Cache GET for key #{payload[:key]} took #{payload[:duration]}ms. Hit? #{payload[:cache_hit]}"
+end
 ```
 
-Payload keys: `:namespace, :key, :duration, :cache_hit`, …
+If you call `with_instrumentation` with no arguments, it uses a `Null` instrumenter, which has no overhead.
+
+### Custom Instrumenters
+
+Just like with back-ends and decorators, you can write and register your own instrumenters. An instrumenter must implement an `instrument` and a `subscribe` method.
+
+```ruby
+class MyCustomInstrumenter
+  include TypedCache::Instrumenter
+
+  def instrument(operation, key, **payload, &block)
+    # ... your logic ...
+  end
+
+  def subscribe(event_name, **filters, &block)
+    # ... your logic ...
+  end
+end
+
+# Register it
+TypedCache::Instrumenters.register(:custom, MyCustomInstrumenter)
+
+# Use it
+store = TypedCache.builder
+  .with_instrumentation(:custom)
+  # ...
+```
 
 ## Further examples
 

data/examples.md

@@ -7,16 +7,19 @@ This document provides practical examples of using TypedCache in real applicatio
 The simplest way to create a type-safe cache:
 
 ```ruby
-user_namespace = TypedCache::Namespace.at("users")
-
-cache_result = TypedCache.builder
+# The builder can be pre-configured and reused
+builder = TypedCache.builder
   .with_backend(:memory, shared: true)
-  .with_instrumentation
-  .build(user_namespace)            # => Either[Error, Store]
+  .with_instrumentation(:rails)
+
+# The store is built with a namespace
+users_store = builder.build(TypedCache::Namespace.at("users")).value
+
+# Get a reference to a key
+user_ref = users_store.ref("123")
 
-store = cache_result.value          # unwrap for brevity
-key   = store.namespace.key("123")  # => CacheKey
-store.set(key, { id: 123, name: "Jane" })
+# Set a value
+user_ref.set({ id: 123, name: "Jane" })
 ```
 
 ## Rails Integration
@@ -24,13 +27,17 @@ store.set(key, { id: 123, name: "Jane" })
 Using TypedCache with `Rails.cache` and ActiveSupport notifications:
 
 ```ruby
-cache_result = TypedCache.builder
+# Use Rails.cache as the backend
+builder = TypedCache.builder
   .with_backend(:active_support, Rails.cache)
-  .with_instrumentation
-  .build                                     # defaults to TypedCache.config.default_namespace
+  .with_instrumentation(:rails)
+
+# Build a store for a specific part of your app
+header_store = builder.build(TypedCache::Namespace.at("views:header")).value
 
-cache = cache_result.value
-cache.fetch(cache.namespace.key("header")) { render_header }
+# Use a ref to fetch/render
+header_ref = header_store.ref("main")
+header_html = header_ref.fetch { render_header }.value.value
 ```
 
 ## Pattern Matching
@@ -58,35 +65,72 @@ Reuse a preconfigured builder for several namespaces:
 base_builder = TypedCache.builder
   .with_backend(:memory, shared: true)
 
-users_store  = base_builder.build(TypedCache::Namespace.at("users")).value
-posts_store  = base_builder.build(TypedCache::Namespace.at("posts")).value
+users_store    = base_builder.build(TypedCache::Namespace.at("users")).value
+posts_store    = base_builder.build(TypedCache::Namespace.at("posts")).value
 comments_store = base_builder.build(TypedCache::Namespace.at("comments")).value
 ```
 
-## Cache Operations
+## CacheRef API
 
-Working with cache values using the monadic interface:
+The `CacheRef` is the most powerful way to interact with a cache key.
 
 ```ruby
-# Set a value
-cache.set({ id: 1, name: "John" })
+ref = store.ref("some-key") # => CacheRef
+```
+
+### Get a value
+
+The `get` method returns an `Either[Error, Snapshot]`.
 
-# Get with error handling
-cache.get.fold(
-  ->(error) { puts "Cache miss: #{error.message}" },
-  ->(snapshot) { puts "Found: #{snapshot.value}" }
+```ruby
+result = ref.get
+result.fold(
+  ->(error)    { puts "Cache miss or error: #{error.message}" },
+  ->(snapshot) { puts "Found: #{snapshot.value} (from cache: #{snapshot.from_cache?})" }
 )
+```
+
+### Fetch (get or compute)
+
+The `fetch` method is the most common operation. It gets a value from the cache, but if it's missing, it runs the block, stores the result, and returns it.
+
+```ruby
+user = ref.fetch { expensive_user_lookup(123) }.value.value
+```
+
+### Mapping values
+
+You can transform the value inside the cache reference without breaking the monadic chain.
+
+```ruby
+# user_ref holds { id: 1, name: "John" }
+name_ref = user_ref.map { |user| user[:name] }
+
+name_snapshot = name_ref.get.value # => Snapshot(value: "John", ...)
+```
+
+### Chaining operations with `bind`
 
-# Get with Maybe semantics (no error details)
-user = cache.peek.value_or({ id: 0, name: "Anonymous" })
+For more complex logic, you can use `bind` (or `flat_map`) to chain operations that return an `Either`.
 
-# Fetch with computation
-result = cache.fetch do
-  # This block runs only on cache miss
-  expensive_user_lookup(user_id)
+```ruby
+user_ref.bind do |user|
+  if user.active?
+    posts_ref.set(user.posts)
+  else
+    TypedCache::Either.left(StandardError.new("User is not active"))
+  end
 end
 ```
 
+### Getting the value or a default
+
+If you just want the value and don't care about the `Snapshot` metadata, you can use `value_or`.
+
+```ruby
+user_name = user_ref.map { |u| u[:name] }.value_or("Anonymous")
+```
+
 ## Custom Backend
 
 Registering and using a custom cache backend:
@@ -126,35 +170,47 @@ cache = TypedCache.builder
   .build.value
 ```
 
-## Instrumentation Only
+## Custom Instrumenter
+
+You can create and register your own instrumenter to integrate with any monitoring or logging system. An instrumenter needs to implement `instrument` and `subscribe` methods.
+
+Here's an example of a simple logging instrumenter:
 
 ```ruby
-TypedCache.configure_instrumentation do |config|
-  config.enabled = true
-  config.namespace = "my_app_cache"
+class LoggingInstrumenter
+  include TypedCache::Instrumenter
+  include TypedCache::Instrumenters::Mixins::NamespacedSingleton
+
+  def instrument(operation, key, **payload, &block)
+    puts "[CACHE] Starting: #{operation} for key #{key}"
+    result = block.call
+    puts "[CACHE] Finished: #{operation} for key #{key}"
+    result
+  end
+
+  def subscribe(operation, **_filters, &block)
+    # For simplicity, this example doesn't implement a full subscription model,
+    # but in a real-world scenario, you would store and manage callbacks here.
+    puts "[CACHE] Subscribed to '#{operation}'"
+  end
 end
 
-cache = TypedCache.builder
+# Register the new instrumenter
+TypedCache::Instrumenters.register(:logger, LoggingInstrumenter)
+
+# Use it in the builder
+logging_cache = TypedCache.builder
   .with_backend(:memory)
-  .with_instrumentation
+  .with_instrumentation(:logger)
   .build.value
 
-cache.set(cache.namespace.key("metrics"), 42)
-```
-
-## Configuration Snippet
+# Subscribe to an event
+logging_cache.instrumenter.subscribe("get")
 
-```ruby
-TypedCache.configure do |config|
-  config.default_namespace = "my_app"
-end
-```
-
-You can register additional decorators or back-ends as needed:
-
-```ruby
-TypedCache::Decorators.register(:logger, MyLoggerDecorator)
-TypedCache::Backends.register(:redis,   MyRedisBackend)
+# Operations will now be logged
+logging_cache.ref("test").set("hello")
+# => [CACHE] Starting: set for key test
+# => [CACHE] Finished: set for key test
 ```
 
 ## Thread Safety

data/lib/typed_cache/backends/memory.rb

@@ -1,7 +1,8 @@
 # frozen_string_literal: true
 
 require 'singleton'
-require 'forwardable'
+
+require 'concurrent/map'
 
 module TypedCache
   class MemoryStoreRegistry
@@ -42,14 +43,16 @@ module TypedCache
         # @rbs! attr_accessor expires_at: Time
         # @rbs! attr_reader value: V
 
-        # @rbs (value: V, expires_in: Integer) -> Entry[V]
-        def self.expiring(value:, expires_in:)
-          new(value: value, expires_at: Clock.moment + expires_in)
+        class << self
+          # @rbs (value: V, expires_in: Integer) -> Entry[V]
+          def expiring(value:, expires_in:)
+            new(value: value, expires_at: Clock.moment + expires_in)
+          end
         end
 
         # @rbs () -> bool
         def expired?
-          Clock.moment >= expires_at
+          Clock.now >= expires_at
         end
       end
       private_constant :Entry
@@ -84,7 +87,7 @@ module TypedCache
       #: (cache_key, V) -> either[Error, Snapshot[V]]
       def set(key, value)
         key = namespaced_key(key)
-        expires_at = Clock.moment + @ttl
+        expires_at = Clock.now + @ttl
         entry = Entry.new(value: value, expires_at: expires_at)
         backing_store[key] = entry
         Either.right(Snapshot.new(value, source: :cache))

data/lib/typed_cache/backends.rb

@@ -1,25 +1,23 @@
 # frozen_string_literal: true
 
-require 'dry/struct'
-require 'dry/types'
-
-require_relative 'backends/memory'
-require_relative 'backends/active_support'
+require 'typed_cache/registry'
 
 module TypedCache
   module Backends
+    autoload :Memory, 'typed_cache/backends/memory'
+    autoload :ActiveSupport, 'typed_cache/backends/active_support'
+
+    # @api private
     # Backend registry using composition
     REGISTRY = Registry.new('backend', {
       memory: Memory,
-      active_support: ActiveSupport,
     }).freeze
 
-    private_constant :REGISTRY
-
     class << self
       extend Forwardable
       delegate [:resolve, :register, :available, :registered?] => :registry
 
+      # @api private
       #: -> Registry
       def registry = REGISTRY
 

data/lib/typed_cache/cache_builder.rb

@@ -1,8 +1,32 @@
 # frozen_string_literal: true
 
+require 'typed_cache/namespace'
+require 'typed_cache/cache_key'
+require 'typed_cache/errors'
+
+require 'typed_cache/store'
+require 'typed_cache/backends'
+require 'typed_cache/decorators'
+require 'typed_cache/instrumenters'
+
+require 'dry/struct'
+require 'dry/types'
+
 module TypedCache
   class CacheBuilder
     # @rbs! type config = TypedCache::typed_cache_config
+    # @rbs! type instrumenter_source = :default | :dry | :rails | Instrumenter
+
+    class BackendConfig < Dry::Struct
+      attribute :name, Dry.Types::Symbol
+      attribute :args, Dry.Types::Array.of(Dry.Types::Any)
+      attribute :options, Dry.Types::Hash.map(Dry.Types::Symbol, Dry.Types::Any)
+    end
+
+    class DecoratorConfig < Dry::Struct
+      attribute :name, Dry.Types::Symbol
+      attribute :options, Dry.Types::Hash.map(Dry.Types::Symbol, Dry.Types::Any)
+    end
 
     # @rbs (config, Registry[backend[untyped]], Registry[decorator[untyped]]) -> void
     def initialize(config, backend_registry = Backends, decorator_registry = Decorators)
@@ -10,15 +34,13 @@ module TypedCache
       @backend_registry = backend_registry
       @decorator_registry = decorator_registry
 
-      @backend_name = nil
-      @backend_args = []
-      @backend_options = {}
-      @decorators = []
+      @backend_config = nil
+      @decorator_configs = []
     end
 
     # Builds the cache - the only method that can fail
     # @rbs (?Namespace) -> either[Error, Store[V]]
-    def build(namespace = Namespace.at(@config.default_namespace))
+    def build(namespace = Namespace.at(@config.instrumentation.namespace))
       validate_and_build(namespace)
     end
 
@@ -26,22 +48,22 @@ module TypedCache
     # Invalid configurations are caught during build()
     # @rbs (Symbol, *untyped, **untyped) -> self
     def with_backend(name, *args, **options)
-      @backend_name = name
-      @backend_args = args
-      @backend_options = options
+      @backend_config = BackendConfig.new(name:, args:, options:)
       self
     end
 
     # Adds an arbitrary decorator by registry key
     # @rbs (Symbol) -> self
-    def with_decorator(name)
-      @decorators << name
+    def with_decorator(name, **options)
+      @decorator_configs << DecoratorConfig.new(name:, options:)
       self
     end
 
-    # @rbs () -> self
-    def with_instrumentation
-      with_decorator(:instrumented)
+    # Adds instrumentation using the specified strategy.
+    # @rbs (instrumenter_source) -> either[Error, self]
+    def with_instrumentation(source = :default)
+      @instrumenter_source = source
+      self
     end
 
     private
@@ -49,29 +71,60 @@ module TypedCache
     # @rbs (Namespace) -> either[Error, Store[V]]
     def validate_and_build(namespace)
       create_store(namespace).bind do |store|
-        apply_decorators(store)
+        apply_decorators(store).bind do |decorated_store|
+          apply_instrumentation(decorated_store)
+        end
       end
     end
 
     # @rbs (Namespace) -> either[Error, Store[V]]
     def create_store(namespace)
-      return Either.left(ArgumentError.new('Backend not configured')) unless @backend_name
+      return Either.left(ArgumentError.new('Backend not configured')) unless @backend_config
 
       # Prepend namespace to the arguments for the backend constructor
-      @backend_registry.resolve(@backend_name, namespace, *@backend_args, **@backend_options)
+      @backend_registry.resolve(@backend_config.name, namespace, *@backend_config.args, **@backend_config.options)
     end
 
     # @rbs (Store[V]) -> either[Error, Store[V]]
     def apply_decorators(store)
-      return Either.right(store) if @decorators.empty?
+      return Either.right(store) if @decorator_configs.empty?
 
-      @decorators.reduce(Either.right(store)) do |result, decorator_name|
+      names = @decorator_configs.map(&:name)
+
+      name_counts = names.tally
+      duplicates = name_counts.keys.select { |name| name_counts[name] > 1 }
+      return Either.left(ArgumentError.new("Duplicate decorator: #{duplicates.join(", ")}")) if duplicates.any?
+
+      @decorator_configs.reduce(Either.right(store)) do |result, decorator_config|
         result.bind do |current_store|
-          @decorator_registry.resolve(decorator_name, current_store)
+          @decorator_registry.resolve(decorator_config.name, current_store, **decorator_config.options)
         end
       end
     rescue => e
       Either.left(StoreError.new(:decorator_application, 'decorator', "Failed to apply decorator: #{e.message}", e))
     end
+
+    def apply_instrumentation(store)
+      return Either.right(store) unless @instrumenter_source
+
+      instrumenter =
+        case @instrumenter_source
+        when Symbol
+          Instrumenters.resolve(@instrumenter_source, namespace: @config.default_namespace)
+        when Instrumenter
+          Either.right(@instrumenter_source)
+        else
+          Either.left(TypedCache::TypeError.new(
+            ':default | :dry | :rails | Instrumenter',
+            @instrumenter_source.class.name,
+            @instrumenter_source,
+            "Invalid instrumenter source: #{@instrumenter_source.inspect}",
+          ))
+        end
+
+      instrumenter.bind do |i|
+        @decorator_registry.resolve(:instrumented, store, instrumenter: i)
+      end
+    end
   end
 end

data/lib/typed_cache/cache_key.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative 'namespace'
+
 module TypedCache
   class CacheKey
     extend Forwardable

data/lib/typed_cache/cache_ref.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+require_relative 'cache_key'
+require_relative 'store'
+require_relative 'snapshot'
+
 module TypedCache
   # A monadic wrapper for cached values that provides safe access with rich error context.
   # All operations return Either[Error, Snapshot[V]] to provide detailed information about