js-routes 1.4.11 → 2.0.1

Sign up to get free protection for your applications and to get access to all the features.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 9c3f51f23d5304f6e3df508ebada74e685ec6305b478f556cb76c8d6ad99a7ff
4
- data.tar.gz: '081dda3bca55d88f5ad34089e9754a219c3603af20987aef0781beb1e57ed79e'
3
+ metadata.gz: 52b735748b525770a79a5dcb0fe510b50350e3e22541fcb34f39fbc04b9a4f02
4
+ data.tar.gz: ca5ec3a0e5adcf943854681413dfc11f4da9cd91c46a3bb817ee85ea6da303a0
5
5
  SHA512:
6
- metadata.gz: 98370a987b6d01b7d3eeab333767b50f668ed67cadeb51a5b7ce9298c85e51ef9edae8081a4396af46096a1dfa0b9854e32b548baef18e1774031c0ed31b0b38
7
- data.tar.gz: e55fa57008421373e99cb9674701d64dc59dc79db419ab216a004bb76405950be5d8c906e4fbdc066d16c74fef0292b7de750da8a314703514736e936dcdaff0
6
+ metadata.gz: 820f89d751dfb532235098abcaf5a26e568d5acd34ab469ccf8d61dfaa4427ac59e8597860ce9cd05728869c401d72e5beb6501aac2ee9713772091db80cc0d5
7
+ data.tar.gz: 0ba55b8c600a1ea89737a860b5ca728572972e149900c35fd39ac439dcae0f9af8541649f356c4341b4331a73ede9382ed20b9c75311cb24c27cb7eebd510c29
data/.eslintrc.js ADDED
@@ -0,0 +1,15 @@
1
+ module.exports = {
2
+ root: true,
3
+ extends: [
4
+ 'eslint:recommended',
5
+ 'plugin:@typescript-eslint/eslint-recommended',
6
+ 'plugin:@typescript-eslint/recommended',
7
+ 'prettier/@typescript-eslint',
8
+ ],
9
+ parser: '@typescript-eslint/parser',
10
+ plugins: ['@typescript-eslint'],
11
+ rules: {
12
+ '@typescript-eslint/ban-types': 'off',
13
+ '@typescript-eslint/no-explicit-any': 'off'
14
+ },
15
+ };
data/.gitignore CHANGED
@@ -15,6 +15,8 @@ log
15
15
  # jeweler generated
16
16
  pkg
17
17
 
18
+ node_modules
19
+
18
20
  # Have editor/IDE/OS specific files you need to ignore? Consider using a global gitignore:
19
21
  #
20
22
  # * Create a file at ~/.gitignore
@@ -58,3 +60,5 @@ gemfiles/*.lock
58
60
  /spec/dummy/app/assets/javascripts/routes.js
59
61
  /spec/dummy/logs
60
62
  /spec/dummy/tmp
63
+ node_modules
64
+
data/.nvmrc ADDED
@@ -0,0 +1 @@
1
+ 14
data/.travis.yml CHANGED
@@ -5,7 +5,6 @@ before_install:
5
5
  - gem install bundler # need for jruby and ruby-head
6
6
 
7
7
  rvm:
8
- - 2.3.1
9
8
  - 2.4.1
10
9
  - 2.5.3
11
10
  - 2.6.0
@@ -22,6 +21,8 @@ gemfile:
22
21
  - gemfiles/rails50_sprockets_3.gemfile
23
22
  - gemfiles/rails51_sprockets_3.gemfile
24
23
  - gemfiles/rails52_sprockets_3.gemfile
24
+ env:
25
+ TRAVIS_CI: true
25
26
 
26
27
  sudo: false
27
28
  dist: xenial
data/CHANGELOG.md CHANGED
@@ -1,9 +1,34 @@
1
1
  ## master
2
2
 
3
+ ## v2.0.1
4
+
5
+ * Fixed backward compatibility issue [#272](https://github.com/railsware/js-routes/issues/272)
6
+
7
+ ## v2.0.0
8
+
9
+ Version 2.0 has some breaking changes.
10
+ See [UPGRADE TO 2.0](./VERSION_2_UPGRADE.md) for guidance.
11
+
12
+ * `module_type` option support
13
+ * `documentation` option spport
14
+ * Migrated implementation to typescript
15
+ * ESM tree shaking support
16
+ * Support camel case `toParam` version of `to_param` property
17
+
18
+ ## v1.4.14
19
+
20
+ * Fix compatibility with UMD modules #237 [Comment](https://github.com/railsware/js-routes/issues/237#issuecomment-752754679)
21
+
22
+ ## v1.4.13
23
+
24
+ * Improve compatibility with node environment #269.
25
+ * Change default file location configuration to Webpacker if both Webpacker and Sprockets are loaded
26
+
27
+ ## v1.4.11
28
+
3
29
  * Use app/javascript/routes.js as a default file location if app/javascript directory exists
4
30
  * Add `default` export for better experience when used as es6 module
5
31
 
6
-
7
32
  ## v1.4.10
8
33
 
9
34
  * Require engine only when sprockets is loaded #257.
data/Readme.md CHANGED
@@ -4,6 +4,8 @@
4
4
 
5
5
  Generates javascript file that defines all Rails named routes as javascript helpers
6
6
 
7
+ [UPGRADE TO 2.0](./VERSION_2_UPGRADE.md)
8
+
7
9
  ## Intallation
8
10
 
9
11
  Your Rails Gemfile:
@@ -12,9 +14,97 @@ Your Rails Gemfile:
12
14
  gem "js-routes"
13
15
  ```
14
16
 
15
- ### Basic Setup
17
+ ## Setup
18
+
19
+ ### Quick Start
20
+
21
+ Run:
22
+
23
+ ```
24
+ rake js:routes
25
+ ```
26
+
27
+ Make routes available globally in `app/javascript/packs/application.js`:
28
+
29
+ ``` javascript
30
+ import * as Routes from 'routes';
31
+ window.Routes = Routes;
32
+ ```
33
+
34
+ Individual routes can be imported using:
35
+
36
+ ``` javascript
37
+ import {edit_post_path} from 'routes';
38
+ console.log(edit_post_path(1))
39
+ ```
40
+
41
+ **Note**: that this setup requires `rake js:routes` to be run each time routes file is updated.
42
+
43
+ <div id='webpacker'></div>
44
+
45
+ #### Webpacker + automatic updates
46
+
47
+
48
+ This setup can automatically update your routes without `rake js:routes` being called manually.
49
+ It requires [rails-erb-loader](https://github.com/usabilityhub/rails-erb-loader) npm package to work.
50
+
51
+ Add `erb` loader to webpacker:
52
+
53
+ ``` sh
54
+ yarn add rails-erb-loader
55
+ rm -f app/javascript/routes.js # delete static file if any
56
+ ```
57
+
58
+ Create webpack ERB config `config/webpack/loaders/erb.js`:
59
+
60
+ ``` javascript
61
+ module.exports = {
62
+ test: /\.js\.erb$/,
63
+ enforce: 'pre',
64
+ exclude: /node_modules/,
65
+ use: [{
66
+ loader: 'rails-erb-loader',
67
+ options: {
68
+ runner: (/^win/.test(process.platform) ? 'ruby ' : '') + 'bin/rails runner'
69
+ }
70
+ }]
71
+ }
72
+ ```
73
+
74
+ Enable `erb` extension in `config/webpack/environment.js`:
16
75
 
17
- Require JsRoutes in `application.js` or other bundle
76
+ ``` javascript
77
+ const erb = require('./loaders/erb')
78
+ environment.loaders.append('erb', erb)
79
+ ```
80
+
81
+ Create routes file `app/javascript/routes.js.erb`:
82
+
83
+ ``` erb
84
+ <%= JsRoutes.generate() %>
85
+ ```
86
+
87
+ Use routes wherever you need them `app/javascript/packs/application.js`:
88
+
89
+ ``` javascript
90
+ import * as Routes from 'routes.js.erb';
91
+ window.Routes = Routes;
92
+ ```
93
+
94
+ #### Sprockets (Deprecated)
95
+
96
+ If you are using [Sprockets](https://github.com/rails/sprockets-rails) you may configure js-routes in the following way.
97
+
98
+ Setup the initializer (e.g. `config/initializers/js_routes.rb`):
99
+
100
+ ``` ruby
101
+ JsRoutes.setup do |config|
102
+ config.module_type = nil
103
+ config.namespace = 'Routes'
104
+ end
105
+ ```
106
+
107
+ Require JsRoutes in `app/assets/javascripts/application.js` or other bundle
18
108
 
19
109
  ``` js
20
110
  //= require js-routes
@@ -32,7 +122,7 @@ This cache is not flushed on server restart in development environment.
32
122
 
33
123
  ### Configuration
34
124
 
35
- You can configure JsRoutes in two main ways. Either with an initializer (e.g. `config/initializers/jsroutes.rb`):
125
+ You can configure JsRoutes in two main ways. Either with an initializer (e.g. `config/initializers/js_routes.rb`):
36
126
 
37
127
  ``` ruby
38
128
  JsRoutes.setup do |config|
@@ -43,6 +133,7 @@ end
43
133
  Or dynamically in JavaScript, although only [Formatter Options](#formatter-options) are supported (see below)
44
134
 
45
135
  ``` js
136
+ import * as Routes from 'routes'
46
137
  Routes.configure({
47
138
  option: value
48
139
  });
@@ -53,8 +144,14 @@ Routes.config(); // current config
53
144
 
54
145
  ##### Generator Options
55
146
 
56
- Options to configure JavaScript file generator:
147
+ Options to configure JavaScript file generator. These options are only available in Ruby context but not JavaScript.
57
148
 
149
+ * `module_type` - JavaScript module type for generated code. [Article](https://dev.to/iggredible/what-the-heck-are-cjs-amd-umd-and-esm-ikm)
150
+ * Options: `ESM`, `UMD`, `CJS`, `AMD`, `nil`.
151
+ * Default: `ESM`
152
+ * `nil` option can be used in case you don't want generated code to export anything.
153
+ * `documentation` - specifies if each route should be annotated with [JSDoc](https://jsdoc.app/) comment
154
+ * Default: `true`
58
155
  * `exclude` - Array of regexps to exclude from routes.
59
156
  * Default: `[]`
60
157
  * 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:
63
160
  * The regexp applies only to the name before the `_path` suffix, eg: you want to match exactly `settings_path`, the regexp should be `/^settings$/`
64
161
  * `namespace` - global object used to access routes.
65
162
  * Supports nested namespace like `MyProject.routes`
66
- * Default: `Routes`
67
- * `camel_case` - Generate camel case route names.
163
+ * Default: `nil`
164
+ * `camel_case` - specifies if route helpers should be generated in camel case instead of underscore case.
68
165
  * Default: `false`
69
- * `url_links` - Generate `*_url` helpers (in addition to the default `*_path` helpers).
70
- * Example: `true`
166
+ * `url_links` - specifies if `*_url` helpers should be generated (in addition to the default `*_path` helpers).
71
167
  * Default: `false`
72
168
  * 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`.
73
169
  * `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:
77
173
  * This option allows to only generate routes for a specific rails engine, that is mounted into routes instead of all Rails app routes
78
174
  * Default: `Rails.application`
79
175
  * `file` - a file location where generated routes are stored
80
- * Default: `app/assets/javascripts/routes.js` if `app/assets/javascripts` directory exists, otherwise `app/javascript/routes.js`.
176
+ * Default: `app/javascript/routes.js` if setup with Webpacker, otherwise `app/assets/javascripts/routes.js` if setup with Sprockets.
81
177
 
82
178
  ##### Formatter Options
83
179
 
84
- Options to configure routes formatting:
180
+ Options to configure routes formatting. These options are available both in Ruby and JavaScript context.
85
181
 
86
182
  * `default_url_options` - default parameters used when generating URLs
87
- * Option is configurable at JS level with `Routes.configure()`
88
183
  * Example: `{format: "json", trailing_slash: true, protocol: "https", subdomain: "api", host: "example.com", port: 3000}`
89
184
  * Default: `{}`
90
- * `prefix` - String representing a url path to prepend to all paths.
91
- * Option is configurable at JS level with `Routes.configure()`
92
- * Example: `http://yourdomain.com`. This will cause route helpers to generate full path only.
185
+ * `prefix` - string that will prepend any generated URL. Usually used when app URL root includes a path component.
186
+ * Example: `/rails-app`
93
187
  * Default: `Rails.application.config.relative_url_root`
94
188
  * `serializer` - a JS function that serializes a Javascript Hash object into URL paramters like `{a: 1, b: 2} => "a=1&b=2"`.
95
189
  * Default: `nil`. Uses built-in serializer compatible with Rails
96
- * Option is configurable at JS level with `Routes.configure()`
97
190
  * Example: `jQuery.param` - use jQuery's serializer algorithm. You can attach serialize function from your favorite AJAX framework.
98
191
  * Example: `function (object) { ... }` - use completely custom serializer of your application.
99
192
  * `special_options_key` - a special key that helps JsRoutes to destinguish serialized model from options hash
100
193
  * This option exists because JS doesn't provide a difference between an object and a hash
101
- * Option is configurable at JS level with `Routes.configure()`
102
194
  * Default: `_options`
103
195
 
104
- ### Very Advanced Setup
196
+ ### Advanced Setup
105
197
 
106
198
  In case you need multiple route files for different parts of your application, you have to create the files manually.
107
199
  If your application has an `admin` and an `application` namespace for example:
108
200
 
201
+ ``` erb
202
+ // app/javascript/admin/routes.js.erb
203
+ <%= JsRoutes.generate(include: /admin/) %>
109
204
  ```
110
- # app/assets/javascripts/admin/routes.js.erb
111
- <%= JsRoutes.generate(namespace: "AdminRoutes", include: /admin/) %>
112
-
113
- # app/assets/javascripts/admin.js.coffee
114
- #= require admin/routes
115
- ```
116
-
117
- ```
118
- # app/assets/javascripts/application/routes.js.erb
119
- <%= JsRoutes.generate(namespace: "AppRoutes", exclude: /admin/) %>
120
205
 
121
- # app/assets/javascripts/application.js.coffee
122
- #= require application/routes
206
+ ``` erb
207
+ // app/javascript/customer/routes.js.erb
208
+ <%= JsRoutes.generate(exclude: /admin/) %>
123
209
  ```
124
210
 
125
- In order to generate the routes JS code to a string:
211
+ You can manipulate the generated helper manually by injecting ruby into javascript:
126
212
 
127
- ```ruby
128
- routes_js = JsRoutes.generate(options)
213
+ ``` erb
214
+ export const routes = <%= JsRoutes.generate(module_type: nil, namespace: nil) %>
129
215
  ```
130
216
 
131
217
  If you want to generate the routes files outside of the asset pipeline, you can use `JsRoutes.generate!`:
132
218
 
133
219
  ``` ruby
134
- path = "app/assets/javascripts"
135
- JsRoutes.generate!("#{path}/app_routes.js", namespace: "AppRoutes", exclude: [/^admin_/, /^api_/])
136
- JsRoutes.generate!("#{path}/adm_routes.js", namespace: "AdmRoutes", include: /^admin_/)
137
- JsRoutes.generate!("#{path}/api_routes.js", namespace: "ApiRoutes", include: /^api_/, default_url_options: {format: "json"})
138
- ```
139
-
140
- ### Rails relative URL root
220
+ path = Rails.root.join("app/javascript")
141
221
 
142
- 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:
222
+ JsRoutes.generate!("#{path}/app_routes.js", exclude: [/^admin_/, /^api_/])
223
+ JsRoutes.generate!("#{path}/adm_routes.js", include: /^admin_/)
224
+ JsRoutes.generate!("#{path}/api_routes.js", include: /^api_/, default_url_options: {format: "json"})
143
225
  ```
144
- RAILS_RELATIVE_URL_ROOT=/Application1 RAILS_ENV=production bundle exec rake assets:precompile
145
- ```
146
- 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.
147
-
148
226
 
149
227
  ## Usage
150
228
 
151
229
  Configuration above will create a nice javascript file with `Routes` object that has all the rails routes available:
152
230
 
153
231
  ``` js
232
+ import * as Routes from 'routes';
233
+
154
234
  Routes.users_path() // => "/users"
155
235
  Routes.user_path(1) // => "/users/1"
156
236
  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
191
271
  '' + Routes.user_path // => "/users/:id(.:format)"
192
272
  ```
193
273
 
194
- Route function also contain inside attribute `required_params` required param names as array:
274
+ Route function also contain method `requiredParams` inside which returns required param names array:
195
275
 
196
276
  ```js
197
- Routes.users_path.required_params // => []
198
- Routes.user_path.required_params // => ['id']
277
+ Routes.users_path.requiredParams() // => []
278
+ Routes.user_path.requiredParams() // => ['id']
199
279
  ```
200
280
 
201
281
 
@@ -216,9 +296,34 @@ Routes.company_project_path({company_id: 1, id: 2, _options: true}) // => "/comp
216
296
 
217
297
  ## What about security?
218
298
 
219
- JsRoutes itself does not have security holes. It makes URLs
220
- without access protection more reachable by potential attacker.
221
- In order to prevent this use `:exclude` option for sensitive urls like `/admin_/`
299
+ JsRoutes itself does not have security holes.
300
+ It makes URLs without access protection more reachable by potential attacker.
301
+ If that is an issue for you, you may use one of the following solutions:
302
+
303
+ ### Explicit Import + ESM Tree shaking
304
+
305
+ Make sure `module_type` is set to `ESM` (the default) and JS files import only required routes into the file like:
306
+
307
+ ``` javascript
308
+ import {
309
+ inbox_path,
310
+ inboxes_path,
311
+ inbox_message_path,
312
+ inbox_attachment_path,
313
+ user_path,
314
+ } from 'routes.js.erb'
315
+ ```
316
+
317
+ ### Exclude option
318
+
319
+ Split your routes into multiple files related to each section of your website like:
320
+
321
+ ``` javascript
322
+ // admin-routes.js.erb
323
+ <%= JsRoutes.generate(include: /^admin_/)
324
+ // app-routes.js.erb
325
+ <%= JsRoutes.generate(exclude: /^admin_/)
326
+ ```
222
327
 
223
328
  ## JsRoutes and Heroku
224
329
 
@@ -238,11 +343,20 @@ There are some alternatives available. Most of them has only basic feature and d
238
343
  Advantages of this one are:
239
344
 
240
345
  * Rails 4,5,6 support
346
+ * [ESM Tree shaking](https://webpack.js.org/guides/tree-shaking/) support
241
347
  * Rich options set
242
348
  * Full rails compatibility
243
349
  * Support Rails `#to_param` convention for seo optimized paths
244
350
  * Well tested
245
351
 
352
+ ## Version 2 TODO
353
+
354
+ * Add routes generation .d.ts file
355
+ * Add config option on the output format: js, ts, d.ts
356
+ * Add prettier
357
+ * Add eslint
358
+ * Add development guide
359
+
246
360
  #### Thanks to [contributors](https://github.com/railsware/js-routes/contributors)
247
361
 
248
362
  #### Have fun
@@ -0,0 +1,61 @@
1
+ ## Version 2.0 upgrade notes
2
+
3
+ ### Using ESM module by default
4
+
5
+ The default setting are now changed:
6
+
7
+ Setting | Old | New
8
+ --- | --- | ---
9
+ module\_type | nil | ESM
10
+ namespace | Routes | nil
11
+
12
+ This is more optimized setup for WebPacker. You can restore the old configuration like this:
13
+
14
+ ``` ruby
15
+ JsRoutes.setup do |config|
16
+ config.module_type = nil
17
+ config.namespace = 'Routes'
18
+ end
19
+ ```
20
+
21
+ However, [ESM+Webpacker](/Readme.md#webpacker) upgrade is recommended.
22
+
23
+ ### `required_params` renamed
24
+
25
+ In case you are using `required_params` property, it is now renamed and converted to a method:
26
+
27
+ ``` javascript
28
+ // Old style
29
+ Routes.post_path.required_params // => ['id']
30
+ // New style
31
+ Routes.post_path.requiredParams() // => ['id']
32
+ ```
33
+
34
+ ### ParameterMissing error rework
35
+
36
+ `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.
37
+
38
+ ``` javascript
39
+ try {
40
+ return Routes.inbox_path();
41
+ } catch(error) {
42
+ if (error.name === 'ParametersMissing') {
43
+ console.warn(`Missing route keys ${error.keys.join(', ')}. Ignoring.`);
44
+ return "#";
45
+ } else {
46
+ throw error;
47
+ }
48
+ }
49
+ ```
50
+
51
+ ### JSDoc comment format
52
+
53
+ New version of js-routes generates function comment in the [JSDoc](https://jsdoc.app) format.
54
+ If you have any problems with that disable the annotation:
55
+
56
+ ``` ruby
57
+ JsRoutes.setup do |config|
58
+ config.documentation = false
59
+ end
60
+ ```
61
+