zeitwerk 2.4.2 → 2.5.0.beta

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f45a7c3caf48f06e10dd513a7b074da7ec059fa3299751d361514aadc83d995e
-  data.tar.gz: c8c29793e95245b47b1283891791d2c20365b8c694b3dcdfb7daab0b74c16bdb
+  metadata.gz: 7ac5e0ce2eba71a2099ead24de8762e3e737656ff4bcae57c83bb5797e922f72
+  data.tar.gz: 85e7c762a5164301ba5bcce82a31e6c49bc7c6caff2b4abff23c425f10374c69
 SHA512:
-  metadata.gz: 6194d326b268c9333ed9d2ac1c62b65756fa9af844c5fb7ad8272ecec33aa439015506758bcd329e421508facb4153e04e45da0efb0a2a42001a6f2e0a0d3b6a
-  data.tar.gz: 656009f40e777f641ff1dc80f54b63559514439538c73965aa9226b6c3e33c6be71c07eb30adfe7f4cd4b3be72aa6e42918392ba27167fb9502b9aed037f36d3
+  metadata.gz: f258acabd660f54702eb904550a109b08bdacff2cecc92d610376376f77ccf70ed421e09c64144930d2a145ebbedb7e9c3c26ff21ad2c1b40dd0537d9947b4d4
+  data.tar.gz: 1612dc2d505fe37b748d81a9055e36a91f9f73267ac273b39a4cbea3736cdd1baa4c557e3059d8f3a9a9807d450e29f3d75c7cb18c94c37ded70768444313336

data/README.md

@@ -3,41 +3,48 @@
 
 
 [![Gem Version](https://img.shields.io/gem/v/zeitwerk.svg?style=for-the-badge)](https://rubygems.org/gems/zeitwerk)
-[![Build Status](https://img.shields.io/travis/com/fxn/zeitwerk/master?style=for-the-badge)](https://travis-ci.com/fxn/zeitwerk)
+[![Build Status](https://img.shields.io/github/workflow/status/fxn/zeitwerk/CI?event=push&style=for-the-badge)](https://github.com/fxn/zeitwerk/actions?query=event%3Apush)
 
 <!-- TOC -->
 
 - [Introduction](#introduction)
 - [Synopsis](#synopsis)
 - [File structure](#file-structure)
-    - [Implicit namespaces](#implicit-namespaces)
-    - [Explicit namespaces](#explicit-namespaces)
-    - [Collapsing directories](#collapsing-directories)
+  - [The idea: File paths match constant paths](#the-idea-file-paths-match-constant-paths)
+  - [Inner simple constants](#inner-simple-constants)
+  - [Root directories and root namespaces](#root-directories-and-root-namespaces)
+    - [The default root namespace is `Object`](#the-default-root-namespace-is-object)
+    - [Custom root namespaces](#custom-root-namespaces)
     - [Nested root directories](#nested-root-directories)
+  - [Implicit namespaces](#implicit-namespaces)
+  - [Explicit namespaces](#explicit-namespaces)
+  - [Collapsing directories](#collapsing-directories)
 - [Usage](#usage)
-    - [Setup](#setup)
-        - [Generic](#generic)
-        - [for_gem](#for_gem)
-    - [Autoloading](#autoloading)
-    - [Eager loading](#eager-loading)
-    - [Reloading](#reloading)
-    - [Inflection](#inflection)
-        - [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)
-        - [Use case: Files that do not follow the conventions](#use-case-files-that-do-not-follow-the-conventions)
-        - [Use case: The adapter pattern](#use-case-the-adapter-pattern)
-        - [Use case: Test files mixed with implementation files](#use-case-test-files-mixed-with-implementation-files)
-    - [Edge cases](#edge-cases)
-    - [Reopening third-party namespaces](#reopening-third-party-namespaces)
-    - [Rules of thumb](#rules-of-thumb)
-    - [Debuggers](#debuggers)
-        - [Break](#break)
-        - [Byebug](#byebug)
+  - [Setup](#setup)
+    - [Generic](#generic)
+    - [for_gem](#for_gem)
+  - [Autoloading](#autoloading)
+  - [Eager loading](#eager-loading)
+  - [Reloading](#reloading)
+  - [Inflection](#inflection)
+    - [Zeitwerk::Inflector](#zeitwerkinflector)
+    - [Zeitwerk::GemInflector](#zeitwerkgeminflector)
+    - [Custom inflector](#custom-inflector)
+  - [The on_load callback](#the-on_load-callback)
+  - [The on_unload callback](#the-on_unload-callback)
+    - [Technical details](#technical-details)
+  - [Logging](#logging)
+    - [Loader tag](#loader-tag)
+  - [Ignoring parts of the project](#ignoring-parts-of-the-project)
+    - [Use case: Files that do not follow the conventions](#use-case-files-that-do-not-follow-the-conventions)
+    - [Use case: The adapter pattern](#use-case-the-adapter-pattern)
+    - [Use case: Test files mixed with implementation files](#use-case-test-files-mixed-with-implementation-files)
+  - [Edge cases](#edge-cases)
+  - [Reopening third-party namespaces](#reopening-third-party-namespaces)
+  - [Rules of thumb](#rules-of-thumb)
+  - [Debuggers](#debuggers)
+    - [Break](#break)
+    - [Byebug](#byebug)
 - [Pronunciation](#pronunciation)
 - [Supported Ruby versions](#supported-ruby-versions)
 - [Testing](#testing)
@@ -117,6 +124,9 @@ Zeitwerk::Loader.eager_load_all
 <a id="markdown-file-structure" name="file-structure"></a>
 ## File structure
 
+<a id="markdown-the-idea-file-paths-match-constant-paths" name="the-idea-file-paths-match-constant-paths"></a>
+### The idea: File paths match constant paths
+
 To have a file structure Zeitwerk can work with, just name files and directories after the name of the classes and modules they define:
 
 ```
@@ -126,25 +136,57 @@ lib/my_gem/bar_baz.rb -> MyGem::BarBaz
 lib/my_gem/woo/zoo.rb -> MyGem::Woo::Zoo
 ```
 
-Every directory configured with `push_dir` acts as root namespace. There can be several of them. For example, given
+You can tune that a bit by [collapsing directories](#collapsing-directories), or by [ignoring parts of the project](#ignoring-parts-of-the-project), but that is the main idea.
+
+<a id="markdown-inner-simple-constants" name="inner-simple-constants"></a>
+### Inner simple constants
+
+While a simple constant like `HttpCrawler::MAX_RETRIES` can be defined in its own file:
 
 ```ruby
-loader.push_dir(Rails.root.join("app/models"))
-loader.push_dir(Rails.root.join("app/controllers"))
+# http_crawler/max_retries.rb
+HttpCrawler::MAX_RETRIES = 10
 ```
 
-Zeitwerk understands that their respective files and subdirectories belong to the root namespace:
+that is not required, you can also define it the regular way:
 
+```ruby
+# http_crawler.rb
+class HttpCrawler
+  MAX_RETRIES = 10
+end
 ```
-app/models/user.rb                        -> User
-app/controllers/admin/users_controller.rb -> Admin::UsersController
+
+<a id="markdown-root-directories-and-root-namespaces" name="root-directories-and-root-namespaces"></a>
+### Root directories and root namespaces
+
+Every directory configured with `push_dir` is called a _root directory_, and they represent _root namespaces_.
+
+<a id="markdown-the-default-root-namespace-is-object" name="the-default-root-namespace-is-object"></a>
+#### The default root namespace is `Object`
+
+By default, the namespace associated to a root directory is the top-level one: `Object`.
+
+For example, given
+
+```ruby
+loader.push_dir("#{__dir__}/models")
+loader.push_dir("#{__dir__}/serializers"))
+```
+
+these are the expected classes and modules being defined by these files:
+
+```
+models/user.rb                 -> User
+serializers/user_serializer.rb -> UserSerializer
 ```
 
-Alternatively, you can associate a custom namespace to a root directory by passing a class or module object in the optional `namespace` keyword argument.
+<a id="markdown-custom-root-namespaces" name="custom-root-namespaces"></a>
+#### Custom root namespaces
 
-For example, Active Job queue adapters have to define a constant after their name in `ActiveJob::QueueAdapters`.
+While `Object` is by far the most common root namespace, you can associate a different one to a particular root directory. The method `push_dir` accepts a class or module object in the optional `namespace` keyword argument.
 
-So, if you declare
+For example, given:
 
 ```ruby
 require "active_job"
@@ -152,9 +194,26 @@ require "active_job/queue_adapters"
 loader.push_dir("#{__dir__}/adapters", namespace: ActiveJob::QueueAdapters)
 ```
 
-your adapter can be stored directly in that directory instead of the canonical `#{__dir__}/active_job/queue_adapters`.
+a file defining `ActiveJob::QueueAdapters::MyQueueAdapter` does not need the conventional parent directories, you can (and have to) store the file directly below `adapters`:
 
-Please, note that the given namespace must be non-reloadable, though autoloaded constants in that namespace can be. That is, if you associate `app/api` with an existing `Api` module, that module should not be reloadable. However, if the project defines and autoloads the class `Api::V2::Deliveries`, that one can be reloaded.
+```
+adapters/my_queue_adapter.rb -> ActiveJob::QueueAdapters::MyQueueAdapter
+```
+
+Please, note that the given root namespace must be non-reloadable, though autoloaded constants in that namespace can be. That is, if you associate `app/api` with an existing `Api` module, that module should not be reloadable. However, if the project defines and autoloads the class `Api::Deliveries`, that one can be reloaded.
+
+<a id="markdown-nested-root-directories" name="nested-root-directories"></a>
+#### Nested root directories
+
+Root directories should not be ideally nested, but Zeitwerk supports them because in Rails, for example, both `app/models` and `app/models/concerns` belong to the autoload paths.
+
+Zeitwerk detects nested root directories, and treats them as roots only. In the example above, `concerns` is not considered to be a namespace below `app/models`. For example, the file:
+
+```
+app/models/concerns/geolocatable.rb
+```
+
+should define `Geolocatable`, not `Concerns::Geolocatable`.
 
 <a id="markdown-implicit-namespaces" name="implicit-namespaces"></a>
 ### Implicit namespaces
@@ -216,19 +275,6 @@ To illustrate usage of glob patterns, if `actions` in the example above is part
 loader.collapse("#{__dir__}/*/actions")
 ```
 
-<a id="markdown-nested-root-directories" name="nested-root-directories"></a>
-### Nested root directories
-
-Root directories should not be ideally nested, but Zeitwerk supports them because in Rails, for example, both `app/models` and `app/models/concerns` belong to the autoload paths.
-
-Zeitwerk detects nested root directories, and treats them as roots only. In the example above, `concerns` is not considered to be a namespace below `app/models`. For example, the file:
-
-```
-app/models/concerns/geolocatable.rb
-```
-
-should define `Geolocatable`, not `Concerns::Geolocatable`.
-
 <a id="markdown-usage" name="usage"></a>
 ## Usage
 
@@ -522,26 +568,23 @@ With `on_load`, it is easy to schedule code at boot time that initializes `endpo
 
 ```ruby
 # config/environments/development.rb
-loader.on_load("SomeApiClient") do
-  SomeApiClient.endpoint = "https://api.dev"
+loader.on_load("SomeApiClient") do |klass, _abspath|
+  klass.endpoint = "https://api.dev"
 end
 
 # config/environments/production.rb
-loader.on_load("SomeApiClient") do
-  SomeApiClient.endpoint = "https://api.prod"
+loader.on_load("SomeApiClient") do |klass, _abspath|
+  klass.endpoint = "https://api.prod"
 end
 ```
 
-Uses cases:
+Some 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.
+`on_load` gets a target constant path as a string (e.g., "User", or "Service::NotificationsGateway"). When fired, its block receives the stored value, and the absolute path to the corresponding file or directory as a string. The callback is executed every time the target is loaded. That includes reloads.
 
 Multiple callbacks on the same target are supported, and they run in order of definition.
 
@@ -549,6 +592,66 @@ The block is executed once the loader has loaded the target. In particular, if t
 
 Defining a callback for a target not managed by the receiver is not an error, the block simply won't ever be executed.
 
+It is also possible to be called when any constant managed by the loader is loaded:
+
+```ruby
+loader.on_load do |cpath, value, abspath|
+  # ...
+end
+```
+
+The block gets the constant path as a string (e.g., "User", or "Foo::VERSION"), the value it stores (e.g., the class object stored in `User`, or "2.5.0"), and the absolute path to the corresponding file or directory as a string.
+
+Multiple callbacks like these are supported, and they run in order of definition.
+
+There are use cases for this last catch-all callback, but they are rare. If you just need to understand how things are being loaded for debugging purposes, please remember that `Zeitwerk::Loader#log!` logs plenty of information.
+
+If both types of callbacks are defined, the specific ones run first.
+
+<a id="markdown-the-on_unload-callback" name="the-on_unload-callback"></a>
+### The on_unload callback
+
+When reloading is enabled, you may occasionally need to execute something before a certain autoloaded class or module is unloaded. The `on_unload` callback allows you to do that.
+
+For example, let's imagine that a `Country` class fetches a list of countries and caches them when it is loaded. You might want to clear that cache if unloaded:
+
+```ruby
+loader.on_unload("Country") do |klass, _abspath|
+  klass.clear_cache
+end
+```
+
+`on_unload` gets a target constant path as a string (e.g., "User", or "Service::NotificationsGateway"). When fired, its block receives the stored value, and the absolute path to the corresponding file or directory as a string. The callback is executed every time the target is unloaded.
+
+`on_unload` blocks are executed before the class is unloaded, but in the middle of unloading, which happens in an unspecified order. Therefore, **that callback should not refer to any reloadable constant because there is no guarantee the constant works there**. Those blocks should rely on objects only, as in the example above, or regular constants not managed by the loader. This remark is transitive, applies to any methods invoked within the block.
+
+Multiple callbacks on the same target are supported, and they run in order of definition.
+
+Defining a callback for a target not managed by the receiver is not an error, the block simply won't ever be executed.
+
+It is also possible to be called when any constant managed by the loader is unloaded:
+
+```ruby
+loader.on_unload do |cpath, value, abspath|
+  # ...
+end
+```
+
+The block gets the constant path as a string (e.g., "User", or "Foo::VERSION"), the value it stores (e.g., the class object stored in `User`, or "2.5.0"), and the absolute path to the corresponding file or directory as a string.
+
+Multiple callbacks like these are supported, and they run in order of definition.
+
+If both types of callbacks are defined, the specific ones run first.
+
+<a id="markdown-technical-details" name="technical-details"></a>
+#### Technical details
+
+Zeitwerk uses the word "unload" to ease communication and for symmetry with `on_load`. However, in Ruby you cannot unload things for real. So, when does `on_unload` technically happen?
+
+When unloading, Zeitwerk issues `Module#remove_const` calls. Classes and modules are no longer reachable through their constants, and `on_unload` callbacks are executed right before those calls.
+
+Technically, though, the objects themselves are still alive, but if everything is used as expected and they are not stored in any non-reloadable place (don't do that), they are ready for garbage collection, which is when the real unloading happens.
+
 <a id="markdown-logging" name="logging"></a>
 ### Logging
 

data/lib/zeitwerk.rb

@@ -3,10 +3,12 @@
 module Zeitwerk
   require_relative "zeitwerk/real_mod_name"
   require_relative "zeitwerk/loader"
+  require_relative "zeitwerk/autoloads"
   require_relative "zeitwerk/registry"
   require_relative "zeitwerk/explicit_namespace"
   require_relative "zeitwerk/inflector"
   require_relative "zeitwerk/gem_inflector"
   require_relative "zeitwerk/kernel"
   require_relative "zeitwerk/error"
+  require_relative "zeitwerk/version"
 end

data/lib/zeitwerk/autoloads.rb

@@ -0,0 +1,69 @@
+module Zeitwerk
+  # @private
+  class Autoloads
+    # Maps crefs for which an autoload has been defined to the corresponding
+    # absolute path.
+    #
+    #   [Object, :User]  => "/Users/fxn/blog/app/models/user.rb"
+    #   [Object, :Hotel] => "/Users/fxn/blog/app/models/hotel"
+    #   ...
+    #
+    # This colection is transient, callbacks delete its entries as autoloads get
+    # executed.
+    #
+    # @sig Hash[[Module, Symbol], String]
+    attr_reader :c2a
+
+    # This is the inverse of c2a, for inverse lookups.
+    #
+    # @sig Hash[String, [Module, Symbol]]
+    attr_reader :a2c
+
+    # @sig () -> void
+    def initialize
+      @c2a = {}
+      @a2c = {}
+    end
+
+    # @sig (Module, Symbol, String) -> void
+    def define(parent, cname, abspath)
+      parent.autoload(cname, abspath)
+      cref = [parent, cname]
+      c2a[cref] = abspath
+      a2c[abspath] = cref
+    end
+
+    # @sig () { () -> [[Module, Symbol], String] } -> void
+    def each(&block)
+      c2a.each(&block)
+    end
+
+    # @sig (Module, Symbol) -> String?
+    def abspath_for(parent, cname)
+      c2a[[parent, cname]]
+    end
+
+    # @sig (String) -> [Module, Symbol]?
+    def cref_for(abspath)
+      a2c[abspath]
+    end
+
+    # @sig (String) -> [Module, Symbol]?
+    def delete(abspath)
+      cref = a2c.delete(abspath)
+      c2a.delete(cref)
+      cref
+    end
+
+    # @sig () -> void
+    def clear
+      c2a.clear
+      a2c.clear
+    end
+
+    # @sig () -> bool
+    def empty?
+      c2a.empty? && a2c.empty?
+    end
+  end
+end

data/lib/zeitwerk/explicit_namespace.rb

@@ -62,8 +62,14 @@ module Zeitwerk
         # than accessing its name.
         return if event.self.singleton_class?
 
-        # Note that it makes sense to compute the hash code unconditionally,
-        # because the trace point is disabled if cpaths is empty.
+        # It might be tempting to return if name.nil?, to avoid the computation
+        # of a hash code and delete call. But Ruby does not trigger the :class
+        # event on Class.new or Module.new, so that would incur in an extra call
+        # for nothing.
+        #
+        # On the other hand, if we were called, cpaths is not empty. Otherwise
+        # the tracer is disabled. So we do need to go ahead with the hash code
+        # computation and delete call.
         if loader = cpaths.delete(real_mod_name(event.self))
           loader.on_namespace_loaded(event.self)
           disable_tracer_if_unneeded

data/lib/zeitwerk/kernel.rb

@@ -12,7 +12,8 @@ module Kernel
   # On the other hand, if you publish a new version of a gem that is now managed
   # by Zeitwerk, client code can reference directly your classes and modules and
   # should not require anything. But if someone has legacy require calls around,
-  # they will work as expected, and in a compatible way.
+  # they will work as expected, and in a compatible way. This feature is by now
+  # EXPERIMENTAL and UNDOCUMENTED.
   #
   # We cannot decorate with prepend + super because Kernel has already been
   # included in Object, and changes in ancestors don't get propagated into
@@ -33,9 +34,9 @@ module Kernel
     else
       zeitwerk_original_require(path).tap do |required|
         if required
-          realpath = $LOADED_FEATURES.last
-          if loader = Zeitwerk::Registry.loader_for(realpath)
-            loader.on_file_autoloaded(realpath)
+          abspath = $LOADED_FEATURES.last
+          if loader = Zeitwerk::Registry.loader_for(abspath)
+            loader.on_file_autoloaded(abspath)
           end
         end
       end

data/lib/zeitwerk/loader.rb

@@ -5,78 +5,31 @@ require "securerandom"
 
 module Zeitwerk
   class Loader
+    require_relative "loader/helpers"
     require_relative "loader/callbacks"
-    include Callbacks
-    include RealModName
-
-    # @sig String
-    attr_reader :tag
+    require_relative "loader/config"
 
-    # @sig #camelize
-    attr_accessor :inflector
-
-    # @sig #call | #debug | nil
-    attr_accessor :logger
+    include RealModName
+    include Callbacks
+    include Helpers
+    include Config
 
-    # Absolute paths of the root directories. Stored in a hash to preserve
-    # order, easily handle duplicates, and also be able to have a fast lookup,
-    # needed for detecting nested paths.
+    # Keeps track of autoloads defined by the loader which have not been
+    # executed so far.
     #
-    #   "/Users/fxn/blog/app/assets"   => true,
-    #   "/Users/fxn/blog/app/channels" => true,
-    #   ...
+    # This metadata helps us implement a few things:
     #
-    # This is a private collection maintained by the loader. The public
-    # interface for it is `push_dir` and `dirs`.
+    # 1. When autoloads are triggered, ensure they define the expected constant
+    #    and invoke user callbacks. If reloading is enabled, remember cref and
+    #    abspath for later unloading logic.
     #
-    # @private
-    # @sig Hash[String, true]
-    attr_reader :root_dirs
-
-    # Absolute paths of files or directories that have to be preloaded.
+    # 2. When unloading, remove autoloads that have not been executed.
     #
-    # @private
-    # @sig Array[String]
-    attr_reader :preloads
-
-    # Absolute paths of files, directories, or glob patterns to be totally
-    # ignored.
+    # 3. Eager load with a recursive const_get, rather than a recursive require,
+    #    for consistency with lazy loading.
     #
     # @private
-    # @sig Set[String]
-    attr_reader :ignored_glob_patterns
-
-    # The actual collection of absolute file and directory names at the time the
-    # ignored glob patterns were expanded. Computed on setup, and recomputed on
-    # reload.
-    #
-    # @private
-    # @sig Set[String]
-    attr_reader :ignored_paths
-
-    # Absolute paths of directories or glob patterns to be collapsed.
-    #
-    # @private
-    # @sig Set[String]
-    attr_reader :collapse_glob_patterns
-
-    # The actual collection of absolute directory names at the time the collapse
-    # glob patterns were expanded. Computed on setup, and recomputed on reload.
-    #
-    # @private
-    # @sig Set[String]
-    attr_reader :collapse_dirs
-
-    # Maps real absolute paths for which an autoload has been set ---and not
-    # executed--- to their corresponding parent class or module and constant
-    # name.
-    #
-    #   "/Users/fxn/blog/app/models/user.rb"          => [Object, :User],
-    #   "/Users/fxn/blog/app/models/hotel/pricing.rb" => [Hotel, :Pricing]
-    #   ...
-    #
-    # @private
-    # @sig Hash[String, [Module, Symbol]]
+    # @sig Zeitwerk::Autoloads
     attr_reader :autoloads
 
     # We keep track of autoloaded directories to remove them from the registry
@@ -93,8 +46,8 @@ module Zeitwerk
     #
     #   "Admin::Role" => [".../admin/role.rb", [Admin, :Role]]
     #
-    # The cpath as key helps implementing unloadable_cpath? The real file name
-    # is stored in order to be able to delete it from $LOADED_FEATURES, and the
+    # The cpath as key helps implementing unloadable_cpath? The file name is
+    # stored in order to be able to delete it from $LOADED_FEATURES, and the
     # pair [Module, Symbol] is used to remove_const the constant from the class
     # or module object.
     #
@@ -123,15 +76,6 @@ module Zeitwerk
     # @sig Hash[String, Array[String]]
     attr_reader :lazy_subdirs
 
-    # Absolute paths of files or directories not to be eager loaded.
-    #
-    # @private
-    # @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
@@ -141,150 +85,21 @@ module Zeitwerk
     attr_reader :mutex2
 
     def initialize
-      @initialized_at = Time.now
-
-      @tag       = SecureRandom.hex(3)
-      @inflector = Inflector.new
-      @logger    = self.class.default_logger
-
-      @root_dirs              = {}
-      @preloads               = []
-      @ignored_glob_patterns  = Set.new
-      @ignored_paths          = Set.new
-      @collapse_glob_patterns = Set.new
-      @collapse_dirs          = Set.new
-      @autoloads              = {}
-      @autoloaded_dirs        = []
-      @to_unload              = {}
-      @lazy_subdirs           = {}
-      @eager_load_exclusions  = Set.new
-      @on_load_callbacks      = {}
-
-      # TODO: find a better name for these mutexes.
-      @mutex        = Mutex.new
-      @mutex2       = Mutex.new
-      @setup        = false
-      @eager_loaded = false
-
-      @reloading_enabled = false
-
-      Registry.register_loader(self)
-    end
-
-    # Sets a tag for the loader, useful for logging.
-    #
-    # @param tag [#to_s]
-    # @sig (#to_s) -> void
-    def tag=(tag)
-      @tag = tag.to_s
-    end
-
-    # Absolute paths of the root directories. This is a read-only collection,
-    # please push here via `push_dir`.
-    #
-    # @sig () -> Array[String]
-    def dirs
-      root_dirs.keys.freeze
-    end
-
-    # Pushes `path` to the list of root directories.
-    #
-    # Raises `Zeitwerk::Error` if `path` does not exist, or if another loader in
-    # the same process already manages that directory or one of its ascendants
-    # or descendants.
-    #
-    # @raise [Zeitwerk::Error]
-    # @sig (String | Pathname, Module) -> void
-    def push_dir(path, namespace: Object)
-      # Note that Class < Module.
-      unless namespace.is_a?(Module)
-        raise Error, "#{namespace.inspect} is not a class or module object, should be"
-      end
+      super
 
-      abspath = File.expand_path(path)
-      if dir?(abspath)
-        raise_if_conflicting_directory(abspath)
-        root_dirs[abspath] = namespace
-      else
-        raise Error, "the root directory #{abspath} does not exist"
-      end
-    end
+      @autoloads       = Autoloads.new
+      @autoloaded_dirs = []
+      @to_unload       = {}
+      @lazy_subdirs    = Hash.new { |h, cpath| h[cpath] = [] }
+      @mutex           = Mutex.new
+      @mutex2          = Mutex.new
+      @setup           = false
+      @eager_loaded    = false
 
-    # You need to call this method before setup in order to be able to reload.
-    # There is no way to undo this, either you want to reload or you don't.
-    #
-    # @raise [Zeitwerk::Error]
-    # @sig () -> void
-    def enable_reloading
-      mutex.synchronize do
-        break if @reloading_enabled
-
-        if @setup
-          raise Error, "cannot enable reloading after setup"
-        else
-          @reloading_enabled = true
-        end
-      end
-    end
-
-    # @sig () -> bool
-    def reloading_enabled?
-      @reloading_enabled
-    end
-
-    # Files or directories to be preloaded instead of lazy loaded.
-    #
-    # @sig (*(String | Pathname | Array[String | Pathname])) -> void
-    def preload(*paths)
-      mutex.synchronize do
-        expand_paths(paths).each do |abspath|
-          preloads << abspath
-          do_preload_abspath(abspath) if @setup
-        end
-      end
-    end
-
-    # Configure files, directories, or glob patterns to be totally ignored.
-    #
-    # @sig (*(String | Pathname | Array[String | Pathname])) -> void
-    def ignore(*glob_patterns)
-      glob_patterns = expand_paths(glob_patterns)
-      mutex.synchronize do
-        ignored_glob_patterns.merge(glob_patterns)
-        ignored_paths.merge(expand_glob_patterns(glob_patterns))
-      end
-    end
-
-    # Configure directories or glob patterns to be collapsed.
-    #
-    # @sig (*(String | Pathname | Array[String | Pathname])) -> void
-    def collapse(*glob_patterns)
-      glob_patterns = expand_paths(glob_patterns)
-      mutex.synchronize do
-        collapse_glob_patterns.merge(glob_patterns)
-        collapse_dirs.merge(expand_glob_patterns(glob_patterns))
-      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
+      Registry.register_loader(self)
     end
 
-    # Sets autoloads in the root namespace and preloads files, if any.
+    # Sets autoloads in the root namespace.
     #
     # @sig () -> void
     def setup
@@ -294,7 +109,6 @@ module Zeitwerk
         actual_root_dirs.each do |root_dir, namespace|
           set_autoloads_in_dir(root_dir, namespace)
         end
-        do_preload
 
         @setup = true
       end
@@ -319,21 +133,26 @@ module Zeitwerk
         # is enough.
         unloaded_files = Set.new
 
-        autoloads.each do |realpath, (parent, cname)|
+        autoloads.each do |(parent, cname), abspath|
           if parent.autoload?(cname)
             unload_autoload(parent, cname)
           else
             # Could happen if loaded with require_relative. That is unsupported,
             # and the constant path would escape unloadable_cpath? This is just
             # defensive code to clean things up as much as we are able to.
-            unload_cref(parent, cname)   if cdef?(parent, cname)
-            unloaded_files.add(realpath) if ruby?(realpath)
+            unload_cref(parent, cname)  if cdef?(parent, cname)
+            unloaded_files.add(abspath) if ruby?(abspath)
           end
         end
 
-        to_unload.each_value do |(realpath, (parent, cname))|
-          unload_cref(parent, cname)   if cdef?(parent, cname)
-          unloaded_files.add(realpath) if ruby?(realpath)
+        to_unload.each do |cpath, (abspath, (parent, cname))|
+          unless on_unload_callbacks.empty?
+            value = parent.const_get(cname)
+            run_on_unload_callbacks(cpath, value, abspath)
+          end
+
+          unload_cref(parent, cname)  if cdef?(parent, cname)
+          unloaded_files.add(abspath) if ruby?(abspath)
         end
 
         unless unloaded_files.empty?
@@ -393,27 +212,29 @@ module Zeitwerk
       mutex.synchronize do
         break if @eager_loaded
 
+        log("eager load start") if logger
+
         queue = []
         actual_root_dirs.each do |root_dir, namespace|
-          queue << [namespace, root_dir] unless eager_load_exclusions.member?(root_dir)
+          queue << [namespace, root_dir] unless excluded_from_eager_load?(root_dir)
         end
 
         while to_eager_load = queue.shift
           namespace, dir = to_eager_load
 
           ls(dir) do |basename, abspath|
-            next if eager_load_exclusions.member?(abspath)
+            next if excluded_from_eager_load?(abspath)
 
             if ruby?(abspath)
-              if cref = autoloads[File.realpath(abspath)]
-                cref[0].const_get(cref[1], false)
+              if cref = autoloads.cref_for(abspath)
+                cget(*cref)
               end
             elsif dir?(abspath) && !root_dirs.key?(abspath)
-              if collapse_dirs.member?(abspath)
+              if collapse?(abspath)
                 queue << [namespace, abspath]
               else
                 cname = inflector.camelize(basename, abspath)
-                queue << [namespace.const_get(cname, false), abspath]
+                queue << [cget(namespace, cname), abspath]
               end
             end
           end
@@ -425,15 +246,9 @@ module Zeitwerk
         autoloaded_dirs.clear
 
         @eager_loaded = true
-      end
-    end
 
-    # Let eager load ignore the given files or directories. The constants
-    # defined in those files are still autoloadable.
-    #
-    # @sig (*(String | Pathname | Array[String | Pathname])) -> void
-    def do_not_eager_load(*paths)
-      mutex.synchronize { eager_load_exclusions.merge(expand_paths(paths)) }
+        log("eager load end") if logger
+      end
     end
 
     # Says if the given constant path would be unloaded on reload. This
@@ -452,28 +267,6 @@ module Zeitwerk
       to_unload.keys.freeze
     end
 
-    # Logs to `$stdout`, handy shortcut for debugging.
-    #
-    # @sig () -> void
-    def log!
-      @logger = ->(msg) { puts msg }
-    end
-
-    # @private
-    # @sig (String) -> bool
-    def manages?(dir)
-      dir = dir + "/"
-      ignored_paths.each do |ignored_path|
-        return false if dir.start_with?(ignored_path + "/")
-      end
-
-      root_dirs.each_key do |root_dir|
-        return true if root_dir.start_with?(dir) || dir.start_with?(root_dir + "/")
-      end
-
-      false
-    end
-
     # --- Class methods ---------------------------------------------------------------------------
 
     class << self
@@ -521,19 +314,12 @@ module Zeitwerk
 
     private # -------------------------------------------------------------------------------------
 
-    # @sig () -> Array[String]
-    def actual_root_dirs
-      root_dirs.reject do |root_dir, _namespace|
-        !dir?(root_dir) || ignored_paths.member?(root_dir)
-      end
-    end
-
     # @sig (String, Module) -> void
     def set_autoloads_in_dir(dir, parent)
       ls(dir) do |basename, abspath|
         begin
           if ruby?(basename)
-            basename[-3..-1] = ''
+            basename.delete_suffix!(".rb")
             cname = inflector.camelize(basename, abspath).to_sym
             autoload_file(parent, cname, abspath)
           elsif dir?(abspath)
@@ -543,9 +329,9 @@ module Zeitwerk
             # To resolve the ambiguity file name -> constant path this introduces,
             # the `app/models/concerns` directory is totally ignored as a namespace,
             # it counts only as root. The guard checks that.
-            unless root_dirs.key?(abspath)
+            unless root_dir?(abspath)
               cname = inflector.camelize(basename, abspath).to_sym
-              if collapse_dirs.member?(abspath)
+              if collapse?(abspath)
                 set_autoloads_in_dir(abspath, parent)
               else
                 autoload_subdir(parent, cname, abspath)
@@ -573,27 +359,28 @@ module Zeitwerk
 
     # @sig (Module, Symbol, String) -> void
     def autoload_subdir(parent, cname, subdir)
-      if autoload_path = autoload_for?(parent, cname)
+      if autoload_path = autoloads.abspath_for(parent, cname)
         cpath = cpath(parent, cname)
         register_explicit_namespace(cpath) if ruby?(autoload_path)
         # We do not need to issue another autoload, the existing one is enough
         # no matter if it is for a file or a directory. Just remember the
         # subdirectory has to be visited if the namespace is used.
-        (lazy_subdirs[cpath] ||= []) << subdir
+        lazy_subdirs[cpath] << subdir
       elsif !cdef?(parent, cname)
         # First time we find this namespace, set an autoload for it.
-        (lazy_subdirs[cpath(parent, cname)] ||= []) << subdir
+        lazy_subdirs[cpath(parent, cname)] << subdir
         set_autoload(parent, cname, subdir)
       else
         # For whatever reason the constant that corresponds to this namespace has
         # already been defined, we have to recurse.
-        set_autoloads_in_dir(subdir, parent.const_get(cname))
+        log("the namespace #{cpath(parent, cname)} already exists, descending into #{subdir}") if logger
+        set_autoloads_in_dir(subdir, cget(parent, cname))
       end
     end
 
     # @sig (Module, Symbol, String) -> void
     def autoload_file(parent, cname, file)
-      if autoload_path = autoload_for?(parent, cname)
+      if autoload_path = strict_autoload_path(parent, cname) || Registry.inception?(cpath(parent, cname))
         # First autoload for a Ruby file wins, just ignore subsequent ones.
         if ruby?(autoload_path)
           log("file #{file} is ignored because #{autoload_path} has precedence") if logger
@@ -620,163 +407,32 @@ module Zeitwerk
       autoloads.delete(dir)
       Registry.unregister_autoload(dir)
 
+      log("earlier autoload for #{cpath(parent, cname)} discarded, it is actually an explicit namespace defined in #{file}") if logger
+
       set_autoload(parent, cname, file)
       register_explicit_namespace(cpath(parent, cname))
     end
 
     # @sig (Module, Symbol, String) -> void
     def set_autoload(parent, cname, abspath)
-      # $LOADED_FEATURES stores real paths since Ruby 2.4.4. We set and save the
-      # real path to be able to delete it from $LOADED_FEATURES on unload, and to
-      # be able to do a lookup later in Kernel#require for manual require calls.
-      #
-      # We freeze realpath because that saves allocations in Module#autoload.
-      # See #125.
-      realpath = File.realpath(abspath).freeze
-      parent.autoload(cname, realpath)
+      autoloads.define(parent, cname, abspath)
+
       if logger
-        if ruby?(realpath)
-          log("autoload set for #{cpath(parent, cname)}, to be loaded from #{realpath}")
+        if ruby?(abspath)
+          log("autoload set for #{cpath(parent, cname)}, to be loaded from #{abspath}")
         else
-          log("autoload set for #{cpath(parent, cname)}, to be autovivified from #{realpath}")
+          log("autoload set for #{cpath(parent, cname)}, to be autovivified from #{abspath}")
         end
       end
 
-      autoloads[realpath] = [parent, cname]
-      Registry.register_autoload(self, realpath)
+      Registry.register_autoload(self, abspath)
 
       # See why in the documentation of Zeitwerk::Registry.inceptions.
       unless parent.autoload?(cname)
-        Registry.register_inception(cpath(parent, cname), realpath, self)
-      end
-    end
-
-    # @sig (Module, Symbol) -> String?
-    def autoload_for?(parent, cname)
-      strict_autoload_path(parent, cname) || Registry.inception?(cpath(parent, cname))
-    end
-
-    # The autoload? predicate takes into account the ancestor chain of the
-    # receiver, like const_defined? and other methods in the constants API do.
-    #
-    # For example, given
-    #
-    #   class A
-    #     autoload :X, "x.rb"
-    #   end
-    #
-    #   class B < A
-    #   end
-    #
-    # B.autoload?(:X) returns "x.rb".
-    #
-    # We need a way to strictly check in parent ignoring ancestors.
-    #
-    # @sig (Module, Symbol) -> String?
-    if method(:autoload?).arity == 1
-      def strict_autoload_path(parent, cname)
-        parent.autoload?(cname) if cdef?(parent, cname)
-      end
-    else
-      def strict_autoload_path(parent, cname)
-        parent.autoload?(cname, false)
-      end
-    end
-
-    # This method is called this way because I prefer `preload` to be the method
-    # name to configure preloads in the public interface.
-    #
-    # @sig () -> void
-    def do_preload
-      preloads.each do |abspath|
-        do_preload_abspath(abspath)
+        Registry.register_inception(cpath(parent, cname), abspath, self)
       end
     end
 
-    # @sig (String) -> void
-    def do_preload_abspath(abspath)
-      if ruby?(abspath)
-        do_preload_file(abspath)
-      elsif dir?(abspath)
-        do_preload_dir(abspath)
-      end
-    end
-
-    # @sig (String) -> void
-    def do_preload_dir(dir)
-      ls(dir) do |_basename, abspath|
-        do_preload_abspath(abspath)
-      end
-    end
-
-    # @sig (String) -> bool
-    def do_preload_file(file)
-      log("preloading #{file}") if logger
-      require file
-    end
-
-    # @sig (Module, Symbol) -> String
-    def cpath(parent, cname)
-      parent.equal?(Object) ? cname.to_s : "#{real_mod_name(parent)}::#{cname}"
-    end
-
-    # @sig (String) { (String, String) -> void } -> void
-    def ls(dir)
-      Dir.foreach(dir) do |basename|
-        next if basename.start_with?(".")
-
-        abspath = File.join(dir, basename)
-        next if ignored_paths.member?(abspath)
-
-        # We freeze abspath because that saves allocations when passed later to
-        # File methods. See #125.
-        yield basename, abspath.freeze
-      end
-    end
-
-    # @sig (String) -> bool
-    def ruby?(path)
-      path.end_with?(".rb")
-    end
-
-    # @sig (String) -> bool
-    def dir?(path)
-      File.directory?(path)
-    end
-
-    # @sig (String | Pathname | Array[String | Pathname]) -> Array[String]
-    def expand_paths(paths)
-      paths.flatten.map! { |path| File.expand_path(path) }
-    end
-
-    # @sig (Array[String]) -> Array[String]
-    def expand_glob_patterns(glob_patterns)
-      # Note that Dir.glob works with regular file names just fine. That is,
-      # glob patterns technically need no wildcards.
-      glob_patterns.flat_map { |glob_pattern| Dir.glob(glob_pattern) }
-    end
-
-    # @sig () -> void
-    def recompute_ignored_paths
-      ignored_paths.replace(expand_glob_patterns(ignored_glob_patterns))
-    end
-
-    # @sig () -> void
-    def recompute_collapse_dirs
-      collapse_dirs.replace(expand_glob_patterns(collapse_glob_patterns))
-    end
-
-    # @sig (String) -> void
-    def log(message)
-      method_name = logger.respond_to?(:debug) ? :debug : :call
-      logger.send(method_name, "Zeitwerk@#{tag}: #{message}")
-    end
-
-    # @sig (Module, Symbol) -> bool
-    def cdef?(parent, cname)
-      parent.const_defined?(cname, false)
-    end
-
     # @sig (String) -> void
     def register_explicit_namespace(cpath)
       ExplicitNamespace.register(cpath, self)
@@ -797,6 +453,13 @@ module Zeitwerk
       end
     end
 
+    # @sig (String, Object, String) -> void
+    def run_on_unload_callbacks(cpath, value, abspath)
+      # Order matters. If present, run the most specific one.
+      on_unload_callbacks[cpath]&.each { |c| c.call(value, abspath) }
+      on_unload_callbacks[:ANY]&.each { |c| c.call(cpath, value, abspath) }
+    end
+
     # @sig (Module, Symbol) -> void
     def unload_autoload(parent, cname)
       parent.__send__(:remove_const, cname)