live_record 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a996d306c6802ca85328ab7bfc6d2c3e10e2d1de
-  data.tar.gz: af1c2f69850844c08823ac0039973408bad1f38f
+  metadata.gz: 68e46da08f168efb9e1ebfb51f075548aaaa42cd
+  data.tar.gz: fbb81c2b262d59fa5b05e7a8b1a84bb20962538f
 SHA512:
-  metadata.gz: d8feaa50d1fd4f9a4c549a1d30f817e8e75ed95ba9cf2fc9eeb1d8353c4706eb6ee3b831db54799d2da2acbd6a75709b640fa3b7f348580c988667b972323e40
-  data.tar.gz: 131c98a95177c115e223d58bcd609dc2621515f445593b9ec41d07e279c80aaffe5efd3521517aabcf8deb71a8ed83a2a53b0b9bc4439f8568fbbed5ee187251
+  metadata.gz: 2c3a0ffcac47a14e301671222403391380ece8577cf2a62ec1477b604155a31fb660b5fcc2e3106ebf2e94245c77e38b32aaf83d7c5e0d24ca1617fdd19370e3
+  data.tar.gz: 95949617075641208bbf35ace36222c43f4d11bb415110ea1da45ef05281191b28dc80e4136dadf9ff71f6f4f4836ae14b102403ae2e53973e49fbdae5992338

data/.gitignore

@@ -1,8 +1,8 @@
 /.bundle
 *.sqlite
 *.sqlite-journal
-/lib/live_record/spec/internal/log/*
-/lib/live_record/spec/internal/tmp/*
+/spec/internal/log/*
+/spec/internal/tmp/*
 .byebug_history
 *.gem
 Gemfile.lock

data/.travis.yml

@@ -9,4 +9,3 @@ rvm:
   - 2.4.1
 before_install:
   - google-chrome-stable --headless --disable-gpu --remote-debugging-port=9222 http://localhost &
-script: cd lib/live_record && bundle exec rspec

data/Gemfile

@@ -5,5 +5,7 @@ gemspec
 group :development, :test do
   # issues with Combustion + FactoryGirl factory loading: https://github.com/pat/combustion/issues/33
   # therefore, this gem should not be part of .gemspec but instead is specified here in the Gemfile
-  gem 'factory_girl_rails', require: false
+  gem 'factory_girl_rails', '~> 4.8', require: false
+  # do not require to prevent Capybara deprecation warning on rspec run
+  gem 'capybara', '~> 2.15', require: false
 end

data/README.md

@@ -2,12 +2,16 @@
 
 ## 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 LiveDOM Plugin)**
-* Automatically resyncs after client-side reconnection.
+* Auto-syncs records in client-side JS (through a Model DSL) from changes (updates/destroy) in the backend Rails server through ActionCable.
+* Also supports streaming newly created records to client-side JS
+* Supports lost connection restreaming for both new records (create), and record-changes (updates/destroy).
+* Auto-updates DOM elements mapped to a record attribute, from changes (updates/destroy). **(Optional LiveDOM Plugin)**
 
 > `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.
 
+*New Version 0.2!*
+*See [Changelog below](#changelog)*
+
 ## Requirements
 
 * **>= Ruby 2.2.2**
@@ -19,18 +23,38 @@
 
 ## Usage Example
 
-* on the client-side:
+* say we have a `Book` model which has the following attributes:
+  * `title:string`
+  * `author:text`
+  * `is_enabled:boolean`
+* on the JS client-side:
 
+### Subscribing to Record Creation
   ```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
+  // subscribe, and auto-receive newly created Book records from the Rails server
+  LiveRecord.Model.all.Book.subscribe()
+
+  // ...or only those which are enabled
+  // LiveRecord.Model.all.Book.subscribe({where: {is_enabled_eq: true}})
+
+  // now, we can just simply add a "create" callback, to apply our own logic whenever a new Book record is streamed from the backend
+  LiveRecord.Model.all.Book.addCallback('after:create', function() {
+    // let's say you have a code here that adds this new Book on the page 
+    // `this` refers to the Book record that has been created
+    console.log(this);
+  })
+  ```
+
+### Subscribing to Record Updates/Destroy
+
+  ```js
+  // instantiate a Book object (only requirement is you pass the ID so it can be referenced when updates/destroy happen)
+  var book = new LiveRecord.Model.all.Book({id: 1})
+
+  // ...or you can also initialise with other attributes 
+  // var book = new LiveRecord.Model.all.Book({id: 1, title: 'Harry Potter', created_at: '2017-08-02T12:39:49.238Z'})
+  
+  // then store this Book object into the JS store
   book.create();
 
   // the store is accessible through
@@ -38,7 +62,15 @@
 
   // 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 (see all supported callbacks further below)
+  // because the `book` above is already created in the store, you'll notice that it should automatically sync itself including all other possible whitelisted attributes
+  console.log(book.attributes);
+  // at this point then, console.log above will show the following on your browser console:
+  // {id: 1, title: 'Harry Potter', author: 'J.K. Rowling', is_enabled: true, created_at: '2017-08-02T12:39:49.238Z', updated_at: '2017-08-02T12:39:49.238Z'}
+
+  // All attributes automatically updates itself so you'll be sure that the following line (for example) is always up-to-date
+  console.log(book.updated_at())
+
+  // you can also add a callback that will be invoked whenever the Book object has been updated (see all supported callbacks further below)
   book.addCallback('after:update', function() {
     // let's say you update the DOM elements here when the attributes have changed
     // `this` refers to the Book record that has been updated
@@ -74,224 +106,305 @@
   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
+* whenever a Book (or any other Model record that you specified) has been created / updated / destroyed, there exists an `after_create_commit`, `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`:
+1. Add the following to your `Gemfile`:
 
-  ```ruby
-  gem 'live_record', '~> 0.1.2'
-  ```
+    ```ruby
+    gem 'live_record', '~> 0.2.0'
+    ```
 
-* Run:
+2. Run:
 
-  ```bash
-  bundle install
-  ```
+    ```bash
+    bundle install
+    ```
 
-* Install by running:
+3. Install by running:
 
-  ```bash
-  rails generate live_record:install
-  ```
+    ```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
+    > `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:
+4. 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:
+5. 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
+    ```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])
+        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
-  end
-  ```
+    ```
 
-* Update your **model** files (only those you would want to be synced), and insert the following public method:
+6. 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
+    > automatically updated if you use Rails scaffold or model generator
 
-  ### Example 1 - Simple Usage
+    ### 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
+      include LiveRecord::Model::Callbacks
 
-  ```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?
+      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]
-      else
-        []
       end
     end
-  end
-  ```
+    ```
+
+    ### Example 2 - Advanced Usage
+
+    ```ruby
+    # app/models/book.rb (example 1)
+    class Book < ApplicationRecord
+      include LiveRecord::Model::Callbacks
+      
+      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.
+7. For each Model you want to sync, insert the following in your Javascript files.
 
-  > automatically updated if you use Rails scaffold or controller generator
+    > automatically updated if you use Rails scaffold or controller generator
 
-  ### Example 1 - Model
+    ### 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`
+    ```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
-          }
-        ]
+    )
+    ```
+
+    ### 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:
-              }
-            ]
+    )
+    ```
+
+      #### 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'})`
+
+8. 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/books/index.html.erb -->
+    <script>
+      // `loadRecords` you may also specify a URL to loadRecords (`url` defaults to `window.location.href` which is the current page) 
+      LiveRecord.helpers.loadRecords({modelName: 'Book', url: '/some/url/that/returns_books_as_a_json'})
+    </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>
+    ```
 
-      #### 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'})`
+    ### Example 2 - Using Custom Loader
 
-* Load the records into the JS Model-store through JSON REST (i.e.):
+    ```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' }
 
-  ### Example 1 - Using Default Loader (Requires JQuery)
+    // 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();
 
-  > Your controller must also support responding with JSON in addition to HTML. If you used scaffold or controller generator, this should already work immediately.
+    var book2 = new LiveRecord.Model.all.Book(book2Attributes);
+    book2.create();
 
-  ```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>
-  ```
+    // 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
+    })
+    ```
 
-  ```html
-  <!-- app/views/books/index.html.erb -->
-  <script>
-    // `loadRecords` you may also specify a URL to loadRecords (`url` defaults to `window.location.href` which is the current page) 
-    LiveRecord.helpers.loadRecords({modelName: 'Book', url: '/some/url/that/returns_books_as_a_json'})
-  </script>
-  ```
+9. To automatically receive new Book records, you may subscribe:
 
-  ```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) {
-        // ...
-      }
+    ```js
+    // subscribe
+    subscription = LiveRecord.Model.all.Book.subscribe();
+
+    // ...or subscribe only to certain conditions (i.e. when `is_enabled` attribute value is `true`)
+    // For the list of supported operators (like `..._eq`), see JS API `MODEL.subscribe(CONFIG)` below
+    // subscription = LiveRecord.Model.all.Book.subscribe({where: {is_enabled_eq: true}});
+
+    // now, we can just simply add a "create" callback, to apply our own logic whenever a new Book record is streamed from the backend
+    LiveRecord.Model.all.Book.addCallback('after:create', function() {
+      // let's say you have a code here that adds this new Book on the page 
+      // `this` refers to the Book record that has been created
+      console.log(this);
     })
-  </script>
-  ```
 
-  ### Example 2 - Using Custom Loader
+    // you may also add callbacks specific to this `subscription`, as you may want to have multiple subscriptions. Then, see JS API `MODEL.subscribe(CONFIG)` below for information
 
-  ```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
-  })
-  ```
+    // then unsubscribe, as you wish
+    LiveRecord.Model.all.Book.unsubscribe(subscription);
+    ```
 
+    ### Ransack Search Queries (Optional)
+  
+      * If you need more complex queries to pass into the `.subscribe(where: { ... })` above, [ransack](https://github.com/activerecord-hackery/ransack) gem is supported.
+      * For example you can then do:
+        ```js
+        // querying upon the `belongs_to :user`
+        subscription = LiveRecord.Model.all.Book.subscribe({where: {user_is_admin_eq: true, is_enabled: true}});
+
+        // or querying "OR" conditions
+        subscription = LiveRecord.Model.all.Book.subscribe({where: {title_eq: 'I am Batman', content_eq: 'I am Batman', m: 'or'}});
+        ```
+
+      #### Model File (w/ Ransack) Example
+
+      ```ruby
+      # app/models/book.rb
+      class Book < ApplicationRecord
+        include LiveRecord::Model::Callbacks
+        has_many :live_record_updates, as: :recordable
+
+        def self.live_record_whitelisted_attributes(book, current_user)
+          [:title, :is_enabled]
+        end
+
+        private
+
+        # see ransack gem for more details: https://github.com/activerecord-hackery/ransack#authorization-whitelistingblacklisting
+        # you can write your own columns here, but you may just simply allow ALL COLUMNS to be searchable, because the `live_record_whitelisted_attributes` method above will be also called anyway, and therefore just simply handle whitelisting there.
+        # therefore you can actually remove the whole `self.ransackable_attributes` method below
+
+        ## LiveRecord passes the `current_user` into `auth_object`, so you can access `current_user` inside below
+        # def self.ransackable_attributes(auth_object = nil)
+        #   column_names + _ransackers.keys
+        # end
+      end
+      ```
+
+    ### Reconnection Streaming (when client got disconnected)
+
+    * Only requirement is that you should have a `created_at` attribute on your Models, which by default should already be there. However, to speed up queries, I highly suggest to add index on `created_at` with the following
+
+    ```bash
+    # this will create a file under db/migrate folder, then edit that file (see the ruby code below)
+    rails generate migration add_created_at_index_to_MODELNAME
+    ```
+
+    ```ruby
+    # db/migrate/2017**********_add_created_at_index_to_MODELNAME.rb
+    class AddCreatedAtIndexToMODELNAME < ActiveRecord::Migration[5.0] # or 5.1, etc
+      def change
+        add_index :TABLENAME, :created_at
+      end
+    end
+    ```
 
 ## Plugins
 
@@ -325,7 +438,7 @@
 
 ## JS API
 
-`LiveRecord.Model.create(CONFIG)`
+### `LiveRecord.Model.create(CONFIG)`
   * `CONFIG` (Object)
     * `modelName`: (String, Required)
     * `callbacks`: (Object)
@@ -340,54 +453,97 @@
       * `after:destroy`: (Array of functions)
     * `plugins`: (Object)
       * `LiveDOM`: (Boolean)
-  * returns the newly create `MODEL`
+  * creates a `MODEL` and stores it into `LiveRecord.Model.all` array
+  * returns the newly created `MODEL`
 
-`new LiveRecord.Model.all.MODELNAME(ATTRIBUTES)`
+### `MODEL`.subscribe(CONFIG)
+  * `CONFIG` (Object, Optional)
+    * `where`: (Object)
+      * `ATTRIBUTENAME_OPERATOR`: (Any Type)
+    * `callbacks`: (Object)
+      * `on:connect`: (function Object)
+      * `on:disconnect`: (function Object)
+      * `before:create`: (function Object)
+      * `after:create`: (function Object)
+  * subscribes to the `PublicationsChannel`, which then automatically receives new records from the backend.
+  * you can also pass in `callbacks` (see above). These callbacks is only applicable to this subscription, and is independent of the Model and Instance callbacks.
+  * `ATTRIBUTENAME_OPERATOR` means something like (for example): `is_enabled_eq`, where `is_enabled` is the `ATTRIBUTENAME` and `eq` is the `OPERATOR`.
+    * you can have as many `ATTRIBUTENAME_OPERATOR` as you like, but keep in mind that the logic applied to them is "AND", and not "OR". For "OR" conditions, use `ransack`
+
+    #### List of Default Supported Query Operators
+
+    > the following list only applies if you are NOT using the `ransack` gem. If you need more complex queries, `ransack` is supported and so see Setup's step 9 above
+
+    * `eq` equals; i.e. `is_enabled_eq: true`
+    * `not_eq` not equals; i.e. `title_not_eq: 'Harry Potter'`
+    * `lt` less than; i.e. `created_at_lt: '2017-12-291T13:47:59.238Z'`
+    * `lteq` less than or equal to; i.e. `created_at_lteq: '2017-12-291T13:47:59.238Z'`
+    * `gt` greater than; i.e. `created_at_gt: '2017-12-291T13:47:59.238Z'`
+    * `gteq` greater than or equal to; i.e. `created_at_gteq: '2017-12-291T13:47:59.238Z'`
+    * `in` in Array; i.e. `id_in: [2, 56, 19, 68]`
+    * `not_in` in Array; i.e. `id_not_in: [2, 56, 19, 68]`
+
+### `MODEL`.unsubscribe(SUBSCRIPTION)
+  * unsubscribes to the `PublicationsChannel`, thereby will not be receiving new records anymore.
+
+### `new LiveRecord.Model.all.MODELNAME(ATTRIBUTES)`
   * `ATTRIBUTES` (Object)
   * returns a `MODELINSTANCE` of the the Model having `ATTRIBUTES` attributes
 
-`MODELINSTANCE.modelName()`
+### `MODELINSTANCE.modelName()`
   * returns the model name (i.e. 'Book')
 
-`MODELINSTANCE.attributes`
+### `MODELINSTANCE.attributes`
   * the attributes object
 
-`MODELINSTANCE.ATTRIBUTENAME()`
+### `MODELINSTANCE.ATTRIBUTENAME()`
   * returns the attribute value of corresponding to `ATTRIBUTENAME`. (i.e. `bookInstance.id()`, `bookInstance.created_at()`)
 
-`MODELINSTANCE.subscribe()`
+### `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()`
+### `MODELINSTANCE.unsubscribe()`
+  * unsubscribes to the `LiveRecordChannel`, thereby will not be receiving changes (updates/destroy) anymore.
+
+### `MODELINSTANCE.isSubscribed()`
   * returns `true` or `false` accordingly if the instance is subscribed
 
-`MODELINSTANCE.subscription`
+### `MODELINSTANCE.subscription`
   * the `subscription` object (the ActionCable subscription object itself)
 
-`MODELINSTANCE.create()`
+### `MODELINSTANCE.create()`
   * stores the instance to the store, and then `subscribe()` to the `LiveRecordChannel` for syncing
   * returns the instance
 
-`MODELINSTANCE.update(ATTRIBUTES)`
+### `MODELINSTANCE.update(ATTRIBUTES)`
   * `ATTRIBUTES` (Object)
   * updates the attributes of the instance
   * returns the instance
 
-`MODELINSTANCE.destroy()`
+### `MODELINSTANCE.destroy()`
   * removes the instance from the store, and then `unsubscribe()`
   * returns the instance
 
-`MODELINSTANCE.addCallback(CALLBACKKEY, CALLBACKFUNCTION)`
+### `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)`
+### `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
 
+## FAQ
+* How to remove the view templates being overriden by LiveRecord when generating a controller or scaffold?
+  * amongst other things, `rails generate live_record:install` will override the default scaffold view templates: **show.html.erb** and **index.html.erb**; to revert back, just simply delete the following files (though you'll need to manually update or regenerate the view files that were already generated prior to deleting to the following files):
+    * **lib/templates/erb/scaffold/index.html.erb**
+    * **lib/templates/erb/scaffold/show.html.erb**
+
+* How to support more complex queries / "where" conditions when subscribing to new records creation?
+  * Please refer to [JS API's MODEL.subscribe(CONFIG) above ](#modelsubscribeconfig)
+
 ## TODOs
 * Change `feature` specs into `system` specs after [this rspec-rails pull request](https://github.com/rspec/rspec-rails/pull/1813) gets merged.
 
@@ -395,4 +551,9 @@
 * pull requests and forks are very much welcomed! :) Let me know if you find any bug! Thanks
 
 ## License
-* MIT
+* MIT
+
+## Changelog
+* 0.2
+  * Ability to subscribe to new records (supports lost connection auto-restreaming)
+    * See [9th step of Setup above](#setup)