@vandenberghinc/volt 1.2.6 → 1.2.8

package/backend/dist/esm/backend/src/image_endpoint.js

@@ -0,0 +1,196 @@
+/**
+ * @author Daan van den Bergh
+ * @copyright © 2022 - 2025 Daan van den Bergh. All rights reserved
+ */
+// ---------------------------------------------------------
+// Libraries.
+import sharp from 'sharp';
+import { Endpoint } from "./endpoint.js";
+// ---------------------------------------------------------
+// ImageEndpoint.
+// Supports resizing and editing formats.
+/**
+ * All static images are served through the `ImageEndpoint`.
+ *
+ * The image endpoint accepts three optional query parameters when retrieving the image to transform the image.
+ *     - `type` string: The input type.
+ *     - `width` number: The height of the image as a number `100` or percentage `50%` / `0.5x`. The aspect ratio will be maintained when `height` is undefined.
+ *     - `height` number: The width of the image as a number `100` or percentage `50%` / `0.5x`. The aspect ratio will be maintained when `width` is undefined.
+ *     - `aspect_ratio` boolean: Maintain the aspect ratio when only one resizing dimension has been defined.
+ * @docs
+ * @nav Endpoints
+ */
+class ImageEndpoint extends Endpoint {
+    // Cache the original and transformed image data in memory.
+    // static cache_in_memory = false;
+    // Supported image extensions.
+    static supported_images = new Set([
+        ".jpg",
+        ".jpeg",
+        ".png",
+        ".webp",
+        ".gif",
+        ".tif",
+        ".tiff",
+        ".svg",
+        ".heif",
+        ".avif"
+    ]);
+    i_path;
+    i_type;
+    // private i_data?: Buffer;
+    is_image_endpoint;
+    /**
+     * A cache of all transformed image paths, mapped by cache id.
+     * We use a cached path since `stat` will be used inside the Stream.send() method.
+     * Since this is cached in the Path object, it will be efficient.
+     */
+    transformed_cache = new Map();
+    /**
+     * Construct an image endpoint.
+     * @docs
+     */
+    constructor({ endpoint, path, cache = true, _is_static = true, rate_limit = undefined, }) {
+        // Initialize base.
+        super({
+            method: "GET",
+            endpoint,
+            compress: false,
+            cache,
+            params: {
+                "type": { type: "string", default: null },
+                "width": { type: ["number", "string"], default: null },
+                "height": { type: ["number", "string"], default: null },
+                "aspect_ratio": { type: "string", default: null },
+            },
+            rate_limit,
+            file_path: path,
+            _is_static,
+        });
+        // Attributes.
+        this.i_path = path.abs();
+        this.i_type = this.i_path.extension().substr(1);
+        // if (ImageEndpoint.cache_in_memory) {
+        //     this.i_data = this.i_path.load_sync({type: "buffer"});
+        // }
+        // Attribute for Endpoint.
+        this.is_image_endpoint = true;
+        // Assign callback.
+        this.callback = async (stream, params) => {
+            // No params.
+            if ((params.type == null || this.i_type === params.type) &&
+                params.width == null &&
+                params.height == null) {
+                return stream.send({
+                    status: 200,
+                    from_file: this.i_path.str(),
+                });
+            }
+            // Cache id.
+            const cache_id = (`${this.route.method}:${this.route.endpoint_str}` +
+                `:${params.width == null ? "" : params.width}.${params.height == null ? "" : params.height}.${params.type == null ? this.i_type : params.type}`).replaceAll("/", "_");
+            let cache_path;
+            if (this.transformed_cache.has(cache_id)) {
+                cache_path = this.transformed_cache.get(cache_id);
+            }
+            else {
+                cache_path = this.server.endpoint_cache_dir.join(cache_id);
+                this.transformed_cache.set(cache_id, cache_path);
+            }
+            // Fast path from cached transformation.
+            if (cache_path.exists()) {
+                return stream.send({
+                    status: 200,
+                    from_file: cache_path,
+                });
+            }
+            // Remove type from params when same as original type.
+            if (this.i_type === params.type) {
+                params.type = null;
+            }
+            // Transform image & save to cache.
+            const data = await this.transform(params.type, params.width, params.height, params.aspect_ratio);
+            await cache_path.save(data);
+            // Send data.
+            return stream.send({
+                status: 200,
+                from_file: cache_path,
+            });
+        };
+    }
+    // Transform image.
+    async transform(type = null, width = null, height = null, aspect_ratio = true) {
+        const img = sharp(this.i_path.str());
+        let metadata;
+        if (width != null || height != null) {
+            let parsed_width;
+            let parsed_height;
+            if (typeof width === "string") {
+                let last_char = width.charAt(width.length - 1);
+                if (last_char === "%" || last_char === "x") {
+                    if (metadata === undefined) {
+                        metadata = await img.metadata();
+                    }
+                    if (last_char === "x") {
+                        parsed_width = parseInt(String(metadata.width * parseFloat(width)));
+                    }
+                    else {
+                        parsed_width = parseInt(String(metadata.width * (parseFloat(width) / 100)));
+                    }
+                }
+                else {
+                    parsed_width = parseInt(width);
+                }
+            }
+            else if (typeof width === "number") {
+                parsed_width = parseInt(String(width));
+            }
+            if (typeof height === "string") {
+                let last_char = height.charAt(height.length - 1);
+                if (last_char === "%" || last_char === "x") {
+                    if (metadata === undefined) {
+                        metadata = await img.metadata();
+                    }
+                    if (last_char === "x") {
+                        parsed_height = parseInt(String(metadata.height * parseFloat(height)));
+                    }
+                    else {
+                        parsed_height = parseInt(String(metadata.height * (parseFloat(height) / 100)));
+                    }
+                }
+                else {
+                    parsed_height = parseInt(height);
+                }
+            }
+            else if (typeof height === "number") {
+                parsed_height = parseInt(String(height));
+            }
+            const opts = {
+                width: parsed_width,
+                height: parsed_height
+            };
+            if (aspect_ratio === "false" || aspect_ratio === false) {
+                opts.fit = 'fill';
+            }
+            img.resize(opts);
+        }
+        if (type != null) {
+            img.toFormat(type);
+        }
+        return img.toBuffer();
+    }
+    // Get aspect ratio.
+    async get_aspect_ratio() {
+        try {
+            const metadata = await sharp(this.file_path?.str()).metadata();
+            return `${metadata.width} / ${metadata.height}`;
+        }
+        catch (err) {
+            this.server?.log.error(`Unable to determine the aspect ratio of image ${this.file_path}: `, err);
+            return null;
+        }
+    }
+}
+// ---------------------------------------------------------
+// Exports.
+export { ImageEndpoint };

package/backend/dist/esm/backend/src/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @author Daan van den Bergh
+ * @copyright © 2022 - 2025 Daan van den Bergh. All rights reserved
+ */
+export * from "./errors/index.js";
+export * from "./status.js";
+export * from "./meta.js";
+export * from "./splash_screen.js";
+export * from "./view.js";
+export * from "./stream.js";
+export * from "./endpoint.js";
+export * from "./server.js";
+export * from "./database/database.js";
+export * from "./database/document.js";
+export * from "./database/collection.js";
+export * from "./database/quota/quota.js";
+export * from "./database/quota/safe_int.js";
+export * from "./rate_limit.js";
+export * from "./events.js";
+export { User } from "./users.js";
+export * as Mail from "./plugins/mail/ui.js";
+export * from "./frontend.js";
+export type { Request } from "../../frontend/src/modules/request.js";

package/backend/dist/esm/backend/src/index.js

@@ -0,0 +1,26 @@
+/**
+ * @author Daan van den Bergh
+ * @copyright © 2022 - 2025 Daan van den Bergh. All rights reserved
+ */
+// ---------------------------------------------------------
+// Exports.
+// Create volt lib.
+export * from "./errors/index.js";
+export * from "./status.js";
+export * from "./meta.js";
+export * from "./splash_screen.js";
+export * from "./view.js";
+export * from "./stream.js";
+export * from "./endpoint.js";
+export * from "./server.js";
+export * from "./database/database.js";
+export * from "./database/document.js";
+export * from "./database/collection.js";
+export * from "./database/quota/quota.js";
+export * from "./database/quota/safe_int.js";
+export * from "./rate_limit.js";
+export * from "./events.js";
+// export * from "./file_watcher.js"
+export * as Mail from "./plugins/mail/ui.js";
+// export * as PDF from "./plugins/pdf.js"
+export * from "./frontend.js";

package/backend/dist/esm/backend/src/logger.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @author Daan van den Bergh
+ * @copyright © 2022 - 2025 Daan van den Bergh. All rights reserved
+ */
+export {};

package/backend/dist/esm/backend/src/logger.js

@@ -0,0 +1,8 @@
+/**
+ * @author Daan van den Bergh
+ * @copyright © 2022 - 2025 Daan van den Bergh. All rights reserved
+ */
+export {};
+// export const log = new vlib.logging.FileLogger({
+//     level: 0,
+// });

package/backend/dist/esm/backend/src/meta.d.ts

@@ -0,0 +1,112 @@
+/**
+ * @author Daan van den Bergh
+ * @copyright © 2022 - 2025 Daan van den Bergh. All rights reserved
+ */
+/** Nested types for the {@link Meta} class. */
+export declare namespace Meta {
+    /**
+     * Options for constructing a {@link Meta} object.
+     *
+     * @docs
+     */
+    interface Opts {
+        /** The author's name. */
+        author?: string;
+        /** The page's title. */
+        title?: string;
+        /** The page's description. */
+        description?: string;
+        /** The page's image source. */
+        image?: string;
+        /** The robots rules. */
+        robots?: string;
+        /** The used charset. */
+        charset?: string;
+        /** The viewport settings. */
+        viewport?: string;
+        /** The url to the favicon. */
+        favicon?: string;
+    }
+}
+/**
+ * The meta information class for HTML endpoints.
+ *
+ * @nav Endpoints
+ * @docs
+ */
+export declare class Meta {
+    author?: string;
+    title?: string;
+    description?: string;
+    image?: string;
+    robots: string;
+    charset: string;
+    viewport: string;
+    favicon: string;
+    /**
+     * Construct a meta information object.
+     * @docs
+     */
+    constructor({ author, title, description, image, robots, charset, viewport, favicon, }?: Meta.Opts);
+    /**
+     * Create a copy of the current meta object without any references.
+     * @param override - The meta constructor arguments to override.
+     * @docs
+     */
+    copy(override?: Partial<Meta.Opts>): Meta;
+    /**
+     * Update the author property.
+     * @return Returns the current {@link Meta} instance for chaining.
+     * @docs
+     */
+    set_author(value: string | undefined): this;
+    /**
+     * Update the title property.
+     * @return Returns the current {@link Meta} instance for chaining.
+     * @docs
+     */
+    set_title(value: string | undefined): this;
+    /**
+     * Update the description property.
+     * @return Returns the current {@link Meta} instance for chaining.
+     * @docs
+     */
+    set_description(value: string | undefined): this;
+    /**
+     * Update the image property.
+     * @return Returns the current {@link Meta} instance for chaining.
+     * @docs
+     */
+    set_image(value: string | undefined): this;
+    /**
+     * Update the robots property.
+     * @return Returns the current {@link Meta} instance for chaining.
+     * @docs
+     */
+    set_robots(value: string): this;
+    /**
+     * Update the charset property.
+     * @return Returns the current {@link Meta} instance for chaining.
+     * @docs
+     */
+    set_charset(value: string): this;
+    /**
+     * Update the viewport property.
+     * @return Returns the current {@link Meta} instance for chaining.
+     * @docs
+     */
+    set_viewport(value: string): this;
+    /**
+     * Update the favicon property.
+     * @return Returns the current {@link Meta} instance for chaining.
+     * @docs
+     */
+    set_favicon(value: string): this;
+    /**
+     * Get the meta information as a plain object.
+     * @docs
+     */
+    obj(): Meta.Opts;
+    build_html(domain?: string | null): string;
+}
+export default Meta;

package/backend/dist/esm/backend/src/meta.js

@@ -0,0 +1,152 @@
+/**
+ * @author Daan van den Bergh
+ * @copyright © 2022 - 2025 Daan van den Bergh. All rights reserved
+ */
+/**
+ * The meta information class for HTML endpoints.
+ *
+ * @nav Endpoints
+ * @docs
+ */
+export class Meta {
+    author;
+    title;
+    description;
+    image;
+    robots;
+    charset;
+    viewport;
+    favicon;
+    /**
+     * Construct a meta information object.
+     * @docs
+     */
+    constructor({ author, title, description, image, robots = "index, follow", charset = "UTF-8", viewport = "width=device-width, initial-scale=1", favicon = "/favicon.ico", } = {}) {
+        this.author = author;
+        this.title = title;
+        this.description = description;
+        this.image = image;
+        this.robots = robots;
+        this.charset = charset;
+        this.viewport = viewport;
+        this.favicon = favicon;
+    }
+    /**
+     * Create a copy of the current meta object without any references.
+     * @param override - The meta constructor arguments to override.
+     * @docs
+     */
+    copy(override = {}) {
+        return new Meta({
+            author: this.author,
+            title: this.title,
+            description: this.description,
+            image: this.image,
+            robots: this.robots,
+            charset: this.charset,
+            viewport: this.viewport,
+            favicon: this.favicon,
+            ...override,
+        });
+    }
+    /**
+     * Update the author property.
+     * @return Returns the current {@link Meta} instance for chaining.
+     * @docs
+     */
+    set_author(value) { this.author = value; return this; }
+    /**
+     * Update the title property.
+     * @return Returns the current {@link Meta} instance for chaining.
+     * @docs
+     */
+    set_title(value) { this.title = value; return this; }
+    /**
+     * Update the description property.
+     * @return Returns the current {@link Meta} instance for chaining.
+     * @docs
+     */
+    set_description(value) { this.description = value; return this; }
+    /**
+     * Update the image property.
+     * @return Returns the current {@link Meta} instance for chaining.
+     * @docs
+     */
+    set_image(value) { this.image = value; return this; }
+    /**
+     * Update the robots property.
+     * @return Returns the current {@link Meta} instance for chaining.
+     * @docs
+     */
+    set_robots(value) { this.robots = value; return this; }
+    /**
+     * Update the charset property.
+     * @return Returns the current {@link Meta} instance for chaining.
+     * @docs
+     */
+    set_charset(value) { this.charset = value; return this; }
+    /**
+     * Update the viewport property.
+     * @return Returns the current {@link Meta} instance for chaining.
+     * @docs
+     */
+    set_viewport(value) { this.viewport = value; return this; }
+    /**
+     * Update the favicon property.
+     * @return Returns the current {@link Meta} instance for chaining.
+     * @docs
+     */
+    set_favicon(value) { this.favicon = value; return this; }
+    /**
+     * Get the meta information as a plain object.
+     * @docs
+     */
+    obj() {
+        return {
+            author: this.author,
+            title: this.title,
+            description: this.description,
+            image: this.image,
+            robots: this.robots,
+            charset: this.charset,
+            viewport: this.viewport,
+            favicon: this.favicon,
+        };
+    }
+    // Build meta headers.
+    build_html(domain = null) {
+        let html = "";
+        // Default meta data.
+        html += `<meta charset='${this.charset}'>`;
+        html += `<meta name='viewport' content='${this.viewport}'/>`;
+        // Meta.
+        html += `<title id='__page_title'>${this.title}</title>`;
+        html += `<meta name='author' content='${this.author}'/>`;
+        html += `<meta name='description' content='${this.description}'/>`;
+        // Meta/facebook.
+        html += `<meta property='og:title' content='${this.title}'/>`;
+        html += `<meta property='og:description' content='${this.description}'/>`;
+        html += `<meta property='og:image' content='${this.image}'/>`;
+        if (domain) {
+            html += `<meta property="og:url" content="${domain}"/>`;
+        }
+        html += `<meta property="og:type" content="website"/>`;
+        // Twitter/X.
+        html += `<meta name='twitter:card' content='summary_large_image'/>`;
+        // html += `<meta name='twitter:site' content='${this.image}'/>`; // twitter username.
+        html += `<meta name='twitter:title' content='${this.title}'/>`;
+        html += `<meta name='twitter:description' content='${this.description}'/>`;
+        html += `<meta name='twitter:image' content='${this.image}'/>`;
+        // FB App id.
+        // <meta property="fb:app_id" content="your-facebook-app-id" />
+        // Meta robots.
+        html += `<meta name='robots' content='${this.robots}'>`;
+        // Favicon.
+        html += `<link rel='icon' href='${this.favicon}' type='image/x-icon'/>`;
+        // Response.
+        return html;
+    }
+}
+// ---------------------------------------------------------
+// Exports.
+export default Meta;