@vandenberghinc/volt 1.1.26 → 1.1.28

package/backend/dist/esm/backend/src/errors/system_error.js

@@ -0,0 +1,402 @@
+/**
+ * @author Daan van den Bergh
+ * @copyright © 2025 - 2025 Daan van den Bergh. All rights reserved.
+ */
+// External imports.
+import * as vlib from "@vandenberghinc/vlib";
+/**
+ * The system error.
+ * Used to indicate a fatal system error that should not occur and should be reported to developers.
+ * When created, it is logged and (optionally) persisted to the configured collection.
+ */
+export class SystemError extends Error {
+    /**
+     * The default logger to dump messages to.
+     * This can either be `console` or a custom logger such as `FileLogger`.
+     *
+     * This logger is shared across all system errors,
+     * unless a specific logger is passed to the {@link SystemError.Opts} constructor options.
+     */
+    static logger = console;
+    /**
+     * The default collection to save the error to.
+     *
+     * This collection is shared across all system errors,
+     * unless a specific collection is passed to the {@link SystemError.Opts} constructor options.
+     *
+     * @warning
+     * If both {@link SystemError.collection} and field {@link SystemError.Opts.collection} are undefined,
+     * the error will not be saved to the database.
+     *
+     * @note Ensure a database index is created for field `id`.
+     */
+    static collection;
+    /**
+     * Set a collection that will be used as default to save system errors to.
+     *
+     * @param collection The collection options to use.
+     */
+    static set_collection(opts) {
+        SystemError.collection = opts.server.db.collection({
+            name: opts.name,
+            ttl: opts.ttl,
+            indexes: [
+                { keys: { id: 1 }, unique: true, forced: true }
+            ],
+            record_version: 1,
+        });
+    }
+    /**
+     * The generated identifier length (characters) for error IDs.
+     * Defaults to 256 to preserve existing behavior; tune per database constraints.
+     */
+    static id_length = 256;
+    /**
+     * The maximum length for the stringified {@link SystemError.details} field when saved to the database collection as a string.
+     * The `details` field is stringified when it (a) contains cycles or non-plain structures, or (b) its full JSON size exceeds
+     * {@link SystemError.max_details_length}. Otherwise, the redacted plain object/array is stored.
+     */
+    static max_details_length = 10_000;
+    /**
+     * A unique id for this error instance.
+     * Unique to this system error instance.
+     */
+    id;
+    /** The attached message. */
+    message;
+    /** The attached details. */
+    details;
+    /** A nested error cause. */
+    cause;
+    /** The collection to save the error to. */
+    collection;
+    /**
+     * The logger to dump messages to.
+     * Defaults to static attribute {@link SystemError.logger}.
+     */
+    logger;
+    /**
+     * An optional owner field.
+     * For instance system errors saved by the {@link QuotaManager} have an owner of `volt.QuotaManager`.
+     */
+    owner;
+    /** The creation timestamp in milliseconds since Unix epoch. */
+    timestamp;
+    /** The captured stacktrace of the creation of the system error. */
+    trace;
+    /** A cache for the result of format({ colored: true }). */
+    _format_colored;
+    /** A cache for the result of format({ colored: false }). */
+    _format_non_colored;
+    /**
+     * Private constructor.
+     * Use {@link SystemError.create} or {@link SystemError.create_detach} to create a new system error.
+     */
+    constructor(opts) {
+        super(opts.message);
+        // Ensures `instanceof SystemError` works in all transpilation targets.
+        Object.setPrototypeOf(this, new.target.prototype);
+        // Attributes.
+        this.message = opts.message;
+        this.details = opts.details;
+        this.collection = opts.collection ?? SystemError.collection;
+        this.logger = opts.logger ?? SystemError.logger;
+        this.owner = opts.owner;
+        // Define 'cause' as non-enumerable to avoid accidental leakage on serialization.
+        if (opts.cause) {
+            Object.defineProperty(this, "cause", {
+                value: opts.cause,
+                enumerable: false,
+                configurable: true,
+                writable: true,
+            });
+        }
+        // Generate an id.
+        this.id = vlib.String.random(SystemError.id_length, "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789");
+        // Set error instance name.
+        this.name = "SystemError";
+        // Add timestamp.
+        this.timestamp = Date.now();
+        /** Capture a robust stack trace at the point of creation (cross-env safe). */
+        const holder = { name: "X", message: "Y" };
+        let prev_limit;
+        try {
+            // Feature-detect Node API.
+            const has_capture = typeof Error.captureStackTrace === "function";
+            const has_limit = typeof Error.stackTraceLimit === "number";
+            if (has_limit) {
+                prev_limit = Error.stackTraceLimit;
+                Error.stackTraceLimit = 35;
+            }
+            if (has_capture) {
+                Error.captureStackTrace(holder, this.constructor);
+            }
+            else {
+                // Fallback: use current error stack
+                holder.stack = this.stack;
+            }
+        }
+        finally {
+            if (typeof prev_limit === "number") {
+                Error.stackTraceLimit = prev_limit;
+            }
+        }
+        this.trace = (holder.stack || "")
+            .split("\n")
+            .slice(1)
+            .map((line) => line.trim());
+        // Dont log from here, log from create or create_detach.
+        // Perhaps we also want to create a constructor for loaded sys errs later.
+    }
+    /** Construct a system error & save it to the database. */
+    static async create(opts) {
+        const error = new SystemError(opts);
+        error.logger.error(error.format({ colored: false }));
+        if (error.collection) {
+            await error.collection.set({ id: error.id }, error.document(), { retry: 25, });
+        }
+        return error;
+    }
+    /**
+     * Construct a system error & save it to the database.
+     * This is a synchronous version of the create method.
+     * Beware that this does not join the async save operation,
+     * Instead it detaches and catches and logs any errors that occur during saving
+     */
+    static create_detach(opts) {
+        const error = new SystemError(opts);
+        error.logger.error(error.format({ colored: false }));
+        if (error.collection) {
+            void error.collection.set({ id: error.id }, error.document(), { retry: 25 }).catch((e) => {
+                try {
+                    error.logger.error(`Failed to save system error to database: ${e instanceof Error ? e.message : String(e)}\n` + error.format({ colored: false }));
+                }
+                catch (_) { /** ignore */ }
+            });
+        }
+        return error;
+    }
+    /**
+     * Get the error as a database document.
+     *
+     * @returns A plain object representing the system error for database storage.
+     */
+    document() {
+        const doc = {
+            id: this.id,
+            message: this.message,
+            timestamp: this.timestamp,
+            trace: this.trace,
+            stack: this.stack,
+            format: vlib.String.truncate(this.format({ colored: false }), 10_000),
+        };
+        if (this.details) {
+            try {
+                doc.details = this.prepare_details_for_db();
+            }
+            catch (e) {
+                doc.details = `Encountered an error while processing details: ${e instanceof Error ? e.message : String(e)}`;
+            }
+        }
+        if (this.owner != null) {
+            doc.owner = this.owner;
+        }
+        if (this.cause) {
+            doc.error = {
+                name: this.cause.name,
+                message: this.cause.message,
+                stack: this.cause.stack,
+            };
+        }
+        return doc;
+    }
+    /**
+     * Format the error as a string.
+     * @param colored Present the formatted error with colors to make it more visually pleasing.
+     *                Defaults to `false`.
+     * @returns A string representation of the system error.
+     */
+    format({ colored = false } = {}) {
+        if (colored && this._format_colored)
+            return this._format_colored;
+        else if (!colored && this._format_non_colored)
+            return this._format_non_colored;
+        try {
+            const green = (m) => colored ? vlib.Color.green(m) : m;
+            const lines = [
+                `SystemError: ${this.message}`,
+            ];
+            if (this.trace) {
+                lines.push(...this.trace.map(l => `  ${l}`));
+            }
+            lines.push(`  error_id: ${green('"' + this.id + '"')}`);
+            if (this.owner != null) {
+                lines.push(`  owner: ${green('"' + this.owner + '"')}`);
+            }
+            let details;
+            try {
+                details = vlib.Object.stringify(this.redact_secrets(this.details), {
+                    indent: 2,
+                    start_indent: 1,
+                    colored: colored,
+                    max_length: 1000,
+                });
+            }
+            catch (e) {
+                details = `Encountered an error while processing details: ${e instanceof Error ? e.message : String(e)}`;
+            }
+            lines.push(`  created_at: ${green('"' + new Date(this.timestamp).toISOString() + '"')}`, `  details: ${details}`);
+            if (this.cause) {
+                lines.push(`  nested error:`, ...(this.cause?.stack ?? this.cause.toString()).split("\n")
+                    .map(line => `    ${line.trim()}`));
+            }
+            if (colored) {
+                return this._format_colored = lines.join("\n");
+            }
+            else {
+                return this._format_non_colored = lines.join("\n");
+            }
+        }
+        catch (e) {
+            return `Encountered an error while formatting the system error: ${e instanceof Error ? e.message : String(e)}`;
+        }
+    }
+    /**
+     * Convert the error to a string without ANSI colors to avoid leaking escape codes into sinks
+     * (e.g., files, JSON logs) that assume plain text.
+     * @returns Non-colored string representation of the error.
+     */
+    toString() {
+        return this.format({ colored: false });
+    }
+    // ----------------------------------------------------------
+    // Private methods.
+    /**
+     * Detect a plain object (no custom prototype, not an array).
+     * @param v - The value to test.
+     */
+    is_plain_object(v) {
+        if (v === null || typeof v !== "object" || Array.isArray(v))
+            return false;
+        const proto = Object.getPrototypeOf(v);
+        return proto === Object.prototype || proto === null;
+    }
+    /**
+     * Inspect and prepare the details for safe storage in `SystemError.Document.details`.
+     *
+     * @returns
+     * - `undefined` if no details were defined.
+     * - A string if (a) the value contains circular references, (b) it is not a plain object / array,
+     *   or (c) the full stringified representation exceeds {@link SystemError.max_details_length}.
+     * - Otherwise, the redacted raw object is returned.
+     */
+    prepare_details_for_db() {
+        if (!this.details)
+            return undefined;
+        /**
+         * Recursively verify JSON-safety and detect cycles using path-level tracking.
+         * @param val - The value to traverse.
+         * @param in_path - WeakSet to track the current recursion path for cycles.
+         */
+        const is_json_safe = (val, in_path = new WeakSet()) => {
+            if (val == null)
+                return true;
+            const t = typeof val;
+            if (t === "undefined" || t === "boolean" || t === "number" || t === "string")
+                return true;
+            if (t === "function" || t === "symbol" || t === "bigint")
+                return false;
+            if (val instanceof String || val instanceof Date)
+                return true;
+            if (typeof val === "object") {
+                const obj = val;
+                if (in_path.has(obj))
+                    return false; // cycle
+                in_path.add(obj);
+                if (Array.isArray(obj)) {
+                    for (const item of obj) {
+                        if (!is_json_safe(item, in_path)) {
+                            in_path.delete(obj);
+                            return false;
+                        }
+                    }
+                    in_path.delete(obj);
+                    return true;
+                }
+                if (this.is_plain_object(obj)) {
+                    for (const v of Object.values(obj)) {
+                        if (!is_json_safe(v, in_path)) {
+                            in_path.delete(obj);
+                            return false;
+                        }
+                    }
+                    in_path.delete(obj);
+                    return true;
+                }
+                in_path.delete(obj);
+                return false; // Non-plain object (Map/Set/RegExp/etc.)
+            }
+            return false;
+        };
+        // Redact early (never mutate the original).
+        const redacted = this.redact_secrets(this.details);
+        // If structurally unsafe => stringify (capped).
+        if (!is_json_safe(redacted)) {
+            return vlib.Object.stringify(redacted, {
+                colored: false,
+                max_length: SystemError.max_details_length,
+            });
+        }
+        // Measure the *full* length (no cap) to decide storage shape.
+        // Measure the *full* length (no cap) to decide storage shape.
+        let full_string;
+        try {
+            full_string = JSON.stringify(redacted);
+        }
+        catch (_) {
+            // Extremely defensive fallback; should not execute after JSON-safety verification.
+            full_string = vlib.Object.stringify(redacted, { colored: false });
+        }
+        if (full_string.length > SystemError.max_details_length) {
+            // Persist as a truncated string to enforce the size budget.
+            return vlib.String.truncate(full_string, SystemError.max_details_length);
+        }
+        // Safe & within budget: store as object.
+        return redacted;
+    }
+    /**
+     * Deep-clone arrays/plain objects and redact sensitive keys (best-effort).
+     * Does not mutate the source object.
+     * Uses a null-prototype object & explicit property definitions to prevent prototype pollution via magic keys.
+     * @param input - The value to clone & redact.
+     * @returns A redacted deep clone of the input.
+     */
+    redact_secrets(input) {
+        const sensitive = /^(password|pass|secret|api[_-]?key|token|access[_-]?token|refresh[_-]?token|authorization|auth|cookie|session|private[_-]?key|client[_-]?secret)$/i;
+        const define_plain = (obj, key, value) => {
+            Object.defineProperty(obj, key, { value, enumerable: true, writable: true, configurable: true });
+        };
+        const clone = (val) => {
+            if (val == null)
+                return val;
+            if (Array.isArray(val))
+                return val.map(clone);
+            if (this.is_plain_object(val)) {
+                const out = Object.create(null);
+                for (const [k, v] of Object.entries(val)) {
+                    if (sensitive.test(k)) {
+                        define_plain(out, k, "[REDACTED]");
+                    }
+                    else {
+                        define_plain(out, k, clone(v));
+                    }
+                }
+                return out;
+            }
+            // Leave other types as-is.
+            return val;
+        };
+        return clone(input);
+    }
+}
+;

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

@@ -0,0 +1,54 @@
+/**
+ * @author Daan van den Bergh
+ * @copyright © 2022 - 2025 Daan van den Bergh.
+ */
+import * as vlib from "@vandenberghinc/vlib";
+import { User } from "./users.js";
+/** All events and their callback types. */
+export type Events = {
+    /**
+     * Add an (async) callback executed at the end of `server.start()`. The callback may take arguments `({forked <boolean>})`.
+     * @example
+     * ...
+     * server.on("start", opts => console.log("Hello World!"));
+     */
+    start: (opts: {
+        forked: boolean;
+    }) => void | Promise<void>;
+    /**
+     * Set an (async) callback which will be executed at the start of `server.stop()`.
+     * @example
+     * ...
+     * server.on("stop", () => console.log("Hello World!"));
+     */
+    stop: () => void | Promise<void>;
+    /**
+     * Set an (async) callback which will be executed at the start of `server.initialize()`.
+     * @example
+     * ...
+     * server.on("initialize", () => console.log("Hello World!"));
+     */
+    initialize: () => void | Promise<void>;
+    /**
+     * This callback is executed when a user is created.
+     * @note Errors thrown in this callback will be logged but ignored.
+     */
+    create_user: (opts: {
+        user: User;
+    }) => void | Promise<void>;
+    /**
+     * This callback is executed when a user is deleted.
+     * @note Errors thrown in this callback will be logged but ignored.
+     */
+    delete_user: (opts: {
+        user: User;
+    }) => void | Promise<void>;
+};
+/** Event name. */
+export type EventName = vlib.EventName<Events>;
+/** Event callback. */
+export type EventCallback<N extends EventName> = vlib.EventCallback<Events, N>;
+/** Event parameters. */
+export type EventParams<N extends EventName> = vlib.EventParams<Events, N>;
+/** Event result type. */
+export type EventResult<N extends EventName> = vlib.EventResult<Events, N>;

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

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

package/backend/dist/esm/{frontend.js → backend/src/frontend.js}

@@ -6,7 +6,7 @@ export const Frontend = {
     /** CSS exports. */
     css: {
         /** The default volt css export. */
-        volt: __dirname + "/../../../frontend/src/css/volt.css",
+        volt: __dirname + "/../../../../../frontend/src/css/volt.css",
     }
 };
 export default Frontend;

package/backend/dist/esm/{image_endpoint.d.ts → backend/src/image_endpoint.d.ts}

@@ -1,6 +1,21 @@
+/**
+ * @author Daan van den Bergh
+ * @copyright © 2022 - 2025 Daan van den Bergh. All rights reserved
+ */
 import * as vlib from "@vandenberghinc/vlib";
 import { Endpoint } from "./endpoint.js";
 import { RateLimitGroup } from "./rate_limit.js";
+/**
+ * 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 Backend/Endpoints
+ */
 declare class ImageEndpoint extends Endpoint implements Endpoint {
     static cache_in_memory: boolean;
     static supported_images: string[];
@@ -19,6 +34,6 @@ declare class ImageEndpoint extends Endpoint implements Endpoint {
     });
     transform(type?: string | null, width?: number | string | null, height?: number | string | null, aspect_ratio?: string | boolean | null): Promise<Buffer>;
     get_aspect_ratio(): Promise<string | null>;
-    _clear_cache(): void;
+    private _clear_cache;
 }
 export { ImageEndpoint };

package/backend/dist/esm/{image_endpoint.js → backend/src/image_endpoint.js}

@@ -1,28 +1,24 @@
-/*
- * Author: Daan van den Bergh
- * Copyright: © 2022 - 2024 Daan van den Bergh.
+/**
+ * @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";
-import { logger } from "./logger.js";
-const { log, error } = logger;
 // ---------------------------------------------------------
 // ImageEndpoint.
 // Supports resizing and editing formats.
-/*  @docs:
-    @nav: Backend
-    @chapter: Endpoints
-    @title: Image Endpoint
-    @description:
-        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.
+/**
+ * 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 Backend/Endpoints
  */
 class ImageEndpoint extends Endpoint {
     // Cache the original and transformed image data in memory.
@@ -60,7 +56,7 @@ class ImageEndpoint extends Endpoint {
                 "aspect_ratio": { type: "string", default: null },
             },
             rate_limit,
-            _static_path: path.str(),
+            file_path: path,
             _is_static,
         });
         // Attributes.
@@ -186,11 +182,11 @@ class ImageEndpoint extends Endpoint {
     // Get aspect ratio.
     async get_aspect_ratio() {
         try {
-            const metadata = await sharp(this._static_path).metadata();
+            const metadata = await sharp(this.file_path?.str()).metadata();
             return `${metadata.width} / ${metadata.height}`;
         }
         catch (err) {
-            error(`Unable to determine the aspect ratio of image ${this._static_path}: `, err);
+            this.server?.log.error(`Unable to determine the aspect ratio of image ${this.file_path}: `, err);
             return null;
         }
     }

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,64 @@
+/**
+ * @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 {
+    /** Constructor options. */
+    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 js view meta information class.
+ * @nav: Backend/Endpoints
+ */
+export declare class Meta {
+    author?: string;
+    title?: string;
+    description?: string;
+    image?: string;
+    robots: string;
+    charset: string;
+    viewport: string;
+    favicon: string;
+    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 <Type>Meta</Type> constructor arguments to override.
+     * @docs
+     */
+    copy(override?: Partial<Meta.Opts>): Meta;
+    /**
+     * Set value funcs that return the current object.
+     * @return: Returns the current <Type>Meta</Type> object.
+     * @funcs 8
+     * @docs
+     */
+    set_author(value: string | undefined): this;
+    set_title(value: string | undefined): this;
+    set_description(value: string | undefined): this;
+    set_image(value: string | undefined): this;
+    set_robots(value: string): this;
+    set_charset(value: string): this;
+    set_viewport(value: string): this;
+    set_favicon(value: string): this;
+    obj(): Meta.Opts;
+    build_html(domain?: string | null): string;
+}
+export default Meta;