js-routes 2.3.0 → 2.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8030ebf1b79303bfad35b2003ced97e6ec398b8bab459bf0f867006c9bc5d763
-  data.tar.gz: 4d84acaa15dacc791f26e059cb620d5c08d90891103fa5d73750d4bae3973e8b
+  metadata.gz: 771e5ddecccbde6b5b78778d456fe9602a4ae4b2aaa89e821cd6bda24be95565
+  data.tar.gz: b0ac96fe4273cc21fa616614429e270a393c7bcd11f15b5b79e1b14e56ec579f
 SHA512:
-  metadata.gz: 24e4500fcf1f799633343366f84d619060cd57979edc25a9f83ec17baf6a505e3fbbd838f66b6ec70618bf7d991a0f0614a3c6ad02ce85a90931e4a047f168a6
-  data.tar.gz: 7cab5ccd03712368ea32d43604381b32491ada2a933bf656b6efa0002132e638653f250e5a5037487e36c6ecfed01454d6df359e2e308b5fc7cd237c7af2fca2
+  metadata.gz: 150bccfe350126ca0db67d03a8a7bbc22884edd63ef2e86c1cecd4ac2d0d72b941d7f1133cadbe64d19f99332be22db9891ca42f2f4ccfbec7e77447b741fb71
+  data.tar.gz: 2a51b7337560e055a21ff96be1b6f89d40d88bc6b541c56129a5f99823436a7c31027cc6e029f6b33b00a42805cd7986d805a30fc8a8ce5cc4e9bd5be20e2757

data/CHANGELOG.md

@@ -1,10 +1,35 @@
 # Changelog
 
+## v2.3.2
+
+* Add `banner` option that allow to control JSDoc on top of generated file. [#324](https://github.com/bogdan/repo/issues/324).
+
+``` ruby
+JsRoutes.configure do |c|
+c.banner = -> {
+  commit_hash = `git rev-parse --short HEAD`.strip
+
+  <<~DOC
+  @file Javascript Route helpers of my magic pony app.
+  @author Bogdan Gusiev
+  @license MIT
+  @version #{commit_hash}
+  DOC
+}
+end
+```
+
+## 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 +37,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,26 @@ 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`
+* `banner` - specify a JSDoc comment on top of the file.
+  * It is not stripped by minifiers by default and helps to originate the content when debugging the build.
+  * You may want to control how much information from backend is exposed to potential attacker at the cost of your own comfort.
+  * See [JSDoc Guide](https://github.com/shri/JSDoc-Style-Guide/blob/master/README.md#files)
+  * Supports a lazy generation with `Proc`.
+  * Default: A string that generates the following:
+
+```
+/**
+ * File generated by js-routes 2.3.1 on 2024-12-04 09:45:59 +0100
+ * Based on Rails 7.2.0 routes of App
+ */
+```
 
 <div id="formatter-options"></div>
 
@@ -359,33 +375,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"
 ```
 
@@ -418,7 +434,10 @@ user_path.requiredParams() // => ['id']
 
 ## Rails Compatibility
 
-JsRoutes tries to replicate the Rails routing API as closely as possible. If you find any incompatibilities (outside of what is described below), please [open an issue](https://github.com/railsware/js-routes/issues/new).
+JsRoutes tries to replicate the Rails routing API as closely as possible. 
+There are only 2 known issues with compatibility that happen very rarely and have their workarounds.
+
+If you find any incompatibilities outside of ones below, please [open an issue](https://github.com/railsware/js-routes/issues/new).
 
 ### Object and Hash distinction issue
 
@@ -428,14 +447,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 +556,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

@@ -3,6 +3,7 @@
 require "pathname"
 require "js_routes/types"
 require 'js_routes/utils'
+require 'js_routes/version'
 
 module JsRoutes
   class Configuration
@@ -37,6 +38,10 @@ module JsRoutes
     attr_accessor :documentation
     sig { returns(T.nilable(String)) }
     attr_accessor :module_type
+    sig { returns(T::Boolean) }
+    attr_accessor :optional_definition_params
+    sig { returns(BannerCaller) }
+    attr_accessor :banner
 
     sig {params(attributes: T.nilable(Options)).void }
     def initialize(attributes = nil)
@@ -51,9 +56,11 @@ module JsRoutes
       @compact = T.let(false, T::Boolean)
       @serializer = T.let(nil, T.nilable(String))
       @special_options_key = T.let("_options", Literal)
-      @application = T.let(-> { Rails.application }, ApplicationCaller)
+      @application = T.let(T.unsafe(-> { 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)
+      @banner = T.let(default_banner, BannerCaller)
 
       return unless attributes
       assign(attributes)
@@ -155,5 +162,17 @@ module JsRoutes
         raise "JsRoutes namespace option can only be used if module_type is nil"
       end
     end
+
+    sig { returns(T.proc.returns(String)) }
+    def default_banner
+      -> () {
+        app = application.is_a?(Proc) ? T.unsafe(application).call : application
+        <<~TXT
+          File generated by js-routes #{JsRoutes::VERSION} on #{Time.now}
+          Based on Rails #{Rails.version} routes of #{app.class}
+        TXT
+
+      }
+    end
   end
 end

data/lib/js_routes/instance.rb

@@ -29,9 +29,9 @@ module JsRoutes
       if named_routes.empty?
         if application.is_a?(Rails::Application)
           if Rails.version >= "8.0.0"
-            application.reload_routes_unless_loaded
+            T.unsafe(application).reload_routes_unless_loaded
           else
-            application.reload_routes!
+            T.unsafe(application).reload_routes!
           end
         end
       end
@@ -43,7 +43,20 @@ module JsRoutes
           raise("Missing key #{key} in JS template")
         end
       end
-      content + routes_export + prevent_types_export
+      banner + content + routes_export + prevent_types_export
+    end
+
+    sig { returns(String) }
+    def banner
+      banner = @configuration.banner
+      banner = banner.call if banner.is_a?(Proc)
+      return "" if banner.blank?
+      [
+        "/**",
+        *banner.split("\n").map { |line| " * #{line}" },
+        " */",
+        "",
+      ].join("\n")
     end
 
     sig { void }
@@ -76,16 +89,11 @@ 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,
         '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',
-        'APP_CLASS'           => application.class.to_s,
+        'DEPRECATED_FALSE_PARAMETER_BEHAVIOR' => Rails.version < '7.0.0',
         'DEFAULT_URL_OPTIONS' => json(@configuration.default_url_options),
         'PREFIX'              => json(prefix),
         'SPECIAL_OPTIONS_KEY' => json(@configuration.special_options_key),
@@ -118,7 +126,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) }
@@ -187,7 +196,7 @@ export {};
       rails_engine_app = T.unsafe(app_from_route(route))
       if rails_engine_app.is_a?(Class) &&
           rails_engine_app < Rails::Engine && !route.path.anchored
-        rails_engine_app.routes.named_routes.flat_map do |_, engine_route|
+        T.unsafe(rails_engine_app).routes.named_routes.flat_map do |_, engine_route|
           route_helpers_if_match(engine_route, route)
         end
       else
@@ -200,7 +209,7 @@ export {};
       app = route.app
       # Rails Engine can use additional
       # ActionDispatch::Routing::Mapper::Constraints, which contain app
-      if app.is_a?(ActionDispatch::Routing::Mapper::Constraints)
+      if app.is_a?(T.unsafe(ActionDispatch::Routing::Mapper::Constraints))
         app.app
       else
         app

data/lib/js_routes/middleware.rb

@@ -6,7 +6,7 @@ module JsRoutes
   # whenever routes.rb is modified
   #
   # Inspired by
-  # https://github.com/fnando/i18n-js/blob/main/lib/i18n/js/middleware.rb
+  # https://github.com/fnando/i18n-js/blob/v3/lib/i18n/js/middleware.rb
   class Middleware
     include JsRoutes::Types
     include RackApp

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

@@ -16,11 +16,20 @@ module JsRoutes
     Literal = T.type_alias { T.any(String, Symbol) }
     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) }
+    Application = T.type_alias do
+      T.any(T::Class[Rails::Engine], Rails::Application)
+    end
+    ApplicationCaller = T.type_alias do
+      T.any(Application, T.proc.returns(Application))
+    end
+    BannerCaller = T.type_alias do
+      T.any(String, NilClass, T.proc.returns(T.any(String, NilClass)))
+    end
     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 }
+    ConfigurationBlock = T.type_alias do
+      T.proc.params(arg0: JsRoutes::Configuration).void
+    end
     Prefix = T.type_alias do
       T.any(T.proc.returns(String), String, NilClass)
     end

data/lib/js_routes/version.rb

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

data/lib/routes.d.ts

@@ -1,7 +1,3 @@
-/**
- * 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;
 };
@@ -64,7 +60,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,7 +1,3 @@
-/**
- * File generated by js-routes RubyVariables.GEM_VERSION
- * Based on Rails RubyVariables.RAILS_VERSION routes of RubyVariables.APP_CLASS
- */
 // eslint-disable-next-line
 RubyVariables.WRAPPER(
 // eslint-disable-next-line
@@ -415,9 +411,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,8 +1,3 @@
-/**
- * File generated by js-routes RubyVariables.GEM_VERSION
- * Based on Rails RubyVariables.RAILS_VERSION routes of RubyVariables.APP_CLASS
- */
-
 type Optional<T> = { [P in keyof T]?: T[P] | null };
 type Collection<T> = Record<string, T>;
 
@@ -82,7 +77,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 +600,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 {

data/lib/templates/initializer.rb

@@ -1,5 +1,27 @@
 JsRoutes.setup do |c|
   # Setup your JS module system:
-  # ESM, CJS, AMD, UMD or nil
+  # ESM, CJS, AMD, UMD or nil.
   # c.module_type = "ESM"
+
+  # Legacy setup for no modules system.
+  # Sets up a global variable `Routes`
+  # that holds route helpers.
+  # c.module_type = nil
+  # c.namespace = "Routes"
+
+  # Follow javascript naming convention
+  # but lose the ability to match helper name
+  # on backend and frontend consistently.
+  # c.camel_case = true
+
+  # Generate only helpers that match specific pattern.
+  # c.exclude = /^api_/
+  # c.include = /^admin_/
+
+  # Generate `*_url` helpers besides `*_path`
+  # for apps that work on multiple domains.
+  # c.url_links = true
+
+  # More options:
+  # @see https://github.com/railsware/js-routes#available-options
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: js-routes
 version: !ruby/object:Gem::Version
-  version: 2.3.0
+  version: 2.3.2
 platform: ruby
 authors:
 - Bogdan Gusiev
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-11-16 00:00:00.000000000 Z
+date: 2024-12-04 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.2/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.2/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.14
 signing_key:
 specification_version: 4
 summary: Brings Rails named routes to javascript