Support using and await using declarations (#54505)

Author: rbuckton

src/compiler/_namespaces/ts.ts

@@ -33,6 +33,8 @@ export * from "../visitorPublic";
 export * from "../sourcemap";
 export * from "../transformers/utilities";
 export * from "../transformers/destructuring";
+export * from "../transformers/classThis";
+export * from "../transformers/namedEvaluation";
 export * from "../transformers/taggedTemplate";
 export * from "../transformers/ts";
 export * from "../transformers/classFields";

src/compiler/binder.ts

@@ -3727,7 +3727,7 @@ function isExecutableStatement(s: Statement): boolean {
     // Don't remove statements that can validly be used before they appear.
     return !isFunctionDeclaration(s) && !isPurelyTypeDeclaration(s) && !isEnumDeclaration(s) &&
         // `var x;` may declare a variable used above
-        !(isVariableStatement(s) && !(getCombinedNodeFlags(s) & (NodeFlags.Let | NodeFlags.Const)) && s.declarationList.declarations.some(d => !d.initializer));
+        !(isVariableStatement(s) && !(getCombinedNodeFlags(s) & (NodeFlags.BlockScoped)) && s.declarationList.declarations.some(d => !d.initializer));
 }
 
 function isPurelyTypeDeclaration(s: Statement): boolean {

src/compiler/checker.ts

@@ -218,6 +218,7 @@ const libEntries: [string, string][] = [
     ["esnext.symbol", "lib.es2019.symbol.d.ts"],
     ["esnext.asynciterable", "lib.es2018.asynciterable.d.ts"],
     ["esnext.intl", "lib.esnext.intl.d.ts"],
+    ["esnext.disposable", "lib.esnext.disposable.d.ts"],
     ["esnext.bigint", "lib.es2020.bigint.d.ts"],
     ["esnext.string", "lib.es2022.string.d.ts"],
     ["esnext.promise", "lib.es2021.promise.d.ts"],

src/compiler/commandLineParser.ts

@@ -451,18 +451,14 @@
         "category": "Error",
         "code": 1149
     },
-    "'const' declarations must be initialized.": {
+    "'{0}' declarations must be initialized.": {
         "category": "Error",
         "code": 1155
     },
-    "'const' declarations can only be declared inside a block.": {
+    "'{0}' declarations can only be declared inside a block.": {
         "category": "Error",
         "code": 1156
     },
-    "'let' declarations can only be declared inside a block.": {
-        "category": "Error",
-        "code": 1157
-    },
     "Unterminated template literal.": {
         "category": "Error",
         "code": 1160
@@ -1601,6 +1597,26 @@
         "category": "Error",
         "code": 1490
     },
+    "'{0}' modifier cannot appear on a 'using' declaration.": {
+        "category": "Error",
+        "code": 1491
+    },
+    "'{0}' declarations may not have binding patterns.": {
+        "category": "Error",
+        "code": 1492
+    },
+    "The left-hand side of a 'for...in' statement cannot be a 'using' declaration.": {
+        "category": "Error",
+        "code": 1493
+    },
+    "The left-hand side of a 'for...in' statement cannot be an 'await using' declaration.": {
+        "category": "Error",
+        "code": 1494
+    },
+    "'{0}' modifier cannot appear on an 'await using' declaration.": {
+        "category": "Error",
+        "code": 1495
+    },
 
     "The types of '{0}' are incompatible between these types.": {
         "category": "Error",
@@ -3623,6 +3639,26 @@
         "category": "Error",
         "code": 2849
     },
+    "The initializer of a 'using' declaration must be either an object with a '[Symbol.dispose]()' method, or be 'null' or 'undefined'.": {
+        "category": "Error",
+        "code": 2850
+    },
+    "The initializer of an 'await using' declaration must be either an object with a '[Symbol.asyncDispose]()' or '[Symbol.dispose]()' method, or be 'null' or 'undefined'.": {
+        "category": "Error",
+        "code": 2851
+    },
+    "'await using' statements are only allowed within async functions and at the top levels of modules.": {
+        "category": "Error",
+        "code": 2852
+    },
+    "'await using' statements are only allowed at the top level of a file when that file is a module, but this file has no imports or exports. Consider adding an empty 'export {}' to make this file a module.": {
+        "category": "Error",
+        "code": 2853
+    },
+    "Top-level 'await using' statements are only allowed when the 'module' option is set to 'es2022', 'esnext', 'system', 'node16', or 'nodenext', and the 'target' option is set to 'es2017' or higher.": {
+        "category": "Error",
+        "code": 2854
+    },
 
     "Import declaration '{0}' is using private name '{1}'.": {
         "category": "Error",
@@ -7757,11 +7793,11 @@
         "category": "Error",
         "code": 18036
     },
-    "Await expression cannot be used inside a class static block.": {
+    "'await' expression cannot be used inside a class static block.": {
         "category": "Error",
         "code": 18037
     },
-    "'For await' loops cannot be used inside a class static block.": {
+    "'for await' loops cannot be used inside a class static block.": {
         "category": "Error",
         "code": 18038
     },
@@ -7820,5 +7856,9 @@
     "Its type '{0}' is not a valid JSX element type.": {
         "category": "Error",
         "code": 18053
+    },
+    "'await using' statements cannot be used inside a class static block.": {
+        "category": "Error",
+        "code": 18054
     }
 }

src/compiler/diagnosticMessages.json

@@ -254,8 +254,10 @@ import {
     isUnparsedNode,
     isUnparsedPrepend,
     isUnparsedSource,
+    isVarAwaitUsing,
     isVarConst,
     isVariableStatement,
+    isVarUsing,
     JSDoc,
     JSDocAugmentsTag,
     JSDocCallbackTag,
@@ -3685,7 +3687,18 @@ export function createPrinter(printerOptions: PrinterOptions = {}, handlers: Pri
     }
 
     function emitVariableDeclarationList(node: VariableDeclarationList) {
-        writeKeyword(isLet(node) ? "let" : isVarConst(node) ? "const" : "var");
+        if (isVarAwaitUsing(node)) {
+            writeKeyword("await");
+            writeSpace();
+            writeKeyword("using");
+        }
+        else {
+            const head = isLet(node) ? "let" :
+                isVarConst(node) ? "const" :
+                isVarUsing(node) ? "using" :
+                "var";
+            writeKeyword(head);
+        }
         writeSpace();
         emitList(node, node.declarations, ListFormat.VariableDeclarationList);
     }

src/compiler/emitter.ts

@@ -136,6 +136,9 @@ export interface EmitHelperFactory {
     createClassPrivateFieldGetHelper(receiver: Expression, state: Identifier, kind: PrivateIdentifierKind, f: Identifier | undefined): Expression;
     createClassPrivateFieldSetHelper(receiver: Expression, state: Identifier, value: Expression, kind: PrivateIdentifierKind, f: Identifier | undefined): Expression;
     createClassPrivateFieldInHelper(state: Identifier, receiver: Expression): Expression;
+    // 'using' helpers
+    createAddDisposableResourceHelper(envBinding: Expression, value: Expression, async: boolean): Expression;
+    createDisposeResourcesHelper(envBinding: Expression): Expression;
 }
 
 /** @internal */
@@ -183,7 +186,10 @@ export function createEmitHelperFactory(context: TransformationContext): EmitHel
         // Class Fields Helpers
         createClassPrivateFieldGetHelper,
         createClassPrivateFieldSetHelper,
-        createClassPrivateFieldInHelper
+        createClassPrivateFieldInHelper,
+        // 'using' helpers
+        createAddDisposableResourceHelper,
+        createDisposeResourcesHelper,
     };
 
     /**
@@ -666,6 +672,20 @@ export function createEmitHelperFactory(context: TransformationContext): EmitHel
         context.requestEmitHelper(classPrivateFieldInHelper);
         return factory.createCallExpression(getUnscopedHelperName("__classPrivateFieldIn"), /*typeArguments*/ undefined, [state, receiver]);
     }
+
+    function createAddDisposableResourceHelper(envBinding: Expression, value: Expression, async: boolean): Expression {
+        context.requestEmitHelper(addDisposableResourceHelper);
+        return factory.createCallExpression(
+            getUnscopedHelperName("__addDisposableResource"),
+            /*typeArguments*/ undefined,
+            [envBinding, value, async ? factory.createTrue() : factory.createFalse()]
+        );
+    }
+
+    function createDisposeResourcesHelper(envBinding: Expression) {
+        context.requestEmitHelper(disposeResourcesHelper);
+        return factory.createCallExpression(getUnscopedHelperName("__disposeResources"), /*typeArguments*/ undefined, [envBinding]);
+    }
 }
 
 /** @internal */
@@ -1367,6 +1387,71 @@ export const classPrivateFieldInHelper: UnscopedEmitHelper = {
             };`
 };
 
+/**
+ * @internal
+ */
+export const addDisposableResourceHelper: UnscopedEmitHelper = {
+    name: "typescript:addDisposableResource",
+    importName: "__addDisposableResource",
+    scoped: false,
+    text: `
+        var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+            if (value !== null && value !== void 0) {
+                if (typeof value !== "object") throw new TypeError("Object expected.");
+                var dispose;
+                if (async) {
+                    if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+                    dispose = value[Symbol.asyncDispose];
+                }
+                if (dispose === void 0) {
+                    if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+                    dispose = value[Symbol.dispose];
+                }
+                if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+                env.stack.push({ value: value, dispose: dispose, async: async });
+            }
+            else if (async) {
+                env.stack.push({ async: true });
+            }
+            return value;
+        };`
+};
+
+/**
+ * @internal
+ */
+export const disposeResourcesHelper: UnscopedEmitHelper = {
+    name: "typescript:disposeResources",
+    importName: "__disposeResources",
+    scoped: false,
+    text: `
+        var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+            return function (env) {
+                function fail(e) {
+                    env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+                    env.hasError = true;
+                }
+                function next() {
+                    while (env.stack.length) {
+                        var rec = env.stack.pop();
+                        try {
+                            var result = rec.dispose && rec.dispose.call(rec.value);
+                            if (rec.async) return Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                        }
+                        catch (e) {
+                            fail(e);
+                        }
+                    }
+                    if (env.hasError) throw env.error;
+                }
+                return next();
+            };
+        })(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+            var e = new Error(message);
+            return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+        });`
+};
+
 let allUnscopedEmitHelpers: ReadonlyMap<string, UnscopedEmitHelper> | undefined;
 
 /** @internal */
@@ -1399,7 +1484,9 @@ export function getAllUnscopedEmitHelpers() {
         classPrivateFieldSetHelper,
         classPrivateFieldInHelper,
         createBindingHelper,
-        setModuleDefaultHelper
+        setModuleDefaultHelper,
+        addDisposableResourceHelper,
+        disposeResourcesHelper,
     ], helper => helper.name));
 }
 

src/compiler/factory/emitHelpers.ts

@@ -6,6 +6,7 @@ import {
     BindingOrAssignmentPattern,
     Block,
     cast,
+    ClassDeclaration,
     ConciseBody,
     Debug,
     Expression,
@@ -17,6 +18,8 @@ import {
     isBindingElement,
     isBindingPattern,
     isBlock,
+    isDefaultModifier,
+    isExportModifier,
     isExpression,
     isIdentifier,
     isObjectBindingPattern,
@@ -39,6 +42,7 @@ export function createNodeConverters(factory: NodeFactory): NodeConverters {
     return {
         convertToFunctionBlock,
         convertToFunctionExpression,
+        convertToClassExpression,
         convertToArrayAssignmentElement,
         convertToObjectAssignmentElement,
         convertToAssignmentPattern,
@@ -59,7 +63,7 @@ export function createNodeConverters(factory: NodeFactory): NodeConverters {
     function convertToFunctionExpression(node: FunctionDeclaration) {
         if (!node.body) return Debug.fail(`Cannot convert a FunctionDeclaration without a body`);
         const updated = factory.createFunctionExpression(
-            getModifiers(node),
+            getModifiers(node)?.filter(modifier => !isExportModifier(modifier) && !isDefaultModifier(modifier)),
             node.asteriskToken,
             node.name,
             node.typeParameters,
@@ -75,6 +79,22 @@ export function createNodeConverters(factory: NodeFactory): NodeConverters {
         return updated;
     }
 
+    function convertToClassExpression(node: ClassDeclaration) {
+        const updated = factory.createClassExpression(
+            node.modifiers?.filter(modifier => !isExportModifier(modifier) && !isDefaultModifier(modifier)),
+            node.name,
+            node.typeParameters,
+            node.heritageClauses,
+            node.members
+        );
+        setOriginalNode(updated, node);
+        setTextRange(updated, node);
+        if (getStartsOnNewLine(node)) {
+            setStartsOnNewLine(updated, /*newLine*/ true);
+        }
+        return updated;
+    }
+
     function convertToArrayAssignmentElement(element: ArrayBindingOrAssignmentElement) {
         if (isBindingElement(element)) {
             if (element.dotDotDotToken) {
@@ -163,6 +183,7 @@ export function createNodeConverters(factory: NodeFactory): NodeConverters {
 export const nullNodeConverters: NodeConverters = {
     convertToFunctionBlock: notImplemented,
     convertToFunctionExpression: notImplemented,
+    convertToClassExpression: notImplemented,
     convertToArrayAssignmentElement: notImplemented,
     convertToObjectAssignmentElement: notImplemented,
     convertToAssignmentPattern: notImplemented,