miki-template 2.0.0 → 2.2.2

package/docs/integrations/tsed.md

@@ -0,0 +1,81 @@
+# TSDX / TSed (Ts.ED)
+
+Use miki-template with Ts.ED (TSed) by wiring it into the underlying Express or Koa adapter.
+
+## Setup
+
+Ts.ED can run on Express or Koa. When using the Express adapter, obtain the raw Express app and call `setupExpress()`.
+
+=== "TypeScript"
+
+    ```typescript
+    // server.ts
+    import { ServerLoader } from '@tsed/di';
+    import * as miki from 'miki-template';
+
+    async function bootstrap() {
+      const server = await ServerLoader.bootstrap();
+      // server.rawApp is the underlying Express/Koa instance depending on adapter
+      miki.setupExpress(server.rawApp, {
+        extension: 'html',
+        views: './views'
+      });
+      await server.listen();
+    }
+
+    bootstrap();
+    ```
+
+=== "CommonJS"
+
+    ```javascript
+    const { ServerLoader } = require('@tsed/di');
+    const miki = require('miki-template');
+
+    async function bootstrap() {
+      const server = await ServerLoader.bootstrap();
+      miki.setupExpress(server.rawApp, {
+        extension: 'html',
+        views: './views'
+      });
+      await server.listen();
+    }
+
+    bootstrap();
+    ```
+
+## Using in Controllers
+
+Once wired, use `res.render()` in your Ts.ED controllers:
+
+```typescript
+import { Controller, Get, Req, Res } from '@tsed/common';
+import { Request, Response } from 'express';
+
+@Controller('/')
+export class AppController {
+  @Get('/')
+  renderHome(@Req() req: Request, @Res() res: Response) {
+    res.render('home', { user: req.user });
+  }
+
+  @Get('/partials/:name')
+  renderPartial(@Req() req: Request, @Res() res: Response) {
+    res.render(`home#${req.params.name}`, { user: req.user });
+  }
+}
+```
+
+## Partial Rendering
+
+```typescript
+@Get('/cards/:id')
+renderCard(@Req() req: Request, @Res() res: Response) {
+  res.render(`home#card`, { user: req.user });
+}
+```
+
+## Next Steps
+
+- [Integrations Overview](../)
+- [API Reference: setupExpress](../api/setup-express)

package/docs/javascripts/extra.js

@@ -0,0 +1,174 @@
+document$.subscribe(function () {
+  console.log("miki-template docs initialized");
+
+  const navbar = document.querySelector(".md-header");
+  if (navbar) {
+    let lastScroll = 0;
+    const scrollThreshold = 50;
+
+    window.addEventListener("scroll", function () {
+      const currentScroll = window.pageYOffset;
+
+      if (currentScroll <= 0) {
+        navbar.style.boxShadow = "0 2px 8px var(--md-shadow-color)";
+        return;
+      }
+
+      if (currentScroll > lastScroll && currentScroll > scrollThreshold) {
+        navbar.style.transform = "translateY(-100%)";
+        navbar.style.transition = "transform 0.3s ease";
+      } else {
+        navbar.style.transform = "translateY(0)";
+        navbar.style.transition = "transform 0.3s ease";
+      }
+
+      lastScroll = currentScroll;
+    });
+  }
+
+  document.querySelectorAll(".md-clipboard").forEach(function (button) {
+    button.addEventListener("click", async function () {
+      const code = this.closest(".highlight").querySelector("code").innerText;
+
+      try {
+        await navigator.clipboard.writeText(code);
+        const originalHTML = this.innerHTML;
+        this.innerHTML = '<span class="md-icon">&#10003;</span> Copied!';
+        this.style.color = "var(--md-accent-fg-color)";
+        this.style.opacity = "1";
+
+        setTimeout(function () {
+          button.innerHTML = originalHTML;
+          button.style.color = "";
+          button.style.opacity = "";
+        }, 2000);
+      } catch (err) {
+        console.error("Failed to copy: ", err);
+      }
+    });
+  });
+
+  document.querySelectorAll(".md-typeset a[href^='#']").forEach(function (anchor) {
+    anchor.addEventListener("click", function (e) {
+      const targetId = this.getAttribute("href");
+      if (targetId === "#") return;
+
+      const target = document.querySelector(targetId);
+      if (target) {
+        e.preventDefault();
+        const headerOffset = 80;
+        const elementPosition = target.getBoundingClientRect().top;
+        const offsetPosition = elementPosition + window.pageYOffset - headerOffset;
+
+        window.scrollTo({
+          top: offsetPosition,
+          behavior: "smooth",
+        });
+
+        history.replaceState(null, null, targetId);
+      }
+    });
+  });
+
+  document.querySelectorAll(".md-typeset .task-list-item input[type='checkbox']").forEach(function (checkbox) {
+    checkbox.addEventListener("change", function () {
+      const label = this.closest(".task-list-item");
+      if (this.checked) {
+        label.style.opacity = "0.6";
+        label.style.textDecoration = "line-through";
+      } else {
+        label.style.opacity = "1";
+        label.style.textDecoration = "none";
+      }
+    });
+  });
+
+  document.querySelectorAll(".md-tabs__link").forEach(function (tab) {
+    tab.addEventListener("click", function () {
+      document.querySelectorAll(".md-tabs__link").forEach(function (t) {
+        t.style.transform = "scale(1)";
+      });
+      this.style.transform = "scale(1.05)";
+      setTimeout(function () {
+        tab.style.transform = "scale(1)";
+      }, 200);
+    });
+  });
+
+  document.querySelectorAll(".md-typeset .tabbed-set > label").forEach(function (tabLabel) {
+    tabLabel.addEventListener("click", function () {
+      this.style.transform = "scale(0.98)";
+      setTimeout(function () {
+        tabLabel.style.transform = "scale(1)";
+      }, 100);
+    });
+  });
+
+  const searchInput = document.querySelector(".md-search__input");
+  if (searchInput) {
+    searchInput.addEventListener("focus", function () {
+      this.parentElement.style.boxShadow = "0 0 0 3px var(--md-accent-fg-color), 0 4px 12px var(--md-shadow-color)";
+      this.parentElement.style.transition = "box-shadow 0.2s ease";
+    });
+
+    searchInput.addEventListener("blur", function () {
+      this.parentElement.style.boxShadow = "";
+    });
+  }
+
+  document.querySelectorAll(".md-typeset .admonition").forEach(function (admonition) {
+    admonition.addEventListener("mouseenter", function () {
+      this.style.transform = "translateY(-2px)";
+      this.style.transition = "transform 0.2s ease";
+    });
+
+    admonition.addEventListener("mouseleave", function () {
+      this.style.transform = "translateY(0)";
+    });
+  });
+
+  document.querySelectorAll(".md-typeset .md-button").forEach(function (button) {
+    button.addEventListener("mouseenter", function () {
+      this.style.transform = "translateY(-2px)";
+    });
+
+    button.addEventListener("mouseleave", function () {
+      this.style.transform = "translateY(0)";
+    });
+  });
+
+  document.querySelectorAll(".md-content__inner table:not([class]) tbody tr").forEach(function (row) {
+    row.addEventListener("mouseenter", function () {
+      this.style.transition = "background-color 0.2s ease";
+    });
+  });
+
+  const observerOptions = {
+    root: null,
+    rootMargin: "0px",
+    threshold: 0.1,
+  };
+
+  const observer = new IntersectionObserver(function (entries) {
+    entries.forEach(function (entry) {
+      if (entry.isIntersecting) {
+        entry.target.style.opacity = "1";
+        entry.target.style.transform = "translateY(0)";
+      }
+    });
+  }, observerOptions);
+
+  document.querySelectorAll(".md-typeset h2, .md-typeset h3, .md-typeset .admonition").forEach(function (el) {
+    el.style.opacity = "0";
+    el.style.transform = "translateY(10px)";
+    el.style.transition = "opacity 0.5s ease, transform 0.5s ease";
+    observer.observe(el);
+  });
+
+  setTimeout(function () {
+    document.querySelectorAll(".md-typeset h2, .md-typeset h3, .md-typeset .admonition").forEach(function (el) {
+      el.style.opacity = "1";
+      el.style.transform = "translateY(0)";
+    });
+  }, 100);
+});

package/docs/performance.md

@@ -0,0 +1,37 @@
+# Performance
+
+miki-template is built for real-world apps. Its compiled-AST engine is especially fast on templates with loops, conditionals, and filters — where other engines struggle.
+
+## Benchmark Results
+
+Renders per second (higher is better):
+
+| Template | miki-template | pug | handlebars | ejs |
+|----------|--------------|-----|------------|-----|
+| Small | ~115k rps | 1.7M rps | 417k rps | 182k rps |
+| Medium | ~454k rps | 625k rps | 48k rps | 29k rps |
+| Large | **~476k rps** | 3.1k rps | 661 rps | 290 rps |
+
+## Key Takeaways
+
+- On **small** templates, miki-template has overhead from the compiled AST approach.
+- On **medium** templates, miki-template is competitive with pug.
+- On **large/realistic** templates (the ones that matter in production), miki-template **dominates by ~150×**.
+
+## Why miki-template Wins on Real Templates
+
+- **Compiled AST**: Templates are compiled once and reused, avoiding repeated parsing.
+- **No runtime interpretation**: No string concatenation or function reconstruction per render.
+- **Optimized loops and filters**: for-loops and filters are implemented as efficient node traversals.
+- **Cache-friendly**: Compiled templates are cached by default.
+
+## Running Benchmarks
+
+```bash
+npm run bench
+```
+
+## Next Steps
+
+- [Getting Started](../guide/getting-started)
+- [API Reference](../api/)