@tsed/platform-views 8.0.1 → 8.0.3

package/package.json

@@ -2,13 +2,14 @@
   "name": "@tsed/platform-views",
   "description": "Views module for Ts.ED Framework",
   "type": "module",
-  "version": "8.0.1",
+  "version": "8.0.3",
   "source": "./src/index.ts",
   "main": "./lib/esm/index.js",
   "module": "./lib/esm/index.js",
   "typings": "./lib/types/index.d.ts",
   "exports": {
     ".": {
+      "@tsed/source": "./src/index.ts",
       "types": "./lib/types/index.d.ts",
       "import": "./lib/esm/index.js",
       "default": "./lib/esm/index.js"
@@ -21,29 +22,29 @@
     "test:ci": "vitest run --coverage.thresholds.autoUpdate=true"
   },
   "dependencies": {
-    "@tsed/engines": "8.0.1",
+    "@tsed/engines": "8.0.3",
     "ejs": "^3.1.10",
     "tslib": "2.7.0"
   },
   "devDependencies": {
-    "@tsed/barrels": "8.0.1",
-    "@tsed/core": "8.0.1",
-    "@tsed/di": "8.0.1",
-    "@tsed/engines": "8.0.1",
-    "@tsed/exceptions": "8.0.1",
-    "@tsed/schema": "8.0.1",
-    "@tsed/typescript": "8.0.1",
+    "@tsed/barrels": "8.0.3",
+    "@tsed/core": "8.0.3",
+    "@tsed/di": "8.0.3",
+    "@tsed/engines": "8.0.3",
+    "@tsed/exceptions": "8.0.3",
+    "@tsed/schema": "8.0.3",
+    "@tsed/typescript": "8.0.3",
     "@types/ejs": "3.1.5",
     "eslint": "9.12.0",
     "typescript": "5.4.5",
     "vitest": "2.1.2"
   },
   "peerDependencies": {
-    "@tsed/core": "8.0.1",
-    "@tsed/di": "8.0.1",
-    "@tsed/engines": "8.0.1",
-    "@tsed/exceptions": "8.0.1",
-    "@tsed/schema": "8.0.1"
+    "@tsed/core": "8.0.3",
+    "@tsed/di": "8.0.3",
+    "@tsed/engines": "8.0.3",
+    "@tsed/exceptions": "8.0.3",
+    "@tsed/schema": "8.0.3"
   },
   "peerDependenciesMeta": {
     "@tsed/core": {

package/src/decorators/view.ts

@@ -0,0 +1,6 @@
+import {View as W} from "@tsed/schema";
+
+/**
+ * @deprecated Use View from @tsed/schema package.
+ */
+export const View: typeof W = W;

package/src/domain/PlatformViewsSettings.ts

@@ -0,0 +1,101 @@
+import {BaseContext} from "@tsed/di";
+import {Writable} from "stream";
+
+export const PLATFORM_VIEWS_EXTENSIONS = {
+  atpl: "atpl",
+  bracket: "bracket",
+  dot: "dot",
+  dust: "dust",
+  ect: "ect",
+  ejs: "ejs",
+  haml: "haml",
+  "haml-coffee": "haml-coffee",
+  hamlet: "hamlet",
+  hbs: "handlebars",
+  handlebars: "handlebars",
+  hogan: "hogan",
+  htmling: "htmling",
+  jazz: "jazz",
+  jqtpl: "jqtpl",
+  just: "just",
+  kernel: "kernel",
+  liquid: "liquid",
+  liquor: "liquor",
+  lodash: "lodash",
+  mote: "mote",
+  mustache: "mustache",
+  nunjucks: "nunjucks",
+  plates: "plates",
+  pug: "pug",
+  qejs: "qejs",
+  ractive: "ractive",
+  razor: "razor",
+  jsx: "react",
+  slm: "slm",
+  squirelly: "squirelly",
+  swig: "swig",
+  teacup: "teacup",
+  templayed: "templayed",
+  twig: "twig",
+  underscore: "underscore",
+  vash: "vash",
+  velocityjs: "velocityjs",
+  walrus: "walrus",
+  whiskers: "whiskers"
+};
+
+export type PlatformViewsExtensionsTypes = Record<string, string>;
+
+export interface PlatformViewsEngineOptions extends Record<string, unknown> {
+  requires?: any;
+}
+
+export interface PlatformRenderOptions extends Record<string, unknown> {
+  $ctx: BaseContext;
+}
+
+export interface PlatformViewWritableStream {
+  pipe(stream: Writable): void;
+}
+
+export interface PlatformViewEngine {
+  options: PlatformViewsEngineOptions;
+
+  render(path: string, options: PlatformRenderOptions): Promise<string | PlatformViewWritableStream>;
+}
+
+export interface PlatformViewsSettings {
+  disabled?: boolean;
+  /**
+   * Views directory.
+   */
+  root?: string;
+  /**
+   * Enable cache. Ts.ED enable cache in PRODUCTION profile by default.
+   */
+  cache?: boolean;
+  /**
+   * Provide extensions mapping to match the expected engines.
+   */
+  extensions?: Partial<PlatformViewsExtensionsTypes>;
+  /**
+   * Default view engine extension.
+   * Allow omitting extension when using View decorator or render method.
+   */
+  viewEngine?: string;
+  /**
+   * Options mapping for each engine.
+   */
+  options?: Record<string, PlatformViewsEngineOptions>;
+}
+
+declare global {
+  namespace TsED {
+    interface Configuration {
+      /**
+       * Object to configure Views engines with Consolidate. See more on [View engine](/docs/template-engine.md).
+       */
+      views: PlatformViewsSettings;
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from "./decorators/view.js";
+export * from "./domain/PlatformViewsSettings.js";
+export * from "./services/PlatformViews.js";
+export {PlatformViews as default} from "./services/PlatformViews.js";

package/src/services/PlatformViews.spec.ts

@@ -0,0 +1,88 @@
+import {Injectable} from "@tsed/di";
+import {requires} from "@tsed/engines";
+import {PlatformTest} from "@tsed/platform-http/testing";
+
+import {PlatformViews} from "./PlatformViews.js";
+
+@Injectable()
+class AlterOptions {
+  $alterRenderOptions(options: any) {
+    options.alter = "alter";
+    return Promise.resolve(options);
+  }
+}
+
+describe("PlatformViews", () => {
+  beforeEach(() =>
+    PlatformTest.create({
+      views: {
+        extensions: {
+          ejs: "ejs"
+        },
+        viewEngine: "ejs",
+        options: {
+          ejs: {
+            global: "global",
+            requires: "requires"
+          }
+        }
+      }
+    })
+  );
+  afterEach(() => {
+    requires.delete("ejs");
+  });
+  afterEach(() => PlatformTest.reset());
+
+  describe("render()", () => {
+    it("should render a template with given extension", async () => {
+      const platformViews = PlatformTest.get<PlatformViews>(PlatformViews);
+      const engine = platformViews.getEngine("ejs")!;
+
+      vi.spyOn(engine, "render").mockResolvedValue("HTML");
+
+      const result = await platformViews.render("views.ejs");
+
+      expect(result).toEqual("HTML");
+      expect(engine.render).toHaveBeenCalledWith("views.ejs", {
+        cache: false,
+        alter: "alter",
+        global: "global",
+        requires: "requires"
+      });
+    });
+    it("should render a template without extension", async () => {
+      const platformViews = PlatformTest.get<PlatformViews>(PlatformViews);
+      const engine = platformViews.getEngine("ejs")!;
+
+      vi.spyOn(engine, "render").mockResolvedValue("HTML");
+
+      const result = await platformViews.render("views", {test: "test"});
+
+      expect(result).toEqual("HTML");
+      expect(engine.render).toHaveBeenCalledWith("views.ejs", {
+        cache: false,
+        global: "global",
+        test: "test",
+        alter: "alter",
+        requires: "requires"
+      });
+    });
+    it("should render a template without extension and catch error", async () => {
+      const platformViews = PlatformTest.get<PlatformViews>(PlatformViews);
+      const engine = platformViews.getEngine("ejs")!;
+
+      vi.spyOn(engine, "render").mockResolvedValue("HTML");
+
+      let error: any;
+
+      try {
+        await platformViews.render("views.toto", {test: "test"});
+      } catch (er) {
+        error = er;
+      }
+
+      expect(error.message).toEqual('Engine not found to render the following "views.toto"');
+    });
+  });
+});

package/src/services/PlatformViews.ts

@@ -0,0 +1,151 @@
+import "../domain/PlatformViewsSettings.js";
+
+import {Env, getValue} from "@tsed/core";
+import {constant, injectable, ProviderType} from "@tsed/di";
+import {engines, getEngine, requires} from "@tsed/engines";
+import {$asyncAlter} from "@tsed/hooks";
+import Fs from "fs";
+import {extname, join, resolve} from "path";
+
+import {
+  PLATFORM_VIEWS_EXTENSIONS,
+  PlatformViewEngine,
+  PlatformViewsEngineOptions,
+  PlatformViewsExtensionsTypes,
+  PlatformViewWritableStream
+} from "../domain/PlatformViewsSettings.js";
+
+async function patchEJS(ejs: any) {
+  if (!ejs) {
+    const mod = await import("ejs");
+    ejs = mod.default;
+  }
+
+  return {
+    compile(str: string, {client, ...options}: any) {
+      return ejs.compile(str, options);
+    }
+  };
+}
+
+/**
+ * @platform
+ */
+export class PlatformViews {
+  readonly root = constant("views.root", `${process.cwd()}/views`);
+  readonly cache = constant<boolean>("views.cache");
+  readonly disabled = constant<string | boolean>("views.disabled", false);
+  readonly viewEngine = constant<string>("views.viewEngine", "ejs");
+  protected env = constant<Env>("env");
+  protected extensionsOptions = constant<PlatformViewsExtensionsTypes>("views.extensions", {});
+  protected engineOptions = constant<Record<string, PlatformViewsEngineOptions>>("views.options", {});
+
+  #extensions: Map<string, string>;
+  #engines = new Map<string, PlatformViewEngine>();
+  #cachePaths = new Map<string, {path: string; extension: string}>();
+
+  async $onInit() {
+    if (!this.disabled) {
+      this.#extensions = new Map(
+        Object.entries({
+          ...PLATFORM_VIEWS_EXTENSIONS,
+          ...this.extensionsOptions
+        })
+      );
+
+      await this.loadEngines();
+    }
+  }
+
+  async loadEngines() {
+    requires.set("ejs", await patchEJS(requires.get("ejs")));
+
+    this.#extensions.forEach((engineType) => {
+      if (engines.has(engineType)) {
+        const options = this.getEngineOptions(engineType);
+
+        if (options.requires) {
+          requires.set(engineType, options.requires);
+        }
+
+        this.registerEngine(engineType, {
+          options,
+          render: getEngine(engineType)
+        });
+      }
+    });
+  }
+
+  getEngines() {
+    return [...this.#extensions.entries()].map(([extension, engineType]) => {
+      const engine = this.getEngine(this.getExtension(engineType))!;
+
+      return {
+        extension,
+        engine
+      };
+    });
+  }
+
+  registerEngine(engineType: string, engine: PlatformViewEngine) {
+    this.#engines.set(engineType, engine);
+
+    return this;
+  }
+
+  getEngine(type: string) {
+    return this.#engines.get(this.#extensions.get(type) || type);
+  }
+
+  getEngineOptions(engineType: string): PlatformViewsEngineOptions {
+    return getValue(this.engineOptions, engineType, {});
+  }
+
+  async render(viewPath: string, options: any = {}): Promise<string | PlatformViewWritableStream> {
+    const {$ctx} = options;
+
+    options = await $asyncAlter("$alterRenderOptions", options, $ctx);
+
+    const {path, extension} = this.#cachePaths.get(viewPath) || this.#cachePaths.set(viewPath, this.resolve(viewPath)).get(viewPath)!;
+    const engine = this.getEngine(extension);
+
+    if (!engine) {
+      throw new Error(`Engine not found to render the following "${viewPath}"`);
+    }
+
+    const finalOpts = Object.assign({cache: this.cache || this.env === Env.PROD}, engine.options, options, {$ctx});
+
+    return engine.render(path, finalOpts);
+  }
+
+  protected getExtension(viewPath: string) {
+    return (extname(viewPath) || this.viewEngine).replace(/\./, "");
+  }
+
+  protected resolve(viewPath: string) {
+    const extension = this.getExtension(viewPath);
+
+    viewPath = viewPath.replace(extname(viewPath), "") + "." + extension;
+
+    const path =
+      [
+        viewPath,
+        resolve(join(this.root, viewPath)),
+        resolve(join(process.cwd(), "views", viewPath)),
+        resolve(join(process.cwd(), "public", viewPath))
+      ].find((file) => Fs.existsSync(file)) || viewPath;
+
+    return {
+      path,
+      extension
+    };
+  }
+}
+
+injectable(PlatformViews)
+  .type(ProviderType.MODULE)
+  .configuration({
+    views: {
+      exists: true
+    }
+  } as never);