@vandenberghinc/volt 1.1.26 → 1.1.28

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

@@ -0,0 +1,393 @@
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var stdin_exports = {};
+__export(stdin_exports, {
+  SystemError: () => SystemError
+});
+module.exports = __toCommonJS(stdin_exports);
+var vlib = __toESM(require("@vandenberghinc/vlib"));
+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 = 1e4;
+  /**
+   * 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);
+    Object.setPrototypeOf(this, new.target.prototype);
+    this.message = opts.message;
+    this.details = opts.details;
+    this.collection = opts.collection ?? SystemError.collection;
+    this.logger = opts.logger ?? SystemError.logger;
+    this.owner = opts.owner;
+    if (opts.cause) {
+      Object.defineProperty(this, "cause", {
+        value: opts.cause,
+        enumerable: false,
+        configurable: true,
+        writable: true
+      });
+    }
+    this.id = vlib.String.random(SystemError.id_length, "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789");
+    this.name = "SystemError";
+    this.timestamp = Date.now();
+    const holder = { name: "X", message: "Y" };
+    let prev_limit;
+    try {
+      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 {
+        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());
+  }
+  /** 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)}
+` + error.format({ colored: false }));
+        } catch (_) {
+        }
+      });
+    }
+    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 }), 1e4)
+    };
+    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,
+          max_length: 1e3
+        });
+      } 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 void 0;
+    const is_json_safe = (val, in_path = /* @__PURE__ */ 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;
+        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;
+      }
+      return false;
+    };
+    const redacted = this.redact_secrets(this.details);
+    if (!is_json_safe(redacted)) {
+      return vlib.Object.stringify(redacted, {
+        colored: false,
+        max_length: SystemError.max_details_length
+      });
+    }
+    let full_string;
+    try {
+      full_string = JSON.stringify(redacted);
+    } catch (_) {
+      full_string = vlib.Object.stringify(redacted, { colored: false });
+    }
+    if (full_string.length > SystemError.max_details_length) {
+      return vlib.String.truncate(full_string, SystemError.max_details_length);
+    }
+    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 = /* @__PURE__ */ 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;
+      }
+      return val;
+    };
+    return clone(input);
+  }
+}
+;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  SystemError
+});

package/backend/dist/cjs/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/cjs/backend/src/events.js

@@ -0,0 +1,15 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var stdin_exports = {};
+module.exports = __toCommonJS(stdin_exports);

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

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

package/backend/dist/cjs/{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/cjs/{image_endpoint.js → backend/src/image_endpoint.js}

@@ -32,8 +32,6 @@ __export(stdin_exports, {
 module.exports = __toCommonJS(stdin_exports);
 var import_sharp = __toESM(require("sharp"));
 var import_endpoint = require("./endpoint.js");
-var import_logger = require("./logger.js");
-const { log, error } = import_logger.logger;
 class ImageEndpoint extends import_endpoint.Endpoint {
   // Cache the original and transformed image data in memory.
   static cache_in_memory = false;
@@ -69,7 +67,7 @@ class ImageEndpoint extends import_endpoint.Endpoint {
         "aspect_ratio": { type: "string", default: null }
       },
       rate_limit,
-      _static_path: path.str(),
+      file_path: path,
       _is_static
     });
     this.i_path = path.abs();
@@ -175,10 +173,10 @@ class ImageEndpoint extends import_endpoint.Endpoint {
   // Get aspect ratio.
   async get_aspect_ratio() {
     try {
-      const metadata = await (0, import_sharp.default)(this._static_path).metadata();
+      const metadata = await (0, import_sharp.default)(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/cjs/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/cjs/backend/src/logger.js

@@ -0,0 +1,15 @@
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var stdin_exports = {};
+module.exports = __toCommonJS(stdin_exports);

package/backend/dist/cjs/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;

package/backend/dist/cjs/{meta.js → backend/src/meta.js}

@@ -30,7 +30,7 @@ class Meta {
   charset;
   viewport;
   favicon;
-  constructor({ author = null, title = null, description = null, image = null, robots = "index, follow", charset = "UTF-8", viewport = "width=device-width, initial-scale=1", favicon = "/favicon.ico" } = {}) {
+  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;
@@ -41,12 +41,10 @@ class Meta {
     this.favicon = favicon;
   }
   // Copy.
-  /*  @docs:
-      @title: Copy
-      @description: Create a copy of the current meta object without any references.
-      @param:
-          @name: override
-          @descr: The <Type>Meta</Type> constructor arguments to override.
+  /**
+   * Create a copy of the current meta object without any references.
+   * @param override - The <Type>Meta</Type> constructor arguments to override.
+   * @docs
    */
   copy(override = {}) {
     return new Meta({
@@ -61,12 +59,11 @@ class Meta {
       ...override
     });
   }
-  /* @docs:
-   * @title: Set value
-   * @description: Set value funcs that return the current object.
+  /**
+   * Set value funcs that return the current object.
    * @return: Returns the current <Type>Meta</Type> object.
-   * @type: Meta
-   * @funcs: 8
+   * @funcs 8
+   * @docs
    */
   set_author(value) {
     this.author = value;