dexiecable 0.1.6 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b4a75838a91bf8b9ef988b1b2ef14f90e2148df75d80b15127487bb3b9efb8e
-  data.tar.gz: 99ca5b8a8cf6a4b12eca7d54753b0de8c35dc699c22bb172a62b7ca826fa9f6a
+  metadata.gz: 2bc64f029d73e3630a14e254852ea7e6b3cf2b00d369f144c0b40ebdd6d4de1f
+  data.tar.gz: ea3df61fd1319c5f8fcc8697e99a7954213b5c4f97748ae55e3e012e00f156ac
 SHA512:
-  metadata.gz: d77d14a92756f3a05c4c038f93f542953036d3df2e010952659a4833a48997fef2fcf4d145360f03d684a40b8fc25715a3aaf8f5624ff0f6bc3934568ff5806c
-  data.tar.gz: ae7f67b4bf0ab26883afd3ba7c17fc944b6f7fc66f0f862c0c6cec6ff9d494ed749b2436e47d80898dc86d11ed1c44235e679e68b4ff3e9c1b662552e2536b59
+  metadata.gz: f44765e378f1860f5a239cc58169c724bc164c9eada457241a7e70f8cfcbe8ef898e2357d0dfa6981f1a6b3b170f9852a5afdb06e0dee935f7deea0489e568c2
+  data.tar.gz: f1227ada19e9a7ccb9825bb9665ec8f7c57be8afc4b05e9f8dd35c07d8da46f92cfb9cebdb74d5b7e5ef3fe87e3a549e14f039ba4412e4f373706e6e4535a318

data/README.md

@@ -1,8 +1,9 @@
 # DexieCable
 
-Run [Dexie.js](https://dexie.org) IndexedDB operations from your Rails ActionCable channels.
+> [!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` 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 [`syncs_to_dexie`](#syncs_to_dexie--automatic-model-syncing) ActiveRecord macro for automatic change syncing.
 
 You can run any Dexie table update directly inside a channel:
 
@@ -29,11 +30,11 @@ class NotificationsController < ApplicationController
 end
 ```
 
-An even more convenient way is to use the `syncs_to_dexie` macro:
+An even more convenient way is to use the `syncs_to_dexie` macro (more info [below](#syncs_to_dexie--automatic-model-syncing))
 
 ```ruby
 class Notification < ApplicationRecord
-  syncs_to_dexie via: UserChannel, subject: :user
+  syncs_to_dexie via: UserChannel, to: :user
 end
 ```
 
@@ -57,19 +58,26 @@ npm install dexiecable
 yarn add dexiecable
 ```
 
-Configure it with your Dexie database and ActionCable consumer before subscribing:
+Pass your Dexie database as the first argument to `subscribe()`:
 
 ```js
-import { configure, subscribe } from "dexiecable";
+import { subscribe } from "dexiecable";
 import { db } from "./db";
-import { createConsumer } from "@rails/actioncable";
 
-configure({ db, consumer: createConsumer() });
-
-const sub = subscribe("UserChannel", { last_update: Date.now() });
+subscribe(db, "UserChannel");
 ```
 
-If you omit `consumer`, one is created for you automatically.
+A consumer is lazily created on the first `subscribe()` call. If you need to access or set the consumer explicitly, use `getConsumer()` and `setConsumer()`:
+
+```js
+import { getConsumer, setConsumer, createConsumer } from "dexiecable";
+
+// Get the consumer (creates one lazily if needed)
+const consumer = getConsumer();
+
+// Or set a custom one
+setConsumer(createConsumer("wss://example.com/cable"));
+```
 
 ## Usage
 
@@ -89,7 +97,7 @@ This gives you:
 
 | Method | Description |
 |---|---|
-| `self.[](subject)` | Returns a `ScopedChannel` bound to a subject. `UserChannel[current_user]` |
+| `self.[](to)` | Returns a `ScopedChannel` bound to a recipient. `UserChannel[current_user]` |
 | `table(name)` | Starts a query chain. `table("messages")` |
 
 ### Chaining Dexie operations
@@ -125,36 +133,39 @@ The full query chain is serialized as JSON and sent over ActionCable. The JS cli
 
 ### `syncs_to_dexie` — automatic model syncing
 
-Add to any ActiveRecord model. `subject` is what gets passed to `broadcast_to` as the stream target:
+Add to any ActiveRecord model. Just provide the channel class and the broadcast target.
 
 ```ruby
 class Message < ApplicationRecord
-  # Calls send(:receiver), then broadcasts: broadcast_to(receiver, ...)
-  syncs_to_dexie via: UserChannel, subject: :receiver
+  # Calls send(:receiver), then broadcasts: UserChannel.broadcast_to(receiver, ...)
+  syncs_to_dexie via: UserChannel, to: :receiver
 
-  # String used directly: broadcast_to("global_feed", ...)
-  syncs_to_dexie via: UserChannel, subject: "global_feed"
+  # String used directly: UserChannel.broadcast_to("global_feed", ...)
+  syncs_to_dexie via: UserChannel, to: "global_feed"
 
   # Procs are also supported. If an array is returned, multiple broadcasts are made
-  # conversation.users.each { |u| broadcast_to(u, ...) }
-  syncs_to_dexie via: UserChannel, subject: -> { conversation.users }
+  # conversation.users.each { |u| UserChannel.broadcast_to(u, ...) }
+  syncs_to_dexie via: UserChannel, to: -> { conversation.users }
 end
 ```
 
+Internally, `syncs_to_dexie` sets up the following ActiveRecord callbacks:
+
 | Event | Action |
 |---|---|
-| `after_commit on: :create` | `channel.table("messages").add(record.as_json_for_dexie)` |
-| `after_commit on: :update` | `channel.table("messages").put(record.as_json_for_dexie)` |
-| `after_commit on: :destroy` | `channel.table("messages").delete(record.id)` |
+| `after_commit on: :create` | `channel.table(table).add(as_json_for_dexie)` |
+| `after_commit on: :update` | `channel.table(table).update(id, as_json_for_dexie.slice(*saved_changes.keys))` |
+| `after_commit on: :destroy` | `channel.table(table).delete(id)` |
 
 #### Options
 
 | Option | Default | Description |
 |---|---|---|
 | `via:` | *(required)* | A DexieCable channel class |
-| `subject:` | *(none)* | The stream target passed to `broadcast_to`. Symbol → calls `send`. String → used as-is. Proc → evaluated in record context. Returns a single subject or collection. |
+| `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 |
 
@@ -162,7 +173,7 @@ You can combine multiple `syncs_to_dexie` declarations, each with different cond
 
 ```ruby
 class Message < ApplicationRecord
-  syncs_to_dexie via: UserChannel, subject: -> { sender },
+  syncs_to_dexie via: UserChannel, to: -> { sender },
                  if: :published?
 
   syncs_to_dexie via: AdminChannel,
@@ -172,15 +183,28 @@ end
 
 #### Customizing the synced payload
 
-Override `as_json_for_dexie` in your model:
+Override `as_json_for_dexie` in your model, or use the `with` option to specify a different method or Proc:
 
 ```ruby
 class Message < ApplicationRecord
-  syncs_to_dexie via: UserChannel, subject: :sender
+  # Using the default as_json_for_dexie override:
+  syncs_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, to: :admin,
+                 with: :admin_payload
+
+  def admin_payload
+    attributes.slice("id", "body", "flagged")
+  end
+
+  # Or a Proc:
+  syncs_to_dexie via: PublicChannel,
+                 with: -> { { id: id, summary: body.truncate(100) } }
 end
 ```
 
@@ -221,6 +245,60 @@ The JS side replays it as:
 dexie.messages.where("room_id").equals(5).add({ id: 1, text: "hello" })
 ```
 
+## Recipies
+
+### 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.
+
+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
+function, it is called and awaited at subscribe time — use this to submit the latest known sequence ID on connection:
+
+```js
+import { subscribe } from "dexiecable";
+import { db, getLastSeqId } from './database';
+
+const roomId = 123;
+
+subscribe(db, {
+  channel: "RoomChannel",
+  room_id: roomId,
+  seq_id: () => getLastSeqId(roomId) // evaluated fresh on each reconnect
+});
+```
+
+Send missed messages on reconnection:
+
+```ruby
+class RoomChannel < ApplicationChannel:Base
+  def subscribed
+    stream_from "room:#{params[:room_id]}"
+    missed_messages = room.messages.where("seq_id > ?", params[:seq_id])
+    table("messages").bulkAdd(missed_messages)
+  end
+end
+```
+
+You might want to have look at the [Sequenced](https://github.com/derrickreimer/sequenced) gem to automatically add sequence IDs to your records.
+
+### Multi-user environments
+
+In multi-user or multi-tenant applications, you can isolate records by binding different subscription channels to separate Dexie database instances. This prevents local data leaks between user accounts and keeps private user data separate from public or shared feeds.
+
+```js
+
+import Dexie from 'dexie'
+import { subscribe } from 'dexiecable'
+
+const userDB = new Dexie("user_"+userId)
+const sharedDB = new Dexie("shared")
+
+subscribe(userDB, 'UserChannel')
+subscribe(sharedDB, 'PublicChannel')
+
+```
+
 ## License
 
 MIT

data/lib/dexiecable/active_record_ext.rb

@@ -9,43 +9,46 @@ module DexieCable
       # DexieCable channel.
       #
       #   class Message < ApplicationRecord
-      #     syncs_to_dexie via: UserChannel, subject: :sender
-      #     syncs_to_dexie via: UserChannel, subject: "global_feed"
-      #     syncs_to_dexie via: UserChannel, subject: -> { conversation.users }
+      #     syncs_to_dexie via: UserChannel, to: :sender
+      #     syncs_to_dexie via: UserChannel, to: "global_feed"
+      #     syncs_to_dexie via: UserChannel, to: -> { conversation.users }
       #     syncs_to_dexie via: PublicChannel
       #   end
       #
-      # @param via     [Class] A DexieCable channel class. When +subject+
-      #                  is given, each subject is mapped through
-      #                  +via[subject]+ to produce scoped channels.
-      #                  Without +subject+, +via+ is used directly as an
+      # @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 subject [Proc, Symbol, String] A Proc evaluated in record
+      # @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+.
-      #                  Must return a single subject or collection of
-      #                  subjects.
+      #                  Must return a single recipient or collection of
+      #                  recipients.
       # @param table   [String, Symbol, Proc] Override the Dexie table name
       #                 (defaults to the model's table_name). A Proc is
       #                 evaluated in the record's context.
       # @param only    [Array<Symbol>] Limit which lifecycle events sync.
       #                 Default: [:create, :update, :destroy].
+      # @param with [Symbol, Proc] Method name or proc to use for
+      #                 serializing records (defaults to :as_json_for_dexie).
       # @param if      [Symbol, Proc] Only sync if the given method or proc
       #                 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:, subject: nil, table: nil, only: nil, **options)
+      def syncs_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
 
         @dexie_sync_configs ||= []
-        @dexie_sync_configs << { via: via, subject: subject, table: table, only: events, **conditions }
+        @dexie_sync_configs << { via: via, to: to, table: table, only: events, with: serializer, **conditions }
 
         if events.include?(:destroy)
           before_destroy :dexie_sync_before_destroy
 
           after_commit on: :destroy, **conditions do
-            Array(resolve_channel(via, subject)).each do |channel|
+            Array(resolve_channel(via, to)).each do |channel|
               next unless channel
               channel.table(resolve_table(table)).delete(dexie_destroy_id)
             end
@@ -54,19 +57,19 @@ module DexieCable
 
         if events.include?(:create)
           after_commit on: :create, **conditions do
-            Array(resolve_channel(via, subject)).each do |channel|
+            Array(resolve_channel(via, to)).each do |channel|
               next unless channel
-              channel.table(resolve_table(table)).add(as_json_for_dexie)
+              channel.table(resolve_table(table)).add(serialize_record(serializer))
             end
           end
         end
 
         if events.include?(:update)
           after_commit on: :update, **conditions do
-            Array(resolve_channel(via, subject)).each do |channel|
+            Array(resolve_channel(via, to)).each do |channel|
               next unless channel
 
-              changes = as_json_for_dexie.slice(*saved_changes.keys)
+              changes = serialize_record(serializer).slice(*saved_changes.keys)
               channel.table(resolve_table(table)).update(id, changes)
             end
           end
@@ -76,20 +79,20 @@ module DexieCable
 
     private
 
-    def resolve_channel(via, subject = nil)
-      if subject
-        subjects = resolve_subject(subject)
-        Array(subjects).map { |s| via[s] }
+    def resolve_channel(via, to = nil)
+      if to
+        recipients = resolve_recipient(to)
+        Array(recipients).map { |r| via[r] }
       else
         via
       end
     end
 
-    def resolve_subject(subject)
-      case subject
-      when Proc   then instance_exec(&subject)
-      when Symbol then send(subject)
-      else subject
+    def resolve_recipient(to)
+      case to
+      when Proc   then instance_exec(&to)
+      when Symbol then send(to)
+      else to
       end
     end
 
@@ -101,6 +104,14 @@ module DexieCable
       end
     end
 
+    def serialize_record(serializer)
+      case serializer
+      when Proc   then instance_exec(&serializer)
+      when Symbol then send(serializer)
+      else serializer
+      end
+    end
+
     # Override in your model to customise the payload synced to Dexie.
     def as_json_for_dexie
       as_json

data/lib/dexiecable/concern.rb

@@ -6,12 +6,12 @@ module DexieCable
   included do
     public :transmit
 
-    # Open a scoped channel for broadcasting to a specific subject.
+    # Open a scoped channel for broadcasting to a specific recipient.
     #
     #   UserChannel[current_user].table("notifications").add(notification)
     #
-    def self.[](subject)
-      ScopedChannel.new(self, subject)
+    def self.[](recipient)
+      ScopedChannel.new(self, recipient)
     end
 
     # Build a query against a Dexie table, transmitted to all subscribers

data/lib/dexiecable/scoped_channel.rb

@@ -2,9 +2,9 @@
 
 module DexieCable
   class ScopedChannel
-    def initialize(klass, subject)
-      @klass   = klass
-      @subject = subject
+    def initialize(klass, recipient)
+      @klass     = klass
+      @recipient = recipient
     end
 
     def table(name)
@@ -12,7 +12,7 @@ module DexieCable
     end
 
     def transmit(data)
-      @klass.broadcast_to @subject, data
+      @klass.broadcast_to @recipient, data
     end
   end
 end

data/lib/dexiecable/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dexiecable
 version: !ruby/object:Gem::Version
-  version: 0.1.6
+  version: 0.1.8
 platform: ruby
 authors:
 - Stefan Buhrmester