typed_cache 0.1.1 → 0.3.0

data/lib/typed_cache/cache_builder.rb

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

data/lib/typed_cache/cache_key.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require 'forwardable'
+require_relative 'namespace'
+
 module TypedCache
   class CacheKey
     extend Forwardable
@@ -20,7 +23,7 @@ module TypedCache
 
     # @rbs () -> String
     def to_s
-      "#{@namespace}:#{@key}"
+      [@namespace.to_s, @key].join(delimiter)
     end
 
     alias cache_key to_s
@@ -41,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

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+require_relative 'cache_key'
+require_relative 'store'
+require_relative 'snapshot'
+
 module TypedCache
   # A monadic wrapper for cached values that provides safe access with rich error context.
   # All operations return Either[Error, Snapshot[V]] to provide detailed information about
@@ -18,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
@@ -44,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
@@ -71,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,
@@ -87,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 },
       )
@@ -97,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) },
       )
@@ -135,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/clock.rb

@@ -1,22 +1,39 @@
 # frozen_string_literal: true
 
+require 'dry/struct'
+require 'dry/types'
+
 module TypedCache
-  # A simple, testable wrapper around Time to provide a consistent way of
-  # getting the current time, respecting ActiveSupport's time zone when available.
-  class Clock
+  module Clock
+    # @rbs generic R
+    class Measured < Dry::Struct
+      # @rbs! def start: () -> Float
+      # @rbs! def end: () -> Float
+      # @rbs! def result: () -> [R]
+
+      attribute :start, Dry.Types::Float
+      attribute :end, Dry.Types::Float
+      attribute :result, Dry.Types.Instance(Object) #: [R]
+
+      # @rbs! def initialize: (start: Float, end: Float, result: [R]) -> void
+
+      #: -> Float
+      def duration
+        self.end - start
+      end
+    end
+
     class << self
-      # Retrieves the current time. If ActiveSupport's `Time.current` is
-      # available, it will be used to respect the configured timezone. Otherwise,
-      # it falls back to the system's `Time.now`.
-      #
-      # @return [Time] The current time.
+      # @rbs [R]() { () -> R } -> Measured[R]
+      def measure(&)
+        start = now
+        result = yield
+        Measured.new(start:, end: now, result:)
+      end
+
       # @rbs () -> Time
-      def moment
-        if Time.respond_to?(:current)
-          Time.current
-        else
-          Time.now
-        end
+      def now
+        Time.now
       end
     end
   end

data/lib/typed_cache/decorator.rb

@@ -1,12 +1,37 @@
 # frozen_string_literal: true
 
+require 'forwardable'
+
 module TypedCache
   # Marker mixin for cache store decorators. A decorator behaves exactly like a
   # Store but must accept another Store instance in its constructor.
   # @rbs generic V
   module Decorator
+    extend Forwardable
+
     include Store #[V]
     # @rbs! include Store::_Store[V]
     # @rbs! include Store::_Decorator[V]
+
+    # @rbs!
+    #  def store: -> Store[V]
+
+    Store.instance_methods(false).each do |method_name|
+      def_delegator :store, method_name
+    end
+
+    # @rbs override
+    #: (cache_key) -> either[Error, CacheRef[V]]
+    def ref(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

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module TypedCache
+  # Decorator that adds instrumentation to any Store implementation
+  # This decorator can wrap any store to add ActiveSupport::Notifications
+  # @rbs generic V
+  class Decorators::Instrumented # rubocop:disable Style/ClassAndModuleChildren
+    include Decorator #[V]
+
+    extend Forwardable
+
+    attr_reader :store #: TypedCache::Store[V]
+    attr_reader :instrumenter #: Instrumenter
+
+    class << self
+      private
+
+      # @rbs (Symbol, ?operation: String) ?{ (*untyped, **untyped) -> String } -> void
+      def instrument(method_name, operation: method_name.to_s, &key_selector)
+        key_selector ||= ->(*_args, **_kwargs, &_block) { 'n/a' }
+        alias_prefix = method_name.to_s.delete('?!')
+
+        define_method(:"#{alias_prefix}_instrumentation_key", &key_selector)
+
+        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
+
+        alias_method(:"#{alias_prefix}_without_instrumentation", method_name)
+        alias_method(method_name, :"#{alias_prefix}_with_instrumentation")
+      end
+    end
+
+    #: (TypedCache::Store[V], instrumenter: Instrumenter) -> void
+    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
+    #: -> 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
+    end
+
+    def method_missing(method_name, *args, &block)
+      if store.respond_to?(method_name)
+        store.send(method_name, *args, &block)
+      else
+        super
+      end
+    end
+
+    # 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(:delete) { |key, *_| key }
+    instrument(:fetch)  { |key, *_| key }
+    instrument(:fetch_all) { |keys, *_| keys.map(&:to_s).join('_') }
+    instrument(:key?)   { |key, *_| key }
+    instrument(:clear)  { 'all' }
+  end
+end

data/lib/typed_cache/decorators.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'typed_cache/registry'
+
 module TypedCache
   # Holds store decorators (e.g., instrumentation wrappers) that can be composed
   # by the CacheBuilder. Decorators must conform to the same API as the wrapped
@@ -14,20 +16,22 @@ module TypedCache
   #              .build.value
   #
   module Decorators
+    autoload :Instrumented, 'typed_cache/decorators/instrumented'
+
+    # @api private
     # Default decorator set – starts with instrumentation only, but this registry
     # lets end-users register their own via `Decorators.register`.
     REGISTRY = Registry.new('decorator', {
-      instrumented: Store::Instrumented,
+      instrumented: Instrumented,
     }).freeze
 
-    private_constant :REGISTRY
-
     class << self
       extend Forwardable
 
       # Delegate common registry helpers
       delegate [:resolve, :register, :available, :registered?] => :registry
 
+      # @api private
       # @rbs () -> Registry[Store[untyped]]
       def registry = REGISTRY
     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/errors.rb

@@ -2,7 +2,13 @@
 
 module TypedCache
   # Base error class for TypedCache operations
-  class Error < StandardError; end
+  class Error < StandardError
+    # @rbs (*untyped) -> void
+    def initialize(*args)
+      super(*args)
+      set_backtrace(caller(2))
+    end
+  end
 
   # Store operation errors (network, I/O, etc.)
   class StoreError < Error
@@ -14,6 +20,8 @@ module TypedCache
       @operation = operation
       @key = key
       @original_error = original_error
+
+      set_backtrace(original_error.backtrace) if original_error
     end
 
     # @rbs () -> String

data/lib/typed_cache/instrumenter.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module TypedCache
+  # Instrumenter for cache operations
+  module Instrumenter
+    # @rbs! type event = Dry::Events::Event | ActiveSupport::Notifications::Event
+
+    # @rbs [R](String, String, **untyped) { -> R } -> R
+    def instrument(event_name, key, **payload, &)
+      raise NotImplementedError, "#{self.class} must implement #instrument"
+    end
+
+    # @rbs (String, **untyped) { (event) -> void } -> void
+    def subscribe(event_name, **filters, &block)
+      raise NotImplementedError, "#{self.class} must implement #subscribe"
+    end
+
+    #: -> String
+    def namespace
+      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 (String) -> String
+    def event_name(operation)
+      "#{namespace}.#{operation}"
+    end
+
+    # @rbs () -> TypedCache::_TypedCacheInstrumentationConfig
+    def config
+      TypedCache.config.instrumentation
+    end
+  end
+end

data/lib/typed_cache/instrumenters/active_support.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require 'active_support/notifications'
+
+module TypedCache
+  module Instrumenters
+    # Instrumenter for ActiveSupport::Notifications
+    class ActiveSupport
+      include Instrumenter
+      include Mixins::NamespacedSingleton
+
+      # @rbs override
+      #: [R] (String, String, Hash[Symbol, untyped]) { -> R } -> R
+      def instrument(operation, key, **payload, &block)
+        return yield unless enabled?
+
+        payload = build_payload(operation, key, **payload)
+        ::ActiveSupport::Notifications.instrument(event_name(operation), **payload, &block)
+      end
+
+      # @rbs override
+      # @rbs (String, **top) { (event) -> void } -> void
+      def subscribe(operation, **filters, &block)
+        ::ActiveSupport::Notifications.monotonic_subscribe(event_name(operation), &block)
+      end
+    end
+  end
+end