@webtypen/webframez-core 0.3.103 → 0.3.105

package/dist/Commands/QueueWorkerCommand.js

@@ -13,6 +13,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.QueueWorkerCommand = void 0;
+const QueueExecutionContext_1 = require("../Queue/QueueExecutionContext");
 const fs_1 = __importDefault(require("fs"));
 const crypto_1 = __importDefault(require("crypto"));
 const path_1 = __importDefault(require("path"));
@@ -662,7 +663,7 @@ class QueueWorkerCommand extends ConsoleCommand_1.ConsoleCommand {
                         if (!jobType) {
                             throw new Error(`QueueError: Invalid job-type ${job.jobclass}`);
                         }
-                        const result = yield ErrorHandler_1.ErrorHandler.withContext({ scope: "job", operationId: jobOperationId, job: { id: String(job._id), number: job.number, jobclass: job.jobclass, worker: this.workerKey, instance: process.env.WEBFRAMEZ_QUEUE_INSTANCE, attempt: job.attempts_made } }, () => jobInstance.handle(job));
+                        const result = yield ErrorHandler_1.ErrorHandler.withContext({ scope: "job", operationId: jobOperationId, job: { id: String(job._id), number: job.number, jobclass: job.jobclass, worker: this.workerKey, instance: process.env.WEBFRAMEZ_QUEUE_INSTANCE, attempt: job.attempts_made } }, () => QueueExecutionContext_1.QueueExecutionContext.run(job.execution_context, () => jobInstance.handle(job)));
                         const endedAt = new Date();
                         job.status = "finished";
                         job.ended_at = endedAt;
@@ -727,7 +728,7 @@ class QueueWorkerCommand extends ConsoleCommand_1.ConsoleCommand {
                         if (exhausted && (jobInstance === null || jobInstance === void 0 ? void 0 : jobInstance.onRetryExhausted) && (job.retry_exhaustion_attempts || 0) < retryPolicy.maxFinalizationAttempts) {
                             job.retry_exhaustion_attempts = (job.retry_exhaustion_attempts || 0) + 1;
                             try {
-                                recovered = (yield jobInstance.onRetryExhausted(job, e)) === "finished";
+                                recovered = (yield QueueExecutionContext_1.QueueExecutionContext.run(job.execution_context, () => jobInstance.onRetryExhausted(job, e))) === "finished";
                                 job.retry_exhaustion_error = null;
                             }
                             catch (finalizationError) {

package/dist/Database/Model.js

@@ -267,7 +267,7 @@ class Model {
                 type: "aggregation",
                 table: collection ? collection : model ? model.__table : undefined,
                 aggregation: aggregation,
-            }, model.__connection);
+            }, model.__connection, options);
         });
     }
     buildRelationship(model, foreignKey, localKey) {

package/dist/Datatable/Datatable.d.ts

@@ -37,6 +37,7 @@ export declare class Datatable {
     autoApplyFilter: "begin" | "end" | null;
     autoApplySearch: "begin" | "end" | null;
     logAggregation: boolean;
+    collation: Record<string, any> | ((req: Request) => Record<string, any> | Promise<Record<string, any>>);
     defaultUnwind?: string | null;
     disablePerPageConfig: boolean;
     selectable: boolean;
@@ -77,6 +78,8 @@ export declare class Datatable {
     }[] | null>;
     getAggregation(req: Request): Promise<any>;
     getSubAggregation(req: Request): Promise<any>;
+    /** Filtered source for whole-result statistics; presentation and pagination are excluded. */
+    getStatisticsAggregation(req: Request): Promise<any[]>;
     getCollection(req: Request): Promise<any>;
     getData(req: Request, context?: DatatableColumnContext): Promise<{
         page: number;

package/dist/Datatable/Datatable.js

@@ -43,6 +43,7 @@ class Datatable {
         this.autoApplyFilter = "begin";
         this.autoApplySearch = null;
         this.logAggregation = false;
+        this.collation = { locale: "de", strength: 2 };
         this.defaultUnwind = null;
         this.disablePerPageConfig = false;
         this.selectable = false;
@@ -252,10 +253,7 @@ class Datatable {
             const results = yield DBConnection_1.DBConnection.documentStore(connection)
                 .collection(yield this.getCollection(req))
                 .aggregate(aggregation, {
-                collation: {
-                    locale: "de",
-                    strength: 2,
-                },
+                collation: typeof this.collation === "function" ? yield this.collation(req) : this.collation,
             })
                 .toArray();
             if (!results[0]) {
@@ -353,6 +351,17 @@ class Datatable {
             return typeof this.subAggregation === "function" ? yield this.subAggregation(req, yield this.getColumnContext(req)) : this.subAggregation;
         });
     }
+    /** Filtered source for whole-result statistics; presentation and pagination are excluded. */
+    getStatisticsAggregation(req) {
+        return __awaiter(this, void 0, void 0, function* () {
+            return [...(yield this.getAggregation(req)) || [], ...(yield this.getSubAggregation(req)) || []]
+                .filter(stage => !stage.skipStats && !stage.$sort && stage.$skip === undefined && stage.$limit === undefined)
+                .map((_a) => {
+                var { skipStats } = _a, stage = __rest(_a, ["skipStats"]);
+                return stage;
+            });
+        });
+    }
     getCollection(req) {
         return __awaiter(this, void 0, void 0, function* () {
             if (this.collection && typeof this.collection === "function") {
@@ -373,15 +382,15 @@ class Datatable {
             let hasSkip = false;
             let hasLimit = false;
             if (aggregationDef && aggregationDef.length > 0) {
-                for (let entry of aggregationDef) {
+                for (const definition of aggregationDef) {
+                    const { skipStats } = definition, entry = __rest(definition, ["skipStats"]);
                     if (entry.$skip !== undefined) {
                         hasSkip = true;
                     }
                     if (entry.$limit !== undefined) {
                         hasLimit = true;
                     }
-                    if (entry.skipStats) {
-                        delete entry.skipStats;
+                    if (skipStats) {
                         aggregation.push(entry);
                     }
                     else {
@@ -391,15 +400,15 @@ class Datatable {
                 }
             }
             if (subAggregationDef && subAggregationDef.length > 0) {
-                for (let entry of subAggregationDef) {
+                for (const definition of subAggregationDef) {
+                    const { skipStats } = definition, entry = __rest(definition, ["skipStats"]);
                     if (entry.$skip !== undefined) {
                         hasSkip = true;
                     }
                     if (entry.$limit !== undefined) {
                         hasLimit = true;
                     }
-                    if (entry.skipStats) {
-                        delete entry.skipStats;
+                    if (skipStats) {
                         subAggregation.push(entry);
                     }
                     else {
@@ -423,10 +432,7 @@ class Datatable {
             const results = yield DBConnection_1.DBConnection.documentStore(connection)
                 .collection(yield this.getCollection(req))
                 .aggregate(aggr, {
-                collation: {
-                    locale: "de",
-                    strength: 2,
-                },
+                collation: typeof this.collation === "function" ? yield this.collation(req) : this.collation,
             })
                 .toArray();
             const sumsAfter = [];
@@ -514,9 +520,9 @@ class Datatable {
             const aggregation = [];
             const aggregationDef = yield this.getAggregation(req);
             if (aggregationDef && aggregationDef.length > 0) {
-                for (let entry of aggregationDef) {
-                    if (entry.skipStats) {
-                        delete entry.skipStats;
+                for (const definition of aggregationDef) {
+                    const { skipStats } = definition, entry = __rest(definition, ["skipStats"]);
+                    if (skipStats) {
                         aggregation.push(entry);
                     }
                     else {

package/dist/Queue/Queue.js

@@ -13,6 +13,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Queue = void 0;
+const QueueExecutionContext_1 = require("./QueueExecutionContext");
 const ErrorHandler_1 = require("../ErrorHandling/ErrorHandler");
 const crypto_1 = __importDefault(require("crypto"));
 const DBConnection_1 = require("../Database/DBConnection");
@@ -29,7 +30,7 @@ class Queue {
         return __awaiter(this, void 0, void 0, function* () {
             QueueJobsRegisty_1.QueueJobsRegisty.getJobOrFail(jobclass);
             const jobs = yield this.collection(), id = props._id || crypto_1.default.randomUUID();
-            yield jobs.updateOne({ _id: id }, { $setOnInsert: Object.assign(Object.assign({}, props), { _id: id, jobclass, status: "pending", created_at: new Date(), not_before: null, worker: null }) }, { upsert: true });
+            yield jobs.updateOne({ _id: id }, { $setOnInsert: Object.assign(Object.assign({}, props), { execution_context: QueueExecutionContext_1.QueueExecutionContext.capture(), _id: id, jobclass, status: "pending", created_at: new Date(), not_before: null, worker: null }) }, { upsert: true });
             return jobs.findOne({ _id: id });
         });
     }
@@ -126,7 +127,7 @@ class Queue {
                     if (job.retry_exhaustion_attempts)
                         throw new QueueRetryLimitError_1.QueueRetryLimitError("Retry exhaustion finalization pending.");
                     QueueRetryPolicy_1.QueueRetryPolicy.assertCanRun(policy, job, previousAttempts, now);
-                    const result = yield ErrorHandler_1.ErrorHandler.withContext({ scope: "job", operationId: token, source: "queue.embedded", job: { id: String(job._id), number: job.number, jobclass: job.jobclass, worker: this.worker, attempt: job.attempts_made } }, () => handler.handle(Object.assign(Object.assign({}, job), { signal: controller.signal })));
+                    const result = yield ErrorHandler_1.ErrorHandler.withContext({ scope: "job", operationId: token, source: "queue.embedded", job: { id: String(job._id), number: job.number, jobclass: job.jobclass, worker: this.worker, attempt: job.attempts_made } }, () => QueueExecutionContext_1.QueueExecutionContext.run(job.execution_context, () => handler.handle(Object.assign(Object.assign({}, job), { signal: controller.signal }))));
                     const endedAt = new Date();
                     const retryAt = (result === null || result === void 0 ? void 0 : result.__execute_again)
                         ? QueueRetryPolicy_1.QueueRetryPolicy.rescheduleAt(policy, job, job.attempts_made, result.__execute_again, endedAt)
@@ -152,7 +153,7 @@ class Queue {
                     if (exhausted && (handler === null || handler === void 0 ? void 0 : handler.onRetryExhausted) && (job.retry_exhaustion_attempts || 0) < policy.maxFinalizationAttempts) {
                         job.retry_exhaustion_attempts = (job.retry_exhaustion_attempts || 0) + 1;
                         try {
-                            recovered = (yield handler.onRetryExhausted(job, error)) === "finished";
+                            recovered = (yield QueueExecutionContext_1.QueueExecutionContext.run(job.execution_context, () => handler.onRetryExhausted(job, error))) === "finished";
                         }
                         catch (finalizationError) {
                             yield ErrorHandler_1.ErrorHandler.report(finalizationError, { scope: "job", source: "queue.embedded.finalization", job: { id: String(job._id), jobclass: job.jobclass, worker: this.worker } });

package/dist/Queue/QueueExecutionContext.d.ts

@@ -0,0 +1,7 @@
+/** Server-owned attribution that follows queued work. Never populate from request payloads.
+ * Consumers must reauthorize persisted identities before performing protected effects. */
+export declare class QueueExecutionContext {
+    private static storage;
+    static capture(): Record<string, unknown> | undefined;
+    static run<T>(context: Record<string, unknown> | undefined, callback: () => T): T;
+}

package/dist/Queue/QueueExecutionContext.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.QueueExecutionContext = void 0;
+const async_hooks_1 = require("async_hooks");
+/** Server-owned attribution that follows queued work. Never populate from request payloads.
+ * Consumers must reauthorize persisted identities before performing protected effects. */
+class QueueExecutionContext {
+    static capture() {
+        const value = this.storage.getStore();
+        return value ? JSON.parse(JSON.stringify(value)) : undefined;
+    }
+    static run(context, callback) {
+        return this.storage.run(context ? JSON.parse(JSON.stringify(context)) : {}, callback);
+    }
+}
+exports.QueueExecutionContext = QueueExecutionContext;
+QueueExecutionContext.storage = new async_hooks_1.AsyncLocalStorage();

package/dist/Queue/QueueJob.d.ts

@@ -6,4 +6,5 @@ export declare class QueueJob extends Model {
     _notification?: DatabaseId;
     notification?: Notification;
     __table: string;
+    save(): Promise<any>;
 }

package/dist/Queue/QueueJob.js

@@ -1,11 +1,32 @@
 "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.QueueJob = void 0;
+const QueueExecutionContext_1 = require("./QueueExecutionContext");
 const Model_1 = require("../Database/Model");
 class QueueJob extends Model_1.Model {
     constructor() {
         super(...arguments);
         this.__table = "queue_jobs";
     }
+    save() {
+        const _super = Object.create(null, {
+            save: { get: () => super.save }
+        });
+        return __awaiter(this, void 0, void 0, function* () {
+            const context = QueueExecutionContext_1.QueueExecutionContext.capture();
+            if (context)
+                this.execution_context = context;
+            return _super.save.call(this);
+        });
+    }
 }
 exports.QueueJob = QueueJob;

package/dist/index.d.ts

@@ -80,3 +80,4 @@ export { Field, Validates, Forms, DataBuilderFieldOptions } from "./DataBuilder/
 export { DataBuilderRouteOptions } from "./DataBuilder/DataBuilderRoute";
 export { LegacyFieldTypeAdapter } from "./DataBuilder/LegacyFieldTypeAdapter";
 export { defaultFormFields } from "./DataBuilder/formScope";
+export * from "./Queue/QueueExecutionContext";

package/dist/index.js

@@ -101,3 +101,4 @@ 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; } });
+__exportStar(require("./Queue/QueueExecutionContext"), exports);

package/docs/datatables.md

@@ -126,3 +126,15 @@ 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.
+
+## Statistics and collation
+
+`getStatisticsAggregation(req)` returns the filtered aggregation and sub-aggregation,
+excluding stages marked `skipStats: true`, sorting and pagination. It does not mutate
+stage definitions. Keep tenant and filter dependencies unmarked; calculate statistic-only
+fields in the statistics service instead of depending on presentation projections.
+
+`collation` defaults to `{ locale: "de", strength: 2 }` for compatibility. It can be
+an object or an async request callback. Tables sorting numeric/date fields can return
+`{ locale: "simple" }` to use matching binary indexes. Keep language collation for
+text sorting or filters that depend on it; collation applies to the entire data query.

package/docs/queue-workers.md

@@ -135,3 +135,14 @@ Dedicated workers with an explicit `jobclasses` allowlist may set
 `includeBackupJobs: false` to prevent the automatic addition of `BackupRunJob`.
 This keeps long backups out of a latency-sensitive worker. Existing workers keep
 the previous default; explicitly listed backup jobs remain allowed.
+
+### Server-owned execution context
+
+`QueueExecutionContext.run(context, callback)` carries JSON-serializable server-owned
+attribution through asynchronous calls. Jobs saved via `QueueJob.save()` or
+`Queue.enqueue()` capture it in `execution_context`; console and embedded workers
+restore it for handlers and retry-exhaustion callbacks. Child jobs inherit it.
+`QueueExecutionContext.capture()` returns a detached snapshot. Do not populate this
+field from client payloads or treat it as authorization: reload the referenced
+account and current permissions before protected effects. Raw database inserts
+must explicitly capture the context when used instead of the queue APIs.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@webtypen/webframez-core",
-    "version": "0.3.103",
+    "version": "0.3.105",
     "description": "The core package of the typescript based webframez (web-framework) by webtypen.de",
     "homepage": "https://webtypen.de/",
     "license": "MIT",