@webtypen/webframez-core 0.3.65 → 0.3.67

package/README.md

@@ -32,7 +32,8 @@ node_modules/@webtypen/webframez-core/agents/webframez_rules.md
 ```
 
 Die Regeln beschreiben unter anderem:
-- bevorzugte Nutzung von Model.objectId(...) statt eigener ObjectId-Resolver
+- verbindliche Nutzung konkreter Model-Klassen fuer fachliche Datenzugriffe statt Collection-Wrappern
+- Nutzung von Model.objectId(...) statt eigener ObjectId-Resolver
 - bevorzugte Nutzung der vorhandenen Helper wie StringFunctions, NumericFunctions und DateFunctions
 - Verwendung der Webframez-Abstraktionen fuer Request, Response, Middleware, Storage, Datatables und Routes
 
@@ -49,6 +50,8 @@ Uebernimm fuer alle Webframez-bezogenen Implementierungen die Konventionen aus:
 ./node_modules/@webtypen/webframez-core/agents/webframez_rules.md
 
 Insbesondere gilt:
+- pro persistierter Entitaet eine Model-Klasse unter app/Models anlegen; Controller, Services und Screens greifen ueber diese Klassen zu
+- keine DatabaseService.collection(...)-Wrapper oder eigene Cursor-/JSON-Persistenzschichten implementieren; fehlende atomare Operationen im Treiber ergaenzen
 - fuer ObjectId-Konvertierungen Model.objectId(...) oder die passende Model-Instanzmethode verwenden
 - vorhandene Webframez-Helper und Facades bevorzugen statt neue Utilities oder Resolver anzulegen
 - fuer HTTP-, Routing-, Middleware-, Storage- und Datatable-Code die Webframez-APIs und Konventionen beibehalten
@@ -60,6 +63,44 @@ Projektspezifische Ergaenzung:
 
 Wenn eine Regel aus der lokalen Projekt-AGENTS.md einer Regel aus der Paketdatei widerspricht, sollte die lokale Projektregel Vorrang haben.
 
+## Application basename
+
+Set the public mount once in `config/application.ts`:
+
+```ts
+export default {
+  router: {
+    get basename() { return process.env.BASENAME || ""; },
+  },
+};
+```
+
+Pass this config as `boot({ config: { application }, ... })`. For example,
+`BASENAME=/my-app` mounts every registered route (including route groups and
+module/API routes) below `/my-app`. Empty or `/` keeps the application at the
+root. The legacy `boot({ basename })` option takes precedence when explicitly
+provided, including `""` or `null`. The basename is normalized and validated at
+boot; changing it requires restarting the application. Web and Lambda use the
+same configuration.
+
+`Route.path("/api/items")`, `appPath("/api/items")`, and
+`res.redirect("/login")` include the basename. Already-prefixed URLs retain one
+prefix, and external URLs, anchors, and relative URLs remain unchanged.
+`Route.relativePath(...)` / `appRelativePath(...)` remove a matching basename
+at a complete path boundary. Route registration always takes application-local
+paths; do not pass `Route.path(...)` into `Route.get(...)`.
+
+Node applications import these helpers from `@webtypen/webframez-core`.
+Browser code can use the public, Node-free `@webtypen/webframez-core/routing`
+entry. Rendering adapters provide the runtime basename to that shared API;
+Core does not rewrite arbitrary HTML strings, native `fetch` calls or raw
+`Location` headers. Use `appPath` for those application URLs.
+
+`webframez-react` automatically adopts the Core basename for `Route.renderReact`,
+including nested mounts and route groups. It publishes the basename for browser
+navigation, forms and asset URLs. The build output directory remains independent
+of the deployment path, so one artifact can be mounted at different basenames.
+
 ## Basic Web Setup
 
 ```ts
@@ -790,3 +831,24 @@ export const handler = (event: any, context: any) => {
   });
 };
 ```
+
+
+## Inline text and icons
+
+`InlineTextDefinition` is a JSON-safe text contract exported by Webframez Core and
+structurally compatible with Native Design. Strings and existing locale maps stay
+valid. Arrays preserve order and explicit whitespace:
+
+```ts
+[{ type: "icon", name: "ubuntu" }, " Ubuntu 24.04"]
+```
+
+Suite screen titles/subtitles, Card/CardHeader, Alert and Text accept this content
+(`SuiteTextDefinition`). In React, use `<InlineText value={content} />` in other
+text slots; `ScreenTitle` also accepts the array directly. On React Native, place
+InlineText inside Text. Icons use the registered Native Design Icon component.
+Built-in names include `linux`, `linux-pinguin` and `ubuntu` (native OS icons use
+a penguin glyph fallback). Set `accessibilityLabel` only when the icon adds meaning
+not already present in adjacent text. Optional `size` is a positive number.
+Content is rendered as text and icons, never HTML. Plain navigation labels retain
+the text representation; their separate `icon` property controls navigation icons.

package/agents/webframez_rules.md

@@ -43,9 +43,13 @@ Vermeide Importe aus internen Pfaden wie src/..., dist/... oder einzelnen Deep-I
 1. Fuer ObjectId-Konvertierungen immer Model.objectId(...) oder die Instanzmethode objectId(...) verwenden, wenn man sich im Kontext eines Models befindet.
 2. Keine redundanten resolveObjectId, parseObjectId, normalizeObjectId, toObjectId oder aehnlichen Hilfsmethoden erzeugen, wenn objectId(...) ausreicht.
 3. Wenn kein konkretes Model passt, ist DBConnection.objectId(...) die zweite Wahl. Ein projektspezifischer Resolver ist nicht die erste Wahl.
-4. Fuer Standardabfragen bevorzugt die vorhandenen Model-Methoden verwenden: where(...), orderBy(...), first(), get(), paginate(), aggregate().
-5. Beziehungen ueber hasOne(...), hasMany(...) und hasManyArray(...) abbilden statt manuelle Lade- oder Resolve-Methoden pro Beziehung zu schreiben.
-6. Model-Klassen sollen die Webframez-Konventionen fuer __table, __primaryKey und Mapping respektieren.
+4. Fachliche Datenzugriffe muessen ueber konkrete Model-Klassen erfolgen: pro persistierter Entitaet eine Klasse unter app/Models mit __table und gegebenenfalls __primaryKey / __connection. Models von Anfang an anlegen und in Controllern, Services, Screens und Formular-Hooks verwenden. Keine DatabaseService.collection(...)-Wrapper und keine eigenen Collection-/Cursor-/JSON-Persistenzschichten im Projekt.
+5. Fuer Abfragen die Model-Methoden where(...), orderBy(...), first(), get(), paginate(), aggregate() verwenden. Fuer Einzelobjekte save(), update() und delete() verwenden. Vorbelegte IDs bei neuen Objekten beachten: Core Model.save() behandelt einen vorhandenen Primaerschluessel als Update; eine dokumentierte Insert-/create-Methode des Treibers nutzen, wenn die ID vor dem Insert feststeht.
+6. Falls eine notwendige Faehigkeit fehlt (z.B. atomare bedingte Updates, Upserts, Projektionen oder Bulk-Inserts), diese generisch im Datenbanktreiber bzw. Framework ergaenzen. Keine Read-Modify-Save-Schleifen fuer Token-Rotation, Zaehler oder einmalige Codes; Filter und Aenderung muessen atomar ausgefuehrt werden.
+7. Direkte DBConnection-/Treiberzugriffe sind auf Verbindungsverwaltung, Migrationen und Framework-Adapter begrenzt. Wenn ein bestehender Framework-Controller einen Datenbank-Handle verlangt, diesen nur an der Adaptergrenze weiterreichen. Geschaeftslogik bleibt bei Models.
+8. Model-Mapping, Projekt-/Tenantfilter, versteckte Felder, Datentypen und bestehende Daten beim Wechsel des Treibers testen. Raw-Aggregationen liefern Datenobjekte; normale Model-Abfragen liefern Model-Instanzen.
+9. Beziehungen ueber hasOne(...), hasMany(...) und hasManyArray(...) abbilden statt manuelle Lade- oder Resolve-Methoden pro Beziehung zu schreiben.
+10. Model-Klassen sollen die Webframez-Konventionen fuer __table, __primaryKey und Mapping respektieren.
 
 Bevorzugt:
 
@@ -234,3 +238,13 @@ Wenn Codex zwischen Eigenbau und Framework-Funktion waehlen muss, gilt standardm
 3. Erst zuletzt eine neue Abstraktion einfuehren.
 
 Wenn eine neue Abstraktion doch noetig ist, muss im Code klar erkennbar sein, warum die vorhandene Webframez-Funktion nicht ausreicht.
+
+## Suite navigation in generated projects
+
+Use actual router Link components for navigation, with href and browser modifiers
+preserved. Keep the Suite provider, renderer and AdminLayout mounted within a
+project; never key them by pathname or hide them behind per-page context loading.
+Key only changing page content, and reset the provider at project/account boundaries.
+Configure Native Design's `suite.navigation.linkComponent` at the application
+boundary. Keep server schemas serializable and authorization checks on every API.
+Verify persistent layout state during navigation, not just HTTP status codes.

package/dist/DataBuilder/DataBuilder.d.ts

@@ -8,6 +8,8 @@ export type DataBuilderSchema = {
     afterSave?: any;
     beforeDelete?: any;
     afterDelete?: any;
+    /** Override persistence for nested/model-backed records; authorization and hooks still run. */
+    deleteHandler?: (element: any, req: Request) => Promise<void>;
     getAggregation?: any;
     events?: {
         [key: string]: any;

package/dist/DataBuilder/DataBuilder.js

@@ -553,7 +553,10 @@ class DataBuilder {
             catch (e) {
                 throw e;
             }
-            yield db.collection(collection).deleteOne({ _id: element._id });
+            if (typeof type.schema.deleteHandler === "function")
+                yield type.schema.deleteHandler(element, req);
+            else
+                yield db.collection(collection).deleteOne({ _id: element._id });
             try {
                 if (typeof type.schema.afterDelete === "function") {
                     yield type.schema.afterDelete(element, req);

package/dist/Database/DBConnection.js

@@ -68,12 +68,14 @@ class DBConnectionFacade {
     }
     runQuery(query, options) {
         return __awaiter(this, void 0, void 0, function* () {
-            const connection = yield this.getConnection();
+            const mapping = query.modelMapping;
+            const model = typeof mapping === "function" ? new mapping() : mapping;
+            const connection = yield this.getConnection(model === null || model === void 0 ? void 0 : model.__connection);
             const data = yield connection.driver.handleQueryBuilder(connection.client, query);
             if (options && options.raw) {
                 return data;
             }
-            if (!data) {
+            if (data === null || data === undefined) {
                 return null;
             }
             // @ToDo: Model-Mapping

package/dist/Database/Model.js

@@ -299,15 +299,16 @@ class Model {
                     primaryKey: this.__primaryKey,
                     filter: { [this.__primaryKey]: this[this.__primaryKey] },
                     data: this.getModelData(),
-                });
+                }, this.__connection);
             }
             else {
                 // Insert
                 status = yield DBConnection_1.DBConnection.execute({
                     type: "insertOne",
                     table: this.__table,
+                    primaryKey: this.__primaryKey,
                     data: this.getModelData(),
-                });
+                }, this.__connection);
             }
             // onModelSave
             const driver = yield DBConnection_1.DBConnection.getDriver(this.__connection);
@@ -329,7 +330,7 @@ class Model {
                 primaryKey: this.__primaryKey,
                 filter: { [this.__primaryKey]: this[this.__primaryKey] },
                 data: updateData,
-            });
+            }, this.__connection);
         });
     }
     /**

package/dist/LambdaApplication.js

@@ -37,7 +37,7 @@ class LambdaApplication {
         Router_1.Router.init({
             mode: "aws-lambda",
             kernel: options && options.kernel ? options.kernel : null,
-            basename: options && options.basename ? options.basename : null,
+            basename: options === null || options === void 0 ? void 0 : options.basename,
             routesFunction: options && options.routesFunction ? options.routesFunction : null,
             tempDir: options && options.tempDir ? options.tempDir : null,
         });

package/dist/Presentation/InlineText.d.ts

@@ -0,0 +1,9 @@
+/** JSON-safe inline content, structurally shared with Native Design/Webframez Core. */
+export type InlineTextIcon = {
+    type: "icon";
+    name: string;
+    /** Omit for decorative icons next to equivalent text. */
+    accessibilityLabel?: string;
+    size?: number;
+};
+export type InlineTextDefinition = string | Record<string, string> | readonly (string | Record<string, string> | InlineTextIcon)[];

package/dist/Presentation/InlineText.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/Queue/AutomationSchedule.d.ts

@@ -8,3 +8,5 @@ export type DueAutomationExecution = {
 };
 export declare function getDueAutomationExecutions(executions: any[], since: any, until: any, timezone?: string, identifier?: string | null): DueAutomationExecution[];
 export declare function matchesAutomationExecutions(executions: any[] | undefined, date: Date | string | undefined, timezone?: string): boolean;
+/** Next wall-clock automation occurrence, preserving the scheduler's timezone/DST semantics. */
+export declare function nextAutomationExecution(executions: any[], after: Date | string, timezone?: string): Date | null;

package/dist/Queue/AutomationSchedule.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.matchesAutomationExecutions = exports.getDueAutomationExecutions = void 0;
+exports.nextAutomationExecution = exports.matchesAutomationExecutions = exports.getDueAutomationExecutions = void 0;
 const moment_timezone_1 = __importDefault(require("moment-timezone"));
 const DateFunctions_1 = require("../Functions/DateFunctions");
 function pushIfDue(out, entry, since, until) {
@@ -124,3 +124,19 @@ function matchesAutomationExecutions(executions, date, timezone = "Europe/Berlin
     return getDueAutomationExecutions(executions, since, until, timezone).some((execution) => execution.dueAt.isSame(dueAt));
 }
 exports.matchesAutomationExecutions = matchesAutomationExecutions;
+/** Next wall-clock automation occurrence, preserving the scheduler's timezone/DST semantics. */
+function nextAutomationExecution(executions, after, timezone = "Europe/Berlin") {
+    const since = (0, moment_timezone_1.default)(after).tz(timezone);
+    if (!since.isValid() || !moment_timezone_1.default.tz.zone(timezone))
+        throw new Error("Invalid automation time or timezone");
+    // Short windows avoid materializing months of minute/hourly occurrences just to find one.
+    const windows = [[1, "minutes"], [1, "hours"], [1, "days"], [8, "days"], [2, "months"]];
+    for (const [amount, unit] of windows) {
+        const due = getDueAutomationExecutions(executions, since, since.clone().add(amount, unit), timezone);
+        const first = due.reduce((best, entry) => !best || entry.dueAt.isBefore(best.dueAt) ? entry : best, null);
+        if (first)
+            return first.dueAt.toDate();
+    }
+    return null;
+}
+exports.nextAutomationExecution = nextAutomationExecution;

package/dist/Queue/Queue.d.ts

@@ -0,0 +1,13 @@
+/** Embedded worker for applications whose database must stay in one process (e.g. DuckDB).
+ * Uses the same queue_jobs records and BaseQueueJob handlers as console workers. */
+export declare class Queue {
+    private static timer;
+    private static running;
+    private static abort;
+    private static worker;
+    private static collection;
+    static enqueue(jobclass: string, props?: Record<string, any>): Promise<any>;
+    static start(jobclasses: string[], intervalMs?: number): void;
+    static stop(): Promise<void>;
+    static runOnce(jobclasses: string[]): Promise<void>;
+}

package/dist/Queue/Queue.js

@@ -0,0 +1,80 @@
+"use strict";
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Queue = void 0;
+const crypto_1 = __importDefault(require("crypto"));
+const DBConnection_1 = require("../Database/DBConnection");
+const QueueJobsRegisty_1 = require("./QueueJobsRegisty");
+/** Embedded worker for applications whose database must stay in one process (e.g. DuckDB).
+ * Uses the same queue_jobs records and BaseQueueJob handlers as console workers. */
+class Queue {
+    static collection() {
+        return __awaiter(this, void 0, void 0, function* () { return (yield DBConnection_1.DBConnection.getConnection()).client.db(null).collection("queue_jobs"); });
+    }
+    static enqueue(jobclass, props = {}) {
+        return __awaiter(this, void 0, void 0, function* () {
+            QueueJobsRegisty_1.QueueJobsRegisty.getJobOrFail(jobclass);
+            const jobs = yield this.collection(), id = props._id || crypto_1.default.randomUUID();
+            yield jobs.updateOne({ _id: id }, { $setOnInsert: Object.assign(Object.assign({}, props), { _id: id, jobclass, status: "pending", created_at: new Date(), not_before: null, worker: null }) }, { upsert: true });
+            return jobs.findOne({ _id: id });
+        });
+    }
+    static start(jobclasses, intervalMs = 1000) {
+        if (this.timer)
+            return;
+        const tick = () => { if (!this.running)
+            this.running = this.runOnce(jobclasses).catch(() => { }).finally(() => { this.running = undefined; }); };
+        this.timer = setInterval(tick, intervalMs);
+        this.timer.unref();
+        tick();
+    }
+    static stop() {
+        var _a;
+        return __awaiter(this, void 0, void 0, function* () { if (this.timer)
+            clearInterval(this.timer); this.timer = undefined; (_a = this.abort) === null || _a === void 0 ? void 0 : _a.abort(); yield this.running; });
+    }
+    static runOnce(jobclasses) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const jobs = yield this.collection(), now = new Date();
+            yield jobs.updateMany({ status: "running", embedded_queue: true, lease_until: { $lt: now } }, { $set: { status: "pending", worker: null, recovered: true } });
+            const token = crypto_1.default.randomUUID();
+            const claimed = yield jobs.findOneAndUpdate({ status: "pending", jobclass: { $in: jobclasses }, $or: [{ not_before: null }, { not_before: { $lte: now } }] }, { $set: { status: "running", worker: this.worker, embedded_queue: true, lease_token: token, lease_until: new Date(Date.now() + 60000), started_at: now } }, { sort: { priority: -1, created_at: 1 }, returnDocument: "after" });
+            const job = (claimed === null || claimed === void 0 ? void 0 : claimed._id) ? claimed : claimed === null || claimed === void 0 ? void 0 : claimed.value;
+            if (!job)
+                return;
+            const filter = { _id: job._id, lease_token: token, status: "running" };
+            const controller = new AbortController();
+            this.abort = controller;
+            const heartbeat = setInterval(() => { void jobs.updateOne(filter, { $set: { lease_until: new Date(Date.now() + 60000) } }).then((result) => { if (!result.matchedCount)
+                controller.abort(); }).catch(() => controller.abort()); }, 15000);
+            heartbeat.unref();
+            try {
+                const Handler = QueueJobsRegisty_1.QueueJobsRegisty.getJobOrFail(job.jobclass), handler = new Handler();
+                const result = yield handler.handle(Object.assign(Object.assign({}, job), { signal: controller.signal }));
+                yield jobs.updateOne(filter, { $set: (result === null || result === void 0 ? void 0 : result.__execute_again) ? { status: "pending", not_before: result.__execute_again, worker: null } : { status: "finished", ended_at: new Date(), worker: null } });
+            }
+            catch (error) {
+                // Handler owns log redaction. Do not persist raw exception output or credentials here.
+                yield jobs.updateOne(filter, { $set: { status: "failed", ended_at: new Date(), worker: null, error: "Queue job failed. See the domain status for details." } });
+            }
+            finally {
+                clearInterval(heartbeat);
+                if (this.abort === controller)
+                    this.abort = undefined;
+            }
+        });
+    }
+}
+exports.Queue = Queue;
+Queue.worker = "embedded-" + crypto_1.default.randomUUID();

package/dist/Router/Response.d.ts

@@ -20,6 +20,8 @@ export declare class Response {
      * @returns Response
      */
     setServerResponse(res: ServerResponse): this;
+    /** Redirect to an application URL, retaining external destinations unchanged. */
+    redirect(location: string, status?: number): Response;
     /**
      * Set the http-status-code
      *
@@ -67,8 +69,8 @@ export declare class Response {
      * @param mimeType
      * @returns void
      */
-    stream(req: Request, filepath: string, filename: string, mimeType: string): Promise<unknown>;
-    download(filepath: string, options?: any): Promise<unknown>;
+    stream(req: Request, filepath: string, filename: string, mimeType: string): Promise<Response | undefined>;
+    download(filepath: string, options?: any): Promise<void>;
     end(): this;
     registerEvent(eventKey: string, func: any): Promise<void>;
     /**

package/dist/Router/Response.js

@@ -13,7 +13,9 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Response = void 0;
+const routing_1 = require("../routing");
 const fs_1 = __importDefault(require("fs"));
+const promises_1 = require("stream/promises");
 const path_1 = __importDefault(require("path"));
 const mime_types_1 = __importDefault(require("mime-types"));
 class Response {
@@ -36,6 +38,10 @@ class Response {
         this.res = res;
         return this;
     }
+    /** Redirect to an application URL, retaining external destinations unchanged. */
+    redirect(location, status = 302) {
+        return this.status(status).header("Location", (0, routing_1.appPath)(location)).send("");
+    }
     /**
      * Set the http-status-code
      *
@@ -129,83 +135,54 @@ class Response {
      * @returns void
      */
     stream(req, filepath, filename, mimeType) {
-        var _a;
+        var _a, _b;
         return __awaiter(this, void 0, void 0, function* () {
-            const stats = fs_1.default.statSync(filepath);
-            const range = ((_a = req.req) === null || _a === void 0 ? void 0 : _a.headers.range) || "";
+            if (!this.res)
+                throw new Error("Native Response-Objekt nicht verfügbar");
+            const stats = yield fs_1.default.promises.stat(filepath);
             const total = stats.size;
-            let start = undefined;
-            let end = undefined;
+            const range = String(((_a = req.headers) === null || _a === void 0 ? void 0 : _a.range) || ((_b = req.message) === null || _b === void 0 ? void 0 : _b.headers.range) || "");
+            let start = 0, end = total - 1;
             if (range) {
-                var parts = range.replace(/bytes=/, "").split("-");
-                var partialstart = parts[0];
-                var partialend = parts[1];
-                start = parseInt(partialstart, 10);
-                end = partialend ? parseInt(partialend, 10) : total - 1;
-                var chunksize = end - start + 1;
-                this.status(206);
-                this.header("Content-Range", "bytes " + start + "-" + end + "/" + total);
-                this.header("Accept-Ranges", "bytes");
-                this.header("Content-Length", chunksize.toString());
-                this.header("Content-Type", mimeType);
-                this.header("Content-Disposition", `attachment; filename="${filename}"`);
-            }
-            else {
-                this.status(200);
-                this.header("Accept-Ranges", "bytes");
-                this.header("Content-Length", stats.size.toString());
-                this.header("Content-Type", mimeType);
-                this.header("Content-Disposition", `attachment; filename="${filename}"`);
-            }
-            // @ts-ignore
-            var readStream = fs_1.default.createReadStream(filepath, { start: start, end: end });
-            readStream.on("error", (streamError) => {
-                console.error("WebframezStreamError:", streamError);
-            });
-            readStream.on("end", () => { });
-            // Prüfe ob res.res verfügbar ist
-            if (!this.res) {
-                throw new Error("Native Response-Objekt nicht verfügbar");
+                const match = /^bytes=(\d*)-(\d*)$/.exec(range);
+                if (!match || (!match[1] && !match[2])) {
+                    return this.status(416).header("Content-Range", `bytes */${total}`).end();
+                }
+                if (!match[1]) {
+                    const suffix = Number(match[2]);
+                    start = Math.max(0, total - suffix);
+                    if (suffix === 0)
+                        start = total;
+                }
+                else {
+                    start = Number(match[1]);
+                    end = match[2] ? Math.min(Number(match[2]), total - 1) : total - 1;
+                }
+                if (!Number.isSafeInteger(start) || !Number.isSafeInteger(end) || start >= total || end < start) {
+                    return this.status(416).header("Content-Range", `bytes */${total}`).end();
+                }
+                this.status(206).header("Content-Range", `bytes ${start}-${end}/${total}`);
             }
-            readStream.pipe(this.res);
-            return new Promise((resolve) => {
-                readStream.on("end", resolve);
-                readStream.on("error", resolve);
-            });
+            this.header("Accept-Ranges", "bytes");
+            this.header("Content-Length", String(range ? end - start + 1 : total));
+            this.header("Content-Type", mimeType);
+            this.header("Content-Disposition", `attachment; filename="${filename.replace(/["\r\n\\]/g, "_")}"`);
+            if (total === 0)
+                return this.end();
+            yield (0, promises_1.pipeline)(fs_1.default.createReadStream(filepath, { start, end }), this.res);
         });
     }
     download(filepath, options) {
         return __awaiter(this, void 0, void 0, function* () {
-            return new Promise((resolve, reject) => {
-                if (!this.res) {
-                    return reject("Cannot download: Original response object is missing");
-                }
-                if (!fs_1.default.existsSync(filepath)) {
-                    return reject("Cannot download: File '" + filepath + "' does not exist");
-                }
-                let mimeType = options && options.contentType ? options.contentType : "application/octet-stream";
-                if (options && options.inline) {
-                    let tempMime = mime_types_1.default.lookup(filepath);
-                    if (tempMime) {
-                        mimeType = tempMime;
-                    }
-                }
-                const stats = fs_1.default.lstatSync(filepath);
-                this.header("Content-Disposition", (options && options.inline ? "inline" : "attachment") +
-                    "; filename=" +
-                    (options && options.filename ? options.filename : path_1.default.basename(filepath)));
-                this.header("Content-Type", mimeType);
-                this.header("Content-Length", stats.size.toString());
-                const readStream = fs_1.default.createReadStream(filepath);
-                readStream.pipe(this.res);
-                readStream.on("close", () => {
-                    resolve();
-                });
-                readStream.on("error", (streamErr) => {
-                    console.error(streamErr);
-                    reject(streamErr);
-                });
-            });
+            if (!this.res)
+                throw new Error("Cannot download: Original response object is missing");
+            const stats = yield fs_1.default.promises.stat(filepath);
+            const mimeType = (options === null || options === void 0 ? void 0 : options.contentType) || ((options === null || options === void 0 ? void 0 : options.inline) && mime_types_1.default.lookup(filepath)) || "application/octet-stream";
+            const filename = String((options === null || options === void 0 ? void 0 : options.filename) || path_1.default.basename(filepath)).replace(/["\r\n\\]/g, "_");
+            this.header("Content-Disposition", `${(options === null || options === void 0 ? void 0 : options.inline) ? "inline" : "attachment"}; filename="${filename}"`);
+            this.header("Content-Type", mimeType);
+            this.header("Content-Length", String(stats.size));
+            yield (0, promises_1.pipeline)(fs_1.default.createReadStream(filepath), this.res);
         });
     }
     end() {

package/dist/Router/Route.d.ts

@@ -3,6 +3,10 @@ type RouteRegistrationOptions = {
 };
 type RouteExtensionFactory = (route: RouteFacade) => (...args: any[]) => any;
 export declare class RouteFacade {
+    get basename(): string;
+    /** Public application URL, including the configured router basename. */
+    path(value: string): string;
+    relativePath(value: string): string;
     tempGroupPrefix: string | null;
     tempGroupMiddleware: string[] | null;
     tempGroupDomains: string[] | null;

package/dist/Router/Route.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Route = exports.RouteFacade = void 0;
+const routing_1 = require("../routing");
 const Router_1 = require("./Router");
 class RouteFacade {
     constructor() {
@@ -24,6 +25,10 @@ class RouteFacade {
             Router_1.Router.register(method, (this.tempGroupPrefix ? this.tempGroupPrefix : "") + path, component, mergedOptions);
         };
     }
+    get basename() { return Router_1.Router.basename || ""; }
+    /** Public application URL, including the configured router basename. */
+    path(value) { return (0, routing_1.appPath)(value, this.basename); }
+    relativePath(value) { return (0, routing_1.appRelativePath)(value, this.basename); }
     normalizeStringArray(values) {
         if (!Array.isArray(values)) {
             return [];

package/dist/Router/Router.js

@@ -13,6 +13,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Router = void 0;
+const Config_1 = require("../Config");
+const routing_1 = require("../routing");
 const http_1 = require("http");
 const Response_1 = require("./Response");
 const Request_1 = require("./Request");
@@ -72,7 +74,9 @@ class RouterFacade {
      * Load the application-routes
      */
     init(options) {
-        this.basename = options && options.basename ? options.basename : null;
+        this.basename = (0, routing_1.normalizeBasename)((options === null || options === void 0 ? void 0 : options.basename) !== undefined
+            ? options.basename : Config_1.Config.get("application.router.basename"));
+        globalThis.__WEBFRAMEZ_ROUTER_BASENAME__ = this.basename;
         this.kernel = options && options.kernel ? options.kernel : null;
         this.mode = options && options.mode ? options.mode : null;
         this.maxRequestBodySizeBytes =

package/dist/WebApplication.js

@@ -71,7 +71,7 @@ class WebApplication {
         Router_1.Router.init({
             mode: options && options.mode ? options.mode : null,
             kernel: options && options.kernel ? options.kernel : null,
-            basename: options && options.basename ? options.basename : null,
+            basename: options === null || options === void 0 ? void 0 : options.basename,
             routesFunction: options && options.routesFunction ? options.routesFunction : null,
             tempDir: options && options.tempDir ? options.tempDir : null,
         });
@@ -94,7 +94,7 @@ class WebApplication {
                     res,
                     kernel: options && options.kernel ? options.kernel : null,
                     modulesLoader: this.modulesLoader,
-                    basename: options && options.basename ? options.basename : null,
+                    basename: Router_1.Router.basename,
                     options,
                 });
                 if (handled) {
@@ -149,7 +149,7 @@ class WebApplication {
             if (runtimeConsole && typeof runtimeConsole.log === "function") {
                 runtimeConsole.log("Server started and listening on port " +
                     port +
-                    (options && options.basename ? " (Basename: " + options && options.basename + ")" : ""));
+                    (Router_1.Router.basename ? " (Basename: " + Router_1.Router.basename + ")" : ""));
             }
             if (options && options.onBoot) {
                 options.onBoot(port);

package/dist/index.d.ts

@@ -61,3 +61,6 @@ export * from "./Notifications/NotificationService";
 export * from "./Notifications/NotificationsOutputChannel";
 export * from "./Notifications/NotificationsOutputChannelsJob";
 export * from "./info";
+export type { InlineTextDefinition, InlineTextIcon } from "./Presentation/InlineText";
+export * from "./Queue/Queue";
+export * from "./routing";

package/dist/index.js

@@ -77,3 +77,5 @@ __exportStar(require("./Notifications/NotificationService"), exports);
 __exportStar(require("./Notifications/NotificationsOutputChannel"), exports);
 __exportStar(require("./Notifications/NotificationsOutputChannelsJob"), exports);
 __exportStar(require("./info"), exports);
+__exportStar(require("./Queue/Queue"), exports);
+__exportStar(require("./routing"), exports);

package/dist/routing.d.ts

@@ -0,0 +1,5 @@
+export declare function normalizeBasename(value?: string | null): string;
+export declare function getBasename(): string;
+/** Prefix application-absolute URLs once; preserve external and relative URLs. */
+export declare function appPath(value: string, basename?: string): string;
+export declare function appRelativePath(value: string, basename?: string): string;

package/dist/routing.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.appRelativePath = exports.appPath = exports.getBasename = exports.normalizeBasename = void 0;
+function normalizeBasename(value) {
+    if (value == null || value === "" || value === "/")
+        return "";
+    if (typeof value !== "string")
+        throw new Error("Router basename must be a string.");
+    const base = value.trim().replace(/\/+$/, "");
+    if (!base && value.trim().length <= 1)
+        return "";
+    if (!/^\/(?:[A-Za-z0-9_~-]+(?:\.[A-Za-z0-9_~-]+)*)(?:\/[A-Za-z0-9_~-]+(?:\.[A-Za-z0-9_~-]+)*)*$/.test(base)) {
+        throw new Error("Router basename must be empty or an absolute path such as /my-app.");
+    }
+    return base;
+}
+exports.normalizeBasename = normalizeBasename;
+function getBasename() {
+    var _a, _b, _c, _d;
+    const runtime = globalThis;
+    return (_d = (_c = (_b = (_a = runtime.__WEBFRAMEZ_ROUTING_CONTEXT__) === null || _a === void 0 ? void 0 : _a.getStore()) !== null && _b !== void 0 ? _b : runtime.__RSC_BASENAME) !== null && _c !== void 0 ? _c : runtime.__WEBFRAMEZ_ROUTER_BASENAME__) !== null && _d !== void 0 ? _d : "";
+}
+exports.getBasename = getBasename;
+/** Prefix application-absolute URLs once; preserve external and relative URLs. */
+function appPath(value, basename = getBasename()) {
+    const base = normalizeBasename(basename);
+    if (!base || !value.startsWith("/") || value.startsWith("//") || hasBasename(value, base))
+        return value;
+    return base + value;
+}
+exports.appPath = appPath;
+function appRelativePath(value, basename = getBasename()) {
+    const base = normalizeBasename(basename);
+    if (!base || !hasBasename(value, base))
+        return value;
+    const relative = value.slice(base.length);
+    return !relative || relative.startsWith("?") || relative.startsWith("#") ? "/" + relative : relative;
+}
+exports.appRelativePath = appRelativePath;
+function hasBasename(value, base) {
+    return value === base || value.startsWith(base + "/") || value.startsWith(base + "?") || value.startsWith(base + "#");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@webtypen/webframez-core",
-    "version": "0.3.65",
+    "version": "0.3.67",
     "description": "The core package of the typescript based webframez (web-framework) by webtypen.de",
     "homepage": "https://webtypen.de/",
     "license": "MIT",
@@ -24,7 +24,9 @@
         "dist",
         "bin",
         "README.md",
-        "agents"
+        "agents",
+        "routing.js",
+        "routing.d.ts"
     ],
     "scripts": {
         "build": "tsc",

package/routing.d.ts

@@ -0,0 +1 @@
+export { normalizeBasename, getBasename, appPath, appRelativePath } from './dist/routing';

package/routing.js

@@ -0,0 +1,2 @@
+// Public browser-safe entry point. Do not import the Node server bundle here.
+module.exports = require('./dist/routing.js');