dexiecable 0.1.9 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 390eddcb71f97e5e8755696c49a8ce2417e7f8636e0e43be8742acd4f31f4b59
-  data.tar.gz: 2058ae8d76759483bc047b4e74622154335eb55fa2124052f518f51d14539a0d
+  metadata.gz: d0959acfdf7865fc834899dd5ec5f14c5fbc85bdbc16a874f269bca2688d2579
+  data.tar.gz: 9e1b0ea9fb9a89c8289aa0faa77b47c6cdd09bb6fd336eb14c9292fc7c67d0a1
 SHA512:
-  metadata.gz: 9057f8f5bdbb694a2673c47773db75d2d99a0f3383043908b51152f3f6279a4aabae9f4436dffeebd31e6882d684ca9f505f7a30e5bf1942de89787199a07589
-  data.tar.gz: 39b6503f4ac13bf8abbaae9352ea6b2355bf34f3210dfd2cd99d87413a39a606f389f39236cafca0143aa94621f8bb0be5835fb34c08027cca0d0c2a7ac6feac
+  metadata.gz: a7106c7ed40f0fcf680109f1f476f4195e911836633766c0706d84852621f8a36b76a7eeaa78b2b9fb09ffa5f750a0147fae11a73fc4d8028e75b00840a77799
+  data.tar.gz: 8f78e58b67faef035cf225ce08d79f4ab0b954123fe76385e7f458e995f955f4880827b3c62353b3763ab888b57f47af4d8954978758fb4edbf5e50601d68ec5

data/README.md

@@ -3,7 +3,7 @@
 > [!NOTE]
 > DexieCable is NOT a local-first solution, because it lacks the capability to automatically sync updates back to the server (this might be added later). For now, think of it as a real-time local-cache solution. Also, check out this [blog post introducing DexieCable](https://dev.to/buhrmi/real-time-rails-without-turbo-modern-reactive-uis-with-inertia-and-dexiecable-4lge).
 
-DexieCable augments ActionCable channels with a query DSL that mirrors the Dexie.js API, letting you push database mutations from the server to the client in real time. It also gives you a [`syncs_to_dexie`](#syncs_to_dexie--automatic-model-syncing) ActiveRecord macro for automatic change syncing.
+DexieCable augments ActionCable channels with a query DSL that mirrors the Dexie.js API, letting you push database mutations from the server to the client in real time. It also gives you a [`streams_to_dexie`](#streams_to_dexie--automatic-model-syncing) ActiveRecord macro for automatic change syncing.
 
 You can run any Dexie table update directly inside a channel:
 
@@ -30,11 +30,11 @@ class NotificationsController < ApplicationController
 end
 ```
 
-An even more convenient way is to use the `syncs_to_dexie` macro (more info [below](#syncs_to_dexie--automatic-model-syncing))
+An even more convenient way is to use the `streams_to_dexie` macro (more info [below](#streams_to_dexie--automatic-model-syncing))
 
 ```ruby
 class Notification < ApplicationRecord
-  syncs_to_dexie via: -> { UserChannel[user] }
+  streams_to_dexie via: UserChannel, to: :user
 end
 ```
 
@@ -48,7 +48,7 @@ Add to your `Gemfile`:
 gem "dexiecable"
 ```
 
-Then `bundle install`. The Railtie automatically extends `ActiveRecord::Base` with `syncs_to_dexie`.
+Then `bundle install`. The Railtie automatically extends `ActiveRecord::Base` with `streams_to_dexie`.
 
 ### npm package
 
@@ -131,33 +131,25 @@ UserChannel[current_user]
 
 The full query chain is serialized as JSON and sent over ActionCable. The JS client replays every method call against the local Dexie database in order.
 
-### `syncs_to_dexie` — automatic model syncing
+### `streams_to_dexie` — automatic model syncing
 
-Add to any ActiveRecord model. The simplest approach: pass a Proc to `via` that returns a scoped channel.
-
-```ruby
-class Message < ApplicationRecord
-  syncs_to_dexie via: -> { UserChannel[current_user] }
-end
-```
-
-You can also pass a channel class with `to:` to have DexieCable handle the scoping:
+Add to any ActiveRecord model. Just provide the channel class and the broadcast target.
 
 ```ruby
 class Message < ApplicationRecord
   # Calls send(:receiver), then broadcasts: UserChannel.broadcast_to(receiver, ...)
-  syncs_to_dexie via: UserChannel, to: :receiver
+  streams_to_dexie via: UserChannel, to: :receiver
 
   # String used directly: UserChannel.broadcast_to("global_feed", ...)
-  syncs_to_dexie via: UserChannel, to: "global_feed"
+  streams_to_dexie via: UserChannel, to: "global_feed"
 
   # Procs are also supported. If an array is returned, multiple broadcasts are made
   # conversation.users.each { |u| UserChannel.broadcast_to(u, ...) }
-  syncs_to_dexie via: UserChannel, to: -> { conversation.users }
+  streams_to_dexie via: UserChannel, to: -> { conversation.users }
 end
 ```
 
-Internally, `syncs_to_dexie` sets up the following ActiveRecord callbacks:
+Internally, `streams_to_dexie` sets up the following ActiveRecord callbacks:
 
 | Event | Action |
 |---|---|
@@ -169,21 +161,23 @@ Internally, `syncs_to_dexie` sets up the following ActiveRecord callbacks:
 
 | Option | Default | Description |
 |---|---|---|
-| `via:` | *(required)* | A DexieCable channel class, or a Proc that returns a channel or scoped channel (e.g. `-> { UserChannel[current_user] }`) |
-| `to:` | *(none)* | The stream target passed to `broadcast_to`. Symbol → calls `send`. String → used as-is. Proc → evaluated in record context. Returns a single recipient or collection. Only used when `via` is a channel class. |
+| `via:` | *(required)* | A DexieCable channel class |
+| `to:` | *(none)* | The stream target passed to `broadcast_to`. Symbol → calls `send`. String → used as-is. Proc → evaluated in record context. Returns a single recipient or collection. |
 | `table:` | model's `table_name` | Override the Dexie table name. A Proc is evaluated in the record's context. |
 | `only:` | `[:create, :update, :destroy]` | Limit which events trigger a sync |
 | `with:` | `:as_json_for_dexie` | Method name (Symbol) or Proc for serializing records |
 | `if:` | *(none)* | Symbol (method name) or Proc — only sync when it returns truthy |
 | `unless:` | *(none)* | Symbol (method name) or Proc — skip sync when it returns truthy |
 
-You can combine multiple `syncs_to_dexie` declarations, each with different conditions:
+You can combine multiple `streams_to_dexie` declarations, each with different conditions:
 
 ```ruby
 class Message < ApplicationRecord
-  syncs_to_dexie via: -> { UserChannel[current_user] }
-  syncs_to_dexie via: -> { BoardChannel[board] },
+  streams_to_dexie via: UserChannel, to: -> { sender },
                  if: :published?
+
+  streams_to_dexie via: AdminChannel,
+                 unless: -> { draft? }
 end
 ```
 
@@ -194,14 +188,14 @@ Override `as_json_for_dexie` in your model, or use the `with` option to specify
 ```ruby
 class Message < ApplicationRecord
   # Using the default as_json_for_dexie override:
-  syncs_to_dexie via: -> { UserChannel[current_user] }
+  streams_to_dexie via: UserChannel, to: :sender
 
   def as_json_for_dexie
     super.merge(room_name: room.name)
   end
 
   # Or use a custom serializer method:
-  syncs_to_dexie via: AdminChannel,
+  streams_to_dexie via: AdminChannel, to: :admin,
                  with: :admin_payload
 
   def admin_payload
@@ -209,7 +203,7 @@ class Message < ApplicationRecord
   end
 
   # Or a Proc:
-  syncs_to_dexie via: PublicChannel,
+  streams_to_dexie via: PublicChannel,
                  with: -> { { id: id, summary: body.truncate(100) } }
 end
 ```
@@ -255,7 +249,7 @@ dexie.messages.where("room_id").equals(5).add({ id: 1, text: "hello" })
 
 ### Use sequence IDs to avoid data loss
 
-A common pattern to avoid data loss during transient disconnections is using sequence IDs to bridge the offline gap. When a connection drops, updates continue on the server. Sending the client’s latest known sequence ID upon reconnect allows the backend to query and stream only the records missed while offline.
+A common pattern to avoid data loss during transient disconnections is using sequence IDs to bridge the offline gap and detect gaps in transmitted records. When a connection drops, updates continue on the server. Sending the client’s latest known sequence ID upon reconnect allows the backend to query and stream only the records missed while offline.
 
 To enable this, DexieCable ships its own version of the ActionCable client with one key
 extension: **channel params can be functions**. When a param value is a
@@ -286,7 +280,7 @@ class RoomChannel < ApplicationChannel:Base
 end
 ```
 
-You might want to have look at the [Sequenced](https://github.com/derrickreimer/sequenced) gem to automatically add sequence IDs to your records.
+To add Sequence IDs, you might want to have look at the [Sequenced](https://github.com/derrickreimer/sequenced). Another option is to use [AnyCable](https://docs.anycable.io/rails/getting_started) since it guarantees deliveries of ActionCable messages.
 
 ### Multi-user environments
 

data/lib/dexiecable/active_record_ext.rb

@@ -9,19 +9,17 @@ module DexieCable
       # DexieCable channel.
       #
       #   class Message < ApplicationRecord
-      #     syncs_to_dexie via: -> { UserChannel[current_user] }
-      #     syncs_to_dexie via: PublicChannel
-      #     syncs_to_dexie via: UserChannel, to: :user
-      #     syncs_to_dexie via: UserChannel, to: -> { conversation.users }
-      #     syncs_to_dexie via: -> { tenant_channel }
+      #     streams_to_dexie via: UserChannel, to: :sender
+      #     streams_to_dexie via: UserChannel, to: "global_feed"
+      #     streams_to_dexie via: UserChannel, to: -> { conversation.users }
+      #     streams_to_dexie via: PublicChannel
       #   end
       #
-      # @param via     [Class, Proc] A DexieCable channel class, or a Proc
-      #                  evaluated in record context that returns a channel
-      #                  class or a scoped channel (e.g.
-      #                  +-> { UserChannel[current_user] }+). When +to+
+      # @param via     [Class] A DexieCable channel class. When +to+
       #                  is given, each recipient is mapped through
       #                  +via[to]+ to produce scoped channels.
+      #                  Without +to+, +via+ is used directly as an
+      #                  unscoped channel.
       # @param to      [Proc, Symbol, String] A Proc evaluated in record
       #                  context, a Symbol to call via +send+, or a String
       #                  used directly as the stream name for +broadcast_to+.
@@ -38,7 +36,7 @@ module DexieCable
       #                 returns truthy (evaluated in the record's context).
       # @param unless  [Symbol, Proc] Skip sync if the given method or proc
       #                 returns truthy (evaluated in the record's context).
-      def syncs_to_dexie(via:, to: nil, table: nil, only: nil, with: nil, **options)
+      def streams_to_dexie(via:, to: nil, table: nil, only: nil, with: nil, **options)
         events     = Array(only || %i[create update destroy])
         conditions = options.slice(:if, :unless)
         serializer = with || :as_json_for_dexie
@@ -82,12 +80,11 @@ module DexieCable
     private
 
     def resolve_channel(via, to = nil)
-      channel = via.is_a?(Proc) ? instance_exec(&via) : via
       if to
         recipients = resolve_recipient(to)
-        Array(recipients).map { |r| channel[r] }
+        Array(recipients).map { |r| via[r] }
       else
-        channel
+        via
       end
     end
 

data/lib/dexiecable/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DexieCable
-  VERSION = "0.1.9"
+  VERSION = "0.2.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dexiecable
 version: !ruby/object:Gem::Version
-  version: 0.1.9
+  version: 0.2.0
 platform: ruby
 authors:
 - Stefan Buhrmester
@@ -39,7 +39,7 @@ dependencies:
         version: '7.0'
 description: DexieCable augments ActionCable channels with a query DSL that mirrors
   the Dexie.js API, letting you push database mutations from the server to the client
-  in real time. Includes an ActiveRecord macro (syncs_to_dexie) for automatic change
+  in real time. Includes an ActiveRecord macro (streams_to_dexie) for automatic change
   syncing.
 email:
 - stefan@buhrmi.de
@@ -75,7 +75,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.8
+rubygems_version: 4.0.16
 specification_version: 4
 summary: Run Dexie.js IndexedDB operations from your Rails ActionCable channels.
 test_files: []