@ynode/squirrellyify 1.1.1 → 1.2.0

package/README.md

@@ -81,9 +81,11 @@ 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 filename.                     |
+| `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.                                                                                           |
+| `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 }`.                                            |
 
@@ -91,12 +93,19 @@ 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.viewCache.clear()`, `fastify.viewCache.stats()`
 
 These APIs are scope-aware:
 
-- In `global` mode they modify shared helpers/filters.
+- 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.
+
+Invalid option types are rejected at plugin registration time with descriptive errors.
+
 ## Advanced Usage
 
 ### Layouts
@@ -161,7 +170,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. They will be automatically registered by their filename.
+there. By default, partials are loaded recursively and registered by forward-slash path from the
+partials directory root.
 
 **`partials/user-card.sqrl`**
 
@@ -176,7 +186,7 @@ there. They will be automatically registered by their filename.
 
 ```html
 <h1>Users</h1>
-{{ include('user-card', { name: 'John Doe', email: 'john@example.com' }) /}}
+{{@include('user-card', { name: 'John Doe', email: 'john@example.com' })/}}
 ```
 
 **Register the `partials` directory:**
@@ -188,6 +198,42 @@ fastify.register(squirrellyify, {
 });
 ```
 
+Nested partials use forward-slash names:
+
+```text
+partials/
+└── cards/
+    └── user-card.sqrl
+```
+
+```html
+{{@include('cards/user-card', { name: 'John Doe', email: 'john@example.com' })/}}
+```
+
+To disable recursive loading:
+
+```javascript
+fastify.register(squirrellyify, {
+    templates: "views",
+    partials: "partials",
+    partialsRecursive: false,
+});
+```
+
+To namespace partial names:
+
+```javascript
+fastify.register(squirrellyify, {
+    templates: "views",
+    partials: "partials",
+    partialsNamespace: "shared",
+});
+```
+
+```html
+{{@include('shared/cards/user-card', { name: 'John Doe', email: 'john@example.com' })/}}
+```
+
 ### Scoped Configuration (Encapsulation)
 
 This plugin supports Fastify's encapsulation model. You can register it multiple times with
@@ -197,8 +243,10 @@ different settings for different route prefixes.
 import Fastify from "fastify";
 import squirrellyify from "@ynode/squirrellyify";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 
 const fastify = Fastify();
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 // Register with default settings
 fastify.register(squirrellyify, {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ynode/squirrellyify",
-    "version": "1.1.1+93166.v1.1-1-g7a9f0f7",
+    "version": "1.2.0",
     "description": "Fastify plugin for rendering Squirrelly templates.",
     "main": "src/plugin.js",
     "type": "module",
@@ -46,7 +46,7 @@
         "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' ' ')",
+        "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",

package/src/config.js

@@ -0,0 +1,201 @@
+import path from "node:path";
+
+import Sqrl from "squirrelly";
+
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+
+function assertOptionType(condition, message) {
+    if (!condition) {
+        throw new TypeError(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.',
+        );
+    }
+    return normalized;
+}
+
+export function validatePluginOptions(options = {}) {
+    assertOptionType(
+        isPlainObject(options),
+        "Invalid options: plugin options must be a plain object.",
+    );
+
+    if (options.templates !== undefined) {
+        assertOptionType(
+            typeof options.templates === "string" || isStringArray(options.templates),
+            'Invalid option "templates": expected a string or an array of strings.',
+        );
+    }
+    if (options.partials !== undefined) {
+        assertOptionType(
+            typeof options.partials === "string" || isStringArray(options.partials),
+            'Invalid option "partials": expected a string or an array of strings.',
+        );
+    }
+    if (options.partialsRecursive !== undefined) {
+        assertOptionType(
+            typeof options.partialsRecursive === "boolean",
+            'Invalid option "partialsRecursive": expected a boolean.',
+        );
+    }
+    if (options.partialsNamespace !== undefined) {
+        assertOptionType(
+            typeof options.partialsNamespace === "boolean" ||
+                typeof options.partialsNamespace === "string",
+            'Invalid option "partialsNamespace": expected a boolean or a string.',
+        );
+    }
+    if (options.layout !== undefined) {
+        assertOptionType(typeof options.layout === "string", 'Invalid option "layout": expected a string.');
+    }
+    if (options.defaultExtension !== undefined) {
+        assertOptionType(
+            typeof options.defaultExtension === "string",
+            'Invalid option "defaultExtension": expected a string.',
+        );
+        normalizeDefaultExtension(options.defaultExtension);
+    }
+    if (options.cache !== undefined) {
+        assertOptionType(typeof options.cache === "boolean", 'Invalid option "cache": expected a boolean.');
+    }
+    if (options.sqrl !== undefined) {
+        assertOptionType(isPlainObject(options.sqrl), 'Invalid option "sqrl": expected an object.');
+
+        if (options.sqrl.scope !== undefined) {
+            assertOptionType(
+                options.sqrl.scope === "global" || options.sqrl.scope === "scoped",
+                'Invalid option "sqrl.scope": expected "global" or "scoped".',
+            );
+        }
+        if (options.sqrl.config !== undefined) {
+            assertOptionType(
+                isPlainObject(options.sqrl.config),
+                'Invalid option "sqrl.config": expected an object.',
+            );
+        }
+        if (options.sqrl.helpers !== undefined) {
+            assertOptionType(
+                isPlainObject(options.sqrl.helpers),
+                'Invalid option "sqrl.helpers": expected an object of functions.',
+            );
+            for (const [name, fn] of Object.entries(options.sqrl.helpers)) {
+                assertOptionType(
+                    typeof fn === "function",
+                    `Invalid option "sqrl.helpers.${name}": expected a function.`,
+                );
+            }
+        }
+        if (options.sqrl.filters !== undefined) {
+            assertOptionType(
+                isPlainObject(options.sqrl.filters),
+                'Invalid option "sqrl.filters": expected an object of functions.',
+            );
+            for (const [name, fn] of Object.entries(options.sqrl.filters)) {
+                assertOptionType(
+                    typeof fn === "function",
+                    `Invalid option "sqrl.filters.${name}": expected a function.`,
+                );
+            }
+        }
+    }
+}
+
+export function resolveInitialTemplateDirs(options = {}) {
+    return Array.isArray(options.templates)
+        ? options.templates
+        : typeof options.templates === "string"
+          ? [options.templates]
+          : [path.join(process.cwd(), "views")];
+}
+
+export function resolveInitialPartialsDirs(options = {}) {
+    return Array.isArray(options.partials)
+        ? options.partials
+        : typeof options.partials === "string"
+          ? [options.partials]
+          : [];
+}
+
+export function resolveExtension(options = {}) {
+    const defaultExtension =
+        options.defaultExtension !== undefined
+            ? normalizeDefaultExtension(options.defaultExtension)
+            : "sqrl";
+    return {
+        defaultExtension,
+        extensionWithDot: `.${defaultExtension}`,
+    };
+}
+
+export function resolveUseCache(options = {}) {
+    return options.cache ?? process.env.NODE_ENV === "production";
+}
+
+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,
+    );
+}
+
+export function resolveSqrlConfig(options = {}) {
+    const sqrlScope = options.sqrl?.scope === "scoped" ? "scoped" : "global";
+    const sqrlConfig =
+        sqrlScope === "scoped"
+            ? createScopedSqrlConfig(options.sqrl?.config)
+            : Sqrl.getConfig(options.sqrl?.config ?? {}, Sqrl.defaultConfig);
+
+    return {
+        sqrlScope,
+        sqrlConfig,
+    };
+}

package/src/plugin.js

@@ -27,12 +27,26 @@ IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
 CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */
 
-import fs from "node:fs/promises";
-import path from "node:path";
-
 import fp from "fastify-plugin";
 import Sqrl from "squirrelly";
 
+import {
+    validatePluginOptions,
+    resolveExtension,
+    resolveInitialPartialsDirs,
+    resolveInitialTemplateDirs,
+    resolveSqrlConfig,
+    resolveUseCache,
+} from "./config.js";
+import {
+    buildTemplateSearchDirs,
+    collectViewScope,
+    createTemplateResolver,
+    preloadPartials,
+} from "./resolver.js";
+import { createRuntimeApi } from "./runtime-api.js";
+import { assertSafeName } from "./safety.js";
+
 /**
  * @typedef {object} FastifyInstance
  * @typedef {object} FastifyReply
@@ -47,6 +61,8 @@ import Sqrl from "squirrelly";
  * @param {object} options Plugin options.
  * @param {string|string[]} [options.templates] The directory or directories where page and layout templates are stored. Defaults to "views". Directories are searched in order.
  * @param {string|string[]} [options.partials] The directory or directories where partial templates are stored.
+ * @param {boolean} [options.partialsRecursive=true] Enables recursive loading of partial templates from subdirectories.
+ * @param {boolean|string} [options.partialsNamespace=false] Optional namespace prefix for partial names. Use `true` to namespace by partials directory basename.
  * @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".
@@ -57,191 +73,54 @@ import Sqrl from "squirrelly";
  * @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")];
-
-    const initialPartialsDirs = Array.isArray(options.partials)
-        ? options.partials
-        : typeof options.partials === "string"
-          ? [options.partials]
-          : [];
+    validatePluginOptions(options);
 
+    const initialTemplatesDirs = resolveInitialTemplateDirs(options);
+    const initialPartialsDirs = resolveInitialPartialsDirs(options);
     const initialLayout = options.layout;
-    const defaultExtension = options.defaultExtension || "sqrl";
-    const extensionWithDot = `.${defaultExtension}`;
-    const useCache = options.cache ?? process.env.NODE_ENV === "production";
-    const templateCache = new Map();
-    const pathCache = new Map();
-    const templateMeta = new Map();
-
-    /**
-     * 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]) => {
-                defineSqrlHelper(name, fn);
-            });
-        }
-        if (options.sqrl.filters) {
-            Object.entries(options.sqrl.filters).forEach(([name, fn]) => {
-                defineSqrlFilter(name, fn);
-            });
-        }
+    const { extensionWithDot } = resolveExtension(options);
+    const useCache = resolveUseCache(options);
+    const { sqrlScope, sqrlConfig } = resolveSqrlConfig(options);
+    const {
+        defineSqrlHelper,
+        defineSqrlFilter,
+        defineSqrlTemplate,
+        viewHelpers,
+        viewFilters,
+        viewPartials,
+    } =
+        createRuntimeApi({
+            sqrlScope,
+            sqrlConfig,
+        });
+
+    if (options.sqrl?.helpers) {
+        Object.entries(options.sqrl.helpers).forEach(([name, fn]) => {
+            defineSqrlHelper(name, fn);
+        });
     }
-
-    // Pre-load and define all partials on startup from all partial directories
-    if (initialPartialsDirs.length > 0) {
-        for (const partialsDir of initialPartialsDirs) {
-            try {
-                const files = await fs.readdir(partialsDir);
-                await Promise.all(
-                    files.map(async (file) => {
-                        if (file.endsWith(extensionWithDot)) {
-                            const partialPath = path.join(partialsDir, file);
-                            const partialName = path.basename(file, extensionWithDot);
-                            const content = await fs.readFile(partialPath, "utf-8");
-                            fastify.log.trace(`Loaded partial: ${partialName}`);
-                            defineSqrlTemplate(partialName, Sqrl.compile(content, sqrlConfig));
-                        }
-                    }),
-                );
-            } catch (error) {
-                fastify.log.error(`Error loading partials from ${partialsDir}: ${error.message}`);
-                throw error;
-            }
-        }
+    if (options.sqrl?.filters) {
+        Object.entries(options.sqrl.filters).forEach(([name, fn]) => {
+            defineSqrlFilter(name, fn);
+        });
     }
 
-    /**
-     * Compiles a template from a file path and caches it if enabled.
-     */
-    async function getTemplate(templatePath) {
-        if (useCache && templateCache.has(templatePath)) {
-            return templateCache.get(templatePath);
-        }
-        const content = await fs.readFile(templatePath, "utf-8");
-        const hasLayoutTag = /{{\s*(?:@extends|!layout)\s*\(/.test(content);
-        const compiled = Sqrl.compile(content, sqrlConfig);
-        templateMeta.set(templatePath, { hasLayoutTag });
-        if (useCache) {
-            templateCache.set(templatePath, compiled);
-        }
-        return compiled;
-    }
+    await preloadPartials({
+        partialsDirs: initialPartialsDirs,
+        extensionWithDot,
+        partialsRecursive: options.partialsRecursive ?? true,
+        partialsNamespace: options.partialsNamespace ?? false,
+        fastify,
+        defineSqrlTemplate,
+        sqrlConfig,
+    });
 
-    /**
-     * Allow nested forward-slash paths (e.g. "admin/dashboard"), but block traversal
-     * or absolute paths.
-     */
-    function assertSafeName(name) {
-        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}`);
-        }
-    }
+    const { findTemplatePath, getTemplate, hasLayoutTag, clearCaches, cacheStats } = createTemplateResolver({
+        fastify,
+        extensionWithDot,
+        useCache,
+        sqrlConfig,
+    });
 
     /**
      * Renders a Squirrelly template and sends it as an HTML response.
@@ -257,61 +136,17 @@ async function squirrellyify(fastify, options = {}) {
             }
 
             const instance = this.request.server;
-
-            const aggregatedTemplatesDirs = [];
-            let scopedLayout = null;
-            let currentInstance = instance;
-            while (currentInstance) {
-                if (currentInstance.views) {
-                    const dirs = Array.isArray(currentInstance.views)
-                        ? currentInstance.views
-                        : [currentInstance.views];
-                    aggregatedTemplatesDirs.push(...dirs);
-                }
-                if (
-                    scopedLayout === null &&
-                    currentInstance.layout !== null &&
-                    currentInstance.layout !== undefined
-                ) {
-                    scopedLayout = currentInstance.layout;
-                }
-                // Defensive: parent may be undefined or private
-                currentInstance = currentInstance.parent ?? null;
-            }
-
-            const combinedDirs = [
-                ...new Set([...aggregatedTemplatesDirs, ...initialTemplatesDirs]),
-            ];
-            const allSearchDirs = [...new Set([...combinedDirs, ...initialPartialsDirs])];
-
-            async function findTemplatePath(templateName) {
-                const templateFile = `${templateName}${extensionWithDot}`;
-                const cacheKey = `${allSearchDirs.join(";")}:${templateFile}`; // Create a unique key
-
-                if (useCache && pathCache.has(cacheKey)) {
-                    return pathCache.get(cacheKey);
-                }
-
-                for (const dir of allSearchDirs) {
-                    const fullPath = path.join(dir, templateFile);
-                    try {
-                        await fs.access(fullPath);
-                        if (useCache) {
-                            pathCache.set(cacheKey, fullPath); // Cache the found path
-                        }
-                        return fullPath;
-                    } catch (error) {
-                        fastify.log.trace(error);
-                    }
-                }
-                return null;
-            }
+            const { aggregatedTemplatesDirs, scopedLayout } = collectViewScope(instance);
+            const templateSearchDirs = buildTemplateSearchDirs(
+                aggregatedTemplatesDirs,
+                initialTemplatesDirs,
+            );
 
             // 1. Find and render the page template
-            const pagePath = await findTemplatePath(template);
+            const pagePath = await findTemplatePath(template, templateSearchDirs);
             if (!pagePath) {
                 throw new Error(
-                    `Template "${template}" not found in [${allSearchDirs.join(", ")}]`,
+                    `Template "${template}" not found in [${templateSearchDirs.join(", ")}]`,
                 );
             }
 
@@ -326,16 +161,15 @@ async function squirrellyify(fastify, options = {}) {
                 return this.type("text/html").send(pageHtml);
             }
 
-            const hasLayoutTag = templateMeta.get(pagePath)?.hasLayoutTag === true;
-            if (hasLayoutTag) {
+            if (hasLayoutTag(pagePath)) {
                 return this.type("text/html").send(pageHtml);
             }
 
             // 3. Find and render the layout, injecting the page content
-            const layoutPath = await findTemplatePath(layoutFile);
+            const layoutPath = await findTemplatePath(layoutFile, templateSearchDirs);
             if (!layoutPath) {
                 throw new Error(
-                    `Layout "${layoutFile}" not found in [${allSearchDirs.join(", ")}]`,
+                    `Layout "${layoutFile}" not found in [${templateSearchDirs.join(", ")}]`,
                 );
             }
 
@@ -362,15 +196,12 @@ 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,
+    fastify.decorate("viewHelpers", viewHelpers);
+    fastify.decorate("viewFilters", viewFilters);
+    fastify.decorate("viewPartials", viewPartials);
+    fastify.decorate("viewCache", {
+        clear: clearCaches,
+        stats: cacheStats,
     });
 
     // Also expose the Squirrelly engine itself for advanced configuration (e.g., adding helpers/filters)

package/src/resolver.js

@@ -0,0 +1,223 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+import Sqrl from "squirrelly";
+
+function trimSlashes(value) {
+    return value.replace(/^\/+|\/+$/g, "");
+}
+
+function resolvePartialsNamespace(partialsNamespace, partialsDir) {
+    if (!partialsNamespace) {
+        return "";
+    }
+    if (partialsNamespace === true) {
+        return trimSlashes(path.basename(path.resolve(partialsDir)));
+    }
+    if (typeof partialsNamespace === "string") {
+        return trimSlashes(partialsNamespace.split("\\").join("/"));
+    }
+    return "";
+}
+
+async function collectPartialFiles(dir, extensionWithDot, recursive) {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    const files = [];
+
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (recursive) {
+                files.push(...(await collectPartialFiles(fullPath, extensionWithDot, recursive)));
+            }
+            continue;
+        }
+        if (entry.isFile() && entry.name.endsWith(extensionWithDot)) {
+            files.push(fullPath);
+        }
+    }
+
+    return files;
+}
+
+function resolvePartialName(partialPath, partialsDir, extensionWithDot, namespace) {
+    const relativePath = path.relative(partialsDir, partialPath);
+    const withoutExt = relativePath.slice(0, -extensionWithDot.length);
+    const normalizedName = withoutExt.split(path.sep).join("/");
+    return namespace ? `${namespace}/${normalizedName}` : normalizedName;
+}
+
+/**
+ * Preload partial templates and define them in the configured Sqrl template store.
+ *
+ * @param {object} options
+ * @param {string[]} options.partialsDirs
+ * @param {string} options.extensionWithDot
+ * @param {boolean} [options.partialsRecursive=true]
+ * @param {boolean|string} [options.partialsNamespace=false]
+ * @param {object} options.fastify
+ * @param {Function} options.defineSqrlTemplate
+ * @param {object} options.sqrlConfig
+ * @returns {Promise<void>}
+ */
+export async function preloadPartials({
+    partialsDirs,
+    extensionWithDot,
+    partialsRecursive = true,
+    partialsNamespace = false,
+    fastify,
+    defineSqrlTemplate,
+    sqrlConfig,
+}) {
+    if (partialsDirs.length === 0) {
+        return;
+    }
+
+    for (const partialsDir of partialsDirs) {
+        try {
+            const namespace = resolvePartialsNamespace(partialsNamespace, partialsDir);
+            const files = await collectPartialFiles(partialsDir, extensionWithDot, partialsRecursive);
+            await Promise.all(
+                files.map(async (partialPath) => {
+                    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));
+                }),
+            );
+        } catch (error) {
+            fastify.log.error(`Error loading partials from ${partialsDir}: ${error.message}`);
+            throw error;
+        }
+    }
+}
+
+/**
+ * Collect encapsulated view dirs and layout overrides from current Fastify scope chain.
+ *
+ * @param {object} instance
+ * @returns {{ aggregatedTemplatesDirs: string[], scopedLayout: string|null }}
+ */
+export function collectViewScope(instance) {
+    const aggregatedTemplatesDirs = [];
+    let scopedLayout = null;
+    let currentInstance = instance;
+
+    while (currentInstance) {
+        if (currentInstance.views) {
+            const dirs = Array.isArray(currentInstance.views)
+                ? currentInstance.views
+                : [currentInstance.views];
+            aggregatedTemplatesDirs.push(...dirs);
+        }
+        if (scopedLayout === null && currentInstance.layout !== null && currentInstance.layout !== undefined) {
+            scopedLayout = currentInstance.layout;
+        }
+        currentInstance = currentInstance.parent ?? null;
+    }
+
+    return {
+        aggregatedTemplatesDirs,
+        scopedLayout,
+    };
+}
+
+/**
+ * Merge initial template dirs with encapsulated scoped dirs.
+ *
+ * @param {string[]} scopedDirs
+ * @param {string[]} initialDirs
+ * @returns {string[]}
+ */
+export function buildTemplateSearchDirs(scopedDirs, initialDirs) {
+    return [...new Set([...scopedDirs, ...initialDirs])];
+}
+
+/**
+ * Build cached template loader / path resolver.
+ *
+ * @param {object} options
+ * @param {object} options.fastify
+ * @param {string} options.extensionWithDot
+ * @param {boolean} options.useCache
+ * @param {object} options.sqrlConfig
+ * @returns {object}
+ */
+export function createTemplateResolver({ fastify, extensionWithDot, useCache, sqrlConfig }) {
+    const templateCache = new Map();
+    const pathCache = new Map();
+    const templateMeta = new Map();
+
+    async function findTemplatePath(templateName, searchDirs) {
+        const templateFile = `${templateName}${extensionWithDot}`;
+        const cacheKey = `${searchDirs.join(";")}:${templateFile}`;
+
+        if (useCache && pathCache.has(cacheKey)) {
+            return pathCache.get(cacheKey);
+        }
+
+        for (const dir of searchDirs) {
+            const fullPath = path.join(dir, templateFile);
+            try {
+                await fs.access(fullPath);
+                if (useCache) {
+                    pathCache.set(cacheKey, fullPath);
+                }
+                return fullPath;
+            } catch (error) {
+                fastify.log.trace(error);
+            }
+        }
+
+        return null;
+    }
+
+    async function getTemplate(templatePath) {
+        if (useCache && templateCache.has(templatePath)) {
+            return templateCache.get(templatePath);
+        }
+
+        const content = await fs.readFile(templatePath, "utf-8");
+        const compiled = Sqrl.compile(content, sqrlConfig);
+        const hasLayoutTag = /{{\s*(?:@extends|!layout)\s*\(/.test(content);
+        templateMeta.set(templatePath, { hasLayoutTag });
+
+        if (useCache) {
+            templateCache.set(templatePath, compiled);
+        }
+
+        return compiled;
+    }
+
+    function hasLayoutTag(templatePath) {
+        return templateMeta.get(templatePath)?.hasLayoutTag === true;
+    }
+
+    function clearCaches() {
+        templateCache.clear();
+        pathCache.clear();
+        templateMeta.clear();
+    }
+
+    function cacheStats() {
+        return {
+            enabled: useCache,
+            templates: templateCache.size,
+            paths: pathCache.size,
+            metadata: templateMeta.size,
+        };
+    }
+
+    return {
+        findTemplatePath,
+        getTemplate,
+        hasLayoutTag,
+        clearCaches,
+        cacheStats,
+    };
+}

package/src/runtime-api.js

@@ -0,0 +1,75 @@
+import Sqrl from "squirrelly";
+
+/**
+ * Build helper/filter/template runtime API wrappers around the selected
+ * Squirrelly storage scope (global or scoped).
+ *
+ * @param {object} options
+ * @param {"global"|"scoped"} options.sqrlScope
+ * @param {object} options.sqrlConfig
+ * @returns {object}
+ */
+export function createRuntimeApi({ sqrlScope, sqrlConfig }) {
+    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, template) {
+        const compiled = typeof template === "function" ? template : Sqrl.compile(String(template), sqrlConfig);
+        templatesStore.define(name, compiled);
+        return compiled;
+    }
+
+    function getSqrlTemplate(name) {
+        return templatesStore.get(name);
+    }
+
+    function removeSqrlTemplate(name) {
+        templatesStore.remove(name);
+    }
+
+    return {
+        defineSqrlHelper,
+        defineSqrlFilter,
+        defineSqrlTemplate,
+        viewHelpers: {
+            define: defineSqrlHelper,
+            get: getSqrlHelper,
+            remove: removeSqrlHelper,
+        },
+        viewFilters: {
+            define: defineSqrlFilter,
+            get: getSqrlFilter,
+            remove: removeSqrlFilter,
+        },
+        viewPartials: {
+            define: defineSqrlTemplate,
+            get: getSqrlTemplate,
+            remove: removeSqrlTemplate,
+        },
+    };
+}

package/src/safety.js

@@ -0,0 +1,27 @@
+import path from "node:path";
+
+/**
+ * Allow nested forward-slash paths (e.g. "admin/dashboard"), but block traversal
+ * or absolute paths.
+ *
+ * @param {string} name
+ * @return {void}
+ */
+export function assertSafeName(name) {
+    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}`);
+    }
+}