typed_cache 0.1.1 → 0.3.0

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

@@ -0,0 +1,55 @@
+# 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 () -> void
+          def clear_namespace_cache = namespace_cache.clear
+
+          # @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,39 @@
+# 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 register: (Symbol, Class[Instrumenter]) -> void
+      # @rbs! def resolve: (Symbol, **untyped) -> either[Error, Instrumenter]
+      # @rbs! def available: () -> Array[Symbol]
+      # @rbs! def registered?: (Symbol) -> Boolean
+
+      def_delegators :registry, :resolve, :available, :registered?, :register
+    end
+  end
+end

data/lib/typed_cache/maybe.rb

@@ -33,6 +33,8 @@ module TypedCache
   #     def nothing?: -> bool
   #     def map: [T] () { (V) -> T } -> maybe[T]
   #     def bind: [T] () { (V) -> maybe[T] } -> maybe[T]
+  #     def value_or: [T] (T) -> T
+  #     def value_or_raise!: -> V
   #     alias flat_map bind
   #   end
 
@@ -62,6 +64,14 @@ module TypedCache
     #: [T] () { (V) -> maybe[T] } -> maybe[T]
     def bind(&) = yield(value)
 
+    # @rbs override
+    #: [T] (T) -> T
+    def value_or(default) = value
+
+    # @rbs override
+    #: -> V
+    def value_or_raise! = value
+
     alias flat_map bind
 
     #: (Array[top]) -> ({ value: V })
@@ -88,5 +98,13 @@ module TypedCache
     #: [T] () { (V) -> maybe[T] } -> maybe[T]
     def bind(&) = self
     alias flat_map bind
+
+    # @rbs override
+    #: [T] (T) -> T
+    def value_or(default) = default
+
+    # @rbs override
+    #: -> V
+    def value_or_raise! = raise TypedCache::TypeError, 'Nothing has no value'
   end
 end

data/lib/typed_cache/namespace.rb

@@ -20,16 +20,17 @@ module TypedCache
       # Returns a new Namespace instance rooted at the given namespace string.
       #
       # @param namespace [String] the root namespace
+      # @param namespaces [Array<String>] additional namespaces to join
       # @return [Namespace] a new Namespace instance at the given root
       #
       # Example:
-      #   TypedCache::Namespace.at("users") # => #<TypedCache::Namespace namespace=users>
+      #   TypedCache::Namespace.at("users", "sessions") # => #<TypedCache::Namespace namespace=users:sessions>
       #
       # The returned Namespace can be further nested or used to generate cache keys.
       #
-      # @rbs (String) -> Namespace
-      def at(namespace)
-        root.nested(namespace)
+      # @rbs (String, *String) -> Namespace
+      def at(namespace, *namespaces)
+        root.join(namespace, *namespaces)
       end
 
       # Returns the root Namespace instance (with an empty namespace).
@@ -79,7 +80,26 @@ module TypedCache
     def nested(namespace, &key_factory)
       key_factory ||= @key_factory
 
-      self.class.new("#{@namespace}:#{namespace}", &key_factory)
+      self.class.new([@namespace, namespace].join(delimiter), &key_factory)
+    end
+
+    # Creates a new namespace by joining the current namespace with the given namespaces.
+    #
+    # @param namespaces [Array<String>] the namespaces to join
+    # @param key_factory [Proc, nil] optional custom key factory for the joined namespace
+    # @return [Namespace] a new Namespace instance with the combined namespace
+    #
+    # Example:
+    #   ns = Namespace.at("users")
+    #   ns.join("sessions", "admin") # => #<TypedCache::Namespace namespace=users:sessions:admin>
+    #
+    # If no key_factory is provided, the parent's key factory is inherited.
+    #
+    # @rbs (*String) ?{ (Namespace, String) -> CacheKey } -> Namespace
+    def join(*namespaces, &key_factory)
+      key_factory ||= @key_factory
+
+      self.class.new([@namespace, *namespaces].join(delimiter), &key_factory)
     end
 
     # Returns the parent namespace by removing the last namespace segment.
@@ -96,7 +116,7 @@ module TypedCache
     def parent_namespace
       return self if @namespace.empty?
 
-      case pathsep_idx = @namespace.rindex(':')
+      case pathsep_idx = @namespace.rindex(delimiter)
       when nil
         self.class.root
       else
@@ -158,5 +178,12 @@ module TypedCache
     end
 
     alias eql? ==
+
+    private
+
+    # @rbs (String) -> String
+    def delimiter
+      TypedCache.config.cache_delimiter
+    end
   end
 end

data/lib/typed_cache/railtie.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module TypedCache
+  class Railtie < ::Rails::Railtie
+    config.to_prepare do
+      # Set the default instrumenter to Rails
+      ::TypedCache.configure do |config|
+        config.instrumentation.instrumenter = :rails
+      end
+
+      # Register the ActiveSupport backend
+      ::TypedCache.backends.register(:active_support, ::TypedCache::Instrumenters::ActiveSupport)
+    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/snapshot.rb

@@ -4,12 +4,14 @@ module TypedCache
   # Immutable snapshot of a cached value with metadata about its source and age
   # @rbs generic V
   class Snapshot
+    attr_reader :key #: CacheKey
     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)
+    #: (CacheKey, V, source: Symbol, retrieved_at: Time) -> void
+    def initialize(key, value, source:, retrieved_at: Time.now)
+      @key = key
       @value = value
       @retrieved_at = retrieved_at
       @source = source
@@ -43,29 +45,35 @@ module TypedCache
     #: [R] () { (V) -> R } -> Snapshot[R]
     def map(&block)
       new_value = yield(value)
-      Snapshot.new(new_value, source: source, retrieved_at: retrieved_at)
+      Snapshot.new(key, 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) }
+      result.map { |new_value| Snapshot.new(key, new_value, source: source, retrieved_at: retrieved_at) }
     end
 
     alias flat_map bind
 
     class << self
+      # Creates a snapshot for a cached value
+      #: [V] (CacheKey, V) -> Snapshot[V]
+      def cached(key, value)
+        new(key, value, source: :cache)
+      end
+
       # Creates a snapshot for a computed value
-      #: [V] (V) -> Snapshot[V]
-      def computed(value)
-        new(value, source: :computed)
+      #: [V] (CacheKey, V) -> Snapshot[V]
+      def computed(key, value)
+        new(key, value, source: :computed)
       end
 
       # Creates a snapshot for an updated value
-      #: [V] (V) -> Snapshot[V]
-      def updated(value)
-        new(value, source: :updated)
+      #: [V] (CacheKey, V) -> Snapshot[V]
+      def updated(key, value)
+        new(key, value, source: :updated)
       end
     end
   end

data/lib/typed_cache/store.rb

@@ -17,13 +17,16 @@ module TypedCache
 
     # @rbs!
     #   interface _Store[V]
-    #     def get: (cache_key) -> either[Error, Snapshot[V]]
+    #     def read: (cache_key) -> either[Error, Snapshot[V]]
+    #     def read_all: (Array[cache_key]) -> either[Error, Array[Snapshot[V]]]
     #     def ref: (cache_key) -> CacheRef[V]
-    #     def set: (cache_key, V) -> either[Error, Snapshot[V]]
+    #     def write: (cache_key, V) -> either[Error, Snapshot[V]]
+    #     def write_all: (Hash[cache_key, V]) -> either[Error, Array[Snapshot[V]]]
     #     def delete: (cache_key) -> either[Error, Snapshot[V]]
     #     def key?: (cache_key) -> bool
     #     def clear: () -> maybe[Error]
-    #     def fetch: (cache_key) { () -> V } -> either[Error, Snapshot[V]]
+    #     def fetch: (cache_key) { () -> V? } -> either[Error, Snapshot[maybe[V]]]
+    #     def fetch_all: (Array[cache_key]) { (CacheKey) -> V? } -> either[Error, Array[Snapshot[V]]]
     #     def namespace: () -> Namespace
     #     def with_namespace: (Namespace) -> Store[V]
     #     def store_type: () -> String
@@ -43,8 +46,17 @@ module TypedCache
 
     # Retrieves a value from the cache
     # @rbs (cache_key) -> either[Error, Snapshot[V]]
-    def get(key)
-      Either.left(NotImplementedError.new("#{self.class} must implement #get"))
+    def read(key)
+      Either.left(NotImplementedError.new("#{self.class} must implement #read"))
+    end
+
+    # @rbs (Array[cache_key]) -> either[Error, Hash[cache_key, Snapshot[V]]]
+    def read_all(keys)
+      keys.map { |key| read(key) }.reduce(Either.right({})) do |acc, result|
+        acc.bind do |values|
+          result.map { |value| values.merge(value.key => value) }
+        end
+      end
     end
 
     # Retrieves a cache reference for a key
@@ -55,8 +67,17 @@ module TypedCache
 
     # Stores a value in the cache
     # @rbs (cache_key, V) -> either[Error, Snapshot[V]]
-    def set(key, value)
-      Either.left(NotImplementedError.new("#{self.class} must implement #set"))
+    def write(key, value)
+      Either.left(NotImplementedError.new("#{self.class} must implement #write"))
+    end
+
+    # @rbs (Hash[cache_key, V]) -> either[Error, Hash[cache_key, Snapshot[V]]]
+    def write_all(values)
+      values.map { |key, value| write(key, value) }.reduce(Either.right({})) do |acc, result|
+        acc.bind do |values|
+          result.map { |value| values.merge(value.key => value) }
+        end
+      end
     end
 
     # Removes a value from the cache, returning the removed value
@@ -78,26 +99,39 @@ module TypedCache
     end
 
     # Fetches a value from cache, computing and storing it if not found
-    # This is an atomic operation that combines get and set
+    # This is an atomic operation that combines read and write
     # @rbs (cache_key) { () -> V } -> either[Error, Snapshot[V]]
     def fetch(key, &block)
-      # Default implementation using get/set pattern
-      get_result = get(key)
-      return get_result if get_result.right?
+      # Default implementation using read/write pattern
+      read_result = read(key)
+      return read_result if read_result.right?
 
       # Only proceed if it's a cache miss
-      return get_result unless get_result.error.is_a?(CacheMissError)
+      return read_result unless read_result.error.is_a?(CacheMissError)
 
       # Compute and store new value
       begin
         computed_value = yield
-        set(key, computed_value)
-        Either.right(Snapshot.computed(computed_value))
+        write(key, computed_value)
+        Either.right(Snapshot.computed(key, computed_value))
       rescue => e
         Either.left(StoreError.new(:fetch, key, "Failed to compute value for key '#{key}': #{e.message}", e))
       end
     end
 
+    # @rbs (Array[cache_key]) { (CacheKey) -> V } -> either[Error, Array[Snapshot[V]]]
+    def fetch_all(keys, &block)
+      keys = keys.map { |key| namespaced_key(key) }
+      keys.reduce(Either.right([])) do |acc, key|
+        acc.bind do |values|
+          fetch(key) { yield(key) }.map { |value| values + [value] }
+        end
+      end
+    end
+
+    # @rbs () -> Instrumenter
+    def instrumenter = Instrumenters::Null.instance
+
     # Returns the namespace for this store (for instrumentation/debugging)
     # @rbs () -> Namespace
     def namespace
@@ -106,11 +140,12 @@ module TypedCache
 
     # Accepts a String segment or a fully-formed Namespace and returns a cloned
     # store scoped to that namespace.
-    # @rbs (Namespace | String) -> Store[V]
+    #: (Namespace | String | Array[String]) -> Store[V]
     def with_namespace(ns)
       new_namespace =
         case ns
         when Namespace then ns
+        when Array then namespace.join(*ns)
         else
           # treat as nested segment under the current namespace
           namespace.nested(ns.to_s)

data/lib/typed_cache/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module TypedCache
-  VERSION = '0.1.1'
+  VERSION = '0.3.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
@@ -22,6 +39,7 @@ module TypedCache
   # @rbs!
   #   interface _TypedCacheConfig
   #     def default_namespace: -> String
+  #     def cache_delimiter: -> String
   #     def instrumentation: -> _TypedCacheInstrumentationConfig
   #   end
 
@@ -29,10 +47,12 @@ module TypedCache
 
   # Configuration
   setting :default_namespace, default: 'typed_cache'
+  setting :cache_delimiter, default: ':'
 
   setting :instrumentation do
     setting :enabled, default: false
     setting :namespace, default: 'typed_cache'
+    setting :instrumenter, default: :default
   end
 
   class << self
@@ -44,15 +64,15 @@ 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
+
+require 'typed_cache/railtie' if defined?(Rails::Railtie)

data/rbi/typed_cache/backend.rbi

@@ -0,0 +1,9 @@
+# typed: strict
+
+module TypedCache
+  module Backend
+    extend T::Generic
+    include ::TypedCache::Store
+    CachedType = type_member
+  end
+end

data/rbi/typed_cache/backends/active_support.rbi

@@ -0,0 +1,13 @@
+# typed: strict
+
+module TypedCache
+  module Backends
+    module ActiveSupport
+      extend T::Generic
+
+      include ::TypedCache::Backend
+
+      CachedType = type_member
+    end
+  end
+end

data/rbi/typed_cache/backends/memory.rbi

@@ -0,0 +1,13 @@
+# typed: strict
+
+module TypedCache
+  module Backends
+    module Memory
+      extend T::Generic
+
+      include ::TypedCache::Backend
+
+      CachedType = type_member
+    end
+  end
+end

data/rbi/typed_cache/backends.rbi

@@ -0,0 +1,19 @@
+# typed: strict
+
+module TypedCache
+  module Backends
+    class << self
+      sig { params(name: Symbol, klass: T::Class[::TypedCache::Backend[T.anything]]).returns(T.self_type) }
+      def register(name, klass); end
+
+      sig { params(name: Symbol, args: T::Array[T.anything], options: T::Hash[Symbol, T.anything]).returns(T.self_type) }
+      def resolve(name, *args, **options); end
+
+      sig { returns(T::Array[T::Class[::TypedCache::Backend[T.anything]]]) }
+      def available; end
+
+      sig { params(name: Symbol).returns(T::Boolean) }
+      def registered?(name); end
+    end
+  end
+end

data/rbi/typed_cache/cache_builder.rbi

@@ -0,0 +1,23 @@
+# typed: strict
+
+module TypedCache
+  class CacheBuilder
+    Error = T.type_alias { TypedCache::Error }
+    Config = T.type_alias { ::TypedCache::Private::Configuration }
+    InstrumenterSource = T.type_alias { T.any(Symbol, ::TypedCache::Instrumenter) }
+
+    private_constant :Config, :Error, :InstrumenterSource
+
+    sig { params(namespace: ::TypedCache::Namespace).returns(::TypedCache::Either[Error, ::TypedCache::Store[T.anything]]) }
+    def build(namespace = T.unsafe(nil)); end
+
+    sig { params(name: Symbol, args: T.untyped, options: T::Hash[Symbol, T.anything]).returns(T.self_type) }
+    def with_backend(name, *args, **options); end
+
+    sig { params(name: Symbol, options: T::Hash[Symbol, T.anything]).returns(T.self_type) }
+    def with_decorator(name, **options); end
+
+    sig { params(source: InstrumenterSource).returns(T.self_type) }
+    def with_instrumentation(source = T.unsafe(nil)); end
+  end
+end