typed_cache 0.1.1

data/lib/typed_cache/errors.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module TypedCache
+  # Base error class for TypedCache operations
+  class Error < StandardError; end
+
+  # Store operation errors (network, I/O, etc.)
+  class StoreError < Error
+    attr_reader :operation, :key, :original_error
+
+    # @rbs (Symbol, String, String, Exception?) -> void
+    def initialize(operation, key, message, original_error = nil)
+      super(message)
+      @operation = operation
+      @key = key
+      @original_error = original_error
+    end
+
+    # @rbs () -> String
+    def detailed_message
+      base = "#{operation.upcase} operation failed for key '#{key}': #{message}"
+      original_error ? "#{base} (#{original_error.class}: #{original_error.message})" : base
+    end
+
+    # @rbs () -> bool
+    def has_cause?
+      !@original_error.nil?
+    end
+  end
+
+  # Type safety violations
+  class TypeError < Error
+    attr_reader :expected_type, :actual_type, :value
+
+    # @rbs (String, String, untyped, String) -> void
+    def initialize(expected_type, actual_type, value, message)
+      super(message)
+      @expected_type = expected_type
+      @actual_type = actual_type
+      @value = value
+    end
+
+    # @rbs () -> String
+    def type_mismatch_message
+      "Expected #{expected_type}, got #{actual_type}"
+    end
+  end
+
+  # Cache miss (when expecting a value to exist)
+  class CacheMissError < Error
+    attr_reader :key
+
+    # @rbs (CacheKey) -> void
+    def initialize(key)
+      super("Cache miss for key: #{key}")
+      @key = key
+    end
+
+    # @rbs () -> bool
+    def cache_miss?
+      true
+    end
+  end
+end

data/lib/typed_cache/instrumentation.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require 'dry/configurable'
+
+module TypedCache
+  # Instrumentation hooks for ActiveSupport::Notifications integration
+  # All instrumentation is explicit and opt-in - no automatic behavior
+  module Instrumentation
+    class << self
+      # @rbs! type config = TypedCache::_TypedCacheInstrumentationConfig
+
+      # @rbs () -> config
+      def config
+        TypedCache.config.instrumentation
+      end
+
+      # Check if ActiveSupport::Notifications is available
+      # @rbs () -> bool
+      def notifications_available?
+        defined?(ActiveSupport::Notifications)
+      end
+
+      # Main instrumentation method
+      #: [T] (String, String, String, Hash[Symbol, untyped]) { -> T } -> T
+      def instrument(operation, namespace, key, payload = {})
+        return yield unless config.enabled && notifications_available?
+
+        event_name = "#{operation}.#{config.namespace}"
+        start_time = current_time
+
+        begin
+          result = yield
+
+          # Determine success and extract metadata
+          success, snapshot_data = extract_result_metadata(result)
+
+          final_payload = base_payload(namespace, key, start_time).merge(payload).merge({
+            success: success,
+            **snapshot_data,
+          })
+
+          ActiveSupport::Notifications.instrument(event_name, final_payload) do
+            # This block is called by subscribers who want the result
+            result
+          end
+
+          result
+        rescue => error
+          error_payload = base_payload(namespace, key, start_time).merge(payload).merge({
+            success: false,
+            error: error.class.name,
+            error_message: error.message,
+          })
+
+          ActiveSupport::Notifications.instrument(event_name, error_payload)
+          raise
+        end
+      end
+
+      private
+
+      # Cross-platform current time helper (uses Time.current when available)
+      #: -> Time
+      def current_time
+        if Time.respond_to?(:current)
+          Time.current
+        else
+          Time.now
+        end
+      end
+
+      # @rbs (String, String, Time) -> Hash[Symbol, untyped]
+      def base_payload(namespace, key, start_time)
+        {
+          namespace: namespace,
+          key: key,
+          duration: (current_time - start_time) * 1000.0, # milliseconds
+          store_type: nil, # Will be set by caller if available
+        }
+      end
+
+      # @rbs (Either[StandardError, Snapshot]) -> [bool, Hash[Symbol, untyped]]
+      def extract_result_metadata(result)
+        case result
+        when Either
+          if result.right?
+            snapshot = result.value
+            if snapshot.is_a?(Snapshot)
+              [true, {
+                cache_hit: snapshot.from_cache?,
+                cache_miss: !snapshot.from_cache?,
+                source: snapshot.source,
+                snapshot_age: snapshot.age,
+              },]
+            else
+              [true, { cache_hit: false, cache_miss: true }]
+            end
+          else
+            error_data = {
+              cache_hit: false,
+              cache_miss: true,
+              error_type: result.error.class.name,
+            }
+            [false, error_data]
+          end
+        else
+          [true, {}]
+        end
+      end
+    end
+  end
+end

data/lib/typed_cache/maybe.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module TypedCache
+  # @rbs!
+  #   type maybe[T] = (Nothing | Some[T]) & _Maybe[T]
+
+  module Maybe
+    include Kernel
+
+    class << self
+      #: [V](V) -> maybe[V]
+      def some(value) = Some.new(value)
+      #: -> maybe[bot]
+      def none = Nothing.new
+
+      #: [V](V? | maybe[V]) -> maybe[V]
+      def wrap(value)
+        case value
+        when Nothing, Some then value
+        when NilClass then Nothing.new
+        else
+          Some.new(value)
+        end
+      end
+
+      alias [] some
+    end
+  end
+
+  # @rbs!
+  #   interface _Maybe[out V]
+  #     def some?: -> bool
+  #     def nothing?: -> bool
+  #     def map: [T] () { (V) -> T } -> maybe[T]
+  #     def bind: [T] () { (V) -> maybe[T] } -> maybe[T]
+  #     alias flat_map bind
+  #   end
+
+  # @rbs generic out V
+  class Some
+    # @rbs! include _Maybe[V]
+
+    attr_reader :value #: V
+
+    #: (V) -> void
+    def initialize(value)
+      @value = value
+    end
+
+    # @rbs override
+    #: -> TrueClass
+    def some? = true
+    # @rbs override
+    #: -> FalseClass
+    def nothing? = false
+
+    # @rbs override
+    #: [T] () { (V) -> T } -> maybe[T]
+    def map(&) = Some.new(yield(value))
+
+    # @rbs override
+    #: [T] () { (V) -> maybe[T] } -> maybe[T]
+    def bind(&) = yield(value)
+
+    alias flat_map bind
+
+    #: (Array[top]) -> ({ value: V })
+    def deconstruct_keys(keys)
+      { value: }
+    end
+  end
+
+  class Nothing
+    # @rbs! include _Maybe[bot]
+
+    # @rbs override
+    #: -> FalseClass
+    def some? = false
+    # @rbs override
+    #: -> TrueClass
+    def nothing? = true
+
+    # @rbs override
+    #: [T] () { (V) -> T } -> maybe[T]
+    def map(&) = self
+
+    # @rbs override
+    #: [T] () { (V) -> maybe[T] } -> maybe[T]
+    def bind(&) = self
+    alias flat_map bind
+  end
+end

data/lib/typed_cache/namespace.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+module TypedCache
+  # Provides a type-safe, composable namespace abstraction for cache keys.
+  #
+  # The Namespace class allows you to create hierarchical namespaces for cache keys,
+  # ensuring that keys are properly scoped and collisions are avoided. Each Namespace
+  # instance can generate cache keys (via #key), create nested namespaces (via #nested),
+  # and traverse to parent namespaces (via #parent_namespace).
+  #
+  # Example:
+  #   ns = TypedCache::Namespace.at("users")
+  #   ns.key("123") # => #<TypedCache::CacheKey namespace=users key=123>
+  #   ns2 = ns.nested("sessions")
+  #   ns2.key("abc") # => #<TypedCache::CacheKey namespace=users:sessions key=abc>
+  #
+  # Namespaces are composable and immutable. The key factory can be customized for advanced use cases.
+  class Namespace
+    class << self
+      # Returns a new Namespace instance rooted at the given namespace string.
+      #
+      # @param namespace [String] the root namespace
+      # @return [Namespace] a new Namespace instance at the given root
+      #
+      # Example:
+      #   TypedCache::Namespace.at("users") # => #<TypedCache::Namespace namespace=users>
+      #
+      # The returned Namespace can be further nested or used to generate cache keys.
+      #
+      # @rbs (String) -> Namespace
+      def at(namespace)
+        root.nested(namespace)
+      end
+
+      # Returns the root Namespace instance (with an empty namespace).
+      #
+      # @return [Namespace] the root Namespace
+      #
+      # Example:
+      #   TypedCache::Namespace.root # => #<TypedCache::Namespace namespace=>
+      #
+      # The root namespace is useful as a starting point for building nested namespaces.
+      #
+      # @rbs () -> Namespace
+      def root
+        new(TypedCache.config.default_namespace) { |ns, key| CacheKey.new(ns, key) }
+      end
+    end
+
+    # Initializes a new Namespace instance with the given namespace string and key factory.
+    #
+    # @param namespace [String] the namespace string for this instance
+    # @param key_factory [Proc] a block that creates CacheKey instances from key strings
+    # @yield [key] the key string to create a CacheKey from
+    # @yieldreturn [CacheKey] the created cache key
+    #
+    # Example:
+    #   Namespace.new("users") { |key| CacheKey.new("users", key) }
+    #
+    # @rbs (String) { (Namespace, String) -> CacheKey } -> void
+    def initialize(namespace, &key_factory)
+      @namespace = namespace
+      @key_factory = key_factory
+    end
+
+    # Creates a nested namespace by appending the given namespace to the current one.
+    #
+    # @param namespace [String] the namespace to append
+    # @param key_factory [Proc, nil] optional custom key factory for the nested namespace
+    # @return [Namespace] a new Namespace instance with the combined namespace
+    #
+    # Example:
+    #   ns = Namespace.at("users")
+    #   ns.nested("sessions") # => #<TypedCache::Namespace namespace=users:sessions>
+    #
+    # If no key_factory is provided, the parent's key factory is inherited.
+    #
+    # @rbs (String) ?{ (Namespace, String) -> CacheKey } -> Namespace
+    def nested(namespace, &key_factory)
+      key_factory ||= @key_factory
+
+      self.class.new("#{@namespace}:#{namespace}", &key_factory)
+    end
+
+    # Returns the parent namespace by removing the last namespace segment.
+    #
+    # @return [Namespace] the parent namespace, or self if already at root
+    #
+    # Example:
+    #   ns = Namespace.at("users:sessions")
+    #   ns.parent_namespace # => #<TypedCache::Namespace namespace=users>
+    #
+    # For root namespaces (empty string), returns self.
+    #
+    # @rbs () -> Namespace
+    def parent_namespace
+      return self if @namespace.empty?
+
+      case pathsep_idx = @namespace.rindex(':')
+      when nil
+        self.class.root
+      else
+        self.class.new(@namespace[...pathsep_idx])
+      end
+    end
+
+    # Creates a cache key using the namespace's key factory.
+    #
+    # @param key [String] the key string to create a cache key from
+    # @return [CacheKey] the created cache key
+    #
+    # Example:
+    #   ns = Namespace.at("users")
+    #   ns.key("123") # => #<TypedCache::CacheKey namespace=users key=123>
+    #
+    # @rbs (String) -> CacheKey
+    def key(key)
+      @key_factory.call(self, key)
+    end
+
+    # @rbs () -> bool
+    def root? = @namespace.empty?
+
+    # Returns the namespace string representation.
+    #
+    # @return [String] the namespace string
+    #
+    # Example:
+    #   ns = Namespace.at("users:sessions")
+    #   ns.to_s # => "users:sessions"
+    #
+    # @rbs () -> String
+    def to_s
+      @namespace
+    end
+
+    # Returns a string representation of the Namespace instance for debugging.
+    #
+    # @return [String] a debug-friendly string representation
+    #
+    # Example:
+    #   ns = Namespace.at("users")
+    #   ns.inspect # => "#<TypedCache::Namespace namespace=users>"
+    #
+    # @rbs () -> String
+    def inspect
+      "#<#{self.class} #{@namespace}>"
+    end
+
+    # @rbs () -> Integer
+    def hash
+      [@namespace].hash
+    end
+
+    # @rbs (Object) -> bool
+    def ==(other)
+      other.is_a?(self.class) && other.to_s == to_s
+    end
+
+    alias eql? ==
+  end
+end

data/lib/typed_cache/registry.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module TypedCache
+  # Generic registry for managing class-based factories
+  # @rbs generic T
+  class Registry
+    # @rbs (String, Hash[Symbol, Class[T]]) -> void
+    def initialize(name, defaults = {})
+      @name = name
+      @registry = defaults.dup
+    end
+
+    # @rbs (Symbol, *untyped, **untyped) -> either[Error, T]
+    def resolve(key, *, **, &)
+      klass = @registry[key]
+      return Either.left(ArgumentError.new("Unknown #{@name}: #{key}")) unless klass
+
+      Either.right(klass.new(*, **))
+    rescue => e
+      Either.left(StoreError.new(
+        :"#{@name}_creation",
+        key.to_s,
+        "Failed to create #{@name} '#{key}': #{e.message}",
+        e,
+      ))
+    end
+
+    # @rbs (Symbol) -> maybe[Class[T]]
+    def find(key)
+      klass = @registry[key]
+      return Maybe.none unless klass
+
+      Maybe.some(klass)
+    end
+
+    # @rbs (Symbol, Class[T]) -> either[Error, void]
+    def register(key, klass)
+      return Either.left(ArgumentError.new("#{@name.capitalize} name cannot be nil")) if key.nil?
+      return Either.left(ArgumentError.new("#{@name.capitalize} class cannot be nil")) if klass.nil?
+
+      @registry[key] = klass
+      Either.right(nil)
+    end
+
+    # @rbs () -> Array[Symbol]
+    def available
+      @registry.keys
+    end
+
+    # @rbs (Symbol) -> bool
+    def registered?(key)
+      @registry.key?(key)
+    end
+  end
+end

data/lib/typed_cache/snapshot.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module TypedCache
+  # Immutable snapshot of a cached value with metadata about its source and age
+  # @rbs generic V
+  class Snapshot
+    attr_reader :value #: V
+    attr_reader :retrieved_at #: Time
+    attr_reader :source #: Symbol
+
+    #: (V, source: Symbol, retrieved_at: Time) -> void
+    def initialize(value, source:, retrieved_at: Time.now)
+      @value = value
+      @retrieved_at = retrieved_at
+      @source = source
+    end
+
+    # Age of the snapshot in seconds
+    #: -> Float
+    def age
+      Time.now - retrieved_at
+    end
+
+    # Whether this value came from cache
+    #: -> bool
+    def from_cache?
+      source == :cache
+    end
+
+    # Whether this value was freshly computed
+    #: -> bool
+    def computed?
+      source == :computed
+    end
+
+    # Whether this value was updated
+    #: -> bool
+    def updated?
+      source == :updated
+    end
+
+    # Map over the value while preserving snapshot metadata
+    #: [R] () { (V) -> R } -> Snapshot[R]
+    def map(&block)
+      new_value = yield(value)
+      Snapshot.new(new_value, source: source, retrieved_at: retrieved_at)
+    end
+
+    # Bind over the value with Either error handling
+    #: [R] () { (V) -> either[Error, R] } -> either[Error, Snapshot[R]]
+    def bind(&block)
+      result = yield(value)
+      result.map { |new_value| Snapshot.new(new_value, source: source, retrieved_at: retrieved_at) }
+    end
+
+    alias flat_map bind
+
+    class << self
+      # Creates a snapshot for a computed value
+      #: [V] (V) -> Snapshot[V]
+      def computed(value)
+        new(value, source: :computed)
+      end
+
+      # Creates a snapshot for an updated value
+      #: [V] (V) -> Snapshot[V]
+      def updated(value)
+        new(value, source: :updated)
+      end
+    end
+  end
+end

data/lib/typed_cache/store/instrumented.rb

@@ -0,0 +1,83 @@
+# 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 Store::Instrumented # rubocop:disable Style/ClassAndModuleChildren
+    include Decorator #[V]
+
+    extend Forwardable
+
+    attr_reader :store #: TypedCache::Store[V]
+
+    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
+
+          Instrumentation.instrument(operation, namespace, key || 'n/a', store_type: store_type) do
+            send(:"#{method_name}_without_instrumentation", *args, **kwargs, &block)
+          end
+        end
+
+        alias_method(:"#{method_name}_without_instrumentation", method_name)
+        alias_method(method_name, :"#{method_name}_with_instrumentation")
+      end
+    end
+
+    #: (TypedCache::Store[V]) -> void
+    def initialize(store)
+      @store = store
+    end
+
+    # @rbs override
+    #: -> String
+    def namespace
+      store.namespace
+    end
+
+    # @rbs override
+    #: -> String
+    def store_type
+      # Use polymorphism - delegate to the wrapped store
+      "instrumented(#{store.store_type})"
+    end
+
+    # @rbs override
+    #: (cache_key) -> either[Error, 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
+    end
+
+    def method_missing(method_name, *args, &block)
+      if store.respond_to?(method_name)
+        store.send(method_name, *args, &block)
+      else
+        super
+      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 }
+    instrument(:delete) { |key, *_| key }
+    instrument(:fetch)  { |key, *_| key }
+    instrument(:key?)   { |key, *_| key }
+    instrument(:clear)  { 'all' }
+  end
+end