lite-template 0.1.0 → 0.1.1

package/README.md

@@ -23,7 +23,7 @@ To prioritize performance and maintain its minimalist footprint (<10KB), `lite-t
 
 1.  **Strictly Logic-Driven**: Unlike EJS, it does not include a complex built-in caching layer. Reusable templates should be pre-compiled using `compile()` at the application level.
 2.  **Explicit Scope**: Uses the `with` block for performance. Variables must be defined within the provided `data` object to be accessible; it does not automatically pull from global scope.
-3.  **No Layout System**: Does not include a proprietary EJS `<%- layout() %>` system. Layout/Include handling is left to the developer via standard async calls (e.g., `<%- await include(...) %>`).
+3.  **Include System**: A native `include()` function works out-of-the-box (just like EJS) when `options.filename` is provided to `render()`, managing recursive resolution automatically. Does not implement `<%- layout() %>` systems.
 4.  **No Middleware Integration**: This is a pure string-to-HTML engine—no native Express.js view-engine integration is included out of the box.
 5.  **ESM Only**: Built exclusively for modern ESM toolchains.
 
@@ -76,6 +76,22 @@ const html = await render(template, {
 });
 ```
 
+### Native Built-in Includes
+
+When you pass `filename` in the options, `lite-template` automatically exposes a built-in cross-file `include()` resolver.
+
+```javascript
+// page.ejs
+// <h1>My Page</h1>
+// <%- await include('footer', { text: "Copyright" }) %>
+
+const html = await render(
+  '<%- await include("footer") %>', 
+  { globalVar: true }, 
+  { filename: '/path/to/page.ejs' }
+);
+```
+
 ### First-Class Async/Await
 
 ```javascript

package/dist/index.d.ts

@@ -1,12 +1,38 @@
 /**
  * Compiles an EJS-style template string into an async function.
- * Supports: <% js %>, <%= escaped %>, <%- unescaped %>
+ * Supports: <% js %>, <%= escaped %>, <%- unescaped %>, <%# comment %>
  */
 export declare function compile(template: any): (data: any) => any;
 /**
- * Convenience method to render template directly.
+ * Renders an EJS-style template string with data.
+ *
+ * Provides a built-in `include()` function when `options.filename` is set,
+ * enabling file-based template inclusion just like EJS.
+ *
+ * If the caller supplies their own `include` in `data`, it takes precedence
+ * over the built-in version (allowing frameworks like docmd to extend behavior).
+ *
+ * @param template - The EJS template string to render
+ * @param data - Data object accessible inside the template via `with(data)`
+ * @param options - Options: `filename` (path of this template, enables include resolution)
+ * @returns The rendered string
+ *
+ * @example
+ * ```js
+ * import tpl from 'lite-template';
+ *
+ * // Simple render
+ * const html = await tpl.render('<h1><%= title %></h1>', { title: 'Hello' });
+ *
+ * // With file-based includes
+ * const html = await tpl.render(
+ *   '<%- include("header") %><p>Body</p>',
+ *   { siteName: 'My Site' },
+ *   { filename: '/path/to/current/template.ejs' }
+ * );
+ * ```
  */
-export declare function render(template: any, data?: {}, options?: {}): Promise<any>;
+export declare function render(template: any, data?: {}, options?: any): Promise<any>;
 declare const _default: {
     render: typeof render;
     compile: typeof compile;

package/dist/index.js

@@ -9,7 +9,7 @@ function escapeHtml(str) {
 }
 /**
  * Compiles an EJS-style template string into an async function.
- * Supports: <% js %>, <%= escaped %>, <%- unescaped %>
+ * Supports: <% js %>, <%= escaped %>, <%- unescaped %>, <%# comment %>
  */
 export function compile(template) {
     let code = "";
@@ -50,7 +50,7 @@ export function compile(template) {
         fn = new AsyncFunction("__data", "escapeHtml", wrappedCode);
     }
     catch (e) {
-        console.error("COMPILATION ERROR CODE:\n" + wrappedCode.split('\\n').map((l, i) => `${i + 1}: ${l}`).join('\\n'));
+        console.error("COMPILATION ERROR CODE:\n" + wrappedCode.split('\n').map((l, i) => `${i + 1}: ${l}`).join('\n'));
         throw e;
     }
     return function (data) {
@@ -58,13 +58,94 @@ export function compile(template) {
     };
 }
 /**
- * Convenience method to render template directly.
+ * Built-in include function for file-based template inclusion.
+ * Reads a file relative to the current template's location, compiles and renders it.
+ *
+ * This provides the core EJS-compatible `include()` behavior:
+ * - Resolves paths relative to the current template's `filename`
+ * - Auto-appends `.ejs` extension if missing
+ * - Recursively renders included templates
+ * - Merges parent data with include-specific data
+ *
+ * Consumers can override this by passing their own `include` function in `data`.
+ *
+ * @param parentFilename - Absolute path of the template doing the including
+ * @param parentData - Data context from the parent template
+ * @param options - Render options (passed through to recursive render calls)
+ */
+async function builtinInclude(parentFilename, parentData, options, name, includeData = {}) {
+    const extName = !name.endsWith('.ejs') ? name + '.ejs' : name;
+    // Custom includer support (e.g. for virtual file systems or memory templates)
+    if (options.includer) {
+        const res = options.includer(extName, parentFilename);
+        if (res && res.template) {
+            const mergedData = { ...parentData, ...includeData };
+            delete mergedData.include;
+            return await render(res.template, mergedData, { ...options, filename: res.filename || parentFilename });
+        }
+    }
+    // Lazy-load Node.js modules (keeps the package usable in non-Node environments at compile time)
+    const { promises: fsPromises } = await import('node:fs');
+    const path = await import('node:path');
+    let targetPath;
+    if (parentFilename) {
+        targetPath = path.resolve(path.dirname(parentFilename), extName);
+    }
+    else {
+        targetPath = path.resolve(extName);
+    }
+    let content = await fsPromises.readFile(targetPath, 'utf8');
+    // Custom preprocessor hook before rendering (useful for stripping syntax outside of the engine's concern)
+    if (options.preprocessor) {
+        content = options.preprocessor(content, targetPath);
+    }
+    const mergedData = { ...parentData, ...includeData };
+    // Remove the parent's include fn — render() will create a new one scoped to the new file
+    delete mergedData.include;
+    return await render(content, mergedData, { ...options, filename: targetPath });
+}
+/**
+ * Renders an EJS-style template string with data.
+ *
+ * Provides a built-in `include()` function when `options.filename` is set,
+ * enabling file-based template inclusion just like EJS.
+ *
+ * If the caller supplies their own `include` in `data`, it takes precedence
+ * over the built-in version (allowing frameworks like docmd to extend behavior).
+ *
+ * @param template - The EJS template string to render
+ * @param data - Data object accessible inside the template via `with(data)`
+ * @param options - Options: `filename` (path of this template, enables include resolution)
+ * @returns The rendered string
+ *
+ * @example
+ * ```js
+ * import tpl from 'lite-template';
+ *
+ * // Simple render
+ * const html = await tpl.render('<h1><%= title %></h1>', { title: 'Hello' });
+ *
+ * // With file-based includes
+ * const html = await tpl.render(
+ *   '<%- include("header") %><p>Body</p>',
+ *   { siteName: 'My Site' },
+ *   { filename: '/path/to/current/template.ejs' }
+ * );
+ * ```
  */
 export async function render(template, data = {}, options = {}) {
-    // Allow caching if 'filename' or 'id' is passed usually, but here we just compile and run.
     const fn = compile(template);
-    // Add locals pseudo-property common in EJS contexts
-    return await fn({ locals: data, ...data });
+    const filename = options.filename || data.__filename || null;
+    const enriched = {
+        locals: data,
+        ...data,
+        __filename: filename
+    };
+    // Provide built-in include() if filename OR a virtual includer is set AND the caller hasn't provided their own
+    if ((filename || options.includer) && !enriched.include) {
+        enriched.include = (name, includeData = {}) => builtinInclude(filename, enriched, options, name, includeData);
+    }
+    return await fn(enriched);
 }
 export default {
     render,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lite-template",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Ultra lightweight, zero-dependency async template engine compatible with basic EJS syntax.",
   "type": "module",
   "files": [
@@ -12,6 +12,7 @@
     "build": "tsc"
   },
   "devDependencies": {
+    "@types/node": "^25.5.2",
     "typescript": "^5.0.0"
   },
   "keywords": [