inertia_cable 0.1.1 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0e8633ccfd90aba7b7ae8a00203730d29755a65c1fc2f825ad9bde1225445387
-  data.tar.gz: 43f041337383fd933d2e7a6b2b9bafa17e8876f22b0bccc9a0b48ffd3b8bd007
+  metadata.gz: 25d0d8cfcadeb38db163745b520998196f61fa48865253227abe0e3ee22d5686
+  data.tar.gz: 7f7f8affa983fa0c0a1543d1118cf67eb3abd609606b1c16fac076b8e5767ad4
 SHA512:
-  metadata.gz: ae7f293c9a1988f85bb2589119dd9cca2752ad4a81ebabc4c3bc2e656e6ee74d6808cc1068c7c026d8a9fa3aa47b95f55cf49e31681a4612b485d2d6633988f4
-  data.tar.gz: 239981663473b24453c8029787f2f869e9f39da6af222943b36adc1d6d58084d8c7f17fa5e5ca153e2635efe496d1c7415e2b8bdc25e59db07b7475d857d35be
+  metadata.gz: 504d3453823e7cf2887da87a0aa9d56839292e2d8fbe2504e7ca76648d0addafef076e2c655eb3d4a1a88d6f688c7709b60237c3c9ed320676dd9fc7a8544a9f
+  data.tar.gz: aba9941405aea7ca05100162c5f7555c0257a9aee672662614167b30d4d75b3e32dd418f8e24d1ce8d014e2e81c4638d3e7d2ab172714d14cc677b51f3bac3a3

data/README.md

@@ -19,6 +19,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 +182,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 +206,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 +251,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 +266,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 +318,70 @@ 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)
+})
+```
+
+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.0"
 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.0
 platform: ruby
 authors:
 - Cole Robertson