@aws/nx-plugin 0.80.1 → 0.81.0

package/src/trpc/backend/__snapshots__/generator.spec.ts.snap

@@ -376,6 +376,7 @@ import {
 } from 'aws-cdk-lib/aws-iam';
 import { IUserPool } from 'aws-cdk-lib/aws-cognito';
 import {
+  ApiIntegrations,
   IntegrationBuilder,
   RestApiIntegration,
 } from '../../core/api/utils.js';
@@ -392,7 +393,7 @@ type Operations = Procedures<AppRouter>;
  * @template TIntegrations - Map of operation names to their integrations
  */
 export interface TestApiProps<
-  TIntegrations extends Record<Operations, RestApiIntegration>,
+  TIntegrations extends ApiIntegrations<Operations, RestApiIntegration>,
 > {
   /**
    * Map of operation names to their API Gateway integrations
@@ -412,7 +413,7 @@ export interface TestApiProps<
  * @template TIntegrations - Map of operation names to their integrations
  */
 export class TestApi<
-  TIntegrations extends Record<Operations, RestApiIntegration>,
+  TIntegrations extends ApiIntegrations<Operations, RestApiIntegration>,
 > extends RestApi<Operations, TIntegrations> {
   /**
    * Creates default integrations for all operations, which implement each operation as
@@ -423,8 +424,9 @@ export class TestApi<
    */
   public static defaultIntegrations = (scope: Construct) => {
     return IntegrationBuilder.rest({
+      pattern: 'isolated',
       operations: routerToOperations(appRouter),
-      defaultIntegrationOptions: {
+      defaultIntegrationOptions: <FunctionProps>{
         runtime: Runtime.NODEJS_LATEST,
         handler: 'index.handler',
         code: Code.fromAsset(
@@ -440,7 +442,7 @@ export class TestApi<
         environment: {
           AWS_CONNECTION_REUSE_ENABLED: '1',
         },
-      } satisfies FunctionProps,
+      },
       buildDefaultIntegration: (op, props: FunctionProps) => {
         const handler = new Function(scope, \`TestApi\${op}Handler\`, props);
         return {
@@ -565,6 +567,7 @@ import { HttpUserPoolAuthorizer } from 'aws-cdk-lib/aws-apigatewayv2-authorizers
 import { HttpLambdaIntegration } from 'aws-cdk-lib/aws-apigatewayv2-integrations';
 import { IUserPool, IUserPoolClient } from 'aws-cdk-lib/aws-cognito';
 import {
+  ApiIntegrations,
   HttpApiIntegration,
   IntegrationBuilder,
 } from '../../core/api/utils.js';
@@ -581,7 +584,7 @@ type Operations = Procedures<AppRouter>;
  * @template TIntegrations - Map of operation names to their integrations
  */
 export interface TestApiProps<
-  TIntegrations extends Record<Operations, HttpApiIntegration>,
+  TIntegrations extends ApiIntegrations<Operations, HttpApiIntegration>,
 > {
   /**
    * Map of operation names to their API Gateway integrations
@@ -602,7 +605,7 @@ export interface TestApiProps<
  * @template TIntegrations - Map of operation names to their integrations
  */
 export class TestApi<
-  TIntegrations extends Record<Operations, HttpApiIntegration>,
+  TIntegrations extends ApiIntegrations<Operations, HttpApiIntegration>,
 > extends HttpApi<Operations, TIntegrations> {
   /**
    * Creates default integrations for all operations, which implement each operation as
@@ -613,8 +616,9 @@ export class TestApi<
    */
   public static defaultIntegrations = (scope: Construct) => {
     return IntegrationBuilder.http({
+      pattern: 'isolated',
       operations: routerToOperations(appRouter),
-      defaultIntegrationOptions: {
+      defaultIntegrationOptions: <FunctionProps>{
         runtime: Runtime.NODEJS_LATEST,
         handler: 'index.handler',
         code: Code.fromAsset(
@@ -630,7 +634,7 @@ export class TestApi<
         environment: {
           AWS_CONNECTION_REUSE_ENABLED: '1',
         },
-      } satisfies FunctionProps,
+      },
       buildDefaultIntegration: (op, props: FunctionProps) => {
         const handler = new Function(scope, \`TestApi\${op}Handler\`, props);
         return {
@@ -768,6 +772,7 @@ import {
   AnyPrincipal,
 } from 'aws-cdk-lib/aws-iam';
 import {
+  ApiIntegrations,
   IntegrationBuilder,
   RestApiIntegration,
 } from '../../core/api/utils.js';
@@ -784,7 +789,7 @@ type Operations = Procedures<AppRouter>;
  * @template TIntegrations - Map of operation names to their integrations
  */
 export interface TestApiProps<
-  TIntegrations extends Record<Operations, RestApiIntegration>,
+  TIntegrations extends ApiIntegrations<Operations, RestApiIntegration>,
 > {
   /**
    * Map of operation names to their API Gateway integrations
@@ -798,7 +803,7 @@ export interface TestApiProps<
  * @template TIntegrations - Map of operation names to their integrations
  */
 export class TestApi<
-  TIntegrations extends Record<Operations, RestApiIntegration>,
+  TIntegrations extends ApiIntegrations<Operations, RestApiIntegration>,
 > extends RestApi<Operations, TIntegrations> {
   /**
    * Creates default integrations for all operations, which implement each operation as
@@ -809,8 +814,9 @@ export class TestApi<
    */
   public static defaultIntegrations = (scope: Construct) => {
     return IntegrationBuilder.rest({
+      pattern: 'isolated',
       operations: routerToOperations(appRouter),
-      defaultIntegrationOptions: {
+      defaultIntegrationOptions: <FunctionProps>{
         runtime: Runtime.NODEJS_LATEST,
         handler: 'index.handler',
         code: Code.fromAsset(
@@ -826,7 +832,7 @@ export class TestApi<
         environment: {
           AWS_CONNECTION_REUSE_ENABLED: '1',
         },
-      } satisfies FunctionProps,
+      },
       buildDefaultIntegration: (op, props: FunctionProps) => {
         const handler = new Function(scope, \`TestApi\${op}Handler\`, props);
         return {
@@ -946,6 +952,7 @@ import {
 } from 'aws-cdk-lib/aws-apigatewayv2';
 import { HttpLambdaIntegration } from 'aws-cdk-lib/aws-apigatewayv2-integrations';
 import {
+  ApiIntegrations,
   HttpApiIntegration,
   IntegrationBuilder,
 } from '../../core/api/utils.js';
@@ -962,7 +969,7 @@ type Operations = Procedures<AppRouter>;
  * @template TIntegrations - Map of operation names to their integrations
  */
 export interface TestApiProps<
-  TIntegrations extends Record<Operations, HttpApiIntegration>,
+  TIntegrations extends ApiIntegrations<Operations, HttpApiIntegration>,
 > {
   /**
    * Map of operation names to their API Gateway integrations
@@ -976,7 +983,7 @@ export interface TestApiProps<
  * @template TIntegrations - Map of operation names to their integrations
  */
 export class TestApi<
-  TIntegrations extends Record<Operations, HttpApiIntegration>,
+  TIntegrations extends ApiIntegrations<Operations, HttpApiIntegration>,
 > extends HttpApi<Operations, TIntegrations> {
   /**
    * Creates default integrations for all operations, which implement each operation as
@@ -987,8 +994,9 @@ export class TestApi<
    */
   public static defaultIntegrations = (scope: Construct) => {
     return IntegrationBuilder.http({
+      pattern: 'isolated',
       operations: routerToOperations(appRouter),
-      defaultIntegrationOptions: {
+      defaultIntegrationOptions: <FunctionProps>{
         runtime: Runtime.NODEJS_LATEST,
         handler: 'index.handler',
         code: Code.fromAsset(
@@ -1004,7 +1012,7 @@ export class TestApi<
         environment: {
           AWS_CONNECTION_REUSE_ENABLED: '1',
         },
-      } satisfies FunctionProps,
+      },
       buildDefaultIntegration: (op, props: FunctionProps) => {
         const handler = new Function(scope, \`TestApi\${op}Handler\`, props);
         return {
@@ -1090,7 +1098,11 @@ export class TestApi<
 exports[`trpc backend generator > should set up shared constructs for http > http-api.ts 1`] = `
 "import { Construct } from 'constructs';
 import { RuntimeConfig } from '../runtime-config.js';
-import { HttpApiIntegration, OperationDetails } from './utils.js';
+import {
+  ApiIntegrations,
+  HttpApiIntegration,
+  OperationDetails,
+} from './utils.js';
 import { CfnOutput } from 'aws-cdk-lib';
 import {
   HttpApi as _HttpApi,
@@ -1109,7 +1121,7 @@ import { suppressRules } from '../checkov.js';
  * @template TOperation - String literal type representing operation names
  */
 export interface HttpApiProps<
-  TIntegrations extends Record<TOperation, HttpApiIntegration>,
+  TIntegrations extends ApiIntegrations<TOperation, HttpApiIntegration>,
   TOperation extends string,
 > extends _HttpApiProps {
   /**
@@ -1139,7 +1151,7 @@ export interface HttpApiProps<
  */
 export class HttpApi<
   TOperation extends string,
-  TIntegrations extends Record<TOperation, HttpApiIntegration>,
+  TIntegrations extends ApiIntegrations<TOperation, HttpApiIntegration>,
 > extends Construct {
   /** The underlying CDK HttpApi instance */
   public readonly api: _HttpApi;
@@ -1189,16 +1201,32 @@ export class HttpApi<
       },
     });
 
+    // Resolve the integration for a given operation.
+    // If the operation has a dedicated integration, use it; otherwise fall back to $router.
+    const resolveIntegration = (op: TOperation): HttpApiIntegration => {
+      const record = integrations as Record<string, HttpApiIntegration>;
+      if (op in record) {
+        return record[op];
+      }
+      if ('$router' in record) {
+        return record['$router'];
+      }
+      throw new Error(
+        \`No integration found for operation '\${op}' and no $router integration available\`,
+      );
+    };
+
     // Create API resources and methods for each operation
     (Object.entries(operations) as [TOperation, OperationDetails][]).map(
       ([op, details]) => {
+        const integration = resolveIntegration(op);
         this.api.addRoutes({
           path: details.path.startsWith('/')
             ? details.path
             : \`/\${details.path}\`,
           methods: [details.method as HttpMethod],
-          integration: integrations[op].integration,
-          ...integrations[op].options,
+          integration: integration.integration,
+          ...integration.options,
         });
       },
     );
@@ -1241,6 +1269,7 @@ import { HttpIamAuthorizer } from 'aws-cdk-lib/aws-apigatewayv2-authorizers';
 import { HttpLambdaIntegration } from 'aws-cdk-lib/aws-apigatewayv2-integrations';
 import { Grant, IGrantable } from 'aws-cdk-lib/aws-iam';
 import {
+  ApiIntegrations,
   HttpApiIntegration,
   IntegrationBuilder,
 } from '../../core/api/utils.js';
@@ -1257,7 +1286,7 @@ type Operations = Procedures<AppRouter>;
  * @template TIntegrations - Map of operation names to their integrations
  */
 export interface TestApiProps<
-  TIntegrations extends Record<Operations, HttpApiIntegration>,
+  TIntegrations extends ApiIntegrations<Operations, HttpApiIntegration>,
 > {
   /**
    * Map of operation names to their API Gateway integrations
@@ -1271,7 +1300,7 @@ export interface TestApiProps<
  * @template TIntegrations - Map of operation names to their integrations
  */
 export class TestApi<
-  TIntegrations extends Record<Operations, HttpApiIntegration>,
+  TIntegrations extends ApiIntegrations<Operations, HttpApiIntegration>,
 > extends HttpApi<Operations, TIntegrations> {
   /**
    * Creates default integrations for all operations, which implement each operation as
@@ -1282,8 +1311,9 @@ export class TestApi<
    */
   public static defaultIntegrations = (scope: Construct) => {
     return IntegrationBuilder.http({
+      pattern: 'isolated',
       operations: routerToOperations(appRouter),
-      defaultIntegrationOptions: {
+      defaultIntegrationOptions: <FunctionProps>{
         runtime: Runtime.NODEJS_LATEST,
         handler: 'index.handler',
         code: Code.fromAsset(
@@ -1299,7 +1329,7 @@ export class TestApi<
         environment: {
           AWS_CONNECTION_REUSE_ENABLED: '1',
         },
-      } satisfies FunctionProps,
+      },
       buildDefaultIntegration: (op, props: FunctionProps) => {
         const handler = new Function(scope, \`TestApi\${op}Handler\`, props);
         return {
@@ -1518,20 +1548,46 @@ export interface HttpApiIntegration {
 }
 
 /**
- * Options for constructing an IntegrationBuilder
+ * Common options shared by all IntegrationBuilder configurations
  */
-export interface IntegrationBuilderProps<
+interface IntegrationBuilderPropsBase<
   TOperation extends string,
-  TBaseIntegration,
   TDefaultIntegrationProps extends object,
-  TDefaultIntegration extends TBaseIntegration,
 > {
   /** Map of operation names to their API path and HTTP method details */
   operations: Record<TOperation, OperationDetails>;
 
   /** Default configuration options for integrations */
   defaultIntegrationOptions: TDefaultIntegrationProps;
+}
 
+/**
+ * Options for constructing an IntegrationBuilder with a shared integration pattern.
+ * A single default integration is built once (for '$router') and reused for all operations.
+ */
+interface SharedIntegrationBuilderProps<
+  TOperation extends string,
+  TDefaultIntegrationProps extends object,
+  TDefaultIntegration,
+> extends IntegrationBuilderPropsBase<TOperation, TDefaultIntegrationProps> {
+  pattern: 'shared';
+  /** Function to create a default integration for the shared router */
+  buildDefaultIntegration: (
+    op: '$router',
+    props: TDefaultIntegrationProps,
+  ) => TDefaultIntegration;
+}
+
+/**
+ * Options for constructing an IntegrationBuilder with an isolated integration pattern.
+ * A separate default integration is built per operation.
+ */
+interface IsolatedIntegrationBuilderProps<
+  TOperation extends string,
+  TDefaultIntegrationProps extends object,
+  TDefaultIntegration,
+> extends IntegrationBuilderPropsBase<TOperation, TDefaultIntegrationProps> {
+  pattern: 'isolated';
   /** Function to create a default integration for an operation */
   buildDefaultIntegration: (
     op: TOperation,
@@ -1539,6 +1595,71 @@ export interface IntegrationBuilderProps<
   ) => TDefaultIntegration;
 }
 
+/**
+ * Options for constructing an IntegrationBuilder
+ */
+export type IntegrationBuilderProps<
+  TOperation extends string,
+  TBaseIntegration,
+  TDefaultIntegrationProps extends object,
+  TDefaultIntegration extends TBaseIntegration,
+> =
+  | SharedIntegrationBuilderProps<
+      TOperation,
+      TDefaultIntegrationProps,
+      TDefaultIntegration
+    >
+  | IsolatedIntegrationBuilderProps<
+      TOperation,
+      TDefaultIntegrationProps,
+      TDefaultIntegration
+    >;
+
+/**
+ * Extracts the IntegrationBuilderProps variant matching the given pattern.
+ */
+type IntegrationBuilderPropsForPattern<
+  TOperation extends string,
+  TBaseIntegration,
+  TDefaultIntegrationProps extends object,
+  TDefaultIntegration extends TBaseIntegration,
+  TPattern extends 'shared' | 'isolated',
+> = Extract<
+  IntegrationBuilderProps<
+    TOperation,
+    TBaseIntegration,
+    TDefaultIntegrationProps,
+    TDefaultIntegration
+  >,
+  { pattern: TPattern }
+>;
+
+/**
+ * Resolves the default integration keys based on the pattern.
+ * - 'shared': only '$router' is a default key
+ * - 'isolated': all TOperation keys are default keys
+ */
+type DefaultIntegrationKeys<
+  TPattern extends 'shared' | 'isolated',
+  TOperation extends string,
+> = TPattern extends 'shared' ? '$router' : TOperation;
+
+/**
+ * Shared integration record: $router is required, individual operations are optional.
+ */
+type SharedIntegrations<TOperation extends string, TBaseIntegration> = {
+  $router: TBaseIntegration;
+} & Partial<Record<TOperation, TBaseIntegration>>;
+
+/**
+ * Valid integration record types for an API.
+ * Either all operations are provided (isolated), or $router is provided
+ * with optional per-operation overrides (shared).
+ */
+export type ApiIntegrations<TOperation extends string, TBaseIntegration> =
+  | SharedIntegrations<TOperation, TBaseIntegration>
+  | (Record<TOperation, TBaseIntegration> & { $router?: never });
+
 /**
  * A builder class for creating API integrations with flexible configuration options.
  *
@@ -1547,16 +1668,18 @@ export interface IntegrationBuilderProps<
  *
  * @template TOperation - String literal type representing operation names
  * @template TBaseIntegration - Base type for all integrations
- * @template TIntegrations - Record mapping operation names to their integrations
+ * @template TIntegrations - Record mapping integration keys to their integrations
  * @template TDefaultIntegrationProps - Type for default integration properties
  * @template TDefaultIntegration - Type for default integration implementation
+ * @template TPattern - The integration pattern ('shared' or 'isolated')
  */
 export class IntegrationBuilder<
   TOperation extends string,
   TBaseIntegration,
-  TIntegrations extends Record<TOperation, TBaseIntegration>,
+  TIntegrations extends Record<string, TBaseIntegration>,
   TDefaultIntegrationProps extends object,
   TDefaultIntegration extends TBaseIntegration,
+  TPattern extends 'shared' | 'isolated',
 > {
   /** Options for the integration builder */
   private options: IntegrationBuilderProps<
@@ -1574,23 +1697,25 @@ export class IntegrationBuilder<
    */
   public static http = <
     TOperation extends string,
-    TIntegrations extends Record<TOperation, TDefaultIntegration>,
     TDefaultIntegrationProps extends object,
     TDefaultIntegration extends HttpApiIntegration,
+    TPattern extends 'shared' | 'isolated',
   >(
-    options: IntegrationBuilderProps<
+    options: IntegrationBuilderPropsForPattern<
       TOperation,
       HttpApiIntegration,
       TDefaultIntegrationProps,
-      TDefaultIntegration
+      TDefaultIntegration,
+      TPattern
     >,
   ) => {
     return new IntegrationBuilder<
       TOperation,
       HttpApiIntegration,
-      TIntegrations,
+      Record<DefaultIntegrationKeys<TPattern, TOperation>, TDefaultIntegration>,
       TDefaultIntegrationProps,
-      TDefaultIntegration
+      TDefaultIntegration,
+      TPattern
     >(options);
   };
 
@@ -1599,23 +1724,25 @@ export class IntegrationBuilder<
    */
   public static rest = <
     TOperation extends string,
-    TIntegrations extends Record<TOperation, TDefaultIntegration>,
     TDefaultIntegrationProps extends object,
     TDefaultIntegration extends RestApiIntegration,
+    TPattern extends 'shared' | 'isolated',
   >(
-    options: IntegrationBuilderProps<
+    options: IntegrationBuilderPropsForPattern<
       TOperation,
       RestApiIntegration,
       TDefaultIntegrationProps,
-      TDefaultIntegration
+      TDefaultIntegration,
+      TPattern
     >,
   ) => {
     return new IntegrationBuilder<
       TOperation,
       RestApiIntegration,
-      TIntegrations,
+      Record<DefaultIntegrationKeys<TPattern, TOperation>, TDefaultIntegration>,
       TDefaultIntegrationProps,
-      TDefaultIntegration
+      TDefaultIntegration,
+      TPattern
     >(options);
   };
 
@@ -1640,13 +1767,20 @@ export class IntegrationBuilder<
     TOverrideIntegrations extends Partial<Record<TOperation, TBaseIntegration>>,
   >(overrides: TOverrideIntegrations) {
     this.integrations = { ...this.integrations, ...overrides };
-    // Re-type to include the overridden integration types
+    // Re-type to include the overridden integration types.
+    // If all operations are overridden in a 'shared' pattern, drop '$router' from the type.
+    type MergedIntegrations = [TOperation] extends [keyof TOverrideIntegrations]
+      ? Omit<TIntegrations, keyof TOverrideIntegrations | '$router'> &
+          TOverrideIntegrations
+      : Omit<TIntegrations, keyof TOverrideIntegrations> &
+          TOverrideIntegrations;
     return this as unknown as IntegrationBuilder<
       TOperation,
       TBaseIntegration,
-      Omit<TIntegrations, keyof TOverrideIntegrations> & TOverrideIntegrations,
+      MergedIntegrations,
       TDefaultIntegrationProps,
-      TDefaultIntegration
+      TDefaultIntegration,
+      TPattern
     >;
   }
 
@@ -1672,24 +1806,39 @@ export class IntegrationBuilder<
    * 1. Including all custom overrides provided via withOverrides()
    * 2. Creating default integrations for any operations without custom overrides
    *
-   * @returns A complete map of operation names to their integrations
+   * For the 'shared' pattern, a single router integration is built and assigned to '$router'.
+   * For the 'isolated' pattern, each operation without an override gets its own integration.
+   *
+   * @returns A complete map of integration keys to their integrations
    */
   public build(): TIntegrations {
+    const options = this.options;
     return {
-      ...this.integrations,
       ...Object.fromEntries(
-        (Object.keys(this.options.operations) as TOperation[])
-          .filter(
-            (op) => !this.integrations[op as keyof typeof this.integrations],
-          )
-          .map((op) => [
-            op,
-            this.options.buildDefaultIntegration(
-              op,
-              this.options.defaultIntegrationOptions,
-            ),
-          ]),
+        options.pattern === 'shared'
+          ? [
+              [
+                '$router',
+                options.buildDefaultIntegration(
+                  '$router',
+                  options.defaultIntegrationOptions,
+                ),
+              ],
+            ]
+          : (Object.keys(options.operations) as TOperation[])
+              .filter(
+                (op) =>
+                  !this.integrations[op as keyof typeof this.integrations],
+              )
+              .map((op) => [
+                op,
+                options.buildDefaultIntegration(
+                  op,
+                  options.defaultIntegrationOptions,
+                ),
+              ]),
       ),
+      ...this.integrations,
     } as unknown as TIntegrations;
   }
 }
@@ -1705,17 +1854,21 @@ import {
   Stage,
 } from 'aws-cdk-lib/aws-apigateway';
 import { RuntimeConfig } from '../runtime-config.js';
-import { OperationDetails, RestApiIntegration } from './utils.js';
+import {
+  ApiIntegrations,
+  OperationDetails,
+  RestApiIntegration,
+} from './utils.js';
 import { suppressRules } from '../checkov.js';
 
 /**
  * Properties for creating a RestApi construct.
  *
- * @template TIntegrations - Record mapping operation names to their integrations
+ * @template TIntegrations - Record mapping integration keys to their integrations
  * @template TOperation - String literal type representing operation names
  */
 export interface RestApiProps<
-  TIntegrations extends Record<TOperation, RestApiIntegration>,
+  TIntegrations extends ApiIntegrations<TOperation, RestApiIntegration>,
   TOperation extends string,
 > extends _RestApiProps {
   /**
@@ -1727,7 +1880,7 @@ export interface RestApiProps<
    */
   readonly operations: Record<TOperation, OperationDetails>;
   /**
-   * Map of operation names to their API Gateway integrations
+   * Map of integration keys to their API Gateway integrations
    */
   readonly integrations: TIntegrations;
 }
@@ -1741,16 +1894,16 @@ export interface RestApiProps<
  * - Integration with runtime configuration for client discovery
  *
  * @template TOperation - String literal type representing operation names
- * @template TIntegrations - Record mapping operation names to their integrations
+ * @template TIntegrations - Record mapping integration keys to their integrations
  */
 export class RestApi<
   TOperation extends string,
-  TIntegrations extends Record<TOperation, RestApiIntegration>,
+  TIntegrations extends ApiIntegrations<TOperation, RestApiIntegration>,
 > extends Construct {
   /** The underlying CDK RestApi instance */
   public readonly api: _RestApi;
 
-  /** Map of operation names to their API Gateway integrations */
+  /** Map of integration keys to their API Gateway integrations */
   public readonly integrations: TIntegrations;
 
   constructor(
@@ -1782,9 +1935,25 @@ export class RestApi<
       (c) => c instanceof Stage,
     );
 
+    // Resolve the integration for a given operation.
+    // If the operation has a dedicated integration, use it; otherwise fall back to $router.
+    const resolveIntegration = (op: TOperation): RestApiIntegration => {
+      const record = integrations as Record<string, RestApiIntegration>;
+      if (op in record) {
+        return record[op];
+      }
+      if ('$router' in record) {
+        return record['$router'];
+      }
+      throw new Error(
+        \`No integration found for operation '\${op}' and no $router integration available\`,
+      );
+    };
+
     // Create API resources and methods for each operation
     (Object.entries(operations) as [TOperation, OperationDetails][]).map(
       ([op, details]) => {
+        const integration = resolveIntegration(op);
         const resource = this.getOrCreateResource(
           this.api.root,
           (details.path.startsWith('/')
@@ -1794,8 +1963,8 @@ export class RestApi<
         );
         resource.addMethod(
           details.method,
-          integrations[op].integration,
-          integrations[op].options,
+          integration.integration,
+          integration.options,
         );
       },
     );
@@ -1856,6 +2025,7 @@ import {
   Grant,
 } from 'aws-cdk-lib/aws-iam';
 import {
+  ApiIntegrations,
   IntegrationBuilder,
   RestApiIntegration,
 } from '../../core/api/utils.js';
@@ -1872,7 +2042,7 @@ type Operations = Procedures<AppRouter>;
  * @template TIntegrations - Map of operation names to their integrations
  */
 export interface TestApiProps<
-  TIntegrations extends Record<Operations, RestApiIntegration>,
+  TIntegrations extends ApiIntegrations<Operations, RestApiIntegration>,
 > {
   /**
    * Map of operation names to their API Gateway integrations
@@ -1886,7 +2056,7 @@ export interface TestApiProps<
  * @template TIntegrations - Map of operation names to their integrations
  */
 export class TestApi<
-  TIntegrations extends Record<Operations, RestApiIntegration>,
+  TIntegrations extends ApiIntegrations<Operations, RestApiIntegration>,
 > extends RestApi<Operations, TIntegrations> {
   /**
    * Creates default integrations for all operations, which implement each operation as
@@ -1897,8 +2067,9 @@ export class TestApi<
    */
   public static defaultIntegrations = (scope: Construct) => {
     return IntegrationBuilder.rest({
+      pattern: 'isolated',
       operations: routerToOperations(appRouter),
-      defaultIntegrationOptions: {
+      defaultIntegrationOptions: <FunctionProps>{
         runtime: Runtime.NODEJS_LATEST,
         handler: 'index.handler',
         code: Code.fromAsset(
@@ -1914,7 +2085,7 @@ export class TestApi<
         environment: {
           AWS_CONNECTION_REUSE_ENABLED: '1',
         },
-      } satisfies FunctionProps,
+      },
       buildDefaultIntegration: (op, props: FunctionProps) => {
         const handler = new Function(scope, \`TestApi\${op}Handler\`, props);
         return {
@@ -2139,20 +2310,46 @@ export interface HttpApiIntegration {
 }
 
 /**
- * Options for constructing an IntegrationBuilder
+ * Common options shared by all IntegrationBuilder configurations
  */
-export interface IntegrationBuilderProps<
+interface IntegrationBuilderPropsBase<
   TOperation extends string,
-  TBaseIntegration,
   TDefaultIntegrationProps extends object,
-  TDefaultIntegration extends TBaseIntegration,
 > {
   /** Map of operation names to their API path and HTTP method details */
   operations: Record<TOperation, OperationDetails>;
 
   /** Default configuration options for integrations */
   defaultIntegrationOptions: TDefaultIntegrationProps;
+}
 
+/**
+ * Options for constructing an IntegrationBuilder with a shared integration pattern.
+ * A single default integration is built once (for '$router') and reused for all operations.
+ */
+interface SharedIntegrationBuilderProps<
+  TOperation extends string,
+  TDefaultIntegrationProps extends object,
+  TDefaultIntegration,
+> extends IntegrationBuilderPropsBase<TOperation, TDefaultIntegrationProps> {
+  pattern: 'shared';
+  /** Function to create a default integration for the shared router */
+  buildDefaultIntegration: (
+    op: '$router',
+    props: TDefaultIntegrationProps,
+  ) => TDefaultIntegration;
+}
+
+/**
+ * Options for constructing an IntegrationBuilder with an isolated integration pattern.
+ * A separate default integration is built per operation.
+ */
+interface IsolatedIntegrationBuilderProps<
+  TOperation extends string,
+  TDefaultIntegrationProps extends object,
+  TDefaultIntegration,
+> extends IntegrationBuilderPropsBase<TOperation, TDefaultIntegrationProps> {
+  pattern: 'isolated';
   /** Function to create a default integration for an operation */
   buildDefaultIntegration: (
     op: TOperation,
@@ -2160,6 +2357,71 @@ export interface IntegrationBuilderProps<
   ) => TDefaultIntegration;
 }
 
+/**
+ * Options for constructing an IntegrationBuilder
+ */
+export type IntegrationBuilderProps<
+  TOperation extends string,
+  TBaseIntegration,
+  TDefaultIntegrationProps extends object,
+  TDefaultIntegration extends TBaseIntegration,
+> =
+  | SharedIntegrationBuilderProps<
+      TOperation,
+      TDefaultIntegrationProps,
+      TDefaultIntegration
+    >
+  | IsolatedIntegrationBuilderProps<
+      TOperation,
+      TDefaultIntegrationProps,
+      TDefaultIntegration
+    >;
+
+/**
+ * Extracts the IntegrationBuilderProps variant matching the given pattern.
+ */
+type IntegrationBuilderPropsForPattern<
+  TOperation extends string,
+  TBaseIntegration,
+  TDefaultIntegrationProps extends object,
+  TDefaultIntegration extends TBaseIntegration,
+  TPattern extends 'shared' | 'isolated',
+> = Extract<
+  IntegrationBuilderProps<
+    TOperation,
+    TBaseIntegration,
+    TDefaultIntegrationProps,
+    TDefaultIntegration
+  >,
+  { pattern: TPattern }
+>;
+
+/**
+ * Resolves the default integration keys based on the pattern.
+ * - 'shared': only '$router' is a default key
+ * - 'isolated': all TOperation keys are default keys
+ */
+type DefaultIntegrationKeys<
+  TPattern extends 'shared' | 'isolated',
+  TOperation extends string,
+> = TPattern extends 'shared' ? '$router' : TOperation;
+
+/**
+ * Shared integration record: $router is required, individual operations are optional.
+ */
+type SharedIntegrations<TOperation extends string, TBaseIntegration> = {
+  $router: TBaseIntegration;
+} & Partial<Record<TOperation, TBaseIntegration>>;
+
+/**
+ * Valid integration record types for an API.
+ * Either all operations are provided (isolated), or $router is provided
+ * with optional per-operation overrides (shared).
+ */
+export type ApiIntegrations<TOperation extends string, TBaseIntegration> =
+  | SharedIntegrations<TOperation, TBaseIntegration>
+  | (Record<TOperation, TBaseIntegration> & { $router?: never });
+
 /**
  * A builder class for creating API integrations with flexible configuration options.
  *
@@ -2168,16 +2430,18 @@ export interface IntegrationBuilderProps<
  *
  * @template TOperation - String literal type representing operation names
  * @template TBaseIntegration - Base type for all integrations
- * @template TIntegrations - Record mapping operation names to their integrations
+ * @template TIntegrations - Record mapping integration keys to their integrations
  * @template TDefaultIntegrationProps - Type for default integration properties
  * @template TDefaultIntegration - Type for default integration implementation
+ * @template TPattern - The integration pattern ('shared' or 'isolated')
  */
 export class IntegrationBuilder<
   TOperation extends string,
   TBaseIntegration,
-  TIntegrations extends Record<TOperation, TBaseIntegration>,
+  TIntegrations extends Record<string, TBaseIntegration>,
   TDefaultIntegrationProps extends object,
   TDefaultIntegration extends TBaseIntegration,
+  TPattern extends 'shared' | 'isolated',
 > {
   /** Options for the integration builder */
   private options: IntegrationBuilderProps<
@@ -2195,23 +2459,25 @@ export class IntegrationBuilder<
    */
   public static http = <
     TOperation extends string,
-    TIntegrations extends Record<TOperation, TDefaultIntegration>,
     TDefaultIntegrationProps extends object,
     TDefaultIntegration extends HttpApiIntegration,
+    TPattern extends 'shared' | 'isolated',
   >(
-    options: IntegrationBuilderProps<
+    options: IntegrationBuilderPropsForPattern<
       TOperation,
       HttpApiIntegration,
       TDefaultIntegrationProps,
-      TDefaultIntegration
+      TDefaultIntegration,
+      TPattern
     >,
   ) => {
     return new IntegrationBuilder<
       TOperation,
       HttpApiIntegration,
-      TIntegrations,
+      Record<DefaultIntegrationKeys<TPattern, TOperation>, TDefaultIntegration>,
       TDefaultIntegrationProps,
-      TDefaultIntegration
+      TDefaultIntegration,
+      TPattern
     >(options);
   };
 
@@ -2220,23 +2486,25 @@ export class IntegrationBuilder<
    */
   public static rest = <
     TOperation extends string,
-    TIntegrations extends Record<TOperation, TDefaultIntegration>,
     TDefaultIntegrationProps extends object,
     TDefaultIntegration extends RestApiIntegration,
+    TPattern extends 'shared' | 'isolated',
   >(
-    options: IntegrationBuilderProps<
+    options: IntegrationBuilderPropsForPattern<
       TOperation,
       RestApiIntegration,
       TDefaultIntegrationProps,
-      TDefaultIntegration
+      TDefaultIntegration,
+      TPattern
     >,
   ) => {
     return new IntegrationBuilder<
       TOperation,
       RestApiIntegration,
-      TIntegrations,
+      Record<DefaultIntegrationKeys<TPattern, TOperation>, TDefaultIntegration>,
       TDefaultIntegrationProps,
-      TDefaultIntegration
+      TDefaultIntegration,
+      TPattern
     >(options);
   };
 
@@ -2261,13 +2529,20 @@ export class IntegrationBuilder<
     TOverrideIntegrations extends Partial<Record<TOperation, TBaseIntegration>>,
   >(overrides: TOverrideIntegrations) {
     this.integrations = { ...this.integrations, ...overrides };
-    // Re-type to include the overridden integration types
+    // Re-type to include the overridden integration types.
+    // If all operations are overridden in a 'shared' pattern, drop '$router' from the type.
+    type MergedIntegrations = [TOperation] extends [keyof TOverrideIntegrations]
+      ? Omit<TIntegrations, keyof TOverrideIntegrations | '$router'> &
+          TOverrideIntegrations
+      : Omit<TIntegrations, keyof TOverrideIntegrations> &
+          TOverrideIntegrations;
     return this as unknown as IntegrationBuilder<
       TOperation,
       TBaseIntegration,
-      Omit<TIntegrations, keyof TOverrideIntegrations> & TOverrideIntegrations,
+      MergedIntegrations,
       TDefaultIntegrationProps,
-      TDefaultIntegration
+      TDefaultIntegration,
+      TPattern
     >;
   }
 
@@ -2293,24 +2568,39 @@ export class IntegrationBuilder<
    * 1. Including all custom overrides provided via withOverrides()
    * 2. Creating default integrations for any operations without custom overrides
    *
-   * @returns A complete map of operation names to their integrations
+   * For the 'shared' pattern, a single router integration is built and assigned to '$router'.
+   * For the 'isolated' pattern, each operation without an override gets its own integration.
+   *
+   * @returns A complete map of integration keys to their integrations
    */
   public build(): TIntegrations {
+    const options = this.options;
     return {
-      ...this.integrations,
       ...Object.fromEntries(
-        (Object.keys(this.options.operations) as TOperation[])
-          .filter(
-            (op) => !this.integrations[op as keyof typeof this.integrations],
-          )
-          .map((op) => [
-            op,
-            this.options.buildDefaultIntegration(
-              op,
-              this.options.defaultIntegrationOptions,
-            ),
-          ]),
+        options.pattern === 'shared'
+          ? [
+              [
+                '$router',
+                options.buildDefaultIntegration(
+                  '$router',
+                  options.defaultIntegrationOptions,
+                ),
+              ],
+            ]
+          : (Object.keys(options.operations) as TOperation[])
+              .filter(
+                (op) =>
+                  !this.integrations[op as keyof typeof this.integrations],
+              )
+              .map((op) => [
+                op,
+                options.buildDefaultIntegration(
+                  op,
+                  options.defaultIntegrationOptions,
+                ),
+              ]),
       ),
+      ...this.integrations,
     } as unknown as TIntegrations;
   }
 }