@eggjs/view 3.0.1 → 4.0.0-beta.17

package/README.md

@@ -1,10 +1,7 @@
 # @eggjs/view
 
 [![NPM version](https://img.shields.io/npm/v/@eggjs/view.svg?style=flat-square)](https://npmjs.org/package/@eggjs/view)
-[![NPM quality](http://npm.packagequality.com/shield/@eggjs/view.svg?style=flat-square)](http://packagequality.com/#?package=@eggjs/view)
 [![NPM download](https://img.shields.io/npm/dm/@eggjs/view.svg?style=flat-square)](https://npmjs.org/package/@eggjs/view)
-[![Continuous Integration](https://github.com/eggjs/view/actions/workflows/nodejs.yml/badge.svg)](https://github.com/eggjs/view/actions/workflows/nodejs.yml)
-[![Test coverage](https://img.shields.io/codecov/c/github/eggjs/view.svg?style=flat-square)](https://codecov.io/gh/eggjs/view)
 [![Node.js Version](https://img.shields.io/node/v/@eggjs/view.svg?style=flat)](https://nodejs.org/en/download/)
 [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg?style=flat-square)](https://makeapullrequest.com)
 ![CodeRabbit Pull Request Reviews](https://img.shields.io/coderabbit/prs/github/eggjs/view)
@@ -76,9 +73,13 @@ module.exports = app => {
   return class UserController extends app.Controller {
     async list() {
       const { ctx } = this;
-      ctx.body = await ctx.renderString('<%= user %>', { user: 'popomore' }, {
-        viewEngine: 'ejs',
-      });
+      ctx.body = await ctx.renderString(
+        '<%= user %>',
+        { user: 'popomore' },
+        {
+          viewEngine: 'ejs',
+        }
+      );
     }
   };
 };
@@ -128,7 +129,9 @@ module.exports = class MyView {
     return myengine.render(fullpath, locals);
   }
 
-  async renderString() { throw new Error('not implement'); }
+  async renderString() {
+    throw new Error('not implement');
+  }
 };
 ```
 
@@ -149,7 +152,7 @@ class MyView {
       });
     });
   }
-};
+}
 ```
 
 These methods receive three arguments, `renderString` will pass tpl as the first argument instead of name in `render`.
@@ -191,7 +194,7 @@ Define plugin name and depend on [egg-view]
 {
   "eggPlugin": {
     "name": "myName",
-    "dependencies": [ "view" ]
+    "dependencies": ["view"]
   }
 }
 ```
@@ -218,10 +221,10 @@ module.exports = appInfo => {
   const baseDir = appInfo.baseDir;
   return {
     view: {
-      root: `${baseDir}/app/view,${baseDir}/app/view2`
-    }
-  }
-}
+      root: `${baseDir}/app/view,${baseDir}/app/view2`,
+    },
+  };
+};
 ```
 
 ### defaultExtension
@@ -259,7 +262,7 @@ exports.view = {
 };
 ```
 
-see [config/config.default.ts](https://github.com/eggjs/view/blob/master/src/config/config.default.ts) for more detail.
+see [config/config.default.ts](https://github.com/eggjs/egg/blob/next/plugins/view/src/config/config.default.ts) for more detail.
 
 ## Questions & Suggestions
 
@@ -271,7 +274,7 @@ Please open an issue [here](https://github.com/eggjs/egg/issues).
 
 ## Contributors
 
-[![Contributors](https://contrib.rocks/image?repo=eggjs/logrotator)](https://github.com/eggjs/logrotator/graphs/contributors)
+[![Contributors](https://contrib.rocks/image?repo=eggjs/egg)](https://github.com/eggjs/egg/graphs/contributors)
 
 Made with [contributors-img](https://contrib.rocks).
 

package/dist/app/extend/application.d.ts

@@ -0,0 +1,15 @@
+import { ViewManager } from "../../lib/view_manager.js";
+import { Application } from "egg";
+
+//#region src/app/extend/application.d.ts
+declare const VIEW: unique symbol;
+declare class ViewApplication extends Application {
+  [VIEW]: ViewManager;
+  /**
+   * Retrieve ViewManager instance
+   * @member {ViewManager} Application#view
+   */
+  get view(): ViewManager;
+}
+//#endregion
+export { ViewApplication as default };

package/dist/app/extend/application.js

@@ -0,0 +1,19 @@
+import { ViewManager } from "../../lib/view_manager.js";
+import { Application } from "egg";
+
+//#region src/app/extend/application.ts
+const VIEW = Symbol("Application#view");
+var ViewApplication = class extends Application {
+	[VIEW];
+	/**
+	* Retrieve ViewManager instance
+	* @member {ViewManager} Application#view
+	*/
+	get view() {
+		if (!this[VIEW]) this[VIEW] = new ViewManager(this);
+		return this[VIEW];
+	}
+};
+
+//#endregion
+export { ViewApplication as default };

package/dist/app/extend/context.d.ts

@@ -0,0 +1,39 @@
+import { RenderOptions } from "../../lib/view_manager.js";
+import { ContextView } from "../../lib/context_view.js";
+import { Context } from "egg";
+
+//#region src/app/extend/context.d.ts
+declare const VIEW: unique symbol;
+declare class ViewContext extends Context {
+  [VIEW]: ContextView;
+  /**
+   * Render a file by view engine, then set to body
+   * @param {String} name - the file path based on root
+   * @param {Object} [locals] - data used by template
+   * @param {Object} [options] - view options, you can use `options.viewEngine` to specify view engine
+   */
+  render(name: string, locals?: Record<string, any>, options?: RenderOptions): Promise<void>;
+  /**
+   * Render a file by view engine and return it
+   * @param {String} name - the file path based on root
+   * @param {Object} [locals] - data used by template
+   * @param {Object} [options] - view options, you can use `options.viewEngine` to specify view engine
+   * @return {Promise<String>} result - return a promise with a render result
+   */
+  renderView(name: string, locals?: Record<string, any>, options?: RenderOptions): Promise<string>;
+  /**
+   * Render template string by view engine and return it
+   * @param {String} tpl - template string
+   * @param {Object} [locals] - data used by template
+   * @param {Object} [options] - view options, you can use `options.viewEngine` to specify view engine
+   * @return {Promise<String>} result - return a promise with a render result
+   */
+  renderString(tpl: string, locals?: Record<string, any>, options?: RenderOptions): Promise<string>;
+  /**
+   * View instance that is created every request
+   * @member {ContextView} Context#view
+   */
+  get view(): ContextView;
+}
+//#endregion
+export { ViewContext as default };

package/dist/app/extend/context.js

@@ -0,0 +1,49 @@
+import "../../lib/view_manager.js";
+import { ContextView } from "../../lib/context_view.js";
+import { Context } from "egg";
+
+//#region src/app/extend/context.ts
+const VIEW = Symbol("Context#view");
+var ViewContext = class extends Context {
+	[VIEW];
+	/**
+	* Render a file by view engine, then set to body
+	* @param {String} name - the file path based on root
+	* @param {Object} [locals] - data used by template
+	* @param {Object} [options] - view options, you can use `options.viewEngine` to specify view engine
+	*/
+	async render(name, locals, options) {
+		this.body = await this.renderView(name, locals, options);
+	}
+	/**
+	* Render a file by view engine and return it
+	* @param {String} name - the file path based on root
+	* @param {Object} [locals] - data used by template
+	* @param {Object} [options] - view options, you can use `options.viewEngine` to specify view engine
+	* @return {Promise<String>} result - return a promise with a render result
+	*/
+	async renderView(name, locals, options) {
+		return await this.view.render(name, locals, options);
+	}
+	/**
+	* Render template string by view engine and return it
+	* @param {String} tpl - template string
+	* @param {Object} [locals] - data used by template
+	* @param {Object} [options] - view options, you can use `options.viewEngine` to specify view engine
+	* @return {Promise<String>} result - return a promise with a render result
+	*/
+	async renderString(tpl, locals, options) {
+		return await this.view.renderString(tpl, locals, options);
+	}
+	/**
+	* View instance that is created every request
+	* @member {ContextView} Context#view
+	*/
+	get view() {
+		if (!this[VIEW]) this[VIEW] = new ContextView(this);
+		return this[VIEW];
+	}
+};
+
+//#endregion
+export { ViewContext as default };

package/dist/config/config.default.d.ts

@@ -0,0 +1,33 @@
+import * as egg1 from "egg";
+
+//#region src/config/config.default.d.ts
+interface ViewConfig {
+  /**
+   * give a path to find the file, you can specify multiple path with `,` delimiter
+   * Default is `${baseDir}/app/view`
+   */
+  root: string;
+  /**
+   * whether cache the file's path
+   * Default is `true`
+   */
+  cache: boolean;
+  /**
+   * defaultExtension can be added automatically when there is no extension  when call `ctx.render`
+   * Default is `.html`
+   */
+  defaultExtension: string;
+  /**
+   * set the default view engine if you don't want specify the viewEngine every request.
+   * Default is `''`
+   */
+  defaultViewEngine: string;
+  /**
+   * map the file extension to view engine, such as `{ '.ejs': 'ejs' }`
+   * Default is `{}`
+   */
+  mapping: Record<string, string>;
+}
+declare const _default: egg1.EggConfigFactory;
+//#endregion
+export { ViewConfig, _default as default };

package/dist/config/config.default.js

@@ -0,0 +1,14 @@
+import path from "node:path";
+import { defineConfigFactory } from "egg";
+
+//#region src/config/config.default.ts
+var config_default_default = defineConfigFactory((appInfo) => ({ view: {
+	root: path.join(appInfo.baseDir, "app/view"),
+	cache: true,
+	defaultExtension: ".html",
+	defaultViewEngine: "",
+	mapping: {}
+} }));
+
+//#endregion
+export { config_default_default as default };

package/dist/config/config.local.d.ts

@@ -0,0 +1,6 @@
+import { EggAppConfig } from "egg";
+
+//#region src/config/config.local.d.ts
+declare const _default: EggAppConfig;
+//#endregion
+export { _default as default };

package/dist/config/config.local.js

@@ -0,0 +1,5 @@
+//#region src/config/config.local.ts
+var config_local_default = { view: { cache: false } };
+
+//#endregion
+export { config_local_default as default };

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import { PlainObject, RenderOptions, ViewEngine, ViewEngineClass, ViewManager, ViewManagerConfig } from "./lib/view_manager.js";
+import { ContextView } from "./lib/context_view.js";
+export { ContextView, PlainObject, RenderOptions, ViewEngine, ViewEngineClass, ViewManager, ViewManagerConfig };

package/dist/index.js

@@ -0,0 +1,8 @@
+import "./config/config.default.js";
+import { ViewManager } from "./lib/view_manager.js";
+import "./app/extend/application.js";
+import { ContextView } from "./lib/context_view.js";
+import "./app/extend/context.js";
+import "./lib/index.js";
+
+export { ContextView, ViewManager };

package/dist/lib/context_view.d.ts

@@ -0,0 +1,52 @@
+import { RenderOptions, ViewEngine, ViewManager, ViewManagerConfig } from "./view_manager.js";
+import * as egg0 from "egg";
+import { Application, Context } from "egg";
+
+//#region src/lib/context_view.d.ts
+declare const RENDER: unique symbol;
+declare const RENDER_STRING: unique symbol;
+declare const GET_VIEW_ENGINE: unique symbol;
+declare const SET_LOCALS: unique symbol;
+/**
+ * View instance for each request.
+ *
+ * It will find the view engine, and render it.
+ * The view engine should be registered in {@link ViewManager}.
+ */
+declare class ContextView {
+  protected ctx: Context;
+  protected app: Application;
+  protected viewManager: ViewManager;
+  protected config: ViewManagerConfig;
+  constructor(ctx: Context);
+  /**
+   * Render a file by view engine
+   * @param {String} name - the file path based on root
+   * @param {Object} [locals] - data used by template
+   * @param {Object} [options] - view options, you can use `options.viewEngine` to specify view engine
+   * @return {Promise<String>} result - return a promise with a render result
+   */
+  render(name: string, locals?: Record<string, any>, options?: RenderOptions): Promise<string>;
+  /**
+   * Render a template string by view engine
+   * @param {String} tpl - template string
+   * @param {Object} [locals] - data used by template
+   * @param {Object} [options] - view options, you can use `options.viewEngine` to specify view engine
+   * @return {Promise<String>} result - return a promise with a render result
+   */
+  renderString(tpl: string, locals?: Record<string, any>, options?: RenderOptions): Promise<string>;
+  [RENDER](name: string, locals?: Record<string, any>, options?: RenderOptions): Promise<string>;
+  [RENDER_STRING](tpl: string, locals?: Record<string, any>, options?: RenderOptions): Promise<string>;
+  [GET_VIEW_ENGINE](name: string): ViewEngine;
+  /**
+   * set locals for view, inject `locals.ctx`, `locals.request`, `locals.helper`
+   * @private
+   */
+  [SET_LOCALS](locals?: Record<string, any>): {
+    ctx: Context;
+    request: egg0.Request;
+    helper: egg0.Helper;
+  } & Record<string, any>;
+}
+//#endregion
+export { ContextView };

package/dist/lib/context_view.js

@@ -0,0 +1,86 @@
+import "./view_manager.js";
+import path from "node:path";
+import assert from "node:assert";
+
+//#region src/lib/context_view.ts
+const RENDER = Symbol.for("contextView#render");
+const RENDER_STRING = Symbol.for("contextView#renderString");
+const GET_VIEW_ENGINE = Symbol.for("contextView#getViewEngine");
+const SET_LOCALS = Symbol.for("contextView#setLocals");
+/**
+* View instance for each request.
+*
+* It will find the view engine, and render it.
+* The view engine should be registered in {@link ViewManager}.
+*/
+var ContextView = class {
+	ctx;
+	app;
+	viewManager;
+	config;
+	constructor(ctx) {
+		this.ctx = ctx;
+		this.app = this.ctx.app;
+		this.viewManager = this.app.view;
+		this.config = this.app.view.config;
+	}
+	/**
+	* Render a file by view engine
+	* @param {String} name - the file path based on root
+	* @param {Object} [locals] - data used by template
+	* @param {Object} [options] - view options, you can use `options.viewEngine` to specify view engine
+	* @return {Promise<String>} result - return a promise with a render result
+	*/
+	async render(name, locals, options) {
+		return await this[RENDER](name, locals, options);
+	}
+	/**
+	* Render a template string by view engine
+	* @param {String} tpl - template string
+	* @param {Object} [locals] - data used by template
+	* @param {Object} [options] - view options, you can use `options.viewEngine` to specify view engine
+	* @return {Promise<String>} result - return a promise with a render result
+	*/
+	async renderString(tpl, locals, options) {
+		return await this[RENDER_STRING](tpl, locals, options);
+	}
+	async [RENDER](name, locals, options = {}) {
+		const filename = await this.viewManager.resolve(name);
+		options.name = name;
+		options.root = filename.replace(path.normalize(name), "").replace(/[/\\]$/, "");
+		options.locals = locals;
+		let viewEngineName = options.viewEngine;
+		if (!viewEngineName) {
+			const ext = path.extname(filename);
+			viewEngineName = this.viewManager.extMap.get(ext);
+		}
+		if (!viewEngineName) viewEngineName = this.config.defaultViewEngine;
+		assert(viewEngineName, `Can't find viewEngine for ${filename}`);
+		return await this[GET_VIEW_ENGINE](viewEngineName).render(filename, this[SET_LOCALS](locals), options);
+	}
+	async [RENDER_STRING](tpl, locals, options) {
+		let viewEngineName = options && options.viewEngine;
+		if (!viewEngineName) viewEngineName = this.config.defaultViewEngine;
+		assert(viewEngineName, "Can't find viewEngine");
+		return await this[GET_VIEW_ENGINE](viewEngineName).renderString(tpl, this[SET_LOCALS](locals), options);
+	}
+	[GET_VIEW_ENGINE](name) {
+		const ViewEngine = this.viewManager.get(name);
+		assert(ViewEngine, `Can't find ViewEngine "${name}"`);
+		return new ViewEngine(this.ctx);
+	}
+	/**
+	* set locals for view, inject `locals.ctx`, `locals.request`, `locals.helper`
+	* @private
+	*/
+	[SET_LOCALS](locals) {
+		return Object.assign({
+			ctx: this.ctx,
+			request: this.ctx.request,
+			helper: this.ctx.helper
+		}, this.ctx.locals, locals);
+	}
+};
+
+//#endregion
+export { ContextView };

package/dist/lib/index.d.ts

@@ -0,0 +1,3 @@
+import { PlainObject, RenderOptions, ViewEngine, ViewEngineClass, ViewManager, ViewManagerConfig } from "./view_manager.js";
+import { ContextView } from "./context_view.js";
+export { ContextView, PlainObject, RenderOptions, ViewEngine, ViewEngineClass, ViewManager, ViewManagerConfig };

package/dist/lib/index.js

@@ -0,0 +1,4 @@
+import { ViewManager } from "./view_manager.js";
+import { ContextView } from "./context_view.js";
+
+export { ContextView, ViewManager };

package/dist/lib/view_manager.d.ts

@@ -0,0 +1,61 @@
+import { ViewConfig } from "../config/config.default.js";
+import { Application, Context } from "egg";
+
+//#region src/lib/view_manager.d.ts
+interface ViewManagerConfig extends Omit<ViewConfig, 'root'> {
+  root: string[];
+}
+type PlainObject<T = any> = {
+  [key: string]: T;
+};
+interface RenderOptions extends PlainObject {
+  name?: string;
+  root?: string;
+  locals?: PlainObject;
+  viewEngine?: string;
+}
+interface ViewEngine {
+  render: (name: string, locals?: Record<string, any>, options?: RenderOptions) => Promise<string>;
+  renderString: (tpl: string, locals?: Record<string, any>, options?: RenderOptions) => Promise<string>;
+}
+type ViewEngineClass = new (app: Context) => ViewEngine;
+/**
+ * ViewManager will manage all view engine that is registered.
+ *
+ * It can find the real file, then retrieve the view engine based on extension.
+ * The plugin just register view engine using {@link ViewManager#use}
+ */
+declare class ViewManager extends Map<string, ViewEngineClass> {
+  config: ViewManagerConfig;
+  extMap: Map<string, string>;
+  fileMap: Map<string, string>;
+  /**
+   * @param {Application} app - application instance
+   */
+  constructor(app: Application);
+  /**
+   * This method can register view engine.
+   *
+   * You can define a view engine class contains two method, `render` and `renderString`
+   *
+   * ```js
+   * class View {
+   *   render() {}
+   *   renderString() {}
+   * }
+   * ```
+   * @param {String} name - the name of view engine
+   * @param {Object} viewEngine - the class of view engine
+   */
+  use(name: string, viewEngine: ViewEngineClass): void;
+  /**
+   * Resolve the path based on the given name,
+   * if the name is `user.html` and root is `app/view` (by default),
+   * it will return `app/view/user.html`
+   * @param {String} name - the given path name, it's relative to config.root
+   * @return {String} filename - the full path
+   */
+  resolve(name: string): Promise<string>;
+}
+//#endregion
+export { PlainObject, RenderOptions, ViewEngine, ViewEngineClass, ViewManager, ViewManagerConfig };

package/dist/lib/view_manager.js

@@ -0,0 +1,83 @@
+import path from "node:path";
+import assert from "node:assert";
+import { existsSync } from "node:fs";
+import { exists } from "utility";
+import { isGeneratorFunction } from "is-type-of";
+
+//#region src/lib/view_manager.ts
+/**
+* ViewManager will manage all view engine that is registered.
+*
+* It can find the real file, then retrieve the view engine based on extension.
+* The plugin just register view engine using {@link ViewManager#use}
+*/
+var ViewManager = class extends Map {
+	config;
+	extMap;
+	fileMap;
+	/**
+	* @param {Application} app - application instance
+	*/
+	constructor(app) {
+		super();
+		this.config = app.config.view;
+		this.config.root = app.config.view.root.split(/\s*,\s*/g).filter((filepath) => existsSync(filepath));
+		this.extMap = /* @__PURE__ */ new Map();
+		this.fileMap = /* @__PURE__ */ new Map();
+		for (const ext of Object.keys(this.config.mapping)) this.extMap.set(ext, this.config.mapping[ext]);
+	}
+	/**
+	* This method can register view engine.
+	*
+	* You can define a view engine class contains two method, `render` and `renderString`
+	*
+	* ```js
+	* class View {
+	*   render() {}
+	*   renderString() {}
+	* }
+	* ```
+	* @param {String} name - the name of view engine
+	* @param {Object} viewEngine - the class of view engine
+	*/
+	use(name, viewEngine) {
+		assert(name, "name is required");
+		assert(!this.has(name), `${name} has been registered`);
+		assert(viewEngine, "viewEngine is required");
+		assert(viewEngine.prototype.render, "viewEngine should implement `render` method");
+		assert(!isGeneratorFunction(viewEngine.prototype.render), "viewEngine `render` method should not be generator function");
+		assert(viewEngine.prototype.renderString, "viewEngine should implement `renderString` method");
+		assert(!isGeneratorFunction(viewEngine.prototype.renderString), "viewEngine `renderString` method should not be generator function");
+		this.set(name, viewEngine);
+	}
+	/**
+	* Resolve the path based on the given name,
+	* if the name is `user.html` and root is `app/view` (by default),
+	* it will return `app/view/user.html`
+	* @param {String} name - the given path name, it's relative to config.root
+	* @return {String} filename - the full path
+	*/
+	async resolve(name) {
+		const config = this.config;
+		let filename = this.fileMap.get(name);
+		if (config.cache && filename) return filename;
+		filename = await resolvePath([name, name + config.defaultExtension], config.root);
+		assert(filename, `Can't find ${name} from ${config.root.join(",")}`);
+		this.fileMap.set(name, filename);
+		return filename;
+	}
+};
+async function resolvePath(names, root) {
+	for (const name of names) for (const dir of root) {
+		const filename = path.join(dir, name);
+		if (await exists(filename)) {
+			if (inpath(dir, filename)) return filename;
+		}
+	}
+}
+function inpath(parent, sub) {
+	return sub.indexOf(parent) > -1;
+}
+
+//#endregion
+export { ViewManager };

package/dist/types.d.ts

@@ -0,0 +1,28 @@
+import { ViewConfig } from "./config/config.default.js";
+import { RenderOptions, ViewManager } from "./lib/view_manager.js";
+import { ContextView } from "./lib/context_view.js";
+
+//#region src/types.d.ts
+declare module 'egg' {
+  interface EggAppConfig {
+    /**
+     * view default config
+     * @member Config#view
+     * @property {String} [root=${baseDir}/app/view] - give a path to find the file, you can specify multiple path with `,` delimiter
+     * @property {Boolean} [cache=true] - whether cache the file's path
+     * @property {String} [defaultExtension] - defaultExtension can be added automatically when there is no extension  when call `ctx.render`
+     * @property {String} [defaultViewEngine] - set the default view engine if you don't want specify the viewEngine every request.
+     * @property {Object} mapping - map the file extension to view engine, such as `{ '.ejs': 'ejs' }`
+     */
+    view: ViewConfig;
+  }
+  interface Application {
+    get view(): ViewManager;
+  }
+  interface Context {
+    view: ContextView;
+    render(name: string, locals?: Record<string, any>, options?: RenderOptions): Promise<void>;
+    renderView(name: string, locals?: Record<string, any>, options?: RenderOptions): Promise<string>;
+    renderString(tpl: string, locals?: Record<string, any>, options?: RenderOptions): Promise<string>;
+  }
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {  };