inertia_cable 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 467488f15b5926bd5b36c68bf873f04d80a9d1d3196f05b8c610dd7e5bbfed1c
-  data.tar.gz: 3d26e273740a16678aea2b6491afe4af7463c7fa492974d2bdccc393787cdb09
+  metadata.gz: 1a8763f30ddbc3cc7e0fc2ade8280ca8e9c57bcd09bbc7eeb9ac4417071b1608
+  data.tar.gz: b98b8c3d8194fcf5f7cc563e7e7ed82e1e923570f5dda6e7c23803abe1caffb1
 SHA512:
-  metadata.gz: 86b16433049aeedf34d478a398531666dec745556bdc21a2090e0d0023658a11aecab505a02ca7727f9e7d60442079a47e009e78cb778c01a37462b862578fc9
-  data.tar.gz: 3001e9c9acc8cfaf12d1287caf84700bf43fb4c4a7a28cbec30a9fa4a51ffdb890da1b856859bbe6a73d1ddcf504dd5e9feb23dabda698e61647ad8c5ca46dfc
+  metadata.gz: cf7a607e798158e08e5d84a58b33256471cbff94710625cec8f4bfd55ea53e1b7874376f23e99c46b043a805c9942d5584ab53d2db1af73ed3ffcaec17ee3fea
+  data.tar.gz: 35224b191abc4f06d2ae4a726daab3a7f9522a0cefa19244e2bd1fbe0f51dd6936966ce2475f3aedcc49042bd7432561cbc2f155abf00f3ac82538c536eb96ca

data/README.md

@@ -52,6 +52,14 @@ 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.
+
+### Upgrading from 0.2
+
+Upgrade `@inertiajs/react` to `^3.0.0`, React and React DOM to `^19.0.0`, and `inertia_rails` to `~> 3.19` or newer compatible 3.x. Follow the [Inertia Rails v3 upgrade guide](https://inertia-rails.dev/guide/upgrade-guide) for application configuration changes. Then upgrade `inertia_cable` and `@inertia-cable/react` to 0.3.
+
+The hook and Ruby broadcast APIs are unchanged. Use ESM `import` statements; CommonJS `require()` is no longer supported. Background refreshes now preserve existing Inertia page validation errors, including reconnect catch-up reloads.
+
 ## Quick Start
 
 ### 1. Model — declare what broadcasts
@@ -418,13 +426,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)
 ```
 
 ---
@@ -475,6 +494,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
@@ -489,7 +523,7 @@ InertiaCable.debounce_delay = 0.5                        # server-side debounce
 
 ## Security
 
-Stream tokens are HMAC-SHA256 signed using `secret_key_base` and verified server-side on subscription. Invalid tokens are rejected. No data travels over the WebSocket — actual data is fetched via Inertia's normal HTTP cycle, which runs through your controller and its authorization logic on every reload. Token rotation follows `secret_key_base` rotation.
+Stream tokens are HMAC-SHA256 signed using `secret_key_base` and verified server-side on subscription. Invalid tokens are rejected. Refresh signals carry model metadata and any `extra` fields over the WebSocket; page props are fetched through your controller and its authorization logic on every reload. Direct messages send their `data` payload over the WebSocket without running controller authorization again. Only issue stream tokens to authorized users, and ensure every subscriber is allowed to receive the stream's metadata and direct messages. Token rotation follows `secret_key_base` rotation.
 
 ---
 
@@ -508,17 +542,9 @@ inertia_cable_stream(@post.board)  # ✓ signs gid://app/Board/1
 inertia_cable_stream(@post)        # ✗ signs gid://app/Post/1
 ```
 
-### `only`/`except` crashes
+### Reloading selected props
 
-Always pass arrays, never `undefined`:
-
-```tsx
-// Bad
-useInertiaCable(stream, { only: someCondition ? ['messages'] : undefined })
-
-// Good
-useInertiaCable(stream, { ...(someCondition ? { only: ['messages'] } : {}) })
-```
+Pass arrays for `only` and `except`. Omitted or `undefined` filters are safely ignored. Without either filter, refresh signals reload all normally included props.
 
 ### Server-side debounce not working across processes
 
@@ -534,16 +560,24 @@ config.cache_store = :redis_cache_store, { url: ENV["REDIS_URL"] }
 
 - Ruby >= 3.1
 - Rails >= 7.0 (ActionCable, ActiveJob, ActiveSupport)
-- Inertia.js >= 1.0 with React (`@inertiajs/react`)
+- Inertia.js 3.x (`@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)
 
 ## Development
 
 ```bash
 bundle install && bundle exec rspec     # Ruby specs
-cd frontend && npm install && npm test  # Frontend
+cd frontend
+npm ci
+npm run typecheck
+npm test
+npm run build
 ```
 
+The integration app imports the built package through a local file dependency. After building `frontend`, run `npm ci`, `npm run check`, and `npx vite build` in `integration_test`. Rebuild the package after changing its source; use `npm run dev` in `frontend` while developing the example app.
+
 ## License
 
 MIT

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.1"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: inertia_cable
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Cole Robertson
 bindir: bin
 cert_chain: []
-date: 2026-02-03 00:00:00.000000000 Z
+date: 2026-09-10 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actioncable