typed_cache 0.1.1

data/lib/typed_cache/store.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+module TypedCache
+  # @rbs!
+  #
+
+  # 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
+    # @rbs! type cache_key = String | CacheKey
+
+    # @rbs!
+    #   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]
+
+    # @rbs!
+    #   interface _Decorator[V]
+    #     def initialize: (Store[V]) -> void
+    #   end
+
+    # @rbs (Store[V]) -> void
+    def initialize_copy(other)
+      super
+      @namespace = other.namespace
+    end
+
+    # 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"))
+    end
+
+    # Retrieves a cache reference for a key
+    # @rbs (cache_key) -> CacheRef[V]
+    def ref(key)
+      CacheRef.new(self, namespaced_key(key))
+    end
+
+    # 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"))
+    end
+
+    # Removes a value from the cache, returning the removed value
+    # @rbs (cache_key) -> either[Error, Snapshot[V]]
+    def delete(key)
+      Either.left(NotImplementedError.new("#{self.class} must implement #delete"))
+    end
+
+    # Checks if a key exists in the cache (query operation)
+    # @rbs (cache_key) -> bool
+    def key?(key)
+      false # Safe default - assume key doesn't exist
+    end
+
+    # Clears all values from the cache namespace (command operation)
+    # @rbs () -> maybe[Error]
+    def clear
+      Maybe.some(NotImplementedError.new("#{self.class} does not implement #clear"))
+    end
+
+    # 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(key, &block)
+      # Default implementation using get/set pattern
+      get_result = get(key)
+      return get_result if get_result.right?
+
+      # Only proceed if it's a cache miss
+      return get_result unless get_result.error.is_a?(CacheMissError)
+
+      # Compute and store new value
+      begin
+        computed_value = yield
+        set(key, computed_value)
+        Either.right(Snapshot.computed(computed_value))
+      rescue => e
+        Either.left(StoreError.new(:fetch, key, "Failed to compute value for key '#{key}': #{e.message}", e))
+      end
+    end
+
+    # Returns the namespace for this store (for instrumentation/debugging)
+    # @rbs () -> Namespace
+    def namespace
+      raise NotImplementedError, "#{self.class} must implement #namespace"
+    end
+
+    # 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(ns)
+      new_namespace =
+        case ns
+        when Namespace then ns
+        else
+          # treat as nested segment under the current namespace
+          namespace.nested(ns.to_s)
+        end
+
+      clone.tap { |store| store.namespace = new_namespace }
+    end
+
+    # Returns the store type identifier for instrumentation/debugging
+    # @rbs () -> String
+    def store_type
+      snake_case(self.class.name.split('::').last)
+    end
+
+    protected
+
+    attr_writer :namespace #: Namespace
+
+    private
+
+    #: (String) -> String
+    def snake_case(string)
+      string
+        .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+        .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+        .tr('-', '_')
+        .downcase
+    end
+
+    #: (cache_key) -> CacheKey
+    def namespaced_key(key)
+      key.is_a?(CacheKey) ? key : CacheKey.new(namespace, key)
+    end
+  end
+
+  # @rbs! type backend[V] = Store::_Store[V]
+  # @rbs! type decorator[V] = backend[V] & Store::_Decorator[V]
+  # @rbs! type store[V] = backend[V] | decorator[V]
+end

data/lib/typed_cache/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module TypedCache
+  VERSION = '0.1.1'
+end

data/lib/typed_cache.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require 'zeitwerk'
+require 'dry-configurable'
+require 'concurrent-ruby'
+
+# Load core registry before Zeitwerk
+require_relative 'typed_cache/registry'
+require_relative 'typed_cache/errors'
+
+Zeitwerk::Loader.for_gem.setup
+
+module TypedCache
+  extend Dry::Configurable
+
+  # @rbs!
+  #   interface _TypedCacheInstrumentationConfig
+  #     def enabled: -> bool
+  #     def namespace: -> String
+  #   end
+
+  # @rbs!
+  #   interface _TypedCacheConfig
+  #     def default_namespace: -> String
+  #     def instrumentation: -> _TypedCacheInstrumentationConfig
+  #   end
+
+  # @rbs! type typed_cache_config = _TypedCacheConfig
+
+  # Configuration
+  setting :default_namespace, default: 'typed_cache'
+
+  setting :instrumentation do
+    setting :enabled, default: false
+    setting :namespace, default: 'typed_cache'
+  end
+
+  class << self
+    # Returns a CacheBuilder with the fluent interface
+    # @rbs [V] () -> CacheBuilder[V]
+    def builder
+      CacheBuilder.new(config, Backends, Decorators)
+    end
+
+    # @rbs! def config: -> _TypedCacheConfig
+
+    # @rbs () -> singleton(Instrumentation)
+    def instrumentation
+      Instrumentation
+    end
+
+    # @rbs () -> Registry[backend[untyped]]
+    def backends = Backends
+
+    # @rbs () -> Register[decorator[untyped]]
+    def decorators = Decorators
+  end
+end

data/sig/generated/typed_cache/backend.rbs

@@ -0,0 +1,17 @@
+# Generated from lib/typed_cache/backend.rb with RBS::Inline
+
+module TypedCache
+  # Marker mixin for concrete cache back-ends.
+  # A Backend *is* a Store, but the reverse is not necessarily true (decorators also
+  # include Store). By tagging back-ends with this module we can type-check and
+  # register them separately from decorators.
+  #
+  # Back-ends should *not* assume they wrap another store – they are the leaf nodes
+  # that actually persist data.
+  # @rbs generic V
+  module Backend[V]
+    include Store[V]
+
+    include Store::_Store[V]
+  end
+end

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

@@ -0,0 +1,56 @@
+# Generated from lib/typed_cache/backends/active_support.rb with RBS::Inline
+
+module TypedCache
+  module Backends
+    # Adapter that wraps any ActiveSupport::Cache::Store to work with TypedCache
+    # @rbs generic V
+    class ActiveSupport[V]
+      include Backend[V]
+
+      attr_reader namespace: Namespace
+
+      attr_reader cache_store: ::ActiveSupport::Cache::Store
+
+      attr_reader default_options: Hash[Symbol, top]
+
+      # : (Namespace, ::ActiveSupport::Cache::Store, ?Hash[Symbol, top]) -> void
+      def initialize: (Namespace, ::ActiveSupport::Cache::Store, ?Hash[Symbol, top]) -> void
+
+      # @rbs override
+      # : (cache_key) -> either[Error, Snapshot[V]]
+      def get: ...
+
+      # @rbs override
+      # : (cache_key, V) -> either[Error, Snapshot[V]]
+      def set: ...
+
+      # @rbs override
+      # : (cache_key) -> either[Error, Snapshot[V]]
+      def delete: ...
+
+      # @rbs override
+      # : (cache_key) -> bool
+      def key?: ...
+
+      # @rbs override
+      # : -> maybe[Error]
+      def clear: ...
+
+      # @rbs override
+      # : -> String
+      def store_type: ...
+
+      # : (Hash[Symbol, top]) -> ActiveSupport[V]
+      def with_options: (Hash[Symbol, top]) -> ActiveSupport[V]
+
+      # : -> ::ActiveSupport::Cache::Store
+      def raw_cache: () -> ::ActiveSupport::Cache::Store
+
+      private
+
+      # Regex patterns that match keys for this namespace (with trailing colon)
+      # : -> Array[Regexp]
+      def namespace_prefix_patterns: () -> Array[Regexp]
+    end
+  end
+end

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

@@ -0,0 +1,95 @@
+# Generated from lib/typed_cache/backends/memory.rb with RBS::Inline
+
+module TypedCache
+  class MemoryStoreRegistry
+    include Singleton
+
+    extend Forwardable
+
+    # : -> void
+    def initialize: () -> void
+  end
+
+  module Backends
+    # A type-safe memory store implementation with built-in namespacing
+    # @rbs generic V
+    class Memory[V]
+      include Backend[V]
+
+      interface _HashLike[K, V]
+        def []: (K) -> V?
+
+        def []=: (K, V) -> V
+
+        def delete: (K) -> V?
+
+        def key?: (K) -> bool
+
+        def keys: () -> Array[K]
+      end
+
+      type hash_like[K, V] = _HashLike[K, V]
+
+      # @private
+      # @rbs generic V
+      class Entry[V] < Dry::Struct
+        attr_accessor expires_at: Time
+
+        attr_reader value: V
+
+        # @rbs (value: V, expires_in: Integer) -> Entry[V]
+        def self.expiring: (value: V, expires_in: Integer) -> Entry[V]
+
+        # @rbs () -> bool
+        def expired?: () -> bool
+      end
+
+      attr_reader namespace: Namespace
+
+      attr_reader ttl: Namespace
+
+      attr_reader backing_store: hash_like[CacheKey, Entry[V]]
+
+      # : (Namespace, shared: bool, ttl: Integer) -> void
+      def initialize: (Namespace, shared: bool, ttl: Integer) -> void
+
+      # @rbs override
+      # : (cache_key) -> either[Error, Snapshot[V]]
+      def get: ...
+
+      # @rbs override
+      # : (cache_key, V) -> either[Error, Snapshot[V]]
+      def set: ...
+
+      # @rbs override
+      # : (cache_key) -> either[Error, Snapshot[V]]
+      def delete: ...
+
+      # @rbs override
+      # : (cache_key) -> bool
+      def key?: ...
+
+      # @rbs override
+      # : -> maybe[Error]
+      def clear: ...
+
+      # @rbs override
+      # : -> String
+      def store_type: ...
+
+      # : -> Integer
+      def size: () -> Integer
+
+      # : -> Array[CacheKey]
+      def keys: () -> Array[CacheKey]
+
+      private
+
+      # : -> Hash[CacheKey, Entry[V]]
+      def namespaced_entries: () -> Hash[CacheKey, Entry[V]]
+
+      # : -> void
+      def purge_expired_keys: () -> void
+    end
+  end
+end

data/sig/generated/typed_cache/backends.rbs

@@ -0,0 +1,21 @@
+# Generated from lib/typed_cache/backends.rb with RBS::Inline
+
+module TypedCache
+  module Backends
+    # Backend registry using composition
+    REGISTRY: untyped
+
+    extend Forwardable
+
+    # : -> Registry
+    def self.registry: () -> Registry
+
+    def resolve: (Symbol, *untyped, **untyped) -> either[Error, Store[untyped]]
+
+    def available: () -> Array[Symbol]
+
+    def register: (Symbol, Class) -> either[Error, void]
+
+    def registered?: (Symbol) -> bool
+  end
+end

data/sig/generated/typed_cache/cache_builder.rbs

@@ -0,0 +1,37 @@
+# Generated from lib/typed_cache/cache_builder.rb with RBS::Inline
+
+module TypedCache
+  class CacheBuilder
+    type config = TypedCache::typed_cache_config
+
+    # @rbs (config, Registry[backend[untyped]], Registry[decorator[untyped]]) -> void
+    def initialize: (config, Registry[backend[untyped]], Registry[decorator[untyped]]) -> void
+
+    # Builds the cache - the only method that can fail
+    # @rbs (?Namespace) -> either[Error, Store[V]]
+    def build: (?Namespace) -> either[Error, Store[V]]
+
+    # Familiar Ruby fluent interface - always succeeds
+    # Invalid configurations are caught during build()
+    # @rbs (Symbol, *untyped, **untyped) -> self
+    def with_backend: (Symbol, *untyped, **untyped) -> self
+
+    # Adds an arbitrary decorator by registry key
+    # @rbs (Symbol) -> self
+    def with_decorator: (Symbol) -> self
+
+    # @rbs () -> self
+    def with_instrumentation: () -> self
+
+    private
+
+    # @rbs (Namespace) -> either[Error, Store[V]]
+    def validate_and_build: (Namespace) -> either[Error, Store[V]]
+
+    # @rbs (Namespace) -> either[Error, Store[V]]
+    def create_store: (Namespace) -> either[Error, Store[V]]
+
+    # @rbs (Store[V]) -> either[Error, Store[V]]
+    def apply_decorators: (Store[V]) -> either[Error, Store[V]]
+  end
+end

data/sig/generated/typed_cache/cache_key.rbs

@@ -0,0 +1,33 @@
+# Generated from lib/typed_cache/cache_key.rb with RBS::Inline
+
+module TypedCache
+  class CacheKey
+    extend Forwardable
+
+    attr_reader namespace: Namespace
+
+    attr_reader key: String
+
+    # @rbs (Namespace, String) -> void
+    def initialize: (Namespace, String) -> void
+
+    # @rbs (Namespace) -> bool
+    def belongs_to?: (Namespace) -> bool
+
+    # @rbs () -> String
+    def to_s: () -> String
+
+    alias cache_key to_s
+
+    # @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/cache_ref.rbs

@@ -0,0 +1,91 @@
+# Generated from lib/typed_cache/cache_ref.rb with RBS::Inline
+
+module TypedCache
+  # A monadic wrapper for cached values that provides safe access with rich error context.
+  # All operations return Either[Error, Snapshot[V]] to provide detailed information about
+  # cache operations and the source of values.
+  #
+  # @rbs generic V
+  class CacheRef[V]
+    attr_reader store: Store[V]
+
+    attr_reader key: CacheKey
+
+    # : (Store[V], CacheKey) -> void
+    def initialize: (Store[V], CacheKey) -> void
+
+    # Gets a value from the cache as a snapshot
+    # : -> either[Error, Snapshot[V]]
+    def get: () -> 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]]
+
+    # Deletes the value from the cache and returns the deleted value as a snapshot
+    # : -> either[Error, Snapshot[V]]
+    def delete: () -> either[Error, Snapshot[V]]
+
+    # Fetches a value from cache, computing and storing it if not found
+    # The snapshot indicates whether the value came from cache or was computed
+    # : () { -> V } -> either[Error, Snapshot[V]]
+    def fetch: () { () -> V } -> either[Error, Snapshot[V]]
+
+    # Checks if the cache contains a value for this key
+    # : -> bool
+    def present?: () -> bool
+
+    # Checks if the cache is empty for this key
+    # : -> bool
+    def empty?: () -> bool
+
+    # Maps over the cached value if it exists, preserving snapshot metadata
+    # : [R] () { (V) -> R } -> either[Error, Snapshot[R]]
+    def map: [R] () { (V) -> R } -> either[Error, Snapshot[R]]
+
+    # Binds over the cached value, allowing for monadic composition with snapshots
+    # : [R] () { (V) -> either[Error, R] } -> either[Error, Snapshot[R]]
+    def bind: [R] () { (V) -> either[Error, R] } -> either[Error, Snapshot[R]]
+
+    alias flat_map bind
+
+    # Updates the cached value using the provided block
+    # Returns the updated value as a snapshot with source=:updated
+    # : () { (V) -> V } -> either[Error, Snapshot[V]]
+    def update: () { (V) -> V } -> either[Error, Snapshot[V]]
+
+    # Returns the cached value or a default if the cache is empty/errored
+    # : (V) -> V
+    def value_or: (V) -> V
+
+    # Returns a Maybe containing the cached value, or None if not present
+    # This provides a more functional approach than value_or
+    # : -> maybe[V]
+    def value_maybe: () -> maybe[V]
+
+    # Computes and caches a value if the cache is currently empty
+    # Returns existing snapshot if present, computed snapshot if cache miss, error otherwise
+    # : () { -> V } -> either[Error, Snapshot[V]]
+    def compute_if_absent: () { () -> V } -> either[Error, Snapshot[V]]
+
+    # Creates a new CacheRef with the same store but different key
+    # : [R] (String) -> CacheRef[R]
+    def with_key: [R] (String) -> CacheRef[R]
+
+    # Creates a scoped CacheRef by appending to the current key path
+    # : [R] (String) -> CacheRef[R]
+    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
+
+    # Convenience method to work with the snapshot directly
+    # : [R] () { (Snapshot[V]) -> R } -> either[Error, R]
+    def with_snapshot: [R] () { (Snapshot[V]) -> R } -> either[Error, R]
+
+    # Convenience method to work with just the value (losing snapshot context)
+    # : [R] () { (V) -> R } -> either[Error, R]
+    def with: [R] () { (V) -> R } -> either[Error, R]
+  end
+end

data/sig/generated/typed_cache/clock.rbs

@@ -0,0 +1,15 @@
+# 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.
+    # @rbs () -> Time
+    def self.moment: () -> Time
+  end
+end

data/sig/generated/typed_cache/decorator.rbs

@@ -0,0 +1,14 @@
+# Generated from lib/typed_cache/decorator.rb with RBS::Inline
+
+module TypedCache
+  # Marker mixin for cache store decorators. A decorator behaves exactly like a
+  # Store but must accept another Store instance in its constructor.
+  # @rbs generic V
+  module Decorator[V]
+    include Store[V]
+
+    include Store::_Store[V]
+
+    include Store::_Decorator[V]
+  end
+end

data/sig/generated/typed_cache/decorators.rbs

@@ -0,0 +1,25 @@
+# Generated from lib/typed_cache/decorators.rb with RBS::Inline
+
+module TypedCache
+  # Holds store decorators (e.g., instrumentation wrappers) that can be composed
+  # by the CacheBuilder. Decorators must conform to the same API as the wrapped
+  # store (see `TypedCache::Store`) and accept the store instance as their first
+  # constructor argument.
+  #
+  # Example:
+  #   Decorators.register(:my_decorator, MyDecorator)
+  #   cache = TypedCache.builder
+  #              .with_backend { |reg, ns| reg.resolve(:memory, ns).value }
+  #              .with_decorator(:my_decorator)
+  #              .build.value
+  module Decorators
+    # Default decorator set – starts with instrumentation only, but this registry
+    # lets end-users register their own via `Decorators.register`.
+    REGISTRY: untyped
+
+    extend Forwardable
+
+    # @rbs () -> Registry[Store[untyped]]
+    def self.registry: () -> Registry[Store[untyped]]
+  end
+end