zeitwerk 2.4.1 → 2.4.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0c408b8f6001e150b16b1e06b1b05d31bcbf4f0144535c995093c822065be3d
-  data.tar.gz: af26de0ecd68b8ebc1836ea431d59c6d7e10d79937c402e3529fc4275631c950
+  metadata.gz: f45a7c3caf48f06e10dd513a7b074da7ec059fa3299751d361514aadc83d995e
+  data.tar.gz: c8c29793e95245b47b1283891791d2c20365b8c694b3dcdfb7daab0b74c16bdb
 SHA512:
-  metadata.gz: 012c9a70cd31973a7251f46f62c102bf11155a6ea90dcdfa62bb2cd1859fca07cfed268dd130528fc55eab4ea0d440347e7ed0cb78f54dca861f96f56014541d
-  data.tar.gz: 7243c0f9b6c39dd389f0570fe03f11a8cadb01b74ae5d5efaa9b895ecf3b2717b5eb71e027c555f1cfeb95457dd5f5d8ace4516eb3a77500b05b1c8f973c1a94
+  metadata.gz: 6194d326b268c9333ed9d2ac1c62b65756fa9af844c5fb7ad8272ecec33aa439015506758bcd329e421508facb4153e04e45da0efb0a2a42001a6f2e0a0d3b6a
+  data.tar.gz: 656009f40e777f641ff1dc80f54b63559514439538c73965aa9226b6c3e33c6be71c07eb30adfe7f4cd4b3be72aa6e42918392ba27167fb9502b9aed037f36d3

data/README.md

@@ -25,6 +25,7 @@
         - [Zeitwerk::Inflector](#zeitwerkinflector)
         - [Zeitwerk::GemInflector](#zeitwerkgeminflector)
         - [Custom inflector](#custom-inflector)
+    - [The on_load callback](#the-on_load-callback)
     - [Logging](#logging)
         - [Loader tag](#loader-tag)
     - [Ignoring parts of the project](#ignoring-parts-of-the-project)
@@ -502,6 +503,52 @@ class MyGem::Inflector < Zeitwerk::GemInflector
 end
 ```
 
+<a id="markdown-the-on_load-callback" name="the-on_load-callback"></a>
+### The on_load callback
+
+The usual place to run something when a file is loaded is the file itself. However, sometimes you'd like to be called, and this is possible with the `on_load` callback.
+
+For example, let's imagine this class belongs to a Rails application:
+
+```ruby
+class SomeApiClient
+  class << self
+    attr_accessor :endpoint
+  end
+end
+```
+
+With `on_load`, it is easy to schedule code at boot time that initializes `endpoint` according to the configuration:
+
+```ruby
+# config/environments/development.rb
+loader.on_load("SomeApiClient") do
+  SomeApiClient.endpoint = "https://api.dev"
+end
+
+# config/environments/production.rb
+loader.on_load("SomeApiClient") do
+  SomeApiClient.endpoint = "https://api.prod"
+end
+```
+
+Uses cases:
+
+* Doing something with an autoloadable class or module in a Rails application during initialization, in a way that plays well with reloading. As in the previous example.
+* Delaying the execution of the block until the class is loaded for performance.
+* Delaying the execution of the block until the class is loaded because it follows the adapter pattern and better not to load the class if the user does not need it.
+* Etc.
+
+However, let me stress that the easiest way to accomplish that is to write whatever you have to do in the actual target file. `on_load` use cases are edgy, use it only if appropriate.
+
+`on_load` receives the name of the target class or module as a string. The given block is executed every time its corresponding file is loaded. That includes reloads.
+
+Multiple callbacks on the same target are supported, and they run in order of definition.
+
+The block is executed once the loader has loaded the target. In particular, if the target was already loaded when the callback is defined, the block won't run. But if you reload and load the target again, then it will. Normally, you'll want to define `on_load` callbacks before `setup`.
+
+Defining a callback for a target not managed by the receiver is not an error, the block simply won't ever be executed.
+
 <a id="markdown-logging" name="logging"></a>
 ### Logging
 

data/lib/zeitwerk/kernel.rb

@@ -28,6 +28,7 @@ module Kernel
         end
       else
         loader.on_dir_autoloaded(path)
+        true
       end
     else
       zeitwerk_original_require(path).tap do |required|

data/lib/zeitwerk/loader.rb

@@ -129,6 +129,9 @@ module Zeitwerk
     # @sig Set[String]
     attr_reader :eager_load_exclusions
 
+    # User-oriented callbacks to be fired when a constant is loaded.
+    attr_reader :on_load_callbacks
+
     # @private
     # @sig Mutex
     attr_reader :mutex
@@ -155,6 +158,7 @@ module Zeitwerk
       @to_unload              = {}
       @lazy_subdirs           = {}
       @eager_load_exclusions  = Set.new
+      @on_load_callbacks      = {}
 
       # TODO: find a better name for these mutexes.
       @mutex        = Mutex.new
@@ -262,6 +266,24 @@ module Zeitwerk
       end
     end
 
+    # Configure a block to be invoked once a certain constant path is loaded.
+    # Supports multiple callbacks, and if there are many, they are executed in
+    # the order in which they were defined.
+    #
+    #   loader.on_load("SomeApiClient") do
+    #     SomeApiClient.endpoint = "https://api.dev"
+    #   end
+    #
+    # @raise [TypeError]
+    # @sig (String) { () -> void } -> void
+    def on_load(cpath, &block)
+      raise TypeError, "on_load only accepts strings" unless cpath.is_a?(String)
+
+      mutex.synchronize do
+        (on_load_callbacks[cpath] ||= []) << block
+      end
+    end
+
     # Sets autoloads in the root namespace and preloads files, if any.
     #
     # @sig () -> void

data/lib/zeitwerk/loader/callbacks.rb

@@ -6,15 +6,19 @@ module Zeitwerk::Loader::Callbacks
   # @private
   # @sig (String) -> void
   def on_file_autoloaded(file)
-    cref = autoloads.delete(file)
-    to_unload[cpath(*cref)] = [file, cref] if reloading_enabled?
+    cref  = autoloads.delete(file)
+    cpath = cpath(*cref)
+
+    to_unload[cpath] = [file, cref] if reloading_enabled?
     Zeitwerk::Registry.unregister_autoload(file)
 
     if logger && cdef?(*cref)
-      log("constant #{cpath(*cref)} loaded from file #{file}")
+      log("constant #{cpath} loaded from file #{file}")
     elsif !cdef?(*cref)
-      raise Zeitwerk::NameError.new("expected file #{file} to define constant #{cpath(*cref)}, but didn't", cref.last)
+      raise Zeitwerk::NameError.new("expected file #{file} to define constant #{cpath}, but didn't", cref.last)
     end
+
+    run_on_load_callbacks(cpath)
   end
 
   # Invoked from our decorated Kernel#require when a managed directory is
@@ -37,9 +41,10 @@ module Zeitwerk::Loader::Callbacks
     mutex2.synchronize do
       if cref = autoloads.delete(dir)
         autovivified_module = cref[0].const_set(cref[1], Module.new)
-        log("module #{autovivified_module.name} autovivified from directory #{dir}") if logger
+        cpath = autovivified_module.name
+        log("module #{cpath} autovivified from directory #{dir}") if logger
 
-        to_unload[autovivified_module.name] = [dir, cref] if reloading_enabled?
+        to_unload[cpath] = [dir, cref] if reloading_enabled?
 
         # We don't unregister `dir` in the registry because concurrent threads
         # wouldn't find a loader associated to it in Kernel#require and would
@@ -48,6 +53,8 @@ module Zeitwerk::Loader::Callbacks
         autoloaded_dirs << dir
 
         on_namespace_loaded(autovivified_module)
+
+        run_on_load_callbacks(cpath)
       end
     end
   end
@@ -65,4 +72,15 @@ module Zeitwerk::Loader::Callbacks
       end
     end
   end
+
+  private
+
+  # @sig (String) -> void
+  def run_on_load_callbacks(cpath)
+    # Very common, do not even compute a hash code.
+    return if on_load_callbacks.empty?
+
+    callbacks = reloading_enabled? ? on_load_callbacks[cpath] : on_load_callbacks.delete(cpath)
+    callbacks.each(&:call) if callbacks
+  end
 end

data/lib/zeitwerk/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Zeitwerk
-  VERSION = "2.4.1"
+  VERSION = "2.4.2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: zeitwerk
 version: !ruby/object:Gem::Version
-  version: 2.4.1
+  version: 2.4.2
 platform: ruby
 authors:
 - Xavier Noria
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2020-10-29 00:00:00.000000000 Z
+date: 2020-11-27 00:00:00.000000000 Z
 dependencies: []
 description: |2
       Zeitwerk implements constant autoloading with Ruby semantics. Each gem