Lazy load experiment results

Related #3199

Please refer to /experiments/lazy_loading doc for
more details.

Author: stefannibrasil

.github/workflows/ruby.yml

@@ -58,4 +58,4 @@ jobs:
         bundler-cache: true
 
     - name: Run tests
-      run: bundle exec rake test
+      run: bundle exec rake test LAZY_LOAD=1

benchmark/load.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require 'benchmark/ips'
+
+Benchmark.ips do |x|
+  x.report('require') { system('ruby load_faker.rb') }
+  x.report('lazyload') { system('LAZY_LOAD=1 ruby load_faker.rb') }
+
+  x.compare!(order: :baseline)
+end

benchmark/load_faker.rb

@@ -0,0 +1,8 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+if defined?(Faker)
+  raise 'fake is already defined...'
+end
+
+load('/Users/stefannibrasil/projects/faker/lib/faker.rb')

doc/internet/http.md

@@ -1,13 +1,14 @@
-# Faker::Internet::HTTP
+# Faker::HTTP
 
 Available since version next.
 
 # Keyword arguments: group
+
 ```ruby
-Faker::Internet::HTTP.status_code #=> 418
-Faker::Internet::HTTP.status_code(group: :information) #=> 102
-Faker::Internet::HTTP.status_code(group: :successful) #=> 200
-Faker::Internet::HTTP.status_code(group: :redirect) #=> 306
-Faker::Internet::HTTP.status_code(group: :client_error) #=> 451
-Faker::Internet::HTTP.status_code(group: :server_error) #=> 502
-```
+Faker::HTTP.status_code #=> 418
+Faker::HTTP.status_code(group: :information) #=> 102
+Faker::HTTP.status_code(group: :successful) #=> 200
+Faker::HTTP.status_code(group: :redirect) #=> 306
+Faker::HTTP.status_code(group: :client_error) #=> 451
+Faker::HTTP.status_code(group: :server_error) #=> 502
+```

doc/music/music.md

@@ -3,17 +3,17 @@
 Available since version 1.6.4.
 
 ```ruby
-Faker::Music.key #=> "C"
+Faker::Song.key #=> "C"
 
-Faker::Music.chord #=> "Amaj7"
+Faker::Song.chord #=> "Amaj7"
 
-Faker::Music.instrument #=> "Ukelele"
+Faker::Song.instrument #=> "Ukelele"
 
-Faker::Music.band #=> "The Beatles"
+Faker::Song.band #=> "The Beatles"
 
-Faker::Music.album #=> "Sgt. Pepper's Lonely Hearts Club"
+Faker::Song.album #=> "Sgt. Pepper's Lonely Hearts Club"
 
-Faker::Music.genre #=> "Rock"
+Faker::Song.genre #=> "Rock"
 
-Faker::Music.mambo_no_5 #=> "Monica"
+Faker::Song.mambo_no_5 #=> "Monica"
 ```

experiments/lazy_loading.md

@@ -0,0 +1,103 @@
+# Lazy load experiment results
+
+Branch: sb-ta/lazy-load-experiment
+Date: February 10th, 2026
+Owner(s): Stefanni Brasil and Thiago Araujo
+
+## Impact
+
+Using `const_missing` to lazy load generators was an idea from talking with Jeremy Evans, who kindly responded our questions about improving faker's performance.
+
+### Changes needed
+
+#### Namespace changes
+
+A few generators had namespaces that didn't match their file name, and most of them were manageable, but two needed to be renamed:
+
+- `Faker::Music` -> `Faker::Song`. `Faker::Music` is a nested namespace.
+- `Faker::Internet::HTTP` -> `Faker::HTTP`. `Faker::Internet` is another generator.
+
+Considering that only two generators would be renamed, it wouldn't be a huge burden for users to use this approach.
+
+#### File location changes
+
+To prevent other generators from erroring out due to namespace clashing, some generators have to be moved around (ex. `Faker::Quote` was moved from `/faker/quotes/quote` to `faker/default/quote`). Users can still use the generators as before, their namespaces didn't change.
+
+### Benefits
+
+- no additional dependencies needed
+- code is extremely faster
+- after changing these two generators, which would be breaking changes, we can enable this as an opt-in configuration
+
+## Results
+
+profiler:
+
+[bundle exec vernier run -- ruby -e "require 'faker'" LAZY_LOAD=1](https://share.firefox.dev/3ZuCP55)
+[bundle exec vernier run --interval 100 --allocation-interval 10 -- ruby -e "require 'faker'; Faker::Internet.email" LAZY_LOAD=1](https://share.firefox.dev/4601PoA)
+
+benchmarks (Machine specs: Apple M1 Pro 16GB memory on MacOS Sequoia 15.7.3.)
+
+```sh
+benchmark % ruby require.rb
+took 250.0249999575317ms to load
+```
+
+```sh
+benchmark % ruby load.rb
+ruby 3.3.10 (2025-10-23 revision 343ea05002) [arm64-darwin24]
+Warming up --------------------------------------
+             require     1.000 i/100ms
+            lazyload     1.000 i/100ms
+Calculating -------------------------------------
+             require      5.874 (± 0.0%) i/s  (170.25 ms/i) -     30.000 in   5.115652s
+            lazyload     12.207 (± 8.2%) i/s   (81.92 ms/i) -     61.000 in   5.007059s
+
+Comparison:
+             require:        5.9 i/s
+            lazyload:       12.2 i/s - 2.08x  faster
+```
+
+## Artifacts
+
+### Scripts
+
+Constants were registered using this script:
+
+```ruby
+# lazy_load.rb
+
+CATEGORIES = {
+  Blockchain: 'blockchain',
+  Books: 'books',
+  Creature: 'creature',
+  Default: 'default',
+  Fantasy: 'fantasy',
+  Games: 'games',
+  JapaneseMedia: 'japanese_media',
+  Locations: 'locations',
+  Movies: 'movies',
+  Music: 'music',
+  Quotes: 'quotes',
+  Religion: 'religion',
+  Sports: 'sports',
+  Travel: 'travel',
+  TvShows: 'tv_shows'
+}.freeze
+
+def template(key)
+"# frozen_string_literal: true
+
+module Faker
+  class #{key}
+    if ENV['LAZY_LOAD'] == '1'
+      Faker.lazy_load(self)
+    end
+  end
+end"
+end
+
+CATEGORIES.each do |key, value|
+  File.write(File.join('lib', 'faker', "#{value}.rb"), template(key))
+end
+```

lib/faker.rb

@@ -275,7 +275,43 @@ def disable_enforce_available_locales
       end
     end
   end
+
+  if ENV['LAZY_LOAD'] == '1'
+    def self.load_path(*constants)
+      constants.map do |class_name|
+        class_name
+          .to_s
+          .gsub('::', '/')
+          .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+          .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+          .tr('-', '_')
+          .downcase
+      end.join('/')
+    end
+
+    def self.lazy_load(klass)
+      def klass.const_missing(class_name)
+        load_path = case class_name
+                    when :DnD
+                      Faker.load_path('faker/games/dnd')
+                    else
+                      Faker.load_path(name, class_name)
+                    end
+
+        begin
+          require(load_path)
+        rescue LoadError
+          require(load_path.gsub('faker/', 'faker/default/'))
+        end
+
+        const_get(class_name)
+      end
+    end
+
+    lazy_load(self)
+  end
 end
 
-# require faker objects
-Dir.glob(File.join(mydir, 'faker', '/**/*.rb')).each { |file| require file }
+if ENV['LAZY_LOAD'] != '1'
+  Dir.glob(File.join(mydir, 'faker', '/**/*.rb')).each { |file| require file }
+end

lib/faker/blockchain.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Faker
+  class Blockchain
+    if ENV['LAZY_LOAD'] == '1'
+      Faker.lazy_load(self)
+    end
+  end
+end

lib/faker/books.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Faker
+  class Books
+    if ENV['LAZY_LOAD'] == '1'
+      Faker.lazy_load(self)
+    end
+  end
+end

lib/faker/creature.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Faker
+  class Creature
+    if ENV['LAZY_LOAD'] == '1'
+      Faker.lazy_load(self)
+    end
+  end
+end