Walkthrough

Adds a public RawConfig class and factory in lib/util.js, threads RawConfig.raw into bootstrap callback context for executable config files, makes raw.js delegate to RawConfig.raw with a deprecation warning, and updates lib/config.js to import RawConfig from ./util.js.

Changes

Sequence Diagram(s)

sequenceDiagram
  participant Loader as Load
  participant Util as Util
  participant Raw as RawConfig
  participant ConfigFn as Config File (function)
  Loader->>ConfigFn: invoke({ defer, util: Util, raw: Raw.raw })
  ConfigFn->>Raw: (optional) call Raw.raw(...)
  ConfigFn-->>Loader: return config object
  Loader->>Util: clone/merge (treat RawConfig as pass-through)
  Loader-->>Caller: final config

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐇 I nibbled bytes and kept them whole,
A raw little parcel, safe for your goal.
Bootstrap carries my quiet cheer,
No copying fuss — I stay right here,
Hooray — configs hop without a toll!

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

• 📝 Generate docstrings

lib/util.js (4)

460-465: RawConfig pass-through in cloneDeep is correct but could return early.

Setting child = parent preserves the reference (intended). Since RawConfig has no enumerable own properties, the subsequent for...in loop is a no-op, so the result is correct. However, unlike the Buffer case (line 463), this doesn't return child early, meaning the instance is unnecessarily registered in the circular-reference tracking arrays.

Consider adding an early return for consistency with the Buffer path:

♻️ Optional: return early like Buffer

       } else if (parent instanceof RawConfig) {
-        child = parent;
+        return parent;
       } else {

---

651-670: Pre-existing: Date assignment at line 652 can be overwritten by the fall-through.

The RawConfig addition to the RegExp condition (line 656) is correct — both are properly guarded by the if/else if chain starting at line 655.

However, the standalone if block for Date (lines 651–653) has no else and falls through to the RegExp/RawConfig if at line 655. When mergeFrom[prop] is a Date, it's assigned at line 652, but then the else if at line 658 can fire (since Util.isObject(date) is true), potentially calling extendDeep on it. This is pre-existing and not introduced by this PR, but worth noting since you're editing this block.

♻️ Optional: chain the Date block into the if/else

-        if (mergeFrom[prop] instanceof Date) {
+        if (mergeFrom[prop] instanceof Date) {
           mergeInto[prop] = mergeFrom[prop];
-        }
-
-        if ((mergeFrom[prop] instanceof RegExp) ||
+        } else if ((mergeFrom[prop] instanceof RegExp) ||
             (mergeFrom[prop] instanceof RawConfig)) {

---

1040-1045: Bootstrap callback context looks good; minor JSDoc nit.

Passing raw: RawConfig.raw as a static method reference is consistent with how defer: deferConfig is passed.

Line 1041: @type bootstrapCallback should use braces per JSDoc convention: @type {bootstrapCallback}.

📝 Fix JSDoc syntax

-      /** `@type` bootstrapCallback */
+      /** `@type` {bootstrapCallback} */

---

17-22: JSDoc type {RawConfig.raw} is non-standard.

RawConfig.raw is a static method, so {RawConfig.raw} isn't a valid JSDoc type reference. Consider using {typeof RawConfig.raw} or an explicit function signature like {function(Object): RawConfig}.

• X
• Mastodon
• Reddit
• LinkedIn