typed_cache 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2cd862f92c635a4ee2fa15fa26186e56226d9dca6a132ad7de2f96fc9935ee31
-  data.tar.gz: a862c34b4e86e838e4a30bfda8149357581782d4e2c64dd6a37882724930955d
+  metadata.gz: 52137d39af663110c085558e5d6885fbe22d02b4a185f7a1ef3f4aa2dbe6a619
+  data.tar.gz: 030bf378a6effe782ab28fdb876c64c73d8997e5a3a9ec543735abe55973e421
 SHA512:
-  metadata.gz: 2df948e5a9e9808c13547e940547484ad9cff0ce75085f3ee512a8ef866459dd791c7d1c85147b65dbb6ccbacea973cc412b44d3be12f7cb564c94afee452f2a
-  data.tar.gz: 57e1c99cb2c11a82e1b9add65357a8abacdc0260ea1ca66c6cd3616ac13db73439b24c25643eed5425a1a23fb62984bf2feb4ce854c1a54f1bcbd790248e0f2d
+  metadata.gz: 38641da2ef43033f286833d84492b02f09dcfca291e7eab53c93bf6c9f737de5f077984a4f742de06c62a0c90db19d00bbc03cb032485143e9a542576fb5f90c
+  data.tar.gz: 2fb8cd40d84bb43a3f9905ccc7c0d30d853cdf0b030cf192a6e17517545ac94f256a3371f85bcd068e4f08d12c7a32a937f8eb3a87622b8b3a16429e772bd8bb

data/README.md

@@ -9,7 +9,7 @@
 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.
@@ -125,9 +125,9 @@ result.fold(
 )
 ```
 
-## The `CacheRef` API
+## 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.
+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)`:
 
@@ -154,6 +154,28 @@ 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

data/examples.md

@@ -70,9 +70,26 @@ posts_store    = base_builder.build(TypedCache::Namespace.at("posts")).value
 comments_store = base_builder.build(TypedCache::Namespace.at("comments")).value
 ```
 
-## CacheRef API
+## Advanced Namespacing
 
-The `CacheRef` is the most powerful way to interact with a cache key.
+You can create nested namespaces using variadic arguments to `Namespace.at` or by chaining `join`.
+
+```ruby
+# 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
@@ -90,6 +107,23 @@ result.fold(
 )
 ```
 
+### 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.

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

@@ -69,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)
 
@@ -80,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.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,
@@ -108,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/cache_key.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'forwardable'
 require_relative 'namespace'
 
 module TypedCache
@@ -22,7 +23,7 @@ module TypedCache
 
     # @rbs () -> String
     def to_s
-      "#{@namespace}:#{@key}"
+      [@namespace.to_s, @key].join(delimiter)
     end
 
     alias cache_key to_s
@@ -43,5 +44,12 @@ module TypedCache
     end
 
     alias eql? ==
+
+    private
+
+    # @rbs (String) -> String
+    def delimiter
+      TypedCache.config.cache_delimiter
+    end
   end
 end

data/lib/typed_cache/cache_ref.rb

@@ -22,14 +22,14 @@ module TypedCache
 
     # Gets a value from the cache as a snapshot
     #: -> either[Error, Snapshot[V]]
-    def get
-      store.get(key)
+    def read
+      store.read(key)
     end
 
     # Sets a value in the cache and returns it as an updated snapshot
     #: (V) -> either[Error, Snapshot[V]]
-    def set(value)
-      store.set(key, value)
+    def write(value)
+      store.write(key, value)
     end
 
     # Deletes the value from the cache and returns the deleted value as a snapshot
@@ -48,25 +48,25 @@ module TypedCache
     # Checks if the cache contains a value for this key
     #: -> bool
     def present?
-      store.get(key).right?
+      store.read(key).right?
     end
 
     # Checks if the cache is empty for this key
     #: -> bool
     def empty?
-      store.get(key).left?
+      store.read(key).left?
     end
 
     # Maps over the cached value if it exists, preserving snapshot metadata
     #: [R] () { (V) -> R } -> either[Error, Snapshot[R]]
     def map(&block)
-      get.map { |snapshot| snapshot.map(&block) }
+      read.map { |snapshot| snapshot.map(&block) }
     end
 
     # Binds over the cached value, allowing for monadic composition with snapshots
     #: [R] () { (V) -> either[Error, R] } -> either[Error, Snapshot[R]]
     def bind(&block)
-      get.bind { |snapshot| snapshot.bind(&block) }
+      read.bind { |snapshot| snapshot.bind(&block) }
     end
 
     alias flat_map bind
@@ -75,9 +75,9 @@ module TypedCache
     # Returns the updated value as a snapshot with source=:updated
     #: () { (V) -> V } -> either[Error, Snapshot[V]]
     def update(&block)
-      get.bind do |snapshot|
+      read.bind do |snapshot|
         new_value = yield(snapshot.value)
-        set(new_value)
+        write(new_value)
       rescue => e
         Either.left(StoreError.new(
           :update,
@@ -91,7 +91,7 @@ module TypedCache
     # Returns the cached value or a default if the cache is empty/errored
     #: (V) -> V
     def value_or(default)
-      get.fold(
+      read.fold(
         ->(_error) { default },
         ->(snapshot) { snapshot.value },
       )
@@ -101,7 +101,7 @@ module TypedCache
     # This provides a more functional approach than value_or
     #: -> maybe[V]
     def value_maybe
-      get.fold(
+      read.fold(
         ->(_error) { Maybe.none },
         ->(snapshot) { Maybe.some(snapshot.value) },
       )
@@ -139,21 +139,21 @@ module TypedCache
     end
 
     # Pattern matching support for Either[Error, Snapshot[V]] results
-    #: [R] () { (Error) -> R } () { (Snapshot[V]) -> R } -> R
+    #: [R] (^(Error) -> R, ^(Snapshot[V]) -> R) -> R
     def fold(left_fn, right_fn)
-      get.fold(left_fn, right_fn)
+      read.fold(left_fn, right_fn)
     end
 
     # Convenience method to work with the snapshot directly
     #: [R] () { (Snapshot[V]) -> R } -> either[Error, R]
     def with_snapshot(&block)
-      get.map(&block)
+      read.map(&block)
     end
 
     # Convenience method to work with just the value (losing snapshot context)
     #: [R] () { (V) -> R } -> either[Error, R]
     def with(&block)
-      get.map { |snapshot| yield(snapshot.value) }
+      read.map { |snapshot| yield(snapshot.value) }
     end
   end
 end

data/lib/typed_cache/decorator.rb

@@ -23,7 +23,15 @@ module TypedCache
     # @rbs override
     #: (cache_key) -> either[Error, CacheRef[V]]
     def ref(key)
-      CacheRef.new(self, key)
+      CacheRef.new(self, namespaced_key(key))
+    end
+
+    # @rbs override
+    #: (self) -> void
+    def initialize_copy(other)
+      super
+
+      @store = other.store.clone
     end
   end
 end

data/lib/typed_cache/decorators/instrumented.rb

@@ -24,9 +24,15 @@ module TypedCache
 
         class_eval(<<~RUBY, __FILE__, __LINE__ + 1)
           def #{alias_prefix}_with_instrumentation(...)
+            return #{alias_prefix}_without_instrumentation(...) if @in_instrumentation
+
             key = #{alias_prefix}_instrumentation_key(...)
             instrumenter.instrument(:"#{operation}", key, store_type: store_type) do
+              @in_instrumentation = true
+
               #{alias_prefix}_without_instrumentation(...)
+            ensure
+              @in_instrumentation = false
             end
           end
         RUBY
@@ -40,6 +46,16 @@ module TypedCache
     def initialize(store, instrumenter:)
       @store = store
       @instrumenter = instrumenter
+
+      # Avoid instrumenting the cache calls themselves, fetch_all may call fetch for example
+      @in_instrumentation = false
+    end
+
+    # @rbs override
+    #: (self) -> self
+    def initialize_copy(other)
+      super
+      @instrumenter = other.instrumenter
     end
 
     # @rbs override
@@ -49,12 +65,6 @@ module TypedCache
       "instrumented(#{store.store_type})"
     end
 
-    # @rbs override
-    # @rbs (key) -> CacheRef[V]
-    def ref(key)
-      CacheRef.new(self, key)
-    end
-
     # Additional methods that might exist on the wrapped store
     def respond_to_missing?(method_name, include_private = false)
       store.respond_to?(method_name, include_private) || super
@@ -69,10 +79,13 @@ module TypedCache
     end
 
     # Instrument core operations with proper key extraction
-    instrument(:get)    { |key, *_| key }
-    instrument(:set)    { |key, *_| key }
+    instrument(:read) { |key, *_| key }
+    instrument(:read_all) { |keys, *_| keys.map(&:to_s).join('_') }
+    instrument(:write)    { |key, *_| key }
+    instrument(:write_all) { |values, *_| values.map { |key, _| key.to_s }.join('_') }
     instrument(:delete) { |key, *_| key }
     instrument(:fetch)  { |key, *_| key }
+    instrument(:fetch_all) { |keys, *_| keys.map(&:to_s).join('_') }
     instrument(:key?)   { |key, *_| key }
     instrument(:clear)  { 'all' }
   end

data/lib/typed_cache/either.rb

@@ -27,6 +27,8 @@ module TypedCache
   # @rbs! interface _Either[out E, out R]
   #     def left?: -> bool
   #     def right?: -> bool
+  #     def right_or_else: (^(E) -> void) -> R
+  #     def right_or_raise!: -> R
   #     def map: [T] () { (R) -> T } -> either[E, T]
   #     def bind: [E2, R2] () { (R) -> either[E2, R2] } -> either[E | E2, R2]
   #     def map_left: [F] () { (E) -> F } -> either[F, R]
@@ -39,6 +41,8 @@ module TypedCache
 
     attr_reader :error #: E
 
+    alias value error
+
     #: (E) -> void
     def initialize(error)
       @error = error
@@ -52,6 +56,14 @@ module TypedCache
     #: -> false
     def right? = false
 
+    # @rbs override
+    #: (^(E) -> void) -> bot
+    def right_or_else(&) = yield(error)
+
+    # @rbs override
+    #: -> bot
+    def right_or_raise! = raise(error)
+
     # @rbs override
     #: [T] () { (R) -> T } -> either[E, T]
     def map(&) = self
@@ -82,6 +94,8 @@ module TypedCache
 
     attr_reader :value #: R
 
+    alias result value
+
     #: (R) -> void
     def initialize(value)
       @value = value
@@ -95,6 +109,14 @@ module TypedCache
     #: -> true
     def right? = true
 
+    # @rbs override
+    #: (^(E) -> void) -> R
+    def right_or_else(&) = value
+
+    # @rbs override
+    #: -> R
+    def right_or_raise! = value
+
     # @rbs override
     #: [T] () { (R) -> T } -> either[E, T]
     def map(&) = Right.new(yield(value))

data/lib/typed_cache/instrumenter.rb

@@ -6,7 +6,7 @@ module TypedCache
     # @rbs! type event = Dry::Events::Event | ActiveSupport::Notifications::Event
 
     # @rbs [R](String, String, **untyped) { -> R } -> R
-    def instrument(event_name, key, **payload)
+    def instrument(event_name, key, **payload, &)
       raise NotImplementedError, "#{self.class} must implement #instrument"
     end
 
@@ -20,21 +20,21 @@ module TypedCache
       config.namespace
     end
 
+    # @rbs () -> bool
+    def enabled? = config.enabled
+
+    private
+
     # @rbs (String, String, **untyped) -> Hash[Symbol, untyped]
     def build_payload(operation, key, **payload)
       { namespace:, key:, operation: }.merge(payload)
     end
 
-    # @rbs () -> bool
-    def enabled? = config.enabled
-
     # @rbs (String) -> String
     def event_name(operation)
       "#{namespace}.#{operation}"
     end
 
-    private
-
     # @rbs () -> TypedCache::_TypedCacheInstrumentationConfig
     def config
       TypedCache.config.instrumentation

data/lib/typed_cache/instrumenters/mixins/namespaced_singleton.rb

@@ -43,6 +43,9 @@ module TypedCache
             namespace_cache.get(namespace.to_s)
           end
 
+          # @rbs () -> void
+          def clear_namespace_cache = namespace_cache.clear
+
           # @rbs () -> Concurrent::Map[String, Class[Instrumenter & NamespacedSingleton]]
           def namespace_cache = @namespace_cache ||= Concurrent::Map.new # rubocop:disable ThreadSafety
         end

data/lib/typed_cache/instrumenters.rb

@@ -28,11 +28,12 @@ module TypedCache
       # @rbs () -> Registry[Symbol, Class[Instrumenter]]
       def registry = REGISTRY
 
+      # @rbs! def register: (Symbol, Class[Instrumenter]) -> void
       # @rbs! def resolve: (Symbol, **untyped) -> either[Error, Instrumenter]
       # @rbs! def available: () -> Array[Symbol]
       # @rbs! def registered?: (Symbol) -> Boolean
 
-      def_delegators :registry, :resolve, :available, :registered?
+      def_delegators :registry, :resolve, :available, :registered?, :register
     end
   end
 end

data/lib/typed_cache/maybe.rb

@@ -33,6 +33,8 @@ module TypedCache
   #     def nothing?: -> bool
   #     def map: [T] () { (V) -> T } -> maybe[T]
   #     def bind: [T] () { (V) -> maybe[T] } -> maybe[T]
+  #     def value_or: [T] (T) -> T
+  #     def value_or_raise!: -> V
   #     alias flat_map bind
   #   end
 
@@ -62,6 +64,14 @@ module TypedCache
     #: [T] () { (V) -> maybe[T] } -> maybe[T]
     def bind(&) = yield(value)
 
+    # @rbs override
+    #: [T] (T) -> T
+    def value_or(default) = value
+
+    # @rbs override
+    #: -> V
+    def value_or_raise! = value
+
     alias flat_map bind
 
     #: (Array[top]) -> ({ value: V })
@@ -88,5 +98,13 @@ module TypedCache
     #: [T] () { (V) -> maybe[T] } -> maybe[T]
     def bind(&) = self
     alias flat_map bind
+
+    # @rbs override
+    #: [T] (T) -> T
+    def value_or(default) = default
+
+    # @rbs override
+    #: -> V
+    def value_or_raise! = raise TypedCache::TypeError, 'Nothing has no value'
   end
 end