@webtypen/webframez-core 0.3.66 → 0.3.67

package/README.md

@@ -63,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

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/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
      *

package/dist/Router/Response.js

@@ -13,6 +13,7 @@ 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"));
@@ -37,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
      *

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

@@ -63,3 +63,4 @@ 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

@@ -78,3 +78,4 @@ __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.66",
+    "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');