@aws/nx-plugin 0.80.1 → 0.81.0

package/src/py/fast-api/__snapshots__/generator.spec.ts.snap

@@ -246,7 +246,11 @@ def test_main():
 exports[`fastapi project 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,
@@ -265,7 +269,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 {
   /**
@@ -295,7 +299,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;
@@ -345,16 +349,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,
         });
       },
     );
@@ -399,6 +419,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';
@@ -414,7 +435,7 @@ import {
  * @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
@@ -428,7 +449,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
@@ -439,8 +460,9 @@ export class TestApi<
    */
   public static defaultIntegrations = (scope: Construct) => {
     return IntegrationBuilder.http({
+      pattern: 'isolated',
       operations: OPERATION_DETAILS,
-      defaultIntegrationOptions: {
+      defaultIntegrationOptions: <FunctionProps>{
         runtime: Runtime.PYTHON_3_12,
         handler: 'run.sh',
         code: Code.fromAsset(
@@ -460,7 +482,7 @@ export class TestApi<
           AWS_LWA_INVOKE_MODE: 'buffered',
           AWS_LAMBDA_EXEC_WRAPPER: '/opt/bootstrap',
         },
-      } satisfies FunctionProps,
+      },
       buildDefaultIntegration: (op, props: FunctionProps) => {
         const handler = new Function(scope, \`TestApi\${op}Handler\`, props);
         const stack = Stack.of(scope);
@@ -616,20 +638,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,
@@ -637,6 +685,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.
  *
@@ -645,16 +758,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<
@@ -672,23 +787,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);
   };
 
@@ -697,23 +814,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);
   };
 
@@ -738,13 +857,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
     >;
   }
 
@@ -770,24 +896,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;
   }
 }
@@ -803,17 +944,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 {
   /**
@@ -825,7 +970,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;
 }
@@ -839,16 +984,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(
@@ -880,9 +1025,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('/')
@@ -892,8 +1053,8 @@ export class RestApi<
         );
         resource.addMethod(
           details.method,
-          integrations[op].integration,
-          integrations[op].options,
+          integration.integration,
+          integration.options,
         );
       },
     );
@@ -956,6 +1117,7 @@ import {
   Grant,
 } from 'aws-cdk-lib/aws-iam';
 import {
+  ApiIntegrations,
   IntegrationBuilder,
   RestApiIntegration,
 } from '../../core/api/utils.js';
@@ -971,7 +1133,7 @@ import {
  * @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
@@ -985,7 +1147,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
@@ -996,8 +1158,9 @@ export class TestApi<
    */
   public static defaultIntegrations = (scope: Construct) => {
     return IntegrationBuilder.rest({
+      pattern: 'isolated',
       operations: OPERATION_DETAILS,
-      defaultIntegrationOptions: {
+      defaultIntegrationOptions: <FunctionProps>{
         runtime: Runtime.PYTHON_3_12,
         handler: 'run.sh',
         code: Code.fromAsset(
@@ -1017,7 +1180,7 @@ export class TestApi<
           AWS_LWA_INVOKE_MODE: 'response_stream',
           AWS_LAMBDA_EXEC_WRAPPER: '/opt/bootstrap',
         },
-      } satisfies FunctionProps,
+      },
       buildDefaultIntegration: (op, props: FunctionProps) => {
         const handler = new Function(scope, \`TestApi\${op}Handler\`, props);
         const stack = Stack.of(scope);
@@ -1179,20 +1342,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,
@@ -1200,6 +1389,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.
  *
@@ -1208,16 +1462,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<
@@ -1235,23 +1491,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);
   };
 
@@ -1260,23 +1518,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);
   };
 
@@ -1301,13 +1561,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
     >;
   }
 
@@ -1333,24 +1600,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;
   }
 }