typed_cache 0.3.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52137d39af663110c085558e5d6885fbe22d02b4a185f7a1ef3f4aa2dbe6a619
-  data.tar.gz: 030bf378a6effe782ab28fdb876c64c73d8997e5a3a9ec543735abe55973e421
+  metadata.gz: 68662a3e64b70950b86c466f7435aa4dc0ba5c31a87637244ece41685aa2cc00
+  data.tar.gz: 07fae7547c15ca5e7bfd900f9f74bb2f40443102bca143ce0f8cee8dc79c4069
 SHA512:
-  metadata.gz: 38641da2ef43033f286833d84492b02f09dcfca291e7eab53c93bf6c9f737de5f077984a4f742de06c62a0c90db19d00bbc03cb032485143e9a542576fb5f90c
-  data.tar.gz: 2fb8cd40d84bb43a3f9905ccc7c0d30d853cdf0b030cf192a6e17517545ac94f256a3371f85bcd068e4f08d12c7a32a937f8eb3a87622b8b3a16429e772bd8bb
+  metadata.gz: f81441fdceb975a4251d9f9d816cf71a40847e8ad1f9a3adea0d92075617ef0c9c85ed980b7707b9327221a75dc385459b954bd492e82ff08416fdb835fd6ba6
+  data.tar.gz: ef41b5392bb1f6adb0b2ccbf7f73ea6363c562b3e0621990f94c52445c048c598b9a0c875ad1d4ffaa03907576f68673614098281620d220ba96d6812b70531a

data/README.md

@@ -1,6 +1,6 @@
 # TypedCache
 
-![Gem Version](https://img.shields.io/gem/v/typed_cache?style=flat-square&logo=rubygems)
+[![Gem Version](https://img.shields.io/gem/v/typed_cache?style=flat-square&logo=rubygems)](https://rubygems.org/gems/typed_cache)
 ![GitHub Release Date](https://img.shields.io/github/release-date/glossawy/typed_cache?style=flat-square&label=released&logo=semanticrelease)
 ![GitHub last commit](https://img.shields.io/github/last-commit/glossawy/typed_cache?style=flat-square&logo=git)
 
@@ -88,7 +88,7 @@ TypedCache::Decorators.available # => [:instrumented]
 ```ruby
 class RedisBackend
   include TypedCache::Backend
-  # … implement #get, #set, etc.
+  # … implement #read, #write, etc.
 end
 
 TypedCache::Backends.register(:redis, RedisBackend)
@@ -98,9 +98,9 @@ TypedCache::Backends.register(:redis, RedisBackend)
 class LogDecorator
   include TypedCache::Decorator
   def initialize(store) = @store = store
-  def set(key, value)
-    puts "[cache] SET #{key}"
-    @store.set(key, value)
+  def write(key, value)
+    puts "[cache] WRITE #{key}"
+    @store.write(key, value)
   end
   # delegate the rest …
 end
@@ -127,7 +127,7 @@ result.fold(
 
 ## The `CacheRef` and `Store` APIs
 
-While you can call `get`, `set`, and `fetch` directly on the `store`, the more powerful way to work with TypedCache is via the `CacheRef` object. It provides a rich, monadic API for a single cache key. The `Store` also provides `fetch_all` for batch operations.
+While you can call `read`, `write`, and `fetch` directly on the `store`, the more powerful way to work with TypedCache is via the `CacheRef` object. It provides a rich, monadic API for a single cache key. The `Store` also provides `fetch_all` for batch operations.
 
 You get a `CacheRef` by calling `store.ref(key)`:
 
@@ -196,7 +196,7 @@ store = TypedCache.builder
   .build.value
 ```
 
-Events are published to a topic like `typed_cache.<operation>` (e.g., `typed_cache.get`). The topic namespace can be configured.
+Events are published to a topic like `typed_cache.<operation>` (e.g., `typed_cache.write`). The topic namespace can be configured.
 
 Payload keys include: `:namespace, :key, :operation, :duration`, and `cache_hit`.
 
@@ -204,13 +204,13 @@ You can subscribe to these events like so:
 
 ```ruby
 # Example for ActiveSupport
-ActiveSupport::Notifications.subscribe("typed_cache.get") do |name, start, finish, id, payload|
+ActiveSupport::Notifications.subscribe("typed_cache.write") do |name, start, finish, id, payload|
 
 # Or you can subscribe via the store object itself
 instrumenter = store.instrumenter
-instrumenter.subscribe("get") do |event|
+instrumenter.subscribe("write") do |event|
   payload = event.payload
-  puts "Cache GET for key #{payload[:key]} took #{payload[:duration]}ms. Hit? #{payload[:cache_hit]}"
+  puts "Cache WRITE for key #{payload[:key]} took #{payload[:duration]}ms. Hit? #{payload[:cache_hit]}"
 end
 ```
 

data/examples.md

@@ -19,7 +19,7 @@ users_store = builder.build(TypedCache::Namespace.at("users")).value
 user_ref = users_store.ref("123")
 
 # Set a value
-user_ref.set({ id: 123, name: "Jane" })
+user_ref.write({ id: 123, name: "Jane" })
 ```
 
 ## Rails Integration
@@ -51,7 +51,7 @@ result = TypedCache.builder
 
 case result
 in TypedCache::Either::Right(store)
-  store.set(store.namespace.key("greeting"), "Hello")
+  store.write(store.namespace.key("greeting"), "Hello")
 in TypedCache::Either::Left(error)
   warn "Failed to set up cache: #{error.message}"
 end
@@ -84,7 +84,7 @@ puts ns2.to_s # => "app:v1:users"
 
 # You can then build a store with this complex namespace
 user_store = base_builder.build(ns1).value
-user_store.ref("123").set({ name: "Deeply Nested" })
+user_store.ref("123").write({ name: "Deeply Nested" })
 ```
 
 ## CacheRef and Store APIs
@@ -95,12 +95,12 @@ The `CacheRef` is the most powerful way to interact with a single cache key, whi
 ref = store.ref("some-key") # => CacheRef
 ```
 
-### Get a value
+### Read a value
 
-The `get` method returns an `Either[Error, Snapshot]`.
+The `read` method returns an `Either[Error, Snapshot]`.
 
 ```ruby
-result = ref.get
+result = ref.read
 result.fold(
   ->(error)    { puts "Cache miss or error: #{error.message}" },
   ->(snapshot) { puts "Found: #{snapshot.value} (from cache: #{snapshot.from_cache?})" }
@@ -140,7 +140,7 @@ You can transform the value inside the cache reference without breaking the mona
 # user_ref holds { id: 1, name: "John" }
 name_ref = user_ref.map { |user| user[:name] }
 
-name_snapshot = name_ref.get.value # => Snapshot(value: "John", ...)
+name_snapshot = name_ref.read.value # => Snapshot(value: "John", ...)
 ```
 
 ### Chaining operations with `bind`
@@ -150,7 +150,7 @@ For more complex logic, you can use `bind` (or `flat_map`) to chain operations t
 ```ruby
 user_ref.bind do |user|
   if user.active?
-    posts_ref.set(user.posts)
+    posts_ref.write(user.posts)
   else
     TypedCache::Either.left(StandardError.new("User is not active"))
   end
@@ -178,12 +178,12 @@ class SimpleStore
     @data      = {}
   end
 
-  def get(key)
+  def read(key)
     value = @data[key]
     value ? TypedCache::Either.right(value) : TypedCache::Either.left(TypedCache::CacheMissError.new(key))
   end
 
-  def set(key, value)
+  def write(key, value)
     @data[key] = value
     TypedCache::Either.right(value)
   end
@@ -239,12 +239,12 @@ logging_cache = TypedCache.builder
   .build.value
 
 # Subscribe to an event
-logging_cache.instrumenter.subscribe("get")
+logging_cache.instrumenter.subscribe("write")
 
 # Operations will now be logged
-logging_cache.ref("test").set("hello")
-# => [CACHE] Starting: set for key test
-# => [CACHE] Finished: set for key test
+logging_cache.ref("test").write("hello")
+# => [CACHE] Starting: write for key test
+# => [CACHE] Finished: write for key test
 ```
 
 ## Thread Safety
@@ -257,7 +257,7 @@ shared_store = TypedCache.builder
   .build.value
 
 threads = 10.times.map do |i|
-  Thread.new { shared_store.set(shared_store.namespace.key(i.to_s), "data_") }
+  Thread.new { shared_store.write(shared_store.namespace.key(i.to_s), "data_") }
 end
 threads.each(&:join)
 ```
@@ -273,7 +273,7 @@ spec_store = TypedCache.builder
 
 RSpec.describe "cache" do
   it "stores data" do
-    result = spec_store.set(spec_store.namespace.key("id"), 1)
+    result = spec_store.write(spec_store.namespace.key("id"), 1)
     expect(result).to be_right
   end
 end

data/lib/typed_cache/backends/active_support.rb

@@ -19,10 +19,10 @@ module TypedCache
       end
 
       # @rbs override
-      #: (cache_key) -> either[Error, Snapshot[V]]
-      def read(key)
+      #: (cache_key, **top) -> either[Error, Snapshot[V]]
+      def read(key, **kwargs)
         cache_key_str = namespaced_key(key).to_s
-        raw_value = cache_store.read(cache_key_str, default_options)
+        raw_value = cache_store.read(cache_key_str, default_options.merge(**kwargs))
         return Either.left(CacheMissError.new(key)) if raw_value.nil?
 
         Either.right(Snapshot.cached(key, raw_value))
@@ -31,10 +31,10 @@ module TypedCache
       end
 
       # @rbs override
-      #: (cache_key, V) -> either[Error, Snapshot[V]]
-      def write(key, value)
+      #: (cache_key, V, **top) -> either[Error, Snapshot[V]]
+      def write(key, value, **kwargs)
         cache_key_str = namespaced_key(key).to_s
-        success = cache_store.write(cache_key_str, value, default_options)
+        success = cache_store.write(cache_key_str, value, default_options.merge(**kwargs))
 
         if success
           Either.right(Snapshot.cached(key, value))
@@ -46,9 +46,9 @@ module TypedCache
       end
 
       # @rbs override
-      #: (Hash[cache_key, V]) -> either[Error, Array[Snapshot[V]]]
-      def write_all(values)
-        results = cache_store.write_multi(values.map { |key, value| [namespaced_key(key).to_s, value] }.to_h, default_options)
+      #: (Hash[cache_key, V], **top) -> either[Error, Array[Snapshot[V]]]
+      def write_all(values, **kwargs)
+        results = cache_store.write_multi(values.map { |key, value| [namespaced_key(key).to_s, value] }.to_h, default_options.merge(**kwargs))
         Either.right(results.map { |key, value| Snapshot.cached(key, value) })
       rescue => e
         Either.left(StoreError.new(:set_all, values, "Failed to write to cache: #{e.message}", e))
@@ -70,20 +70,20 @@ module TypedCache
       end
 
       # @rbs override
-      #: (Array[cache_key]) -> either[Error, Array[Snapshot[V]]]
-      def read_all(keys)
-        results = cache_store.read_multi(*keys.map { |key| namespaced_key(key).to_s }, default_options)
+      #: (Array[cache_key], **top) -> either[Error, Array[Snapshot[V]]]
+      def read_all(keys, **kwargs)
+        results = cache_store.read_multi(*keys.map { |key| namespaced_key(key).to_s }, default_options.merge(**kwargs))
         Either.right(results.map { |key, value| [key, Snapshot.cached(key, value)] }.to_h)
       end
 
       # @rbs override
-      #: (Array[cache_key]) { (CacheKey) -> V? } -> either[Error, Array[Snapshot[V]]]
-      def fetch_all(keys, &block)
+      #: (Array[cache_key], **top) { (CacheKey) -> V? } -> either[Error, Array[Snapshot[V]]]
+      def fetch_all(keys, **kwargs, &block)
         cache_keys = keys.map { |key| namespaced_key(key) }
         key_map = cache_keys.index_by(&:to_s)
 
         computed_keys = Set.new #: Set[String]
-        results = cache_store.fetch_multi(*key_map.keys, default_options) do |key|
+        results = cache_store.fetch_multi(*key_map.keys, default_options.merge(**kwargs)) do |key|
           computed_keys << key
           yield(key_map[key])
         end

data/lib/typed_cache/backends/memory.rb

@@ -68,8 +68,8 @@ module TypedCache
       end
 
       # @rbs override
-      #: (cache_key) -> either[Error, Snapshot[V]]
-      def read(key)
+      #: (cache_key, **top) -> either[Error, Snapshot[V]]
+      def read(key, **kwargs)
         key = namespaced_key(key)
         return Either.left(CacheMissError.new(key)) unless backing_store.key?(key)
 
@@ -84,10 +84,9 @@ module TypedCache
       end
 
       # @rbs override
-      #: (cache_key, V) -> either[Error, Snapshot[V]]
-      def write(key, value)
+      #: (cache_key, V, expires_in: Integer, expires_at: Time, **top) -> either[Error, Snapshot[V]]
+      def write(key, value, expires_in: @ttl, expires_at: Clock.now + expires_in, **kwargs)
         key = namespaced_key(key)
-        expires_at = Clock.now + @ttl
         entry = Entry.new(value: value, expires_at: expires_at)
         backing_store[key] = entry
         Either.right(Snapshot.cached(key, value))

data/lib/typed_cache/store.rb

@@ -45,14 +45,14 @@ module TypedCache
     end
 
     # Retrieves a value from the cache
-    # @rbs (cache_key) -> either[Error, Snapshot[V]]
-    def read(key)
+    # @rbs (cache_key, **top) -> either[Error, Snapshot[V]]
+    def read(key, **kwargs)
       Either.left(NotImplementedError.new("#{self.class} must implement #read"))
     end
 
-    # @rbs (Array[cache_key]) -> either[Error, Hash[cache_key, Snapshot[V]]]
-    def read_all(keys)
-      keys.map { |key| read(key) }.reduce(Either.right({})) do |acc, result|
+    # @rbs (Array[cache_key], **top) -> either[Error, Hash[cache_key, Snapshot[V]]]
+    def read_all(keys, **kwargs)
+      keys.map { |key| read(key, **kwargs) }.reduce(Either.right({})) do |acc, result|
         acc.bind do |values|
           result.map { |value| values.merge(value.key => value) }
         end
@@ -66,14 +66,14 @@ module TypedCache
     end
 
     # Stores a value in the cache
-    # @rbs (cache_key, V) -> either[Error, Snapshot[V]]
-    def write(key, value)
+    # @rbs (cache_key, V, **top) -> either[Error, Snapshot[V]]
+    def write(key, value, **kwargs)
       Either.left(NotImplementedError.new("#{self.class} must implement #write"))
     end
 
-    # @rbs (Hash[cache_key, V]) -> either[Error, Hash[cache_key, Snapshot[V]]]
-    def write_all(values)
-      values.map { |key, value| write(key, value) }.reduce(Either.right({})) do |acc, result|
+    # @rbs (Hash[cache_key, V], **top) -> either[Error, Hash[cache_key, Snapshot[V]]]
+    def write_all(values, **kwargs)
+      values.map { |key, value| write(key, value, **kwargs) }.reduce(Either.right({})) do |acc, result|
         acc.bind do |values|
           result.map { |value| values.merge(value.key => value) }
         end
@@ -100,8 +100,8 @@ module TypedCache
 
     # Fetches a value from cache, computing and storing it if not found
     # This is an atomic operation that combines read and write
-    # @rbs (cache_key) { () -> V } -> either[Error, Snapshot[V]]
-    def fetch(key, &block)
+    # @rbs (cache_key, **top) { () -> V } -> either[Error, Snapshot[V]]
+    def fetch(key, **kwargs, &block)
       # Default implementation using read/write pattern
       read_result = read(key)
       return read_result if read_result.right?
@@ -112,19 +112,19 @@ module TypedCache
       # Compute and store new value
       begin
         computed_value = yield
-        write(key, computed_value)
+        write(key, computed_value, **kwargs)
         Either.right(Snapshot.computed(key, computed_value))
       rescue => e
         Either.left(StoreError.new(:fetch, key, "Failed to compute value for key '#{key}': #{e.message}", e))
       end
     end
 
-    # @rbs (Array[cache_key]) { (CacheKey) -> V } -> either[Error, Array[Snapshot[V]]]
-    def fetch_all(keys, &block)
+    # @rbs (Array[cache_key], **top) { (CacheKey) -> V } -> either[Error, Array[Snapshot[V]]]
+    def fetch_all(keys, **kwargs, &block)
       keys = keys.map { |key| namespaced_key(key) }
       keys.reduce(Either.right([])) do |acc, key|
         acc.bind do |values|
-          fetch(key) { yield(key) }.map { |value| values + [value] }
+          fetch(key. **kwargs) { yield(key) }.map { |value| values + [value] }
         end
       end
     end

data/lib/typed_cache/version.rb

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

data/rbi/typed_cache/store.rbi

@@ -12,17 +12,17 @@ module TypedCache
     Key = T.type_alias { T.any(String, ::TypedCache::CacheKey) }
     private_constant :Error, :Key
 
-    sig { params(key: Key).returns(::TypedCache::Either[Error, CachedType]) }
-    def read(key); end
+    sig { params(key: Key, kwargs: T::Hash[Symbol, T.untyped]).returns(::TypedCache::Either[Error, CachedType]) }
+    def read(key, **kwargs); end
 
-    sig { params(keys: T::Array[Key]).returns(::TypedCache::Either[Error, T::Array[::TypedCache::Snapshot[CachedType]]]) }
-    def read_all(keys); end
+    sig { params(keys: T::Array[Key], kwargs: T::Hash[Symbol, T.untyped]).returns(::TypedCache::Either[Error, T::Array[::TypedCache::Snapshot[CachedType]]]) }
+    def read_all(keys, **kwargs); end
 
-    sig { params(key: Key, value: CachedType).returns(::TypedCache::Either[Error, ::TypedCache::Snapshot[CachedType]]) }
-    def write(key, value); end
+    sig { params(key: Key, value: CachedType, kwargs: T::Hash[Symbol, T.untyped]).returns(::TypedCache::Either[Error, ::TypedCache::Snapshot[CachedType]]) }
+    def write(key, value, **kwargs); end
 
-    sig { params(values: T::Hash[Key, CachedType]).returns(::TypedCache::Either[Error, T::Array[::TypedCache::Snapshot[CachedType]]]) }
-    def write_all(values); end
+    sig { params(values: T::Hash[Key, CachedType], kwargs: T::Hash[Symbol, T.untyped]).returns(::TypedCache::Either[Error, T::Array[::TypedCache::Snapshot[CachedType]]]) }
+    def write_all(values, **kwargs); end
 
     sig { params(key: Key).returns(::TypedCache::Either[Error, ::TypedCache::Snapshot[CachedType]]) }
     def delete(key); end
@@ -36,11 +36,11 @@ module TypedCache
     sig { params(key: Key).returns(T::Boolean) }
     def key?(key); end
 
-    sig { params(key: Key, block: T.proc.returns(T.nilable(CachedType))).returns(::TypedCache::Either[Error, ::TypedCache::Snapshot[::TypedCache::Maybe[CachedType]]]) }
-    def fetch(key, &block); end
+    sig { params(key: Key, kwargs: T::Hash[Symbol, T.untyped], block: T.proc.returns(T.nilable(CachedType))).returns(::TypedCache::Either[Error, ::TypedCache::Snapshot[::TypedCache::Maybe[CachedType]]]) }
+    def fetch(key, **kwargs, &block); end
 
-    sig { params(keys: T::Array[Key], block: T.proc.params(key: ::TypedCache::CacheKey).returns(T.nilable(CachedType))).returns(::TypedCache::Either[Error, T::Array[::TypedCache::Snapshot[CachedType]]]) }
-    def fetch_all(keys, &block); end
+    sig { params(keys: T::Array[Key], kwargs: T::Hash[Symbol, T.untyped], block: T.proc.params(key: ::TypedCache::CacheKey).returns(T.nilable(CachedType))).returns(::TypedCache::Either[Error, T::Array[::TypedCache::Snapshot[CachedType]]]) }
+    def fetch_all(keys, **kwargs, &block); end
 
     sig { returns(::TypedCache::Namespace) }
     def namespace; end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: typed_cache
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.3.1
 platform: ruby
 authors:
 - Autumn Winter
@@ -220,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#030
+  changelog_uri: https://github.com/glossawy/typed_cache/blob/main/VERSIONS.adoc#031
   license_uri: https://github.com/glossawy/typed_cache/blob/main/LICENSE
   label: caching
   labels: typed_cache,ruby,caching,type-safety,rails,rbs