@aws/nx-plugin 0.80.1 → 0.81.0

package/src/utils/api-constructs/files/cdk/core/api/utils/utils.ts.template

@@ -46,20 +46,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,
@@ -67,6 +93,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.
  *
@@ -75,16 +166,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<
@@ -102,23 +195,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);
   };
 
@@ -127,23 +222,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);
   };
 
@@ -168,13 +265,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
     >;
   }
 
@@ -200,24 +304,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;
   }
 }