lite-template 0.0.1

package/.gitattributes

@@ -0,0 +1,2 @@
+# Auto detect text files and perform LF normalization
+* text=auto

package/.github/workflows/publish.yml

@@ -0,0 +1,32 @@
+name: Publish to NPM
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '22'
+          registry-url: 'https://registry.npmjs.org'
+          
+      - name: Install dependencies
+        run: npm install
+        
+      - name: Build package
+        run: npm run build
+        
+      - name: Publish to npm
+        run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present docmd.io
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,116 @@
+# lite-template
+
+**High-Performance, Async-Safe JavaScript Template Engine.**
+
+`lite-template` is a modern, ultra-lightweight template engine designed for the needs of today's asynchronous web applications. It serves as a drop-in replacement for the aging, sync-heavy legacy of **EJS**, while introducing native, first-class support for `async/await` throughout the entire template lifecycle.
+
+## Technical Specifications
+
+- **Runtime**: Node.js (v18+), Browser (Modern), Cloudflare Workers.
+- **Language**: Core engine logic written in TypeScript.
+- **Compiler**: Direct-to-string AsyncFunction compilation.
+- **Distribution**: Native ESM (CommonJS not supported).
+
+## The Architecture: Async-First Compilation
+
+Most legacy engines (like `EJS`) were built in the pre-Promise era of Node.js. They execute template logic synchronously, which can block the event loop in high-throughput environments or when templates require database/API interaction.
+
+`lite-tpl` compiles logic directly into native, V8-optimized **`AsyncFunction`** objects. This enables seamless, non-blocking template execution that leverages existing JavaScript primitives for maximum efficiency.
+
+### Technical Limitations (Design Philosophy)
+
+To prioritize performance and maintain its minimalist footprint (<10KB), `lite-template` purposefully omits several non-core EJS features:
+
+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(...) %>`).
+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.
+
+
+*   **Async Native Engine**: Supports `await` natively within any `<% ... %>` or `<%= ... %>` block without messy workarounds.
+*   **Optimal Performance**: Compiles template strings directly into optimized JavaScript function strings, skipping the AST-processing overhead of heavier engines.
+*   **Predictable Scoping**: Leverages the JavaScript `with` scope for safe, predictable, and performant variable resolution.
+*   **Micro Footprint**: Under 10KB. Eliminates the hundreds of cascading dependencies common in larger engines.
+*   **Modern Compatibility**: Built for standard **EJS syntax** but engineered for the modern ES Module ecosystem.
+
+## Installation
+
+```bash
+npm install lite-template
+```
+
+## Comparisons
+
+| Feature | EJS | lite-template |
+| :--- | :--- | :--- |
+| **Logic** | Sync-First | **Async-Native** |
+| **Parsing** | Bulky AST | **Direct-to-Function** |
+| **Weight (approx)** | ~50KB | **<10KB** |
+| **Dependencies** | Multiple (jake, async, etc.) | **Zero** |
+
+## Quick Start
+
+### Basic Rendering
+
+```javascript
+import { render } from 'lite-tpl';
+
+const template = `<h2>Hello, <%= name %></h2>`;
+const html = await render(template, { name: "System" });
+```
+
+### Advanced Loops and Logic
+
+```javascript
+const template = `
+  <div class="user-list">
+    <% users.forEach(user => { %>
+      <div class="user-card"><%= user.name %></div>
+    <% }); %>
+  </div>
+`;
+
+const html = await render(template, {
+  users: [{ name: "Alice" }, { name: "Bob" }]
+});
+```
+
+### First-Class Async/Await
+
+```javascript
+const template = `
+  <div class="profile">
+    <h2>User Details</h2>
+    <p>Age: <%= await getUserAge(id) %></p>
+  </div>
+`;
+
+const html = await render(template, {
+  id: 101,
+  getUserAge: async (id) => `Verified Age for User #${id}`
+});
+```
+
+## API Reference
+
+### `render(template, data)`
+
+**Arguments:**
+- `template` (string): The raw template string to compile and evaluate.
+- `data` (object): The variable context to be accessible within the template.
+
+**Returns:**
+- `Promise<string>`: The final rendered output.
+
+### `compile(template)`
+
+**Arguments:**
+- `template` (string): The raw template string.
+
+**Returns:**
+- `(data) => Promise<string>`: A reusable, high-performance async render function.
+
+## License
+
+MIT - Developed under the docmd ecosystem by [Ghazi](https://mgks.dev).

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Compiles an EJS-style template string into an async function.
+ * Supports: <% js %>, <%= escaped %>, <%- unescaped %>
+ */
+export declare function compile(template: any): (data: any) => any;
+/**
+ * Convenience method to render template directly.
+ */
+export declare function render(template: any, data?: {}, options?: {}): Promise<any>;
+declare const _default: {
+    render: typeof render;
+    compile: typeof compile;
+};
+export default _default;

package/dist/index.js

@@ -0,0 +1,72 @@
+const AsyncFunction = Object.getPrototypeOf(async function () { }).constructor;
+function escapeHtml(str) {
+    return String(str)
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#039;');
+}
+/**
+ * Compiles an EJS-style template string into an async function.
+ * Supports: <% js %>, <%= escaped %>, <%- unescaped %>
+ */
+export function compile(template) {
+    let code = "";
+    const regex = /<%(=|-|_|#)?([\s\S]+?)([-_])?%>/g;
+    let cursor = 0;
+    let match;
+    while ((match = regex.exec(template)) !== null) {
+        const textBefore = template.slice(cursor, match.index);
+        if (textBefore) {
+            code += `__out += \`${textBefore.replace(/\\/g, "\\\\").replace(/`/g, "\\`").replace(/\$/g, "\\$")}\`;\n`;
+        }
+        const type = match[1];
+        let script = match[2].trim();
+        if (type === '#') {
+            // It's a comment, completely ignore it.
+        }
+        else if (type === '=') {
+            // Escape HTML output
+            code += `__out += escapeHtml(typeof (${script}) !== 'undefined' ? (${script}) : '');\n`;
+        }
+        else if (type === '-') {
+            // Raw HTML output
+            code += `__out += String(typeof (${script}) !== 'undefined' ? (${script}) : '');\n`;
+        }
+        else {
+            // Literal JS code execution
+            code += `${script}\n`;
+        }
+        cursor = match.index + match[0].length;
+    }
+    const textAfter = template.slice(cursor);
+    if (textAfter) {
+        code += `__out += \`${textAfter.replace(/\\/g, "\\\\").replace(/`/g, "\\`").replace(/\$/g, "\\$")}\`;\n`;
+    }
+    const wrappedCode = `let __out = '';\nwith(__data || {}) {\n${code}\nreturn __out;\n}`;
+    let fn;
+    try {
+        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'));
+        throw e;
+    }
+    return function (data) {
+        return fn(data, escapeHtml);
+    };
+}
+/**
+ * Convenience method to render template directly.
+ */
+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 });
+}
+export default {
+    render,
+    compile
+};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "lite-template",
+  "version": "0.0.1",
+  "description": "Ultra lightweight, zero-dependency async template engine compatible with basic EJS syntax.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsc"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "keywords": [
+    "ejs",
+    "template",
+    "engine",
+    "micro",
+    "lite",
+    "async",
+    "minimal",
+    "lightweight",
+    "typescript",
+    "javascript",
+    "nodejs",
+    "docmd"
+  ],
+  "author": {
+    "name": "Ghazi",
+    "url": "https://mgks.dev"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/docmd-io/docmd.git",
+    "directory": "lite-template"
+  },
+  "bugs": {
+    "url": "https://github.com/docmd-io/docmd/issues"
+  },
+  "homepage": "https://docmd.io",
+  "funding": "https://github.com/sponsors/mgks",
+  "license": "MIT"
+}

package/src/index.ts

@@ -0,0 +1,79 @@
+const AsyncFunction = Object.getPrototypeOf(async function(){}).constructor;
+
+function escapeHtml(str) {
+  return String(str)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#039;');
+}
+
+/**
+ * Compiles an EJS-style template string into an async function.
+ * Supports: <% js %>, <%= escaped %>, <%- unescaped %>
+ */
+export function compile(template) {
+  let code = "";
+  const regex = /<%(=|-|_|#)?([\s\S]+?)([-_])?%>/g;
+  let cursor = 0;
+  let match;
+
+  while ((match = regex.exec(template)) !== null) {
+    const textBefore = template.slice(cursor, match.index);
+    if (textBefore) {
+      code += `__out += \`${textBefore.replace(/\\/g, "\\\\").replace(/`/g, "\\`").replace(/\$/g, "\\$")}\`;\n`;
+    }
+
+    const type = match[1];
+    let script = match[2].trim();
+
+    if (type === '#') {
+      // It's a comment, completely ignore it.
+    } else if (type === '=') {
+      // Escape HTML output
+      code += `__out += escapeHtml(typeof (${script}) !== 'undefined' ? (${script}) : '');\n`;
+    } else if (type === '-') {
+      // Raw HTML output
+      code += `__out += String(typeof (${script}) !== 'undefined' ? (${script}) : '');\n`;
+    } else {
+      // Literal JS code execution
+      code += `${script}\n`;
+    }
+    cursor = match.index + match[0].length;
+  }
+
+  const textAfter = template.slice(cursor);
+  if (textAfter) {
+    code += `__out += \`${textAfter.replace(/\\/g, "\\\\").replace(/`/g, "\\`").replace(/\$/g, "\\$")}\`;\n`;
+  }
+
+  const wrappedCode = `let __out = '';\nwith(__data || {}) {\n${code}\nreturn __out;\n}`;
+
+  let fn;
+  try {
+    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'));
+    throw e;
+  }
+
+  return function(data) {
+    return fn(data, escapeHtml);
+  };
+}
+
+/**
+ * Convenience method to render template directly.
+ */
+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 });
+}
+
+export default {
+  render,
+  compile
+};

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "node16",
+    "strict": false,
+    "declaration": true,
+    "outDir": "dist",
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "skipLibCheck": true
+  },
+  "include": ["src/**/*"]
+}