vortez 5.0.0-dev.19 → 5.0.1

package/.gitignore

@@ -1,9 +1,11 @@
 # Build setting
 **/node_modules/
 **/build/
+**/build-*/
 **/.**
 **/*.log
 **/*.env
+**/*.tsbuildinfo
 !.gitignore
 
 # Work space setting to Project IDX

package/README.md

@@ -26,12 +26,14 @@ The package exports a default `Vortez` server class, plus named exports for `Rou
 - [Installation](#installation)
 - [Getting Started](#getting-started)
 - [Configuration Files](#configuration-files)
+- [Architecture Guide](#architecture-guide)
 - [Examples Repository](#examples-repository)
 - [Core Concepts](#core-concepts)
 - [Routing Rules](#routing-rules)
 - [Server Configuration](#server-configuration)
 - [Use Cases](#use-cases)
 - [Development Features](#development-features)
+- [Acknowledgments](#acknowledgments)
 
 ---
 
@@ -162,8 +164,16 @@ const server = new Vortez(config);
 await server.start();
 ```
 
+> [!NOTE]
+> Template defaults are absolute by design and point to this module's bundled `global/Template/*` files.
+> If you set `templates.error` or `templates.folder` yourself, you can still use paths relative to your own project.
+
 This workflow is also covered in the dedicated examples repository.
 
+### Architecture Guide
+
+For a comprehensive guide on Vortez's internal architecture, request lifecycle, performance considerations, and deployment patterns, see [Architecture Documentation](docs/ARCHITECTURE.md).
+
 ### Examples Repository
 
 The runnable examples are being moved to a separate repository to keep this package focused.
@@ -217,24 +227,20 @@ server.router.addAction('GET', '/api/$action/$id', (request, response) => {
   console.log(request.headers);       // HTTP headers
   // For body, use: const body = await request.post;
 });
-```
-
-### Response Object
-
-The `response` object provides methods to send data back to the client:
+```. All methods are **async** and must be awaited:
 
 ```js
 // Send JSON
-response.sendJson({ key: 'value' });
+await response.sendJson({ key: 'value' });
 
 // Send HTML/text
-response.send('Hello World');
+await response.send('Hello World');
 
 // Send file
-response.sendFile('path/to/file.html');
+await response.sendFile('path/to/file.html');
 
 // Send with custom status and headers
-response.sendJson({ id: 123 }, {
+await response.sendJson({ id: 123 }, {
   status: 201,
   headers: {
     'X-Test': 'TestHeader'
@@ -244,6 +250,12 @@ response.sendJson({ id: 123 }, {
 // The same options shape is supported by send, sendJson, sendFile and sendTemplate
 ```
 
+> **Breaking Change in 5.0.0**: All response methods are now async. Update your route handlers to use `await` when calling response methods.
+});
+
+// The same options shape is supported by send, sendJson, sendFile and sendTemplate
+```
+
 ### Middleware Execution Model
 
 Vortez uses a **snapshot middleware composition model**:
@@ -563,6 +575,12 @@ server.config.set('ssl', {
 
 The framework will automatically create an HTTPS server alongside the HTTP server.
 
+### Template Path Behavior
+
+- `templates.error` and `templates.folder` default to absolute module paths inside Vortez's own `global/Template` directory.
+- This is intentional so defaults work consistently regardless of where your app is executed from.
+- When you provide your own template paths, relative paths are allowed and resolved from your app/project context.
+
 ### Available Configuration Keys
 
 ```js
@@ -802,6 +820,12 @@ const mailer = new Mail({
 });
 ```
 
+---
+
+# Acknowledgments
+
+Special thanks to my girlfriend for helping me identify and report a critical path traversal vulnerability during the 5.0.0 release process. Your support made this release safer for everyone.
+
 > [!WARNING]
 > Beta features are experimental and may change significantly. Use with caution in production.
 

package/build/Template/Compiler.d.ts

@@ -0,0 +1,70 @@
+/**
+ * @author NetFeez <netfeez.dev@gmail.com>
+ * @description Add the vhtml template compiler to the Vortez.
+ * @license Apache-2.0
+ */
+export declare const VARIABLE: RegExp;
+export declare const VARIABLE_TAG: RegExp;
+export declare const EACH_BLOCK: RegExp;
+export declare const IF_BLOCK: RegExp;
+export declare class Compiler {
+    /**
+     * Compile a template.
+     * This internal method takes the raw template content and the data object
+     * and performs the actual compilation, replacing variables and processing
+     * object/array blocks according to the defined syntax.
+     *
+     * @example `Template.compile('Hello, ${name}!', { name: 'Alice' });`
+     * @param content - The content of the template.
+     * @param data - The data used to compile the template.
+     * @returns The compiled template.
+     * @throws Error if key and value names are equal in object blocks.
+     */
+    static compile(content: string, data: Compiler.Data): string;
+    /**
+     * Compile all the variables in the template content using the provided data object.
+     * @param content - The raw template content containing variable placeholders.
+     * @param data - The data object used for variable substitution.
+     * @returns The template content with all variables replaced by their corresponding values from the data object.
+     */
+    private static compileVariables;
+    /**
+     * Finds the index of the closing tag corresponding to a given opening tag in the template content, accounting for nested tags of the same type.
+     * @param content - The raw template content containing the tags.
+     * @param openTag - The opening tag to match (e.g., '<vortez-each').
+     * @param closeTag - The closing tag to match (e.g., '</vortez-each>').
+     * @param startIndex - The index in the content where the search should begin (typically right after the opening tag).
+     * @returns The index of the closing tag that matches the opening tag, or -1 if no matching closing tag is found.
+     */
+    private static findClosingTag;
+    /**
+     * Compile all the if/else blocks in the template content using the provided data object.
+     * @param content - The raw template content containing if/else block placeholders.
+     * @param data - The data object used for block processing.
+     * @returns The template content with all if/else blocks processed and replaced by their corresponding generated content based on the data object.
+     */
+    static compileEachBlocks(content: string, data: Compiler.Data): string;
+    static compileIfBlocks(content: string, data: Compiler.Data): string;
+}
+export declare namespace Compiler {
+    interface VariableGroups {
+        name: string;
+        default?: string;
+    }
+    interface EachBlockGroups {
+        name: string;
+        keyName?: string;
+        valueName?: string;
+        loop: string;
+    }
+    interface IfBlockGroups {
+        name: string;
+        condition?: '==' | '!=';
+        expected?: string;
+        content: string;
+    }
+    interface Data {
+        [key: string]: any;
+    }
+}
+export default Compiler;

package/build/Template/Compiler.js

@@ -0,0 +1,135 @@
+/**
+ * @author NetFeez <netfeez.dev@gmail.com>
+ * @description Add the vhtml template compiler to the Vortez.
+ * @license Apache-2.0
+ */
+export const VARIABLE = /\{\{\s*?(?<name>\w+)(?:\s*\|\|\s*(?<quote>["'])(?<default>.*?)\k<quote>)?\s*\}\}/g;
+export const VARIABLE_TAG = /<vortez-var\s+name=["'](?<name>\w+)["'](?:\s+default=["'](?<default>.*?)["'])?\s*(?:\/>|>(?<content>.*?)<\/vortez-var>)/g;
+export const EACH_BLOCK = /<vortez-each\s+name=["'](?<name>\w+)["'](?:\s+value=["'](?<valueName>\w+)["'])?(?:\s+key=["'](?<keyName>\w+)["'])?\s*>(?<loop>[^]+?)<\/vortez-each>/g;
+export const IF_BLOCK = /<vortez-if\s+name=["'](?<name>\w+)["'](?:\s+condition=["'](?<condition>==|!=)["']\s+expected=["'](?<expected>.*?)["'])?\s*>(?<content>[^]+?)<\/vortez-if>/g;
+export class Compiler {
+    /**
+     * Compile a template.
+     * This internal method takes the raw template content and the data object
+     * and performs the actual compilation, replacing variables and processing
+     * object/array blocks according to the defined syntax.
+     *
+     * @example `Template.compile('Hello, ${name}!', { name: 'Alice' });`
+     * @param content - The content of the template.
+     * @param data - The data used to compile the template.
+     * @returns The compiled template.
+     * @throws Error if key and value names are equal in object blocks.
+     */
+    static compile(content, data) {
+        content = Compiler.compileEachBlocks(content, data);
+        content = Compiler.compileIfBlocks(content, data);
+        content = Compiler.compileVariables(content, data);
+        return content;
+    }
+    /**
+     * Compile all the variables in the template content using the provided data object.
+     * @param content - The raw template content containing variable placeholders.
+     * @param data - The data object used for variable substitution.
+     * @returns The template content with all variables replaced by their corresponding values from the data object.
+     */
+    static compileVariables(content, data) {
+        content = content.replace(VARIABLE, (text, ...args) => {
+            const groups = args.pop();
+            const { name, default: defaultValue } = groups;
+            return name && name in data ? data[name] : defaultValue || text;
+        });
+        content = content.replace(VARIABLE_TAG, (text, ...args) => {
+            const groups = args.pop();
+            const { name, default: defaultValue, content: tagContent } = groups;
+            return name && name in data ? data[name] : defaultValue || tagContent || text;
+        });
+        return content;
+    }
+    /**
+     * Finds the index of the closing tag corresponding to a given opening tag in the template content, accounting for nested tags of the same type.
+     * @param content - The raw template content containing the tags.
+     * @param openTag - The opening tag to match (e.g., '<vortez-each').
+     * @param closeTag - The closing tag to match (e.g., '</vortez-each>').
+     * @param startIndex - The index in the content where the search should begin (typically right after the opening tag).
+     * @returns The index of the closing tag that matches the opening tag, or -1 if no matching closing tag is found.
+     */
+    static findClosingTag(content, openTag, closeTag, startIndex) {
+        let depth = 0;
+        const tagRegex = new RegExp(`${openTag}|${closeTag}`, 'g');
+        tagRegex.lastIndex = startIndex;
+        let match;
+        while ((match = tagRegex.exec(content)) !== null) {
+            if (match[0].startsWith(openTag.substring(0, 3)))
+                depth++;
+            if (match[0] === closeTag)
+                depth--;
+            if (depth === 0)
+                return match.index;
+        }
+        return -1;
+    }
+    /**
+     * Compile all the if/else blocks in the template content using the provided data object.
+     * @param content - The raw template content containing if/else block placeholders.
+     * @param data - The data object used for block processing.
+     * @returns The template content with all if/else blocks processed and replaced by their corresponding generated content based on the data object.
+     */
+    static compileEachBlocks(content, data) {
+        const openTagMatch = /<vortez-each\s+name=["'](?<name>\w+)["']/.exec(content);
+        if (!openTagMatch)
+            return content;
+        const startIdx = openTagMatch.index;
+        const endHeaderIdx = content.indexOf('>', startIdx);
+        const closingIdx = this.findClosingTag(content, '<vortez-each', '</vortez-each>', startIdx);
+        if (closingIdx === -1)
+            return `<p>the block is not closed: ${content.substring(startIdx, startIdx + 30)}...</p>`;
+        const fullBlock = content.substring(startIdx, closingIdx + 14);
+        const innerLoop = content.substring(endHeaderIdx + 1, closingIdx);
+        const header = content.substring(startIdx, endHeaderIdx);
+        const name = openTagMatch.groups?.name;
+        const valueName = /value=["'](?<v>\w+)["']/.exec(header)?.groups?.v || 'value';
+        const keyName = /key=["'](?<k>\w+)["']/.exec(header)?.groups?.k || 'key';
+        const iterable = data[name];
+        let result = "";
+        if (!iterable)
+            return `<p>the iterable "${name}" is not defined</p>`;
+        if (keyName === valueName)
+            return `<p>the key and value names must be different in block: ${fullBlock}</p>`;
+        if (iterable instanceof Object) {
+            result = Object.entries(iterable).map(([k, v]) => {
+                const context = { ...data, [keyName]: k, [valueName]: v };
+                return this.compile(innerLoop, context);
+            }).join('');
+        }
+        return this.compileEachBlocks(content.replace(fullBlock, result), data);
+    }
+    static compileIfBlocks(content, data) {
+        const openTagMatch = /<vortez-if\s+name=["'](?<name>\w+)["']/.exec(content);
+        if (!openTagMatch)
+            return content;
+        const startIdx = openTagMatch.index;
+        const endHeaderIdx = content.indexOf('>', startIdx);
+        const closingIdx = this.findClosingTag(content, '<vortez-if', '</vortez-if>', startIdx);
+        if (closingIdx === -1)
+            return `<p>the block is not closed: ${content.substring(startIdx, startIdx + 30)}...</p>`;
+        const fullBlock = content.substring(startIdx, closingIdx + 12);
+        const innerContent = content.substring(endHeaderIdx + 1, closingIdx);
+        const header = content.substring(startIdx, endHeaderIdx);
+        const name = openTagMatch.groups?.name;
+        const condition = /condition=["'](?<c>==|!=)["']/.exec(header)?.groups?.c;
+        const expected = /expected=["'](?<e>.*?)["']/.exec(header)?.groups?.e;
+        const [ifPart, elsePart] = innerContent.split(/<vortez-else\s*?\/>/);
+        const value = data[name];
+        let isTrue = false;
+        if (condition && expected !== undefined) {
+            const resExpected = expected.includes('{{') ? this.compileVariables(expected, data) : expected;
+            isTrue = (condition === '==') ? String(value) === String(resExpected) : String(value) !== String(resExpected);
+        }
+        else
+            isTrue = !!value;
+        const compiledPart = this.compile(isTrue ? ifPart : (elsePart || ""), data);
+        return this.compileIfBlocks(content.replace(fullBlock, compiledPart), data);
+    }
+}
+export default Compiler;
+//# sourceMappingURL=Compiler.js.map

package/build/Template/Compiler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Compiler.js","sourceRoot":"","sources":["../../src/Template/Compiler.ts"],"names":[],"mappings":"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"}

package/build/Template/StreamCompiler.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @author NetFeez <netfeez.dev@gmail.com>
+ * @description Add the vhtml template stream compiler to the Vortez.
+ * @license Apache-2.0
+ */
+import { Transform, TransformCallback } from 'stream';
+import { Compiler } from './Compiler.js';
+export declare class StreamCompiler extends Transform {
+    private buffer;
+    private data;
+    constructor(data: Compiler.Data);
+    _transform(chunk: unknown, encoding: BufferEncoding, callback: TransformCallback): void;
+    _flush(callback: TransformCallback): void;
+}
+export declare namespace StreamCompiler { }
+export default StreamCompiler;

package/build/Template/StreamCompiler.js

@@ -0,0 +1,54 @@
+/**
+ * @author NetFeez <netfeez.dev@gmail.com>
+ * @description Add the vhtml template stream compiler to the Vortez.
+ * @license Apache-2.0
+ */
+import { Transform } from 'stream';
+import { Compiler } from './Compiler.js';
+export class StreamCompiler extends Transform {
+    buffer = '';
+    data;
+    constructor(data) {
+        super();
+        this.data = data;
+    }
+    _transform(chunk, encoding, callback) {
+        if (typeof chunk === 'string')
+            this.buffer += chunk;
+        else if (Buffer.isBuffer(chunk))
+            this.buffer += chunk.toString('utf-8');
+        else
+            return callback(new Error('Invalid chunk type. Expected string or Buffer.'));
+        const matches = Array.from(this.buffer.matchAll(/<(vortez-if|vortez-each)|<\/(vortez-if|vortez-each)>/g));
+        let depth = 0;
+        let lastBalancedIndex = -1;
+        if (matches.length > 0) {
+            for (const match of matches) {
+                if (match[0].startsWith('</'))
+                    depth--;
+                else
+                    depth++;
+                if (depth === 0)
+                    lastBalancedIndex = match.index + match[0].length;
+            }
+        }
+        else {
+            const lastVar = Math.max(this.buffer.lastIndexOf('}}'), this.buffer.lastIndexOf('/>'));
+            if (lastVar !== -1)
+                lastBalancedIndex = this.buffer.indexOf('>', lastVar) + 1 || lastVar + 2;
+        }
+        if (lastBalancedIndex !== -1) {
+            const completePart = this.buffer.substring(0, lastBalancedIndex);
+            this.buffer = this.buffer.substring(lastBalancedIndex);
+            this.push(Compiler.compile(completePart, this.data));
+        }
+        callback();
+    }
+    _flush(callback) {
+        if (this.buffer.trim())
+            this.push(Compiler.compile(this.buffer, this.data));
+        callback();
+    }
+}
+export default StreamCompiler;
+//# sourceMappingURL=StreamCompiler.js.map

package/build/Template/StreamCompiler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"StreamCompiler.js","sourceRoot":"","sources":["../../src/Template/StreamCompiler.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAqB,MAAM,QAAQ,CAAC;AACtD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC,MAAM,OAAO,cAAe,SAAQ,SAAS;IACjC,MAAM,GAAW,EAAE,CAAC;IACpB,IAAI,CAAgB;IAE5B,YAAY,IAAmB;QAC3B,KAAK,EAAE,CAAC;QACR,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACrB,CAAC;IAEW,UAAU,CAAC,KAAc,EAAE,QAAwB,EAAE,QAA2B;QACxF,IAAI,OAAO,KAAK,KAAK,QAAQ;YAAE,IAAI,CAAC,MAAM,IAAI,KAAK,CAAC;aAC/C,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;YAAE,IAAI,CAAC,MAAM,IAAI,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;;YACnE,OAAO,QAAQ,CAAC,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC,CAAC;QAElF,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,uDAAuD,CAAC,CAAC,CAAC;QAE1G,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,IAAI,iBAAiB,GAAG,CAAC,CAAC,CAAC;QAE3B,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACrB,KAAK,MAAM,KAAK,IAAI,OAAO,EAAE,CAAC;gBAC1B,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC;oBAAE,KAAK,EAAE,CAAC;;oBAClC,KAAK,EAAE,CAAC;gBACb,IAAI,KAAK,KAAK,CAAC;oBAAE,iBAAiB,GAAG,KAAK,CAAC,KAAM,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;YACxE,CAAC;QACL,CAAC;aAAM,CAAC;YACJ,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CACpB,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,EAC7B,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,CAAC,CAChC,CAAC;YACF,IAAI,OAAO,KAAK,CAAC,CAAC;gBAAE,iBAAiB,GAAG,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,IAAI,OAAO,GAAG,CAAC,CAAC;QACjG,CAAC;QACD,IAAI,iBAAiB,KAAK,CAAC,CAAC,EAAE,CAAC;YAC3B,MAAM,YAAY,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,EAAE,iBAAiB,CAAC,CAAC;YACjE,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,iBAAiB,CAAC,CAAC;YACvD,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,YAAY,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QACzD,CAAC;QAED,QAAQ,EAAE,CAAC;IACf,CAAC;IAEe,MAAM,CAAC,QAA2B;QAC9C,IAAI,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE;YAAE,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;QAC5E,QAAQ,EAAE,CAAC;IACf,CAAC;CACJ;AAED,eAAe,cAAc,CAAC"}

package/build/Template/Template.d.ts

@@ -0,0 +1,49 @@
+/**
+ * @author NetFeez <netfeez.dev@gmail.com>
+ * @description Add the vhtml template engine to the Vortez.
+ * @license Apache-2.0
+ */
+import { Readable } from 'stream';
+import Compiler from './Compiler.js';
+import { StreamCompiler } from './StreamCompiler.js';
+export declare class Template {
+    /**
+     * Load and compile a template.
+     * This method reads a template file from the specified path,
+     * checks if it's a valid file, and then compiles its content
+     * using the provided data object.
+     *
+     * @example `Template.load('./templates/myTemplate.html', { username: 'John Doe' });`
+     * @param path - The path to the template file.
+     * @param data - The data used to compile the template.
+     * @returns The compiled template.
+     * @throws Error if the path is not a file.
+     * @throws Error if the file does not exist.
+     */
+    static load(path: string, data: Compiler.Data): Promise<string>;
+    /**
+     * Load and compile a template using streams.
+     * Ideal for large files or serving directly to a response.
+     * @example `Template.stream('./views/index.vhtml', data).pipe(res);`
+     * @param path - The path to the template file.
+     * @param data - The data used to compile the template.
+     * @returns A Readable stream with the compiled content.
+     */
+    static stream(path: string, data: Compiler.Data): Promise<Readable>;
+    /**
+     * Compile a template string with the provided data.
+     * @param content - The template content to compile.
+     * @param data - The data used to compile the template.
+     * @returns The compiled template.
+     */
+    static compile(content: string, data: Compiler.Data): string;
+    /**
+     * Compile a template from a stream with the provided data.
+     * @param stream - The Readable stream containing the template content.
+     * @param data - The data used to compile the template.
+     * @returns A StreamCompiler instance that can be piped to a Writable stream.
+     */
+    static compileStream(stream: Readable, data: Compiler.Data): StreamCompiler;
+}
+export declare namespace Template { }
+export default Template;

package/build/Template/Template.js

@@ -0,0 +1,77 @@
+/**
+ * @author NetFeez <netfeez.dev@gmail.com>
+ * @description Add the vhtml template engine to the Vortez.
+ * @license Apache-2.0
+ */
+import { promises as FSP, createReadStream } from 'fs';
+import Utilities from '../utilities/Utilities.js';
+import Compiler from './Compiler.js';
+import { StreamCompiler } from './StreamCompiler.js';
+export class Template {
+    /**
+     * Load and compile a template.
+     * This method reads a template file from the specified path,
+     * checks if it's a valid file, and then compiles its content
+     * using the provided data object.
+     *
+     * @example `Template.load('./templates/myTemplate.html', { username: 'John Doe' });`
+     * @param path - The path to the template file.
+     * @param data - The data used to compile the template.
+     * @returns The compiled template.
+     * @throws Error if the path is not a file.
+     * @throws Error if the file does not exist.
+     */
+    static async load(path, data) {
+        path = Utilities.Path.normalize(path);
+        if (!Utilities.File.exists(path))
+            throw new Error('template file does not exist');
+        const details = await FSP.stat(path);
+        if (!details.isFile())
+            throw new Error('the path is not a template file');
+        const template = await FSP.readFile(path);
+        return Compiler.compile(template.toString('utf-8'), data);
+    }
+    /**
+     * Load and compile a template using streams.
+     * Ideal for large files or serving directly to a response.
+     * @example `Template.stream('./views/index.vhtml', data).pipe(res);`
+     * @param path - The path to the template file.
+     * @param data - The data used to compile the template.
+     * @returns A Readable stream with the compiled content.
+     */
+    static async stream(path, data) {
+        path = Utilities.Path.normalize(path);
+        if (!Utilities.File.exists(path))
+            throw new Error('template file does not exist');
+        const details = await FSP.stat(path);
+        if (!details.isFile())
+            throw new Error('the path is not a template file');
+        const readStream = createReadStream(path);
+        const compiler = new StreamCompiler(data);
+        readStream.on('error', (err) => compiler.emit('error', err));
+        return readStream.pipe(compiler);
+    }
+    /**
+     * Compile a template string with the provided data.
+     * @param content - The template content to compile.
+     * @param data - The data used to compile the template.
+     * @returns The compiled template.
+     */
+    static compile(content, data) {
+        return Compiler.compile(content, data);
+    }
+    /**
+     * Compile a template from a stream with the provided data.
+     * @param stream - The Readable stream containing the template content.
+     * @param data - The data used to compile the template.
+     * @returns A StreamCompiler instance that can be piped to a Writable stream.
+     */
+    static compileStream(stream, data) {
+        const compiler = new StreamCompiler(data);
+        stream.on('error', (err) => compiler.emit('error', err));
+        stream.pipe(compiler);
+        return compiler;
+    }
+}
+export default Template;
+//# sourceMappingURL=Template.js.map

package/build/Template/Template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Template.js","sourceRoot":"","sources":["../../src/Template/Template.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,QAAQ,IAAI,GAAG,EAAE,gBAAgB,EAAE,MAAM,IAAI,CAAC;AAGvD,OAAO,SAAS,MAAM,2BAA2B,CAAC;AAClD,OAAO,QAAQ,MAAM,eAAe,CAAC;AACrC,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAErD,MAAM,OAAO,QAAQ;IACjB;;;;;;;;;;;;OAYG;IACI,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,IAAY,EAAE,IAAmB;QACtD,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAC5C,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;QAC5E,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACrC,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;QAC1E,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC1C,OAAO,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,CAAC;IAC9D,CAAC;IACD;;;;;;;OAOG;IACI,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,IAAY,EAAE,IAAmB;QACxD,IAAI,GAAG,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;QAC5C,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,8BAA8B,CAAC,CAAC;QAClF,MAAM,OAAO,GAAG,MAAM,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAE/B,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,iCAAiC,CAAC,CAAC;QAC1E,MAAM,UAAU,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;QAC1C,MAAM,QAAQ,GAAG,IAAI,cAAc,CAAC,IAAI,CAAC,CAAC;QAE1C,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC;QAE7D,OAAO,UAAU,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IACrC,CAAC;IACJ;;;;;OAKG;IACI,MAAM,CAAC,OAAO,CAAC,OAAe,EAAE,IAAmB;QACzD,OAAO,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACxC,CAAC;IACD;;;;;OAKG;IACI,MAAM,CAAC,aAAa,CAAC,MAAgB,EAAE,IAAmB;QAChE,MAAM,QAAQ,GAAG,IAAI,cAAc,CAAC,IAAI,CAAC,CAAC;QAC1C,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,CAAC;QACzD,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QACtB,OAAO,QAAQ,CAAC;IACjB,CAAC;CACD;AAED,eAAe,QAAQ,CAAC"}

package/build/Vortez.d.ts

@@ -5,7 +5,7 @@
  * @license Apache-2.0
  */
 export { Logger } from "./logger/Logger.js";
-export { Template } from "./Template.js";
+export { Template } from "./Template/Template.js";
 export { Utilities } from "./utilities/Utilities.js";
 export * as Beta from "./beta/Beta.js";
 export { ServerError } from "./server/ServerError.js";

package/build/Vortez.js

@@ -5,7 +5,7 @@
  * @license Apache-2.0
  */
 export { Logger } from "./logger/Logger.js";
-export { Template } from "./Template.js";
+export { Template } from "./Template/Template.js";
 export { Utilities } from "./utilities/Utilities.js";
 export * as Beta from "./beta/Beta.js";
 export { ServerError } from "./server/ServerError.js";

package/build/Vortez.js.map

@@ -1 +1 @@
-{"version":3,"file":"Vortez.js","sourceRoot":"","sources":["../src/Vortez.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AACrD,OAAO,KAAK,IAAI,MAAM,gBAAgB,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAC;AACnD,OAAO,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAC;AACnD,OAAO,EAAE,MAAM,IAAI,OAAO,EAAE,MAAM,IAAI,MAAM,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"Vortez.js","sourceRoot":"","sources":["../src/Vortez.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAClD,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AACrD,OAAO,KAAK,IAAI,MAAM,gBAAgB,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AACtD,OAAO,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAC;AACnD,OAAO,EAAE,MAAM,EAAE,MAAM,2BAA2B,CAAC;AACnD,OAAO,EAAE,MAAM,IAAI,OAAO,EAAE,MAAM,IAAI,MAAM,EAAE,MAAM,oBAAoB,CAAC"}

package/build/beta/JwtManager/JwtError.d.ts

@@ -0,0 +1,8 @@
+export declare class JwtError extends Error {
+    readonly code: JwtError.Code;
+    constructor(code: JwtError.Code, message: string, options?: ErrorOptions);
+}
+export declare namespace JwtError {
+    type Code = ('TOKEN_INVALID' | 'KEY_NOT_FOUND' | 'INVALID_SIGNATURE' | 'TOKEN_EXPIRED' | 'SIGN_FAILED');
+}
+export default JwtError;

package/build/beta/JwtManager/JwtError.js

@@ -0,0 +1,10 @@
+export class JwtError extends Error {
+    code;
+    constructor(code, message, options = {}) {
+        super(message, options);
+        this.name = 'JwtError';
+        this.code = code;
+    }
+}
+export default JwtError;
+//# sourceMappingURL=JwtError.js.map

package/build/beta/JwtManager/JwtError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"JwtError.js","sourceRoot":"","sources":["../../../src/beta/JwtManager/JwtError.ts"],"names":[],"mappings":"AAAA,MAAM,OAAO,QAAS,SAAQ,KAAK;IACf,IAAI,CAAgB;IAEpC,YAAmB,IAAmB,EAAE,OAAe,EAAE,UAAwB,EAAE;QAC/E,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACxB,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACrB,CAAC;CACJ;AAYD,eAAe,QAAQ,CAAC"}

package/build/beta/JwtManager/JwtManager.d.ts

@@ -3,12 +3,15 @@ import _Algorithm from "./algorithm/Algorithm.js";
 import _JwtUtils from "./JwtUtils.js";
 import _KeyEntry from "./KeyEntry.js";
 import _Jwt from "./Jwt.js";
+import _JwtError from "./JwtError.js";
 export { KeyGenerator } from "./KeyGenerator.js";
 export { Algorithm } from "./algorithm/Algorithm.js";
 export { JwtUtils } from "./JwtUtils.js";
 export { KeyEntry as KIDEntry } from "./KeyEntry.js";
 export { Jwt } from "./Jwt.js";
+export { JwtError } from "./JwtError.js";
 export declare class JwtManager {
+    static readonly DEFAULT_KID = "vortez-default-kid";
     protected KIDMap: JwtManager.KIDMap;
     protected defaultEntry: JwtManager.KeyEntry;
     constructor(entry: JwtManager.KeyOption, ...entries: JwtManager.KeyOption[]);
@@ -48,6 +51,7 @@ export declare namespace JwtManager {
     export import JwtUtils = _JwtUtils;
     export import KeyEntry = _KeyEntry;
     export import Jwt = _Jwt;
+    export import JwtError = _JwtError;
     type KeyOption = KeyEntry | KeyEntry.KeyEntryOptions;
     interface KIDMap {
         [kid: string]: KeyEntry;