js-routes 2.1.1 → 2.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 64ddd33bda1dffe333670e22c7abe2e578d960709c5ddb42a1559fea57495288
-  data.tar.gz: af6b923046c1d3e0e838be4502355d9a2c8646af03c90b084e0bf04ec41cbce5
+  metadata.gz: 52db2ffdef9bea714377b9c00e152177b17e40de0fd8ef57ba09a84fee2f206e
+  data.tar.gz: 8f899234c70859fee6a7c0486825c12ce501a01052e2b5d9a038f08544ac6df9
 SHA512:
-  metadata.gz: 15d336c5dae45e63e7ca1700a58ca9d9146c867a59034f9a1346fbdb03153162055fee77d018a8b206bf5ead8a813730ca8618332d1fd5b1a42e0336db8c4ece
-  data.tar.gz: fe9f55283a5b5d71a25b117f35cf9c2562128a4ca6d1efe4022a3f0108fb93779dd1ec13183b019cbf895df30ea52657c4c0f8c9df780ec7dcd486ad6eb71932
+  metadata.gz: e697c45b1908906c40cdc4591f5914dd415226de79a42a8e948f6095e0f09eb5edb5bfb0c5fd61953fde7121d9a025b3472b644ddb17ca2c13cb075c97311000
+  data.tar.gz: 7f48edacee6659d4e4b5be0d71b5127f26e473119a8bf13a73c55a7b3c295dbee7fc34b9d3f515725c5871baad319ceb0bb32ed176900845b48a84c786ba3f9c

data/CHANGELOG.md

@@ -1,5 +1,26 @@
 ## master
 
+## v2.2.2.
+
+* Fix custom file path [#295](https://github.com/railsware/js-routes/issues/295)
+
+## v2.2.1
+
+* Improve generator to update route files on `assets:precompile` and add them to `.gitignore by default` [#288](https://github.com/railsware/js-routes/issues/288#issuecomment-1012182815)
+
+## v2.2.0
+
+* Use Rack Middleware to automatically update routes file in development [#288](https://github.com/railsware/js-routes/issues/288)
+  * This setup is now a default recommended due to lack of any downside comparing to [ERB Loader](./Readme.md#webpacker) and [Manual Setup](./Readme.md#advanced-setup)
+
+## v2.1.3
+
+* Fix `default_url_options` bug. [#290](https://github.com/railsware/js-routes/issues/290)
+
+## v2.1.2
+
+* Improve browser window object detection. [#287](https://github.com/railsware/js-routes/issues/287)
+
 ## v2.1.1
 
 * Added webpacker generator `./bin/rails generate js_routes:webpacker`

data/Readme.md

@@ -16,13 +16,16 @@ gem "js-routes"
 
 ## Setup
 
-There are 3 possible ways to setup JsRoutes:
+There are several possible ways to setup JsRoutes:
 
 * [Quick and easy](#quick-start)
-  * Requires rake task to be run each time route file is updated
-* [Webpacker](#webpacker) automatic updates
+  * Uses Rack Middleware to automatically update routes locally
+  * Works great for a simple Rails application
+* [Webpacker ERB Loader](#webpacker)
   * Requires ESM module system (the default)
   * Doesn't support typescript definitions
+* [Advanced Setup](#advanced-setup)
+  * Allows very custom setups
 * [Sprockets](#sprockets) legacy
   * Deprecated and not recommended for modern apps
 
@@ -30,36 +33,54 @@ There are 3 possible ways to setup JsRoutes:
 
 ### Quick Start 
 
-Run:
+Setup [Rack Middleware](https://guides.rubyonrails.org/rails_on_rack.html#action-dispatcher-middleware-stack) 
+to automatically generate and maintain `routes.js` file and corresponding 
+[Typescript definitions](https://www.typescriptlang.org/docs/handbook/declaration-files/templates/module-d-ts.html) `routes.d.ts`:
+
+#### Use a Generator
+
+Run a command:
 
 ``` sh
-rake js:routes 
-# OR for typescript support
-rake js:routes:typescript
+rails generate js_routes:middleware
 ```
 
-**IMPORTANT**: that this setup requires the rake task to be run each time routes file is updated.
+#### Setup Manually
 
-Individual routes can be imported using:
+Add the following to `config/environments/development.rb`:
 
-``` javascript
-import {edit_post_path, posts_path} from 'routes';
-console.log(posts_path({format: 'json'})) // => "/posts.json"
-console.log(edit_post_path(1)) // => "/posts/1/edit"
+``` ruby
+  config.middleware.use(JsRoutes::Middleware)
 ```
 
-Make routes available globally in `app/javascript/packs/application.js`: 
+Use it in `app/javascript/packs/application.js`:
 
 ``` javascript
-import * as Routes from 'routes';
-window.Routes = Routes;
+import * as Routes from '../routes';
+// window.Routes = Routes;
+alert(Routes.post_path(1))
+```
+
+Upgrade `rake assets:precompile` to update js-routes files: 
+
+``` ruby
+namespace :assets do
+  task :precompile => "js:routes:typescript"
+end
+```
+
+Add js-routes files to `.gitignore`:
+
+```
+/app/javascript/routes.js
+/app/javascript/routes.d.ts
 ```
 
 <div id='webpacker'></div>
 
-### Webpacker + automatic updates - Typescript
+### Webpacker ERB loader
 
-**IMPORTANT**: this setup doesn't support IDE autocompletion with [Typescript](#definitions)
+**IMPORTANT**: this setup doesn't support IDE autocompletion with [Typescript](https://www.typescriptlang.org/docs/handbook/declaration-files/templates/module-d-ts.html)
 
 
 #### Use a Generator
@@ -118,9 +139,54 @@ import * as Routes from 'routes.js.erb';
 window.Routes = Routes;
 ```
 
+<div id='advanced-setup'></div>
+
+### Advanced Setup
+
+**IMPORTANT**: that this setup requires the JS routes file to be updates manually
+
+Routes file can be generated with a `rake` task:
+
+``` sh
+rake js:routes 
+# OR for typescript support
+rake js:routes:typescript
+```
+
+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:
+
+**IMPORTANT**: Requires [Webpacker ERB Loader](#webpacker) setup.
+
+``` erb
+// app/javascript/admin/routes.js.erb
+<%= JsRoutes.generate(include: /admin/) %>
+```
+
+``` erb
+// app/javascript/customer/routes.js.erb
+<%= JsRoutes.generate(exclude: /admin/) %>
+```
+
+You can manipulate the generated helper manually by injecting ruby into javascript:
+
+``` 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 = Rails.root.join("app/javascript")
+
+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"})
+```
+
 <div id='definitions'></div>
 
-### Typescript Definitions
+#### Typescript Definitions
 
 JsRoutes has typescript support out of the box. 
 
@@ -230,6 +296,8 @@ Options to configure JavaScript file generator. These options are only available
 * `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.
 
+<div id="formatter-options"></div>
+
 #### Formatter Options
 
 Options to configure routes formatting. These options are available both in Ruby and JavaScript context.
@@ -248,36 +316,6 @@ Options to configure routes formatting. These options are available both in Ruby
   * This option exists because JS doesn't provide a difference between an object and a hash
   * Default: `_options`
 
-## 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/) %>
-```
-
-``` erb
-// app/javascript/customer/routes.js.erb
-<%= JsRoutes.generate(exclude: /admin/) %>
-```
-
-You can manipulate the generated helper manually by injecting ruby into javascript:
-
-``` 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 = Rails.root.join("app/javascript")
-
-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"})
-```
 
 ## Usage
 

data/lib/js_routes/configuration.rb

@@ -0,0 +1,111 @@
+require "pathname"
+
+module JsRoutes
+  class Configuration
+    DEFAULTS = {
+      namespace: nil,
+      exclude: [],
+      include: //,
+      file: nil,
+      prefix: -> { Rails.application.config.relative_url_root || "" },
+      url_links: false,
+      camel_case: false,
+      default_url_options: {},
+      compact: false,
+      serializer: nil,
+      special_options_key: "_options",
+      application: -> { Rails.application },
+      module_type: 'ESM',
+      documentation: true,
+    } #:nodoc:
+
+    attr_accessor(*DEFAULTS.keys)
+
+    def initialize(attributes = nil)
+      assign(DEFAULTS)
+      return unless attributes
+      assign(attributes)
+    end
+
+    def assign(attributes = nil, &block)
+      if !attributes && !block
+        raise "Provide attributes or block"
+      end
+      tap(&block) if block
+      if attributes
+        attributes.each do |attribute, value|
+          value = value.call if value.is_a?(Proc)
+          send(:"#{attribute}=", value)
+        end
+      end
+      normalize_and_verify
+      self
+    end
+
+    def [](attribute)
+      send(attribute)
+    end
+
+    def merge(attributes)
+      clone.assign(attributes)
+    end
+
+    def to_hash
+      Hash[*members.zip(values).flatten(1)].symbolize_keys
+    end
+
+    def esm?
+      module_type === 'ESM'
+    end
+
+    def dts?
+      self.module_type === 'DTS'
+    end
+
+    def modern?
+      esm? || dts?
+    end
+
+    def require_esm
+      raise "ESM module type is required" unless modern?
+    end
+
+    def source_file
+      File.dirname(__FILE__) + "/../" + default_file_name
+    end
+
+    def output_file
+      webpacker_dir = pathname('app', 'javascript')
+      sprockets_dir = pathname('app','assets','javascripts')
+      file_name = file || default_file_name
+      sprockets_file = sprockets_dir.join(file_name)
+      webpacker_file = webpacker_dir.join(file_name)
+      !Dir.exist?(webpacker_dir) && defined?(::Sprockets) ? sprockets_file : webpacker_file
+    end
+
+    protected
+
+    def normalize_and_verify
+      normalize
+      verify
+    end
+
+    def pathname(*parts)
+      Pathname.new(File.join(*parts))
+    end
+
+    def default_file_name
+      dts? ? "routes.d.ts" : "routes.js"
+    end
+
+    def normalize
+      self.module_type = module_type&.upcase || 'NIL'
+    end
+
+    def verify
+      if module_type != 'NIL' && namespace
+        raise "JsRoutes namespace option can only be used if module_type is nil"
+      end
+    end
+  end
+end

data/lib/js_routes/engine.rb

@@ -1,4 +1,4 @@
-class JsRoutes
+module JsRoutes
 class SprocketsExtension
   def initialize(filename, &block)
     @filename = filename

data/lib/js_routes/generators/middleware.rb

@@ -0,0 +1,58 @@
+require "rails/generators"
+
+class JsRoutes::Generators::Middleware < Rails::Generators::Base
+
+  source_root File.expand_path(__FILE__ + "/../../../templates")
+
+  def create_middleware
+    copy_file "initializer.rb", "config/initializers/js_routes.rb"
+    inject_into_file "app/javascript/packs/application.js", pack_content
+    inject_into_file "config/environments/development.rb", middleware_content, before: /^end\n\z/
+    inject_into_file "Rakefile", rakefile_content
+    inject_into_file ".gitignore", gitignore_content
+    JsRoutes.generate!
+    JsRoutes.definitions!
+  end
+
+  protected
+
+  def pack_content
+    <<-JS
+import * as Routes from '../routes';
+window.Routes = Routes;
+    JS
+  end
+
+  def middleware_content
+    <<-RB
+
+  # Automatically update js-routes file
+  # when routes.rb is changed
+  config.middleware.use(JsRoutes::Middleware)
+    RB
+  end
+
+  def rakefile_content
+    <<-RB
+
+# Update js-routes file before assets precompile
+namespace :assets do
+  task :precompile => "js:routes:typescript"
+end
+    RB
+  end
+
+  def gitignore_content
+    banner = <<-TXT
+
+# Ignore automatically generated js-routes files.
+    TXT
+
+    banner + [
+      {},
+      {module_type: 'DTS'}
+    ].map do |config|
+      File.join('/', JsRoutes.new(config).configuration.output_file) + "\n"
+    end.join
+  end
+end

data/lib/js_routes/generators/webpacker.rb

@@ -1,6 +1,6 @@
 require "rails/generators"
 
-class JsRoutes::Webpacker < Rails::Generators::Base
+class JsRoutes::Generators::Webpacker < Rails::Generators::Base
 
   source_root File.expand_path(__FILE__ + "/../../../templates")
 

data/lib/js_routes/instance.rb

@@ -0,0 +1,154 @@
+require "js_routes/configuration"
+require "js_routes/route"
+
+module JsRoutes
+  class Instance
+
+    attr_reader :configuration
+    #
+    # Implementation
+    #
+
+    def initialize(options = {})
+      @configuration = JsRoutes.configuration.merge(options)
+    end
+
+    def generate
+      # Ensure routes are loaded. If they're not, load them.
+      if named_routes.empty? && application.respond_to?(:reload_routes!)
+        application.reload_routes!
+      end
+      content = File.read(@configuration.source_file)
+
+      if !@configuration.dts?
+        content = js_variables.inject(content) do |js, (key, value)|
+          js.gsub!("RubyVariables.#{key}", value.to_s) ||
+          raise("Missing key #{key} in JS template")
+        end
+      end
+      content + routes_export + prevent_types_export
+    end
+
+    def generate!
+      # Some libraries like Devise did not load their routes yet
+      # so we will wait until initialization process finishes
+      # https://github.com/railsware/js-routes/issues/7
+      Rails.configuration.after_initialize do
+        file_path = Rails.root.join(@configuration.output_file)
+        source_code = generate
+
+        # We don't need to rewrite file if it already exist and have same content.
+        # It helps asset pipeline or webpack understand that file wasn't changed.
+        next if File.exist?(file_path) && File.read(file_path) == source_code
+
+        File.open(file_path, 'w') do |f|
+          f.write source_code
+        end
+      end
+    end
+
+    protected
+
+    def js_variables
+      {
+        'GEM_VERSION'         => JsRoutes::VERSION,
+        'ROUTES_OBJECT'       => routes_object,
+        'RAILS_VERSION'       => ActionPack.version,
+        'DEPRECATED_GLOBBING_BEHAVIOR' => ActionPack::VERSION::MAJOR == 4 && ActionPack::VERSION::MINOR == 0,
+
+        'APP_CLASS'           => application.class.to_s,
+        'NAMESPACE'           => json(@configuration.namespace),
+        'DEFAULT_URL_OPTIONS' => json(@configuration.default_url_options),
+        'PREFIX'              => json(@configuration.prefix),
+        'SPECIAL_OPTIONS_KEY' => json(@configuration.special_options_key),
+        'SERIALIZER'          => @configuration.serializer || json(nil),
+        'MODULE_TYPE'         => json(@configuration.module_type),
+        'WRAPPER'             => @configuration.esm? ? 'const __jsr = ' : '',
+      }
+    end
+
+    def application
+      @configuration.application
+    end
+
+    def json(string)
+      JsRoutes.json(string)
+    end
+
+    def named_routes
+      application.routes.named_routes.to_a
+    end
+
+    def routes_object
+      return json({}) if @configuration.modern?
+      properties = routes_list.map do |comment, name, body|
+        "#{comment}#{name}: #{body}".indent(2)
+      end
+      "{\n" + properties.join(",\n\n") + "}\n"
+    end
+
+    def static_exports
+      [:configure, :config, :serialize].map do |name|
+        [
+          "", name,
+          @configuration.dts? ?
+          "RouterExposedMethods['#{name}']" :
+          "__jsr.#{name}"
+        ]
+      end
+    end
+
+    def routes_export
+      return "" unless @configuration.modern?
+      [*static_exports, *routes_list].map do |comment, name, body|
+        "#{comment}export const #{name}#{export_separator}#{body};\n\n"
+      end.join
+    end
+
+    def prevent_types_export
+      return "" unless @configuration.dts?
+      <<-JS
+// By some reason this line prevents all types in a file
+// from being automatically exported
+export {};
+      JS
+    end
+
+    def export_separator
+      @configuration.dts? ? ': ' : ' = '
+    end
+
+    def routes_list
+      named_routes.sort_by(&:first).flat_map do |_, route|
+        route_helpers_if_match(route) + mounted_app_routes(route)
+      end
+    end
+
+    def mounted_app_routes(route)
+      rails_engine_app = app_from_route(route)
+      if rails_engine_app.respond_to?(:superclass) &&
+          rails_engine_app.superclass == Rails::Engine && !route.path.anchored
+        rails_engine_app.routes.named_routes.flat_map do |_, engine_route|
+          route_helpers_if_match(engine_route, route)
+        end
+      else
+        []
+      end
+    end
+
+    def app_from_route(route)
+      app = route.app
+      # rails engine in Rails 4.2 use additional
+      # ActionDispatch::Routing::Mapper::Constraints, which contain app
+      if app.respond_to?(:app) && app.respond_to?(:constraints)
+        app.app
+      else
+        app
+      end
+    end
+
+    def route_helpers_if_match(route, parent_route = nil)
+      Route.new(@configuration, route, parent_route).helpers
+    end
+  end
+end

data/lib/js_routes/middleware.rb

@@ -0,0 +1,36 @@
+module JsRoutes
+  # A Rack middleware that automatically updates routes file
+  # whenever routes.rb is modified
+  #
+  # Inspired by
+  # https://github.com/fnando/i18n-js/blob/main/lib/i18n/js/middleware.rb
+  class Middleware
+    def initialize(app)
+      @app = app
+      @routes_file = Rails.root.join("config/routes.rb")
+      @mtime = nil
+    end
+
+    def call(env)
+      update_js_routes
+      @app.call(env)
+    end
+
+    protected
+
+    def update_js_routes
+      new_mtime = routes_mtime
+      unless new_mtime == @mtime
+        JsRoutes.generate!
+        JsRoutes.definitions!
+        @mtime = new_mtime
+      end
+    end
+
+    def routes_mtime
+      File.mtime(@routes_file)
+    rescue Errno::ENOENT
+      nil
+    end
+  end
+end