typed_cache 0.1.1 → 0.3.0

data/rbi/typed_cache.rbi

@@ -0,0 +1,49 @@
+# typed: strict
+
+module TypedCache
+  module Private
+    class Configuration < BasicObject
+      class Instrumentation < BasicObject
+        sig { returns(T::Boolean) }
+        attr_accessor :enabled
+
+        sig { returns(String) }
+        attr_accessor :namespace
+
+        sig { returns(Symbol) }
+        attr_accessor :instrumenter
+      end
+
+      sig { returns(String) }
+      attr_accessor :namespace
+
+      sig { returns(String) }
+      attr_accessor :cache_delimiter
+
+      sig { returns(::TypedCache::Private::Configuration::Instrumentation) }
+      def instrumentation; end
+    end
+  end
+
+  class << self
+    sig { params(block: T.proc.params(config: ::TypedCache::Private::Configuration).void).void }
+    def configure(&block); end
+
+    sig { returns(::TypedCache::Private::Configuration) }
+    def config; end
+
+    sig { returns(::TypedCache::CacheBuilder) }
+    def builder; end
+
+    sig { returns(T.class_of(::TypedCache::Backends)) }
+    def backends; end
+
+    sig { returns(T.class_of(::TypedCache::Decorators)) }
+    def decorators; end
+
+    sig { returns(T.class_of(::TypedCache::Instrumenters)) }
+    def instrumenters; end
+  end
+
+  private_constant :Backends, :Decorators, :Instrumenters
+end

data/sig/generated/typed_cache/backends/active_support.rbs

@@ -18,16 +18,28 @@ module TypedCache
 
       # @rbs override
       # : (cache_key) -> either[Error, Snapshot[V]]
-      def get: ...
+      def read: ...
 
       # @rbs override
       # : (cache_key, V) -> either[Error, Snapshot[V]]
-      def set: ...
+      def write: ...
+
+      # @rbs override
+      # : (Hash[cache_key, V]) -> either[Error, Array[Snapshot[V]]]
+      def write_all: ...
 
       # @rbs override
       # : (cache_key) -> either[Error, Snapshot[V]]
       def delete: ...
 
+      # @rbs override
+      # : (Array[cache_key]) -> either[Error, Array[Snapshot[V]]]
+      def read_all: ...
+
+      # @rbs override
+      # : (Array[cache_key]) { (CacheKey) -> V? } -> either[Error, Array[Snapshot[V]]]
+      def fetch_all: ...
+
       # @rbs override
       # : (cache_key) -> bool
       def key?: ...

data/sig/generated/typed_cache/backends/memory.rbs

@@ -55,11 +55,11 @@ module TypedCache
 
       # @rbs override
       # : (cache_key) -> either[Error, Snapshot[V]]
-      def get: ...
+      def read: ...
 
       # @rbs override
       # : (cache_key, V) -> either[Error, Snapshot[V]]
-      def set: ...
+      def write: ...
 
       # @rbs override
       # : (cache_key) -> either[Error, Snapshot[V]]

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/cache_key.rbs

@@ -29,5 +29,10 @@ module TypedCache
     def ==: (Object) -> bool
 
     alias eql? ==
+
+    private
+
+    # @rbs (String) -> String
+    def delimiter: (String) -> String
   end
 end

data/sig/generated/typed_cache/cache_ref.rbs

@@ -16,11 +16,11 @@ module TypedCache
 
     # Gets a value from the cache as a snapshot
     # : -> either[Error, Snapshot[V]]
-    def get: () -> either[Error, Snapshot[V]]
+    def read: () -> either[Error, Snapshot[V]]
 
     # Sets a value in the cache and returns it as an updated snapshot
     # : (V) -> either[Error, Snapshot[V]]
-    def set: (V) -> either[Error, Snapshot[V]]
+    def write: (V) -> either[Error, Snapshot[V]]
 
     # Deletes the value from the cache and returns the deleted value as a snapshot
     # : -> either[Error, Snapshot[V]]
@@ -77,8 +77,8 @@ module TypedCache
     def scope: [R] (String) -> CacheRef[R]
 
     # Pattern matching support for Either[Error, Snapshot[V]] results
-    # : [R] () { (Error) -> R } () { (Snapshot[V]) -> R } -> R
-    def fold: (untyped left_fn, untyped right_fn) -> untyped
+    # : [R] (^(Error) -> R, ^(Snapshot[V]) -> R) -> R
+    def fold: [R] (^(Error) -> R, ^(Snapshot[V]) -> R) -> R
 
     # Convenience method to work with the snapshot directly
     # : [R] () { (Snapshot[V]) -> R } -> either[Error, R]

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,22 @@ 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: ...
+
+    # @rbs override
+    # : (self) -> void
+    def initialize_copy: ...
   end
 end

data/sig/generated/typed_cache/decorators/instrumented.rbs

@@ -0,0 +1,35 @@
+# Generated from lib/typed_cache/decorators/instrumented.rb with RBS::Inline
+
+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[V]
+    include Decorator[V]
+
+    extend Forwardable
+
+    attr_reader store: TypedCache::Store[V]
+
+    attr_reader instrumenter: Instrumenter
+
+    # @rbs (Symbol, ?operation: String) ?{ (*untyped, **untyped) -> String } -> void
+    private def self.instrument: (Symbol, ?operation: String) ?{ (*untyped, **untyped) -> String } -> void
+
+    # : (TypedCache::Store[V], instrumenter: Instrumenter) -> void
+    def initialize: (TypedCache::Store[V], instrumenter: Instrumenter) -> void
+
+    # @rbs override
+    # : (self) -> self
+    def initialize_copy: ...
+
+    # @rbs override
+    # : -> String
+    def store_type: ...
+
+    # Additional methods that might exist on the wrapped store
+    def respond_to_missing?: (untyped method_name, ?untyped include_private) -> untyped
+
+    def method_missing: (untyped method_name, *untyped args) ?{ (?) -> untyped } -> untyped
+  end
+end

data/sig/generated/typed_cache/decorators.rbs

@@ -13,12 +13,14 @@ module TypedCache
   #              .with_decorator(:my_decorator)
   #              .build.value
   module Decorators
+    # @api private
     # Default decorator set – starts with instrumentation only, but this registry
     # lets end-users register their own via `Decorators.register`.
     REGISTRY: untyped
 
     extend Forwardable
 
+    # @api private
     # @rbs () -> Registry[Store[untyped]]
     def self.registry: () -> Registry[Store[untyped]]
   end

data/sig/generated/typed_cache/either.rbs

@@ -21,6 +21,10 @@ module TypedCache
 
     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]
@@ -36,6 +40,8 @@ module TypedCache
 
     attr_reader error: E
 
+    alias value error
+
     # : (E) -> void
     def initialize: (E) -> void
 
@@ -47,6 +53,14 @@ module TypedCache
     # : -> false
     def right?: ...
 
+    # @rbs override
+    # : (^(E) -> void) -> bot
+    def right_or_else: ...
+
+    # @rbs override
+    # : -> bot
+    def right_or_raise!: ...
+
     # @rbs override
     # : [T] () { (R) -> T } -> either[E, T]
     def map: ...
@@ -73,6 +87,8 @@ module TypedCache
 
     attr_reader value: R
 
+    alias result value
+
     # : (R) -> void
     def initialize: (R) -> void
 
@@ -84,6 +100,14 @@ module TypedCache
     # : -> true
     def right?: ...
 
+    # @rbs override
+    # : (^(E) -> void) -> R
+    def right_or_else: ...
+
+    # @rbs override
+    # : -> R
+    def right_or_raise!: ...
+
     # @rbs override
     # : [T] () { (R) -> T } -> either[E, T]
     def map: ...

data/sig/generated/typed_cache/errors.rbs

@@ -3,6 +3,8 @@
 module TypedCache
   # Base error class for TypedCache operations
   class Error < StandardError
+    # @rbs (*untyped) -> void
+    def initialize: (*untyped) -> void
   end
 
   # Store operation errors (network, I/O, etc.)

data/sig/generated/typed_cache/instrumenter.rbs

@@ -0,0 +1,31 @@
+# Generated from lib/typed_cache/instrumenter.rb with RBS::Inline
+
+module TypedCache
+  # Instrumenter for cache operations
+  module Instrumenter
+    type event = Dry::Events::Event | ActiveSupport::Notifications::Event
+
+    # @rbs [R](String, String, **untyped) { -> R } -> R
+    def instrument: [R] (String, String, **untyped) { () -> R } -> R
+
+    # @rbs (String, **untyped) { (event) -> void } -> void
+    def subscribe: (String, **untyped) { (event) -> void } -> void
+
+    # : -> String
+    def namespace: () -> String
+
+    # @rbs () -> bool
+    def enabled?: () -> bool
+
+    private
+
+    # @rbs (String, String, **untyped) -> Hash[Symbol, untyped]
+    def build_payload: (String, String, **untyped) -> Hash[Symbol, untyped]
+
+    # @rbs (String) -> String
+    def event_name: (String) -> String
+
+    # @rbs () -> TypedCache::_TypedCacheInstrumentationConfig
+    def config: () -> TypedCache::_TypedCacheInstrumentationConfig
+  end
+end

data/sig/generated/typed_cache/instrumenters/active_support.rbs

@@ -0,0 +1,20 @@
+# Generated from lib/typed_cache/instrumenters/active_support.rb with RBS::Inline
+
+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: ...
+
+      # @rbs override
+      # @rbs (String, **top) { (event) -> void } -> void
+      def subscribe: ...
+    end
+  end
+end

data/sig/generated/typed_cache/instrumenters/mixins/namespaced_singleton.rbs

@@ -0,0 +1,36 @@
+# Generated from lib/typed_cache/instrumenters/mixins/namespaced_singleton.rb with RBS::Inline
+
+module TypedCache
+  module Instrumenters
+    module Mixins
+      module NamespacedSingleton
+        # @rbs () -> Array[Class[Instrumenter & NamespacedSingleton]]
+        def self.all: () -> Array[Class[Instrumenter & NamespacedSingleton]]
+
+        # @rbs (Class[Instrumenter & NamespacedSingleton]) -> void
+        def self.included: (Class[Instrumenter & NamespacedSingleton]) -> void
+
+        # @rbs override
+        # @rbs () -> String
+        def namespace: ...
+
+        # @rbs (String | Namespace) -> void
+        def initialize: (String | Namespace) -> void
+
+        module ClassMethods
+          # @rbs (String | Namespace) -> class
+          def new: (String | Namespace) -> class
+
+          # @rbs (String) -> maybe[class]
+          def get: (String) -> maybe[class]
+
+          # @rbs () -> void
+          def clear_namespace_cache: () -> void
+
+          # @rbs () -> Concurrent::Map[String, Class[Instrumenter & NamespacedSingleton]]
+          def namespace_cache: () -> Concurrent::Map[String, Class[Instrumenter & NamespacedSingleton]]
+        end
+      end
+    end
+  end
+end

data/sig/generated/typed_cache/instrumenters/mixins.rbs

@@ -0,0 +1,8 @@
+# Generated from lib/typed_cache/instrumenters/mixins.rb with RBS::Inline
+
+module TypedCache
+  module Instrumenters
+    module Mixins
+    end
+  end
+end

data/sig/generated/typed_cache/instrumenters/monitor.rbs

@@ -0,0 +1,19 @@
+# Generated from lib/typed_cache/instrumenters/monitor.rb with RBS::Inline
+
+module TypedCache
+  module Instrumenters
+    class Monitor
+      include Instrumenter
+
+      include Mixins::NamespacedSingleton
+
+      # @rbs override
+      # : [R] (String, String, **untyped) { -> R } -> R
+      def instrument: ...
+
+      # @rbs override
+      # @rbs (String, **top) { (event) -> void } -> void
+      def subscribe: ...
+    end
+  end
+end

data/sig/generated/typed_cache/instrumenters/null.rbs

@@ -0,0 +1,21 @@
+# Generated from lib/typed_cache/instrumenters/null.rb with RBS::Inline
+
+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: ...
+
+      # @rbs override
+      # @rbs (String, **top) { (event) -> void } -> void
+      def subscribe: ...
+    end
+  end
+end

data/sig/generated/typed_cache/instrumenters.rbs

@@ -0,0 +1,26 @@
+# Generated from lib/typed_cache/instrumenters.rb with RBS::Inline
+
+module TypedCache
+  module Instrumenters
+    # @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[Symbol, Class[Instrumenter]]
+
+    extend Forwardable
+
+    # @api private
+    # @rbs () -> Registry[Symbol, Class[Instrumenter]]
+    def self.registry: () -> Registry[Symbol, Class[Instrumenter]]
+
+    def register: (Symbol, Class[Instrumenter]) -> void
+
+    def resolve: (Symbol, **untyped) -> either[Error, Instrumenter]
+
+    def available: () -> Array[Symbol]
+
+    def registered?: (Symbol) -> Boolean
+  end
+end

data/sig/generated/typed_cache/maybe.rbs

@@ -27,6 +27,10 @@ module TypedCache
 
     def bind: [T] () { (V) -> maybe[T] } -> maybe[T]
 
+    def value_or: [T] (T) -> T
+
+    def value_or_raise!: () -> V
+
     alias flat_map bind
   end
 
@@ -55,6 +59,14 @@ module TypedCache
     # : [T] () { (V) -> maybe[T] } -> maybe[T]
     def bind: ...
 
+    # @rbs override
+    # : [T] (T) -> T
+    def value_or: ...
+
+    # @rbs override
+    # : -> V
+    def value_or_raise!: ...
+
     alias flat_map bind
 
     # : (Array[top]) -> ({ value: V })
@@ -81,5 +93,13 @@ module TypedCache
     def bind: ...
 
     alias flat_map bind
+
+    # @rbs override
+    # : [T] (T) -> T
+    def value_or: ...
+
+    # @rbs override
+    # : -> V
+    def value_or_raise!: ...
   end
 end

data/sig/generated/typed_cache/namespace.rbs

@@ -19,15 +19,16 @@ 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 self.at: (String) -> Namespace
+    # @rbs (String, *String) -> Namespace
+    def self.at: (String, *String) -> Namespace
 
     # Returns the root Namespace instance (with an empty namespace).
     #
@@ -69,6 +70,21 @@ module TypedCache
     # @rbs (String) ?{ (Namespace, String) -> CacheKey } -> Namespace
     def nested: (String) ?{ (Namespace, String) -> CacheKey } -> Namespace
 
+    # 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: (*String) ?{ (Namespace, String) -> CacheKey } -> Namespace
+
     # Returns the parent namespace by removing the last namespace segment.
     #
     # @return [Namespace] the parent namespace, or self if already at root
@@ -126,5 +142,10 @@ module TypedCache
     def ==: (Object) -> bool
 
     alias eql? ==
+
+    private
+
+    # @rbs (String) -> String
+    def delimiter: (String) -> String
   end
 end

data/sig/generated/typed_cache/railtie.rbs

@@ -0,0 +1,6 @@
+# Generated from lib/typed_cache/railtie.rb with RBS::Inline
+
+module TypedCache
+  class Railtie < ::Rails::Railtie
+  end
+end

data/sig/generated/typed_cache/registry.rbs

@@ -7,6 +7,12 @@ module TypedCache
     # @rbs (String, Hash[Symbol, Class[T]]) -> void
     def initialize: (String, Hash[Symbol, Class[T]]) -> void
 
+    # @rbs (Registry[T]) -> Registry[T]
+    def initialize_copy: (Registry[T]) -> Registry[T]
+
+    # @rbs () -> void
+    def clear: () -> void
+
     # @rbs (Symbol, *untyped, **untyped) -> either[Error, T]
     def resolve: (Symbol, *untyped, **untyped) -> either[Error, T]
 
@@ -21,5 +27,7 @@ module TypedCache
 
     # @rbs (Symbol) -> bool
     def registered?: (Symbol) -> bool
+
+    attr_reader registry: Hash[Symbol, Class[T]]
   end
 end