typed_cache 0.1.1 → 0.2.0

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,29 @@
 # 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, key)
+    end
   end
 end

data/lib/typed_cache/{store → decorators}/instrumented.rb

@@ -4,40 +4,42 @@ module TypedCache
   # Decorator that adds instrumentation to any Store implementation
   # This decorator can wrap any store to add ActiveSupport::Notifications
   # @rbs generic V
-  class Store::Instrumented # rubocop:disable Style/ClassAndModuleChildren
+  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)
-        define_method(:"#{method_name}_with_instrumentation") do |*args, **kwargs, &block|
-          key = key_selector.call(*args, **kwargs) if key_selector # rubocop:disable Performance/RedundantBlockCall
+        key_selector ||= ->(*_args, **_kwargs, &_block) { 'n/a' }
+        alias_prefix = method_name.to_s.delete('?!')
 
-          Instrumentation.instrument(operation, namespace, key || 'n/a', store_type: store_type) do
-            send(:"#{method_name}_without_instrumentation", *args, **kwargs, &block)
+        define_method(:"#{alias_prefix}_instrumentation_key", &key_selector)
+
+        class_eval(<<~RUBY, __FILE__, __LINE__ + 1)
+          def #{alias_prefix}_with_instrumentation(...)
+            key = #{alias_prefix}_instrumentation_key(...)
+            instrumenter.instrument(:"#{operation}", key, store_type: store_type) do
+              #{alias_prefix}_without_instrumentation(...)
+            end
           end
-        end
+        RUBY
 
-        alias_method(:"#{method_name}_without_instrumentation", method_name)
-        alias_method(method_name, :"#{method_name}_with_instrumentation")
+        alias_method(:"#{alias_prefix}_without_instrumentation", method_name)
+        alias_method(method_name, :"#{alias_prefix}_with_instrumentation")
       end
     end
 
-    #: (TypedCache::Store[V]) -> void
-    def initialize(store)
+    #: (TypedCache::Store[V], instrumenter: Instrumenter) -> void
+    def initialize(store, instrumenter:)
       @store = store
-    end
-
-    # @rbs override
-    #: -> String
-    def namespace
-      store.namespace
+      @instrumenter = instrumenter
     end
 
     # @rbs override
@@ -48,7 +50,7 @@ module TypedCache
     end
 
     # @rbs override
-    #: (cache_key) -> either[Error, CacheRef[V]]
+    # @rbs (key) -> CacheRef[V]
     def ref(key)
       CacheRef.new(self, key)
     end
@@ -66,12 +68,6 @@ module TypedCache
       end
     end
 
-    Store.instance_methods(false).each do |method_name|
-      next if instance_methods(false).include?(method_name)
-
-      def_delegator :store, method_name
-    end
-
     # Instrument core operations with proper key extraction
     instrument(:get)    { |key, *_| key }
     instrument(:set)    { |key, *_| key }

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/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 (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
+    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

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

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module TypedCache
+  module Instrumenters
+    module Mixins
+      module NamespacedSingleton
+        class << self
+          # @rbs () -> Array[Class[Instrumenter & NamespacedSingleton]]
+          def all = @all ||= [] # rubocop:disable ThreadSafety
+
+          # @rbs (Class[Instrumenter & NamespacedSingleton]) -> void
+          def included(base)
+            base.singleton_class.class_eval do
+              alias private_new new
+              private(:private_new)
+            end
+
+            base.extend(ClassMethods)
+
+            all << base
+          end
+        end
+
+        # @rbs override
+        # @rbs () -> String
+        def namespace
+          @namespace
+        end
+
+        # @rbs (String | Namespace) -> void
+        def initialize(namespace)
+          @namespace = namespace.to_s
+        end
+
+        module ClassMethods
+          # @rbs (String | Namespace) -> class
+          def new(namespace: TypedCache.config.instrumentation.namespace)
+            namespace_cache.compute_if_absent(namespace.to_s) { private_new(namespace) }
+          end
+
+          # @rbs (String) -> maybe[class]
+          def get(namespace)
+            namespace_cache.get(namespace.to_s)
+          end
+
+          # @rbs () -> Concurrent::Map[String, Class[Instrumenter & NamespacedSingleton]]
+          def namespace_cache = @namespace_cache ||= Concurrent::Map.new # rubocop:disable ThreadSafety
+        end
+      end
+    end
+  end
+end

data/lib/typed_cache/instrumenters/mixins.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module TypedCache
+  module Instrumenters
+    module Mixins
+    end
+  end
+end

data/lib/typed_cache/instrumenters/monitor.rb

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

data/lib/typed_cache/instrumenters/null.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+require 'singleton'
+
+module TypedCache
+  module Instrumenters
+    # A no-op implementation used when instrumentation is disabled.
+    # It fulfils the Instrumenter contract but simply yields.
+    class Null
+      include Instrumenter
+      include Mixins::NamespacedSingleton
+
+      # @rbs override
+      # [R] (String, String, **untyped) { -> R } -> R
+      def instrument(_operation, _key, **_payload)
+        yield
+      end
+
+      # @rbs override
+      # @rbs (String, **top) { (event) -> void } -> void
+      def subscribe(_event_name, **_filters, &_block)
+        # no-op
+      end
+    end
+  end
+end

data/lib/typed_cache/instrumenters.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require 'typed_cache/instrumenters/mixins'
+require 'typed_cache/instrumenters/mixins/namespaced_singleton'
+
+module TypedCache
+  module Instrumenters
+    autoload :ActiveSupport, 'typed_cache/instrumenters/active_support'
+    autoload :Monitor, 'typed_cache/instrumenters/monitor'
+    autoload :Null, 'typed_cache/instrumenters/null'
+
+    # @api private
+    # Registry mapping symbols to instrumenter classes. We can't reuse the generic
+    # Registry class directly because many instrumenters mix in `Singleton`,
+    # making `.new` inaccessible. Instead we implement a thin facade that
+    # returns either the singleton instance (preferred) or a fresh instance.
+    REGISTRY = Registry.new('instrumenter', {
+      dry: Monitor,
+      rails: ActiveSupport,
+      default: Null,
+      null: Null,
+    }) #: Registry[Symbol, Class[Instrumenter]]
+
+    class << self
+      extend Forwardable
+
+      # @api private
+      # @rbs () -> Registry[Symbol, Class[Instrumenter]]
+      def registry = REGISTRY
+
+      # @rbs! def resolve: (Symbol, **untyped) -> either[Error, Instrumenter]
+      # @rbs! def available: () -> Array[Symbol]
+      # @rbs! def registered?: (Symbol) -> Boolean
+
+      def_delegators :registry, :resolve, :available, :registered?
+    end
+  end
+end

data/lib/typed_cache/registry.rb

@@ -10,6 +10,17 @@ module TypedCache
       @registry = defaults.dup
     end
 
+    # @rbs (Registry[T]) -> Registry[T]
+    def initialize_copy(other)
+      super
+      @registry = other.registry.dup
+    end
+
+    # @rbs () -> void
+    def clear
+      @registry.clear
+    end
+
     # @rbs (Symbol, *untyped, **untyped) -> either[Error, T]
     def resolve(key, *, **, &)
       klass = @registry[key]
@@ -51,5 +62,9 @@ module TypedCache
     def registered?(key)
       @registry.key?(key)
     end
+
+    protected
+
+    attr_reader :registry #: Hash[Symbol, Class[T]]
   end
 end

data/lib/typed_cache/store.rb

@@ -98,6 +98,9 @@ module TypedCache
       end
     end
 
+    # @rbs () -> Instrumenter
+    def instrumenter = Instrumenters::Null.instance
+
     # Returns the namespace for this store (for instrumentation/debugging)
     # @rbs () -> Namespace
     def namespace

data/lib/typed_cache/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TypedCache
-  VERSION = '0.1.1'
+  VERSION = '0.2.0'
 end

data/lib/typed_cache.rb

@@ -1,18 +1,35 @@
 # frozen_string_literal: true
 
-require 'zeitwerk'
-require 'dry-configurable'
-require 'concurrent-ruby'
+require 'dry/configurable'
+require 'dry/struct'
+require 'dry/types'
 
-# Load core registry before Zeitwerk
-require_relative 'typed_cache/registry'
-require_relative 'typed_cache/errors'
+require 'typed_cache/either'
+require 'typed_cache/maybe'
 
-Zeitwerk::Loader.for_gem.setup
+require 'typed_cache/cache_key'
+require 'typed_cache/errors'
+require 'typed_cache/namespace'
+require 'typed_cache/registry'
+require 'typed_cache/clock'
+
+require 'typed_cache/store'
+require 'typed_cache/instrumenter'
+require 'typed_cache/backend'
+require 'typed_cache/decorator'
+
+require 'typed_cache/snapshot'
+require 'typed_cache/cache_ref'
+
+require 'typed_cache/cache_builder'
 
 module TypedCache
   extend Dry::Configurable
 
+  autoload :Backends, 'typed_cache/backends'
+  autoload :Decorators, 'typed_cache/decorators'
+  autoload :Instrumenters, 'typed_cache/instrumenters'
+
   # @rbs!
   #   interface _TypedCacheInstrumentationConfig
   #     def enabled: -> bool
@@ -33,6 +50,7 @@ module TypedCache
   setting :instrumentation do
     setting :enabled, default: false
     setting :namespace, default: 'typed_cache'
+    setting :instrumenter, default: :default
   end
 
   class << self
@@ -44,15 +62,13 @@ module TypedCache
 
     # @rbs! def config: -> _TypedCacheConfig
 
-    # @rbs () -> singleton(Instrumentation)
-    def instrumentation
-      Instrumentation
-    end
-
-    # @rbs () -> Registry[backend[untyped]]
+    # @rbs () -> singleton(Backends)
     def backends = Backends
 
-    # @rbs () -> Register[decorator[untyped]]
+    # @rbs () -> singleton(Decorators)
     def decorators = Decorators
+
+    # @rbs () -> singleton(Instrumenters)
+    def instrumenters = Instrumenters
   end
 end

data/sig/generated/typed_cache/backends.rbs

@@ -2,11 +2,13 @@
 
 module TypedCache
   module Backends
+    # @api private
     # Backend registry using composition
     REGISTRY: untyped
 
     extend Forwardable
 
+    # @api private
     # : -> Registry
     def self.registry: () -> Registry
 

data/sig/generated/typed_cache/cache_builder.rbs

@@ -4,6 +4,14 @@ module TypedCache
   class CacheBuilder
     type config = TypedCache::typed_cache_config
 
+    type instrumenter_source = :default | :dry | :rails | Instrumenter
+
+    class BackendConfig < Dry::Struct
+    end
+
+    class DecoratorConfig < Dry::Struct
+    end
+
     # @rbs (config, Registry[backend[untyped]], Registry[decorator[untyped]]) -> void
     def initialize: (config, Registry[backend[untyped]], Registry[decorator[untyped]]) -> void
 
@@ -20,8 +28,9 @@ module TypedCache
     # @rbs (Symbol) -> self
     def with_decorator: (Symbol) -> self
 
-    # @rbs () -> self
-    def with_instrumentation: () -> self
+    # Adds instrumentation using the specified strategy.
+    # @rbs (instrumenter_source) -> either[Error, self]
+    def with_instrumentation: (instrumenter_source) -> either[Error, self]
 
     private
 
@@ -33,5 +42,7 @@ module TypedCache
 
     # @rbs (Store[V]) -> either[Error, Store[V]]
     def apply_decorators: (Store[V]) -> either[Error, Store[V]]
+
+    def apply_instrumentation: (untyped store) -> untyped
   end
 end

data/sig/generated/typed_cache/clock.rbs

@@ -1,15 +1,25 @@
 # Generated from lib/typed_cache/clock.rb with RBS::Inline
 
 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
-    # 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.
+  module Clock
+    # @rbs generic R
+    class Measured[R] < Dry::Struct
+      def start: () -> Float
+
+      def end: () -> Float
+
+      def result: () -> [ R ]
+
+      def initialize: (start: Float, end: Float, result: [ R ]) -> void
+
+      # : -> Float
+      def duration: () -> Float
+    end
+
+    # @rbs [R]() { () -> R } -> Measured[R]
+    def self.measure: [R] () { () -> R } -> Measured[R]
+
     # @rbs () -> Time
-    def self.moment: () -> Time
+    def self.now: () -> Time
   end
 end

data/sig/generated/typed_cache/decorator.rbs

@@ -5,10 +5,18 @@ module TypedCache
   # Store but must accept another Store instance in its constructor.
   # @rbs generic V
   module Decorator[V]
+    extend Forwardable
+
     include Store[V]
 
     include Store::_Store[V]
 
     include Store::_Decorator[V]
+
+    def store: () -> Store[V]
+
+    # @rbs override
+    # : (cache_key) -> either[Error, CacheRef[V]]
+    def ref: ...
   end
 end