inertia_cable 0.1.1 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e8633ccfd90aba7b7ae8a00203730d29755a65c1fc2f825ad9bde1225445387
-  data.tar.gz: 43f041337383fd933d2e7a6b2b9bafa17e8876f22b0bccc9a0b48ffd3b8bd007
+  metadata.gz: 467488f15b5926bd5b36c68bf873f04d80a9d1d3196f05b8c610dd7e5bbfed1c
+  data.tar.gz: 3d26e273740a16678aea2b6491afe4af7463c7fa492974d2bdccc393787cdb09
 SHA512:
-  metadata.gz: ae7f293c9a1988f85bb2589119dd9cca2752ad4a81ebabc4c3bc2e656e6ee74d6808cc1068c7c026d8a9fa3aa47b95f55cf49e31681a4612b485d2d6633988f4
-  data.tar.gz: 239981663473b24453c8029787f2f869e9f39da6af222943b36adc1d6d58084d8c7f17fa5e5ca153e2635efe496d1c7415e2b8bdc25e59db07b7475d857d35be
+  metadata.gz: 86b16433049aeedf34d478a398531666dec745556bdc21a2090e0d0023658a11aecab505a02ca7727f9e7d60442079a47e009e78cb778c01a37462b862578fc9
+  data.tar.gz: 3001e9c9acc8cfaf12d1287caf84700bf43fb4c4a7a28cbec30a9fa4a51ffdb890da1b856859bbe6a73d1ddcf504dd5e9feb23dabda698e61647ad8c5ca46dfc

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)
@@ -19,6 +21,7 @@ Inertia HTTP request → controller re-evaluates props → React re-renders
 - [Model DSL](#model-dsl)
 - [Controller Helper](#controller-helper)
 - [React Hook](#react-hook)
+- [Direct Messages](#direct-messages)
 - [Suppressing Broadcasts](#suppressing-broadcasts)
 - [Server-Side Debounce](#server-side-debounce)
 - [Testing](#testing)
@@ -181,11 +184,16 @@ post.broadcast_refresh_later_to(board, debounce: 2.0)
 
 # With inline condition (block — skips broadcast if falsy)
 post.broadcast_refresh_to(board) { published? }
+
+# Direct messages (ephemeral data, no prop reload)
+post.broadcast_message_to(board, data: { progress: 50 })
+post.broadcast_message_later_to(board, data: { progress: 50 })
+post.broadcast_message_to(board, data: { progress: 50 }) { running? }
 ```
 
 ### Broadcast payload
 
-Every broadcast sends this JSON:
+Refresh broadcasts send this JSON:
 
 ```json
 {
@@ -200,6 +208,17 @@ Every broadcast sends this JSON:
 
 The `action` field is `"create"`, `"update"`, or `"destroy"`. The `extra` field contains data from the `extra:` option (empty object if not set).
 
+Message broadcasts send a minimal payload:
+
+```json
+{
+  "type": "message",
+  "data": { "progress": 50, "total": 200 }
+}
+```
+
+Messages are ephemeral — no `model`, `id`, `action`, or `timestamp` fields.
+
 ---
 
 ## Controller Helper
@@ -234,6 +253,9 @@ const { connected } = useInertiaCable(cable_stream, {
     console.log(`${data.model} #${data.id} was ${data.action}`)
     if (data.extra?.priority === 'high') toast.warn('Priority update!')
   },
+  onMessage: (data) => {        // receive direct messages (no reload)
+    setProgress(data.progress)
+  },
   onConnected: () => {},        // subscription connected
   onDisconnected: () => {},     // connection dropped
   debounce: 200,                // client-side debounce in ms (default: 100)
@@ -246,6 +268,7 @@ const { connected } = useInertiaCable(cable_stream, {
 | `only` | `string[]` | — | Only reload these props |
 | `except` | `string[]` | — | Reload all props except these |
 | `onRefresh` | `(data) => void` | — | Callback before each reload |
+| `onMessage` | `(data) => void` | — | Receive direct message data (no reload) |
 | `onConnected` | `() => void` | — | Called when subscription connects |
 | `onDisconnected` | `() => void` | — | Called when connection drops |
 | `debounce` | `number` | `100` | Debounce delay in ms |
@@ -297,7 +320,79 @@ createInertiaApp({
 
 `getConsumer()` and `setConsumer()` are also exported for low-level access to the ActionCable consumer singleton.
 
-TypeScript types (`RefreshPayload`, `UseInertiaCableOptions`, `UseInertiaCableReturn`, `InertiaCableProviderProps`) are exported from `@inertia-cable/react`.
+TypeScript types (`RefreshPayload`, `MessagePayload`, `CablePayload`, `UseInertiaCableOptions`, `UseInertiaCableReturn`, `InertiaCableProviderProps`) are exported from `@inertia-cable/react`. `CablePayload` is a discriminated union of `RefreshPayload | MessagePayload` for type-safe handling of raw payloads.
+
+---
+
+## Direct Messages
+
+Push ephemeral data directly into React state over the same signed stream — no prop reload, no extra hook.
+
+### Job progress example
+
+```ruby
+# app/jobs/csv_import_job.rb
+class CsvImportJob < ApplicationJob
+  def perform(import)
+    rows = CSV.read(import.file.path)
+    rows.each_with_index do |row, i|
+      process_row(row)
+      import.broadcast_message_to(import.user, data: { progress: i + 1, total: rows.size })
+    end
+    import.broadcast_refresh_to(import.user) # final reload with completed data
+  end
+end
+```
+
+```tsx
+import { useState } from 'react'
+import { useInertiaCable } from '@inertia-cable/react'
+
+export default function ImportShow({ import_record, cable_stream }) {
+  const [progress, setProgress] = useState<{ progress: number; total: number } | null>(null)
+
+  useInertiaCable(cable_stream, {
+    only: ['import_record'],
+    onMessage: (data) => setProgress({ progress: data.progress as number, total: data.total as number }),
+  })
+
+  return (
+    <div>
+      <h1>Import #{import_record.id}</h1>
+      {progress && <p>Processing {progress.progress} / {progress.total}</p>}
+    </div>
+  )
+}
+```
+
+### Usage patterns
+
+```tsx
+// Prop reload only (unchanged)
+useInertiaCable(stream, { only: ['messages'] })
+
+// Direct data only (no reload)
+useInertiaCable(stream, {
+  onMessage: (data) => setProgress(data.progress)
+})
+
+// Both — progress during job, final reload on completion
+useInertiaCable(stream, {
+  only: ['imports'],
+  onMessage: (data) => setProgress(data.progress)
+})
+```
+
+### 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.
 
 ---
 

data/lib/inertia_cable/broadcastable.rb

@@ -128,6 +128,33 @@ module InertiaCable
       broadcast_refresh_later_to(self.class.model_name.plural, &block)
     end
 
+    # Broadcast a direct message synchronously to explicit stream(s).
+    #
+    #   post.broadcast_message_to(board, data: { progress: 50 })
+    #   post.broadcast_message_to(board, :posts, data: { progress: 50 })
+    #   post.broadcast_message_to(board, data: { progress: 50 }) { running? }
+    #
+    def broadcast_message_to(*streamables, data:, &block)
+      return if self.class.suppressed_inertia_cable_broadcasts?
+      return if block && !instance_exec(&block)
+
+      InertiaCable.broadcast(streamables, message_payload(data: data))
+    end
+
+    # Broadcast a direct message asynchronously to explicit stream(s).
+    #
+    #   post.broadcast_message_later_to(board, data: { progress: 50 })
+    #   post.broadcast_message_later_to(board, :posts, data: { progress: 50 })
+    #   post.broadcast_message_later_to(board, data: { progress: 50 }) { running? }
+    #
+    def broadcast_message_later_to(*streamables, data:, &block)
+      return if self.class.suppressed_inertia_cable_broadcasts?
+      return if block && !instance_exec(&block)
+
+      resolved = InertiaCable::Streams::StreamName.stream_name_from(streamables)
+      InertiaCable::BroadcastJob.perform_later(resolved, message_payload(data: data))
+    end
+
     private
 
     def resolve_stream(stream)
@@ -168,5 +195,9 @@ module InertiaCable
       payload[:extra] = extra if extra.present?
       payload
     end
+
+    def message_payload(data:)
+      { type: "message", data: data }
+    end
   end
 end

data/lib/inertia_cable/version.rb

@@ -1,3 +1,3 @@
 module InertiaCable
-  VERSION = "0.1.1"
+  VERSION = "0.2.1"
 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.1.1
+  version: 0.2.1
 platform: ruby
 authors:
 - Cole Robertson