js-routes 2.3.7 → 2.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8e1323cccad426e331d7f99923e967b09d06e028ec3f2665798dad91ff5ce582
-  data.tar.gz: 4ddb07ef468133b25d7ace1313b948f689a77a1c576e3102e88ff2b87f82a5c5
+  metadata.gz: 80c67cfe21ee9772f3912537cec0994797a76128083d495d9963381888e7833c
+  data.tar.gz: b2d63fcf45117749fa00be661b94fcd8a606ac711bdbcfd1bc2699be87d7c407
 SHA512:
-  metadata.gz: 9840b6fa125bec3de173ce942e7daae8cac4de026d424d70a4bb82d67d9cf075d050c182c02fadef9d5c64a989599dd3a0cbc59197652d836b44f3452588bad2
-  data.tar.gz: 449669e3e6719f2c1ee22bd1b6b7bfaa34ca2821f7d6050563d76f43781c8e4efc8c1d6e986443007451550002abad649e6dc6bdf10629ba683be3ccf3f3f1ee
+  metadata.gz: abebd07a033d7046989e71b1fc00aad559c1973f9eadaf0f93df25057bd01d1c3cd9bca2447d272c2c56ccef10a9803d6ae81479999be7ed315eefeb7c0211e1
+  data.tar.gz: c000eb635b4b77167cb04df8b3b691528cebe78ce557d8bcab75e95c420e033b79d066e3f8135a7b04f5b899c964512e741b5c0fc0a30c99692d1b2ebb76b883

data/CHANGELOG.md

@@ -2,6 +2,118 @@
 
 ## Pending
 
+## [2.4.1]
+
+### Fix camelCase TypeScript definitions for optional parameters
+
+Fix a bug introduced in 2.4.0 where `camel_case: true` caused TypeScript type definitions to advertise camelCase keys for optional route parameters while the JavaScript runtime still required snake_case. Fixes [#351](https://github.com/railsware/js-routes/issues/351).
+
+Optional parameter names in `.d.ts` output now match what the runtime actually accepts:
+
+```typescript
+// Before (broken): type advertised perPage but runtime required per_page
+itemsPath({ perPage: 20 })   // → "/items?perPage=20"  ✗ (silently wrong)
+itemsPath({ per_page: 20 })  // → "/items/20"          ✓ (worked but type was misleading)
+
+// After (fixed): type and runtime agree on snake_case
+itemsPath({ per_page: 20 })  // → "/items/20"          ✓
+```
+
+## [2.4.0]
+
+### Package mode
+
+Add `package` option and `JsRoutes.package` / `JsRoutes.package!` API for sharing a single Router runtime across multiple route files.
+
+**Why:** When an app generates several ESM route files (e.g. one per domain or engine), each file previously embedded the full js-routes runtime (~10 KB minified). With `package`, the runtime is extracted into one `router.js` and every route file imports it — the runtime is downloaded and parsed only once.
+
+Generate the shared router package (no route definitions, just the runtime):
+
+``` ruby
+# config/initializers/js_routes.rb
+JsRoutes.package!                   # writes app/javascript/router.js
+# or with a custom path:
+JsRoutes.package!("shared/router.js")
+```
+
+Generate consumer route files that import from it:
+
+``` ruby
+JsRoutes.generate!(
+  "app/javascript/admin_routes.js",
+  typed: true,
+  package: "./router.js",   # or package: true for the default path
+  include: /\Aadmin_/
+)
+
+JsRoutes.generate!(
+  "app/javascript/api_routes.js",
+  typed: true,
+  package: "./router.js",
+  include: /\Aapi_/
+)
+```
+
+Or share one configuration block:
+
+``` ruby
+JsRoutes.setup do |c|
+  c.module_type = "ESM"
+  c.package     = "./router.js"   # all generated files import the same runtime
+end
+
+JsRoutes.package!                 # router.js  — runtime only
+JsRoutes.generate!                # routes.js  — route helpers only
+```
+
+`package: true` is a shorthand for `package: "./router.js"`.
+
+### `include_undefined_query_parameters` option
+
+Add `include_undefined_query_parameters` configuration option. Fixes [#345](https://github.com/railsware/js-routes/issues/345).
+
+JavaScript uses `undefined` to mean "not provided," but js-routes previously treated `undefined` query object values the same as `null`. With Rails 8.1's nil parameter handling, that causes `undefined` values to appear as bare keys like `?foo`.
+
+* Set it to `false` to omit object properties whose value is `undefined`, matching typical JavaScript semantics. This is the recommended value for new and upgrading apps.
+* Set it to `true` only when the application depends on serializing `undefined` as Rails `nil` (legacy behavior).
+* Explicit `null` values continue to serialize as Rails `nil` in all cases.
+* When unset, the legacy behavior is preserved and a deprecation warning is emitted so apps can opt in deliberately.
+
+### JavaScript reserved word escaping
+
+Escape JavaScript reserved words in route helper names and TypeScript parameter names. Fixes broken `.d.ts` output when a route segment name collides with a JS keyword.
+
+Given a route like:
+
+``` ruby
+scope "/returns/:return" do
+  resources :objects, only: [:show]
+end
+```
+
+The generated `.d.ts` now uses `return_` instead of the invalid `return`:
+
+``` typescript
+export const object_path: ((
+  return_: RequiredRouteParameter,
+  id: RequiredRouteParameter,
+  options?: RouteOptions
+) => string) & RouteHelperExtras;
+```
+
+In `compact` mode, if the short helper name would itself be a reserved word, the `_path` suffix is kept as a fallback:
+
+``` ruby
+# route named :return with compact: true
+return_path(…)  # kept — `return` alone would be invalid
+```
+
+### Bug Fixes
+
+* Fix `generate!` with `typed: true` raising when `package:` option is set. The `package:` option is now stripped before being forwarded to `definitions!`, which only generates type declarations and has no use for it.
+* Support `config.javascript_path` Rails configuration. Fixes [#344](https://github.com/railsware/js-routes/issues/344).
+* Do not emit a deprecation warning when `prefix` is set to an empty string. Fixes [#340](https://github.com/railsware/js-routes/issues/340).
+
 ## [2.3.7]
 
 * Obfuscate assignment to module.exports in order to prevent warnings in javascript bundlers, like Vite. Fixes [#337](https://github.com/railsware/js-routes/issues/337).

data/Readme.md

@@ -4,7 +4,16 @@
 
 <img src="/logo.webp" alt="Logo" width="200" height="200">
 
-Generates javascript file that defines all Rails named routes as javascript helpers:
+Generates javascript file that defines all Rails named routes as javascript functions:
+
+``` ruby
+Rails.application.routes.draw do
+  root "home#index"
+  namespace :api do
+    resources :users
+  end
+end
+```
 
 ``` js
 import { root_path, api_user_path } from './routes';
@@ -15,6 +24,12 @@ api_user_path(25, include_profile: true, format: 'json') // => /api/users/25.jso
 
 [More Examples](#usage)
 
+## Philosophy
+
+1. Move fast, break nothing.
+2. Minimum invention, maximum compatiblity with Rails.
+3. Ready for your advanced architecture.
+
 ## Intallation
 
 Your Rails Gemfile:
@@ -240,6 +255,31 @@ which will cause any `JsRoutes` instance to generate defintions instead of route
 
 <div id="sprockets"></div>
 
+<div id="package"></div>
+
+#### Using shared package
+
+Some setups may benefit from splitting routes into multiple files with the core js-routes utils shared between these files. This can be helpful for codebases that have a large number of routes and can improve tree shaking. This is only available when the `module_type` is set to `ESM`.
+
+```ruby
+class AdvancedJsRoutesMiddleware < JsRoutes::Middleware
+  def regenerate
+    JsRoutes.package!
+
+    JsRoutes.generate!(
+      "admin_routes.js",
+      include: /^admin_/,
+      package: './router.js'
+    )
+    JsRoutes.generate!(
+      "api_routes.js",
+      include: /^api_/,
+      package: './router.js'
+    )
+  end
+end
+```
+
 ### Sprockets (Deprecated)
 
 If you are using [Sprockets](https://github.com/rails/sprockets-rails) you may configure js-routes in the following way.
@@ -328,6 +368,10 @@ Options to configure JavaScript file generator. These options are only available
   * Default: `-> { Rails.application }`
 * `file` - a file location where generated routes are stored
   * Default: `app/javascript/routes.js` if setup with Webpacker, otherwise `app/assets/javascripts/routes.js` if setup with Sprockets.
+* `package` - specify where the shared package will be imported from. e.g. `'./router.js'`.
+  * Generate the shared package with `package!`.
+  * See [Using shared package](#package).
+  * Default: `nil`
 * `optional_definition_params` - make all route paramters in definition optional
   * See [related compatibility issue](#optional-definition-params)
   * Default: `false`
@@ -359,6 +403,12 @@ Options to configure routes formatting. These options are available both in Ruby
   * Default: `nil`. Uses built-in serializer compatible with Rails
   * Example: `jQuery.param` - use jQuery's serializer algorithm. You can attach serialize function from your favorite AJAX framework.
   * Example: `function (object) { ... }` - use completely custom serializer of your application.
+* `include_undefined_query_parameters` - when using the built-in serializer, include query object properties whose value is `undefined` as Rails `nil` instead of omitting them.
+  * Default: `nil`. Preserves legacy serialization and emits a warning until this option is set explicitly.
+  * New generated initializers set this option to `false`.
+  * Set this option to `false` to omit `undefined` query object properties.
+  * Compatible with Rails nil query serialization: explicit `null` still serializes as Rails `nil`, including the Rails 8.1 bare-key behavior.
+  * Custom `serializer` functions remain responsible for their own `undefined` handling.
 * `special_options_key` - a special key that helps JsRoutes to destinguish serialized model from options hash
   * This option exists because JS doesn't provide a difference between an object and a hash
   * Default: `_options`

data/lib/js_routes/configuration.rb

@@ -18,6 +18,12 @@ module JsRoutes
     attr_accessor :include
     sig { returns(FileName) }
     attr_accessor :file
+    sig { returns(T.nilable(String)) }
+    attr_reader :package
+
+    def package=(value)
+      @package = value == true ? "./router.js" : (value == false ? nil : value)
+    end
     sig { returns(Prefix) }
     attr_reader :prefix
     sig { returns(T::Boolean) }
@@ -26,6 +32,8 @@ module JsRoutes
     attr_accessor :camel_case
     sig { returns(Options) }
     attr_accessor :default_url_options
+    sig { returns(T.nilable(T::Boolean)) }
+    attr_accessor :include_undefined_query_parameters
     sig { returns(T::Boolean) }
     attr_accessor :compact
     sig { returns(T.nilable(String)) }
@@ -42,6 +50,10 @@ module JsRoutes
     attr_accessor :optional_definition_params
     sig { returns(BannerCaller) }
     attr_accessor :banner
+    sig { returns(T::Boolean) }
+    attr_accessor :deprecated_false_parameter_behavior
+    sig { returns(T::Boolean) }
+    attr_accessor :deprecated_nil_query_parameter_behavior
 
     sig {params(attributes: T.nilable(Options)).void }
     def initialize(attributes = nil)
@@ -53,6 +65,7 @@ module JsRoutes
       @url_links = T.let(false, T::Boolean)
       @camel_case = T.let(false, T::Boolean)
       @default_url_options = T.let(T.unsafe({}), Options)
+      @include_undefined_query_parameters = T.let(nil, T.nilable(T::Boolean))
       @compact = T.let(false, T::Boolean)
       @serializer = T.let(nil, T.nilable(String))
       @special_options_key = T.let("_options", Literal)
@@ -61,6 +74,15 @@ module JsRoutes
       @documentation = T.let(true, T::Boolean)
       @optional_definition_params = T.let(false, T::Boolean)
       @banner = T.let(default_banner, BannerCaller)
+      @package = T.let(nil, T.nilable(String))
+      @deprecated_false_parameter_behavior = T.let(
+        defined?(Rails) ? JsRoutes::Utils.rails_version < Gem::Version.new('7.0.0') : false,
+        T::Boolean
+      )
+      @deprecated_nil_query_parameter_behavior = T.let(
+        defined?(Rails) ? JsRoutes::Utils.rails_version < Gem::Version.new('8.1.0') : false,
+        T::Boolean
+      )
 
       return unless attributes
       assign(attributes)
@@ -92,7 +114,7 @@ module JsRoutes
     end
 
     def prefix=(value)
-      JsRoutes::Utils.deprecator.warn("JsRoutes configuration prefix is deprecated in favor of default_url_options.script_name.")
+      JsRoutes::Utils.deprecator.warn("JsRoutes configuration prefix is deprecated in favor of default_url_options.script_name.") unless value.blank?
       @prefix = value
     end
 
@@ -111,11 +133,20 @@ module JsRoutes
       self.module_type === 'DTS'
     end
 
+    sig {returns(T::Boolean)}
+    def pkg?
+      module_type === 'PKG'
+    end
+
     sig {returns(T::Boolean)}
     def modern?
       esm? || dts?
     end
 
+    def use_package?
+      esm? && package
+    end
+
     sig { void }
     def require_esm
       raise "ESM module type is required" unless modern?
@@ -123,21 +154,44 @@ module JsRoutes
 
     sig { returns(String) }
     def source_file
-      File.dirname(__FILE__) + "/../" + default_file_name
+      template = dts? ? "routes.d.ts" : "routes.js"
+      File.dirname(__FILE__) + "/../" + template
+    end
+
+    sig { returns(String) }
+    def router_source_file
+      template = dts? ? "router.d.ts" : "router.js"
+      File.dirname(__FILE__) + "/../" + template
     end
 
     sig { returns(Pathname) }
     def output_file
+      output_file_path(file || default_file_name)
+    end
+
+    protected
+
+    sig { params(file_name: FileName).returns(Pathname) }
+    def output_file_path(file_name)
       shakapacker = JsRoutes::Utils.shakapacker
       shakapacker_dir = shakapacker ?
-        shakapacker.config.source_path : pathname('app', 'javascript')
+        shakapacker.config.source_path : pathname(self.class.rails_javascript_path)
       sprockets_dir = pathname('app','assets','javascripts')
-      file_name = file || default_file_name
       sprockets_file = sprockets_dir.join(file_name)
       webpacker_file = shakapacker_dir.join(file_name)
       !Dir.exist?(shakapacker_dir) && defined?(::Sprockets) ? sprockets_file : webpacker_file
     end
 
+    sig { returns(String) }
+    def self.rails_javascript_path
+      js_dir = if defined?(Rails) && Rails.application&.config&.respond_to?(:javascript_path)
+        Rails.application.config.javascript_path
+      else
+        "javascript"
+      end
+      "app/#{js_dir}"
+    end
+
     protected
 
     sig { void }
@@ -153,7 +207,7 @@ module JsRoutes
 
     sig { returns(String) }
     def default_file_name
-      dts? ? "routes.d.ts" : "routes.js"
+      dts? ? "routes.d.ts" : pkg? ? "router.js" : "routes.js"
     end
 
     sig {void}
@@ -166,6 +220,9 @@ module JsRoutes
       if module_type != 'NIL' && namespace
         raise "JsRoutes namespace option can only be used if module_type is nil"
       end
+      if package && !esm?
+        raise "JsRoutes package option can only be used with ESM module type"
+      end
     end
 
     sig { returns(T.proc.returns(String)) }

data/lib/js_routes/generators/base.rb

@@ -11,11 +11,12 @@ class JsRoutes::Generators::Base < Rails::Generators::Base
   protected
 
   def application_js_path
+    js_dir = JsRoutes::Configuration.rails_javascript_path
     [
-      "app/javascript/packs/application.ts",
-      "app/javascript/packs/application.js",
-      "app/javascript/controllers/application.ts",
-      "app/javascript/controllers/application.js",
+      "#{js_dir}/packs/application.ts",
+      "#{js_dir}/packs/application.js",
+      "#{js_dir}/controllers/application.ts",
+      "#{js_dir}/controllers/application.js",
     ].find do |path|
       File.exist?(Rails.root.join(path))
     end

data/lib/js_routes/instance.rb

@@ -28,29 +28,29 @@ module JsRoutes
       application = T.unsafe(self.application)
       if routes_from(application).empty?
         if application.is_a?(Rails::Application)
-          if Rails.version >= "8.0.0"
+          if JsRoutes::Utils.rails_version >= Gem::Version.new("8.0.0")
             T.unsafe(application).reload_routes_unless_loaded
           else
             T.unsafe(application).reload_routes!
           end
         end
       end
-      content = File.read(@configuration.source_file)
 
-      unless @configuration.dts?
-        content = js_variables.inject(content) do |js, (key, value)|
-          js.gsub!("RubyVariables.#{key}", value.to_s) ||
-          raise("Missing key #{key} in JS template")
-        end
-      end
       unless @configuration.module_type == "NIL"
-        banner + content + routes_export + prevent_types_export
+        banner + routes_js + routes_export
       else
-        content.sub('"use strict";', "")
+        routes_js
       end
 
     end
 
+    sig {returns(String)}
+    def package
+      raise "Package generation requires module_type: 'PKG'" unless @configuration.pkg?
+
+      routes_js
+    end
+
     sig { returns(String) }
     def banner
       banner = @configuration.banner
@@ -83,6 +83,22 @@ module JsRoutes
       end
     end
 
+    sig { void }
+    def package!
+      raise "Package generation requires module_type: 'PKG'" unless @configuration.pkg?
+
+      file_path = Rails.root.join(@configuration.output_file)
+      source_code = package
+
+      # 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.
+      return if File.exist?(file_path) && File.read(file_path) == source_code
+
+      File.open(file_path, 'w') do |f|
+        f.write source_code
+      end
+    end
+
     sig { void }
     def remove!
       path = Rails.root.join(@configuration.output_file)
@@ -92,41 +108,105 @@ module JsRoutes
 
     protected
 
+    ESM_MODULE_MARKER = /export \{\};\n?\z/
+
+    def read_js(path)
+      File.read(path).sub(ESM_MODULE_MARKER, "")
+    end
+
+    sig { returns(String) }
+    def routes_js
+      return pkg_jsr if @configuration.pkg?
+
+      if @configuration.dts?
+        return File.read(@configuration.router_source_file)
+      end
+
+      content = read_js(@configuration.source_file)
+
+      js_variables.inject(content) do |js, (key, value)|
+        js.gsub!("RubyVariables.#{key}", value.to_s) ||
+        raise("Missing key #{key} in JS template")
+      end
+    end
+
+    sig { returns(String) }
+    def pkg_jsr
+      read_js(@configuration.router_source_file) + "export default Router;\n"
+    end
+
     sig { returns(T::Hash[String, String]) }
     def js_variables
+      warn_on_implicit_undefined_query_parameter_behavior
+
       prefix = @configuration.prefix
       prefix = prefix.call if prefix.is_a?(Proc)
       {
         'ROUTES_OBJECT'       => routes_object,
-        'DEPRECATED_FALSE_PARAMETER_BEHAVIOR' => Rails.version < '7.0.0',
-        'DEPRECATED_NIL_QUERY_PARAMETER_BEHAVIOR' => Rails.version < '8.1.0',
+        'DEPRECATED_FALSE_PARAMETER_BEHAVIOR' => @configuration.deprecated_false_parameter_behavior,
+        'DEPRECATED_NIL_QUERY_PARAMETER_BEHAVIOR' => @configuration.deprecated_nil_query_parameter_behavior,
+        'INCLUDE_UNDEFINED_QUERY_PARAMETERS' => json(@configuration.include_undefined_query_parameters != false),
         'DEFAULT_URL_OPTIONS' => json(@configuration.default_url_options),
         'PREFIX'              => json(prefix),
         'SPECIAL_OPTIONS_KEY' => json(@configuration.special_options_key),
         'SERIALIZER'          => @configuration.serializer || json(nil),
         'MODULE_TYPE'         => json(@configuration.module_type),
         'WRAPPER'             => wrapper_variable,
+        "EMBED_ROUTER"        => embed_router_variable,
       }
     end
 
+    sig { void }
+    def warn_on_implicit_undefined_query_parameter_behavior
+      return unless @configuration.include_undefined_query_parameters.nil?
+
+      JsRoutes::Utils.deprecator.warn(
+        "JsRoutes include_undefined_query_parameters is not configured. " \
+        "Set JsRoutes.setup { |c| c.include_undefined_query_parameters = false } " \
+        "to omit undefined query parameters, or set it to true to keep legacy nil serialization. " \
+        "The default will change to false in a future release."
+      )
+    end
+
+    sig { returns(String) }
+    def embed_router_variable
+      unless @configuration.use_package? || @configuration.modern?
+        read_js(@configuration.router_source_file)
+      else
+        ""
+      end
+    end
+
+    sig { returns(String) }
+    def router_js
+      if @configuration.use_package?
+        "import Router from '#{@configuration.package}';"
+      elsif @configuration.modern?
+        read_js(@configuration.router_source_file)
+      else
+        ""
+      end
+    end
+
     sig { returns(String) }
     def wrapper_variable
       case @configuration.module_type
-      when 'ESM'
-        'const __jsr = '
+      when 'ESM', 'PKG'
+        "#{router_js}const __jsr = "
       when 'NIL'
         namespace = @configuration.namespace
         if namespace
-          if namespace.include?('.')
+          assignment = if namespace.include?('.')
             "#{namespace} = "
           else
             "(typeof window !== 'undefined' ? window : this).#{namespace} = "
           end
+          "#{router_js}#{assignment}"
         else
-          ''
+          router_js
         end
       else
-        ''
+        router_js
       end
     end
 
@@ -148,7 +228,7 @@ module JsRoutes
 
     sig { returns(String) }
     def routes_object
-      return json({}) if @configuration.modern?
+      return json({}) if @configuration.modern? || @configuration.pkg?
       properties = routes_list.map do |comment, name, body|
         "#{comment}#{name}: #{body}".indent(2)
       end
@@ -157,7 +237,7 @@ module JsRoutes
 
     sig { returns(T::Array[StringArray]) }
     def static_exports
-      [:configure, :config, :serialize].map do |name|
+      [:configure, :config, :serialize, :__route].map do |name|
         [
           "", name.to_s,
           @configuration.dts? ?
@@ -175,16 +255,6 @@ module JsRoutes
       end.join
     end
 
-    sig { returns(String) }
-    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
-
     sig { returns(String) }
     def export_separator
       @configuration.dts? ? ': ' : ' = '

data/lib/js_routes/route.rb

@@ -10,6 +10,21 @@ module JsRoutes
 
     FILTERED_DEFAULT_PARTS = T.let([:controller, :action].freeze, SymbolArray)
     URL_OPTIONS = T.let([:protocol, :domain, :host, :port, :subdomain].freeze, SymbolArray)
+
+    # JavaScript reserved words that are invalid as function parameter names.
+    # @see https://www.w3schools.com/js/js_reserved.asp
+    JS_RESERVED_WORDS = T.let(%w[
+      abstract arguments async await boolean break byte case
+      catch char class const continue debugger default delete
+      do double else enum eval export extends false
+      final finally float for function goto if implements
+      import in instanceof int interface let long native
+      new null package private protected public return short
+      static super switch synchronized this throw throws transient
+      true try typeof using var void volatile while
+      with yield
+    ].freeze, T::Array[String])
+
     NODE_TYPES = T.let({
       GROUP: 1,
       CAT: 2,
@@ -55,11 +70,12 @@ module JsRoutes
       if @configuration.dts?
         definition_body
       else
-        # For tree-shaking ESM, add a #__PURE__ comment informing js bundlers that the call to `__jsr.r`
-        # has no side-effects (e.g. modifying global variables) and is safe to remove when unused.
+        # For tree-shaking ESM, add a #__PURE__ comment informing js bundlers that the call has
+        # no side-effects (e.g. modifying global variables) and is safe to remove when unused.
         # https://webpack.js.org/guides/tree-shaking/#clarifying-tree-shaking-and-sidyeeffects
         pure_comment = @configuration.esm? ? '/*#__PURE__*/ ' : ''
-        "#{pure_comment}__jsr.r(#{arguments(absolute).map{|a| json(a)}.join(', ')})"
+        call = '__route'
+        "#{pure_comment}#{call}(#{arguments(absolute).map{|a| json(a)}.join(', ')})"
       end
     end
 
@@ -67,7 +83,7 @@ module JsRoutes
     def definition_body
       options_type = optional_parts_type ? "#{optional_parts_type} & RouteOptions" : "RouteOptions"
       predicate = @configuration.optional_definition_params ? '?' : ''
-      args = required_parts.map{|p| "#{apply_case(p)}#{predicate}: RequiredRouteParameter"}
+      args = required_parts.map{|p| "#{format_param(p)}#{predicate}: RequiredRouteParameter"}
       args << "options?: #{options_type}"
       "((\n#{args.join(",\n").indent(2)}\n) => string) & RouteHelperExtras"
     end
@@ -117,8 +133,14 @@ module JsRoutes
 
     sig { params(absolute: T::Boolean).returns(String) }
     def helper_name(absolute)
-      suffix = absolute ? :url : @configuration.compact ? nil : :path
-      apply_case(base_name, suffix)
+      apply_case(base_name, helper_suffix(absolute))
+    end
+
+    sig { params(absolute: T::Boolean).returns(T.nilable(Symbol)) }
+    def helper_suffix(absolute)
+      return :url if absolute
+      return :path unless @configuration.compact
+      JS_RESERVED_WORDS.include?(apply_case(base_name)) ? :path : nil
     end
 
     sig { returns(String) }
@@ -173,7 +195,7 @@ JS
     sig { returns(String) }
     def documentation_params
       required_parts.map do |param|
-        "\n * @param {any} #{apply_case(param)}"
+        "\n * @param {any} #{format_param(param)}"
       end.join
     end
 
@@ -188,6 +210,16 @@ JS
       @configuration.camel_case ? value.camelize(:lower) : value
     end
 
+    sig { params(part: T.nilable(Literal)).returns(String) }
+    def format_param(part)
+      sanitize_param(apply_case(part))
+    end
+
+    sig { params(name: String).returns(String) }
+    def sanitize_param(name)
+      JS_RESERVED_WORDS.include?(name) ? "#{name}_" : name
+    end
+
     # This function serializes Journey route into JSON structure
     # We do not use Hash for human readable serialization
     # And preffer Array serialization because it is shorter.