js-routes 2.3.0 → 2.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8030ebf1b79303bfad35b2003ced97e6ec398b8bab459bf0f867006c9bc5d763
-  data.tar.gz: 4d84acaa15dacc791f26e059cb620d5c08d90891103fa5d73750d4bae3973e8b
+  metadata.gz: 97421ede18a16a1cb38ede32268ea60e79dc3aeee2dbe419cbbc4f117848cebb
+  data.tar.gz: d65a56e1026ef6551a7e0c30f90278245dfed8b4ceca460c285b16855586709c
 SHA512:
-  metadata.gz: 24e4500fcf1f799633343366f84d619060cd57979edc25a9f83ec17baf6a505e3fbbd838f66b6ec70618bf7d991a0f0614a3c6ad02ce85a90931e4a047f168a6
-  data.tar.gz: 7cab5ccd03712368ea32d43604381b32491ada2a933bf656b6efa0002132e638653f250e5a5037487e36c6ecfed01454d6df359e2e308b5fc7cd237c7af2fca2
+  metadata.gz: 13c8299991c8821aff0aa09f4b90ce3a38a9881b780688a6aabadf4871ab79948a095feb0fc9c76b4cc51c84f00aa758f5276838234e963efa1bb641db526984
+  data.tar.gz: 651ae1108a3845a1b948c0b9a1bb9475a2374d6178bd0cf35a7da2dca990081b2bfd40fb2beb92301a4efa3cdef143e83e04a7c39afb7394a685383d9a6b8a91

data/CHANGELOG.md

@@ -1,10 +1,16 @@
 # Changelog
 
+## v2.3.1
+
+* Add timestamp on when routes.js was generated into banner.
+* Fix application specified directly without proc. [#323](https://github.com/railsware/js-routes/issues/323)
+* Support `optional_definition_params` option. See [Related Docs](./Readme.md#optional-definition-params).
+
 ## v2.3.0
 
 * Drop support of Rails 4.x
-* Fix support of shakapacker [#321](https://github.com/railsware/js-routes/issue/321).
-* Fix support for Rails 8 [#319](https://github.com/railsware/js-routes/issue/319)
+* Fix support of shakapacker [#321](https://github.com/railsware/js-routes/issues/321).
+* Fix support for Rails 8 [#319](https://github.com/railsware/js-routes/issues/319)
 * Deprecated `rake js:routes:typescript`.
   `rake js:routes` now automatically detects if types support can be used on not.
 
@@ -12,7 +18,7 @@
 
 * Remove sorbet files from repo
 * Clearly define files included in gem
-* Fix Middleware and Middleware generator bugs [#316](https://github.com/railsware/js-routes/issue/316)
+* Fix Middleware and Middleware generator bugs [#316](https://github.com/railsware/js-routes/issues/316)
 * Remove empty object linter warning on DTS module
 * Generators: Add `.ts` extension when searching for main JS file of the project
 

data/Readme.md

@@ -42,8 +42,8 @@ There are several possible ways to setup JsRoutes:
 
 ### Quick Start
 
-Setup [Rack Middleware](https://guides.rubyonrails.org/rails_on_rack.html#action-dispatcher-middleware-stack) 
-to automatically generate and maintain `routes.js` file and corresponding 
+Setup [Rack Middleware](https://guides.rubyonrails.org/rails_on_rack.html#action-dispatcher-middleware-stack)
+to automatically generate and maintain `routes.js` file and corresponding
 [Typescript definitions](https://www.typescriptlang.org/docs/handbook/declaration-files/templates/module-d-ts.html) `routes.d.ts`:
 
 #### Use a Generator
@@ -70,13 +70,12 @@ import {post_path} from '../routes';
 alert(post_path(1))
 ```
 
-Upgrade js building process to update js-routes files in `Rakefile`: 
+Upgrade js building process to update js-routes files in `Rakefile`:
 
 ``` ruby
-task "javascript:build" => "js:routes:typescript"
+task "javascript:build" => "js:routes"
 # For setups without jsbundling-rails
-task "assets:precompile" => "js:routes:typescript"
-
+task "assets:precompile" => "js:routes"
 ```
 
 Add js-routes files to `.gitignore`:
@@ -236,7 +235,7 @@ JsRoutes.definitions! # to output to file
 JsRoutes.definitions # to output to string
 ```
 
-Even more advanced setups can be achieved by setting `module_type` to `DTS` inside [configuration](#module_type) 
+Even more advanced setups can be achieved by setting `module_type` to `DTS` inside [configuration](#module_type)
 which will cause any `JsRoutes` instance to generate defintions instead of routes themselves.
 
 <div id="sprockets"></div>
@@ -325,9 +324,13 @@ Options to configure JavaScript file generator. These options are only available
   * Sample route call when option is set to true: `users() // => /users`
 * `application` - a key to specify which rails engine you want to generate routes too.
   * This option allows to only generate routes for a specific rails engine, that is mounted into routes instead of all Rails app routes
-  * Default: `Rails.application`
+  * It is recommended to wrap the value with `lambda`. This will reduce the reliance on order during initialization your application.
+  * 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.
+* `optional_definition_params` - make all route paramters in definition optional
+  * See [related compatibility issue](#optional-definition-params)
+  * Default: `false`
 
 <div id="formatter-options"></div>
 
@@ -359,33 +362,33 @@ import {
   user_path, user_project_path, company_path
 } from 'routes';
 
-users_path() 
+users_path()
   // => "/users"
 
-user_path(1) 
+user_path(1)
   // => "/users/1"
-  
-user_path(1, {format: 'json'}) 
+
+user_path(1, {format: 'json'})
   // => "/users/1.json"
 
-user_path(1, {anchor: 'profile'}) 
+user_path(1, {anchor: 'profile'})
   // => "/users/1#profile"
 
-new_user_project_path(1, {format: 'json'}) 
+new_user_project_path(1, {format: 'json'})
   // => "/users/1/projects/new.json"
 
-user_project_path(1,2, {q: 'hello', custom: true}) 
+user_project_path(1,2, {q: 'hello', custom: true})
   // => "/users/1/projects/2?q=hello&custom=true"
 
-user_project_path(1,2, {hello: ['world', 'mars']}) 
+user_project_path(1,2, {hello: ['world', 'mars']})
   // => "/users/1/projects/2?hello%5B%5D=world&hello%5B%5D=mars"
 
 var google = {id: 1, name: "Google"};
-company_path(google) 
+company_path(google)
   // => "/companies/1"
 
 var google = {id: 1, name: "Google", to_param: "google"};
-company_path(google) 
+company_path(google)
   // => "/companies/google"
 ```
 
@@ -428,14 +431,63 @@ In this case you would need to pass a special key to help:
 ``` js
 import {company_project_path} from '../routes'
 
-company_project_path({company_id: 1, id: 2}) // => Not enough parameters
-company_project_path({company_id: 1, id: 2, _options: true}) // => "/companies/1/projects/2"
+company_project_path({company_id: 1, id: 2})
+    // => Not enough parameters
+company_project_path({company_id: 1, id: 2, _options: true})
+    // => "/companies/1/projects/2"
+```
+
+Use `special_options_key` to configure the `_options` parameter name.
+
+<div id="optional-definition-params"></div>
+
+### Rails required parameters specified as optional
+
+Rails is very flexible on how route parameters can be specified.
+All of the following calls will make the same result:
+
+``` ruby
+# Given route
+# /inboxes/:inbox_id/messages/:message_id/attachments/:id
+# every call below returns:
+# => "/inboxes/1/messages/2/attachments/3"
+
+inbox_message_attachment_path(1, 2, 3)
+inbox_message_attachment_path(1, 2, id: 3)
+inbox_message_attachment_path(1, message_id: 2, id: 3)
+inbox_message_attachment_path(inbox_id: 1, message_id: 2, id: 3)
+
+# including these mad versions
+inbox_message_attachment_path(2, inbox_id: 1, id: 3)
+inbox_message_attachment_path(1, 3, message_id: 2)
+inbox_message_attachment_path(3, inbox_id: 1, message_id: 2)
+```
+
+While all of these methods are supported by JsRoutes, it is impossible to support them in `DTS` type definitions.
+If you are using routes like this, use the following configuration that will prevent required parameters presence to be validated by definition:
+
+``` ruby
+JsRoutes.configure do |c|
+  c.optional_definition_params = true
+end
 ```
 
+This will enforce the following route signature:
+
+``` typescript
+export const inbox_message_attachment_path: ((
+  inbox_id?: RequiredRouteParameter,
+  message_id?: RequiredRouteParameter,
+  id?: RequiredRouteParameter,
+  options?: RouteOptions
+) => string) & RouteHelperExtras;
+```
+
+That will make every call above valid.
 
 ## What about security?
 
-JsRoutes itself does not have security holes. 
+JsRoutes itself does not have security holes.
 It makes URLs without access protection more reachable by potential attacker.
 If that is an issue for you, you may use one of the following solutions:
 
@@ -488,5 +540,3 @@ Advantages of this one are:
 * Full rails compatibility
 * Support Rails `#to_param` convention for seo optimized paths
 * Well tested
-
-

data/lib/js_routes/configuration.rb

@@ -37,6 +37,8 @@ module JsRoutes
     attr_accessor :documentation
     sig { returns(T.nilable(String)) }
     attr_accessor :module_type
+    sig { returns(T::Boolean) }
+    attr_accessor :optional_definition_params
 
     sig {params(attributes: T.nilable(Options)).void }
     def initialize(attributes = nil)
@@ -54,6 +56,7 @@ module JsRoutes
       @application = T.let(-> { Rails.application }, ApplicationCaller)
       @module_type = T.let('ESM', T.nilable(String))
       @documentation = T.let(true, T::Boolean)
+      @optional_definition_params = T.let(false, T::Boolean)
 
       return unless attributes
       assign(attributes)

data/lib/js_routes/instance.rb

@@ -76,15 +76,14 @@ module JsRoutes
 
     sig { returns(T::Hash[String, String]) }
     def js_variables
-      version = Rails.version
       prefix = @configuration.prefix
       prefix = prefix.call if prefix.is_a?(Proc)
       {
         'GEM_VERSION'         => JsRoutes::VERSION,
+        'TIMESTAMP'           => Time.now.to_s,
         'ROUTES_OBJECT'       => routes_object,
         'RAILS_VERSION'       => ::Rails.version,
-        'DEPRECATED_GLOBBING_BEHAVIOR' => version >= '4.0.0' && version < '4.1.0',
-        'DEPRECATED_FALSE_PARAMETER_BEHAVIOR' => version < '7.0.0',
+        'DEPRECATED_FALSE_PARAMETER_BEHAVIOR' => Rails.version < '7.0.0',
         'APP_CLASS'           => application.class.to_s,
         'DEFAULT_URL_OPTIONS' => json(@configuration.default_url_options),
         'PREFIX'              => json(prefix),
@@ -118,7 +117,8 @@ module JsRoutes
 
     sig { returns(Application) }
     def application
-      @configuration.application.call
+      app = @configuration.application
+      app.is_a?(Proc) ? app.call : app
     end
 
     sig { params(value: T.untyped).returns(String) }

data/lib/js_routes/route.rb

@@ -66,7 +66,8 @@ module JsRoutes
     sig { returns(String) }
     def definition_body
       options_type = optional_parts_type ? "#{optional_parts_type} & RouteOptions" : "RouteOptions"
-      args = required_parts.map{|p| "#{apply_case(p)}: RequiredRouteParameter"}
+      predicate = @configuration.optional_definition_params ? '?' : ''
+      args = required_parts.map{|p| "#{apply_case(p)}#{predicate}: RequiredRouteParameter"}
       args << "options?: #{options_type}"
       "((\n#{args.join(",\n").indent(2)}\n) => string) & RouteHelperExtras"
     end

data/lib/js_routes/types.rb

@@ -17,7 +17,7 @@ module JsRoutes
     JourneyRoute = T.type_alias{ActionDispatch::Journey::Route}
     RouteSpec = T.type_alias {T.untyped}
     Application = T.type_alias { T.any(T::Class[Rails::Engine], Rails::Application) }
-    ApplicationCaller = T.type_alias { T.proc.returns(Application) }
+    ApplicationCaller = T.type_alias { T.any(Application, T.proc.returns(Application)) }
     Clusivity = T.type_alias { T.any(Regexp, T::Array[Regexp]) }
     FileName = T.type_alias { T.any(String, Pathname, NilClass) }
     ConfigurationBlock = T.type_alias { T.proc.params(arg0: JsRoutes::Configuration).void }

data/lib/js_routes/version.rb

@@ -1,4 +1,4 @@
 # typed: strict
 module JsRoutes
-  VERSION = "2.3.0"
+  VERSION = "2.3.1"
 end

data/lib/routes.d.ts

@@ -1,5 +1,5 @@
 /**
- * File generated by js-routes RubyVariables.GEM_VERSION
+ * File generated by js-routes RubyVariables.GEM_VERSION on RubyVariables.TIMESTAMP
  * Based on Rails RubyVariables.RAILS_VERSION routes of RubyVariables.APP_CLASS
  */
 declare type Optional<T> = {
@@ -64,7 +64,6 @@ declare type PartsTable = Collection<{
 declare type ModuleType = "CJS" | "AMD" | "UMD" | "ESM" | "DTS" | "NIL";
 declare const RubyVariables: {
     PREFIX: string;
-    DEPRECATED_GLOBBING_BEHAVIOR: boolean;
     DEPRECATED_FALSE_PARAMETER_BEHAVIOR: boolean;
     SPECIAL_OPTIONS_KEY: string;
     DEFAULT_URL_OPTIONS: RouteParameters;

data/lib/routes.js

@@ -1,5 +1,5 @@
 /**
- * File generated by js-routes RubyVariables.GEM_VERSION
+ * File generated by js-routes RubyVariables.GEM_VERSION on RubyVariables.TIMESTAMP
  * Based on Rails RubyVariables.RAILS_VERSION routes of RubyVariables.APP_CLASS
  */
 // eslint-disable-next-line
@@ -415,9 +415,7 @@ RubyVariables.WRAPPER(
                 value = value.join("/");
             }
             const result = this.path_identifier(value);
-            return RubyVariables.DEPRECATED_GLOBBING_BEHAVIOR
-                ? result
-                : encodeURI(result);
+            return encodeURI(result);
         }
         get_prefix() {
             const prefix = this.configuration.prefix;

data/lib/routes.ts

@@ -1,5 +1,5 @@
 /**
- * File generated by js-routes RubyVariables.GEM_VERSION
+ * File generated by js-routes RubyVariables.GEM_VERSION on RubyVariables.TIMESTAMP
  * Based on Rails RubyVariables.RAILS_VERSION routes of RubyVariables.APP_CLASS
  */
 
@@ -82,7 +82,6 @@ type ModuleType = "CJS" | "AMD" | "UMD" | "ESM" | "DTS" | "NIL";
 
 declare const RubyVariables: {
   PREFIX: string;
-  DEPRECATED_GLOBBING_BEHAVIOR: boolean;
   DEPRECATED_FALSE_PARAMETER_BEHAVIOR: boolean;
   SPECIAL_OPTIONS_KEY: string;
   DEFAULT_URL_OPTIONS: RouteParameters;
@@ -606,9 +605,7 @@ RubyVariables.WRAPPER(
           value = value.join("/");
         }
         const result = this.path_identifier(value as any);
-        return RubyVariables.DEPRECATED_GLOBBING_BEHAVIOR
-          ? result
-          : encodeURI(result);
+        return encodeURI(result);
       }
 
       get_prefix(): string {

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: js-routes
 version: !ruby/object:Gem::Version
-  version: 2.3.0
+  version: 2.3.1
 platform: ruby
 authors:
 - Bogdan Gusiev
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-11-16 00:00:00.000000000 Z
+date: 2024-11-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -144,9 +144,9 @@ licenses:
 - MIT
 metadata:
   bug_tracker_uri: https://github.com/railsware/js-routes/issues
-  changelog_uri: https://github.com/railsware/js-routes/blob/v2.3.0/CHANGELOG.md
+  changelog_uri: https://github.com/railsware/js-routes/blob/v2.3.1/CHANGELOG.md
   documentation_uri: https://github.com/railsware/js-routes
-  source_code_uri: https://github.com/railsware/js-routes/tree/v2.3.0/activerecord
+  source_code_uri: https://github.com/railsware/js-routes/tree/v2.3.1/activerecord
   rubygems_mfa_required: 'true'
   github_repo: ssh://github.com/railsware/js-routes
 post_install_message:
@@ -164,7 +164,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.11
+rubygems_version: 3.5.16
 signing_key:
 specification_version: 4
 summary: Brings Rails named routes to javascript