@peter.naydenov/fsm 4.0.1 → 5.0.0

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@peter.naydenov/fsm",
-  "version": "4.0.1",
+  "version": "5.0.0",
   "description": "Simple Finite State Machine",
-  "main": "src/index.js",
+  "main": "src/main.js",
   "type": "module",
   "scripts": {
     "test": "mocha test",
@@ -11,13 +11,14 @@
   "author": "Peter Naydenov",
   "license": "MIT",
   "dependencies": {
-    "@peter.naydenov/walk": "3.0.1",
-    "ask-for-promise": "1.3.1"
+    "@peter.naydenov/dt-queries": "^1.0.2",
+    "ask-for-promise": "1.3.1",
+    "dt-toolbox": "^7.1.3"
   },
   "devDependencies": {
-    "c8": "^7.12.0",
-    "chai": "4.3.7",
-    "mocha": "10.1.0"
+    "c8": "^8.0.1",
+    "chai": "4.3.8",
+    "mocha": "10.2.0"
   },
   "repository": {
     "type": "git",

package/src/main.js

@@ -0,0 +1,75 @@
+import askForPromise  from 'ask-for-promise'    // Docs: https://github.com/PeterNaydenov/ask-for-promise
+import dtbox from 'dt-toolbox'                  // Docs: https://github.com/PeterNaydenov/dt-toolbox
+import { 
+      splitSegments
+    , joinSegments
+    , updateState 
+       } from '@peter.naydenov/dt-queries'     // Docs: https://github.com/PeterNaydenov/dt-queries
+import methods from './methods/index.js'
+
+const 
+    MISSING_STATE = 'N/A'                     // State name if not defined
+  , walk = dtbox.getWalk ()                   // Docs: https://github.com/PeterNaydenov/walk
+  ;
+
+
+function Fsm ({init, behavior, stateData={}, debug, stateDataFormat={as:'std'} }, lib={} ) {
+            const 
+                  fsm = this
+                , api = {}
+                ;
+                
+            fsm.state            = init || MISSING_STATE
+            fsm.initialState     = init || MISSING_STATE
+            fsm.stateDataFormat  = stateDataFormat   // Used in 'extractList' methods (library and transitions).
+            fsm.lock             = false             // Switch 'ON' during transition in progress. Write other updates in cache.
+            fsm.cache            = []                // cached 'update' actions
+
+            fsm.dependencies = { 
+                                walk
+                              , dtbox
+                              , askForPromise
+                              , query : { splitSegments, joinSegments, updateState } 
+                            }
+
+            fsm.callback = {
+                             update     : []
+                           , transition : []
+                           , positive   : []
+                           , negative   : []
+                        }
+                        
+            for ( let k in methods ) {   // Separate public and private methods.
+                      if ( k.startsWith('_') )   fsm[k] = methods[k](fsm)  // Methods with '_' are private.
+                      else                       api[k] = methods[k](fsm)
+                }
+            fsm.api = api
+            fsm.stateData        = dtbox.init ( stateData ).query ( splitSegments )
+            fsm.initialStateData = dtbox.init ( stateData ).query ( splitSegments )
+
+            const {transitions, nextState, chainActions } = fsm._setTransitions ( behavior, lib );
+            if ( debug ) {  
+                        fsm._warn ( transitions )
+                        global.debugFSM = fsm
+                }
+
+            fsm.transitions   = transitions
+            fsm.nextState     = nextState
+            fsm.chainActions  = chainActions
+            return api
+} // Fsm func.  
+
+
+
+Fsm.dependencies = { 
+                      walk
+                    , dtbox
+                    , askForPromise
+                    , query : { splitSegments, joinSegments, updateState }
+                  }
+
+
+
+export default Fsm
+
+

package/src/methods/_getChain.js

@@ -1,5 +1,6 @@
-function _getChain () {
-return function ( chainActions, key ) {
+function _getChain ( fsm ) {
+return function _getChain ( key ) {
+    const chainActions = fsm.chainActions;
     if ( !chainActions[key] )   return false
     return chainActions [key]
 }}  // getChain func.

package/src/methods/_onUpdateTask.js

@@ -2,7 +2,7 @@ function _onUpdateTask ( fsm ) {
 return function _onUpdateTask ( data ) {
     const 
            cb = fsm.callback
-        ,  updateCallbacks = fsm.askForPromise ( cb['update'] )
+        ,  updateCallbacks = fsm.dependencies.askForPromise ( cb['update'] )
         ;
 
     cb [ 'update' ].forEach ( (fn,i) => {

package/src/methods/_setTransitions.js

@@ -1,14 +1,14 @@
 function _setTransitions () {
-return function ( table, lib ) {   // ( machineTable, transitionLib ) --> {transitions, nextState, chainActions}
+return function ( behavior, lib ) {   // ( machineTable, transitionLib ) --> {transitions, nextState, chainActions}
      // *** Converts initial FSM data to useful fsm objects.
                 let 
                        transitions = {}
                      , nextState = {}
                      , chainActions = {}
                      ;
-                table.forEach ( el => {
+                behavior.forEach ( line => {
                         const 
-                              [ from, action, next, transitionName, alt ] = el
+                              [ from, action, next, transitionName, alt ] = line
                             , transition = lib [ transitionName ]
                             , key = `${from}/${action}`
                             ;

package/src/methods/_transit.js

@@ -1,13 +1,16 @@
 function _transit (fsm ) {
-return function ( task, key, dt ) {   //   ( promiseObj, transitionKey, additionalData ) -> void
+return function () {   //  -> void
 // *** Execute transition if exists. Ignore all non-predefined cases
         const
-                  dependencies = fsm.dependencies
-                , stateData    = { ...fsm.stateData }
+                  [ task, key,...args] = arguments   // ( promiseObj, transitionKey, ...additionalData )
+                , { state, stateData, dependencies } = fsm
                 , transition   = fsm.transitions [ key ]
+                , extractList = fsm.api.extractList
+                , system = { task, state, extractList, dependencies }
                 ;
-        if ( typeof transition === 'function' )   transition ( task, dependencies, stateData, dt )
+        if ( typeof transition === 'function' )   transition ( system, ...args )
         else                                      task.done ({ success : false })   // ignore all non-predefined cases
+
 }} // _transit func.
 
 

package/src/methods/_triggerCacheUpdate.js

@@ -1,3 +1,5 @@
+'use strict'
+
 function _triggerCacheUpdate ( fsm ) {
 return function () {
         if ( fsm.cache.length !== 0 ) {

package/src/methods/_updateStateData.js

@@ -0,0 +1,43 @@
+'use strict'
+
+function _updateStateData ( fsm ) {
+/**
+ * Updates the state data.
+ * @param {object} updateObject - The update object.
+ * @returns {dt-object}         - The updated state data.
+ */
+return function _updateStateData ( updateObject ) {
+    
+        const { dtbox, query } = fsm.dependencies;
+        // Recognize the updateObject type: dt-object, dt-model or javascript object;
+        let updateType = 'javascriptObject';
+        if ( updateObject.export )   updateType = 'dt-object'
+        if ( 
+                updateObject instanceof Array &&
+                updateObject[0][0] === updateObject[0][2] &&
+                updateObject.every ( line => line.length === 4)
+            ) {
+                    updateType = 'dt-model' 
+            }
+        if ( 
+                updateType === 'javascriptObject' &&
+                updateObject instanceof Array
+            ) {  // Wrong updateObject! Should be an object, because property name of top-level is the name of the segment. 
+                console.error ( 'State update failed. Reason: Received an array. Expectation: Object where top-level property name is the name of the data segment.' )
+                return fsm.stateData
+            }
+            
+        // Setup the update segments and root object of dt-model
+        if ( ['javascriptObject'].includes(updateType)                        )   updateObject = dtbox.init ( updateObject ).export ()
+        if ( ['javascriptObject','dt-model'].includes(updateType)             )   updateObject = dtbox.load ( updateObject )
+        if ( ['javascriptObject','dt-model','dt-object'].includes(updateType) )   updateObject = updateObject.query ( query.splitSegments )
+        // Update the state data
+    
+        return fsm.stateData.query ( query.updateState, updateObject )
+}} // _updateStateData func.
+
+
+
+export default _updateStateData
+
+

package/src/methods/_updateStep.js

@@ -1,12 +1,14 @@
 function _updateStep ( fsm ) {
-return function ( updateTask, action, dt ) {
+return function ( updateTask, action, data ) {
     const 
-          task = fsm.askForPromise ()
+          { askForPromise } = fsm.dependencies
+        , task = askForPromise ()
         , key  = `${fsm.state}/${action}`
-        , cb   = fsm.callback
+        , cb   = fsm.callback   // Event-based callbacks
         ;
+
     fsm.lock = true
-    fsm._transit ( task, key, dt )
+    fsm._transit ( task, key, data )
     task.onComplete (
             result => {
                     /**
@@ -15,18 +17,17 @@ return function ( updateTask, action, dt ) {
                      *       success   - boolean. Is it transition successful.
                      *     ? stateData - object. Flat object with fsm state values.
                      *     ? response  - object. External data as response of transition if needed.
-                     *     ? command   - string. Next action if function-chaining. (depricated!) Use a chainAction inside the logic table
                      *  }
                      */
-                    
+
                     let 
-                          chainActions = fsm._getChain ( fsm.chainActions, key)
+                          chainActions = fsm._getChain ( key )
                         , data = result.response
                         ;
-                
                     if ( result.success ) {
                             fsm.state = fsm.nextState [ key ]
-                            if ( result.stateData )   fsm.stateData = result.stateData
+                            if ( result.stateData != null   )   fsm.stateData = fsm._updateStateData ( result.stateData ) 
+                        
                             cb [ 'positive'   ].forEach ( fn => fn ( fsm.state, data)   )
                             cb [ 'transition' ].forEach ( fn => fn ( fsm.state, data)   )
                             if ( chainActions && chainActions[0] ) {
@@ -42,10 +43,6 @@ return function ( updateTask, action, dt ) {
                                     return
                                }
                          }
-                    if ( result.command ) {
-                               fsm._updateStep ( updateTask, result.command, data )
-                               return
-                          }
                     updateTask.done ( data )
             }) // task onComplete
 

package/src/methods/_warn.js

@@ -1,7 +1,7 @@
 function _warn ( fsm ) {
 return function ( transitions ) {
     // *** Warn if transition function used in description table is not defined.
-    Object.entries ( transitions ).forEach ( ([v,k]) => {
+    Object.entries ( transitions ).forEach ( ([k,v]) => {
             if ( v == null )   console.log ( `Warning: Transition for ${k} is not defined` )
         })
 }} // warn func.

package/src/methods/exportState.js

@@ -1,13 +1,10 @@
-function exportState (fsm) {
-return function () {
+function exportState ( fsm ) {
+return function exportState () {
+    const { query } = fsm.dependencies;
     // *** Export internal flags and state as an object
-            const 
-                  state     = fsm.state
-                , stateData = { ...fsm.stateData }
-                ;
             return {
-                      state
-                    , stateData
+                      state: fsm.state
+                    , stateData : fsm.stateData.query ( query.joinSegments ).export ()
                  }
 }} // exportState func.
 

package/src/methods/extractList.js

@@ -0,0 +1,26 @@
+'use strict'
+
+function extractList ( fsm ) {
+/**
+ *  Returns a list of requested segments from the state data.
+ *  @param {array.<string>} requestedSegments       - The list of requested segments.
+ *  @param {string|boolean} [options=false]         - The model option for the query.
+ *  @returns {array.<[object,dt-object,string,number,null]>}  - The list of requested segments.
+ */
+return function extractList ( requestedSegments, options=false ) {
+// *** Returns a list of requested segments
+        
+
+            const query = fsm.dependencies.query;
+            // v--- It's a debug case. Return all data to see what is available.
+            if ( arguments.length == 0 )  return fsm.stateData.query ( query.joinSegments ).model (() => ({as:'std'}))
+
+            if ( !options )   return fsm.stateData.extractList ( requestedSegments, fsm.stateDataFormat )
+            else              return fsm.stateData.extractList ( requestedSegments, options )
+}} // extractList func.
+
+
+
+export default extractList
+
+

package/src/methods/getDependencies.js

@@ -0,0 +1,10 @@
+function getDependencies (fsm) {
+return function getDependencies () {
+        return fsm.dependencies
+}} // getDependencies func.
+
+
+
+export default getDependencies
+
+

package/src/methods/importState.js

@@ -1,10 +1,12 @@
 function importState (fsm) {
 return function ( {state, stateData } ) {
 // *** Import existing state to fsm
+const { dtbox, query } = fsm.dependencies;
         if ( state ) {
                     fsm.state = state
                     if ( stateData ) {
-                                fsm.stateData = { ...stateData }
+                                const update = dtbox.load ( stateData ).query ( query.splitSegments )
+                                fsm.stateData = fsm.stateData.query ( query.updateState, update )
                         }
             }
 }} // importState func.           

package/src/methods/index.js

@@ -1,25 +1,31 @@
-import _setTransitions from './_setTransitions.js'
-import _updateStep     from './_updateStep.js'         
-import _warn           from './_warn.js'               
-import _transit        from './_transit.js'            
-import _getChain       from './_getChain.js'           
+import _setTransitions  from './_setTransitions.js'
+
+import _updateStateData from './_updateStateData.js'
+import _updateStep      from './_updateStep.js'         
+import _warn            from './_warn.js'               
+import _transit         from './_transit.js'            
+import _getChain        from './_getChain.js'           
 import _triggerCacheUpdate from './_triggerCacheUpdate.js' 
-import _onUpdateTask   from './_onUpdateTask.js'       
-import setDependencies from './setDependencies.js'    
-import on              from './on.js'                 
-import off             from './off.js'                
-import importState     from './importState.js'
-import exportState     from './exportState.js'
-import update          from './update.js'     
-import reset           from './reset.js'           
+import _onUpdateTask    from './_onUpdateTask.js'
+
+import setDependencies     from './setDependencies.js'
+import getDependencies     from './getDependencies.js'    
+import on                  from './on.js'                 
+import off                 from './off.js'                
+import importState         from './importState.js'
+import exportState         from './exportState.js'
+import update              from './update.js'     
+import reset               from './reset.js'           
 import ignoreCachedUpdates from './ignoreCacheUpdates.js'
-import getState        from './getState.js'
+import getState            from './getState.js'
+import extractList        from './extractList.js'
 
 
 
 const fn = {
 // *** "Private" methods
               _setTransitions     // Convert machine configuration and transition library in a internal fsm structures
+            , _updateStateData    // Update stateData dt-object
             , _updateStep         // Process results of transitions
             , _warn               // Warn on issues if "debug:true" in machine configuration
             , _transit            // Executes a transition if it is defined
@@ -27,7 +33,8 @@ const fn = {
             , _triggerCacheUpdate // Call next transition from the cache
             , _onUpdateTask       // Executes on update success. Used in "update" and "_triggerCacheUpdate"
 // *** Public methods
-            , setDependencies          // Add objects in dependencies
+            , setDependencies          // Add objects to dependencies object
+            , getDependencies          // Returns the dependencies object
             , on                       // Register callback functions on: 'update', 'transition', 'negative', 'positive'
             , off                      // Remove callbacks
             , importState              // Get state and data from outside
@@ -36,6 +43,7 @@ const fn = {
             , reset                    // Change state and stateData to initial values
             , ignoreCachedUpdates      // Disable update records in the cache
             , getState                 // Return a state value
+            , extractList              // Return a stateData values
         }
 
 

package/src/methods/reset.js

@@ -1,8 +1,9 @@
+'use strict'
 function reset ( fsm ) {
 return function () {
+    const { dtbox } = fsm.dependencies;
     fsm.state = fsm.initialState
-    fsm.stateData = {}
-    Object.entries ( fsm.initialStateData ).forEach ( ([key,value]) => fsm.stateData[key] = value )
+    fsm.stateData = dtbox.load ( fsm.initialStateData.export() ) 
 }} // reset func.
 
 

package/src/methods/setDependencies.js

@@ -1,5 +1,5 @@
 function setDependencies ( fsm ) {
-return function ( deps ) {
+return function setDependencies ( deps ) {
     fsm.dependencies = { ...fsm.dependencies, ...deps }
 }} // setDependencies func.
 

package/src/methods/update.js

@@ -1,13 +1,23 @@
 function update ( fsm ) {
-return function ( action, dt ) {   //   () -> Promise<transitionResponse>
+/**
+ * @method update
+ * @description Executes transition-functions or sets transition steps into a cache queue
+ * @param {string} action - action name.
+ * @param {any} dt - any upcoming data.
+ * @returns {Promise} - Promise<transitionResponse>
+ */
+return function update ( action, dt ) {   //   () -> Promise<transitionResponse>
 // *** Executes transition-functions and transition-chains.
-        const updateTask = fsm.askForPromise ();
-        
+        const
+             { askForPromise } = fsm.dependencies 
+           , updateTask = askForPromise ()
+           ;
+ 
         if ( fsm.lock ) {  
                 fsm.cache.push ( { updateTask, action, dt })
                 return updateTask.promise
             }
-            
+      
         fsm._updateStep ( updateTask, action, dt )
         updateTask.onComplete ( data =>  fsm._onUpdateTask ( data )   )
         return updateTask.promise

package/src/queryStateUpdate.js

@@ -0,0 +1,38 @@
+'use strict'
+
+function queryStateUpdate ( fsm ) {
+return function queryStateUpdate ( stateData, updateObject ) {
+        const { dtbox, query } = fsm.dependencies;
+
+        // Recognize the updateObject type: dt-object, dt-model or javascript object;
+        let updateType = 'javascriptObject';
+        if ( updateObject.export )   updateType = 'dt-object'
+        if ( 
+                updateObject instanceof Array &&
+                updateObject[0] === updateObject[3] &&
+                updateObject.every ( line => line.length === 4)
+            ) {
+                    updateType = 'dt-model' 
+            }
+        if ( 
+                updateType === 'javascriptObject' &&
+                updateObject instanceof Array
+            ) {  // Wrong updateObject! Should be an object, because property name of top-level is the name of the segment. 
+                console.error ( 'State update failed. Reason: Received an array. Expectation: Object where top-level property name is the name of the data segment.' )
+                return
+            }
+            
+        // Setup the update segments and root object of dt-model
+        if ( ['javascriptObject'].includes(updateType)                          )   updateObject =  dtbox.init(updateObject).export ()
+        if ( ['javascriptObject','dt-model'].includes(updateType)               )   updateObject = dtbox.load ( updateObject )
+        if ( ['javascriptObject','dt-model', 'dt-object' ].includes(updateType) )   updateObject = updateObject.query ( query.splitSegments )
+
+        return stateData.query ( query.updateState, updateObject )
+        
+}} // queryStateUpdate func.
+
+
+
+export default queryStateUpdate
+
+