ExternalContextOptions

Kind: Interface

Source: packages/core/helpers/external-context-creator.ts

Part of: Core

ExternalContextOptions controls which framework-level enhancements are applied when creating an external execution context. It allows callers to enable or disable guards, interceptors, and exception filters independently for handlers invoked outside the standard request pipeline.

Properties

Diagram

mermaid
graph LR
  A[External Context Creation] --> B[ExternalContextOptions]
  B --> C{guards enabled?}
  B --> D{interceptors enabled?}
  B --> E{filters enabled?}
  C --> F[Apply Guards]
  D --> G[Apply Interceptors]
  E --> H[Apply Exception Filters]

Usage

ts
import { ExternalContextOptions } from './helpers/external-context-creator';

const options: ExternalContextOptions = {
  guards: true,
  interceptors: true,
  filters: false,
};

// Pass options when creating an external handler context.
// Guards and interceptors run, while exception filters are skipped.
const handler = externalContextCreator.create(
  instance,
  method,
  methodName,
  options,
);

AI Coding Instructions

• Provide all three boolean fields when constructing ExternalContextOptions; do not rely on implicit defaults.
• Enable guards when external handlers must enforce authorization or access-control rules.
• Enable interceptors when handlers require cross-cutting behavior such as logging, transformation, caching, or timing.
• Enable filters when exceptions should be processed through configured exception filters instead of propagating directly.
• Keep option values aligned with the execution environment so external contexts behave consistently with the intended application pipeline.

How it works

ExternalContextOptions is an exported TypeScript interface used as the options parameter of ExternalContextCreator.create() to select whether the generated external handler runs guards, creates/runs interceptors, and wraps execution in external exception-filter handling. Its three optional boolean fields are guards, interceptors, and filters. packages/core/helpers/external-context-creator.ts:32-36 packages/core/helpers/external-context-creator.ts:91-108

• When options is omitted, create() defaults all three fields to true. packages/core/helpers/external-context-creator.ts:102-106
• guards controls creation of the guard activation function. A truthy value creates it; a falsy or omitted field sets it to null, so the target does not invoke guard activation. packages/core/helpers/external-context-creator.ts:150-152 packages/core/helpers/external-context-creator.ts:164-167
  • When enabled and guards exist, failed guard activation throws ForbiddenException with FORBIDDEN_MESSAGE. packages/core/helpers/external-context-creator.ts:338-357
• interceptors controls whether interceptor instances are created. A truthy value creates them; otherwise the handler passes an empty interceptor array to interceptorsConsumer.intercept(). packages/core/helpers/external-context-creator.ts:135-143 packages/core/helpers/external-context-creator.ts:168-175
• filters controls the returned function. A truthy value returns an ExternalErrorProxy wrapper; otherwise create() returns the unwrapped target. packages/core/helpers/external-context-creator.ts:178-184
  • The proxy catches errors from the target, creates an ExecutionContextHost from the call arguments, sets its context type, and passes the error and host to the exception handler. packages/core/helpers/external-proxy.ts:11-18

The options do not control pipe creation or parameter-pipe application: create() constructs pipes before testing these flags, and its handler applies parameter pipes when parameter metadata exists. packages/core/helpers/external-context-creator.ts:114-120 packages/core/helpers/external-context-creator.ts:153-162