@zenweb/template 5.1.0 → 5.2.0

package/AGENTS.md

@@ -0,0 +1,187 @@
+# @zenweb/template - AI API Reference
+
+AI 专用 API 参考文档，随 npm 包发布，供 AI 编程助手使用。
+
+## 模块概述
+
+`@zenweb/template` 是 ZenWeb 框架的服务端模版渲染模块。集成模版引擎（如 Nunjucks、Handlebars）并根据请求条件（路径匹配、Accept 头、控制器显式指定）按需渲染输出。支持多个模版引擎实例共存。
+
+## 导出
+
+```ts
+export default function setup(option: TemplateSetupOption): SetupFunction;
+export { $template, TemplateSetupOption, TemplateOption, TemplateEngine };
+```
+
+## 类型
+
+```ts
+/**
+ * 渲染引擎方法签名
+ * - 函数名 (name) 作为默认引擎名称
+ */
+type TemplateEngine = (template: string, data?: any) => any;
+
+interface TemplateSetupOption {
+  /** 输出类型，默认 'html' */
+  type?: string;
+  /** 匹配路径，例如 [/\.html$/i] */
+  matchPath?: RegExp[];
+  /** 忽略路径，例如 [/^\/api\//i] */
+  ignorePath?: RegExp[];
+  /** 匹配 Accept 头类型 */
+  matchAccept?: string[];
+  /**
+   * 模版名后缀，例如 '.html'
+   * 在不指定 TemplateOption.template 时有效
+   */
+  templateAffix?: string;
+  /**
+   * ctx.fail 操作使用的模版（全局）
+   * 不指定则使用 TemplateOption.template 值
+   * 控制器中可设置 TemplateOption.failTemplate = false 关闭
+   */
+  failTemplate?: string;
+  /** 渲染引擎 */
+  engine: TemplateEngine;
+  /**
+   * 自定义引擎名称
+   * 默认取 engine.name，多引擎共存时用于区分
+   */
+  engineName?: string;
+}
+
+interface TemplateOption {
+  /** 指定模版名，不指定取 ctx.path */
+  template?: string;
+  /**
+   * 失败模版
+   * 默认使用全局 failTemplate
+   * 设为 false 强制使用 template
+   */
+  failTemplate?: string | false;
+  /** 使用的引擎名称，对应 TemplateSetupOption.engineName */
+  engine?: string;
+}
+```
+
+## setup(option) (default export)
+
+模块安装函数，用于 `app.setup(modTemplate({ ... }))`。
+
+**处理流程：**
+1. 设置引擎名称（默认取 `option.engine.name`）
+2. 断言 `@zenweb/result` 模块已安装
+3. 创建 `TemplateRender` 实例并注册到 `RenderManager`
+4. 扩展 Context，挂载 `ctx.template()` 方法
+
+**基本用法：**
+```ts
+import { create } from 'zenweb';
+import modTemplate from '@zenweb/template';
+import nunjucks from '@zenweb/template-nunjucks';
+
+create()
+.setup(modTemplate({
+  matchPath: [/\.html$/i],
+  engine: nunjucks(),
+}))
+.start();
+```
+
+**多引擎配置：**
+```ts
+create()
+.setup(modTemplate({
+  matchPath: [/\.html$/i],
+  engine: nunjucks(),
+}))
+.setup(modTemplate({
+  type: 'xml',
+  matchAccept: ['xml'],
+  templateAffix: '.xml',
+  engine: handlebars(),
+  engineName: 'xml',
+}))
+.start();
+```
+
+## $template(template_or_option?)
+
+全局方法，在控制器或服务中使用，基于 `@zenweb/core` 的 `$getContext()` 获取当前请求上下文。
+
+```ts
+$template()                              // 启用模版渲染（使用默认匹配）
+$template('detail.html')                 // 指定模版文件
+$template({ failTemplate: 'error.html' }) // 指定失败模版
+$template({ engine: 'xml' })             // 切换引擎
+$template(false)                         // 关闭当前请求的模版渲染
+```
+
+**控制器示例：**
+```ts
+import { Context, mapping } from 'zenweb';
+import { $template } from '@zenweb/template';
+
+export class Controller {
+  @mapping({ path: '/user.html' })
+  user(ctx: Context) {
+    $template();              // 启用渲染
+    return { name: 'test' };  // 渲染 user.html 模版
+  }
+
+  @mapping({ path: '/api/data' })
+  data() {
+    $template(false);         // 禁用渲染，返回 JSON
+    return { name: 'test' };
+  }
+}
+```
+
+## Context 挂载
+
+```ts
+interface Context {
+  /** 当前请求的模版渲染选项 */
+  templateOption?: TemplateOption;
+
+  /**
+   * 启用并设置模版渲染
+   * 不传参数: 启用
+   * false: 关闭模版渲染
+   * string: 设置模版文件名
+   * TemplateOption: 详细设置
+   */
+  template(template_or_option?: false | string | TemplateOption): void;
+}
+```
+
+## 匹配规则
+
+`TemplateRender.match()` 按以下优先级判断请求是否需要模版渲染：
+
+1. **引擎名匹配** — `ctx.templateOption.engine === option.engineName` 时直接匹配
+2. **模版后缀匹配** — `ctx.templateOption.template` 以 `templateAffix` 结尾时匹配
+3. **忽略路径** — `ignorePath` 中任一正则匹配 `ctx.path` 时返回 `false`
+4. **路径匹配** — `matchPath` 中任一正则匹配 `ctx.path` 时匹配
+5. **Accept 头匹配** — `matchAccept` 包含请求 Accept 类型时匹配
+6. 以上均不满足则不匹配，回退到 JSON 渲染
+
+## 渲染流程
+
+`TemplateRender.render()` 按以下逻辑确定模版名：
+
+1. 若数据为 `ResultFail` 实例，包装为 `{ fail: data }`，并使用 `failTemplate`
+2. 模版名优先级：`opt.template` → `ctx.path.slice(1) + templateAffix`
+3. 调用 `engine(template, data)` 渲染输出
+
+## 依赖模块
+
+- `@zenweb/result` — 必须在此之前安装，提供 `RenderManager` 和 `ResultRender` 接口
+
+## 已知模版引擎适配器
+
+| 包名 | 引擎 |
+|------|------|
+| `@zenweb/template-nunjucks` | Nunjucks |
+| `@zenweb/template-handlebars` | Handlebars |

package/dist/global.d.ts

@@ -1,4 +1,4 @@
-import { TemplateOption } from "./types.js";
+import { TemplateOption } from "./types";
 /**
  * 启用并设置模版渲染
  * - 不传参数: 启用

package/dist/global.js

@@ -1,4 +1,7 @@
-import { $getContext } from "@zenweb/core";
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.$template = $template;
+const core_1 = require("@zenweb/core");
 /**
  * 启用并设置模版渲染
  * - 不传参数: 启用
@@ -6,6 +9,6 @@ import { $getContext } from "@zenweb/core";
  * - string: 设置模版文件名
  * - TemplateOption: 详细设置
  */
-export function $template(template_or_option) {
-    return $getContext().template(template_or_option);
+function $template(template_or_option) {
+    return (0, core_1.$getContext)().template(template_or_option);
 }

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { SetupFunction } from '@zenweb/core';
-import { TemplateSetupOption, TemplateOption } from './types.js';
-export * from './types.js';
-export * from './global.js';
+import { TemplateSetupOption, TemplateOption } from './types';
+export * from './types';
+export * from './global';
 export default function setup(option: TemplateSetupOption): SetupFunction;
 declare module '@zenweb/core' {
     interface Context {

package/dist/index.js

@@ -1,7 +1,24 @@
-import { RenderManager } from '@zenweb/result';
-import { TemplateRender } from './render.js';
-export * from './types.js';
-export * from './global.js';
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = setup;
+const result_1 = require("@zenweb/result");
+const render_1 = require("./render");
+__exportStar(require("./types"), exports);
+__exportStar(require("./global"), exports);
 function contextTemplate(template_or_option) {
     if (template_or_option === false) {
         this.templateOption = undefined;
@@ -17,15 +34,15 @@ function contextTemplate(template_or_option) {
         Object.assign(this.templateOption, template_or_option);
     }
 }
-export default function setup(option) {
+function setup(option) {
     return async function template(setup) {
         if (!option.engineName) {
             option.engineName = option.engine.name;
         }
         setup.debug('option: %o', option);
         setup.assertModuleExists('result', '@zenweb/result');
-        const renderManager = await setup.core.injector.getInstance(RenderManager);
-        renderManager.add(new TemplateRender(option));
+        const renderManager = await setup.core.injector.getInstance(result_1.RenderManager);
+        renderManager.add(new render_1.TemplateRender(option));
         if (!('template' in setup.app.context)) {
             setup.defineContextProperty('template', { value: contextTemplate });
         }

package/dist/render.d.ts

@@ -1,6 +1,6 @@
 import { Context } from '@zenweb/core';
 import { ResultRender } from '@zenweb/result';
-import { TemplateSetupOption } from './types.js';
+import { TemplateSetupOption } from './types';
 export declare class TemplateRender implements ResultRender {
     private _option;
     enwrap: boolean;

package/dist/render.js

@@ -1,11 +1,12 @@
-import { ResultFail } from '@zenweb/result';
-import { debug } from './utils.js';
-export class TemplateRender {
-    _option;
-    enwrap = false;
-    type;
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TemplateRender = void 0;
+const result_1 = require("@zenweb/result");
+const utils_1 = require("./utils");
+class TemplateRender {
     constructor(_option) {
         this._option = _option;
+        this.enwrap = false;
         this.type = _option.type || 'html';
     }
     match(ctx) {
@@ -13,12 +14,12 @@ export class TemplateRender {
         if (opt) {
             // 匹配引擎
             if (opt.engine === this._option.engineName) {
-                debug('matchEngine: %o', this._option.engineName);
+                (0, utils_1.debug)('matchEngine: %o', this._option.engineName);
                 return true;
             }
             // 指定模版
             if (opt.template && this._option.templateAffix && opt.template.endsWith(this._option.templateAffix)) {
-                debug('matchTemplateAffix: %o', this._option.templateAffix);
+                (0, utils_1.debug)('matchTemplateAffix: %o', this._option.templateAffix);
                 return true;
             }
         }
@@ -26,7 +27,7 @@ export class TemplateRender {
         if (this._option.ignorePath) {
             for (const reg of this._option.ignorePath) {
                 if (reg.test(ctx.path)) {
-                    debug('ignorePath: %o', reg);
+                    (0, utils_1.debug)('ignorePath: %o', reg);
                     return false;
                 }
             }
@@ -35,7 +36,7 @@ export class TemplateRender {
         if (this._option.matchPath) {
             for (const reg of this._option.matchPath) {
                 if (reg.test(ctx.path)) {
-                    debug('matchPath: %o', reg);
+                    (0, utils_1.debug)('matchPath: %o', reg);
                     return true;
                 }
             }
@@ -44,7 +45,7 @@ export class TemplateRender {
         if (this._option.matchAccept) {
             const _type = ctx.accepts().some(accept => this._option.matchAccept?.includes(accept));
             if (_type) {
-                debug('matchAccept: %o', _type);
+                (0, utils_1.debug)('matchAccept: %o', _type);
                 return true;
             }
         }
@@ -53,7 +54,7 @@ export class TemplateRender {
     render(ctx, data) {
         const opt = ctx.templateOption || {};
         let template = opt.template;
-        if (data instanceof ResultFail) {
+        if (data instanceof result_1.ResultFail) {
             data = { fail: data };
             if (opt.failTemplate !== false) {
                 template = opt.failTemplate || this._option.failTemplate || template;
@@ -68,3 +69,4 @@ export class TemplateRender {
         return this._option.engine(template, data);
     }
 }
+exports.TemplateRender = TemplateRender;

package/dist/types.js

@@ -1 +1,2 @@
-export {};
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/utils.js

@@ -1,7 +1,44 @@
-import * as path from 'path';
-import { debug as _debug } from '@zenweb/core';
-export const debug = _debug.extend('template');
-export function cwdPath(p) {
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.debug = void 0;
+exports.cwdPath = cwdPath;
+const path = __importStar(require("path"));
+const core_1 = require("@zenweb/core");
+exports.debug = core_1.debug.extend('template');
+function cwdPath(p) {
     if (p.startsWith('./')) {
         return path.join(process.cwd(), p.slice(2));
     }

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@zenweb/template",
-  "type": "module",
-  "version": "5.1.0",
+  "version": "5.2.0",
   "description": "zenweb template render module",
   "exports": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "scripts": {
-    "build": "rimraf dist && tsc",
+    "build": "rimraf dist && tsc -p tsconfig.build.json",
     "prepack": "npm run build",
-    "dev": "cd example && node --env-file=.env --import tsx/esm app.ts"
+    "dev": "cd example && node --env-file=.env -r ts-node/register app.ts"
   },
   "files": [
+    "AGENTS.md",
     "dist"
   ],
   "author": {
@@ -25,17 +25,17 @@
   "license": "MIT",
   "homepage": "https://zenweb.node.ltd",
   "devDependencies": {
-    "@types/node": "^20.10.6",
-    "@zenweb/inject": "^5.1.0",
-    "@zenweb/template-handlebars": "^3.0.0",
-    "@zenweb/template-nunjucks": "^3.3.0",
+    "@types/node": "^16.18.126",
+    "@zenweb/inject": "^5.4.0",
+    "@zenweb/template-handlebars": "^4.1.0",
+    "@zenweb/template-nunjucks": "^4.1.0",
     "rimraf": "^4.4.1",
-    "tsx": "^4.19.1",
-    "typescript": "^5.3.3",
-    "zenweb": "^5.1.0"
+    "ts-node": "^10.9.2",
+    "typescript": "^6.0.3",
+    "zenweb": "^6.4.0"
   },
   "dependencies": {
-    "@zenweb/core": "^5.1.0",
-    "@zenweb/result": "^5.0.0"
+    "@zenweb/core": "^5.3.0",
+    "@zenweb/result": "^5.3.0"
   }
 }