typed_cache 0.1.1

data/lib/typed_cache/backends/memory.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require 'singleton'
+require 'forwardable'
+
+module TypedCache
+  class MemoryStoreRegistry
+    include Singleton
+    extend Forwardable
+
+    def_delegators :@backing_store, :[], :[]=, :delete, :key?, :keys
+
+    #: -> void
+    def initialize
+      @backing_store = Concurrent::Map.new
+    end
+  end
+
+  module Backends
+    # A type-safe memory store implementation with built-in namespacing
+    # @rbs generic V
+    class Memory
+      include Backend #[V]
+
+      # @rbs!
+      #   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 < Dry::Struct
+        attribute :value, Dry.Types::Any
+        attribute :expires_at, Dry.Types::Time
+
+        # @rbs! attr_accessor expires_at: Time
+        # @rbs! attr_reader value: V
+
+        # @rbs (value: V, expires_in: Integer) -> Entry[V]
+        def self.expiring(value:, expires_in:)
+          new(value: value, expires_at: Clock.moment + expires_in)
+        end
+
+        # @rbs () -> bool
+        def expired?
+          Clock.moment >= expires_at
+        end
+      end
+      private_constant :Entry
+
+      attr_reader :namespace, :ttl #: Namespace, Integer
+      attr_reader :backing_store #: hash_like[CacheKey, Entry[V]]
+
+      #: (Namespace, shared: bool, ttl: Integer) -> void
+      def initialize(namespace, shared: false, ttl: 600)
+        @namespace = namespace
+        @ttl = ttl
+        @backing_store = shared ? MemoryStoreRegistry.instance : {}
+      end
+
+      # @rbs override
+      #: (cache_key) -> either[Error, Snapshot[V]]
+      def get(key)
+        key = namespaced_key(key)
+        return Either.left(CacheMissError.new(key)) unless backing_store.key?(key)
+
+        entry = backing_store[key]
+
+        if entry.expired?
+          backing_store.delete(key)
+          return Either.left(CacheMissError.new(key))
+        end
+
+        Either.right(Snapshot.new(entry.value, source: :cache))
+      end
+
+      # @rbs override
+      #: (cache_key, V) -> either[Error, Snapshot[V]]
+      def set(key, value)
+        key = namespaced_key(key)
+        expires_at = Clock.moment + @ttl
+        entry = Entry.new(value: value, expires_at: expires_at)
+        backing_store[key] = entry
+        Either.right(Snapshot.new(value, source: :cache))
+      rescue => e
+        Either.left(StoreError.new(
+          :set,
+          key,
+          "Failed to store value for key '#{key}': #{e.message}",
+          e,
+        ))
+      end
+
+      # @rbs override
+      #: (cache_key) -> either[Error, Snapshot[V]]
+      def delete(key)
+        key = namespaced_key(key)
+        entry = backing_store.delete(key)
+        if entry.nil?
+          Either.left(CacheMissError.new(key))
+        else
+          Either.right(Snapshot.new(entry.value, source: :cache))
+        end
+      end
+
+      # @rbs override
+      #: (cache_key) -> bool
+      def key?(key)
+        key = namespaced_key(key)
+        return false unless backing_store.key?(key) && key.belongs_to?(namespace)
+
+        entry = backing_store[key]
+        !entry.expired?
+      end
+
+      # @rbs override
+      #: -> maybe[Error]
+      def clear
+        keys_to_delete = backing_store.keys.select { |k| k.belongs_to?(namespace) }
+        keys_to_delete.each { |key| backing_store.delete(key) }
+        Maybe.none
+      rescue => e
+        Maybe.some(e)
+      end
+
+      # @rbs override
+      #: -> String
+      def store_type
+        'memory'
+      end
+
+      #: -> Integer
+      def size
+        purge_expired_keys
+        backing_store.keys.count { |k| k.belongs_to?(namespace) }
+      end
+
+      #: -> Array[CacheKey]
+      def keys
+        purge_expired_keys
+        backing_store.keys
+          .select { |k| k.belongs_to?(namespace) }
+      end
+
+      private
+
+      #: -> Hash[CacheKey, Entry[V]]
+      def namespaced_entries
+        backing_store.select { |key, _entry| key.belongs_to?(namespace) }
+      end
+
+      #: -> void
+      def purge_expired_keys
+        namespaced_entries.each do |key, entry|
+          backing_store.delete(key) if entry.expired?
+        end
+      end
+    end
+  end
+end

data/lib/typed_cache/backends.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+require 'dry/struct'
+require 'dry/types'
+
+require_relative 'backends/memory'
+require_relative 'backends/active_support'
+
+module TypedCache
+  module Backends
+    # Backend registry using composition
+    REGISTRY = Registry.new('backend', {
+      memory: Memory,
+      active_support: ActiveSupport,
+    }).freeze
+
+    private_constant :REGISTRY
+
+    class << self
+      extend Forwardable
+      delegate [:resolve, :register, :available, :registered?] => :registry
+
+      #: -> Registry
+      def registry = REGISTRY
+
+      # Convenience method delegating to registry
+      # @rbs!
+      #   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
+end

data/lib/typed_cache/cache_builder.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module TypedCache
+  class CacheBuilder
+    # @rbs! type config = TypedCache::typed_cache_config
+
+    # @rbs (config, Registry[backend[untyped]], Registry[decorator[untyped]]) -> void
+    def initialize(config, backend_registry = Backends, decorator_registry = Decorators)
+      @config = config
+      @backend_registry = backend_registry
+      @decorator_registry = decorator_registry
+
+      @backend_name = nil
+      @backend_args = []
+      @backend_options = {}
+      @decorators = []
+    end
+
+    # Builds the cache - the only method that can fail
+    # @rbs (?Namespace) -> either[Error, Store[V]]
+    def build(namespace = Namespace.at(@config.default_namespace))
+      validate_and_build(namespace)
+    end
+
+    # Familiar Ruby fluent interface - always succeeds
+    # Invalid configurations are caught during build()
+    # @rbs (Symbol, *untyped, **untyped) -> self
+    def with_backend(name, *args, **options)
+      @backend_name = name
+      @backend_args = args
+      @backend_options = options
+      self
+    end
+
+    # Adds an arbitrary decorator by registry key
+    # @rbs (Symbol) -> self
+    def with_decorator(name)
+      @decorators << name
+      self
+    end
+
+    # @rbs () -> self
+    def with_instrumentation
+      with_decorator(:instrumented)
+    end
+
+    private
+
+    # @rbs (Namespace) -> either[Error, Store[V]]
+    def validate_and_build(namespace)
+      create_store(namespace).bind do |store|
+        apply_decorators(store)
+      end
+    end
+
+    # @rbs (Namespace) -> either[Error, Store[V]]
+    def create_store(namespace)
+      return Either.left(ArgumentError.new('Backend not configured')) unless @backend_name
+
+      # Prepend namespace to the arguments for the backend constructor
+      @backend_registry.resolve(@backend_name, namespace, *@backend_args, **@backend_options)
+    end
+
+    # @rbs (Store[V]) -> either[Error, Store[V]]
+    def apply_decorators(store)
+      return Either.right(store) if @decorators.empty?
+
+      @decorators.reduce(Either.right(store)) do |result, decorator_name|
+        result.bind do |current_store|
+          @decorator_registry.resolve(decorator_name, current_store)
+        end
+      end
+    rescue => e
+      Either.left(StoreError.new(:decorator_application, 'decorator', "Failed to apply decorator: #{e.message}", e))
+    end
+  end
+end

data/lib/typed_cache/cache_key.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module TypedCache
+  class CacheKey
+    extend Forwardable
+
+    attr_reader :namespace #: Namespace
+    attr_reader :key       #: String
+
+    # @rbs (Namespace, String) -> void
+    def initialize(namespace, key)
+      @namespace = namespace
+      @key = key
+    end
+
+    # @rbs (Namespace) -> bool
+    def belongs_to?(namespace)
+      @namespace.to_s.start_with?(namespace.to_s)
+    end
+
+    # @rbs () -> String
+    def to_s
+      "#{@namespace}:#{@key}"
+    end
+
+    alias cache_key to_s
+
+    # @rbs () -> String
+    def inspect
+      "#<#{self.class} namespace=#{@namespace} key=#{@key}>"
+    end
+
+    # @rbs () -> Integer
+    def hash
+      [@namespace, @key].hash
+    end
+
+    # @rbs (Object) -> bool
+    def ==(other)
+      other.is_a?(self.class) && other.namespace == @namespace && other.key == @key
+    end
+
+    alias eql? ==
+  end
+end

data/lib/typed_cache/cache_ref.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+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
+    attr_reader :store #: Store[V]
+    attr_reader :key #: CacheKey
+
+    #: (Store[V], CacheKey) -> void
+    def initialize(store, key)
+      @store = store
+      @key = key
+    end
+
+    # Gets a value from the cache as a snapshot
+    #: -> either[Error, Snapshot[V]]
+    def get
+      store.get(key)
+    end
+
+    # Sets a value in the cache and returns it as an updated snapshot
+    #: (V) -> either[Error, Snapshot[V]]
+    def set(value)
+      store.set(key, value)
+    end
+
+    # Deletes the value from the cache and returns the deleted value as a snapshot
+    #: -> either[Error, Snapshot[V]]
+    def delete
+      store.delete(key)
+    end
+
+    # 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(&block)
+      store.fetch(key, &block)
+    end
+
+    # Checks if the cache contains a value for this key
+    #: -> bool
+    def present?
+      store.get(key).right?
+    end
+
+    # Checks if the cache is empty for this key
+    #: -> bool
+    def empty?
+      store.get(key).left?
+    end
+
+    # Maps over the cached value if it exists, preserving snapshot metadata
+    #: [R] () { (V) -> R } -> either[Error, Snapshot[R]]
+    def map(&block)
+      get.map { |snapshot| snapshot.map(&block) }
+    end
+
+    # Binds over the cached value, allowing for monadic composition with snapshots
+    #: [R] () { (V) -> either[Error, R] } -> either[Error, Snapshot[R]]
+    def bind(&block)
+      get.bind { |snapshot| snapshot.bind(&block) }
+    end
+
+    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(&block)
+      get.bind do |snapshot|
+        new_value = yield(snapshot.value)
+        set(new_value)
+      rescue => e
+        Either.left(StoreError.new(
+          :update,
+          key,
+          "Failed to update value: #{e.message}",
+          e,
+        ))
+      end
+    end
+
+    # Returns the cached value or a default if the cache is empty/errored
+    #: (V) -> V
+    def value_or(default)
+      get.fold(
+        ->(_error) { default },
+        ->(snapshot) { snapshot.value },
+      )
+    end
+
+    # 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
+      get.fold(
+        ->(_error) { Maybe.none },
+        ->(snapshot) { Maybe.some(snapshot.value) },
+      )
+    end
+
+    # 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(&block)
+      fetch(&block).fold(
+        ->(error) {
+          Either.left(StoreError.new(
+            :compute_if_absent,
+            key,
+            "Failed to compute value: #{error.message}",
+            error,
+          ))
+        },
+        ->(snapshot) { Either.right(snapshot) },
+      )
+    end
+
+    # Creates a new CacheRef with the same store but different key
+    #: [R] (String) -> CacheRef[R]
+    def with_key(new_key)
+      CacheRef.new(store, store.namespace.key(new_key))
+    end
+
+    # Creates a scoped CacheRef by appending to the current key path
+    #: [R] (String) -> CacheRef[R]
+    def scope(scope_key)
+      new_namespace = store.namespace.nested(key.key)
+      new_store = store.with_namespace(new_namespace)
+      CacheRef.new(new_store, new_namespace.key(scope_key))
+    end
+
+    # Pattern matching support for Either[Error, Snapshot[V]] results
+    #: [R] () { (Error) -> R } () { (Snapshot[V]) -> R } -> R
+    def fold(left_fn, right_fn)
+      get.fold(left_fn, right_fn)
+    end
+
+    # Convenience method to work with the snapshot directly
+    #: [R] () { (Snapshot[V]) -> R } -> either[Error, R]
+    def with_snapshot(&block)
+      get.map(&block)
+    end
+
+    # Convenience method to work with just the value (losing snapshot context)
+    #: [R] () { (V) -> R } -> either[Error, R]
+    def with(&block)
+      get.map { |snapshot| yield(snapshot.value) }
+    end
+  end
+end

data/lib/typed_cache/clock.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+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
+    class << self
+      # 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 moment
+        if Time.respond_to?(:current)
+          Time.current
+        else
+          Time.now
+        end
+      end
+    end
+  end
+end

data/lib/typed_cache/decorator.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+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
+    include Store #[V]
+    # @rbs! include Store::_Store[V]
+    # @rbs! include Store::_Decorator[V]
+  end
+end

data/lib/typed_cache/decorators.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+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 = Registry.new('decorator', {
+      instrumented: Store::Instrumented,
+    }).freeze
+
+    private_constant :REGISTRY
+
+    class << self
+      extend Forwardable
+
+      # Delegate common registry helpers
+      delegate [:resolve, :register, :available, :registered?] => :registry
+
+      # @rbs () -> Registry[Store[untyped]]
+      def registry = REGISTRY
+    end
+  end
+end

data/lib/typed_cache/either.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+module TypedCache
+  # @rbs! type either[out E, out R] = (Left[E] | Right[R]) & _Either[E, R]
+
+  module Either
+    include Kernel
+
+    class << self
+      #: [E] (E) -> either[E, bot]
+      def left(error) = Left.new(error)
+      #: [R] (R) -> either[bot, R]
+      def right(value) = Right.new(value)
+
+      #: [E, R] (E | R) -> either[E, R]
+      def wrap(value, error_class = StandardError)
+        case value
+        when Left, Right then value
+        when error_class then Left.new(value)
+        else
+          Right.new(value)
+        end
+      end
+    end
+  end
+
+  # @rbs! 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
+    # @rbs! include _Either[E, bot]
+
+    attr_reader :error #: E
+
+    #: (E) -> void
+    def initialize(error)
+      @error = error
+    end
+
+    # @rbs override
+    #: -> true
+    def left? = true
+
+    # @rbs override
+    #: -> false
+    def right? = false
+
+    # @rbs override
+    #: [T] () { (R) -> T } -> either[E, T]
+    def map(&) = self
+
+    # @rbs override
+    #: [E2, R2] () { (R) -> either[E2, R2] } -> either[E | E2, R2]
+    def bind(&) = self
+
+    # @rbs override
+    #: [F] () { (E) -> F } -> either[F, R]
+    def map_left(&) = Left.new(yield(error))
+
+    # @rbs override
+    #: [T, E, R] (^(E) -> T, ^(R) -> T) -> T
+    def fold(left_fn, right_fn)
+      left_fn.call(error)
+    end
+
+    #: (Array[top]) -> ({ error: E })
+    def deconstruct_keys(keys)
+      { error: }
+    end
+  end
+
+  # @rbs generic out R
+  class Right
+    # @rbs! include _Either[bot, R]
+
+    attr_reader :value #: R
+
+    #: (R) -> void
+    def initialize(value)
+      @value = value
+    end
+
+    # @rbs override
+    #: -> false
+    def left? = false
+
+    # @rbs override
+    #: -> true
+    def right? = true
+
+    # @rbs override
+    #: [T] () { (R) -> T } -> either[E, T]
+    def map(&) = Right.new(yield(value))
+
+    # @rbs override
+    #: [E2, R2] () { (R) -> either[E2, R2] } -> either[E | E2, R2]
+    def bind(&) = yield(value)
+
+    # @rbs override
+    #: [F] () { (E) -> F } -> either[F, R]
+    def map_left(&) = self
+
+    # @rbs override
+    #: [T, E, R] (^(E) -> T, ^(R) -> T) -> T
+    def fold(left_fn, right_fn)
+      right_fn.call(value)
+    end
+
+    #: (Array[top]) -> ({ value: R })
+    def deconstruct_keys(keys)
+      { value: }
+    end
+  end
+end