dexiecable 0.2.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d0959acfdf7865fc834899dd5ec5f14c5fbc85bdbc16a874f269bca2688d2579
-  data.tar.gz: 9e1b0ea9fb9a89c8289aa0faa77b47c6cdd09bb6fd336eb14c9292fc7c67d0a1
+  metadata.gz: b462191000153b424593099689d503a34152404f08cd33911f8db01a61d154cf
+  data.tar.gz: 3fd86cd2c4b9cb4a73b43fc0fee7e686a91a9c4d1a1e390cc544d87f0dddbdc0
 SHA512:
-  metadata.gz: a7106c7ed40f0fcf680109f1f476f4195e911836633766c0706d84852621f8a36b76a7eeaa78b2b9fb09ffa5f750a0147fae11a73fc4d8028e75b00840a77799
-  data.tar.gz: 8f78e58b67faef035cf225ce08d79f4ab0b954123fe76385e7f458e995f955f4880827b3c62353b3763ab888b57f47af4d8954978758fb4edbf5e50601d68ec5
+  metadata.gz: 933c9999fa8d60d04fb3571a094568f1fe78ace8f3a13de6e48dd18d71471e647a1b33c6eb49e2ec6123321933967a8479a1fb6c10906412b5a518302b141f66
+  data.tar.gz: 13751b561bb8f7d57d05ba7639b474c15d3077262a3ec488a8f217f1d5c20be4235757172eac5fa1b5e558af50b5c97d6d253d5a04544c60c80a768f44ab3049

data/README.md

@@ -1,9 +1,11 @@
 # DexieCable
 
 > [!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).
+> The current version of DexieCable is NOT a local-first solution, because it lacks the capability to automatically sync updates back to the server. For now, think of it more as an alternative to turbo streams that works well with component frameworks.
+>
+> Full synchronization utilizing event streams will arrive in DexieCable 2.0.
 
-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.
+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_via`](#streams_via--automatic-model-syncing) ActiveRecord macro for automatic change syncing.
 
 You can run any Dexie table update directly inside a channel:
 
@@ -30,11 +32,11 @@ class NotificationsController < ApplicationController
 end
 ```
 
-An even more convenient way is to use the `streams_to_dexie` macro (more info [below](#streams_to_dexie--automatic-model-syncing))
+An even more convenient way is to use the `streams_via` macro (more info [below](#streams_via--automatic-model-syncing))
 
 ```ruby
 class Notification < ApplicationRecord
-  streams_to_dexie via: UserChannel, to: :user
+  streams_via UserChannel, to: :user
 end
 ```
 
@@ -48,7 +50,7 @@ Add to your `Gemfile`:
 gem "dexiecable"
 ```
 
-Then `bundle install`. The Railtie automatically extends `ActiveRecord::Base` with `streams_to_dexie`.
+Then `bundle install`. The Railtie automatically extends `ActiveRecord::Base` with `streams_via`.
 
 ### npm package
 
@@ -131,25 +133,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.
 
-### `streams_to_dexie` — automatic model syncing
+### `streams_via` — automatic model streaming
 
-Add to any ActiveRecord model. Just provide the channel class and the broadcast target.
+Add to any ActiveRecord model. Just provide the channel class and, optionally, the broadcast target.
 
 ```ruby
 class Message < ApplicationRecord
   # Calls send(:receiver), then broadcasts: UserChannel.broadcast_to(receiver, ...)
-  streams_to_dexie via: UserChannel, to: :receiver
+  streams_via UserChannel, to: :receiver
 
-  # String used directly: UserChannel.broadcast_to("global_feed", ...)
-  streams_to_dexie via: UserChannel, to: "global_feed"
+  # String used directly: RoomChannel.broadcast_to("public", ...)
+  streams_via RoomChannel, to: "public"
 
   # Procs are also supported. If an array is returned, multiple broadcasts are made
   # conversation.users.each { |u| UserChannel.broadcast_to(u, ...) }
-  streams_to_dexie via: UserChannel, to: -> { conversation.users }
+  streams_via UserChannel, to: -> { conversation.users }
 end
 ```
 
-Internally, `streams_to_dexie` sets up the following ActiveRecord callbacks:
+Internally, `streams_via` sets up the following ActiveRecord callbacks:
 
 | Event | Action |
 |---|---|
@@ -161,23 +163,23 @@ Internally, `streams_to_dexie` sets up the following ActiveRecord callbacks:
 
 | Option | Default | Description |
 |---|---|---|
-| `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. |
+| *(first argument)* | *(required)* | A DexieCable channel class |
+| `to:` | the record itself | 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 `streams_to_dexie` declarations, each with different conditions:
+You can combine multiple `streams_via` declarations, each with different conditions:
 
 ```ruby
 class Message < ApplicationRecord
-  streams_to_dexie via: UserChannel, to: -> { sender },
-                 if: :published?
+  streams_via UserChannel, to: -> { sender },
+              if: :published?
 
-  streams_to_dexie via: AdminChannel,
-                 unless: -> { draft? }
+  streams_via AdminChannel,
+              unless: -> { draft? }
 end
 ```
 
@@ -188,23 +190,23 @@ 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:
-  streams_to_dexie via: UserChannel, to: :sender
+  streams_via UserChannel, to: :sender
 
   def as_json_for_dexie
     super.merge(room_name: room.name)
   end
 
   # Or use a custom serializer method:
-  streams_to_dexie via: AdminChannel, to: :admin,
-                 with: :admin_payload
+  streams_via AdminChannel, to: :admin,
+             with: :admin_payload
 
   def admin_payload
     attributes.slice("id", "body", "flagged")
   end
 
   # Or a Proc:
-  streams_to_dexie via: PublicChannel,
-                 with: -> { { id: id, summary: body.truncate(100) } }
+  streams_via PublicChannel,
+             with: -> { { id: id, summary: body.truncate(100) } }
 end
 ```
 

data/lib/dexiecable/active_record_ext.rb

@@ -9,22 +9,21 @@ module DexieCable
       # DexieCable channel.
       #
       #   class Message < ApplicationRecord
-      #     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
+      #     streams_via UserChannel, to: :sender
+      #     streams_via UserChannel, to: "global_feed"
+      #     streams_via UserChannel, to: -> { conversation.users }
+      #     streams_via PublicChannel
       #   end
       #
-      # @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 via     [Class] A DexieCable channel class, passed as the
+      #                  first positional argument. Each recipient is
+      #                  mapped through +via[to]+ to produce scoped
+      #                  channels.
       # @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 recipient or collection of
-      #                  recipients.
+      #                  recipients. Defaults to the record itself.
       # @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.
@@ -36,7 +35,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 streams_to_dexie(via:, to: nil, table: nil, only: nil, with: nil, **options)
+      def streams_via(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
@@ -48,7 +47,7 @@ module DexieCable
           before_destroy :dexie_sync_before_destroy
 
           after_commit on: :destroy, **conditions do
-            Array(resolve_channel(via, to)).each do |channel|
+            resolve_channels(via, to).each do |channel|
               next unless channel
               channel.table(resolve_table(table)).delete(dexie_destroy_id)
             end
@@ -57,19 +56,19 @@ module DexieCable
 
         if events.include?(:create)
           after_commit on: :create, **conditions do
-            Array(resolve_channel(via, to)).each do |channel|
+            resolve_channels(via, to).each do |channel|
               next unless channel
-              channel.table(resolve_table(table)).add(serialize_record(serializer))
+              channel.table(resolve_table(table)).add(resolve(serializer))
             end
           end
         end
 
         if events.include?(:update)
           after_commit on: :update, **conditions do
-            Array(resolve_channel(via, to)).each do |channel|
+            resolve_channels(via, to).each do |channel|
               next unless channel
 
-              changes = serialize_record(serializer).slice(*saved_changes.keys)
+              changes = resolve(serializer).slice(*saved_changes.keys)
               channel.table(resolve_table(table)).update(id, changes)
             end
           end
@@ -79,20 +78,16 @@ module DexieCable
 
     private
 
-    def resolve_channel(via, to = nil)
-      if to
-        recipients = resolve_recipient(to)
-        Array(recipients).map { |r| via[r] }
-      else
-        via
-      end
+    def resolve_channels(via, to = nil)
+      recipients = to ? resolve(to) : self
+      Array(recipients).map { |r| via[r] }
     end
 
-    def resolve_recipient(to)
-      case to
-      when Proc   then instance_exec(&to)
-      when Symbol then send(to)
-      else to
+    def resolve(val)
+      case val
+      when Proc   then instance_exec(&val)
+      when Symbol then send(val)
+      else val
       end
     end
 
@@ -104,14 +99,6 @@ 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/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: dexiecable
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 1.0.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 (streams_to_dexie) for automatic change
+  in real time. Includes an ActiveRecord macro (streams_via) for automatic change
   syncing.
 email:
 - stefan@buhrmi.de