support_table_cache 1.1.2 → 1.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 96d5ff63c1cd08f7389bf3b409d0afc4f706f42bed958c7b3a7f2b592d391453
-  data.tar.gz: 76e59a449b9eeffd9df794f014abcbf324f4df2590e250817a4dd3b77467e5b5
+  metadata.gz: 5102ba8b7a75ecc7186dc527880ff0278f9e259b020fc8b36b8e3e72c4b0c150
+  data.tar.gz: ebf2696d9ea3917895038b35989d2c23c5b418db4f405c4b36812e6da59f7691
 SHA512:
-  metadata.gz: 970762a6cb7aaf507552dce376efbcf1da64feb54b261fa315aaff2fc8898b4b8d3db755690c3c09e57e4c615ac7ae23e334e8d1426613b59a800a34c55f6b52
-  data.tar.gz: deed3048a34f40d30aec7c902f09f265642e34a6e8108cca9db806929ab74ef57fd2f31d24b01dd892717a463e5c3bfdb1f6aaaf15b74d9b791d987560c2bc0f
+  metadata.gz: eae75a3e8afea4fcf9cff14fec02110ab0f332685bd912ca3f37fdd17baeeaa2db107824cbd0f6bec18acdf501815012476fd48f50d63b3a38c0767daae7cf98
+  data.tar.gz: 1be4a2c1013221d4af65eb26dbfd5e9c56eb130a4bdc94ce540854f11a3df7dd7526e264ba645f7e46340cd43de8bef8899837043031aeae8897e463113e4fc5

data/ARCHITECTURE.md

@@ -0,0 +1,386 @@
+# Support Table Cache Architecture
+
+This document describes the architecture and design of the `support_table_cache` gem, which provides automatic caching for ActiveRecord support table models.
+
+## Overview
+
+Support Table Cache is designed to optimize database queries for small lookup tables (support tables) that have:
+- Unique keys (e.g., unique `name` attribute)
+- Limited number of entries (a few hundred at most)
+- Rarely updated data but frequently queried
+- Used for data normalization (lookup tables)
+
+The gem automatically caches records when using `find_by` methods and `belongs_to` associations, eliminating redundant database queries.
+
+## High-Level Architecture
+
+```mermaid
+flowchart TB
+    subgraph "Application Layer"
+        App["Application Code"]
+        Models["ActiveRecord Models"]
+    end
+
+    subgraph "Support Table Cache Gem"
+        STC["SupportTableCache Module"]
+        Assoc["Associations Module"]
+        FindBy["FindByOverride"]
+        RelOverride["RelationOverride"]
+        MemCache["MemoryCache"]
+    end
+
+    subgraph "Cache Layer"
+        RC["Rails.cache / Custom Cache"]
+        MC["In-Memory Cache"]
+    end
+
+    subgraph "Database Layer"
+        DB["PostgreSQL/MySQL/SQLite"]
+    end
+
+    App --> Models
+    Models --> STC
+    STC --> FindBy
+    STC --> Assoc
+    STC --> RelOverride
+    STC --> MemCache
+
+    FindBy --> RC
+    FindBy --> MC
+    Assoc --> RC
+    Assoc --> MC
+    RelOverride --> RC
+    RelOverride --> MC
+
+    FindBy -.-> DB
+    Assoc -.-> DB
+    RelOverride -.-> DB
+
+    RC -.-> DB
+    MC -.-> DB
+
+    classDef appLayer fill:#e1f5fe
+    classDef cacheLayer fill:#fff3e0
+    classDef dbLayer fill:#f3e5f5
+    classDef gemLayer fill:#e8f5e8
+
+    class App,Models appLayer
+    class STC,Assoc,FindBy,RelOverride,MemCache gemLayer
+    class RC,MC cacheLayer
+    class DB dbLayer
+```
+
+## Core Components
+
+### 1. SupportTableCache Module
+
+The main module that provides caching functionality to ActiveRecord models.
+
+```mermaid
+flowchart LR
+    subgraph "SupportTableCache Module"
+        CM["Class Methods"]
+        IM["Instance Methods"]
+        CC["Cache Configuration"]
+        CCE["Cache Control & Expiry"]
+    end
+
+    subgraph "Class Methods"
+        CB["cache_by()"]
+        DC["disable_cache()"]
+        EC["enable_cache()"]
+        LC["load_cache()"]
+        SC["support_table_cache="]
+    end
+
+    subgraph "Instance Methods"
+        UC["uncache()"]
+        ClearCache["support_table_clear_cache_entries()"]
+    end
+
+    CM --> CB
+    CM --> DC
+    CM --> EC
+    CM --> LC
+    CM --> SC
+
+    IM --> UC
+    IM --> ClearCache
+
+    CB --> CC
+    SC --> CC
+    UC --> CCE
+    ClearCache --> CCE
+```
+
+### 2. Cache Key Generation Flow
+
+```mermaid
+sequenceDiagram
+    participant App as Application
+    participant Model as Model.find_by
+    participant Override as FindByOverride
+    participant Cache as Cache Store
+    participant DB as Database
+
+    App->>Model: Model.find_by(name: "example")
+    Model->>Override: Intercept find_by call
+
+    Override->>Override: Extract attributes from query
+    Override->>Override: Check cache_by_attributes config
+    Override->>Override: Generate cache key from attributes
+
+    alt Cache Hit
+        Override->>Cache: fetch(cache_key)
+        Cache-->>Override: Return cached record
+        Override-->>App: Return record
+    else Cache Miss
+        Override->>Cache: fetch(cache_key) with block
+        Cache->>DB: Execute original find_by query
+        DB-->>Cache: Return record from DB
+        Cache->>Cache: Store record with TTL
+        Cache-->>Override: Return record
+        Override-->>App: Return record
+    end
+```
+
+### 3. Cache Key Structure
+
+```mermaid
+flowchart TD
+    Attrs["Query Attributes<br/>{name: 'active', type: 'primary'}"]
+
+    subgraph "Key Generation Process"
+        Sort["Sort attribute names<br/>['name', 'type']"]
+        CaseCheck["Apply case sensitivity<br/>name: 'active' → 'active'<br/>type: 'primary' → 'primary'"]
+        KeyGen["Generate cache key<br/>['ModelName', {name: 'active', type: 'primary'}]"]
+    end
+
+    Attrs --> Sort
+    Sort --> CaseCheck
+    CaseCheck --> KeyGen
+
+    KeyGen --> CacheStore["Cache Store<br/>Key: ['Status', {name: 'active', type: 'primary'}]<br/>Value: #&lt;Status id: 1, name: 'active'&gt;"]
+```
+
+### 4. Association Caching Flow
+
+```mermaid
+sequenceDiagram
+    participant App as Application
+    participant Parent as Parent Model
+    participant Assoc as Association Reader
+    participant Cache as Cache Store
+    participant Child as Child Model
+    participant DB as Database
+
+    App->>Parent: parent.status
+    Parent->>Assoc: Call association reader
+
+    Assoc->>Assoc: Extract foreign key value
+    Assoc->>Assoc: Build cache key from foreign key
+
+    alt Cache Hit
+        Assoc->>Cache: fetch(cache_key)
+        Cache-->>Assoc: Return cached record
+        Assoc-->>App: Return associated record
+    else Cache Miss
+        Assoc->>Cache: fetch(cache_key) with block
+        Cache->>Child: Load association normally
+        Child->>DB: Query database
+        DB-->>Child: Return record
+        Child-->>Cache: Return record
+        Cache->>Cache: Store record with TTL
+        Cache-->>Assoc: Return record
+        Assoc-->>App: Return associated record
+    end
+```
+
+### 5. Cache Invalidation Strategy
+
+```mermaid
+flowchart TD
+    subgraph "Record Lifecycle Events"
+        Create["Record Created"]
+        Update["Record Updated"]
+        Delete["Record Deleted"]
+    end
+
+    subgraph "Cache Invalidation Process"
+        Hook["after_commit callback"]
+        ExtractKeys["Extract all cacheable<br/>attribute combinations"]
+        BuildKeys["Build cache keys for<br/>before & after states"]
+        ClearCache["Delete cache entries"]
+    end
+
+    subgraph "Cache Keys Cleared"
+        BeforeKeys["Keys with old values"]
+        AfterKeys["Keys with new values"]
+    end
+
+    Create --> Hook
+    Update --> Hook
+    Delete --> Hook
+
+    Hook --> ExtractKeys
+    ExtractKeys --> BuildKeys
+    BuildKeys --> ClearCache
+
+    ClearCache --> BeforeKeys
+    ClearCache --> AfterKeys
+```
+
+### 6. Cache Implementation Types
+
+```mermaid
+flowchart LR
+    subgraph "Cache Types"
+        subgraph "External Cache"
+            RC["Rails.cache<br/>(Redis/Memcached)"]
+            CC["Custom Cache Store"]
+        end
+
+        subgraph "In-Memory Cache"
+            MC["MemoryCache<br/>(Process-local)"]
+        end
+    end
+
+    subgraph "Configuration"
+        Global["Global Cache<br/>SupportTableCache.cache = store"]
+        PerClass["Per-Class Cache<br/>Model.support_table_cache = :memory"]
+        Testing["Test Mode<br/>SupportTableCache.testing!"]
+    end
+
+    Global --> RC
+    Global --> CC
+    PerClass --> MC
+    Testing --> MC
+
+    subgraph "Trade-offs"
+        ExtPros["✓ Shared across processes<br/>✓ Automatic invalidation<br/>✓ TTL support"]
+        ExtCons["✗ Network overhead<br/>✗ Serialization cost"]
+
+        MemPros["✓ Ultra-fast access<br/>✓ No network overhead<br/>✓ No serialization"]
+        MemCons["✗ Per-process storage<br/>✗ Manual invalidation<br/>✗ Memory usage"]
+    end
+
+    RC -.-> ExtPros
+    CC -.-> ExtPros
+    RC -.-> ExtCons
+    CC -.-> ExtCons
+
+    MC -.-> MemPros
+    MC -.-> MemCons
+```
+
+### 7. Testing Integration
+
+```mermaid
+flowchart TD
+    subgraph "Test Execution"
+        TestStart["Test Begins"]
+        TestCode["Test Code Execution"]
+        TestEnd["Test Ends"]
+    end
+
+    subgraph "Cache Isolation"
+        TestCache["Isolated Test Cache<br/>(MemoryCache per test)"]
+        CleanSlate["Clean State<br/>(No cache pollution)"]
+    end
+
+    TestStart --> TestCache
+    TestCache --> TestCode
+    TestCode --> CleanSlate
+    CleanSlate --> TestEnd
+
+    subgraph "Integration Pattern"
+        RSpecWrap["RSpec around hook<br/>SupportTableCache.testing!"]
+        MiniTestWrap["MiniTest around hook<br/>SupportTableCache.testing!"]
+    end
+
+    RSpecWrap -.-> TestCache
+    MiniTestWrap -.-> TestCache
+```
+
+## Configuration Patterns
+
+### Model Setup
+
+```ruby
+class Status < ApplicationRecord
+  include SupportTableCache
+
+  # Cache by single unique attribute
+  cache_by :name, case_sensitive: false
+
+  # Cache by composite unique key
+  cache_by [:group, :name]
+
+  # Cache by id (for associations)
+  cache_by :id
+
+  # Optional: Set TTL for cache entries
+  self.support_table_cache_ttl = 5.minutes
+
+  # Optional: Use in-memory cache
+  self.support_table_cache = :memory
+end
+```
+
+### Association Setup
+
+```ruby
+class Order < ApplicationRecord
+  include SupportTableCache::Associations
+
+  belongs_to :status
+  cache_belongs_to :status
+end
+```
+
+## Performance Benefits
+
+### Query Elimination
+
+```mermaid
+sequenceDiagram
+    participant App as Application
+    participant Cache as Cache
+    participant DB as Database
+
+    Note over App,DB: Without Cache
+    App->>DB: Status.find_by(name: 'active')
+    DB-->>App: Record
+    App->>DB: Status.find_by(name: 'active')
+    DB-->>App: Same Record (redundant query)
+    App->>DB: Status.find_by(name: 'active')
+    DB-->>App: Same Record (redundant query)
+
+    Note over App,DB: With Cache
+    App->>Cache: Status.find_by(name: 'active')
+    Cache->>DB: First query only
+    DB-->>Cache: Record
+    Cache-->>App: Record
+    App->>Cache: Status.find_by(name: 'active')
+    Cache-->>App: Record (from cache)
+    App->>Cache: Status.find_by(name: 'active')
+    Cache-->>App: Record (from cache)
+```
+
+## Design Principles
+
+1. **Transparent Integration**: No code changes required beyond configuration
+2. **Selective Caching**: Only caches queries that match configured unique keys
+3. **Automatic Invalidation**: Cache entries are cleared when records change
+4. **Flexible Cache Backends**: Supports various cache stores including in-memory
+5. **Test Isolation**: Provides testing utilities to prevent cache pollution
+6. **Performance Optimization**: Minimizes database queries for frequently accessed lookup data
+
+## Use Cases
+
+- **Status/Type Tables**: Small enums stored in database tables
+- **Configuration Tables**: Application settings and parameters
+- **Reference Data**: Countries, states, categories, etc.
+- **Lookup Tables**: Any small, rarely-changing reference data
+
+This architecture enables significant performance improvements for applications that heavily query small support tables while maintaining data consistency and providing flexible caching options.

data/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 1.1.4
+
+### Fixed
+
+- Fixed issue where using `find_by` on a `has_many` relation would not take the scope of the relation into account when looking up the cached record. Now chaining a `find_by` onto a `has_many` relation will correctly bypass the cache and directly query the database.
+
+## 1.1.3
+
+### Fixed
+- Avoid calling methods that require a database connection when setting up belongs to caching.
+
 ## 1.1.2
 
 ### Fixed

data/README.md

@@ -2,6 +2,7 @@
 
 [![Continuous Integration](https://github.com/bdurand/support_table_cache/actions/workflows/continuous_integration.yml/badge.svg)](https://github.com/bdurand/support_table_cache/actions/workflows/continuous_integration.yml)
 [![Ruby Style Guide](https://img.shields.io/badge/code_style-standard-brightgreen.svg)](https://github.com/testdouble/standard)
+[![Gem Version](https://badge.fury.io/rb/support_table_cache.svg)](https://badge.fury.io/rb/support_table_cache)
 
 This gem adds caching for ActiveRecord support table models. These models have a unique key (i.e. a unique `name` attribute, etc.) and a limited number of entries (a few hundred at most). These are often models added to normalize the data structure and are also known as lookup tables.
 

data/VERSION

@@ -1 +1 @@
-1.1.2
+1.1.4

data/lib/support_table_cache/associations.rb

@@ -14,7 +14,7 @@ module SupportTableCache
       #
       # @param association_name [Symbol, String] The association name to cache.
       # @return [void]
-      # @raise ArgumentError if the association is not defined or if it has a runtime scope.
+      # @raise [ArgumentError] if the association is not defined or if it has a runtime scope.
       def cache_belongs_to(association_name)
         reflection = reflections[association_name.to_s]
 
@@ -26,13 +26,21 @@ module SupportTableCache
           raise ArgumentError.new("Cannot cache belongs_to #{association_name} association because it has a scope")
         end
 
+        define_belongs_to_with_cache(association_name.to_s)
+      end
+
+      private
+
+      def define_belongs_to_with_cache(association_name)
         class_eval <<~RUBY, __FILE__, __LINE__ + 1
           def #{association_name}_with_cache
-            foreign_key = self.send(#{reflection.foreign_key.inspect})
+            reflection = self.class.reflections[#{association_name.inspect}]
+            foreign_key = self.send(reflection.foreign_key)
             return nil if foreign_key.nil?
-            key = [#{reflection.class_name.inspect}, {#{reflection.association_primary_key.inspect} => foreign_key}]
-            cache = #{reflection.class_name}.send(:current_support_table_cache)
-            ttl = #{reflection.class_name}.send(:support_table_cache_ttl)
+
+            key = [reflection.class_name, {reflection.association_primary_key => foreign_key}]
+            cache = reflection.klass.send(:current_support_table_cache)
+            ttl = reflection.klass.send(:support_table_cache_ttl)
             if cache
               cache.fetch(key, expires_in: ttl) do
                 #{association_name}_without_cache

data/lib/support_table_cache/find_by_override.rb

@@ -39,7 +39,8 @@ module SupportTableCache
     # Same as find_by, but performs a safety check to confirm the query will hit the cache.
     #
     # @param attributes [Hash] Attributes to find the record by.
-    # @raise ArgumentError if the query cannot use the cache.
+    # @return [ActiveRecord::Base, nil] The found record or nil if not found.
+    # @raise [ArgumentError] if the query cannot use the cache.
     def fetch_by(attributes)
       find_by_attribute_names = support_table_find_by_attribute_names(attributes)
       unless support_table_cache_by_attributes.any? { |attribute_names, _ci, _where| attribute_names == find_by_attribute_names }
@@ -51,8 +52,9 @@ module SupportTableCache
     # Same as find_by!, but performs a safety check to confirm the query will hit the cache.
     #
     # @param attributes [Hash] Attributes to find the record by.
-    # @raise ArgumentError if the query cannot use the cache.
-    # @raise ActiveRecord::RecordNotFound if no record is found.
+    # @return [ActiveRecord::Base] The found record.
+    # @raise [ArgumentError] if the query cannot use the cache.
+    # @raise [ActiveRecord::RecordNotFound] if no record is found.
     def fetch_by!(attributes)
       value = fetch_by(attributes)
       if value.nil?

data/lib/support_table_cache/memory_cache.rb

@@ -8,11 +8,20 @@ module SupportTableCache
   # This cache will not store nil values. This is to prevent the cache from filling up with
   # cache misses because there is no purging mechanism.
   class MemoryCache
+    # Create a new memory cache.
+    #
+    # @return [SupportTableCache::MemoryCache]
     def initialize
       @cache = {}
       @mutex = Mutex.new
     end
 
+    # Fetch a value from the cache. If the key is not found or has expired, yields to get a new value.
+    #
+    # @param key [Object] The cache key.
+    # @param expires_in [Integer, nil] Time in seconds until the cached value expires.
+    # @yield Block to execute to get a new value if the key is not cached.
+    # @return [Object, nil] The cached value or the result of the block, or nil if no value is found.
     def fetch(key, expires_in: nil)
       serialized_value, expire_at = @cache[key]
       if serialized_value.nil? || (expire_at && expire_at < Process.clock_gettime(Process::CLOCK_MONOTONIC))
@@ -24,10 +33,20 @@ module SupportTableCache
       Marshal.load(serialized_value)
     end
 
+    # Read a value from the cache.
+    #
+    # @param key [Object] The cache key.
+    # @return [Object, nil] The cached value or nil if not found.
     def read(key)
       fetch(key)
     end
 
+    # Write a value to the cache.
+    #
+    # @param key [Object] The cache key.
+    # @param value [Object] The value to cache. Nil values are not cached.
+    # @param expires_in [Integer, nil] Time in seconds until the cached value expires.
+    # @return [void]
     def write(key, value, expires_in: nil)
       return if value.nil?
 
@@ -42,10 +61,17 @@ module SupportTableCache
       end
     end
 
+    # Delete a value from the cache.
+    #
+    # @param key [Object] The cache key.
+    # @return [void]
     def delete(key)
       @cache.delete(key)
     end
 
+    # Clear all values from the cache.
+    #
+    # @return [void]
     def clear
       @cache.clear
     end

data/lib/support_table_cache/relation_override.rb

@@ -5,12 +5,18 @@ module SupportTableCache
 
   module RelationOverride
     # Override for the find_by method that looks in the cache first.
+    #
+    # @param args [Array<Object>] Arguments passed to find_by.
+    # @return [ActiveRecord::Base, nil] The found record or nil if not found.
     def find_by(*args)
       return super unless klass.include?(SupportTableCache)
 
       cache = klass.send(:current_support_table_cache)
       return super unless cache
 
+      # Skip caching for has_many or has_many :through associations
+      return super if is_a?(ActiveRecord::Associations::CollectionProxy)
+
       return super if select_values.present?
 
       cache_key = nil
@@ -43,7 +49,10 @@ module SupportTableCache
     end
 
     # Override for the find_by! method that looks in the cache first.
-    # @raise ActiveRecord::RecordNotFound if no record is found.
+    #
+    # @param args [Array<Object>] Arguments passed to find_by!.
+    # @return [ActiveRecord::Base] The found record.
+    # @raise [ActiveRecord::RecordNotFound] if no record is found.
     def find_by!(*args)
       value = find_by(*args)
       unless value
@@ -55,7 +64,8 @@ module SupportTableCache
     # Same as find_by, but performs a safety check to confirm the query will hit the cache.
     #
     # @param attributes [Hash] Attributes to find the record by.
-    # @raise ArgumentError if the query cannot use the cache.
+    # @return [ActiveRecord::Base, nil] The found record or nil if not found.
+    # @raise [ArgumentError] if the query cannot use the cache.
     def fetch_by(attributes)
       find_by_attribute_names = support_table_find_by_attribute_names(attributes)
       unless klass.support_table_cache_by_attributes.any? { |attribute_names, _ci| attribute_names == find_by_attribute_names }
@@ -67,8 +77,9 @@ module SupportTableCache
     # Same as find_by!, but performs a safety check to confirm the query will hit the cache.
     #
     # @param attributes [Hash] Attributes to find the record by.
-    # @raise ArgumentError if the query cannot use the cache.
-    # @raise ActiveRecord::RecordNotFound if no record is found.
+    # @return [ActiveRecord::Base] The found record.
+    # @raise [ArgumentError] if the query cannot use the cache.
+    # @raise [ActiveRecord::RecordNotFound] if no record is found.
     def fetch_by!(attributes)
       value = fetch_by(attributes)
       if value.nil?

data/lib/support_table_cache.rb

@@ -39,7 +39,8 @@ module SupportTableCache
     # for a class will always take precedence over the global setting.
     #
     # @param disabled [Boolean] Caching will be disabled if this is true and enabled if false.
-    # @yieldreturn The return value of the block.
+    # @yield Executes the provided block with caching disabled or enabled.
+    # @return [Object] The return value of the block.
     def disable_cache(disabled = true, &block)
       varname = "support_table_cache_disabled:#{name}"
       save_val = Thread.current.thread_variable_get(varname)
@@ -54,7 +55,8 @@ module SupportTableCache
     # Enable the caching behavior for this class within the block. The enabled setting
     # for a class will always take precedence over the global setting.
     #
-    # @yieldreturn The return value of the block.
+    # @yield Executes the provided block with caching enabled.
+    # @return [Object] The return value of the block.
     def enable_cache(&block)
       disable_cache(false, &block)
     end
@@ -69,7 +71,7 @@ module SupportTableCache
 
       find_each do |record|
         support_table_cache_by_attributes.each do |attribute_names, case_sensitive|
-          attributes = record.attributes.select { |name, value| attribute_names.include?(name) }
+          attributes = record.attributes.slice(*attribute_names)
           cache_key = SupportTableCache.cache_key(self, attributes, attribute_names, case_sensitive)
           cache.fetch(cache_key, expires_in: support_table_cache_ttl) { record }
         end
@@ -89,16 +91,16 @@ module SupportTableCache
     protected
 
     # Specify which attributes can be used for looking up records in the cache. Each value must
-    # define a unique key, Multiple unique keys can be specified.
+    # define a unique key. Multiple unique keys can be specified.
     #
     # If multiple attributes are used to make up a unique key, then they should be passed in as an array.
     #
     # If you need to remove caching setup in a superclass, you can pass in the value false to reset
     # cache behavior on the class.
     #
-    # @param attributes [String, Symbol, Array<String, Symbol>, FalseClass] Attributes that make up a unique key.
-    # @param case_sensitive [Boolean] Indicate if strings should treated as case insensitive in the key.
-    # @param where [Hash] A hash representing a hard coded set of attributes that must match a query in order
+    # @param attributes [String, Symbol, Array<String, Symbol>, false] Attributes that make up a unique key.
+    # @param case_sensitive [Boolean] Indicate if strings should be treated as case insensitive in the key.
+    # @param where [Hash, nil] A hash representing a hard coded set of attributes that must match a query in order
     #   to cache the result. If a model has a default scope, then this value should be set to match the
     #   where clause in that scope.
     # @return [void]
@@ -144,7 +146,8 @@ module SupportTableCache
     # disabled for that block. If no block is specified, then caching is disabled globally.
     #
     # @param disabled [Boolean] Caching will be disabled if this is true and enabled if false.
-    # @yieldreturn The return value of the block.
+    # @yield Executes the provided block with caching disabled or enabled (if block is given).
+    # @return [Object, nil] The return value of the block if a block is given, nil otherwise.
     def disable(disabled = true, &block)
       if block
         save_val = Thread.current.thread_variable_get(:support_table_cache_disabled)
@@ -162,7 +165,8 @@ module SupportTableCache
     # Enable the caching behavior for all classes. If a block is specified, then caching is only
     # enabled for that block. If no block is specified, then caching is enabled globally.
     #
-    # @yieldreturn The return value of the block.
+    # @yield Executes the provided block with caching enabled (if block is given).
+    # @return [Object, nil] The return value of the block if a block is given, nil otherwise.
     def enable(&block)
       disable(false, &block)
     end
@@ -204,7 +208,8 @@ module SupportTableCache
     # can use this to wrap your test methods so that cached values from one test don't show up
     # in subsequent tests.
     #
-    # @return [void]
+    # @yield Executes the provided block in test mode.
+    # @return [Object] The return value of the block.
     def testing!(&block)
       save_val = Thread.current.thread_variable_get(:support_table_cache_test_cache)
       if save_val.nil?
@@ -219,7 +224,7 @@ module SupportTableCache
 
     # Get the current test mode cache. This will only return a value inside of a `testing!` block.
     #
-    # @return [SupportTableCache::MemoryCache]
+    # @return [SupportTableCache::MemoryCache, nil] The test cache or nil if not in test mode.
     # @api private
     def testing_cache
       unless defined?(@cache) && @cache.nil?
@@ -232,9 +237,9 @@ module SupportTableCache
     #
     # @param klass [Class] The class that is being cached.
     # @param attributes [Hash] The attributes used to find a record.
-    # @param key_attribute_names [Array] List of attributes that can be used as a key in the cache.
+    # @param key_attribute_names [Array<String>] List of attributes that can be used as a key in the cache.
     # @param case_sensitive [Boolean] Indicator if string values are case-sensitive in the cache key.
-    # @return [String]
+    # @return [Array(String, Hash), nil] A two-element array with the class name and attributes hash, or nil if not cacheable.
     # @api private
     def cache_key(klass, attributes, key_attribute_names, case_sensitive)
       return nil if attributes.blank? || key_attribute_names.blank?

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: support_table_cache
 version: !ruby/object:Gem::Version
-  version: 1.1.2
+  version: 1.1.4
 platform: ruby
 authors:
 - Brian Durand
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-12-17 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -38,13 +37,13 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: 
 email:
 - bbdurand@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- ARCHITECTURE.md
 - CHANGELOG.md
 - MIT-LICENSE
 - README.md
@@ -59,7 +58,6 @@ homepage: https://github.com/bdurand/support_table_cache
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -74,8 +72,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
-signing_key: 
+rubygems_version: 3.6.9
 specification_version: 4
 summary: Automatic ActiveRecord caching for small support tables.
 test_files: []