js-routes 2.2.5 → 2.2.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d0fd81f6f8575bb26353c7e485f0551cc62420a266e22d5503739332b5762037
-  data.tar.gz: b84d4ad0f70f8e1f454bdd2c6fb8b77a316376b3407a3fd0b6c681d87b87ada9
+  metadata.gz: cc558c858345b705d2ca048eaab529acf4d4ffe20299e152f1c23fcbeb31388e
+  data.tar.gz: 70dc5ab9c6f629d3236d45a5cf202c6bb8f00893041857f137b9569a3467d48c
 SHA512:
-  metadata.gz: 23db2ecfc872d470727b60d7c63148aa15d9d5b76d6eaedbf7bbe5ee964ae5ca5abfb09f69199dd813fcd0b09b12d0920fcb0abf9b09a1bb2a6dbfbaf7884e75
-  data.tar.gz: faf0d713243b705277604493bdf2f5d9f61c5cd953ef9bcfbcd1f2d88fdfd850d27ed48e0740f0fa4c0f4492a310bec13d6a76fc070113703ab7e7750e812b0c
+  metadata.gz: 0536cff5b25734ae0c0399cba8d65fb48503e7038c6e5f7396acb69497505ab8849b109e3348bc2c7a010b073cb3cd4aebed1798c538e8bd0e0270f8949dd53c
+  data.tar.gz: 99e9d0487c9062cf3789a8018beba7bcc0b9f985251921cb6f042c20c571d74fab8a4c79f82ad0a6530dde42ee8a678fb5dbfae184dd64e8756ef47d06805b0b

data/CHANGELOG.md

@@ -1,5 +1,13 @@
 ## master
 
+## v2.2.7
+
+* Fix ESM Tree Shaking [#306](https://github.com/railsware/js-routes/issues/306)
+
+## v2.2.6
+
+* Prefer to extend `javascript:build` instead of `assets:precompile`. [#305](https://github.com/railsware/js-routes/issues/305)
+* Add stimulus framework application.js location to generators
 
 ## v2.2.5
 

data/Readme.md

@@ -18,7 +18,7 @@ There are several possible ways to setup JsRoutes:
 
 * [Quick and easy](#quick-start)
   * Uses Rack Middleware to automatically update routes locally
-  * Automatically generates routes files on `assets:precompile` in production
+  * Automatically generates routes files on javascript build
   * Works great for a simple Rails application
 * [Webpacker ERB Loader](#webpacker)
   * Requires ESM module system (the default)
@@ -60,12 +60,13 @@ import {post_path} from '../routes';
 alert(post_path(1))
 ```
 
-Upgrade `rake assets:precompile` to update js-routes files in `Rakefile`: 
+Upgrade js building process to update js-routes files in `Rakefile`: 
 
 ``` ruby
-namespace :assets do
-  task :precompile => "js:routes:typescript"
-end
+task "javascript:build" => "js:routes:typescript"
+# For setups without jsbundling-rails
+task "assets:precompile" => "js:routes:typescript"
+
 ```
 
 Add js-routes files to `.gitignore`:
@@ -413,9 +414,14 @@ 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:
 
-### Explicit Import + ESM Tree shaking
+### ESM Tree shaking
 
-Make sure `module_type` is set to `ESM` (the default) and JS files import only required routes into the file like:
+Make sure `module_type` is set to `ESM` (the default). Modern JS bundlers like
+[Webpack](https://webpack.js.org) can statically determine which ESM exports are used, and remove
+the unused exports to reduce bundle size. This is known as [Tree
+Shaking](https://webpack.js.org/guides/tree-shaking/).
+
+JS files can use named imports to import only required routes into the file, like:
 
 ``` javascript
 import {
@@ -427,8 +433,15 @@ import {
 } from '../routes'
 ```
 
-Such import structure allows for moddern JS bundlers like [Webpack](https://webpack.js.org/) to only include explicitly imported routes into JS bundle file.
-See [Tree Shaking](https://webpack.js.org/guides/tree-shaking/) for more information.
+JS files can also use star imports (`import * as`) for tree shaking, as long as only explicit property accesses are used.
+
+``` javascript
+import * as routes from '../routes';
+
+console.log(routes.inbox_path); // OK, only `inbox_path` is included in the bundle
+
+console.log(Object.keys(routes)); // forces bundler to include all exports, breaking tree shaking
+```
 
 ### Exclude option
 

data/lib/js_routes/generators/base.rb

@@ -0,0 +1,16 @@
+
+require "rails/generators"
+
+class JsRoutes::Generators::Base < Rails::Generators::Base
+
+  protected
+
+  def application_js_path
+    [
+      "app/javascript/packs/application.js",
+      "app/javascript/controllers/application.js",
+    ].find do |path|
+      File.exists?(Rails.root.join(path))
+    end
+  end
+end

data/lib/js_routes/generators/middleware.rb

@@ -1,15 +1,17 @@
-require "rails/generators"
+require "js_routes/generators/base"
 
-class JsRoutes::Generators::Middleware < Rails::Generators::Base
+class JsRoutes::Generators::Middleware < JsRoutes::Generators::Base
 
   source_root File.expand_path(__FILE__ + "/../../../templates")
 
   def create_middleware
     copy_file "initializer.rb", "config/initializers/js_routes.rb"
-    inject_into_file "app/javascript/packs/application.js", pack_content
     inject_into_file "config/environments/development.rb", middleware_content, before: /^end\n\z/
     inject_into_file "Rakefile", rakefile_content
     inject_into_file ".gitignore", gitignore_content
+    if path = application_js_path
+      inject_into_file path, pack_content
+    end
     JsRoutes.generate!
     JsRoutes.definitions!
   end
@@ -33,12 +35,11 @@ window.Routes = Routes;
   end
 
   def rakefile_content
+    enhanced_task = Bundler.load.gems.find {|g| g.name = 'jsbundling-rails'} ?
+      "javascript:build" : "assets:precompile"
     <<-RB
-
-# Update js-routes file before assets precompile
-namespace :assets do
-  task :precompile => "js:routes:typescript"
-end
+# Update js-routes file before javascript build
+task "#{enhanced_task}" => "js:routes:typescript"
     RB
   end
 

data/lib/js_routes/generators/webpacker.rb

@@ -9,7 +9,9 @@ class JsRoutes::Generators::Webpacker < Rails::Generators::Base
     copy_file "erb.js", "config/webpack/loaders/erb.js"
     copy_file "routes.js.erb", "app/javascript/routes.js.erb"
     inject_into_file "config/webpack/environment.js", loader_content
-    inject_into_file "app/javascript/packs/application.js", pack_content
+    if path = application_js_path
+      inject_into_file path, pack_content
+    end
     command = Rails.root.join("./bin/yarn add rails-erb-loader")
     run command
   end

data/lib/js_routes/route.rb

@@ -33,8 +33,15 @@ module JsRoutes
     end
 
     def body(absolute)
-      @configuration.dts? ?
-        definition_body : "__jsr.r(#{arguments(absolute).map{|a| json(a)}.join(', ')})"
+      if @configuration.dts?
+        definition_body
+      else
+        # For tree-shaking ESM, add a #__PURE__ comment informing Webpack/minifiers that the call to `__jsr.r`
+        # 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-sideeffects
+        pure_comment = @configuration.esm? ? '/*#__PURE__*/ ' : ''
+        "#{pure_comment}__jsr.r(#{arguments(absolute).map{|a| json(a)}.join(', ')})"
+      end
     end
 
     def definition_body

data/lib/js_routes/version.rb

@@ -1,3 +1,3 @@
 module JsRoutes
-  VERSION = "2.2.5"
+  VERSION = "2.2.7"
 end

data/lib/routes.d.ts

@@ -32,8 +32,8 @@ declare type RequiredParameters<T extends number> = T extends 1 ? [RequiredRoute
     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 RouteHelperOptions = RouteOptions & Record<string, OptionalRouteParameter>;
+declare type RouteHelper<T extends number = number> = ((...args: [...RequiredParameters<T>, RouteHelperOptions]) => string) & RouteHelperExtras;
 declare type RouteHelpers = Record<string, RouteHelper>;
 declare type Configuration = {
     prefix: string;

data/lib/routes.ts

@@ -40,11 +40,10 @@ type RequiredParameters<T extends number> = T extends 1
     ]
   : RequiredRouteParameter[];
 
-type RouteHelperOptions<T extends string> = RouteOptions &
-  Optional<Record<T, OptionalRouteParameter>>;
+type RouteHelperOptions = RouteOptions & Record<string, OptionalRouteParameter>;
 
-type RouteHelper<T extends number = number, U extends string = string> = ((
-  ...args: [...RequiredParameters<T>, RouteHelperOptions<U>]
+type RouteHelper<T extends number = number> = ((
+  ...args: [...RequiredParameters<T>, RouteHelperOptions]
 ) => string) &
   RouteHelperExtras;
 
@@ -539,7 +538,7 @@ RubyVariables.WRAPPER(
         let key: string;
         switch (route[0]) {
           case NodeTypes.GROUP:
-            return "(" + this.build_path_spec(route[1]) + ")";
+            return `(${this.build_path_spec(route[1])})`;
           case NodeTypes.CAT:
             return (
               this.build_path_spec(route[1]) + this.build_path_spec(route[2])

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

@@ -32,8 +32,8 @@ declare type RequiredParameters<T extends number> = T extends 1 ? [RequiredRoute
     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 RouteHelperOptions = RouteOptions & Record<string, OptionalRouteParameter>;
+declare type RouteHelper<T extends number = number> = ((...args: [...RequiredParameters<T>, RouteHelperOptions]) => string) & RouteHelperExtras;
 declare type RouteHelpers = Record<string, RouteHelper>;
 declare type Configuration = {
     prefix: string;

data/spec/js_routes/module_types/dts_spec.rb

@@ -105,7 +105,7 @@ DOC
   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(")
+      is_expected.to include("export const inbox_message_path = /*#__PURE__*/ __jsr.r(")
     end
   end
 end

data/spec/js_routes/module_types/esm_spec.rb

@@ -24,7 +24,7 @@ describe JsRoutes, "compatibility with ESM"  do
  * @param {object | undefined} options
  * @returns {string} route path
  */
-export const inboxes_path = __jsr.r
+export const inboxes_path = /*#__PURE__*/ __jsr.r(
 DOC
   end
 
@@ -39,7 +39,7 @@ DOC
   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(")
+      is_expected.to include("export const inbox_message_path = /*#__PURE__*/ __jsr.r(")
     end
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: js-routes
 version: !ruby/object:Gem::Version
-  version: 2.2.5
+  version: 2.2.7
 platform: ruby
 authors:
 - Bogdan Gusiev
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-03-08 00:00:00.000000000 Z
+date: 2023-07-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -167,6 +167,7 @@ files:
 - lib/js_routes.rb
 - lib/js_routes/configuration.rb
 - lib/js_routes/engine.rb
+- lib/js_routes/generators/base.rb
 - lib/js_routes/generators/middleware.rb
 - lib/js_routes/generators/webpacker.rb
 - lib/js_routes/instance.rb
@@ -221,7 +222,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.3.7
+rubygems_version: 3.4.15
 signing_key:
 specification_version: 4
 summary: Brings Rails named routes to javascript