@webtypen/webframez-core 0.3.97 → 0.3.101

package/README.md

@@ -996,7 +996,10 @@ Metro consumers can call
 `require('@webtypen/webframez-core/build-cache').configureMetroCache(config)`.
 It applies `WEBFRAMEZ_BUILD_MAX_WORKERS` and `WEBFRAMEZ_METRO_CACHE_DIRECTORY`,
 preserving Expo's FileStore implementation and supporting old/new file-map option
-names. Do not pass Expo `--clear` on normal cached builds.
+names. Transform and file-map caches are separated by a stable hash of sorted
+`EXPO_PUBLIC_*`, `NODE_ENV` and `BABEL_ENV` values. The cache version also includes
+this hash for custom/remote stores; public values are not written into path names.
+Private registry credentials do not participate in this build identity. Do not pass Expo `--clear` on normal cached builds.
 
 
 ### Reusable build workspaces
@@ -1024,3 +1027,9 @@ Asset builds use a stable staging directory so bundler caches can reuse module p
 An exclusive per-output lock prevents concurrent builds overwriting that directory.
 After a killed local build, remove its `.webframez-build/.building-*.lock` directory
 only after confirming that no previous build is running. WSM Force Clear removes it.
+
+### Explicit HEAD routes
+
+`Route.head(path, handler, options)` registers metadata-only requests separately from GET.
+Group prefixes, middleware, domain filters and OPTIONS preflight resolution work as for other routes.
+Return headers with `res.header(...)` and finish with `res.end()`; no response body is needed.

package/build-cache.d.ts

@@ -1 +1 @@
-export function configureMetroCache<T extends {cacheStores?: any; maxWorkers?: number}>(config:T, env?:Record<string,string | undefined>):T;
+export function configureMetroCache<T extends {cacheVersion?: string; cacheStores?: any; maxWorkers?: number}>(config:T, env?:Record<string,string | undefined>):T;

package/build-cache.js

@@ -1,15 +1,26 @@
 const path = require("node:path");
 const fs = require("node:fs");
+const crypto = require("node:crypto");
 
 /** Preserve the platform's FileStore subclass (including Expo CSS handling). */
 function configureMetroCache(config, env = process.env) {
+    // Expo inlines public values into transforms. Metro's persistent cache must
+    // not share those transforms between origins or feature configurations.
+    const publicEnvironment = Object.keys(env)
+        .filter(key => key.startsWith("EXPO_PUBLIC_") || key === "NODE_ENV" || key === "BABEL_ENV")
+        .sort()
+        .map(key => [key, env[key]]);
+    const environmentKey = crypto.createHash("sha256").update(JSON.stringify(publicEnvironment)).digest("hex");
+    config.cacheVersion = `${config.cacheVersion || "1.0"}:webframez-public-env-v1:${environmentKey}`;
+
+
     if (env.WEBFRAMEZ_BUILD_MAX_WORKERS !== undefined) {
         const workers = Number(env.WEBFRAMEZ_BUILD_MAX_WORKERS);
         if (!Number.isInteger(workers) || workers < 1 || workers > 64) throw new Error("Invalid WEBFRAMEZ_BUILD_MAX_WORKERS");
         config.maxWorkers = workers;
     }
     if (!env.WEBFRAMEZ_METRO_CACHE_DIRECTORY) return config;
-    const root = path.resolve(env.WEBFRAMEZ_METRO_CACHE_DIRECTORY);
+    const root = path.join(path.resolve(env.WEBFRAMEZ_METRO_CACHE_DIRECTORY), `env-${environmentKey}`);
     const relocate = stores => stores.map((store, index) => {
         // Leave remote and custom stores untouched; their constructors need other options.
         if (!store || typeof store._root !== "string") return store;

package/dist/Datatable/Datatable.d.ts

@@ -1,4 +1,5 @@
 import { Request } from "../Router/Request";
+import { DatatableColumnContext, DatatableColumnPreferencesConfig } from "./DatatableColumnPreferences";
 export interface DatatableModelSelectorConfig {
     value?: string;
     label?: string;
@@ -10,6 +11,9 @@ export interface NormalizedDatatableModelSelectorConfig {
     subtitle?: string;
 }
 export declare class Datatable {
+    static columnPreferences: DatatableColumnPreferencesConfig | false;
+    columnPreferences?: DatatableColumnPreferencesConfig | false;
+    private columnStates;
     collection: string | Function;
     aggregation: {
         [key: string]: any;
@@ -49,6 +53,15 @@ export declare class Datatable {
         };
     } | null;
     getInit(req: Request): Promise<any>;
+    private loadColumnState;
+    private getColumnState;
+    saveColumnPreferences(req: Request, columns: unknown): Promise<any>;
+    resetColumnPreferences(req: Request): Promise<any>;
+    /** All definitions remain available through getColumns(); this returns the user's ordered layout. */
+    getVisibleColumns(req: Request): Promise<Record<string, any>>;
+    getVisibleColumnKeys(req: Request): Promise<string[]>;
+    isColumnVisible(req: Request, key: string): Promise<boolean>;
+    getColumnContext(req: Request): Promise<DatatableColumnContext>;
     getModelSelectorConfig(): NormalizedDatatableModelSelectorConfig | null;
     getModelSelectorPreview(req: Request): Promise<any>;
     getSelectableFunctionsDef(req: Request): Promise<{
@@ -62,7 +75,7 @@ export declare class Datatable {
     getAggregation(req: Request): Promise<any>;
     getSubAggregation(req: Request): Promise<any>;
     getCollection(req: Request): Promise<any>;
-    getData(req: Request): Promise<{
+    getData(req: Request, context?: DatatableColumnContext): Promise<{
         page: number;
         max_entries: any;
         total_pages: number;

package/dist/Datatable/Datatable.js

@@ -27,8 +27,11 @@ exports.Datatable = void 0;
 const moment_1 = __importDefault(require("moment"));
 const DBConnection_1 = require("../Database/DBConnection");
 const NumericFunctions_1 = require("../Functions/NumericFunctions");
+const DatatableColumnPreferences_1 = require("./DatatableColumnPreferences");
+const DatatablePreferencesStore_1 = require("./DatatablePreferencesStore");
 class Datatable {
     constructor() {
+        this.columnStates = new WeakMap();
         this.collection = "";
         this.aggregation = null;
         this.subAggregation = null;
@@ -57,26 +60,19 @@ class Datatable {
             if (modelSelector) {
                 out.modelSelector = modelSelector;
             }
-            const promises = [];
-            promises.push(new Promise((resolve) => __awaiter(this, void 0, void 0, function* () {
-                out.filter = yield this.getFilter(req);
-                resolve(true);
-            })));
-            promises.push(new Promise((resolve) => __awaiter(this, void 0, void 0, function* () {
-                const cols = [];
-                const colsData = yield this.getColumns(req);
-                if (colsData && Object.keys(colsData).length > 0) {
-                    for (let i in colsData) {
-                        cols.push(Object.assign(Object.assign({}, colsData[i]), { key: i }));
-                    }
-                }
-                out.columns = cols;
-                resolve(true);
-            })));
-            promises.push(new Promise((resolve) => __awaiter(this, void 0, void 0, function* () {
-                out.onPressLink = yield this.getOnPressLink(req);
-                resolve(true);
-            })));
+            const [filter, state, onPressLink] = yield Promise.all([
+                this.getFilter(req), this.getColumnState(req), this.getOnPressLink(req),
+            ]);
+            out.filter = filter;
+            out.columns = Object.entries(state.visible).map(([key, column]) => (Object.assign(Object.assign({}, column), { key })));
+            out.availableColumns = Object.entries(state.all).map(([key, column]) => (Object.assign(Object.assign({}, column), { key })));
+            out.columnPreferences = Boolean(state.scope) && Object.keys(state.all).length > 0;
+            out.columnSelection = out.columns.map((column) => {
+                var _a, _b;
+                return (Object.assign({ key: column.key }, (((_b = (_a = state.preferences) === null || _a === void 0 ? void 0 : _a.find((entry) => entry.key === column.key)) === null || _b === void 0 ? void 0 : _b.width)
+                    ? { width: state.preferences.find((entry) => entry.key === column.key).width } : {})));
+            });
+            out.onPressLink = onPressLink;
             if (this.exports) {
                 out.export_definitions = [];
                 for (let key in this.exports) {
@@ -87,13 +83,105 @@ class Datatable {
                     });
                 }
             }
-            yield Promise.all(promises);
             if (typeof this.onInit === "function") {
                 yield this.onInit(req, out);
             }
             return out;
         });
     }
+    loadColumnState(req) {
+        var _a, _b;
+        return __awaiter(this, void 0, void 0, function* () {
+            const all = (_a = yield this.getColumns(req)) !== null && _a !== void 0 ? _a : {};
+            const config = (_b = this.columnPreferences) !== null && _b !== void 0 ? _b : Datatable.columnPreferences;
+            const store = new DatatablePreferencesStore_1.DatatablePreferencesStore(config || {});
+            const scope = config === false ? null : yield store.scope(req);
+            const preferences = scope ? yield store.load(scope) : null;
+            return { all, visible: DatatableColumnPreferences_1.DatatableColumnPreferences.apply(all, preferences), preferences, store, scope };
+        });
+    }
+    getColumnState(req) {
+        let state = this.columnStates.get(req);
+        if (!state) {
+            state = this.loadColumnState(req);
+            this.columnStates.set(req, state);
+        }
+        return state;
+    }
+    saveColumnPreferences(req, columns) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const state = yield this.getColumnState(req);
+            if (!state.scope)
+                throw Object.assign(new Error("Spalteneinstellungen sind für diesen Benutzer nicht verfügbar."), { status: 403 });
+            let preferences;
+            try {
+                preferences = DatatableColumnPreferences_1.DatatableColumnPreferences.validate(columns, state.all);
+            }
+            catch (error) {
+                throw Object.assign(error, { status: 400 });
+            }
+            yield state.store.save(state.scope, preferences);
+            this.columnStates.delete(req);
+            return this.getInit(req);
+        });
+    }
+    resetColumnPreferences(req) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const state = yield this.getColumnState(req);
+            if (!state.scope)
+                throw Object.assign(new Error("Spalteneinstellungen sind für diesen Benutzer nicht verfügbar."), { status: 403 });
+            yield state.store.reset(state.scope);
+            this.columnStates.delete(req);
+            return this.getInit(req);
+        });
+    }
+    /** All definitions remain available through getColumns(); this returns the user's ordered layout. */
+    getVisibleColumns(req) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return (yield this.getColumnState(req)).visible;
+        });
+    }
+    getVisibleColumnKeys(req) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return Object.keys(yield this.getVisibleColumns(req));
+        });
+    }
+    isColumnVisible(req, key) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return Object.prototype.hasOwnProperty.call(yield this.getVisibleColumns(req), key);
+        });
+    }
+    getColumnContext(req) {
+        var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r;
+        return __awaiter(this, void 0, void 0, function* () {
+            const { all, visible: columns } = yield this.getColumnState(req);
+            const columnKeys = Object.keys(columns);
+            const filters = (_a = yield this.getFilter(req)) !== null && _a !== void 0 ? _a : {};
+            const required = new Set(columnKeys);
+            for (const key of columnKeys)
+                required.add((_b = columns[key].mapping) !== null && _b !== void 0 ? _b : key);
+            for (const key of Object.keys((_d = (_c = req.body) === null || _c === void 0 ? void 0 : _c.sort) !== null && _d !== void 0 ? _d : {}))
+                required.add(key);
+            for (const key of Object.keys((_f = (_e = req.body) === null || _e === void 0 ? void 0 : _e.search) !== null && _f !== void 0 ? _f : {}))
+                required.add((_h = (_g = all[key]) === null || _g === void 0 ? void 0 : _g.mapping) !== null && _h !== void 0 ? _h : key);
+            for (const key of Object.keys((_k = (_j = req.body) === null || _j === void 0 ? void 0 : _j.filter) !== null && _k !== void 0 ? _k : {}))
+                required.add((_m = (_l = filters[key]) === null || _l === void 0 ? void 0 : _l.mapping) !== null && _m !== void 0 ? _m : key);
+            for (const [key, sum] of Object.entries((_p = (_o = req.body) === null || _o === void 0 ? void 0 : _o.sums) !== null && _p !== void 0 ? _p : {}))
+                required.add((_q = sum === null || sum === void 0 ? void 0 : sum.mapping) !== null && _q !== void 0 ? _q : key);
+            if (((_r = req.body) === null || _r === void 0 ? void 0 : _r.mode) === "model-selector-preview") {
+                const selector = this.getModelSelectorConfig();
+                for (const field of [selector === null || selector === void 0 ? void 0 : selector.value, selector === null || selector === void 0 ? void 0 : selector.label, selector === null || selector === void 0 ? void 0 : selector.subtitle])
+                    if (field)
+                        required.add(field);
+            }
+            const matches = (field) => Array.from(required).some(key => key === field || key.startsWith(field + ".") || field.startsWith(key + "."));
+            return {
+                columns, columnKeys,
+                isColumnVisible: key => Object.prototype.hasOwnProperty.call(columns, key),
+                isColumnRequired: key => { var _a; return matches(key) || (typeof ((_a = all[key]) === null || _a === void 0 ? void 0 : _a.mapping) === "string" && matches(all[key].mapping)); },
+            };
+        });
+    }
     getModelSelectorConfig() {
         if (!this.modelSelector) {
             return null;
@@ -198,7 +286,7 @@ class Datatable {
             if (this.defaultUnwind && this.defaultUnwind.trim() !== "") {
                 prefix.push({ $unwind: this.defaultUnwind });
             }
-            const aggr = typeof this.aggregation === "function" ? yield this.aggregation(req) : this.aggregation;
+            const aggr = typeof this.aggregation === "function" ? yield this.aggregation(req, yield this.getColumnContext(req)) : this.aggregation;
             if (this.autoApplyFilter && req.body.filter && typeof req.body.filter === "object") {
                 const filterMatch = yield this.getFilterMatch(req, req.body.filter);
                 if (this.autoApplyFilter === "begin") {
@@ -233,7 +321,7 @@ class Datatable {
     }
     getSubAggregation(req) {
         return __awaiter(this, void 0, void 0, function* () {
-            return typeof this.subAggregation === "function" ? yield this.subAggregation(req) : this.subAggregation;
+            return typeof this.subAggregation === "function" ? yield this.subAggregation(req, yield this.getColumnContext(req)) : this.subAggregation;
         });
     }
     getCollection(req) {
@@ -244,8 +332,9 @@ class Datatable {
             return this.collection;
         });
     }
-    getData(req) {
+    getData(req, context) {
         return __awaiter(this, void 0, void 0, function* () {
+            const columns = context !== null && context !== void 0 ? context : yield this.getColumnContext(req);
             const page = req.body.page && parseInt(req.body.page) > 0 ? parseInt(req.body.page) : 0;
             const aggregation = [];
             const aggregationStats = [];
@@ -332,10 +421,10 @@ class Datatable {
             if (this.onRow || this.onAttributes) {
                 for (let i in results) {
                     if (this.onRow) {
-                        results[i] = yield this.onRow(results[i]);
+                        results[i] = yield this.onRow(results[i], req, columns);
                     }
                     if (this.onAttributes) {
-                        results[i].__cellattr = yield this.onAttributes(results[i]);
+                        results[i].__cellattr = yield this.onAttributes(results[i], req, columns);
                     }
                 }
             }
@@ -381,7 +470,7 @@ class Datatable {
                 sums: sums,
             };
             if (typeof this.onData === "function") {
-                yield this.onData(req, data);
+                yield this.onData(req, data, columns);
             }
             return data;
         });
@@ -708,3 +797,4 @@ class Datatable {
     }
 }
 exports.Datatable = Datatable;
+Datatable.columnPreferences = {};

package/dist/Datatable/DatatableColumnPreferences.d.ts

@@ -0,0 +1,30 @@
+import type { DatabaseId } from "../Database/DatabaseAdapter";
+import type { Request } from "../Router/Request";
+export type DatatableColumnWidth = {
+    mode: "auto";
+} | {
+    mode: "px" | "percent";
+    value: number;
+};
+export interface DatatableColumnPreference {
+    key: string;
+    /** Omit to retain the current backend default. */
+    width?: DatatableColumnWidth;
+}
+export interface DatatableColumnPreferencesConfig {
+    collection?: string;
+    connection?: string;
+    /** Resolve exclusively from authenticated server context. Null disables persistence for this request. */
+    owner?: (req: Request) => Record<string, DatabaseId> | null | Promise<Record<string, DatabaseId> | null>;
+}
+export interface DatatableColumnContext {
+    columns: Record<string, any>;
+    columnKeys: string[];
+    isColumnVisible: (key: string) => boolean;
+    /** Includes visible mappings and fields used by filters, search, sorting or sums. */
+    isColumnRequired: (key: string) => boolean;
+}
+export declare class DatatableColumnPreferences {
+    static validate(value: unknown, columns: Record<string, any>): DatatableColumnPreference[];
+    static apply(columns: Record<string, any>, preferences: unknown): Record<string, any>;
+}

package/dist/Datatable/DatatableColumnPreferences.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DatatableColumnPreferences = void 0;
+class DatatableColumnPreferences {
+    static validate(value, columns) {
+        if (!Array.isArray(value) || value.length === 0 || value.length > Object.keys(columns).length) {
+            throw new Error("Bitte mindestens eine gültige Spalte auswählen.");
+        }
+        const seen = new Set();
+        return value.map(entry => {
+            if (!entry || typeof entry.key !== "string" || !Object.prototype.hasOwnProperty.call(columns, entry.key) || seen.has(entry.key)) {
+                throw new Error("Unbekannte oder doppelte Spalte.");
+            }
+            seen.add(entry.key);
+            const preference = { key: entry.key };
+            if (entry.width !== undefined) {
+                const width = entry.width;
+                if ((width === null || width === void 0 ? void 0 : width.mode) === "auto") {
+                    preference.width = { mode: "auto" };
+                }
+                else if (((width === null || width === void 0 ? void 0 : width.mode) === "px" || (width === null || width === void 0 ? void 0 : width.mode) === "percent") && typeof width.value === "number"
+                    && Number.isFinite(width.value) && width.value > 0 && width.value <= (width.mode === "percent" ? 100 : 10000)) {
+                    preference.width = { mode: width.mode, value: width.value };
+                }
+                else {
+                    throw new Error("Ungültige Spaltenbreite.");
+                }
+            }
+            return preference;
+        });
+    }
+    static apply(columns, preferences) {
+        const defaults = () => Object.fromEntries(Object.entries(columns).filter(([, column]) => column.hidden !== true));
+        if (!Array.isArray(preferences))
+            return defaults();
+        const available = preferences.filter(entry => entry && typeof entry.key === "string" && Object.prototype.hasOwnProperty.call(columns, entry.key));
+        if (!available.length)
+            return defaults();
+        let validated;
+        try {
+            validated = this.validate(available, columns);
+        }
+        catch (_a) {
+            return defaults();
+        }
+        return Object.fromEntries(validated.map(preference => {
+            const column = Object.assign({}, columns[preference.key]);
+            if (preference.width) {
+                delete column.width;
+                delete column.minWidth;
+                delete column.maxWidth;
+                column.autogrow = preference.width.mode === "auto";
+                column.grow = preference.width.mode === "auto" ? 1 : 0;
+                if (preference.width.mode === "px")
+                    column.width = preference.width.value;
+                if (preference.width.mode === "percent")
+                    column.width = `${preference.width.value}%`;
+            }
+            return [preference.key, column];
+        }));
+    }
+}
+exports.DatatableColumnPreferences = DatatableColumnPreferences;

package/dist/Datatable/DatatableController.d.ts

@@ -1,7 +1,10 @@
 import { Controller } from "../Controller/Controller";
 import { Request } from "../Router/Request";
 import { Response } from "../Router/Response";
+import { Datatable } from "./Datatable";
 export declare class DatatableController extends Controller {
-    restApi(req: Request, res: Response): Promise<Response>;
+    protected getTableClass(req: Request): any;
+    protected configureTable(table: Datatable, req: Request): void | Promise<void>;
+    restApi(req: Request, res: Response): Promise<Response | undefined>;
     tableExport(req: Request, res: Response): Promise<Response>;
 }

package/dist/Datatable/DatatableController.js

@@ -13,36 +13,47 @@ exports.DatatableController = void 0;
 const Controller_1 = require("../Controller/Controller");
 const DatatableRegistry_1 = require("./DatatableRegistry");
 class DatatableController extends Controller_1.Controller {
+    getTableClass(req) {
+        return DatatableRegistry_1.DatatableRegistry.getTable(req.body._table);
+    }
+    configureTable(table, req) { }
     restApi(req, res) {
-        var _a;
+        var _a, _b, _c;
         return __awaiter(this, void 0, void 0, function* () {
-            if (!req.body._table || req.body._table.trim() === "") {
+            if (typeof ((_a = req.body) === null || _a === void 0 ? void 0 : _a._table) !== "string" || req.body._table.trim() === "") {
                 return res.status(404).send({
                     status: "error",
                     message: "Missing table-key ...",
                 });
             }
-            const tableClass = DatatableRegistry_1.DatatableRegistry.getTable(req.body._table);
+            const tableClass = this.getTableClass(req);
             if (!tableClass) {
                 return res.status(404).send({
                     status: "error",
                     message: "Table '" + req.body._table + "' not found ...",
                 });
             }
-            if (req.body.init_request) {
-                const table = new tableClass();
-                return res.send({
-                    status: "success",
-                    data: yield table.getInit(req),
-                });
+            if (req.body.export)
+                return this.tableExport(req, res);
+            const table = new tableClass();
+            yield this.configureTable(table, req);
+            if (req.body.init_request || req.body.mode === "columns-get") {
+                return res.send({ status: "success", data: yield table.getInit(req) });
             }
-            if (!req.body._table || req.body._table.trim() === "") {
-                return res.status(404).send({
-                    status: "error",
-                    message: "Missing table-key ...",
-                });
+            if (req.body.mode === "columns-save" || req.body.mode === "columns-reset") {
+                try {
+                    const data = req.body.mode === "columns-save"
+                        ? yield table.saveColumnPreferences(req, req.body.columns)
+                        : yield table.resetColumnPreferences(req);
+                    return res.send({ status: "success", data });
+                }
+                catch (error) {
+                    const status = error === null || error === void 0 ? void 0 : error.status;
+                    if (status !== 400 && status !== 403)
+                        throw error;
+                    return res.status(status).send({ status: "error", message: error.message });
+                }
             }
-            const table = new tableClass();
             if (req.body.mode === "model-selector-preview") {
                 if (!table.getModelSelectorConfig()) {
                     return res.status(403).send({
@@ -62,7 +73,7 @@ class DatatableController extends Controller_1.Controller {
                 });
             }
             if (req.body.apiFunction && typeof req.body.apiFunction === "string" && req.body.apiFunction.trim() !== "") {
-                const func = (_a = table.selectableFunctions) === null || _a === void 0 ? void 0 : _a[req.body.apiFunction];
+                const func = (_b = table.selectableFunctions) === null || _b === void 0 ? void 0 : _b[req.body.apiFunction];
                 if (!func || !func.handle) {
                     return res.status(404).send({
                         status: "error",
@@ -96,25 +107,28 @@ class DatatableController extends Controller_1.Controller {
                         message: e instanceof Error ? e.message : "Unknown error ...",
                     });
                 }
+                if (res.content !== undefined || ((_c = res.res) === null || _c === void 0 ? void 0 : _c.headersSent) || res.headersSent || res.writableEnded)
+                    return;
                 return res.send({
                     status: "success",
                 });
             }
             return res.send({
                 status: "success",
-                data: yield table.getData(req),
+                data: yield table.getData(req, yield table.getColumnContext(req)),
             });
         });
     }
     tableExport(req, res) {
+        var _a;
         return __awaiter(this, void 0, void 0, function* () {
-            if (!req.body._table || req.body._table.trim() === "") {
+            if (typeof ((_a = req.body) === null || _a === void 0 ? void 0 : _a._table) !== "string" || req.body._table.trim() === "") {
                 return res.status(404).send({
                     status: "error",
                     message: "Missing table-key ...",
                 });
             }
-            const tableClass = DatatableRegistry_1.DatatableRegistry.getTable(req.body._table);
+            const tableClass = this.getTableClass(req);
             if (!tableClass) {
                 return res.status(404).send({
                     status: "error",
@@ -122,6 +136,7 @@ class DatatableController extends Controller_1.Controller {
                 });
             }
             const table = new tableClass();
+            yield this.configureTable(table, req);
             if (!req.body.export || !table.exports || (table.exports && !table.exports[req.body.export])) {
                 return res.status(404).send({
                     status: "error",
@@ -130,7 +145,7 @@ class DatatableController extends Controller_1.Controller {
             }
             const exp = table.exports[req.body.export];
             const cols = [];
-            const colsData = yield table.getColumns(req);
+            const colsData = yield table.getVisibleColumns(req);
             if (colsData && Object.keys(colsData).length > 0) {
                 for (let i in colsData) {
                     cols.push(Object.assign(Object.assign({}, colsData[i]), { key: i }));

package/dist/Datatable/DatatablePreferencesStore.d.ts

@@ -0,0 +1,15 @@
+import type { Request } from "../Router/Request";
+import type { DatatableColumnPreference, DatatableColumnPreferencesConfig } from "./DatatableColumnPreferences";
+/** Document-store adapter for per-owner table layouts. The deterministic ID makes first saves atomic. */
+export declare class DatatablePreferencesStore {
+    private config;
+    constructor(config?: DatatableColumnPreferencesConfig);
+    scope(req: Request): Promise<{
+        table: any;
+        _id: string;
+    } | null>;
+    private collection;
+    load(scope: Record<string, any>): Promise<any>;
+    save(scope: Record<string, any>, columns: DatatableColumnPreference[]): Promise<void>;
+    reset(scope: Record<string, any>): Promise<void>;
+}

package/dist/Datatable/DatatablePreferencesStore.js

@@ -0,0 +1,59 @@
+"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());
+    });
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DatatablePreferencesStore = void 0;
+const crypto_1 = require("crypto");
+const DBConnection_1 = require("../Database/DBConnection");
+/** Document-store adapter for per-owner table layouts. The deterministic ID makes first saves atomic. */
+class DatatablePreferencesStore {
+    constructor(config = {}) {
+        this.config = config;
+    }
+    scope(req) {
+        var _a, _b, _c, _d;
+        return __awaiter(this, void 0, void 0, function* () {
+            const user = (_b = (_a = req.auth) === null || _a === void 0 ? void 0 : _a.user) !== null && _b !== void 0 ? _b : req.user;
+            const userId = user === null || user === void 0 ? void 0 : user[(_c = user.__primaryKey) !== null && _c !== void 0 ? _c : "_id"];
+            const owner = this.config.owner ? yield this.config.owner(req) : userId !== undefined && userId !== null ? { _user: userId } : null;
+            if (!owner || !Object.keys(owner).length || typeof ((_d = req.body) === null || _d === void 0 ? void 0 : _d._table) !== "string" || !req.body._table.trim())
+                return null;
+            if (Object.entries(owner).some(([key, value]) => ["_id", "table", "columns", "updated_at"].includes(key) || value === null || value === undefined)) {
+                throw new Error("Invalid datatable preference owner.");
+            }
+            const identity = Object.keys(owner).sort().map(key => [key, typeof owner[key] === "number" ? "number" : "id", String(owner[key])]);
+            const id = (0, crypto_1.createHash)("sha256").update(JSON.stringify([req.body._table, identity])).digest("hex");
+            return Object.assign(Object.assign({}, owner), { table: req.body._table, _id: id });
+        });
+    }
+    collection() {
+        var _a;
+        return __awaiter(this, void 0, void 0, function* () {
+            return (yield DBConnection_1.DBConnection.getDocumentStore(this.config.connection)).collection((_a = this.config.collection) !== null && _a !== void 0 ? _a : "users_datatables");
+        });
+    }
+    load(scope) {
+        var _a, _b;
+        return __awaiter(this, void 0, void 0, function* () {
+            return (_b = (_a = (yield (yield this.collection()).findOne(scope))) === null || _a === void 0 ? void 0 : _a.columns) !== null && _b !== void 0 ? _b : null;
+        });
+    }
+    save(scope, columns) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield (yield this.collection()).updateOne(scope, { $set: { columns, updated_at: new Date() } }, { upsert: true });
+        });
+    }
+    reset(scope) {
+        return __awaiter(this, void 0, void 0, function* () {
+            yield (yield this.collection()).deleteOne(scope);
+        });
+    }
+}
+exports.DatatablePreferencesStore = DatatablePreferencesStore;

package/dist/Router/Route.d.ts

@@ -27,6 +27,8 @@ export declare class RouteFacade {
      * @param options
      */
     get(path: string, component: any, options?: RouteRegistrationOptions): void;
+    /** Register a HEAD route, for metadata without a response body. */
+    head(path: string, component: any, options?: RouteRegistrationOptions): void;
     /** Register the existing DataBuilder POST protocol with request-local configuration. */
     databuilder(path: string, options?: DataBuilderRouteOptions): void;
     /** Register CSRF, model login, logout and refresh using the browser auth contract. */

package/dist/Router/Route.js

@@ -77,6 +77,10 @@ class RouteFacade {
     get(path, component, options) {
         this.registerWithGroupContext("GET", path, component, options);
     }
+    /** Register a HEAD route, for metadata without a response body. */
+    head(path, component, options) {
+        this.registerWithGroupContext("HEAD", path, component, options);
+    }
     /** Register the existing DataBuilder POST protocol with request-local configuration. */
     databuilder(path, options = {}) {
         this.registerWithGroupContext("POST", path, (0, DataBuilderRoute_1.dataBuilderRoute)(options), { middleware: options.middleware, domains: options.domains });

package/dist/Router/Router.d.ts

@@ -43,6 +43,10 @@ declare class RouterFacade {
     routesGET: {
         [key: string]: RouteObject[];
     };
+    /** Explicit HEAD routes, with the same middleware and domain matching as GET. */
+    routesHEAD: {
+        [key: string]: RouteObject[];
+    };
     /**
      * POST Route Store
      */

package/dist/Router/Router.js

@@ -53,6 +53,8 @@ class RouterFacade {
          * GET Route Store
          */
         this.routesGET = {};
+        /** Explicit HEAD routes, with the same middleware and domain matching as GET. */
+        this.routesHEAD = {};
         /**
          * POST Route Store
          */
@@ -86,6 +88,7 @@ class RouterFacade {
                 ? options.maxRequestBodySizeBytes
                 : 10 * 1024 * 1024;
         this.routesGET = {};
+        this.routesHEAD = {};
         this.routesPOST = {};
         this.routesPUT = {};
         this.routesPATCH = {};
@@ -153,6 +156,12 @@ class RouterFacade {
             }
             this.routesGET[path].push(routeConf);
         }
+        else if (type === "HEAD") {
+            if (!this.routesHEAD[path]) {
+                this.routesHEAD[path] = [];
+            }
+            this.routesHEAD[path].push(routeConf);
+        }
         else if (type === "POST") {
             if (!this.routesPOST[path]) {
                 this.routesPOST[path] = [];
@@ -196,6 +205,9 @@ class RouterFacade {
         if (req.method === "GET") {
             return this.dissolveRoute(this.routesGET, cleanUrl, req);
         }
+        else if (req.method === "HEAD") {
+            return this.dissolveRoute(this.routesHEAD, cleanUrl, req);
+        }
         else if (req.method === "POST") {
             return this.dissolveRoute(this.routesPOST, cleanUrl, req);
         }
@@ -212,6 +224,9 @@ class RouterFacade {
             if (req.headers["access-control-request-method"] === "GET") {
                 return this.dissolveRoute(this.routesGET, cleanUrl, req);
             }
+            else if (req.headers["access-control-request-method"] === "HEAD") {
+                return this.dissolveRoute(this.routesHEAD, cleanUrl, req);
+            }
             else if (req.headers["access-control-request-method"] === "POST") {
                 return this.dissolveRoute(this.routesPOST, cleanUrl, req);
             }

package/dist/index.d.ts

@@ -28,6 +28,8 @@ export * from "./Facades/Storage";
 export * from "./DataBuilder/DataBuilder";
 export * from "./DataBuilder/DataBuilderController";
 export * from "./Datatable/Datatable";
+export * from "./Datatable/DatatableColumnPreferences";
+export * from "./Datatable/DatatablePreferencesStore";
 export * from "./Datatable/DatatableRegistry";
 export * from "./Datatable/DatatableController";
 export * from "./Queue/BaseQueueJob";
@@ -76,3 +78,4 @@ export { ModelForm, ModelFormContext, ModelFormConstructor } from "./DataBuilder
 export { Field, Validates, Forms, DataBuilderFieldOptions } from "./DataBuilder/decorators";
 export { DataBuilderRouteOptions } from "./DataBuilder/DataBuilderRoute";
 export { LegacyFieldTypeAdapter } from "./DataBuilder/LegacyFieldTypeAdapter";
+export { defaultFormFields } from "./DataBuilder/formScope";

package/dist/index.js

@@ -14,7 +14,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.LegacyFieldTypeAdapter = exports.Forms = exports.Validates = exports.Field = exports.ModelForm = void 0;
+exports.defaultFormFields = exports.LegacyFieldTypeAdapter = exports.Forms = exports.Validates = exports.Field = exports.ModelForm = void 0;
 __exportStar(require("./Config"), exports);
 __exportStar(require("./Functions/DateFunctions"), exports);
 __exportStar(require("./Functions/FileFunctions"), exports);
@@ -45,6 +45,8 @@ __exportStar(require("./Facades/Storage"), exports);
 __exportStar(require("./DataBuilder/DataBuilder"), exports);
 __exportStar(require("./DataBuilder/DataBuilderController"), exports);
 __exportStar(require("./Datatable/Datatable"), exports);
+__exportStar(require("./Datatable/DatatableColumnPreferences"), exports);
+__exportStar(require("./Datatable/DatatablePreferencesStore"), exports);
 __exportStar(require("./Datatable/DatatableRegistry"), exports);
 __exportStar(require("./Datatable/DatatableController"), exports);
 __exportStar(require("./Queue/BaseQueueJob"), exports);
@@ -96,3 +98,5 @@ Object.defineProperty(exports, "Validates", { enumerable: true, get: function ()
 Object.defineProperty(exports, "Forms", { enumerable: true, get: function () { return decorators_1.Forms; } });
 var LegacyFieldTypeAdapter_1 = require("./DataBuilder/LegacyFieldTypeAdapter");
 Object.defineProperty(exports, "LegacyFieldTypeAdapter", { enumerable: true, get: function () { return LegacyFieldTypeAdapter_1.LegacyFieldTypeAdapter; } });
+var formScope_1 = require("./DataBuilder/formScope");
+Object.defineProperty(exports, "defaultFormFields", { enumerable: true, get: function () { return formScope_1.defaultFormFields; } });

package/docs/databuilder.md

@@ -32,6 +32,11 @@ Metadata is inherited without mutating parent definitions. Decorated definitions
 
 Without registered forms or legacy `__forms`, decorated models get a default form containing their fields, including child layouts. Existing `__schema` still carries version, collection, hooks, aggregation, uniqueness, new-data and deletion behavior. Defining `static forms = () => [UserProfileForm]` is an alternative to `@Forms()`; the decorator takes precedence.
 
+For dynamic sections inside an explicit layout, import `defaultFormFields` from
+`@webtypen/webframez-core` and use `{ field: "attributes", fields: defaultFormFields(attributeSchema) }`.
+It recursively supplies the `fields` layouts for object and array schemas, including
+objects inside array entries. It does not modify the schema or populate data values.
+
 ## Server-side form classes
 
 ```ts

package/docs/datatables.md

@@ -0,0 +1,103 @@
+# Datatable column preferences
+
+`DatatableController@restApi` automatically restores the authenticated user's
+column order, visibility and widths. `getColumns(req)` still returns all columns
+allowed by the table definition. A column with `hidden: true` starts hidden and
+can be added in the column editor. Hiding a column is presentation state, never
+an authorization mechanism; omit unauthorized columns from `columns(req)`.
+
+Native Design's Datatable and DataTableScreen show **Filter zurücksetzen** and
+**Spalten bearbeiten** in their ellipsis menu when the backend supports this
+protocol. The editor supports drag and drop (including keyboard/native actions),
+hiding/adding columns, backend default widths, auto grow, pixels and percentages.
+Saving refreshes rows without resetting filters. Cancel leaves the layout intact.
+At least one column must remain visible. `features.columnPreferences = false`
+disables the editor; explicit client `columns` overrides also disable it.
+
+## Storage and scope
+
+The default document collection is `users_datatables`. The owner comes from
+`req.auth.user` or `req.user`, respecting its `__primaryKey` (default `_id`). No
+owner means no persistence and no edit action. Records contain `_user`, `table`,
+`columns` and `updated_at`. A deterministic `_id` provides atomic upserts without
+creating indexes or running schema changes during requests.
+
+Configure all tables via `Datatable.columnPreferences`, or assign a per-table
+`columnPreferences` configuration in a controller's `configureTable` hook. Use
+only authenticated server context for owner fields. The client cannot select a
+collection or another owner. Connections can be selected with `connection`.
+
+```ts
+class EnvironmentDatatableController extends DatatableController {
+    protected configureTable(table: Datatable, req: Request) {
+        table.columnPreferences = {
+            collection: "environments_users_datatables",
+            owner: request => request.envUser?._id && request.env?._id
+                ? { _environment_user: request.envUser._id, _env: request.env._id }
+                : null,
+        };
+    }
+}
+```
+
+Set `columnPreferences = false` to opt out. Existing definitions keep their
+widths until explicitly overridden. Old saved keys no longer present in the
+request's allowed definitions are removed; if none remain, defaults are used.
+New columns become available in the editor without altering a saved layout.
+
+## Request protocol
+
+All operations use the same authorized POST route and `_table` plus the host's
+normal request context:
+
+- `init_request: true` or `mode: "columns-get"`: returns effective `columns`,
+  `availableColumns`, `columnSelection` and the boolean `columnPreferences`.
+- `mode: "columns-save", columns: [...]`: validates and saves the ordered visible
+  columns, then returns current initialization metadata.
+- `mode: "columns-reset"`: removes the preference and returns backend defaults.
+
+```json
+{
+    "_table": "customers",
+    "mode": "columns-save",
+    "columns": [
+        { "key": "email", "width": { "mode": "percent", "value": 40 } },
+        { "key": "name", "width": { "mode": "auto" } },
+        { "key": "created_at", "width": { "mode": "px", "value": 140 } }
+    ]
+}
+```
+
+Omitting `width` follows the current backend default. Percentages are greater
+than zero and at most 100; pixels are greater than zero and at most 10,000.
+Unknown/duplicate columns or invalid widths return HTTP 400; a missing owner or
+disabled persistence returns HTTP 403. Normal table/middleware authorization
+must run for every operation. Exports use the visible columns in their saved order.
+
+## Conditional lookups and custom data methods
+
+Use `await this.getVisibleColumns(req)`, `getVisibleColumnKeys(req)` or
+`isColumnVisible(req, "email")` anywhere in a custom data method. Reads are cached
+per table instance and request, never across users or environments.
+
+`aggregation(req, context)` and `subAggregation(req, context)` receive a
+`DatatableColumnContext`. The controller also passes it as the second argument
+to `getData(req, context)`, including overrides. `onData(req, result, context)`,
+`onRow(row, req, context)` and `onAttributes(row, req, context)` receive it during
+normal paginated loading. The context exposes `columns`, `columnKeys`,
+`isColumnVisible(key)` and `isColumnRequired(key)`.
+
+```ts
+aggregation = async (req: Request, columns: DatatableColumnContext) => [
+    { $match: { environment: req.env._id } },
+    ...(columns.isColumnRequired("customer") ? [
+        { $lookup: { from: "customers", localField: "customer_id", foreignField: "_id", as: "customer" } },
+    ] : []),
+];
+```
+
+Prefer `isColumnRequired` for query optimization: it also considers declared
+mappings, active filter/search/sort fields and sums, as well as model-selector
+preview fields. This avoids breaking a sort/filter on a hidden column. Dependencies
+inside custom expressions, custom filters, exports or other calculated columns
+remain the table author's responsibility.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@webtypen/webframez-core",
-    "version": "0.3.97",
+    "version": "0.3.101",
     "description": "The core package of the typescript based webframez (web-framework) by webtypen.de",
     "homepage": "https://webtypen.de/",
     "license": "MIT",
@@ -36,7 +36,8 @@
         "docs/queue-workers.md",
         "docs/errors.md",
         "build-cache.js",
-        "build-cache.d.ts"
+        "build-cache.d.ts",
+        "docs/datatables.md"
     ],
     "scripts": {
         "build": "tsc",