@nestarc/tenancy

Classes

BullTenantPropagator

Defined in: src/propagation/bull-tenant-propagator.ts:35

Bull/BullMQ tenant propagator.

Injects the current tenant ID into job data on the producer side, and extracts it on the consumer side. Uses a configurable key (default: __tenantId) to avoid collisions with application data.

No runtime dependency on bullmq — uses plain object types.

Example

typescript

const propagator = new BullTenantPropagator(new TenancyContext());

// Producer: inject tenant into job data
await queue.add('process', propagator.inject({ orderId: '123' }));

// Consumer: extract tenant from job data
const tenantId = propagator.extract(job.data);

Implements

TenantContextCarrier<Record<string, unknown>>

Constructors

Constructor

new BullTenantPropagator(context, options?): BullTenantPropagator;

Defined in: src/propagation/bull-tenant-propagator.ts:42

Parameters

Parameter	Type
`context`	`TenancyContext`
`options?`	`BullPropagationOptions`

Returns

BullTenantPropagator

Methods

extract()

extract(jobData): string | null;

Defined in: src/propagation/bull-tenant-propagator.ts:69

Extracts the tenant ID from an incoming carrier. Returns the tenant ID string, or null if not present.

Parameters

Parameter	Type
`jobData`	`Record`<`string`, `unknown`>

Returns

string | null

Implementation of

TenantContextCarrier.extract

inject()

inject(jobData): Record<string, unknown>;

Defined in: src/propagation/bull-tenant-propagator.ts:51

Attaches the current tenant ID to the carrier for outbound propagation. Returns the carrier with tenant context included. If no tenant context is available, returns the carrier unchanged.

Parameters

Parameter	Type
`jobData`	`Record`<`string`, `unknown`>

Returns

Record<string, unknown>

Implementation of

TenantContextCarrier.inject

CompositeTenantExtractor

Defined in: src/extractors/composite.extractor.ts:4

Contract for extracting a tenant ID from an inbound HTTP request.

Return the tenant ID string when present, or null when the request does not carry tenant information. A missing tenant is not an error condition; TenantMiddleware will call onTenantNotFound and let the application decide whether to continue, respond, or throw.

Implementations may return synchronously or return a Promise for async lookups. Throw only for malformed input or policy failures that should reject the request immediately.

Implements

TenantExtractor

Constructors

Constructor

new CompositeTenantExtractor(extractors): CompositeTenantExtractor;

Defined in: src/extractors/composite.extractor.ts:7

Parameters

Parameter	Type
`extractors`	`TenantExtractor`[]

Returns

CompositeTenantExtractor

Methods

extract()

extract(request): string | Promise<string | null> | null;

Defined in: src/extractors/composite.extractor.ts:11

Parameters

Parameter	Type
`request`	`TenancyRequest`

Returns

string | Promise<string | null> | null

Implementation of

TenantExtractor.extract

GrpcTenantPropagator

Defined in: src/propagation/grpc-tenant-propagator.ts:48

gRPC tenant propagator.

Injects tenant ID into gRPC call metadata on the client side, and extracts it on the server side.

Uses lowercase metadata keys per gRPC convention (keys are case-insensitive but lowercase is standard).

No runtime dependency on @grpc/grpc-js — uses structural types.

Example

typescript

const propagator = new GrpcTenantPropagator(new TenancyContext());

// Client: inject tenant into outgoing metadata
const metadata = new Metadata();
propagator.inject(metadata);

// Server: extract tenant from incoming metadata
const tenantId = propagator.extract(call.metadata);

Implements

TenantContextCarrier<GrpcMetadataLike>

Constructors

Constructor

new GrpcTenantPropagator(context, options?): GrpcTenantPropagator;

Defined in: src/propagation/grpc-tenant-propagator.ts:55

Parameters

Parameter	Type
`context`	`TenancyContext`
`options?`	`GrpcPropagationOptions`

Returns

GrpcTenantPropagator

Methods

extract()

extract(metadata): string | null;

Defined in: src/propagation/grpc-tenant-propagator.ts:74

Extracts the tenant ID from an incoming carrier. Returns the tenant ID string, or null if not present.

Parameters

Parameter	Type
`metadata`	`GrpcMetadataLike`

Returns

string | null

Implementation of

TenantContextCarrier.extract

inject()

inject(metadata): GrpcMetadataLike;

Defined in: src/propagation/grpc-tenant-propagator.ts:64

Attaches the current tenant ID to the carrier for outbound propagation. Returns the carrier with tenant context included. If no tenant context is available, returns the carrier unchanged.

Parameters

Parameter	Type
`metadata`	`GrpcMetadataLike`

Contract for extracting a tenant ID from an inbound HTTP request.

Implementations may return synchronously or return a Promise for async lookups. Throw only for malformed input or policy failures that should reject the request immediately.

Implements

TenantExtractor

Constructors

Constructor

new HeaderTenantExtractor(headerName): HeaderTenantExtractor;

Defined in: src/extractors/header.extractor.ts:7

Parameters

Parameter	Type
`headerName`	`string`

Returns

HeaderTenantExtractor

Methods

extract()

extract(request): string | null;

Defined in: src/extractors/header.extractor.ts:11

Parameters

Parameter	Type
`request`	`TenancyRequest`

Returns

string | null

Implementation of

TenantExtractor.extract

HttpTenantPropagator

Defined in: src/propagation/http-tenant-propagator.ts:23

HTTP-specific tenant propagator.

Reads the current tenant from TenancyContext and returns it as an HTTP header. Returns an empty object when no tenant context is available.

Example

typescript

const propagator = new HttpTenantPropagator(tenancyContext);
const headers = propagator.getHeaders();
// { 'X-Tenant-Id': 'tenant-abc' }

Implements

TenantPropagator

Constructors

Constructor

new HttpTenantPropagator(context, options?): HttpTenantPropagator;

Defined in: src/propagation/http-tenant-propagator.ts:26

Parameters

Parameter	Type
`context`	`TenancyContext`
`options?`	`HttpPropagationOptions`

Returns

HttpTenantPropagator

Methods

getHeaders()

getHeaders(): Record<string, string>;

Defined in: src/propagation/http-tenant-propagator.ts:33

Returns headers to propagate tenant context. Returns an empty object if no tenant context is available.

Returns

Record<string, string>

Implementation of

TenantPropagator.getHeaders

JwtClaimTenantExtractor

Defined in: src/extractors/jwt-claim.extractor.ts:37

Extracts the tenant ID from a JWT claim in the Authorization header.

IMPORTANT: This extractor does NOT verify the JWT signature. It decodes the payload (Base64URL) without cryptographic validation. You MUST ensure that JWT authentication (e.g., @nestjs/passport AuthGuard, or an upstream auth middleware) has already validated the token before this extractor runs. Using this extractor without prior JWT verification allows attackers to forge tenant IDs via crafted tokens.

Implements

TenantExtractor

Constructors

Constructor

new JwtClaimTenantExtractor(options): JwtClaimTenantExtractor;

Defined in: src/extractors/jwt-claim.extractor.ts:41

Parameters

Parameter	Type
`options`	`JwtClaimExtractorOptions`

Returns

JwtClaimTenantExtractor

Methods

extract()

extract(request): string | null;

Defined in: src/extractors/jwt-claim.extractor.ts:46

Parameters

Parameter	Type
`request`	`TenancyRequest`

Returns

string | null

Implementation of

TenantExtractor.extract

KafkaTenantPropagator

Defined in: src/propagation/kafka-tenant-propagator.ts:45

Kafka tenant propagator.

Implements both TenantContextCarrier<KafkaMessageLike> (for inject/extract) and TenantPropagator (for getHeaders compatibility).

Handles Kafka headers that may be string or Buffer on extraction. No runtime dependency on kafkajs — uses structural types.

Example

typescript

const propagator = new KafkaTenantPropagator(new TenancyContext());

// Producer: inject tenant into message
await producer.send({
  topic: 'orders',
  messages: [propagator.inject({ value: JSON.stringify(payload) })],
});

// Consumer: extract tenant from message
const tenantId = propagator.extract(message);

Implements

TenantContextCarrier<KafkaMessageLike>
TenantPropagator

Constructors

Constructor

new KafkaTenantPropagator(context, options?): KafkaTenantPropagator;

Defined in: src/propagation/kafka-tenant-propagator.ts:52

Parameters

Parameter	Type
`context`	`TenancyContext`
`options?`	`KafkaPropagationOptions`

Returns

KafkaTenantPropagator

Methods

extract()

extract(message): string | null;

Defined in: src/propagation/kafka-tenant-propagator.ts:73

Extracts the tenant ID from an incoming carrier. Returns the tenant ID string, or null if not present.

Parameters

Parameter	Type
`message`	`KafkaMessageLike`

Returns

string | null

Implementation of

TenantContextCarrier.extract

getHeaders()

getHeaders(): Record<string, string>;

Defined in: src/propagation/kafka-tenant-propagator.ts:84

Returns headers to propagate tenant context. Returns an empty object if no tenant context is available.

Returns

Record<string, string>

Implementation of

TenantPropagator.getHeaders

inject()

inject(message): KafkaMessageLike;

Defined in: src/propagation/kafka-tenant-propagator.ts:61

Attaches the current tenant ID to the carrier for outbound propagation. Returns the carrier with tenant context included. If no tenant context is available, returns the carrier unchanged.

Parameters

Parameter	Type
`message`	`KafkaMessageLike`

Returns

KafkaMessageLike

Implementation of

TenantContextCarrier.inject

PathTenantExtractor

Defined in: src/extractors/path.extractor.ts:13

Contract for extracting a tenant ID from an inbound HTTP request.

Implementations may return synchronously or return a Promise for async lookups. Throw only for malformed input or policy failures that should reject the request immediately.

Implements

TenantExtractor

Constructors

Constructor

new PathTenantExtractor(options): PathTenantExtractor;

Defined in: src/extractors/path.extractor.ts:17

Parameters

Parameter	Type
`options`	`PathExtractorOptions`

Returns

PathTenantExtractor

Methods

extract()

extract(request): string | null;

Defined in: src/extractors/path.extractor.ts:29

Parameters

Parameter	Type
`request`	`TenancyRequest`

Returns

string | null

Implementation of

TenantExtractor.extract

SubdomainTenantExtractor

Defined in: src/extractors/subdomain.extractor.ts:30

Contract for extracting a tenant ID from an inbound HTTP request.

Implementations may return synchronously or return a Promise for async lookups. Throw only for malformed input or policy failures that should reject the request immediately.

Implements

TenantExtractor

Constructors

Constructor

new SubdomainTenantExtractor(options?): SubdomainTenantExtractor;

Defined in: src/extractors/subdomain.extractor.ts:34

Parameters

Parameter	Type
`options?`	`SubdomainExtractorOptions`

Returns

SubdomainTenantExtractor

Methods

extract()

extract(request): string | null;

Defined in: src/extractors/subdomain.extractor.ts:41

Parameters

Parameter	Type
`request`	`TenancyRequest`

Returns

string | null

Implementation of

TenantExtractor.extract

TenancyContext

Defined in: src/services/tenancy-context.ts:23

Constructors

Constructor

new TenancyContext(): TenancyContext;

Returns

TenancyContext

Methods

getCurrentTenantId()

static getCurrentTenantId(): string | null;

Defined in: src/services/tenancy-context.ts:24

Returns

string | null

getTenantId()

getTenantId(): string | null;

Defined in: src/services/tenancy-context.ts:34

Returns

string | null

isBypassed()

isBypassed(): boolean;

Defined in: src/services/tenancy-context.ts:38

Returns

boolean

run()

Call Signature

run<T>(tenantId, callback): Promise<T>;

Defined in: src/services/tenancy-context.ts:28

Type Parameters

Type Parameter
`T`

Parameters

Parameter	Type
`tenantId`	`string`
`callback`	() => `Promise`<`T`>

Returns

Promise<T>

Call Signature

run<T>(tenantId, callback): T;

Defined in: src/services/tenancy-context.ts:29

Type Parameters

Type Parameter
`T`

Parameters

Parameter	Type
`tenantId`	`string`
`callback`	() => `T`

Returns

T

runWithoutTenant()

Call Signature

runWithoutTenant<T>(callback): Promise<T>;

Defined in: src/services/tenancy-context.ts:42

Type Parameters

Type Parameter
`T`

Parameters

Parameter	Type
`callback`	() => `Promise`<`T`>

Returns

Promise<T>

Call Signature

runWithoutTenant<T>(callback): T;

Defined in: src/services/tenancy-context.ts:43

Type Parameters

Type Parameter
`T`

Parameters

Parameter	Type
`callback`	() => `T`

Returns

T

TenancyContextRequiredError

Defined in: src/errors/tenancy-context-required.error.ts:3

Extends

TenantContextMissingError

Constructors

Constructor

new TenancyContextRequiredError(model, operation): TenancyContextRequiredError;

Defined in: src/errors/tenancy-context-required.error.ts:6

Parameters

Parameter	Type
`model`	`string`
`operation`	`string`

Returns

TenancyContextRequiredError

Overrides

TenantContextMissingError.constructor

Properties

message

message: string;

Defined in: ../../../../../../Users/ksy/Documents/GitHub/nestarc.dev/node_modules/typescript/lib/lib.es5.d.ts:1077

Inherited from

TenantContextMissingError.message

model

readonly model: string;

Defined in: src/errors/tenancy-context-required.error.ts:7

name

name: string = 'TenancyContextRequiredError';

Defined in: src/errors/tenancy-context-required.error.ts:4

Overrides

TenantContextMissingError.name

operation

readonly operation: string;

Defined in: src/errors/tenancy-context-required.error.ts:8

stack?

optional stack?: string;

Defined in: ../../../../../../Users/ksy/Documents/GitHub/nestarc.dev/node_modules/typescript/lib/lib.es5.d.ts:1078

Inherited from

TenantContextMissingError.stack

stackTraceLimit

static stackTraceLimit: number;

Defined in: node_modules/@types/node/globals.d.ts:68

The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)).

The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will not capture any frames.

Inherited from

TenantContextMissingError.stackTraceLimit

Methods

captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/@types/node/globals.d.ts:52

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();

Parameters

Parameter	Type
`targetObject`	`object`
`constructorOpt?`	`Function`

Returns

void

Inherited from

TenantContextMissingError.captureStackTrace

prepareStackTrace()

static prepareStackTrace(err, stackTraces): any;

Defined in: node_modules/@types/node/globals.d.ts:56

Parameters

Parameter	Type
`err`	`Error`
`stackTraces`	`CallSite`[]

Returns

any

See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from

TenantContextMissingError.prepareStackTrace

toJSON()

toJSON(): {
  message: string;
  model: string;
  name: string;
  operation: string;
};

Defined in: src/errors/tenancy-context-required.error.ts:17

Returns

{
  message: string;
  model: string;
  name: string;
  operation: string;
}

Name	Type	Defined in
`message`	`string`	src/errors/tenancy-context-required.error.ts:20
`model`	`string`	src/errors/tenancy-context-required.error.ts:21
`name`	`string`	src/errors/tenancy-context-required.error.ts:19
`operation`	`string`	src/errors/tenancy-context-required.error.ts:22

TenancyEventService

Defined in: src/events/tenancy-event.service.ts:14

Optional event emission service that integrates with @nestjs/event-emitter.

If @nestjs/event-emitter is installed and EventEmitterModule.forRoot() is imported, events are emitted via EventEmitter2. If not installed, all emit() calls are silently ignored.

Implements

OnModuleInit

Constructors

Constructor

new TenancyEventService(moduleRef): TenancyEventService;

Defined in: src/events/tenancy-event.service.ts:18

Parameters

Parameter	Type
`moduleRef`	`ModuleRef`

Returns

TenancyEventService

Methods

emit()

emit<K>(event, payload): void;

Defined in: src/events/tenancy-event.service.ts:31

Type Parameters

Type Parameter
`K` extends keyof `TenancyEventMap`

Parameters

Parameter	Type
`event`	`K`
`payload`	`TenancyEventMap`[`K`]

Returns

void

onModuleInit()

onModuleInit(): Promise<void>;

Defined in: src/events/tenancy-event.service.ts:20

Returns

Promise<void>

Implementation of

OnModuleInit.onModuleInit

TenancyModule

Defined in: src/tenancy.module.ts:54

Implements

NestModule

Constructors

Constructor

new TenancyModule(): TenancyModule;

Returns

TenancyModule

Methods

configure()

configure(consumer): void;

Defined in: src/tenancy.module.ts:55

Parameters

Parameter	Type
`consumer`	`MiddlewareConsumer`

Returns

void

Implementation of

NestModule.configure

forRoot()

static forRoot(options): DynamicModule;

Defined in: src/tenancy.module.ts:64

Parameters

Parameter	Type
`options`	`TenancyModuleOptions`

Returns

DynamicModule

forRootAsync()

static forRootAsync(options): DynamicModule;

Defined in: src/tenancy.module.ts:73

Parameters

Parameter	Type
`options`	`TenancyModuleAsyncOptions`

Returns

DynamicModule

TenancyService

Defined in: src/services/tenancy.service.ts:14

Constructors

Constructor

new TenancyService(context, eventService?): TenancyService;

Defined in: src/services/tenancy.service.ts:17

Parameters

Parameter	Type
`context`	`TenancyContext`
`eventService?`	`TenancyEventService`

Returns

TenancyService

Methods

getCurrentTenant()

getCurrentTenant(): string | null;

Defined in: src/services/tenancy.service.ts:40

Returns

string | null

getCurrentTenantOrThrow()

getCurrentTenantOrThrow(): string;

Defined in: src/services/tenancy.service.ts:44

Returns

string

getDbSettingKey()

getDbSettingKey(): string;

Defined in: src/services/tenancy.service.ts:28

Returns

string

isTenantBypassed()

isTenantBypassed(): boolean;

Defined in: src/services/tenancy.service.ts:52

Returns

boolean

withoutTenant()

withoutTenant<T>(callback): Promise<T>;

Defined in: src/services/tenancy.service.ts:56

Type Parameters

Type Parameter
`T`

Parameters

Parameter	Type
`callback`	() => `T` \| `Promise`<`T`>

Returns

Promise<T>

TenancyTelemetryService

Defined in: src/telemetry/tenancy-telemetry.service.ts:28

Optional OpenTelemetry integration service.

If @opentelemetry/api is installed, automatically adds the tenant ID as a span attribute to the current active span. Optionally creates custom spans for tenant lifecycle events.

If @opentelemetry/api is not installed, all methods are silently no-ops. Follows the same graceful degradation pattern as TenancyEventService.

Implements

OnModuleInit

Constructors

Constructor

new TenancyTelemetryService(options): TenancyTelemetryService;

Defined in: src/telemetry/tenancy-telemetry.service.ts:37

Parameters

Parameter	Type
`options`	`TenancyModuleOptions`

Returns

TenancyTelemetryService

Methods

endSpan()

endSpan(span): void;

Defined in: src/telemetry/tenancy-telemetry.service.ts:152

Safely end a span (null-safe).

Parameters

Parameter	Type
`span`	`Pick`<`Span`, `"end"`> \| `null`

Returns

void

onModuleInit()

onModuleInit(): Promise<void>;

Defined in: src/telemetry/tenancy-telemetry.service.ts:45

Returns

Promise<void>

Implementation of

OnModuleInit.onModuleInit

recordInvalidContext()

recordInvalidContext(diagnostic): void;

Defined in: src/telemetry/tenancy-telemetry.service.ts:91

Record an RPC validation rejection without the rejected tenant value.

Parameters

Parameter	Type
`diagnostic`	`InvalidTenantContextDiagnostic`

Returns

void

recordMissingContext()

recordMissingContext(diagnostic): void;

Defined in: src/telemetry/tenancy-telemetry.service.ts:74

Record a non-HTTP missing-context span event and metric counter.

Parameters

Parameter	Type
`diagnostic`	`MissingTenantContextDiagnostic`

Returns

void

setTenantAttribute()

setTenantAttribute(tenantId): void;

Defined in: src/telemetry/tenancy-telemetry.service.ts:67

Add tenant.id attribute to the current active span.

Parameters

Parameter	Type
`tenantId`	`string`

Returns

void

startSpan()

startSpan(name, attributes?): Span | null;

Defined in: src/telemetry/tenancy-telemetry.service.ts:108

Start a custom span (only when createSpans is true). Returns null if disabled or OTel unavailable.

Parameters

Parameter	Type
`name`	`string`
`attributes?`	`Attributes`

Returns

Span | null

startTenantSpan()

startTenantSpan(name, tenantId): Span | null;

Defined in: src/telemetry/tenancy-telemetry.service.ts:114

Start a custom span with the configured tenant ID attribute attached.

Parameters

Parameter	Type
`name`	`string`
`tenantId`	`string`

Returns

Span | null

withSpan()

withSpan<T>(
   name,
   attributes,
   callback): T;

Defined in: src/telemetry/tenancy-telemetry.service.ts:119

Run a callback with a custom span set as the active OpenTelemetry span.

Type Parameters

Type Parameter
`T`

Parameters

Parameter	Type
`name`	`string`
`attributes`	`Attributes` \| `undefined`
`callback`	(`span`) => `T`

Returns

T

withTenantSpan()

withTenantSpan<T>(
   name,
   tenantId,
   callback): T;

Defined in: src/telemetry/tenancy-telemetry.service.ts:143

Run a callback with a tenant lifecycle span set as active.

Type Parameters

Type Parameter
`T`

Parameters

Parameter	Type
`name`	`string`
`tenantId`	`string`
`callback`	(`span`) => `T`

Returns

T

TenantContextDiagnostics

Defined in: src/diagnostics/tenant-context-diagnostics.ts:53

Reports missing or invalid tenant context across non-HTTP transports and resources.

ignore preserves the pre-diagnostics behavior. warn reports and continues, while throw reports and then raises TenantContextMissingError. That policy applies only to missing context; invalid-ID reporting is observational because the interceptor always rejects a validator result of false.

Constructors

Constructor

new TenantContextDiagnostics(
   options?,
   eventService?,
   telemetryService?): TenantContextDiagnostics;

Defined in: src/diagnostics/tenant-context-diagnostics.ts:57

Parameters

Parameter	Type
`options`	`TenantContextDiagnosticsOptions`
`eventService?`	`Pick`<`TenancyEventService`, `"emit"`>
`telemetryService?`	`TenantContextTelemetryReporter`

Returns

TenantContextDiagnostics

Properties

policy

readonly policy: MissingTenantContextPolicy;

Defined in: src/diagnostics/tenant-context-diagnostics.ts:55

Methods

report()

report(diagnostic): void;

Defined in: src/diagnostics/tenant-context-diagnostics.ts:68

Parameters

Parameter	Type
`diagnostic`	`MissingTenantContextDiagnostic`

Returns

void

reportInvalid()

reportInvalid(diagnostic): void;

Defined in: src/diagnostics/tenant-context-diagnostics.ts:95

Records a rejected inbound tenant ID without exposing the rejected value. Validation rejection is independent of the missing-context policy; the interceptor remains responsible for failing the message.

Parameters

Parameter	Type
`diagnostic`	`InvalidTenantContextDiagnostic`

Returns

void

TenantContextInterceptor

Defined in: src/propagation/tenant-context.interceptor.ts:75

NestJS interceptor that restores tenant context from incoming microservice messages.

Designed for RPC transports only (Kafka, Bull, gRPC). HTTP requests are skipped because TenantMiddleware + TenancyGuard already handle HTTP tenant extraction as part of TenancyModule.

Wraps the handler execution inside TenancyContext.run(), ensuring that all downstream code (services, Prisma extension, etc.) has access to the tenant context through AsyncLocalStorage.

For best results, set the transport option explicitly to avoid duck-typing ambiguity when multiple RPC transports share similar context shapes. During 0.x, tenant ID validation is opt-in through validateTenantId; omitting it preserves the historical arbitrary non-empty string behavior.

Extraction and format validation do not authenticate a message producer or authorize it for the claimed tenant. Establish that trust boundary before tenant-scoped handler work.

Example

typescript

// Global interceptor for Kafka consumers
app.useGlobalInterceptors(
  new TenantContextInterceptor(new TenancyContext(), { transport: 'kafka' }),
);

// Bull processor with explicit transport
@UseInterceptors(new TenantContextInterceptor(new TenancyContext(), { transport: 'bull' }))
@Controller()
export class OrderProcessor { ... }

Implements

NestInterceptor

Constructors

Constructor

new TenantContextInterceptor(context, options?): TenantContextInterceptor;

Defined in: src/propagation/tenant-context.interceptor.ts:84

Parameters

Parameter	Type
`context`	`TenancyContext`
`options?`	`TenantContextInterceptorOptions`

Returns

TenantContextInterceptor

Methods

intercept()

intercept(executionContext, next): Observable<unknown>;

Defined in: src/propagation/tenant-context.interceptor.ts:105

Method to implement a custom interceptor.

Parameters

Parameter	Type	Description
`executionContext`	`ExecutionContext`	-
`next`	`CallHandler`	a reference to the `CallHandler`, which provides access to an `Observable` representing the response stream from the route handler.

Returns

Observable<unknown>

Implementation of

NestInterceptor.intercept

TenantContextMissingError

Defined in: src/errors/tenant-context-missing.error.ts:22

Extends

Error

Extended by

TenancyContextRequiredError

Constructors

Constructor

new TenantContextMissingError(message?): TenantContextMissingError;

Defined in: src/errors/tenant-context-missing.error.ts:25

Parameters

Parameter	Type
`message?`	`string`

Returns

TenantContextMissingError

Overrides

Error.constructor

Properties

message

message: string;

Defined in: ../../../../../../Users/ksy/Documents/GitHub/nestarc.dev/node_modules/typescript/lib/lib.es5.d.ts:1077

Inherited from

Error.message

name

name: string = 'TenantContextMissingError';

Defined in: src/errors/tenant-context-missing.error.ts:23

Overrides

Error.name

stack?

optional stack?: string;

Defined in: ../../../../../../Users/ksy/Documents/GitHub/nestarc.dev/node_modules/typescript/lib/lib.es5.d.ts:1078

Inherited from

Error.stack

stackTraceLimit

static stackTraceLimit: number;

Defined in: node_modules/@types/node/globals.d.ts:68

The Error.stackTraceLimit property specifies the number of stack frames collected by a stack trace (whether generated by new Error().stack or Error.captureStackTrace(obj)).

The default value is 10 but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed.

If set to a non-number value, or set to a negative number, stack traces will not capture any frames.

Inherited from

Error.stackTraceLimit

Methods

captureStackTrace()

static captureStackTrace(targetObject, constructorOpt?): void;

Defined in: node_modules/@types/node/globals.d.ts:52

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();

Parameters

Parameter	Type
`targetObject`	`object`
`constructorOpt?`	`Function`

Returns

void

Inherited from

Error.captureStackTrace

prepareStackTrace()

static prepareStackTrace(err, stackTraces): any;

Defined in: node_modules/@types/node/globals.d.ts:56

Parameters

Parameter	Type
`err`	`Error`
`stackTraces`	`CallSite`[]

Returns

any

See

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from

Error.prepareStackTrace

TenantResourceKey

Defined in: src/resources/tenant-resource-key.ts:18

Creates collision-safe tenant-scoped identifiers for Redis and search resources.

Constructors

Constructor

new TenantResourceKey(context, options): TenantResourceKey;

Defined in: src/resources/tenant-resource-key.ts:22

Parameters

Parameter	Type
`context`	`TenancyContext`
`options`	`TenantResourceKeyOptions`

Returns

TenantResourceKey

Methods

create()

create(key): string | null;

Defined in: src/resources/tenant-resource-key.ts:30

Parameters

Parameter	Type
`key`	`string`

Returns

string | null

TenantSearch

Defined in: src/resources/tenant-search.ts:26

Resolves tenant scope before invoking a vendor-specific search adapter. The adapter is never called without a tenant. ignore and warn return null; throw raises TenantContextMissingError.

Type Parameters

Type Parameter
`TQuery`
`TResult`

Constructors

Constructor

new TenantSearch<TQuery, TResult>(
   context,
   adapter,
options): TenantSearch<TQuery, TResult>;

Defined in: src/resources/tenant-search.ts:27

Parameters

Parameter	Type
`context`	`TenancyContext`
`adapter`	`TenantSearchAdapter`<`TQuery`, `TResult`>
`options`	`TenantSearchOptions`

Returns

TenantSearch<TQuery, TResult>

Methods

search()

search(query): Promise<TResult | null>;

Defined in: src/resources/tenant-search.ts:33

Parameters

Parameter	Type
`query`	`TQuery`

Returns

Promise<TResult | null>

Interfaces

BullPropagationOptions

Defined in: src/propagation/bull-tenant-propagator.ts:6

Properties

dataKey?

optional dataKey?: string;

Defined in: src/propagation/bull-tenant-propagator.ts:8

Key name used to store tenant ID in job data. Defaults to '__tenantId'.

diagnostics?

optional diagnostics?: TenantContextDiagnostics;

Defined in: src/propagation/bull-tenant-propagator.ts:10

Opt-in missing-context diagnostics.

resource?

optional resource?: string;

Defined in: src/propagation/bull-tenant-propagator.ts:12

Stable queue or job-family name included in diagnostics.

GrpcMetadataLike

Defined in: src/propagation/grpc-tenant-propagator.ts:20

Structural type for gRPC Metadata — no dependency on @grpc/grpc-js.

Matches the subset of @grpc/grpc-js Metadata used for tenant propagation.

Methods

get()

get(key): (string | Buffer<ArrayBufferLike>)[];

Defined in: src/propagation/grpc-tenant-propagator.ts:22

Parameters

Parameter	Type
`key`	`string`

Returns

(string | Buffer<ArrayBufferLike>)[]

set()

set(key, value): void;

Defined in: src/propagation/grpc-tenant-propagator.ts:21

Parameters

Parameter	Type
`key`	`string`
`value`	`string`

Returns

void

GrpcPropagationOptions

Defined in: src/propagation/grpc-tenant-propagator.ts:6

Properties

diagnostics?

optional diagnostics?: TenantContextDiagnostics;

Defined in: src/propagation/grpc-tenant-propagator.ts:10

Opt-in missing-context diagnostics.

metadataKey?

optional metadataKey?: string;

Defined in: src/propagation/grpc-tenant-propagator.ts:8

Metadata key for tenant ID. Defaults to 'x-tenant-id' (lowercase per gRPC convention).

resource?

optional resource?: string;

Defined in: src/propagation/grpc-tenant-propagator.ts:12

Stable service or method name included in diagnostics.

HttpPropagationOptions

Defined in: src/propagation/http-tenant-propagator.ts:5

Properties

headerName?

optional headerName?: string;

Defined in: src/propagation/http-tenant-propagator.ts:7

Header name for tenant ID propagation. Defaults to 'X-Tenant-Id'.

InvalidTenantContextDiagnostic

Defined in: src/diagnostics/tenant-context-diagnostics.ts:28

Low-cardinality metadata for an inbound tenant ID rejected by an explicit RPC validator. The interceptor does not copy the rejected value here; callers must keep resource stable and non-sensitive.

Properties

operation

operation: "consume";

Defined in: src/diagnostics/tenant-context-diagnostics.ts:30

resource?

optional resource?: string;

Defined in: src/diagnostics/tenant-context-diagnostics.ts:31

transport

transport: "bull" | "kafka" | "grpc";

Defined in: src/diagnostics/tenant-context-diagnostics.ts:29

JwtClaimExtractorOptions

Defined in: src/extractors/jwt-claim.extractor.ts:4

Properties

claimKey

claimKey: string;

Defined in: src/extractors/jwt-claim.extractor.ts:5

headerName?

optional headerName?: string;

Defined in: src/extractors/jwt-claim.extractor.ts:6

KafkaMessageLike

Defined in: src/propagation/kafka-tenant-propagator.ts:17

Structural type for Kafka message — no dependency on kafkajs.

Indexable

[key: string]: unknown

Properties

headers?

optional headers?: Record<string, string | Buffer<ArrayBufferLike> | undefined>;

Defined in: src/propagation/kafka-tenant-propagator.ts:18

KafkaPropagationOptions

Defined in: src/propagation/kafka-tenant-propagator.ts:7

Properties

diagnostics?

optional diagnostics?: TenantContextDiagnostics;

Defined in: src/propagation/kafka-tenant-propagator.ts:11

Opt-in missing-context diagnostics.

headerName?

optional headerName?: string;

Defined in: src/propagation/kafka-tenant-propagator.ts:9

Header name for tenant ID in Kafka message headers. Defaults to 'X-Tenant-Id'.

resource?

optional resource?: string;

Defined in: src/propagation/kafka-tenant-propagator.ts:13

Stable topic name included in diagnostics.

MissingTenantContextDiagnostic

Defined in: src/diagnostics/tenant-context-diagnostics.ts:17

Properties

operation

operation: TenantContextDiagnosticOperation;

Defined in: src/diagnostics/tenant-context-diagnostics.ts:19

resource?

optional resource?: string;

Defined in: src/diagnostics/tenant-context-diagnostics.ts:20

transport

transport: "bull" | "kafka" | "grpc" | "cache" | "redis" | "search";

Defined in: src/diagnostics/tenant-context-diagnostics.ts:18

PathExtractorOptions

Defined in: src/extractors/path.extractor.ts:4

Properties

paramName

paramName: string;

Defined in: src/extractors/path.extractor.ts:6

pattern

pattern: string;

Defined in: src/extractors/path.extractor.ts:5

PrismaTenancyExtensionOptions

Defined in: src/prisma/prisma-tenancy.extension.ts:30

Properties

autoInjectTenantId?

optional autoInjectTenantId?: boolean;

Defined in: src/prisma/prisma-tenancy.extension.ts:43

Inject the current tenant into top-level create/createMany/createManyAndReturn data and upsert.create, replacing any supplied value. Removes the tenant field from upsert.update. Does not recursively inject nested writes.

Default

false

dbSettingKey?

optional dbSettingKey?: string;

Defined in: src/prisma/prisma-tenancy.extension.ts:36

Optional compatibility assertion for the canonical setting configured on TenancyService. Omit this when using TenancyModule; a different value fails before the extension is created.

failClosed?

optional failClosed?: boolean;

Defined in: src/prisma/prisma-tenancy.extension.ts:60

When true, throws TenancyContextRequiredError if a query is executed without a tenant context (unless the model is in sharedModels or withoutTenant() was used to explicitly bypass the client-side check).

This check covers model operations, not raw SQL. It does not replace correctly configured database RLS policies or alter database privileges.

Default

true

interactiveTransactionSupport?

optional interactiveTransactionSupport?: boolean;

Defined in: src/prisma/prisma-tenancy.extension.ts:80

Enable transparent interactive transaction support.

When enabled, the extension detects interactive transactions ($transaction(async (tx) => ...)) and sets the RLS context on the transaction's connection directly.

Relies on Prisma internal APIs (__internalParams, _createItxClient). Extension creation verifies _createItxClient, but Prisma does not expose a public way to validate the full __internalParams.transaction shape. A Prisma internal change can therefore bypass transparent detection.

For an alternative that uses only public Prisma APIs, see tenancyTransaction().

Deprecated

Use tenancyTransaction() for interactive transactions. This compatibility-sensitive mode is supported through v0.16.x and scheduled for removal in v0.17.0.

Default

false

sharedModels?

optional sharedModels?: string[];

Defined in: src/prisma/prisma-tenancy.extension.ts:50

Prisma model names that skip this extension's context setup, automatic injection, and fail-closed check. Database RLS policies still apply.

tenantIdField?

optional tenantIdField?: string;

Defined in: src/prisma/prisma-tenancy.extension.ts:45

Tenant field used by automatic injection.

Default

tenant_id

PrismaTransactionClient

Defined in: src/prisma/tenancy-transaction.ts:17

Structural type representing a Prisma-like client that supports interactive transactions. PrismaClient satisfies this automatically.

Type Parameters

Type Parameter	Default type
`TTx` extends `PrismaTransactionContext`	`any`

Methods

$transaction()

$transaction<T>(fn, options?): Promise<T>;

Defined in: src/prisma/tenancy-transaction.ts:18

Type Parameters

Type Parameter
`T`

Parameters

Parameter	Type
`fn`	(`tx`) => `Promise`<`T`>
`options?`	`Record`<`string`, `unknown`>

Returns

Promise<T>

PrismaTransactionContext

Defined in: src/prisma/tenancy-transaction.ts:6

Minimal transaction client shape required by tenancyTransaction.

Methods

$executeRaw()

$executeRaw(strings, ...values): Promise<unknown>;

Defined in: src/prisma/tenancy-transaction.ts:7

Parameters

Parameter	Type
`strings`	`TemplateStringsArray`
...`values`	`unknown`[]

Returns

Promise<unknown>

SubdomainExtractorOptions

Defined in: src/extractors/subdomain.extractor.ts:4

Properties

excludeSubdomains?

optional excludeSubdomains?: string[];

Defined in: src/extractors/subdomain.extractor.ts:5

TelemetryOptions

Defined in: src/interfaces/tenancy-module-options.interface.ts:8

Properties

createSpans?

optional createSpans?: boolean;

Defined in: src/interfaces/tenancy-module-options.interface.ts:12

Create custom spans for tenant lifecycle events (resolved, not_found, etc.).

Default

false

spanAttributeKey?

optional spanAttributeKey?: string;

Defined in: src/interfaces/tenancy-module-options.interface.ts:10

Span attribute key for tenant ID.

Default

'tenant.id'

TenancyEventMap

Defined in: src/events/tenancy-events.ts:90

Type-safe mapping from event name to payload type. Used by TenancyEventService.emit() to enforce correct payloads at compile time.

Properties

tenant.context_bypassed

tenant.context_bypassed: TenantContextBypassedEvent;

Defined in: src/events/tenancy-events.ts:95

tenant.context_invalid

tenant.context_invalid: InvalidTenantContextDiagnostic;

Defined in: src/events/tenancy-events.ts:98

tenant.context_missing

tenant.context_missing: MissingTenantContextDiagnostic;

Defined in: src/events/tenancy-events.ts:97

tenant.cross_check_failed

tenant.cross_check_failed: TenantCrossCheckFailedEvent;

Defined in: src/events/tenancy-events.ts:96

tenant.extraction_failed

tenant.extraction_failed: TenantExtractionFailedEvent;

Defined in: src/events/tenancy-events.ts:93

tenant.not_found

tenant.not_found: TenancyEventRequestPayload;

Defined in: src/events/tenancy-events.ts:92

tenant.resolved

tenant.resolved: TenantResolvedEvent;

Defined in: src/events/tenancy-events.ts:91

tenant.validation_failed

tenant.validation_failed: TenantValidationFailedEvent;

Defined in: src/events/tenancy-events.ts:94

TenancyEventRequestSummary

Defined in: src/events/tenancy-events.ts:7

Properties

host?

optional host?: string;

Defined in: src/events/tenancy-events.ts:12

ip?

optional ip?: string;

Defined in: src/events/tenancy-events.ts:10

method?

optional method?: string;

Defined in: src/events/tenancy-events.ts:8

path?

optional path?: string;

Defined in: src/events/tenancy-events.ts:9

userAgent?

optional userAgent?: string;

Defined in: src/events/tenancy-events.ts:11

TenancyModuleAsyncOptions

Defined in: src/interfaces/tenancy-module-options.interface.ts:115

Extends

Pick<ModuleMetadata, "imports">

Properties

imports?

optional imports?: (
  | DynamicModule
  | Type<any>
  | Promise<DynamicModule>
  | ForwardReference<any>)[];

Defined in: node_modules/@nestjs/common/interfaces/modules/module-metadata.interface.d.ts:18

Optional list of imported modules that export the providers which are required in this module.

Inherited from

Pick.imports

inject?

optional inject?: (InjectionToken | OptionalFactoryDependency)[];

Defined in: src/interfaces/tenancy-module-options.interface.ts:117

useClass?

optional useClass?: Type<TenancyModuleOptionsFactory>;

Defined in: src/interfaces/tenancy-module-options.interface.ts:121

useExisting?

optional useExisting?: Type<TenancyModuleOptionsFactory>;

Defined in: src/interfaces/tenancy-module-options.interface.ts:122

useFactory?

optional useFactory?: (...args) =>
  | TenancyModuleOptions
| Promise<TenancyModuleOptions>;

Defined in: src/interfaces/tenancy-module-options.interface.ts:118

Parameters

Parameter	Type
...`args`	`any`[]

Returns

| TenancyModuleOptions | Promise<TenancyModuleOptions>

TenancyModuleOptions

Defined in: src/interfaces/tenancy-module-options.interface.ts:15

Properties

crossCheck?

optional crossCheck?: {
  extractor: TenantExtractor;
  onFailed?: "reject" | "log";
  required?: boolean;
};

Defined in: src/interfaces/tenancy-module-options.interface.ts:78

Cross-check configuration for tenant ID forgery prevention.

Compares the primary extractor result with a secondary source. Common pattern: primary = header, cross-check = JWT claim.

If the cross-check extractor returns null (e.g., no JWT present), validation is skipped — allowing unauthenticated endpoints to work normally. Set required: true to reject requests when the cross-check extractor returns null, enforcing that every request must have a verifiable secondary source.

extractor

extractor: TenantExtractor;

Secondary extractor to validate the tenant ID against.

onFailed?

optional onFailed?: "reject" | "log";

Behavior on mismatch.

'reject' (default): throws ForbiddenException
'log': logs a warning and continues with the primary extractor's value

required?

optional required?: boolean;

When true, the cross-check extractor must return a non-null value. Throws ForbiddenException if the extractor returns null. Use this for endpoints that require authenticated cross-validation.

Default

false

dbSettingKey?

optional dbSettingKey?: string;

Defined in: src/interfaces/tenancy-module-options.interface.ts:36

Canonical PostgreSQL custom setting used by Prisma RLS integration. The extension and tenancyTransaction() inherit this value through TenancyService; explicit per-call values must match it.

Default

'app.current_tenant'

missingContext?

optional missingContext?: TenantContextDiagnosticsOptions;

Defined in: src/interfaces/tenancy-module-options.interface.ts:106

Opt-in diagnostics for missing tenant context outside HTTP requests. The default ignore policy preserves existing pass-through behavior.

onTenantNotFound?

optional onTenantNotFound?: (request, response) => void | "skip" | Promise<void | "skip">;

Defined in: src/interfaces/tenancy-module-options.interface.ts:65

Called when no tenant ID could be extracted from the request.

Behavior based on return value:

void / undefined: request continues to the next middleware (observation-only hook)
'skip': request continues but next() is NOT called. Warning: You must send a response (e.g., response.status(403).end()) or throw an exception before returning 'skip'. Otherwise the HTTP request will hang indefinitely with no response sent to the client.

Throwing an exception (e.g., throw new ForbiddenException()) always aborts the request regardless of return value.

Parameters

Parameter	Type
`request`	`TenancyRequest`
`response`	`TenancyResponse`

Returns

void | "skip" | Promise<void | "skip">

onTenantResolved?

optional onTenantResolved?: (tenantId, request) => void | Promise<void>;

Defined in: src/interfaces/tenancy-module-options.interface.ts:50

Called after a tenant ID is successfully extracted and validated. Runs inside TenancyContext.run(), so getCurrentTenant() is available.

Throwing an exception aborts the request — NestJS handles it as a 500 (or whatever your exception filter maps it to). The telemetry span is always closed via finally, so throwing is safe for audit/authorization checks.

Parameters

Parameter	Type
`tenantId`	`string`
`request`	`TenancyRequest`

Returns

void | Promise<void>

telemetry?

optional telemetry?: TelemetryOptions;

Defined in: src/interfaces/tenancy-module-options.interface.ts:100

OpenTelemetry integration. Automatically adds tenant.id to active spans. Silently ignored if @opentelemetry/api is not installed.

tenantExtractor

tenantExtractor: string | TenantExtractor;

Defined in: src/interfaces/tenancy-module-options.interface.ts:29

Tenant extraction strategy.

A string is a shortcut for HeaderTenantExtractor and is interpreted as the HTTP header name. Use a TenantExtractor instance for non-header strategies such as subdomain, path, JWT claim, or composite extraction.

Example

typescript

tenantExtractor: 'X-Tenant-Id'
tenantExtractor: new SubdomainTenantExtractor()

validateTenantId?

optional validateTenantId?: TenantIdValidator;

Defined in: src/interfaces/tenancy-module-options.interface.ts:41

Validates an extracted HTTP tenant ID before context is established. Defaults to the built-in dashed UUID-like validator when omitted.

TenancyModuleOptionsFactory

Defined in: src/interfaces/tenancy-module-options.interface.ts:109

Methods

createTenancyOptions()

createTenancyOptions():
  | TenancyModuleOptions
| Promise<TenancyModuleOptions>;

Defined in: src/interfaces/tenancy-module-options.interface.ts:110

Returns

| TenancyModuleOptions | Promise<TenancyModuleOptions>

TenancyRequest

Defined in: src/interfaces/tenancy-request.interface.ts:11

Minimal HTTP request interface for @nestarc/tenancy public API.

This adapter-neutral shape describes the fields used by extractors and callbacks. The actual fields depend on the HTTP adapter and middleware; compatible types alone do not verify an adapter's middleware integration. Narrow platform-specific properties before use, or assert the request type after selecting that adapter (e.g., request as import('express').Request). Authentication and cookie properties require the corresponding middleware.

Indexable

[key: string]: unknown

Index signature for platform-specific properties. Use type assertion to access.

Properties

headers

headers: Record<string, string | string[] | undefined>;

Defined in: src/interfaces/tenancy-request.interface.ts:13

HTTP request headers. Keys are lowercase in Node.js.

hostname?

optional hostname?: string;

Defined in: src/interfaces/tenancy-request.interface.ts:15

Hostname derived from the Host header.

path?

optional path?: string;

Defined in: src/interfaces/tenancy-request.interface.ts:17

Adapter-provided request path, preferred by PathTenantExtractor.

url?

optional url?: string;

Defined in: src/interfaces/tenancy-request.interface.ts:19

Request target such as /api/users?page=1; used when path is absent or empty.

TenancyResponse

Defined in: src/interfaces/tenancy-request.interface.ts:37

Minimal HTTP response interface for @nestarc/tenancy public API.

Used only in the onTenantNotFound callback. Available methods depend on the HTTP adapter; for example, raw Node responses do not expose status or json, and Fastify replies use send instead of json.

The named methods are optional to maintain compatibility with any response-like object. After selecting an adapter, assert its response type to use its full API: (response as import('express').Response). A callback that handles a missing tenant must actually send a response or throw; optional calls alone do not establish that a response was sent.

Indexable

[key: string]: unknown

Index signature for platform-specific properties. Use type assertion to access.

Methods

end()?

optional end(): void;

Defined in: src/interfaces/tenancy-request.interface.ts:43

End the response without a body.

Returns

void

json()?

optional json(body): void;

Defined in: src/interfaces/tenancy-request.interface.ts:41

Send JSON response body.

Parameters

Parameter	Type
`body`	`unknown`

Returns

void

status()?

optional status(code): this;

Defined in: src/interfaces/tenancy-request.interface.ts:39

Set HTTP status code. Returns this for chaining (Express/Fastify convention).

Parameters

Parameter	Type
`code`	`number`

Returns

this

TenancyTransactionOptions

Defined in: src/prisma/tenancy-transaction.ts:24

Properties

dbSettingKey?

optional dbSettingKey?: string;

Defined in: src/prisma/tenancy-transaction.ts:38

Optional compatibility assertion for the canonical setting configured on TenancyService. Omit it when using TenancyModule.

isolationLevel?

optional isolationLevel?: "ReadUncommitted" | "ReadCommitted" | "RepeatableRead" | "Serializable";

Defined in: src/prisma/tenancy-transaction.ts:33

PostgreSQL transaction isolation level.

maxWait?

optional maxWait?: number;

Defined in: src/prisma/tenancy-transaction.ts:29

Maximum time in milliseconds to wait for Prisma to start the transaction. Forwarded to Prisma; enforcement depends on the selected Prisma runtime.

timeout?

optional timeout?: number;

Defined in: src/prisma/tenancy-transaction.ts:31

Maximum time in milliseconds the interactive transaction may run.

TenantContextBypassedEvent

Defined in: src/events/tenancy-events.ts:45

Properties

previousTenantId?

optional previousTenantId?: string | null;

Defined in: src/events/tenancy-events.ts:47

reason

reason: "decorator" | "withoutTenant";

Defined in: src/events/tenancy-events.ts:46

requestSummary?

optional requestSummary?: TenancyEventRequestSummary;

Defined in: src/events/tenancy-events.ts:48

TenantContextCarrier

Defined in: src/interfaces/tenant-context-carrier.interface.ts:14

Transport-agnostic contract for propagating tenant context across service boundaries.

Unlike TenantPropagator (HTTP-specific, returns Record<string, string>), this interface supports any carrier type: Bull job data, Kafka messages, gRPC metadata, or custom transports.

Follows the OpenTelemetry inject/extract pattern:

inject: attaches the current tenant ID to an outgoing carrier
extract: reads a tenant ID from an incoming carrier

Type Parameters

Type Parameter	Default type	Description
`TCarrier`	`unknown`	The transport-specific data structure (e.g., job data object, Kafka message, gRPC Metadata)

Methods

extract()

extract(carrier): string | null;

Defined in: src/interfaces/tenant-context-carrier.interface.ts:26

Extracts the tenant ID from an incoming carrier. Returns the tenant ID string, or null if not present.

Parameters

Parameter	Type
`carrier`	`TCarrier`

Returns

string | null

inject()

inject(carrier): TCarrier;

Defined in: src/interfaces/tenant-context-carrier.interface.ts:20

Attaches the current tenant ID to the carrier for outbound propagation. Returns the carrier with tenant context included. If no tenant context is available, returns the carrier unchanged.

Parameters

Parameter	Type
`carrier`	`TCarrier`

Returns

TCarrier

TenantContextDiagnosticsOptions

Defined in: src/diagnostics/tenant-context-diagnostics.ts:38

Properties

onMissing?

optional onMissing?: (diagnostic) => void;

Defined in: src/diagnostics/tenant-context-diagnostics.ts:42

Optional hook for structured logging or application metrics.

Parameters

Parameter	Type
`diagnostic`	`MissingTenantContextDiagnostic`

Returns

void

policy?

optional policy?: MissingTenantContextPolicy;

Defined in: src/diagnostics/tenant-context-diagnostics.ts:40

Existing silent/pass-through behavior remains the default.

TenantCrossCheckFailedEvent

Defined in: src/events/tenancy-events.ts:51

Extends

TenancyEventRequestPayload

Properties

crossCheckTenantId

crossCheckTenantId: string;

Defined in: src/events/tenancy-events.ts:53

extractedTenantId

extractedTenantId: string;

Defined in: src/events/tenancy-events.ts:52

requestSummary?

optional requestSummary?: TenancyEventRequestSummary;

Defined in: src/events/tenancy-events.ts:27

Inherited from

TenancyEventRequestPayload.requestSummary

TenantExtractionFailedEvent

Defined in: src/events/tenancy-events.ts:36

Extends

TenancyEventRequestPayload

Properties

errorMessage

errorMessage: string;

Defined in: src/events/tenancy-events.ts:38

errorName

errorName: string;

Defined in: src/events/tenancy-events.ts:37

requestSummary?

optional requestSummary?: TenancyEventRequestSummary;

Defined in: src/events/tenancy-events.ts:27

Inherited from

TenancyEventRequestPayload.requestSummary

TenantExtractor

Defined in: src/interfaces/tenant-extractor.interface.ts:15

Contract for extracting a tenant ID from an inbound HTTP request.

Implementations may return synchronously or return a Promise for async lookups. Throw only for malformed input or policy failures that should reject the request immediately.

Methods

extract()

extract(request): string | Promise<string | null> | null;

Defined in: src/interfaces/tenant-extractor.interface.ts:16

Parameters

Parameter	Type
`request`	`TenancyRequest`

Returns

string | Promise<string | null> | null

TenantPropagator

Defined in: src/interfaces/tenant-propagator.interface.ts:8

Contract for propagating tenant context to outgoing requests.

Implementations transform the current tenant ID into transport-specific headers or metadata. Used by HttpTenantPropagator for HTTP and KafkaTenantPropagator for Kafka. For Bull and gRPC, see TenantContextCarrier.

Methods

getHeaders()

getHeaders(): Record<string, string>;

Defined in: src/interfaces/tenant-propagator.interface.ts:13

Returns headers to propagate tenant context. Returns an empty object if no tenant context is available.

Returns

Record<string, string>

TenantResolvedEvent

Defined in: src/events/tenancy-events.ts:30

Extends

TenancyEventRequestPayload

Properties

requestSummary?

optional requestSummary?: TenancyEventRequestSummary;

Defined in: src/events/tenancy-events.ts:27

Inherited from

TenancyEventRequestPayload.requestSummary

tenantId

tenantId: string;

Defined in: src/events/tenancy-events.ts:31

TenantResourceKeyOptions

Defined in: src/resources/tenant-resource-key.ts:4

Properties

diagnostics?

optional diagnostics?: TenantContextDiagnostics;

Defined in: src/resources/tenant-resource-key.ts:14

Opt-in missing-context diagnostics.

prefix?

optional prefix?: string;

Defined in: src/resources/tenant-resource-key.ts:10

Prefix for generated keys.

Default

'tenant'

resource?

optional resource?: string;

Defined in: src/resources/tenant-resource-key.ts:8

Stable cache, index, or resource name included in diagnostics.

separator?

optional separator?: string;

Defined in: src/resources/tenant-resource-key.ts:12

Separator between encoded key parts.

Default

':'

transport

transport: "redis" | "search";

Defined in: src/resources/tenant-resource-key.ts:6

Resource kind used in diagnostics.

TenantSearchAdapter

Defined in: src/resources/tenant-search.ts:10

Vendor-neutral search contract. Adapters must apply both scope fields.

Type Parameters

Type Parameter
`TQuery`
`TResult`

Methods

search()

search(scope, query): Promise<TResult>;

Defined in: src/resources/tenant-search.ts:11

Parameters

Parameter	Type
`scope`	`TenantSearchScope`
`query`	`TQuery`

Returns

Promise<TResult>

TenantSearchOptions

Defined in: src/resources/tenant-search.ts:14

Properties

diagnostics?

optional diagnostics?: TenantContextDiagnostics;

Defined in: src/resources/tenant-search.ts:18

Opt-in missing-context diagnostics.

index

index: string;

Defined in: src/resources/tenant-search.ts:16

Logical or physical index name.

TenantSearchScope

Defined in: src/resources/tenant-search.ts:4

Properties

index

index: string;

Defined in: src/resources/tenant-search.ts:6

tenantId

tenantId: string;

Defined in: src/resources/tenant-search.ts:5

TenantValidationFailedEvent

Defined in: src/events/tenancy-events.ts:41

Extends

TenancyEventRequestPayload

Properties

requestSummary?

optional requestSummary?: TenancyEventRequestSummary;

Defined in: src/events/tenancy-events.ts:27

Inherited from

TenancyEventRequestPayload.requestSummary

tenantId

tenantId: string;

Defined in: src/events/tenancy-events.ts:42

Type Aliases

MissingTenantContextPolicy

type MissingTenantContextPolicy = "ignore" | "warn" | "throw";

Defined in: src/diagnostics/tenant-context-diagnostics.ts:7

TenantContextDiagnosticOperation

type TenantContextDiagnosticOperation = "inject" | "extract" | "consume" | "cache" | "key" | "search";

Defined in: src/diagnostics/tenant-context-diagnostics.ts:9

TenantContextInterceptorOptions

type TenantContextInterceptorOptions = TenantContextInterceptorDiagnosticOptions &
  | {
  kafkaHeaderName?: string;
  transport: "kafka";
}
  | {
  bullDataKey?: string;
  transport: "bull";
}
  | {
  grpcMetadataKey?: string;
  transport: "grpc";
}
  | {
  bullDataKey?: string;
  grpcMetadataKey?: string;
  kafkaHeaderName?: string;
  transport?: undefined;
};

Defined in: src/propagation/tenant-context.interceptor.ts:33

Options for TenantContextInterceptor.

When transport is specified, only the matching transport key is accepted. When transport is omitted, all keys are available for duck-typing fallback.

TenantIdValidator

type TenantIdValidator = (tenantId) => boolean | Promise<boolean>;

Defined in: src/interfaces/tenant-id-validator.interface.ts:7

Validates an extracted tenant identifier before it enters tenant context.

Returning false rejects the inbound request or message. Throwing or returning a rejected promise propagates the original error.

Parameters

Parameter	Type
`tenantId`	`string`

Returns

boolean | Promise<boolean>

TenantNotFoundEvent

type TenantNotFoundEvent = TenancyEventRequestPayload;

Defined in: src/events/tenancy-events.ts:34

Variables

CurrentTenant

const CurrentTenant: (...dataOrPipes) => ParameterDecorator;

Defined in: src/decorators/current-tenant.decorator.ts:4

Parameters

Parameter	Type
...`dataOrPipes`	`unknown`[]

Returns

ParameterDecorator

TENANCY_MODULE_OPTIONS

const TENANCY_MODULE_OPTIONS: typeof TENANCY_MODULE_OPTIONS;

Defined in: src/tenancy.constants.ts:2

TenancyEvents

const TenancyEvents: {
  CONTEXT_BYPASSED: "tenant.context_bypassed";
  CONTEXT_INVALID: "tenant.context_invalid";
  CONTEXT_MISSING: "tenant.context_missing";
  CROSS_CHECK_FAILED: "tenant.cross_check_failed";
  EXTRACTION_FAILED: "tenant.extraction_failed";
  NOT_FOUND: "tenant.not_found";
  RESOLVED: "tenant.resolved";
  VALIDATION_FAILED: "tenant.validation_failed";
};

Defined in: src/events/tenancy-events.ts:15

Type Declaration

Name	Type	Default value	Defined in
`CONTEXT_BYPASSED`	`"tenant.context_bypassed"`	`'tenant.context_bypassed'`	src/events/tenancy-events.ts:20
`CONTEXT_INVALID`	`"tenant.context_invalid"`	`'tenant.context_invalid'`	src/events/tenancy-events.ts:23
`CONTEXT_MISSING`	`"tenant.context_missing"`	`'tenant.context_missing'`	src/events/tenancy-events.ts:22
`CROSS_CHECK_FAILED`	`"tenant.cross_check_failed"`	`'tenant.cross_check_failed'`	src/events/tenancy-events.ts:21
`EXTRACTION_FAILED`	`"tenant.extraction_failed"`	`'tenant.extraction_failed'`	src/events/tenancy-events.ts:18
`NOT_FOUND`	`"tenant.not_found"`	`'tenant.not_found'`	src/events/tenancy-events.ts:17
`RESOLVED`	`"tenant.resolved"`	`'tenant.resolved'`	src/events/tenancy-events.ts:16
`VALIDATION_FAILED`	`"tenant.validation_failed"`	`'tenant.validation_failed'`	src/events/tenancy-events.ts:19

Functions

BypassTenancy()

function BypassTenancy(): CustomDecorator<typeof BYPASS_TENANCY_KEY>;

Defined in: src/decorators/bypass-tenancy.decorator.ts:14

Marks a route or controller to skip TenancyGuard's tenant-required check.

Important: This only bypasses the guard — it does NOT clear the tenant context. If the request contains a tenant header, TenantMiddleware still sets the context, so getCurrentTenant() may return a value and Prisma queries will still be RLS-filtered.

Use this for endpoints that should work with or without a tenant (e.g., health checks, public APIs). If you need to explicitly run without tenant context, use withoutTenant().

Returns

CustomDecorator<typeof BYPASS_TENANCY_KEY>

createPrismaTenancyExtension()

function createPrismaTenancyExtension(tenancyService, options?): (client) => PrismaClientExtends<InternalArgs<{
}, {
}, {
}, {
}>>;

Defined in: src/prisma/prisma-tenancy.extension.ts:118

Creates a Prisma Client Extension that sets the PostgreSQL RLS context before model queries when a tenant context exists, except for sharedModels. Raw SQL operations are outside this extension's model query hook.

Uses Prisma.defineExtension to access the base client via closure, then wraps each covered query in a batch transaction:

SELECT set_config(key, tenantId, TRUE) — sets the RLS variable (transaction-local)
query(args) — the original query, subject to the database's RLS policies

SECURITY: Uses $executeRaw tagged template with bind parameters. set_config() accepts the setting key and tenant ID as bound values, so those values cannot alter this context-setting statement's SQL structure. This does not make arbitrary application SQL safe or replace authorization.

Options:

dbSettingKey: Optional assertion matching the TenancyService canonical key
autoInjectTenantId: Inject tenant ID into supported top-level create operations
tenantIdField: Field name to inject tenant ID into (default: tenant_id)
sharedModels: Skip extension handling for listed models; database RLS still applies
failClosed: Throw when model queries run without tenant context (default: true)

Interactive transactions: By default, the batch $transaction([set_config, query]) does not propagate into interactive transactions ($transaction(async (tx) => ...)). Use the standalone tenancyTransaction() helper (public APIs only). The deprecated interactiveTransactionSupport: true mode remains for existing consumers.

Usage:

typescript

const prisma = basePrisma.$extends(
  createPrismaTenancyExtension(tenancyService)
);

Parameters

Parameter	Type
`tenancyService`	`TenancyService`
`options?`	`PrismaTenancyExtensionOptions`

Returns

(client) => PrismaClientExtends<InternalArgs<{ }, { }, { }, { }>>

propagateTenantHeaders()

function propagateTenantHeaders(headerName?): Record<string, string>;

Defined in: src/propagation/propagate-tenant-headers.ts:34

Returns HTTP headers containing the current tenant ID for service-to-service propagation.

Works with any HTTP client (fetch, axios, got, undici, node:http) — no dependencies required. Returns an empty object when no tenant context is available.

Uses the static AsyncLocalStorage from TenancyContext, so it works anywhere in the call stack without dependency injection.

Parameters

Parameter	Type	Default value	Description
`headerName`	`string`	`DEFAULT_PROPAGATION_HEADER`	Header name for tenant ID (default: 'X-Tenant-Id')

Returns

Record<string, string>

Object with tenant header, or empty object if no tenant context

Example

typescript

// With fetch
const res = await fetch('/api/orders', {
  headers: { ...propagateTenantHeaders() },
});

// With axios
const res = await axios.get('/api/orders', {
  headers: propagateTenantHeaders(),
});

// With @nestjs/axios HttpService
this.httpService.get('/api/orders', {
  headers: propagateTenantHeaders(),
});

tenancyTransaction()

function tenancyTransaction<T, TTx>(
   prisma,
   tenancyService,
   callback,
options?): Promise<T>;

Defined in: src/prisma/tenancy-transaction.ts:53

Executes a Prisma interactive transaction with RLS tenant context.

Runs set_config() as the first statement inside the interactive transaction, ensuring the PostgreSQL session variable is set on the same connection that executes the callback queries.

Type Parameters

Type Parameter	Default type
`T`	-
`TTx` extends `PrismaTransactionContext`	`any`

Parameters

Parameter	Type	Description
`prisma`	`PrismaTransactionClient`<`TTx`>	PrismaClient instance (not extended — raw client)
`tenancyService`	`TenancyService`	TenancyService to read current tenant
`callback`	(`tx`) => `Promise`<`T`>	Function receiving the transaction client
`options?`	`TenancyTransactionOptions`	Transaction wait/timeout, isolation level, and DB setting key

Returns

Promise<T>

@nestarc/tenancy ​

Classes ​

BullTenantPropagator ​

Example ​

Implements ​

Constructors ​

Constructor ​

Parameters ​

Returns ​

Methods ​

extract() ​

Parameters ​

Returns ​

Implementation of ​

inject() ​

Parameters ​

Returns ​

Implementation of ​

CompositeTenantExtractor ​

Implements ​

Constructors ​

Constructor ​

Parameters ​

Returns ​

Methods ​

extract() ​

Parameters ​

Returns ​

Implementation of ​

GrpcTenantPropagator ​

Example ​

Implements ​

Constructors ​

Constructor ​

Parameters ​

Returns ​

Methods ​

extract() ​

Parameters ​

Returns ​

Implementation of ​

inject() ​

Parameters ​

Returns ​

Implementation of ​

HeaderTenantExtractor ​

Implements ​

Constructors ​

Constructor ​

Parameters ​

Returns ​

Methods ​

extract() ​

Parameters ​

Returns ​

Implementation of ​

HttpTenantPropagator ​

Example ​

Implements ​

Constructors ​

Constructor ​

Parameters ​

Returns ​

Methods ​

getHeaders() ​

Returns ​

Implementation of ​

JwtClaimTenantExtractor ​

Implements ​

Constructors ​

Constructor ​

Parameters ​

Returns ​

Methods ​

extract() ​

Parameters ​

Returns ​

Implementation of ​

KafkaTenantPropagator ​

Example ​

@nestarc/tenancy

Classes

BullTenantPropagator

Example

Implements

Constructors

Constructor

Parameters

Returns

Methods

extract()

Parameters

Returns

Implementation of

inject()

Parameters

Returns

Implementation of

CompositeTenantExtractor

Implements

Constructors

Constructor

Parameters

Returns

Methods

extract()

Parameters

Returns

Implementation of

GrpcTenantPropagator

Example

Implements

Constructors

Constructor

Parameters

Returns

Methods

extract()

Parameters

Returns

Implementation of

inject()

Parameters

Returns

Implementation of

HeaderTenantExtractor

Implements

Constructors

Constructor

Parameters

Returns

Methods

extract()

Parameters

Returns

Implementation of

HttpTenantPropagator

Example

Implements

Constructors

Constructor

Parameters

Returns

Methods

getHeaders()

Returns

Implementation of

JwtClaimTenantExtractor

Implements

Constructors

Constructor

Parameters

Returns

Methods

extract()

Parameters

Returns

Implementation of

KafkaTenantPropagator

Example