html-express-js 3.0.6 → 3.1.0

package/README.md

@@ -23,7 +23,7 @@ The following is a high level example of how the package can be used as an Expre
 Set up your Express app to use this engine:
 
 ```js
-import htmlExpress from 'html-express-js';
+import htmlExpress, { renderView } from 'html-express-js';
 
 const app = express();
 const __dirname = resolve();
@@ -47,7 +47,7 @@ app.set('views', viewsDir);
 
 // render HTML in public/homepage.js with data
 app.get('/', function (req, res, next) {
-  res.render('homepage', {
+  renderView('homepage', req, res, {
     title: 'Awesome Homepage',
     name: 'Bob',
   });
@@ -101,7 +101,7 @@ export const view = (data, state) => html`
 The following shows an example of showing a logged out state based on the cookie on a request.
 
 ```js
-import htmlExpress from 'html-express-js';
+import htmlExpress, { renderView } from 'html-express-js';
 
 const app = express();
 const __dirname = resolve();
@@ -127,7 +127,7 @@ app.set('view engine', 'js');
 app.set('views', viewsDir);
 
 app.get('/', function (req, res, next) {
-  res.render('homepage');
+  renderView('homepage', req, res);
 });
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "html-express-js",
-  "version": "3.0.6",
+  "version": "3.1.0",
   "description": "An Express template engine to render HTML views using native JavaScript",
   "main": "src/index.js",
   "type": "module",
@@ -45,6 +45,7 @@
     "@types/chai": "^4.3.13",
     "@types/express": "^4.17.21",
     "@types/mocha": "^10.0.6",
+    "@types/reload": "^3.2.3",
     "@types/sinon": "^17.0.3",
     "chai": "^5.1.0",
     "chokidar": "^3.5.3",

package/src/index.d.ts

@@ -1,3 +1,13 @@
+/**
+ * Renders a JS HTML file and adds all includes to state object.
+ *
+ * @param {string} filePath - The path to html file
+ * @param {import('express').Request} req
+ * @param {import('express').Response} res
+ * @param {Record<string, any>} [data]
+ * @returns {Promise<void>} HTML with includes available (appended to state)
+ */
+export function renderView(filePath: string, req: import('express').Request, res: import('express').Response, data?: Record<string, any> | undefined): Promise<void>;
 /**
  * Template literal that supports string
  * interpolating in passed HTML.
@@ -17,10 +27,11 @@ export function html(strings: any, ...data: any[]): string;
  * engine: Parameters<import('express').Application['engine']>[1],
  * }}
  */
-export default function _default(opts?: HTMLExpressOptions): {
+export default function _default(opts?: HTMLExpressOptions | undefined): {
     staticIndexHandler: HTMLExpressStaticIndexHandler;
-    engine: [ext: string, fn: (path: string, options: object, callback: (e: any, rendered?: string) => void) => void][1];
+    engine: [ext: string, fn: (path: string, options: object, callback: (e: any, rendered?: string | undefined) => void) => void][1];
 };
+export type HTMLExpressStaticIndexHandler = () => import('express').RequestHandler;
 export type HTMLExpressBuildStateHandler = (req: import('express').Request) => Record<string, any>;
 export type HTMLExpressOptions = {
     /**
@@ -31,18 +42,21 @@ export type HTMLExpressOptions = {
      * - The directory that houses all of the includes
      * that will be available on the includes property of each static page.
      */
-    includesDir?: string;
+    includesDir?: string | undefined;
     /**
      * - The path of a file relative to the views
      * directory that should be served as 404 when no matching index page exists. Defaults to `404/index`.
      */
-    notFoundView?: string;
+    notFoundView?: string | undefined;
     /**
      * - A callback function that allows for
      * building a state object from request information, that will be merged with default state and made available to all views
      */
-    buildRequestState?: HTMLExpressBuildStateHandler;
+    buildRequestState?: HTMLExpressBuildStateHandler | undefined;
+};
+export type HTMLExpressViewState = Record<string, string> & {
+    includes: Record<string, string>;
 };
-export type HTMLExpressStaticIndexHandler = (options?: HTMLExpressOptions) => import('express').RequestHandler;
-declare function staticIndexHandler(options?: HTMLExpressOptions): import('express').RequestHandler;
+export type HTMLExpressView<D extends Record<string, any> = Record<string, any>> = (data: D, state: HTMLExpressViewState) => string;
+declare function staticIndexHandler(): import('express').RequestHandler;
 export {};

package/src/index.js

@@ -19,6 +19,40 @@ import { stat } from 'fs/promises';
  * building a state object from request information, that will be merged with default state and made available to all views
  */
 
+/**
+ * @typedef {Record<string, string> & {
+ * includes: Record<string, string>
+ * }} HTMLExpressViewState
+ */
+
+/**
+ * @template {Record<string, any>} [D=Record<string, any>]
+ * @callback HTMLExpressView
+ * @param {D} data
+ * @param {HTMLExpressViewState} state
+ * @returns {string}
+ */
+
+/**
+ * @type {string}
+ */
+let includesDir = '';
+
+/**
+ * @type {string}
+ */
+let viewsDir = '';
+
+/**
+ * @type {HTMLExpressBuildStateHandler | undefined}
+ */
+let buildRequestState;
+
+/**
+ * @type {string}
+ */
+let notFoundView = `404/index`;
+
 /**
  * Renders an HTML template in a file.
  *
@@ -28,7 +62,7 @@ import { stat } from 'fs/promises';
  * @param {object} [state] - Page-level attributes
  * @returns {Promise<string>} HTML
  */
-async function renderHtmlFileTemplate(path, data, state) {
+async function renderFileTemplate(path, data, state) {
   const { view } = await import(path);
   const rendered = view(data, state);
   let html = '';
@@ -38,31 +72,41 @@ async function renderHtmlFileTemplate(path, data, state) {
   return html;
 }
 
+/**
+ * Renders a JS HTML file and adds all includes to state object.
+ *
+ * @param {string} filePath - The path to html file
+ * @param {import('express').Request} req
+ * @param {import('express').Response} res
+ * @param {Record<string, any>} [data]
+ * @returns {Promise<void>} HTML with includes available (appended to state)
+ */
+export async function renderView(filePath, req, res, data = {}) {
+  const requestState = buildRequestState ? buildRequestState(req) : {};
+  const html = await buildViewHtml(filePath, data, requestState);
+  res.send(html);
+}
+
 /**
  * Renders a JS HTML file and adds all includes to state object.
  *
  * @param {string} filePath - The path to html file
  * @param {object} data - Data to be made available in view
- * @param {object} options - Options passed to original instantiation
- * @param {HTMLExpressOptions['includesDir']} options.includesDir
- * @param {Record<string, any>} [options.state]
+ * @param {Record<string, any>} [customState]
  * @returns {Promise<string>} HTML with includes available (appended to state)
  */
-async function renderHtmlFile(filePath, data = {}, options) {
-  const { includesDir } = options || {};
-  const state = options.state || {};
-  state.includes = {};
+async function buildViewHtml(filePath, data = {}, customState = {}) {
+  /**
+   * @type {Record<string, any>}
+   */
+  const state = { ...customState, includes: {} };
 
   const includeFilePaths = await glob(`${includesDir}/*.js`);
   for await (const includePath of includeFilePaths) {
     const key = basename(includePath, '.js');
-    state.includes[key] = await renderHtmlFileTemplate(
-      includePath,
-      data,
-      state,
-    );
+    state.includes[key] = await renderFileTemplate(includePath, data, state);
   }
-  return await renderHtmlFileTemplate(filePath, data, state);
+  return await renderFileTemplate(`${viewsDir}/${filePath}.js`, data, state);
 }
 
 /**
@@ -84,19 +128,16 @@ export function html(strings, ...data) {
 
 /**
  * @callback HTMLExpressStaticIndexHandler
- * @param {HTMLExpressOptions} [options]
  * @returns {import('express').RequestHandler}
  */
 
 /**
  * Attempts to render index.js pages when requesting to
- * directories and fallback to 404/index.js if doesnt exist.
+ * directories and fallback to 404 view if they don't exist.
  *
  * @type {HTMLExpressStaticIndexHandler}
  */
-function staticIndexHandler(options) {
-  const { viewsDir, notFoundView, includesDir, buildRequestState } = options;
-
+function staticIndexHandler() {
   return async function (req, res, next) {
     const { path: rawPath } = req;
     const fileExtension = extname(rawPath);
@@ -108,31 +149,17 @@ function staticIndexHandler(options) {
       ? `${pathWithoutPrecedingSlash}/index`
       : 'index';
 
-    const requestState = buildRequestState ? buildRequestState(req) : {};
-
-    const renderOptions = {
-      includesDir,
-      state: requestState,
-    };
     res.setHeader('Content-Type', 'text/html');
     try {
-      const absoluteFilePath = `${viewsDir}/${path}.js`;
-      await stat(absoluteFilePath); // check if file exists
-      const html = await renderHtmlFile(absoluteFilePath, {}, renderOptions);
-      res.send(html);
-    } catch (e) {
+      await stat(`${viewsDir}/${path}.js`); // check if file exists
+      await renderView(path, req, res);
+    } catch (err) {
+      const e = /** @type {Error & {code?: string}} */ (err);
       if (e.code !== 'ENOENT') {
         throw e;
       }
-      const notFoundViewPath = notFoundView || `404/index`;
-      const notFoundAbsoluteFilePath = `${viewsDir}/${notFoundViewPath}.js`;
-      const html = await renderHtmlFile(
-        notFoundAbsoluteFilePath,
-        {},
-        renderOptions,
-      );
       res.status(404);
-      res.send(html);
+      renderView(notFoundView, req, res);
     }
   };
 }
@@ -147,25 +174,20 @@ function staticIndexHandler(options) {
  * engine: Parameters<import('express').Application['engine']>[1],
  * }}
  */
-export default function (opts) {
-  const { buildRequestState, notFoundView, viewsDir } = opts;
-  const includesDir = opts.includesDir
-    ? opts.includesDir
-    : `${viewsDir}/includes`;
+export default function (
+  opts = {
+    viewsDir: '',
+  },
+) {
+  notFoundView = opts.notFoundView || notFoundView;
+  buildRequestState = opts.buildRequestState;
+  viewsDir = opts.viewsDir;
+  includesDir = opts.includesDir ? opts.includesDir : `${viewsDir}/includes`;
+
   return {
-    staticIndexHandler: (options) => {
-      return staticIndexHandler({
-        includesDir,
-        viewsDir,
-        notFoundView,
-        buildRequestState,
-        ...options,
-      });
-    },
+    staticIndexHandler,
     engine: async (filePath, data, callback) => {
-      const html = await renderHtmlFile(filePath, data, {
-        includesDir,
-      });
+      const html = await buildViewHtml(filePath, data);
       return callback(null, html);
     },
   };