js-routes 1.4.1 → 2.1.0

data/lib/js_routes.rb

@@ -1,46 +1,32 @@
 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
 
-  #
-  # 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)
 
-  DEFAULT_PATH = File.join('app','assets','javascripts','routes.js')
-
-  DEFAULTS = {
-    namespace: "Routes",
-    exclude: [],
-    include: //,
-    file: DEFAULT_PATH,
-    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 }
-  }
-
-  NODE_TYPES = {
-    GROUP: 1,
-    CAT: 2,
-    SYMBOL: 3,
-    OR: 4,
-    STAR: 5,
-    LITERAL: 6,
-    SLASH: 7,
-    DOT: 8
-  }
-
-  LAST_OPTIONS_KEY = "options".freeze
-  FILTERED_DEFAULT_PARTS = [:controller, :action, :subdomain]
-  URL_OPTIONS = [:protocol, :domain, :host, :port, :subdomain]
-
-  class Configuration < Struct.new(*DEFAULTS.keys)
     def initialize(attributes = nil)
       assign(DEFAULTS)
       return unless attributes
@@ -52,6 +38,7 @@ class JsRoutes
         value = value.call if value.is_a?(Proc)
         send(:"#{attribute}=", value)
       end
+      normalize_and_verify
       self
     end
 
@@ -66,6 +53,52 @@ class JsRoutes
     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 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
 
   #
@@ -75,11 +108,7 @@ class JsRoutes
   class << self
     def setup(&block)
       configuration.tap(&block) if block
-    end
-
-    def options
-      ActiveSupport::Deprecation.warn('JsRoutes.options method is deprecated use JsRoutes.configuration instead')
-      configuration
+      configuration.normalize_and_verify
     end
 
     def configuration
@@ -90,22 +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
 
-    # Under rails 3.1.1 and higher, perform a check to ensure that the
-    # full environment will be available during asset compilation.
-    # This is required to ensure routes are loaded.
-    def assert_usable_configuration!
-      if 3 == Rails::VERSION::MAJOR && !Rails.application.config.assets.initialize_on_precompile
-        raise("Cannot precompile js-routes unless environment is initialized. Please set config.assets.initialize_on_precompile to true.")
-      end
-      true
+    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)
@@ -126,66 +146,127 @@ 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"              => js_routes,
-      "DEPRECATED_BEHAVIOR" => Rails.version < "4",
-      "NODE_TYPES"          => json(NODE_TYPES),
-
-      "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),
-    }.inject(File.read(File.dirname(__FILE__) + "/routes.js")) do |js, (key, value)|
-      js.gsub!(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
     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.open(Rails.root.join(file_name), 'w') do |f|
-        f.write 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) == 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)
+    self.class.json(string)
+  end
+
   def named_routes
     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)
-    end.compact
-    "{\n" + js_routes.join(",\n") + "}\n"
+  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 = 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 = 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 get_app_from_route(route)
-    # rails engine in Rails 4.2 use additional ActionDispatch::Routing::Mapper::Constraints, which contain app
+  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)
       route.app.app
     else
@@ -193,101 +274,178 @@ class JsRoutes
     end
   end
 
-  def build_route_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)
-    end
+  def route_helpers_if_match(route, parent_route = nil)
+    JsRoute.new(@configuration, route, parent_route).helpers
   end
 
-  def any_match?(route, parent_route, matchers)
-    full_route = [parent_route.try(:name), route.name].compact.join('_')
+  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)
+      @configuration = configuration
+      @route = route
+      @parent_route = parent_route
+    end
 
-    matchers = Array(matchers)
-    matchers.any? {|regex| full_route =~ regex}
-  end
+    def helpers
+      helper_types.map do |absolute|
+        [ documentation, helper_name(absolute), body(absolute) ]
+      end
+    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_name, route_arguments, route)
-    _ = <<-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
-  end
+    def helper_types
+      return [] unless match_configuration?
+      @configuration[:url_links] ? [true, false] : [false]
+    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)
-    end
-    default_options = route.defaults.select do |part, _|
-      FILTERED_DEFAULT_PARTS.exclude?(part) && URL_OPTIONS.include?(part) || parts_table[part]
-    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,
-      serialize(route.path.spec, parent_spec)
-    ].map do |argument|
-      json(argument)
-    end.join(", ")
-  end
+    def body(absolute)
+      @configuration.dts? ?
+        definition_body : "__jsr.r(#{arguments(absolute).map{|a| json(a)}.join(', ')})"
+    end
 
-  def generate_url_link(name, route_name, route_arguments, route)
-    return "" unless @configuration[:url_links]
-    <<-JS.strip!
-    #{generate_route_name(name, :url)}: Utils.route(#{route_arguments}, true)
-    JS
-  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 generate_route_name(name, suffix)
-    route_name = name.join('_')
-    route_name << "_#{ suffix }" if suffix
-    @configuration[:camel_case] ? route_name.camelize(:lower) : route_name
-  end
+    def optional_parts_type
+      @optional_parts_type ||=
+        "{" + optional_parts.map {|p| "#{p}?: OptionalRouteParameter"}.join(', ') + "}"
+    end
 
-  def json(string)
-    self.class.json(string)
-  end
+    protected
 
-  def build_params(required_parts)
-    params = required_parts + [LAST_OPTIONS_KEY]
-    params.join(", ")
-  end
+    def arguments(absolute)
+      absolute ? [*base_arguments, true] : base_arguments
+    end
 
-  # This function serializes Journey route into JSON structure
-  # We do not use Hash for human readable serialization
-  # And preffer Array serialization because it is shorter.
-  # Routes.js file will be smaller.
-  def serialize(spec, parent_spec=nil)
-    return nil unless spec
-    return spec.tr(':', '') if spec.is_a?(String)
-    result = serialize_spec(spec, parent_spec)
-    if parent_spec && result[1].is_a?(String)
-      result = [
-        # We encode node symbols as integer
-        # to reduce the routes.js file size
-        NODE_TYPES[:CAT],
-        serialize_spec(parent_spec),
-        result
-      ]
+    def match_configuration?
+      !match?(@configuration[:exclude]) && match?(@configuration[:include])
+    end
+
+    def base_name
+      @base_name ||= parent_route ?
+        [parent_route.name, route.name].join('_') : route.name
+    end
+
+    def parent_spec
+      parent_route&.path&.spec
+    end
+
+    def spec
+      route.path.spec
     end
-    result
-  end
 
-  def serialize_spec(spec, parent_spec=nil)
-    [
-      NODE_TYPES[spec.type],
-      serialize(spec.left, parent_spec),
-      spec.respond_to?(:right) && serialize(spec.right)
-    ]
+    def json(value)
+      JsRoutes.json(value)
+    end
+
+    def helper_name(absolute)
+      suffix = absolute ? :url : @configuration[:compact] ? nil : :path
+      apply_case(base_name, suffix)
+    end
+
+    def documentation
+      return nil unless @configuration[:documentation]
+      <<-JS
+/**
+ * Generates rails route to
+ * #{parent_spec}#{spec}#{documentation_params}
+ * @param {object | undefined} options
+ * @returns {string} route path
+ */
+JS
+    end
+
+    def required_parts
+      route.required_parts
+    end
+
+    def optional_parts
+      route.path.optional_names
+    end
+
+    def 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] ||= {}
+        if required_parts.include?(part)
+          # Using shortened keys to reduce js file size
+          parts_table[part][:r] = true
+        end
+      end
+      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
+      parts_table
+    end
+
+    def documentation_params
+      required_parts.map do |param|
+        "\n * @param {any} #{apply_case(param)}"
+      end.join
+    end
+
+    def match?(matchers)
+      Array(matchers).any? { |regex| base_name =~ regex }
+    end
+
+    def apply_case(*values)
+      value = values.compact.map(&:to_s).join('_')
+      @configuration[:camel_case] ? value.camelize(:lower) : value
+    end
+
+    # This function serializes Journey route into JSON structure
+    # We do not use Hash for human readable serialization
+    # And preffer Array serialization because it is shorter.
+    # Routes.js file will be smaller.
+    def serialize(spec, parent_spec=nil)
+      return nil unless spec
+      # Rails 4 globbing requires * removal
+      return spec.tr(':*', '') if spec.is_a?(String)
+
+      result = serialize_spec(spec, parent_spec)
+      if parent_spec && result[1].is_a?(String) && parent_spec.type != :SLASH
+        result = [
+          # We encode node symbols as integer
+          # to reduce the routes.js file size
+          NODE_TYPES[:CAT],
+          serialize_spec(parent_spec),
+          result
+        ]
+      end
+      result
+    end
+
+    def serialize_spec(spec, parent_spec = nil)
+      [
+        NODE_TYPES[spec.type],
+        serialize(spec.left, parent_spec),
+        spec.respond_to?(:right) ? serialize(spec.right) : nil
+      ].compact
+    end
   end
 end
-

data/lib/routes.d.ts

@@ -0,0 +1,79 @@
+/**
+ * File generated by js-routes RubyVariables.GEM_VERSION
+ * Based on Rails RubyVariables.RAILS_VERSION routes of RubyVariables.APP_CLASS
+ */
+declare type Optional<T> = {
+    [P in keyof T]?: T[P] | null;
+};
+declare type BaseRouteParameter = string | boolean | Date | number;
+declare type MethodRouteParameter = BaseRouteParameter | (() => BaseRouteParameter);
+declare type ModelRouteParameter = {
+    id: MethodRouteParameter;
+} | {
+    to_param: MethodRouteParameter;
+} | {
+    toParam: MethodRouteParameter;
+};
+declare type RequiredRouteParameter = BaseRouteParameter | ModelRouteParameter;
+declare type OptionalRouteParameter = undefined | null | RequiredRouteParameter;
+declare type QueryRouteParameter = OptionalRouteParameter | QueryRouteParameter[] | {
+    [k: string]: QueryRouteParameter;
+};
+declare type RouteParameters = Record<string, QueryRouteParameter>;
+declare type Serializable = Record<string, unknown>;
+declare type Serializer = (value: Serializable) => string;
+declare type RouteHelperExtras = {
+    requiredParams(): string[];
+    toString(): string;
+};
+declare type RequiredParameters<T extends number> = T extends 1 ? [RequiredRouteParameter] : T extends 2 ? [RequiredRouteParameter, RequiredRouteParameter] : T extends 3 ? [RequiredRouteParameter, RequiredRouteParameter, RequiredRouteParameter] : T extends 4 ? [
+    RequiredRouteParameter,
+    RequiredRouteParameter,
+    RequiredRouteParameter,
+    RequiredRouteParameter
+] : RequiredRouteParameter[];
+declare type RouteHelperOptions<T extends string> = RouteOptions & Optional<Record<T, OptionalRouteParameter>>;
+declare type RouteHelper<T extends number = number, U extends string = string> = ((...args: [...RequiredParameters<T>, RouteHelperOptions<U>]) => string) & RouteHelperExtras;
+declare type RouteHelpers = Record<string, RouteHelper>;
+declare type Configuration = {
+    prefix: string;
+    default_url_options: RouteParameters;
+    special_options_key: string;
+    serializer: Serializer;
+};
+interface RouterExposedMethods {
+    config(): Configuration;
+    configure(arg: Partial<Configuration>): Configuration;
+    serialize: Serializer;
+}
+declare type KeywordUrlOptions = Optional<{
+    host: string;
+    protocol: string;
+    subdomain: string;
+    port: string | number;
+    anchor: string;
+    trailing_slash: boolean;
+}>;
+declare type RouteOptions = KeywordUrlOptions & RouteParameters;
+declare type PartsTable = Record<string, {
+    r?: boolean;
+    d?: OptionalRouteParameter;
+}>;
+declare type ModuleType = "CJS" | "AMD" | "UMD" | "ESM" | "DTS" | "NIL";
+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;
+    WRAPPER: <T>(callback: T) => T;
+};
+declare const define: undefined | (((arg: unknown[], callback: () => unknown) => void) & {
+    amd?: unknown;
+});
+declare const module: {
+    exports: any;
+} | undefined;