@reidelsaltres/pureper 0.1.157 → 0.1.160

package/src/foundation/engine/Rule.ts

@@ -0,0 +1,136 @@
+import Scope from './Scope.js';
+import Expression from './Expression.js';
+
+/**
+ * RuleMatch - результат поиска Rule в шаблоне
+ */
+export interface RuleMatch {
+    /** Полное совпадение включая синтаксис Rule */
+    fullMatch: string;
+    /** Начальная позиция в исходной строке */
+    start: number;
+    /** Конечная позиция в исходной строке */
+    end: number;
+    /** Дополнительные данные специфичные для Rule */
+    data?: Record<string, any>;
+}
+
+/**
+ * RuleResult - результат выполнения Rule
+ */
+export interface RuleResult {
+    /** HTML-результат для замены */
+    output: string;
+    /** Использованные Observable для отслеживания */
+    observables?: any[];
+    /** Дочерние Rule (для вложенных структур) */
+    children?: Rule[];
+}
+
+/**
+ * RuleType - тип Rule
+ */
+export type RuleType = 'syntax' | 'attribute';
+
+/**
+ * Rule - базовый абстрактный класс для всех правил шаблонизатора.
+ */
+export default abstract class Rule {
+    /** Уникальное имя правила */
+    public abstract readonly name: string;
+    
+    /** Тип правила: syntax или attribute */
+    public abstract readonly type: RuleType;
+    
+    /** Приоритет выполнения (меньше = раньше) */
+    public readonly priority: number = 100;
+
+    /**
+     * Найти все вхождения этого Rule в шаблоне.
+     * @param template - исходный шаблон
+     * @returns массив найденных совпадений
+     */
+    public abstract find(template: string): RuleMatch[];
+
+    /**
+     * Выполнить Rule и вернуть результат.
+     * @param match - найденное совпадение
+     * @param scope - текущий Scope
+     * @param engine - ссылка на TemplateEngine (для рекурсивной обработки)
+     */
+    public abstract execute(
+        match: RuleMatch, 
+        scope: Scope,
+        engine?: any // TemplateEngine, circular dependency workaround
+    ): RuleResult | Promise<RuleResult>;
+
+    /**
+     * Проверить, поддерживает ли Rule Observable значения
+     */
+    public supportsObservable(): boolean {
+        return true;
+    }
+}
+
+/**
+ * SyntaxRule - базовый класс для синтаксических правил.
+ * Синтаксические правила могут быть в любом месте шаблона (кроме атрибутов).
+ */
+export abstract class SyntaxRule extends Rule {
+    public readonly type: RuleType = 'syntax';
+}
+
+/**
+ * AttributeRule - базовый класс для атрибутивных правил.
+ * Атрибутивные правила работают только внутри HTML-тегов.
+ */
+export abstract class AttributeRule extends Rule {
+    public readonly type: RuleType = 'attribute';
+    
+    /**
+     * Получить элемент, к которому применяется атрибут.
+     * @param template - шаблон
+     * @param attributePosition - позиция атрибута
+     * @returns информация об элементе
+     */
+    protected findParentElement(
+        template: string, 
+        attributePosition: number
+    ): { tagName: string; tagStart: number; tagEnd: number } | null {
+        // Find opening < before attribute
+        let tagStart = attributePosition;
+        while (tagStart > 0 && template[tagStart] !== '<') {
+            tagStart--;
+        }
+
+        if (template[tagStart] !== '<') {
+            return null;
+        }
+
+        // Extract tag name
+        let nameEnd = tagStart + 1;
+        while (nameEnd < template.length && /[a-zA-Z0-9_-]/.test(template[nameEnd])) {
+            nameEnd++;
+        }
+        const tagName = template.slice(tagStart + 1, nameEnd);
+
+        // Find closing >
+        let tagEnd = attributePosition;
+        let inString = false;
+        let stringChar = '';
+        while (tagEnd < template.length) {
+            const ch = template[tagEnd];
+            if (!inString && (ch === '"' || ch === "'")) {
+                inString = true;
+                stringChar = ch;
+            } else if (inString && ch === stringChar) {
+                inString = false;
+            } else if (!inString && ch === '>') {
+                break;
+            }
+            tagEnd++;
+        }
+
+        return { tagName, tagStart, tagEnd: tagEnd + 1 };
+    }
+}

package/src/foundation/engine/Scope.ts

@@ -0,0 +1,166 @@
+/**
+ * Scope - класс для работы с контекстом переменных и функций.
+ * Поддерживает объединение нескольких Scope, извлечение полей из объектов и классов.
+ */
+export default class Scope {
+    private variables: Record<string, any> = {};
+    private readonly debugWarnings: boolean;
+
+    constructor(options?: { debugWarnings?: boolean }) {
+        this.debugWarnings = options?.debugWarnings ?? true;
+    }
+
+    /**
+     * Получить все переменные Scope как Record
+     */
+    public getVariables(): Record<string, any> {
+        return { ...this.variables };
+    }
+
+    /**
+     * Установить переменную в Scope
+     */
+    public set(key: string, value: any): void {
+        if (this.debugWarnings && key in this.variables) {
+            console.warn(`[Scope] Warning: Variable "${key}" is being overwritten`);
+        }
+        this.variables[key] = value;
+    }
+
+    /**
+     * Получить переменную из Scope
+     */
+    public get(key: string): any {
+        return this.variables[key];
+    }
+
+    /**
+     * Проверить наличие переменной
+     */
+    public has(key: string): boolean {
+        return key in this.variables;
+    }
+
+    /**
+     * Удалить переменную из Scope
+     */
+    public delete(key: string): boolean {
+        if (key in this.variables) {
+            delete this.variables[key];
+            return true;
+        }
+        return false;
+    }
+
+    /**
+     * Объединить другой Scope или объект в текущий Scope.
+     * При конфликте имён выводится предупреждение, последнее значение имеет приоритет.
+     */
+    public merge(source: Scope | Record<string, any> | object): Scope {
+        const sourceVars = source instanceof Scope 
+            ? source.getVariables() 
+            : this.extractFromObject(source);
+
+        for (const [key, value] of Object.entries(sourceVars)) {
+            if (this.debugWarnings && key in this.variables) {
+                console.warn(`[Scope] Warning: Variable "${key}" conflict during merge, using new value`);
+            }
+            this.variables[key] = value;
+        }
+
+        return this;
+    }
+
+    /**
+     * Создать дочерний (локальный) Scope на основе текущего.
+     * Изменения в дочернем Scope не влияют на родительский.
+     */
+    public createChild(localVariables?: Record<string, any>): Scope {
+        const child = new Scope({ debugWarnings: this.debugWarnings });
+        child.variables = { ...this.variables };
+        
+        if (localVariables) {
+            for (const [key, value] of Object.entries(localVariables)) {
+                child.variables[key] = value;
+            }
+        }
+
+        return child;
+    }
+
+    /**
+     * Извлечь поля и методы из объекта или экземпляра класса.
+     * Пропускает нативные DOM/браузерные прототипы.
+     */
+    public extractFromObject(obj: object): Record<string, any> {
+        const ctx: Record<string, any> = {};
+
+        if (!obj || typeof obj !== 'object') {
+            return ctx;
+        }
+
+        // Copy own properties
+        for (const key of Object.keys(obj)) {
+            ctx[key] = (obj as any)[key];
+        }
+
+        // Copy prototype methods (for class instances)
+        let proto = Object.getPrototypeOf(obj);
+        while (proto && proto !== Object.prototype) {
+            // Avoid copying host (DOM/native) prototype methods which may throw
+            const ctorName = proto?.constructor 
+                ? String(proto.constructor.name ?? '') 
+                : '';
+            
+            if (/HTMLElement|Element|Node|EventTarget|Window|GlobalThis/i.test(ctorName)) {
+                proto = Object.getPrototypeOf(proto);
+                continue;
+            }
+
+            for (const key of Object.getOwnPropertyNames(proto)) {
+                if (key === 'constructor' || key in ctx) continue;
+
+                let desc: PropertyDescriptor | undefined;
+                try {
+                    desc = Object.getOwnPropertyDescriptor(proto, key);
+                } catch {
+                    continue;
+                }
+                if (!desc) continue;
+
+                // Only bind plain function values — don't copy getters/setters
+                if (typeof desc.value === 'function') {
+                    try {
+                        ctx[key] = (desc.value as Function).bind(obj);
+                    } catch {
+                        continue;
+                    }
+                }
+            }
+
+            proto = Object.getPrototypeOf(proto);
+        }
+
+        return ctx;
+    }
+
+    /**
+     * Статический метод для создания Scope из объекта
+     */
+    public static from(source: object | Record<string, any>, options?: { debugWarnings?: boolean }): Scope {
+        const scope = new Scope(options);
+        scope.merge(source);
+        return scope;
+    }
+
+    /**
+     * Статический метод для объединения нескольких Scope/объектов
+     */
+    public static combine(...sources: (Scope | Record<string, any> | object)[]): Scope {
+        const scope = new Scope();
+        for (const source of sources) {
+            scope.merge(source);
+        }
+        return scope;
+    }
+}

package/src/foundation/engine/TemplateEngine.ts

@@ -0,0 +1,243 @@
+import Scope from './Scope.js';
+import Expression from './Expression.js';
+import EscapeHandler from './EscapeHandler.js';
+import TemplateInstance, { TemplateSection } from './TemplateInstance.js';
+import Rule, { RuleMatch, RuleResult, SyntaxRule, AttributeRule } from './Rule.js';
+import Observable from '../api/Observer.js';
+
+// Import rules
+import ExpressionRule from './rules/syntax/ExpressionRule.js';
+import IfRule from './rules/syntax/IfRule.js';
+import ForRule from './rules/syntax/ForRule.js';
+import RefRule from './rules/attribute/RefRule.js';
+import EventRule from './rules/attribute/EventRule.js';
+import InjectionRule from './rules/attribute/InjectionRule.js';
+
+/**
+ * TemplateEngineOptions - настройки TemplateEngine
+ */
+export interface TemplateEngineOptions {
+    /** Оставлять синтаксис атрибутивных Rule в финальном HTML */
+    showAttributeRule?: boolean;
+    /** Включить предупреждения отладки */
+    debugWarnings?: boolean;
+}
+
+/**
+ * ProcessResult - результат обработки шаблона
+ */
+export interface ProcessResult {
+    output: string;
+    observables: Observable<any>[];
+    sections: TemplateSection[];
+}
+
+/**
+ * TemplateEngine - главный класс шаблонизатора.
+ * Обрабатывает HTML-шаблон с Rule и создаёт TemplateInstance.
+ */
+export default class TemplateEngine {
+    private readonly scope: Scope;
+    private readonly options: TemplateEngineOptions;
+    private readonly syntaxRules: SyntaxRule[] = [];
+    private readonly attributeRules: AttributeRule[] = [];
+
+    constructor(scope: Scope | object, options?: TemplateEngineOptions) {
+        this.scope = scope instanceof Scope ? scope : Scope.from(scope);
+        this.options = {
+            showAttributeRule: false,
+            debugWarnings: true,
+            ...options
+        };
+
+        // Register default rules (sorted by priority)
+        this.registerDefaultRules();
+    }
+
+    /**
+     * Зарегистрировать стандартные правила
+     */
+    private registerDefaultRules(): void {
+        // Syntax rules
+        this.syntaxRules.push(new ForRule());
+        this.syntaxRules.push(new IfRule());
+        this.syntaxRules.push(new ExpressionRule());
+
+        // Attribute rules
+        this.attributeRules.push(new RefRule());
+        this.attributeRules.push(new EventRule());
+        this.attributeRules.push(new InjectionRule());
+
+        // Sort by priority
+        this.syntaxRules.sort((a, b) => a.priority - b.priority);
+        this.attributeRules.sort((a, b) => a.priority - b.priority);
+    }
+
+    /**
+     * Добавить пользовательское правило
+     */
+    public addRule(rule: Rule): void {
+        if (rule.type === 'syntax') {
+            this.syntaxRules.push(rule as SyntaxRule);
+            this.syntaxRules.sort((a, b) => a.priority - b.priority);
+        } else {
+            this.attributeRules.push(rule as AttributeRule);
+            this.attributeRules.sort((a, b) => a.priority - b.priority);
+        }
+    }
+
+    /**
+     * Получить Scope
+     */
+    public getScope(): Scope {
+        return this.scope;
+    }
+
+    /**
+     * Обработать шаблон и вернуть TemplateInstance
+     */
+    public parse(template: string): TemplateInstance {
+        const result = this.processTemplate(template, this.scope);
+        const templateInstance = new TemplateInstance(result.output, this.scope);
+
+        // Add sections
+        for (const section of result.sections) {
+            templateInstance.addSection(section);
+
+            // Track observables
+            for (const observable of section.result.observables || []) {
+                templateInstance.trackObservable(observable, section, (s) => {
+                    return this.processTemplate(s.sourceTemplate, this.scope);
+                });
+            }
+        }
+
+        return templateInstance;
+    }
+
+    /**
+     * Обработать шаблон (внутренний метод, используется Rule для рекурсии)
+     */
+    public processTemplate(template: string, scope: Scope): ProcessResult {
+        const allObservables: Observable<any>[] = [];
+        const allSections: TemplateSection[] = [];
+
+        // Step 1: Handle @@ escape sequences
+        let processed = EscapeHandler.process(template, (escaped) => {
+            let result = escaped;
+
+            // Step 2: Process syntax rules (in priority order)
+            for (const rule of this.syntaxRules) {
+                result = this.processRule(rule, result, scope, allObservables, allSections);
+            }
+
+            // Step 3: Process attribute rules
+            for (const rule of this.attributeRules) {
+                // Skip injection - processed last
+                if (rule.name === 'injection') continue;
+                result = this.processRule(rule, result, scope, allObservables, allSections);
+            }
+
+            return result;
+        });
+
+        // Step 4: Process injection rules last
+        const injectionRule = this.attributeRules.find(r => r.name === 'injection');
+        if (injectionRule) {
+            processed = this.processRule(injectionRule, processed, scope, allObservables, allSections);
+        }
+
+        // Step 5: Handle showAttributeRule option
+        if (!this.options.showAttributeRule) {
+            processed = this.removeAttributeSyntax(processed);
+        }
+
+        return {
+            output: processed,
+            observables: allObservables,
+            sections: allSections
+        };
+    }
+
+    /**
+     * Обработать одно правило
+     */
+    private processRule(
+        rule: Rule,
+        template: string,
+        scope: Scope,
+        observables: Observable<any>[],
+        sections: TemplateSection[]
+    ): string {
+        const matches = rule.find(template);
+        
+        // Sort matches by position (reverse to process from end)
+        matches.sort((a, b) => b.start - a.start);
+
+        let result = template;
+
+        for (const match of matches) {
+            try {
+                const ruleResult = rule.execute(match, scope, this) as RuleResult;
+
+                // Track observables
+                if (ruleResult.observables) {
+                    observables.push(...ruleResult.observables);
+                }
+
+                // Create section
+                const section: TemplateSection = {
+                    rule,
+                    match,
+                    result: ruleResult,
+                    sourceTemplate: match.fullMatch,
+                    children: [],
+                    subscriptions: []
+                };
+                sections.push(section);
+
+                // Replace in template
+                result = result.slice(0, match.start) + ruleResult.output + result.slice(match.end);
+
+            } catch (error) {
+                console.error(`[TemplateEngine] Error processing rule "${rule.name}":`, error);
+                // Continue processing other rules
+            }
+        }
+
+        return result;
+    }
+
+    /**
+     * Удалить синтаксис атрибутивных Rule из финального HTML
+     */
+    private removeAttributeSyntax(template: string): string {
+        // Remove @[ref], @on[...], @injection[...] patterns that weren't processed
+        return template
+            .replace(/@\[ref\]\s*=\s*["'][^"']*["']/gi, '')
+            .replace(/@on\[[a-zA-Z]+\]\s*=\s*["'][^"']*["']/gi, '')
+            .replace(/@injection\[(head|tail)\]\s*=\s*["'][^"']*["']/gi, '');
+    }
+
+    /**
+     * Статический метод для быстрой обработки
+     */
+    public static process(template: string, scope: object, options?: TemplateEngineOptions): string {
+        const engine = new TemplateEngine(scope, options);
+        const TemplateInstance = engine.parse(template);
+        return TemplateInstance.getTemplate();
+    }
+
+    /**
+     * Создать TemplateInstance из шаблона
+     */
+    public static create(template: string, scope: object, options?: TemplateEngineOptions): TemplateInstance {
+        const engine = new TemplateEngine(scope, options);
+        return engine.parse(template);
+    }
+}
+
+// Re-export useful types
+export { Scope, Expression, TemplateInstance, Rule, SyntaxRule, AttributeRule };
+export { ExpressionRule, IfRule, ForRule, RefRule, EventRule, InjectionRule };
+export * from './exceptions/TemplateExceptions.js';