Walkthrough

Replaces in-file defer implementation with a new lib/defer module and re-exports, adds Util.resolveAsyncConfigs() and support for invoking config files as factory functions with injected {defer, util}, updates docs/deprecation notes, tests, and copyright years.

Changes

Sequence Diagram(s)

sequenceDiagram
    participant App as Application
    participant Loader as Config Loader
    participant ConfigFn as Config Function
    participant Util as Util
    participant Defer as lib/defer

    App->>Loader: require/load config file
    Loader->>ConfigFn: invoke with ({defer: Defer.deferConfig, util: Util})
    ConfigFn->>Defer: create deferred values (deferConfig)
    ConfigFn-->>Loader: return config object (may contain DeferredConfig or Promises)
    Loader->>Util: Util.resolveAsyncConfigs(config)
    Util->>Util: traverse config, collect Promises/Deferreds
    Util->>Defer: prepare/resolve deferreds (resolve may return Promises)
    Util->>Util: Promise.all on collected promises
    Util-->>App: finalized, resolved config object

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Possibly related PRs

• Delete deprecated functions in Config.util, and associated tests. #845 — touches the deferred-config resolution API and relates to exposing/exporting defer for bundlers and similar loader scenarios.

Suggested labels

breaking-change

Suggested reviewers

• markstos

Poem

🐰 I nibbled code where deferred seeds lay,
I planted getters that wake and say "play",
Promises bloom when util tends the plot,
A config garden—resolved on the dot. 🥕✨

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

• 📝 Generate docstrings

lib/defer.js (1)

14-22: Consider documenting the double-assignment pattern for async resolution.

The pattern of setting the property first to the promise (line 18) then to the resolved value (line 19) is clever—it allows intermediate access to get the in-flight promise. However, this behavior isn't immediately obvious.

A brief inline comment explaining this design choice would help future maintainers understand the intent.

📝 Suggested documentation

     if (isAsyncFunction(func)) {
       obj.resolve = async function () {
         const promise = func.call(config, config, original);
 
+        // First, expose the promise for intermediate access, then replace with resolved value
         Object.defineProperty(prop, property, { value: promise });
         Object.defineProperty(prop, property, { value: await promise });
 
         return promise;
       }

defer.js (2)

3-6: Clarify the deprecation message with actionable guidance.

The current deprecation message mentions "the new callback mechanism" without explaining what it is or how users should migrate. Consider either:

1. Specifying the new import path if users should import directly from lib/defer
2. Explaining what "callback mechanism" refers to (e.g., passing factory functions to config files)

📝 Suggested improvement

 /**
- * `@deprecated` please use the new callback mechanism
- * `@see` lib/defer.js
+ * `@deprecated` Import from 'config/lib/defer' instead, or use the config file callback pattern
+ * which provides defer injection. See lib/defer.js for implementation details.
  */

---

9-12: Add @see reference for consistency with deferConfig deprecation.

The DeferredConfig deprecation is missing the @see reference that's present in the deferConfig deprecation above.

📝 Suggested fix

 /**
  * `@deprecated` please use the new callback mechanism
+ * `@see` lib/defer.js
  */
 module.exports.DeferredConfig = DeferredConfig;

Configuration used: defaults

Review profile: CHILL

Plan: Pro

_{✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.}

• X
• Mastodon
• Reddit
• LinkedIn