inertia_cable 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 25d0d8cfcadeb38db163745b520998196f61fa48865253227abe0e3ee22d5686
-  data.tar.gz: 7f7f8affa983fa0c0a1543d1118cf67eb3abd609606b1c16fac076b8e5767ad4
+  metadata.gz: 77598665249ec9fc7f6d8fa69ad070661e2db15513a1720c83e937e318e4b828
+  data.tar.gz: 388cc18e32909027f18da2b65352859299120f18984e2a1e7f15fc1e3fff905a
 SHA512:
-  metadata.gz: 504d3453823e7cf2887da87a0aa9d56839292e2d8fbe2504e7ca76648d0addafef076e2c655eb3d4a1a88d6f688c7709b60237c3c9ed320676dd9fc7a8544a9f
-  data.tar.gz: aba9941405aea7ca05100162c5f7555c0257a9aee672662614167b30d4d75b3e32dd418f8e24d1ce8d014e2e81c4638d3e7d2ab172714d14cc677b51f3bac3a3
+  metadata.gz: 4b9ae8be00c92656c2ce2787e2ec939028a3cebc77cb7c54adbc2acf4c673cebea5e828fae83e3e8f76bef7ee7c10e266de0eea3cdcce5ba3a3180f2705586ef
+  data.tar.gz: 16182946b7e2f836b14aed916c937762002052c8cab9c48617d47eb3599b42e4fcb35b307a1c7c93c59f1e3a08c5f8ef979b09db46a4431a365647a252d6a4b8

data/README.md

@@ -2,7 +2,7 @@
 
 ActionCable broadcast DSL for [Inertia.js](https://inertiajs.com/) Rails applications. Three lines of code to get real-time updates.
 
-InertiaCable broadcasts lightweight JSON signals over ActionCable. The client receives them and calls `router.reload()` to re-fetch props through Inertia's normal HTTP flow. No data travels over the WebSocket — your controller stays the single source of truth.
+InertiaCable broadcasts lightweight JSON signals over ActionCable. The client receives them and calls `router.reload()` to re-fetch props through Inertia's normal HTTP flow — your controller stays the single source of truth. For ephemeral data like job progress or notifications, [direct messages](#direct-messages) stream data over the WebSocket without triggering a reload.
 
 ```
 Model save → after_commit → ActionCable broadcast (signal)
@@ -12,6 +12,8 @@ React hook subscribes → receives signal → router.reload({ only: ['messages']
 Inertia HTTP request → controller re-evaluates props → React re-renders
 ```
 
+> **Coming from Turbo Streams?** `broadcasts_to` replaces `broadcasts_refreshes_to`, and `broadcast_message_to` covers use cases where you'd reach for `broadcast_append_to` or `broadcast_replace_to` — but without HTML partials, since Inertia reloads props from your controller instead.
+
 ## Table of Contents
 
 - [Installation](#installation)
@@ -381,6 +383,15 @@ useInertiaCable(stream, {
 })
 ```
 
+### Broadcasting without a model instance
+
+Use `InertiaCable.broadcast_message_to` from anywhere — jobs, services, controllers — without needing a model instance:
+
+```ruby
+InertiaCable.broadcast_message_to("dashboard", data: { alert: "Deployment complete" })
+InertiaCable.broadcast_message_to(user, :notifications, data: { count: 5 })
+```
+
 Messages are delivered immediately with no debouncing. Each `broadcast_message_to` call triggers exactly one `onMessage` callback.
 
 ---
@@ -407,13 +418,24 @@ end
 
 Optionally coalesce rapid broadcasts using Rails cache. **Not used by default** — the client-side 100ms debounce handles most cases.
 
-Requires a shared cache store (Redis, Memcached, or SolidCache) in multi-process deployments.
+Server-side debounce is useful when a single operation triggers many model callbacks (e.g., bulk imports, cascading updates) and you want to reduce the number of ActionCable messages sent. The client-side debounce already coalesces rapid reloads into one, so server-side debounce is only needed when the volume of WebSocket messages itself is a concern.
+
+Requires a shared cache store (Redis, Memcached, or SolidCache) in multi-process deployments. `MemoryStore` (the Rails default) only works within a single process.
 
 ```ruby
-InertiaCable.debounce_delay = 0.5  # seconds (default)
+# Via the model DSL
+broadcasts_to :board, debounce: true        # uses InertiaCable.debounce_delay (0.5s)
+broadcasts_to :board, debounce: 1.0         # custom delay in seconds
+
+# Via instance methods
+post.broadcast_refresh_later_to(board, debounce: 2.0)
 
+# Direct usage
 InertiaCable::Debounce.broadcast("my_stream", payload)
 InertiaCable::Debounce.broadcast("my_stream", payload, delay: 2.0)
+
+# Configure the global default
+InertiaCable.debounce_delay = 0.5  # seconds (default)
 ```
 
 ---
@@ -464,6 +486,21 @@ end
 
 All three accept splat streamables: `assert_broadcasts_on(chat, :messages) { ... }`
 
+### Broadcast callbacks
+
+`InertiaCable.on_broadcast` registers a callback that fires for every broadcast (including debounced ones). The test helpers use this internally, but you can use it for custom instrumentation or logging:
+
+```ruby
+callback = ->(stream_name, payload) {
+  Rails.logger.info "[InertiaCable] #{payload[:type]} on #{stream_name}"
+}
+
+InertiaCable.on_broadcast(&callback)
+
+# Later, to unregister:
+InertiaCable.off_broadcast(&callback)
+```
+
 ---
 
 ## Configuration

data/lib/inertia_cable/debounce.rb

@@ -6,6 +6,7 @@ module InertiaCable
       return if Rails.cache.exist?(cache_key)
 
       Rails.cache.write(cache_key, true, expires_in: delay)
+      InertiaCable.broadcast_callbacks.each { |cb| cb.call(stream_name, payload) }
       ActionCable.server.broadcast(stream_name, payload)
     end
   end

data/lib/inertia_cable/version.rb

@@ -1,3 +1,3 @@
 module InertiaCable
-  VERSION = "0.2.0"
+  VERSION = "0.2.2"
 end

data/lib/inertia_cable.rb

@@ -28,6 +28,15 @@ module InertiaCable
     ActionCable.server.broadcast(resolved, payload)
   end
 
+  # Broadcast a direct message without a model instance.
+  #
+  #   InertiaCable.broadcast_message_to("dashboard", data: { alert: "done" })
+  #   InertiaCable.broadcast_message_to(user, :notifications, data: { count: 5 })
+  #
+  def self.broadcast_message_to(*streamables, data:)
+    broadcast(streamables, { type: "message", data: data })
+  end
+
   def self.suppressing_broadcasts(&block)
     InertiaCable::Suppressor.suppressing(&block)
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: inertia_cable
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.2
 platform: ruby
 authors:
 - Cole Robertson