inertia_cable 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1a8763f30ddbc3cc7e0fc2ade8280ca8e9c57bcd09bbc7eeb9ac4417071b1608
-  data.tar.gz: b98b8c3d8194fcf5f7cc563e7e7ed82e1e923570f5dda6e7c23803abe1caffb1
+  metadata.gz: 65880c281b47d6ea0c032a6a44adb84554f9927668d817c589b8c16c53db74a5
+  data.tar.gz: ae6a35e548370cce9572c6e0a404dbc527c7e2ec419996defe36f72b258aac38
 SHA512:
-  metadata.gz: cf7a607e798158e08e5d84a58b33256471cbff94710625cec8f4bfd55ea53e1b7874376f23e99c46b043a805c9942d5584ab53d2db1af73ed3ffcaec17ee3fea
-  data.tar.gz: 35224b191abc4f06d2ae4a726daab3a7f9522a0cefa19244e2bd1fbe0f51dd6936966ce2475f3aedcc49042bd7432561cbc2f155abf00f3ac82538c536eb96ca
+  metadata.gz: decce67595c86d5dc150feb10a2e505612d1d64aaaeded7eb2b22ca645c30f5e84697cbd22d5bf37304dcb71897ad3d2d34e52a26758cea81f14a37444ac188c
+  data.tar.gz: 7150f27fc86c68df0cb96fcfd026c8122c0cadce8e355c71b6d22c80cb4a13ef45868a1d9a4e32ddd2383fe610a08a2e72f697d8a8007737215a16c5f7d35e18

data/README.md

@@ -52,7 +52,11 @@ Optionally run the install generator:
 rails generate inertia_cable:install
 ```
 
-Version 0.3 targets **Inertia.js 3 and React 19**, and ships ES modules only. Applications on Inertia 1 or 2 should stay on `@inertia-cable/react@0.2` until upgrading.
+Version 0.4 targets **Inertia.js 3.7+ and React 19**, and ships ES modules only. Applications on Inertia 1 or 2 should stay on `@inertia-cable/react@0.2` until upgrading.
+
+### Upgrading from 0.3
+
+Upgrade `@inertiajs/react` to `^3.7.0`. Existing subscriptions keep working. The new coordinator uses Inertia's built-in rest-mode polling; the Ruby broadcast protocol is unchanged and works with the 0.3 gem.
 
 ### Upgrading from 0.2
 
@@ -251,7 +255,47 @@ The token is verified server-side when the client subscribes — invalid or tamp
 
 ### `useInertiaCable(signedStreamName, options?)`
 
-Returns `{ connected }` — a boolean indicating whether the WebSocket subscription is active.
+Returns `{ connected, status, refreshing, lastRefreshedAt, refreshError }`. `status` is `disabled`, `connecting`, `connected`, `reconnecting`, or `rejected`. `lastRefreshedAt` is a completion timestamp in milliseconds, initially `null`; a connected socket alone does not prove fresh page data. `onRejected` observes subscription rejection.
+
+The optional `refresh(context)` callback replaces the default reload. Its context contains `reason` (`broadcast` or `reconnect`), `only`, and `except`. Return a promise to track completion/failure in this hook, or return void when another coordinator owns freshness. `onRefresh(payload)` remains an observer of broadcast signals and does not replace reloads.
+
+### Shared refresh coordination
+
+Use one coordinator per mounted page and share it across subscriptions:
+
+```tsx
+import { router } from '@inertiajs/react'
+import { useInertiaCable, useInertiaRefresh } from '@inertia-cable/react'
+
+const live = useInertiaRefresh({
+  scope: `${site.id}:${pageUrl}`,
+  only: ['orders', 'shipments'],
+  debounce: 100,
+  pollInterval: 60_000,
+})
+useInertiaCable(orderStream, {
+  only: ['orders'],
+  debounce: 0,
+  refresh: ({ only }) => live.refresh(only),
+  onConnected: () => live.refresh(),
+})
+useInertiaCable(shipmentStream, {
+  only: ['shipments'],
+  debounce: 0,
+  refresh: ({ only }) => live.refresh(only),
+})
+
+// Route scope-changing controls through the barrier.
+const selectSite = (id: number) => live.visit(() => {
+  router.get('/operations', { site_id: id }, { preserveState: true })
+})
+```
+
+`useInertiaRefresh({ scope, only, enabled?, debounce?, pollInterval? })` returns `refresh(keys?)`, `visit(run)`, `refreshing`, `lastRefreshedAt`, and `error`. It unions invalidated prop keys, permits one owned reload at a time, and retains a trailing refresh when signals arrive during a request. The default debounce is 100ms; polling is opt-in. Hidden tabs pause polling and catch up when visible. An optional `onConnected` catch-up also covers changes between the initial HTTP response and subscription.
+
+Use `live`'s freshness fields when delegating with a void callback. `scope` must change with the selected site/filter. `visit(run)` cancels the coordinator's request or waits for response processing to finish before running navigation, preserving the original closure and callbacks. Automatic router listeners also yield to other visits, but cannot delay a visit already started elsewhere: route same-page scope changes through `visit`. It never cancels unrelated requests. Inertia continues to own HTTP, prop merging, form state, and polling.
+
+For non-hook integration, `createInertiaRefresh({ only, debounce?, pollInterval? })` exposes the same `refresh`/`visit` operations plus `getSnapshot()`, `subscribe(listener)` (returns unsubscribe), and `dispose()`. Create it only in a browser lifecycle and always dispose it on scope changes/unmount. The React hook handles this lifecycle, including SSR.
 
 ```tsx
 const { connected } = useInertiaCable(cable_stream, {
@@ -560,7 +604,7 @@ config.cache_store = :redis_cache_store, { url: ENV["REDIS_URL"] }
 
 - Ruby >= 3.1
 - Rails >= 7.0 (ActionCable, ActiveJob, ActiveSupport)
-- Inertia.js 3.x (`@inertiajs/react`) with React and React DOM 19.x
+- Inertia.js >= 3.7, < 4 (`@inertiajs/react`) with React and React DOM 19.x
 - `inertia_rails` >= 3.19, < 4 for Inertia.js 3 applications
 - An ESM-capable frontend build setup (such as Vite)
 - ActionCable configured with Redis or SolidCable (production) or async (development)

data/lib/inertia_cable/version.rb

@@ -1,3 +1,3 @@
 module InertiaCable
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: inertia_cable
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Cole Robertson
 bindir: bin
 cert_chain: []
-date: 2026-09-10 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actioncable
@@ -104,7 +104,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.2
+rubygems_version: 3.6.9
 specification_version: 4
 summary: ActionCable broadcast DSL for Inertia Rails
 test_files: []