js-routes 1.4.9 → 2.0.0

data/VERSION_2_UPGRADE.md

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

data/js-routes.gemspec

@@ -7,13 +7,16 @@ Gem::Specification.new do |s|
   s.name = %q{js-routes}
   s.version = JsRoutes::VERSION
 
-  s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
+  if s.respond_to? :required_rubygems_version=
+    s.required_rubygems_version = Gem::Requirement.new(">= 0")
+  end
   s.authors = ["Bogdan Gusiev"]
   s.description = %q{Generates javascript file that defines all Rails named routes as javascript helpers}
   s.email = %q{agresso@gmail.com}
   s.extra_rdoc_files = [
     "LICENSE.txt"
   ]
+  s.required_ruby_version = '>= 2.4.0'
   s.files = `git ls-files`.split("\n")
   s.homepage = %q{http://github.com/railsware/js-routes}
   s.licenses = ["MIT"]
@@ -21,16 +24,16 @@ Gem::Specification.new do |s|
   s.summary = %q{Brings Rails named routes to javascript}
 
   s.add_runtime_dependency(%q<railties>, [">= 4"])
-  s.add_runtime_dependency(%q<sprockets-rails>)
+  s.add_development_dependency(%q<sprockets-rails>)
   s.add_development_dependency(%q<rspec>, [">= 3.0.0"])
   s.add_development_dependency(%q<bundler>, [">= 1.1.0"])
-  s.add_development_dependency(%q<coffee-script>, [">= 0"])
   s.add_development_dependency(%q<appraisal>, [">= 0.5.2"])
+  s.add_development_dependency(%q<bump>, [">= 0.10.0"])
   if defined?(JRUBY_VERSION)
     s.add_development_dependency(%q<therubyrhino>, [">= 2.0.4"])
   else
     s.add_development_dependency(%q<byebug>)
     s.add_development_dependency(%q<pry-byebug>)
-    s.add_development_dependency(%q<mini_racer>, [">= 0.2.4"])
+    s.add_development_dependency(%q<mini_racer>, [">= 0.4.0"])
   end
 end

data/lib/js_routes.rb

@@ -1,6 +1,9 @@
 require 'uri'
-require 'js_routes/engine' if defined?(Rails)
+if defined?(::Rails) && defined?(::Sprockets::Railtie)
+  require 'js_routes/engine'
+end
 require 'js_routes/version'
+require 'active_support/core_ext/string/indent'
 
 class JsRoutes
 
@@ -8,13 +11,17 @@ class JsRoutes
   # OPTIONS
   #
 
-  DEFAULT_PATH = File.join('app','assets','javascripts','routes.js')
-
   DEFAULTS = {
-    namespace: "Routes",
+    namespace: -> { defined?(Webpacker) ? nil : "Routes" },
     exclude: [],
     include: //,
-    file: DEFAULT_PATH,
+    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,
@@ -22,8 +29,10 @@ class JsRoutes
     compact: false,
     serializer: nil,
     special_options_key: "_options",
-    application: -> { Rails.application }
-  }
+    application: -> { Rails.application },
+    module_type: 'ESM',
+    documentation: true,
+  } #:nodoc:
 
   NODE_TYPES = {
     GROUP: 1,
@@ -34,11 +43,11 @@ class JsRoutes
     LITERAL: 6,
     SLASH: 7,
     DOT: 8
-  }
+  } #:nodoc:
 
-  LAST_OPTIONS_KEY = "options".freeze
-  FILTERED_DEFAULT_PARTS = [:controller, :action]
-  URL_OPTIONS = [:protocol, :domain, :host, :port, :subdomain]
+  LAST_OPTIONS_KEY = "options".freeze #: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)
@@ -66,6 +75,10 @@ class JsRoutes
     def to_hash
       Hash[*members.zip(values).flatten(1)].symbolize_keys
     end
+
+    def esm?
+      self.module_type === 'ESM'
+    end
   end
 
   #
@@ -77,11 +90,6 @@ class JsRoutes
       configuration.tap(&block) if block
     end
 
-    def options
-      ActiveSupport::Deprecation.warn('JsRoutes.options method is deprecated use JsRoutes.configuration instead')
-      configuration
-    end
-
     def configuration
       @configuration ||= Configuration.new
     end
@@ -119,8 +127,7 @@ class JsRoutes
 
     {
       'GEM_VERSION'         => JsRoutes::VERSION,
-      'ROUTES'              => js_routes,
-      'NODE_TYPES'          => json(NODE_TYPES),
+      'ROUTES_OBJECT'              => routes_object,
       'RAILS_VERSION'       => ActionPack.version,
       'DEPRECATED_GLOBBING_BEHAVIOR' => ActionPack::VERSION::MAJOR == 4 && ActionPack::VERSION::MINOR == 0,
 
@@ -130,9 +137,12 @@ class JsRoutes
       '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!(key, value.to_s)
-    end
+      js.gsub!("RubyVariables.#{key}", value.to_s) ||
+        raise("Missing key #{key} in JS template")
+    end + routes_export
   end
 
   def generate!(file_name = nil)
@@ -164,19 +174,37 @@ class JsRoutes
     application.routes.named_routes.to_a
   end
 
-  def js_routes
-    js_routes = named_routes.sort_by(&:first).flat_map do |_, route|
-      [build_route_if_match(route)] + mounted_app_routes(route)
+  def routes_object
+    return json({}) if @configuration.esm?
+    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}"]
+  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")
+  end
+
+  def routes_list
+    named_routes.sort_by(&:first).flat_map do |_, route|
+      build_routes_if_match(route) + mounted_app_routes(route)
     end.compact
-    "{\n" + js_routes.join(",\n") + "}\n"
   end
 
   def mounted_app_routes(route)
     rails_engine_app = get_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.map do |_, engine_route|
-        build_route_if_match(engine_route, route)
+      rails_engine_app.routes.named_routes.flat_map do |_, engine_route|
+        build_routes_if_match(engine_route, route)
       end
     else
       []
@@ -193,12 +221,17 @@ class JsRoutes
     end
   end
 
-  def build_route_if_match(route, parent_route = nil)
+  def build_routes_if_match(route, parent_route = nil)
     if any_match?(route, parent_route, @configuration[:exclude]) ||
        !any_match?(route, parent_route, @configuration[:include])
-      nil
+      []
     else
-      build_js(route, parent_route)
+      name = [parent_route.try(:name), route.name].compact
+      parent_spec = parent_route.try(:path).try(:spec)
+      route_arguments = route_js_arguments(route, parent_spec)
+      return [false, true].map do |absolute|
+        route_js(name, parent_spec, route, route_arguments, absolute)
+      end
     end
   end
 
@@ -209,59 +242,72 @@ class JsRoutes
     matchers.any? { |regex| full_route =~ regex }
   end
 
-  def build_js(route, parent_route)
-    name = [parent_route.try(:name), route.name].compact
-    route_name = generate_route_name(name, (:path unless @configuration[:compact]))
-    parent_spec = parent_route.try(:path).try(:spec)
-    route_arguments = route_js_arguments(route, parent_spec)
-    url_link = generate_url_link(name, route_arguments)
-    _ = <<-JS.strip!
-  // #{name.join('.')} => #{parent_spec}#{route.path.spec}
-  // function(#{build_params(route.required_parts)})
-  #{route_name}: Utils.route(#{route_arguments})#{",\n" + url_link if url_link.length > 0}
-  JS
+  def route_js(name_parts, parent_spec, route, route_arguments, absolute)
+    if absolute
+      return nil unless @configuration[:url_links]
+      route_arguments = route_arguments + [json(true)]
+    end
+    name_suffix = absolute ? :url : @configuration[:compact] ? nil : :path
+    name = generate_route_name(name_parts, name_suffix)
+    body = "__jsr.r(#{route_arguments.join(', ')})"
+    comment = documentation(route, parent_spec)
+    [ comment, name, body ]
+  end
+
+  def documentation(route, parent_spec)
+    return nil unless @configuration[:documentation]
+    <<-JS
+/**
+ * Generates rails route to
+ * #{parent_spec}#{route.path.spec}#{build_params(route.required_parts)}
+ * @param {object | undefined} options
+ * @returns {string} route path
+ */
+JS
   end
 
   def route_js_arguments(route, parent_spec)
     required_parts = route.required_parts
-    parts_table = route.parts.each_with_object({}) do |part, hash|
-      hash[part] = required_parts.include?(part)
+    parts_table = {}
+    route.parts.each do |part, hash|
+      parts_table[part] ||= {}
+      if required_parts.include?(part)
+        # Using shortened keys to reduce js file size
+        parts_table[part][:r] = true
+      end
     end
-    default_options = route.defaults.select do |part, _|
-      FILTERED_DEFAULT_PARTS.exclude?(part) &&
+    route.defaults.each do |part, value|
+      if FILTERED_DEFAULT_PARTS.exclude?(part) &&
         URL_OPTIONS.include?(part) || parts_table[part]
+        parts_table[part] ||= {}
+        # Using shortened keys to reduce js file size
+        parts_table[part][:d] = value
+      end
     end
     [
-      # JS objects don't preserve the order of properties which is crucial,
-      # so array is a better choice.
-      parts_table.to_a,
-      default_options,
+      parts_table,
       serialize(route.path.spec, parent_spec)
     ].map do |argument|
       json(argument)
-    end.join(', ')
-  end
-
-  def generate_url_link(name, route_arguments)
-    return '' unless @configuration[:url_links]
-
-    <<-JS.strip!
-    #{generate_route_name(name, :url)}: Utils.route(#{route_arguments}, true)
-    JS
+    end
   end
 
   def generate_route_name(*parts)
-    route_name = parts.compact.join('_')
-    @configuration[:camel_case] ? route_name.camelize(:lower) : route_name
+    apply_case(parts.compact.join('_'))
   end
 
   def json(string)
     self.class.json(string)
   end
 
+  def apply_case(value)
+    @configuration[:camel_case] ? value.to_s.camelize(:lower) : value
+  end
+
   def build_params(required_parts)
-    params = required_parts + [LAST_OPTIONS_KEY]
-    params.join(', ')
+    required_parts.map do |param|
+      "\n * @param {any} #{apply_case(param)}"
+    end.join
   end
 
   # This function serializes Journey route into JSON structure
@@ -290,7 +336,7 @@ class JsRoutes
     [
       NODE_TYPES[spec.type],
       serialize(spec.left, parent_spec),
-      spec.respond_to?(:right) && serialize(spec.right)
-    ]
+      spec.respond_to?(:right) ? serialize(spec.right) : nil
+    ].compact
   end
 end

data/lib/js_routes/engine.rb

@@ -47,7 +47,6 @@ class Engine < ::Rails::Engine
       when  -> (v) { v2.match?('', v) },
             -> (v) { vgte3.match?('', v) }
 
-      # Other rails version, assumed newer
       Rails.application.config.assets.configure do |config|
         config.register_preprocessor(
           "application/javascript",

data/lib/js_routes/version.rb

@@ -1,3 +1,3 @@
 class JsRoutes
-  VERSION = "1.4.9"
+  VERSION = "2.0.0"
 end

data/lib/routes.d.ts

@@ -0,0 +1,64 @@
+/**
+ * File generated by js-routes RubyVariables.GEM_VERSION
+ * Based on Rails RubyVariables.RAILS_VERSION routes of RubyVariables.APP_CLASS
+ */
+declare type RouteParameter = unknown;
+declare type RouteParameters = Record<string, RouteParameter>;
+declare type Serializer = (value: unknown) => string;
+declare type RouteHelper = {
+  (...args: RouteParameter[]): string;
+  requiredParams(): string[];
+  toString(): string;
+};
+declare type RouteHelpers = Record<string, RouteHelper>;
+declare type Configuration = {
+  prefix: string;
+  default_url_options: RouteParameters;
+  special_options_key: string;
+  serializer: Serializer;
+};
+declare type Optional<T> = {
+  [P in keyof T]?: T[P] | null;
+};
+interface RouterExposedMethods {
+  config(): Configuration;
+  configure(arg: Partial<Configuration>): Configuration;
+  serialize: Serializer;
+}
+declare type KeywordUrlOptions = Optional<{
+  host: string;
+  protocol: string;
+  subdomain: string;
+  port: string;
+  anchor: string;
+  trailing_slash: boolean;
+}>;
+declare type PartsTable = Record<
+  string,
+  {
+    r?: boolean;
+    d?: unknown;
+  }
+>;
+declare type ModuleType = "CJS" | "AMD" | "UMD" | "ESM";
+declare const RubyVariables: {
+  PREFIX: string;
+  DEPRECATED_GLOBBING_BEHAVIOR: boolean;
+  SPECIAL_OPTIONS_KEY: string;
+  DEFAULT_URL_OPTIONS: RouteParameters;
+  SERIALIZER: Serializer;
+  NAMESPACE: string;
+  ROUTES_OBJECT: RouteHelpers;
+  MODULE_TYPE: ModuleType | null;
+  WRAPPER: <T>(callback: T) => T;
+};
+declare const define:
+  | undefined
+  | (((arg: unknown[], callback: () => unknown) => void) & {
+      amd?: unknown;
+    });
+declare const module:
+  | {
+      exports: any;
+    }
+  | undefined;