typed_cache 0.1.1

data/sig/generated/typed_cache/either.rbs

@@ -0,0 +1,106 @@
+# Generated from lib/typed_cache/either.rb with RBS::Inline
+
+module TypedCache
+  type either[out E, out R] = (Left[E] | Right[R]) & _Either[E, R]
+
+  module Either
+    include Kernel
+
+    # : [E] (E) -> either[E, bot]
+    def self.left: [E] (E) -> either[E, bot]
+
+    # : [R] (R) -> either[bot, R]
+    def self.right: [R] (R) -> either[bot, R]
+
+    # : [E, R] (E | R) -> either[E, R]
+    def self.wrap: [E, R] (E | R) -> either[E, R]
+  end
+
+  interface _Either[out E, out R]
+    def left?: () -> bool
+
+    def right?: () -> bool
+
+    def map: [T] () { (R) -> T } -> either[E, T]
+
+    def bind: [E2, R2] () { (R) -> either[E2, R2] } -> either[E | E2, R2]
+
+    def map_left: [F] () { (E) -> F } -> either[F, R]
+
+    def fold: [T, E, R] (^(E) -> T, ^(R) -> T) -> T
+  end
+
+  # @rbs generic out E
+  class Left[out E]
+    include _Either[E, bot]
+
+    attr_reader error: E
+
+    # : (E) -> void
+    def initialize: (E) -> void
+
+    # @rbs override
+    # : -> true
+    def left?: ...
+
+    # @rbs override
+    # : -> false
+    def right?: ...
+
+    # @rbs override
+    # : [T] () { (R) -> T } -> either[E, T]
+    def map: ...
+
+    # @rbs override
+    # : [E2, R2] () { (R) -> either[E2, R2] } -> either[E | E2, R2]
+    def bind: ...
+
+    # @rbs override
+    # : [F] () { (E) -> F } -> either[F, R]
+    def map_left: ...
+
+    # @rbs override
+    # : [T, E, R] (^(E) -> T, ^(R) -> T) -> T
+    def fold: ...
+
+    # : (Array[top]) -> ({ error: E })
+    def deconstruct_keys: (Array[top]) -> { error: E }
+  end
+
+  # @rbs generic out R
+  class Right[out R]
+    include _Either[bot, R]
+
+    attr_reader value: R
+
+    # : (R) -> void
+    def initialize: (R) -> void
+
+    # @rbs override
+    # : -> false
+    def left?: ...
+
+    # @rbs override
+    # : -> true
+    def right?: ...
+
+    # @rbs override
+    # : [T] () { (R) -> T } -> either[E, T]
+    def map: ...
+
+    # @rbs override
+    # : [E2, R2] () { (R) -> either[E2, R2] } -> either[E | E2, R2]
+    def bind: ...
+
+    # @rbs override
+    # : [F] () { (E) -> F } -> either[F, R]
+    def map_left: ...
+
+    # @rbs override
+    # : [T, E, R] (^(E) -> T, ^(R) -> T) -> T
+    def fold: ...
+
+    # : (Array[top]) -> ({ value: R })
+    def deconstruct_keys: (Array[top]) -> { value: R }
+  end
+end

data/sig/generated/typed_cache/errors.rbs

@@ -0,0 +1,51 @@
+# Generated from lib/typed_cache/errors.rb with RBS::Inline
+
+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: untyped
+
+    attr_reader key: untyped
+
+    attr_reader original_error: untyped
+
+    # @rbs (Symbol, String, String, Exception?) -> void
+    def initialize: (Symbol, String, String, Exception?) -> void
+
+    # @rbs () -> String
+    def detailed_message: () -> String
+
+    # @rbs () -> bool
+    def has_cause?: () -> bool
+  end
+
+  # Type safety violations
+  class TypeError < Error
+    attr_reader expected_type: untyped
+
+    attr_reader actual_type: untyped
+
+    attr_reader value: untyped
+
+    # @rbs (String, String, untyped, String) -> void
+    def initialize: (String, String, untyped, String) -> void
+
+    # @rbs () -> String
+    def type_mismatch_message: () -> String
+  end
+
+  # Cache miss (when expecting a value to exist)
+  class CacheMissError < Error
+    attr_reader key: untyped
+
+    # @rbs (CacheKey) -> void
+    def initialize: (CacheKey) -> void
+
+    # @rbs () -> bool
+    def cache_miss?: () -> bool
+  end
+end

data/sig/generated/typed_cache/instrumentation.rbs

@@ -0,0 +1,30 @@
+# 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/generated/typed_cache/maybe.rbs

@@ -0,0 +1,85 @@
+# Generated from lib/typed_cache/maybe.rb with RBS::Inline
+
+module TypedCache
+  type maybe[T] = (Nothing | Some[T]) & _Maybe[T]
+
+  module Maybe
+    include Kernel
+
+    # : [V](V) -> maybe[V]
+    def self.some: [V] (V) -> maybe[V]
+
+    # : -> maybe[bot]
+    def self.none: () -> maybe[bot]
+
+    # : [V](V? | maybe[V]) -> maybe[V]
+    def self.wrap: [V] (V? | maybe[V]) -> maybe[V]
+
+    alias self.[] self.some
+  end
+
+  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[out V]
+    include _Maybe[V]
+
+    attr_reader value: V
+
+    # : (V) -> void
+    def initialize: (V) -> void
+
+    # @rbs override
+    # : -> TrueClass
+    def some?: ...
+
+    # @rbs override
+    # : -> FalseClass
+    def nothing?: ...
+
+    # @rbs override
+    # : [T] () { (V) -> T } -> maybe[T]
+    def map: ...
+
+    # @rbs override
+    # : [T] () { (V) -> maybe[T] } -> maybe[T]
+    def bind: ...
+
+    alias flat_map bind
+
+    # : (Array[top]) -> ({ value: V })
+    def deconstruct_keys: (Array[top]) -> { value: V }
+  end
+
+  class Nothing
+    include _Maybe[bot]
+
+    # @rbs override
+    # : -> FalseClass
+    def some?: ...
+
+    # @rbs override
+    # : -> TrueClass
+    def nothing?: ...
+
+    # @rbs override
+    # : [T] () { (V) -> T } -> maybe[T]
+    def map: ...
+
+    # @rbs override
+    # : [T] () { (V) -> maybe[T] } -> maybe[T]
+    def bind: ...
+
+    alias flat_map bind
+  end
+end

data/sig/generated/typed_cache/namespace.rbs

@@ -0,0 +1,130 @@
+# Generated from lib/typed_cache/namespace.rb with RBS::Inline
+
+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
+    # 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 self.at: (String) -> Namespace
+
+    # 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 self.root: () -> Namespace
+
+    # 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: (String) { (Namespace, String) -> CacheKey } -> void
+
+    # 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: (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
+    #
+    # 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: () -> Namespace
+
+    # 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: (String) -> CacheKey
+
+    # @rbs () -> bool
+    def root?: () -> bool
+
+    # 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: () -> String
+
+    # 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: () -> String
+
+    # @rbs () -> Integer
+    def hash: () -> Integer
+
+    # @rbs (Object) -> bool
+    def ==: (Object) -> bool
+
+    alias eql? ==
+  end
+end

data/sig/generated/typed_cache/registry.rbs

@@ -0,0 +1,25 @@
+# Generated from lib/typed_cache/registry.rb with RBS::Inline
+
+module TypedCache
+  # Generic registry for managing class-based factories
+  # @rbs generic T
+  class Registry[T]
+    # @rbs (String, Hash[Symbol, Class[T]]) -> void
+    def initialize: (String, Hash[Symbol, Class[T]]) -> void
+
+    # @rbs (Symbol, *untyped, **untyped) -> either[Error, T]
+    def resolve: (Symbol, *untyped, **untyped) -> either[Error, T]
+
+    # @rbs (Symbol) -> maybe[Class[T]]
+    def find: (Symbol) -> maybe[Class[T]]
+
+    # @rbs (Symbol, Class[T]) -> either[Error, void]
+    def register: (Symbol, Class[T]) -> either[Error, void]
+
+    # @rbs () -> Array[Symbol]
+    def available: () -> Array[Symbol]
+
+    # @rbs (Symbol) -> bool
+    def registered?: (Symbol) -> bool
+  end
+end

data/sig/generated/typed_cache/snapshot.rbs

@@ -0,0 +1,50 @@
+# Generated from lib/typed_cache/snapshot.rb with RBS::Inline
+
+module TypedCache
+  # Immutable snapshot of a cached value with metadata about its source and age
+  # @rbs generic V
+  class Snapshot[V]
+    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
+
+    # Age of the snapshot in seconds
+    # : -> Float
+    def age: () -> Float
+
+    # Whether this value came from cache
+    # : -> bool
+    def from_cache?: () -> bool
+
+    # Whether this value was freshly computed
+    # : -> bool
+    def computed?: () -> bool
+
+    # Whether this value was updated
+    # : -> bool
+    def updated?: () -> bool
+
+    # Map over the value while preserving snapshot metadata
+    # : [R] () { (V) -> R } -> Snapshot[R]
+    def map: [R] () { (V) -> R } -> Snapshot[R]
+
+    # Bind over the value with Either error handling
+    # : [R] () { (V) -> either[Error, R] } -> either[Error, Snapshot[R]]
+    def bind: [R] () { (V) -> either[Error, R] } -> either[Error, Snapshot[R]]
+
+    alias flat_map bind
+
+    # Creates a snapshot for a computed value
+    # : [V] (V) -> Snapshot[V]
+    def self.computed: [V] (V) -> Snapshot[V]
+
+    # Creates a snapshot for an updated value
+    # : [V] (V) -> Snapshot[V]
+    def self.updated: [V] (V) -> Snapshot[V]
+  end
+end

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

@@ -0,0 +1,37 @@
+# Generated from lib/typed_cache/store/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 Store::Instrumented[V]
+    include Decorator[V]
+
+    extend Forwardable
+
+    attr_reader store: TypedCache::Store[V]
+
+    # @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
+
+    # @rbs override
+    # : -> String
+    def namespace: ...
+
+    # @rbs override
+    # : -> 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
+
+    def method_missing: (untyped method_name, *untyped args) ?{ (?) -> untyped } -> untyped
+  end
+end

data/sig/generated/typed_cache/store.rbs

@@ -0,0 +1,104 @@
+# Generated from lib/typed_cache/store.rb with RBS::Inline
+
+module TypedCache
+  # Generic interface for type-safe cache storage implementations
+  # All stores are assumed to handle namespacing internally
+  #
+  # This interface follows the Command-Query Separation principle:
+  # - Commands (set, delete, clear) perform actions and may return results
+  # - Queries (get, key?, fetch) ask questions without side effects
+  #
+  # @rbs generic V
+  module Store[V]
+    type cache_key = String | CacheKey
+
+    interface _Store[V]
+      def get: (cache_key) -> either[Error, Snapshot[V]]
+
+      def ref: (cache_key) -> CacheRef[V]
+
+      def set: (cache_key, V) -> either[Error, 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 namespace: () -> Namespace
+
+      def with_namespace: (Namespace) -> Store[V]
+
+      def store_type: () -> String
+    end
+
+    include _Store[V]
+
+    interface _Decorator[V]
+      def initialize: (Store[V]) -> void
+    end
+
+    # @rbs (Store[V]) -> void
+    def initialize_copy: (Store[V]) -> void
+
+    # Retrieves a value from the cache
+    # @rbs (cache_key) -> either[Error, Snapshot[V]]
+    def get: (cache_key) -> either[Error, Snapshot[V]]
+
+    # Retrieves a cache reference for a key
+    # @rbs (cache_key) -> CacheRef[V]
+    def ref: (cache_key) -> CacheRef[V]
+
+    # Stores a value in the cache
+    # @rbs (cache_key, V) -> either[Error, Snapshot[V]]
+    def set: (cache_key, V) -> either[Error, Snapshot[V]]
+
+    # Removes a value from the cache, returning the removed value
+    # @rbs (cache_key) -> either[Error, Snapshot[V]]
+    def delete: (cache_key) -> either[Error, Snapshot[V]]
+
+    # Checks if a key exists in the cache (query operation)
+    # @rbs (cache_key) -> bool
+    def key?: (cache_key) -> bool
+
+    # Clears all values from the cache namespace (command operation)
+    # @rbs () -> maybe[Error]
+    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
+    # @rbs (cache_key) { () -> V } -> either[Error, Snapshot[V]]
+    def fetch: (cache_key) { () -> V } -> either[Error, Snapshot[V]]
+
+    # 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]
+
+    # Returns the store type identifier for instrumentation/debugging
+    # @rbs () -> String
+    def store_type: () -> String
+
+    attr_writer namespace: Namespace
+
+    private
+
+    # : (String) -> String
+    def snake_case: (String) -> String
+
+    # : (cache_key) -> CacheKey
+    def namespaced_key: (cache_key) -> CacheKey
+  end
+
+  type backend[V] = Store::_Store[V]
+
+  type decorator[V] = backend[V] & Store::_Decorator[V]
+
+  type store[V] = backend[V] | decorator[V]
+end

data/sig/generated/typed_cache/version.rbs

@@ -0,0 +1,5 @@
+# Generated from lib/typed_cache/version.rb with RBS::Inline
+
+module TypedCache
+  VERSION: ::String
+end

data/sig/generated/typed_cache.rbs

@@ -0,0 +1,34 @@
+# Generated from lib/typed_cache.rb with RBS::Inline
+
+module TypedCache
+  extend Dry::Configurable
+
+  interface _TypedCacheInstrumentationConfig
+    def enabled: () -> bool
+
+    def namespace: () -> String
+  end
+
+  interface _TypedCacheConfig
+    def default_namespace: () -> String
+
+    def instrumentation: () -> _TypedCacheInstrumentationConfig
+  end
+
+  type typed_cache_config = _TypedCacheConfig
+
+  # Returns a CacheBuilder with the fluent interface
+  # @rbs [V] () -> CacheBuilder[V]
+  def self.builder: [V] () -> CacheBuilder[V]
+
+  def config: () -> _TypedCacheConfig
+
+  # @rbs () -> singleton(Instrumentation)
+  def self.instrumentation: () -> singleton(Instrumentation)
+
+  # @rbs () -> Registry[backend[untyped]]
+  def self.backends: () -> Registry[backend[untyped]]
+
+  # @rbs () -> Register[decorator[untyped]]
+  def self.decorators: () -> Register[decorator[untyped]]
+end

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

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