typed_cache 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9beff9345d3d58fb92c4cb77467271af9f8bc1212529dd7d6d21d13fa4e285ad
-  data.tar.gz: 0aef7f30f5f5029e8667944c4b6724694f5cf8e1bae1a7358a4c0a6c0931902b
+  metadata.gz: 52137d39af663110c085558e5d6885fbe22d02b4a185f7a1ef3f4aa2dbe6a619
+  data.tar.gz: 030bf378a6effe782ab28fdb876c64c73d8997e5a3a9ec543735abe55973e421
 SHA512:
-  metadata.gz: a848cd77e148388fc0624acdd2f5b5826c573fc418d13dc15ce1f7b75acf365d8860cff1ceb123bb0b3b8f374fba100e25b5d818f51b66ac3aea0f3e6c6fe745
-  data.tar.gz: 9e0929925806d7449462bb70deb7773eb19301d268cb93fc0fb321ca5ff38619c724f9e305c40e255a21a3b85e44fd80d4bed69ac97d13f4385af878a25c9f8d
+  metadata.gz: 38641da2ef43033f286833d84492b02f09dcfca291e7eab53c93bf6c9f737de5f077984a4f742de06c62a0c90db19d00bbc03cb032485143e9a542576fb5f90c
+  data.tar.gz: 2fb8cd40d84bb43a3f9905ccc7c0d30d853cdf0b030cf192a6e17517545ac94f256a3371f85bcd068e4f08d12c7a32a937f8eb3a87622b8b3a16429e772bd8bb

data/README.md

@@ -1,9 +1,15 @@
 # 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:
 
-1. **Namespacing** – hierarchical `Namespace` helpers prevent key collisions.
+1. **Namespacing** – hierarchical `Namespace` helpers prevent key collisions. You can create nested namespaces easily, like `Namespace.at("users", "profiles", "avatars")`.
 2. **Stronger types** – RBS signatures as well as monadic types like `Either`, `Maybe`, and `Snapshot` wrap cache results so you always know whether you have a value, an error, or a cache-miss.
 3. **Composable decorators** – behaviours like instrumentation can be layered
    on without touching the underlying store.
@@ -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,122 @@ result.fold(
 )
 ```
 
+## The `CacheRef` and `Store` APIs
+
+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. The `Store` also provides `fetch_all` for batch operations.
+
+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
+```
+
+### Batch Operations with `fetch_all`
+
+For retrieving multiple keys at once, the `Store` provides a `fetch_all` method. This is more efficient than fetching keys one by one, especially with remote back-ends like Redis.
+
+It takes a list of keys and a block to compute the values for any missing keys.
+
+```ruby
+user_refs = store.fetch_all("users:123", "users:456") do |missing_key|
+  # This block is called for each cache miss
+  user_id = missing_key.split(":").last
+  puts "Cache miss for #{missing_key}! Computing..."
+  { id: user_id, name: "Fetched User #{user_id}" }
+end
+
+user_refs.each do |key, snapshot_either|
+  snapshot_either.fold(
+    ->(err)      { warn "Error for #{key}: #{err.message}" },
+    ->(snapshot) { puts "Got value for #{key}: #{snapshot.value}" }
+  )
+end
+```
+
+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
 
-store = cache_result.value          # unwrap for brevity
-key   = store.namespace.key("123")  # => CacheKey
-store.set(key, { id: 123, name: "Jane" })
+# Get a reference to a key
+user_ref = users_store.ref("123")
+
+# 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)
 
-cache = cache_result.value
-cache.fetch(cache.namespace.key("header")) { render_header }
+# Build a store for a specific part of your app
+header_store = builder.build(TypedCache::Namespace.at("views:header")).value
+
+# 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,106 @@ 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
+## Advanced Namespacing
 
-Working with cache values using the monadic interface:
+You can create nested namespaces using variadic arguments to `Namespace.at` or by chaining `join`.
 
 ```ruby
-# Set a value
-cache.set({ id: 1, name: "John" })
+# These are equivalent
+ns1 = TypedCache::Namespace.at("app", "v1", "users")
+ns2 = TypedCache::Namespace.at("app").join("v1").join("users")
+
+puts ns1.to_s # => "app:v1:users"
+puts ns2.to_s # => "app:v1:users"
+
+# You can then build a store with this complex namespace
+user_store = base_builder.build(ns1).value
+user_store.ref("123").set({ name: "Deeply Nested" })
+```
+
+## CacheRef and Store APIs
+
+The `CacheRef` is the most powerful way to interact with a single cache key, while the `Store` provides batch operations.
+
+```ruby
+ref = store.ref("some-key") # => CacheRef
+```
+
+### Get a value
 
-# Get with error handling
-cache.get.fold(
-  ->(error) { puts "Cache miss: #{error.message}" },
-  ->(snapshot) { puts "Found: #{snapshot.value}" }
+The `get` method returns an `Either[Error, Snapshot]`.
+
+```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 all (get or compute)
+
+The `fetch_all` method on the `store` is used for bulk-retrieving items. It gets all existing values from the cache and for the ones that are missing, it runs the block, stores the result, and returns it.
+
+```ruby
+results = store.fetch_all("user:1", "user:2") do |missing_key|
+  # logic to compute the value for a missing key
+  "computed-#{missing_key}"
+end
+
+results.each do |key, snapshot_either|
+   snapshot_either.map do |snapshot|
+      puts "#{key} -> #{snapshot.value} (from_cache?=#{snapshot.from_cache?})"
+   end
+end
+```
+
+### 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 +204,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)
-```
+# Subscribe to an event
+logging_cache.instrumenter.subscribe("get")
 
-## Configuration Snippet
-
-```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/active_support.rb

@@ -20,24 +20,24 @@ module TypedCache
 
       # @rbs override
       #: (cache_key) -> either[Error, Snapshot[V]]
-      def get(key)
+      def read(key)
         cache_key_str = namespaced_key(key).to_s
         raw_value = cache_store.read(cache_key_str, default_options)
         return Either.left(CacheMissError.new(key)) if raw_value.nil?
 
-        Either.right(Snapshot.new(raw_value, source: :cache))
+        Either.right(Snapshot.cached(key, raw_value))
       rescue => e
         Either.left(StoreError.new(:get, key, "Failed to read from cache: #{e.message}", e))
       end
 
       # @rbs override
       #: (cache_key, V) -> either[Error, Snapshot[V]]
-      def set(key, value)
+      def write(key, value)
         cache_key_str = namespaced_key(key).to_s
         success = cache_store.write(cache_key_str, value, default_options)
 
         if success
-          Either.right(Snapshot.new(value, source: :cache))
+          Either.right(Snapshot.cached(key, value))
         else
           Either.left(StoreError.new(:set, key, 'Failed to write to cache', nil))
         end
@@ -45,10 +45,19 @@ module TypedCache
         Either.left(StoreError.new(:set, key, "Failed to write to cache: #{e.message}", e))
       end
 
+      # @rbs override
+      #: (Hash[cache_key, V]) -> either[Error, Array[Snapshot[V]]]
+      def write_all(values)
+        results = cache_store.write_multi(values.map { |key, value| [namespaced_key(key).to_s, value] }.to_h, default_options)
+        Either.right(results.map { |key, value| Snapshot.cached(key, value) })
+      rescue => e
+        Either.left(StoreError.new(:set_all, values, "Failed to write to cache: #{e.message}", e))
+      end
+
       # @rbs override
       #: (cache_key) -> either[Error, Snapshot[V]]
       def delete(key)
-        get(key).fold(
+        read(key).fold(
           ->(error) { Either.left(error) },
           ->(snapshot) {
             cache_key_str = namespaced_key(key).to_s
@@ -60,6 +69,42 @@ module TypedCache
         Either.left(StoreError.new(:delete, key, "Failed to delete from cache: #{e.message}", e))
       end
 
+      # @rbs override
+      #: (Array[cache_key]) -> either[Error, Array[Snapshot[V]]]
+      def read_all(keys)
+        results = cache_store.read_multi(*keys.map { |key| namespaced_key(key).to_s }, default_options)
+        Either.right(results.map { |key, value| [key, Snapshot.cached(key, value)] }.to_h)
+      end
+
+      # @rbs override
+      #: (Array[cache_key]) { (CacheKey) -> V? } -> either[Error, Array[Snapshot[V]]]
+      def fetch_all(keys, &block)
+        cache_keys = keys.map { |key| namespaced_key(key) }
+        key_map = cache_keys.index_by(&:to_s)
+
+        computed_keys = Set.new #: Set[String]
+        results = cache_store.fetch_multi(*key_map.keys, default_options) do |key|
+          computed_keys << key
+          yield(key_map[key])
+        end
+
+        snapshots = [] #: Array[Snapshot[V]]
+
+        results.each do |key, value|
+          maybe_value = Maybe.wrap(value)
+          snapshots <<
+            if computed_keys.include?(key)
+              Snapshot.computed(key, maybe_value)
+            else
+              Snapshot.cached(key, maybe_value)
+            end
+        end
+
+        Either.right(snapshots)
+      rescue StandardError => e
+        Either.left(StoreError.new(:fetch_all, keys, "Failed to fetch from cache: #{e.message}", e))
+      end
+
       # @rbs override
       #: (cache_key) -> bool
       def key?(key)

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
@@ -66,7 +69,7 @@ module TypedCache
 
       # @rbs override
       #: (cache_key) -> either[Error, Snapshot[V]]
-      def get(key)
+      def read(key)
         key = namespaced_key(key)
         return Either.left(CacheMissError.new(key)) unless backing_store.key?(key)
 
@@ -77,17 +80,17 @@ module TypedCache
           return Either.left(CacheMissError.new(key))
         end
 
-        Either.right(Snapshot.new(entry.value, source: :cache))
+        Either.right(Snapshot.cached(key, entry.value))
       end
 
       # @rbs override
       #: (cache_key, V) -> either[Error, Snapshot[V]]
-      def set(key, value)
+      def write(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))
+        Either.right(Snapshot.cached(key, value))
       rescue => e
         Either.left(StoreError.new(
           :set,
@@ -105,7 +108,7 @@ module TypedCache
         if entry.nil?
           Either.left(CacheMissError.new(key))
         else
-          Either.right(Snapshot.new(entry.value, source: :cache))
+          Either.right(Snapshot.cached(key, entry.value))
         end
       end
 

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