js-routes 1.4.11 → 2.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9c3f51f23d5304f6e3df508ebada74e685ec6305b478f556cb76c8d6ad99a7ff
-  data.tar.gz: '081dda3bca55d88f5ad34089e9754a219c3603af20987aef0781beb1e57ed79e'
+  metadata.gz: 52b735748b525770a79a5dcb0fe510b50350e3e22541fcb34f39fbc04b9a4f02
+  data.tar.gz: ca5ec3a0e5adcf943854681413dfc11f4da9cd91c46a3bb817ee85ea6da303a0
 SHA512:
-  metadata.gz: 98370a987b6d01b7d3eeab333767b50f668ed67cadeb51a5b7ce9298c85e51ef9edae8081a4396af46096a1dfa0b9854e32b548baef18e1774031c0ed31b0b38
-  data.tar.gz: e55fa57008421373e99cb9674701d64dc59dc79db419ab216a004bb76405950be5d8c906e4fbdc066d16c74fef0292b7de750da8a314703514736e936dcdaff0
+  metadata.gz: 820f89d751dfb532235098abcaf5a26e568d5acd34ab469ccf8d61dfaa4427ac59e8597860ce9cd05728869c401d72e5beb6501aac2ee9713772091db80cc0d5
+  data.tar.gz: 0ba55b8c600a1ea89737a860b5ca728572972e149900c35fd39ac439dcae0f9af8541649f356c4341b4331a73ede9382ed20b9c75311cb24c27cb7eebd510c29

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,9 +1,34 @@
 ## master
 
+## v2.0.1
+
+* Fixed backward compatibility issue [#272](https://github.com/railsware/js-routes/issues/272)
+
+## 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.

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/webpack/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|
@@ -43,6 +133,7 @@ end
 Or dynamically in JavaScript, although only [Formatter Options](#formatter-options) are supported (see below)
 
 ``` js
+import * as Routes from 'routes'
 Routes.configure({
   option: value
 });
@@ -53,8 +144,14 @@ Routes.config(); // current config
 
 ##### Generator Options
 
-Options to configure JavaScript file generator:
+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: `[]`
   * The regexp applies only to the name before the `_path` suffix, eg: you want to match exactly `settings_path`, the regexp should be `/^settings$/`
@@ -63,11 +160,10 @@ Options to configure JavaScript file generator:
   * 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`
-* `camel_case` - Generate camel case route names.
+  * Default: `nil`
+* `camel_case` - specifies if route helpers should be generated in camel case instead of underscore case.
   * Default: `false`
-* `url_links` - Generate `*_url` helpers (in addition to the default `*_path` helpers).
-  * Example: `true`
+* `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` - Remove `_path` suffix in path routes(`*_url` routes stay untouched if they were enabled)
@@ -77,80 +173,64 @@ Options to configure JavaScript file generator:
   * 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/assets/javascripts/routes.js` if `app/assets/javascripts` directory exists, otherwise `app/javascript/routes.js`.
+  * 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:
+Options to configure routes formatting. These options are available both in Ruby and JavaScript context.
 
 * `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: `{}`
-* `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.
+* `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
-  * 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: `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
-  * Option is configurable at JS level with `Routes.configure()`
   * 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:
 
+``` erb
+// app/javascript/admin/routes.js.erb
+<%= JsRoutes.generate(include: /admin/) %>
 ```
-# app/assets/javascripts/admin/routes.js.erb
-<%= JsRoutes.generate(namespace: "AdminRoutes", include: /admin/) %>
-
-# app/assets/javascripts/admin.js.coffee
-#= require admin/routes
-```
-
-```
-# app/assets/javascripts/application/routes.js.erb
-<%= JsRoutes.generate(namespace: "AppRoutes", exclude: /admin/) %>
 
-# app/assets/javascripts/application.js.coffee
-#= require application/routes
+``` erb
+// 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"
@@ -191,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']
 ```
 
 
@@ -216,9 +296,34 @@ Routes.company_project_path({company_id: 1, id: 2, _options: true}) // => "/comp
 
 ## What about security?
 
-JsRoutes itself does 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
 
@@ -238,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

data/VERSION_2_UPGRADE.md

@@ -0,0 +1,61 @@
+## Version 2.0 upgrade notes
+
+### Using ESM module by default
+
+The default setting are now changed:
+
+Setting | Old | New 
+--- | --- | ---
+module\_type | nil | ESM 
+namespace | Routes | nil
+
+This is more optimized setup for WebPacker. You can restore the old configuration like this:
+
+``` ruby
+JsRoutes.setup do |config|
+  config.module_type = nil
+  config.namespace = 'Routes'
+end
+```
+
+However, [ESM+Webpacker](/Readme.md#webpacker) upgrade is recommended. 
+
+### `required_params` renamed
+
+In case you are using `required_params` property, it is now renamed and converted to a method:
+
+``` javascript
+// Old style
+Routes.post_path.required_params  // => ['id']
+// New style
+Routes.post_path.requiredParams() // => ['id']
+```
+
+### ParameterMissing error rework
+
+`ParameterMissing` is renamed to `ParametersMissing` error and now list all missing parameters instead of just first encountered in its message. Missing parameters are now available via `ParametersMissing#keys` property.
+
+``` javascript
+try {
+  return Routes.inbox_path();
+} catch(error) {
+  if (error.name === 'ParametersMissing') {
+    console.warn(`Missing route keys ${error.keys.join(', ')}. Ignoring.`);
+    return "#";
+  } else {
+    throw error;
+  }
+}
+```
+
+### JSDoc comment format
+
+New version of js-routes generates function comment in the [JSDoc](https://jsdoc.app) format.
+If you have any problems with that disable the annotation:
+
+``` ruby
+JsRoutes.setup do |config|
+  config.documentation = false
+end
+```
+