Skip to content

Commit 408c83c

Browse files
committed
docs(core): Document the 'undefined' sentinel value for reactive config initialization (#9287)
1 parent ed3f0dc commit 408c83c

1 file changed

Lines changed: 7 additions & 0 deletions

File tree

src/core/Base.mjs

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -71,6 +71,13 @@ class Base {
7171
* - `beforeSetMyConfig(newValue, oldValue)`: Executed before a new value is set. Can be used for validation or transformation. Returning `undefined` from this hook will cancel the update.
7272
* - `afterSetMyConfig(newValue, oldValue)`: Executed after a new value has been successfully set. Ideal for triggering side effects.
7373
*
74+
* **The `undefined` Sentinel Value:**
75+
* In Neo.mjs, `undefined` is used as a strict, immutable sentinel value representing "initial instantiation".
76+
* When an `afterSet` hook runs for the very first time during component creation, its `oldValue` will ALWAYS be `undefined`.
77+
* This allows developers to easily skip logic that should not run during setup using a simple `if (oldValue !== undefined)`.
78+
* Because of this architecture, **you should never set a config to `undefined` later in its lifecycle.**
79+
* If you need to clear or reset a config's state, explicitly set it to `null`.
80+
*
7481
* 2. **Non-Reactive (Prototype-based) Configs:** Property names without a trailing underscore.
7582
* These are applied directly to the class's **prototype** during the `Neo.setupClass`
7683
* process. This is highly memory-efficient as the value is shared across all instances.

0 commit comments

Comments
 (0)