@nestjs-pipeline/job-context 0.4.0 → 0.4.2

package/README.md

@@ -8,12 +8,7 @@ the correlation id and the principal. A job then makes the decisions the request
 have made. System-started work, such as a cron job, declares its context explicitly
 instead. Nothing falls back to a default tenant or an anonymous principal.
 
-It depends on no other pipeline package. It reads and restores the tenant and the
-correlation id through the sources it is given, usually `tenantSource` of
-[`@nestjs-pipeline/tenant`](https://github.com/aristoteliss/nestjs-pipeline/tree/master/packages/pipeline-tenant#readme)
-and `correlationSource` of
-[`@nestjs-pipeline/correlation`](https://github.com/aristoteliss/nestjs-pipeline/tree/master/packages/pipeline-correlation#readme),
-so pipelines a job dispatches get the same tenant and correlation id.
+**Documentation:** [guide](https://aristoteliss.github.io/nestjs-pipeline/packages/nestjs-pipeline/job-context/) · [API reference](https://aristoteliss.github.io/nestjs-pipeline/api/nestjs-pipeline/job-context/) · [all packages](https://aristoteliss.github.io/nestjs-pipeline/)
 
 ## Installation
 
@@ -23,194 +18,7 @@ pnpm add @nestjs-pipeline/job-context @nestjs/common
 
 Requires Node.js 22.12 or later and `@nestjs/common` `^12.1.0`.
 
-Published as an ES module; a CommonJS application loads it with `require()`. Coming from
-0.3.x, see [Upgrading from 0.3.x](https://github.com/aristoteliss/nestjs-pipeline#upgrading-from-03x).
-
-## Setup
-
-Implement `IJobPrincipal` over the application's authentication state, and register it
-with the tenants jobs may run in and the tenant and correlation id sources:
-
-`Capability`, `SessionRepository`, `SessionsModule`, `currentPrincipal`,
-`runAsPrincipal` and `SessionRevokedError` stand for the application's own authentication
-code.
-
-```typescript
-import { Injectable, Module } from '@nestjs/common';
-import { correlationSource } from '@nestjs-pipeline/correlation';
-import {
-  type IJobPrincipal,
-  JobContextModule,
-  type PrincipalReference,
-} from '@nestjs-pipeline/job-context';
-import { tenantSource } from '@nestjs-pipeline/tenant';
-
-@Injectable()
-export class SessionJobPrincipal implements IJobPrincipal<Capability> {
-  constructor(private readonly sessions: SessionRepository) {}
-
-  capture(): PrincipalReference | undefined {
-    const principal = currentPrincipal();
-    return principal && { id: principal.id, type: principal.type, sessionId: principal.sid };
-  }
-
-  async restore<T>(
-    principal: PrincipalReference,
-    work: () => Promise<T>,
-    grants?: readonly Capability[],
-  ): Promise<T> {
-    if (grants) return runAsPrincipal({ ...principal, grants }, work);
-    const session = await this.sessions.findActive(principal.sessionId, principal.id);
-    if (!session) throw new SessionRevokedError();
-    return runAsPrincipal(principal, work);
-  }
-}
-
-@Module({
-  imports: [
-    JobContextModule.forRoot({
-      principal: SessionJobPrincipal,
-      tenants: ['tenant_a', 'tenant_b'],
-      sources: { tenantId: tenantSource, correlationId: correlationSource },
-      imports: [SessionsModule],
-    }),
-  ],
-})
-export class JobsModule {}
-```
-
-`tenants` is a list, or a function that returns one. A function is called once, when the
-application builds the module's providers, so the list can come from configuration read
-at startup (`tenants: () => config().tenants`) instead of when the module file is
-imported. An empty list throws: a list in `forRoot`, a function when the application
-starts.
-
-`capture` reads the current principal when a job is enqueued; only its `id`, `type` and
-`sessionId` are kept. `restore` runs when the job does, inside the job's tenant and
-correlation id: it must re-check the principal against current state, bind it the way a
-request would, and throw to refuse the job.
-
-## Usage
-
-Stamp the payload when enqueuing, from inside the request or handler, so the tenant,
-correlation id and principal are current:
-
-```typescript
-import { InjectQueue } from '@nestjs/bullmq';
-import { EventsHandler, type IEventHandler } from '@nestjs/cqrs';
-import { withJobContext, type WithJobContext } from '@nestjs-pipeline/job-context';
-import type { Queue } from 'bullmq';
-
-type WelcomeEmail = { userId: string; email: string };
-
-@EventsHandler(UserRegisteredEvent)
-export class EnqueueWelcomeEmail implements IEventHandler<UserRegisteredEvent> {
-  constructor(
-    @InjectQueue(WELCOME_EMAIL_QUEUE)
-    private readonly queue: Queue<WithJobContext<WelcomeEmail>>,
-  ) {}
-
-  async handle({ userId, email }: UserRegisteredEvent) {
-    await this.queue.add('send', withJobContext({ userId, email }));
-  }
-}
-```
-
-Restore it in the processor. Place the decorator under the transport decorator:
-
-```typescript
-import { Processor, WorkerHost } from '@nestjs/bullmq';
-import { CommandBus } from '@nestjs/cqrs';
-import { InJobContext, type WithJobContext } from '@nestjs-pipeline/job-context';
-import type { Job } from 'bullmq';
-
-@Processor(WELCOME_EMAIL_QUEUE)
-export class SendWelcomeEmailProcessor extends WorkerHost {
-  constructor(private readonly commandBus: CommandBus) {
-    super();
-  }
-
-  @InJobContext()
-  async process(job: Job<WithJobContext<WelcomeEmail>>) {
-    await this.commandBus.execute(new SendWelcomeEmailCommand(job.data));
-  }
-}
-```
-
-`@InJobContext()` reads `data.jobContext` from the first argument (a BullMQ `Job`); pass
-`{ path: 'jobContext' }` for a transport that hands the payload itself.
-
-```typescript
-@EventPattern('user.registered')
-@InJobContext({ path: 'jobContext' })
-async onRegistered(@Payload() data: WithJobContext<WelcomeEmail>) {
-  await this.commandBus.execute(new SendWelcomeEmailCommand(data));
-}
-```
-
-A refused job throws `MissingJobContextError` or `InvalidJobContextError` before the method
-runs; let the queue mark it failed rather than retrying it, since the payload will not change.
-
-Declare system-started work:
-
-```typescript
-import { AsSystem } from '@nestjs-pipeline/job-context';
-import { Cron } from '@nestjs/schedule';
-
-@Cron('0 3 * * *')
-@AsSystem({
-  principal: { id: 'session-cleanup', type: 'service' },
-  grants: [{ action: 'delete', subject: 'Auth' }],
-})
-async purgeSessions() {
-  await this.commandBus.execute(new PurgeExpiredSessionsCommand());
-}
-```
-
-## Behavior
-
-- **`withJobContext(data)`** returns a copy of `data` with `jobContext`: the tenant and
-  the correlation id of the configured sources (a new one from the correlation source's
-  `create()` when none is active), and the captured principal. It throws `MissingJobContextError` without a
-  running `JobContextModule`, a tenant, or a principal, and `TypeError` for a payload that
-  is not a plain object.
-- **`@InJobContext()`** validates the payload's context before the method runs. It refuses
-  a missing context (`MissingJobContextError`), and a malformed one, an unconfigured
-  tenant, a correlation id the correlation source's `accepts` refuses
-  (`correlationSource` accepts at most 128 characters of `A-Z a-z 0-9 . _ ~ : / + = @ -`), or a
-  principal carrying any field beyond `id`, `type` and `sessionId`, such as grants
-  (`InvalidJobContextError`). It then runs the method inside the tenant, the correlation
-  id, and `restore(principal, work)`. The method becomes async.
-- **`@AsSystem({ principal, grants })`** runs the method once per configured tenant, one
-  after another, each with a new correlation id from `create()` and `restore(principal, work, grants)`. A
-  failing tenant does not stop the others; the method then rejects with an
-  `AggregateError` of the failures. Return values are discarded.
-- **`JobContextModule.forRoot`** registers the principal port, tenants and sources when the module
-  is instantiated and removes them at application shutdown. The decorators wrap methods
-  outside dependency injection, so they use the registration of the running application;
-  without one they fail closed. Register it once per application.
-
-## Security
-
-A payload is data: anyone who can write to the queue can write it. The package therefore
-carries an identity reference only, never grants, and `restore` decides what that
-identity may do now. Re-check a user's session and account in `restore`, so a revoked
-session or a deleted user refuses the job. Grants come only from `@AsSystem`, in code.
-The tenant must be one of the configured tenants.
-
-## API
-
-| Export | Kind | Description |
-| --- | --- | --- |
-| `withJobContext(data)` | function | Copies `data` and adds the current `jobContext` |
-| `InJobContext(options?)` | decorator | Runs a job method in its payload's context; `path` defaults to `'data.jobContext'` |
-| `AsSystem(options)` | decorator | Runs system work once per tenant as the declared principal and grants |
-| `JobContextModule.forRoot(options)` | module | Registers `principal` (a class), `tenants` (a list, or a function called at startup), `sources` and optional `imports` |
-| `ContextSource`, `CorrelationSource`, `JobContextSources` | type | `{ current, run }`; the correlation source adds `create()` and `accepts(id)`; and the `{ tenantId, correlationId }` pair `sources` takes |
-| `IJobPrincipal<TGrant>` | interface | Application port: `capture()` and `restore(principal, work, grants?)` |
-| `PrincipalReference` | type | `{ id, type, sessionId? }` |
-| `JobContext`, `WithJobContext<T>` | type | The carried context, and a payload with it |
-| `MissingJobContextError`, `InvalidJobContextError` | error | Framework-neutral; map them in the consumer if needed |
+Published as an ES module; a CommonJS application loads it with `require()`. Coming from 0.3.x, see [Upgrading from 0.3.x](https://aristoteliss.github.io/nestjs-pipeline/upgrading/from-0-3/).
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestjs-pipeline/job-context",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Carries the tenant, correlation id and principal of a request into the queue jobs it enqueues, and gives system-started work an explicit context",
   "author": "Aristotelis",
   "license": "SEE LICENSE IN LICENSE",
@@ -13,7 +13,7 @@
     "url": "git+https://github.com/aristoteliss/nestjs-pipeline.git",
     "directory": "packages/pipeline-job-context"
   },
-  "homepage": "https://github.com/aristoteliss/nestjs-pipeline/tree/master/packages/pipeline-job-context#readme",
+  "homepage": "https://aristoteliss.github.io/nestjs-pipeline/packages/nestjs-pipeline/job-context/",
   "bugs": {
     "url": "https://github.com/aristoteliss/nestjs-pipeline/issues"
   },