@gajae-code/utils 0.9.2 → 0.9.3

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@gajae-code/utils",
-	"version": "0.9.2",
+	"version": "0.9.3",
 	"description": "Shared utilities for pi packages",
 	"homepage": "https://gajae-code.com",
 	"author": "Yeachan-Heo",
@@ -31,7 +31,7 @@
 		"fmt": "biome format --write ."
 	},
 	"dependencies": {
-		"@gajae-code/natives": "0.9.2",
+		"@gajae-code/natives": "0.9.3",
 		"beautiful-mermaid": "^1.1.3",
 		"handlebars": "^4.7.9",
 		"winston": "^3.19.0",

package/src/logger.ts

@@ -11,8 +11,7 @@
  */
 import { AsyncLocalStorage } from "node:async_hooks";
 import * as fs from "node:fs";
-import winston from "winston";
-import DailyRotateFile from "winston-daily-rotate-file";
+import type * as winston from "winston";
 import { getLogsDir } from "./dirs";
 
 /** Ensure a logs directory exists; return the resolved path. */
@@ -23,28 +22,59 @@ function ensureDir(dir: string): string {
 	return dir;
 }
 
-/** Custom format that includes pid and flattens metadata */
-const logFormat = winston.format.combine(
-	winston.format.timestamp({ format: "YYYY-MM-DDTHH:mm:ss.SSSZ" }),
-	winston.format.printf(({ timestamp, level, message, ...meta }) => {
-		const entry: Record<string, unknown> = {
-			timestamp,
-			level,
-			pid: process.pid,
-			message,
-		};
-		// Flatten metadata into entry
-		for (const [key, value] of Object.entries(meta)) {
-			if (key !== "level" && key !== "timestamp" && key !== "message") {
-				entry[key] = value;
+type WinstonModule = typeof import("winston");
+type DailyRotateFileCtor = typeof import("winston-daily-rotate-file");
+type Logger = winston.Logger;
+type Transport = winston.transport;
+type LogLevel = "error" | "warn" | "info" | "debug";
+type LogRecord = { level: LogLevel; message: string; context?: Record<string, unknown> };
+
+let winstonModule: WinstonModule | undefined;
+let dailyRotateFileCtor: DailyRotateFileCtor | undefined;
+let winstonLogger: Logger | undefined;
+let loggerInit: Promise<Logger> | undefined;
+let flushingBufferedLogs = false;
+const bufferedLogs: LogRecord[] = [];
+/** Cap pre-init buffering so a hung/failed winston import cannot grow heap unboundedly. */
+const MAX_BUFFERED_LOGS = 10_000;
+let transportOptions: { console?: boolean; file?: boolean | string } = { file: true };
+
+async function loadLoggingModules(): Promise<{ winston: WinstonModule; DailyRotateFile: DailyRotateFileCtor }> {
+	if (!winstonModule || !dailyRotateFileCtor) {
+		const [winstonImport, dailyRotateFileImport] = await Promise.all([
+			import("winston"),
+			import("winston-daily-rotate-file"),
+		]);
+		winstonModule = (winstonImport.default ?? winstonImport) as WinstonModule;
+		dailyRotateFileCtor = dailyRotateFileImport.default;
+	}
+	return { winston: winstonModule, DailyRotateFile: dailyRotateFileCtor };
+}
+
+/** Build the JSON log formatter after winston is loaded. */
+function makeLogFormat(winston: WinstonModule): winston.Logform.Format {
+	return winston.format.combine(
+		winston.format.timestamp({ format: "YYYY-MM-DDTHH:mm:ss.SSSZ" }),
+		winston.format.printf(({ timestamp, level, message, ...meta }) => {
+			const entry: Record<string, unknown> = {
+				timestamp,
+				level,
+				pid: process.pid,
+				message,
+			};
+			// Flatten metadata into entry
+			for (const [key, value] of Object.entries(meta)) {
+				if (key !== "level" && key !== "timestamp" && key !== "message") {
+					entry[key] = value;
+				}
 			}
-		}
-		return JSON.stringify(entry);
-	}),
-);
+			return JSON.stringify(entry);
+		}),
+	);
+}
 
 /** Build a rotating file transport, materializing the target directory lazily. */
-function makeFileTransport(dir?: string): winston.transport {
+function makeFileTransport(DailyRotateFile: DailyRotateFileCtor, dir?: string): Transport {
 	return new DailyRotateFile({
 		dirname: ensureDir(dir ?? getLogsDir()),
 		filename: "gjc.%DATE%.log",
@@ -55,18 +85,83 @@ function makeFileTransport(dir?: string): winston.transport {
 	});
 }
 
-function makeConsoleTransport(): winston.transport {
-	return new winston.transports.Console({ format: logFormat });
+function makeConsoleTransport(winston: WinstonModule): Transport {
+	return new winston.transports.Console({ format: makeLogFormat(winston) });
+}
+
+function applyTransports(
+	logger: Logger,
+	modules: { winston: WinstonModule; DailyRotateFile: DailyRotateFileCtor },
+): void {
+	logger.clear();
+	if (transportOptions.file) {
+		logger.add(
+			makeFileTransport(
+				modules.DailyRotateFile,
+				typeof transportOptions.file === "string" ? transportOptions.file : undefined,
+			),
+		);
+	}
+	if (transportOptions.console) logger.add(makeConsoleTransport(modules.winston));
 }
 
 /** The winston logger instance. Default: file ON (TUI-safe), console OFF. */
-const winstonLogger = winston.createLogger({
-	level: "debug",
-	format: logFormat,
-	transports: [makeFileTransport()],
-	// Don't exit on error - logging failures shouldn't crash the app
-	exitOnError: false,
-});
+async function getWinstonLogger(): Promise<Logger> {
+	if (winstonLogger) return winstonLogger;
+	loggerInit ??= (async () => {
+		const modules = await loadLoggingModules();
+		const logger = modules.winston.createLogger({
+			level: "debug",
+			format: makeLogFormat(modules.winston),
+			transports: [],
+			// Don't exit on error - logging failures shouldn't crash the app
+			exitOnError: false,
+		});
+		applyTransports(logger, modules);
+		winstonLogger = logger;
+		flushBufferedLogs();
+		return logger;
+	})();
+	return loggerInit;
+}
+
+function flushBufferedLogs(): void {
+	if (!winstonLogger || flushingBufferedLogs) return;
+	flushingBufferedLogs = true;
+	try {
+		// Loop: records buffered by reentrant writes during a flush pass (e.g.
+		// a transport callback that logs) are drained by the next pass instead
+		// of being stranded forever.
+		while (bufferedLogs.length > 0) {
+			for (const record of bufferedLogs.splice(0)) {
+				winstonLogger[record.level](record.message, record.context);
+			}
+		}
+	} finally {
+		flushingBufferedLogs = false;
+	}
+}
+
+function writeLog(level: LogLevel, message: string, context?: Record<string, unknown>): void {
+	try {
+		if (winstonLogger && !flushingBufferedLogs) {
+			winstonLogger[level](message, context);
+			return;
+		}
+		bufferedLogs.push({ level, message, context });
+		if (bufferedLogs.length > MAX_BUFFERED_LOGS) {
+			bufferedLogs.splice(0, bufferedLogs.length - MAX_BUFFERED_LOGS);
+		}
+		void getWinstonLogger().catch(() => {
+			bufferedLogs.length = 0;
+			// Allow a later write to retry initialization instead of pinning a
+			// rejected promise forever.
+			loggerInit = undefined;
+		});
+	} catch {
+		// Silently ignore logging failures
+	}
+}
 
 /**
  * Replace the active log transports. Pass `console: true, file: false` for
@@ -74,11 +169,20 @@ const winstonLogger = winston.createLogger({
  * logs piped into a process supervisor instead of the rotating file.
  */
 export function setTransports(opts: { console?: boolean; file?: boolean | string }): void {
-	winstonLogger.clear();
-	if (opts.file) {
-		winstonLogger.add(makeFileTransport(typeof opts.file === "string" ? opts.file : undefined));
+	transportOptions = opts;
+	if (winstonLogger && winstonModule && dailyRotateFileCtor) {
+		applyTransports(winstonLogger, { winston: winstonModule, DailyRotateFile: dailyRotateFileCtor });
+	} else if (loggerInit) {
+		// Init in flight: re-apply once it settles so the new options can never
+		// be silently skipped by an ordering race inside the init closure.
+		void loggerInit
+			.then(logger => {
+				if (winstonModule && dailyRotateFileCtor) {
+					applyTransports(logger, { winston: winstonModule, DailyRotateFile: dailyRotateFileCtor });
+				}
+			})
+			.catch(() => {});
 	}
-	if (opts.console) winstonLogger.add(makeConsoleTransport());
 }
 
 /**
@@ -87,11 +191,7 @@ export function setTransports(opts: { console?: boolean; file?: boolean | string
  * @param context - The context to log.
  */
 export function error(message: string, context?: Record<string, unknown>): void {
-	try {
-		winstonLogger.error(message, context);
-	} catch {
-		// Silently ignore logging failures
-	}
+	writeLog("error", message, context);
 }
 
 /**
@@ -100,11 +200,7 @@ export function error(message: string, context?: Record<string, unknown>): void
  * @param context - The context to log.
  */
 export function warn(message: string, context?: Record<string, unknown>): void {
-	try {
-		winstonLogger.warn(message, context);
-	} catch {
-		// Silently ignore logging failures
-	}
+	writeLog("warn", message, context);
 }
 
 /**
@@ -113,11 +209,7 @@ export function warn(message: string, context?: Record<string, unknown>): void {
  * @param context - The context to log.
  */
 export function info(message: string, context?: Record<string, unknown>): void {
-	try {
-		winstonLogger.info(message, context);
-	} catch {
-		// Silently ignore logging failures
-	}
+	writeLog("info", message, context);
 }
 
 /**
@@ -126,11 +218,7 @@ export function info(message: string, context?: Record<string, unknown>): void {
  * @param context - The context to log.
  */
 export function debug(message: string, context?: Record<string, unknown>): void {
-	try {
-		winstonLogger.debug(message, context);
-	} catch {
-		// Silently ignore logging failures
-	}
+	writeLog("debug", message, context);
 }
 
 const LOGGED_TIMING_THRESHOLD_MS = 0.5;

package/src/prompt.ts

@@ -1,5 +1,5 @@
+import { createRequire } from "node:module";
 import type { HelperDelegate, HelperOptions, Template, TemplateDelegate } from "handlebars";
-import Handlebars from "handlebars";
 
 export type { HelperDelegate, HelperOptions, Template, TemplateDelegate };
 
@@ -223,107 +223,132 @@ export interface TemplateContext extends Record<string, unknown> {
 	arguments?: string;
 }
 
-const handlebars = Handlebars.create();
+type HandlebarsRuntime = typeof import("handlebars");
+type HandlebarsInstance = ReturnType<HandlebarsRuntime["create"]>;
+
+const require = createRequire(import.meta.url);
+const COMPILED_HANDLEBARS_PATH = "/$bunfs/root/node_modules/handlebars/lib/index.js";
+let handlebars: HandlebarsInstance | undefined;
+
+function getHandlebars(): HandlebarsInstance {
+	if (handlebars) return handlebars;
+	const Handlebars = asHandlebarsRuntime(
+		require(process.env.PI_COMPILED === "true" ? COMPILED_HANDLEBARS_PATH : "handlebars"),
+	);
+	handlebars = Handlebars.create();
+	registerBuiltinHelpers(handlebars);
+	return handlebars;
+}
 
-handlebars.registerHelper("arg", function (this: TemplateContext, index: number | string): string {
-	const args = this.args ?? [];
-	const parsedIndex = typeof index === "number" ? index : Number.parseInt(index, 10);
-	if (!Number.isFinite(parsedIndex)) return "";
-	const zeroBased = parsedIndex - 1;
-	if (zeroBased < 0) return "";
-	return args[zeroBased] ?? "";
-});
+function asHandlebarsRuntime(value: unknown): HandlebarsRuntime {
+	if (isHandlebarsRuntime(value)) return value;
+	if (isObjectRecord(value) && isHandlebarsRuntime(value.default)) return value.default;
+	throw new Error("Loaded handlebars module does not expose the expected runtime API.");
+}
 
-/**
- * {{#list items prefix="- " suffix="" join="\n"}}{{this}}{{/list}}
- * Renders an array with customizable prefix, suffix, and join separator.
- * Note: Use \n in join for newlines (will be unescaped automatically).
- */
-handlebars.registerHelper(
-	"list",
-	function (this: unknown, context: unknown[], options: Handlebars.HelperOptions): string {
+function isHandlebarsRuntime(value: unknown): value is HandlebarsRuntime {
+	return isObjectRecord(value) && typeof value.create === "function";
+}
+
+function isObjectRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null;
+}
+
+function registerBuiltinHelpers(handlebars: HandlebarsInstance): void {
+	handlebars.registerHelper("arg", function (this: TemplateContext, index: number | string): string {
+		const args = this.args ?? [];
+		const parsedIndex = typeof index === "number" ? index : Number.parseInt(index, 10);
+		if (!Number.isFinite(parsedIndex)) return "";
+		const zeroBased = parsedIndex - 1;
+		if (zeroBased < 0) return "";
+		return args[zeroBased] ?? "";
+	});
+
+	/**
+	 * {{#list items prefix="- " suffix="" join="\n"}}{{this}}{{/list}}
+	 * Renders an array with customizable prefix, suffix, and join separator.
+	 * Note: Use \n in join for newlines (will be unescaped automatically).
+	 */
+	handlebars.registerHelper("list", function (this: unknown, context: unknown[], options: HelperOptions): string {
 		if (!Array.isArray(context) || context.length === 0) return "";
 		const prefix = (options.hash.prefix as string) ?? "";
 		const suffix = (options.hash.suffix as string) ?? "";
 		const rawSeparator = (options.hash.join as string) ?? "\n";
 		const separator = rawSeparator.replace(/\\n/g, "\n").replace(/\\t/g, "\t");
 		return context.map(item => `${prefix}${options.fn(item)}${suffix}`).join(separator);
-	},
-);
-
-/**
- * {{join array ", "}}
- * Joins an array with a separator (default: ", ").
- */
-handlebars.registerHelper("join", (context: unknown[], separator?: unknown): string => {
-	if (!Array.isArray(context)) return "";
-	const sep = typeof separator === "string" ? separator : ", ";
-	return context.join(sep);
-});
-
-/**
- * {{default value "fallback"}}
- * Returns the value if truthy, otherwise returns the fallback.
- */
-handlebars.registerHelper("default", (value: unknown, defaultValue: unknown): unknown => value || defaultValue);
-
-/**
- * {{pluralize count "item" "items"}}
- * Returns "1 item" or "5 items" based on count.
- */
-handlebars.registerHelper(
-	"pluralize",
-	(count: number, singular: string, plural: string): string => `${count} ${count === 1 ? singular : plural}`,
-);
+	});
 
-/**
- * {{#when value "==" compare}}...{{else}}...{{/when}}
- * Conditional block with comparison operators: ==, ===, !=, !==, >, <, >=, <=
- */
-handlebars.registerHelper(
-	"when",
-	function (this: unknown, lhs: unknown, operator: string, rhs: unknown, options: Handlebars.HelperOptions): string {
-		const ops: Record<string, (a: unknown, b: unknown) => boolean> = {
-			"==": (a, b) => a === b,
-			"===": (a, b) => a === b,
-			"!=": (a, b) => a !== b,
-			"!==": (a, b) => a !== b,
-			">": (a, b) => (a as number) > (b as number),
-			"<": (a, b) => (a as number) < (b as number),
-			">=": (a, b) => (a as number) >= (b as number),
-			"<=": (a, b) => (a as number) <= (b as number),
-		};
-		const fn = ops[operator];
-		if (!fn) return options.inverse(this);
-		return fn(lhs, rhs) ? options.fn(this) : options.inverse(this);
-	},
-);
+	/**
+	 * {{join array ", "}}
+	 * Joins an array with a separator (default: ", ").
+	 */
+	handlebars.registerHelper("join", (context: unknown[], separator?: unknown): string => {
+		if (!Array.isArray(context)) return "";
+		const sep = typeof separator === "string" ? separator : ", ";
+		return context.join(sep);
+	});
 
-/**
- * {{#ifAny a b c}}...{{else}}...{{/ifAny}}
- * True if any argument is truthy.
- */
-handlebars.registerHelper("ifAny", function (this: unknown, ...args: unknown[]): string {
-	const options = args.pop() as Handlebars.HelperOptions;
-	return args.some(Boolean) ? options.fn(this) : options.inverse(this);
-});
+	/**
+	 * {{default value "fallback"}}
+	 * Returns the value if truthy, otherwise returns the fallback.
+	 */
+	handlebars.registerHelper("default", (value: unknown, defaultValue: unknown): unknown => value || defaultValue);
+
+	/**
+	 * {{pluralize count "item" "items"}}
+	 * Returns "1 item" or "5 items" based on count.
+	 */
+	handlebars.registerHelper(
+		"pluralize",
+		(count: number, singular: string, plural: string): string => `${count} ${count === 1 ? singular : plural}`,
+	);
+
+	/**
+	 * {{#when value "==" compare}}...{{else}}...{{/when}}
+	 * Conditional block with comparison operators: ==, ===, !=, !==, >, <, >=, <=
+	 */
+	handlebars.registerHelper(
+		"when",
+		function (this: unknown, lhs: unknown, operator: string, rhs: unknown, options: HelperOptions): string {
+			const ops: Record<string, (a: unknown, b: unknown) => boolean> = {
+				"==": (a, b) => a === b,
+				"===": (a, b) => a === b,
+				"!=": (a, b) => a !== b,
+				"!==": (a, b) => a !== b,
+				">": (a, b) => (a as number) > (b as number),
+				"<": (a, b) => (a as number) < (b as number),
+				">=": (a, b) => (a as number) >= (b as number),
+				"<=": (a, b) => (a as number) <= (b as number),
+			};
+			const fn = ops[operator];
+			if (!fn) return options.inverse(this);
+			return fn(lhs, rhs) ? options.fn(this) : options.inverse(this);
+		},
+	);
+
+	/**
+	 * {{#ifAny a b c}}...{{else}}...{{/ifAny}}
+	 * True if any argument is truthy.
+	 */
+	handlebars.registerHelper("ifAny", function (this: unknown, ...args: unknown[]): string {
+		const options = args.pop() as HelperOptions;
+		return args.some(Boolean) ? options.fn(this) : options.inverse(this);
+	});
 
-/**
- * {{#ifAll a b c}}...{{else}}...{{/ifAll}}
- * True if all arguments are truthy.
- */
-handlebars.registerHelper("ifAll", function (this: unknown, ...args: unknown[]): string {
-	const options = args.pop() as Handlebars.HelperOptions;
-	return args.every(Boolean) ? options.fn(this) : options.inverse(this);
-});
+	/**
+	 * {{#ifAll a b c}}...{{else}}...{{/ifAll}}
+	 * True if all arguments are truthy.
+	 */
+	handlebars.registerHelper("ifAll", function (this: unknown, ...args: unknown[]): string {
+		const options = args.pop() as HelperOptions;
+		return args.every(Boolean) ? options.fn(this) : options.inverse(this);
+	});
 
-/**
- * {{#table rows headers="Col1|Col2"}}{{col1}}|{{col2}}{{/table}}
- * Generates a markdown table from an array of objects.
- */
-handlebars.registerHelper(
-	"table",
-	function (this: unknown, context: unknown[], options: Handlebars.HelperOptions): string {
+	/**
+	 * {{#table rows headers="Col1|Col2"}}{{col1}}|{{col2}}{{/table}}
+	 * Generates a markdown table from an array of objects.
+	 */
+	handlebars.registerHelper("table", function (this: unknown, context: unknown[], options: HelperOptions): string {
 		if (!Array.isArray(context) || context.length === 0) return "";
 		const headersStr = options.hash.headers as string | undefined;
 		const headers = headersStr?.split("|") ?? [];
@@ -331,108 +356,108 @@ handlebars.registerHelper(
 		const headerRow = headers.length > 0 ? `| ${headers.join(" | ")} |\n| ${separator} |\n` : "";
 		const rows = context.map(item => `| ${options.fn(item).trim()} |`).join("\n");
 		return headerRow + rows;
-	},
-);
-
-/**
- * {{#codeblock lang="diff"}}...{{/codeblock}}
- * Wraps content in a fenced code block.
- */
-handlebars.registerHelper("codeblock", function (this: unknown, options: Handlebars.HelperOptions): string {
-	const lang = (options.hash.lang as string) ?? "";
-	const content = options.fn(this).trim();
-	return `\`\`\`${lang}\n${content}\n\`\`\``;
-});
-
-/**
- * {{#xml "tag"}}content{{/xml}}
- * Wraps content in XML-style tags. Returns empty string if content is empty.
- */
-handlebars.registerHelper("xml", function (this: unknown, tag: string, options: Handlebars.HelperOptions): string {
-	const content = options.fn(this).trim();
-	if (!content) return "";
-	return `<${tag}>\n${content}\n</${tag}>`;
-});
+	});
 
-/**
- * {{escapeXml value}}
- * Escapes XML special characters: & < > "
- */
-handlebars.registerHelper("escapeXml", (value: unknown): string => {
-	if (value == null) return "";
-	return String(value).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
-});
+	/**
+	 * {{#codeblock lang="diff"}}...{{/codeblock}}
+	 * Wraps content in a fenced code block.
+	 */
+	handlebars.registerHelper("codeblock", function (this: unknown, options: HelperOptions): string {
+		const lang = (options.hash.lang as string) ?? "";
+		const content = options.fn(this).trim();
+		return `\`\`\`${lang}\n${content}\n\`\`\``;
+	});
 
-/**
- * {{len array}}
- * Returns the length of an array or string.
- */
-handlebars.registerHelper("len", (value: unknown): number => {
-	if (Array.isArray(value)) return value.length;
-	if (typeof value === "string") return value.length;
-	return 0;
-});
+	/**
+	 * {{#xml "tag"}}content{{/xml}}
+	 * Wraps content in XML-style tags. Returns empty string if content is empty.
+	 */
+	handlebars.registerHelper("xml", function (this: unknown, tag: string, options: HelperOptions): string {
+		const content = options.fn(this).trim();
+		if (!content) return "";
+		return `<${tag}>\n${content}\n</${tag}>`;
+	});
 
-/**
- * {{add a b}}
- * Adds two numbers.
- */
-handlebars.registerHelper("add", (a: number, b: number): number => (a ?? 0) + (b ?? 0));
+	/**
+	 * {{escapeXml value}}
+	 * Escapes XML special characters: & < > "
+	 */
+	handlebars.registerHelper("escapeXml", (value: unknown): string => {
+		if (value == null) return "";
+		return String(value).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+	});
 
-/**
- * {{sub a b}}
- * Subtracts b from a.
- */
-handlebars.registerHelper("sub", (a: number, b: number): number => (a ?? 0) - (b ?? 0));
+	/**
+	 * {{len array}}
+	 * Returns the length of an array or string.
+	 */
+	handlebars.registerHelper("len", (value: unknown): number => {
+		if (Array.isArray(value)) return value.length;
+		if (typeof value === "string") return value.length;
+		return 0;
+	});
 
-/**
- * {{#has collection item}}...{{else}}...{{/has}}
- * Checks if an array includes an item or if a Set/Map has a key.
- */
-handlebars.registerHelper(
-	"has",
-	function (this: unknown, collection: unknown, item: unknown, options: Handlebars.HelperOptions): string {
-		let found = false;
-		if (Array.isArray(collection)) {
-			found = collection.includes(item);
-		} else if (collection instanceof Set) {
-			found = collection.has(item);
-		} else if (collection instanceof Map) {
-			found = collection.has(item);
-		} else if (collection && typeof collection === "object") {
-			if (typeof item === "string" || typeof item === "number" || typeof item === "symbol") {
-				found = item in collection;
+	/**
+	 * {{add a b}}
+	 * Adds two numbers.
+	 */
+	handlebars.registerHelper("add", (a: number, b: number): number => (a ?? 0) + (b ?? 0));
+
+	/**
+	 * {{sub a b}}
+	 * Subtracts b from a.
+	 */
+	handlebars.registerHelper("sub", (a: number, b: number): number => (a ?? 0) - (b ?? 0));
+
+	/**
+	 * {{#has collection item}}...{{else}}...{{/has}}
+	 * Checks if an array includes an item or if a Set/Map has a key.
+	 */
+	handlebars.registerHelper(
+		"has",
+		function (this: unknown, collection: unknown, item: unknown, options: HelperOptions): string {
+			let found = false;
+			if (Array.isArray(collection)) {
+				found = collection.includes(item);
+			} else if (collection instanceof Set) {
+				found = collection.has(item);
+			} else if (collection instanceof Map) {
+				found = collection.has(item);
+			} else if (collection && typeof collection === "object") {
+				if (typeof item === "string" || typeof item === "number" || typeof item === "symbol") {
+					found = item in collection;
+				}
 			}
-		}
-		return found ? options.fn(this) : options.inverse(this);
-	},
-);
+			return found ? options.fn(this) : options.inverse(this);
+		},
+	);
+
+	/**
+	 * {{includes array item}}
+	 * Returns true if array includes item. For use in other helpers.
+	 */
+	handlebars.registerHelper("includes", (collection: unknown, item: unknown): boolean => {
+		if (Array.isArray(collection)) return collection.includes(item);
+		if (collection instanceof Set) return collection.has(item);
+		if (collection instanceof Map) return collection.has(item);
+		return false;
+	});
 
-/**
- * {{includes array item}}
- * Returns true if array includes item. For use in other helpers.
- */
-handlebars.registerHelper("includes", (collection: unknown, item: unknown): boolean => {
-	if (Array.isArray(collection)) return collection.includes(item);
-	if (collection instanceof Set) return collection.has(item);
-	if (collection instanceof Map) return collection.has(item);
-	return false;
-});
+	/**
+	 * {{not value}}
+	 * Returns logical NOT of value. For use in subexpressions.
+	 */
+	handlebars.registerHelper("not", (value: unknown): boolean => !value);
 
-/**
- * {{not value}}
- * Returns logical NOT of value. For use in subexpressions.
- */
-handlebars.registerHelper("not", (value: unknown): boolean => !value);
-
-handlebars.registerHelper("jsonStringify", (value: unknown): string => JSON.stringify(value));
+	handlebars.registerHelper("jsonStringify", (value: unknown): string => JSON.stringify(value));
+}
 
 export function registerHelper(name: string, fn: HelperDelegate): void {
-	handlebars.registerHelper(name, fn);
+	getHandlebars().registerHelper(name, fn);
 }
 
 export function registerPartial(name: string, fn: Template): void {
-	handlebars.registerPartial(name, fn);
+	getHandlebars().registerPartial(name, fn);
 }
 
 /**
@@ -457,7 +482,7 @@ export function compile(template: string): (context: TemplateContext) => string
 	const disambiguated = disambiguateClosingBraces(template);
 	const cached = compiledTemplateCache.get(disambiguated);
 	if (cached) return cached;
-	const compiled = handlebars.compile(disambiguated, { noEscape: true, strict: false }) as (
+	const compiled = getHandlebars().compile(disambiguated, { noEscape: true, strict: false }) as (
 		context: TemplateContext,
 	) => string;
 	compiledTemplateCache.set(disambiguated, compiled);