express-hbs 4.0.1 → 4.1.0

package/README.md

@@ -79,6 +79,36 @@ hbs.express4({
 });
 ```
 
+## TypeScript
+
+Type declarations ship with the package (`index.d.ts`), so no `@types` package
+is needed:
+
+```ts
+import hbs = require('express-hbs');
+
+app.engine('hbs', hbs.express4({ partialsDir: __dirname + '/views/partials' }));
+```
+
+Supporting types such as `hbs.Options` and `hbs.AsyncHelperCallback` are
+available on the `hbs` namespace.
+
+Async helpers come in two forms, `(context, cb)` and `(context, options, cb)`.
+TypeScript infers parameter types for the first form only. For the second, add
+`satisfies hbs.AsyncHelperWithOptions` so the parameters are inferred:
+
+```ts
+hbs.registerAsyncHelper('lookup', function (context, options, cb) {
+  cb(options.hash.fallback ?? context);
+} satisfies hbs.AsyncHelperWithOptions);
+```
+
+Promise helpers infer `context` and `options` without `satisfies`:
+
+```ts
+hbs.registerPromiseHelper('lookup', async (context, options) => options.hash.fallback ?? context);
+```
+
 ## Syntax
 
 To mark where a layout should insert page content:
@@ -190,6 +220,41 @@ in markup
 {{{readFile 'tos.txt'}}}
 ```
 
+The value returned by an async helper is ignored; only `cb` delivers output.
+
+### Promise helpers
+
+`registerPromiseHelper` renders whatever the helper returns, waiting for it when
+it is a promise, so `async` functions work directly. The helper is called like a
+synchronous helper: template params first, then `options`.
+
+```js
+hbs.registerPromiseHelper('readFile', async function(filename, options) {
+  var content = await fs.promises.readFile(path.join(viewsDir, filename), 'utf8');
+  return new hbs.SafeString(content);
+});
+```
+
+in markup
+```
+{{readFile 'tos.txt'}}
+```
+
+- A rejected promise or a thrown error fails the render and is passed to the
+  render callback.
+- `null` and `undefined` render as an empty string.
+- Strings are escaped in `{{ }}` and not in `{{{ }}}`; return `hbs.SafeString`
+  to skip escaping.
+- The result is only available as output. Like async helpers, a promise helper
+  returns a placeholder that is replaced after rendering, so subexpressions and
+  block conditions such as `{{#if (enabled)}}` or `{{upper (readFile 'a')}}`
+  see the placeholder string, not the resolved value. Do that work inside the
+  helper instead.
+
+Use `registerAsyncHelper` for callback-style helpers. It does not wait for a
+returned promise, because an `async function (context, cb)` that calls `cb`
+later returns a promise that resolves to `undefined` first.
+
 
 ## i18n support
 

package/index.d.ts

@@ -0,0 +1,146 @@
+import Handlebars = require('handlebars');
+
+declare namespace hbs {
+  type HandlebarsEnvironment = typeof Handlebars;
+
+  /** Compiled Handlebars template, tagged with the file it came from when known. */
+  type CompiledTemplate = Handlebars.TemplateDelegate & { __filename?: string };
+
+  /** Minimal shape of the `i18n` module used to register the `__` and `__n` helpers. */
+  interface I18n {
+    __(...args: any[]): string;
+    __n(...args: any[]): string;
+  }
+
+  interface Options {
+    /** Path to partial templates; one directory or several. */
+    partialsDir?: string | string[];
+    /** Absolute path to a directory that layouts must reside in. */
+    restrictLayoutsTo?: string;
+    /** Name of the block helper. Defaults to `block`. */
+    blockHelperName?: string;
+    /** Name of the content helper. Defaults to `contentFor`. */
+    contentHelperName?: string;
+    /** Absolute path to the default layout template. */
+    defaultLayout?: string;
+    /** Extension for templates and partials. Defaults to `.hbs`. */
+    extname?: string;
+    /** Handlebars module to use instead of the bundled instance. */
+    handlebars?: HandlebarsEnvironment;
+    /** i18n object; registers the `__` and `__n` helpers. */
+    i18n?: I18n;
+    /** Path to layout templates. */
+    layoutsDir?: string;
+    /** Views directory used when not rendering through Express. */
+    viewsDir?: string | string[];
+    /** Options passed to every compiled template call. */
+    templateOptions?: Handlebars.RuntimeOptions;
+    /** Pretty-print rendered HTML with js-beautify. */
+    beautify?: boolean;
+    /** Override template compilation. */
+    onCompile?: (exhbs: ExpressHbs, source: string, filename?: string) => CompiledTemplate;
+  }
+
+  /** Locals passed to `res.render()` / the engine function. */
+  interface RenderOptions {
+    settings?: { views?: string | string[]; [key: string]: any };
+    cache?: boolean;
+    /**
+     * Layout to render with, or a falsy value to render without any layout.
+     *
+     * Passing user-controlled data here can read arbitrary files unless
+     * `restrictLayoutsTo` is set.
+     */
+    layout?: string | null | false | 0;
+    [key: string]: any;
+  }
+
+  type RenderCallback = (err: any, html?: string) => void;
+
+  /** Express-compatible view engine function. */
+  interface Engine {
+    (filename: string, options: RenderOptions, cb: RenderCallback): void;
+    (filename: string, source: string | null, options: RenderOptions, cb: RenderCallback): void;
+  }
+
+  type AsyncHelperCallback = (result: any) => void;
+
+  type AsyncHelper = (this: any, context: any, cb: AsyncHelperCallback) => void;
+
+  type AsyncHelperWithOptions = (
+    this: any,
+    context: any,
+    options: Handlebars.HelperOptions,
+    cb: AsyncHelperCallback,
+  ) => void;
+
+  /**
+   * Promise helper. Handlebars passes `(...params, options)`; this type covers
+   * the common one-param form so TypeScript can infer every parameter.
+   */
+  type PromiseHelper = (this: any, context: any, options: Handlebars.HelperOptions) => unknown;
+
+  interface ExpressHbs {
+    handlebars: HandlebarsEnvironment;
+    SafeString: typeof Handlebars.SafeString;
+    Utils: typeof Handlebars.Utils;
+
+    express3(options?: Options): Engine;
+    express4(options?: Options): Engine;
+
+    registerHelper(name: string, fn: Handlebars.HelperDelegate): void;
+    registerHelper(helpers: Handlebars.HelperDeclareSpec): void;
+    /**
+     * Register a helper that delivers its result later via `cb(result)`. The
+     * helper receives `options` only when it declares three parameters.
+     *
+     * TypeScript infers parameter types for the `(context, cb)` form. For the
+     * `(context, options, cb)` form, add `satisfies hbs.AsyncHelperWithOptions`
+     * to the function so its parameters are inferred.
+     *
+     * @example
+     * hbs.registerAsyncHelper('readFile', function (filename, cb) {
+     *   fs.readFile(filename, 'utf8', (err, content) => cb(content));
+     * });
+     *
+     * hbs.registerAsyncHelper('lookup', function (context, options, cb) {
+     *   cb(options.hash.fallback ?? context);
+     * } satisfies hbs.AsyncHelperWithOptions);
+     */
+    registerAsyncHelper(name: string, fn: AsyncHelper): void;
+    registerAsyncHelper(name: string, fn: AsyncHelperWithOptions): void;
+    /**
+     * Register a helper whose return value, or the value its promise resolves
+     * to, is rendered. A rejection or thrown error fails the render, and
+     * `null`/`undefined` render as an empty string. It is called like a sync
+     * helper, with the template params followed by `options`.
+     *
+     * The result is only usable as output: subexpressions and block conditions
+     * such as `{{#if (helper)}}` see a placeholder string, not the resolved value.
+     *
+     * @example
+     * hbs.registerPromiseHelper('readFile', async function (filename, options) {
+     *   return new hbs.SafeString(await fs.promises.readFile(filename, 'utf8'));
+     * });
+     */
+    registerPromiseHelper(name: string, fn: PromiseHelper): void;
+    registerPromiseHelper(name: string, fn: (this: any, ...args: any[]) => unknown): void;
+    registerPartial(name: string, source: string, filename?: string): void;
+    compile(source: string, filename?: string): CompiledTemplate;
+
+    getTemplateOptions(): Handlebars.RuntimeOptions;
+    updateTemplateOptions(templateOptions: Handlebars.RuntimeOptions): void;
+    getLocalTemplateOptions(locals: object): Handlebars.RuntimeOptions;
+    updateLocalTemplateOptions<T extends Handlebars.RuntimeOptions | undefined>(
+      locals: object,
+      localTemplateOptions: T,
+    ): T;
+
+    /** Creates an isolated instance with its own cache and Handlebars environment. */
+    create(): ExpressHbs;
+  }
+}
+
+declare const hbs: hbs.ExpressHbs;
+
+export = hbs;

package/lib/hbs.js

@@ -348,7 +348,7 @@ ExpressHbs.prototype.compile = function (source, filename) {
   if (typeof source !== 'string') {
     throw new Error('registerPartial must be a string for empty comment workaround');
   }
-  if (source.indexOf('}}') === source.length - 2) {
+  if (source.length >= 2 && source.indexOf('}}') === source.length - 2) {
     source += ' ';
   }
 
@@ -375,15 +375,20 @@ ExpressHbs.prototype.compile = function (source, filename) {
  * @param {String} name The name of the partial as used in a template.
  * @param {String} fn The `function(options, cb)`
  */
+function getResolverCache(self, name, context, options) {
+  var resolverCache =
+    self.resolverCache ||
+    _.get(context, 'data.root.resolverCache') ||
+    _.get(options, 'data.root.resolverCache');
+  if (!resolverCache) {
+    throw new Error('Could not find resolver cache in async helper ' + name + '.');
+  }
+  return resolverCache;
+}
+
 ExpressHbs.prototype.registerAsyncHelper = function (name, fn) {
   this.handlebars.registerHelper(name, function (context, options) {
-    var resolverCache =
-      this.resolverCache ||
-      _.get(context, 'data.root.resolverCache') ||
-      _.get(options, 'data.root.resolverCache');
-    if (!resolverCache) {
-      throw new Error('Could not find resolver cache in async helper ' + name + '.');
-    }
+    var resolverCache = getResolverCache(this, name, context, options);
     if (options && fn.length > 2) {
       var resolveFunc = function (arr, cb) {
         return fn.call(this, arr[0], arr[1], cb);
@@ -395,6 +400,28 @@ ExpressHbs.prototype.registerAsyncHelper = function (name, fn) {
   });
 };
 
+/**
+ * Registers a helper that returns its result, or a promise for it.
+ *
+ * Unlike `registerAsyncHelper`, the returned value is used as the output, so
+ * `async` functions work directly. A rejection or thrown error fails the render.
+ *
+ * @param {String} name The name of the helper as used in a template.
+ * @param {Function} fn Called like a sync helper, `function(...params, options)`, and
+ *   returns a value or a promise for one.
+ */
+ExpressHbs.prototype.registerPromiseHelper = function (name, fn) {
+  this.handlebars.registerHelper(name, function () {
+    var self = this;
+    var args = arguments;
+    var options = args[args.length - 1];
+    var resolverCache = getResolverCache(self, name, args[0], options);
+    return resolver.resolvePromise(resolverCache, function () {
+      return fn.apply(self, args);
+    });
+  });
+};
+
 ExpressHbs.prototype.getTemplateOptions = function () {
   return this._options.templateOptions;
 };
@@ -459,7 +486,7 @@ ExpressHbs.prototype.___express = function ___express(filename, source, options,
   options.blockCache = {};
   options.resolverCache = {};
 
-  this.viewsDir = options.settings.views || this.viewsDirOpt;
+  this.viewsDir = (options.settings && options.settings.views) || this.viewsDirOpt;
   var self = this;
 
   /**
@@ -643,10 +670,16 @@ ExpressHbs.prototype.___express = function ___express(filename, source, options,
       Object.keys(values).forEach(function (key) {
         values[key] = replaceValue(values, values[key]);
       });
-      res = replaceValue(values, res);
-      if (resolver.hasResolvers(res)) {
-        return handleAsync(null, res);
+      var replaced = replaceValue(values, res);
+      // Re-check against the live cache: nested async helpers may have registered new IDs
+      // while resolving. Stop if a pass made no progress so unknown IDs can never loop forever.
+      if (
+        replaced !== res &&
+        resolver.hasResolvers(replaced, options.resolverCache, self.Utils.escapeExpression)
+      ) {
+        return handleAsync(null, replaced);
       }
+      res = replaced;
       cb(null, res);
     });
   }

package/lib/resolver.js

@@ -12,8 +12,12 @@ var ID_ESCAPED_STRING = '<_';
 
 var ID_SUFFIX = '__';
 
+function createId() {
+  return ID_PREFIX + ID_ESCAPED_STRING + generateId(ID_LENGTH) + ID_SUFFIX;
+}
+
 function resolve(cache, fn, context) {
-  var id = ID_PREFIX + ID_ESCAPED_STRING + generateId(ID_LENGTH) + ID_SUFFIX;
+  var id = createId();
   cache[id] = new Promise(function (passed, failed) {
     try {
       fn(context, function (res) {
@@ -26,6 +30,23 @@ function resolve(cache, fn, context) {
   return id;
 }
 
+// Like resolve, but `fn` takes no callback: it returns the result or a thenable.
+// A sync throw or a rejection fails the render. null/undefined render as an empty
+// string, matching how Handlebars renders sync helpers.
+function resolvePromise(cache, fn) {
+  var id = createId();
+  var promise = new Promise(function (passed) {
+    passed(fn());
+  }).then(function (res) {
+    return res === undefined || res === null ? '' : res;
+  });
+  // done() reports the rejection; this stops Node flagging it as unhandled when the
+  // render fails before done() attaches its handlers.
+  promise.catch(function () {});
+  cache[id] = promise;
+  return id;
+}
+
 // cache is an object where the keys are cache keys and values are promises. See above.
 function done(cache, callback) {
   return Promise.all(Object.values(cache))
@@ -38,22 +59,35 @@ function done(cache, callback) {
       callback(null, resolvedCache);
     })
     .catch(function (error) {
+      // Callers use `if (err)`, so a falsy reason (e.g. `Promise.reject()`) would
+      // otherwise be treated as success with no values.
+      if (!error) {
+        error = new Error('Async helper failed with ' + String(error));
+      }
       callback(error);
     });
 }
 
-function hasResolvers(text) {
+function hasResolvers(text, cache, escape) {
   // NOTE: We specifically search the text for the ID_PREFIX **NOT** including the escapable character
   // This is because that character can be escaped in the text, and lead us to not finding unresolved
   // async helper outputs.
-  if (text.search(ID_PREFIX) >= 0) {
+  if (text.indexOf(ID_PREFIX) < 0) {
+    return false;
+  }
+  if (!cache) {
     return true;
   }
-  return false;
+  // Only report IDs that were actually generated by an async helper. The prefix can also
+  // appear in user-supplied data, which must never be treated as an unresolved helper.
+  return Object.keys(cache).some(function (id) {
+    return text.indexOf(id) >= 0 || (escape && text.indexOf(escape(id)) >= 0);
+  });
 }
 
 module.exports = {
   done: done,
   hasResolvers: hasResolvers,
   resolve: resolve,
+  resolvePromise: resolvePromise,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "express-hbs",
-  "version": "4.0.1",
+  "version": "4.1.0",
   "description": "Express handlebars template engine complete with multiple layouts, partials and blocks.",
   "keywords": [
     "express4",
@@ -10,8 +10,10 @@
     "partials"
   ],
   "main": "index.js",
+  "types": "index.d.ts",
   "files": [
     "index.js",
+    "index.d.ts",
     "lib"
   ],
   "engines": {
@@ -28,7 +30,9 @@
   "author": "Mario Gutierrez <mario@barc.com>",
   "license": "MIT",
   "devDependencies": {
-    "@tryghost/pro-ship": "2.0.1",
+    "@tryghost/pro-ship": "2.0.4",
+    "@types/express": "5.0.6",
+    "@types/node": "26.6.6",
     "cookie-parser": "1.4.7",
     "express": "5.3.0",
     "i18n": "0.15.4",
@@ -37,7 +41,8 @@
     "oxfmt": "0.76.0",
     "oxlint": "1.91.0",
     "rewire": "9.0.1",
-    "supertest": "7.3.2"
+    "supertest": "7.3.2",
+    "typescript": "7.0.2"
   },
   "dependencies": {
     "handlebars": "^4.7.10",
@@ -48,7 +53,8 @@
     "js-beautify": "^2.0.0"
   },
   "scripts": {
-    "lint": "oxlint --quiet && oxfmt --check .",
+    "lint": "oxlint --quiet && oxfmt --check . && pnpm lint:types",
+    "lint:types": "tsc -p test/types",
     "lint:fix": "oxlint --fix && oxfmt .",
     "format": "oxfmt .",
     "test": "mocha",