@ynode/squirrellyify 1.2.0 → 1.5.1

package/README.md

@@ -74,26 +74,49 @@ 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:
+
+```javascript
+fastify.addHook("preHandler", async (request, reply) => {
+    reply.locals = { appName: "YNode", greeting: "Welcome" };
+});
+
+fastify.get("/", (request, reply) => {
+    // Route-level values win over locals/context on key conflicts.
+    return reply.view("index", { greeting: "Hello" });
+});
+```
+
+Merge precedence is:
+
+1. `reply.context`
+2. `reply.locals`
+3. `reply.view(..., data)` (highest precedence)
+
 ## Configuration Options
 
 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:
 
 - `fastify.viewHelpers.define(name, fn)`, `fastify.viewHelpers.get(name)`, `fastify.viewHelpers.remove(name)`
 - `fastify.viewFilters.define(name, fn)`, `fastify.viewFilters.get(name)`, `fastify.viewFilters.remove(name)`
-- `fastify.viewPartials.define(name, templateOrFn)`, `fastify.viewPartials.get(name)`, `fastify.viewPartials.remove(name)`
+- `fastify.viewPartials.define(name, templateOrFn)`, `fastify.viewPartials.get(name)`,
+  `fastify.viewPartials.remove(name)`
 - `fastify.viewCache.clear()`, `fastify.viewCache.stats()`
 
 These APIs are scope-aware:
@@ -101,8 +124,8 @@ 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.
 
@@ -110,8 +133,8 @@ 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`**
 
@@ -124,8 +147,8 @@ variable within the layout.
     <body>
         <header>My Awesome Site</header>
         <main>
-            {{@block("content")}} {{@try}} {{it.body | safe}} {{#catch => err}} Uh-oh, error!
-            Message was '{{err.message}}' {{/try}} {{/block}}
+            {{@block("content")}} {{@try}} {{it.body | safe}} {{#catch => err}} Uh-oh, error! Message was
+            '{{err.message}}' {{/try}} {{/block}}
         </main>
     </body>
 </html>
@@ -169,9 +192,8 @@ 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`**
 
@@ -236,8 +258,8 @@ 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";
@@ -286,8 +308,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, {
@@ -310,3 +331,4 @@ fastify.register(squirrellyify, {
 ## License
 
 This project is licensed under the [MIT License](./LICENSE).
+

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.2.0",
+    "version": "1.5.1",
     "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,
@@ -130,32 +125,36 @@ 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 mergedData = {
+                ...replyContext,
+                ...replyLocals,
+                ...requestData,
+            };
+
             assertSafeName(template);
-            if (data.layout && data.layout !== false) {
-                assertSafeName(data.layout);
+            if (mergedData.layout && mergedData.layout !== false) {
+                assertSafeName(mergedData.layout);
             }
 
             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);
-            const pageHtml = await pageTemplate(data, sqrlConfig);
+            const pageHtml = await pageTemplate(mergedData, sqrlConfig);
 
             // 2. Determine which layout to use
             const currentLayout = scopedLayout !== null ? scopedLayout : initialLayout;
-            const layoutFile = data.layout === false ? null : data.layout || currentLayout;
+            const layoutFile = mergedData.layout === false ? null : mergedData.layout || currentLayout;
 
             if (!layoutFile) {
                 return this.type("text/html").send(pageHtml);
@@ -168,18 +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 layoutData = { ...data, ...data.layoutData, body: pageHtml };
+            const layoutPayload =
+                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) {