miki-template 2.0.0 → 2.0.1

package/docs/integrations.md

@@ -0,0 +1,214 @@
+## Integrations — miki-template
+
+This document shows concise examples for integrating `miki-template` with popular Node.js and Bun web frameworks. Use the synchronous `render()` API for CPU-bound sync templates, and `asyncRender()` when using async helpers.
+
+Notes
+- For CommonJS: `const miki = require('miki-template');`
+- For ESM / Bun: `import miki from 'miki-template';` or `import * as miki from 'miki-template';`
+- When rendering files, pass `options.views` or set framework view roots so the engine can locate templates.
+
+Setup (install)
+
+```bash
+# npm
+npm install miki-template
+
+# bun
+bun add miki-template
+```
+
+Express (recommended: use `setupExpress`)
+
+CommonJS
+
+```js
+const express = require('express');
+const miki = require('miki-template');
+
+const app = express();
+
+// One-line setup: wires engine, sets views, and patches res.render to support `view#partial`
+miki.setupExpress(app, { extension: 'html', views: './views' });
+
+app.get('/', (req, res) => {
+  res.render('index', { user: req.user });
+});
+
+app.get('/partial/:name', (req, res) => {
+  // Renders only the named partial inside the template
+  res.render(`index#${req.params.name}`, { user: req.user });
+});
+
+app.listen(3000);
+```
+
+ESM / Bun (similar)
+
+```js
+import express from 'express';
+import miki from 'miki-template';
+
+const app = express();
+miki.setupExpress(app, { extension: 'html', views: './views' });
+app.listen(3000);
+```
+
+Koa
+
+```js
+// CommonJS
+const Koa = require('koa');
+const path = require('path');
+const miki = require('miki-template');
+
+const app = new Koa();
+
+// Simple render helper attached to context
+app.context.render = async function (view, locals = {}) {
+  const html = await miki.asyncRender(view, locals, { views: path.resolve('./views') });
+  this.type = 'text/html';
+  this.body = html;
+};
+
+app.use(async (ctx) => {
+  await ctx.render('index', { user: ctx.state.user });
+});
+
+app.listen(3000);
+```
+
+Fastify
+
+```js
+const Fastify = require('fastify');
+const path = require('path');
+const miki = require('miki-template');
+
+const app = Fastify();
+
+app.get('/', async (request, reply) => {
+  const html = await miki.asyncRender('index', { user: request.user }, { views: path.resolve('./views') });
+  reply.type('text/html').send(html);
+});
+
+app.listen(3000);
+```
+
+NestJS (Express under the hood)
+
+```ts
+// In main.ts
+import { NestFactory } from '@nestjs/core';
+import { AppModule } from './app.module';
+import * as miki from 'miki-template';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  // Use the underlying Express instance
+  const expressApp = app.getHttpAdapter().getInstance();
+  miki.setupExpress(expressApp, { extension: 'html', views: './views' });
+  await app.listen(3000);
+}
+bootstrap();
+```
+
+Ts.ED
+
+```ts
+// In server bootstrap
+import { ServerLoader } from '@tsed/di';
+import * as miki from 'miki-template';
+
+// Ts.ED also runs on Express/Koa — obtain the underlying app
+// and call miki.setupExpress(...) when using the Express adapter.
+
+// Example when using Express adapter:
+// miki.setupExpress(server.rawApp, { extension: 'html', views: './views' });
+```
+
+Elysia (Bun-friendly)
+
+```js
+// ESM / Bun example
+import { Elysia } from 'elysia';
+import * as miki from 'miki-template';
+import path from 'path';
+
+const app = new Elysia();
+
+app.get('/', async () => {
+  const html = await miki.asyncRender('index', { }, { views: path.resolve('./views') });
+  return new Response(html, { headers: { 'Content-Type': 'text/html' } });
+});
+
+app.listen(3000);
+```
+
+Hono (Edge + Bun)
+
+```js
+import { Hono } from 'hono';
+import * as miki from 'miki-template';
+import path from 'path';
+
+const app = new Hono();
+
+app.get('/', async (c) => {
+  const html = await miki.asyncRender('index', { }, { views: path.resolve('./views') });
+  return c.html(html);
+});
+
+app.listen({ port: 3000 });
+```
+
+Nifra / other minimal frameworks
+
+```js
+// Generic handler pattern — works in almost any framework
+// (Nifra users can adapt the response API)
+const miki = require('miki-template');
+const path = require('path');
+
+async function handler(req, res) {
+  const html = await miki.asyncRender('index', { }, { views: path.resolve('./views') });
+  res.setHeader('Content-Type', 'text/html');
+  res.end(html);
+}
+```
+
+Bun-specific notes
+- Bun is ESM-first; import `miki-template` using `import miki from 'miki-template'`.
+- Use `bun add miki-template` to install.
+- When using Bun's native servers, call `miki.asyncRender(...)` and return/send the Response object accordingly.
+
+Tips and best practices
+- Prefer `miki.setupExpress()` for Express-based apps — it wires partial rendering and view expansion.
+- For non-Express frameworks, call `miki.render()` (sync) or `miki.asyncRender()` (async) and set `options.views` to your views root (or pass absolute file paths resolved with your framework).
+- To support Django-style app templates (e.g. `packages/*/templates/...`), call `miki.setAppTemplateDirNames(['templates','app_templates'])` early in your app startup if you use a custom folder name.
+
+Engine usage & partial rendering
+
+Use the engine APIs directly when you don't want framework-specific wiring or when you need fine-grained control over `views` roots.
+
+```js
+const miki = require('miki-template');
+const path = require('path');
+
+// Sync render of a named partial inside a template file
+const html = miki.render('home#card', { user: 'Alice', title: 'Card' }, { views: path.resolve('./views') });
+
+// Async render when templates use async helpers
+const htmlAsync = await miki.asyncRender('home#card', { user: 'Bob' }, { views: path.resolve('./views') });
+
+// If your project arranges templates under custom folder names, configure
+// what constitutes an "app template" directory before rendering:
+miki.setAppTemplateDirNames(['templates', 'app_templates']);
+
+// To locate a template file programmatically without rendering, use the
+// exported finder helper:
+const found = miki.findTemplateInViews('home', [path.resolve('./views')]);
+if (found) console.log('Resolved to', found);
+```
+
+Further reading
+- See the main API docs for `setupExpress`, `render`, and `asyncRender` in `docs/api.md`.

package/live-test/integrations/elysia-example.js

@@ -0,0 +1,16 @@
+import { Elysia } from 'elysia';
+import path from 'path';
+import miki from '../../src/esm.mjs';
+
+const app = new Elysia();
+
+app.get('/', async () => {
+  const html = await miki.asyncRender('home', {}, { views: path.resolve('./live-test/views') });
+  return new Response(html, { headers: { 'Content-Type': 'text/html' } });
+});
+
+export async function start(port = 3004) {
+  return app.listen({ port });
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) start().then(() => console.log('Elysia example listening on 3004'));

package/live-test/integrations/express-example.js

@@ -0,0 +1,24 @@
+const express = require('express');
+const path = require('path');
+const miki = require('../../');
+
+const app = express();
+miki.setupExpress(app, { extension: 'html', views: path.resolve(__dirname, '..', 'views') });
+
+app.get('/', (req, res) => res.render('home', { user: 'ExpressUser', title: 'ExpressCard' }));
+app.get('/partial', (req, res) => res.render('home#card', { user: 'ExpressUser', title: 'ExpressCard' }));
+
+function start(port = 3000, host = '127.0.0.1') {
+	return new Promise((resolve, reject) => {
+		try {
+			const srv = app.listen(port, host, () => {
+				console.log('Express example listening on', port);
+				resolve(srv);
+			});
+		} catch (err) { reject(err); }
+	});
+}
+
+if (require.main === module) start().catch(err => { console.error(err); process.exit(1); });
+
+module.exports = { app, start };

package/live-test/integrations/fastify-example.js

@@ -0,0 +1,20 @@
+const Fastify = require('fastify');
+const path = require('path');
+const miki = require('../../');
+
+const app = Fastify();
+
+app.get('/', async (request, reply) => {
+  const html = await miki.asyncRender('home', { user: 'FastifyUser', title: 'FastifyCard' }, { views: path.resolve(__dirname, '..', 'views') });
+  reply.type('text/html').send(html);
+});
+
+function start(port = 3002, host = '127.0.0.1') {
+  return app.listen({ port, host });
+}
+
+if (require.main === module) {
+  start().then(() => console.log('Fastify example listening on 3002')).catch(err => { console.error('Fastify failed to start', err); process.exit(1); });
+}
+
+module.exports = { app, start };

package/live-test/integrations/hono-example.js

@@ -0,0 +1,16 @@
+import { Hono } from 'hono';
+import miki from '../../src/esm.mjs';
+import path from 'path';
+
+const app = new Hono();
+
+app.get('/', async (c) => {
+  const html = await miki.asyncRender('home', {}, { views: path.resolve('./live-test/views') });
+  return c.html(html);
+});
+
+export async function start(port = 3005) {
+  return app.listen({ port });
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) start().then(() => console.log('Hono example listening on 3005'));

package/live-test/integrations/koa-example.js

@@ -0,0 +1,30 @@
+const Koa = require('koa');
+const path = require('path');
+const miki = require('../../');
+
+const app = new Koa();
+
+app.context.render = async function (view, locals = {}) {
+  const html = await miki.asyncRender(view, locals, { views: path.resolve(__dirname, '..', 'views') });
+  this.type = 'text/html';
+  this.body = html;
+};
+
+app.use(async (ctx) => {
+  await ctx.render('home', { user: 'KoaUser', title: 'KoaCard' });
+});
+
+function start(port = 3001, host = '127.0.0.1') {
+  return new Promise((resolve, reject) => {
+    try {
+      const srv = app.listen(port, host, () => {
+        console.log('Koa example listening on', port);
+        resolve(srv);
+      });
+    } catch (err) { reject(err); }
+  });
+}
+
+if (require.main === module) start().catch(err => { console.error(err); process.exit(1); });
+
+module.exports = { app, start };

package/live-test/integrations/nestjs-example.js

@@ -0,0 +1,25 @@
+/*
+Minimal NestJS integration example (TypeScript flavor shown).
+
+This file is an illustrative snippet and is NOT executed by the
+smoke-test (NestJS requires heavier deps). Use it as a guide.
+
+// main.ts
+import { NestFactory } from '@nestjs/core';
+import { AppModule } from './app.module';
+import * as miki from 'miki-template';
+
+async function bootstrap() {
+  const app = await NestFactory.create(AppModule);
+  const expressApp = app.getHttpAdapter().getInstance();
+  // Wire miki into underlying Express instance
+  miki.setupExpress(expressApp, { extension: 'html', views: './views' });
+  await app.listen(3006);
+}
+
+bootstrap();
+
+*/
+
+// Plain JS note: If you use Nest with JS, the same pattern applies:
+// obtain the underlying Express instance and call miki.setupExpress(...)

package/live-test/integrations/smoke-test.js

@@ -0,0 +1,166 @@
+const { spawn } = require('child_process');
+const path = require('path');
+const http = require('http');
+
+async function start(scriptPath) {
+  // Skip optional ESM integrations when their deps are missing
+  const missing = {
+    'elysia-example.js': 'elysia',
+    'hono-example.js': 'hono'
+  };
+  const basename = path.basename(scriptPath);
+  if (missing[basename]) {
+    try { require.resolve(missing[basename]); }
+    catch {
+      console.warn(`Skipping ${basename}: ${missing[basename]} is not installed`);
+      return null;
+    }
+  }
+
+  // Require the example module and call its exported start() which
+  // returns a Promise or a server instance.
+  const mod = require(scriptPath);
+  if (mod && typeof mod.start === 'function') {
+    let res;
+    try {
+      res = mod.start();
+    } catch (err) {
+      console.warn(`Skipping ${basename}: start() failed: ${err.message}`);
+      return null;
+    }
+    // Fastify returns a Promise resolving to server address; Koa/Express
+    // return a server instance synchronously — normalize both.
+    if (res && typeof res.then === 'function') {
+      try {
+        await res;
+        return res;
+      } catch (err) {
+        console.warn(`Skipping ${basename}: start() promise rejected: ${err.message}`);
+        return null;
+      }
+    }
+    return res;
+  }
+  // Fallback: spawn as a child process
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [scriptPath], { stdio: 'inherit' });
+    child.on('error', reject);
+    setTimeout(() => resolve(child), 800);
+  });
+}
+
+async function fetch(url) {
+  return new Promise((resolve, reject) => {
+    http.get(url, res => {
+      let data = '';
+      res.on('data', c => data += c.toString());
+      res.on('end', () => resolve({ status: res.statusCode, body: data }));
+    }).on('error', reject);
+  });
+}
+
+async function main() {
+  const root = path.resolve(__dirname);
+  const servers = [
+    { file: path.join(root, 'express-example.js'), url: 'http://localhost:3000/' },
+    { file: path.join(root, 'koa-example.js'), url: 'http://localhost:3001/' },
+    { file: path.join(root, 'fastify-example.js'), url: 'http://localhost:3002/' }
+  ];
+  // Add ESM-based examples (elysia, hono). These will be spawned as
+  // child processes if they cannot be required as modules.
+  servers.push({ file: path.join(root, 'elysia-example.js'), url: 'http://localhost:3004/' });
+  servers.push({ file: path.join(root, 'hono-example.js'), url: 'http://localhost:3005/' });
+
+  const procs = [];
+  for (const s of servers) {
+    procs.push(await start(s.file));
+  }
+
+  // Test each server
+  for (let i = 0; i < servers.length; i++) {
+    const s = servers[i];
+    const p = procs[i];
+    if (!p) {
+      console.warn(`Skipping smoke-test for ${path.basename(s.file)} (not running)`);
+      continue;
+    }
+    try {
+      const res = await fetch(s.url);
+      console.log(`${s.url} -> ${res.status} length=${res.body.length}`);
+    } catch (e) {
+      console.error(`Failed to fetch ${s.url}:`, e.message || e);
+    }
+  }
+
+  // Test partial route on express
+  try {
+    const res = await fetch('http://localhost:3000/partial');
+    console.log(`/partial -> ${res.status} length=${res.body.length}`);
+  } catch (e) { console.error('Partial fetch failed', e.message || e); }
+
+  // Programmatic engine tests: render('home#card') via the engine APIs
+  try {
+    // Try requiring as if the package were installed; fallback to local
+    let miki;
+    try { miki = require('miki-template'); } catch (e) { miki = require('../..'); }
+
+    // For each framework, test programmatic partial rendering and finder behavior
+    const frameworks = ['express', 'koa', 'fastify', 'elysia', 'hono'];
+    for (const name of frameworks) {
+      const viewsDir = path.resolve(__dirname, '..', 'views');
+      try {
+        const asyncHtml = await miki.asyncRender('home#card', { user: name + 'Async', title: name + 'Card' }, { views: viewsDir });
+        console.log(`${name}: asyncRender(home#card) length=${asyncHtml.length}`);
+      } catch (e) { console.error(`${name}: asyncRender failed`, e && e.message ? e.message : e); }
+
+      try {
+        const syncHtml = miki.render('home#card', { user: name + 'Sync', title: name + 'Card' }, { views: viewsDir });
+        console.log(`${name}: render(home#card) length=${syncHtml.length}`);
+      } catch (e) { console.error(`${name}: render failed`, e && e.message ? e.message : e); }
+
+      // Finder tests: simulate multiple view roots including nested app-template dirs
+      try {
+        const found = miki.findTemplateInViews('home', [viewsDir, path.resolve(__dirname, '..')]);
+        console.log(`${name}: finder resolved -> ${found ? found : 'not found'}`);
+      } catch (e) { console.error(`${name}: finder error`, e && e.message ? e.message : e); }
+    }
+  } catch (e) {
+    console.error('Engine partial render failed:', e && e.stack ? e.stack : e);
+  }
+
+  // Cleanup: attempt graceful shutdown for each started server
+  for (let i = 0; i < procs.length; i++) {
+    const p = procs[i];
+    if (!p) continue;
+    try {
+      if (typeof p.kill === 'function') {
+        p.kill();
+        continue;
+      }
+      if (typeof p.close === 'function') {
+        p.close();
+        continue;
+      }
+      // Fastify may return an address string; try to require module and call exported stop/close
+      try {
+        const mod = require(servers[i].file);
+        if (mod) {
+          if (typeof mod.stop === 'function') await mod.stop();
+          else if (typeof mod.close === 'function') await mod.close();
+          else if (mod.app && typeof mod.app.close === 'function') mod.app.close();
+        }
+      } catch (e) {
+        // ignore
+      }
+    } catch (e) {
+      // ignore errors during cleanup
+    }
+  }
+}
+
+if (require.main === module) {
+  main().catch(err => {
+    console.error('smoke-test failed', err && err.stack ? err.stack : err);
+    process.exit(1);
+  });
+}

package/live-test/integrations/tsed-example.js

@@ -0,0 +1,23 @@
+/*
+Ts.ED integration (Express adapter)
+
+This is an example snippet for Ts.ED users. Ts.ED can run on Express
+or Koa — when using the Express adapter, obtain the raw Express app
+and call `miki.setupExpress()` as shown.
+
+// server.ts (snippet)
+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();
+
+*/
+
+// Plain JS: same approach — call setupExpress on the underlying app.