typed_cache 0.2.0 → 0.3.0

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/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.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,10 +80,13 @@ 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
 
@@ -81,8 +96,8 @@ module TypedCache
 
     # 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
 

data/typed_cache.gemspec

@@ -39,5 +39,5 @@ Gem::Specification.new do |spec|
   spec.add_dependency('multi_json', '~> 1.17')
 
   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.2.0
+  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-08-06 00:00:00.000000000 Z
+date: 2025-08-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: concurrent-ruby
@@ -159,10 +159,32 @@ files:
 - 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/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
@@ -186,6 +208,7 @@ files:
 - 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
@@ -197,7 +220,7 @@ 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#020
+  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