typed_cache 0.2.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2cd862f92c635a4ee2fa15fa26186e56226d9dca6a132ad7de2f96fc9935ee31
-  data.tar.gz: a862c34b4e86e838e4a30bfda8149357581782d4e2c64dd6a37882724930955d
+  metadata.gz: 68662a3e64b70950b86c466f7435aa4dc0ba5c31a87637244ece41685aa2cc00
+  data.tar.gz: 07fae7547c15ca5e7bfd900f9f74bb2f40443102bca143ce0f8cee8dc79c4069
 SHA512:
-  metadata.gz: 2df948e5a9e9808c13547e940547484ad9cff0ce75085f3ee512a8ef866459dd791c7d1c85147b65dbb6ccbacea973cc412b44d3be12f7cb564c94afee452f2a
-  data.tar.gz: 57e1c99cb2c11a82e1b9add65357a8abacdc0260ea1ca66c6cd3616ac13db73439b24c25643eed5425a1a23fb62984bf2feb4ce854c1a54f1bcbd790248e0f2d
+  metadata.gz: f81441fdceb975a4251d9f9d816cf71a40847e8ad1f9a3adea0d92075617ef0c9c85ed980b7707b9327221a75dc385459b954bd492e82ff08416fdb835fd6ba6
+  data.tar.gz: ef41b5392bb1f6adb0b2ccbf7f73ea6363c562b3e0621990f94c52445c048c598b9a0c875ad1d4ffaa03907576f68673614098281620d220ba96d6812b70531a

data/README.md

@@ -1,6 +1,6 @@
 # TypedCache
 
-![Gem Version](https://img.shields.io/gem/v/typed_cache?style=flat-square&logo=rubygems)
+[![Gem Version](https://img.shields.io/gem/v/typed_cache?style=flat-square&logo=rubygems)](https://rubygems.org/gems/typed_cache)
 ![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)
 
@@ -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.
@@ -88,7 +88,7 @@ TypedCache::Decorators.available # => [:instrumented]
 ```ruby
 class RedisBackend
   include TypedCache::Backend
-  # … implement #get, #set, etc.
+  # … implement #read, #write, etc.
 end
 
 TypedCache::Backends.register(:redis, RedisBackend)
@@ -98,9 +98,9 @@ TypedCache::Backends.register(:redis, RedisBackend)
 class LogDecorator
   include TypedCache::Decorator
   def initialize(store) = @store = store
-  def set(key, value)
-    puts "[cache] SET #{key}"
-    @store.set(key, value)
+  def write(key, value)
+    puts "[cache] WRITE #{key}"
+    @store.write(key, value)
   end
   # delegate the rest …
 end
@@ -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 `read`, `write`, 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
@@ -174,7 +196,7 @@ store = TypedCache.builder
   .build.value
 ```
 
-Events are published to a topic like `typed_cache.<operation>` (e.g., `typed_cache.get`). The topic namespace can be configured.
+Events are published to a topic like `typed_cache.<operation>` (e.g., `typed_cache.write`). The topic namespace can be configured.
 
 Payload keys include: `:namespace, :key, :operation, :duration`, and `cache_hit`.
 
@@ -182,13 +204,13 @@ You can subscribe to these events like so:
 
 ```ruby
 # Example for ActiveSupport
-ActiveSupport::Notifications.subscribe("typed_cache.get") do |name, start, finish, id, payload|
+ActiveSupport::Notifications.subscribe("typed_cache.write") do |name, start, finish, id, payload|
 
 # Or you can subscribe via the store object itself
 instrumenter = store.instrumenter
-instrumenter.subscribe("get") do |event|
+instrumenter.subscribe("write") do |event|
   payload = event.payload
-  puts "Cache GET for key #{payload[:key]} took #{payload[:duration]}ms. Hit? #{payload[:cache_hit]}"
+  puts "Cache WRITE for key #{payload[:key]} took #{payload[:duration]}ms. Hit? #{payload[:cache_hit]}"
 end
 ```
 

data/examples.md

@@ -19,7 +19,7 @@ users_store = builder.build(TypedCache::Namespace.at("users")).value
 user_ref = users_store.ref("123")
 
 # Set a value
-user_ref.set({ id: 123, name: "Jane" })
+user_ref.write({ id: 123, name: "Jane" })
 ```
 
 ## Rails Integration
@@ -51,7 +51,7 @@ result = TypedCache.builder
 
 case result
 in TypedCache::Either::Right(store)
-  store.set(store.namespace.key("greeting"), "Hello")
+  store.write(store.namespace.key("greeting"), "Hello")
 in TypedCache::Either::Left(error)
   warn "Failed to set up cache: #{error.message}"
 end
@@ -70,26 +70,60 @@ 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").write({ 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
+### Read a value
 
-The `get` method returns an `Either[Error, Snapshot]`.
+The `read` method returns an `Either[Error, Snapshot]`.
 
 ```ruby
-result = ref.get
+result = ref.read
 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.
@@ -106,7 +140,7 @@ You can transform the value inside the cache reference without breaking the mona
 # user_ref holds { id: 1, name: "John" }
 name_ref = user_ref.map { |user| user[:name] }
 
-name_snapshot = name_ref.get.value # => Snapshot(value: "John", ...)
+name_snapshot = name_ref.read.value # => Snapshot(value: "John", ...)
 ```
 
 ### Chaining operations with `bind`
@@ -116,7 +150,7 @@ For more complex logic, you can use `bind` (or `flat_map`) to chain operations t
 ```ruby
 user_ref.bind do |user|
   if user.active?
-    posts_ref.set(user.posts)
+    posts_ref.write(user.posts)
   else
     TypedCache::Either.left(StandardError.new("User is not active"))
   end
@@ -144,12 +178,12 @@ class SimpleStore
     @data      = {}
   end
 
-  def get(key)
+  def read(key)
     value = @data[key]
     value ? TypedCache::Either.right(value) : TypedCache::Either.left(TypedCache::CacheMissError.new(key))
   end
 
-  def set(key, value)
+  def write(key, value)
     @data[key] = value
     TypedCache::Either.right(value)
   end
@@ -205,12 +239,12 @@ logging_cache = TypedCache.builder
   .build.value
 
 # Subscribe to an event
-logging_cache.instrumenter.subscribe("get")
+logging_cache.instrumenter.subscribe("write")
 
 # Operations will now be logged
-logging_cache.ref("test").set("hello")
-# => [CACHE] Starting: set for key test
-# => [CACHE] Finished: set for key test
+logging_cache.ref("test").write("hello")
+# => [CACHE] Starting: write for key test
+# => [CACHE] Finished: write for key test
 ```
 
 ## Thread Safety
@@ -223,7 +257,7 @@ shared_store = TypedCache.builder
   .build.value
 
 threads = 10.times.map do |i|
-  Thread.new { shared_store.set(shared_store.namespace.key(i.to_s), "data_") }
+  Thread.new { shared_store.write(shared_store.namespace.key(i.to_s), "data_") }
 end
 threads.each(&:join)
 ```
@@ -239,7 +273,7 @@ spec_store = TypedCache.builder
 
 RSpec.describe "cache" do
   it "stores data" do
-    result = spec_store.set(spec_store.namespace.key("id"), 1)
+    result = spec_store.write(spec_store.namespace.key("id"), 1)
     expect(result).to be_right
   end
 end

data/lib/typed_cache/backends/active_support.rb

@@ -19,25 +19,25 @@ module TypedCache
       end
 
       # @rbs override
-      #: (cache_key) -> either[Error, Snapshot[V]]
-      def get(key)
+      #: (cache_key, **top) -> either[Error, Snapshot[V]]
+      def read(key, **kwargs)
         cache_key_str = namespaced_key(key).to_s
-        raw_value = cache_store.read(cache_key_str, default_options)
+        raw_value = cache_store.read(cache_key_str, default_options.merge(**kwargs))
         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)
+      #: (cache_key, V, **top) -> either[Error, Snapshot[V]]
+      def write(key, value, **kwargs)
         cache_key_str = namespaced_key(key).to_s
-        success = cache_store.write(cache_key_str, value, default_options)
+        success = cache_store.write(cache_key_str, value, default_options.merge(**kwargs))
 
         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], **top) -> either[Error, Array[Snapshot[V]]]
+      def write_all(values, **kwargs)
+        results = cache_store.write_multi(values.map { |key, value| [namespaced_key(key).to_s, value] }.to_h, default_options.merge(**kwargs))
+        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], **top) -> either[Error, Array[Snapshot[V]]]
+      def read_all(keys, **kwargs)
+        results = cache_store.read_multi(*keys.map { |key| namespaced_key(key).to_s }, default_options.merge(**kwargs))
+        Either.right(results.map { |key, value| [key, Snapshot.cached(key, value)] }.to_h)
+      end
+
+      # @rbs override
+      #: (Array[cache_key], **top) { (CacheKey) -> V? } -> either[Error, Array[Snapshot[V]]]
+      def fetch_all(keys, **kwargs, &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.merge(**kwargs)) 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

@@ -68,8 +68,8 @@ module TypedCache
       end
 
       # @rbs override
-      #: (cache_key) -> either[Error, Snapshot[V]]
-      def get(key)
+      #: (cache_key, **top) -> either[Error, Snapshot[V]]
+      def read(key, **kwargs)
         key = namespaced_key(key)
         return Either.left(CacheMissError.new(key)) unless backing_store.key?(key)
 
@@ -80,17 +80,16 @@ 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)
+      #: (cache_key, V, expires_in: Integer, expires_at: Time, **top) -> either[Error, Snapshot[V]]
+      def write(key, value, expires_in: @ttl, expires_at: Clock.now + expires_in, **kwargs)
         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 +107,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))