LibJS: Add using declaration support, RAII like operation in js

In this patch only top level and not the more complicated for loop using
statements are supported. Also, as noted in the latest meeting of tc39
async parts of the spec are not stage 3 thus not included.

3 files changed, 404 insertions, 0 deletions

diff --git a/Userland/Libraries/LibJS/Tests/modules/basic-modules.js b/Userland/Libraries/LibJS/Tests/modules/basic-modules.js
index 769356aabe..8df534cd3a 100644
--- a/Userland/Libraries/LibJS/Tests/modules/basic-modules.js
+++ b/Userland/Libraries/LibJS/Tests/modules/basic-modules.js
@@ -206,6 +206,10 @@ describe("in- and exports", () => {
     test("exporting anonymous function", () => {
         expectModulePassed("./anon-func-decl-default-export.mjs");
     });
+
+    test("can have top level using declarations which trigger at the end of running a module", () => {
+        expectModulePassed("./top-level-dispose.mjs");
+    });
 });
 
 describe("loops", () => {
diff --git a/Userland/Libraries/LibJS/Tests/modules/top-level-dispose.mjs b/Userland/Libraries/LibJS/Tests/modules/top-level-dispose.mjs
new file mode 100644
index 0000000000..16678db0ff
--- /dev/null
+++ b/Userland/Libraries/LibJS/Tests/modules/top-level-dispose.mjs
@@ -0,0 +1,14 @@
+export let passed = false;
+let failed = false;
+
+if (passed)
+    failed = true;
+
+using a = { [Symbol.dispose]() { if (!failed) passed = true; } }
+
+if (passed)
+    failed = true;
+
+failed = true;
+// Should trigger before
+using b = { [Symbol.dispose]() { if (!passed) failed = false; } }
diff --git a/Userland/Libraries/LibJS/Tests/using-declaration.js b/Userland/Libraries/LibJS/Tests/using-declaration.js
new file mode 100644
index 0000000000..588683e1ee
--- /dev/null
+++ b/Userland/Libraries/LibJS/Tests/using-declaration.js
@@ -0,0 +1,386 @@
+describe("basic usage", () => {
+    test("disposes after block exit", () => {
+        let disposed = false;
+        let inBlock = false;
+        {
+            expect(disposed).toBeFalse();
+            using a = { [Symbol.dispose]() { disposed = true; } };
+            inBlock = true;
+            expect(disposed).toBeFalse();
+        }
+
+        expect(inBlock).toBeTrue();
+        expect(disposed).toBeTrue();
+    });
+
+    test("disposes in reverse order after block exit", () => {
+        const disposed = [];
+        {
+            expect(disposed).toHaveLength(0);
+            using a = { [Symbol.dispose]() { disposed.push('a'); } };
+            using b = { [Symbol.dispose]() { disposed.push('b'); } };
+            expect(disposed).toHaveLength(0);
+        }
+
+        expect(disposed).toEqual(['b', 'a']);
+    });
+
+    test("disposes in reverse order after block exit even in same declaration", () => {
+        const disposed = [];
+        {
+            expect(disposed).toHaveLength(0);
+            using a = { [Symbol.dispose]() { disposed.push('a'); } },
+                  b = { [Symbol.dispose]() { disposed.push('b'); } };
+            expect(disposed).toHaveLength(0);
+        }
+
+        expect(disposed).toEqual(['b', 'a']);
+    });
+});
+
+describe("behavior with exceptions", () => {
+    function ExpectedError(name) { this.name = name; }
+
+    test("is run even after throw", () => {
+        let disposed = false;
+        let inBlock = false;
+        let inCatch = false;
+        try {
+            expect(disposed).toBeFalse();
+            using a = { [Symbol.dispose]() { disposed = true; } };
+            inBlock = true;
+            expect(disposed).toBeFalse();
+            throw new ExpectedError();
+            expect().fail();
+        } catch (e) {
+            expect(disposed).toBeTrue();
+            expect(e).toBeInstanceOf(ExpectedError);
+            inCatch = true;
+        }
+        expect(disposed).toBeTrue();
+        expect(inBlock).toBeTrue();
+        expect(inCatch).toBeTrue();
+    });
+
+    test("throws error if dispose method does", () => {
+        let disposed = false;
+        let endOfTry = false;
+        let inCatch = false;
+        try {
+            expect(disposed).toBeFalse();
+            using a = { [Symbol.dispose]() {
+                    disposed = true;
+                    throw new ExpectedError();
+                } };
+            expect(disposed).toBeFalse();
+            endOfTry = true;
+        } catch (e) {
+            expect(disposed).toBeTrue();
+            expect(e).toBeInstanceOf(ExpectedError);
+            inCatch = true;
+        }
+        expect(disposed).toBeTrue();
+        expect(endOfTry).toBeTrue();
+        expect(inCatch).toBeTrue();
+    });
+
+    test("if block and using throw get suppressed error", () => {
+        let disposed = false;
+        let inCatch = false;
+        try {
+            expect(disposed).toBeFalse();
+            using a = { [Symbol.dispose]() {
+                    disposed = true;
+                    throw new ExpectedError('dispose');
+                } };
+            expect(disposed).toBeFalse();
+            throw new ExpectedError('throw');
+        } catch (e) {
+            expect(disposed).toBeTrue();
+            expect(e).toBeInstanceOf(SuppressedError);
+            expect(e.error).toBeInstanceOf(ExpectedError);
+            expect(e.error.name).toBe('dispose');
+            expect(e.suppressed).toBeInstanceOf(ExpectedError);
+            expect(e.suppressed.name).toBe('throw');
+            inCatch = true;
+        }
+        expect(disposed).toBeTrue();
+        expect(inCatch).toBeTrue();
+    });
+
+    test("multiple throwing disposes give suppressed error", () => {
+        let inCatch = false;
+        try {
+            {
+                using a = { [Symbol.dispose]() {
+                    throw new ExpectedError('a');
+                } };
+
+                using b = { [Symbol.dispose]() {
+                    throw new ExpectedError('b');
+                } };
+            }
+
+            expect().fail();
+        } catch (e) {
+            expect(e).toBeInstanceOf(SuppressedError);
+            expect(e.error).toBeInstanceOf(ExpectedError);
+            expect(e.error.name).toBe('a');
+            expect(e.suppressed).toBeInstanceOf(ExpectedError);
+            expect(e.suppressed.name).toBe('b');
+            inCatch = true;
+        }
+        expect(inCatch).toBeTrue();
+    });
+
+    test("3 throwing disposes give chaining suppressed error", () => {
+        let inCatch = false;
+        try {
+            {
+                using a = { [Symbol.dispose]() {
+                    throw new ExpectedError('a');
+                } };
+
+                using b = { [Symbol.dispose]() {
+                    throw new ExpectedError('b');
+                } };
+
+                using c = { [Symbol.dispose]() {
+                    throw new ExpectedError('c');
+                } };
+            }
+
+            expect().fail();
+        } catch (e) {
+            expect(e).toBeInstanceOf(SuppressedError);
+            expect(e.error).toBeInstanceOf(ExpectedError);
+            expect(e.error.name).toBe('a');
+            expect(e.suppressed).toBeInstanceOf(SuppressedError);
+
+            const inner = e.suppressed;
+
+            expect(inner.error).toBeInstanceOf(ExpectedError);
+            expect(inner.error.name).toBe('b');
+            expect(inner.suppressed).toBeInstanceOf(ExpectedError);
+            expect(inner.suppressed.name).toBe('c');
+            inCatch = true;
+        }
+        expect(inCatch).toBeTrue();
+    });
+
+    test("normal error and multiple disposing erorrs give chaining suppressed errors", () => {
+        let inCatch = false;
+        try {
+            using a = { [Symbol.dispose]() {
+                throw new ExpectedError('a');
+            } };
+
+            using b = { [Symbol.dispose]() {
+                throw new ExpectedError('b');
+            } };
+
+            throw new ExpectedError('top');
+        } catch (e) {
+            expect(e).toBeInstanceOf(SuppressedError);
+            expect(e.error).toBeInstanceOf(ExpectedError);
+            expect(e.error.name).toBe('a');
+            expect(e.suppressed).toBeInstanceOf(SuppressedError);
+
+            const inner = e.suppressed;
+
+            expect(inner.error).toBeInstanceOf(ExpectedError);
+            expect(inner.error.name).toBe('b');
+            expect(inner.suppressed).toBeInstanceOf(ExpectedError);
+            expect(inner.suppressed.name).toBe('top');
+            inCatch = true;
+        }
+        expect(inCatch).toBeTrue();
+    });
+});
+
+describe("works in a bunch of scopes", () => {
+    test("works in block", () => {
+        let dispose = false;
+        expect(dispose).toBeFalse();
+        {
+            expect(dispose).toBeFalse();
+            using a = { [Symbol.dispose]() { dispose = true; } }
+            expect(dispose).toBeFalse();
+        }
+        expect(dispose).toBeTrue();
+    });
+
+    test("works in static class block", () => {
+        let dispose = false;
+        expect(dispose).toBeFalse();
+        class A {
+            static {
+                expect(dispose).toBeFalse();
+                using a = { [Symbol.dispose]() { dispose = true; } }
+                expect(dispose).toBeFalse();
+            }
+        }
+        expect(dispose).toBeTrue();
+    });
+
+    test("works in function", () => {
+        let dispose = [];
+        function f(val) {
+            const disposeLength = dispose.length;
+            using a = { [Symbol.dispose]() { dispose.push(val); } }
+            expect(dispose.length).toBe(disposeLength);
+        }
+        expect(dispose).toEqual([]);
+        f(0);
+        expect(dispose).toEqual([0]);
+        f(1);
+        expect(dispose).toEqual([0, 1]);
+    });
+
+    test("switch block is treated as full block in function", () => {
+        let disposeFull = [];
+        let disposeInner = false;
+
+        function pusher(val) {
+            return {
+                val,
+                [Symbol.dispose]() { disposeFull.push(val); }
+            };
+        }
+
+        switch (2) {
+            case 3:
+                using notDisposed = { [Symbol.dispose]() { expect().fail("not-disposed 1"); } };
+            case 2:
+                expect(disposeFull).toEqual([]);
+                using a = pusher('a');
+                expect(disposeFull).toEqual([]);
+
+                using b = pusher('b');
+                expect(disposeFull).toEqual([]);
+                expect(b.val).toBe('b');
+
+                expect(disposeInner).toBeFalse();
+                // fallthrough
+            case 1: {
+                expect(disposeFull).toEqual([]);
+                expect(disposeInner).toBeFalse();
+
+                using inner = { [Symbol.dispose]() { disposeInner = true; } }
+
+                expect(disposeInner).toBeFalse();
+            }
+                expect(disposeInner).toBeTrue();
+                using c = pusher('c');
+                expect(c.val).toBe('c');
+                break;
+            case 0:
+                using notDisposed2 = { [Symbol.dispose]() { expect().fail("not-disposed 2"); } };
+        }
+
+        expect(disposeInner).toBeTrue();
+        expect(disposeFull).toEqual(['c', 'b', 'a']);
+    });
+});
+
+describe("invalid using bindings", () => {
+    test("nullish values do not throw", () => {
+        using a = null, b = undefined;
+        expect(a).toBeNull();
+        expect(b).toBeUndefined();
+    });
+
+    test("non-object throws", () => {
+        [0, "a", true, NaN, 4n, Symbol.dispose].forEach(value => {
+            expect(() => {
+                using v = value;
+            }).toThrowWithMessage(TypeError, "is not an object");
+        });
+    });
+
+    test("object without dispose throws", () => {
+        expect(() => {
+            using a = {};
+        }).toThrowWithMessage(TypeError, "does not have dispose method");
+    });
+
+    test("object with non callable dispose throws", () => {
+        [0, "a", true, NaN, 4n, Symbol.dispose, [], {}].forEach(value => {
+            expect(() => {
+                using a = { [Symbol.dispose]: value };
+            }).toThrowWithMessage(TypeError, "is not a function");
+        });
+    });
+});
+
+describe("using is still a valid variable name", () => {
+    test("var", () => {
+        "use strict";
+        var using = 1;
+        expect(using).toBe(1);
+    });
+
+    test("const", () => {
+        "use strict";
+        const using = 1;
+        expect(using).toBe(1);
+    });
+
+    test("let", () => {
+        "use strict";
+        let using = 1;
+        expect(using).toBe(1);
+    });
+
+    test("using", () => {
+        "use strict";
+        using using = null;
+        expect(using).toBeNull();
+    });
+
+    test("function", () => {
+        "use strict";
+        function using() { return 1; }
+        expect(using()).toBe(1);
+    });
+});
+
+describe("syntax errors / werid artifacts which remain valid", () => {
+    test("no patterns in using", () => {
+        expect("using {a} = {}").not.toEval();
+        expect("using a, {a} = {}").not.toEval();
+        expect("using a = null, [b] = [null]").not.toEval();
+    });
+
+    test("using with array pattern is valid array access", () => {
+        const using = [0, 9999];
+        const a = 1;
+
+        expect(eval("using [a] = 1")).toBe(1);
+        expect(using[1]).toBe(1);
+
+        expect(eval("using [{a: a}, a] = 2")).toBe(2);
+        expect(using[1]).toBe(2);
+
+        expect(eval("using [a, a] = 3")).toBe(3);
+        expect(using[1]).toBe(3);
+
+        expect(eval("using [[a, a], a] = 4")).toBe(4);
+        expect(using[1]).toBe(4);
+
+        expect(eval("using [2, 1, a] = 5")).toBe(5);
+        expect(using[1]).toBe(5);
+    });
+
+    test("declaration without initializer", () => {
+        expect("using a").not.toEval();
+    });
+
+    test("no repeat declarations in single using", () => {
+        expect("using a = null, a = null;").not.toEval();
+    });
+
+    test("cannot have a using declaration named let", () => {
+        expect("using let = null").not.toEval();
+    });
+});