@ynode/squirrellyify 1.3.0 → 1.5.2

package/README.md

@@ -2,11 +2,9 @@
 
 Copyright (c) 2025 Michael Welter <me@mikinho.com>
 
-[![npm version](https://img.shields.io/npm/v/@ynode/squirrellyify.svg)](https://www.npmjs.com/package/@ynode/squirrellyify)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![npm version](https://img.shields.io/npm/v/@ynode/squirrellyify.svg)](https://www.npmjs.com/package/@ynode/squirrellyify) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A simple and fast plugin for using the [Squirrelly](https://squirrelly.js.org/) template engine with
-[Fastify](https://www.fastify.io/).
+A simple and fast plugin for using the [Squirrelly](https://squirrelly.js.org/) template engine with [Fastify](https://www.fastify.io/).
 
 ## Features
 
@@ -76,8 +74,7 @@ fastify.listen({ port: 3000 }, (err) => {
 
 ### Request-Scoped View Data
 
-`reply.view(template, data)` automatically merges request-scoped values from `reply.locals` and
-`reply.context` into the template data:
+`reply.view(template, data)` automatically merges request-scoped values from `reply.locals` and `reply.context` into the template data:
 
 ```javascript
 fastify.addHook("preHandler", async (request, reply) => {
@@ -100,16 +97,16 @@ Merge precedence is:
 
 You can pass an options object when registering the plugin.
 
-| Option             | Type                 | Default                             | Description                                                                                                                          |
-| ------------------ | -------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
-| `templates`        | `string \| string[]` | `path.join(process.cwd(), "views")` | The directory or directories to search for page and layout templates. Searched in the provided order.                                |
-| `partials`         | `string \| string[]` | `[]`                                | The directory or directories for partial templates. All partials are loaded on startup and available by name.                         |
-| `partialsRecursive` | `boolean`           | `true`                              | If `true`, partials are loaded recursively from subdirectories. Names use forward slashes (for example, `emails/header`).           |
-| `partialsNamespace` | `boolean \| string` | `false`                             | Optional namespace prefix for partial names. Use `true` to prefix with each partials directory basename, or provide a custom string. |
-| `layout`           | `string`             | `undefined`                         | The name of the default layout file to use (without extension). Can be overridden per-route.                                         |
-| `defaultExtension` | `string`             | `"sqrl"`                            | The file extension for all template files. Leading `.` is optional (for example, `"html"` or `".html"`).                           |
-| `cache`            | `boolean`            | `NODE_ENV === "production"`         | If `true`, compiled templates and resolved file paths will be cached in memory.                                                      |
-| `sqrl`             | `object`             | `undefined`                         | Squirrelly options. Supports `{ scope: "global" \| "scoped", config, helpers, filters }`.                                            |
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `templates` | `string \| string[]` | `path.join(process.cwd(), "views")` | The directory or directories to search for page and layout templates. Searched in the provided order. |
+| `partials` | `string \| string[]` | `[]` | The directory or directories for partial templates. All partials are loaded on startup and available by name. |
+| `partialsRecursive` | `boolean` | `true` | If `true`, partials are loaded recursively from subdirectories. Names use forward slashes (for example, `emails/header`). |
+| `partialsNamespace` | `boolean \| string` | `false` | Optional namespace prefix for partial names. Use `true` to prefix with each partials directory basename, or provide a custom string. |
+| `layout` | `string` | `undefined` | The name of the default layout file to use (without extension). Can be overridden per-route. |
+| `defaultExtension` | `string` | `"sqrl"` | The file extension for all template files. Leading `.` is optional (for example, `"html"` or `".html"`). |
+| `cache` | `boolean` | `NODE_ENV === "production"` | If `true`, compiled templates and resolved file paths will be cached in memory. |
+| `sqrl` | `object` | `undefined` | Squirrelly options. Supports `{ scope: "global" \| "scoped", config, helpers, filters }`. |
 
 Runtime API after registration:
 
@@ -123,8 +120,7 @@ These APIs are scope-aware:
 - In `global` mode they modify shared helpers/filters/partials.
 - In `scoped` mode they only affect the current plugin registration scope.
 
-The cache API is process-local and lets you invalidate compiled template/path caches at runtime when
-`cache: true` is used.
+The cache API is process-local and lets you invalidate compiled template/path caches at runtime when `cache: true` is used.
 
 Invalid option types are rejected at plugin registration time with descriptive errors.
 
@@ -132,8 +128,7 @@ Invalid option types are rejected at plugin registration time with descriptive e
 
 ### Layouts
 
-Layouts are wrappers for your page templates. The rendered page content is injected into the `body`
-variable within the layout.
+Layouts are wrappers for your page templates. The rendered page content is injected into the `body` variable within the layout.
 
 **`views/layouts/main.sqrl`**
 
@@ -191,9 +186,7 @@ You can specify a layout in three ways (in order of precedence):
 
 ### Partials
 
-Partials are reusable chunks of template code. Create a `partials` directory and place your files
-there. By default, partials are loaded recursively and registered by forward-slash path from the
-partials directory root.
+Partials are reusable chunks of template code. Create a `partials` directory and place your files there. By default, partials are loaded recursively and registered by forward-slash path from the partials directory root.
 
 **`partials/user-card.sqrl`**
 
@@ -258,8 +251,7 @@ fastify.register(squirrellyify, {
 
 ### Scoped Configuration (Encapsulation)
 
-This plugin supports Fastify's encapsulation model. You can register it multiple times with
-different settings for different route prefixes.
+This plugin supports Fastify's encapsulation model. You can register it multiple times with different settings for different route prefixes.
 
 ```javascript
 import Fastify from "fastify";
@@ -308,8 +300,7 @@ Use `sqrl.scope` to choose registration mode:
 - `global` (default): helpers, filters, and partials are shared across plugin registrations.
 - `scoped`: helpers, filters, and partials are isolated to each plugin registration.
 
-You can also add/remove helpers and filters at runtime via `fastify.viewHelpers` and
-`fastify.viewFilters`.
+You can also add/remove helpers and filters at runtime via `fastify.viewHelpers` and `fastify.viewFilters`.
 
 ```javascript
 fastify.register(squirrellyify, {

package/index.d.ts

@@ -0,0 +1,21 @@
+import { FastifyPluginAsync } from "fastify";
+
+export interface SquirrellyifyOptions {
+    /**
+     * Enable caching of templates.
+     * @default process.env.NODE_ENV === 'production'
+     */
+    cache?: boolean;
+    /**
+     * Path to the views directory.
+     * @default './views'
+     */
+    views?: string;
+    /**
+     * Squirrelly specific configuration options overriden.
+     */
+    options?: Record<string, any>;
+}
+
+export const squirrellyify: FastifyPluginAsync<SquirrellyifyOptions>;
+export default squirrellyify;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ynode/squirrellyify",
-    "version": "1.3.0",
+    "version": "1.5.2",
     "description": "Fastify plugin for rendering Squirrelly templates.",
     "main": "src/plugin.js",
     "type": "module",
@@ -21,16 +21,18 @@
         "squirrelly"
     ],
     "engines": {
-        "node": ">=18"
+        "node": ">=20"
     },
     "devDependencies": {
         "@eslint/js": "^9.37.0",
         "@eslint/json": "^0.13.2",
         "@eslint/markdown": "^7.4.0",
         "@mikinho/autover": "^2.0.1",
+        "auto-changelog": "^2.5.0",
         "eslint": "^9.37.0",
         "eslint-config-prettier": "^10.1.8",
         "eslint-plugin-prettier": "^5.5.4",
+        "eslint-plugin-simple-import-sort": "^12.1.1",
         "fastify": "^5.8.1",
         "globals": "^16.4.0",
         "jsdoc": "^4.0.5",
@@ -38,6 +40,7 @@
         "rimraf": "^6.0.1"
     },
     "scripts": {
+        "changelog": "auto-changelog -p",
         "docs": "node scripts/gen-docs.mjs",
         "docs:clean": "rimraf docs || rmdir /s /q docs 2> NUL || true",
         "docs:open": "node -e \"import('node:child_process').then(m=>m.exec(process.platform==='win32'?'start docs/index.html':(process.platform==='darwin'?'open docs/index.html':'xdg-open docs/index.html')))\"",
@@ -49,14 +52,15 @@
         "test:staged": "node scripts/lint-staged.mjs",
         "ver:preview": "npx autover --no-amend --dry-run --short",
         "ver:apply": "npx autover --guard-unchanged --short",
-        "test": "npm run lint && npm run test:integration",
-        "prepublishOnly": "npm test",
+        "test": "node --test",
+        "prepublishOnly": "npm run lint && npm test",
         "postversion": "git push && git push --tags"
     },
     "publishConfig": {
         "access": "public"
     },
     "files": [
+        "index.d.ts",
         "src",
         "README.md",
         "LICENSE"
@@ -65,7 +69,7 @@
         "fastify-plugin": "^5.1.0"
     },
     "peerDependencies": {
-        "fastify": "^5.0.0",
+        "fastify": "5.x",
         "squirrelly": "^9.1.0"
     }
 }

package/src/config.js

@@ -19,18 +19,13 @@ function assertOptionType(condition, message) {
 function normalizeDefaultExtension(defaultExtension) {
     const normalized = defaultExtension.replace(/^\.+/, "");
     if (normalized.length === 0) {
-        throw new TypeError(
-            'Invalid option "defaultExtension": must contain at least one non-dot character.',
-        );
+        throw new TypeError('Invalid option "defaultExtension": must contain at least one non-dot character.');
     }
     return normalized;
 }
 
 export function validatePluginOptions(options = {}) {
-    assertOptionType(
-        isPlainObject(options),
-        "Invalid options: plugin options must be a plain object.",
-    );
+    assertOptionType(isPlainObject(options), "Invalid options: plugin options must be a plain object.");
 
     if (options.templates !== undefined) {
         assertOptionType(
@@ -52,8 +47,7 @@ export function validatePluginOptions(options = {}) {
     }
     if (options.partialsNamespace !== undefined) {
         assertOptionType(
-            typeof options.partialsNamespace === "boolean" ||
-                typeof options.partialsNamespace === "string",
+            typeof options.partialsNamespace === "boolean" || typeof options.partialsNamespace === "string",
             'Invalid option "partialsNamespace": expected a boolean or a string.',
         );
     }
@@ -80,10 +74,7 @@ export function validatePluginOptions(options = {}) {
             );
         }
         if (options.sqrl.config !== undefined) {
-            assertOptionType(
-                isPlainObject(options.sqrl.config),
-                'Invalid option "sqrl.config": expected an object.',
-            );
+            assertOptionType(isPlainObject(options.sqrl.config), 'Invalid option "sqrl.config": expected an object.');
         }
         if (options.sqrl.helpers !== undefined) {
             assertOptionType(
@@ -130,9 +121,7 @@ export function resolveInitialPartialsDirs(options = {}) {
 
 export function resolveExtension(options = {}) {
     const defaultExtension =
-        options.defaultExtension !== undefined
-            ? normalizeDefaultExtension(options.defaultExtension)
-            : "sqrl";
+        options.defaultExtension !== undefined ? normalizeDefaultExtension(options.defaultExtension) : "sqrl";
     return {
         defaultExtension,
         extensionWithDot: `.${defaultExtension}`,
@@ -153,15 +142,7 @@ function createScopedSqrlConfig(baseConfig) {
     const scopedFilters = new Cacher({});
     const scopedTemplates = new Cacher({});
 
-    for (const helperName of [
-        "each",
-        "foreach",
-        "include",
-        "extends",
-        "useScope",
-        "includeFile",
-        "extendsFile",
-    ]) {
+    for (const helperName of ["each", "foreach", "include", "extends", "useScope", "includeFile", "extendsFile"]) {
         const helperFn = Sqrl.helpers.get(helperName);
         if (helperFn) {
             scopedHelpers.define(helperName, helperFn);

package/src/plugin.js

@@ -31,19 +31,14 @@ import fp from "fastify-plugin";
 import Sqrl from "squirrelly";
 
 import {
-    validatePluginOptions,
     resolveExtension,
     resolveInitialPartialsDirs,
     resolveInitialTemplateDirs,
     resolveSqrlConfig,
     resolveUseCache,
+    validatePluginOptions,
 } from "./config.js";
-import {
-    buildTemplateSearchDirs,
-    collectViewScope,
-    createTemplateResolver,
-    preloadPartials,
-} from "./resolver.js";
+import { buildTemplateSearchDirs, collectViewScope, createTemplateResolver, preloadPartials } from "./resolver.js";
 import { createRuntimeApi } from "./runtime-api.js";
 import { assertSafeName } from "./safety.js";
 
@@ -75,20 +70,20 @@ import { assertSafeName } from "./safety.js";
 async function squirrellyify(fastify, options = {}) {
     validatePluginOptions(options);
 
+    if (typeof fastify.hasDecorator === "function" && fastify.hasDecorator("Sqrl")) {
+        throw new Error("@ynode/squirrellyify has already been registered");
+    }
+
+    const log =
+        typeof fastify.log?.child === "function" ? fastify.log.child({ name: "@ynode/squirrellyify" }) : fastify.log;
+
     const initialTemplatesDirs = resolveInitialTemplateDirs(options);
     const initialPartialsDirs = resolveInitialPartialsDirs(options);
     const initialLayout = options.layout;
     const { extensionWithDot } = resolveExtension(options);
     const useCache = resolveUseCache(options);
     const { sqrlScope, sqrlConfig } = resolveSqrlConfig(options);
-    const {
-        defineSqrlHelper,
-        defineSqrlFilter,
-        defineSqrlTemplate,
-        viewHelpers,
-        viewFilters,
-        viewPartials,
-    } =
+    const { defineSqrlHelper, defineSqrlFilter, defineSqrlTemplate, viewHelpers, viewFilters, viewPartials } =
         createRuntimeApi({
             sqrlScope,
             sqrlConfig,
@@ -131,10 +126,8 @@ async function squirrellyify(fastify, options = {}) {
     async function view(template, data = {}) {
         try {
             const requestData = data && typeof data === "object" ? data : {};
-            const replyContext =
-                this.context && typeof this.context === "object" ? this.context : {};
-            const replyLocals =
-                this.locals && typeof this.locals === "object" ? this.locals : {};
+            const replyContext = this.context && typeof this.context === "object" ? this.context : {};
+            const replyLocals = this.locals && typeof this.locals === "object" ? this.locals : {};
             const mergedData = {
                 ...replyContext,
                 ...replyLocals,
@@ -148,17 +141,12 @@ async function squirrellyify(fastify, options = {}) {
 
             const instance = this.request.server;
             const { aggregatedTemplatesDirs, scopedLayout } = collectViewScope(instance);
-            const templateSearchDirs = buildTemplateSearchDirs(
-                aggregatedTemplatesDirs,
-                initialTemplatesDirs,
-            );
+            const templateSearchDirs = buildTemplateSearchDirs(aggregatedTemplatesDirs, initialTemplatesDirs);
 
             // 1. Find and render the page template
             const pagePath = await findTemplatePath(template, templateSearchDirs);
             if (!pagePath) {
-                throw new Error(
-                    `Template "${template}" not found in [${templateSearchDirs.join(", ")}]`,
-                );
+                throw new Error(`Template "${template}" not found in [${templateSearchDirs.join(", ")}]`);
             }
 
             const pageTemplate = await getTemplate(pagePath);
@@ -179,22 +167,18 @@ async function squirrellyify(fastify, options = {}) {
             // 3. Find and render the layout, injecting the page content
             const layoutPath = await findTemplatePath(layoutFile, templateSearchDirs);
             if (!layoutPath) {
-                throw new Error(
-                    `Layout "${layoutFile}" not found in [${templateSearchDirs.join(", ")}]`,
-                );
+                throw new Error(`Layout "${layoutFile}" not found in [${templateSearchDirs.join(", ")}]`);
             }
 
             const layoutTemplate = await getTemplate(layoutPath);
             const layoutPayload =
-                mergedData.layoutData && typeof mergedData.layoutData === "object"
-                    ? mergedData.layoutData
-                    : {};
+                mergedData.layoutData && typeof mergedData.layoutData === "object" ? mergedData.layoutData : {};
             const layoutData = { ...mergedData, ...layoutPayload, body: pageHtml };
             const finalHtml = await layoutTemplate(layoutData, sqrlConfig);
 
             return this.type("text/html").send(finalHtml);
         } catch (error) {
-            this.request.server.log.error(error);
+            log.error(error);
             if (process.env.NODE_ENV === "production") {
                 // In production, send a generic error and don't leak details
                 this.status(500).send("An internal server error occurred.");

package/src/resolver.js

@@ -79,12 +79,7 @@ export async function preloadPartials({
             const files = await collectPartialFiles(partialsDir, extensionWithDot, partialsRecursive);
             await Promise.all(
                 files.map(async (partialPath) => {
-                    const partialName = resolvePartialName(
-                        partialPath,
-                        partialsDir,
-                        extensionWithDot,
-                        namespace,
-                    );
+                    const partialName = resolvePartialName(partialPath, partialsDir, extensionWithDot, namespace);
                     const content = await fs.readFile(partialPath, "utf-8");
                     fastify.log.trace(`Loaded partial: ${partialName}`);
                     defineSqrlTemplate(partialName, Sqrl.compile(content, sqrlConfig));
@@ -110,9 +105,7 @@ export function collectViewScope(instance) {
 
     while (currentInstance) {
         if (currentInstance.views) {
-            const dirs = Array.isArray(currentInstance.views)
-                ? currentInstance.views
-                : [currentInstance.views];
+            const dirs = Array.isArray(currentInstance.views) ? currentInstance.views : [currentInstance.views];
             aggregatedTemplatesDirs.push(...dirs);
         }
         if (scopedLayout === null && currentInstance.layout !== null && currentInstance.layout !== undefined) {