@webtypen/webframez-core 0.3.100 → 0.3.102

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,18 @@ export declare class Datatable {
         };
     } | null;
     getInit(req: Request): Promise<any>;
+    private loadColumnState;
+    /** Options may be declared inline or loaded from an authenticated host callback. */
+    getColumnDisplayOptions(req: Request, key: string): Promise<any>;
+    private resolveDisplayOptions;
+    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 +78,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), { displayOptions: typeof column.displayOptions === "function" ? true : column.displayOptions, key })));
+            out.availableColumns = Object.entries(state.all).map(([key, column]) => (Object.assign(Object.assign({}, column), { displayOptions: typeof column.displayOptions === "function" ? true : column.displayOptions, key })));
+            out.columnPreferences = Boolean(state.scope) && Object.keys(state.all).length > 0;
+            out.columnSelection = out.columns.map((column) => {
+                var _a;
+                const saved = (_a = state.preferences) === null || _a === void 0 ? void 0 : _a.find((entry) => entry.key === column.key);
+                return Object.assign(Object.assign(Object.assign({ key: column.key }, ((saved === null || saved === void 0 ? void 0 : saved.width) ? { width: saved.width } : {})), ((saved === null || saved === void 0 ? void 0 : saved.title) ? { title: saved.title } : {})), ((saved === null || saved === void 0 ? void 0 : saved.displayField) && saved.displayField === column.displayField ? { displayField: saved.displayField } : {}));
+            });
+            out.onPressLink = onPressLink;
             if (this.exports) {
                 out.export_definitions = [];
                 for (let key in this.exports) {
@@ -87,13 +83,134 @@ 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;
+            const savedKeys = Array.isArray(preferences) ? preferences.map(entry => entry === null || entry === void 0 ? void 0 : entry.key).filter(key => Object.prototype.hasOwnProperty.call(all, key)) : [];
+            const selected = savedKeys.length ? savedKeys : Object.keys(all).filter(key => !all[key].hidden);
+            const resolved = yield this.resolveDisplayOptions(req, all, selected);
+            return { all, visible: DatatableColumnPreferences_1.DatatableColumnPreferences.apply(resolved, preferences), preferences, store, scope };
+        });
+    }
+    /** Options may be declared inline or loaded from an authenticated host callback. */
+    getColumnDisplayOptions(req, key) {
+        var _a;
+        return __awaiter(this, void 0, void 0, function* () {
+            const all = (_a = yield this.getColumns(req)) !== null && _a !== void 0 ? _a : {};
+            if (typeof key !== "string" || !Object.prototype.hasOwnProperty.call(all, key)) {
+                throw Object.assign(new Error("Unbekannte Spalte."), { status: 400 });
+            }
+            const resolved = yield this.resolveDisplayOptions(req, all, [key]);
+            return resolved[key].displayOptions || [];
+        });
+    }
+    resolveDisplayOptions(req, columns, keys) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const resolved = Object.assign({}, columns);
+            yield Promise.all(Array.from(new Set(keys)).filter(key => typeof key === "string" && Object.prototype.hasOwnProperty.call(columns, key)).map((key) => __awaiter(this, void 0, void 0, function* () {
+                const column = columns[key];
+                if (typeof column.displayOptions === "function") {
+                    const options = yield column.displayOptions(req, key);
+                    resolved[key] = Object.assign(Object.assign({}, column), { displayOptions: Array.isArray(options) ? options : [] });
+                }
+            })));
+            return resolved;
+        });
+    }
+    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 {
+                const resolved = yield this.resolveDisplayOptions(req, state.all, Array.isArray(columns) ? columns.map(entry => entry === null || entry === void 0 ? void 0 : entry.key) : []);
+                preferences = DatatableColumnPreferences_1.DatatableColumnPreferences.validate(columns, resolved);
+            }
+            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 +315,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 +350,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 +361,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 +450,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 +499,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 +826,4 @@ class Datatable {
     }
 }
 exports.Datatable = Datatable;
+Datatable.columnPreferences = {};

package/dist/Datatable/DatatableColumnPreferences.d.ts

@@ -0,0 +1,40 @@
+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;
+    title?: string;
+    displayField?: string;
+}
+export interface DatatableDisplayOption {
+    value: string;
+    label: string;
+    type?: string;
+    plain?: boolean;
+    options?: any[];
+}
+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 display(definition: any, selected?: string): any;
+    static apply(columns: Record<string, any>, preferences: unknown): Record<string, any>;
+}

package/dist/Datatable/DatatableColumnPreferences.js

@@ -0,0 +1,97 @@
+"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.title !== undefined) {
+                if (typeof entry.title !== "string" || entry.title.length > 160)
+                    throw new Error("Ungültiger Spaltentitel (maximal 160 Zeichen).");
+                if (entry.title.trim())
+                    preference.title = entry.title.trim();
+            }
+            if (entry.displayField !== undefined && entry.displayField !== "") {
+                if (typeof entry.displayField !== "string" || !Array.isArray(columns[entry.key].displayOptions)
+                    || !columns[entry.key].displayOptions.some((option) => option.value === entry.displayField)) {
+                    throw new Error("Unzulässiges Anzeigefeld für diese Spalte.");
+                }
+                preference.displayField = entry.displayField;
+            }
+            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 display(definition, selected) {
+        const column = Object.assign({}, definition);
+        const options = Array.isArray(column.displayOptions) ? column.displayOptions : [];
+        const option = options.find(entry => entry.value === (selected || column.displayField)) || options[0];
+        if (option) {
+            column.displayField = option.value;
+            for (const key of ["type", "plain", "options"])
+                if (option[key] !== undefined)
+                    column[key] = option[key];
+        }
+        return column;
+    }
+    static apply(columns, preferences) {
+        const defaults = () => Object.fromEntries(Object.entries(columns).filter(([, column]) => column.hidden !== true).map(([key, column]) => [key, this.display(column)]));
+        if (!Array.isArray(preferences))
+            return defaults();
+        const available = preferences.filter(entry => entry && typeof entry.key === "string" && Object.prototype.hasOwnProperty.call(columns, entry.key)).map(entry => {
+            const options = columns[entry.key].displayOptions;
+            // Removed target fields fall back independently; retain the rest of the layout.
+            return entry.displayField && (!Array.isArray(options) || !options.some((option) => option.value === entry.displayField))
+                ? Object.assign(Object.assign({}, entry), { displayField: undefined }) : entry;
+        });
+        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 = this.display(columns[preference.key], preference.displayField);
+            if (preference.title) {
+                column.title = preference.title;
+                column.label = preference.title;
+            }
+            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,49 @@ 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 (["columns-save", "columns-reset", "columns-options"].includes(req.body.mode)) {
+                try {
+                    const data = req.body.mode === "columns-options"
+                        ? yield table.getColumnDisplayOptions(req, req.body.column)
+                        : 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 +75,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 +109,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 +138,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 +147,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/Datatable/DatatableSchemaColumns.d.ts

@@ -0,0 +1,8 @@
+/** Converts DataBuilder/DataSchema field definitions into an extensible column catalog. */
+export declare class DatatableSchemaColumns {
+    static fromSchema(schema: Record<string, any>, options?: {
+        prefix?: string;
+        labelPrefix?: string;
+        prepare?: (column: Record<string, any>, field: any, path: string) => Record<string, any> | null;
+    }): Record<string, any>;
+}

package/dist/Datatable/DatatableSchemaColumns.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DatatableSchemaColumns = void 0;
+/** Converts DataBuilder/DataSchema field definitions into an extensible column catalog. */
+class DatatableSchemaColumns {
+    static fromSchema(schema, options = {}) {
+        const columns = {};
+        for (const [key, field] of Object.entries(schema || {})) {
+            if (!field || /[.$]/.test(key) || ["__proto__", "constructor", "prototype"].includes(key)
+                || field.secret || field.writeOnly || field.type === "password")
+                continue;
+            const mapping = options.prefix ? `${options.prefix}.${key}` : key;
+            const label = [options.labelPrefix, field.label || key].filter(Boolean).join(" · ");
+            if (field.type === "object") {
+                Object.assign(columns, this.fromSchema(field.schema, Object.assign(Object.assign({}, options), { prefix: mapping, labelPrefix: label })));
+                continue;
+            }
+            const types = { integer: "number", float: "number", number: "number", boolean: "boolean", date: "date", datetime: "datetime", option: "option", currency_cent: "currency", currency: "currency" };
+            const column = Object.assign(Object.assign({ label, mapping, type: types[field.type] || "string", width: 170, hidden: true, sortable: !["array", "file", "filemanager_file", "relation"].includes(field.type) && !field.multi }, (field.type === "currency" ? { plain: true } : {})), (field.options ? { options: field.options } : {}));
+            const prepared = options.prepare ? options.prepare(column, field, mapping) : column;
+            if (prepared)
+                columns[mapping] = prepared;
+        }
+        return columns;
+    }
+}
+exports.DatatableSchemaColumns = DatatableSchemaColumns;

package/dist/index.d.ts

@@ -28,6 +28,9 @@ export * from "./Facades/Storage";
 export * from "./DataBuilder/DataBuilder";
 export * from "./DataBuilder/DataBuilderController";
 export * from "./Datatable/Datatable";
+export * from "./Datatable/DatatableColumnPreferences";
+export * from "./Datatable/DatatableSchemaColumns";
+export * from "./Datatable/DatatablePreferencesStore";
 export * from "./Datatable/DatatableRegistry";
 export * from "./Datatable/DatatableController";
 export * from "./Queue/BaseQueueJob";

package/dist/index.js

@@ -45,6 +45,9 @@ __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/DatatableSchemaColumns"), exports);
+__exportStar(require("./Datatable/DatatablePreferencesStore"), exports);
 __exportStar(require("./Datatable/DatatableRegistry"), exports);
 __exportStar(require("./Datatable/DatatableController"), exports);
 __exportStar(require("./Queue/BaseQueueJob"), exports);

package/docs/datatables.md

@@ -0,0 +1,128 @@
+# 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.
+
+## Relation display fields and custom titles
+
+A column can declare `displayOptions: [{ value: "name", label: "Name", type: "string" }]`
+or an async `displayOptions(req, columnKey)` callback. The callback receives the
+normal authenticated request. Initialization advertises lazy options with `true`;
+`mode: "columns-options", column: "key"` resolves them when the editor needs them.
+Only visible columns resolve options during normal loading. `displayField` selects
+the backend default; otherwise the first option is used.
+
+Saved preferences accept `title` (up to 160 characters) and `displayField` in
+addition to width. Empty values restore the backend defaults. An unknown display
+field is rejected on save; if a previously saved field disappears, loading falls
+back to the default while preserving the other layout settings.
+
+Core validates the selection and exposes it through `context.columns[key].displayField`;
+the host performs the relation lookup and writes the value to the column's stable
+`mapping`. Options can supply `type`, `plain` and `options` for typed rendering.
+Never interpret an unchecked client field as a database projection.
+
+`DatatableSchemaColumns.fromSchema(schema, { prefix, labelPrefix, prepare })`
+creates an optional column catalog from nested DataBuilder/DataSchema fields.
+The `prepare(column, field, path)` callback can attach inline or lazy display
+options, change the mapping, or return null to omit a field. Plugin installation,
+tenant checks and relation hydration belong in the host adapter.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@webtypen/webframez-core",
-    "version": "0.3.100",
+    "version": "0.3.102",
     "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",