neo.mjs 10.0.0-beta.3 → 10.0.0-beta.5

package/src/Neo.mjs

@@ -1,17 +1,46 @@
-import DefaultConfig from './DefaultConfig.mjs';
+import DefaultConfig  from './DefaultConfig.mjs';
+import {isDescriptor} from './core/ConfigSymbols.mjs';
 
 const
     camelRegex   = /-./g,
     configSymbol = Symbol.for('configSymbol'),
     getSetCache  = Symbol('getSetCache'),
+    cloneMap = {
+        Array(obj, deep, ignoreNeoInstances) {
+            return !deep ? [...obj] : [...obj.map(val => Neo.clone(val, deep, ignoreNeoInstances))]
+        },
+        Date(obj) {
+            return new Date(obj.valueOf())
+        },
+        Map(obj) {
+            return new Map(obj) // shallow copy
+        },
+        NeoInstance(obj, ignoreNeoInstances) {
+            return ignoreNeoInstances ? obj : Neo.cloneNeoInstance(obj)
+        },
+        Set(obj) {
+            return new Set(obj)
+        },
+        Object(obj, deep, ignoreNeoInstances) {
+            const out = {};
+
+            // Use Reflect.ownKeys() to include symbol properties (e.g., for config descriptors)
+            Reflect.ownKeys(obj).forEach(key => {
+                const value = obj[key];
+                out[key] = !deep ? value : Neo.clone(value, deep, ignoreNeoInstances)
+            });
+
+            return out
+        }
+    },
     typeDetector = {
         function: item => {
-            if (item.prototype?.constructor.isClass) {
+            if (item.prototype?.constructor?.isClass) {
                 return 'NeoClass'
             }
         },
         object: item => {
-            if (item.constructor.isClass && item instanceof Neo.core.Base) {
+            if (item.constructor?.isClass && item instanceof Neo.core.Base) {
                 return 'NeoInstance'
             }
         }
@@ -22,7 +51,6 @@ const
  * @module Neo
  * @singleton
  * @borrows Neo.core.Util.bindMethods       as bindMethods
- * @borrows Neo.core.Util.capitalize        as capitalize
  * @borrows Neo.core.Util.createStyleObject as createStyleObject
  * @borrows Neo.core.Util.createStyles      as createStyles
  * @borrows Neo.core.Util.decamel           as decamel
@@ -177,25 +205,7 @@ Neo = globalThis.Neo = Object.assign({
      * @returns {Object|Array|*} the cloned input
      */
     clone(obj, deep=false, ignoreNeoInstances=false) {
-        let out;
-
-        return {
-            Array      : () => !deep ? [...obj] : [...obj.map(val => Neo.clone(val, deep, ignoreNeoInstances))],
-            Date       : () => new Date(obj.valueOf()),
-            Map        : () => new Map(obj), // shallow copy
-            NeoInstance: () => ignoreNeoInstances ? obj : this.cloneNeoInstance(obj),
-            Set        : () => new Set(obj),
-
-            Object: () => {
-                out = {};
-
-                Object.entries(obj).forEach(([key, value]) => {
-                    out[key] = !deep ? value : Neo.clone(value, deep, ignoreNeoInstances)
-                });
-
-                return out
-            }
-        }[Neo.typeOf(obj)]?.() || obj
+        return cloneMap[Neo.typeOf(obj)]?.(obj, deep, ignoreNeoInstances) || obj
     },
 
     /**
@@ -263,7 +273,7 @@ Neo = globalThis.Neo = Object.assign({
                     return null
                 }
 
-                className = config.className || config.module.prototype.className;
+                className = config.className || config.module.prototype.className
             }
 
             if (!exists(className)) {
@@ -324,6 +334,10 @@ Neo = globalThis.Neo = Object.assign({
             return Neo.merge(Neo.merge(target, defaults), source)
         }
 
+        if (!target) {
+            return source
+        }
+
         for (const key in source) {
             const value = source[key];
 
@@ -337,6 +351,35 @@ Neo = globalThis.Neo = Object.assign({
         return target
     },
 
+    /**
+     * Merges a new value into an existing config value based on a specified strategy.
+     * This method is used during instance creation to apply merge strategies defined in config descriptors.
+     * @param {any} defaultValue - The default value of the config (from static config).
+     * @param {any} instanceValue - The value provided during instance creation.
+     * @param {string|Function} strategy - The merge strategy: 'shallow', 'deep', 'replace', or a custom function.
+     * @returns {any} The merged value.
+     */
+    mergeConfig(defaultValue, instanceValue, strategy) {
+        const
+            defaultValueType  = Neo.typeOf(defaultValue),
+            instanceValueType = Neo.typeOf(instanceValue);
+
+        if (strategy === 'shallow') {
+            if (defaultValueType === 'Object' && instanceValueType === 'Object') {
+                return {...defaultValue, ...instanceValue}
+            }
+        } else if (strategy === 'deep') {
+            if (defaultValueType === 'Object' && instanceValueType === 'Object') {
+                return Neo.merge(Neo.clone(defaultValue, true), instanceValue)
+            }
+        } else if (typeof strategy === 'function') {
+            return strategy(defaultValue, instanceValue)
+        }
+
+        // Default to 'replace' or if strategy is not recognized
+        return instanceValue
+    },
+
     /**
      * Maps a className string into a given or global namespace
      * @example
@@ -460,13 +503,14 @@ Neo = globalThis.Neo = Object.assign({
      * @returns {T}
      */
     setupClass(cls) {
-        let baseCfg    = null,
-            ntypeChain = [],
-            {ntypeMap} = Neo,
-            proto      = cls.prototype || cls,
-            ns         = Neo.ns(proto.constructor.config.className, false),
-            protos     = [],
-            cfg, config, ctor, hierarchyInfo, ntype;
+        let baseConfig            = null,
+            baseConfigDescriptors = null,
+            ntypeChain            = [],
+            {ntypeMap}            = Neo,
+            proto                 = cls.prototype || cls,
+            ns                    = Neo.ns(proto.constructor.config.className, false),
+            protos                = [],
+            cfg, config, configDescriptors, ctor, hierarchyInfo, ntype;
 
         /*
          * If the namespace already exists, directly return it.
@@ -480,12 +524,16 @@ Neo = globalThis.Neo = Object.assign({
             return ns
         }
 
+        // Traverse the prototype chain to collect inherited configs and descriptors
         while (proto.__proto__) {
             ctor = proto.constructor;
 
+            // If a class in the prototype chain has already had its config applied,
+            // we can use its pre-processed config and descriptors as a base.
             if (Object.hasOwn(ctor, 'classConfigApplied')) {
-                baseCfg    = Neo.clone(ctor.config, true);
-                ntypeChain = [...ctor.ntypeChain];
+                baseConfig            = Neo.clone(ctor.config, true);
+                baseConfigDescriptors = Neo.clone(ctor.configDescriptors, true);
+                ntypeChain            = [...ctor.ntypeChain];
                 break
             }
 
@@ -493,29 +541,43 @@ Neo = globalThis.Neo = Object.assign({
             proto = proto.__proto__
         }
 
-        config = baseCfg || {};
+        // Initialize accumulated config and descriptors
+        config            = baseConfig            || {};
+        configDescriptors = baseConfigDescriptors || {};
 
+        // Process each class in the prototype chain (from top to bottom)
         protos.forEach(element => {
             let mixins;
 
             ctor = element.constructor;
-
-            cfg = ctor.config || {};
+            cfg  = ctor.config || {};
 
             if (Neo.overwrites) {
                 ctor.applyOverwrites?.(cfg)
             }
 
+            // Process each config property defined in the current class's static config
             Object.entries(cfg).forEach(([key, value]) => {
-                if (key.slice(-1) === '_') {
-                    delete cfg[key];
-                    key = key.slice(0, -1);
-                    cfg[key] = value;
-                    autoGenerateGetSet(element, key)
+                const
+                    isReactive = key.slice(-1) === '_',
+                    baseKey    = isReactive ? key.slice(0, -1) : key;
+
+                // 1. Handle descriptors: If the value is a descriptor object, store it.
+                //    The 'value' property of the descriptor is then used as the actual config value.
+                if (Neo.isObject(value) && value[isDescriptor] === true) {
+                    ctor.configDescriptors ??= {};
+                    ctor.configDescriptors[baseKey] = Neo.clone(value, true); // Deep clone to prevent mutation
+                    value = value.value // Use the descriptor's value as the config value
                 }
 
-                    // only apply properties which have no setters inside the prototype chain
-                // those will get applied on create (Neo.core.Base -> initConfig)
+                // 2. Handle reactive vs. non-reactive configs: Generate getters/setters for reactive configs.
+                if (isReactive) {
+                    delete cfg[key];      // Remove original key with underscore
+                    cfg[baseKey] = value; // Use the potentially modified value
+                    autoGenerateGetSet(element, baseKey)
+                }
+                // This part handles non-reactive configs (including those that were descriptors)
+                // If no property setter exists, define it directly on the prototype.
                 else if (!Neo.hasPropertySetter(element, key)) {
                     Object.defineProperty(element, key, {
                         enumerable: true,
@@ -525,6 +587,17 @@ Neo = globalThis.Neo = Object.assign({
                 }
             });
 
+            // Merge configDescriptors: Apply "first-defined wins" strategy.
+            // If a descriptor for a key already exists (from a parent class), it is not overwritten.
+            if (ctor.configDescriptors) {
+                for (const key in ctor.configDescriptors) {
+                    if (!Object.hasOwn(configDescriptors, key)) {
+                        configDescriptors[key] = Neo.clone(ctor.configDescriptors[key], true) // Deep clone for immutability
+                    }
+                }
+            }
+
+            // Process ntype and ntypeChain
             if (Object.hasOwn(cfg, 'ntype')) {
                 ntype = cfg.ntype;
 
@@ -539,6 +612,7 @@ Neo = globalThis.Neo = Object.assign({
                 ntypeMap[ntype] = cfg.className
             }
 
+            // Process mixins
             mixins = Object.hasOwn(config, 'mixins') && config.mixins || [];
 
             if (ctor.observable) {
@@ -550,7 +624,7 @@ Neo = globalThis.Neo = Object.assign({
             }
 
             if (mixins.length > 0) {
-                applyMixins(ctor, mixins);
+                applyMixins(ctor, mixins, cfg);
 
                 if (Neo.ns('Neo.core.Observable', false, ctor.prototype.mixins)) {
                     ctor.observable = true
@@ -560,29 +634,45 @@ Neo = globalThis.Neo = Object.assign({
             delete cfg.mixins;
             delete config.mixins;
 
-            Object.assign(config, cfg);
+            // Hierarchical merging of static config values based on descriptors.
+            // This ensures that values are merged (e.g., shallow/deep) instead of simply overwritten.
+            Object.entries(cfg).forEach(([key, value]) => {
+                const descriptor = configDescriptors[key];
+
+                if (descriptor?.merge) {
+                    config[key] = Neo.mergeConfig(config[key], value, descriptor.merge)
+                } else {
+                    config[key] = value
+                }
+            });
 
+            // Assign final processed config and descriptors to the class constructor
             Object.assign(ctor, {
                 classConfigApplied: true,
-                config            : Neo.clone(config, true),
+                config            : Neo.clone(config,            true), // Deep clone final config for immutability
+                configDescriptors : Neo.clone(configDescriptors, true), // Deep clone final descriptors for immutability
                 isClass           : true,
                 ntypeChain
             });
 
+            // Apply to global namespace if not a singleton
             !config.singleton && this.applyToGlobalNs(cls)
         });
 
         proto = cls.prototype || cls;
 
+        // Add is<Ntype> flags to the prototype
         ntypeChain.forEach(ntype => {
             proto[`is${Neo.capitalize(Neo.camel(ntype))}`] = true
         });
 
+        // If it's a singleton, create and apply the instance to the global namespace
         if (proto.singleton) {
             cls = Neo.create(cls);
             Neo.applyToGlobalNs(cls)
         }
 
+        // Add class hierarchy information to the manager or a temporary map
         hierarchyInfo = {
             className      : proto.className,
             module         : cls,
@@ -609,7 +699,7 @@ Neo = globalThis.Neo = Object.assign({
             return null
         }
 
-        return typeDetector[typeof item]?.(item) || item.constructor.name
+        return typeDetector[typeof item]?.(item) || item.constructor?.name
     }
 }, Neo);
 
@@ -623,6 +713,7 @@ const ignoreMixin = [
     'classConfigApplied',
     'className',
     'constructor',
+    'id',
     'isClass',
     'mixin',
     'ntype',
@@ -635,9 +726,10 @@ const ignoreMixin = [
 /**
  * @param {Neo.core.Base} cls
  * @param {Array}         mixins
+ * @param {Object}        classConfig
  * @private
  */
-function applyMixins(cls, mixins) {
+function applyMixins(cls, mixins, classConfig) {
     if (!Array.isArray(mixins)) {
         mixins = [mixins];
     }
@@ -659,12 +751,12 @@ function applyMixins(cls, mixins) {
             }
 
             mixinCls   = Neo.ns(mixin);
-            mixinProto = mixinCls.prototype;
+            mixinProto = mixinCls.prototype
         }
 
         mixinProto.className.split('.').reduce(mixReduce(mixinCls), mixinClasses);
 
-        Object.getOwnPropertyNames(mixinProto).forEach(mixinProperty(cls.prototype, mixinProto))
+        Object.entries(Object.getOwnPropertyDescriptors(mixinProto)).forEach(mixinProperty(cls.prototype, mixinProto, classConfig))
     }
 
     cls.prototype.mixins = mixinClasses // todo: we should do a deep merge
@@ -682,30 +774,54 @@ function autoGenerateGetSet(proto, key) {
         throw('Config ' + key + '_ (' + proto.className + ') already has a set method, use beforeGet, beforeSet & afterSet instead')
     }
 
+    const
+        _key      = '_' + key,
+        uKey      = key[0].toUpperCase() + key.slice(1),
+        beforeGet = 'beforeGet' + uKey,
+        beforeSet = 'beforeSet' + uKey,
+        afterSet  = 'afterSet'  + uKey;
+
     if (!Neo[getSetCache]) {
         Neo[getSetCache] = {}
     }
 
     if (!Neo[getSetCache][key]) {
+        // Public Descriptor
         Neo[getSetCache][key] = {
             get() {
                 let me        = this,
-                    beforeGet = `beforeGet${key[0].toUpperCase() + key.slice(1)}`,
+                    config    = me.getConfig(key),
                     hasNewKey = Object.hasOwn(me[configSymbol], key),
                     newKey    = me[configSymbol][key],
-                    value     = hasNewKey ? newKey : me['_' + key];
+                    value     = hasNewKey ? newKey : me[_key];
 
-                if (Array.isArray(value)) {
-                    if (key !== 'items') {
-                        value = [...value]
+                if (value instanceof Date) {
+                    value = new Date(value.valueOf());
+                }
+                // new, explicit opt-in path
+                else if (config.cloneOnGet) {
+                    const {cloneOnGet} = config;
+
+                    if (cloneOnGet === 'deep') {
+                        value = Neo.clone(value, true, true);
+                    } else if (cloneOnGet === 'shallow') {
+                        const type = Neo.typeOf(value);
+
+                        if (type === 'Array') {
+                            value = [...value];
+                        } else if (type === 'Object') {
+                            value = {...value};
+                        }
                     }
-                } else if (value instanceof Date) {
-                    value = new Date(value.valueOf())
+                }
+                // legacy behavior
+                else if (Array.isArray(value)) {
+                    value = [...value];
                 }
 
                 if (hasNewKey) {
-                    me[key] = value; // we do want to trigger the setter => beforeSet, afterSet
-                    value = me['_' + key]; // return the value parsed by the setter
+                    me[key] = value;  // We do want to trigger the setter => beforeSet, afterSet
+                    value = me[_key]; // Return the value parsed by the setter
                     delete me[configSymbol][key]
                 }
 
@@ -715,28 +831,37 @@ function autoGenerateGetSet(proto, key) {
 
                 return value
             },
-
             set(value) {
-                if (value === undefined) {
-                    return
-                }
+                if (value === undefined) return;
 
-                let me        = this,
-                    _key      = '_' + key,
-                    uKey      = key[0].toUpperCase() + key.slice(1),
-                    beforeSet = 'beforeSet' + uKey,
-                    afterSet  = 'afterSet'  + uKey,
-                    oldValue  = me[_key];
+                const config = this.getConfig(key);
+                if (!config) return;
+
+                let me                   = this,
+                    oldValue             = config.get(), // Get the old value from the Config instance
+                    {EffectBatchManager} = Neo.core,
+                    isNewBatch           = !EffectBatchManager?.isBatchActive();
 
-                // every set call has to delete the matching symbol
+                // If a config change is not triggered via `core.Base#set()`, honor changes inside hooks.
+                isNewBatch && EffectBatchManager?.startBatch();
+
+                // 1. Prevent infinite loops:
+                // Immediately remove the pending value from the configSymbol to prevent a getter from
+                // recursively re-triggering this setter.
                 delete me[configSymbol][key];
 
-                if (key !== 'items' && key !== 'vnode') {
-                    value = Neo.clone(value, true, true)
+                switch (config.clone) {
+                    case 'deep':
+                        value = Neo.clone(value, true, true);
+                        break;
+                    case 'shallow':
+                        value = Neo.clone(value, false, true);
+                        break;
                 }
 
-                // we do want to store the value before the beforeSet modification as well,
-                // since it could get pulled by other beforeSet methods of different configs
+                // 2. Create a temporary state for beforeSet hooks:
+                // Set the new value directly on the private backing property. This allows any beforeSet
+                // hook to access the new value of this and other configs within the same `set()` call.
                 me[_key] = value;
 
                 if (typeof me[beforeSet] === 'function') {
@@ -744,25 +869,43 @@ function autoGenerateGetSet(proto, key) {
 
                     // If they don't return a value, that means no change
                     if (value === undefined) {
+                        // Restore the original value if the update is canceled.
                         me[_key] = oldValue;
+                        isNewBatch && EffectBatchManager?.endBatch();
                         return
                     }
-
-                    me[_key] = value;
                 }
 
-                if (
-                    (key === 'vnode' && value !== oldValue) || // vnode trees can be huge, avoid a deep comparison
-                    !Neo.isEqual(value, oldValue)
-                ) {
+                // 3. Restore state for change detection:
+                // Revert the private backing property to its original value. This is crucial for the
+                // `config.set()` method to correctly detect if the value has actually changed.
+                me[_key] = oldValue;
+
+                // 4. Finalize the change:
+                // The config.set() method performs the final check and, if the value changed,
+                // triggers afterSet hooks and notifies subscribers.
+                if (config.set(value)) {
                     me[afterSet]?.(value, oldValue);
                     me.afterSetConfig?.(key, value, oldValue)
                 }
+
+                isNewBatch && EffectBatchManager?.endBatch()
+            }
+        };
+
+        // Private Descriptor
+        Neo[getSetCache][_key] = {
+            get() {
+                return this.getConfig(key)?.get()
+            },
+            set(value) {
+                this.getConfig(key)?.setRaw(value)
             }
         }
     }
 
-    Object.defineProperty(proto, key, Neo[getSetCache][key])
+    Object.defineProperty(proto, key,  Neo[getSetCache][key]);
+    Object.defineProperty(proto, _key, Neo[getSetCache][_key])
 }
 
 /**
@@ -783,9 +926,7 @@ function createArrayNs(create, current, prev) {
         arrRoot = prev[arrDetails[0]]
     }
 
-    if (!arrRoot) {
-        return
-    }
+    if (!arrRoot) return;
 
     for (; i < len; i++) {
         arrItem = parseInt(arrDetails[i]);
@@ -819,12 +960,27 @@ function exists(className) {
 /**
  * @param {Neo.core.Base} proto
  * @param {Neo.core.Base} mixinProto
+ * @param {Object}        classConfig
  * @returns {Function}
  * @private
  */
-function mixinProperty(proto, mixinProto) {
-    return function(key) {
-        if (~ignoreMixin.indexOf(key)) {
+function mixinProperty(proto, mixinProto, classConfig) {
+    return function([key, descriptor]) {
+        if (ignoreMixin.includes(key)) return;
+
+        // Mixins must not override existing class properties with a setter
+        if (Neo.hasPropertySetter(proto, key)) return;
+
+        // Reactive neo configs, or public class fields defined via get() AND set()
+        if (descriptor.get && descriptor.set) {
+            autoGenerateGetSet(proto, key);
+
+            const mixinClassConfig = mixinProto.constructor.config;
+
+            if (Object.hasOwn(mixinClassConfig, key)) {
+                classConfig[key] = mixinClassConfig[key];
+            }
+
             return
         }
 
@@ -871,7 +1027,7 @@ function parseArrayFromString(str) {
     )
 }
 
-Neo.config = Neo.config || {};
+Neo.config ??= {};
 
 Neo.assignDefaults(Neo.config, DefaultConfig);