rails_query 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c5fc3a99fb7dcbafa2b6f9385808a7474b2c9b5a3405da0b91a1fb8ba56cf27a
-  data.tar.gz: 1cdeff8c81675c2ff6db8bc229ec5c6abc293c7b527561b35e5e0c1b6e4040b5
+  metadata.gz: e8ca91e8274e6e24acc0f4101ad2ef02b18a4aeef9e2adafdc65f28188c80fc5
+  data.tar.gz: 54d293281ead95744f0970457f91fe0367c84bb8b623f54a2a2fe607900023d5
 SHA512:
-  metadata.gz: 2edc4e880007981026be9d9dfe6b91243d81400473561b414ca22687b6d60cb0b6de2b423772482d829bf64330236b6c2d6f6614eb6403a2caad1ef7f494524d
-  data.tar.gz: f99c922f1e671480f609f90f4581761a8701243f221e2bceeefe0c1940897d3448199e98fbb88203756269c2de1e969fa808a4c915bcea7c40fc18721fe697be
+  metadata.gz: 2c16e22500a124ca6f03e7e8d37761457c6aadf69e5bccb4fd6eda48fea1859ed911899fb93ac6b17b8b7f9dc22016bc61391bda6a4809a39171adf56982645a
+  data.tar.gz: b6de1573128e8c403af465e0927af4b9402e319897cbe6759069cd6b18b6f4cd348fb4294464b9e94f91af98135c2ce13a9cfa66c9ed12a0fa6a2ac360bc24ea

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 ## [Unreleased]
 
+## [0.3.0] - 2026-04-02
+* Add support stale time by @ilsonlasmar in https://github.com/ilsonlasmar/rails_query/pull/7
+* Support more ruby version by @ilsonlasmar in https://github.com/ilsonlasmar/rails_query/pull/8
+
+## [0.2.0] - 2026-04-02
+* Fix badge version in README by @ilsonlasmar in https://github.com/ilsonlasmar/rails_query/pull/4
+* Add dynamic values by context by @ilsonlasmar in https://github.com/ilsonlasmar/rails_query/pull/5
+* change version 0.2.0 by @ilsonlasmar in https://github.com/ilsonlasmar/rails_query/pull/6
+
 ## [0.1.0] - 2026-04-29
 
 🚀 [FEATURE] Initial release of Rails Query

data/README.md

@@ -50,6 +50,7 @@ app/providers/
 - [Generators](#generators)
 - [Caching](#caching)
 - [Invalidation](#invalidation)
+- [Stale Time](#stale-time)
 
 
 ## Installation
@@ -141,7 +142,7 @@ UserProvider
 
 ```ruby
 class UserProvider
-  include RailsQuery::Provider
+  include RailsQuery::Adapter
 
   base_url ENV["USER_API_URL"]
 
@@ -196,6 +197,41 @@ Mutations invalidate cache after execution.
 invalidates "UserProvider"
 ```
 
+# Stale Time
+`stale` defines how long cached data is considered **fresh**.
+
+#### How it works
+- While data is **fresh**:
+  - RailsQuery will **not trigger new requests**
+  - Cached data is returned immediately
+  - No background refetch occurs
+
+- When data becomes **stale**:
+  - Data remains in cache
+  - RailsQuery may **refetch in the background** when a trigger occurs
+
+### Default behavior
+Stale behavior is disabled by default
+
+```ruby
+stale nil
+```
+
+### Obs.:
+Never configure `stale` to be greater than your cache expiration (TTL or equivalent).
+
+If data is considered fresh for longer than it actually exists in cache, RailsQuery will be forced to fetch everything again from the source, losing the benefit of freshness.
+
+
+### Stale vs Cache Expiration (TTL)
+
+| Feature | Stale | Cache expiration (TTL) |
+|--------|--------|------------------------|
+| **What it controls** | When data is considered outdated and eligible for refetch | How long data remains stored in cache |
+| **Does the data still exist?** | Yes, but marked as stale | Yes, until it expires and is removed |
+| **Triggers new request?** | No while fresh; yes when stale (on next call/trigger) | Not directly; only after cache is gone |
+| **Default** | nil (disabled) | 0 (not cache store) |
+| **Example** | 0 (revalidate always) | 5 minutes (after disuse)  |
 
 ## Development
 

data/lib/rails_query/client.rb

@@ -4,16 +4,34 @@ module RailsQuery
   # Internal client class responsible for cache interactions
   class Client
     def initialize(config)
-      @cache       = config.cache_store
-      @default_ttl = config.default_ttl
-      @namespace   = config.namespace
-      @logger      = config.logger
+      @cache         = config.cache_store
+      @default_ttl   = config.default_ttl
+      @default_stale = config.default_stale
+      @executor      = config.executor
+      @namespace     = config.namespace
+      @logger        = config.logger
     end
 
-    def fetch(key, ttl: @default_ttl, provider: nil, &block)
-      store_index(provider, key) if provider
+    def fetch(key, ttl: @default_ttl, stale: @default_stale, provider: nil, &block)
       namespaced = namespaced_key(key)
-      @cache.fetch(namespaced, expires_in: ttl, &block)
+      entry = @cache.read(namespaced)
+
+      if entry
+        age = Time.now - entry[:fetched_at]
+        async_refetch(namespaced, ttl, provider, &block) if stale && stale < age
+        return entry[:data]
+      end
+
+      data = block.call
+      write(namespaced, data, ttl, provider: provider)
+
+      data
+    end
+
+    def write(key, data, ttl, provider: nil)
+      store_index(provider, key) if provider
+
+      @cache.write(key, { data: data, fetched_at: Time.now }, expires_in: ttl)
     end
 
     def store_index(provider, key)
@@ -45,6 +63,36 @@ module RailsQuery
 
     private
 
+    def in_lock?(key)
+      lock_key = "lock:#{key}"
+      @cache.exist?(lock_key)
+    end
+
+    def write_lock(key)
+      lock_key = "lock:#{key}"
+      @cache.write(lock_key, true, expires_in: 10.seconds)
+    end
+
+    def delete_lock(key)
+      lock_key = "lock:#{key}"
+      @cache.delete(lock_key)
+    end
+
+    def async_refetch(key, ttl, provider, &block)
+      return if in_lock?(key)
+
+      write_lock(key)
+
+      @executor.post do
+        data = block.call
+        write(key, data, ttl, provider: provider)
+      rescue StandardError => e
+        @logger.error("[RailsQuery] SWR refetch failed: #{e.message}")
+      ensure
+        delete_lock(key)
+      end
+    end
+
     def namespaced_key(key)
       "#{@namespace}:#{Array(key).join(":")}"
     end

data/lib/rails_query/configuration.rb

@@ -3,11 +3,13 @@
 module RailsQuery
   # Configuration class for RailsQuery
   class Configuration
-    attr_accessor :cache_store, :default_ttl, :namespace, :logger
+    attr_accessor :cache_store, :default_ttl, :default_stale, :namespace, :executor, :logger
 
     def initialize
       @cache_store = default_cache_store
-      @default_ttl = 30.seconds
+      @executor = default_executor
+      @default_ttl = 0
+      @default_stale = nil
       @namespace = "rails_query"
       @logger = default_logger
     end
@@ -22,6 +24,15 @@ module RailsQuery
       end
     end
 
+    def default_executor
+      Concurrent::ThreadPoolExecutor.new(
+        min_threads: 2,
+        max_threads: Concurrent.processor_count * 2,
+        max_queue: 100,
+        fallback_policy: :discard
+      )
+    end
+
     def default_logger
       if defined?(Rails) && Rails.respond_to?(:logger)
         Rails.logger

data/lib/rails_query/query.rb

@@ -13,6 +13,11 @@ module RailsQuery
         @ttl
       end
 
+      def stale(value = nil)
+        @stale = value if value
+        @stale
+      end
+
       def key(&block)
         @key_block = block if block
         @key_block
@@ -22,7 +27,7 @@ module RailsQuery
     def call(*args, **opts)
       key = build_key(*args, **opts)
       provider_class = opts[:provider] || self.class.name
-      RailsQuery.client.fetch(key, ttl: ttl, provider: provider_class) do
+      RailsQuery.client.fetch(key, ttl: ttl, stale: stale, provider: provider_class) do
         kwargs? ? resolve(*args, **opts) : resolve(*args)
       end
     end
@@ -31,6 +36,10 @@ module RailsQuery
       self.class.ttl || RailsQuery.configuration.default_ttl
     end
 
+    def stale
+      self.class.stale || RailsQuery.configuration.default_stale
+    end
+
     def build_key(*args, **opts)
       opts = opts.select { |k, _| self.class.key.parameters.map(&:last).include?(k) }
       return instance_exec(*args, **opts, &self.class.key) if self.class.key

data/lib/rails_query/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module RailsQuery
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: rails_query
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Ilson Lasmar
@@ -9,6 +9,34 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: concurrent-ruby
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.3'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -52,19 +80,33 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0.14'
 - !ruby/object:Gem::Dependency
-  name: rails
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '1.21'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '7.1'
+        version: '1.21'
 - !ruby/object:Gem::Dependency
   name: simplecov
   requirement: !ruby/object:Gem::Requirement