js-routes 1.4.1 → 2.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- checksums.yaml +5 -5
- data/.eslintrc.js +15 -0
- data/.gitignore +5 -0
- data/.nvmrc +1 -0
- data/.travis.yml +37 -30
- data/Appraisals +16 -13
- data/CHANGELOG.md +95 -0
- data/Rakefile +6 -2
- data/Readme.md +220 -88
- data/VERSION_2_UPGRADE.md +66 -0
- data/app/assets/javascripts/js-routes.js.erb +1 -1
- data/gemfiles/{rails40.gemfile → rails40_sprockets_2.gemfile} +1 -1
- data/gemfiles/{rails40_sprockets3.gemfile → rails40_sprockets_3.gemfile} +0 -0
- data/gemfiles/{rails41.gemfile → rails41_sprockets_2.gemfile} +1 -1
- data/gemfiles/{rails41_sprockets3.gemfile → rails41_sprockets_3.gemfile} +0 -0
- data/gemfiles/{rails32.gemfile → rails42_sprockets_2.gemfile} +2 -2
- data/gemfiles/{rails42_sprockets3.gemfile → rails42_sprockets_3.gemfile} +1 -1
- data/gemfiles/{rails50_sprockets3.gemfile → rails50_sprockets_3.gemfile} +1 -1
- data/gemfiles/rails51_sprockets_3.gemfile +8 -0
- data/gemfiles/rails52_sprockets_3.gemfile +8 -0
- data/js-routes.gemspec +9 -6
- data/lib/js_routes/engine.rb +6 -18
- data/lib/js_routes/version.rb +1 -1
- data/lib/js_routes.rb +329 -171
- data/lib/routes.d.ts +79 -0
- data/lib/routes.js +499 -485
- data/lib/routes.ts +732 -0
- data/lib/tasks/js_routes.rake +8 -2
- data/package.json +37 -0
- data/spec/dummy/app/assets/config/manifest.js +2 -0
- data/spec/js_routes/default_serializer_spec.rb +19 -3
- data/spec/js_routes/{amd_compatibility_spec.rb → module_types/amd_spec.rb} +1 -9
- data/spec/js_routes/module_types/cjs_spec.rb +15 -0
- data/spec/js_routes/module_types/dts/routes.spec.d.ts +114 -0
- data/spec/js_routes/module_types/dts/test.spec.ts +56 -0
- data/spec/js_routes/module_types/dts_spec.rb +111 -0
- data/spec/js_routes/module_types/esm_spec.rb +45 -0
- data/spec/js_routes/{generated_javascript_spec.rb → module_types/umd_spec.rb} +33 -27
- data/spec/js_routes/options_spec.rb +92 -50
- data/spec/js_routes/rails_routes_compatibility_spec.rb +107 -45
- data/spec/js_routes/zzz_last_post_rails_init_spec.rb +19 -8
- data/spec/spec_helper.rb +45 -42
- data/spec/support/routes.rb +19 -14
- data/spec/tsconfig.json +4 -0
- data/tsconfig.json +28 -0
- data/yarn.lock +2145 -0
- metadata +47 -34
- data/gemfiles/rails42.gemfile +0 -8
- data/gemfiles/rails50.gemfile +0 -8
- data/lib/routes.js.coffee +0 -386
    
        data/Readme.md
    CHANGED
    
    | @@ -1,8 +1,11 @@ | |
| 1 1 | 
             
            # JsRoutes
         | 
| 2 2 | 
             
            [](https://travis-ci.org/railsware/js-routes)
         | 
| 3 | 
            +
            [](https://app.fossa.io/projects/git%2Bgithub.com%2Frailsware%2Fjs-routes?ref=badge_shield)
         | 
| 3 4 |  | 
| 4 5 | 
             
            Generates javascript file that defines all Rails named routes as javascript helpers
         | 
| 5 6 |  | 
| 7 | 
            +
            [UPGRADE TO 2.0](./VERSION_2_UPGRADE.md)
         | 
| 8 | 
            +
             | 
| 6 9 | 
             
            ## Intallation
         | 
| 7 10 |  | 
| 8 11 | 
             
            Your Rails Gemfile:
         | 
| @@ -11,9 +14,117 @@ Your Rails Gemfile: | |
| 11 14 | 
             
            gem "js-routes"
         | 
| 12 15 | 
             
            ```
         | 
| 13 16 |  | 
| 14 | 
            -
             | 
| 17 | 
            +
            ## Setup
         | 
| 18 | 
            +
             | 
| 19 | 
            +
            ### Quick Start 
         | 
| 20 | 
            +
             | 
| 21 | 
            +
            Run:
         | 
| 22 | 
            +
             | 
| 23 | 
            +
            ``` sh
         | 
| 24 | 
            +
            rake js:routes 
         | 
| 25 | 
            +
            # OR for typescript support
         | 
| 26 | 
            +
            rake js:routes:typescript
         | 
| 27 | 
            +
            ```
         | 
| 28 | 
            +
             | 
| 29 | 
            +
             | 
| 30 | 
            +
            Individual routes can be imported using:
         | 
| 31 | 
            +
             | 
| 32 | 
            +
            ``` javascript
         | 
| 33 | 
            +
            import {edit_post_path, posts_path} from 'routes';
         | 
| 34 | 
            +
            console.log(posts_path({format: 'json'})) // => "/posts.json"
         | 
| 35 | 
            +
            console.log(edit_post_path(1)) // => "/posts/1/edit"
         | 
| 36 | 
            +
            ```
         | 
| 37 | 
            +
             | 
| 38 | 
            +
            Make routes available globally in `app/javascript/packs/application.js`: 
         | 
| 39 | 
            +
             | 
| 40 | 
            +
            ``` javascript
         | 
| 41 | 
            +
            import * as Routes from 'routes';
         | 
| 42 | 
            +
            window.Routes = Routes;
         | 
| 43 | 
            +
            ```
         | 
| 44 | 
            +
             | 
| 45 | 
            +
            **Note**: that this setup requires `rake js:routes` to be run each time routes file is updated.
         | 
| 46 | 
            +
             | 
| 47 | 
            +
            <div id='webpacker'></div>
         | 
| 48 | 
            +
             | 
| 49 | 
            +
            #### Webpacker + automatic updates
         | 
| 50 | 
            +
             | 
| 51 | 
            +
             | 
| 52 | 
            +
            This setup can automatically update your routes without `rake js:routes` being called manually.
         | 
| 53 | 
            +
            It requires [rails-erb-loader](https://github.com/usabilityhub/rails-erb-loader) npm package to work.
         | 
| 54 | 
            +
             | 
| 55 | 
            +
            Add `erb` loader to webpacker:
         | 
| 56 | 
            +
             | 
| 57 | 
            +
            ``` sh
         | 
| 58 | 
            +
            yarn add rails-erb-loader
         | 
| 59 | 
            +
            rm -f app/javascript/routes.js # delete static file if any
         | 
| 60 | 
            +
            ```
         | 
| 61 | 
            +
             | 
| 62 | 
            +
            Create webpack ERB config `config/webpack/loaders/erb.js`:
         | 
| 63 | 
            +
             | 
| 64 | 
            +
            ``` javascript
         | 
| 65 | 
            +
            module.exports = {
         | 
| 66 | 
            +
              test: /\.js\.erb$/,
         | 
| 67 | 
            +
              enforce: 'pre',
         | 
| 68 | 
            +
              exclude: /node_modules/,
         | 
| 69 | 
            +
              use: [{
         | 
| 70 | 
            +
                loader: 'rails-erb-loader',
         | 
| 71 | 
            +
                options: {
         | 
| 72 | 
            +
                  runner: (/^win/.test(process.platform) ? 'ruby ' : '') + 'bin/rails runner'
         | 
| 73 | 
            +
                }
         | 
| 74 | 
            +
              }]
         | 
| 75 | 
            +
            }
         | 
| 76 | 
            +
            ```
         | 
| 77 | 
            +
             | 
| 78 | 
            +
            Enable `erb` extension in `config/webpack/environment.js`:
         | 
| 79 | 
            +
             | 
| 80 | 
            +
            ``` javascript
         | 
| 81 | 
            +
            const erb = require('./loaders/erb')
         | 
| 82 | 
            +
            environment.loaders.append('erb', erb)
         | 
| 83 | 
            +
            ```
         | 
| 84 | 
            +
             | 
| 85 | 
            +
            Create routes file `app/javascript/routes.js.erb`:
         | 
| 86 | 
            +
             | 
| 87 | 
            +
            ``` erb
         | 
| 88 | 
            +
            <%= JsRoutes.generate() %>
         | 
| 89 | 
            +
            ```
         | 
| 90 | 
            +
             | 
| 91 | 
            +
            Use routes wherever you need them `app/javascript/packs/application.js`: 
         | 
| 92 | 
            +
             | 
| 93 | 
            +
            ``` javascript
         | 
| 94 | 
            +
            import * as Routes from 'routes.js.erb';
         | 
| 95 | 
            +
            window.Routes = Routes;
         | 
| 96 | 
            +
            ```
         | 
| 97 | 
            +
             | 
| 98 | 
            +
            <div id='definitions'></div>
         | 
| 99 | 
            +
             | 
| 100 | 
            +
            #### Typescript Definitions
         | 
| 101 | 
            +
             | 
| 102 | 
            +
            JsRoutes has typescript support out of the box. In order to generate typscript definitions file (aka `routes.d.ts`) you can call:
         | 
| 103 | 
            +
             | 
| 104 | 
            +
            ``` ruby
         | 
| 105 | 
            +
            JsRoutes.definitions!
         | 
| 106 | 
            +
            ```
         | 
| 107 | 
            +
             | 
| 108 | 
            +
            Or create an automatic updates file at `app/javascript/routes.d.ts.erb`:
         | 
| 109 | 
            +
             | 
| 110 | 
            +
            ``` erb
         | 
| 111 | 
            +
            <%= JsRoutes.defintions %>
         | 
| 112 | 
            +
            ```
         | 
| 15 113 |  | 
| 16 | 
            -
             | 
| 114 | 
            +
            #### Sprockets (Deprecated)
         | 
| 115 | 
            +
             | 
| 116 | 
            +
            If you are using [Sprockets](https://github.com/rails/sprockets-rails) you may configure js-routes in the following way.
         | 
| 117 | 
            +
             | 
| 118 | 
            +
            Setup the initializer (e.g. `config/initializers/js_routes.rb`):
         | 
| 119 | 
            +
             | 
| 120 | 
            +
            ``` ruby
         | 
| 121 | 
            +
            JsRoutes.setup do |config|
         | 
| 122 | 
            +
              config.module_type = nil
         | 
| 123 | 
            +
              config.namespace = 'Routes'
         | 
| 124 | 
            +
            end
         | 
| 125 | 
            +
            ```
         | 
| 126 | 
            +
             | 
| 127 | 
            +
            Require JsRoutes in `app/assets/javascripts/application.js` or other bundle
         | 
| 17 128 |  | 
| 18 129 | 
             
            ``` js
         | 
| 19 130 | 
             
            //= require js-routes
         | 
| @@ -29,9 +140,9 @@ This cache is not flushed on server restart in development environment. | |
| 29 140 |  | 
| 30 141 | 
             
            **Important:** If routes.js file is not updated after some configuration change you need to run this rake task again.
         | 
| 31 142 |  | 
| 32 | 
            -
            ###  | 
| 143 | 
            +
            ### Configuration
         | 
| 33 144 |  | 
| 34 | 
            -
             | 
| 145 | 
            +
            You can configure JsRoutes in two main ways. Either with an initializer (e.g. `config/initializers/js_routes.rb`):
         | 
| 35 146 |  | 
| 36 147 | 
             
            ``` ruby
         | 
| 37 148 | 
             
            JsRoutes.setup do |config|
         | 
| @@ -39,107 +150,108 @@ JsRoutes.setup do |config| | |
| 39 150 | 
             
            end
         | 
| 40 151 | 
             
            ```
         | 
| 41 152 |  | 
| 42 | 
            -
            Or  | 
| 153 | 
            +
            Or dynamically in JavaScript, although only [Formatter Options](#formatter-options) are supported (see below)
         | 
| 43 154 |  | 
| 44 155 | 
             
            ``` js
         | 
| 156 | 
            +
            import * as Routes from 'routes'
         | 
| 45 157 | 
             
            Routes.configure({
         | 
| 46 158 | 
             
              option: value
         | 
| 47 159 | 
             
            });
         | 
| 48 160 | 
             
            Routes.config(); // current config
         | 
| 49 161 | 
             
            ```
         | 
| 50 162 |  | 
| 51 | 
            -
            Available  | 
| 163 | 
            +
            #### Available Options
         | 
| 52 164 |  | 
| 53 | 
            -
             | 
| 54 | 
            -
             | 
| 55 | 
            -
             | 
| 56 | 
            -
             | 
| 57 | 
            -
            * ` | 
| 58 | 
            -
              *  | 
| 165 | 
            +
            ##### Generator Options
         | 
| 166 | 
            +
             | 
| 167 | 
            +
            Options to configure JavaScript file generator. These options are only available in Ruby context but not JavaScript.
         | 
| 168 | 
            +
             | 
| 169 | 
            +
            * `module_type` - JavaScript module type for generated code. [Article](https://dev.to/iggredible/what-the-heck-are-cjs-amd-umd-and-esm-ikm)
         | 
| 170 | 
            +
              * Options: `ESM`, `UMD`, `CJS`, `AMD`, `DTS`, `nil`.
         | 
| 171 | 
            +
              * Default: `ESM`
         | 
| 172 | 
            +
              * `nil` option can be used in case you don't want generated code to export anything.
         | 
| 173 | 
            +
            * `documentation` - specifies if each route should be annotated with [JSDoc](https://jsdoc.app/) comment
         | 
| 174 | 
            +
              * Default: `true`
         | 
| 175 | 
            +
            * `exclude` - Array of regexps to exclude from routes.
         | 
| 176 | 
            +
              * Default: `[]`
         | 
| 59 177 | 
             
              * The regexp applies only to the name before the `_path` suffix, eg: you want to match exactly `settings_path`, the regexp should be `/^settings$/`
         | 
| 60 | 
            -
            * `include` - Array of regexps to include in  | 
| 61 | 
            -
              * Default: []
         | 
| 178 | 
            +
            * `include` - Array of regexps to include in routes.
         | 
| 179 | 
            +
              * Default: `[]`
         | 
| 62 180 | 
             
              * 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 181 | 
             
            * `namespace` - global object used to access routes.
         | 
| 182 | 
            +
              * Only available if `module_type` option is set to `nil`.
         | 
| 64 183 | 
             
              * Supports nested namespace like `MyProject.routes`
         | 
| 65 | 
            -
              * Default: ` | 
| 66 | 
            -
            * ` | 
| 67 | 
            -
              *  | 
| 68 | 
            -
             | 
| 69 | 
            -
              * Default: ` | 
| 70 | 
            -
            * `camel_case` (version >= 0.8.8) - Generate camel case route names.
         | 
| 71 | 
            -
              * Default: false
         | 
| 72 | 
            -
            * `url_links` (version >= 0.8.9) - Generate `*_url` helpers (in addition to the default `*_path` helpers).
         | 
| 73 | 
            -
              * Example: true
         | 
| 74 | 
            -
              * Default: false
         | 
| 184 | 
            +
              * Default: `nil`
         | 
| 185 | 
            +
            * `camel_case` - specifies if route helpers should be generated in camel case instead of underscore case.
         | 
| 186 | 
            +
              * Default: `false`
         | 
| 187 | 
            +
            * `url_links` - specifies if `*_url` helpers should be generated (in addition to the default `*_path` helpers).
         | 
| 188 | 
            +
              * Default: `false`
         | 
| 75 189 | 
             
              * 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`.
         | 
| 76 | 
            -
            * `compact`  | 
| 77 | 
            -
              * Default: false
         | 
| 190 | 
            +
            * `compact` - Remove `_path` suffix in path routes(`*_url` routes stay untouched if they were enabled)
         | 
| 191 | 
            +
              * Default: `false`
         | 
| 78 192 | 
             
              * Sample route call when option is set to true: Routes.users() => `/users`
         | 
| 79 | 
            -
            * `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"`.
         | 
| 80 | 
            -
              * Default: `nil`. Uses built-in serializer
         | 
| 81 | 
            -
              * Option is configurable at JS level with `Routes.configure()`
         | 
| 82 | 
            -
              * Example: `jQuery.param` - use jQuery's serializer algorithm. You can attach serialize function from your favorite AJAX framework.
         | 
| 83 | 
            -
              * Example: `MyApp.custom_serialize` - use completely custom serializer of your application.
         | 
| 84 | 
            -
             | 
| 85 | 
            -
            * `special_options_key` - a special key that helps js-routes to destinguish serialized model from options hash
         | 
| 86 | 
            -
              * This option is required because JS doesn't provide a difference between an object and a hash
         | 
| 87 | 
            -
              * Option is configurable at JS level with `Routes.configure()`
         | 
| 88 | 
            -
              * Default: `_options`
         | 
| 89 193 | 
             
            * `application` - a key to specify which rails engine you want to generate routes too.
         | 
| 90 194 | 
             
              * This option allows to only generate routes for a specific rails engine, that is mounted into routes instead of all Rails app routes
         | 
| 91 195 | 
             
              * Default: `Rails.application`
         | 
| 196 | 
            +
            * `file` - a file location where generated routes are stored
         | 
| 197 | 
            +
              * Default: `app/javascript/routes.js` if setup with Webpacker, otherwise `app/assets/javascripts/routes.js` if setup with Sprockets.
         | 
| 92 198 |  | 
| 93 | 
            -
             | 
| 199 | 
            +
            ##### Formatter Options
         | 
| 94 200 |  | 
| 95 | 
            -
             | 
| 96 | 
            -
            If your application has an `admin` and an `application` namespace for example:
         | 
| 201 | 
            +
            Options to configure routes formatting. These options are available both in Ruby and JavaScript context.
         | 
| 97 202 |  | 
| 98 | 
            -
             | 
| 99 | 
            -
             | 
| 100 | 
            -
             | 
| 203 | 
            +
            * `default_url_options` - default parameters used when generating URLs
         | 
| 204 | 
            +
              * Example: `{format: "json", trailing_slash: true, protocol: "https", subdomain: "api", host: "example.com", port: 3000}`
         | 
| 205 | 
            +
              * Default: `{}`
         | 
| 206 | 
            +
            * `prefix` - string that will prepend any generated URL. Usually used when app URL root includes a path component.
         | 
| 207 | 
            +
              * Example: `/rails-app`
         | 
| 208 | 
            +
              * Default: `Rails.application.config.relative_url_root`
         | 
| 209 | 
            +
            * `serializer` - a JS function that serializes a Javascript Hash object into URL paramters like `{a: 1, b: 2} => "a=1&b=2"`.
         | 
| 210 | 
            +
              * Default: `nil`. Uses built-in serializer compatible with Rails
         | 
| 211 | 
            +
              * Example: `jQuery.param` - use jQuery's serializer algorithm. You can attach serialize function from your favorite AJAX framework.
         | 
| 212 | 
            +
              * Example: `function (object) { ... }` - use completely custom serializer of your application.
         | 
| 213 | 
            +
            * `special_options_key` - a special key that helps JsRoutes to destinguish serialized model from options hash
         | 
| 214 | 
            +
              * This option exists because JS doesn't provide a difference between an object and a hash
         | 
| 215 | 
            +
              * Default: `_options`
         | 
| 101 216 |  | 
| 102 | 
            -
             | 
| 103 | 
            -
             | 
| 104 | 
            -
             | 
| 217 | 
            +
            ### Advanced Setup
         | 
| 218 | 
            +
             | 
| 219 | 
            +
            In case you need multiple route files for different parts of your application, you have to create the files manually.
         | 
| 220 | 
            +
            If your application has an `admin` and an `application` namespace for example:
         | 
| 105 221 |  | 
| 222 | 
            +
            ``` erb
         | 
| 223 | 
            +
            // app/javascript/admin/routes.js.erb
         | 
| 224 | 
            +
            <%= JsRoutes.generate(include: /admin/) %>
         | 
| 106 225 | 
             
            ```
         | 
| 107 | 
            -
            # app/assets/javascripts/application/routes.js.erb
         | 
| 108 | 
            -
            <%= JsRoutes.generate(namespace: "AppRoutes", exclude: /admin/) %>
         | 
| 109 226 |  | 
| 110 | 
            -
             | 
| 111 | 
            -
             | 
| 227 | 
            +
            ``` erb
         | 
| 228 | 
            +
            // app/javascript/customer/routes.js.erb
         | 
| 229 | 
            +
            <%= JsRoutes.generate(exclude: /admin/) %>
         | 
| 112 230 | 
             
            ```
         | 
| 113 231 |  | 
| 114 | 
            -
             | 
| 232 | 
            +
            You can manipulate the generated helper manually by injecting ruby into javascript:
         | 
| 115 233 |  | 
| 116 | 
            -
            ``` | 
| 117 | 
            -
             | 
| 234 | 
            +
            ``` erb
         | 
| 235 | 
            +
            export const routes = <%= JsRoutes.generate(module_type: nil, namespace: nil) %>
         | 
| 118 236 | 
             
            ```
         | 
| 119 237 |  | 
| 120 238 | 
             
            If you want to generate the routes files outside of the asset pipeline, you can use `JsRoutes.generate!`:
         | 
| 121 239 |  | 
| 122 240 | 
             
            ``` ruby
         | 
| 123 | 
            -
            path = "app/ | 
| 124 | 
            -
            JsRoutes.generate!("#{path}/app_routes.js", :namespace => "AppRoutes", :exclude => [/^admin_/, /^api_/])
         | 
| 125 | 
            -
            JsRoutes.generate!("#{path}/adm_routes.js", :namespace => "AdmRoutes", :include => /^admin_/)
         | 
| 126 | 
            -
            JsRoutes.generate!("#{path}/api_routes.js", :namespace => "ApiRoutes", :include => /^api_/, :default_url_options => {:format => "json"})
         | 
| 127 | 
            -
            ```
         | 
| 128 | 
            -
             | 
| 129 | 
            -
            ### Rails relative URL root
         | 
| 241 | 
            +
            path = Rails.root.join("app/javascript")
         | 
| 130 242 |  | 
| 131 | 
            -
             | 
| 243 | 
            +
            JsRoutes.generate!("#{path}/app_routes.js", exclude: [/^admin_/, /^api_/])
         | 
| 244 | 
            +
            JsRoutes.generate!("#{path}/adm_routes.js", include: /^admin_/)
         | 
| 245 | 
            +
            JsRoutes.generate!("#{path}/api_routes.js", include: /^api_/, default_url_options: {format: "json"})
         | 
| 132 246 | 
             
            ```
         | 
| 133 | 
            -
            RAILS_RELATIVE_URL_ROOT=/Application1 RAILS_ENV=production bundle exec rake assets:precompile
         | 
| 134 | 
            -
            ```
         | 
| 135 | 
            -
            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.
         | 
| 136 | 
            -
             | 
| 137 247 |  | 
| 138 248 | 
             
            ## Usage
         | 
| 139 249 |  | 
| 140 250 | 
             
            Configuration above will create a nice javascript file with `Routes` object that has all the rails routes available:
         | 
| 141 251 |  | 
| 142 252 | 
             
            ``` js
         | 
| 253 | 
            +
            import * as Routes from 'routes';
         | 
| 254 | 
            +
             | 
| 143 255 | 
             
            Routes.users_path() // => "/users"
         | 
| 144 256 | 
             
            Routes.user_path(1) // => "/users/1"
         | 
| 145 257 | 
             
            Routes.user_path(1, {format: 'json'}) // => "/users/1.json"
         | 
| @@ -180,67 +292,87 @@ This function allow to get the same `spec` for route, if you will get string rep | |
| 180 292 | 
             
            '' + Routes.user_path // => "/users/:id(.:format)"
         | 
| 181 293 | 
             
            ```
         | 
| 182 294 |  | 
| 183 | 
            -
            Route function also contain  | 
| 295 | 
            +
            Route function also contain method `requiredParams` inside which returns required param names array:
         | 
| 184 296 |  | 
| 185 297 | 
             
            ```js
         | 
| 186 | 
            -
            Routes.users_path. | 
| 187 | 
            -
            Routes.user_path. | 
| 298 | 
            +
            Routes.users_path.requiredParams() // => []
         | 
| 299 | 
            +
            Routes.user_path.requiredParams() // => ['id']
         | 
| 188 300 | 
             
            ```
         | 
| 189 301 |  | 
| 190 302 |  | 
| 191 | 
            -
            ## Rails  | 
| 303 | 
            +
            ## Rails Compatibility
         | 
| 192 304 |  | 
| 193 | 
            -
            JsRoutes  | 
| 194 | 
            -
            Please make and issue in case of any incomtibilities found outside of described below.
         | 
| 305 | 
            +
            JsRoutes tries to replicate the Rails routing API as closely as possible. If you find any incompatibilities (outside of what is described below), please [open an issue](https://github.com/railsware/js-routes/issues/new).
         | 
| 195 306 |  | 
| 196 307 | 
             
            ### Object and Hash distinction issue
         | 
| 197 308 |  | 
| 198 | 
            -
            Sometimes the destinction between JS Hash and Object can not be found by  | 
| 309 | 
            +
            Sometimes the destinction between JS Hash and Object can not be found by JsRoutes.
         | 
| 199 310 | 
             
            In this case you would need to pass a special key to help:
         | 
| 200 311 |  | 
| 201 312 | 
             
            ``` js
         | 
| 202 | 
            -
            Routes.company_project_path({company_id: 1, id: 2}) // => Not  | 
| 313 | 
            +
            Routes.company_project_path({company_id: 1, id: 2}) // => Not enough parameters
         | 
| 203 314 | 
             
            Routes.company_project_path({company_id: 1, id: 2, _options: true}) // => "/companies/1/projects/2"
         | 
| 204 315 | 
             
            ```
         | 
| 205 316 |  | 
| 206 317 |  | 
| 207 318 | 
             
            ## What about security?
         | 
| 208 319 |  | 
| 209 | 
            -
             | 
| 210 | 
            -
            without access protection more reachable by potential attacker.
         | 
| 211 | 
            -
             | 
| 320 | 
            +
            JsRoutes itself does not have security holes. 
         | 
| 321 | 
            +
            It makes URLs without access protection more reachable by potential attacker.
         | 
| 322 | 
            +
            If that is an issue for you, you may use one of the following solutions:
         | 
| 212 323 |  | 
| 213 | 
            -
             | 
| 324 | 
            +
            ### Explicit Import + ESM Tree shaking
         | 
| 214 325 |  | 
| 215 | 
            -
             | 
| 326 | 
            +
            Make sure `module_type` is set to `ESM` (the default) and JS files import only required routes into the file like:
         | 
| 216 327 |  | 
| 217 | 
            -
            ```  | 
| 218 | 
            -
             | 
| 328 | 
            +
            ``` javascript
         | 
| 329 | 
            +
            import {
         | 
| 330 | 
            +
              inbox_path,
         | 
| 331 | 
            +
              inboxes_path,
         | 
| 332 | 
            +
              inbox_message_path,
         | 
| 333 | 
            +
              inbox_attachment_path,
         | 
| 334 | 
            +
              user_path,
         | 
| 335 | 
            +
            } from 'routes.js.erb'
         | 
| 219 336 | 
             
            ```
         | 
| 220 337 |  | 
| 221 | 
            -
             | 
| 338 | 
            +
            Such import structure allows for moddern JS bundlers like [Webpack](https://webpack.js.org/) to only include explicitly imported routes into JS bundle file.
         | 
| 339 | 
            +
            See [Tree Shaking](https://webpack.js.org/guides/tree-shaking/) for more information.
         | 
| 222 340 |  | 
| 223 | 
            -
             | 
| 341 | 
            +
            ### Exclude option
         | 
| 224 342 |  | 
| 225 | 
            -
             | 
| 343 | 
            +
            Split your routes into multiple files related to each section of your website like:
         | 
| 226 344 |  | 
| 227 | 
            -
            ```  | 
| 228 | 
            -
             | 
| 345 | 
            +
            ``` javascript
         | 
| 346 | 
            +
            // admin-routes.js.erb
         | 
| 347 | 
            +
            <%= JsRoutes.generate(include: /^admin_/) %>
         | 
| 348 | 
            +
            // app-routes.js.erb
         | 
| 349 | 
            +
            <%= JsRoutes.generate(exclude: /^admin_/) %>
         | 
| 229 350 | 
             
            ```
         | 
| 230 351 |  | 
| 231 | 
            -
            This should just work.
         | 
| 232 | 
            -
             | 
| 233 352 | 
             
            ## Advantages over alternatives
         | 
| 234 353 |  | 
| 235 354 | 
             
            There are some alternatives available. Most of them has only basic feature and don't reach the level of quality I accept.
         | 
| 236 355 | 
             
            Advantages of this one are:
         | 
| 237 356 |  | 
| 238 | 
            -
            * Rails  | 
| 357 | 
            +
            * Rails 4,5,6 support
         | 
| 358 | 
            +
            * [ESM Tree shaking](https://webpack.js.org/guides/tree-shaking/) support
         | 
| 239 359 | 
             
            * Rich options set
         | 
| 240 360 | 
             
            * Full rails compatibility
         | 
| 241 361 | 
             
            * Support Rails `#to_param` convention for seo optimized paths
         | 
| 242 362 | 
             
            * Well tested
         | 
| 243 363 |  | 
| 244 | 
            -
             | 
| 364 | 
            +
            ## Version 2 TODO
         | 
| 365 | 
            +
             | 
| 366 | 
            +
            * Add routes generation .d.ts file
         | 
| 367 | 
            +
            * Add config option on the output format: js, ts, d.ts
         | 
| 368 | 
            +
            * Add prettier
         | 
| 369 | 
            +
            * Add eslint
         | 
| 370 | 
            +
            * Add development guide
         | 
| 371 | 
            +
             | 
| 372 | 
            +
            #### Thanks to [contributors](https://github.com/railsware/js-routes/contributors)
         | 
| 245 373 |  | 
| 246 374 | 
             
            #### Have fun
         | 
| 375 | 
            +
             | 
| 376 | 
            +
             | 
| 377 | 
            +
            ## License
         | 
| 378 | 
            +
            [](https://app.fossa.io/projects/git%2Bgithub.com%2Frailsware%2Fjs-routes?ref=badge_large)
         | 
| @@ -0,0 +1,66 @@ | |
| 1 | 
            +
            ## Version 2.0 upgrade notes
         | 
| 2 | 
            +
             | 
| 3 | 
            +
            ### Using ESM module by default
         | 
| 4 | 
            +
             | 
| 5 | 
            +
            New version of JsRoutes doesn't try to guess your javascript environment module system because JS has generated a ton of legacy module systems in the past. 
         | 
| 6 | 
            +
            [ESM+Webpacker](/Readme.md#webpacker) upgrade is recommended. 
         | 
| 7 | 
            +
             | 
| 8 | 
            +
            However, if you don't want to follow that pass, specify `module_type` configuration option instead based on module system available in your JS environment.
         | 
| 9 | 
            +
            Here are supported values:
         | 
| 10 | 
            +
             | 
| 11 | 
            +
            * CJS
         | 
| 12 | 
            +
            * UMD
         | 
| 13 | 
            +
            * AMD
         | 
| 14 | 
            +
            * ESM
         | 
| 15 | 
            +
            * nil
         | 
| 16 | 
            +
             | 
| 17 | 
            +
            [Explaination Article](https://dev.to/iggredible/what-the-heck-are-cjs-amd-umd-and-esm-ikm)
         | 
| 18 | 
            +
             | 
| 19 | 
            +
            If you don't want to use any JS module system and make routes available via a **global variable**, specify `nil` as a `module_type` and use `namespace` option:
         | 
| 20 | 
            +
             | 
| 21 | 
            +
            ``` ruby
         | 
| 22 | 
            +
            JsRoutes.setup do |config|
         | 
| 23 | 
            +
              config.module_type = nil
         | 
| 24 | 
            +
              config.namespace = "Routes"
         | 
| 25 | 
            +
            end
         | 
| 26 | 
            +
            ```
         | 
| 27 | 
            +
             | 
| 28 | 
            +
            ### JSDoc comment
         | 
| 29 | 
            +
             | 
| 30 | 
            +
            New version of js-routes generates function comment in the [JSDoc](https://jsdoc.app) format.
         | 
| 31 | 
            +
            If you have any problems with that, you can disable it like this:
         | 
| 32 | 
            +
             | 
| 33 | 
            +
             | 
| 34 | 
            +
            ``` ruby
         | 
| 35 | 
            +
            JsRoutes.setup do |config|
         | 
| 36 | 
            +
              config.documentation = false
         | 
| 37 | 
            +
            end
         | 
| 38 | 
            +
            ```
         | 
| 39 | 
            +
             | 
| 40 | 
            +
            ### `required_params` renamed
         | 
| 41 | 
            +
             | 
| 42 | 
            +
            In case you are using `required_params` property, it is now renamed and converted to a method:
         | 
| 43 | 
            +
             | 
| 44 | 
            +
            ``` javascript
         | 
| 45 | 
            +
            // Old style
         | 
| 46 | 
            +
            Routes.post_path.required_params  // => ['id']
         | 
| 47 | 
            +
            // New style
         | 
| 48 | 
            +
            Routes.post_path.requiredParams() // => ['id']
         | 
| 49 | 
            +
            ```
         | 
| 50 | 
            +
             | 
| 51 | 
            +
            ### ParameterMissing error rework
         | 
| 52 | 
            +
             | 
| 53 | 
            +
            `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.
         | 
| 54 | 
            +
             | 
| 55 | 
            +
            ``` javascript
         | 
| 56 | 
            +
            try {
         | 
| 57 | 
            +
              return Routes.inbox_path();
         | 
| 58 | 
            +
            } catch(error) {
         | 
| 59 | 
            +
              if (error.name === 'ParametersMissing') {
         | 
| 60 | 
            +
                console.warn(`Missing route keys ${error.keys.join(', ')}. Ignoring.`);
         | 
| 61 | 
            +
                return "#";
         | 
| 62 | 
            +
              } else {
         | 
| 63 | 
            +
                throw error;
         | 
| 64 | 
            +
              }
         | 
| 65 | 
            +
            }
         | 
| 66 | 
            +
            ```
         | 
| @@ -1,2 +1,2 @@ | |
| 1 1 | 
             
            <%# encoding: UTF-8 %>
         | 
| 2 | 
            -
            <%= JsRoutes. | 
| 2 | 
            +
            <%= JsRoutes.generate %>
         | 
| 
            File without changes
         | 
| 
            File without changes
         | 
    
        data/js-routes.gemspec
    CHANGED
    
    | @@ -7,30 +7,33 @@ Gem::Specification.new do |s| | |
| 7 7 | 
             
              s.name = %q{js-routes}
         | 
| 8 8 | 
             
              s.version = JsRoutes::VERSION
         | 
| 9 9 |  | 
| 10 | 
            -
               | 
| 10 | 
            +
              if s.respond_to? :required_rubygems_version=
         | 
| 11 | 
            +
                s.required_rubygems_version = Gem::Requirement.new(">= 0")
         | 
| 12 | 
            +
              end
         | 
| 11 13 | 
             
              s.authors = ["Bogdan Gusiev"]
         | 
| 12 14 | 
             
              s.description = %q{Generates javascript file that defines all Rails named routes as javascript helpers}
         | 
| 13 15 | 
             
              s.email = %q{agresso@gmail.com}
         | 
| 14 16 | 
             
              s.extra_rdoc_files = [
         | 
| 15 17 | 
             
                "LICENSE.txt"
         | 
| 16 18 | 
             
              ]
         | 
| 19 | 
            +
              s.required_ruby_version = '>= 2.4.0'
         | 
| 17 20 | 
             
              s.files = `git ls-files`.split("\n")
         | 
| 18 21 | 
             
              s.homepage = %q{http://github.com/railsware/js-routes}
         | 
| 19 22 | 
             
              s.licenses = ["MIT"]
         | 
| 20 23 | 
             
              s.require_paths = ["lib"]
         | 
| 21 24 | 
             
              s.summary = %q{Brings Rails named routes to javascript}
         | 
| 22 25 |  | 
| 23 | 
            -
              s.add_runtime_dependency(%q<railties>, [">=  | 
| 24 | 
            -
              s. | 
| 25 | 
            -
              s.add_development_dependency(%q<rspec>, [">= 3. | 
| 26 | 
            +
              s.add_runtime_dependency(%q<railties>, [">= 4"])
         | 
| 27 | 
            +
              s.add_development_dependency(%q<sprockets-rails>)
         | 
| 28 | 
            +
              s.add_development_dependency(%q<rspec>, [">= 3.10.0"])
         | 
| 26 29 | 
             
              s.add_development_dependency(%q<bundler>, [">= 1.1.0"])
         | 
| 27 | 
            -
              s.add_development_dependency(%q<coffee-script>, [">= 0"])
         | 
| 28 30 | 
             
              s.add_development_dependency(%q<appraisal>, [">= 0.5.2"])
         | 
| 31 | 
            +
              s.add_development_dependency(%q<bump>, [">= 0.10.0"])
         | 
| 29 32 | 
             
              if defined?(JRUBY_VERSION)
         | 
| 30 33 | 
             
                s.add_development_dependency(%q<therubyrhino>, [">= 2.0.4"])
         | 
| 31 34 | 
             
              else
         | 
| 32 35 | 
             
                s.add_development_dependency(%q<byebug>)
         | 
| 33 36 | 
             
                s.add_development_dependency(%q<pry-byebug>)
         | 
| 34 | 
            -
                s.add_development_dependency(%q< | 
| 37 | 
            +
                s.add_development_dependency(%q<mini_racer>, [">= 0.4.0"])
         | 
| 35 38 | 
             
              end
         | 
| 36 39 | 
             
            end
         | 
    
        data/lib/js_routes/engine.rb
    CHANGED
    
    | @@ -1,4 +1,5 @@ | |
| 1 | 
            -
            class  | 
| 1 | 
            +
            class JsRoutes
         | 
| 2 | 
            +
            class SprocketsExtension
         | 
| 2 3 | 
             
              def initialize(filename, &block)
         | 
| 3 4 | 
             
                @filename = filename
         | 
| 4 5 | 
             
                @source   = block.call
         | 
| @@ -41,33 +42,20 @@ class Engine < ::Rails::Engine | |
| 41 42 | 
             
                                      raise StandardError, "Sprockets version #{sprockets_version} is not supported"
         | 
| 42 43 | 
             
                                  end
         | 
| 43 44 |  | 
| 44 | 
            -
              is_running_rails = defined?(Rails) && Rails.respond_to?(:version)
         | 
| 45 | 
            -
              is_running_rails_32 = is_running_rails && Rails.version.match(/3\.2/)
         | 
| 46 | 
            -
             | 
| 47 45 | 
             
              initializer 'js-routes.dependent_on_routes', initializer_args do
         | 
| 48 46 | 
             
                case sprockets_version
         | 
| 49 47 | 
             
                  when  -> (v) { v2.match?('', v) },
         | 
| 50 48 | 
             
                        -> (v) { vgte3.match?('', v) }
         | 
| 51 49 |  | 
| 52 | 
            -
                   | 
| 53 | 
            -
             | 
| 54 | 
            -
                  # registering preprocessor
         | 
| 55 | 
            -
                  if is_running_rails_32
         | 
| 56 | 
            -
                    Rails.application.assets.register_preprocessor(
         | 
| 50 | 
            +
                  Rails.application.config.assets.configure do |config|
         | 
| 51 | 
            +
                    config.register_preprocessor(
         | 
| 57 52 | 
             
                      "application/javascript",
         | 
| 58 | 
            -
                       | 
| 53 | 
            +
                      SprocketsExtension,
         | 
| 59 54 | 
             
                    )
         | 
| 60 | 
            -
                  else
         | 
| 61 | 
            -
                    # Other rails version, assumed newer
         | 
| 62 | 
            -
                    Rails.application.config.assets.configure do |config|
         | 
| 63 | 
            -
                      config.register_preprocessor(
         | 
| 64 | 
            -
                        "application/javascript",
         | 
| 65 | 
            -
                        JsRoutesSprocketsExtension,
         | 
| 66 | 
            -
                      )
         | 
| 67 | 
            -
                    end
         | 
| 68 55 | 
             
                  end
         | 
| 69 56 | 
             
                else
         | 
| 70 57 | 
             
                  raise StandardError, "Sprockets version #{sprockets_version} is not supported"
         | 
| 71 58 | 
             
                end
         | 
| 72 59 | 
             
              end
         | 
| 73 60 | 
             
            end
         | 
| 61 | 
            +
            end
         | 
    
        data/lib/js_routes/version.rb
    CHANGED