cable_ready 5.0.0.pre8 → 5.0.0.pre9

data/Gemfile.lock

@@ -2,7 +2,12 @@ PATH
   remote: .
   specs:
     cable_ready (5.0.0.pre8)
-      rails (>= 5.2)
+      actioncable (>= 5.2)
+      actionpack (>= 5.2)
+      actionview (>= 5.2)
+      activerecord (>= 5.2)
+      activesupport (>= 5.2)
+      railties (>= 5.2)
       thread-local (>= 1.1.0)
 
 GEM
@@ -67,70 +72,17 @@ GEM
       minitest (>= 5.1)
       tzinfo (~> 2.0)
       zeitwerk (~> 2.3)
-    addressable (2.8.0)
-      public_suffix (>= 2.0.2, < 5.0)
     ast (2.4.2)
-    async (1.30.1)
-      console (~> 1.10)
-      nio4r (~> 2.3)
-      timers (~> 4.1)
-    async-http (0.56.5)
-      async (>= 1.25)
-      async-io (>= 1.28)
-      async-pool (>= 0.2)
-      protocol-http (~> 0.22.0)
-      protocol-http1 (~> 0.14.0)
-      protocol-http2 (~> 0.14.0)
-    async-http-faraday (0.11.0)
-      async-http (~> 0.42)
-      faraday
-    async-io (1.32.2)
-      async
-    async-pool (0.3.9)
-      async (>= 1.25)
     builder (3.2.4)
     coderay (1.1.3)
     concurrent-ruby (1.1.9)
-    console (1.13.1)
-      fiber-local
     crass (1.0.6)
     erubi (1.10.0)
-    faraday (1.8.0)
-      faraday-em_http (~> 1.0)
-      faraday-em_synchrony (~> 1.0)
-      faraday-excon (~> 1.1)
-      faraday-httpclient (~> 1.0.1)
-      faraday-net_http (~> 1.0)
-      faraday-net_http_persistent (~> 1.1)
-      faraday-patron (~> 1.0)
-      faraday-rack (~> 1.0)
-      multipart-post (>= 1.2, < 3)
-      ruby2_keywords (>= 0.0.4)
-    faraday-em_http (1.0.0)
-    faraday-em_synchrony (1.0.0)
-    faraday-excon (1.1.0)
-    faraday-http-cache (2.2.0)
-      faraday (>= 0.8)
-    faraday-httpclient (1.0.1)
-    faraday-net_http (1.0.1)
-    faraday-net_http_persistent (1.2.0)
-    faraday-patron (1.0.0)
-    faraday-rack (1.0.0)
-    fiber-local (1.0.0)
-    github_changelog_generator (1.16.4)
-      activesupport
-      async (>= 1.25.0)
-      async-http-faraday
-      faraday-http-cache
-      multi_json
-      octokit (~> 4.6)
-      rainbow (>= 2.2.1)
-      rake (>= 10.0)
-    globalid (0.5.2)
+    globalid (1.0.0)
       activesupport (>= 5.0)
     i18n (1.8.11)
       concurrent-ruby (~> 1.0)
-    loofah (2.12.0)
+    loofah (2.13.0)
       crass (~> 1.0.2)
       nokogiri (>= 1.5.9)
     magic_frozen_string_literal (1.2.0)
@@ -141,30 +93,19 @@ GEM
     mini_mime (1.1.2)
     minitest (5.14.4)
     mocha (1.13.0)
-    multi_json (1.15.0)
-    multipart-post (2.1.1)
     nio4r (2.5.8)
-    nokogiri (1.12.5-x86_64-linux)
+    nokogiri (1.13.3-x86_64-darwin)
+      racc (~> 1.4)
+    nokogiri (1.13.3-x86_64-linux)
       racc (~> 1.4)
-    octokit (4.21.0)
-      faraday (>= 0.9)
-      sawyer (~> 0.8.0, >= 0.5.3)
     parallel (1.21.0)
     parser (3.0.2.0)
       ast (~> 2.4.1)
-    protocol-hpack (1.4.2)
-    protocol-http (0.22.5)
-    protocol-http1 (0.14.2)
-      protocol-http (~> 0.22)
-    protocol-http2 (0.14.2)
-      protocol-hpack (~> 1.4)
-      protocol-http (~> 0.18)
     pry (0.14.1)
       coderay (~> 1.1)
       method_source (~> 1.0)
     pry-nav (1.0.0)
       pry (>= 0.9.10, < 0.15)
-    public_suffix (4.0.6)
     racc (1.6.0)
     rack (2.2.3)
     rack-test (1.1.0)
@@ -214,14 +155,10 @@ GEM
       rubocop (>= 1.7.0, < 2.0)
       rubocop-ast (>= 0.4.0)
     ruby-progressbar (1.11.0)
-    ruby2_keywords (0.0.5)
-    sawyer (0.8.2)
-      addressable (>= 2.3.5)
-      faraday (> 0.8, < 2.0)
     sprockets (4.0.2)
       concurrent-ruby (~> 1.0)
       rack (> 1, < 3)
-    sprockets-rails (3.4.0)
+    sprockets-rails (3.4.2)
       actionpack (>= 5.2)
       activesupport (>= 5.2)
       sprockets (>= 3.0.0)
@@ -233,7 +170,6 @@ GEM
       standard
     thor (1.1.0)
     thread-local (1.1.0)
-    timers (4.3.3)
     tzinfo (2.0.4)
       concurrent-ruby (~> 1.0)
     unicode-display_width (2.1.0)
@@ -243,18 +179,20 @@ GEM
     zeitwerk (2.5.1)
 
 PLATFORMS
+  x86_64-darwin-18
+  x86_64-darwin-19
   x86_64-linux
 
 DEPENDENCIES
   cable_ready!
-  github_changelog_generator
   magic_frozen_string_literal
   mocha
   pry
   pry-nav
+  rails (>= 5.2)
   rake
   sqlite3
   standardrb
 
 BUNDLED WITH
-   2.2.27
+   2.2.33

data/IMPLEMENTATION.md

@@ -0,0 +1,93 @@
+# CableReady Language Implementation Project
+
+We believe that CableReady can become the universal standard tool for developers to dynamically control client browsers from the server. While the project has roots in the Ruby on Rails community, the JS client is unopinionated about how the simple JSON structure that it consumes was created.
+
+We would like to announce support for Python, Go, C#, Java, PHP and NodeJS server libraries in early 2022. While there's a broad set of features a server library could implement, there's a baseline that we'd like to make sure all implementations can offer.
+
+## Background
+
+CableReady was started in 2017 by Nate Hopkins. It predates LiveView and the HTML-on-the-wire trend by 18 months. It sees roughly 15,000 downloads per week and offers 36 different [operations](https://cableready.stimulusreflex.com/v/v5/reference/operations).
+
+CableReady is currently a client-side JS module and a server-side Ruby module.
+
+## Key concepts
+
+- available everywhere
+- multiple operations per payload
+- schemaless
+- simple JSON wire format
+- method chaining
+- transport agnostic
+- extensible via custom operations
+
+### Available everywhere
+
+Rails developers can access a `cable_ready` singleton from just about anywhere in their application, and we believe it's a big part of the secret sauce. While every language and framework has their own idioms, we encourage implementors to remove barriers and make it easy to call CableReady anywhere it could be useful.
+
+https://cableready.stimulusreflex.com/v/v5/cableready-everywhere
+
+### Operations and their options
+
+Operations are the basic atomic unit of activity in CableReady. Each operation typically has a very specific focus and often mimics the DOM JS spec for the activity in question. Operations have options passed to them which specify their exact behavior.
+
+Multiple operations can be prepared together. They will be executed in the order that they were created. Different operation types can be mixed together in one payload.
+
+The Ruby implementation offers two interfaces; the (original) primary mechanism delivers the operations to a WebSocket channel in what we refer to as a "broadcast". The other - known as "cable car" - returns a JSON string that can be sent, persisted or displayed for any purpose.
+
+### Schemaless
+
+CableReady operations each have their own mandatory and optional options, along with options that are provided to every operation by the library. However, arbitrary additional options can be passed to an operation and they will be passed to the client. This makes it easy for CableReady to form the basis of much larger projects, such as StimulusReflex.
+
+### JSON wire format
+
+As of v5.0, the CableReady JSON wire format is an array of objects, where each object represents one operation. It's intentionally very simple.
+
+```json
+[{\"message\":\"Hello!\",\"operation\":\"consoleLog\"}]
+```
+
+Each operation has **camelCased** key/value pairs that convey options. Every operation must have an `operation` value, or the client will raise an exception.
+
+### Method chaining
+
+Developer experience is a high priority. We take pride in the readability and expressiveness offered by our server API. The basic pseudocode structure we provide looks like:
+
+```rb
+cable_ready[:foo].operation(options).broadcast
+```
+
+In other words, the first method `cable_ready` starts a method chain by returning `self`, and then each operation is a method that also returns the chain started by the initial method. In this way, you can chain together as many operations as you like. Finally, we have a `broadcast` method which takes the current chain and broadcasts it via WebSockets to the `:foo` channel.
+
+We also have our "cable car" interface which emits JSON when `to_json` is called. This makes it perfect for responding to Ajax fetch requests:
+
+```rb
+cable_car.operation(options).to_json
+```
+
+The `cable_car` might be assembled in steps, perhaps via a control loop:
+
+```rb
+inspiration = cable_car.console_log(message: "Hello there!").dispatch_event(name: "fred", detail: {inspiring: true})
+3.times do |i|
+  inspiration.console_log(message: "Still here: #{i}")
+end
+inspiration.to_json
+```
+
+The main expectation that should hold between languages is that you will start the chain with a command, add one or many operation methods, and then execute the chain.
+
+### Transport agnostic
+
+CableReady started its life as a WebSocket library, but the neutral JSON format has potential far beyond just WebSocket usage. We now frequently return CableReady JSON payloads via Ajax as well. There's nothing stopping you from embedding payloads into a DOM element attribute, for example.
+
+We believe that a minimally viable CableReady server library must be able to produce compatible JSON. There's no hard requirement that it interface with WebSockets, although we do find this to be a major sweet spot and will do our best to provide support.
+
+### Custom operations
+
+While CableReady ships with an impressive number of operations out of the box, users should be able to add their own operations. Admittedly, the method used to dynamically create all of the methods for each operation is the [most sophisticated](https://github.com/stimulusreflex/cable_ready/blob/master/lib/cable_ready/operation_builder.rb) one in our framework, but again, we're here to help.
+
+https://cableready.stimulusreflex.com/v/v5/customization#custom-operations
+
+# Get involved!
+
+We have a wonderful community with over 1600 folks on our Discord server, helping people get started. Come join https://discord.gg/stimulus-reflex and drop by the #cable_ready channel with any questions.

data/README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://gitcdn.link/repo/stimulusreflex/cable_ready/master/assets/cable-ready-logo-with-copy.svg" width="360" />
+  <img src="https://raw.githubusercontent.com/stimulusreflex/cable_ready/master/assets/cable-ready-logo-with-copy.svg" width="360" />
   <h1 align="center">Welcome to CableReady 👋</h1>
   <p align="center">
     <a href="https://rubygems.org/gems/cable_ready">
@@ -60,12 +60,41 @@ to learn more about ActionCable before proceeding.
 
 ## 🚀 Install
 
+### Rubygem
+
 ```sh
-bundle add cable_ready && yarn add cable_ready
+bundle add cable_ready
 ```
 
-Checkout the [documentation](https://cableready.stimulusreflex.com) to continue!
+### JavaScript
+
+There are a few ways to install the CableReady JavaScript client, depending on your application setup.
+
+#### ESBuild / Webpacker
+
+```sh
+yarn add cable_ready
+```
+
+#### Import maps:
+
+```ruby
+# config/importmap.rb
 
+# ...
+
+pin 'cable_ready', to: 'cable_ready.min.js', preload: true
+```
+
+#### Rails Asset pipeline (Sprockets):
+
+```html+erb
+<!-- app/views/layouts/application.html.erb -->
+
+<%= javascript_include_tag "cable_ready.umd.min.js", "data-turbo-track": "reload" %>
+```
+
+Checkout the [documentation](https://cableready.stimulusreflex.com) to continue!
 
 ## 🙏 Contributing
 
@@ -84,13 +113,13 @@ Please run `./bin/standardize` prior submitting pull requests.
 
 1. Make sure that you run `yarn` and `bundle` to pick up the latest.
 1. Bump version number at `lib/cable_ready/version.rb`. Pre-release versions use `.preN`
-1. Run `rake build`
+1. Run `rake build` and `yarn build`
 1. Commit and push changes to github
 1. Run `rake release`
 1. Run `yarn publish --no-git-tag-version`
 1. Yarn will prompt you for the new version. Pre-release versions use `-preN`
-1. Run `GITHUB_CHANGELOG_GENERATOR_TOKEN=SECRET rake changelog`
-1. Commit and push changes to github
+1. Commit and push changes to GitHub
+1. Create a new release on GitHub ([here](https://github.com/stimulusreflex/stimulus_reflex/releases)) and generate the changelog for the stable release for it
 
 ## 📝 License
 

data/Rakefile

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
 
 require "bundler/gem_tasks"
-require "github_changelog_generator/task"
 require "rake/testtask"
 require "pry"
 
@@ -14,10 +13,3 @@ Rake::TestTask.new(:test) do |t|
   t.verbose = true
   t.warning = false
 end
-
-GitHubChangelogGenerator::RakeTask.new :changelog do |config|
-  config.user = "stimulusreflex"
-  config.project = "cable_ready"
-  config.exclude_labels = %w[duplicate question invalid wontfix nodoc]
-  config.token = ENV["GITHUB_CHANGELOG_GENERATOR_TOKEN"]
-end