js-routes 2.0.7 → 2.1.2

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: nil,
-    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,53 @@ 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 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 = 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,22 +112,28 @@ class JsRoutes
   class << self
     def setup(&block)
       configuration.tap(&block) if block
+      configuration.normalize_and_verify
     end
 
     def configuration
       @configuration ||= Configuration.new
     end
 
-    def generate(opts = {})
+    def generate(**opts)
       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(**opts)
+      generate(module_type: 'DTS', **opts)
+    end
+
+    def definitions!(file_name = nil, **opts)
+      file_name ||= configuration.file&.sub!(%r{\.(j|t)s\Z}, ".d.ts")
+      generate!(file_name, module_type: 'DTS', **opts)
     end
 
     def json(string)
@@ -123,48 +154,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 +216,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 +272,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 +287,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 +309,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 +383,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 +408,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
@@ -371,3 +457,5 @@ JS
     end
   end
 end
+
+require "js_routes/generators/webpacker"

data/lib/routes.d.ts

@@ -2,14 +2,38 @@
  * 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;
+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;
@@ -17,9 +41,6 @@ declare type Configuration = {
     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;
@@ -29,15 +50,16 @@ declare type KeywordUrlOptions = Optional<{
     host: string;
     protocol: string;
     subdomain: string;
-    port: string;
+    port: string | number;
     anchor: string;
     trailing_slash: boolean;
 }>;
+declare type RouteOptions = KeywordUrlOptions & RouteParameters;
 declare type PartsTable = Record<string, {
     r?: boolean;
-    d?: unknown;
+    d?: OptionalRouteParameter;
 }>;
-declare type ModuleType = "CJS" | "AMD" | "UMD" | "ESM";
+declare type ModuleType = "CJS" | "AMD" | "UMD" | "ESM" | "DTS" | "NIL";
 declare const RubyVariables: {
     PREFIX: string;
     DEPRECATED_GLOBBING_BEHAVIOR: boolean;
@@ -46,7 +68,7 @@ declare const RubyVariables: {
     SERIALIZER: Serializer;
     NAMESPACE: string;
     ROUTES_OBJECT: RouteHelpers;
-    MODULE_TYPE: ModuleType | null;
+    MODULE_TYPE: ModuleType;
     WRAPPER: <T>(callback: T) => T;
 };
 declare const define: undefined | (((arg: unknown[], callback: () => unknown) => void) & {

data/lib/routes.js

@@ -16,27 +16,35 @@ RubyVariables.WRAPPER((that) => {
         NodeTypes[NodeTypes["DOT"] = 8] = "DOT";
     })(NodeTypes || (NodeTypes = {}));
     const Root = that;
+    const isBroswer = typeof window !== "undefined";
     const ModuleReferences = {
         CJS: {
-            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-            define: (routes) => (module.exports = routes),
-            support: () => typeof module === "object",
+            define(routes) {
+                // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+                module.exports = routes;
+            },
+            isSupported() {
+                return typeof module === "object";
+            },
         },
         AMD: {
-            define: (routes) => 
-            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
-            define([], function () {
-                return routes;
-            }),
-            support: () => typeof define === "function" && !!define.amd,
+            define(routes) {
+                // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+                define([], function () {
+                    return routes;
+                });
+            },
+            isSupported() {
+                return typeof define === "function" && !!define.amd;
+            },
         },
         UMD: {
-            define: (routes) => {
-                if (ModuleReferences.AMD.support()) {
+            define(routes) {
+                if (ModuleReferences.AMD.isSupported()) {
                     ModuleReferences.AMD.define(routes);
                 }
                 else {
-                    if (ModuleReferences.CJS.support()) {
+                    if (ModuleReferences.CJS.isSupported()) {
                         try {
                             ModuleReferences.CJS.define(routes);
                         }
@@ -47,11 +55,36 @@ RubyVariables.WRAPPER((that) => {
                     }
                 }
             },
-            support: () => ModuleReferences.AMD.support() || ModuleReferences.CJS.support(),
+            isSupported() {
+                return (ModuleReferences.AMD.isSupported() ||
+                    ModuleReferences.CJS.isSupported());
+            },
         },
         ESM: {
-            define: () => null,
-            support: () => true,
+            define() {
+                // Module can only be defined using ruby code generation
+            },
+            isSupported() {
+                // Its impossible to check if "export" keyword is supported
+                return true;
+            },
+        },
+        NIL: {
+            define(routes) {
+                Utils.namespace(Root, RubyVariables.NAMESPACE, routes);
+            },
+            isSupported() {
+                return !!Root;
+            },
+        },
+        DTS: {
+            // Acts the same as ESM
+            define(routes) {
+                ModuleReferences.ESM.define(routes);
+            },
+            isSupported() {
+                return ModuleReferences.ESM.isSupported();
+            },
         },
     };
     class ParametersMissing extends Error {
@@ -62,7 +95,6 @@ RubyVariables.WRAPPER((that) => {
             this.name = ParametersMissing.name;
         }
     }
-    const DeprecatedGlobbingBehavior = RubyVariables.DEPRECATED_GLOBBING_BEHAVIOR;
     const UriEncoderSegmentRegex = /[^a-zA-Z0-9\-._~!$&'()*+,;=:@]/g;
     const ReservedOptions = [
         "anchor",
@@ -140,7 +172,7 @@ RubyVariables.WRAPPER((that) => {
         }
         looks_like_serialized_model(object) {
             return (this.is_object(object) &&
-                !object[this.configuration.special_options_key] &&
+                !(this.configuration.special_options_key in object) &&
                 ("id" in object || "to_param" in object || "toParam" in object));
         }
         path_identifier(object) {
@@ -298,9 +330,7 @@ RubyVariables.WRAPPER((that) => {
             }
         }
         encode_segment(segment) {
-            return segment.replace(UriEncoderSegmentRegex, function (str) {
-                return encodeURIComponent(str);
-            });
+            return segment.replace(UriEncoderSegmentRegex, (str) => encodeURIComponent(str));
         }
         is_optional_node(node) {
             return [NodeTypes.STAR, NodeTypes.SYMBOL, NodeTypes.CAT].includes(node);
@@ -342,7 +372,9 @@ RubyVariables.WRAPPER((that) => {
                 value = value.join("/");
             }
             const result = this.path_identifier(value);
-            return DeprecatedGlobbingBehavior ? result : encodeURI(result);
+            return RubyVariables.DEPRECATED_GLOBBING_BEHAVIOR
+                ? result
+                : encodeURI(result);
         }
         get_prefix() {
             const prefix = this.configuration.prefix;
@@ -386,32 +418,17 @@ RubyVariables.WRAPPER((that) => {
             port = port ? ":" + port : "";
             return protocol + "://" + subdomain + hostname + port;
         }
-        has_location() {
-            return this.is_not_nullable(window) && !!window.location;
-        }
         current_host() {
-            if (this.has_location()) {
-                return window.location.hostname;
-            }
-            else {
-                return null;
-            }
+            var _a;
+            return (isBroswer && ((_a = window === null || window === void 0 ? void 0 : window.location) === null || _a === void 0 ? void 0 : _a.hostname)) || "";
         }
         current_protocol() {
-            if (this.has_location() && window.location.protocol !== "") {
-                return window.location.protocol.replace(/:$/, "");
-            }
-            else {
-                return "http";
-            }
+            var _a, _b;
+            return ((isBroswer && ((_b = (_a = window === null || window === void 0 ? void 0 : window.location) === null || _a === void 0 ? void 0 : _a.protocol) === null || _b === void 0 ? void 0 : _b.replace(/:$/, ""))) || "http");
         }
         current_port() {
-            if (this.has_location() && window.location.port !== "") {
-                return window.location.port;
-            }
-            else {
-                return "";
-            }
+            var _a;
+            return (isBroswer && ((_a = window === null || window === void 0 ? void 0 : window.location) === null || _a === void 0 ? void 0 : _a.port)) || "";
         }
         is_object(value) {
             return (typeof value === "object" &&
@@ -449,7 +466,7 @@ RubyVariables.WRAPPER((that) => {
             return { ...this.configuration };
         }
         is_module_supported(name) {
-            return ModuleReferences[name].support();
+            return ModuleReferences[name].isSupported();
         }
         ensure_module_supported(name) {
             if (!this.is_module_supported(name)) {
@@ -457,9 +474,6 @@ RubyVariables.WRAPPER((that) => {
             }
         }
         define_module(name, module) {
-            if (!name) {
-                return;
-            }
             this.ensure_module_supported(name);
             ModuleReferences[name].define(module);
         }
@@ -484,9 +498,6 @@ RubyVariables.WRAPPER((that) => {
         },
         ...RubyVariables.ROUTES_OBJECT,
     };
-    Utils.namespace(Root, RubyVariables.NAMESPACE, result);
-    if (RubyVariables.MODULE_TYPE) {
-        Utils.define_module(RubyVariables.MODULE_TYPE, result);
-    }
+    Utils.define_module(RubyVariables.MODULE_TYPE, result);
     return result;
 })(this);