# ExternalContextOptions

**Kind:** Interface

**Source:** [`packages/core/helpers/external-context-creator.ts`](https://github.com/nestjs/nest/blob/master/packages/core/helpers/external-context-creator.ts#L32)

**Part of:** [Core](subsystem-packages-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

| Property | Type |
|---|---|
| `guards` | `boolean` |
| `interceptors` | `boolean` |
| `filters` | `boolean` |

## 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#L32-L36) [packages/core/helpers/external-context-creator.ts:91-108](packages/core/helpers/external-context-creator.ts#L91-L108)

- When `options` is omitted, `create()` defaults all three fields to `true`. [packages/core/helpers/external-context-creator.ts:102-106](packages/core/helpers/external-context-creator.ts#L102-L106)
- `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#L150-L152) [packages/core/helpers/external-context-creator.ts:164-167](packages/core/helpers/external-context-creator.ts#L164-L167)
  - When enabled and guards exist, failed guard activation throws `ForbiddenException` with `FORBIDDEN_MESSAGE`. [packages/core/helpers/external-context-creator.ts:338-357](packages/core/helpers/external-context-creator.ts#L338-L357)
- `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#L135-L143) [packages/core/helpers/external-context-creator.ts:168-175](packages/core/helpers/external-context-creator.ts#L168-L175)
- `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](packages/core/helpers/external-context-creator.ts#L178-L184)
  - 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](packages/core/helpers/external-proxy.ts#L11-L18)

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#L114-L120) [packages/core/helpers/external-context-creator.ts:153-162](packages/core/helpers/external-context-creator.ts#L153-L162)