@trustme24/flext 1.10.3 → 1.10.5

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@trustme24/flext",
-  "version": "1.10.3",
-  "description": "A Powerful Templating Engine",
-  "keywords": ["templates", "templating engine", "modular templates", "handlebars"],
+  "version": "1.10.5",
+  "description": "A technology for building reliable document templates",
+  "keywords": ["templates", "templating engine", "documents", "document engine", "handlebars"],
   "repository": "https://github.com/TrustMe-kz/flext.git",
   "type": "module",
   "main": "dist/index.js",
@@ -35,24 +35,24 @@
   "devDependencies": {
     "@babel/cli": "^7.28.6",
     "@babel/core": "^7.29.0",
-    "@babel/preset-env": "^7.29.0",
+    "@babel/preset-env": "^7.29.2",
     "@babel/preset-typescript": "^7.28.5",
     "@handlebars/parser": "^2.2.2",
-    "@tailwindcss/cli": "^4.2.1",
+    "@tailwindcss/cli": "^4.2.2",
     "@types/node": "^25.5.0",
     "esbuild": "^0.27.4",
     "esbuild-plugin-import-glob": "^0.1.1",
-    "tailwindcss": "^4.2.1",
+    "tailwindcss": "^4.2.2",
     "tsc-alias": "^1.8.16",
     "typescript": "^5.9.3",
     "vitest": "^4.1.0"
   },
   "dependencies": {
-    "@unocss/preset-wind4": "^66.6.6",
+    "@unocss/preset-wind4": "^66.6.7",
     "handlebars": "^4.7.8",
     "luxon": "^3.7.2",
     "striptags": "^3.2.0",
-    "unocss": "^66.6.6",
+    "unocss": "^66.6.7",
     "written-number": "^0.11.1"
   }
 }

package/src/engine.ts

@@ -0,0 +1,414 @@
+import { AST } from '@handlebars/parser';
+import * as types from '@/types';
+import * as lib from '@/lib';
+import * as errors from '@/errors';
+import * as modules from './modules';
+
+
+// Constants
+
+export const DEFAULT_HELPER_NAME = '__default';
+
+export const DEFAULT_MODEL_DEPTH = 10;
+
+
+// Types
+
+export type MacrosData = {
+    version?: string|null,
+    lang?: string|null,
+    timeZone?: string|null,
+    title?: string|null,
+    moduleNames?: string[] | null,
+    lineHeight?: string|null,
+    fields?: types.Field[] | null,
+};
+
+
+// Classes
+
+export class SimpleFlext  {
+    declare public ast: AST.Program;
+    declare public data: types.Obj;
+    declare public helpers: types.Obj;
+    public onGetProcessed: types.GetProcessedTemplateHandler = defaultGetProcessed;
+    public onGetAst: types.GetTemplateAstHandler = lib.getAst;
+
+    constructor(val: string|null = null, data: types.Obj = {}, helpers: types.Obj = {}) {
+        if (val) this.setTemplate(val);
+        this.setData({ ...this.data, ...data });
+        this.setHelpers({ ...this.helpers, ...helpers});
+    }
+
+    public setTemplate(val: string): this {
+
+        // Clearing the data
+
+        this.data = {};
+        this.helpers = {};
+
+
+        // Getting the AST
+
+        const template = this.onGetProcessed(val);
+
+        this.ast = this.onGetAst(template);
+
+
+        return this;
+    }
+
+    public setData(val: types.Obj): this {
+        this.data = val;
+        return this;
+    }
+
+    public setHelpers(val: types.Obj): this {
+        this.helpers = val;
+        return this;
+    }
+
+    public addHelper(name: string, val: any): this {
+        this.helpers[name] = val;
+        return this;
+    }
+
+    public setOnGetProcessed(val: types.GetProcessedTemplateHandler): this {
+        this.onGetProcessed = val;
+        return this;
+    }
+
+    public setOnGetAst(val: types.GetTemplateAstHandler): this {
+        this.onGetAst = val;
+        return this;
+    }
+
+    public getHtml(data?: types.Obj | null, helpers?: types.Obj | null): string {
+        const template = lib.getTemplate(this.ast);
+
+
+        // Doing some checks
+
+        if (!template)
+            throw new errors.BaseError('Flext: Unable to get HTML: No template');
+
+
+        return lib.getHtml(
+            template,
+            data ?? this.data,
+            helpers ?? this.helpers,
+        );
+    }
+
+    public async getCss(data?: types.Obj | null, options: types.Obj = {}): Promise<string> {
+        const template = lib.getTemplate(this.ast);
+        const helpersObj = options?.helpers ?? {};
+        const helpers = { ...this.helpers, ...helpersObj };
+
+
+        // Doing some checks
+
+        if (!template)
+            throw new errors.BaseError('Flext: Unable to get CSS: No template');
+
+
+        return await lib.getCss(
+            template,
+            data ?? this.data,
+            { ...options, helpers },
+        );
+    }
+
+    public get html(): string {
+        return this.getHtml();
+    }
+}
+
+export class Flext extends SimpleFlext {
+    declare public version: string;
+    declare public lang: string;
+    declare public title: string;
+    declare public timeZone: string;
+    declare public lineHeight: number;
+    declare public assets: types.Obj<Blob>;
+    declare public fields: types.Field[];
+    public onGetTitle: types.GetTemplateTitleHandler = lib.getHtmlH1;
+    public onGetMacro: types.GetTemplateMacroHandler = lib.getMacros;
+
+    constructor(val: string|null = null, data: types.Obj = {}, helpers: types.Obj = {}) {
+        super(null, data, helpers);
+
+        if (val) this.setTemplate(val);
+        this.setData({ ...this.data, ...data });
+        this.setHelpers({ ...this.helpers, ...helpers});
+    }
+
+    public useModule(...val: string[]): this {
+        for (const name of val)
+            this.addModule(name, modules[name]);
+
+        return this;
+    }
+
+    public setTemplate(val: string): this {
+
+        // Setting the template
+
+        super.setTemplate(val);
+
+
+        // Defining the variables
+
+        const [ titleStr ] = this.onGetTitle(this.ast);
+
+        const macros = this.onGetMacro(this.ast);
+
+
+        // Getting the data
+
+        const { version, lang, timeZone, title, moduleNames, lineHeight, fields } = macrosToData(macros);
+
+
+        // Setting the data
+
+        if (version)
+            this.setVersion(version);
+
+        if (lang)
+            this.setLang(lang);
+
+        if (timeZone)
+            this.setTimeZone(timeZone);
+
+        if (title || titleStr)
+            this.setTitle(title ?? lib.ensureTitle(titleStr));
+
+        if (lineHeight)
+            this.setLineHeight(Number(lineHeight));
+
+        if (fields && fields?.length)
+            this.setFields(fields);
+
+
+        // Using the modules
+
+        this.useModule(...moduleNames);
+
+
+        return this;
+    }
+
+    public setVersion(val: string): this {
+        this.version = val;
+        return this;
+    }
+
+    public setLang(val: string): this {
+        this.lang = val;
+        return this;
+    }
+
+    public setTitle(val: string): this {
+        this.title = val;
+        return this;
+    }
+
+    public setTimeZone(val: string): this {
+        this.timeZone = val;
+        return this;
+    }
+
+    public setLineHeight(val: number): this {
+        this.lineHeight = val;
+        return this;
+    }
+
+    public setAssets(val: types.Obj<Blob>): this {
+        this.assets = val;
+        return this;
+    }
+
+    public addAsset(name: string, val: Blob): this {
+        this.assets[name] = val;
+        return this;
+    }
+
+    public setFields(val: types.Field[]): this {
+        this.fields = val;
+        return this;
+    }
+
+    public addModule(name: string, val: any): this {
+        const helpers = val?.helpers ?? {};
+
+
+        // Iterating for each helper
+
+        for (const helperName in helpers) {
+            if (!lib.has(helpers, helperName)) continue;
+
+
+            // Getting the data
+
+            const handle = helpers[helperName];
+
+            const isDefault = helperName === DEFAULT_HELPER_NAME;
+
+
+            // Adding the helper
+
+            const flext = this;
+
+            const helper = function (..._args: any[]): any {
+                const args = _args?.slice(0, -1) ?? [];
+                const options = _args[_args.length - 1] ?? {};
+                const namedArgs = options?.hash ?? {};
+                // @ts-ignore
+                const self = this;
+                const getContent = () => options?.fn(self) ?? null;
+
+                return handle({ flext, args, options, namedArgs, self, getContent });
+            }
+
+            if (isDefault)
+                this.addHelper(name, helper);
+            else
+                this.addHelper(name + ':' + helperName, helper);
+        }
+
+
+        return this;
+    }
+
+    public setOnGetTitle(val: types.GetTemplateTitleHandler): this {
+        this.onGetTitle = val;
+        return this;
+    }
+
+    public setOnGetMacro(val: types.GetTemplateMacroHandler): this {
+        this.onGetMacro = val;
+        return this;
+    }
+
+    public getDataModel(depth: number = DEFAULT_MODEL_DEPTH): types.MetadataModelNode[] {
+
+        // Defining the functions
+
+        /**
+         * TODO: kr: Costyl: Detects if it is a helper call (like 'put:noColor')
+         */
+        const isHelper = (node: types.DataModelNode): boolean => {
+            for (const helperName in this.helpers) {
+                if (!lib.has(this.helpers, helperName))
+                    continue;
+                else if (node?.name === helperName)
+                    return true;
+            }
+
+            return false;
+        }
+
+        /**
+         * TODO: kr: Costyl: Filters the helper calls (like 'put:noColor')
+         */
+        const isValid = (node: types.DataModelNode): boolean => !isHelper(node);
+
+        const dataModelNodeToMetadata = (node: types.DataModelNode): types.MetadataModelNode => lib.dataModelNodeToMetadata(node, this.fields, {}, depth);
+
+
+        // Getting the nodes
+
+        const model = lib.getDataModel(this.ast);
+        const nodes: types.DataModelNode[] = model?.$ ?? [];
+
+
+        return nodes.filter(isValid).map(dataModelNodeToMetadata);
+    }
+
+    public getValidationErrors(data?: types.Obj | null, depth: number = DEFAULT_MODEL_DEPTH): errors.TemplateDataValidationError[] {
+        return lib.getTemplateValidationErrorsByMetadata(data ?? this.data, this.model, depth);
+    }
+
+    public getIsValid(data?: types.Obj | null, depth: number = DEFAULT_MODEL_DEPTH): boolean {
+        const errors = this.getValidationErrors(data ?? this.data, depth);
+        return !errors?.length;
+    }
+
+    public get model(): types.MetadataModelNode[] {
+        return this.getDataModel();
+    }
+
+    public get validationErrors(): errors.TemplateDataValidationError[] {
+        return this.getValidationErrors();
+    }
+
+    public get errors(): errors.BaseError[] {
+        return this.validationErrors;
+    }
+
+    public get isValid(): boolean {
+        return this.getIsValid();
+    }
+}
+
+
+// Functions
+
+export function macrosToData(macros: types.Macro[]): MacrosData {
+
+    // Defining the functions
+
+    const getAll = (..._val: string[]): types.Macro[] | null => macros?.filter(m => lib.inarr(m?.name, ..._val)) ?? null;
+
+    const get = (_val: string): string | null => {
+        const [macro] = getAll(_val);
+        const [param] = macro?.params ?? [];
+
+        return param?.value ?? null;
+    };
+
+
+    // Getting the data
+
+    const version = get('v');
+    const lang = get('lang');
+    const title = get('title');
+    const timeZone = get('timeZone');
+    const modulesMacros = getAll('use');
+    const lineHeight = get('lineHeight');
+    const optionMacros = getAll('option');
+    const fieldMacros = getAll('group', 'field');
+
+
+    // Getting the fields
+
+    const fieldValueOptions = optionMacros?.map(lib.macroToFieldValueOption) ?? null;
+    const fields = fieldMacros?.map(lib.macroToField) ?? [];
+
+    lib.applyValueOptionsToFields(fieldValueOptions, fields);
+
+    lib.applyAbsoluteOrderToFields(fields);
+
+
+    // Getting the field groups
+
+    const fieldGroups = fields.filter(f => f?.extra?.macroName === 'group');
+
+    for (const fieldGroup of fieldGroups)
+        fieldGroup.type = 'object';
+
+
+    // Getting the modules
+
+    const moduleNames = modulesMacros.map(lib.macroToModuleNames).flat();
+
+
+    return { version, lang, timeZone, title, moduleNames, lineHeight, fields };
+}
+
+export function defaultGetProcessed(val: string): string {
+    return val;
+}
+
+
+export default Flext;