js-routes 2.0.8 → 2.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4f78bfaf0cba479c48245d0606cc10b262481e854f3fc82e7195a8b58548bf7a
-  data.tar.gz: 118cafad50e73568ba4b1758821af072194e9570178f1f9caf067785e9f5a0f5
+  metadata.gz: 242f329ab92abe8be4a2fa3790f72a3f161a6c2355b2392eae484a36a91d3a24
+  data.tar.gz: 120e5191eccfe3a8978c89ecb690a4f93a62279b249c58bc84b9273fe3e900c7
 SHA512:
-  metadata.gz: 95490b886a00861b0fe4a5e2419c67ec804bbb94a916edefe333acd2e0c94b407137952b97e4bf70d928ad1ebc5cf47333b5b5083f0dc227a43be2d3ebba7648
-  data.tar.gz: 666d2862d8a86e760176afdfdd62711a34202a4725d08609e5f5bf69732becb8829826ddeccaca0f8cacffa6a78022e69a05872ea26ce550e7352a9bfde0d0e4
+  metadata.gz: e1998fd3c98dff227905bfcd8a09be8bb6901d3da7293b60d1a6f11c3a2627c623372324a13010cbe425eb7b93781fa64db042c08e7b4123d4a50ec8bd8814b2
+  data.tar.gz: 5395c808f148bd39a99de0ce748cbb3a57c27620f048764bfcf6a455ac6ce2bbc43e282f4c660ba019f8d4b5df39a316728bb673d56b2667aecb667dde82d91b

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 ## master
 
+## v2.1.0
+
+* Support typescript defintions file aka `routes.d.ts`. See [Readme.md](./Readme.md#definitions) for more information.
+
 ## v2.0.8
 
 * Forbid usage of `namespace` option if `module_type` is not `nil`. [#281](https://github.com/railsware/js-routes/issues/281).

data/Readme.md

@@ -20,22 +20,26 @@ gem "js-routes"
 
 Run:
 
-```
+``` sh
 rake js:routes 
+# OR for typescript support
+rake js:routes:typescript
 ```
 
-Make routes available globally in `app/javascript/packs/application.js`: 
+
+Individual routes can be imported using:
 
 ``` javascript
-import * as Routes from 'routes';
-window.Routes = Routes;
+import {edit_post_path, posts_path} from 'routes';
+console.log(posts_path({format: 'json'})) // => "/posts.json"
+console.log(edit_post_path(1)) // => "/posts/1/edit"
 ```
 
-Individual routes can be imported using:
+Make routes available globally in `app/javascript/packs/application.js`: 
 
 ``` javascript
-import {edit_post_path} from 'routes';
-console.log(edit_post_path(1))
+import * as Routes from 'routes';
+window.Routes = Routes;
 ```
 
 **Note**: that this setup requires `rake js:routes` to be run each time routes file is updated.
@@ -91,6 +95,22 @@ import * as Routes from 'routes.js.erb';
 window.Routes = Routes;
 ```
 
+<div id='definitions'></div>
+
+#### Typescript Definitions
+
+JsRoutes has typescript support out of the box. In order to generate typscript definitions file (aka `routes.d.ts`) you can call:
+
+``` ruby
+JsRoutes.definitions!
+```
+
+Or create an automatic updates file at `app/javascript/routes.d.ts.erb`:
+
+``` erb
+<%= JsRoutes.defintions %>
+```
+
 #### Sprockets (Deprecated)
 
 If you are using [Sprockets](https://github.com/rails/sprockets-rails) you may configure js-routes in the following way.
@@ -147,7 +167,7 @@ Routes.config(); // current config
 Options to configure JavaScript file generator. These options are only available in Ruby context but not JavaScript.
 
 * `module_type` - JavaScript module type for generated code. [Article](https://dev.to/iggredible/what-the-heck-are-cjs-amd-umd-and-esm-ikm)
-  * Options: `ESM`, `UMD`, `CJS`, `AMD`, `nil`.
+  * Options: `ESM`, `UMD`, `CJS`, `AMD`, `DTS`, `nil`.
   * Default: `ESM`
   * `nil` option can be used in case you don't want generated code to export anything.
 * `documentation` - specifies if each route should be annotated with [JSDoc](https://jsdoc.app/) comment
@@ -324,9 +344,9 @@ Split your routes into multiple files related to each section of your website li
 
 ``` javascript
 // admin-routes.js.erb
-<%= JsRoutes.generate(include: /^admin_/)
+<%= JsRoutes.generate(include: /^admin_/) %>
 // app-routes.js.erb
-<%= JsRoutes.generate(exclude: /^admin_/)
+<%= JsRoutes.generate(exclude: /^admin_/) %>
 ```
 
 ## Advantages over alternatives

data/js-routes.gemspec

@@ -25,7 +25,7 @@ Gem::Specification.new do |s|
 
   s.add_runtime_dependency(%q<railties>, [">= 4"])
   s.add_development_dependency(%q<sprockets-rails>)
-  s.add_development_dependency(%q<rspec>, [">= 3.0.0"])
+  s.add_development_dependency(%q<rspec>, [">= 3.10.0"])
   s.add_development_dependency(%q<bundler>, [">= 1.1.0"])
   s.add_development_dependency(%q<appraisal>, [">= 0.5.2"])
   s.add_development_dependency(%q<bump>, [">= 0.10.0"])

data/lib/js_routes/version.rb

@@ -1,3 +1,3 @@
 class JsRoutes
-  VERSION = "2.0.8"
+  VERSION = "2.1.0"
 end

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,27 @@ class JsRoutes
       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
@@ -87,6 +86,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
@@ -116,12 +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
+
+    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)
@@ -142,48 +146,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
@@ -197,32 +208,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,7 +264,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)
@@ -248,6 +279,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 +301,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 +375,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

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

@@ -76,6 +76,15 @@ RubyVariables.WRAPPER((that) => {
                 return !!Root;
             },
         },
+        DTS: {
+            // Acts the same as ESM
+            define(routes) {
+                ModuleReferences.ESM.define(routes);
+            },
+            isSupported() {
+                return ModuleReferences.ESM.isSupported();
+            },
+        },
     };
     class ParametersMissing extends Error {
         constructor(...keys) {
@@ -162,7 +171,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) {
@@ -320,9 +329,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 +417,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 ((_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 ((_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 ((_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" &&

data/lib/routes.ts

@@ -3,15 +3,51 @@
  * Based on Rails RubyVariables.RAILS_VERSION routes of RubyVariables.APP_CLASS
  */
 
-type RouteParameter = unknown;
-type RouteParameters = Record<string, RouteParameter>;
-type Serializer = (value: unknown) => string;
-type RouteHelper = {
-  (...args: RouteParameter[]): string;
+type Optional<T> = { [P in keyof T]?: T[P] | null };
+type BaseRouteParameter = string | boolean | Date | number;
+type MethodRouteParameter = BaseRouteParameter | (() => BaseRouteParameter);
+type ModelRouteParameter =
+  | { id: MethodRouteParameter }
+  | { to_param: MethodRouteParameter }
+  | { toParam: MethodRouteParameter };
+type RequiredRouteParameter = BaseRouteParameter | ModelRouteParameter;
+type OptionalRouteParameter = undefined | null | RequiredRouteParameter;
+type QueryRouteParameter =
+  | OptionalRouteParameter
+  | QueryRouteParameter[]
+  | { [k: string]: QueryRouteParameter };
+type RouteParameters = Record<string, QueryRouteParameter>;
+
+type Serializable = Record<string, unknown>;
+type Serializer = (value: Serializable) => string;
+type RouteHelperExtras = {
   requiredParams(): string[];
   toString(): string;
 };
 
+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[];
+
+type RouteHelperOptions<T extends string> = RouteOptions &
+  Optional<Record<T, OptionalRouteParameter>>;
+
+type RouteHelper<T extends number = number, U extends string = string> = ((
+  ...args: [...RequiredParameters<T>, RouteHelperOptions<U>]
+) => string) &
+  RouteHelperExtras;
+
 type RouteHelpers = Record<string, RouteHelper>;
 
 type Configuration = {
@@ -21,7 +57,6 @@ type Configuration = {
   serializer: Serializer;
 };
 
-type Optional<T> = { [P in keyof T]?: T[P] | null };
 interface RouterExposedMethods {
   config(): Configuration;
   configure(arg: Partial<Configuration>): Configuration;
@@ -32,14 +67,16 @@ type KeywordUrlOptions = Optional<{
   host: string;
   protocol: string;
   subdomain: string;
-  port: string;
+  port: string | number;
   anchor: string;
   trailing_slash: boolean;
 }>;
 
-type PartsTable = Record<string, { r?: boolean; d?: unknown }>;
+type RouteOptions = KeywordUrlOptions & RouteParameters;
 
-type ModuleType = "CJS" | "AMD" | "UMD" | "ESM" | "NIL";
+type PartsTable = Record<string, { r?: boolean; d?: OptionalRouteParameter }>;
+
+type ModuleType = "CJS" | "AMD" | "UMD" | "ESM" | "DTS" | "NIL";
 
 declare const RubyVariables: {
   PREFIX: string;
@@ -93,7 +130,7 @@ RubyVariables.WRAPPER(
 
     const Root = that;
     type ModuleDefinition = {
-      define: (routes: unknown) => void;
+      define: (routes: RouterExposedMethods) => void;
       isSupported: () => boolean;
     };
     const ModuleReferences: Record<ModuleType, ModuleDefinition> = {
@@ -155,6 +192,15 @@ RubyVariables.WRAPPER(
           return !!Root;
         },
       },
+      DTS: {
+        // Acts the same as ESM
+        define(routes) {
+          ModuleReferences.ESM.define(routes);
+        },
+        isSupported() {
+          return ModuleReferences.ESM.isSupported();
+        },
+      },
     };
 
     class ParametersMissing extends Error {
@@ -225,16 +271,16 @@ RubyVariables.WRAPPER(
         return result.join("&");
       }
 
-      serialize(object: unknown): string {
+      serialize(object: Serializable): string {
         return this.configuration.serializer(object);
       }
 
       extract_options(
         number_of_params: number,
-        args: RouteParameter[]
+        args: OptionalRouteParameter[]
       ): {
-        args: RouteParameter[];
-        options: KeywordUrlOptions & RouteParameters;
+        args: OptionalRouteParameter[];
+        options: RouteOptions;
       } {
         const last_el = args[args.length - 1];
         if (
@@ -247,32 +293,27 @@ RubyVariables.WRAPPER(
           }
           return {
             args: args.slice(0, args.length - 1),
-            options: last_el as KeywordUrlOptions & RouteParameters,
+            options: (last_el as any) as RouteOptions,
           };
         } else {
           return { args, options: {} };
         }
       }
 
-      looks_like_serialized_model(
-        object: any
-      ): object is
-        | { id: unknown }
-        | { to_param: unknown }
-        | { toParam: unknown } {
+      looks_like_serialized_model(object: any): object is ModelRouteParameter {
         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: unknown): string {
+      path_identifier(object: QueryRouteParameter): string {
         const result = this.unwrap_path_identifier(object);
         return this.is_nullable(result) || result === false ? "" : "" + result;
       }
 
-      unwrap_path_identifier(object: any): unknown {
+      unwrap_path_identifier(object: QueryRouteParameter): unknown {
         let result: any = object;
         if (!this.is_object(object)) {
           return object;
@@ -293,7 +334,7 @@ RubyVariables.WRAPPER(
         parts: string[],
         required_params: string[],
         default_options: RouteParameters,
-        call_arguments: RouteParameter[]
+        call_arguments: OptionalRouteParameter[]
       ): {
         keyword_parameters: KeywordUrlOptions;
         query_parameters: RouteParameters;
@@ -357,7 +398,7 @@ RubyVariables.WRAPPER(
         default_options: RouteParameters,
         route: RouteTree,
         absolute: boolean,
-        args: RouteParameter[]
+        args: OptionalRouteParameter[]
       ): string {
         const {
           keyword_parameters,
@@ -467,9 +508,9 @@ RubyVariables.WRAPPER(
       }
 
       encode_segment(segment: string): string {
-        return segment.replace(UriEncoderSegmentRegex, function (str) {
-          return encodeURIComponent(str);
-        });
+        return segment.replace(UriEncoderSegmentRegex, (str) =>
+          encodeURIComponent(str)
+        );
       }
 
       is_optional_node(node: NodeTypes): boolean {
@@ -550,7 +591,7 @@ RubyVariables.WRAPPER(
             default_options[part] = value;
           }
         }
-        const result = (...args: RouteParameter[]): string => {
+        const result = (...args: OptionalRouteParameter[]): string => {
           return this.build_route(
             parts,
             required_params,
@@ -564,7 +605,7 @@ RubyVariables.WRAPPER(
         result.toString = () => {
           return this.build_path_spec(route_spec);
         };
-        return result;
+        return result as any;
       }
 
       route_url(route_defaults: KeywordUrlOptions): string {
@@ -583,31 +624,16 @@ RubyVariables.WRAPPER(
         return protocol + "://" + subdomain + hostname + port;
       }
 
-      has_location(): boolean {
-        return this.is_not_nullable(window) && !!window.location;
-      }
-
-      current_host(): string | null {
-        if (this.has_location()) {
-          return window.location.hostname;
-        } else {
-          return null;
-        }
+      current_host(): string {
+        return window?.location?.hostname || "";
       }
 
       current_protocol(): string {
-        if (this.has_location() && window.location.protocol !== "") {
-          return window.location.protocol.replace(/:$/, "");
-        } else {
-          return "http";
-        }
+        return window?.location?.protocol?.replace(/:$/, "") || "http";
       }
+
       current_port(): string {
-        if (this.has_location() && window.location.port !== "") {
-          return window.location.port;
-        } else {
-          return "";
-        }
+        return window?.location?.port || "";
       }
 
       is_object(value: unknown): value is Record<string, unknown> {
@@ -694,7 +720,7 @@ RubyVariables.WRAPPER(
       config: (): Configuration => {
         return Utils.config();
       },
-      serialize: (object: unknown): string => {
+      serialize: (object: Serializable): string => {
         return Utils.serialize(object);
       },
       ...RubyVariables.ROUTES_OBJECT,

data/lib/tasks/js_routes.rake

@@ -1,8 +1,14 @@
 namespace :js do
-  desc "Make a js file that will have functions that will return restful routes/urls."
+  desc "Make a js file with all rails route URL helpers"
   task routes: :environment do
     require "js-routes"
-
     JsRoutes.generate!
   end
+
+  namespace :routes do
+    desc "Make a js file with all rails route URL helpers and typescript definitions for them"
+    task typescript: "js:routes" do
+      JsRoutes.definitions!
+    end
+  end
 end

data/spec/js_routes/module_types/dts/routes.spec.d.ts

@@ -0,0 +1,114 @@
+/**
+ * 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;
+export const configure: RouterExposedMethods['configure'];
+
+export const config: RouterExposedMethods['config'];
+
+export const serialize: RouterExposedMethods['serialize'];
+
+/**
+ * Generates rails route to
+ * /inboxes/:inbox_id/messages/:message_id/attachments/:id(.:format)
+ * @param {any} inbox_id
+ * @param {any} message_id
+ * @param {any} id
+ * @param {object | undefined} options
+ * @returns {string} route path
+ */
+export const inbox_message_attachment_path: ((
+  inbox_id: RequiredRouteParameter,
+  message_id: RequiredRouteParameter,
+  id: RequiredRouteParameter,
+  options?: {format?: OptionalRouteParameter} & RouteOptions
+) => string) & RouteHelperExtras;
+
+/**
+ * Generates rails route to
+ * /inboxes(.:format)
+ * @param {object | undefined} options
+ * @returns {string} route path
+ */
+export const inboxes_path: ((
+  options?: {format?: OptionalRouteParameter} & RouteOptions
+) => string) & RouteHelperExtras;
+
+// By some reason this line prevents all types in a file
+// from being automatically exported
+export {};

data/spec/js_routes/module_types/dts/test.spec.ts

@@ -0,0 +1,56 @@
+import {
+  inbox_message_attachment_path,
+  inboxes_path,
+  serialize,
+  configure,
+  config,
+} from "./routes.spec";
+
+// Route Helpers
+inboxes_path();
+inboxes_path({
+  locale: "en",
+  search: {
+    q: "ukraine",
+    page: 3,
+    keywords: ["large", "small", { advanced: true }],
+  },
+});
+
+inbox_message_attachment_path(1, "2", true);
+inbox_message_attachment_path(
+  { id: 1 },
+  { to_param: () => "2" },
+  { toParam: () => true }
+);
+inbox_message_attachment_path(1, "2", true, { format: "json" });
+inboxes_path.toString();
+inboxes_path.requiredParams();
+
+// serialize test
+const SerializerArgument = {
+  locale: "en",
+  search: {
+    q: "ukraine",
+    page: 3,
+    keywords: ["large", "small", { advanced: true }],
+  },
+};
+serialize(SerializerArgument);
+config().serializer(SerializerArgument);
+
+// configure test
+configure({
+  default_url_options: { port: 1, host: null },
+  prefix: "",
+  special_options_key: "_options",
+  serializer: (value) => JSON.stringify(value),
+});
+
+// config tests
+const Config = config();
+console.log(
+  Config.prefix,
+  Config.default_url_options,
+  Config.special_options_key
+);

data/spec/js_routes/module_types/dts_spec.rb

@@ -0,0 +1,111 @@
+
+require "active_support/core_ext/string/strip"
+require "fileutils"
+require "open3"
+require "spec_helper"
+
+describe JsRoutes, "compatibility with DTS"  do
+
+  OPTIONS = {module_type: 'DTS', include: [/^inboxes$/, /^inbox_message_attachment$/]}
+  let(:extra_options) do
+    {}
+  end
+
+  let(:generated_js) do
+    JsRoutes.generate({**OPTIONS, **extra_options})
+  end
+
+  context "when file is generated" do
+    let(:dir_name) do
+       File.expand_path(__dir__ + "/dts")
+    end
+
+    let(:file_name) do
+      dir_name + "/routes.spec.d.ts"
+    end
+
+    before do
+      FileUtils.mkdir_p(dir_name)
+      File.write(file_name, generated_js)
+    end
+
+    it "has no compile errors", :slow do
+      command = "yarn tsc --strict --noEmit -p spec/tsconfig.json"
+      stdout, stderr, status = Open3.capture3(command)
+      expect(stderr).to eq("")
+      expect(stdout).to include("Done in ")
+      expect(status).to eq(0)
+    end
+  end
+
+  context "when camel case is enabled" do
+    let(:extra_options) { {camel_case: true} }
+
+    it "camelizes route name and arguments" do
+
+      expect(generated_js).to include(<<-DOC.rstrip)
+/**
+ * Generates rails route to
+ * /inboxes/:inbox_id/messages/:message_id/attachments/:id(.:format)
+ * @param {any} inboxId
+ * @param {any} messageId
+ * @param {any} id
+ * @param {object | undefined} options
+ * @returns {string} route path
+ */
+export const inboxMessageAttachmentPath: ((
+  inboxId: RequiredRouteParameter,
+  messageId: RequiredRouteParameter,
+  id: RequiredRouteParameter,
+  options?: {format?: OptionalRouteParameter} & RouteOptions
+) => string) & RouteHelperExtras;
+DOC
+    end
+  end
+
+  it "exports route helpers" do
+    expect(generated_js).to include(<<-DOC.rstrip)
+/**
+ * Generates rails route to
+ * /inboxes(.:format)
+ * @param {object | undefined} options
+ * @returns {string} route path
+ */
+export const inboxes_path: ((
+  options?: {format?: OptionalRouteParameter} & RouteOptions
+) => string) & RouteHelperExtras;
+DOC
+    expect(generated_js).to include(<<-DOC.rstrip)
+/**
+ * Generates rails route to
+ * /inboxes/:inbox_id/messages/:message_id/attachments/:id(.:format)
+ * @param {any} inbox_id
+ * @param {any} message_id
+ * @param {any} id
+ * @param {object | undefined} options
+ * @returns {string} route path
+ */
+export const inbox_message_attachment_path: ((
+  inbox_id: RequiredRouteParameter,
+  message_id: RequiredRouteParameter,
+  id: RequiredRouteParameter,
+  options?: {format?: OptionalRouteParameter} & RouteOptions
+) => string) & RouteHelperExtras
+DOC
+  end
+
+  it "exports utility methods" do
+    expect(generated_js).to include("export const serialize: RouterExposedMethods['serialize'];")
+  end
+
+  it "prevents all types from automatic export" do
+    expect(generated_js).to include("export {};")
+  end
+
+  describe "compiled javascript asset" do
+    subject { ERB.new(File.read("app/assets/javascripts/js-routes.js.erb")).result(binding) }
+    it "should have js routes code" do
+      is_expected.to include("export const inbox_message_path = __jsr.r(")
+    end
+  end
+end

data/spec/js_routes/zzz_last_post_rails_init_spec.rb

@@ -5,7 +5,7 @@
 require 'spec_helper'
 require "fileutils"
 
-describe "after Rails initialization" do
+describe "after Rails initialization", :slow do
   NAME = Rails.root.join('app', 'assets', 'javascripts', 'routes.js').to_s
 
   def sprockets_v3?
@@ -122,7 +122,7 @@ describe "after Rails initialization" do
   end
 end
 
-describe "JSRoutes thread safety" do
+describe "JSRoutes thread safety", :slow do
   before do
     begin
       Rails.application.initialize!

data/spec/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": "../tsconfig.json",
+  "include": ["./**/*.spec.ts"]
+}

data/tsconfig.json

@@ -3,14 +3,10 @@
     "target": "es2019",
     "lib": ["es2020", "dom"],
     "module": "commonjs",
-    "outDir": "lib",
     "sourceMap": false,
     "declaration": true,
     "allowSyntheticDefaultImports": true,
-    "resolveJsonModule": true,
-    "typeRoots": ["node_modules/@types", "./@types"],
-
-    "strict": true,
+    "resolveJsonModule": false,
     "strictNullChecks": true,
     "noImplicitAny": true,
     "noImplicitThis": true,
@@ -22,11 +18,11 @@
     "forceConsistentCasingInFileNames": true,
     "emitDecoratorMetadata": true,
     "experimentalDecorators": true
+
   },
   "ts-node": {
     "files": true,
     "transpileOnly": false
   },
-  "include": ["./**/*.ts", "lib/**/*.json", "./**/*.tsx"],
-  "exclude": ["node_modules", "**/thorn", "**/support", "**/tmp"]
+  "include": ["lib/*.ts"]
 }

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: js-routes
 version: !ruby/object:Gem::Version
-  version: 2.0.8
+  version: 2.1.0
 platform: ruby
 authors:
 - Bogdan Gusiev
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-07-21 00:00:00.000000000 Z
+date: 2021-09-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -44,14 +44,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.0.0
+        version: 3.10.0
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.0.0
+        version: 3.10.0
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -183,6 +183,9 @@ files:
 - spec/js_routes/default_serializer_spec.rb
 - spec/js_routes/module_types/amd_spec.rb
 - spec/js_routes/module_types/cjs_spec.rb
+- spec/js_routes/module_types/dts/routes.spec.d.ts
+- spec/js_routes/module_types/dts/test.spec.ts
+- spec/js_routes/module_types/dts_spec.rb
 - spec/js_routes/module_types/esm_spec.rb
 - spec/js_routes/module_types/umd_spec.rb
 - spec/js_routes/options_spec.rb
@@ -190,6 +193,7 @@ files:
 - spec/js_routes/zzz_last_post_rails_init_spec.rb
 - spec/spec_helper.rb
 - spec/support/routes.rb
+- spec/tsconfig.json
 - tsconfig.json
 - yarn.lock
 homepage: http://github.com/railsware/js-routes