@peter.naydenov/morph 3.3.1 → 3.3.3

package/src/methods/build.js

@@ -1,9 +1,8 @@
-import _chopTemplate       from "./_chopTemplates.js"
 import _readTemplate       from "./_readTemplate.js"
 import _defineDataType     from "./_defineType.js"
 import walk                from '@peter.naydenov/walk'
 import processPlaceholders from './processPlaceholders.js'
-import {   
+import {
            handleDebug
          , handleSet
          , handleSnippets } from './processCommands.js'
@@ -30,7 +29,7 @@ import {
 /**
  * @typedef {Object} Template
  * @property {string} template - Data to be rendered;
- * @property {Object.<string, HelperFn|string>} [helpers] - Optional. Object with helper functions or simple templates for this template; 
+ * @property {Object.<string, HelperFn|string>} [helpers] - Optional. Object with helper functions or simple templates for this template;
  * @property {object} [handshake] - Optional. Example for data to be rendered with;
  */
 
@@ -42,110 +41,89 @@ import {
 
 
 
+const COMMANDS = [ 'render', 'debug', 'snippets', 'set', 'curry' ]
+
+
+
 /**
- * 
+ *
  * @param {Template} tpl - template definition;
  * @param {boolean} [extra] - Optional. How to receive the answer - false:as a string(answer) or true: as tuple[success, answer];
  * @param {object} [buildDependencies] - Optional. External dependencies injected;
  * @returns {function|tupleResult} - rendering function
  */
 function build ( tpl, extra = false, buildDependencies = {}) {
-        let { hasError, placeholders, chop, helpers, handshake, snippets } = _readTemplate(tpl);
+        const { hasError, placeholders, chop, helpers, handshake, snippets } = _readTemplate ( tpl );
 
         if ( hasError ) {
-                function fail() { return hasError }
-                return extra ? [false, fail] : fail
+                const fail = () => hasError
+                return extra ? [ false, fail ] : fail
             }
-        else {
-                const originalPlaceholders = structuredClone(placeholders);
-
-                function success ( command = 'render', d = {}, dependencies = {}, ...args ) {
-                        const cuts = structuredClone(chop)
-                        let onlySnippets = false;
-
-                        // Command Validation
-                        if (typeof command !== 'string') return `Error: Wrong command "${command}". Available commands: render, debug, snippets, set, curry.`
-                        if (!['render', 'debug', 'snippets', 'set', 'curry'].includes(command) && !command.startsWith('snippets')) return `Error: Wrong command "${command}". Available commands: render, debug, snippets, set, curry.`
-
-
-                        // Handle Commands
-                        if (command.startsWith('snippets')) {
-                                onlySnippets = true
-                                const subset = handleSnippets(command, snippets)
-                                if (subset) placeholders = subset
-                            }
-                        else if (command === 'snippets') {
-                                onlySnippets = true
-                            }
-                        else if (command === 'set') {
-                                return handleSet(d, { helpers, handshake, placeholders, chop, build, buildDependencies })
-                            }
-                        else if (command === 'curry') {
-                                // Curry logic
-                                const rendered = success ( 'render', d, dependencies, ...args );
-                                const newTpl = {
-                                        template: rendered,
-                                        helpers,
-                                        handshake
-                                        };
-                                return build ( newTpl, false, buildDependencies )
-                            }
-                        else {
-                                placeholders = structuredClone ( originalPlaceholders )
-                            }
-
-
-                        // Handle 'DEBUG' (if d is string and command render/debug?)
-                        // Original logic: if (typeof d === 'string').
-                        // Wait, success('debug', 'raw') -> command='debug', d='raw'.
-                        // success('render', 'demo') -> command='render', d='demo'.
-                        // So any string d is treated as instruction ??
-                        if (typeof d === 'string') {
-                                const res = handleDebug(d, { handshake, helpers, placeholders, cuts })
-                                // If handleDebug returns string/number/object, return it.
-                                // Unless d='demo' which returns handshake object, then we proceed to render?
-                                if (d === 'demo' && typeof res === 'object') d = res
-                                else return res
-                        }
-                        // Proceed to Rendering
-                        const memory = {};
-                        let topLevelType = _defineDataType(d);
-                        let deps = { ...buildDependencies, ...dependencies }
-
-                        d = walk({ data: d })
-                        let original = walk({ data: d })
-
-                        if (topLevelType === 'null') return cuts.join('')
-                        if (topLevelType !== 'array') d = [d]
-                        if (topLevelType === 'null') return cuts.join('') // Redundant check?
-
-
-                        const endData = processPlaceholders({
-                                                        d
-                                                        , chop
-                                                        , placeholders
-                                                        , original
-                                                        , helpers
-                                                        , dependencies: deps
-                                                        , memory
-                                                        , args
-                                                        , onlySnippets
-                                                });
-
-
-                        if ( topLevelType === 'array' )   return endData
-
-                        // Post-process
-                        if (args) {
-                                return args.reduce ( ( acc, fn ) => {
-                                                        if (typeof fn !== 'function') return acc
-                                                        return fn ( acc, deps )
-                                                }, endData.join(''))
-                        }
-                        else return endData.join ( '' )
-                } // success func.
-                return extra ? [true, success] : success
-        }
+
+        /**
+         * Rendering function. First argument selects a command,
+         * the rest of the arguments depend on the command:
+         *   - 'render'      : ( 'render', data, dependencies, ...postprocessFn ) -> string
+         *   - 'debug'       : ( 'debug', instruction ) -> template internals
+         *   - 'snippets'    : ( 'snippets[: names]', data ) -> selected placeholders joined with '<~>'
+         *   - 'set'         : ( 'set', { placeholders, helpers, handshake }) -> new rendering function
+         *   - 'curry'       : ( 'curry', partialData ) -> new rendering function
+         */
+        function success ( command = 'render', d = {}, dependencies = {}, ...args ) {
+
+                const knownCommand = ( typeof command === 'string' )  &&  ( COMMANDS.includes ( command ) || command.startsWith ( 'snippets' ))
+                if ( !knownCommand )   return `Error: Wrong command "${command}". Available commands: ${COMMANDS.join ( ', ' )}.`
+
+                // Commands 'set' and 'curry' do not render. They produce a new rendering function.
+                if ( command === 'set' )   return handleSet ( d, { helpers, handshake, placeholders, chop, build, buildDependencies })
+                if ( command === 'curry' ) {
+                        const rendered = success ( 'render', d, dependencies, ...args )
+                        return build ({ template: rendered, helpers, handshake }, false, buildDependencies )
+                    }
+
+                // Command 'snippets' renders only the selected placeholders. 'snippets: a, b' selects, plain 'snippets' takes all.
+                const
+                      onlySnippets = command.startsWith ( 'snippets' )
+                    , activePlaceholders = onlySnippets  ?  ( handleSnippets ( command, snippets ) || placeholders )  :  placeholders
+                    ;
+
+                // A string instead of data is a debug instruction. Instruction 'demo' continues by rendering the handshake data.
+                if ( typeof d === 'string' ) {
+                        const result = handleDebug ( d, { handshake, helpers, placeholders : activePlaceholders, cuts : chop })
+                        const renderTheDemo = ( d === 'demo' )  &&  ( typeof result === 'object' )
+                        if ( !renderTheDemo )   return result
+                        d = result
+                    }
+
+                // Rendering
+                const dataType = _defineDataType ( d )
+                if ( dataType === 'null' )   return chop.join ( '' )
+
+                const
+                      deps = { ...buildDependencies, ...dependencies }
+                    , data = walk ({ data: d })   // Deep copy. Rendering should never touch caller's data.
+                    , original = walk ({ data })
+                    , levelData = ( dataType === 'array' )  ?  data  :  [ data ]
+                    ;
+
+                const endData = processPlaceholders ({
+                                                  d : levelData
+                                                , chop
+                                                , placeholders : activePlaceholders
+                                                , original
+                                                , helpers
+                                                , dependencies : deps
+                                                , memory : {}
+                                                , args
+                                                , onlySnippets
+                                        });
+
+                if ( dataType === 'array' )   return endData
+                // Extra arguments are post-processing functions: ( result, dependencies ) -> result
+                return args.reduce (( acc, fn ) => ( typeof fn === 'function' )  ?  fn ( acc, deps )  :  acc, endData.join ( '' ))
+        } // success func.
+
+        return extra ? [ true, success ] : success
 } // build func.
 
 

package/src/methods/executeActions.js

@@ -2,64 +2,78 @@ import actionRender                    from './actionRender.js'
 import actionData                      from './actionData.js'
 import actionMix                       from './actionMix.js'
 import actionExtendedRender            from './actionExtendedRender.js'
-import _defineDataType                 from "./_defineType.js"
 import { actionSave, actionOverwrite } from './actionSave.js'
 
 
 
-function executeActions({ nestedData, actSetup, helpers, original, dependencies, memory, dElement, createUseHelper }) {
+/**
+ * Executes the action chain of a placeholder over the prepared nested data.
+ *
+ * Actions arrive from the action supplier level by level. Each action type has a
+ * dedicated handler that writes its result into `nestedData`. Only 'overwrite'
+ * replaces the current data element and hands it back to the caller.
+ *
+ * @param {object} params - Parameters object
+ * @param {array} params.nestedData - Data slices organized by depth level
+ * @param {Generator} params.actSetup - Action supplier (see _actionSupply.js)
+ * @param {object} params.helpers - Helper functions
+ * @param {any} params.original - Original data context
+ * @param {object} params.dependencies - Injected dependencies
+ * @param {object} params.memory - Internal memory state ('save' action writes here)
+ * @param {any} params.dElement - Current top-level data element
+ * @param {function} params.createUseHelper - Factory for useHelper functions
+ * @returns {any} The (possibly overwritten) data element
+ */
+function executeActions ({ nestedData, actSetup, helpers, original, dependencies, memory, dElement, createUseHelper }) {
     let currentDElement = dElement;
 
-    for (let step of actSetup) {
-        let
-            { type, name, level } = step
-            , levelData = nestedData[level] || []
-            ;
+    for ( const step of actSetup ) {
+            const
+                  { type, level } = step
+                , levelData = nestedData[level] || []
+                ;
 
-        // If levelData is undefined, we can't loop. But it should be [] from _defineData?
-        // nestedData[level] might be undefined?
-        // build.js said: `let levelData = nestedData[level] || []`
+            levelData.forEach ( ( theData, iData ) => {
+                        const context = {
+                                          helpers
+                                        , original
+                                        , dependencies
+                                        , memory
+                                        , useHelper : createUseHelper
+                                        , nestedData
+                                        , level
+                                        , iData
+                                        , extendArguments : { dependencies, memory }
+                                }
 
-        levelData.forEach((theData, iData) => {
-            const context = {
-                helpers
-                , original
-                , dependencies
-                , memory
-                , useHelper: createUseHelper
-                , nestedData
-                , level
-                , iData
-                , extendArguments: { dependencies, memory }
-            }
-
-            switch (type) {
-                case 'render':
-                    actionRender(step, theData, context)
-                    break
-                case 'data':
-                    actionData(step, theData, context)
-                    break
-                case 'mix':
-                    actionMix(step, theData, context)
-                    break
-                case 'save':
-                    actionSave(step, theData, context)
-                    break
-                case 'overwrite':
-                    currentDElement = actionOverwrite(step, theData)
-                    break
-                case 'route':
-                    // Deprecated, removed as per refactoring plan
-                    break
-                case 'extendedRender':
-                    actionExtendedRender(step, theData, context)
-                    break
-            }
-        })
-    }
+                        switch ( type ) {
+                                case 'render':
+                                        actionRender ( step, theData, context )
+                                        break
+                                case 'data':
+                                        actionData ( step, theData, context )
+                                        break
+                                case 'mix':
+                                        actionMix ( step, theData, context )
+                                        break
+                                case 'save':
+                                        actionSave ( step, theData, context )
+                                        break
+                                case 'overwrite':
+                                        currentDElement = actionOverwrite ( step, theData )
+                                        break
+                                case 'extendedRender':
+                                        actionExtendedRender ( step, theData, context )
+                                        break
+                            }
+                }) // forEach levelData
+        } // for actSetup
 
     return currentDElement
-}
+} // executeActions func.
+
+
 
 export default executeActions
+
+

package/src/methods/processCommands.js

@@ -52,16 +52,12 @@ function handleSet(d, { helpers, handshake, placeholders, chop, build, buildDepe
     const newChop = [...chop]
 
     if (d.placeholders) {
-        Object.entries(d.placeholders).forEach(([k, v]) => {
-            if (!isNaN(k)) {
-                let index = placeholders[k].index;
-                newChop[index] = v
-            }
-            else {
-                let plx = placeholders.find(p => p.name === k)
-                newChop[plx.index] = v
-            }
-        })
+        for (const [k, v] of Object.entries(d.placeholders)) {
+            // Placeholders are addressed by position ('0', '1', ...) or by name
+            const holder = !isNaN(k) ? placeholders[k] : placeholders.find(p => p.name === k)
+            if (!holder) return `Error: Placeholder "${k}" does not exist in the template.`
+            newChop[holder.index] = v
+        }
     }
 
     const newTemplateStr = newChop.join('');

package/src/methods/processPlaceholders.js

@@ -17,139 +17,121 @@ import render          from "./render.js"
  * @param {object} params.dependencies - Injected dependencies
  * @param {object} params.memory - Internal memory state
  * @param {array} params.args - Additional arguments
- * @param {boolean} params.onlySnippets - Whether to process only snippets
- * @returns {array} Processed template parts
+ * @param {boolean} params.onlySnippets - Whether to render only the selected placeholders
+ * @returns {array} Rendered result - one string per data element
  */
 function processPlaceholders ({ d, chop, placeholders, original, helpers, dependencies, memory, args, onlySnippets }) {
     const endData = []
-    // We need a factory for useHelper.
-    // It depends on 'currentData'. But here we are iterating 'd'.
-
-    // Helper factory to share with executeActions
-    const createUseHelperFactory = (currentData) => (targetName, targetData) => {
-        let
-            targetFn = helpers[targetName]
-            , isCompiledTemplate = targetFn && typeof targetFn === 'function' && targetFn.length >= 2
-            ;
-        if (!targetFn) return `( Error: Helper '${targetName}' is not available )`
-
-        if (isCompiledTemplate) {
-            try {
-                return targetFn('render', targetData || currentData, dependencies)
-            }
-            catch (e) {
-                return render(targetData || currentData, targetName, helpers, original, dependencies, ...args)
-            }
-        }
-        return render(targetData || currentData, targetName, helpers, original, dependencies, ...args)
-    }
-
-
-    d.forEach(dElement => {
-        let
-            cuts = structuredClone(chop)
-            , currentDElement = dElement // Can be updated by overwrite
-            ;
-
-        placeholders.forEach(holder => {
+
+    // useHelper factory, shared with executeActions. 'currentData' is the fallback
+    // when the helper calls useHelper without its own data.
+    const createUseHelperFactory = ( currentData ) => ( targetName, targetData ) => {
             const
-                { index, data, action } = holder
-                , dataOnly = !action
-                , mem = structuredClone(memory)
+                  targetFn = helpers[targetName]
+                , isCompiledTemplate = targetFn  &&  typeof targetFn === 'function'  &&  targetFn.length >= 2
                 ;
-            let info = currentDElement;
+            if ( !targetFn )   return `( Error: Helper '${targetName}' is not available )`
 
-            // Data Resolution
-            if (data && data.includes('/')) {
-                if (info.hasOwnProperty(data)) {
-                    info = info[data]
-                }
-                else {
-                    data.split('/').forEach(d => {
-                        if (info.hasOwnProperty(d)) info = info[d]
-                        else info = [] // Bug in original? info = [] then info['next'] crashes? 
-                        // Original: else info = []. 256. 
-                        // If info is [], next iteration info['key'] is undefined.
-                        // So safe.
-                    })
-                }
-            }
-            else if (data === '@all' || data === null || data === '@root') info = currentDElement
-            else if (data) info = info[data]
-
-
-            if (dataOnly) {
-                const type = _defineDataType(info);
-                switch (type) {
-                    case 'function':
-                        cuts[index] = info()
-                        break
-                    case 'primitive':
-                        cuts[index] = info
-                        break
-                    case 'array':
-                        if (_defineDataType(info[0]) === 'primitive') cuts[index] = info[0]
-                        break
-                    case 'object':
-                        if (info.text) cuts[index] = info.text
-                        break
+            if ( isCompiledTemplate ) {
+                    try   { return targetFn ( 'render', targetData || currentData, dependencies ) }
+                    catch ( e ) { return render ( targetData || currentData, targetName, helpers, original, dependencies, ...args ) }
                 }
-            }
-            else {
-                // Logic for data processing via actions
-                let
-                    { dataDeepLevel, nestedData } = _defineData(info, action)
-                    , actSetup = _actionSupply(_setupActions(action, dataDeepLevel), dataDeepLevel)
-                    ;
-
-                const createUseHelper = createUseHelperFactory(info); // use info as context? 
-                // In build.js it was `d` (the item from levelData).
-                // `executeActions` passes `theData` to `createUseHelper`.
-
-                currentDElement = executeActions({
-                    nestedData
-                    , actSetup
-                    , helpers
-                    , original
-                    , dependencies
-                    , memory
-                    , dElement: currentDElement
-                    , createUseHelper: createUseHelperFactory
-                })
-
-                // Flatten Step
-                if (nestedData instanceof Array && nestedData.length === 1 && nestedData[0] instanceof Array) nestedData = nestedData[0]
-                if (nestedData[0] == null) return
-
-                let
-                    accType = _defineDataType(nestedData[0])
-                    , fineData = nestedData[0]
-                    ;
-
-                switch (accType) {
-                    case 'primitive':
-                        if (fineData == null) return
-                        cuts[index] = fineData
-                        break
-                    case 'object':
-                        if (fineData['text'] == null) return
-                        cuts[index] = fineData['text']
-                        break
-                    case 'array':
-                        const aType = _defineDataType(fineData[0])
-                        if (aType === 'object') cuts[index] = fineData.map(x => x.text).join('')
-                        else cuts[index] = fineData.join('')
-                        break
-                }
-            }
-        }) // placeholders loop
+            return render ( targetData || currentData, targetName, helpers, original, dependencies, ...args )
+        } // createUseHelperFactory func.
+
 
-        if (onlySnippets) endData.push(placeholders.map(x => cuts[x.index]).join('<~>'))
-        else endData.push(cuts.join(''))
+    d.forEach ( dElement => {
+            let
+                  cuts = structuredClone ( chop )
+                , currentDElement = dElement   // 'overwrite' action can replace it
+                ;
 
-    }) // d.forEach
+            placeholders.forEach ( holder => {
+                    const
+                          { index, data, action } = holder
+                        , dataOnly = !action
+                        ;
+                    let info = currentDElement;
+
+                    // Data resolution. A name with '/' is a breadcrumb path into the data,
+                    // unless the data has it as a literal key. Missing or null steps resolve to [].
+                    if ( data && data.includes ( '/' )) {
+                            if ( info != null  &&  info.hasOwnProperty ( data ))   info = info[data]
+                            else {
+                                    data.split ( '/' ).forEach ( step => {
+                                            if ( info != null  &&  info.hasOwnProperty ( step ))   info = info[step]
+                                            else                                                   info = []
+                                        })
+                                }
+                        }
+                    else if ( data === '@all' || data === null || data === '@root' )   info = currentDElement
+                    else if ( data )   info = ( info != null )  ?  info[data]  :  null
+
+
+                    if ( dataOnly ) {   // No actions - place the data directly
+                            switch ( _defineDataType ( info )) {
+                                case 'function':
+                                        cuts[index] = info ()
+                                        break
+                                case 'primitive':
+                                        cuts[index] = info
+                                        break
+                                case 'array':
+                                        if ( _defineDataType ( info[0] ) === 'primitive' )   cuts[index] = info[0]
+                                        break
+                                case 'object':
+                                        if ( info.text )   cuts[index] = info.text
+                                        break
+                            }
+                        }
+                    else {   // Run the action chain over the data
+                            let { dataDeepLevel, nestedData } = _defineData ( info, action )
+                            const actSetup = _actionSupply ( _setupActions ( action, dataDeepLevel ), dataDeepLevel )
+
+                            currentDElement = executeActions ({
+                                                          nestedData
+                                                        , actSetup
+                                                        , helpers
+                                                        , original
+                                                        , dependencies
+                                                        , memory
+                                                        , dElement : currentDElement
+                                                        , createUseHelper : createUseHelperFactory
+                                                })
+
+                            // The action chain leaves the result at the root level. Unwrap it.
+                            if ( nestedData instanceof Array  &&  nestedData.length === 1  &&  nestedData[0] instanceof Array )   nestedData = nestedData[0]
+                            if ( nestedData[0] == null )   return
+
+                            const fineData = nestedData[0]
+                            switch ( _defineDataType ( fineData )) {
+                                case 'primitive':
+                                        cuts[index] = fineData
+                                        break
+                                case 'object':
+                                        if ( fineData['text'] == null )   return
+                                        cuts[index] = fineData['text']
+                                        break
+                                case 'array': {
+                                        const itemType = _defineDataType ( fineData[0] )
+                                        if ( itemType === 'object' )   cuts[index] = fineData.map ( x => x.text ).join ( '' )
+                                        else                           cuts[index] = fineData.join ( '' )
+                                        break
+                                    }
+                            }
+                        }
+                }) // forEach placeholders
+
+            if ( onlySnippets )   endData.push ( placeholders.map ( x => cuts[x.index] ).join ( '<~>' ))
+            else                  endData.push ( cuts.join ( '' ))
+
+        }) // forEach d
 
     return endData
-}
+} // processPlaceholders func.
+
+
 
 export default processPlaceholders
+
+

package/src/methods/render.js

@@ -15,19 +15,17 @@ import _renderHolder from './_renderHolder.js'
  * 
  * @returns {any} The result of the rendering process, or an error string if the helper is not available.
  */
-function render ( theData, name, helpers, original, dependencies, ...args) {
-                const useHelper = ( targetName, targetData ) => render ( targetData || theData, targetName, helpers, original, dependencies, ...args )
-                if (!helpers[name]) return `( Error: Helper '${name}' is not available )`
-
-                const isRenderFunction = typeof helpers[name] === 'function';
-
-                if ( isRenderFunction )   return helpers[name]({ data: theData, dependencies, full: original, useHelper }, ...args)
-                else {
-                        let dataForHolder = theData
-                        if ( typeof theData !== 'object' || theData === null )   dataForHolder = { text: theData }
-                        return _renderHolder ( helpers[name], dataForHolder )
-                }
-        }  // render func.
+function render ( theData, name, helpers, original, dependencies, ...args ) {
+        const useHelper = ( targetName, targetData ) => render ( targetData || theData, targetName, helpers, original, dependencies, ...args )
+        if ( !helpers[name] )   return `( Error: Helper '${name}' is not available )`
+
+        const isRenderFunction = typeof helpers[name] === 'function';
+        if ( isRenderFunction )   return helpers[name] ({ data: theData, dependencies, full: original, useHelper }, ...args )
+
+        // String helpers are mini templates. Wrap primitives, so the template can address them as {{ text }}.
+        const dataForHolder = ( typeof theData === 'object'  &&  theData !== null )  ?  theData  :  { text: theData }
+        return _renderHolder ( helpers[name], dataForHolder )
+} // render func.