@peter.naydenov/morph 3.1.4 → 3.2.0

package/src/methods/_setupActions.js

@@ -1,3 +1,20 @@
+/**
+ * Parses and organizes template actions into a structured setup by processing level.
+ * 
+ * Converts action strings into structured objects with types and levels. Validates that
+ * there are enough level markers (#) for the data depth.
+ * 
+ * @param {string[]} actions - Array of action strings to process
+ * @param {number} [dataDeepLevel=10] - Maximum depth level for nested data processing
+ * 
+ * @returns {Object} Object with numeric keys containing arrays of action objects by level
+ * 
+ * @example
+ * const setup = _setupActions(['render', '#', 'save:var'], 2);
+ * // Returns: { 0: [{type: 'render', name: 'render', level: 0}], 
+ * //            1: [{type: 'save', name: 'var', level: 1}], 
+ * //            2: [] }
+ */
 function _setupActions ( actions, dataDeepLevel=10 ) {
     let 
       actSetup = {}
@@ -23,14 +40,7 @@ function _setupActions ( actions, dataDeepLevel=10 ) {
                                     if ( actLevel > dataDeepLevel )  return false
                                     return true
                             }
-                    if ( act.startsWith ( '?' ) ) {   // it's a condition render action
-                                    actSetup[actLevel].push ({
-                                                      type: 'route'
-                                                    , name: act.replace ( '?', '' )
-                                                    , level: actLevel
-                                                    })
-                                    return true
-                            }
+
                     if ( act.startsWith ('^')  && act !== '^^'  ) {
                                    actSetup[actLevel].push ({
                                                           type: 'save'

package/src/methods/build.js

@@ -34,8 +34,6 @@ import walk from '@peter.naydenov/walk'
  */
 function build  ( tpl, extra=false, buildDependencies={} ) {
         let { hasError, placeholders, chop, helpers, handshake, snippets } = _readTemplate ( tpl );
-
-        
         
         if ( hasError ) {
                         function fail () { return hasError }
@@ -44,36 +42,49 @@ function build  ( tpl, extra=false, buildDependencies={} ) {
         else {  // If NO Error:
                         const originalPlaceholders = structuredClone ( placeholders );
                         // *** Template recognition complete. Start building the rendering function -->
-                        /**
-                         * Processes template rendering commands with provided data, dependencies, and optional post-processing functions.
-                         *
-                         * @function success
-                         * @typedef { 'render' | 'debug' | 'snippets' } Command
-                         * @param {Command} [command='render'] - The command to execute. Supported commands: 'render', 'debug', 'snippets', or 'snippets:<names>'.
-                         * @param {Object|string} [d={}] - The data object to render, or a string instruction ('raw', 'demo', 'handshake', 'placeholders').
-                         * @param {Object} [dependencies={}] - Additional dependencies to be merged with internal dependencies.
-                         * @param {...any} args - Optional post-processing functions to apply to the rendered output.
-                         * @returns {string|Array[]} The rendered template, snippets, or data depending on the command and input.
-                         *
-                         * @throws {Error} If an unsupported command or instruction is provided.
-                         *
-                         * @example
-                         * // Render a template with data
-                         * success('render', { name: 'Alice' }, { helperFn });
-                         *
-                         * @example
-                         * // Get raw template
-                         * success('debug', 'raw');
-                         *
-                         * @example
-                         * // Render only specific snippets
-                         * success('snippets:header,footer', { ... });
-                         */
-                        function success ( command='render', d={}, dependencies={}, ...args ) {
-                                        const cuts = structuredClone ( chop )
-                                        let onlySnippets = false;
-                                        
-                                        if ( ![ 'render', 'debug', 'snippets'].includes ( command )  && !command.startsWith('snippets') )   return `Error: Wrong command "${command}". Available commands: render, debug, snippets.`
+                         /**
+                          * Processes template rendering commands with provided data, dependencies, and optional post-processing functions.
+                          *
+                          * @function success
+                          * @typedef { 'render' | 'debug' | 'snippets' | 'curry' | 'set' } Command
+                          * @param {Command} [command='render'] - The command to execute. Supported commands: 'render', 'debug', 'snippets', 'curry', 'set', or 'snippets:<names>'.
+                          * @param {Object|string} [d={}] - The data object to render, or a string instruction ('raw', 'demo', 'handshake', 'placeholders', 'count').
+                          * @param {Object} [dependencies={}] - Additional dependencies to be merged with internal dependencies.
+                          * @param {...any} args - Optional post-processing functions to apply to the rendered output.
+                          * @returns {string|Array[]|function} The rendered template, snippets, data, or new function depending on the command and input.
+                          *
+                          * @throws {Error} If an unsupported command or instruction is provided.
+                          *
+                          * @example
+                          * // Render a template with data
+                          * success('render', { name: 'Alice' }, { helperFn });
+                          *
+                          * @example
+                          * // Get raw template
+                          * success('debug', 'raw');
+                          *
+                          * @example
+                          * // Get count of remaining placeholders
+                          * success('debug', 'count');
+                          *
+                          * @example
+                          * // Render only specific snippets
+                          * success('snippets:header,footer', { ... });
+                          *
+                          * @example
+                          * // Curry partial data and get new render function
+                          * const curried = success('curry', { partial: 'data' });
+                          * curried('render', { more: 'data' });
+                          *
+                          * @example
+                          * // Set placeholders and get modified template
+                          * const modified = success('set', { placeholders: { key: 'value' } });
+                          */
+                         function success ( command='render', d={}, dependencies={}, ...args ) {
+                                         const cuts = structuredClone ( chop )
+                                         let onlySnippets = false;
+                                          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.`
 
                                         if ( command.startsWith ( 'snippets') && command.includes ( ':' ) ) {
                                                         onlySnippets = true
@@ -87,9 +98,49 @@ function build  ( tpl, extra=false, buildDependencies={} ) {
                                         else if ( command === 'snippets' ) {
                                                         onlySnippets = true
                                                 }
-                                        else  placeholders = structuredClone ( originalPlaceholders )   // Reset placeholders if not snippets
+                                         else if ( command === 'set' ) {
+                                                         if ( typeof d !== 'object' || !d ) return `Error: 'set' command requires an object with placeholders, helpers, handshake.`
+                                                         // Merge helpers
+                                                         const newHelpers = { ...helpers, ...(d.helpers || {}) }
+                                                         
+                                                         // Merge handshake
+                                                         const newHandshake = handshake ? { ...handshake, ...(d.handshake || {}) } : d.handshake || {}
+                                                         // Modify chop for placeholders
+                                                         const newChop = [...chop]
+                                                         if ( d.placeholders ) {
+                                                                 Object.entries ( d.placeholders ).forEach ( ([k,v]) => {
+                                                                                if ( !isNaN(k) ) { // If k is a number
+                                                                                        let index = placeholders[k].index;
+                                                                                        newChop[index] = v
+                                                                                  } // if k is a number
+                                                                                else { // If k is a string
+                                                                                        let plx = placeholders.find ( p => p.name === k )
+                                                                                        newChop[ plx.index ] = v
+                                                                                  }
+                                                                        }) // placeholders
+                                                         } // if d.placeholders
+                                                         const newTemplateStr = newChop.join ( '' );
+                                                         const newTpl = {
+                                                                        template: newTemplateStr,
+                                                                        helpers: newHelpers,
+                                                                        handshake: newHandshake
+                                                                }
+                                                          const result = build ( newTpl, false, buildDependencies )
+                                                          return typeof result === 'function' ? result : () => result
+                                                  } else if ( command === 'curry' ) {
+                                                          // Render the template with current data
+                                                          const rendered = success('render', d, dependencies, ...args)
+                                                          // Create new template with rendered as template, keep helpers and handshake
+                                                          const newTpl = {
+                                                              template: rendered,
+                                                              helpers,
+                                                              handshake
+                                                          }
+                                                          const newFn = build(newTpl, false, buildDependencies)
+                                                          return newFn
+                                                  } else  placeholders = structuredClone ( originalPlaceholders )   // Reset placeholders if not snippets
 
-                                        if ( typeof d === 'string' ) {
+                                         if ( typeof d === 'string' ) {
                                                         switch ( d ) {
                                                                 case 'raw':
                                                                         return cuts.join ( '' )   // Original template with placeholders
@@ -100,13 +151,17 @@ function build  ( tpl, extra=false, buildDependencies={} ) {
                                                                 case 'handshake':
                                                                         if ( !handshake ) return `Error: No handshake data.`
                                                                         return structuredClone (handshake)   // return a copy of handshake object
-                                                                case 'placeholders':
-                                                                        return placeholders.map ( h => cuts[h.index] ).join ( ', ')
-                                                                default:
-                                                                        return `Error: Wrong instruction "${d}". Available instructions: raw, demo, handshake, placeholders.`
+                                                                case 'helpers' : 
+                                                                        return Object.keys ( helpers ).join ( ', ' )
+                                                                 case 'placeholders':
+                                                                         return placeholders.map ( h => cuts[h.index] ).join ( ', ')
+                                                                 case 'count':
+                                                                         return placeholders.length
+                                                                 default:
+                                                                         return `Error: Wrong instruction "${d}". Available instructions: raw, demo, handshake, helpers, placeholders, count.`
                                                         }
                                                 } // if d is string
-                                        
+    
                                         const endData = [];
                                         const memory = {};
 
@@ -177,10 +232,10 @@ function build  ( tpl, extra=false, buildDependencies={} ) {
 
                                                                                         levelData.forEach ( (theData, iData ) => {
                                                                                         
-                                                                                        let dataType = _defineDataType ( theData )                                                                                        
-                                                                                        
+                                                                                        let dataType = _defineDataType ( theData )
+                                                                                                                                                                                
                                                                                         switch ( type ) {   // Action type 'route','data', 'render', or mix -> different operations
-                                                                                                case 'route':
+                                                                                                case 'route':   // DEPRICATED in version 3.2.0. This functionality can be replaced with normal render functions
                                                                                                         switch ( dataType ) {
                                                                                                                         case 'array': 
                                                                                                                                 theData.forEach ( (d,i) => {
@@ -270,7 +325,7 @@ function build  ( tpl, extra=false, buildDependencies={} ) {
                                                                                                                 }
                                                                                                         break
                                                                                                 case 'mix': 
-                                                                                                        if ( name === '' ) {   // when is anonymous mixing helper
+                                                                                                        if ( name === '' ) {   // when is anonymous mixing action
                                                                                                                 switch ( dataType ) {
                                                                                                                                 case 'object':
                                                                                                                                         let kTest = Object.keys ( theData ).find ( k => k.includes ( '/' )   );   // Check if keys are breadcrumbs

package/src/methods/render.js

@@ -3,15 +3,27 @@ import _renderHolder from "./_renderHolder.js"
 
 
 /**
+ * Executes rendering and returns the rendered result.
  * 
- *  Execute rendering and return the results
+ * Handles both function-based and template-based rendering. Normalizes data objects
+ * by converting nested objects to their 'text' properties and arrays to their first elements.
  * 
- * @param {object|string} theData - Data to be rendered. If it's a string, it's the value of 'text' property.
- * @param {string} name - Name of the render to be executed.
- * @param {object} helpers - Object with helper functions or templates.
- * @param {...any} args - Extra arguments to be passed to the render function.
+ * @param {object|string} theData - Data to be rendered. If string, becomes the 'text' property value.
+ * @param {string} name - Name of the render helper/template to execute
+ * @param {object} helpers - Object containing helper functions and templates
+ * @param {object} original - Original data context for full data access
+ * @param {object} dependencies - External dependencies available to helpers
+ * @param {...any} args - Additional arguments passed to the render function
  * 
- * @returns {string} - Rendered string.
+ * @returns {string} Rendered string result
+ * 
+ * @example
+ * // Render with function helper
+ * const result = render(data, 'myHelper', helpers, originalData, deps);
+ * 
+ * @example
+ * // Render with template
+ * const result = render(data, 'myTemplate', helpers, originalData, deps);
  */
 function render ( theData, name, helpers, original, dependencies, ...args ) {
 // *** Executes rendering and return the results
@@ -21,15 +33,24 @@ function render ( theData, name, helpers, original, dependencies, ...args ) {
                                         if ( value instanceof Array    ) theData[key] = value[0]
                                 })
                     }
+
+                /**
+                 * Normalizes render data by wrapping strings in text objects.
+                 * 
+                 * @param {any} d - Data to normalize
+                 * @returns {object} Returns { text: d } if d is string, otherwise returns d unchanged
+                 */
                 function setRenderData ( d={} ) {
                                 if ( typeof d === 'string' )  return { text: d }
                                 else return d
                         } // setRenderData func.
-                const isRenderFunction = typeof helpers[name] === 'function';   // Render could be a function or template.
-                theData = setRenderData ( theData )
-                
-                if ( isRenderFunction )  return helpers[name]( { theData, dependencies, full:original},  ...args )
-                else                     return _renderHolder ( helpers[name], theData   )
+
+                 if (!helpers[name])      return `{{ Error: Helper '${name}' is not available}}`
+                 const isRenderFunction = typeof helpers[name] === 'function';   // Render could be a function or template.
+                 theData = setRenderData ( theData )
+
+                 if ( isRenderFunction )  return helpers[name]( { theData, dependencies, full:original},  ...args )
+                 else                     return _renderHolder ( helpers[name], theData   )
         }  // render func.
 
 

package/src/methods/settings.js

@@ -1,3 +1,14 @@
+/**
+ * Template engine configuration settings.
+ * 
+ * Defines the delimiters and sizes used for template placeholder parsing.
+ * 
+ * @type {Object}
+ * @property {string} TG_PRX - Opening tag prefix for placeholders ('{{')
+ * @property {string} TG_SFX - Closing tag suffix for placeholders ('}}')
+ * @property {number} TG_SIZE_P - Length of opening tag prefix (2)
+ * @property {number} TG_SIZE_S - Length of closing tag suffix (2)
+ */
 export default {
     TG_PRX: '{{'
   , TG_SFX: '}}'

package/tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "outDir": "./dist",
+    "module": "ESNext",
+    "moduleResolution": "node",
+    "target": "ES2020",
+    "lib": ["ES2020"],
+    "strict": false,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "esModuleInterop": true,
+    "allowSyntheticDefaultImports": true,
+    "resolveJsonModule": true
+  },
+  "include": [
+    "src/**/*"
+  ],
+  "exclude": [
+    "node_modules",
+    "dist",
+    "test",
+    "types"
+  ]
+}

package/types/index.d.ts

@@ -1,60 +0,0 @@
-declare module '@peter.naydenov/morph' {
-  /**
-   * Template description object
-   */
-  interface TemplateDescription {
-    /**
-     * Template string with placeholders
-     */
-    template: string;
-    /**
-     * Optional helper functions or templates
-     */
-    helpers?: Record<string, any>;
-    /**
-     * Optional example data for rendering
-     */
-    handshake?: Record<string, any>;
-  }
-
-  /**
-   * Build a component from template description
-   */
-  function build(tpl: TemplateDescription, extra?: boolean, buildDependencies?: Record<string, any>): Function;
-
-  /**
-   * Get a component from component storage
-   */
-  function get(location: [string, string?]): Function;
-
-  /**
-   * Add a component to component storage
-   */
-  function add(location: [string, string?], tplfn: Function | TemplateDescription, ...args: any[]): void;
-
-  /**
-   * List the names of all components in the component storage
-   */
-  function list(storageNames?: string[]): string[];
-
-  /**
-   * Clear up all the components in the storage
-   */
-  function clear(): void;
-
-  /**
-   * Remove a template from component storage
-   */
-  function remove(location: [string, string?]): void | string;
-
-  const morphAPI: {
-    build: typeof build;
-    get: typeof get;
-    add: typeof add;
-    list: typeof list;
-    clear: typeof clear;
-    remove: typeof remove;
-  };
-
-  export default morphAPI;
-}