@peter.naydenov/morph 3.2.0 → 3.3.1

package/Changelog.md

@@ -2,6 +2,11 @@
 
 
 
+### 3.3.0 (2025-12-13)
+- [x] Use other helper from inside of helper functionsHelper functions attribute - useHelper;
+
+
+
 ### 3.2.0 (2025-12-01)
 - [x] Conditional actions are depricated. ( starting with `?` ). Too unconsistant with other actions. It's can be solved with normal helper functions by providing a list of possible templates. It's something that is possible even now;
 - [x] Templates can have empty placeholders - just {{ }};

package/README.md

@@ -10,18 +10,6 @@
 
 
 
-## What's new in version 3.x.x
-
-In version 3 introduced `snippets`, you can choose to render only certain placeholders or groups of placeholders from the template. This lets you use templates as collections of reusable templates, so you can extract and use just the parts you need without having to render the whole template. This makes it easier to create and manage reusable template libraries for your project or rerender only the parts that need to be updated.
-
-The `render` function now takes a command as its first argument. Available commands are: `render`, `debug`, `snippets`, `curry`, and `set`. Other arguments have no changes. Just shifted right. The second argument becomes the data, the third is dependencies, and the fourth is a list of post-processing functions.
-
-In version 3.x.x, the data is always the second argument. It can be a string, as in version 2.x.x. The term "command" is no longer used for this argument; instead, it is called "instructions". Available instructions include: `raw`, `demo`, `handshake`, `placeholders`, and `count`.
-
-How to migrate to version 3.x.x, please read the [Migration guide](./Migration.guide.md). Read more about `snippets` down below.
-
-
-
 ## General Information
 
 `Morph` has a logic-less template syntax. Placeholders are places surrounded by double curly braces `{{ }}` and they represents the pleces where the data will be inserted.
@@ -259,6 +247,38 @@ Helpers are templates and functions that are used by actions to decorate the dat
 - `Extended render functions` will return a string like regular render functions, but will receive a deep branch of requested data;
 - `Conditional render functions` could return null, that means: ignore this action. The result could be also a string: the name of other helper function that will render the data.
 
+### Calling Helpers within Helpers
+
+Starting from version 3.3.0, helper functions receive a `useHelper` function in their arguments object. This allows helpers to call other helpers programmatically.
+
+```js
+const helpers = {
+    // Basic helper
+    format: ({ data }) => `[${data}]`,
+
+    // Helper using another helper
+    process: ({ data, useHelper }) => {
+        return useHelper('format') // Uses current data
+    },
+
+    // Helper overriding data
+    customProcess: ({ data, useHelper }) => {
+        return useHelper('format', 'Override') // Uses provided data
+    },
+
+    // Helper calling a template string helper
+    linkToCheck: ({ data, useHelper }) => {
+        // 'link' is a string template helper defined elsewhere
+        if (data.url) return useHelper('link', { text: data.name, href: data.url })
+        return data.name
+    }
+}
+```
+
+`useHelper` signature: `useHelper(helperName, [dataOverride])`
+- `helperName`: String name of the helper to call.
+- `dataOverride`: Optional. Data to pass to the helper. If omitted, the current data context of the caller is used.
+
 
 
 ## Commands

package/dist/methods/actionData.d.ts

@@ -0,0 +1,10 @@
+export default actionData;
+declare function actionData({ name }: {
+    name: any;
+}, levelData: any, { helpers, extendArguments, nestedData, level, useHelper }: {
+    helpers: any;
+    extendArguments: any;
+    nestedData: any;
+    level: any;
+    useHelper: any;
+}): void;

package/dist/methods/actionExtendedRender.d.ts

@@ -0,0 +1,10 @@
+export default actionExtendedRender;
+declare function actionExtendedRender({ name }: {
+    name: any;
+}, levelData: any, { helpers, extendArguments, nestedData, level, useHelper }: {
+    helpers: any;
+    extendArguments: any;
+    nestedData: any;
+    level: any;
+    useHelper: any;
+}): void;

package/dist/methods/actionMix.d.ts

@@ -0,0 +1,10 @@
+export default actionMix;
+declare function actionMix({ name }: {
+    name: any;
+}, levelData: any, { helpers, extendArguments, nestedData, level, useHelper }: {
+    helpers: any;
+    extendArguments: any;
+    nestedData: any;
+    level: any;
+    useHelper: any;
+}): void;

package/dist/methods/actionRender.d.ts

@@ -0,0 +1,13 @@
+export default actionRender;
+declare function actionRender({ name }: {
+    name: any;
+}, levelData: any, { helpers, original, dependencies, useHelper, extendArguments, nestedData, level, iData }: {
+    helpers: any;
+    original: any;
+    dependencies: any;
+    useHelper: any;
+    extendArguments: any;
+    nestedData: any;
+    level: any;
+    iData: any;
+}): void;

package/dist/methods/actionSave.d.ts

@@ -0,0 +1,8 @@
+export function actionSave({ name }: {
+    name: any;
+}, levelData: any, { memory }: {
+    memory: any;
+}): void;
+export function actionOverwrite({ name }: {
+    name: any;
+}, levelData: any): any;

package/dist/methods/build.d.ts

@@ -1,4 +1,12 @@
 export default build;
+export type UseHelperFn = (name: string, data?: any) => any;
+export type HelperFn = (args: {
+    data: any;
+    dependencies: object;
+    full?: any;
+    useHelper?: UseHelperFn;
+    memory?: object;
+}) => any;
 export type Template = {
     /**
      * - Data to be rendered;
@@ -7,17 +15,35 @@ export type Template = {
     /**
      * - Optional. Object with helper functions or simple templates for this template;
      */
-    helpers?: object;
+    helpers?: {
+        [x: string]: string | HelperFn;
+    };
     /**
      * - Optional. Example for data to be rendered with;
      */
     handshake?: object;
 };
 export type tupleResult = any[];
+/**
+ * @callback UseHelperFn
+ * @param {string} name - Name of the helper to call.
+ * @param {any} [data] - Optional data override.
+ * @returns {any} Result of the helper call.
+ */
+/**
+ * @callback HelperFn
+ * @param {object} args
+ * @param {any} args.data - The data context.
+ * @param {object} args.dependencies - Injected dependencies.
+ * @param {any} [args.full] - Full data context.
+ * @param {UseHelperFn} [args.useHelper] - Function to call other helpers.
+ * @param {object} [args.memory] - internal memory state.
+ * @returns {any} Rendered output.
+ */
 /**
  * @typedef {Object} Template
  * @property {string} template - Data to be rendered;
- * @property {object} [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;
  */
 /**

package/dist/methods/executeActions.d.ts

@@ -0,0 +1,11 @@
+export default executeActions;
+declare function executeActions({ nestedData, actSetup, helpers, original, dependencies, memory, dElement, createUseHelper }: {
+    nestedData: any;
+    actSetup: any;
+    helpers: any;
+    original: any;
+    dependencies: any;
+    memory: any;
+    dElement: any;
+    createUseHelper: any;
+}): any;

package/dist/methods/processCommands.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Handles debug commands for template inspection.
+ *
+ * @param {string} d - Debug instruction
+ * @param {object} context - Context object
+ * @param {object} context.handshake - Example data
+ * @param {object} context.helpers - Helper functions
+ * @param {array} context.placeholders - Placeholder definitions
+ * @param {array} context.cuts - Chopped template parts
+ * @returns {any} Debug result or error message
+ */
+export function handleDebug(d: string, { handshake, helpers, placeholders, cuts }: {
+    handshake: object;
+    helpers: object;
+    placeholders: any[];
+    cuts: any[];
+}): any;
+/**
+ * Handles the 'set' command to modify template properties.
+ *
+ * @param {object} d - Modification data
+ * @param {object} context - Context object
+ * @param {object} context.helpers - Current helper functions
+ * @param {object} context.handshake - Current handshake data
+ * @param {array} context.placeholders - Current placeholders
+ * @param {array} context.chop - Current chopped template
+ * @param {function} context.build - Build function
+ * @param {object} context.buildDependencies - Build dependencies
+ * @returns {function} Modified template function
+ */
+export function handleSet(d: object, { helpers, handshake, placeholders, chop, build, buildDependencies }: {
+    helpers: object;
+    handshake: object;
+    placeholders: any[];
+    chop: any[];
+    build: Function;
+    buildDependencies: object;
+}): Function;
+/**
+ * Handles snippets command to select specific placeholders.
+ *
+ * @param {string} command - Snippets command
+ * @param {object} snippets - Snippets mapping
+ * @returns {array|null} Selected placeholders or null
+ */
+export function handleSnippets(command: string, snippets: object): any[] | null;

package/dist/methods/processPlaceholders.d.ts

@@ -0,0 +1,27 @@
+export default processPlaceholders;
+/**
+ * Processes placeholders in the template with provided data and context.
+ *
+ * @param {object} params - Parameters object
+ * @param {array} params.d - Data array to process
+ * @param {array} params.chop - Chopped template parts
+ * @param {array} params.placeholders - Placeholder definitions
+ * @param {any} params.original - Original data context
+ * @param {object} params.helpers - Helper functions
+ * @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
+ */
+declare function processPlaceholders({ d, chop, placeholders, original, helpers, dependencies, memory, args, onlySnippets }: {
+    d: any[];
+    chop: any[];
+    placeholders: any[];
+    original: any;
+    helpers: object;
+    dependencies: object;
+    memory: object;
+    args: any[];
+    onlySnippets: boolean;
+}): any[];

package/dist/methods/render.d.ts

@@ -1,25 +1,14 @@
 export default render;
 /**
- * Executes rendering and returns the rendered result.
+ * Renders a helper or template with the provided data and context.
  *
- * 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 {any} theData - The data to process.
+ * @param {string} name - The name of the helper or template to render.
+ * @param {object} helpers - Dictionary of available helpers.
+ * @param {any} original - The full original data context.
+ * @param {object} dependencies - injected dependencies.
+ * @param {...any} args - Additional arguments.
  *
- * @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 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);
+ * @returns {any} The result of the rendering process, or an error string if the helper is not available.
  */
-declare function render(theData: object | string, name: string, helpers: object, original: object, dependencies: object, ...args: any[]): string;
+declare function render(theData: any, name: string, helpers: object, original: any, dependencies: object, ...args: any[]): any;

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@peter.naydenov/morph",
     "description": "Template engine",
-    "version": "3.2.0",
+    "version": "3.3.1",
     "license": "MIT",
     "author": "Peter Naydenov",
     "main": "./src/main.js",

package/src/methods/_renderHolder.js

@@ -26,17 +26,23 @@ function _renderHolder ( template, data ) {
           chop = _chopTemplate (settings)( template )
         , set  = settings
         ;
-    chop.forEach ( (item,i) => {
-                            const isPlaceholder = item.includes ( set.TG_PRX )
-                            if ( isPlaceholder ) {
-                                            const field = item.replace ( set.TG_PRX, '' ).replace ( set.TG_SFX, '' ).trim();
-                                            if ( data.hasOwnProperty (field) && data[field] != null )  chop[i] = data[field]
-                                    } // if isPlaceholder
-                    }) // forEach chop
+    if ( typeof chop === 'string' )   return chop
+    chop.forEach ( ( item, i ) => {
+            const isPlaceholder = item.includes ( set.TG_PRX )
+            if ( isPlaceholder ) {
+                        const field = item.replace(set.TG_PRX, '').replace(set.TG_SFX, '').trim();
+                        if (data.hasOwnProperty(field) && data[field] != null) {
+                                let val = data [ field ]
+                                if ( typeof val === 'object' && val.text )   val = val.text
+                                chop[i] = val
+                            }
+                } // if isPlaceholder
+        }) // forEach chop
     return chop.join ( '' )
 } // _renderHolder func.
 
 
+
 export default _renderHolder
 
 

package/src/methods/actionData.js

@@ -0,0 +1,30 @@
+import _defineDataType from "./_defineType.js"
+
+function actionData({ name }, levelData, { helpers, extendArguments, nestedData, level, useHelper }) {
+    const theData = levelData
+    let dataType = _defineDataType(theData)
+
+    switch (dataType) {
+        case 'array':
+            theData.forEach((d, i) => {
+                const localUseHelper = useHelper(d);
+                theData[i] = (d instanceof Function) ? helpers[name]({ data: d(), ...extendArguments, full: d, useHelper: localUseHelper }) : helpers[name]({ data: d, ...extendArguments, full: d, useHelper: localUseHelper })
+            })
+            break
+        case 'object':
+            const uhObj = useHelper(theData);
+            nestedData[level] = [helpers[name]({ data: theData, ...extendArguments, full: theData, useHelper: uhObj })]
+            break
+        case 'function':
+            const fnData = theData();
+            const uhFn = useHelper(fnData);
+            nestedData[level] = [helpers[name]({ data: fnData, ...extendArguments, full: theData, useHelper: uhFn })]
+            break
+        case 'primitive':
+            const uhPrim = useHelper(theData);
+            nestedData[level] = helpers[name]({ data: theData, ...extendArguments, full: theData, useHelper: uhPrim })
+            break
+    } // switch dataType
+}
+
+export default actionData

package/src/methods/actionExtendedRender.js

@@ -0,0 +1,28 @@
+import _defineDataType from "./_defineType.js"
+
+function actionExtendedRender({ name }, levelData, { helpers, extendArguments, nestedData, level, useHelper }) {
+    // levelData is unused?
+    // build.js used `nestedData[0]`.
+    // "nestedData[0].forEach((d, i) => {"
+    // "const uh = createUseHelper(d);"
+    // "nestedData[0][i] = helpers[name]({ data: d, ...extendArguments, full: d, useHelper: uh })"
+
+    // This seems to assume extendedRender operates on ROOT data (nestedData[0])?
+    // Yes, `nestedData[0]` is typically the initial data list.
+
+    const isValid = typeof helpers[name] === 'function';
+
+    if (isValid) {
+        if (nestedData[0] && Array.isArray(nestedData[0])) {
+            nestedData[0].forEach((d, i) => {
+                const uh = useHelper(d);
+                nestedData[0][i] = helpers[name]({ data: d, ...extendArguments, full: d, useHelper: uh })
+            })
+        }
+    }
+    else {
+        // TODO: Error...
+    }
+}
+
+export default actionExtendedRender

package/src/methods/actionMix.js

@@ -0,0 +1,66 @@
+import _defineDataType from "./_defineType.js"
+import walk from '@peter.naydenov/walk'
+
+function actionMix({ name }, levelData, { helpers, extendArguments, nestedData, level, useHelper }) {
+    const theData = levelData
+    let dataType = _defineDataType(theData)
+
+    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
+                        if (kTest) Object.entries(theData).forEach(([k, v]) => nestedData[level][k] = v['text'])
+                        else nestedData[level] = theData['text']
+                        for (let i = level - 1; i >= 0; i--) {
+                                nestedData[i] = walk({ data: nestedData[i], objectCallback: check })
+                            }
+                        function check({ value, breadcrumbs }) {
+                                if (nestedData[level][breadcrumbs]) return nestedData[level][breadcrumbs]
+                                return value
+                            } // check func.
+                        break
+                    case 'array':
+                        theData.forEach((x, i) => {
+                                if (i > 0) {
+                                        let xType = _defineDataType(x);
+                                        if (x == null) return
+                                        if (xType === 'object') theData[0] += `${x.text}`
+                                        else theData[0] += `${x}`
+                                        theData.toSpliced(i, 1)
+                                    }
+                                else {
+                                        let xxType = _defineDataType(x);
+                                        theData[0] = ''
+                                        if (xxType === null) return
+                                        else if (xxType === 'object') theData[0] = `${x.text}`
+                                        else theData[0] = `${x}`
+                                    }
+                            }) // forEach theData
+                        theData.length = 1
+                        break
+            } // switch dataType
+        } // if name === ''
+    else {
+                const dType = _defineDataType ( theData ); // 'd' in build.js was 'd' from loop, here 'theData'
+                const localUseHelper = useHelper ( theData );
+                let val = helpers[name]({ data: theData, ...extendArguments, full: theData, useHelper: localUseHelper }); // 'full: d' in build.js, here 'theData'
+                let valType = _defineDataType(val);
+
+                theData.forEach((x, i) => theData.splice(i, 1))
+                theData.length = 0
+                switch (valType) {
+                            case 'primitive':
+                                theData[0] = val
+                                break
+                            case 'array':
+                                theData.push(...val)
+                                break
+                    } // switch valType
+        }
+} // actionMix func.
+
+
+
+export default actionMix
+
+

package/src/methods/actionRender.js

@@ -0,0 +1,86 @@
+import _defineDataType from "./_defineType.js"
+import render from "./render.js"
+
+function actionRender({ name }, levelData, { helpers, original, dependencies, useHelper, extendArguments, nestedData, level, iData }) {
+    /**
+     * logic from build.js 'render' case
+     * levelData is the array we are iterating (nestedData[level] or similar)
+     * But wait, build.js iterates levelData.
+     * "levelData.forEach((theData, iData) => {"
+     * So actionRender receives a SINGLE item?
+     * No, existing logic handles 'array' dataType inside the switch.
+     * But the loop inside build.js ALREADY iterates levelData.
+     * Line 276: `levelData.forEach((theData, iData) => { ... switch(type) ... })`
+     * So 'theData' is a single item from the level.
+     * BUT 'dataType' switch inside handles 'array'?
+     * _defineDataType(theData).
+     * If 'theData' is array, it iterates it.
+     * Yes.
+     */
+
+    const theData = levelData
+    let dataType = _defineDataType(theData)
+    const isRenderFunction = typeof helpers[name] === 'function';
+
+    switch (dataType) {
+        case 'array':
+            if (isRenderFunction) {
+                theData.forEach((d, i) => {
+                    if (d == null) return
+                    const dType = _defineDataType(d);
+                    // useHelper is specialized for 'd' ??
+                    // in build.js: const useHelper = createUseHelper(d);
+                    // access to 'createUseHelper' needed?
+                    // Yes.
+                    // So we pass 'createUseHelper' factory, not the instance?
+                    // Or we pass the instance if it was already created?
+                    // In build.js loop: "const useHelper = createUseHelper(d);" happens INSIDE case 'route'/'data'/'render' loops usually.
+                    // But here we are inside case 'render'.
+                    // So we need 'createUseHelper' passed in context.
+
+                    const localUseHelper = useHelper(d)
+                    const text = helpers[name]({ data: d, ...extendArguments, full: original, useHelper: localUseHelper });
+
+                    if (text == null) theData[i] = null
+                    if (dType === 'object') d['text'] = text
+                    else theData[i] = text
+                })
+            }
+            else {
+                theData.forEach((d, i) => {
+                    if (d == null) return
+                    const
+                        dType = _defineDataType(d)
+                        , text = render(d, name, helpers, original, dependencies)
+                        ;
+                    if (text == null) theData[i] = null
+                    else if (dType === 'object') d['text'] = text
+                    else theData[i] = text
+                })
+            }
+            break
+        case 'function':
+            const fD = theData();
+            const useHelperFn = useHelper(fD);
+            nestedData[level] = helpers[name]({ data: fD, ...extendArguments, full: theData, useHelper: useHelperFn })
+            break
+        case 'primitive':
+            if (isRenderFunction) {
+                const uhPrim = useHelper(theData);
+                nestedData[level] = helpers[name]({ data: theData, ...extendArguments, full: theData, useHelper: uhPrim })
+            }
+            else nestedData[level] = render(theData, name, helpers, original, dependencies)
+            break
+        case 'object':
+            if (isRenderFunction) {
+                const uhO = useHelper(theData);
+                nestedData[level][iData]['text'] = helpers[name]({ data: theData, ...extendArguments, full: theData, useHelper: uhO })
+            }
+            else {
+                theData['text'] = render(theData, name, helpers, original, dependencies)
+            }
+            break
+    } // switch renderDataType 
+}
+
+export default actionRender

package/src/methods/actionSave.js

@@ -0,0 +1,9 @@
+function actionSave({ name }, levelData, { memory }) {
+    memory[name] = structuredClone(levelData)
+}
+
+function actionOverwrite({ name }, levelData) {
+    return structuredClone(levelData)
+}
+
+export { actionSave, actionOverwrite }