rotor-framework 0.3.2

package/src/source/RotorFrameworkTask.bs

@@ -0,0 +1,278 @@
+'''''''''
+' ▗▄▄▖  ▗▄▖▗▄▄▄▖▗▄▖ ▗▄▄▖     ▗▄▄▄▖▗▄▄▖  ▗▄▖ ▗▖  ▗▖▗▄▄▄▖▗▖ ▗▖ ▗▄▖ ▗▄▄▖ ▗▖ ▗▖
+' ▐▌ ▐▌▐▌ ▐▌ █ ▐▌ ▐▌▐▌ ▐▌    ▐▌   ▐▌ ▐▌▐▌ ▐▌▐▛▚▞▜▌▐▌   ▐▌ ▐▌▐▌ ▐▌▐▌ ▐▌▐▌▗▞▘
+' ▐▛▀▚▖▐▌ ▐▌ █ ▐▌ ▐▌▐▛▀▚▖    ▐▛▀▀▘▐▛▀▚▖▐▛▀▜▌▐▌  ▐▌▐▛▀▀▘▐▌ ▐▌▐▌ ▐▌▐▛▀▚▖▐▛▚▖
+' ▐▌ ▐▌▝▚▄▞▘ █ ▝▚▄▞▘▐▌ ▐▌    ▐▌   ▐▌ ▐▌▐▌ ▐▌▐▌  ▐▌▐▙▄▄▖▐▙█▟▌▝▚▄▞▘▐▌ ▐▌▐▌ ▐▌
+' Rotor Framework™               © 2025 Balázs Molnár. All rights reserved.
+' Version 0.3.2
+'''''''''
+
+' constants
+import "engine/Constants.bs"
+
+' engine
+import "engine/providers/DispatcherProvider.bs"
+import "engine/providers/Dispatcher.bs"
+
+' base classes
+import "base/DispatcherCreator.bs"
+import "base/DispatcherExternal.bs"
+import "base/BaseReducer.bs"
+import "base/BaseModel.bs"
+import "base/BaseStack.bs"
+
+' utils
+import "utils/GeneralUtils.bs"
+import "utils/NodeUtils.bs"
+import "utils/ArrayUtils.bs"
+
+namespace Rotor
+    ' =====================================================================
+    ' FrameworkTask - Task thread version of Rotor Framework for MVI
+    '
+    ' Task thread version of the Rotor Framework that enables cross-thread MVI
+    ' (Model-View-Intent) architecture. This class manages state and dispatchers
+    ' on a separate task thread, allowing heavy computations and state management
+    ' to run off the render thread for better performance.
+    '
+    ' Configuration:
+    '   - tasks (array, optional): List of additional task node names to synchronize with.
+    '                             Allows multiple task threads to communicate and share
+    '                             dispatchers across different threads.
+    '
+    ' USAGE NOTES:
+    ' The FrameworkTask must be instantiated in the task's init() function and the sync()
+    ' method MUST be called at the end of your task function to establish the message loop.
+    '
+    ' IMPORTANT: The sync() method creates an infinite loop that handles cross-thread
+    ' communication and dispatcher synchronization. This call should be the LAST statement
+    ' in your task function, after all dispatcher initialization.
+    '
+    ' Example:
+    '   File: MyTask.task.bs
+    '   import "pkg:/source/RotorFrameworkTask.bs"
+    '   import "pkg:/source/MyDispatcher.bs"
+    '
+    '   sub init()
+    '       m.top.functionName = "task"
+    '       m.appFw = new Rotor.FrameworkTask({
+    '           tasks: ["AnotherTask"]
+    '       })
+    '   end sub
+    '
+    '   sub task()
+    '       m.fooDispatcher = createFooDispatcher()
+    '       m.barDispatcher = createBarDispatcher()
+    '       m.appFw.sync()
+    '   end sub
+    ' =====================================================================
+    class FrameworkTask
+
+        name = "Rotor Framework"
+        version = "0.3.2"
+
+        config = {
+            tasks: invalid, ' optional
+            debug: {
+            }
+        }
+
+        threadType = Rotor.Const.ThreadType.TASK
+
+        keepAlive = true
+
+        ' helper vars
+        taskNode as object
+        dispatcherProvider as object
+        port as object
+
+        ' ---------------------------------------------------------------------
+        ' new - Initializes the FrameworkTask instance
+        '
+        ' Sets up the task thread dispatcher provider, message port, and
+        ' global framework helper for cross-thread communication.
+        '
+        ' @param {object} config - Configuration object (see class documentation)
+        '
+        sub new(config = {} as object)
+
+            Rotor.Utils.deepExtendAA(m.config, config)
+
+            globalScope = GetGlobalAA()
+            globalScope.rotor_framework_helper = { ' this give to dispatcher instance the possibility to self-register
+                threadType: m.threadType,
+                frameworkInstance: m
+            }
+            m.taskNode = globalScope.top
+
+            m.dispatcherProvider = new Rotor.DispatcherProvider(m.threadType)
+
+            m.taskNode.addField("rotorSync", "assocarray", true)
+            m.port = CreateObject("roMessagePort")
+            m.taskNode.observeFieldScoped("rotorSync", m.port)
+
+        end sub
+
+        ' =====================================================================
+        ' PUBLIC API
+        ' =====================================================================
+
+        ' ---------------------------------------------------------------------
+        ' getDispatcher - Gets dispatcher facade by ID
+        '
+        ' @param {string} dispatcherId - Dispatcher identifier
+        ' @returns {object} Dispatcher facade instance
+        '
+        public function getDispatcher(dispatcherId as string) as object
+            return m.dispatcherProvider.getFacade(dispatcherId, GetGlobalAA())
+        end function
+
+        ' ---------------------------------------------------------------------
+        ' sync - Starts the message loop for cross-thread communication
+        '
+        ' IMPORTANT: This method creates an infinite loop that handles:
+        '   - Intent dispatching from render thread
+        '   - External dispatcher registration
+        '   - State change notifications
+        '   - Async reducer callbacks
+        '
+        ' This method MUST be the last call in your task function, as it
+        ' blocks execution until the framework is destroyed.
+        '
+        sub sync()
+            m.notifySyncStatus(Rotor.Const.ThreadSyncType.TASK_SYNCING)
+
+            keepAlive = true
+
+            while true and keepAlive = true
+                msg = wait(0, m.port)
+                if msg <> invalid
+                    msgType = type(msg)
+                    if msgType = "roSGNodeEvent"
+                        fieldId = msg.getField()
+
+                        if fieldId = "rotorSync"
+
+                            sync = msg.getData() ' @type:AA
+
+                            if sync.type = Rotor.Const.ThreadSyncType.DISPATCH
+
+
+                                dispatcherId = sync.payload.dispatcherId
+                                intent = sync.payload.intent
+                                dispatcherInstance = m.dispatcherProvider.stack.LookupCI(dispatcherId)
+
+                                ' taskIntent = Rotor.Utils.deepCopy(intent)
+                                dispatcherInstance.dispatch(intent)
+
+                            else if sync.type = Rotor.Const.ThreadSyncType.REGISTER_EXTERNAL_DISPATCHER
+
+                                for each item in sync.externalDispatcherList
+                                    m.dispatcherProvider.registerExternalDispatchers(item.dispatcherId, item.externalTaskNode)
+                                end for
+
+                                m.notifySyncStatus(Rotor.Const.ThreadSyncType.TASK_SYNCED)
+
+                            else if sync.type = Rotor.Const.ThreadSyncType.DESTROY
+
+                                keepAlive = false
+
+                            end if
+                        else
+
+                            data = msg.getData()
+                            extraInfo = msg.GetInfo() ' Info AA passed during observeFieldScoped
+
+                            if extraInfo?.asyncReducerCallbackId <> invalid and m.dispatcherProvider.get(extraInfo?.asyncReducerCallbackId) <> invalid
+                                ' Catch by dispatcherId
+                                m.dispatcherProvider.get(extraInfo?.asyncReducerCallbackId).asyncReducerCallback(msg)
+                            else
+                                dispatcherId = fieldId
+                                dispatcherInstance = m.dispatcherProvider.get(dispatcherId)
+                                dispatcherInstance.notifyListeners(data)
+                            end if
+
+                        end if
+                    end if
+                end if
+            end while
+            m.destroy()
+        end sub
+
+        ' =====================================================================
+        ' INTERNAL METHODS
+        ' =====================================================================
+
+        ' ---------------------------------------------------------------------
+        ' notifySyncStatus - Notifies render thread of sync status
+        '
+        ' Sends sync status message to render thread via rotorSync field.
+        '
+        ' @param {string} status - Sync status type (TASK_SYNCING or TASK_SYNCED)
+        '
+        sub notifySyncStatus(status as string)
+
+            payload = {
+                type: status,
+                taskNode: m.taskNode
+            }
+
+            if status = Rotor.Const.ThreadSyncType.TASK_SYNCING
+                payload.append({
+                    dispatcherIds: m.dispatcherProvider.stack.Keys(),
+                    tasks: m.config.tasks
+                })
+            end if
+
+            m.taskNode.rootNode.setField("rotorSync", payload)
+
+        end sub
+
+        ' ---------------------------------------------------------------------
+        ' addObserver - Adds field observer to task thread message port
+        '
+        ' @param {string} fieldId - Field name to observe
+        ' @param {object} node - SceneGraph node to observe
+        '
+        sub addObserver(fieldId as string, node)
+            node.observeFieldScoped(fieldId, m.port)
+        end sub
+
+        ' ---------------------------------------------------------------------
+        ' removeObserver - Removes field observer from node
+        '
+        ' @param {string} fieldId - Field name to stop observing
+        ' @param {object} node - SceneGraph node to unobserve
+        '
+        sub removeObserver(fieldId as string, node)
+            node.unobserveFieldScoped(fieldId)
+        end sub
+
+        ' =====================================================================
+        ' CLEANUP
+        ' =====================================================================
+
+        ' ---------------------------------------------------------------------
+        ' destroy - Cleans up task thread resources
+        '
+        ' Destroys dispatcher provider and clears global framework helper.
+        '
+        public sub destroy()
+            m.dispatcherProvider.destroy()
+
+            globalScope = GetGlobalAA()
+            globalScope.rotor_framework_helper = {
+                frameworkInstance: invalid
+            }
+
+            m.taskNode.rootNode = invalid
+            m.taskNode = invalid
+        end sub
+
+    end class
+
+end namespace
+
+
+
+

package/src/source/base/BaseModel.bs

@@ -0,0 +1,52 @@
+namespace Rotor
+
+    ' =====================================================================
+    ' Model (BaseModel) - Base model class for MVI pattern state management
+    '
+    ' Responsibilities:
+    '   - Holds application state as immutable container
+    '   - Works with Dispatchers and Reducers for state changes
+    '   - Provides cleanup mechanism
+    '
+    ' Usage in MVI:
+    '   Model → Holds current state
+    '   Reducer → Creates new state based on intents
+    '   Dispatcher → Routes intents and state updates
+    ' =====================================================================
+    class Model
+
+        ' =============================================================
+        ' MEMBER VARIABLES
+        ' =============================================================
+
+        state as object                 ' Application state container
+
+        ' =============================================================
+        ' CONSTRUCTOR
+        ' =============================================================
+
+        ' ---------------------------------------------------------------------
+        ' Constructor - Initializes model with optional initial state
+        '
+        ' @param {object} state - Initial state object (optional)
+        '
+        sub new(state = invalid as object)
+            if state <> invalid
+                m.state = state
+            end if
+        end sub
+
+        ' =============================================================
+        ' CLEANUP
+        ' =============================================================
+
+        ' ---------------------------------------------------------------------
+        ' destroy - Cleans up model by invalidating state reference
+        '
+        sub destroy()
+            m.state = invalid
+        end sub
+
+    end class
+
+end namespace

package/src/source/base/BasePlugin.bs

@@ -0,0 +1,48 @@
+namespace Rotor
+
+    ' =====================================================================
+    ' BasePlugin - Base class for all Rotor Framework plugins
+    '
+    ' Provides:
+    '   - Plugin identification and lifecycle management
+    '   - Enable/disable functionality
+    '   - Parameter storage
+    '
+    ' Plugin Types:
+    '   - Lifecycle plugins: Implement hooks {} for beforeMount, beforeUpdate, etc.
+    '   - Widget method plugins: Implement widgetMethods {} to inject methods
+    ' =====================================================================
+    class BasePlugin
+
+        ' =============================================================
+        ' MEMBER VARIABLES
+        ' =============================================================
+
+        isEnabled = true                ' Plugin enabled/disabled flag
+        key as string                   ' Plugin identifier (unique key)
+        scope as object                 ' Plugin scope (m context in plugin definitions)
+        params as object                ' Plugin initialization parameters
+
+        ' Optional plugin features (implemented by subclasses):
+        ' hooks as object               ' Widget lifecycle hooks (beforeMount, beforeUpdate, etc.)
+        ' widgetMethods as object       ' Methods to inject into widgets
+
+        ' =============================================================
+        ' CONSTRUCTOR
+        ' =============================================================
+
+        ' ---------------------------------------------------------------------
+        ' Constructor - Initializes plugin with key and parameters
+        '
+        ' @param {string} key - Plugin identifier (auto-generated if empty)
+        ' @param {object} params - Plugin initialization parameters
+        '
+        sub new(key = "" as string, params = invalid as object)
+            if key = "" then key = Rotor.Utils.getUUIDHex(8)
+            m.params = params
+            m.key = key
+        end sub
+
+    end class
+
+end namespace

package/src/source/base/BaseReducer.bs

@@ -0,0 +1,184 @@
+namespace Rotor
+
+    ' =====================================================================
+    ' Reducer (BaseReducer) - Base class for state reducers in the MVI pattern
+    '
+    ' Responsibilities:
+    '   - Computes next state from current state + intent
+    '   - Applies middleware pipeline for async operations, logging, validation
+    '   - Provides pure state transformation logic
+    '   - Integrates with Dispatcher for state updates
+    '
+    ' MVI Flow:
+    '   Intent → Middleware → Reducer → New State → Model → View Update
+    '
+    ' Override Points:
+    '   - reducer(state, intent): Define state transitions
+    '   - applyMiddlewares(): Return array of middleware functions
+    '   - middlewares: Set middleware array directly
+    ' =====================================================================
+    class Reducer
+
+        ' =============================================================
+        ' MEMBER VARIABLES
+        ' =============================================================
+
+        model as object                 ' Reference to Model holding state
+        middlewares = [] as function[]  ' Middleware function array
+        port as object                  ' Framework port for async operations
+
+        ' Dispatcher integration
+        getDispatcher as function       ' Get dispatcher facade by ID
+        dispatch as function            ' Dispatch intent to owner dispatcher
+        ownerDispatcher as object       ' Owning dispatcher instance
+        ownerDispatcherId as string     ' Owning dispatcher ID
+
+        ' Internal
+        middlewareFnScoped as dynamic   ' Currently executing middleware
+
+        ' =============================================================
+        ' CONSTRUCTOR
+        ' =============================================================
+
+        ' ---------------------------------------------------------------------
+        ' Constructor - Initializes reducer with framework integration
+        '
+        sub new()
+            frameworkInstance = GetGlobalAA().rotor_framework_helper.frameworkInstance
+            m.port = frameworkInstance.port
+
+            ' Inject getDispatcher method
+            m.getDispatcher = function(dispatcherId as string) as object
+                return GetGlobalAA().rotor_framework_helper.frameworkInstance.dispatcherProvider.getFacade(dispatcherId, m)
+            end function
+
+            ' Inject dispatch method for self-dispatching
+            m.dispatch = sub(intent as object)
+                m.ownerDispatcher.dispatch(intent)
+            end sub
+        end sub
+
+        ' =============================================================
+        ' REDUCER LOGIC
+        ' =============================================================
+
+        ' ---------------------------------------------------------------------
+        ' reducer - Pure function that computes next state
+        '
+        ' Override this method to implement custom state transitions based on intent type.
+        ' Should return a new state object (immutable pattern).
+        '
+        ' @param {object} state - Current state
+        ' @param {Intent} intent - Intent object { type, payload, ... }
+        ' @return {object} New state
+        '
+        ' Example:
+        '   function reducer(state as object, intent as Intent)
+        '       if intent.type = "INCREMENT"
+        '           newState = Rotor.Utils.deepCopy(state)
+        '           newState.count = state.count + 1
+        '           return newState
+        '       end if
+        '       return state
+        '   end function
+        '
+        public function reducer(state as object, intent as Intent)
+            return state
+        end function
+
+        ' =============================================================
+        ' MIDDLEWARE
+        ' =============================================================
+
+        ' ---------------------------------------------------------------------
+        ' applyMiddlewares - Returns middleware function array
+        '
+        ' Override to implement middleware logic for:
+        '   - Async operations (API calls, timers)
+        '   - Logging and debugging
+        '   - Intent validation
+        '   - Intent transformation
+        '
+        ' @return {function[]} Array of middleware functions
+        '
+        ' Middleware signature:
+        '   function(intent as Intent, state as object) as Dynamic
+        '   - Return intent to continue pipeline
+        '   - Return modified intent to transform
+        '   - Return invalid to cancel reducer execution
+        '
+        public function applyMiddlewares() as function[]
+            return [] as function[]
+        end function
+
+        ' =============================================================
+        ' REDUCE PIPELINE
+        ' =============================================================
+
+        ' ---------------------------------------------------------------------
+        ' reduce - Executes middleware pipeline and reducer
+        '
+        ' Process flow:
+        '   1. Validate intent payload
+        '   2. Execute middleware pipeline
+        '   3. If intent survives, execute reducer
+        '   4. Return new state or invalid
+        '
+        ' @param {object} state - Current state
+        ' @param {Intent} intent - Intent to process
+        ' @return {object} New state, or invalid if cancelled
+        '
+        function reduce(state as object, intent as Intent) as object
+            if intent?.payload <> invalid and intent.payload.Count() > 1 and intent.payload = invalid
+                throw "[WARNING] Intent payload is invalid."
+            end if
+
+            ' Execute middleware pipeline
+            middlewares = m.applyMiddlewares()
+            mwIndex = 0
+            mwCount = middlewares.Count()
+            while intent <> invalid and mwIndex < mwCount
+                middlewareFnScoped = middlewares[mwIndex]
+                m.middlewareFnScoped = middlewareFnScoped
+                intent = m.middlewareFnScoped(intent, state)
+                mwIndex++
+            end while
+            m.middlewareFnScoped = invalid
+
+            ' Middleware cancelled intent
+            if intent = invalid then return invalid
+
+            ' Execute reducer
+            newState = m.reducer(state, intent)
+
+            return newState
+        end function
+
+        ' =============================================================
+        ' ASYNC CALLBACK
+        ' =============================================================
+
+        ' ---------------------------------------------------------------------
+        ' asyncReducerCallback - Callback for async middleware operations
+        '
+        ' @param {object} msg - Message from async operation
+        '
+        sub asyncReducerCallback(msg)
+            ' Override in subclass to handle async responses
+        end sub
+
+        ' =============================================================
+        ' CLEANUP
+        ' =============================================================
+
+        ' ---------------------------------------------------------------------
+        ' destroy - Cleans up reducer references
+        '
+        sub destroy()
+            m.ownerDispatcher = invalid
+            m.port = invalid
+        end sub
+
+    end class
+
+end namespace

package/src/source/base/BaseStack.bs

@@ -0,0 +1,92 @@
+namespace Rotor
+
+    ' =====================================================================
+    ' BaseStack - Generic stack/collection base class for managing keyed items
+    '
+    ' Provides:
+    '   - Add/set items by ID
+    '   - Get items by ID (case-insensitive)
+    '   - Remove items by ID
+    '   - Clear all items
+    '   - Check item existence
+    '
+    ' Used by:
+    '   - ObserverStack (observer management)
+    '   - FocusStack (focus state management)
+    '   - Other framework collection needs
+    ' =====================================================================
+    class BaseStack
+
+        ' =============================================================
+        ' MEMBER VARIABLES
+        ' =============================================================
+
+        stack = {}                      ' Internal associative array storage
+
+        ' =============================================================
+        ' STACK OPERATIONS
+        ' =============================================================
+
+        ' ---------------------------------------------------------------------
+        ' set - Adds or replaces item in stack
+        '
+        ' If item exists, removes old item first.
+        '
+        ' @param {string} id - Item identifier
+        ' @param {object} newItem - Item to store
+        '
+        sub set(id as string, newItem as object)
+            if m.has(id) = true
+                m.remove(id)
+            end if
+            m.stack[id] = newItem
+        end sub
+
+        ' ---------------------------------------------------------------------
+        ' get - Retrieves item by ID (case-insensitive)
+        '
+        ' @param {string} id - Item identifier
+        ' @returns {object} Item if found, or invalid
+        '
+        function get(id as string) as object
+            return m.stack.LookupCI(id)
+        end function
+
+        ' ---------------------------------------------------------------------
+        ' getAll - Returns all items in stack
+        '
+        ' @returns {object} Associative array of all items
+        '
+        function getAll() as object
+            return m.stack
+        end function
+
+        ' ---------------------------------------------------------------------
+        ' remove - Removes item from stack
+        '
+        ' @param {string} id - Item identifier to remove
+        '
+        sub remove(id as string)
+            m.stack.delete(id)
+        end sub
+
+        ' ---------------------------------------------------------------------
+        ' clear - Removes all items from stack
+        '
+        sub clear()
+            m.stack.Clear()
+        end sub
+
+        ' ---------------------------------------------------------------------
+        ' has - Checks if item exists in stack
+        '
+        ' @param {string} id - Item identifier to check
+        ' @returns {boolean} True if item exists
+        '
+        function has(id as string) as boolean
+            return m.stack.doesExist(id)
+        end function
+
+    end class
+
+end namespace