railbus 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3a4d4f90743b019f021dce043615b79204496078835955c549aee7e31238aaad
+  data.tar.gz: d0d414564db34c8c3a12ee40a060333f208da3443754fba9af7c4943d3ce3843
+SHA512:
+  metadata.gz: ffaadfde8d0fc1367f75a6b4ddd49d6bf399269ccb6e92fde68d5b712fb21f3fc657a952e4129739ef40dabf34f471e03f0a0e69ce40d8596806d6b220c7bfc4
+  data.tar.gz: 2e6b62c58abfa3fe253d387eb3d4d863998784b1f11734e8fa133db09c5493b85705c02b4106bc4a022c17fbbae5d99ef7d2281a7cdc9323d93e78cb959db4c3

data/.editorconfig

@@ -0,0 +1,33 @@
+root = true
+
+[*.{rb,md,editorconfig,js,rake,erb}]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2
+max_line_length = 80
+trim_trailing_whitespace = true
+
+[{Gemfile*,Rakefile,.git*,.rspec}]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+indent_style = space
+indent_size = 2
+max_line_length = 80
+trim_trailing_whitespace = true
+
+[*.md]
+indent_size = unset
+max_line_length = unset
+trim_trailing_whitespace = false
+
+[{{.git,bin,tmp,vendor}/**,*.lock}]
+charset = unset
+end_of_line = unset
+insert_final_newline = unset
+indent_style = unset
+indent_size = unset
+max_line_length = unset
+trim_trailing_whitespace = unset

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.travis.yml

@@ -0,0 +1,6 @@
+---
+language: ruby
+cache: bundler
+rvm:
+  - 2.6.5
+before_install: gem install bundler -v 2.1.4

data/Gemfile

@@ -0,0 +1,4 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in railbus.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Evgeniy Nochevnov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,227 @@
+# Railbus
+
+Do you want to use autogenerated set of Rails application routes in your JavaScript files?
+
+Do you want to make requests to your routes from JS with human-readable names like `create_news`, `update_message`?
+
+Here comes Railbus to you.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'railbus'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install railbus
+
+To use it with Webpack, create `*.js.erb` file in `app/javascript`
+(e.g. `lib/routes.js.erb`):
+
+```erb
+/* rails-erb-loader-dependencies ../config/routes */
+<%= Railbus.generate %>
+```
+
+And the last step, require this file in your `.js` files where you want to use application routes.
+
+```js
+import Routes from 'lib/routes'
+```
+
+## Usage
+
+In short:
+
+1. See output of `rails routes`, it includes route names. You may use these names in JS as functions for XHR requests.
+2. Append `_path` to a route name to get its URL.
+
+Route names in JS depend on route names in Rails:
+
+Action name | HTTP method | Request function       | Path function
+------------|-------------|------------------------|----------------------------
+index       | GET         | {plural_name}          | {plural_name}_path
+show        | GET         | {singular_name}        | {singular_name}_path
+new         | GET         | new_{singular_name}    | new_{singular_name}_path
+edit        | GET         | edit_{singular_name}   | edit_{singular_name}_path
+create      | POST        | create_{singular_name} | create_{singular_name}_path
+update      | PUT/PATCH   | update_{singular_name} | update_{singular_name}_path
+destroy     | DELETE      | delete_{singular_name} | delete_{singular_name}_path
+
+### Functions' arguments
+
+Here `String or Number, ...` represents values used in paths, e.g.
+`:id`, `:category_id` (zero, one or more params).
+
+And `...path_params` means hash-like object with values for paths, e.g.
+`{id: 123, category_id: 56}` (zero, one or more params).
+
+`data` means request body (payload), it can be hash-like object, `FormData` and so on, its allowed types depend on XHR library.
+
+All arguments are optional.
+
+```js
+// Request `index`, `show`, `new`, `edit`, `destroy` actions.
+({format: String, ...path_params, ...url_options})
+// Or:
+(String or Number, ..., {format: String, ...url_options})
+
+// Request `create` and `update` actions.
+({format: String, ...path_params, ...url_options}, data)
+// Or:
+(String or Number, ..., {format: String, ...url_options}, data)
+
+// Get path for any action (does not include query string starting with '?').
+({format: String, ...path_params})
+// Or:
+(String or Number, ..., {format: String})
+```
+
+### Configuration
+
+By default Railbus generates functions for all routes defined
+in `Rails.application` and these functions use `axios`. You may change it:
+
+```js
+<%=
+  Railbus.generate(
+    # Here `YourApp::Engine` inherits `Rails::Engine`.
+    # Default: `Rails.application`.
+    app:    YourApp::Engine,
+
+    # 'axios' or the name of function defined or imported in this file.
+    # Default: 'axios'.
+    client: 'request_api',
+
+    # Include only these route paths that start with '/api'.
+    # Empty array: include all routes (default).
+    include: [%r{^/api}],
+
+    # Exclude all route paths matching regexpes.
+    # Empty array: do not exclude any routes (default).
+    exclude: [/edit|new/]
+  )
+%>
+
+import axios from 'axios';
+const axios_api = axios.create({
+  baseURL: `${document.location.origin}/api/`
+})
+
+function request_api(route, params) {
+  return axios_api.request({
+    url:    params.path,
+    method: route.verb,
+    params: params.url_options,
+    data:   params.data
+  })
+}
+```
+
+### Examples
+
+Let's take these routes as an example:
+
+```ruby
+resources :news do
+  resources :images, only: %w[index show create update destroy]
+end
+resources :messages, only: %w[new create]
+namespace :my do
+  resources :favourites, only: %w[index show create update destroy]
+end
+```
+
+To make XHR requests with promises you may do this in JS
+([axios](https://github.com/axios/axios) required):
+
+```js
+import Routes from 'lib/routes'
+
+// Request all favourites and print to console. Note: using namespace `my`.
+// It will call `My::FavouritesController#index`.
+// Path: '/my/favourites'.
+Routes.my_favourites().then(response => console.log(response.data))
+
+// Request all news and print to console.
+// String `index` appended to distinguish `index` and `show` actions.
+// It will call `NewsController#index`.
+// Path: '/news'.
+Routes.news_index().then(response => console.log(response.data))
+
+// Request all news filtered by date, and print to console.
+// `NewsController#index` with param `date` in query string (GET).
+// Path: '/news' with query string '?date=2020-12-31'.
+Routes.news_index({date: '2020-12-31'}).then(response => console.log(response.data))
+
+// Request one news and print to console.
+// `NewsController#show` with param `id` = 327 (GET).
+// Path: '/news/327'.
+Routes.news(327).then(response => console.log(response.data))
+// Or
+Routes.news({id: 327}).then(response => console.log(response.data))
+
+// Specify format (for example, '.json').
+// `NewsController#show` with param `id` = 327 (GET) and `format` = 'json'.
+// Path: '/news/327.json'.
+Routes.news(327, {format: 'json'}).then(response => console.log(response.data))
+// Or
+Routes.news({id: 327, format: 'json'}).then(response => console.log(response.data))
+
+// Create news with given title.
+// `NewsController#create` with param `title` (POST).
+Routes.create_news({title: 'Bears showed up in Tomsk'}).then(response => console.log(response.data))
+
+// Create message with given title. Note: `message`, singular form.
+// `MessagesController#create` with params `body`, `to` (POST).
+Routes.create_message({body: 'Fantastic!', to: 23}).then(response => console.log(response.data))
+
+// Create message with given title. Note: using namespace `my`.
+// `My::FavouritesController#create` with param `url` (POST).
+Routes.create_my_favourite({url: 'https://best.site'}).then(response => console.log(response.data))
+
+// Attach an image to the news.
+// `ImageController#create` with param `news_id` = 41 (GET), `blob` (POST).
+Routes.create_news_image(41, {blob: file})
+
+// Get URL for `create` action.
+Routes.create_my_favourite_path() // => 'my/favourites'
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+TODO:
+
+- Support [fetch](https://developer.mozilla.org/ru/docs/Web/API/Fetch_API/Using_Fetch)
+- Tests
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at [github.com/crosspath/railbus](https://github.com/crosspath/railbus).
+
+Please do not change version number in pull requests.
+
+## Alternative solutions
+
+1. [rswag](https://github.com/rswag/rswag) +
+  [swagger-js](https://github.com/swagger-api/swagger-js) +
+  your integration specs (tests)
+2. [railsware/js-routes](https://github.com/railsware/js-routes)
+3. [mtrpcic/js-routes](https://github.com/mtrpcic/js-routes)
+4. [less-js-routes](https://github.com/stevenbristol/less-js-routes)
+5. [js_named_routes](https://github.com/jsierles/js_named_routes)
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "railbus"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start(__FILE__)

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/railbus.rb

@@ -0,0 +1,28 @@
+require 'json'
+require 'erubi'
+require 'active_support'
+
+require_relative 'railbus/version'
+require_relative 'railbus/route_set'
+require_relative 'railbus/route_set_presenter'
+
+module Railbus
+  module_function
+
+  def generate(
+    app:     Rails.application,
+    client:  'axios',
+    include: [],
+    exclude: []
+  )
+    route_set   = RouteSet.new(app, include, exclude)
+    routes_json = Railbus::RouteSetPresenter.to_h(route_set).to_json
+
+    js_template = File.join(__dir__, 'railbus', 'templates', 'js.erb')
+    erb_engine  = Erubi::Engine.new(File.read(js_template))
+
+    # Template uses `routes_json`, `client`
+    client = client.to_s
+    eval(erb_engine.src)
+  end
+end

data/lib/railbus/route_set.rb

@@ -0,0 +1,114 @@
+class Railbus::RouteSet
+  # Example:
+  # get, /users/:id, ['/users/', {a: 'id'}], ['id'], user
+  Route = Struct.new(:verb, :path, :parts, :required, :name)
+
+  %w[post patch put].each do |word|
+    Route.define_method("#{word}?") { verb == word }
+  end
+
+  MAP_NAMES = {
+    'post'   => 'create_',
+    'put'    => 'update_',
+    'patch'  => 'update_',
+    'delete' => 'destroy_'
+  }
+
+  attr_reader :paths
+
+  def initialize(app, include, exclude)
+    @paths = add_route_names(paths_for_app(app, include, exclude))
+  end
+
+  private
+
+  def paths_for_app(app, include, exclude)
+    app.routes.set.routes.map do |route|
+      formatter   = route.instance_variable_get(:@path_formatter)
+      route_parts = parts_combined(formatter.instance_variable_get(:@parts))
+
+      path = join_parts(route_parts)
+      next nil unless include_path?(path, include, exclude)
+
+      Route.new(
+        route.verb.downcase,
+        path,
+        route_parts,
+        required_params(route_parts),
+        route.name
+      )
+    end.compact
+  end
+
+  def parts_combined(parts)
+    parts.reduce([]) do |a, pt|
+      e = parts_element(pt)
+      next a if e.empty?
+      if a.empty?
+        a = [e]
+      elsif a[-1].respond_to?(:<<) && e.respond_to?(:<<)
+        # Both vars are strings -> concat them.
+        a[-1] << e
+      else
+        a << e
+      end
+      a
+    end
+  end
+
+  def parts_element(part)
+    if part.respond_to?(:name)
+      # Is a path parameter (e.g. `:id`).
+      {a: part.name}
+    else
+      # Is a `format` parameter -> skip it.
+      # Otherwise it is a string.
+      (part.respond_to?(:evaluate) ? '' : part).dup
+    end
+  end
+
+  def join_parts(route_parts)
+    route_parts.map { |x| x.respond_to?(:<<) ? x : ":#{x[:a]}" }.join
+  end
+
+  def required_params(route_parts)
+    route_parts.reject { |x| x.respond_to?(:<<) }.map { |x| x[:a] }
+  end
+
+  def include_path?(path, include, exclude)
+    return false if !include.empty? && include.none? { |re| path =~ re }
+    return false if exclude.any? { |re| path =~ re }
+    true
+  end
+
+  def add_route_names(paths)
+    paths.group_by(&:path).flat_map do |_, routes|
+      name = routes.find(&:name)&.name
+      if name
+        routes.reject!(&:patch?) if routes.find(&:put?)
+        routes.map do |route|
+          route.name ||= "#{MAP_NAMES[route.verb]}#{route_name(route, name)}"
+          route
+        end
+      else
+        []
+      end
+    end.uniq
+  end
+
+  def route_name(route, base_name)
+    if route.post?
+      route_name_for_create(base_name)
+    else
+      base_name
+    end
+  end
+
+  def route_name_for_create(base_name)
+    if base_name.end_with?('_index')
+      base_name.sub(/_index$/, '')
+    else
+      base_name.singularize
+    end
+  end
+end

data/lib/railbus/route_set_presenter.rb

@@ -0,0 +1,11 @@
+module Railbus::RouteSetPresenter
+  module_function
+
+  def to_h(route_set)
+    result = {}
+    route_set.paths.each do |route|
+      result[route.name] = route.to_h
+    end
+    result
+  end
+end

data/lib/railbus/templates/js.erb

@@ -0,0 +1,92 @@
+const routes = <%= routes_json.html_safe %>;
+
+<% if client == 'axios' %>
+import axios from 'axios'
+
+function request(route, args) {
+  const params = build_request_options(route, args)
+  return axios.request({
+    url:    params.path,
+    method: route.verb,
+    params: params.url_options,
+    data:   params.data
+  })
+}
+<% else %>
+function request(route, args) {
+  const params = build_request_options(route, args)
+  return <%= client %>(route, params)
+}
+<% end %>
+
+const request_functions = Object.fromEntries(
+  Object.entries(routes).map(pair => {
+    const route = pair[1]
+    const func  = (...args) => request(route, args)
+    return [pair[0], func]
+  })
+)
+
+const path_functions = Object.fromEntries(
+  Object.entries(routes).map(pair => {
+    const route = pair[1]
+    const func  = (...args) => build_request_options(route, args).path
+    return [`${pair[0]}_path`, func]
+  })
+)
+
+export default Object.assign({}, request_functions, path_functions)
+
+function split_args(route, args) {
+  const required_params = route.required
+  let path_params = {}, url_options = {}, data = {}
+  for (let index in args) {
+    const arg = args[index]
+    if (['string', 'number'].includes(typeof arg)) {
+      path_params[required_params[index]] = arg
+    } else {
+      break
+    }
+  }
+  let options = args[Object.keys(path_params).length]
+  data = args[Object.keys(path_params).length + 1]
+  if (typeof options !== 'object')
+    options = {}
+  if (typeof data !== 'object')
+    data = {}
+  for (let param of required_params) {
+    if (!(param in path_params)) {
+      if (param in options) {
+        path_params[param] = options[param]
+      } else {
+        throw new Error(required_param(route, param))
+      }
+    }
+  }
+  const format = presence(options.format)
+  const extracted = required_params.concat(['format'])
+  url_options = Object.fromEntries(
+    Object.entries(options).filter(pair => !extracted.includes(pair[0]))
+  )
+  return {path_params, format, url_options, data}
+}
+
+function presence(v) {
+  return (v != null && v !== '') ? v : null
+}
+
+function required_param(route, param) {
+  return `Cannot find "${param}" in passed URL options. `+
+      `This value is required for route "${route.name}" (${route.path}).`;
+}
+
+function build_request_options(route, args) {
+  const params = split_args(route, args)
+  let path = route.parts.
+      map(v => typeof v === 'string' ? v : params.path_params[v.a]).join('')
+  if (params.format)
+    path += `.${params.format}`
+  if (['get', 'delete'].includes(route.verb))
+    params.data = null
+  return {path: path, url_options: params.url_options, data: params.data}
+}

data/lib/railbus/version.rb

@@ -0,0 +1,3 @@
+module Railbus
+  VERSION = "0.1.0"
+end

data/railbus.gemspec

@@ -0,0 +1,34 @@
+require_relative 'lib/railbus/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "railbus"
+  spec.version       = Railbus::VERSION
+  spec.authors       = ["Evgeniy Nochevnov"]
+
+  spec.summary       = %q{Generate JS functions for XHR requests to Rails routes}
+  # spec.description   = %q{TODO: Write a longer description or delete this line.}
+  spec.homepage      = "https://github.com/crosspath/railbus"
+  spec.license       = "MIT"
+  spec.required_ruby_version = Gem::Requirement.new(">= 2.3.0")
+
+  spec.add_dependency 'activesupport'
+  spec.add_dependency 'erubi'
+
+  spec.add_development_dependency 'rake'
+  # spec.add_development_dependency 'rspec', '>= 3'
+
+  # spec.metadata["allowed_push_host"] = "TODO: Set to 'http://mygemserver.com'"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/crosspath/railbus"
+  # spec.metadata["changelog_uri"] = "TODO: Put your gem's CHANGELOG.md URL here."
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
+    `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+end

metadata

@@ -0,0 +1,102 @@
+--- !ruby/object:Gem::Specification
+name: railbus
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Evgeniy Nochevnov
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2020-07-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: erubi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email: 
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".editorconfig"
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Gemfile
+- LICENSE
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/railbus.rb
+- lib/railbus/route_set.rb
+- lib/railbus/route_set_presenter.rb
+- lib/railbus/templates/js.erb
+- lib/railbus/version.rb
+- railbus.gemspec
+homepage: https://github.com/crosspath/railbus
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/crosspath/railbus
+  source_code_uri: https://github.com/crosspath/railbus
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.0.3
+signing_key: 
+specification_version: 4
+summary: Generate JS functions for XHR requests to Rails routes
+test_files: []