live_record 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: '00451863c5ada349c3b74b4c4ad8fd6332e748fe'
+  data.tar.gz: ed18de46bdb44a11f5d54fa7ff76af65202381d9
+SHA512:
+  metadata.gz: 064c14f91640de8fb7ef723fc147c7ee475d4c2223469b1eb4fa0c2c0131e95a9b2df308f195f688bd833bdf7dd110807f15d7cceb71a6a355d87da53edf6d72
+  data.tar.gz: 0a4f1d3fc4312cd88757c2f4dbb434944bd7cc52d2f665d0a8a5e3d4bf58296030cae6fe6334ca31daf1005cc3e0f43dae64b1eac92f924638ecbcc4829d5bd7

data/.gitignore

@@ -0,0 +1,7 @@
+/.bundle
+/db/*.sqlite3
+/db/*.sqlite3-journal
+/log/*
+/tmp/*
+.byebug_history
+*.gem

data/Gemfile

@@ -0,0 +1,5 @@
+source 'https://rubygems.org'
+
+gemspec
+
+gem 'rails', '~> 5.0', '< 5.2'

data/Gemfile.lock

@@ -0,0 +1,11 @@
+GEM
+  remote: https://rubygems.org/
+  specs:
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+
+BUNDLED WITH
+   1.12.5

data/README.md

@@ -0,0 +1,369 @@
+*WIP! (TODO: Tests)*
+
+## About
+
+* Auto-syncs records in client-side JS (through a Model DSL) from changes in the backend Rails server through ActionCable
+* Auto-updates DOM elements mapped to a record attribute, from changes. **(Optional Plugin)**
+* Automatically resyncs after client-side reconnection.
+
+> `live_record` is intentionally designed for read-only one-way syncing from the backend server, and does not support pushing changes to the Rails server from the client-side JS. Updates from client-side then is intended to use the normal HTTP REST requests.
+
+## Requirements
+
+* **>= Rails 5.0**
+
+## Demo
+
+* https://obscure-refuge-63797.herokuapp.com/
+
+## Usage Example
+
+* on the client-side:
+
+  ```js
+  // instantiate a Book object
+  var book = new LiveRecord.Model.all.Book({
+    id: 1,
+    title: 'Harry Potter',
+    author: 'J. K. Rowling',
+    created_at: '2017-08-02T12:39:49.238Z',
+    updated_at: '2017-08-02T12:39:49.238Z'
+  });
+  // store this Book object into the JS store
+  book.create();
+
+  // the store is accessible through
+  LiveRecord.Model.all.Book.all;
+
+  // all records in the JS store are automatically subscribed to the backend LiveRecordChannel, which meant syncing (update / destroy) changes from the backend
+
+  // you can add a callback that will be invoked whenever the Book object has been updated
+  book.addCallback('after:update', function() {
+    // let's say you update the DOM elements here when the attributes have changed
+  });
+  ```
+
+* on the backend-side, you can handle attributes authorisation:
+
+  ```ruby
+  # app/models/book.rb
+  class Book < ApplicationRecord
+    def self.live_record_whitelisted_attributes(book, current_user)
+      # Add attributes to this array that you would like `current_user` to have access to when syncing this particular `book`
+      # empty array means not-authorised
+      if book.user == current_user
+        [:title, :author, :created_at, :updated_at, :reference_id, :origin_address]
+      elsif current_user.present?
+        [:title, :author, :created_at, :updated_at]
+      else
+        []
+      end
+    end
+  end
+  ```
+
+* whenever a Book (or any other Model record that you specified) has been updated / destroyed, there exists an `after_update_commit` and an `after_destroy_commit` ActiveRecord callback that will broadcast changes to all subscribed JS clients
+
+## Setup
+* Add the following to your `Gemfile`:
+
+  ```ruby
+  gem 'live_record', '~> 0.0.1'
+  ```
+
+* Run:
+
+  ```bash
+  bundle install
+  ```
+
+* Install by running:
+
+  ```bash
+  rails generate live_record:install
+  ```
+
+  > `rails generate live_record:install --live_dom=false` if you do not need the `LiveDom` plugin; `--live_dom=true` by default
+
+* Run migration to create the `live_record_updates` table, which is going to be used for client reconnection resyncing:
+
+  ```bash
+  rake db:migrate
+  ```
+
+* Update your **app/channels/application_cable/connection.rb**, and add `current_user` method, unless you already have it:
+
+  ```ruby
+  module ApplicationCable
+    class Connection < ActionCable::Connection::Base
+      identified_by :current_user
+
+      def current_user
+        # write something here if you have a current_user, or you may just leave this blank. Example below when using `devise` gem:
+        # User.find_by(id: cookies.signed[:user_id])
+      end
+    end
+  end
+  ```
+
+* Update your **model** files (only those you would want to be synced), and insert the following public method:
+
+  > automatically updated if you use Rails scaffold or model generator
+
+  ### Example 1 - Simple Usage
+
+  ```ruby
+  # app/models/book.rb (example 1)
+  class Book < ApplicationRecord
+    def self.live_record_whitelisted_attributes(book, current_user)
+      # Add attributes to this array that you would like current_user to have access to when syncing.
+      # Defaults to empty array, thereby blocking everything by default, only unless explicitly stated here so.
+      [:title, :author, :created_at, :updated_at]
+    end
+  end
+  ```
+
+  ### Example 2 - Advanced Usage
+
+  ```ruby
+  # app/models/book.rb (example 1)
+  class Book < ApplicationRecord
+    def self.live_record_whitelisted_attributes(book, current_user)
+      # Notice that from above, you also have access to `book` (the record currently requested by the client to be synced),
+      # and the `current_user`, the current user who is trying to sync the `book` record.
+      if book.user == current_user
+        [:title, :author, :created_at, :updated_at, :reference_id, :origin_address]
+      elsif current_user.present?
+        [:title, :author, :created_at, :updated_at]
+      else
+        []
+      end
+    end
+  end
+  ```
+
+* For each Model you want to sync, insert the following in your Javascript files.
+
+  > automatically updated if you use Rails scaffold or controller generator
+
+  ### Example 1 - Model
+
+  ```js
+  // app/assets/javascripts/books.js
+  LiveRecord.Model.create(
+    {
+      modelName: 'Book' // should match the Rails model name
+      plugins: {
+        LiveDOM: true // remove this if you do not need `LiveDom`
+      }
+    }
+  )
+  ```
+
+  ### Example 2 - Model + Callbacks
+
+  ```js
+  // app/assets/javascripts/books.js
+  LiveRecord.Model.create(
+    {
+      modelName: 'Book',
+      callbacks: {
+        'on:connect': [
+          function() {
+            console.log(this); // `this` refers to the current `Book` record that has just connected for syncing
+          }
+        ],
+        'after:update': [
+          function() {
+            console.log(this); // `this` refers to the current `Book` record that has just been updated with changes synced from the backend
+          }
+        ]
+      }
+    }
+  )
+  ```
+
+    #### Model Callbacks supported:
+    * `on:connect`
+    * `on:disconnect`
+    * `on:response_error`
+    * `before:create`
+    * `after:create`
+    * `before:update`
+    * `after:update`
+    * `before:destroy`
+    * `after:destroy`
+
+    > Each callback should map to an array of functions
+
+    * `on:response_error` supports a function argument: The "Error Code". i.e.
+
+      ### Example 3 - Handling Response Error
+
+      ```js
+      LiveRecord.Model.create(
+        {
+          modelName: 'Book',
+          callbacks: {
+            'on:response_error': [
+              function(errorCode) {
+                console.log(errorCode); // errorCode is a string, representing the type of error. See Response Error Codes below:
+              }
+            ]
+          }
+        }
+      )
+      ```
+
+      #### Response Error Codes:
+      * `"forbidden"` - Current User is not authorized to sync record changes. Happens when Model's `live_record_whitelisted_attributes` method returns empty array.
+      * `"bad_request"` - Happens when `LiveRecord.Model.create({modelName: 'INCORRECTMODELNAME'})`
+
+* Load the records into the JS Model-store through JSON REST (i.e.):
+
+  ### Example 1 - Using Default Loader (Requires JQuery)
+
+  > Your controller must also support responding with JSON in addition to HTML. If you used scaffold or controller generator, this should already work immediately.
+
+  ```html
+  <!-- app/views/books/index.html.erb -->
+  <script>
+    // `loadRecords` asynchronously loads all records (using the current URL) to the store, through a JSON AJAX request.
+    // in this example, `loadRecords` will load JSON from the current URL which is /books
+    LiveRecord.helpers.loadRecords({modelName: 'Book'})
+  </script>
+  ```
+
+  ```html
+  <!-- app/views/posts/index.html.erb -->
+  <script>
+    // You may also pass in a callback for synchronous logic
+    LiveRecord.helpers.loadRecords({
+      modelName: 'Book',
+      onLoad: function(records) {
+        // ...
+      },
+      onError: function(jqxhr, textStatus, error) {
+        // ...
+      }
+    })
+  </script>
+  ```
+
+  ### Example 2 - Using Custom Loader
+
+  ```js
+  // do something here that will fetch Book record attributes...
+  // as an example, say you already have the following attributes:
+  var book1Attributes = { id: 1, title: 'Noli Me Tangere', author: 'José Rizal' }
+  var book2Attributes = { id: 2, title: 'ABNKKBSNPLAko?!', author: 'Bob Ong' }
+
+  // then we instantiate a Book object
+  var book1 = new LiveRecord.Model.all.Book(book1Attributes);
+  // then we push this Book object to the Book store, which then automatically subscribes them to changes in the backend
+  book1.create();
+
+  var book2 = new LiveRecord.Model.all.Book(book2Attributes);
+  book2.create();
+
+  // you can also add Instance callbacks specific only to this Object (supported callbacks are the same as the Model callbacks)
+  book2.addCallback('after:update', function() {
+    // do something when book2 has been updated after syncing
+  })
+  ```
+
+
+## Plugins
+
+### LiveDom (Requires JQuery)
+
+* enabled by default, unless explicitly removed.
+* `LiveDom` allows DOM elements' text content to be automatically updated, whenever the mapped record-attribute has been updated.
+
+> text content is safely escaped using JQuery's `.text()` function
+
+#### Example 1 (Mapping to a Record-Attribute: `after:update`)
+```html
+<span data-live-record-update-from='Book-24-title'>Harry Potter</span>
+```
+
+* `data-live-record-update-from` format should be `MODELNAME-RECORDID-RECORDATTRIBUTE`
+* whenever `LiveRecord.all.Book.all[24]` has been updated/synced from backend, "Harry Potter" text above changes accordingly.
+* this does not apply to only `<span>` elements. You can use whatever elements you like.
+
+#### Example 2 (Mapping to a Record: `after:destroy`)
+
+```html
+<section data-live-record-destroy-from='Book-31'>This example element is a container for the Book-31 record which can also contain children elements</section>
+```
+
+* `data-live-record-destroy-from` format should be `MODELNAME-RECORDID`
+* whenever `LiveRecord.all.Book.all[31]` has been destroyed/synced from backend, the `<section>` element above is removed, and thus all of its children elements.
+* this does not apply to only `<section>` elements. You can use whatever elements you like.
+
+* You may combine `data-live-record-destroy-from` and `data-live-record-update-from` within the same element.
+
+## JS API
+
+`LiveRecord.Model.create(CONFIG)`
+  * `CONFIG` (Object)
+    * `modelName`: (String, Required)
+    * `callbacks`: (Object)
+      * `on:connect`: (Array of functions)
+      * `on:disconnect`: (Array of functions)
+      * `on:response_error`: (Array of functions; function argument = ERROR_CODE (String))
+      * `before:create`: (Array of functions)
+      * `after:create`: (Array of functions)
+      * `before:update`: (Array of functions)
+      * `after:update`: (Array of functions)
+      * `before:destroy`: (Array of functions)
+      * `after:destroy`: (Array of functions)
+    * `plugins`: (Object)
+      * `LiveDom`: (Boolean)
+  * returns the newly create `MODEL`
+
+`new LiveRecord.Model.all.MODELNAME(ATTRIBUTES)`
+  * `ATTRIBUTES` (Object)
+  * returns a `MODELINSTANCE` of the the Model having `ATTRIBUTES` attributes
+
+`MODELINSTANCE.modelName()`
+  * returns the model name (i.e. 'Book')
+
+`MODELINSTANCE.attributes`
+  * the attributes object
+
+`MODELINSTANCE.ATTRIBUTENAME()`
+  * returns the attribute value of corresponding to `ATTRIBUTENAME`. (i.e. `bookInstance.id()`, `bookInstance.created_at()`)
+
+`MODELINSTANCE.subscribe()`
+  * subscribes to the `LiveRecordChannel`. This instance should already be subscribed by default after being stored, unless there is a `on:response_error` or manually `unsubscribed()` which then you should manually call this `subscribe()` function after correctly handling the response error, or whenever desired.
+  * returns the `subscription` object (the ActionCable subscription object itself)
+
+`MODELINSTANCE.isSubscribed()`
+  * returns `true` or `false` accordingly if the instance is subscribed
+
+`MODELINSTANCE.subscription`
+  * the `subscription` object (the ActionCable subscription object itself)
+
+`MODELINSTANCE.create()`
+  * stores the instance to the store, and then `subscribe()` to the `LiveRecordChannel` for syncing
+  * returns the instance
+
+`MODELINSTANCE.update(ATTRIBUTES)`
+  * `ATTRIBUTES` (Object)
+  * updates the attributes of the instance
+  * returns the instance
+
+`MODELINSTANCE.destroy()`
+  * removes the instance from the store, and then `unsubscribe()`
+  * returns the instance
+
+`MODELINSTANCE.addCallback(CALLBACKKEY, CALLBACKFUNCTION)`
+  * `CALLBACKKEY` (String) see supported callbacks above
+  * `CALLBACKFUNCTION` (function Object)
+  * returns the function Object if successfuly added, else returns `false` if callback already added
+
+`MODELINSTANCE.removeCallback(CALLBACKKEY, CALLBACKFUNCTION)`
+  * `CALLBACKKEY` (String) see supported callbacks above
+  * `CALLBACKFUNCTION` (function Object) the function callback that will be removed
+  * returns the function Object if successfully removed, else returns `false` if callback is already removed

data/app/assets/javascripts/live_record.js

@@ -0,0 +1,8 @@
+//= require_self
+//= require_directory ./live_record/
+
+this.LiveRecord || (this.LiveRecord = {});
+
+if (window.jQuery === undefined) {
+	 throw new Error('jQuery is not loaded yet, and is a dependency of LiveRecord')
+}

data/app/assets/javascripts/live_record/helpers.js

@@ -0,0 +1,4 @@
+//= require_self
+//= require_directory ./helpers/
+
+this.LiveRecord.helpers || (this.LiveRecord.helpers = {});

data/app/assets/javascripts/live_record/helpers/load_records.coffee

@@ -0,0 +1,31 @@
+LiveRecord.helpers.loadRecords = (args) ->
+  args['modelName'] || throw new Error(':modelName argument required')
+  throw new Error(':modelName is not defined in LiveRecord.Model.all') if LiveRecord.Model.all[args['modelName']] == undefined
+
+  args['url'] ||= window.location.href
+
+  $.getJSON(
+    args['url']
+  ).done(
+    (data) -> 
+      # Array JSON
+      if $.isArray(data)
+        records_attributes = data;
+        records = []
+
+        for record_attributes in records_attributes
+          record = new LiveRecord.Model.all[args['modelName']](record_attributes);
+          record.create();
+          records << record
+
+      # Single-Record JSON
+      else
+        record_attributes = data
+        record = new LiveRecord.Model.all[args['modelName']](record_attributes);
+        record.create();
+
+      args['onLoad'].call(this, records) if args['onLoad']
+  ).fail(
+    (jqxhr, textStatus, error) ->
+      args['onError'].call(this, jqxhr, textStatus, error) if args['onError']
+  )

data/app/assets/javascripts/live_record/model.js

@@ -0,0 +1,4 @@
+//= require_self
+//= require_directory ./model/
+
+this.LiveRecord.Model || (this.LiveRecord.Model = {});

data/app/assets/javascripts/live_record/model/all.coffee

@@ -0,0 +1 @@
+LiveRecord.Model.all = {}

data/app/assets/javascripts/live_record/model/create.coffee

@@ -0,0 +1,192 @@
+LiveRecord.Model.create = (config) ->
+  config.modelName != undefined || throw new Error('missing :modelName argument')
+  config.callbacks != undefined || config.callbacks = {}
+  config.plugins != undefined || config.callbacks = {}
+
+  # NEW
+  Model = (attributes) ->
+    this.attributes = attributes
+    # instance callbacks
+    this._callbacks = {
+      'on:connect': [],
+      'on:disconnect': [],
+      'on:response_error': [],
+      'before:create': [],
+      'after:create': [],
+      'before:update': [],
+      'after:update': [],
+      'before:destroy': [],
+      'after:destroy': []
+    }
+
+    Object.keys(this.attributes).forEach (attribute_key) ->
+      if Model.prototype[attribute_key] == undefined
+        Model.prototype[attribute_key] = ->
+          this.attributes[attribute_key]
+    this
+
+  Model.modelName = config.modelName
+
+  Model.prototype.modelName = ->
+    Model.modelName
+
+  Model.prototype.subscribe = ->
+    return this.subscription if this.subscription != undefined
+
+    # listen for record changes (update / destroy)
+    subscription = App['live_record_' + this.modelName() + '_' + this.id()] = App.cable.subscriptions.create({
+      channel: 'LiveRecordChannel'
+      model_name: this.modelName()
+      record_id: this.id()
+    },
+      record: ->
+        return @_record if @_record
+        identifier = JSON.parse(this.identifier)
+        @_record = Model.all[identifier.record_id]
+
+      # on: connect
+      connected: ->
+        if @record()._staleSince != undefined
+          @syncRecord(@record())
+
+        @record()._callCallbacks('on:connect', undefined)
+
+      # on: disconnect
+      disconnected: ->
+        @record()._staleSince = (new Date()).toISOString() unless @record()._staleSince
+        @record()._callCallbacks('on:disconnect', undefined)
+
+      # on: receive
+      received: (data) ->
+        if data.error
+          @record()._staleSince = (new Date()).toISOString() unless @record()._staleSince
+          @onError[data.error.code].call(this, data)
+          @record()._callCallbacks('on:response_error', [data.error.code])
+          delete @record()['subscription']
+        else
+          @onAction[data.action].call(this, data)
+
+      # handler for received() callback above
+      onAction:
+        update: (data) ->
+          @record().update(data.attributes)
+
+        destroy: (data) ->
+          @record().destroy()
+
+      # handler for received() callback above
+      onError:
+        forbidden: (data) ->
+          console.error('[LiveRecord Response Error]', data.error.code, ':', data.error.message, 'for', @record())
+        bad_request: (data) ->
+          console.error('[LiveRecord Response Error]', data.error.code, ':', data.error.message, 'for', @record())
+
+      # syncs local record from remote record
+      syncRecord: ->
+        @perform(
+          'sync_record',
+          model_name: @record().modelName(),
+          record_id: @record().id(),
+          stale_since: @record()._staleSince
+        )
+        @record()._staleSince = undefined
+    )
+
+    this.subscription = subscription
+
+  Model.prototype.unsubscribe = ->
+    return if this.subscription == undefined
+    App.cable.subscriptions.remove(this.subscription)
+    delete this['subscription']
+
+  Model.prototype.isSubscribed = ->
+    this.subscription != undefined
+
+  # ALL
+  Model.all = {}
+
+  # CREATE
+  Model.prototype.create = () ->
+    this._callCallbacks('before:create', undefined)
+
+    Model.all[this.attributes.id] = this
+    this.subscribe()
+
+    this._callCallbacks('after:create', undefined)
+    this
+
+  # UPDATE
+  Model.prototype.update = (attributes) ->
+    this._callCallbacks('before:update', undefined)
+
+    self = this
+    Object.keys(attributes).forEach (attribute_key) ->
+      self.attributes[attribute_key] = attributes[attribute_key]
+
+    this._callCallbacks('after:update', undefined)
+    true
+
+  # DESTROY
+  Model.prototype.destroy = ->
+    this._callCallbacks('before:destroy', undefined)
+
+    this.unsubscribe()
+    delete Model.all[this.attributes.id]
+
+    this._callCallbacks('after:destroy', undefined)
+    this
+
+  # CALLBACKS
+
+  ## class callbacks
+  Model._callbacks = {
+    'on:connect': [],
+    'on:disconnect': [],
+    'on:response_error': [],
+    'before:create': [],
+    'after:create': [],
+    'before:update': [],
+    'after:update': [],
+    'before:destroy': [],
+    'after:destroy': []
+  }
+
+  Model.addCallback = Model.prototype.addCallback = (callbackKey, callbackFunction) ->
+    index = this._callbacks[callbackKey].indexOf(callbackFunction)
+    if index == -1
+      this._callbacks[callbackKey].push(callbackFunction)
+      return callbackFunction
+
+  Model.removeCallback = Model.prototype.removeCallback = (callbackKey, callbackFunction) ->
+    index = this._callbacks[callbackKey].indexOf(callbackFunction)
+    if index != -1
+      this._callbacks[callbackKey].splice(index, 1)
+      return callbackFunction
+
+  Model.prototype._callCallbacks = (callbackKey, args) ->
+    # call class callbacks
+    for callback in Model._callbacks[callbackKey]
+      callback.apply(this, args)
+
+    # call instance callbacks
+    for callback in this._callbacks[callbackKey]
+      callback.apply(this, args)
+
+  # AFTER MODEL INITIALISATION
+
+  # add callbacks from arguments
+  for callbackKey, callbackFunctions of config.callbacks
+    for callbackFunction in callbackFunctions
+      Model.addCallback(callbackKey, callbackFunction)
+
+
+  # enable plugins from arguments
+  for pluginKey, pluginValue of config.plugins
+    if LiveRecord.plugins
+      index =  Object.keys(LiveRecord.plugins).indexOf(pluginKey)
+      LiveRecord.plugins[pluginKey].applyToModel(Model, pluginValue) if index != -1
+
+  # add new Model to collection
+  LiveRecord.Model.all[config.modelName] = Model
+
+  Model

data/app/assets/javascripts/live_record/plugins.js

@@ -0,0 +1,3 @@
+//= require_self
+
+this.LiveRecord.plugins || (this.LiveRecord.plugins = {});

data/app/assets/javascripts/live_record/plugins/live_dom.coffee

@@ -0,0 +1,18 @@
+this.LiveRecord.plugins.LiveDOM || (this.LiveRecord.plugins.LiveDOM = {});
+
+LiveRecord.plugins.LiveDOM.applyToModel = (Model, pluginValue) ->
+  return if pluginValue != true
+
+  # DOM callbacks
+
+  Model._updateDomCallback = ->
+    $updateableElements = $('[data-live-record-update-from]')
+
+    for key, value of this.attributes
+      $updateableElements.filter('[data-live-record-update-from="' + Model.modelName + '-' + this.id() + '-' + key + '"]').text(this[key]())
+
+  Model._destroyDomCallback = ->
+    $('[data-live-record-destroy-from="' + Model.modelName + '-' + this.id() + '"]').remove()
+
+  Model.addCallback('after:update', Model._updateDomCallback)
+  Model.addCallback('after:destroy', Model._destroyDomCallback)

data/lib/live_record.rb

@@ -0,0 +1,8 @@
+require 'rails'
+require 'active_support/concern'
+
+Dir[__dir__ + '/live_record/*.rb'].each {|file| require file }
+Dir[__dir__ + '/live_record/generators/*.rb'].each {|file| require file }
+
+module LiveRecord
+end

data/lib/live_record/channel.rb

@@ -0,0 +1,99 @@
+module LiveRecord
+  module Channel
+    extend ActiveSupport::Concern
+
+    included do
+      def subscribed
+        find_record_from_params(params) do |record|
+          authorised_attributes = authorised_attributes(record, current_user)
+
+          if authorised_attributes.present?
+            stream_for record, coder: ActiveSupport::JSON do |message|
+              record.reload
+              authorised_attributes = authorised_attributes(record, current_user)
+
+              if authorised_attributes.present?
+                response = filtered_message(message, authorised_attributes)
+                transmit response if response.present?
+              else
+                respond_with_error(:forbidden)
+                reject_subscription
+              end
+            end
+          else
+            respond_with_error(:forbidden)
+            reject
+          end
+        end
+      end
+
+      def sync_record(data)
+        find_record_from_params(data.symbolize_keys) do |record|
+          authorised_attributes = authorised_attributes(record, current_user)
+
+          if authorised_attributes.present?
+            live_record_update = LiveRecordUpdate.where(
+              recordable_type: record.class.name,
+              recordable_id: record.id
+            ).where(
+              'created_at >= ?', DateTime.parse(data['stale_since']) - 1.minute
+            ).order(id: :asc)
+
+            if live_record_update.exists?
+              message = { 'action' => 'update', 'attributes' => record.attributes }
+              response = filtered_message(message, authorised_attributes)
+              transmit response if response.present?
+            end
+          else
+            respond_with_error(:forbidden)
+            reject_subscription
+          end
+        end
+      end
+
+      def unsubscribed
+        # Any cleanup needed when channel is unsubscribed
+      end
+
+      private
+
+      def authorised_attributes(record, current_user)
+        return record.class.live_record_whitelisted_attributes(record, current_user).map(&:to_s)
+      end
+
+      def filtered_message(message, filters)
+        if message['attributes'].present?
+          message['attributes'].slice!(*filters)
+        end
+        message
+      end
+
+      def find_record_from_params(params)
+        model_class = params[:model_name].safe_constantize
+
+        if model_class && model_class < ApplicationRecord
+          record = model_class.find_by(id: params[:record_id])
+
+          if record.present?
+            yield record
+          else
+            transmit 'action' => 'destroy'
+          end
+        else
+          respond_with_error(:bad_request, 'Not a correct model name')
+          reject_subscription
+        end
+      end
+
+      def respond_with_error(type, message = nil)
+        case type
+        when :forbidden
+          transmit error: { 'code' => 'forbidden', 'message' => (message || 'You are not authorised') }
+        when :bad_request
+          transmit error: { 'code' => 'bad_request', 'message' => (message || 'Invalid request parameters') }
+        end
+      end
+
+    end
+  end
+end

data/lib/live_record/engine.rb

@@ -0,0 +1,4 @@
+module LiveRecord
+  class Engine < Rails::Engine
+  end
+end

data/lib/live_record/generators/install_generator.rb

@@ -0,0 +1,72 @@
+module LiveRecord
+  module Generators
+    class InstallGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      desc 'Copy LiveRecord Javascript template'
+      source_root File.expand_path('../templates', __FILE__)
+
+      class_option :live_dom, desc: 'Enables LiveDom plugin: [true, false]', default: 'true'
+      class_option :javascript_engine, desc: 'JS engine to be used: [js, coffee]'
+      class_option :template_engine, desc: 'Template engine to be used (if LiveDom plugin enabled): [erb, slim, haml]'
+
+      def copy_assets_javascript_template
+        copy_file "javascript.#{javascript_engine}.rb", "lib/templates/#{javascript_engine}/assets/javascript.#{javascript_engine}"
+      end
+
+      def copy_model_template
+        copy_file "model.rb.rb", "lib/templates/active_record/model/model.rb"
+      end
+
+      def copy_scaffold_index_template
+        copy_file "index.html.#{template_engine}", "lib/templates/#{template_engine}/scaffold/index.html.#{template_engine}" if live_dom
+      end
+
+      def copy_scaffold_show_template
+        copy_file "show.html.#{template_engine}", "lib/templates/#{template_engine}/scaffold/show.html.#{template_engine}" if live_dom
+      end
+
+      def copy_live_record_update_model_template
+        class_collisions 'LiveRecordUpdate'
+        template 'live_record_update.rb', File.join('app/models', 'live_record_update.rb')
+        migration_template 'create_live_record_updates.rb', 'db/migrate/create_live_record_updates.rb'
+      end
+
+      def copy_live_record_channel_template
+        class_collisions 'LiveRecordChannel'
+        template 'live_record_channel.rb', File.join('app/channels', 'live_record_channel.rb')
+      end
+
+      def update_application_record
+        in_root do
+          insert_into_file 'app/models/application_record.rb', "  include LiveRecord::Model\n", after: "self.abstract_class = true\n"
+        end
+      end
+
+      def update_application_javascript
+        in_root do
+          insert_into_file 'app/assets/javascripts/application.js', "//= require live_record\n", before: "//= require_tree ."
+          insert_into_file 'app/assets/javascripts/application.js', "//= require live_record/plugins/live_dom\n", before: "//= require_tree ." if live_dom
+        end
+      end
+
+      private
+
+      def self.next_migration_number(dir)
+        Time.now.utc.strftime("%Y%m%d%H%M%S")
+      end
+
+      def javascript_engine
+        Rails.application.config.generators.options[:rails][:javascript_engine] || options[:javascript_engine]
+      end
+
+      def template_engine
+        Rails.application.config.generators.options[:rails][:template_engine] || options[:template_engine]
+      end
+
+      def live_dom
+        options[:live_dom] == 'true' ? true : options[:live_dom] == 'false' ? false : raise(ArgumentError, 'invalid value for --live_dom. Can only be `true` or `false`')
+      end
+    end
+  end
+end

data/lib/live_record/generators/templates/create_live_record_updates.rb

@@ -0,0 +1,8 @@
+class CreateLiveRecordUpdates < ActiveRecord::Migration[5.0]
+	def change
+    create_table :live_record_updates do |t|
+      t.references :recordable, polymorphic: true
+      t.datetime :created_at, null: false, index: true
+    end
+  end
+end

data/lib/live_record/generators/templates/index.html.erb

@@ -0,0 +1,34 @@
+<script>
+  LiveRecord.helpers.loadRecords({modelName: '<%= singular_table_name.camelcase %>'})
+</script>
+<p id="notice"><%%= notice %></p>
+
+<h1><%= plural_table_name.titleize %></h1>
+
+<table>
+  <thead>
+    <tr>
+<% attributes.reject(&:password_digest?).each do |attribute| -%>
+      <th><%= attribute.human_name %></th>
+<% end -%>
+      <th colspan="3"></th>
+    </tr>
+  </thead>
+
+  <tbody>
+    <%% @<%= plural_table_name %>.each do |<%= singular_table_name %>| %>
+      <tr data-live-record-destroy-from='<%= singular_table_name.camelcase %>-<%%= <%= singular_table_name %>.id %>'>
+<% attributes.reject(&:password_digest?).each do |attribute| -%>
+        <td data-live-record-update-from='<%= singular_table_name.camelcase %>-<%%= <%= singular_table_name %>.id %>-<%= attribute.name %>'><%%= <%= singular_table_name %>.<%= attribute.name %> %></td>
+<% end -%>
+        <td><%%= link_to 'Show', <%= singular_table_name %> %></td>
+        <td><%%= link_to 'Edit', edit_<%= singular_table_name %>_path(<%= singular_table_name %>) %></td>
+        <td><%%= link_to 'Destroy', <%= singular_table_name %>, method: :delete, data: { confirm: 'Are you sure?' } %></td>
+      </tr>
+    <%% end %>
+  </tbody>
+</table>
+
+<br>
+
+<%%= link_to 'New <%= singular_table_name.titleize %>', new_<%= singular_table_name %>_path %>

data/lib/live_record/generators/templates/javascript.coffee.rb

@@ -0,0 +1,16 @@
+<% module_namespacing do -%>
+LiveRecord.Model.create(
+  {
+    modelName: '<%= singular_table_name.camelcase %>',
+    plugins: {
+      LiveDOM: true
+    },
+    # See TODO: URL_TO_DOCUMENTATION for supported callbacks
+    # Add Callbacks (callback name => array of functions)
+    # callbacks: {
+    #   'on:disconnect': [],
+    #   'after:update': [],
+    # }
+  }
+)
+<% end -%>

data/lib/live_record/generators/templates/javascript.js.rb

@@ -0,0 +1,16 @@
+<% module_namespacing do -%>
+LiveRecord.Model.create(
+  {
+    modelName: '<%= file_name.singularize.camelcase %>',
+    plugins: {
+      LiveDOM: true
+    },
+    // See TODO: URL_TO_DOCUMENTATION for supported callbacks
+    // Add Callbacks (callback name => array of functions)
+    // callbacks: {
+    //   'on:disconnect': [],
+    //   'after:update': [],
+    // }
+  }
+)
+<% end -%>

data/lib/live_record/generators/templates/live_record_channel.rb

@@ -0,0 +1,4 @@
+class LiveRecordChannel < ApplicationCable::Channel
+  include ActiveSupport::Rescuable
+  include LiveRecord::Channel
+end

data/lib/live_record/generators/templates/live_record_update.rb

@@ -0,0 +1,3 @@
+class LiveRecordUpdate < ApplicationRecord
+  belongs_to :recordable, polymorphic: true
+end

data/lib/live_record/generators/templates/model.rb.rb

@@ -0,0 +1,19 @@
+<% module_namespacing do -%>
+class <%= class_name %> < <%= parent_class_name.classify %>
+<% attributes.select(&:reference?).each do |attribute| -%>
+  belongs_to :<%= attribute.name %><%= ', polymorphic: true' if attribute.polymorphic? %><%= ', required: true' if attribute.required? %>
+<% end -%>
+<% attributes.select(&:token?).each do |attribute| -%>
+  has_secure_token<% if attribute.name != "token" %> :<%= attribute.name %><% end %>
+<% end -%>
+<% if attributes.any?(&:password_digest?) -%>
+  has_secure_password
+<% end -%>
+
+  def self.live_record_whitelisted_attributes(<%= class_name.underscore %>, current_user)
+	  # Add attributes to this array that you would like current_user to have access to.
+	  # Defaults to empty array, thereby blocking everything by default, only unless explicitly stated here so.
+	  []
+  end
+end
+<% end -%>

data/lib/live_record/generators/templates/show.html.erb

@@ -0,0 +1,16 @@
+<script>
+  LiveRecord.helpers.loadRecords({modelName: '<%= singular_table_name.camelcase %>'})
+</script>
+<p id="notice"><%%= notice %></p>
+
+<% attributes.reject(&:password_digest?).each do |attribute| -%>
+<p>
+  <strong><%= attribute.human_name %>:</strong>
+  <span data-live-record-update-from='<%= singular_table_name.camelcase %>-<%%= @<%= singular_table_name %>.id %>-<%= attribute.name %>'>
+  	<%%= @<%= singular_table_name %>.<%= attribute.name %> %>
+  </span>
+</p>
+
+<% end -%>
+<%%= link_to 'Edit', edit_<%= singular_table_name %>_path(@<%= singular_table_name %>) %> |
+<%%= link_to 'Back', <%= index_helper %>_path %>

data/lib/live_record/model.rb

@@ -0,0 +1,36 @@
+module LiveRecord
+  module Model
+    extend ActiveSupport::Concern
+
+    included do
+      has_many :live_record_updates, as: :recordable
+      
+      after_update :__live_record_reference_changed_attributes__
+      after_update_commit :__live_record_broadcast_record_update__
+      after_destroy_commit :__live_record_broadcast_record_destroy__
+
+      def self.live_record_whitelisted_attributes(record, current_user)
+        []
+      end
+
+      private
+
+      def __live_record_reference_changed_attributes__
+        @_live_record_changed_attributes = changed
+      end
+
+      def __live_record_broadcast_record_update__
+        included_attributes = attributes.slice(*@_live_record_changed_attributes)
+        @_live_record_changed_attributes = nil
+        message_data = { 'action' => 'update', 'attributes' => included_attributes }
+        LiveRecordChannel.broadcast_to(self, message_data)
+        LiveRecordUpdate.create!(recordable: self)
+      end
+
+      def __live_record_broadcast_record_destroy__
+        message_data = { 'action' => 'destroy' }
+        LiveRecordChannel.broadcast_to(self, message_data)
+      end
+    end
+  end
+end

data/lib/live_record/version.rb

@@ -0,0 +1,3 @@
+module LiveRecord
+	VERSION = '0.0.1'.freeze
+end

data/live_record.gemspec

@@ -0,0 +1,20 @@
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'live_record/version'
+
+Gem::Specification.new do |s|
+  s.name        = 'live_record'
+  s.version     = LiveRecord::VERSION
+  s.date        = '2017-08-03'
+  s.summary     = 'Rails 5 ActionCable Live JS Objects and DOM Elements'
+  s.description = "Auto-syncs records in client-side JS (through a Model DSL) from changes in the backend Rails server through ActionCable.\nAuto-updates DOM elements mapped to a record attribute, from changes.\nAutomatically resyncs after client-side reconnection."
+  s.authors     = ['Jules Roman B. Polidario']
+  s.email       = 'jrpolidario@gmail.com'
+  s.files       = `git ls-files`.split("\n")
+  s.homepage    = 'https://github.com/jrpolidario/live_record'
+  s.license     = 'MIT'
+  s.required_ruby_version = '~> 2.0'
+
+  s.add_dependency 'rails', '~> 5.0', '< 5.2'
+  s.add_development_dependency 'byebug', '~> 9.0'
+end

metadata

@@ -0,0 +1,107 @@
+--- !ruby/object:Gem::Specification
+name: live_record
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Jules Roman B. Polidario
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2017-08-03 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.2'
+- !ruby/object:Gem::Dependency
+  name: byebug
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '9.0'
+description: |-
+  Auto-syncs records in client-side JS (through a Model DSL) from changes in the backend Rails server through ActionCable.
+  Auto-updates DOM elements mapped to a record attribute, from changes.
+  Automatically resyncs after client-side reconnection.
+email: jrpolidario@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- Gemfile.lock
+- README.md
+- app/assets/javascripts/live_record.js
+- app/assets/javascripts/live_record/helpers.js
+- app/assets/javascripts/live_record/helpers/load_records.coffee
+- app/assets/javascripts/live_record/model.js
+- app/assets/javascripts/live_record/model/all.coffee
+- app/assets/javascripts/live_record/model/create.coffee
+- app/assets/javascripts/live_record/plugins.js
+- app/assets/javascripts/live_record/plugins/live_dom.coffee
+- lib/live_record.rb
+- lib/live_record/channel.rb
+- lib/live_record/engine.rb
+- lib/live_record/generators/install_generator.rb
+- lib/live_record/generators/templates/create_live_record_updates.rb
+- lib/live_record/generators/templates/index.html.erb
+- lib/live_record/generators/templates/javascript.coffee.rb
+- lib/live_record/generators/templates/javascript.js.rb
+- lib/live_record/generators/templates/live_record_channel.rb
+- lib/live_record/generators/templates/live_record_update.rb
+- lib/live_record/generators/templates/model.rb.rb
+- lib/live_record/generators/templates/show.html.erb
+- lib/live_record/model.rb
+- lib/live_record/version.rb
+- live_record.gemspec
+homepage: https://github.com/jrpolidario/live_record
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - "~>"
+    - !ruby/object:Gem::Version
+      version: '2.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.6.11
+signing_key: 
+specification_version: 4
+summary: Rails 5 ActionCable Live JS Objects and DOM Elements
+test_files: []