neo.mjs 10.0.0-alpha.5 → 10.0.0-beta.2

package/src/main/addon/AmCharts.mjs

@@ -37,6 +37,18 @@ class AmCharts extends Base {
          * @protected
          */
         fallbackPath: 'https://raw.githubusercontent.com/neomjs/pages/main/resources_pub/amCharts/',
+        /**
+         * List methods which must get cached until the addon reaches its `isReady` state
+         * @member {String[]} interceptRemotes
+         */
+        interceptRemotes: [
+            'callMethod',
+            'create',
+            'destroy',
+            'setProperties',
+            'setProperty',
+            'updateData'
+        ],
         /**
          * Remote method access for other workers
          * @member {Object} remote
@@ -91,19 +103,15 @@ class AmCharts extends Base {
     callMethod(data) {
         let me = this;
 
-        if (!me.isReady) {
-            return me.cacheMethodCall({fn: 'callMethod', data})
-        } else {
-            if (me.hasChart(data.id)) {
-                let chart      = me.charts[data.id],
-                    pathArray  = data.path.split('.'),
-                    methodName = pathArray.pop(),
-                    scope      = pathArray.length < 1 ? chart:  Neo.ns(pathArray.join('.'), false, chart);
+        if (me.hasChart(data.id)) {
+            let chart      = me.charts[data.id],
+                pathArray  = data.path.split('.'),
+                methodName = pathArray.pop(),
+                scope      = pathArray.length < 1 ? chart:  Neo.ns(pathArray.join('.'), false, chart);
 
-                scope[methodName].call(scope, ...data.params || [])
-            } else {
-                // todo
-            }
+            scope[methodName].call(scope, ...data.params || [])
+        } else {
+            // todo
         }
     }
 
@@ -137,29 +145,25 @@ class AmCharts extends Base {
     create(data) {
         let me = this;
 
-        if (!me.isReady) {
-            return me.cacheMethodCall({fn: 'create', data})
-        } else {
-            // todo: check if globalThis[data.package] exists, if not load it and call create afterwards
-            am4core.useTheme(am4themes_dark);
+        // todo: check if globalThis[data.package] exists, if not load it and call create afterwards
+        am4core.useTheme(am4themes_dark);
 
-            me.charts[data.id] = am4core.createFromConfig(data.config, data.id, globalThis[data.package][data.type || 'XYChart']);
+        me.charts[data.id] = am4core.createFromConfig(data.config, data.id, globalThis[data.package][data.type || 'XYChart']);
 
-            if (data.combineSeriesTooltip) {
-                me.combineSeriesTooltip(me.charts[data.id])
-            }
+        if (data.combineSeriesTooltip) {
+            me.combineSeriesTooltip(me.charts[data.id])
+        }
 
-            // in case data has arrived before the chart got created, apply it now
-            if (data.data) {
-                me.updateData({
-                    data    : data.data,
-                    dataPath: data.dataPath,
-                    id      : data.id
-                })
-            } else if (me.dataMap[data.id]) {
-                me.updateData(me.dataMap[data.id]);
-                delete me.dataMap[data.id]
-            }
+        // in case data has arrived before the chart got created, apply it now
+        if (data.data) {
+            me.updateData({
+                data    : data.data,
+                dataPath: data.dataPath,
+                id      : data.id
+            })
+        } else if (me.dataMap[data.id]) {
+            me.updateData(me.dataMap[data.id]);
+            delete me.dataMap[data.id]
         }
     }
 
@@ -167,15 +171,9 @@ class AmCharts extends Base {
      * @param {Object} data
      * @param {String} data.id
      */
-    destroy(data) {
-        let me = this;
-
-        if (!me.isReady) {
-            return me.cacheMethodCall({fn: 'destroy', data})
-        } else {
-            me.charts[data.id]?.dispose?.();
-            delete me.charts[data.id]
-        }
+    destroy({id}) {
+        this.charts[id]?.dispose?.();
+        delete this.charts[id]
     }
 
     /**
@@ -192,7 +190,7 @@ class AmCharts extends Base {
      * => fetching the other files after core.js is loaded
      * @param {Boolean} useFallback=false
      */
-    loadFiles(useFallback=false) {
+    async loadFiles(useFallback=false) {
         let me              = this,
             useFallbackPath = me.useFallbackPath || useFallback,
             basePath;
@@ -207,24 +205,21 @@ class AmCharts extends Base {
             basePath = useFallbackPath ? me.fallbackPath : me.downloadPath
         }
 
-        me.isLoading = true;
+        try {
+            await DomAccess.loadScript(basePath + 'core.js');
 
-        DomAccess.loadScript(basePath + 'core.js').then(() => {
-            Promise.all([
+            await Promise.all([
                 DomAccess.loadScript(basePath + 'charts.js'),
                 DomAccess.loadScript(basePath + 'maps.js'),
                 DomAccess.loadScript(basePath + 'themes/dark.js'),
                 DomAccess.loadScript(basePath + 'geodata/worldLow.js')
-            ]).then(() => {
-                me.isLoading = false;
-                me.isReady   = true
-            })
-        }).catch(e => {
+            ])
+        } catch(e) {
             if (!useFallback && !me.useFallbackPath) {
                 console.log('Download from amcharts.com failed, switching to fallback', e);
-                me.loadFiles(true)
+                await me.loadFiles(true)
             }
-        })
+        }
     }
 
     /**
@@ -232,20 +227,10 @@ class AmCharts extends Base {
      * @param {String} data.id
      * @param {Object} data.properties
      */
-    setProperties(data) {
-        let me = this;
-
-        if (!me.isReady) {
-            return me.cacheMethodCall({fn: 'setProperties', data})
-        } else {
-            Object.entries(data.properties).forEach(([key, value]) => {
-                me.setProperty({
-                    id   : data.id,
-                    path : key,
-                    value
-                })
-            })
-        }
+    setProperties({id, properties}) {
+        Object.entries(properties).forEach(([key, value]) => {
+            this.setProperty({id, path: key, value})
+        })
     }
 
     /**
@@ -255,22 +240,16 @@ class AmCharts extends Base {
      * @param {String} data.path
      * @param {*} data.value
      */
-    setProperty(data) {
-        let me = this;
-
-        if (!me.isReady) {
-            return me.cacheMethodCall({fn: 'setProperty', data})
+    setProperty({id, isColor=false, path, value}) {
+        if (this.hasChart(id)) {
+            let chart        = this.charts[id],
+                pathArray    = path.split('.'),
+                propertyName = pathArray.pop(),
+                scope        = Neo.ns(pathArray.join('.'), false, chart);
+
+            scope[propertyName] = isColor ? am4core.color(value) : value
         } else {
-            if (this.hasChart(data.id)) {
-                let chart        = this.charts[data.id],
-                    pathArray    = data.path.split('.'),
-                    propertyName = pathArray.pop(),
-                    scope        = Neo.ns(pathArray.join('.'), false, chart);
-
-                scope[propertyName] = data.isColor ? am4core.color(data.value) : data.value
-            } else {
-                // todo
-            }
+            // todo
         }
     }
 
@@ -283,9 +262,7 @@ class AmCharts extends Base {
     updateData(data) {
         let me = this;
 
-        if (!me.isReady) {
-            return me.cacheMethodCall({fn: 'updateData', data})
-        } else if (!me.hasChart(data.id)) {
+        if (!me.hasChart(data.id)) {
             me.dataMap[data.id] = data
         } else {
             let chart = me.charts[data.id];

package/src/main/addon/Base.mjs

@@ -4,6 +4,11 @@ import CoreBase from '../../core/Base.mjs';
  * Base class for main thread addons
  * @class Neo.main.addon.Base
  * @extends Neo.core.Base
+ *
+ * This version aligns the file loading and readiness state according to the rule:
+ * `initAsync()` MUST await for `loadFiles()` to be completed before the addon is considered `isReady`.
+ * `preloadFilesDelay` controls when `loadFiles()` is initiated in the background, but can be
+ * overridden by `cacheMethodCall()`.
  */
 class Base extends CoreBase {
     static config = {
@@ -19,34 +24,39 @@ class Base extends CoreBase {
          */
         isMainThreadAddon: true,
         /**
-         * Will get set to true once all addon related files got loaded (if there is a need to load)
-         * @member {Boolean} isReady_=false
-         * @protected
-         */
-        isReady_: false,
-        /**
-         * Amount in ms to delay the loading of library files, unless remote method access happens
-         * Change the value to false in case you don't want an automated preloading
+         * Amount in ms to delay the background loading of library files.
+         * Set to `false` to disable automated preloading and rely solely on lazy loading
+         * via `cacheMethodCall()`. Set to `0` for immediate background preload.
          * @member {Boolean|Number} preloadFilesDelay=5000
          * @protected
          */
-        preloadFilesDelay: 5000,
+        preloadFilesDelay: 5000
     }
 
     /**
+     * Internal cache for remote method calls received when `isReady` is false.
      * @member {Object[]} cache=[]
      */
     cache = []
     /**
-     * Will get set to true once we start loading Monaco related files
-     * @member {Boolean} isLoading=false
+     * Returns true if `loadFiles()` has been initiated and is currently in progress.
+     * @member {Boolean} isLoading
      */
-    isLoading = false
+    get isLoading() {
+        // isLoading is true if the promise exists and its resolver is still available (meaning it's pending).
+        return !!this.#loadFilesPromise && !!this.#loadFilesPromiseResolver
+    }
     /**
-     * Internal flag to store the setTimeout() id for loading external files
-     * @member {Number|null} loadingTimeoutId=null
+     * A private promise that tracks the completion of `loadFiles()`.
+     * This ensures `loadFiles()` is called only once and can be awaited by multiple consumers.
+     * @member {Promise<void>|null} #loadFilesPromise=null
      */
-    loadingTimeoutId = null
+    #loadFilesPromise = null
+    /**
+     * The `resolve` function for `#loadFilesPromise`, allowing external control over its resolution.
+     * @member {Function|null} #loadFilesPromiseResolver=null
+     */
+    #loadFilesPromiseResolver = null
 
     /**
      * @param {Object} config
@@ -56,56 +66,165 @@ class Base extends CoreBase {
 
         let me = this;
 
-        if (me.loadFiles) {
-            if (me.preloadFilesDelay === 0) {
-                me.loadFiles()
-            } else if (Neo.isNumber(me.preloadFilesDelay)) {
-                me.loadingTimeoutId = setTimeout(() => {
-                    me.loadFiles()
-                }, me.preloadFilesDelay)
+        // Initialize #loadFilesPromise as a controllable promise.
+        // This promise will be awaited by initAsync and resolved by executeLoadFiles.
+        me.#loadFilesPromise = new Promise(resolve => {
+            me.#loadFilesPromiseResolver = resolve
+        });
+
+        if (me.preloadFilesDelay === false) {
+            // No automated preload: resolve #loadFilesPromise immediately as it won't be triggered by delay.
+            // It will only be triggered by cacheMethodCall or initAsync if needed.
+            me.#loadFilesPromiseResolver();
+            me.#loadFilesPromiseResolver = null // Mark as resolved/no longer pending
+        } else {
+            const delay = Neo.isNumber(me.preloadFilesDelay) ? me.preloadFilesDelay : 0;
+
+            if (delay === 0) {
+                // Immediate preload: Directly execute loadFiles and resolve the promise.
+                me.#executeLoadFiles()
+            } else {
+                // Delayed preload: Set up a timer to execute loadFiles later.
+                me.timeout(delay).then(() => {
+                    // This callback checks if #loadFilesPromise is still pending (resolver is available).
+                    if (me.#loadFilesPromiseResolver) {
+                        me.#executeLoadFiles()
+                    }
+                })
             }
         }
     }
 
     /**
-     * Triggered after the isReady config got changed
+     * Executes the actual `loadFiles()` method and resolves `#loadFilesPromise`.
+     * This method is called internally to manage the single execution of `loadFiles()`.
+     * It ensures `loadFiles()` is only truly called once.
+     * @private
+     */
+    async #executeLoadFiles() {
+        let me = this;
+
+        // Only execute if the promise is still pending (resolver is available).
+        if (me.#loadFilesPromiseResolver) {
+            const resolver = me.#loadFilesPromiseResolver;
+            me.#loadFilesPromiseResolver = null; // Mark as no longer pending/resolved
+
+            await me.loadFiles();
+            resolver() // Resolve the main #loadFilesPromise
+        }
+    }
+
+    /**
+     * Async initialization hook for instances.
+     * `initAsync` MUST await for `loadFiles()` to be completed. Only then the addon is ready.
+     * @returns {Promise<void>}
+     */
+    async initAsync() {
+        await super.initAsync();
+
+        let me = this;
+
+        // `initAsync` must always wait for `me.#loadFilesPromise` to complete its resolution,
+        // regardless of how it was triggered (immediate, delayed, or by cacheMethodCall).
+        // `me.#loadFilesPromise` is always initialized in `construct()`.
+        await me.#loadFilesPromise
+    }
+
+    /**
+     * Triggered after the `isReady` config got changed.
+     * When `isReady` becomes true, any cached remote method calls are executed.
+     * At this point, `initAsync` has already ensured that `me.#loadFilesPromise` is resolved.
+     *
+     * This method is kept synchronous, delegating the async cache processing to a private method.
+     *
      * @param {Boolean} value
      * @param {Boolean} oldValue
      * @protected
      */
-    afterSetIsReady(value, oldValue) {
+    afterSetIsReady(value, oldValue) { // Keep this synchronous
         if (value) {
-            let me = this,
-                returnValue;
-
-            me.cache.forEach(item => {
-                returnValue = me[item.fn](item.data);
-                item.resolve(returnValue)
-            });
-
-            me.cache = []
+            // Initiate the asynchronous processing of cached method calls.
+            // This method itself does not need to be awaited here.
+            this.#processCachedMethodCalls();
         }
     }
 
     /**
-     * Internally caches call when isReady===false
-     * Loads the library files in case this is not already happening
-     * @param item
-     * @returns {Promise<unknown>}
+     * Internally caches remote method calls if `isReady` is false.
+     * It also ensures that `loadFiles()` is initiated immediately, bypassing `preloadFilesDelay`.
+     * @param {Object} item - Contains method name (`fn`) and data (`data`).
+     * @returns {Promise<unknown>} A promise that resolves with the method's return value.
      */
     cacheMethodCall(item) {
         let me = this;
 
-        if (!me.isLoading) {
-            me.loadingTimeoutId && clearTimeout(me.loadingTimeoutId);
-            me.loadingTimeoutId = null;
-            me.loadFiles()
+        // If loadFiles is defined, and it hasn't started yet (i.e., #loadFilesPromiseResolver is still available),
+        // execute it now, bypassing any pending preloadFilesDelay timer.
+        if (me.#loadFilesPromiseResolver) {
+            me.#executeLoadFiles() // This will resolve #loadFilesPromise immediately
         }
 
         return new Promise((resolve, reject) => {
-            me.cache.push({...item, resolve})
+            me.cache.push({...item, reject, resolve})
         })
     }
+
+    /**
+     * Placeholder method for loading external files.
+     * Subclasses (e.g., `Neo.main.addon.AmCharts`) must implement this.
+     * It **must** return a Promise that resolves when all necessary files are loaded.
+     * If `loadFiles()` is called multiple times, it should return the same pending promise
+     * or a resolved promise if files are already loaded.
+     * @returns {Promise<void>}
+     */
+    async loadFiles() {}
+
+    /**
+     * Handles intercepted remote method calls.
+     * If the addon is not ready, the call is cached using `cacheMethodCall()`.
+     * Otherwise, the original method is executed.
+     * @param {Object} msg The remote message object.
+     * @returns {Promise<any>} A promise that resolves with the method's return value.
+     */
+    onInterceptRemotes(msg) {
+        return this.cacheMethodCall({fn: msg.remoteMethod, data: msg.data})
+    }
+
+    /**
+     * Sequentially processes any method calls that were cached while the addon was not ready.
+     * This method is asynchronous to allow awaiting the execution of individual cached methods.
+     * @returns {Promise<void>} A promise that resolves when all cached methods have been processed.
+     * @private
+     */
+    async #processCachedMethodCalls() {
+        let me = this;
+
+        // Iterate over the cache items and await each one in sequence
+        for (const item of me.cache) {
+            let returnValue;
+
+            try {
+                returnValue = me[item.fn](item.data);
+
+                if (Neo.isPromise(returnValue)) {
+                    returnValue = await returnValue;
+                }
+
+                item.resolve(returnValue)
+            } catch (e) {
+                // If an error occurs (either synchronous or a promise rejection),
+                // reject the promise associated with the current cached item.
+                item.reject(e)
+
+                // *** FAIL-FAST STRATEGY ***
+                // If any cached method call fails, we assume subsequent cached calls
+                // (especially for the same addon instance) are likely to also fail.
+                break
+            }
+        }
+
+        me.cache = []
+    }
 }
 
 export default Neo.setupClass(Base);

package/src/main/addon/GoogleMaps.mjs

@@ -8,16 +8,19 @@ import Observable from '../../core/Observable.mjs';
  * @extends Neo.main.addon.Base
  */
 class GoogleMaps extends Base {
+    /**
+     * True automatically applies the core.Observable mixin
+     * @member {Boolean} observable=true
+     * @static
+     */
+    static observable = true
+
     static config = {
         /**
          * @member {String} className='Neo.main.addon.GoogleMaps'
          * @protected
          */
         className: 'Neo.main.addon.GoogleMaps',
-        /**
-         * @member {Neo.core.Base[]} mixins=[Observable]
-         */
-        mixins: [Observable],
         /**
          * @member {Object} remote
          * @protected
@@ -52,14 +55,6 @@ class GoogleMaps extends Base {
      */
     markers = {}
 
-    /**
-     * @param {Object} config
-     */
-    construct(config) {
-        super.construct(config);
-        this.loadApi()
-    }
-
     /**
      * @param {Object} data
      * @param {Object} [data.anchorPoint] x & y
@@ -176,13 +171,11 @@ class GoogleMaps extends Base {
     /**
      * @protected
      */
-    loadApi() {
+    async loadFiles() {
         let key = Neo.config.googleMapsApiKey,
             url = ' https://maps.googleapis.com/maps/api/js';
 
-        DomAccess.loadScript(`${url}?key=${key}&v=weekly&callback=Neo.emptyFn`).then(() => {
-            console.log('GoogleMaps API loaded')
-        })
+        await DomAccess.loadScript(`${url}?key=${key}&v=weekly&callback=Neo.emptyFn`)
     }
 
     /**

package/src/main/addon/HighlightJS.mjs

@@ -68,17 +68,11 @@ class HighlightJS extends Base {
 
     /**
      * @param {Object} data
-     * @returns {Boolean}
+     * @returns {Promise<void>}
      */
     async loadFiles(data) {
         let me = this;
 
-        if (me.isLoading || me.isReady) {
-            return true
-        }
-
-        me.isLoading = true;
-
         if (data) {
             delete data.appName;
             delete data.windowId;
@@ -91,12 +85,7 @@ class HighlightJS extends Base {
         await Promise.all([
             DomAccess.loadScript(me.highlightJsLineNumbersPath),
             Neo.main.addon.Stylesheet.createStyleSheet(null, 'hljs-theme', me.themePath)
-        ]);
-
-        me.isLoading = false;
-        me.isReady   = true;
-
-        return true
+        ])
     }
 
     /**

package/src/main/addon/IntersectionObserver.mjs

@@ -29,17 +29,17 @@ class NeoIntersectionObserver extends Base {
     }
 
     /**
-     * Storing data from observe() calls which arrived prior to register()
+     * Storing component ids and their IntersectionObservers
      * @member {Object} map={}
      * @protected
      */
-    cache = {}
+    map = {}
     /**
-     * Storing component ids and their IntersectionObservers
-     * @member {Object} map={}
+     * Storing data from observe() calls which arrived prior to register()
+     * @member {Object} observeCache={}
      * @protected
      */
-    map = {}
+    observeCache = {}
 
     /**
      * @param {Object} data
@@ -107,12 +107,12 @@ class NeoIntersectionObserver extends Base {
      *     {Number}  opts.countTargets: amount of found target nodes inside the DOM
      */
     observe(data) {
-        let me            = this,
-            cache         = me.cache,
-            cached        = false,
-            {id, observe} = data,
-            observer      = me.map[data.id],
-            targets       = [];
+        let me             = this,
+            cached         = false,
+            {id, observe}  = data,
+            {observeCache} = me,
+            observer       = me.map[data.id],
+            targets        = [];
 
         if (!Neo.isArray(observe)) {
             observe = [observe]
@@ -131,11 +131,11 @@ class NeoIntersectionObserver extends Base {
         } else {
             cached = true;
 
-            if (!cache[id]) {
-                cache[id] = []
+            if (!observeCache[id]) {
+                observeCache[id] = []
             }
 
-            cache[id].push(data);
+            observeCache[id].push(data);
         }
 
         return {
@@ -157,10 +157,10 @@ class NeoIntersectionObserver extends Base {
      *     if data.observe is not passed: true
      */
     register(data) {
-        let me            = this,
-            {cache}       = me,
-            {id, observe} = data,
-            returnValue   = true,
+        let me             = this,
+            {observeCache} = me,
+            {id, observe}  = data,
+            returnValue    = true,
             observer;
 
         me.map[id] = observer = new IntersectionObserver(me[data.callback].bind(me), {
@@ -175,9 +175,9 @@ class NeoIntersectionObserver extends Base {
             returnValue = me.observe({id, observe})
         }
 
-        if (cache[id]) {
-            cache[id].forEach(item => me.observe(item));
-            delete cache[id]
+        if (observeCache[id]) {
+            observeCache[id].forEach(item => me.observe(item));
+            delete observeCache[id]
         }
 
         return returnValue