js-routes 2.0.6 → 2.1.1

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,63 +2,78 @@
  * 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 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;
-};
-declare type Optional<T> = {
-  [P in keyof T]?: T[P] | null;
+    prefix: string;
+    default_url_options: RouteParameters;
+    special_options_key: string;
+    serializer: Serializer;
 };
 interface RouterExposedMethods {
-  config(): Configuration;
-  configure(arg: Partial<Configuration>): Configuration;
-  serialize: Serializer;
+    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;
+    host: string;
+    protocol: string;
+    subdomain: string;
+    port: string | number;
+    anchor: string;
+    trailing_slash: boolean;
 }>;
-declare type PartsTable = Record<
-  string,
-  {
+declare type RouteOptions = KeywordUrlOptions & RouteParameters;
+declare type PartsTable = Record<string, {
     r?: boolean;
-    d?: unknown;
-  }
->;
-declare type ModuleType = "CJS" | "AMD" | "UMD" | "ESM";
+    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 | null;
-  WRAPPER: <T>(callback: T) => T;
+    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;
+declare const define: undefined | (((arg: unknown[], callback: () => unknown) => void) & {
+    amd?: unknown;
+});
+declare const module: {
+    exports: any;
+} | undefined;