inertia_cable 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d3eef5ebaf526671cbdfa7efd381c2487f9ec19633a4dd6478bd3f399f262c1c
-  data.tar.gz: 064c84423d1c5742e146404d410581d5610223e916082e94c71c214336ab3247
+  metadata.gz: 25d0d8cfcadeb38db163745b520998196f61fa48865253227abe0e3ee22d5686
+  data.tar.gz: 7f7f8affa983fa0c0a1543d1118cf67eb3abd609606b1c16fac076b8e5767ad4
 SHA512:
-  metadata.gz: b16694b36fc8c42c3661a66d6ef94329b306a4b40a183f866993ed43460d3538ae120b68b5ec5115d83523cb252204fc34721c52fd93ba93e376a3246287caeb
-  data.tar.gz: '01828651d1f2f96acbe07e85c5b02cd64153a7f7089a99e77c8d054e6694bd71c8514e6a8a7f864735ca0fac42f7c0358681194c0f7de914206f9ed3577e0799'
+  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/generators/inertia_cable/install/install_generator.rb

@@ -1,40 +1,105 @@
 module InertiaCable
   module Generators
     class InstallGenerator < Rails::Generators::Base
-      source_root File.expand_path("templates", __dir__)
-
       desc "Install InertiaCable into your Rails application"
 
-      def copy_cable_setup
-        template "cable_setup.ts", "app/javascript/channels/inertia_cable.ts"
+      def patch_inertia_entrypoint
+        entrypoint = detect_entrypoint
+        unless entrypoint
+          say "Could not find Inertia entrypoint — you'll need to add InertiaCableProvider manually.", :yellow
+          return
+        end
+
+        say "Patching #{entrypoint}...", :green
+
+        # Add import after the createInertiaApp import
+        if File.read(entrypoint).include?("@inertia-cable/react")
+          say "  Import already present, skipping", :yellow
+        else
+          inject_into_file entrypoint, after: /^import \{ createInertiaApp \} from .+\n/ do
+            "import { InertiaCableProvider } from '@inertia-cable/react'\n"
+          end
+        end
+
+        content = File.read(entrypoint)
+
+        if content.include?("InertiaCableProvider")
+          say "  InertiaCableProvider already present, skipping", :yellow
+          return
+        end
+
+        # Pattern 1: createElement style
+        #   createRoot(el).render(createElement(App, props))
+        if content.match?(/createRoot\(el\)\.render\(\s*createElement\(App,\s*props\)\s*\)/)
+          gsub_file entrypoint,
+            /createRoot\(el\)\.render\(\s*createElement\(App,\s*props\)\s*\)/,
+            "createRoot(el).render(\n        createElement(InertiaCableProvider, null, createElement(App, props)),\n      )"
+          say "  Wrapped render in InertiaCableProvider (createElement style)", :green
+
+        # Pattern 2: JSX with StrictMode
+        #   createRoot(el).render(<StrictMode><App {...props} /></StrictMode>)
+        elsif content.match?(/createRoot\(el\)\.render\(\s*\n?\s*<StrictMode>\s*\n?\s*<App\s+\{\.\.\.props\}\s*\/>\s*\n?\s*<\/StrictMode>/)
+          gsub_file entrypoint,
+            /<StrictMode>\s*\n?\s*<App\s+\{\.\.\.props\}\s*\/>\s*\n?\s*<\/StrictMode>/,
+            "<StrictMode>\n        <InertiaCableProvider>\n          <App {...props} />\n        </InertiaCableProvider>\n      </StrictMode>"
+          say "  Wrapped render in InertiaCableProvider (JSX + StrictMode style)", :green
+
+        # Pattern 3: JSX without StrictMode
+        #   createRoot(el).render(<App {...props} />)
+        elsif content.match?(/createRoot\(el\)\.render\(\s*\n?\s*<App\s+\{\.\.\.props\}\s*\/>/)
+          gsub_file entrypoint,
+            /<App\s+\{\.\.\.props\}\s*\/>/,
+            "<InertiaCableProvider>\n          <App {...props} />\n        </InertiaCableProvider>"
+          say "  Wrapped render in InertiaCableProvider (JSX style)", :green
+
+        else
+          say "  Could not detect render pattern — add InertiaCableProvider manually.", :yellow
+          say "  See: https://github.com/cole-robertson/inertia_cable#inertiaCableProvider"
+        end
       end
 
-      def show_instructions
+      def show_next_steps
         say ""
         say "InertiaCable installed!", :green
         say ""
         say "Next steps:"
-        say "  1. Add the npm package to your frontend:"
-        say "     npm install @inertia-cable/react @rails/actioncable"
         say ""
-        say "  2. Ensure ActionCable is configured in config/cable.yml"
-        say "     (use redis adapter for production)"
+        say "  1. Install the npm package:"
+        say "     npm install @inertia-cable/react @rails/actioncable"
         say ""
-        say "  3. Add broadcasts_refreshes_to to your models:"
+        say "  2. Add broadcasts to your models:"
         say "     class Message < ApplicationRecord"
         say "       belongs_to :chat"
-        say "       broadcasts_refreshes_to :chat"
+        say "       broadcasts_to :chat"
         say "     end"
         say ""
-        say "  4. Pass cable_stream prop from your controller:"
+        say "  3. Pass cable_stream prop from your controller:"
         say "     render inertia: 'Chats/Show', props: {"
         say "       cable_stream: inertia_cable_stream(chat)"
         say "     }"
         say ""
-        say "  5. Use the hook in your React component:"
-        say "     useInertiaCable(cable_stream, { only: ['messages'] })"
+        say "  4. Use the hook in your React component:"
+        say "     import { useInertiaCable } from '@inertia-cable/react'"
+        say ""
+        say "     const { connected } = useInertiaCable(cable_stream, { only: ['messages'] })"
         say ""
       end
+
+      private
+
+      def detect_entrypoint
+        candidates = %w[
+          app/frontend/entrypoints/inertia.ts
+          app/frontend/entrypoints/inertia.tsx
+          app/frontend/entrypoints/inertia.js
+          app/frontend/entrypoints/inertia.jsx
+          app/javascript/entrypoints/inertia.ts
+          app/javascript/entrypoints/inertia.tsx
+          app/javascript/entrypoints/inertia.js
+          app/javascript/entrypoints/inertia.jsx
+        ]
+        candidates.find { |f| File.exist?(Rails.root.join(f)) }
+      end
     end
   end
 end

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.0"
+  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.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Cole Robertson
@@ -75,7 +75,6 @@ files:
 - README.md
 - app/channels/inertia_cable/stream_channel.rb
 - lib/generators/inertia_cable/install/install_generator.rb
-- lib/generators/inertia_cable/install/templates/cable_setup.ts
 - lib/inertia_cable.rb
 - lib/inertia_cable/broadcast_job.rb
 - lib/inertia_cable/broadcastable.rb

data/lib/generators/inertia_cable/install/templates/cable_setup.ts

@@ -1,7 +0,0 @@
-// InertiaCable - ActionCable setup for Inertia.js
-//
-// This file is auto-generated by `rails g inertia_cable:install`.
-// You can customize the cable URL below if needed.
-
-export { useInertiaCable } from '@inertia-cable/react'
-export { InertiaCableProvider } from '@inertia-cable/react'