@nci-gis/js-tmpl 0.1.0 → 0.1.1

package/README.md

@@ -51,7 +51,8 @@ See [Design Principles](docs/PRINCIPLES.md) - Core philosophy guiding all decisi
 ## Features
 
 - 🎯 **Dynamic File Paths** - Use `${var}` placeholders in paths and filenames
-- 🧩 **Handlebars Templates** - Full Handlebars feature set (loops, conditionals, helpers)
+- 🧩 **Handlebars Templates** - Full Handlebars feature set (loops, conditionals, partials)
+- 🛠️ **Custom Helpers** - `registerHelpers` on a scoped instance, validated and atomic
 - 📦 **Partial System** - Reusable components with root and namespaced partials
 - ⚙️ **Flexible Configuration** - CLI args > project config > defaults
 - 🌲 **BFS Tree Walking** - Async, non-blocking template discovery
@@ -167,6 +168,27 @@ const config = resolveConfig({
 await renderDirectory(config);
 ```
 
+**With custom helpers:**
+
+```javascript
+import Handlebars from 'handlebars';
+import {
+  registerHelpers,
+  renderDirectory,
+  resolveConfig,
+} from '@nci-gis/js-tmpl';
+
+const hbs = Handlebars.create();
+registerHelpers(hbs, { upper: (s) => s.toUpperCase() });
+
+await renderDirectory(resolveConfig({ valuesFile: './values.yaml' }), hbs);
+```
+
+Helpers must be pure functions. Strict mode still applies to plain
+`{{var}}` lookups around them; see
+[Strict templates](docs/API.md#strict-templates) for what is not checked
+inside helper arguments.
+
 ### 4. Get output
 
 ```text
@@ -284,6 +306,12 @@ js-tmpl render [options]
 | `--config-file FILE`     | Explicit config file                     | Auto-discovered |
 | `--env-keys KEYS`        | Comma-separated env var names to expose  | None            |
 | `--env-prefix PREFIX`    | Auto-include env vars with this prefix   | None            |
+| `--verbose`              | Print stack traces on error              | Off             |
+| `-h, --help`             | Show usage                               |                 |
+
+The CLI is strict: an unknown option, an option without its value, a
+repeated option, or an unexpected argument is an error. Exit codes: `0`
+success, `1` render or configuration error, `2` usage error.
 
 Both `--values` and `--values-dir` are optional (VP-8, VP-6). If neither is
 supplied, `view` is `{ env: {...} }` only. Missing `{{var}}` in a template
@@ -320,6 +348,8 @@ See [docs/API.md](docs/API.md) for the complete API reference — parameters, re
 - [examples/value-partials/](examples/value-partials/) — composing `view`
   from multiple structured files via `--values-dir` (directory-as-namespace,
   no merge, `@`-flatten escape).
+- [examples/helpers/](examples/helpers/) — registering pure custom helpers on
+  a scoped Handlebars instance with `registerHelpers`.
 
 ## Testing
 

package/bin/js-tmpl.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+// Installed CLI entry. A Node file, not a shell wrapper: npm links it from
+// node_modules/.bin on every OS, and imports resolve from this file's real
+// location, not from the symlink.
+import { run } from '../src/cli/main.js';
+
+process.exitCode = await run(process.argv.slice(2));

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@nci-gis/js-tmpl",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "The pure JavaScript templating engine that uses handlebars.",
   "type": "module",
   "bin": {
-    "js-tmpl": "bin/js-tmpl"
+    "js-tmpl": "bin/js-tmpl.js"
   },
   "exports": {
     ".": {
@@ -13,9 +13,9 @@
   },
   "scripts": {
     "prepare": "husky",
-    "test": "node --test $(find tests -name '*.test.js')",
-    "test:watch": "node --test --watch $(find tests -name '*.test.js')",
-    "test:coverage": "node --experimental-test-coverage --test $(find tests -name '*.test.js')",
+    "test": "node --test",
+    "test:watch": "node --test --watch",
+    "test:coverage": "node --test --experimental-test-coverage --test-coverage-exclude=\"tests/**\" --test-coverage-exclude=\"examples/**\" --test-coverage-lines=99 --test-coverage-branches=99 --test-coverage-functions=99",
     "format": "pnpm format:code && pnpm format:md",
     "format:check": "pnpm format:code:check && pnpm format:md:check",
     "format:code": "prettier --write src/ tests/",
@@ -31,7 +31,10 @@
     "tool": "node src/cli/main.js",
     "docs:check-links": "remark --frail --quiet *.md docs/*.md tests/README.md examples/**/*.md",
     "docs:check-exports": "node scripts/check-doc-exports.js",
-    "docs:check": "pnpm docs:check-links && pnpm docs:check-exports"
+    "docs:check": "pnpm docs:check-links && pnpm docs:check-exports",
+    "examples:update": "node scripts/update-golden.js",
+    "pack:check": "node scripts/check-pack.js",
+    "verify": "pnpm lint && pnpm format:check && pnpm docs:check && pnpm pack:check && pnpm test:coverage"
   },
   "keywords": [
     "js",
@@ -61,7 +64,6 @@
   },
   "packageManager": "pnpm@10.22.0",
   "dependencies": {
-    "config": "^4.1.1",
     "handlebars": "^4.7.8",
     "js-yaml": "^4.1.1"
   },

package/src/cli/args.js

@@ -1,73 +1,146 @@
+import { parseArgs as parseNodeArgs } from 'node:util';
+
 /**
- * Parse CLI arguments.
- *
- * @param {string[]} args
- * @returns {import('../types.js').CliArgs}
+ * The command line was malformed: unknown option, missing value, stray
+ * argument. The CLI exits with code 2 for these, distinct from render or
+ * config failures (code 1).
  */
-export function parseArgs(args) {
-  /** @type {import('../types.js').CliArgs} */
-  const opts = { command: 'render' };
-
-  let i = 0;
-  while (i < args.length) {
-    const a = args[i];
-
-    switch (a) {
-      case '-h':
-      case '--help':
-        opts.command = 'help';
-        break;
+export class UsageError extends Error {
+  /** @param {string} message */
+  constructor(message) {
+    super(message);
+    this.name = 'UsageError';
+  }
+}
 
-      case 'render':
-        opts.command = 'render';
-        break;
+/** Option name → CliArgs field. Short aliases live in OPTIONS. */
+const FIELDS = {
+  'template-dir': 'templateDir',
+  values: 'valuesFile',
+  'values-dir': 'valuesDir',
+  out: 'outDir',
+  'partials-dir': 'partialsDir',
+  'config-file': 'configFile',
+  ext: 'extname',
+  'env-prefix': 'envPrefix',
+};
 
-      case '-t':
-      case '--template-dir':
-        opts.templateDir = args[++i];
-        break;
+/** @type {import('node:util').ParseArgsConfig['options']} */
+const OPTIONS = {
+  help: { type: 'boolean', short: 'h' },
+  verbose: { type: 'boolean' },
+  'template-dir': { type: 'string', short: 't' },
+  values: { type: 'string', short: 'c' },
+  'values-dir': { type: 'string' },
+  out: { type: 'string', short: 'o' },
+  'partials-dir': { type: 'string', short: 'p' },
+  'config-file': { type: 'string' },
+  ext: { type: 'string', short: 'x' },
+  'env-keys': { type: 'string' },
+  'env-prefix': { type: 'string' },
+};
 
-      case '-c':
-      case '--values':
-        opts.valuesFile = args[++i];
-        break;
+const COMMANDS = new Set(['render']);
 
-      case '--values-dir':
-        opts.valuesDir = args[++i];
-        break;
+/**
+ * Run node:util parseArgs, turning its errors into UsageError with the
+ * first sentence of Node's message (the rest is generic advice). An option
+ * followed by another option (`-o --values x`) is reported as missing its
+ * value rather than taking `--values` as the output dir.
+ *
+ * @param {string[]} args
+ */
+function tokenize(args) {
+  try {
+    return parseNodeArgs({
+      args,
+      options: OPTIONS,
+      strict: true,
+      allowPositionals: true,
+      tokens: true,
+    });
+  } catch (error) {
+    const err = /** @type {Error & { code?: string }} */ (error);
+    if (err.code?.startsWith('ERR_PARSE_ARGS_')) {
+      const first = err.message.split(/\.(?:\s|$)/)[0];
+      const ambiguous = first.match(/^Option '([^']+)' argument is ambiguous/);
+      throw new UsageError(
+        ambiguous ? `Option '${ambiguous[1]}' is missing its value` : first,
+      );
+    }
+    throw err;
+  }
+}
 
-      case '-o':
-      case '--out':
-        opts.outDir = args[++i];
-        break;
+/**
+ * Throw if any option appears more than once (no silent last-wins).
+ *
+ * @param {Array<{ kind: string, name?: string, rawName?: string }>} tokens
+ */
+function assertNoRepeats(tokens) {
+  /** @type {Map<string, string>} */
+  const seen = new Map();
+  for (const t of tokens) {
+    if (t.kind !== 'option' || !t.name) {
+      continue;
+    }
+    if (seen.has(t.name)) {
+      throw new UsageError(
+        `Option '--${t.name}' given more than once (${seen.get(t.name)}, ${t.rawName})`,
+      );
+    }
+    seen.set(t.name, t.rawName ?? `--${t.name}`);
+  }
+}
 
-      case '-p':
-      case '--partials-dir':
-        opts.partialsDir = args[++i];
-        break;
+/**
+ * Parse CLI arguments (without the node binary and script path).
+ *
+ * Strict: unknown options, options missing their value, repeated options,
+ * and positional arguments other than one `render` command throw
+ * `UsageError`. Only options actually given appear in the result, so unset
+ * options never override config-file or default values.
+ *
+ * @param {string[]} args - e.g. `process.argv.slice(2)`
+ * @returns {import('../types.js').CliArgs}
+ * @throws {UsageError}
+ */
+export function parseArgs(args) {
+  const { values, positionals, tokens } = tokenize(args);
+  assertNoRepeats(/** @type {any[]} */ (tokens));
 
-      case '--config-file':
-        opts.configFile = args[++i];
-        break;
+  const [command = 'render', ...extra] = positionals;
+  if (!COMMANDS.has(command)) {
+    throw new UsageError(`Unknown command '${command}'`);
+  }
+  if (extra.length > 0) {
+    throw new UsageError(`Unexpected argument '${extra[0]}'`);
+  }
 
-      case '-x':
-      case '--ext':
-        opts.extname = args[++i];
-        break;
+  /** @type {import('../types.js').CliArgs} */
+  const opts = { command: values.help ? 'help' : command };
+  if (values.verbose) {
+    opts.verbose = true;
+  }
 
-      case '--env-keys':
-        opts.envKeys = args[++i]
-          .split(',')
-          .map((s) => s.trim())
-          .filter(Boolean);
-        break;
+  for (const [option, field] of Object.entries(FIELDS)) {
+    const value = values[option];
+    if (typeof value === 'string') {
+      /** @type {Record<string, unknown>} */ (opts)[field] = value;
+    }
+  }
 
-      case '--env-prefix':
-        opts.envPrefix = args[++i];
-        break;
+  if (typeof values['env-keys'] === 'string') {
+    const keys = values['env-keys']
+      .split(',')
+      .map((s) => s.trim())
+      .filter(Boolean);
+    if (keys.length === 0) {
+      throw new UsageError(
+        "Option '--env-keys' needs at least one variable name",
+      );
     }
-    // next argument:
-    i++;
+    opts.envKeys = keys;
   }
 
   return opts;

package/src/cli/main.js

@@ -2,40 +2,61 @@
 
 import { resolveConfig } from '../config/resolver.js';
 import { renderDirectory } from '../engine/renderDirectory.js';
-import { parseArgs } from './args.js';
+import { parseArgs, UsageError } from './args.js';
 import { USAGE } from './usage.js';
 
-/** @returns {Promise<void>} */
-export async function main() {
-  const cli = parseArgs(process.argv);
+/**
+ * Parse arguments and run the command. Throws on any failure; `run` turns
+ * that into output and an exit code.
+ *
+ * @param {string[]} argv - Arguments without the node binary and script path
+ * @returns {Promise<void>}
+ */
+export async function main(argv) {
+  const cli = parseArgs(argv);
 
   if (cli.command === 'help') {
     console.log(USAGE);
     return;
   }
 
-  if (cli.command !== 'render') {
-    console.error('Unknown command:', cli.command);
-    process.exit(1);
-  }
-
   const cfg = resolveConfig(cli);
-
   await renderDirectory(cfg);
-
   console.log('✔ js-tmpl completed.');
 }
 
-// Execute main function if this file is run directly
+/**
+ * CLI error boundary. Prints `js-tmpl: <message>` (plus the stack with
+ * `--verbose`) and returns the exit code: 0 ok, 1 render/config error,
+ * 2 usage error.
+ *
+ * @param {string[]} argv - Arguments without the node binary and script path
+ * @returns {Promise<number>}
+ */
+export async function run(argv) {
+  try {
+    await main(argv);
+    return 0;
+  } catch (error) {
+    const err = /** @type {Error} */ (error);
+    console.error(`js-tmpl: ${err.message}`);
+    if (err instanceof UsageError) {
+      console.error("Run 'js-tmpl --help' for usage.");
+      return 2;
+    }
+    if (argv.includes('--verbose')) {
+      console.error(err.stack);
+    }
+    return 1;
+  }
+}
+
+// Direct execution (`node src/cli/main.js …`). The installed CLI enters
+// through bin/js-tmpl.js instead, which calls `run` itself.
 const isDirectRun =
   process.argv[1] &&
   import.meta.url.endsWith(process.argv[1].replaceAll('\\', '/'));
 
 if (isDirectRun) {
-  try {
-    await main();
-  } catch (error) {
-    console.error('Error:', error);
-    process.exit(1);
-  }
+  process.exitCode = await run(process.argv.slice(2));
 }

package/src/cli/usage.js

@@ -14,4 +14,10 @@ Options:
       --config-file <file>   Project config file
       --env-keys <keys>      Comma-separated env var names to expose (default: none)
       --env-prefix <prefix>  Auto-include env vars with this prefix (e.g. JS_TMPL_)
-  -h, --help                 Show this help message`;
+      --verbose              Print stack traces on error
+  -h, --help                 Show this help message
+
+Exit codes:
+  0  success
+  1  render or configuration error
+  2  usage error (unknown option, missing value, unexpected argument)`;

package/src/engine/helpers.js

@@ -0,0 +1,93 @@
+/**
+ * Bare-identifier rule for helper names: `{{name}}` must parse without
+ * bracket notation. Hyphens are allowed (`date-format` is idiomatic).
+ */
+const HELPER_NAME_RE = /^[a-zA-Z_$][\w$-]*$/;
+
+/**
+ * Describe a value's type for error messages (`null` and arrays included).
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+function describeType(value) {
+  if (value === null) {
+    return 'null';
+  }
+  if (Array.isArray(value)) {
+    return 'array';
+  }
+  return typeof value;
+}
+
+/**
+ * Throw if a single helper entry is invalid or collides on `hbs`.
+ *
+ * @param {string} name
+ * @param {unknown} fn
+ * @param {typeof import('handlebars')} hbs
+ */
+function assertValidHelper(name, fn, hbs) {
+  if (!HELPER_NAME_RE.test(name)) {
+    throw new Error(
+      `Invalid helper name '${name}' — must start with a letter, underscore, or\n` +
+        'dollar sign, and contain only letters, digits, underscores, dollars, or hyphens.\n' +
+        'For exotic names, use hbs.registerHelper() directly.',
+    );
+  }
+  if (typeof fn !== 'function') {
+    throw new Error(
+      `Helper '${name}' must be a function, got ${describeType(fn)}.\n` +
+        'Each value in helpersMap must be a callable function.',
+    );
+  }
+  if (Object.hasOwn(hbs.helpers, name)) {
+    throw new Error(
+      `Helper '${name}' is already registered on this Handlebars instance.\n` +
+        'To intentionally override a built-in, use hbs.registerHelper() directly.',
+    );
+  }
+}
+
+/**
+ * Register custom helpers on a scoped Handlebars instance.
+ *
+ * Validates every entry before registering any (atomic): a map with one
+ * invalid entry registers nothing. Names must be bare identifiers
+ * (`/^[a-zA-Z_$][\w$-]*$/`), values must be functions, and a name already
+ * registered on `hbs` (built-ins included) throws. Skips silently if
+ * `helpersMap` is falsy or empty.
+ *
+ * Helpers must be pure: same arguments, same result. js-tmpl cannot enforce
+ * this; a helper reading the clock, randomness, env, or disk makes output
+ * non-deterministic.
+ *
+ * @param {typeof import('handlebars')} hbs - Handlebars instance to register on
+ * @param {Record<string, import('handlebars').HelperDelegate>} [helpersMap] - Helper name → function
+ * @returns {void}
+ */
+export function registerHelpers(hbs, helpersMap) {
+  if (!hbs || typeof hbs.registerHelper !== 'function') {
+    throw new Error(
+      'registerHelpers requires a Handlebars instance as its first argument.\n' +
+        'Create one with Handlebars.create() and pass it to renderDirectory too.',
+    );
+  }
+  if (!helpersMap) {
+    return;
+  }
+  if (typeof helpersMap !== 'object' || Array.isArray(helpersMap)) {
+    throw new Error(
+      `helpersMap must be an object of name → function, got ${describeType(helpersMap)}.\n` +
+        'Example: registerHelpers(hbs, { upper: (s) => s.toUpperCase() })',
+    );
+  }
+
+  const entries = Object.entries(helpersMap);
+  for (const [name, fn] of entries) {
+    assertValidHelper(name, fn, hbs);
+  }
+  for (const [name, fn] of entries) {
+    hbs.registerHelper(name, fn);
+  }
+}

package/src/engine/renderDirectory.js

@@ -8,6 +8,63 @@ import { registerPartials } from './partials.js';
 import { renderPath } from './pathRenderer.js';
 import { walkTemplateTree } from './treeWalker.js';
 
+/**
+ * Throw if `target` is not strictly inside `outDir` — a `${var}` value such
+ * as `../x` must never write outside the output directory.
+ *
+ * @param {string} target
+ * @param {string} outDir
+ * @param {string} relPath - Template path, for the error message
+ * @param {string} rendered - Rendered path, for the error message
+ */
+function assertInsideOutDir(target, outDir, relPath, rendered) {
+  const rel = path.relative(path.resolve(outDir), path.resolve(target));
+  const escapes =
+    rel === '' || rel.split(path.sep)[0] === '..' || path.isAbsolute(rel);
+  if (escapes) {
+    const vars = [...relPath.matchAll(/\$\{([^}]+)\}/g)].map((m) => m[1]);
+    throw new Error(
+      `Template '${relPath}' renders to '${rendered}', which is outside outDir '${outDir}'.\n` +
+        (vars.length ? `Check the values of: ${vars.join(', ')}. ` : '') +
+        "Path values must not contain '..' segments.",
+    );
+  }
+}
+
+/**
+ * Map every template to its output path before anything is rendered or
+ * written, so an escaping path or two templates sharing a target fail
+ * before the first file is touched.
+ *
+ * @param {Array<{ relPath: string, absPath: string }>} files
+ * @param {import('../types.js').TemplateConfig} cfg
+ * @returns {Array<{ file: { relPath: string, absPath: string }, target: string }>}
+ */
+function planTargets(files, cfg) {
+  const { outDir, view, extname } = cfg;
+  /** @type {Map<string, string>} */
+  const owners = new Map();
+
+  return files.map((file) => {
+    const rendered = renderPath(file.relPath, view).replace(
+      new RegExp(`${extname}$`),
+      '',
+    );
+    const target = path.join(outDir, rendered);
+    assertInsideOutDir(target, outDir, file.relPath, rendered);
+
+    const owner = owners.get(target);
+    if (owner) {
+      throw new Error(
+        `Templates '${owner}' and '${file.relPath}' both render to '${rendered}'.\n` +
+          'Each output file must come from exactly one template; check the path values.',
+      );
+    }
+    owners.set(target, file.relPath);
+    return { file, target };
+  });
+}
+
 /**
  * Main rendering orchestrator.
  * @param {import('../types.js').TemplateConfig} cfg
@@ -15,20 +72,14 @@ import { walkTemplateTree } from './treeWalker.js';
  * @returns {Promise<void>}
  */
 export async function renderDirectory(cfg, hbs) {
-  const { templateDir, partialsDir, outDir, view, extname } = cfg;
+  const { templateDir, partialsDir, view, extname } = cfg;
 
   hbs = hbs || Handlebars.create();
   await registerPartials(partialsDir, extname, hbs);
 
   const files = await walkTemplateTree(templateDir, { ext: extname, view });
 
-  for (const file of files) {
-    const relRendered = renderPath(file.relPath, view);
-    const target = path.join(
-      outDir,
-      relRendered.replace(new RegExp(`${extname}$`), ''),
-    );
-
+  for (const { file, target } of planTargets(files, cfg)) {
     const content = await renderContent(file.absPath, view, hbs, file.relPath);
 
     await ensureDir(path.dirname(target));

package/src/index.js

@@ -1,2 +1,3 @@
 export * from './config/resolver.js';
+export * from './engine/helpers.js';
 export * from './engine/renderDirectory.js';

package/src/types.js

@@ -10,6 +10,7 @@
  * @property {string} [valuesDir]
  * @property {string[]} [envKeys]
  * @property {string} [envPrefix]
+ * @property {boolean} [verbose] - CLI only: print stack traces on error
  */
 
 /**

package/bin/js-tmpl

@@ -1,3 +0,0 @@
-#!/usr/bin/env bash
-# CLI entry point for js-tmpl
-node "$(dirname "$0")/../src/cli/main.js" "$@"