dexiecable 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 86f0f439d4d0a6320b38ce77c0e188fdd590b592107c8a6c4b41f6d63d72c900
+  data.tar.gz: da0d7f54b972206adf4e07bbcec2660a597f4ac89c28865fc2a8974bc21ac38f
+SHA512:
+  metadata.gz: 22d044c313789238aaa192415a96d8795111078727745ed9ed1b26ce28d14016be02415ef9903eebcfc75fa6d1a4b0856c8eb4cebbdd7693c3b67984ba6a6dd1
+  data.tar.gz: 7fc66fe6550e35e92fc426ae01131bda13b9a83394c763d24b3c19a7a84670c974843ee47385b9c0298cdfa0e3e8c5507115d4565370fdcbc3eb589632898143

data/README.md

@@ -0,0 +1,203 @@
+# DexieCable
+
+Run Dexie.js IndexedDB operations from your Rails ActionCable channels.
+
+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.
+
+You can run any Dexie table update directly inside a channel:
+
+```ruby
+class UserChannel < ApplicationCable::Channel
+  include DexieCable
+
+  def subscribed
+    stream_for current_user
+    recent_notifications = current_user.notifications.last(10)
+    table("notifications").bulkAdd(recent_notifications)
+  end
+end
+```
+
+Or from inside a controller:
+
+```ruby
+class NotificationsController < ApplicationController
+  def create
+    notification = current_user.notifications.create!(notification_params)
+    UserChannel[current_user].table("notifications").add(notification)
+  end
+end
+```
+
+An even more convenient way is to use the `syncs_to_dexie` macro:
+
+```ruby
+class Notification < ApplicationRecord
+  syncs_to_dexie via: -> { UserChannel[user] }
+end
+```
+
+## Installation
+
+### Ruby gem
+
+Add to your `Gemfile`:
+
+```ruby
+gem "dexiecable"
+```
+
+Then `bundle install`. The Railtie automatically extends `ActiveRecord::Base` with `syncs_to_dexie`.
+
+### npm package
+
+```bash
+npm install dexiecable
+# or
+yarn add dexiecable
+```
+
+Configure it with your Dexie database and ActionCable consumer before subscribing:
+
+```js
+import { configure, subscribe } from "dexiecable";
+import { db } from "./db";
+import { createConsumer } from "@rails/actioncable";
+
+configure({ db, consumer: createConsumer() });
+
+const sub = subscribe("UserChannel", { last_update: Date.now() });
+```
+
+If you omit `consumer`, one is created for you automatically.
+
+## Usage
+
+### `include DexieCable` in a channel
+
+```ruby
+class UserChannel < ApplicationCable::Channel
+  include DexieCable
+
+  def subscribed
+    stream_for current_user
+  end
+end
+```
+
+This gives you:
+
+| Method | Description |
+|---|---|
+| `self.[](subject)` | Returns a `ScopedChannel` bound to a subject. `UserChannel[current_user]` |
+| `table(name)` | Starts a query chain. `table("messages")` |
+
+### Chaining Dexie operations
+
+Any Dexie.js write operation triggers an immediate broadcast:
+
+```ruby
+# Single insert
+UserChannel[current_user].table("messages").add(id: 1, text: "hello")
+
+# Filtered bulk insert
+UserChannel[current_user]
+  .table("messages")
+  .where(:room_id).equals(room.id)
+  .bulkAdd(messages)
+
+# Update
+UserChannel[current_user]
+  .table("messages")
+  .where(:id).equals(msg.id)
+  .modify(read: true)
+
+# Delete
+UserChannel[current_user]
+  .table("messages")
+  .where(:room_id).equals(room.id)
+  .delete()
+```
+
+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
+
+Add to any ActiveRecord model:
+
+```ruby
+class Message < ApplicationRecord
+  syncs_to_dexie via: -> { UserChannel[sender] }
+  syncs_to_dexie via: -> { UserChannel[receiver] }
+  syncs_to_dexie via: PublicChannel  # broadcast to all connected clients
+end
+```
+
+| 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)` |
+
+#### Options
+
+| Option | Default | Description |
+|---|---|---|
+| `via:` | *(required)* | Proc (evaluated in record context), channel class, or channel instance |
+| `table:` | model's `table_name` | Override the Dexie table name |
+| `only:` | `[:create, :update, :destroy]` | Limit which events trigger a sync |
+
+#### Customizing the synced payload
+
+Override `as_json_for_dexie` in your model:
+
+```ruby
+class Message < ApplicationRecord
+  syncs_to_dexie via: -> { UserChannel[sender] }
+
+  def as_json_for_dexie
+    super.merge(room_name: room.name)
+  end
+end
+```
+
+## How it works
+
+```mermaid
+sequenceDiagram
+    participant Model as ActiveRecord Model
+    participant Channel as DexieCable Channel
+    participant WS as ActionCable WebSocket
+    participant JS as dexiecable.js
+    participant DB as Dexie.js (IndexedDB)
+
+    Model->>Channel: after_commit
+    Channel->>Channel: build Query DSL
+    Channel->>WS: broadcast JSON { table, ops }
+    WS->>JS: received(data)
+    JS->>DB: replay ops chain
+    DB-->>JS: result
+```
+
+The Ruby side builds a JSON payload like:
+
+```json
+{
+  "table": "messages",
+  "ops": [
+    { "method": "where", "params": ["room_id"] },
+    { "method": "equals", "params": [5] },
+    { "method": "add", "params": [{ "id": 1, "text": "hello" }] }
+  ]
+}
+```
+
+The JS side replays it as:
+
+```js
+dexie.messages.where("room_id").equals(5).add({ id: 1, text: "hello" })
+```
+
+## License
+
+MIT

data/lib/dexiecable/active_record_ext.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module DexieCable
+  module ActiveRecordExt
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # Declares that this model syncs changes to Dexie (IndexedDB) via a
+      # DexieCable channel.
+      #
+      #   class Message < ApplicationRecord
+      #     syncs_to_dexie via: -> { UserChannel[sender] }
+      #     syncs_to_dexie via: -> { UserChannel[receiver] }
+      #     syncs_to_dexie via: PublicChannel
+      #   end
+      #
+      # @param via    [Proc, DexieCable] Proc evaluated in record context,
+      #                 must return a channel (responds to +table+). A channel
+      #                 class/instance can also be passed directly. Skipped if nil.
+      # @param table  [String, Symbol] Override the Dexie table name
+      #                (defaults to the model's table_name).
+      # @param only   [Array<Symbol>] Limit which lifecycle events sync.
+      #                Default: [:create, :update, :destroy].
+      def syncs_to_dexie(via:, table: nil, only: nil)
+        table_name = (table || self.table_name).to_s
+        events     = Array(only || %i[create update destroy])
+
+        @dexie_sync_configs ||= []
+        @dexie_sync_configs << { via: via, table: table_name, only: events }
+
+        if events.include?(:destroy)
+          before_destroy :dexie_sync_before_destroy
+
+          after_commit on: :destroy do
+            channel = resolve_channel(via)
+            next unless channel
+            channel.table(table_name).delete(dexie_destroy_id)
+          end
+        end
+
+        if events.include?(:create)
+          after_commit on: :create do
+            channel = resolve_channel(via)
+            next unless channel
+            channel.table(table_name).add(as_json_for_dexie)
+          end
+        end
+
+        if events.include?(:update)
+          after_commit on: :update do
+            channel = resolve_channel(via)
+            next unless channel
+
+            changes = as_json_for_dexie.slice(*saved_changes.keys)
+            channel.table(table_name).update(id, changes)
+          end
+        end
+      end
+    end
+
+    private
+
+    def resolve_channel(via)
+      case via
+      when Proc then instance_exec(&via)
+      else via
+      end
+    end
+
+    # Override in your model to customise the payload synced to Dexie.
+    def as_json_for_dexie
+      as_json
+    end
+
+    def dexie_sync_before_destroy
+      @dexie_destroy_id = id
+    end
+
+    def dexie_destroy_id
+      @dexie_destroy_id
+    end
+  end
+end

data/lib/dexiecable/concern.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module DexieCable
+  extend ActiveSupport::Concern
+
+  included do
+    public :transmit
+
+    # Open a scoped channel for broadcasting to a specific subject.
+    #
+    #   UserChannel[current_user].table("notifications").add(notification)
+    #
+    def self.[](subject)
+      ScopedChannel.new(self, subject)
+    end
+
+    # Build a query against a Dexie table, transmitted to all subscribers
+    # of this channel.
+    #
+    #   table("messages").where(:room_id).equals(room.id).add(message)
+    #
+    def table(name)
+      Query.new(self, name)
+    end
+  end
+end

data/lib/dexiecable/query.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module DexieCable
+  # Builds a chain of Dexie.js operations and transmits them as a single
+  # payload once a write operation is reached.
+  #
+  #   DexieCable::Query.new(channel, "messages")
+  #     .where(:room_id).equals(5)
+  #     .add(text: "hello")
+  #
+  class Query
+    WRITE_OPS = %i[
+      add bulkAdd put bulkPut bulkDelete
+      upsert update delete modify clear
+    ].freeze
+
+    attr_accessor :query
+
+    def initialize(transmitter, name)
+      @transmitter = transmitter
+      @query = { table: name, ops: [] }
+    end
+
+    def method_missing(method, *params)
+      @query[:ops] << { method: method, params: params }
+      if WRITE_OPS.include?(method)
+        @transmitter.transmit(query)
+      else
+        self
+      end
+    end
+
+    def respond_to_missing?(method, *)
+      true
+    end
+  end
+end

data/lib/dexiecable/railtie.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module DexieCable
+  class Railtie < Rails::Railtie
+    initializer "dexiecable.active_record" do
+      ActiveSupport.on_load(:active_record) do
+        include DexieCable::ActiveRecordExt
+      end
+    end
+  end
+end

data/lib/dexiecable/scoped_channel.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module DexieCable
+  class ScopedChannel
+    def initialize(klass, subject)
+      @klass   = klass
+      @subject = subject
+    end
+
+    def table(name)
+      Query.new(self, name)
+    end
+
+    def transmit(data)
+      @klass.broadcast_to @subject, data
+    end
+  end
+end

data/lib/dexiecable/version.rb

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

data/lib/dexiecable.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "dexiecable/version"
+require_relative "dexiecable/concern"
+require_relative "dexiecable/scoped_channel"
+require_relative "dexiecable/query"
+require_relative "dexiecable/active_record_ext"
+require_relative "dexiecable/railtie" if defined?(Rails::Railtie)
+
+module DexieCable
+  class Error < StandardError; end
+end

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification
+name: dexiecable
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Stefan Buhrmester
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: actioncable
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        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
+  syncing.
+email:
+- stefan@buhrmi.de
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/dexiecable.rb
+- lib/dexiecable/active_record_ext.rb
+- lib/dexiecable/concern.rb
+- lib/dexiecable/query.rb
+- lib/dexiecable/railtie.rb
+- lib/dexiecable/scoped_channel.rb
+- lib/dexiecable/version.rb
+homepage: https://github.com/buhrmi/dexiecable
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/buhrmi/dexiecable
+  source_code_uri: https://github.com/buhrmi/dexiecable
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.1'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.8
+specification_version: 4
+summary: Run Dexie.js IndexedDB operations from your Rails ActionCable channels.
+test_files: []