npm - html-express-js - Versions diffs - 2.0.0 → 3.0.1 - Mend

html-express-js 2.0.0 → 3.0.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (20) hide show

package/README.md +89 -16
package/package.json +22 -7
package/src/index.d.ts +48 -0
package/src/index.js +93 -37
package/.github/dependabot.yml +0 -6
package/.github/workflows/dependabot-automerge.yml +0 -17
package/.husky/pre-commit +0 -4
package/.nvmrc +0 -1
package/.prettierignore +0 -8
package/.prettierrc.cjs +0 -3
package/.release-it.cjs +0 -13
package/.travis.yml +0 -8
package/example/app.js +0 -36
package/example/public/hello/index.js +0 -17
package/example/public/includes/head.js +0 -15
package/example/public/index.js +0 -21
package/example/public/main.css +0 -3
package/example/public/not-found.js +0 -15
package/example/server.js +0 -20
package/jsconfig.json +0 -9

package/README.md CHANGED Viewed

@@ -7,7 +7,8 @@
 ## Features
 - Serves HTML documents using template literals
-- Supports includes in served HTML documents
+- Supports includes in HTML documents
+- Allows shared global state throughout templates
 ## Installation
@@ -17,28 +18,32 @@ npm install html-express-js
 ## Basic Usage
-The following shows at a high level how the package can be used as an Express template engine. See [example](/example) directory for all details of a working implementation.
+The following is a high level example of how the package can be used as an Express template engine. See [example](/example) directory for all details of a working implementation.
 Set up your Express app to use this engine:
 ```js
-import htmlExpress, { staticIndexHandler } from 'html-express-js';
+import htmlExpress from 'html-express-js';
 const app = express();
 const __dirname = resolve();
+const viewsDir = `${__dirname}/public`;
+const { engine, staticIndexHandler } = htmlExpress({
+  viewsDir, // root views directory to serve all index.js files
+  includesDir: `${viewsDir}/includes`, // OPTIONAL: where all includes reside
+  notFoundView: '404/index', // OPTIONAL: relative to viewsDir above
+});
 // set up engine
-app.engine(
-  'js',
-  htmlExpress({
-    includesDir: 'includes', // where all includes reside
-  }),
-);
+app.engine('js', engine);
 // use engine
 app.set('view engine', 'js');
 // set directory where all index.js pages are served
-app.set('views', `${__dirname}/public`);
+app.set('views', viewsDir);
 // render HTML in public/homepage.js with data
 app.get('/', function (req, res, next) {
@@ -51,12 +56,7 @@ app.get('/', function (req, res, next) {
 // OPTIONALLY: route all GET requests to directories
 // to their associated static index.js views in the public directory
 // and, if not found, route to the 404/index.js view
-app.use(
-  staticIndexHandler({
-    viewsDir: `${__dirname}/public`, // root views directory to serve all index.js files
-    notFoundView: '404/index', // relative to viewsDir above
-  }),
-);
+app.use(staticIndexHandler());
 ```
 Then you can create the associated files:
@@ -93,3 +93,76 @@ export const view = (data, state) => html`
   </html>
 `;
 ```
+## Advanced usage
+### Injecting and using state based on a request
+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';
+const app = express();
+const __dirname = resolve();
+const viewsDir = `${__dirname}/public`;
+const { engine, staticIndexHandler } = htmlExpress({
+  viewsDir,
+  /**
+   * Inject global state into all views based on cookie
+   */
+  buildRequestState: (req) => {
+    if (req.cookies['authed']) {
+      return {
+        loggedIn: true,
+      };
+    }
+  },
+});
+app.engine('js', engine);
+app.set('view engine', 'js');
+app.set('views', viewsDir);
+app.get('/', function (req, res, next) {
+  res.render('homepage');
+});
+```
+```js
+// public/homepage.js
+import { html } from 'html-express-js';
+export const view = (data, state) => {
+  const { loggedIn } = state;
+  return html`
+    <!doctype html>
+    <html lang="en">
+      <head>
+        <title>${data.title}</title>
+      </head>
+      <body>
+        ${loggedIn ? `<a href="/logout">Logout</a>` : 'Not logged in'}
+      </body>
+    </html>
+  `;
+};
+```
+## Development
+Run site in examples directory
+```bash
+npm start
+```
+Run tests
+```bash
+npm test
+```

package/package.json CHANGED Viewed

@@ -1,17 +1,25 @@
 {
   "name": "html-express-js",
-  "version": "2.0.0",
+  "version": "3.0.1",
   "description": "An Express template engine to render HTML views using native JavaScript",
   "main": "src/index.js",
   "type": "module",
   "engines": {
     "node": ">=16"
   },
+  "files": [
+    "src/index.js",
+    "src/index.d.ts"
+  ],
   "scripts": {
-    "format": "prettier --write '**/*'",
-    "test": "prettier --check '**/*'",
+    "format": "prettier --write '**/*' --log-level=warn",
+    "format-check": "prettier --check '**/*' --ignore-unknown",
+    "test": "npm run test:src && npm run type-check && npm run format-check",
+    "test:src": "mocha src/**/*.tests.js",
     "start": "node ./example/server.js",
-    "prepare": "husky install"
+    "type-check": "tsc -p tsconfig.json",
+    "prepare": "husky install",
+    "build": "tsc -p tsconfig.build.json"
   },
   "repository": {
     "type": "git",
@@ -34,12 +42,19 @@
     "glob": "^10.2.2"
   },
   "devDependencies": {
-    "@types/glob": "^8.1.0",
+    "@types/chai": "^4.3.13",
+    "@types/express": "^4.17.21",
+    "@types/mocha": "^10.0.6",
+    "@types/sinon": "^17.0.3",
+    "chai": "^5.1.0",
     "chokidar": "^3.5.3",
     "express": "^4.18.1",
     "husky": "^9.0.7",
+    "mocha": "^10.3.0",
     "prettier": "^3.0.3",
-    "release-it": "^17.0.0",
-    "reload": "^3.2.0"
+    "release-it": "^17.1.1",
+    "reload": "^3.2.0",
+    "sinon": "^17.0.1",
+    "typescript": "^5.4.3"
   }
 }

package/src/index.d.ts ADDED Viewed

@@ -0,0 +1,48 @@
+/**
+ * Template literal that supports string
+ * interpolating in passed HTML.
+ *
+ * @param {*} strings
+ * @param  {...any} data
+ * @returns {string} - HTML string
+ */
+export function html(strings: any, ...data: any[]): string;
+/**
+ * Returns an object containing both static
+ * index handler and the template engine callback.
+ *
+ * @param {HTMLExpressOptions} [opts]
+ * @returns {{
+ * staticIndexHandler: HTMLExpressStaticIndexHandler,
+ * engine: Parameters<import('express').Application['engine']>[1],
+ * }}
+ */
+export default function _default(opts?: HTMLExpressOptions): {
+    staticIndexHandler: HTMLExpressStaticIndexHandler;
+    engine: [ext: string, fn: (path: string, options: object, callback: (e: any, rendered?: string) => void) => void][1];
+};
+export type HTMLExpressBuildStateHandler = (req: import('express').Request) => Record<string, any>;
+export type HTMLExpressOptions = {
+    /**
+     * - The directory that houses any potential index files
+     */
+    viewsDir: string;
+    /**
+     * - The directory that houses all of the includes
+     * that will be available on the includes property of each static page.
+     */
+    includesDir?: string;
+    /**
+     * - 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;
+    /**
+     * - 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;
+};
+export type HTMLExpressStaticIndexHandler = (options?: HTMLExpressOptions) => import('express').RequestHandler;
+declare function staticIndexHandler(options?: HTMLExpressOptions): import('express').RequestHandler;
+export {};

package/src/index.js CHANGED Viewed

@@ -2,6 +2,23 @@ import { basename, extname } from 'path';
 import { glob } from 'glob';
 import { stat } from 'fs/promises';
+/**
+ * @callback HTMLExpressBuildStateHandler
+ * @param {import('express').Request} req
+ * @returns {Record<string, any>}
+ */
+/**
+ * @typedef {object} HTMLExpressOptions
+ * @property {string} viewsDir - The directory that houses any potential index files
+ * @property {string} [includesDir] - The directory that houses all of the includes
+ * that will be available on the includes property of each static page.
+ * @property {string} [notFoundView] - 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`.
+ * @property {HTMLExpressBuildStateHandler} [buildRequestState] - 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
+ */
 /**
  * Renders an HTML template in a file.
  *
@@ -26,14 +43,15 @@ async function renderHtmlFileTemplate(path, data, state) {
  *
  * @param {string} filePath - The path to html file
  * @param {object} data - Data to be made available in view
- * @param {object} instanceOptions - Options passed to original instantiation
+ * @param {object} options - Options passed to original instantiation
+ * @param {HTMLExpressOptions['includesDir']} options.includesDir
+ * @param {Record<string, any>} [options.state]
  * @returns {Promise<string>} HTML with includes available (appended to state)
  */
-async function renderHtmlFile(filePath, data = {}, instanceOptions = {}) {
-  const state = {
-    includes: {},
-  };
-  const { includesDir } = instanceOptions;
+async function renderHtmlFile(filePath, data = {}, options) {
+  const { includesDir } = options || {};
+  const state = options.state || {};
+  state.includes = {};
   const includeFilePaths = await glob(`${includesDir}/*.js`);
   for await (const includePath of includeFilePaths) {
@@ -48,7 +66,9 @@ async function renderHtmlFile(filePath, data = {}, instanceOptions = {}) {
 }
 /**
- * Template literal that supports string interpolating in passed HTML.
+ * Template literal that supports string
+ * interpolating in passed HTML.
+ *
  * @param {*} strings
  * @param  {...any} data
  * @returns {string} - HTML string
@@ -59,22 +79,23 @@ export function html(strings, ...data) {
     const exp = data[i] || '';
     rawHtml += str + exp;
   }
-  const html = rawHtml.replace(/[\n\r]/g, '');
-  return html;
+  return rawHtml;
 }
+/**
+ * @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.
  *
- * @param {object} [options]
- * @param {object} options.viewsDir - The directory that houses any potential index files
- * @param {string} [options.notFoundView] - 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`.
- * @returns {import('express').RequestHandler} - Middleware function
+ * @type {HTMLExpressStaticIndexHandler}
  */
-export function staticIndexHandler(options) {
-  const notFoundView = options.notFoundView || `404/index`;
+function staticIndexHandler(options) {
+  const { viewsDir, notFoundView, includesDir, buildRequestState } = options;
   return async function (req, res, next) {
     const { path: rawPath } = req;
@@ -82,39 +103,74 @@ export function staticIndexHandler(options) {
     if (fileExtension) {
       return next();
     }
-    const sanitizedPath = rawPath.replace('/', ''); // remove beginning slash
-    const path = sanitizedPath ? `${sanitizedPath}/index` : 'index';
+    const pathWithoutPrecedingSlash = rawPath.replace('/', ''); // remove beginning slash
+    const path = pathWithoutPrecedingSlash
+      ? `${pathWithoutPrecedingSlash}/index`
+      : 'index';
+    const requestState = buildRequestState ? buildRequestState(req) : {};
+    const renderOptions = {
+      includesDir,
+      state: requestState,
+    };
+    res.setHeader('Content-Type', 'text/html');
     try {
-      await stat(`${options.viewsDir}/${path}.js`); // check if file exists
-      res.render(path);
+      const absoluteFilePath = `${viewsDir}/${path}.js`;
+      await stat(absoluteFilePath); // check if file exists
+      const html = await renderHtmlFile(absoluteFilePath, {}, renderOptions);
+      res.send(html);
     } catch (e) {
       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.render(notFoundView);
+      res.send(html);
     }
   };
 }
 /**
- * Returns a template engine view function.
+ * Returns an object containing both static
+ * index handler and the template engine callback.
  *
- * @param {object} [opts]
- * @param {object} [opts.includesDir]
- * @returns {(path: string, options: object, callback: (e: any, rendered?: string) => void) => void}
+ * @param {HTMLExpressOptions} [opts]
+ * @returns {{
+ * staticIndexHandler: HTMLExpressStaticIndexHandler,
+ * engine: Parameters<import('express').Application['engine']>[1],
+ * }}
  */
-export default function (opts = {}) {
-  return async (filePath, data, callback) => {
-    const viewsDir = data.settings.views;
-    const includePath = opts.includesDir || 'includes';
-    const sanitizedOptions = {
-      viewsDir,
-      includesDir: `${viewsDir}/${includePath}`,
-    };
-    const html = await renderHtmlFile(filePath, data, sanitizedOptions);
-    return callback(null, html);
+export default function (opts) {
+  const { buildRequestState, notFoundView, viewsDir } = opts;
+  const includesDir = opts.includesDir
+    ? opts.includesDir
+    : `${viewsDir}/includes`;
+  return {
+    staticIndexHandler: (options) => {
+      return staticIndexHandler({
+        includesDir,
+        viewsDir,
+        notFoundView,
+        buildRequestState,
+        ...options,
+      });
+    },
+    engine: async (filePath, data, callback) => {
+      const html = await renderHtmlFile(
+        filePath,
+        {},
+        {
+          includesDir,
+        },
+      );
+      return callback(null, html);
+    },
   };
 }

package/.github/dependabot.yml DELETED Viewed

@@ -1,6 +0,0 @@
-version: 2
-updates:
-  - package-ecosystem: npm
-    directory: '/'
-    schedule:
-      interval: monthly

package/.github/workflows/dependabot-automerge.yml DELETED Viewed

@@ -1,17 +0,0 @@
-name: Dependabot auto-merge
-on: pull_request
-permissions:
-  pull-requests: write
-  contents: write
-jobs:
-  dependabot:
-    runs-on: ubuntu-latest
-    if: ${{ github.actor == 'dependabot[bot]' }}
-    steps:
-      - name: Enable auto-merge for Dependabot PRs
-        run: gh pr merge --auto --squash "$PR_URL"
-        env:
-          PR_URL: ${{github.event.pull_request.html_url}}
-          GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}

package/.husky/pre-commit DELETED Viewed

@@ -1,4 +0,0 @@
-#!/usr/bin/env sh
-. "$(dirname -- "$0")/_/husky.sh"
-npm run format

package/.nvmrc DELETED Viewed

	@@ -1 +0,0 @@
1	- 16

package/.prettierignore DELETED Viewed

@@ -1,8 +0,0 @@
-package*.json
-node_modules
-.husky
-LICENSE
-.gitignore
-.npmrc
-.prettierignore
-.nvmrc

package/.prettierrc.cjs DELETED Viewed

@@ -1,3 +0,0 @@
-module.exports = {
-  singleQuote: true,
-};

package/.release-it.cjs DELETED Viewed

@@ -1,13 +0,0 @@
-module.exports = {
-  git: {
-    commitMessage: '${version}',
-    tagName: 'v${version}',
-  },
-  github: {
-    release: true,
-    releaseName: '${version}',
-  },
-  hooks: {
-    'before:init': ['npm test'],
-  },
-};

package/.travis.yml DELETED Viewed

@@ -1,8 +0,0 @@
-language: node_js
-node_js:
-  - '16'
-branches:
-  only:
-    - master
-script:
-  - npm test

package/example/app.js DELETED Viewed

@@ -1,36 +0,0 @@
-import express from 'express';
-import { resolve } from 'path';
-import htmlExpress, { staticIndexHandler } from '../src/index.js';
-const __dirname = resolve();
-const app = express();
-app.engine(
-  'js',
-  htmlExpress({
-    includesDir: 'includes',
-  }),
-);
-app.set('view engine', 'js');
-app.set('views', `${__dirname}/example/public`);
-// serve all other static files like CSS, images, etc
-app.use(express.static(`${__dirname}/example/public`));
-app.get('/hello', async function (req, res) {
-  res.render('hello', {
-    name: 'world',
-  });
-});
-// Automatically serve any index.js file as HTML in the public directory
-app.use(
-  staticIndexHandler({
-    viewsDir: `${__dirname}/example/public`,
-    notFoundView: 'not-found', // OPTIONAL: defaults to `404/index`
-  }),
-);
-export default app;

package/example/public/hello/index.js DELETED Viewed

@@ -1,17 +0,0 @@
-import { html } from '../../../src/index.js';
-export const view = (data, state) => html`
-  <!doctype html>
-  <html lang="en">
-    <head>
-      ${state.includes.head}
-      <title>Hello!</title>
-    </head>
-    <body>
-      <h1>Hello, ${data.name}!</h1>
-      <p>Click <a href="/">here</a> to go back to the dashboard.</p>
-    </body>
-  </html>
-`;

package/example/public/includes/head.js DELETED Viewed

@@ -1,15 +0,0 @@
-import { html } from '../../../src/index.js';
-export const view = (/*data, state*/) => html`
-  <meta charset="utf-8" />
-  <meta http-equiv="X-UA-Compatible" content="IE=edge" />
-  <meta
-    name="viewport"
-    content="width=device-width, initial-scale=1, maximum-scale=1.0, user-scalable=0"
-  />
-  <link rel="stylesheet" href="/main.css" />
-  <!-- For HMR! -->
-  <script src="/reload/reload.js"></script>
-`;

package/example/public/index.js DELETED Viewed

@@ -1,21 +0,0 @@
-import { html } from '../../src/index.js';
-export const view = (data, state) => html`
-  <!doctype html>
-  <html lang="en">
-    <head>
-      ${state.includes.head}
-      <title>Dashboard</title>
-    </head>
-    <body>
-      <h1>This is the dashboard!</h1>
-      <p>
-        This file is served by the <code>staticIndexHandler</code> in app.js
-      </p>
-      <p>Click <a href="/hello">here</a> to go hello route.</p>
-    </body>
-  </html>
-`;

package/example/public/main.css DELETED Viewed

@@ -1,3 +0,0 @@
-body {
-  background-color: lightgray;
-}

package/example/public/not-found.js DELETED Viewed

@@ -1,15 +0,0 @@
-import { html } from '../../src/index.js';
-export const view = (data, state) => html`
-  <!doctype html>
-  <html lang="en">
-    <head>
-      ${state.includes.head}
-      <title>404</title>
-    </head>
-    <body>
-      Not found!
-    </body>
-  </html>
-`;

package/example/server.js DELETED Viewed

@@ -1,20 +0,0 @@
-import app from './app.js';
-import reload from 'reload';
-import chokidar from 'chokidar';
-const port = 2222;
-// reload browser on file changes
-reload(app, { verbose: true })
-  .then(function (reloadReturned) {
-    chokidar.watch(['./src', './example']).on('all', (/*event, path*/) => {
-      reloadReturned.reload();
-    });
-    app.listen(port, function () {
-      console.log(`Server started at http://localhost:${port}`);
-    });
-  })
-  .catch(function (err) {
-    console.error('Reload could not start, could not start example app', err);
-  });

package/jsconfig.json DELETED Viewed

@@ -1,9 +0,0 @@
-{
-  "compilerOptions": {
-    "checkJs": true,
-    "maxNodeModuleJsDepth": 1,
-    "moduleResolution": "nodenext",
-    "module": "nodenext",
-    "target": "es2022"
-  }
-}