CHANGELOG.md

CHANGELOG

2.6.0 (13 June 2022)

• Directories are processed in lexicographic order.

  Different file systems may list directories in different order, and with this change we ensure that client code eager loads consistently across platforms, for example.

• Before this release, subdirectories of root directories always represented namespaces (unless ignored or collapsed). From now on, to be considered namespaces they also have to contain at least one non-ignored Ruby file with extension .rb, directly or recursively.

  If you know beforehand a certain directory or directory pattern does not represent a namespace, it is intentional and more efficient to tell Zeitwerk to ignore it.

  However, if you don't do so and have a directory tasks that only contains Rake files, arguably that directory is not meant to represent a Ruby module. Before, Zeitwerk would define a top-level Tasks module after it; now, it does not.

  This feature is also handy for projects that have directories with auxiliary resources mixed in the project tree in a way that is too dynamic for an ignore pattern to be practical. See #216.

  In the unlikely case that an existing project has an empty directory for the sole purpose of defining a totally empty module (no code, and no nested classes or modules), such module has now to be defined in a file.

  Directories are scanned again on reloads.

• On setup, loaders created with Zeitwerk::Loader.for_gem issue warnings if lib has extra, non-ignored Ruby files or directories.

  This is motivated by existing gems with directories under lib that are not meant to define Ruby modules, like directories for Rails generators, for instance.

  This warning can be silenced in the unlikely case that the extra stuff is actually autoloadable and has to be managed by Zeitwerk.

  Please, check the documentation for further details.

  This method returns an instance of a private subclass of Zeitwerk::Loader now, but you cannot rely on the type, just on the interface.

2.5.4 (28 January 2022)

• If a file did not define the expected constant, there was a reload, and there were on_unload callbacks, Zeitwerk still tried to access the constant during reload, which raised. This has been corrected.

2.5.3 (30 December 2021)

• The change introduced in 2.5.2 implied a performance regression that was particularly dramatic in Ruby 3.1. We'll address #198 in a different way.

2.5.2 (27 December 2021)

• When Module#autoload triggers the autovivification of an implicit namespace, $LOADED_FEATURES now gets the correspoding directory pushed. This is just a tweak to Zeitwerk's Kernel#require decoration. That way it acts more like the original, and cooperates better with other potential Kernel#require wrappers, like Bootsnap's.

2.5.1 (20 October 2021)

• Restores support for namespaces that are not hashable. For example namespaces that override the hash method with a different arity as shown in #188.

2.5.0 (20 October 2021)

Breaking changes

• Requires Ruby 2.5.

• Deletes the long time deprecated preload API. Instead of:

  loader.preload("app/models/user.rb")

  just reference the constant on setup:

  loader.on_setup { User }

  If you want to eager load a namespace, use the constants API:

  loader.on_setup do
    Admin.constants(false).each { |cname| Admin.const_get(cname) }
  end

Bug fixes

• Fixes a bug in which a certain valid combination of overlapping trees managed by different loaders and ignored directories was mistakenly reported as having conflicting directories.

• Detects external namespaces defined with Module#autoload. If your project reopens a 3rd party namespace, Zeitwerk already detected it and did not consider the namespace to be managed by the loader (automatically descends, ignored for reloads, etc.). However, the loader did not do that if the namespace had only an autoload in the 3rd party code yet to be executed. Now it does.

Callbacks

• Implements Zeitwerk::Loader#on_setup, which allows you to configure blocks of code to be executed on setup and on each reload. When the callback is fired, the loader is ready, you can refer to project constants in the block.

  See the documentation for further details.

• There is a new catch-all Zeitwerk::Loader#on_load that takes no argument and is triggered for all loaded objects:

  loader.on_load do |cpath, value, abspath|
    # ...
  end

  Please, remember that if you want to trace the activity of a loader, Zeitwerk::Loader#log! logs plenty of information.

  See the documentation for further details.

• The block of the existing Zeitwerk::Loader#on_load receives also the value stored in the constant, and the absolute path to its corresponding file or directory:

  loader.on_load("Service::NotificationsGateway") do |klass, abspath|
    # ...
  end

  Remember that blocks can be defined to take less arguments than passed. So this change is backwards compatible. If you had

  loader.on_load("Service::NotificationsGateway") do
    Service::NotificationsGateway.endpoint = ...
  end

  That works.

• Implements Zeitwerk::Loader#on_unload, which allows you to configure blocks of code to be executed before a certain class or module gets unloaded:

  loader.on_unload("Country") do |klass, _abspath|
    klass.clear_cache
  end

  These callbacks are invoked during unloading, which happens in an unspecified order. Therefore, they should not refer to reloadable constants.

  You can also be called for all unloaded objects:

  loader.on_unload do |cpath, value, abspath|
    # ...
  end

  Please, remember that if you want to trace the activity of a loader, Zeitwerk::Loader#log! logs plenty of information.

  See the documentation for further details.

Assorted

• Performance improvements.

• Documentation improvements.

• The method Zeitwerk::Loader#eager_load accepts a force flag:

  loader.eager_load(force: true)

  If passed, eager load exclusions configured with do_not_eager_load are not honoured (but ignored files and directories are).

  This may be handy for test suites that eager load in order to ensure all files define the expected constant.

• Eliminates internal use of File.realpath. One visible consequence is that in logs root dirs are shown as configured if they contain symlinks.

• When an autoloaded file does not define the expected constant, Ruby clears state differently starting with Ruby 3.1. Unloading has been revised to be compatible with both behaviours.

• Logging prints a few new traces.

2.4.2 (27 November 2020)

• Implements Zeitwerk::Loader#on_load, which allows you to configure blocks of code to be executed after a certain class or module have been loaded:

  # config/environments/development.rb
  loader.on_load("SomeApiClient") do
    SomeApiClient.endpoint = "https://api.dev"
  
  # config/environments/production.rb
  loader.on_load("SomeApiClient") do
    SomeApiClient.endpoint = "https://api.prod"
  end

  See the documentation for further details.

2.4.1 (29 October 2020)

• Use __send__ instead of send internally.

2.4.0 (15 July 2020)

• Zeitwerk::Loader#push_dir supports an optional namespace keyword argument. Pass a class or module object if you want the given root directory to be associated with it instead of Object. Said class or module object cannot be reloadable.

• The default inflector is even more performant.

2.3.1 (29 June 2020)

• Saves some unnecessary allocations made internally by MRI. See #125, by @casperisfine.

• Documentation improvements.

• Internal code base maintenance.

2.3.0 (3 March 2020)

• Adds support for collapsing directories.

  For example, if booking/actions/create.rb is meant to define Booking::Create because the subdirectory actions is there only for organizational purposes, you can tell Zeitwerk with collapse:

  loader.collapse("booking/actions")

  The method also accepts glob patterns to support standardized project structures:

  loader.collapse("*/actions")

  Please check the documentation for more details.

• Eager loading is idempotent, but now you can eager load again after reloading.

2.2.2 (29 November 2019)

• Zeitwerk::NameError#name has the name of the missing constant now.

2.2.1 (1 November 2019)

• Zeitwerk raised NameError when a managed file did not define its expected constant. Now, it raises Zeitwerk::NameError instead, so it is possible for client code to distinguish that mismatch from a regular NameError.

  Regarding backwards compatibility, Zeitwerk::NameError is a subclass of NameError.

2.2.0 (9 October 2019)

• The default inflectors have API to override how to camelize selected basenames:

  loader.inflector.inflect "mysql_adapter" => "MySQLAdapter"

  This addresses a common pattern, which is to use the basic inflectors with a few straightforward exceptions typically configured in a hash table or case expression. You no longer have to define a custom inflector if that is all you need.

• Documentation improvements.

2.1.10 (6 September 2019)

• Raises Zeitwerk::NameError with a better error message when a managed file or directory has a name that yields an invalid constant name when inflected. Zeitwerk::NameError is a subclass of NameError.

2.1.9 (16 July 2019)

• Preloading is soft-deprecated. The use case it was thought for is no longer. Please, if you have a legit use case for it, drop me a line.

• Root directory conflict detection among loaders takes ignored directories into account.

• Supports classes and modules with overridden name methods.

• Documentation improvements.

2.1.8 (29 June 2019)

• Fixes eager loading nested root directories. The new approach in 2.1.7 introduced a regression.

2.1.7 (29 June 2019)

• Prevent the inflector from deleting parts un multiword constants whose capitalization is the same. For example, point_2d should be inflected as Point2d, rather than Point. While the inflector is frozen, this seems to be just wrong, and the refinement should be backwards compatible, since those constants were not usable.

• Make eager loading consistent with auto loading with regard to detecting namespaces that do not define the matching constant.

• Documentation improvements.

2.1.6 (30 April 2019)

• Fixed: If an eager load exclusion contained an autoload for a namespace also present in other branches that had to be eager loaded, they could be skipped.

• loader.log! is a convenient shortcut to get traces to $stdout.

• Allocates less strings.

2.1.5 (24 April 2019)

• Failed autoloads raise NameError as always, but with a more user-friendly message instead of the original generic one from Ruby.

• Eager loading uses const_get now rather than require. A file that does not define the expected constant could be eager loaded, but not autoloaded, which would be inconsistent. Thanks to @casperisfine for reporting this one and help testing the alternative.

2.1.4 (23 April 2019)

• Supports deletion of root directories in disk after they've been configured.

  push_dir requires root directories to exist to prevent misconfigurations, but after that Zeitwerk no longer assumes they exist. This might be convenient if you removed one in a web application while a server was running.

2.1.3 (22 April 2019)

• Documentation improvements.
• Internal work.

2.1.2 (11 April 2019)

• Calling reload with reloading disabled raises Zeitwerk::ReloadingDisabledError.

2.1.1 (10 April 2019)

• Internal performance work.

2.1.0 (9 April 2019)

• loaded_cpaths is gone, you can ask if a constant path is going to be unloaded instead with loader.to_unload?(cpath). Thanks to this refinement, Zeitwerk is able to consume even less memory. (Change included in a minor upgrade because the introspection API is not documented, and it still isn't, needs some time to settle down).

2.0.0 (7 April 2019)

• Reloading is disabled by default. In order to be able to reload you need to opt-in by calling loader.enable_reloading before setup. The motivation for this breaking change is twofold. On one hand, this is a design decision at the interface/usage level that reflects that the majority of use cases for Zeitwerk do not need reloading. On the other hand, if reloading is not enabled, Zeitwerk is able to use less memory. Notably, this is more optimal for large web applications in production.

1.4.3 (26 March 2019)

• Faster reload. If you're using bootsnap, requires at least version 1.4.2.

1.4.2 (23 March 2019)

• Includes an optimization.

1.4.1 (23 March 2019)

• Fixes concurrent autovivifications.

1.4.0 (19 March 2019)

• Trace point optimization for singleton classes by @casperisfine. See the use case, explanation, and patch in #24.

• Zeitwerk::Loader#do_not_eager_load provides a way to have autoloadable files and directories that should be skipped when eager loading.

1.3.4 (14 March 2019)

• Files shadowed by previous occurrences defining the same constant path were being correctly skipped when autoloading, but not when eager loading. This has been fixed. This mimicks what happens when there are two files in $LOAD_PATH with the same relative name, only the first one is loaded by require.

1.3.3 (12 March 2019)

• Bug fix by @casperisfine: If the superclass or one of the ancestors of an explicit namespace N has an autoload set for constant C, and n/c.rb exists, the autoload for N::C proper could be missed.

1.3.2 (6 March 2019)

• Improved documentation.

• Zeitwerk creates at most one trace point per process, instead of one per loader. This is more performant when there are multiple gems managed by Zeitwerk.

1.3.1 (23 February 2019)

• After module vivification, the tracer could trigger one unnecessary autoload walk.

1.3.0 (21 February 2019)

• In addition to callables, loggers can now also be any object that responds to debug, which accepts one string argument.

1.2.0 (14 February 2019)

• Use pretty_print in the exception message for conflicting directories.

1.2.0.beta (14 February 2019)

• Two different loaders cannot be managing the same files. Now, Zeitwerk::Loader#push_dir raises Zeitwerk::ConflictingDirectory if it detects a conflict.

1.1.0 (14 February 2019)

• New class attribute Zeitwerk::Loader.default_logger, inherited by newly instantiated loaders. Default is nil.
• Traces include the loader tag in the prefix to easily distinguish them.
• Loaders now have a tag.

1.0.0 (12 February 2019)

• Documentation improvements.

1.0.0.beta3 (4 February 2019)

• Documentation improvements.
• Zeitwerk::Loader#ignore accepts glob patterns.
• New read-only introspection method Zeitwerk::Loader.all_dirs.
• New read-only introspection method Zeitwerk::Loader#dirs.
• New introspection predicate Zeitwerk::Loader#loaded?(cpath).

1.0.0.beta2 (22 January 2019)

• do_not_eager_load has been removed, please use ignore to opt-out.
• Documentation improvements.
• Pronunciation section in the README, linking to sample audio file.
• All logged messages have a "Zeitwerk:" prefix for easy grepping.
• On reload, the logger also traces constants and autoloads removed.

1.0.0.beta (18 January 2019)

• Initial beta release.