datastar 1.0.2 → 1.0.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 885e73382637f598ee1feeea492556e30f4dea1dcdd9eae1627649a8dbadc0bc
-  data.tar.gz: 2945bedd152787c39ae3843f2cf2c937bdba3d7d8a0ea0f6b9a4d0ac2bf34a18
+  metadata.gz: 568e2026e9657b4042957c360641bc3c1b51bfdfe7dcf1710a78b75e07a71ccf
+  data.tar.gz: 25851c3fc4b6bb74c8db43d6ecfbbd8fa796be259fe9b0b4bc4653e3077c0e41
 SHA512:
-  metadata.gz: bc0bb40586da1e305aa87b6c4b830baeaacd671e259aa7105a043ceaebab8659c23df8b12665d1a1bf1b9ca09aa518e275cdc30b5978627da6d818e818cc14f8
-  data.tar.gz: 5ae556f5ce37d9805fe920c68ab5164464ec6fabbd2f4355d9d17139dbf381bd0dde65b5c33bf8f0e4de6eda431ece4cc7b20a41080f3362fea9f7daedad580d
+  metadata.gz: 880721f4912523484e4c79c8faeba5241e371007d5a6d81cbf45f1979ef4d25a6a1c32c25afe24165c4e646bf1523355ae9bea9a13310da2a05287fab71acb82
+  data.tar.gz: 9b594d6249a5a923d8da9d693e495d8f1622835bd8b698c5e8ff8396bbf00f5ac6f5c6302591ac9ae4690f06c7b6e9dc1c9e752d9d9f3757e74648349472ba3d

data/README.md

@@ -245,6 +245,21 @@ You can also set it to a different number (in seconds)
 heartbeat: 0.5
 ```
 
+#### Per-stream override
+
+The `#stream` method also accepts a `heartbeat:` keyword that overrides the constructor-level setting for a single call. This is useful when a dispatcher is generally configured with a heartbeat but a particular response doesn't need one (e.g. a one-shot update). The previous value is restored once the call returns.
+
+```ruby
+datastar = Datastar.new(request:, response:) # default heartbeat
+
+# Disable heartbeat for this single response
+datastar.stream(heartbeat: false) do |sse|
+  sse.patch_elements(html)
+end
+```
+
+The one-shot helpers (`#patch_elements`, `#remove_elements`, `#patch_signals`, `#remove_signals`, `#execute_script`, `#redirect`) use this internally to avoid spawning a heartbeat thread for a single message.
+
 #### Manual connection check
 
 If you want to check connection status on your own, you can disable the heartbeat and use `sse.check_connection!`, which will close the connection and trigger callbacks if the client is disconnected.

data/lib/datastar/dispatcher.rb

@@ -28,7 +28,7 @@ module Datastar
     HTTP_ACCEPT = 'HTTP_ACCEPT'
     HTTP1 = 'HTTP/1.1'
 
-    attr_reader :request, :response
+    attr_reader :request, :response, :heartbeat
 
     # @option request [Rack::Request] the request object
     # @option response [Rack::Response, nil] the response object
@@ -137,7 +137,7 @@ module Datastar
     # @param elements [String, #call(view_context: Object) => Object] the HTML elements or object
     # @param options [Hash] the options to send with the message
     def patch_elements(elements, options = BLANK_OPTIONS)
-      stream_no_heartbeat do |sse|
+      stream(heartbeat: false) do |sse|
         sse.patch_elements(elements, options)
       end
     end
@@ -152,7 +152,7 @@ module Datastar
     # @param selector [String] a CSS selector for the fragment to remove
     # @param options [Hash] the options to send with the message
     def remove_elements(selector, options = BLANK_OPTIONS)
-      stream_no_heartbeat do |sse|
+      stream(heartbeat: false) do |sse|
         sse.remove_elements(selector, options)
       end
     end
@@ -166,7 +166,7 @@ module Datastar
     # @param signals [Hash, String] signals to merge
     # @param options [Hash] the options to send with the message
     def patch_signals(signals, options = BLANK_OPTIONS)
-      stream_no_heartbeat do |sse|
+      stream(heartbeat: false) do |sse|
         sse.patch_signals(signals, options)
       end
     end
@@ -180,7 +180,7 @@ module Datastar
     # @param paths [Array<String>] object paths to the signals to remove
     # @param options [Hash] the options to send with the message
     def remove_signals(paths, options = BLANK_OPTIONS)
-      stream_no_heartbeat do |sse|
+      stream(heartbeat: false) do |sse|
         sse.remove_signals(paths, options)
       end
     end
@@ -194,7 +194,7 @@ module Datastar
     # @param script [String] the script to execute
     # @param options [Hash] the options to send with the message
     def execute_script(script, options = BLANK_OPTIONS)
-      stream_no_heartbeat do |sse|
+      stream(heartbeat: false) do |sse|
         sse.execute_script(script, options)
       end
     end
@@ -204,7 +204,7 @@ module Datastar
     #
     # @param url [String] the URL or path to redirect to
     def redirect(url)
-      stream_no_heartbeat do |sse|
+      stream(heartbeat: false) do |sse|
         sse.redirect(url)
       end
     end
@@ -245,10 +245,24 @@ module Datastar
     # By default, the built-in Rack finalzer just returns the resposne Array which can be used by any Rack handler.
     # On Rails, the Rails controller response is set to this objects streaming response.
     #
+    # A per-call +heartbeat:+ keyword overrides the constructor-level heartbeat
+    # for the duration of this call. Pass +false+ to disable heartbeat for a
+    # one-shot message (e.g. a single +patch_elements+), or a Numeric interval
+    # to enable it. The previous value is restored once the call returns.
+    # @example Disable heartbeat for a single response
+    #
+    #  datastar.stream(heartbeat: false) do |sse|
+    #    sse.patch_elements(html)
+    #  end
+    #
     # @param streamer [#call(ServerSentEventGenerator), nil] a callable to call with the generator
+    # @param heartbeat [Numeric, false] override the heartbeat interval for this call, or +false+ to disable
     # @yieldparam sse [ServerSentEventGenerator] the generator object
     # @return [Object] depends on the finalize callback
-    def stream(streamer = nil, &block)
+    def stream(streamer = nil, heartbeat: @heartbeat, &block)
+      heartbeat_was = @heartbeat
+      @heartbeat = heartbeat
+
       streamer ||= block
       @streamers << streamer
       if @heartbeat && !@heartbeat_on
@@ -269,18 +283,12 @@ module Datastar
 
       @response.body = body
       @finalize.call(@view_context, @response)
+    ensure
+      @heartbeat = heartbeat_was
     end
 
     private
 
-    def stream_no_heartbeat(&block)
-      was = @heartbeat
-      @heartbeat = false
-      stream(&block).tap do
-        @heartbeat = was
-      end
-    end
-
     # Produce a response body for a single stream
     # In this case, the SSE generator can write directly to the socket
     #

data/lib/datastar/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Datastar
-  VERSION = '1.0.2'
+  VERSION = '1.0.3'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: datastar
 version: !ruby/object:Gem::Version
-  version: 1.0.2
+  version: 1.0.3
 platform: ruby
 authors:
 - Ismael Celis