@ynode/squirrellyify 1.0.1

package/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Michael Welter <nme@mikinho.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+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.

package/README.md

@@ -0,0 +1,247 @@
+# @ynode/squirrellyify
+
+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)
+
+A simple and fast plugin for using the [Squirrelly](https://squirrelly.js.org/) template engine with
+[Fastify](https://www.fastify.io/).
+
+## Features
+
+- 🐿️ **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.
+- 🛡️ **Secure:** Protects against path traversal attacks in template names.
+- 🔧 **Extensible:** Easily add custom Squirrelly helpers and filters.
+
+## Installation
+
+You need to install `squirrelly` and `fastify` alongside this plugin.
+
+```bash
+npm install @ynode/squirrellyify squirrelly fastify
+```
+
+## Basic Usage
+
+1.  **Register the plugin.**
+2.  **Use the `reply.view()` decorator in your routes.**
+
+By default, the plugin looks for templates in a `views` directory in your project's root.
+
+**File structure:**
+
+```text
+.
+├── views/
+│   └── index.sqrl
+└── server.js
+```
+
+**`views/index.sqrl`**
+
+```html
+<h1>Hello, {{ it.name }}!</h1>
+```
+
+**`server.js`**
+
+```javascript
+import Fastify from "fastify";
+import squirrellyify from "@ynode/squirrellyify";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const fastify = Fastify({
+    logger: true,
+});
+
+fastify.register(squirrellyify, {
+    templates: path.join(__dirname, "views"),
+});
+
+fastify.get("/", (request, reply) => {
+    return reply.view("index", { name: "World" });
+});
+
+fastify.listen({ port: 3000 }, (err) => {
+    if (err) throw err;
+});
+```
+
+## 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 are available globally by their 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.                    |
+
+## Advanced Usage
+
+### Layouts
+
+Layouts are wrappers for your page templates. The rendered page content is injected into the `body`
+variable within the layout.
+
+**`views/layouts/main.sqrl`**
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+    <head>
+        <title>{{ it.title }}</title>
+    </head>
+    <body>
+        <header>My Awesome Site</header>
+        <main>
+            {{@block("content")}} {{@try}} {{it.body | safe}} {{#catch => err}} Uh-oh, error!
+            Message was '{{err.message}}' {{/try}} {{/block}}
+        </main>
+    </body>
+</html>
+```
+
+**`views/about.sqrl`**
+
+```html
+{{@extends("layout", it)}} {{#content}}
+<h2>About Us</h2>
+<p>This is the about page content.</p>
+
+{{/extends}}
+```
+
+You can specify a layout in three ways (in order of precedence):
+
+1.  **In the `reply.view()` data object:**
+
+    ```javascript
+    fastify.get("/about", (request, reply) => {
+        const pageData = { title: "About Page" };
+        // Use `main.sqrl` as the layout for this request
+        return reply.view("about", { ...pageData, layout: "layouts/main" });
+    });
+
+    // To disable the default layout for a specific route:
+    fastify.get("/no-layout", (request, reply) => {
+        return reply.view("some-page", { layout: false });
+    });
+    ```
+
+2.  **As a default plugin option:**
+
+    ```javascript
+    fastify.register(squirrellyify, {
+        templates: "views",
+        layout: "layouts/main", // All views will use this layout by default
+    });
+    ```
+
+### 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.
+
+**`partials/user-card.sqrl`**
+
+```html
+<div class="card">
+    <h3>{{ it.name }}</h4>
+    <p>{{ it.email }}</p>
+</div>
+```
+
+**`views/index.sqrl`**
+
+```html
+<h1>Users</h1>
+{{ include('user-card', { name: 'John Doe', email: 'john@example.com' }) /}}
+```
+
+**Register the `partials` directory:**
+
+```javascript
+fastify.register(squirrellyify, {
+    templates: "views",
+    partials: "partials",
+});
+```
+
+### Scoped Configuration (Encapsulation)
+
+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";
+import squirrellyify from "@ynode/squirrellyify";
+import path from "node:path";
+
+const fastify = Fastify();
+
+// Register with default settings
+fastify.register(squirrellyify, {
+    templates: path.join(__dirname, "views"),
+    layout: "layouts/main",
+});
+
+fastify.get("/", (req, reply) => {
+    // Renders from ./views/index.sqrl with layouts/main.sqrl
+    return reply.view("index", { title: "Homepage" });
+});
+
+// Create a separate scope for an "admin" section
+fastify.register(
+    (instance, opts, done) => {
+        // Override the templates directory and layout for this scope
+        instance.views = path.join(__dirname, "admin/views");
+        instance.layout = "layouts/admin";
+
+        instance.get("/", (req, reply) => {
+            // Renders from ./admin/views/dashboard.sqrl with layouts/admin.sqrl
+            return reply.view("dashboard", { title: "Admin Panel" });
+        });
+
+        done();
+    },
+    { prefix: "/admin" },
+);
+```
+
+### Custom Helpers and Filters
+
+You can extend Squirrelly with custom helper and filter functions via the `sqrl` option.
+
+```javascript
+fastify.register(squirrellyify, {
+    templates: "views",
+    sqrl: {
+        helpers: {
+            capitalize: (str) => {
+                return str.charAt(0).toUpperCase() + str.slice(1);
+            },
+        },
+        filters: {
+            truncate: (str, len) => {
+                return str.length > len ? str.substring(0, len) + "..." : str;
+            },
+        },
+    },
+});
+```
+
+## License
+
+[MIT](./LICENSE)

package/package.json

@@ -0,0 +1,65 @@
+{
+    "name": "@ynode/squirrellyify",
+    "version": "1.0.1",
+    "description": "Fastify plugin for rendering Squirrelly templates.",
+    "main": "src/plugin.js",
+    "type": "module",
+    "license": "MIT",
+    "author": "Michael Welter <me@mikinho.com>",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/yammm/ynode-squirrellyify.git"
+    },
+    "bugs": {
+        "url": "https://github.com/yammm/ynode-squirrellyify/issues"
+    },
+    "homepage": "https://github.com/yammm/ynode-squirrellyify#readme",
+    "keywords": [
+        "fastify",
+        "template",
+        "view",
+        "squirrelly"
+    ],
+    "engines": {
+        "node": ">=18"
+    },
+    "devDependencies": {
+        "@eslint/js": "^9.37.0",
+        "@eslint/json": "^0.13.2",
+        "@eslint/markdown": "^7.4.0",
+        "@mikinho/autover": "^2.0.1",
+        "eslint": "^9.37.0",
+        "eslint-config-prettier": "^10.1.8",
+        "eslint-plugin-prettier": "^5.5.4",
+        "globals": "^16.4.0",
+        "prettier": "^3.6.2",
+        "rimraf": "^6.0.1",
+        "yuidocjs": "^0.10.2"
+    },
+    "scripts": {
+        "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')))\"",
+        "format": "prettier --write .",
+        "format:check": "prettier --check .",
+        "lint": "eslint .",
+        "lint:fix": "eslint . --fix",
+        "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",
+        "postversion": "git push && git push --tags"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "files": [
+        "src",
+        "README.md",
+        "LICENSE"
+    ],
+    "dependencies": {
+        "fastify-plugin": "^5.1.0",
+        "squirrelly": "^9.1.0"
+    }
+}

package/src/plugin.js

@@ -0,0 +1,275 @@
+/**
+ *  A Squirrelly Fastify plugin
+ *
+ * @module @ynode/squirrellyify
+ */
+
+/*
+The MIT License (MIT)
+
+Copyright (c) 2025 Michael Welter <me@mikinho.com>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+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";
+
+/**
+ * @typedef {import("fastify").FastifyInstance} FastifyInstance
+ * @typedef {import("fastify").FastifyReply} FastifyReply
+ * @typedef {import("squirrelly").SqrlConfig} SqrlConfig
+ */
+
+/**
+ * This plugin adds a "view" decorator to the Fastify reply object,
+ * allowing for the rendering of Squirrelly templates with support for layouts and partials.
+ *
+ * @param {FastifyInstance} fastify The Fastify instance.
+ * @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 {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".
+ */
+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]
+            : [];
+
+    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();
+
+    // Allow passing optional Squirrelly compile/render configuration
+    const sqrlConfig = options.sqrl?.config;
+
+    // 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);
+            });
+        }
+        if (options.sqrl.filters) {
+            Object.entries(options.sqrl.filters).forEach(([name, fn]) => {
+                Sqrl.filters.define(name, fn);
+            });
+        }
+    }
+
+    // Pre-load and define all partials globally 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}`);
+                            Sqrl.templates.define(partialName, Sqrl.compile(content, sqrlConfig));
+                        }
+                    }),
+                );
+            } catch (error) {
+                fastify.log.error(`Error loading partials from ${partialsDir}: ${error.message}`);
+                throw error;
+            }
+        }
+    }
+
+    /**
+     * 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;
+    }
+
+    /**
+     * Because template comes from route code, a mistaken ../ could escape the views dir.
+     * Disallow path separators and .. in template/layout names.
+     */
+    function assertSafeName(name) {
+        if (
+            name.includes("..") ||
+            name.includes(path.sep) ||
+            name.includes("/") ||
+            name.includes("\\")
+        ) {
+            throw new Error(`Illegal template name: ${name}`);
+        }
+    }
+
+    /**
+     * Renders a Squirrelly template and sends it as an HTML response.
+     * @this {FastifyReply}
+     * @param {string} template The name of the template file (without extension).
+     * @param {object} [data={}] The data to pass to the template. Can include a `layout` property to specify a layout file or set to `false` to disable layout for this request.
+     */
+    async function view(template, data = {}) {
+        try {
+            assertSafeName(template);
+            if (data.layout && data.layout !== false) {
+                assertSafeName(data.layout);
+            }
+
+            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;
+            }
+
+            // 1. Find and render the page template
+            const pagePath = await findTemplatePath(template);
+            if (!pagePath) {
+                throw new Error(
+                    `Template "${template}" not found in [${allSearchDirs.join(", ")}]`,
+                );
+            }
+
+            const pageTemplate = await getTemplate(pagePath);
+            const pageHtml = pageTemplate(data, sqrlConfig ?? Sqrl.defaultConfig);
+
+            // 2. Determine which layout to use
+            const currentLayout = scopedLayout !== null ? scopedLayout : initialLayout;
+            const layoutFile = data.layout === false ? null : data.layout || currentLayout;
+
+            if (!layoutFile) {
+                return this.type("text/html").send(pageHtml);
+            }
+
+            const hasLayoutTag = templateMeta.get(pagePath)?.hasLayoutTag === true;
+            if (hasLayoutTag) {
+                return this.type("text/html").send(pageHtml);
+            }
+
+            // 3. Find and render the layout, injecting the page content
+            const layoutPath = await findTemplatePath(layoutFile);
+            if (!layoutPath) {
+                throw new Error(
+                    `Layout "${layoutFile}" not found in [${allSearchDirs.join(", ")}]`,
+                );
+            }
+
+            const layoutTemplate = await getTemplate(layoutPath);
+            const layoutData = { ...data, ...data.layoutData, body: pageHtml };
+            const finalHtml = layoutTemplate(layoutData, sqrlConfig ?? Sqrl.defaultConfig);
+
+            return this.type("text/html").send(finalHtml);
+        } catch (error) {
+            fastify.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.");
+            } else {
+                // In development, it's okay to send the detailed error
+                this.code(500).send(error);
+            }
+        }
+    }
+
+    // Decorate the reply object with the main view function
+    fastify.decorateReply("view", view);
+
+    // Decorate the fastify instance so users can override settings in different scopes
+    fastify.decorate("views", null);
+    fastify.decorate("layout", null);
+
+    // Also expose the Squirrelly engine itself for advanced configuration (e.g., adding helpers/filters)
+    fastify.decorate("Sqrl", Sqrl);
+}
+
+export default fp(squirrellyify, {
+    fastify: "5.x",
+    name: "squirrellyify",
+});