aws-cdk 2.1138.0 → 2.1140.0

package/lib/cli/io-host/cli-io-host.d.ts

@@ -146,6 +146,24 @@ export type MessageListenerResultOrPromise = void | MessageListenerResult | Prom
  * of codes, or on the message level).
  */
 export type MessageSelector<T> = IoMessageMaker<T> | IoRequestMaker<T, any> | ((msg: IoMessage<any>) => boolean);
+/**
+ * Removes a previously registered message listener.
+ *
+ * Callable directly (`dispose()`), and also a `Disposable`, so it can be bound
+ * to the enclosing scope with a `using` declaration — the listener is then
+ * removed when the scope exits, even on an early return or a throw:
+ *
+ * ```ts
+ * using _fmt = ioHost.rewrite(IO.CDK_TOOLKIT_I2901, format);
+ * ```
+ *
+ * `using x = cond ? ioHost.on(...) : undefined` is also valid: disposal is
+ * simply skipped for `undefined`, which makes conditional listeners cheap.
+ */
+export interface DisposeListener {
+    (): void;
+    [Symbol.dispose](): void;
+}
 /**
  * How an IoHost processed a single message or request.
  *
@@ -301,8 +319,8 @@ export declare class CliIoHost implements IIoHost, ObservableIoHost {
      * // Match with a custom predicate instead of a code, e.g. a maker's `.is`:
      * const dispose = ioHost.on(IO.CDK_TOOLKIT_I7010.is, (msg) => ({ respond: true }));
      */
-    on<T>(selector: IoMessageMaker<T> | IoRequestMaker<T, any> | ((msg: IoMessage<any>) => msg is IoMessage<T>), listener: (msg: IoMessage<T>) => MessageListenerResultOrPromise): () => void;
-    on(predicate: (msg: IoMessage<any>) => boolean, listener: (msg: IoMessage<unknown>) => MessageListenerResultOrPromise): () => void;
+    on<T>(selector: IoMessageMaker<T> | IoRequestMaker<T, any> | ((msg: IoMessage<any>) => msg is IoMessage<T>), listener: (msg: IoMessage<T>) => MessageListenerResultOrPromise): DisposeListener;
+    on(predicate: (msg: IoMessage<any>) => boolean, listener: (msg: IoMessage<unknown>) => MessageListenerResultOrPromise): DisposeListener;
     /**
      * Register an observer that is invoked for every message the host handles —
      * both notifications and requests — with the disposition the host computed
@@ -317,8 +335,8 @@ export declare class CliIoHost implements IIoHost, ObservableIoHost {
      * Like `on`, but the listener is automatically removed after it has been
      * invoked once.
      */
-    once<T>(selector: IoMessageMaker<T> | IoRequestMaker<T, any> | ((msg: IoMessage<any>) => msg is IoMessage<T>), listener: (msg: IoMessage<T>) => MessageListenerResultOrPromise): () => void;
-    once(predicate: (msg: IoMessage<any>) => boolean, listener: (msg: IoMessage<unknown>) => MessageListenerResultOrPromise): () => void;
+    once<T>(selector: IoMessageMaker<T> | IoRequestMaker<T, any> | ((msg: IoMessage<any>) => msg is IoMessage<T>), listener: (msg: IoMessage<T>) => MessageListenerResultOrPromise): DisposeListener;
+    once(predicate: (msg: IoMessage<any>) => boolean, listener: (msg: IoMessage<unknown>) => MessageListenerResultOrPromise): DisposeListener;
     /**
      * Remove every message listener registered via `on`/`once`/`rewrite`/`respond`.
      *
@@ -346,11 +364,11 @@ export declare class CliIoHost implements IIoHost, ObservableIoHost {
      * // Under --force, auto-confirm the destroy prompt without prompting.
      * const dispose = ioHost.respond(IO.CDK_TOOLKIT_I7010, true);
      */
-    respond<T, U>(code: IoRequestMaker<T, U>, value: U, suppressQuestion?: boolean): () => void;
+    respond<T, U>(code: IoRequestMaker<T, U>, value: U, suppressQuestion?: boolean): DisposeListener;
     /**
      * Like `respond`, but the answer is given only once and then removed.
      */
-    respondOnce<T, U>(code: IoRequestMaker<T, U>, value: U, suppressQuestion?: boolean): () => void;
+    respondOnce<T, U>(code: IoRequestMaker<T, U>, value: U, suppressQuestion?: boolean): DisposeListener;
     /**
      * Register a formatter that replaces the printed text of messages with the
      * given code. This lets a caller define _how_ a toolkit message is presented
@@ -367,14 +385,15 @@ export declare class CliIoHost implements IIoHost, ObservableIoHost {
      * const dispose = ioHost.rewrite(IO.CDK_TOOLKIT_I2901, (msg) =>
      *   serializeStructure(msg.data.stacks, true));
      */
-    rewrite<T>(code: IoMessageMaker<T> | IoRequestMaker<T, any>, formatter: (msg: IoMessage<T>) => string, level?: IoMessageLevel): () => void;
+    rewrite<T>(code: IoMessageMaker<T> | IoRequestMaker<T, any>, formatter: (msg: IoMessage<T>) => string, level?: IoMessageLevel): DisposeListener;
     /**
      * Like `rewrite`, but the formatter is automatically removed after it has
      * been applied once.
      */
-    rewriteOnce<T>(code: IoMessageMaker<T> | IoRequestMaker<T, any>, formatter: (msg: IoMessage<T>) => string, level?: IoMessageLevel): () => void;
+    rewriteOnce<T>(code: IoMessageMaker<T> | IoRequestMaker<T, any>, formatter: (msg: IoMessage<T>) => string, level?: IoMessageLevel): DisposeListener;
     /**
-     * Add a listener to the registry and return a function that removes it.
+     * Add a listener to the registry and return a remover for it (callable and
+     * `using`-compatible, see `DisposeListener`).
      */
     private addMessageListener;
     /**
@@ -472,3 +491,26 @@ export declare class CliIoHost implements IIoHost, ObservableIoHost {
  * `ioHost.on(matchAny(IO.CDK_TOOLKIT_I5501, IO.CDK_TOOLKIT_I5502), listener)`.
  */
 export declare function matchAny(...selectors: MessageSelector<any>[]): (msg: IoMessage<unknown>) => boolean;
+/**
+ * Method decorator that suppresses the given IoHost messages for the duration
+ * of the decorated method.
+ *
+ * Before the method runs, a single `preventDefault` listener covering all
+ * given selectors is registered on the instance's `ioHost`; when the method
+ * settles (returns or throws), exactly that listener is removed again. This
+ * replaces the manual pattern of registering drop-listeners at the top of a
+ * method and cleaning them up in a `finally`, and — unlike a blanket
+ * `removeAllListeners()` — it does not disturb listeners registered elsewhere.
+ *
+ * The decorated method must be async and live on a class whose instances carry
+ * the `CliIoHost` on an `ioHost` property (like `CdkToolkit`).
+ *
+ * @example
+ * class CdkToolkit {
+ *   \@suppressMessages(IO.CDK_TOOLKIT_I1001, IO.CDK_TOOLKIT_I1000)
+ *   public async metadata(stackName: string, json: boolean) {
+ *     // I1001/I1000 are dropped while this runs
+ *   }
+ * }
+ */
+export declare function suppressMessages(...selectors: MessageSelector<any>[]): <A extends any[], R>(_target: object, _propertyKey: string | symbol, descriptor: TypedPropertyDescriptor<(...args: A) => Promise<R>>) => void;