js-routes 1.4.9 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bcc3b758ce05ed0444162cda94d5442b811a582330ea4418cf816763e4e482b0
-  data.tar.gz: 3bfd8cc484ba00a6cd7ff0e5ffb90c3f3ec11c1d7aa9171572e93bc66b1cab42
+  metadata.gz: 86ed2a6e4f90ea3c7bbc91836148b23121acbb21c59e4b26e55f0925a2d37fce
+  data.tar.gz: 485241d5aa3e009545a78113c49e2781be677cb4ddfe91286329f325f8a6b9dc
 SHA512:
-  metadata.gz: a51ee9fc01642e16287b648085debd75749b983b2602a2407068cc7159cd302f8b04bd065b1ea28f7314cd19ae60e535cede86af4e7d7073648ffe2b3222d006
-  data.tar.gz: a979758f820232a129f9befd597a248511c76b05eab8aae5b62b56bf31a2f94580b889371aa52e584aac0fdfd5802a03f1632eaee65713b2438d98e29265846b
+  metadata.gz: 75844cdc35fc7cbf506fdd40eb00bc002c8bdc35397607943d28519572ae63f3f374cd249c4f50c218a979ffbbafe3938d5d2de0d1f03505e00549b9483a7ae6
+  data.tar.gz: ffb6920c23e81c18cc4c6e1476ae61f60801973e93583cd481ef6cd9f45171005de01124cc62aefc7862c2451cdbde31787efeeb8d2fb2e9dab223b1f5964230

data/.eslintrc.js

@@ -0,0 +1,15 @@
+ module.exports = {
+  root: true,
+  extends: [
+    'eslint:recommended',
+    'plugin:@typescript-eslint/eslint-recommended',
+    'plugin:@typescript-eslint/recommended',
+    'prettier/@typescript-eslint',
+  ],
+  parser: '@typescript-eslint/parser',
+  plugins: ['@typescript-eslint'],
+  rules: {
+    '@typescript-eslint/ban-types': 'off',
+    '@typescript-eslint/no-explicit-any': 'off'
+  },
+};

data/.gitignore

@@ -15,6 +15,8 @@ log
 # jeweler generated
 pkg
 
+node_modules
+
 # Have editor/IDE/OS specific files you need to ignore? Consider using a global gitignore:
 #
 # * Create a file at ~/.gitignore
@@ -58,3 +60,5 @@ gemfiles/*.lock
 /spec/dummy/app/assets/javascripts/routes.js
 /spec/dummy/logs
 /spec/dummy/tmp
+node_modules
+

data/.nvmrc

@@ -0,0 +1 @@
+14

data/.travis.yml

@@ -5,7 +5,6 @@ before_install:
   - gem install bundler # need for jruby and ruby-head
 
 rvm:
-  - 2.3.1
   - 2.4.1
   - 2.5.3
   - 2.6.0
@@ -22,6 +21,8 @@ gemfile:
   - gemfiles/rails50_sprockets_3.gemfile
   - gemfiles/rails51_sprockets_3.gemfile
   - gemfiles/rails52_sprockets_3.gemfile
+env:
+  TRAVIS_CI: true
 
 sudo: false
 dist: xenial

data/CHANGELOG.md

@@ -1,5 +1,34 @@
 ## master
 
+## v2.0.0
+
+Version 2.0 has some breaking changes.
+See [UPGRADE TO 2.0](./VERSION_2_UPGRADE.md) for guidance.
+
+* `module_type` option support
+* `documentation` option spport
+* Migrated implementation to typescript
+* ESM tree shaking support
+* Support camel case `toParam` version of `to_param` property
+
+## v1.4.14
+
+* Fix compatibility with UMD modules #237 [Comment](https://github.com/railsware/js-routes/issues/237#issuecomment-752754679)
+
+## v1.4.13
+
+* Improve compatibility with node environment #269.
+* Change default file location configuration to Webpacker if both Webpacker and Sprockets are loaded
+
+## v1.4.11
+
+* Use app/javascript/routes.js as a default file location if app/javascript directory exists
+* Add `default` export for better experience when used as es6 module
+
+## v1.4.10
+
+* Require engine only when sprockets is loaded #257.
+
 ## v1.4.9
 
 * Allow to specify null namespace and receive routes as an object without assigning it anywhere #247

data/Readme.md

@@ -4,6 +4,8 @@
 
 Generates javascript file that defines all Rails named routes as javascript helpers
 
+[UPGRADE TO 2.0](./VERSION_2_UPGRADE.md)
+
 ## Intallation
 
 Your Rails Gemfile:
@@ -12,9 +14,97 @@ Your Rails Gemfile:
 gem "js-routes"
 ```
 
-### Basic Setup
+## Setup
+
+### Quick Start 
+
+Run:
+
+```
+rake js:routes 
+```
+
+Make routes available globally in `app/javascript/packs/application.js`: 
+
+``` javascript
+import * as Routes from 'routes';
+window.Routes = Routes;
+```
+
+Individual routes can be imported using:
+
+``` javascript
+import {edit_post_path} from 'routes';
+console.log(edit_post_path(1))
+```
+
+**Note**: that this setup requires `rake js:routes` to be run each time routes file is updated.
+
+<div id='webpacker'></div>
+
+#### Webpacker + automatic updates
+
+
+This setup can automatically update your routes without `rake js:routes` being called manually.
+It requires [rails-erb-loader](https://github.com/usabilityhub/rails-erb-loader) npm package to work.
+
+Add `erb` loader to webpacker:
+
+``` sh
+yarn add rails-erb-loader
+rm -f app/javascript/routes.js # delete static file if any
+```
+
+Create webpack ERB config `config/webpack/loaders/erb.js`:
+
+``` javascript
+module.exports = {
+  test: /\.js\.erb$/,
+  enforce: 'pre',
+  exclude: /node_modules/,
+  use: [{
+    loader: 'rails-erb-loader',
+    options: {
+      runner: (/^win/.test(process.platform) ? 'ruby ' : '') + 'bin/rails runner'
+    }
+  }]
+}
+```
+
+Enable `erb` extension in `config/webpacker/environment.js`:
 
-Require JsRoutes in `application.js` or other bundle
+``` javascript
+const erb = require('./loaders/erb')
+environment.loaders.append('erb', erb)
+```
+
+Create routes file `app/javascript/routes.js.erb`:
+
+``` erb
+<%= JsRoutes.generate() %>
+```
+
+Use routes wherever you need them `app/javascript/packs/application.js`: 
+
+``` javascript
+import * as Routes from 'routes.js.erb';
+window.Routes = Routes;
+```
+
+#### Sprockets (Deprecated)
+
+If you are using [Sprockets](https://github.com/rails/sprockets-rails) you may configure js-routes in the following way.
+
+Setup the initializer (e.g. `config/initializers/js_routes.rb`):
+
+``` ruby
+JsRoutes.setup do |config|
+  config.module_type = nil
+  config.namespace = 'Routes'
+end
+```
+
+Require JsRoutes in `app/assets/javascripts/application.js` or other bundle
 
 ``` js
 //= require js-routes
@@ -32,7 +122,7 @@ This cache is not flushed on server restart in development environment.
 
 ### Configuration
 
-You can configure JsRoutes in two main ways. Either with an initializer (e.g. `config/initializers/jsroutes.rb`):
+You can configure JsRoutes in two main ways. Either with an initializer (e.g. `config/initializers/js_routes.rb`):
 
 ``` ruby
 JsRoutes.setup do |config|
@@ -40,107 +130,107 @@ JsRoutes.setup do |config|
 end
 ```
 
-Or dynamically in JavaScript, although not all configuration options are supported:
+Or dynamically in JavaScript, although only [Formatter Options](#formatter-options) are supported (see below)
 
 ``` js
+import * as Routes from 'routes'
 Routes.configure({
   option: value
 });
 Routes.config(); // current config
 ```
 
-Available options:
+#### Available Options
 
-* `default_url_options` - default parameters used when generating URLs
-  * Option is configurable at JS level with `Routes.configure()`
-  * Example: {:format => "json", :trailing\_slash => true, :protocol => "https", :subdomain => "api", :host => "example.com", :port => 3000}
-  * Default: {}
+##### Generator Options
+
+Options to configure JavaScript file generator. These options are only available in Ruby context but not JavaScript.
+
+* `module_type` - JavaScript module type for generated code. [Article](https://dev.to/iggredible/what-the-heck-are-cjs-amd-umd-and-esm-ikm)
+  * Options: `ESM`, `UMD`, `CJS`, `AMD`, `nil`.
+  * Default: `ESM`
+  * `nil` option can be used in case you don't want generated code to export anything.
+* `documentation` - specifies if each route should be annotated with [JSDoc](https://jsdoc.app/) comment
+  * Default: `true`
 * `exclude` - Array of regexps to exclude from routes.
-  * Default: []
+  * Default: `[]`
   * The regexp applies only to the name before the `_path` suffix, eg: you want to match exactly `settings_path`, the regexp should be `/^settings$/`
 * `include` - Array of regexps to include in routes.
-  * Default: []
+  * Default: `[]`
   * The regexp applies only to the name before the `_path` suffix, eg: you want to match exactly `settings_path`, the regexp should be `/^settings$/`
 * `namespace` - global object used to access routes.
   * Supports nested namespace like `MyProject.routes`
-  * Default: `Routes`
-* `prefix` - String representing a url path to prepend to all paths.
-  * Option is configurable at JS level with `Routes.configure()`
-  * Example: `http://yourdomain.com`. This will cause route helpers to generate full path only.
-  * Default: `Rails.application.config.relative_url_root`
-* `camel_case` (version >= 0.8.8) - Generate camel case route names.
-  * Default: false
-* `url_links` (version >= 0.8.9) - Generate `*_url` helpers (in addition to the default `*_path` helpers).
-  * Example: true
-  * Default: false
+  * Default: `nil`
+* `camel_case` - specifies if route helpers should be generated in camel case instead of underscore case.
+  * Default: `false`
+* `url_links` - specifies if `*_url` helpers should be generated (in addition to the default `*_path` helpers).
+  * Default: `false`
   * Note: generated URLs will first use the protocol, host, and port options specified in the route definition. Otherwise, the URL will be based on the option specified in the `default_url_options` config. If no default option has been set, then the URL will fallback to the current URL based on `window.location`.
-* `compact` (version > 0.9.9) - Remove `_path` suffix in path routes(`*_url` routes stay untouched if they were enabled)
-  * Default: false
+* `compact` - Remove `_path` suffix in path routes(`*_url` routes stay untouched if they were enabled)
+  * Default: `false`
   * Sample route call when option is set to true: Routes.users() => `/users`
-* `serializer` (version >= 1.1.0) - Puts a JS function here that serializes a Javascript Hash object into URL paramters: `{a: 1, b: 2} => "a=1&b=2"`.
-  * Default: `nil`. Uses built-in serializer
-  * Option is configurable at JS level with `Routes.configure()`
-  * Example: `jQuery.param` - use jQuery's serializer algorithm. You can attach serialize function from your favorite AJAX framework.
-  * Example: `MyApp.custom_serialize` - use completely custom serializer of your application.
-
-* `special_options_key` - a special key that helps JsRoutes to destinguish serialized model from options hash
-  * This option is required because JS doesn't provide a difference between an object and a hash
-  * Option is configurable at JS level with `Routes.configure()`
-  * Default: `_options`
 * `application` - a key to specify which rails engine you want to generate routes too.
   * This option allows to only generate routes for a specific rails engine, that is mounted into routes instead of all Rails app routes
   * Default: `Rails.application`
+* `file` - a file location where generated routes are stored
+  * Default: `app/javascript/routes.js` if setup with Webpacker, otherwise `app/assets/javascripts/routes.js` if setup with Sprockets.
+
+##### Formatter Options
+
+Options to configure routes formatting. These options are available both in Ruby and JavaScript context.
+
+* `default_url_options` - default parameters used when generating URLs
+  * Example: `{format: "json", trailing_slash: true, protocol: "https", subdomain: "api", host: "example.com", port: 3000}`
+  * Default: `{}`
+* `prefix` - string that will prepend any generated URL. Usually used when app URL root includes a path component.
+  * Example: `/rails-app`
+  * Default: `Rails.application.config.relative_url_root`
+* `serializer` - a JS function that serializes a Javascript Hash object into URL paramters like `{a: 1, b: 2} => "a=1&b=2"`.
+  * Default: `nil`. Uses built-in serializer compatible with Rails
+  * Example: `jQuery.param` - use jQuery's serializer algorithm. You can attach serialize function from your favorite AJAX framework.
+  * Example: `function (object) { ... }` - use completely custom serializer of your application.
+* `special_options_key` - a special key that helps JsRoutes to destinguish serialized model from options hash
+  * This option exists because JS doesn't provide a difference between an object and a hash
+  * Default: `_options`
 
-### Very Advanced Setup
+### Advanced Setup
 
 In case you need multiple route files for different parts of your application, you have to create the files manually.
 If your application has an `admin` and an `application` namespace for example:
 
 ```
-# app/assets/javascripts/admin/routes.js.erb
-<%= JsRoutes.generate(namespace: "AdminRoutes", include: /admin/) %>
-
-# app/assets/javascripts/admin.js.coffee
-#= require admin/routes
+# app/javascript/admin/routes.js.erb
+<%= JsRoutes.generate(include: /admin/) %>
 ```
 
 ```
-# app/assets/javascripts/application/routes.js.erb
-<%= JsRoutes.generate(namespace: "AppRoutes", exclude: /admin/) %>
-
-# app/assets/javascripts/application.js.coffee
-#= require application/routes
+# app/javascript/customer/routes.js.erb
+<%= JsRoutes.generate(exclude: /admin/) %>
 ```
 
-In order to generate the routes JS code to a string:
+You can manipulate the generated helper manually by injecting ruby into javascript:
 
-```ruby
-routes_js = JsRoutes.generate(options)
+``` erb
+export const routes = <%= JsRoutes.generate(module_type: nil, namespace: nil) %>
 ```
 
 If you want to generate the routes files outside of the asset pipeline, you can use `JsRoutes.generate!`:
 
 ``` ruby
-path = "app/assets/javascripts"
-JsRoutes.generate!("#{path}/app_routes.js", :namespace => "AppRoutes", :exclude => [/^admin_/, /^api_/])
-JsRoutes.generate!("#{path}/adm_routes.js", :namespace => "AdmRoutes", :include => /^admin_/)
-JsRoutes.generate!("#{path}/api_routes.js", :namespace => "ApiRoutes", :include => /^api_/, :default_url_options => {:format => "json"})
-```
-
-### Rails relative URL root
+path = Rails.root.join("app/javascript")
 
-If you've installed your application in a sub-path or sub-URI of your server instead of at the root, you need to set the `RAILS_RELATIVE_URL_ROOT` environment variable to the correct path prefix for your application when you precompile assets. Eg., if your application's base URL is "https://appl.example.com/Application1", the command to precompile assets would be:
+JsRoutes.generate!("#{path}/app_routes.js", exclude: [/^admin_/, /^api_/])
+JsRoutes.generate!("#{path}/adm_routes.js", include: /^admin_/)
+JsRoutes.generate!("#{path}/api_routes.js", include: /^api_/, default_url_options: {format: "json"})
 ```
-RAILS_RELATIVE_URL_ROOT=/Application1 RAILS_ENV=production bundle exec rake assets:precompile
-```
-The environment variable is only needed for precompilation of assets, at any other time (eg. when assets are compiled on-the-fly as in the development environment) Rails will set the relative URL root correctly on it's own.
-
 
 ## Usage
 
 Configuration above will create a nice javascript file with `Routes` object that has all the rails routes available:
 
 ``` js
+import * as Routes from 'routes';
+
 Routes.users_path() // => "/users"
 Routes.user_path(1) // => "/users/1"
 Routes.user_path(1, {format: 'json'}) // => "/users/1.json"
@@ -181,11 +271,11 @@ This function allow to get the same `spec` for route, if you will get string rep
 '' + Routes.user_path // => "/users/:id(.:format)"
 ```
 
-Route function also contain inside attribute `required_params` required param names as array:
+Route function also contain method `requiredParams` inside which returns required param names array:
 
 ```js
-Routes.users_path.required_params // => []
-Routes.user_path.required_params // => ['id']
+Routes.users_path.requiredParams() // => []
+Routes.user_path.requiredParams() // => ['id']
 ```
 
 
@@ -206,9 +296,34 @@ Routes.company_project_path({company_id: 1, id: 2, _options: true}) // => "/comp
 
 ## What about security?
 
-JsRoutes itself do not have security holes. It makes URLs
-without access protection more reachable by potential attacker.
-In order to prevent this use `:exclude` option for sensitive urls like `/admin_/`
+JsRoutes itself does not have security holes. 
+It makes URLs without access protection more reachable by potential attacker.
+If that is an issue for you, you may use one of the following solutions:
+
+### Explicit Import + ESM Tree shaking
+
+Make sure `module_type` is set to `ESM` (the default) and JS files import only required routes into the file like:
+
+``` javascript
+import {
+  inbox_path,
+  inboxes_path,
+  inbox_message_path,
+  inbox_attachment_path,
+  user_path,
+} from 'routes.js.erb'
+```
+
+### Exclude option
+
+Split your routes into multiple files related to each section of your website like:
+
+``` javascript
+// admin-routes.js.erb
+<%= JsRoutes.generate(include: /^admin_/)
+// app-routes.js.erb
+<%= JsRoutes.generate(exclude: /^admin_/)
+```
 
 ## JsRoutes and Heroku
 
@@ -228,11 +343,20 @@ There are some alternatives available. Most of them has only basic feature and d
 Advantages of this one are:
 
 * Rails 4,5,6 support
+* [ESM Tree shaking](https://webpack.js.org/guides/tree-shaking/) support
 * Rich options set
 * Full rails compatibility
 * Support Rails `#to_param` convention for seo optimized paths
 * Well tested
 
+## Version 2 TODO
+
+* Add routes generation .d.ts file
+* Add config option on the output format: js, ts, d.ts
+* Add prettier
+* Add eslint
+* Add development guide
+
 #### Thanks to [contributors](https://github.com/railsware/js-routes/contributors)
 
 #### Have fun