support_table_cache 1.1.3 → 1.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 919adfaf6654d3accefd95fbba6cc116484780d0e73bc23c975da5e310c10173
-  data.tar.gz: 5c93b1ffc131dddc417b5de585f38ba89e4872e7d4a009705a0b8c669d7a6dd9
+  metadata.gz: 9fe5a9190c32271b431faed20e0b6ddbeb195cd05c927cae94c03b5c7d20bc8a
+  data.tar.gz: 8f8bc59c1a0eb6240712e50fb34da28f45d071e1c6b59e28d647d8bcf7e17896
 SHA512:
-  metadata.gz: 922e53c4a25b835aadf77fa0bdc18af93d70406476ab08a4ee72828dad79265203d89fef68963260666cb44cc1990bccffa0034f43376e9dc1cc632debaad87c
-  data.tar.gz: 756b44a620b8a6138358d23fcb4739c927d630c7e26685f173e9643d136b9ec41ddf045e77078a0bb73ada847dc46a5b952ccbb35693cd682fa0c0e8e38d92d8
+  metadata.gz: c833468a94fed3f16efd45022c56cbf19c755d6f0e2f48a2d93b8b92c2d946bd46f246170a623f2edeade892aa017851d581794fc7505c4efd5c5bce3fdf29b9
+  data.tar.gz: d4307c2d653184fe890e8aa8af0c548ef340d817141fddcb69e8a083ffcd235fa7d0d124b98e6ece0dd99e5a8fc549db1a8a986acf571aada17cb6f0619c67e1

data/AGENTS.md

@@ -0,0 +1,74 @@
+# Copilot Instructions for support_table_cache
+
+## Project Overview
+
+This is a Ruby gem that adds transparent caching to ActiveRecord support/lookup tables. It intercepts `find_by` queries and `belongs_to` associations to cache small, rarely-changing reference tables (statuses, types, categories) without code changes.
+
+**Core principle**: Cache entries keyed by unique attribute combinations, auto-invalidated on record changes via `after_commit` callbacks.
+
+## Architecture
+
+- **lib/support_table_cache.rb**: Main module with `cache_by` DSL, cache configuration, and invalidation logic
+- **lib/support_table_cache/find_by_override.rb**: Prepends to model class to intercept `find_by` calls
+- **lib/support_table_cache/relation_override.rb**: Prepends to `ActiveRecord::Relation` to handle scoped queries (e.g., `where(group: 'x').find_by(name: 'y')`)
+- **lib/support_table_cache/associations.rb**: Extends `belongs_to` with `cache_belongs_to` to cache foreign key lookups
+- **lib/support_table_cache/memory_cache.rb**: In-process cache implementation (use `support_table_cache = :memory`)
+
+See [ARCHITECTURE.md](../ARCHITECTURE.md) for detailed flow diagrams showing cache key generation, invalidation, and association caching sequences.
+
+## Key Patterns
+
+### Model Configuration
+Models use `cache_by` to declare unique keys that can be cached. Support composite keys and case-insensitivity:
+```ruby
+cache_by :name, case_sensitive: false
+cache_by [:group, :code]
+cache_by :name, where: {deleted_at: nil}  # For default scopes
+```
+
+### Cache Key Structure
+Cache keys are `[ClassName, {attr1: val1, attr2: val2}]` arrays with sorted attribute names. Case-insensitive values are downcased before keying.
+
+### Module Prepending Pattern
+Uses `prepend` to wrap ActiveRecord methods (`find_by`) rather than monkey-patching. This allows `super` to call original behavior on cache misses or when caching disabled.
+
+## Testing
+
+- **Multi-version testing**: Uses Appraisal gem to test against ActiveRecord 5.0-8.0 (see [Appraisals](../Appraisals))
+- **Run tests**: `bundle exec rspec` (default rake task) or `bundle exec appraisal rspec` for all versions
+- **Test setup**: In-memory SQLite database created in [spec/spec_helper.rb](../spec/spec_helper.rb) with test tables
+- **Test isolation**: Tests wrapped with `SupportTableCache.testing!` in RSpec `config.before` to prevent cache pollution
+
+### Code Style
+Use **standardrb** for linting. Run `standardrb --fix` before committing. CI enforces this on ActiveRecord 8.0 matrix entry.
+
+## Common Operations
+
+### Adding Cache Support to Models
+1. Include `SupportTableCache` in model class
+2. Call `cache_by` with unique key attributes
+3. Optionally set `self.support_table_cache_ttl = 5.minutes`
+4. For associations: include `SupportTableCache::Associations` in parent model, then `cache_belongs_to :association_name`
+
+### Cache Invalidation
+Automatic via `after_commit` callback that clears all cache key variations (both old and new attribute values on updates). No manual invalidation needed unless using in-memory cache across processes.
+
+### Debugging Cache Behavior
+- Use `fetch_by` instead of `find_by` to raise error if query won't hit cache
+- Disable caching in block: `Model.disable_cache { ... }` or globally `SupportTableCache.disable { ... }`
+- Check if caching enabled: inspect `support_table_cache_by_attributes` class attribute
+
+## Development Workflow
+
+1. **Running specs locally**: `bundle exec rspec` (uses Ruby 3.3+ and ActiveRecord 8.0 from Gemfile)
+2. **Testing specific AR version**: `bundle exec appraisal activerecord_7 rspec`
+3. **Generating all gemfiles**: `bundle exec appraisal generate`
+4. **Lint before commit**: `standardrb --fix`
+5. **Release**: Only from `main` branch (enforced by `Rakefile` pre-release check)
+
+## Important Constraints
+
+- **Target models**: Only for small tables (few hundred rows max)
+- **Unique keys only**: `cache_by` attributes must define unique constraints
+- **No runtime scopes**: Cannot use `cache_belongs_to` with scoped associations (checked at configuration time)
+- **In-memory cache caveat**: Per-process, not invalidated across processes—only use for truly static data or with TTL

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,24 +4,41 @@ 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.5
+
+### Fixed
+
+- Replaced thread local variables with fiber local variables to prevent the possibility of behavior from leaking across fibers when disabling the cache in a block.
+- Allow setting the cache to an in-memory cache by setting `support_table_cache` to `true`.
+
+## 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
+
 - Do not cache records where only some of the columns have been loaded with a call to `select`.
 
 ## 1.1.1
 
 ### Fixed
+
 - Fixed disabled and disable_cache methods to yield a block to match the documentation.
 
 ## 1.1.0
 
 ### Added
+
 - Added fetch_by and fetch_by! methods that can verify the result will be cacheable.
 - Allow configuring cache storage on a per class basis.
 - Allow disabling caching on per class basis.
@@ -30,15 +47,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added test mode to intialize new caches within a test block.
 
 ### Changed
+
 - Changed fiber local variables used for disabling the cache to thread local variables.
 - Using find_by! on a relation will now use the cache.
 
 ## 1.0.1
 
 ### Added
+
 - Preserve scope on relations terminated with a `find_by`.
 
 ## 1.0.0
 
 ### Added
+
 - Add SupportTableCache concern to enable automatic caching on models when calling `find_by` with unique key parameters.

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.
 
@@ -18,6 +19,18 @@ end
 
 With this gem, you can avoid the database query associated with the `find_by` call. You don't need to alter your code in any way other than to include `SupportTableCache` in your model and telling it the attributes that comprise a unique key, which can be used for caching.
 
+## Table of Contents
+
+- [Usage](#usage)
+  - [Setting the Cache](#setting-the-cache)
+  - [Disabling Caching](#disabling-caching)
+  - [Caching Belongs to Associations](#caching-belongs-to-associations)
+  - [Testing](#testing)
+  - [Companion Gems](#companion-gems)
+- [Installation](#installation)
+- [Contributing](#contributing)
+- [License](#license)
+
 ## Usage
 
 To use the gem, you need to include it in you models and then specify which attributes can be used for caching with the `cache_by` method. A caching attribute must be a unique key on the model. For a composite unique key, you can specify an array of attributes. If any of the attributes are case-insensitive strings, you need to specify that as well.
@@ -114,6 +127,9 @@ end
 
 You can include `SupportTableCache::Associations` in your `ApplicationRecord` class to make association caching available on all models.
 
+> [!NOTE]
+> You still need to set up the target model to cache by the primary key used by the belongs to association. Otherwise the association will not be cached.
+
 ### Testing
 
 Caching may interfere with tests by allowing data created in one test to leak into subsequent tests. You can resolve this by wrapping your tests with the `SupportTableCache.testing!` method.
@@ -131,14 +147,16 @@ class MiniTest::Spec
   around do |tests|
     SupportTableCache.testing!(&tests)
   end
-=end
-
+end
 ```
 
-### Maintaining Data
+### Companion Gems
 
 You can use the companion [support_table_data gem](https://github.com/bdurand/support_table_data) to provide functionality for loading static data into your support tables as well as adding helper functions to make looking up specific rows much easier.
 
+> [!TIP]
+> The [support_table](https://github.com/bdurand/support_table) gem combines both gems in a drop in solution for Rails applications.
+
 ## Installation
 
 Add this line to your application's Gemfile:

data/VERSION

@@ -1 +1 @@
-1.1.3
+1.1.5

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]
 

data/lib/support_table_cache/fiber_locals.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module SupportTableCache
+  # Utility class for managing fiber-local variables. This implementation
+  # does not pollute the global namespace.
+  class FiberLocals
+    def initialize
+      @mutex = Mutex.new
+      @locals = {}
+    end
+
+    def [](key)
+      fiber_locals = nil
+      @mutex.synchronize do
+        fiber_locals = @locals[Fiber.current.object_id]
+      end
+      return nil if fiber_locals.nil?
+
+      fiber_locals[key]
+    end
+
+    def with(key, value)
+      fiber_id = Fiber.current.object_id
+      fiber_locals = nil
+      previous_value = nil
+      inited_vars = false
+
+      begin
+        @mutex.synchronize do
+          fiber_locals = @locals[fiber_id]
+          if fiber_locals.nil?
+            fiber_locals = {}
+            @locals[fiber_id] = fiber_locals
+            inited_vars = true
+          end
+        end
+
+        previous_value = fiber_locals[key]
+        fiber_locals[key] = value
+
+        yield
+      ensure
+        if inited_vars
+          @mutex.synchronize do
+            @locals.delete(fiber_id)
+          end
+        else
+          fiber_locals[key] = previous_value
+        end
+      end
+    end
+  end
+end

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

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "support_table_cache/associations"
+require_relative "support_table_cache/fiber_locals"
 require_relative "support_table_cache/find_by_override"
 require_relative "support_table_cache/relation_override"
 require_relative "support_table_cache/memory_cache"
@@ -10,6 +11,13 @@ require_relative "support_table_cache/memory_cache"
 module SupportTableCache
   extend ActiveSupport::Concern
 
+  NOT_SET = Object.new.freeze
+  private_constant :NOT_SET
+
+  @fiber_locals = FiberLocals.new
+  @cache = NOT_SET
+  @disabled = false
+
   included do
     # @api private Used to store the list of attribute names used for caching.
     class_attribute :support_table_cache_by_attributes, instance_accessor: false
@@ -39,22 +47,17 @@ 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)
-      begin
-        Thread.current.thread_variable_set(varname, !!disabled)
-        yield
-      ensure
-        Thread.current.thread_variable_set(varname, save_val)
-      end
+      SupportTableCache.with_fiber_local("support_table_cache_disabled:#{name}", !!disabled, &block)
     end
 
     # 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 +72,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
@@ -79,26 +82,26 @@ module SupportTableCache
     # Set a class-specific cache to use in lieu of the global cache.
     #
     # @param cache [ActiveSupport::Cache::Store, Symbol] The cache instance to use. You can also
-    #   specify the value :memory to use an optimized in-memory cache.
+    #   specify the value :memory or true to use an optimized in-memory cache.
     # @return [void]
     def support_table_cache=(cache)
-      cache = MemoryCache.new if cache == :memory
+      cache = MemoryCache.new if cache == :memory || cache == true
       self.support_table_cache_impl = cache
     end
 
     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]
@@ -125,7 +128,7 @@ module SupportTableCache
     private
 
     def support_table_cache_disabled?
-      current_block_value = Thread.current.thread_variable_get("support_table_cache_disabled:#{name}")
+      current_block_value = SupportTableCache.fiber_local_value("support_table_cache_disabled:#{name}")
       if current_block_value.nil?
         SupportTableCache.disabled?
       else
@@ -144,16 +147,11 @@ 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)
-        begin
-          Thread.current.thread_variable_set(:support_table_cache_disabled, !!disabled)
-          yield
-        ensure
-          Thread.current.thread_variable_set(:support_table_cache_disabled, save_val)
-        end
+        SupportTableCache.with_fiber_local("support_table_cache_disabled", !!disabled, &block)
       else
         @disabled = !!disabled
       end
@@ -162,7 +160,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
@@ -170,9 +169,9 @@ module SupportTableCache
     # Return true if caching has been disabled.
     # @return [Boolean]
     def disabled?
-      block_value = Thread.current.thread_variable_get(:support_table_cache_disabled)
+      block_value = SupportTableCache.fiber_local_value("support_table_cache_disabled")
       if block_value.nil?
-        !!(defined?(@disabled) && @disabled)
+        !!@disabled
       else
         block_value
       end
@@ -193,7 +192,7 @@ module SupportTableCache
     def cache
       if testing_cache
         testing_cache
-      elsif defined?(@cache)
+      elsif @cache != NOT_SET
         @cache
       elsif defined?(Rails.cache)
         Rails.cache
@@ -204,27 +203,25 @@ 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)
+      save_val = SupportTableCache.fiber_local_value("support_table_cache_test_cache")
       if save_val.nil?
-        Thread.current.thread_variable_set(:support_table_cache_test_cache, MemoryCache.new)
-      end
-      begin
+        SupportTableCache.with_fiber_local("support_table_cache_test_cache", MemoryCache.new, &block)
+      else
         yield
-      ensure
-        Thread.current.thread_variable_set(:support_table_cache_test_cache, save_val)
       end
     end
 
     # 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?
-        Thread.current.thread_variable_get(:support_table_cache_test_cache)
-      end
+      return nil if @cache.nil?
+
+      SupportTableCache.fiber_local_value("support_table_cache_test_cache")
     end
 
     # Generate a consistent cache key for a set of attributes. It will return nil if the attributes
@@ -232,9 +229,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?
@@ -253,6 +250,14 @@ module SupportTableCache
 
       [klass.name, sorted_attributes]
     end
+
+    def fiber_local_value(varname)
+      @fiber_locals[varname]
+    end
+
+    def with_fiber_local(varname, value, &block)
+      @fiber_locals.with(varname, value, &block)
+    end
   end
 
   # Remove the cache entry for this record.

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: support_table_cache
 version: !ruby/object:Gem::Version
-  version: 1.1.3
+  version: 1.1.5
 platform: ruby
 authors:
 - Brian Durand
-autorequire: 
 bindir: bin
 cert_chain: []
-date: 2023-01-23 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -38,19 +37,21 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-description: 
 email:
 - bbdurand@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- AGENTS.md
+- ARCHITECTURE.md
 - CHANGELOG.md
 - MIT-LICENSE
 - README.md
 - VERSION
 - lib/support_table_cache.rb
 - lib/support_table_cache/associations.rb
+- lib/support_table_cache/fiber_locals.rb
 - lib/support_table_cache/find_by_override.rb
 - lib/support_table_cache/memory_cache.rb
 - lib/support_table_cache/relation_override.rb
@@ -59,7 +60,6 @@ homepage: https://github.com/bdurand/support_table_cache
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
 rdoc_options: []
 require_paths:
 - lib
@@ -74,8 +74,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
-signing_key: 
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Automatic ActiveRecord caching for small support tables.
 test_files: []