lib.esnext.disposable.d.ts (6806B)
1 /*! ***************************************************************************** 2 Copyright (c) Microsoft Corporation. All rights reserved. 3 Licensed under the Apache License, Version 2.0 (the "License"); you may not use 4 this file except in compliance with the License. You may obtain a copy of the 5 License at http://www.apache.org/licenses/LICENSE-2.0 6 7 THIS CODE IS PROVIDED ON AN *AS IS* BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 8 KIND, EITHER EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION ANY IMPLIED 9 WARRANTIES OR CONDITIONS OF TITLE, FITNESS FOR A PARTICULAR PURPOSE, 10 MERCHANTABLITY OR NON-INFRINGEMENT. 11 12 See the Apache Version 2.0 License for specific language governing permissions 13 and limitations under the License. 14 ***************************************************************************** */ 15 16 17 /// <reference no-default-lib="true"/> 18 19 /// <reference lib="es2015.symbol" /> 20 /// <reference lib="es2015.iterable" /> 21 /// <reference lib="es2018.asynciterable" /> 22 23 interface SymbolConstructor { 24 /** 25 * A method that is used to release resources held by an object. Called by the semantics of the `using` statement. 26 */ 27 readonly dispose: unique symbol; 28 29 /** 30 * A method that is used to asynchronously release resources held by an object. Called by the semantics of the `await using` statement. 31 */ 32 readonly asyncDispose: unique symbol; 33 } 34 35 interface Disposable { 36 [Symbol.dispose](): void; 37 } 38 39 interface AsyncDisposable { 40 [Symbol.asyncDispose](): PromiseLike<void>; 41 } 42 43 interface SuppressedError extends Error { 44 error: any; 45 suppressed: any; 46 } 47 48 interface SuppressedErrorConstructor { 49 new (error: any, suppressed: any, message?: string): SuppressedError; 50 (error: any, suppressed: any, message?: string): SuppressedError; 51 readonly prototype: SuppressedError; 52 } 53 declare var SuppressedError: SuppressedErrorConstructor; 54 55 interface DisposableStack { 56 /** 57 * Returns a value indicating whether this stack has been disposed. 58 */ 59 readonly disposed: boolean; 60 /** 61 * Disposes each resource in the stack in the reverse order that they were added. 62 */ 63 dispose(): void; 64 /** 65 * Adds a disposable resource to the stack, returning the resource. 66 * @param value The resource to add. `null` and `undefined` will not be added, but will be returned. 67 * @returns The provided {@link value}. 68 */ 69 use<T extends Disposable | null | undefined>(value: T): T; 70 /** 71 * Adds a value and associated disposal callback as a resource to the stack. 72 * @param value The value to add. 73 * @param onDispose The callback to use in place of a `[Symbol.dispose]()` method. Will be invoked with `value` 74 * as the first parameter. 75 * @returns The provided {@link value}. 76 */ 77 adopt<T>(value: T, onDispose: (value: T) => void): T; 78 /** 79 * Adds a callback to be invoked when the stack is disposed. 80 */ 81 defer(onDispose: () => void): void; 82 /** 83 * Move all resources out of this stack and into a new `DisposableStack`, and marks this stack as disposed. 84 * @example 85 * ```ts 86 * class C { 87 * #res1: Disposable; 88 * #res2: Disposable; 89 * #disposables: DisposableStack; 90 * constructor() { 91 * // stack will be disposed when exiting constructor for any reason 92 * using stack = new DisposableStack(); 93 * 94 * // get first resource 95 * this.#res1 = stack.use(getResource1()); 96 * 97 * // get second resource. If this fails, both `stack` and `#res1` will be disposed. 98 * this.#res2 = stack.use(getResource2()); 99 * 100 * // all operations succeeded, move resources out of `stack` so that they aren't disposed 101 * // when constructor exits 102 * this.#disposables = stack.move(); 103 * } 104 * 105 * [Symbol.dispose]() { 106 * this.#disposables.dispose(); 107 * } 108 * } 109 * ``` 110 */ 111 move(): DisposableStack; 112 [Symbol.dispose](): void; 113 readonly [Symbol.toStringTag]: string; 114 } 115 116 interface DisposableStackConstructor { 117 new (): DisposableStack; 118 readonly prototype: DisposableStack; 119 } 120 declare var DisposableStack: DisposableStackConstructor; 121 122 interface AsyncDisposableStack { 123 /** 124 * Returns a value indicating whether this stack has been disposed. 125 */ 126 readonly disposed: boolean; 127 /** 128 * Disposes each resource in the stack in the reverse order that they were added. 129 */ 130 disposeAsync(): Promise<void>; 131 /** 132 * Adds a disposable resource to the stack, returning the resource. 133 * @param value The resource to add. `null` and `undefined` will not be added, but will be returned. 134 * @returns The provided {@link value}. 135 */ 136 use<T extends AsyncDisposable | Disposable | null | undefined>(value: T): T; 137 /** 138 * Adds a value and associated disposal callback as a resource to the stack. 139 * @param value The value to add. 140 * @param onDisposeAsync The callback to use in place of a `[Symbol.asyncDispose]()` method. Will be invoked with `value` 141 * as the first parameter. 142 * @returns The provided {@link value}. 143 */ 144 adopt<T>(value: T, onDisposeAsync: (value: T) => PromiseLike<void> | void): T; 145 /** 146 * Adds a callback to be invoked when the stack is disposed. 147 */ 148 defer(onDisposeAsync: () => PromiseLike<void> | void): void; 149 /** 150 * Move all resources out of this stack and into a new `DisposableStack`, and marks this stack as disposed. 151 * @example 152 * ```ts 153 * class C { 154 * #res1: Disposable; 155 * #res2: Disposable; 156 * #disposables: DisposableStack; 157 * constructor() { 158 * // stack will be disposed when exiting constructor for any reason 159 * using stack = new DisposableStack(); 160 * 161 * // get first resource 162 * this.#res1 = stack.use(getResource1()); 163 * 164 * // get second resource. If this fails, both `stack` and `#res1` will be disposed. 165 * this.#res2 = stack.use(getResource2()); 166 * 167 * // all operations succeeded, move resources out of `stack` so that they aren't disposed 168 * // when constructor exits 169 * this.#disposables = stack.move(); 170 * } 171 * 172 * [Symbol.dispose]() { 173 * this.#disposables.dispose(); 174 * } 175 * } 176 * ``` 177 */ 178 move(): AsyncDisposableStack; 179 [Symbol.asyncDispose](): Promise<void>; 180 readonly [Symbol.toStringTag]: string; 181 } 182 183 interface AsyncDisposableStackConstructor { 184 new (): AsyncDisposableStack; 185 readonly prototype: AsyncDisposableStack; 186 } 187 declare var AsyncDisposableStack: AsyncDisposableStackConstructor; 188 189 interface IteratorObject<T, TReturn, TNext> extends Disposable { 190 } 191 192 interface AsyncIteratorObject<T, TReturn, TNext> extends AsyncDisposable { 193 }