@cqrs-ddd/pipeline-job-context 0.5.0

package/README.md

@@ -0,0 +1,42 @@
+# @cqrs-ddd/pipeline-job-context
+
+Carries the tenant, correlation id and principal of a request into the queue jobs it
+enqueues, and gives system-started work an explicit context: `registerJobContext()` once
+at startup, `withJobContext()` when a job is enqueued, `@InJobContext()` on the consumer
+and `@AsSystem()` on system work (both TypeScript decorator modes). No framework.
+
+**Documentation:** [guide](https://aristoteliss.github.io/ddd-cqrs/packages/pipeline-job-context/) · [API reference](https://aristoteliss.github.io/ddd-cqrs/api/cqrs-ddd/pipeline-job-context/) · [all packages](https://aristoteliss.github.io/ddd-cqrs/)
+
+## Installation
+
+```bash
+pnpm add @cqrs-ddd/pipeline-job-context
+```
+
+Requires Node.js 22.12 or later. Published as an ES module; a CommonJS application loads
+it with `require()`.
+
+## Example
+
+```ts
+registerJobContext({
+  principal: new SessionJobPrincipal(sessions),
+  tenants: ['acme'],
+  sources: { tenantId: tenantSource, correlationId: correlationSource },
+});
+
+await queue.add('welcome', withJobContext({ userId }));
+
+class WelcomeWorker {
+  @InJobContext()
+  async process(job: { data: { userId: string } }) {}
+}
+```
+
+A queue payload is untrusted data: it carries only the principal's identity, and the
+principal is re-checked when the job runs.
+
+## License
+
+Dual-licensed under **AGPLv3** and a **Commercial License**. See `LICENSE` and
+`COMMERCIAL_LICENSE.txt`.

package/dist/decorators/as-system.decorator.d.ts

@@ -0,0 +1,36 @@
+import { type DualMethodDecorator } from '../helpers/method-decorator.js';
+import type { PrincipalReference } from '../interfaces/principal-reference.interface.js';
+/** Options of {@link AsSystem}. */
+export interface AsSystemOptions<TGrant = unknown> {
+    /** The service principal the work acts as. */
+    principal: PrincipalReference;
+    /** The principal's complete authorization; nothing else grants it anything. */
+    grants: readonly TGrant[];
+}
+/**
+ * Runs system-started work, such as a cron job, once per configured tenant.
+ * Each run has its own tenant, a new correlation id, and the declared service
+ * principal and grants, bound through the registered `IJobPrincipal`. Grants
+ * come only from this declaration, never from data.
+ *
+ * Tenants run one after another. A failing tenant does not stop the others;
+ * the method then rejects with an `AggregateError` of the failures. Its return
+ * values are discarded. Place it under the scheduling decorator.
+ *
+ * @example
+ * ```ts
+ * class Maintenance {
+ *   @AsSystem({
+ *     principal: { id: 'session-cleanup', type: 'service' },
+ *     grants: [{ action: 'delete', subject: 'Auth' }],
+ *   })
+ *   async purgeSessions() {
+ *     await purgeExpiredSessions();
+ *   }
+ * }
+ *
+ * cron.schedule('0 3 * * *', () => maintenance.purgeSessions());
+ * ```
+ */
+export declare function AsSystem<TGrant>(options: AsSystemOptions<TGrant>): DualMethodDecorator;
+//# sourceMappingURL=as-system.decorator.d.ts.map

package/dist/decorators/as-system.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"as-system.decorator.d.ts","sourceRoot":"","sources":["../../src/decorators/as-system.decorator.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,mBAAmB,EAEzB,MAAM,gCAAgC,CAAC;AAGxC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gDAAgD,CAAC;AAEzF,mCAAmC;AACnC,MAAM,WAAW,eAAe,CAAC,MAAM,GAAG,OAAO;IAC/C,8CAA8C;IAC9C,SAAS,EAAE,kBAAkB,CAAC;IAC9B,+EAA+E;IAC/E,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAC7B,OAAO,EAAE,eAAe,CAAC,MAAM,CAAC,GAC/B,mBAAmB,CAiCrB"}

package/dist/decorators/as-system.decorator.js

@@ -0,0 +1,53 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+import { methodDecorator, } from '../helpers/method-decorator.js';
+import { toReference } from '../helpers/principal-reference.js';
+import { activeRegistration } from '../helpers/registration.js';
+/**
+ * Runs system-started work, such as a cron job, once per configured tenant.
+ * Each run has its own tenant, a new correlation id, and the declared service
+ * principal and grants, bound through the registered `IJobPrincipal`. Grants
+ * come only from this declaration, never from data.
+ *
+ * Tenants run one after another. A failing tenant does not stop the others;
+ * the method then rejects with an `AggregateError` of the failures. Its return
+ * values are discarded. Place it under the scheduling decorator.
+ *
+ * @example
+ * ```ts
+ * class Maintenance {
+ *   @AsSystem({
+ *     principal: { id: 'session-cleanup', type: 'service' },
+ *     grants: [{ action: 'delete', subject: 'Auth' }],
+ *   })
+ *   async purgeSessions() {
+ *     await purgeExpiredSessions();
+ *   }
+ * }
+ *
+ * cron.schedule('0 3 * * *', () => maintenance.purgeSessions());
+ * ```
+ */
+export function AsSystem(options) {
+    const reference = toReference(options.principal);
+    const grants = [...options.grants];
+    return methodDecorator((original) => {
+        return async function (...args) {
+            const { principal, tenants, sources } = activeRegistration();
+            const failures = [];
+            const failed = [];
+            for (const tenant of tenants) {
+                try {
+                    await sources.tenantId.run(tenant, () => sources.correlationId.run(sources.correlationId.create(), () => principal.restore(reference, async () => original.apply(this, args), grants)));
+                }
+                catch (error) {
+                    failures.push(error);
+                    failed.push(tenant);
+                }
+            }
+            if (failures.length > 0) {
+                throw new AggregateError(failures, `System work failed in tenants: ${failed.join(', ')}`);
+            }
+        };
+    });
+}
+//# sourceMappingURL=as-system.decorator.js.map

package/dist/decorators/as-system.decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"as-system.decorator.js","sourceRoot":"","sources":["../../src/decorators/as-system.decorator.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE,OAAO,EAEL,eAAe,GAChB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,mCAAmC,CAAC;AAChE,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAWhE;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,UAAU,QAAQ,CACtB,OAAgC;IAEhC,MAAM,SAAS,GAAG,WAAW,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACjD,MAAM,MAAM,GAAG,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAEnC,OAAO,eAAe,CAAC,CAAC,QAAQ,EAAE,EAAE;QAClC,OAAO,KAAK,WAA0B,GAAG,IAAe;YACtD,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,kBAAkB,EAAE,CAAC;YAC7D,MAAM,QAAQ,GAAc,EAAE,CAAC;YAC/B,MAAM,MAAM,GAAa,EAAE,CAAC;YAC5B,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;gBAC7B,IAAI,CAAC;oBACH,MAAM,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE,CACtC,OAAO,CAAC,aAAa,CAAC,GAAG,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,EAAE,EAAE,GAAG,EAAE,CAC7D,SAAS,CAAC,OAAO,CACf,SAAS,EACT,KAAK,IAAI,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,EACtC,MAAM,CACP,CACF,CACF,CAAC;gBACJ,CAAC;gBAAC,OAAO,KAAK,EAAE,CAAC;oBACf,QAAQ,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;oBACrB,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBACtB,CAAC;YACH,CAAC;YACD,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACxB,MAAM,IAAI,cAAc,CACtB,QAAQ,EACR,kCAAkC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CACtD,CAAC;YACJ,CAAC;QACH,CAAC,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/decorators/in-job-context.decorator.d.ts

@@ -0,0 +1,35 @@
+import { type DualMethodDecorator } from '../helpers/method-decorator.js';
+/** Options of {@link InJobContext}. */
+export interface InJobContextOptions {
+    /**
+     * Dot path to the job context in the method's first argument.
+     *
+     * @default 'data.jobContext' (a BullMQ `Job`)
+     */
+    path?: string;
+}
+/**
+ * Runs a job-processing method inside the context `withJobContext` stamped on
+ * its payload: the tenant, the correlation id, and the principal the registered
+ * `IJobPrincipal` re-checks and binds. The method becomes async.
+ *
+ * It fails closed before the method runs: a payload without a context, with a
+ * malformed one, with an unconfigured tenant, or with a principal carrying
+ * anything beyond `id`, `type` and `sessionId` is refused, and so is a
+ * principal `restore` rejects. Place it under the transport decorator.
+ *
+ * @example
+ * ```ts
+ * class WelcomeEmailWorker {
+ *   @InJobContext()
+ *   async process(job: Job<WithJobContext<WelcomeEmail>>) {
+ *     await sendWelcomeEmail(job.data);
+ *   }
+ * }
+ *
+ * const worker = new WelcomeEmailWorker();
+ * new Worker(WELCOME_EMAIL_QUEUE, (job) => worker.process(job));
+ * ```
+ */
+export declare function InJobContext(options?: InJobContextOptions): DualMethodDecorator;
+//# sourceMappingURL=in-job-context.decorator.d.ts.map

package/dist/decorators/in-job-context.decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-job-context.decorator.d.ts","sourceRoot":"","sources":["../../src/decorators/in-job-context.decorator.ts"],"names":[],"mappings":"AAEA,OAAO,EACL,KAAK,mBAAmB,EAEzB,MAAM,gCAAgC,CAAC;AAIxC,uCAAuC;AACvC,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAWD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,YAAY,CAC1B,OAAO,GAAE,mBAAwB,GAChC,mBAAmB,CAoBrB"}

package/dist/decorators/in-job-context.decorator.js

@@ -0,0 +1,47 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+import { methodDecorator, } from '../helpers/method-decorator.js';
+import { parseJobContext } from '../helpers/parse-job-context.js';
+import { activeRegistration } from '../helpers/registration.js';
+function readPath(value, segments) {
+    let current = value;
+    for (const segment of segments) {
+        if (typeof current !== 'object' || current === null)
+            return undefined;
+        current = current[segment];
+    }
+    return current;
+}
+/**
+ * Runs a job-processing method inside the context `withJobContext` stamped on
+ * its payload: the tenant, the correlation id, and the principal the registered
+ * `IJobPrincipal` re-checks and binds. The method becomes async.
+ *
+ * It fails closed before the method runs: a payload without a context, with a
+ * malformed one, with an unconfigured tenant, or with a principal carrying
+ * anything beyond `id`, `type` and `sessionId` is refused, and so is a
+ * principal `restore` rejects. Place it under the transport decorator.
+ *
+ * @example
+ * ```ts
+ * class WelcomeEmailWorker {
+ *   @InJobContext()
+ *   async process(job: Job<WithJobContext<WelcomeEmail>>) {
+ *     await sendWelcomeEmail(job.data);
+ *   }
+ * }
+ *
+ * const worker = new WelcomeEmailWorker();
+ * new Worker(WELCOME_EMAIL_QUEUE, (job) => worker.process(job));
+ * ```
+ */
+export function InJobContext(options = {}) {
+    const segments = (options.path ?? 'data.jobContext').split('.');
+    return methodDecorator((original) => {
+        return async function (...args) {
+            const { principal, tenants, sources } = activeRegistration();
+            const context = parseJobContext(readPath(args[0], segments), tenants, sources.correlationId.accepts);
+            return sources.tenantId.run(context.tenantId, () => sources.correlationId.run(context.correlationId, () => principal.restore(context.principal, async () => original.apply(this, args))));
+        };
+    });
+}
+//# sourceMappingURL=in-job-context.decorator.js.map

package/dist/decorators/in-job-context.decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"in-job-context.decorator.js","sourceRoot":"","sources":["../../src/decorators/in-job-context.decorator.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE,OAAO,EAEL,eAAe,GAChB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAClE,OAAO,EAAE,kBAAkB,EAAE,MAAM,4BAA4B,CAAC;AAYhE,SAAS,QAAQ,CAAC,KAAc,EAAE,QAA2B;IAC3D,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,KAAK,IAAI;YAAE,OAAO,SAAS,CAAC;QACtE,OAAO,GAAI,OAAmC,CAAC,OAAO,CAAC,CAAC;IAC1D,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,UAAU,YAAY,CAC1B,OAAO,GAAwB,EAAE;IAEjC,MAAM,QAAQ,GAAG,CAAC,OAAO,CAAC,IAAI,IAAI,iBAAiB,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IAEhE,OAAO,eAAe,CAAC,CAAC,QAAQ,EAAE,EAAE;QAClC,OAAO,KAAK,WAA0B,GAAG,IAAe;YACtD,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,kBAAkB,EAAE,CAAC;YAC7D,MAAM,OAAO,GAAG,eAAe,CAC7B,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,QAAQ,CAAC,EAC3B,OAAO,EACP,OAAO,CAAC,aAAa,CAAC,OAAO,CAC9B,CAAC;YACF,OAAO,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,EAAE,CACjD,OAAO,CAAC,aAAa,CAAC,GAAG,CAAC,OAAO,CAAC,aAAa,EAAE,GAAG,EAAE,CACpD,SAAS,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,EAAE,KAAK,IAAI,EAAE,CAC9C,QAAQ,CAAC,KAAK,CAAC,IAAI,EAAE,IAAI,CAAC,CAC3B,CACF,CACF,CAAC;QACJ,CAAC,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/errors/invalid-job-context.error.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Raised when a job payload's context is malformed, names an unconfigured
+ * tenant, or carries fields a principal reference must not have, such as
+ * grants. A payload is data written by whoever can write to the queue.
+ *
+ * @example
+ * ```ts
+ * throw new InvalidJobContextError('tenantId is not a configured tenant');
+ * ```
+ */
+export declare class InvalidJobContextError extends Error {
+    readonly reason: string;
+    constructor(reason: string);
+}
+//# sourceMappingURL=invalid-job-context.error.d.ts.map

package/dist/errors/invalid-job-context.error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invalid-job-context.error.d.ts","sourceRoot":"","sources":["../../src/errors/invalid-job-context.error.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM;IAAnC,YAAqB,MAAM,EAAE,MAAM,EAGlC;CACF"}

package/dist/errors/invalid-job-context.error.js

@@ -0,0 +1,20 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+/**
+ * Raised when a job payload's context is malformed, names an unconfigured
+ * tenant, or carries fields a principal reference must not have, such as
+ * grants. A payload is data written by whoever can write to the queue.
+ *
+ * @example
+ * ```ts
+ * throw new InvalidJobContextError('tenantId is not a configured tenant');
+ * ```
+ */
+export class InvalidJobContextError extends Error {
+    reason;
+    constructor(reason) {
+        super(`Invalid job context: ${reason}.`);
+        this.reason = reason;
+        this.name = InvalidJobContextError.name;
+    }
+}
+//# sourceMappingURL=invalid-job-context.error.js.map

package/dist/errors/invalid-job-context.error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"invalid-job-context.error.js","sourceRoot":"","sources":["../../src/errors/invalid-job-context.error.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE;;;;;;;;;GASG;AACH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAC1B,MAAM;IAA3B,YAAqB,MAAc;QACjC,KAAK,CAAC,wBAAwB,MAAM,GAAG,CAAC,CAAC;sBADtB,MAAM;QAEzB,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC,IAAI,CAAC;IAC1C,CAAC;CACF"}

package/dist/errors/missing-job-context.error.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Raised when a job would run, or be enqueued, without part of its execution
+ * context. A job never falls back to a default tenant or an anonymous principal.
+ *
+ * @example
+ * ```ts
+ * throw new MissingJobContextError('principal');
+ * ```
+ */
+export declare class MissingJobContextError extends Error {
+    readonly missing: string;
+    constructor(missing: string);
+}
+//# sourceMappingURL=missing-job-context.error.d.ts.map

package/dist/errors/missing-job-context.error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"missing-job-context.error.d.ts","sourceRoot":"","sources":["../../src/errors/missing-job-context.error.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;IACnC,QAAQ,CAAC,OAAO,EAAE,MAAM;IAApC,YAAqB,OAAO,EAAE,MAAM,EAKnC;CACF"}

package/dist/errors/missing-job-context.error.js

@@ -0,0 +1,19 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+/**
+ * Raised when a job would run, or be enqueued, without part of its execution
+ * context. A job never falls back to a default tenant or an anonymous principal.
+ *
+ * @example
+ * ```ts
+ * throw new MissingJobContextError('principal');
+ * ```
+ */
+export class MissingJobContextError extends Error {
+    missing;
+    constructor(missing) {
+        super(`Missing job context: ${missing}. A job never runs without it and never falls back to a default.`);
+        this.missing = missing;
+        this.name = MissingJobContextError.name;
+    }
+}
+//# sourceMappingURL=missing-job-context.error.js.map

package/dist/errors/missing-job-context.error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"missing-job-context.error.js","sourceRoot":"","sources":["../../src/errors/missing-job-context.error.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE;;;;;;;;GAQG;AACH,MAAM,OAAO,sBAAuB,SAAQ,KAAK;IAC1B,OAAO;IAA5B,YAAqB,OAAe;QAClC,KAAK,CACH,wBAAwB,OAAO,kEAAkE,CAClG,CAAC;uBAHiB,OAAO;QAI1B,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC,IAAI,CAAC;IAC1C,CAAC;CACF"}

package/dist/helpers/method-decorator.d.ts

@@ -0,0 +1,13 @@
+type AnyMethod = (this: unknown, ...args: any[]) => unknown;
+/** A method decorator for the standard and the `experimentalDecorators` mode. */
+export interface DualMethodDecorator {
+    <F extends AnyMethod>(method: F, context: ClassMethodDecoratorContext): F;
+    (target: object, propertyKey: string | symbol, descriptor: PropertyDescriptor): PropertyDescriptor;
+}
+/**
+ * Builds a decorator that replaces a method with `replace(method, name)`, keeping the
+ * method's own name for stack traces.
+ */
+export declare function methodDecorator(replace: (method: AnyMethod, name: string) => AnyMethod): DualMethodDecorator;
+export {};
+//# sourceMappingURL=method-decorator.d.ts.map

package/dist/helpers/method-decorator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"method-decorator.d.ts","sourceRoot":"","sources":["../../src/helpers/method-decorator.ts"],"names":[],"mappings":"AAGA,KAAK,SAAS,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,OAAO,CAAC;AAE5D,iFAAiF;AACjF,MAAM,WAAW,mBAAmB;IAClC,CAAC,CAAC,SAAS,SAAS,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,EAAE,2BAA2B,GAAG,CAAC,CAAC;IAC1E,CACE,MAAM,EAAE,MAAM,EACd,WAAW,EAAE,MAAM,GAAG,MAAM,EAC5B,UAAU,EAAE,kBAAkB,GAC7B,kBAAkB,CAAC;CACvB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,KAAK,SAAS,GACtD,mBAAmB,CAiBrB"}

package/dist/helpers/method-decorator.js

@@ -0,0 +1,24 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+/**
+ * Builds a decorator that replaces a method with `replace(method, name)`, keeping the
+ * method's own name for stack traces.
+ */
+export function methodDecorator(replace) {
+    const replaced = (method, name) => {
+        const replacement = replace(method, name);
+        Object.defineProperty(replacement, 'name', {
+            value: method.name,
+            configurable: true,
+        });
+        return replacement;
+    };
+    return ((target, key, descriptor) => {
+        if (typeof key === 'object' && key !== null && 'name' in key) {
+            return replaced(target, String(key.name));
+        }
+        const property = descriptor;
+        property.value = replaced(property.value, String(key));
+        return property;
+    });
+}
+//# sourceMappingURL=method-decorator.js.map

package/dist/helpers/method-decorator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"method-decorator.js","sourceRoot":"","sources":["../../src/helpers/method-decorator.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAetE;;;GAGG;AACH,MAAM,UAAU,eAAe,CAC7B,OAAuD;IAEvD,MAAM,QAAQ,GAAG,CAAC,MAAiB,EAAE,IAAY,EAAE,EAAE;QACnD,MAAM,WAAW,GAAG,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QAC1C,MAAM,CAAC,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE;YACzC,KAAK,EAAE,MAAM,CAAC,IAAI;YAClB,YAAY,EAAE,IAAI;SACnB,CAAC,CAAC;QACH,OAAO,WAAW,CAAC;IACrB,CAAC,CAAC;IACF,OAAO,CAAC,CAAC,MAAe,EAAE,GAAY,EAAE,UAA+B,EAAE,EAAE;QACzE,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,KAAK,IAAI,IAAI,MAAM,IAAI,GAAG,EAAE,CAAC;YAC7D,OAAO,QAAQ,CAAC,MAAmB,EAAE,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;QACzD,CAAC;QACD,MAAM,QAAQ,GAAG,UAAgC,CAAC;QAClD,QAAQ,CAAC,KAAK,GAAG,QAAQ,CAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;QACvD,OAAO,QAAQ,CAAC;IAClB,CAAC,CAAwB,CAAC;AAC5B,CAAC"}

package/dist/helpers/parse-job-context.d.ts

@@ -0,0 +1,20 @@
+import type { JobContext } from '../interfaces/job-context.interface.js';
+/**
+ * Validates a job payload's context before anything runs with it. Every field
+ * is checked, unknown fields are refused, the tenant must be configured, and
+ * the correlation id must be one `acceptsCorrelationId` accepts.
+ *
+ * @param value - The payload's `jobContext` value, as read from the queue.
+ * @param tenants - The configured tenants.
+ * @param acceptsCorrelationId - The correlation source's `accepts`.
+ * @returns A context holding only the validated fields.
+ * @throws {MissingJobContextError} When `value` is `undefined`.
+ * @throws {InvalidJobContextError} For any other value that is not a valid context.
+ *
+ * @example
+ * ```ts
+ * const context = parseJobContext(job.data.jobContext, ['tenant_a'], sources.correlationId.accepts);
+ * ```
+ */
+export declare function parseJobContext(value: unknown, tenants: readonly string[], acceptsCorrelationId: (id: string) => boolean): JobContext;
+//# sourceMappingURL=parse-job-context.d.ts.map

package/dist/helpers/parse-job-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-job-context.d.ts","sourceRoot":"","sources":["../../src/helpers/parse-job-context.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wCAAwC,CAAC;AAyBzE;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,OAAO,EACd,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,oBAAoB,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,GAC5C,UAAU,CAmCZ"}

package/dist/helpers/parse-job-context.js

@@ -0,0 +1,68 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+import { InvalidJobContextError } from '../errors/invalid-job-context.error.js';
+import { MissingJobContextError } from '../errors/missing-job-context.error.js';
+import { toReference } from './principal-reference.js';
+const CONTEXT_FIELDS = new Set(['tenantId', 'correlationId', 'principal']);
+const PRINCIPAL_FIELDS = new Set(['id', 'type', 'sessionId']);
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function isText(value) {
+    return typeof value === 'string' && value.trim() !== '';
+}
+function assertFields(value, allowed, name) {
+    const extra = Object.keys(value).find((key) => !allowed.has(key));
+    if (extra !== undefined) {
+        throw new InvalidJobContextError(`${name} carries the field "${extra}"`);
+    }
+}
+/**
+ * Validates a job payload's context before anything runs with it. Every field
+ * is checked, unknown fields are refused, the tenant must be configured, and
+ * the correlation id must be one `acceptsCorrelationId` accepts.
+ *
+ * @param value - The payload's `jobContext` value, as read from the queue.
+ * @param tenants - The configured tenants.
+ * @param acceptsCorrelationId - The correlation source's `accepts`.
+ * @returns A context holding only the validated fields.
+ * @throws {MissingJobContextError} When `value` is `undefined`.
+ * @throws {InvalidJobContextError} For any other value that is not a valid context.
+ *
+ * @example
+ * ```ts
+ * const context = parseJobContext(job.data.jobContext, ['tenant_a'], sources.correlationId.accepts);
+ * ```
+ */
+export function parseJobContext(value, tenants, acceptsCorrelationId) {
+    if (value === undefined) {
+        throw new MissingJobContextError('the payload has no jobContext');
+    }
+    if (!isRecord(value)) {
+        throw new InvalidJobContextError('jobContext is not an object');
+    }
+    assertFields(value, CONTEXT_FIELDS, 'jobContext');
+    const { tenantId, correlationId, principal } = value;
+    if (typeof tenantId !== 'string' || !tenants.includes(tenantId)) {
+        throw new InvalidJobContextError('tenantId is not a configured tenant');
+    }
+    if (typeof correlationId !== 'string' ||
+        !acceptsCorrelationId(correlationId)) {
+        throw new InvalidJobContextError('correlationId is malformed');
+    }
+    if (!isRecord(principal)) {
+        throw new InvalidJobContextError('principal is not an object');
+    }
+    assertFields(principal, PRINCIPAL_FIELDS, 'principal');
+    const { id, type, sessionId } = principal;
+    if (!isText(id) ||
+        !isText(type) ||
+        (sessionId !== undefined && !isText(sessionId))) {
+        throw new InvalidJobContextError('principal is malformed');
+    }
+    return {
+        tenantId,
+        correlationId,
+        principal: toReference({ id, type, sessionId }),
+    };
+}
+//# sourceMappingURL=parse-job-context.js.map

package/dist/helpers/parse-job-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-job-context.js","sourceRoot":"","sources":["../../src/helpers/parse-job-context.ts"],"names":[],"mappings":"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"}

package/dist/helpers/principal-reference.d.ts

@@ -0,0 +1,12 @@
+import type { PrincipalReference } from '../interfaces/principal-reference.interface.js';
+/**
+ * Copies only the identity fields of `principal`, so grants or session data an
+ * application object also holds never reach a payload or a restore call.
+ *
+ * @example
+ * ```ts
+ * toReference({ id: 'u-1', type: 'user', sid: 's-1', grants: [] }); // { id: 'u-1', type: 'user' }
+ * ```
+ */
+export declare function toReference(principal: PrincipalReference): PrincipalReference;
+//# sourceMappingURL=principal-reference.d.ts.map

package/dist/helpers/principal-reference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"principal-reference.d.ts","sourceRoot":"","sources":["../../src/helpers/principal-reference.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gDAAgD,CAAC;AAEzF;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,SAAS,EAAE,kBAAkB,GAAG,kBAAkB,CAG7E"}

package/dist/helpers/principal-reference.js

@@ -0,0 +1,15 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+/**
+ * Copies only the identity fields of `principal`, so grants or session data an
+ * application object also holds never reach a payload or a restore call.
+ *
+ * @example
+ * ```ts
+ * toReference({ id: 'u-1', type: 'user', sid: 's-1', grants: [] }); // { id: 'u-1', type: 'user' }
+ * ```
+ */
+export function toReference(principal) {
+    const { id, type, sessionId } = principal;
+    return sessionId === undefined ? { id, type } : { id, type, sessionId };
+}
+//# sourceMappingURL=principal-reference.js.map

package/dist/helpers/principal-reference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"principal-reference.js","sourceRoot":"","sources":["../../src/helpers/principal-reference.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAItE;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAC,SAA6B;IACvD,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,GAAG,SAAS,CAAC;IAC1C,OAAO,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;AAC1E,CAAC"}

package/dist/helpers/registration.d.ts

@@ -0,0 +1,39 @@
+import type { JobContextSources } from '../interfaces/context-source.interface.js';
+import type { IJobPrincipal } from '../interfaces/job-principal.interface.js';
+/** What `registerJobContext` registers for the decorators. */
+export interface Registration {
+    readonly principal: IJobPrincipal;
+    readonly tenants: readonly string[];
+    readonly sources: JobContextSources;
+}
+/**
+ * Makes `registration` the one the decorators and `withJobContext` use.
+ *
+ * @example
+ * ```ts
+ * register({ principal, tenants: ['tenant_a'], sources });
+ * ```
+ */
+export declare function register(registration: Registration): void;
+/**
+ * Removes `registration` if it is still the active one, so closing one
+ * application does not remove another's.
+ *
+ * @example
+ * ```ts
+ * unregister(registration);
+ * ```
+ */
+export declare function unregister(registration: Registration): void;
+/**
+ * The active registration.
+ *
+ * @throws {MissingJobContextError} When no job context is registered.
+ *
+ * @example
+ * ```ts
+ * const { principal, tenants, sources } = activeRegistration();
+ * ```
+ */
+export declare function activeRegistration(): Registration;
+//# sourceMappingURL=registration.d.ts.map

package/dist/helpers/registration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registration.d.ts","sourceRoot":"","sources":["../../src/helpers/registration.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,2CAA2C,CAAC;AACnF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,0CAA0C,CAAC;AAE9E,8DAA8D;AAC9D,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,SAAS,EAAE,aAAa,CAAC;IAClC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;CACrC;AAID;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,YAAY,EAAE,YAAY,GAAG,IAAI,CAEzD;AAED;;;;;;;;GAQG;AACH,wBAAgB,UAAU,CAAC,YAAY,EAAE,YAAY,GAAG,IAAI,CAE3D;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,IAAI,YAAY,CAOjD"}

package/dist/helpers/registration.js

@@ -0,0 +1,44 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+import { MissingJobContextError } from '../errors/missing-job-context.error.js';
+let active;
+/**
+ * Makes `registration` the one the decorators and `withJobContext` use.
+ *
+ * @example
+ * ```ts
+ * register({ principal, tenants: ['tenant_a'], sources });
+ * ```
+ */
+export function register(registration) {
+    active = registration;
+}
+/**
+ * Removes `registration` if it is still the active one, so closing one
+ * application does not remove another's.
+ *
+ * @example
+ * ```ts
+ * unregister(registration);
+ * ```
+ */
+export function unregister(registration) {
+    if (active === registration)
+        active = undefined;
+}
+/**
+ * The active registration.
+ *
+ * @throws {MissingJobContextError} When no job context is registered.
+ *
+ * @example
+ * ```ts
+ * const { principal, tenants, sources } = activeRegistration();
+ * ```
+ */
+export function activeRegistration() {
+    if (active === undefined) {
+        throw new MissingJobContextError('a job context registered with registerJobContext');
+    }
+    return active;
+}
+//# sourceMappingURL=registration.js.map

package/dist/helpers/registration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registration.js","sourceRoot":"","sources":["../../src/helpers/registration.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE,OAAO,EAAE,sBAAsB,EAAE,MAAM,wCAAwC,CAAC;AAWhF,IAAI,MAAgC,CAAC;AAErC;;;;;;;GAOG;AACH,MAAM,UAAU,QAAQ,CAAC,YAA0B;IACjD,MAAM,GAAG,YAAY,CAAC;AACxB,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU,CAAC,YAA0B;IACnD,IAAI,MAAM,KAAK,YAAY;QAAE,MAAM,GAAG,SAAS,CAAC;AAClD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB;IAChC,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QACzB,MAAM,IAAI,sBAAsB,CAC9B,kDAAkD,CACnD,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/helpers/with-job-context.d.ts

@@ -0,0 +1,21 @@
+import type { WithJobContext } from '../interfaces/job-context.interface.js';
+/**
+ * Stamps the current execution context onto a job payload: the tenant and
+ * correlation id of the registered sources (a new one from the correlation
+ * source's `create()` when none is active), and the principal the registered `IJobPrincipal`
+ * captures, reduced to its identity. The processor restores it with
+ * `@InJobContext`.
+ *
+ * @param data - The payload. Must be a plain object; a shallow copy is returned.
+ * @returns A copy of `data` with `jobContext` added.
+ * @throws {TypeError} When `data` is not a plain object.
+ * @throws {MissingJobContextError} Without a `registerJobContext` registration, a
+ *   current tenant, or a current principal.
+ *
+ * @example
+ * ```ts
+ * await queue.add('send', withJobContext({ userId, email }));
+ * ```
+ */
+export declare function withJobContext<T extends Record<string, unknown>>(data: T): WithJobContext<T>;
+//# sourceMappingURL=with-job-context.d.ts.map

package/dist/helpers/with-job-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-job-context.d.ts","sourceRoot":"","sources":["../../src/helpers/with-job-context.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AAI7E;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,cAAc,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9D,IAAI,EAAE,CAAC,GACN,cAAc,CAAC,CAAC,CAAC,CAwBnB"}