js-routes 2.0.5 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c9a63dedd682c2cf4330ffc7c4ce012845e35fae3c315846a2ba5ef52b980ba2
-  data.tar.gz: 5e62c6831d3799376fad6a8e6e433488c4674bc7d7ac4917fe9f9e0a0ca9f03d
+  metadata.gz: 242f329ab92abe8be4a2fa3790f72a3f161a6c2355b2392eae484a36a91d3a24
+  data.tar.gz: 120e5191eccfe3a8978c89ecb690a4f93a62279b249c58bc84b9273fe3e900c7
 SHA512:
-  metadata.gz: 2ee773fcb0b7ea746248c06d6fac1365a23ab732ff16620d555bb4d035e9661187d02fb093a127a9d240e0621976cbc6680996c22e065bd70e7c8d2318e37753
-  data.tar.gz: 5a7e0d7fc1b1af56c4ee72a3b8cdef0d6b42671425c35b60410ffe2b62e63779deeb733ca5293fc62507b224094686de436d763f7b49ffc29248b1fc2e653d71
+  metadata.gz: e1998fd3c98dff227905bfcd8a09be8bb6901d3da7293b60d1a6f11c3a2627c623372324a13010cbe425eb7b93781fa64db042c08e7b4123d4a50ec8bd8814b2
+  data.tar.gz: 5395c808f148bd39a99de0ce748cbb3a57c27620f048764bfcf6a455ac6ce2bbc43e282f4c660ba019f8d4b5df39a316728bb673d56b2667aecb667dde82d91b

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 ## master
 
+## v2.1.0
+
+* Support typescript defintions file aka `routes.d.ts`. See [Readme.md](./Readme.md#definitions) for more information.
+
+## v2.0.8
+
+* Forbid usage of `namespace` option if `module_type` is not `nil`. [#281](https://github.com/railsware/js-routes/issues/281).
+
+## v2.0.7
+
+* Remove source map annotation from JS file. Fixes [#277](https://github.com/railsware/js-routes/issues/277)
+  * Generated file is not minified, so it is better to use app side bundler/compressor for source maps
+
+
+## v2.0.6
+
+* Disable `namespace` option default for all envs [#278](https://github.com/railsware/js-routes/issues/278)
+
 ## v2.0.5
 
 * Fixed backward compatibility issue [#276](https://github.com/railsware/js-routes/issues/276)

data/Readme.md

@@ -20,22 +20,26 @@ gem "js-routes"
 
 Run:
 
-```
+``` sh
 rake js:routes 
+# OR for typescript support
+rake js:routes:typescript
 ```
 
-Make routes available globally in `app/javascript/packs/application.js`: 
+
+Individual routes can be imported using:
 
 ``` javascript
-import * as Routes from 'routes';
-window.Routes = Routes;
+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"
 ```
 
-Individual routes can be imported using:
+Make routes available globally in `app/javascript/packs/application.js`: 
 
 ``` javascript
-import {edit_post_path} from 'routes';
-console.log(edit_post_path(1))
+import * as Routes from 'routes';
+window.Routes = Routes;
 ```
 
 **Note**: that this setup requires `rake js:routes` to be run each time routes file is updated.
@@ -91,6 +95,22 @@ import * as Routes from 'routes.js.erb';
 window.Routes = Routes;
 ```
 
+<div id='definitions'></div>
+
+#### Typescript Definitions
+
+JsRoutes has typescript support out of the box. In order to generate typscript definitions file (aka `routes.d.ts`) you can call:
+
+``` ruby
+JsRoutes.definitions!
+```
+
+Or create an automatic updates file at `app/javascript/routes.d.ts.erb`:
+
+``` erb
+<%= JsRoutes.defintions %>
+```
+
 #### Sprockets (Deprecated)
 
 If you are using [Sprockets](https://github.com/rails/sprockets-rails) you may configure js-routes in the following way.
@@ -147,7 +167,7 @@ Routes.config(); // current config
 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`.
+  * Options: `ESM`, `UMD`, `CJS`, `AMD`, `DTS`, `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
@@ -159,6 +179,7 @@ Options to configure JavaScript file generator. These options are only available
   * Default: `[]`
   * The regexp applies only to the name before the `_path` suffix, eg: you want to match exactly `settings_path`, the regexp should be `/^settings$/`
 * `namespace` - global object used to access routes.
+  * Only available if `module_type` option is set to `nil`.
   * Supports nested namespace like `MyProject.routes`
   * Default: `nil`
 * `camel_case` - specifies if route helpers should be generated in camel case instead of underscore case.
@@ -314,29 +335,20 @@ import {
 } from 'routes.js.erb'
 ```
 
+Such import structure allows for moddern JS bundlers like [Webpack](https://webpack.js.org/) to only include explicitly imported routes into JS bundle file.
+See [Tree Shaking](https://webpack.js.org/guides/tree-shaking/) for more information.
+
 ### 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_/)
+<%= JsRoutes.generate(include: /^admin_/) %>
 // app-routes.js.erb
-<%= JsRoutes.generate(exclude: /^admin_/)
+<%= JsRoutes.generate(exclude: /^admin_/) %>
 ```
 
-## JsRoutes and Heroku
-
-When using this setup on Heroku, it is impossible to use the asset pipeline. You should use the "Very Advanced Setup" schema in this case.
-
-For example create routes.js.erb in assets folder with needed content:
-
-``` erb
-<%= JsRoutes.generate(options) %>
-```
-
-This should just work.
-
 ## Advantages over alternatives
 
 There are some alternatives available. Most of them has only basic feature and don't reach the level of quality I accept.

data/VERSION_2_UPGRADE.md

@@ -2,23 +2,40 @@
 
 ### Using ESM module by default
 
-The default setting are now changed:
+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. 
+[ESM+Webpacker](/Readme.md#webpacker) upgrade is recommended. 
 
-Setting | Old | New 
---- | --- | ---
-module\_type | nil | ESM 
-namespace | Routes | nil
+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.
+Here are supported values:
 
-This is more optimized setup for WebPacker. You can restore the old configuration like this:
+* CJS
+* UMD
+* AMD
+* ESM
+* nil
+
+[Explaination Article](https://dev.to/iggredible/what-the-heck-are-cjs-amd-umd-and-esm-ikm)
+
+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:
 
 ``` ruby
 JsRoutes.setup do |config|
   config.module_type = nil
-  config.namespace = 'Routes'
+  config.namespace = "Routes"
 end
 ```
 
-However, [ESM+Webpacker](/Readme.md#webpacker) upgrade is recommended. 
+### JSDoc comment
+
+New version of js-routes generates function comment in the [JSDoc](https://jsdoc.app) format.
+If you have any problems with that, you can disable it like this:
+
+
+``` ruby
+JsRoutes.setup do |config|
+  config.documentation = false
+end
+```
 
 ### `required_params` renamed
 
@@ -47,15 +64,3 @@ try {
   }
 }
 ```
-
-### 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
-```
-

data/js-routes.gemspec

@@ -25,7 +25,7 @@ Gem::Specification.new do |s|
 
   s.add_runtime_dependency(%q<railties>, [">= 4"])
   s.add_development_dependency(%q<sprockets-rails>)
-  s.add_development_dependency(%q<rspec>, [">= 3.0.0"])
+  s.add_development_dependency(%q<rspec>, [">= 3.10.0"])
   s.add_development_dependency(%q<bundler>, [">= 1.1.0"])
   s.add_development_dependency(%q<appraisal>, [">= 0.5.2"])
   s.add_development_dependency(%q<bump>, [">= 0.10.0"])

data/lib/js_routes/version.rb

@@ -1,3 +1,3 @@
 class JsRoutes
-  VERSION = "2.0.5"
+  VERSION = "2.1.0"
 end

data/lib/js_routes.rb

@@ -7,48 +7,26 @@ require 'active_support/core_ext/string/indent'
 
 class JsRoutes
 
-  #
-  # OPTIONS
-  #
+  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)
 
-  DEFAULTS = {
-    namespace: -> { defined?(Webpacker) ? nil : "Routes" },
-    exclude: [],
-    include: //,
-    file: -> do
-      webpacker_dir = Rails.root.join('app', 'javascript')
-      sprockets_dir = Rails.root.join('app','assets','javascripts')
-      sprockets_file = sprockets_dir.join('routes.js')
-      webpacker_file = webpacker_dir.join('routes.js')
-      !Dir.exist?(webpacker_dir) && defined?(::Sprockets) ? sprockets_file : webpacker_file
-    end,
-    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:
-
-  NODE_TYPES = {
-    GROUP: 1,
-    CAT: 2,
-    SYMBOL: 3,
-    OR: 4,
-    STAR: 5,
-    LITERAL: 6,
-    SLASH: 7,
-    DOT: 8
-  } #:nodoc:
-
-  FILTERED_DEFAULT_PARTS = [:controller, :action] #:nodoc:
-  URL_OPTIONS = [:protocol, :domain, :host, :port, :subdomain] #:nodoc:
-
-  class Configuration < Struct.new(*DEFAULTS.keys)
     def initialize(attributes = nil)
       assign(DEFAULTS)
       return unless attributes
@@ -60,6 +38,7 @@ class JsRoutes
         value = value.call if value.is_a?(Proc)
         send(:"#{attribute}=", value)
       end
+      normalize_and_verify
       self
     end
 
@@ -76,7 +55,49 @@ class JsRoutes
     end
 
     def esm?
-      self.module_type === 'ESM'
+      module_type === 'ESM'
+    end
+
+    def dts?
+      self.module_type === 'DTS'
+    end
+
+    def modern?
+      esm? || dts?
+    end
+
+    def source_file
+      File.dirname(__FILE__) + "/" + default_file_name
+    end
+
+    def output_file
+      webpacker_dir = Rails.root.join('app', 'javascript')
+      sprockets_dir = Rails.root.join('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
+
+    def normalize_and_verify
+      normalize
+      verify
+    end
+
+    protected
+
+    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
 
@@ -87,6 +108,7 @@ class JsRoutes
   class << self
     def setup(&block)
       configuration.tap(&block) if block
+      configuration.normalize_and_verify
     end
 
     def configuration
@@ -97,12 +119,13 @@ class JsRoutes
       new(opts).generate
     end
 
-    def generate!(file_name=nil, opts = {})
-      if file_name.is_a?(Hash)
-        opts = file_name
-        file_name = opts[:file]
-      end
-      new(opts).generate!(file_name)
+    def generate!(file_name=nil, **opts)
+      new(file: file_name, **opts).generate!
+    end
+
+    def definitions!(file_name = nil, **opts)
+      file_name ||= configuration.file&.sub!(%r{\.(j|t)s\Z}, ".d.ts")
+      new(file: file_name, module_type: 'DTS', **opts).generate!
     end
 
     def json(string)
@@ -123,48 +146,55 @@ class JsRoutes
     if named_routes.to_a.empty? && application.respond_to?(:reload_routes!)
       application.reload_routes!
     end
+    content = File.read(@configuration.source_file)
 
-    {
-      '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 = ' : '',
-    }.inject(File.read(File.dirname(__FILE__) + "/routes.js")) do |js, (key, value)|
-      js.gsub!("RubyVariables.#{key}", value.to_s) ||
+    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 + routes_export
+      end
+    end
+    content + routes_export + prevent_types_export
   end
 
-  def generate!(file_name = nil)
-    # Some libraries like Devise do not yet loaded their routes so we will wait
-    # until initialization process finish
+  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_name ||= self.class.configuration['file']
-      file_path = Rails.root.join(file_name)
-      js_content = generate
+      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) == js_content
+      next if File.exist?(file_path) && File.read(file_path) == source_code
 
       File.open(file_path, 'w') do |f|
-        f.write js_content
+        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
@@ -178,32 +208,52 @@ class JsRoutes
   end
 
   def routes_object
-    return json({}) if @configuration.esm?
+    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
 
-  STATIC_EXPORTS = [:configure, :config, :serialize].map do |name|
-    ["", name, "__jsr.#{name}"]
+  def static_exports
+    [:configure, :config, :serialize].map do |name|
+      [
+        "", name,
+        @configuration.dts? ?
+          "RouterExposedMethods['#{name}']" :
+          "__jsr.#{name}"
+      ]
+    end
   end
 
   def routes_export
-    return "" unless @configuration.esm?
-    [*STATIC_EXPORTS, *routes_list].map do |comment, name, body|
-      "#{comment}export const #{name} = #{body};"
-    end.join("\n\n")
+    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.compact
+    end
   end
 
   def mounted_app_routes(route)
-    rails_engine_app = get_app_from_route(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|
@@ -214,7 +264,7 @@ class JsRoutes
     end
   end
 
-  def get_app_from_route(route)
+  def app_from_route(route)
     # rails engine in Rails 4.2 use additional
     # ActionDispatch::Routing::Mapper::Constraints, which contain app
     if route.app.respond_to?(:app) && route.app.respond_to?(:constraints)
@@ -229,6 +279,19 @@ class JsRoutes
   end
 
   class JsRoute #:nodoc:
+    FILTERED_DEFAULT_PARTS = [:controller, :action]
+    URL_OPTIONS = [:protocol, :domain, :host, :port, :subdomain]
+    NODE_TYPES = {
+      GROUP: 1,
+      CAT: 2,
+      SYMBOL: 3,
+      OR: 4,
+      STAR: 5,
+      LITERAL: 6,
+      SLASH: 7,
+      DOT: 8
+    }
+
     attr_reader :configuration, :route, :parent_route
 
     def initialize(configuration, route, parent_route = nil)
@@ -238,22 +301,36 @@ class JsRoutes
     end
 
     def helpers
-      unless match_configuration?
-        []
-      else
-        [false, true].map do |absolute|
-          absolute && !@configuration[:url_links] ?
-            nil : [ documentation, helper_name(absolute), body(absolute) ]
-        end
+      helper_types.map do |absolute|
+        [ documentation, helper_name(absolute), body(absolute) ]
       end
     end
 
+    def helper_types
+      return [] unless match_configuration?
+      @configuration[:url_links] ? [true, false] : [false]
+    end
+
     def body(absolute)
-      "__jsr.r(#{arguments(absolute).join(', ')})"
+      @configuration.dts? ?
+        definition_body : "__jsr.r(#{arguments(absolute).map{|a| json(a)}.join(', ')})"
+    end
+
+    def definition_body
+      args = required_parts.map{|p| "#{apply_case(p)}: RequiredRouteParameter"}
+      args << "options?: #{optional_parts_type} & RouteOptions"
+      "((\n#{args.join(",\n").indent(2)}\n) => string) & RouteHelperExtras"
+    end
+
+    def optional_parts_type
+      @optional_parts_type ||=
+        "{" + optional_parts.map {|p| "#{p}?: OptionalRouteParameter"}.join(', ') + "}"
     end
 
+    protected
+
     def arguments(absolute)
-      absolute ? base_arguments + [json(true)] : base_arguments
+      absolute ? [*base_arguments, true] : base_arguments
     end
 
     def match_configuration?
@@ -298,10 +375,15 @@ JS
       route.required_parts
     end
 
-    protected
+    def optional_parts
+      route.path.optional_names
+    end
 
     def base_arguments
-      return @base_arguments if defined?(@base_arguments)
+      @base_arguments ||= [parts_table, serialize(spec, parent_spec)]
+    end
+
+    def parts_table
       parts_table = {}
       route.parts.each do |part, hash|
         parts_table[part] ||= {}
@@ -318,11 +400,7 @@ JS
           parts_table[part][:d] = value
         end
       end
-      @base_arguments = [
-        parts_table, serialize(spec, parent_spec)
-      ].map do |argument|
-        json(argument)
-      end
+      parts_table
     end
 
     def documentation_params