js-routes 2.0.8 → 2.2.0

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
@@ -80,6 +58,31 @@ class JsRoutes
       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
@@ -87,6 +90,10 @@ class JsRoutes
 
     protected
 
+    def default_file_name
+      dts? ? "routes.d.ts" : "routes.js"
+    end
+
     def normalize
       self.module_type = module_type&.upcase || 'NIL'
     end
@@ -112,16 +119,21 @@ class JsRoutes
       @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{(\.d)?\.(j|t)s\Z}, ".d.ts")
+      generate!(file_name, module_type: 'DTS', **opts)
     end
 
     def json(string)
@@ -139,51 +151,58 @@ class JsRoutes
 
   def generate
     # Ensure routes are loaded. If they're not, load them.
-    if named_routes.to_a.empty? && application.respond_to?(:reload_routes!)
+    if named_routes.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
@@ -197,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|
@@ -233,13 +272,14 @@ class JsRoutes
     end
   end
 
-  def get_app_from_route(route)
+  def app_from_route(route)
+    app = route.app
     # 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
+    if app.respond_to?(:app) && app.respond_to?(:constraints)
+      app.app
     else
-      route.app
+      app
     end
   end
 
@@ -248,6 +288,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)
@@ -257,24 +310,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
 
-    protected
+    def helper_types
+      return [] unless match_configuration?
+      @configuration[:url_links] ? [true, false] : [false]
+    end
 
     def body(absolute)
-      "__jsr.r(#{arguments(absolute).map{|a| json(a)}.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 + [true] : base_arguments
+      absolute ? [*base_arguments, true] : base_arguments
     end
 
     def match_configuration?
@@ -319,6 +384,10 @@ JS
       route.required_parts
     end
 
+    def optional_parts
+      route.path.optional_names
+    end
+
     def base_arguments
       @base_arguments ||= [parts_table, serialize(spec, parent_spec)]
     end
@@ -388,4 +457,10 @@ JS
       ].compact
     end
   end
+  module Generators
+  end
 end
+
+require "js_routes/middleware"
+require "js_routes/generators/webpacker"
+require "js_routes/generators/middleware"

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" | "NIL";
+declare type ModuleType = "CJS" | "AMD" | "UMD" | "ESM" | "DTS" | "NIL";
 declare const RubyVariables: {
     PREFIX: string;
     DEPRECATED_GLOBBING_BEHAVIOR: boolean;

data/lib/routes.js

@@ -16,6 +16,7 @@ RubyVariables.WRAPPER((that) => {
         NodeTypes[NodeTypes["DOT"] = 8] = "DOT";
     })(NodeTypes || (NodeTypes = {}));
     const Root = that;
+    const isBroswer = typeof window !== "undefined";
     const ModuleReferences = {
         CJS: {
             define(routes) {
@@ -73,7 +74,16 @@ RubyVariables.WRAPPER((that) => {
                 Utils.namespace(Root, RubyVariables.NAMESPACE, routes);
             },
             isSupported() {
-                return !!Root;
+                return !RubyVariables.NAMESPACE || !!Root;
+            },
+        },
+        DTS: {
+            // Acts the same as ESM
+            define(routes) {
+                ModuleReferences.ESM.define(routes);
+            },
+            isSupported() {
+                return ModuleReferences.ESM.isSupported();
             },
         },
     };
@@ -162,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) {
@@ -195,7 +205,9 @@ RubyVariables.WRAPPER((that) => {
                 throw new Error("Too many parameters provided for path");
             }
             let use_all_parts = args.length > required_params.length;
-            const parts_options = {};
+            const parts_options = {
+                ...this.configuration.default_url_options,
+            };
             for (const key in options) {
                 const value = options[key];
                 if (!hasProp(options, key))
@@ -320,9 +332,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);
@@ -410,32 +420,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" &&
@@ -453,7 +448,7 @@ RubyVariables.WRAPPER((that) => {
         namespace(object, namespace, routes) {
             const parts = (namespace === null || namespace === void 0 ? void 0 : namespace.split(".")) || [];
             if (parts.length === 0) {
-                return routes;
+                return;
             }
             for (let index = 0; index < parts.length; index++) {
                 const part = parts[index];
@@ -461,7 +456,7 @@ RubyVariables.WRAPPER((that) => {
                     object = object[part] || (object[part] = {});
                 }
                 else {
-                    return (object[part] = routes);
+                    object[part] = routes;
                 }
             }
         }