typed_cache 0.1.1 → 0.3.0

data/sig/generated/typed_cache/snapshot.rbs

@@ -4,14 +4,16 @@ module TypedCache
   # Immutable snapshot of a cached value with metadata about its source and age
   # @rbs generic V
   class Snapshot[V]
+    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: (V, source: Symbol, retrieved_at: Time) -> void
+    # : (CacheKey, V, source: Symbol, retrieved_at: Time) -> void
+    def initialize: (CacheKey, V, source: Symbol, retrieved_at: Time) -> void
 
     # Age of the snapshot in seconds
     # : -> Float
@@ -39,12 +41,16 @@ module TypedCache
 
     alias flat_map bind
 
+    # Creates a snapshot for a cached value
+    # : [V] (CacheKey, V) -> Snapshot[V]
+    def self.cached: [V] (CacheKey, V) -> Snapshot[V]
+
     # Creates a snapshot for a computed value
-    # : [V] (V) -> Snapshot[V]
-    def self.computed: [V] (V) -> Snapshot[V]
+    # : [V] (CacheKey, V) -> Snapshot[V]
+    def self.computed: [V] (CacheKey, V) -> Snapshot[V]
 
     # Creates a snapshot for an updated value
-    # : [V] (V) -> Snapshot[V]
-    def self.updated: [V] (V) -> Snapshot[V]
+    # : [V] (CacheKey, V) -> Snapshot[V]
+    def self.updated: [V] (CacheKey, V) -> Snapshot[V]
   end
 end

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

@@ -14,8 +14,8 @@ module TypedCache
     # @rbs (Symbol, ?operation: String) ?{ (*untyped, **untyped) -> String } -> void
     private def self.instrument: (Symbol, ?operation: String) ?{ (*untyped, **untyped) -> String } -> void
 
-    # : (TypedCache::Store[V]) -> void
-    def initialize: (TypedCache::Store[V]) -> void
+    # : (TypedCache::Store[V], instrumenter: Instrumenter) -> void
+    def initialize: (TypedCache::Store[V], instrumenter: Instrumenter) -> void
 
     # @rbs override
     # : -> String
@@ -25,10 +25,6 @@ module TypedCache
     # : -> String
     def store_type: ...
 
-    # @rbs override
-    # : (cache_key) -> either[Error, CacheRef[V]]
-    def ref: ...
-
     # Additional methods that might exist on the wrapped store
     def respond_to_missing?: (untyped method_name, ?untyped include_private) -> untyped
 

data/sig/generated/typed_cache/store.rbs

@@ -13,11 +13,15 @@ module TypedCache
     type cache_key = String | CacheKey
 
     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]]
 
@@ -25,7 +29,9 @@ module TypedCache
 
       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
 
@@ -45,7 +51,10 @@ module TypedCache
 
     # Retrieves a value from the cache
     # @rbs (cache_key) -> either[Error, Snapshot[V]]
-    def get: (cache_key) -> either[Error, Snapshot[V]]
+    def read: (cache_key) -> either[Error, Snapshot[V]]
+
+    # @rbs (Array[cache_key]) -> either[Error, Hash[cache_key, Snapshot[V]]]
+    def read_all: (Array[cache_key]) -> either[Error, Hash[cache_key, Snapshot[V]]]
 
     # Retrieves a cache reference for a key
     # @rbs (cache_key) -> CacheRef[V]
@@ -53,7 +62,10 @@ module TypedCache
 
     # Stores a value in the cache
     # @rbs (cache_key, V) -> either[Error, Snapshot[V]]
-    def set: (cache_key, V) -> either[Error, Snapshot[V]]
+    def write: (cache_key, V) -> either[Error, Snapshot[V]]
+
+    # @rbs (Hash[cache_key, V]) -> either[Error, Hash[cache_key, Snapshot[V]]]
+    def write_all: (Hash[cache_key, V]) -> either[Error, Hash[cache_key, Snapshot[V]]]
 
     # Removes a value from the cache, returning the removed value
     # @rbs (cache_key) -> either[Error, Snapshot[V]]
@@ -68,18 +80,24 @@ module TypedCache
     def clear: () -> maybe[Error]
 
     # 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: (cache_key) { () -> V } -> either[Error, Snapshot[V]]
 
+    # @rbs (Array[cache_key]) { (CacheKey) -> V } -> either[Error, Array[Snapshot[V]]]
+    def fetch_all: (Array[cache_key]) { (CacheKey) -> V } -> either[Error, Array[Snapshot[V]]]
+
+    # @rbs () -> Instrumenter
+    def instrumenter: () -> Instrumenter
+
     # Returns the namespace for this store (for instrumentation/debugging)
     # @rbs () -> Namespace
     def namespace: () -> Namespace
 
     # Accepts a String segment or a fully-formed Namespace and returns a cloned
     # store scoped to that namespace.
-    # @rbs (Namespace | String) -> Store[V]
-    def with_namespace: (Namespace | String) -> Store[V]
+    # : (Namespace | String | Array[String]) -> Store[V]
+    def with_namespace: (Namespace | String | Array[String]) -> Store[V]
 
     # Returns the store type identifier for instrumentation/debugging
     # @rbs () -> String

data/sig/generated/typed_cache.rbs

@@ -12,6 +12,8 @@ module TypedCache
   interface _TypedCacheConfig
     def default_namespace: () -> String
 
+    def cache_delimiter: () -> String
+
     def instrumentation: () -> _TypedCacheInstrumentationConfig
   end
 
@@ -23,12 +25,12 @@ module TypedCache
 
   def config: () -> _TypedCacheConfig
 
-  # @rbs () -> singleton(Instrumentation)
-  def self.instrumentation: () -> singleton(Instrumentation)
+  # @rbs () -> singleton(Backends)
+  def self.backends: () -> singleton(Backends)
 
-  # @rbs () -> Registry[backend[untyped]]
-  def self.backends: () -> Registry[backend[untyped]]
+  # @rbs () -> singleton(Decorators)
+  def self.decorators: () -> singleton(Decorators)
 
-  # @rbs () -> Register[decorator[untyped]]
-  def self.decorators: () -> Register[decorator[untyped]]
+  # @rbs () -> singleton(Instrumenters)
+  def self.instrumenters: () -> singleton(Instrumenters)
 end

data/typed_cache.gemspec

@@ -29,14 +29,15 @@ Gem::Specification.new do |spec|
   spec.cert_chain = [Gem.default_cert_path]
 
   spec.required_ruby_version = '>= 3.2.0'
-  spec.add_dependency('concurrent-ruby', '~> 1.3.5')
-  spec.add_dependency('concurrent-ruby-edge', '~>0.7.2')
+
+  spec.add_dependency('concurrent-ruby', '~> 1.0')
+
   spec.add_dependency('dry-configurable', '~> 1.0')
+  spec.add_dependency('dry-monitor', '~>1.0')
   spec.add_dependency('dry-struct', '~> 1.0')
   spec.add_dependency('dry-types', '~>1.0')
   spec.add_dependency('multi_json', '~> 1.17')
-  spec.add_dependency('zeitwerk', '~> 2.7')
 
   spec.extra_rdoc_files = Dir['README*', 'LICENSE*', 'examples*']
-  spec.files = Dir['*.gemspec', 'lib/**/*', 'sig/**/*']
+  spec.files = Dir['*.gemspec', 'lib/**/*', 'sig/**/*', 'rbi/**/*']
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: typed_cache
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Autumn Winter
@@ -35,7 +35,7 @@ cert_chain:
   uuhUq525FXA3gYeLAfnCSHNm7D1H7whsXYd3z+gKvEhSEQPb3mSBQ+31TDFmA5k7
   q7YL3dwhxKPXtnAboI+30XBImpdizFG9Nyqgzgj/kD0QwVzL0QsVdVWnNTJXrm4n
   -----END CERTIFICATE-----
-date: 2025-07-21 00:00:00.000000000 Z
+date: 2025-08-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -43,30 +43,30 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.3.5
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 1.3.5
+        version: '1.0'
 - !ruby/object:Gem::Dependency
-  name: concurrent-ruby-edge
+  name: dry-configurable
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.7.2
+        version: '1.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: 0.7.2
+        version: '1.0'
 - !ruby/object:Gem::Dependency
-  name: dry-configurable
+  name: dry-monitor
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
@@ -121,20 +121,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.17'
-- !ruby/object:Gem::Dependency
-  name: zeitwerk
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.7'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '2.7'
 description: |
   TypedCache is a Ruby caching library designed to eliminate common caching pitfalls by providing a monadic, type-safe API that makes cache operations explicit and predictable. Cache interactions are first-class operations with
   comprehensive error handling and transparent state management. The library supports wrapping other caching libraries via custom backends and ActiveSupport::Cache is supported out of the box.
@@ -161,16 +147,44 @@ files:
 - lib/typed_cache/clock.rb
 - lib/typed_cache/decorator.rb
 - lib/typed_cache/decorators.rb
+- lib/typed_cache/decorators/instrumented.rb
 - lib/typed_cache/either.rb
 - lib/typed_cache/errors.rb
-- lib/typed_cache/instrumentation.rb
+- lib/typed_cache/instrumenter.rb
+- lib/typed_cache/instrumenters.rb
+- lib/typed_cache/instrumenters/active_support.rb
+- lib/typed_cache/instrumenters/mixins.rb
+- lib/typed_cache/instrumenters/mixins/namespaced_singleton.rb
+- lib/typed_cache/instrumenters/monitor.rb
+- lib/typed_cache/instrumenters/null.rb
 - lib/typed_cache/maybe.rb
 - lib/typed_cache/namespace.rb
+- lib/typed_cache/railtie.rb
 - lib/typed_cache/registry.rb
 - lib/typed_cache/snapshot.rb
 - lib/typed_cache/store.rb
-- lib/typed_cache/store/instrumented.rb
 - lib/typed_cache/version.rb
+- rbi/typed_cache.rbi
+- rbi/typed_cache/backend.rbi
+- rbi/typed_cache/backends.rbi
+- rbi/typed_cache/backends/active_support.rbi
+- rbi/typed_cache/backends/memory.rbi
+- rbi/typed_cache/cache_builder.rbi
+- rbi/typed_cache/cache_key.rbi
+- rbi/typed_cache/cache_ref.rbi
+- rbi/typed_cache/decorator.rbi
+- rbi/typed_cache/decorators.rbi
+- rbi/typed_cache/decorators/instrumented.rbi
+- rbi/typed_cache/either.rbi
+- rbi/typed_cache/errors.rbi
+- rbi/typed_cache/instrumenter.rbi
+- rbi/typed_cache/instrumenters.rbi
+- rbi/typed_cache/instrumenters/mixins/namedspaced_singleton.rbi
+- rbi/typed_cache/maybe.rbi
+- rbi/typed_cache/namespace.rbi
+- rbi/typed_cache/snapshot.rbi
+- rbi/typed_cache/store.rbi
+- rbi/typed_cache/version.rbi
 - sig/generated/typed_cache.rbs
 - sig/generated/typed_cache/backend.rbs
 - sig/generated/typed_cache/backends.rbs
@@ -182,24 +196,31 @@ files:
 - sig/generated/typed_cache/clock.rbs
 - sig/generated/typed_cache/decorator.rbs
 - sig/generated/typed_cache/decorators.rbs
+- sig/generated/typed_cache/decorators/instrumented.rbs
 - sig/generated/typed_cache/either.rbs
 - sig/generated/typed_cache/errors.rbs
-- sig/generated/typed_cache/instrumentation.rbs
+- sig/generated/typed_cache/instrumenter.rbs
+- sig/generated/typed_cache/instrumenters.rbs
+- sig/generated/typed_cache/instrumenters/active_support.rbs
+- sig/generated/typed_cache/instrumenters/mixins.rbs
+- sig/generated/typed_cache/instrumenters/mixins/namespaced_singleton.rbs
+- sig/generated/typed_cache/instrumenters/monitor.rbs
+- sig/generated/typed_cache/instrumenters/null.rbs
 - sig/generated/typed_cache/maybe.rbs
 - sig/generated/typed_cache/namespace.rbs
+- sig/generated/typed_cache/railtie.rbs
 - sig/generated/typed_cache/registry.rbs
 - sig/generated/typed_cache/snapshot.rbs
 - sig/generated/typed_cache/store.rbs
 - sig/generated/typed_cache/store/instrumented.rbs
 - sig/generated/typed_cache/version.rbs
-- sig/handwritten/gems/zeitwerk/2.7/zeitwerk.rbs
 - typed_cache.gemspec
 homepage: https://github.com/glossawy/typed_cache
 licenses:
 - Apache-2.0
 metadata:
   issue_tracker_uri: https://github.com/glossawy/typed_cache/issues
-  changelog_uri: https://github.com/glossawy/typed_cache/blob/main/VERSIONS.adoc#011
+  changelog_uri: https://github.com/glossawy/typed_cache/blob/main/VERSIONS.adoc#030
   license_uri: https://github.com/glossawy/typed_cache/blob/main/LICENSE
   label: caching
   labels: typed_cache,ruby,caching,type-safety,rails,rbs

data/lib/typed_cache/instrumentation.rb

@@ -1,112 +0,0 @@
-# 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/store/instrumented.rb

@@ -1,83 +0,0 @@
-# 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

data/sig/generated/typed_cache/instrumentation.rbs

@@ -1,30 +0,0 @@
-# Generated from lib/typed_cache/instrumentation.rb with RBS::Inline
-
-module TypedCache
-  # Instrumentation hooks for ActiveSupport::Notifications integration
-  # All instrumentation is explicit and opt-in - no automatic behavior
-  module Instrumentation
-    type config = TypedCache::_TypedCacheInstrumentationConfig
-
-    # @rbs () -> config
-    def self.config: () -> config
-
-    # Check if ActiveSupport::Notifications is available
-    # @rbs () -> bool
-    def self.notifications_available?: () -> bool
-
-    # Main instrumentation method
-    # : [T] (String, String, String, Hash[Symbol, untyped]) { -> T } -> T
-    def self.instrument: [T] (String, String, String, Hash[Symbol, untyped]) { () -> T } -> T
-
-    # Cross-platform current time helper (uses Time.current when available)
-    # : -> Time
-    private def self.current_time: () -> Time
-
-    # @rbs (String, String, Time) -> Hash[Symbol, untyped]
-    private def self.base_payload: (String, String, Time) -> Hash[Symbol, untyped]
-
-    # @rbs (Either[StandardError, Snapshot]) -> [bool, Hash[Symbol, untyped]]
-    private def self.extract_result_metadata: (Either[StandardError, Snapshot]) -> [ bool, Hash[Symbol, untyped] ]
-  end
-end

data/sig/handwritten/gems/zeitwerk/2.7/zeitwerk.rbs

@@ -1,9 +0,0 @@
-
-
-module Zeitwerk
-  class Loader
-    def self.for_gem: -> instance
-
-    def setup: -> void
-  end
-end