typed_cache 0.3.1 → 0.4.0.pre.1

data/lib/typed_cache/cache_builder.rb

@@ -13,117 +13,202 @@ require 'dry/struct'
 require 'dry/types'
 
 module TypedCache
-  class CacheBuilder
-    # @rbs! type config = TypedCache::typed_cache_config
+  # @rbs!
+  #  interface _CacheBuilder
+  #    def build(namespace: Namespace) -> either[Error, Store[untyped]]
+  #    def build!(namespace: Namespace) -> Store[untyped]
+  #    def build_backend -> either[Error, Backend[untyped]]
+  #    def build_backend! -> Backend[untyped]
+  #  end
+
+  # @rbs!
+  #  interface _CacheDefinition
+  #    def with_backend(Symbol, *untyped, **untyped) -> (_CacheDefinition & _CacheBuilder)
+  #    def with_decorator(Symbol, **untyped) -> self
+  #    def with_instrumentation(Symbol) -> self
+  #  end
+
+  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
+
+  class CacheDefinition
+    # @rbs! include _CacheDefinition
+
     # @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)
+    attr_reader :backend_config #: BackendConfig?
+    attr_reader :decorator_configs #: Array[DecoratorConfig]
+    attr_reader :instrumenter_source #: instrumenter_source
+
+    # @rbs (?BackendConfig?, ?Array[DecoratorConfig], ?instrumenter_source) -> void
+    def initialize(backend_config = nil, decorator_configs = [], instrumenter_source = nil)
+      @backend_config = backend_config
+      @decorator_configs = decorator_configs
+      @instrumenter_source = instrumenter_source
+    end
+
+    # @rbs override
+    # @rbs (Symbol, *untyped, **untyped) -> self
+    def with_backend(name, *args, **options)
+      self.class.new(BackendConfig.new(name:, args:, options:), @decorator_configs)
+    end
+
+    # @rbs override
+    # @rbs (Symbol, **untyped) -> self
+    def with_decorator(name, **options)
+      self.class.new(@backend_config, @decorator_configs + [DecoratorConfig.new(name:, options:)])
     end
 
-    class DecoratorConfig < Dry::Struct
-      attribute :name, Dry.Types::Symbol
-      attribute :options, Dry.Types::Hash.map(Dry.Types::Symbol, Dry.Types::Any)
+    # @rbs override
+    # @rbs (instrumenter_source) -> self
+    def with_instrumentation(source = :default)
+      self.class.new(@backend_config, @decorator_configs, source)
     end
+  end
+
+  class CacheBuilder
+    # @rbs! include _CacheBuilder
+    # @rbs! include _CacheDefinition
 
-    # @rbs (config, Registry[backend[untyped]], Registry[decorator[untyped]]) -> void
-    def initialize(config, backend_registry = Backends, decorator_registry = Decorators)
-      @config = config
+    # @rbs (?_CacheDefinition, ?Registry[backend[untyped]], ?Registry[decorator[untyped]]) -> void
+    def initialize(cache_definition = CacheDefinition.new, backend_registry = Backends, decorator_registry = Decorators)
       @backend_registry = backend_registry
       @decorator_registry = decorator_registry
 
-      @backend_config = nil
-      @decorator_configs = []
+      @cache_definition = cache_definition
     end
 
-    # Builds the cache - the only method that can fail
-    # @rbs (?Namespace) -> either[Error, Store[V]]
-    def build(namespace = Namespace.at(@config.instrumentation.namespace))
+    # Builds the cache using the given namespace, defaulting to the root namespace
+    # @rbs (?Namespace) -> either[Error, Store[untyped]]
+    def build(namespace = Namespace.root)
       validate_and_build(namespace)
     end
 
+    # @rbs (Namespace) -> Store[untyped]
+    def build!(namespace = Namespace.root)
+      build(namespace).right_or_raise!
+    end
+
+    # Constructs only a typed backend from the registry without a Store wrapper
+    # @rbs () -> either[Error, Backend[untyped]]
+    def build_backend
+      create_backend
+    end
+
+    # Constructs only a typed backend from the registry without a Store wrapper,
+    # raises an error if the backend cannot be constructed
+    #
+    # @rbs () -> Backend[untyped]
+    def build_backend!
+      create_backend.right_or_raise!
+    end
+
     # Familiar Ruby fluent interface - always succeeds
     # Invalid configurations are caught during build()
     # @rbs (Symbol, *untyped, **untyped) -> self
     def with_backend(name, *args, **options)
-      @backend_config = BackendConfig.new(name:, args:, options:)
-      self
+      self.class.new(
+        @cache_definition.with_backend(name, *args, **options),
+        @backend_registry,
+        @decorator_registry,
+      )
     end
 
     # Adds an arbitrary decorator by registry key
     # @rbs (Symbol) -> self
     def with_decorator(name, **options)
-      @decorator_configs << DecoratorConfig.new(name:, options:)
-      self
+      self.class.new(
+        @cache_definition.with_decorator(name, **options),
+        @backend_registry,
+        @decorator_registry,
+      )
     end
 
     # Adds instrumentation using the specified strategy.
     # @rbs (instrumenter_source) -> either[Error, self]
     def with_instrumentation(source = :default)
-      @instrumenter_source = source
-      self
+      self.class.new(
+        @cache_definition.with_instrumentation(source),
+        @backend_registry,
+        @decorator_registry,
+      )
     end
 
     private
 
     # @rbs (Namespace) -> either[Error, Store[V]]
     def validate_and_build(namespace)
-      create_store(namespace).bind do |store|
-        apply_decorators(store).bind do |decorated_store|
-          apply_instrumentation(decorated_store)
+      create_backend.bind do |backend|
+        apply_decorators(backend).bind do |decorated_backend|
+          apply_instrumentation(decorated_backend).bind do |instrumented_backend|
+            Either.right(Store.new(namespace, instrumented_backend))
+          end
         end
       end
     end
 
-    # @rbs (Namespace) -> either[Error, Store[V]]
-    def create_store(namespace)
-      return Either.left(ArgumentError.new('Backend not configured')) unless @backend_config
+    # @rbs (Namespace) -> either[Error, Backend[untyped]]
+    def create_backend
+      backend_config = @cache_definition.backend_config
+
+      return Either.left(ArgumentError.new('Backend not configured')) unless backend_config
 
       # Prepend namespace to the arguments for the backend constructor
-      @backend_registry.resolve(@backend_config.name, namespace, *@backend_config.args, **@backend_config.options)
+      @backend_registry.resolve(backend_config.name, *backend_config.args, **backend_config.options)
     end
 
-    # @rbs (Store[V]) -> either[Error, Store[V]]
-    def apply_decorators(store)
-      return Either.right(store) if @decorator_configs.empty?
+    # @rbs (Backend[untyped]) -> either[Error, Decorator[untyped]]
+    def apply_decorators(backend)
+      decorator_configs = @cache_definition.decorator_configs
+
+      return Either.right(backend) if decorator_configs.empty?
 
-      names = @decorator_configs.map(&: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_config.name, current_store, **decorator_config.options)
+      decorator_configs.reduce(Either.right(backend)) do |result, decorator_config|
+        result.bind do |current_backend|
+          @decorator_registry.resolve(decorator_config.name, current_backend, **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
+    # @rbs (Backend[untyped]) -> either[Error, Backend[untyped]]
+    def apply_instrumentation(backend)
+      instrumenter_source = @cache_definition.instrumenter_source
+
+      return Either.right(backend) unless instrumenter_source
 
       instrumenter =
-        case @instrumenter_source
+        case instrumenter_source
         when Symbol
-          Instrumenters.resolve(@instrumenter_source, namespace: @config.default_namespace)
+          Instrumenters.resolve(instrumenter_source)
         when Instrumenter
-          Either.right(@instrumenter_source)
+          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}",
+            instrumenter_source.class.name,
+            instrumenter_source,
+            "Invalid instrumenter source: #{instrumenter_source.inspect}",
           ))
         end
 
       instrumenter.bind do |i|
-        @decorator_registry.resolve(:instrumented, store, instrumenter: i)
+        @decorator_registry.resolve(:instrumented, backend, instrumenter: i)
       end
     end
   end

data/lib/typed_cache/cache_key.rb

@@ -30,7 +30,7 @@ module TypedCache
 
     # @rbs () -> String
     def inspect
-      "#<#{self.class} namespace=#{@namespace} key=#{@key}>"
+      "CacheKey(#{@namespace}:#{@key})"
     end
 
     # @rbs () -> Integer

data/lib/typed_cache/cache_ref.rb

@@ -21,7 +21,7 @@ module TypedCache
     end
 
     # Gets a value from the cache as a snapshot
-    #: -> either[Error, Snapshot[V]]
+    #: -> either[Error, Snapshot[maybe[V]]]
     def read
       store.read(key)
     end
@@ -33,14 +33,14 @@ module TypedCache
     end
 
     # Deletes the value from the cache and returns the deleted value as a snapshot
-    #: -> either[Error, Snapshot[V]]
+    #: -> either[Error, maybe[V]]
     def delete
       store.delete(key)
     end
 
     # Fetches a value from cache, computing and storing it if not found
     # The snapshot indicates whether the value came from cache or was computed
-    #: () { -> V } -> either[Error, Snapshot[V]]
+    #: () { -> V? } -> either[Error, Snapshot[maybe[V]]]
     def fetch(&block)
       store.fetch(key, &block)
     end
@@ -60,24 +60,26 @@ module TypedCache
     # Maps over the cached value if it exists, preserving snapshot metadata
     #: [R] () { (V) -> R } -> either[Error, Snapshot[R]]
     def map(&block)
-      read.map { |snapshot| snapshot.map(&block) }
+      read.map { |snapshot| snapshot.map { |mb| mb.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)
-      read.bind { |snapshot| snapshot.bind(&block) }
-    end
-
-    alias flat_map bind
-
     # Updates the cached value using the provided block
     # Returns the updated value as a snapshot with source=:updated
-    #: () { (V) -> V } -> either[Error, Snapshot[V]]
+    #: () { (V) -> V? } -> either[Error, Snapshot[maybe[V]]]
     def update(&block)
       read.bind do |snapshot|
-        new_value = yield(snapshot.value)
-        write(new_value)
+        new_value = snapshot.value.bind do |value|
+          new_value = yield(value)
+          Maybe.wrap(new_value)
+        end
+
+        if new_value.some?
+          write(new_value.value).map do |snapshot|
+            snapshot.map { new_value }
+          end
+        else
+          delete.map { snapshot }
+        end
       rescue => e
         Either.left(StoreError.new(
           :update,
@@ -88,28 +90,9 @@ module TypedCache
       end
     end
 
-    # Returns the cached value or a default if the cache is empty/errored
-    #: (V) -> V
-    def value_or(default)
-      read.fold(
-        ->(_error) { default },
-        ->(snapshot) { snapshot.value },
-      )
-    end
-
-    # Returns a Maybe containing the cached value, or None if not present
-    # This provides a more functional approach than value_or
-    #: -> maybe[V]
-    def value_maybe
-      read.fold(
-        ->(_error) { Maybe.none },
-        ->(snapshot) { Maybe.some(snapshot.value) },
-      )
-    end
-
     # Computes and caches a value if the cache is currently empty
     # Returns existing snapshot if present, computed snapshot if cache miss, error otherwise
-    #: () { -> V } -> either[Error, Snapshot[V]]
+    #: () { -> V? } -> either[Error, Snapshot[maybe[V]]]
     def compute_if_absent(&block)
       fetch(&block).fold(
         ->(error) {
@@ -124,26 +107,6 @@ module TypedCache
       )
     end
 
-    # Creates a new CacheRef with the same store but different key
-    #: [R] (String) -> CacheRef[R]
-    def with_key(new_key)
-      CacheRef.new(store, store.namespace.key(new_key))
-    end
-
-    # Creates a scoped CacheRef by appending to the current key path
-    #: [R] (String) -> CacheRef[R]
-    def scope(scope_key)
-      new_namespace = store.namespace.nested(key.key)
-      new_store = store.with_namespace(new_namespace)
-      CacheRef.new(new_store, new_namespace.key(scope_key))
-    end
-
-    # Pattern matching support for Either[Error, Snapshot[V]] results
-    #: [R] (^(Error) -> R, ^(Snapshot[V]) -> R) -> R
-    def 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)
@@ -155,5 +118,11 @@ module TypedCache
     def with(&block)
       read.map { |snapshot| yield(snapshot.value) }
     end
+
+    # @rbs () -> String
+    def to_s = "CacheRef(#{key} from #{store.namespace})"
+
+    # @rbs () -> String
+    def inspect = "CacheRef(#{key}, #{store.inspect})"
   end
 end

data/lib/typed_cache/decorator.rb

@@ -9,21 +9,21 @@ module TypedCache
   module Decorator
     extend Forwardable
 
-    include Store #[V]
-    # @rbs! include Store::_Store[V]
-    # @rbs! include Store::_Decorator[V]
-
     # @rbs!
-    #  def store: -> Store[V]
+    #   interface _Decorator[V]
+    #     def initialize: (Backend[V]) -> void
+    #   end
 
-    Store.instance_methods(false).each do |method_name|
-      def_delegator :store, method_name
-    end
+    include Backend #[V]
+    # @rbs! include Backend::_Backend[V]
+    # @rbs! include _Decorator[V]
 
     # @rbs override
-    #: (cache_key) -> either[Error, CacheRef[V]]
-    def ref(key)
-      CacheRef.new(self, namespaced_key(key))
+    # @rbs () -> Backend[V]
+    def backend = raise NotImplementedError, "#{self.class} must implement #backend"
+
+    Backend.instance_methods(false).each do |method_name|
+      def_delegator :backend, method_name
     end
 
     # @rbs override
@@ -31,7 +31,17 @@ module TypedCache
     def initialize_copy(other)
       super
 
-      @store = other.store.clone
+      @backend = other.backend.clone
     end
+
+    # @rbs override
+    # @rbs () -> String
+    def to_s = "#{self.class.name}(#{backend})"
+
+    # @rbs override
+    # @rbs () -> String
+    def inspect = "Decorator(#{self.class.name}, #{backend.inspect})"
   end
+
+  # @rbs! type decorator[V] = Decorator::_Decorator[V] & Backend[V]
 end

data/lib/typed_cache/decorators/instrumented.rb

@@ -9,7 +9,7 @@ module TypedCache
 
     extend Forwardable
 
-    attr_reader :store #: TypedCache::Store[V]
+    attr_reader :backend #: Backend[V]
     attr_reader :instrumenter #: Instrumenter
 
     class << self
@@ -27,7 +27,7 @@ module TypedCache
             return #{alias_prefix}_without_instrumentation(...) if @in_instrumentation
 
             key = #{alias_prefix}_instrumentation_key(...)
-            instrumenter.instrument(:"#{operation}", key, store_type: store_type) do
+            instrumenter.instrument(:"#{operation}", key) do
               @in_instrumentation = true
 
               #{alias_prefix}_without_instrumentation(...)
@@ -42,9 +42,9 @@ module TypedCache
       end
     end
 
-    #: (TypedCache::Store[V], instrumenter: Instrumenter) -> void
-    def initialize(store, instrumenter:)
-      @store = store
+    #: (Backend[V], instrumenter: Instrumenter) -> void
+    def initialize(backend, instrumenter:)
+      @backend = backend
       @instrumenter = instrumenter
 
       # Avoid instrumenting the cache calls themselves, fetch_all may call fetch for example
@@ -58,21 +58,14 @@ module TypedCache
       @instrumenter = other.instrumenter
     end
 
-    # @rbs override
-    #: -> String
-    def store_type
-      # Use polymorphism - delegate to the wrapped store
-      "instrumented(#{store.store_type})"
-    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
+      backend.respond_to?(method_name, include_private) || super
     end
 
     def method_missing(method_name, *args, &block)
-      if store.respond_to?(method_name)
-        store.send(method_name, *args, &block)
+      if backend.respond_to?(method_name)
+        backend.send(method_name, *args, &block)
       else
         super
       end
@@ -80,12 +73,12 @@ module TypedCache
 
     # Instrument core operations with proper key extraction
     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(:read_multi) { |keys, *_| keys.map(&:to_s).join('_') }
+    instrument(:write) { |key, *_| key }
+    instrument(:write_multi) { |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(:fetch_multi) { |keys, *_| keys.map(&:to_s).join('_') }
     instrument(:key?)   { |key, *_| key }
     instrument(:clear)  { 'all' }
   end

data/lib/typed_cache/decorators.rb

@@ -23,7 +23,7 @@ module TypedCache
     # lets end-users register their own via `Decorators.register`.
     REGISTRY = Registry.new('decorator', {
       instrumented: Instrumented,
-    }).freeze
+    }).freeze #: Registry[Decorator]
 
     class << self
       extend Forwardable
@@ -31,6 +31,12 @@ module TypedCache
       # Delegate common registry helpers
       delegate [:resolve, :register, :available, :registered?] => :registry
 
+      # @rbs!
+      #   def resolve: (Symbol, *untyped, **untyped) -> either[Error, Decorator[untyped]]
+      #   def available: -> Array[Symbol]
+      #   def register: (Symbol, Class) -> either[Error, void]
+      #   def registered?: (Symbol) -> bool
+
       # @api private
       # @rbs () -> Registry[Store[untyped]]
       def registry = REGISTRY

data/lib/typed_cache/either.rb

@@ -86,6 +86,20 @@ module TypedCache
     def deconstruct_keys(keys)
       { error: }
     end
+
+    # @rbs (other: Object) -> bool
+    def ==(other)
+      other.is_a?(Left) && other.error == error
+    end
+
+    # @rbs () -> Integer
+    def hash = [Left, error].hash
+
+    # @rbs () -> String
+    def to_s = "Left(#{error})"
+
+    # @rbs () -> String
+    def inspect = "Left(#{error.inspect})"
   end
 
   # @rbs generic out R
@@ -139,5 +153,19 @@ module TypedCache
     def deconstruct_keys(keys)
       { value: }
     end
+
+    # @rbs (other: Object) -> bool
+    def ==(other)
+      other.is_a?(Right) && other.value == value
+    end
+
+    # @rbs () -> Integer
+    def hash = [Right, value].hash
+
+    # @rbs () -> String
+    def to_s = "Right(#{value})"
+
+    # @rbs () -> String
+    def inspect = "Right(#{value.inspect})"
   end
 end

data/lib/typed_cache/instrumenters.rb

@@ -19,7 +19,7 @@ module TypedCache
       rails: ActiveSupport,
       default: Null,
       null: Null,
-    }) #: Registry[Symbol, Class[Instrumenter]]
+    }) #: Registry[Instrumenter]
 
     class << self
       extend Forwardable
@@ -28,8 +28,12 @@ module TypedCache
       # @rbs () -> Registry[Symbol, Class[Instrumenter]]
       def registry = REGISTRY
 
+      # @rbs (Symbol, ?namespace: String, **untyped) -> either[Error, Instrumenter]
+      def resolve(name, namespace: TypedCache.config.instrumentation.namespace, **options)
+        registry.resolve(name, namespace: namespace, **options)
+      end
+
       # @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
 

data/lib/typed_cache/maybe.rb

@@ -78,6 +78,20 @@ module TypedCache
     def deconstruct_keys(keys)
       { value: }
     end
+
+    # @rbs (other: Object) -> bool
+    def ==(other)
+      other.is_a?(Some) && other.value == value
+    end
+
+    # @rbs () -> Integer
+    def hash = [Some, value].hash
+
+    # @rbs () -> String
+    def to_s = "Some(#{value})"
+
+    # @rbs () -> String
+    def inspect = "Some(#{value.inspect})"
   end
 
   class Nothing
@@ -106,5 +120,19 @@ module TypedCache
     # @rbs override
     #: -> V
     def value_or_raise! = raise TypedCache::TypeError, 'Nothing has no value'
+
+    # @rbs (other: Object) -> bool
+    def ==(other)
+      other.is_a?(Nothing)
+    end
+
+    # @rbs () -> Integer
+    def hash = [Nothing].hash
+
+    # @rbs () -> String
+    def to_s = 'Nothing'
+
+    # @rbs () -> String
+    def inspect = to_s
   end
 end

data/lib/typed_cache/namespace.rb

@@ -164,7 +164,7 @@ module TypedCache
     #
     # @rbs () -> String
     def inspect
-      "#<#{self.class} #{@namespace}>"
+      "Namespace(#{@namespace})"
     end
 
     # @rbs () -> Integer
@@ -177,8 +177,6 @@ module TypedCache
       other.is_a?(self.class) && other.to_s == to_s
     end
 
-    alias eql? ==
-
     private
 
     # @rbs (String) -> String

data/lib/typed_cache/snapshot.rb

@@ -57,6 +57,12 @@ module TypedCache
 
     alias flat_map bind
 
+    # @rbs () -> String
+    def to_s = "Snapshot(#{key} retrieved at #{retrieved_at} from #{source} with value #{value})"
+
+    # @rbs () -> String
+    def inspect = "Snapshot(#{key}, #{value.inspect}, #{source}, #{retrieved_at})"
+
     class << self
       # Creates a snapshot for a cached value
       #: [V] (CacheKey, V) -> Snapshot[V]