@ynode/squirrellyify 1.0.1 → 1.1.1

package/README.md

@@ -3,8 +3,7 @@
 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)
-[![build](https://img.shields.io/github/actions/workflow/status/yammm/ynode-squirrellyify/your-workflow.yml)](https://github.com/yammm/ynode-squirrellyify/actions)
-[![license](https://img.shields.io/npm/l/@ynode/squirrellyify.svg)](https://github.com/yammm/ynode-squirrellyify/blob/main/LICENSE)
+[![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/).
@@ -14,7 +13,7 @@ A simple and fast plugin for using the [Squirrelly](https://squirrelly.js.org/)
 - 🐿️ **Modern Templating:** Full support for Squirrelly v9 features.
 - ⚡ **High Performance:** Template caching is enabled by default in production.
 - 📁 **Layouts & Partials:** Built-in support for layouts and shared partials.
-- 🧬 **Encapsulation-Aware:** Respects Fastify's encapsulation model for s ed configurations.
+- 🧬 **Encapsulation-Aware:** Supports Fastify encapsulation with scoped template settings.
 - 🛡️ **Secure:** Protects against path traversal attacks in template names.
 - 🔧 **Extensible:** Easily add custom Squirrelly helpers and filters.
 
@@ -82,11 +81,21 @@ 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 are available globally by their filename. |
+| `partials`         | `string \| string[]` | `[]`                                | The directory or directories for partial templates. All partials are loaded on startup and available by filename.                     |
 | `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.                                                                                           |
 | `cache`            | `boolean`            | `NODE_ENV === "production"`         | If `true`, compiled templates and resolved file paths will be cached in memory.                                                      |
-| `sqrl`             | `object`             | `undefined`                         | An object to configure Squirrelly. Currently supports `{ helpers: {}, filters: {} }` for adding custom functions.                    |
+| `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)`
+
+These APIs are scope-aware:
+
+- In `global` mode they modify shared helpers/filters.
+- In `scoped` mode they only affect the current plugin registration scope.
 
 ## Advanced Usage
 
@@ -158,7 +167,7 @@ there. They will be automatically registered by their filename.
 
 ```html
 <div class="card">
-    <h3>{{ it.name }}</h4>
+    <h3>{{ it.name }}</h3>
     <p>{{ it.email }}</p>
 </div>
 ```
@@ -224,6 +233,14 @@ fastify.register(
 
 You can extend Squirrelly with custom helper and filter functions via the `sqrl` option.
 
+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`.
+
 ```javascript
 fastify.register(squirrellyify, {
     templates: "views",
@@ -244,4 +261,4 @@ fastify.register(squirrellyify, {
 
 ## License
 
-[MIT](./LICENSE)
+This project is licensed under the [MIT License](./LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ynode/squirrellyify",
-    "version": "1.0.1",
+    "version": "1.1.1+93166.v1.1-1-g7a9f0f7",
     "description": "Fastify plugin for rendering Squirrelly templates.",
     "main": "src/plugin.js",
     "type": "module",
@@ -31,10 +31,11 @@
         "eslint": "^9.37.0",
         "eslint-config-prettier": "^10.1.8",
         "eslint-plugin-prettier": "^5.5.4",
+        "fastify": "^5.8.1",
         "globals": "^16.4.0",
+        "jsdoc": "^4.0.5",
         "prettier": "^3.6.2",
-        "rimraf": "^6.0.1",
-        "yuidocjs": "^0.10.2"
+        "rimraf": "^6.0.1"
     },
     "scripts": {
         "docs": "node scripts/gen-docs.mjs",
@@ -44,10 +45,12 @@
         "format:check": "prettier --check .",
         "lint": "eslint .",
         "lint:fix": "eslint . --fix",
+        "test:integration": "node --test tests/**/*.test.js",
+        "test:staged": "eslint --no-warn-ignored $(git diff --cached --name-only --diff-filter=ACMRTUXB | tr '\\n' ' ')",
         "ver:preview": "npx autover --no-amend --dry-run --short",
         "ver:apply": "npx autover --guard-unchanged --short",
-        "test": "eslint --no-warn-ignored $(git diff --cached --name-only --diff-filter=ACMRTUXB | tr '\\n' ' ')",
-        "prepublishOnly": "npm test || true",
+        "test": "npm run lint && npm run test:integration",
+        "prepublishOnly": "npm test",
         "postversion": "git push && git push --tags"
     },
     "publishConfig": {
@@ -59,7 +62,10 @@
         "LICENSE"
     ],
     "dependencies": {
-        "fastify-plugin": "^5.1.0",
+        "fastify-plugin": "^5.1.0"
+    },
+    "peerDependencies": {
+        "fastify": "^5.0.0",
         "squirrelly": "^9.1.0"
     }
 }

package/src/plugin.js

@@ -34,9 +34,9 @@ import fp from "fastify-plugin";
 import Sqrl from "squirrelly";
 
 /**
- * @typedef {import("fastify").FastifyInstance} FastifyInstance
- * @typedef {import("fastify").FastifyReply} FastifyReply
- * @typedef {import("squirrelly").SqrlConfig} SqrlConfig
+ * @typedef {object} FastifyInstance
+ * @typedef {object} FastifyReply
+ * @typedef {object} SqrlConfig
  */
 
 /**
@@ -50,20 +50,25 @@ import Sqrl from "squirrelly";
  * @param {string} [options.layout] The name of the default layout file to use (without extension).
  * @param {string} [options.defaultExtension="sqrl"] The default extension for template files.
  * @param {boolean} [options.cache] Enables template caching. Defaults to true if NODE_ENV is "production".
+ * @param {object} [options.sqrl] Squirrelly engine options.
+ * @param {"global"|"scoped"} [options.sqrl.scope="global"] Whether to share helpers/filters/partials globally or isolate them per Fastify registration.
+ * @param {SqrlConfig} [options.sqrl.config] Squirrelly compile/render config.
+ * @param {Record<string, Function>} [options.sqrl.helpers] Custom Squirrelly helpers.
+ * @param {Record<string, Function>} [options.sqrl.filters] Custom Squirrelly filters.
  */
 async function squirrellyify(fastify, options = {}) {
     // Get initial options and set defaults from the plugin registration
     const initialTemplatesDirs = Array.isArray(options.templates)
         ? options.templates
         : typeof options.templates === "string"
-            ? [options.templates]
-            : [path.join(process.cwd(), "views")];
+          ? [options.templates]
+          : [path.join(process.cwd(), "views")];
 
     const initialPartialsDirs = Array.isArray(options.partials)
         ? options.partials
         : typeof options.partials === "string"
-            ? [options.partials]
-            : [];
+          ? [options.partials]
+          : [];
 
     const initialLayout = options.layout;
     const defaultExtension = options.defaultExtension || "sqrl";
@@ -73,24 +78,109 @@ async function squirrellyify(fastify, options = {}) {
     const pathCache = new Map();
     const templateMeta = new Map();
 
-    // Allow passing optional Squirrelly compile/render configuration
-    const sqrlConfig = options.sqrl?.config;
+    /**
+     * When using scoped mode, clone built-ins into per-plugin caches so helpers/filters/partials
+     * do not bleed across Fastify encapsulation boundaries.
+     *
+     * @param {SqrlConfig|undefined} baseConfig
+     * @returns {SqrlConfig}
+     */
+    function createScopedSqrlConfig(baseConfig) {
+        const Cacher = Sqrl.helpers?.constructor;
+        if (typeof Cacher !== "function") {
+            throw new Error("Unable to initialize scoped Squirrelly storage.");
+        }
+
+        const scopedHelpers = new Cacher({});
+        const scopedFilters = new Cacher({});
+        const scopedTemplates = new Cacher({});
+
+        for (const helperName of [
+            "each",
+            "foreach",
+            "include",
+            "extends",
+            "useScope",
+            "includeFile",
+            "extendsFile",
+        ]) {
+            const helperFn = Sqrl.helpers.get(helperName);
+            if (helperFn) {
+                scopedHelpers.define(helperName, helperFn);
+            }
+        }
+
+        const escapeFilter = Sqrl.filters.get("e");
+        if (escapeFilter) {
+            scopedFilters.define("e", escapeFilter);
+        }
+
+        return Sqrl.getConfig(
+            {
+                ...baseConfig,
+                storage: {
+                    helpers: scopedHelpers,
+                    nativeHelpers: Sqrl.nativeHelpers,
+                    filters: scopedFilters,
+                    templates: scopedTemplates,
+                },
+            },
+            Sqrl.defaultConfig,
+        );
+    }
+
+    const sqrlScope = options.sqrl?.scope === "scoped" ? "scoped" : "global";
+    const sqrlConfig =
+        sqrlScope === "scoped"
+            ? createScopedSqrlConfig(options.sqrl?.config)
+            : Sqrl.getConfig(options.sqrl?.config ?? {}, Sqrl.defaultConfig);
+    const helpersStore = sqrlScope === "scoped" ? sqrlConfig.storage.helpers : Sqrl.helpers;
+    const filtersStore = sqrlScope === "scoped" ? sqrlConfig.storage.filters : Sqrl.filters;
+    const templatesStore = sqrlScope === "scoped" ? sqrlConfig.storage.templates : Sqrl.templates;
+
+    function defineSqrlHelper(name, fn) {
+        helpersStore.define(name, fn);
+    }
+
+    function getSqrlHelper(name) {
+        return helpersStore.get(name);
+    }
+
+    function removeSqrlHelper(name) {
+        helpersStore.remove(name);
+    }
+
+    function defineSqrlFilter(name, fn) {
+        filtersStore.define(name, fn);
+    }
+
+    function getSqrlFilter(name) {
+        return filtersStore.get(name);
+    }
+
+    function removeSqrlFilter(name) {
+        filtersStore.remove(name);
+    }
+
+    function defineSqrlTemplate(name, fn) {
+        templatesStore.define(name, fn);
+    }
 
     // Allow Passing Custom Squirrelly Configuration
     if (options.sqrl) {
         if (options.sqrl.helpers) {
             Object.entries(options.sqrl.helpers).forEach(([name, fn]) => {
-                Sqrl.helpers.define(name, fn);
+                defineSqrlHelper(name, fn);
             });
         }
         if (options.sqrl.filters) {
             Object.entries(options.sqrl.filters).forEach(([name, fn]) => {
-                Sqrl.filters.define(name, fn);
+                defineSqrlFilter(name, fn);
             });
         }
     }
 
-    // Pre-load and define all partials globally on startup from all partial directories
+    // Pre-load and define all partials on startup from all partial directories
     if (initialPartialsDirs.length > 0) {
         for (const partialsDir of initialPartialsDirs) {
             try {
@@ -102,7 +192,7 @@ async function squirrellyify(fastify, options = {}) {
                             const partialName = path.basename(file, extensionWithDot);
                             const content = await fs.readFile(partialPath, "utf-8");
                             fastify.log.trace(`Loaded partial: ${partialName}`);
-                            Sqrl.templates.define(partialName, Sqrl.compile(content, sqrlConfig));
+                            defineSqrlTemplate(partialName, Sqrl.compile(content, sqrlConfig));
                         }
                     }),
                 );
@@ -131,16 +221,24 @@ async function squirrellyify(fastify, options = {}) {
     }
 
     /**
-     * Because template comes from route code, a mistaken ../ could escape the views dir.
-     * Disallow path separators and .. in template/layout names.
+     * Allow nested forward-slash paths (e.g. "admin/dashboard"), but block traversal
+     * or absolute paths.
      */
     function assertSafeName(name) {
-        if (
-            name.includes("..") ||
-            name.includes(path.sep) ||
-            name.includes("/") ||
-            name.includes("\\")
-        ) {
+        if (typeof name !== "string" || name.length === 0 || name.includes("\0")) {
+            throw new Error(`Illegal template name: ${name}`);
+        }
+        if (name.includes("\\") || path.posix.isAbsolute(name) || path.win32.isAbsolute(name)) {
+            throw new Error(`Illegal template name: ${name}`);
+        }
+        const normalized = path.posix.normalize(name);
+        if (normalized !== name || normalized === "." || normalized === "..") {
+            throw new Error(`Illegal template name: ${name}`);
+        }
+        if (normalized.startsWith("../")) {
+            throw new Error(`Illegal template name: ${name}`);
+        }
+        if (name.split("/").some((segment) => segment.length === 0 || segment === "." || segment === "..")) {
             throw new Error(`Illegal template name: ${name}`);
         }
     }
@@ -218,7 +316,7 @@ async function squirrellyify(fastify, options = {}) {
             }
 
             const pageTemplate = await getTemplate(pagePath);
-            const pageHtml = pageTemplate(data, sqrlConfig ?? Sqrl.defaultConfig);
+            const pageHtml = await pageTemplate(data, sqrlConfig);
 
             // 2. Determine which layout to use
             const currentLayout = scopedLayout !== null ? scopedLayout : initialLayout;
@@ -243,11 +341,11 @@ async function squirrellyify(fastify, options = {}) {
 
             const layoutTemplate = await getTemplate(layoutPath);
             const layoutData = { ...data, ...data.layoutData, body: pageHtml };
-            const finalHtml = layoutTemplate(layoutData, sqrlConfig ?? Sqrl.defaultConfig);
+            const finalHtml = await layoutTemplate(layoutData, sqrlConfig);
 
             return this.type("text/html").send(finalHtml);
         } catch (error) {
-            fastify.log.error(error);
+            this.request.server.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.");
@@ -264,6 +362,16 @@ async function squirrellyify(fastify, options = {}) {
     // Decorate the fastify instance so users can override settings in different scopes
     fastify.decorate("views", null);
     fastify.decorate("layout", null);
+    fastify.decorate("viewHelpers", {
+        define: defineSqrlHelper,
+        get: getSqrlHelper,
+        remove: removeSqrlHelper,
+    });
+    fastify.decorate("viewFilters", {
+        define: defineSqrlFilter,
+        get: getSqrlFilter,
+        remove: removeSqrlFilter,
+    });
 
     // Also expose the Squirrelly engine itself for advanced configuration (e.g., adding helpers/filters)
     fastify.decorate("Sqrl", Sqrl);
@@ -271,5 +379,5 @@ async function squirrellyify(fastify, options = {}) {
 
 export default fp(squirrellyify, {
     fastify: "5.x",
-    name: "squirrellyify",
+    name: "@ynode/squirrellyify",
 });