@scriptc/compiler 0.3.1 → 0.3.3

package/dist/frontend/lowering/lower-stream.js

@@ -35,8 +35,29 @@ import { newFnCtx, own } from "./lowerer.js";
 import { appendImplicitUndefinedReturn } from "./function-returns.js";
 import { bufEncoding, knownBufEncoding } from "./containers/bytes.js";
 import { tryLowerExpression } from "./expressions/try-lower-expression.js";
+import { sideEffectFreeOptionValue } from "./surfaces.js";
 import { BOOL, DYN, F64, RUNTIME_STREAM_CLASSES, STRING, VOID, arrayOf, BYTES_U8, canBoxFuncIntoDyn, funcOf, typeEquals, typeKey, } from "../../ir/ir.js";
 const BYTES = BYTES_U8;
+/** An expression that only reads bindings and properties (no calls,
+ * assignments or construction): reading it a step later observes the
+ * same values. */
+function pureRead(node) {
+    if (ts.isParenthesizedExpression(node) ||
+        ts.isNonNullExpression(node) ||
+        ts.isAsExpression(node)) {
+        return pureRead(node.expression);
+    }
+    if (ts.isIdentifier(node) || node.kind === ts.SyntaxKind.ThisKeyword)
+        return true;
+    if (ts.isPropertyAccessExpression(node))
+        return pureRead(node.expression);
+    if (ts.isElementAccessExpression(node)) {
+        return ((ts.isStringLiteral(node.argumentExpression) ||
+            ts.isNumericLiteral(node.argumentExpression)) &&
+            pureRead(node.expression));
+    }
+    return false;
+}
 /** The stream sides of a receiver class: the nearest stream-class
  * ancestor's, or null off the stream hierarchy. */
 export function streamSidesOf(lowerer, info) {
@@ -466,6 +487,7 @@ fallbackCb) {
         encoding: null,
         badEncoding: null,
         pushEncoding: null,
+        signal: null,
         flags: 0,
         cbs: [],
     };
@@ -527,6 +549,12 @@ fallbackCb) {
             present.set(name, lowerStreamCallback(lowerer, name, fnNode, thisType, tuple));
             continue;
         }
+        // `{ signal }` shorthand: the binding is the value.
+        if (name === "signal" && ts.isShorthandPropertyAssignment(prop)) {
+            if (ts.isIdentifier(prop.name))
+                out.signal = lowerer.lowerExprExpecting(prop.name, DYN);
+            continue;
+        }
         // Scalar options.
         if (!ts.isPropertyAssignment(prop)) {
             lowerer.unsupported("SC1090", prop, `the ${ctorName} option '${name}' as a shorthand/method member`);
@@ -609,9 +637,20 @@ fallbackCb) {
                 }
                 lowerer.noLowering(`the ${ctorName} option 'defaultEncoding'`, prop, "utf8 (the default) is the supported write-side string encoding");
                 break;
-            case "signal":
-                lowerer.noLowering(`the ${ctorName} option 'signal'`, prop, "AbortSignal-driven destruction is not lowered yet");
+            case "signal": {
+                // `if (options.signal) addAbortSignal(options.signal, this)`:
+                // applied over the fresh stream, so the value is read after the
+                // constructor — only values whose evaluation has no effects.
+                if (value.kind === ts.SyntaxKind.NullKeyword)
+                    break;
+                if (ts.isIdentifier(value) && value.text === "undefined")
+                    break;
+                if (!sideEffectFreeOptionValue(value) && !pureRead(value)) {
+                    lowerer.noLowering(`the ${ctorName} option 'signal' with this value`, prop, "pass a variable or property read (const signal = controller.signal) — the signal is read after construction");
+                }
+                out.signal = lowerer.lowerExprExpecting(value, DYN);
                 break;
+            }
             case "captureRejections": {
                 // `false` is the default — admit the literal; the rejection-
                 // capturing mode has no lowering (async listeners' promises are
@@ -691,6 +730,7 @@ function streamCtorArgs(lowerer, cls, arg, thisType, loc, fallbackCb) {
         encoding: o.encoding,
         badEncoding: o.badEncoding,
         pushEncoding: o.pushEncoding,
+        signal: o.signal,
     };
 }
 /** `new Readable(opts?)` and friends — called from lowerNew once the
@@ -736,14 +776,24 @@ export function lowerStreamNew(lowerer, expr, info) {
             loc,
         };
     }
-    if (parsed.encoding === null)
+    if (parsed.encoding !== null) {
+        // { encoding }: chain a setEncoding over the fresh stream (the operand
+        // temp releases with the frame; setEncoding answers the receiver +1).
+        built = {
+            kind: "libCall",
+            fn: "readable.setEncoding",
+            args: [built, strLit(parsed.encoding, loc)],
+            type: thisType,
+            loc,
+        };
+    }
+    if (parsed.signal === null)
         return built;
-    // { encoding }: chain a setEncoding over the fresh stream (the operand
-    // temp releases with the frame; setEncoding answers the receiver +1).
+    // { signal }: addAbortSignal over the fresh stream (answers it +1).
     return {
         kind: "libCall",
-        fn: "readable.setEncoding",
-        args: [built, strLit(parsed.encoding, loc)],
+        fn: "stream.addAbortSignal",
+        args: [built, parsed.signal],
         type: thisType,
         loc,
     };
@@ -759,8 +809,8 @@ function streamMethodWrapper(lowerer, info, which, methodName, thisType, loc, bl
     const found = lowerer.findMethodOn(info, methodName);
     if (!found) {
         // A DESCENDANT-only declaration (the base chain never declares it):
-        // this constructor cannot see it, and silently binding nothing would
-        // diverge from Node (which dispatches through the prototype chain).
+        // this constructor cannot see it, and binding nothing without a
+        // diagnostic would diverge from Node (which dispatches through the prototype chain).
         if (lowerer.overrideBelow(info, methodName)) {
             lowerer.noLowering(`a subclass of ${info.def.name.replace(/^%/, "")} declaring '${methodName}' below a base whose constructor cannot see it`, blame, `declare '${methodName}' on the class whose constructor calls the stream super(), and override it below`);
         }
@@ -959,6 +1009,19 @@ export function lowerStreamSuperCall(lowerer, info, base, argNodes, thisLocal, l
             loc,
         });
     }
+    if (parsed.signal !== null) {
+        out.push({
+            kind: "exprStmt",
+            expr: {
+                kind: "libCall",
+                fn: "stream.addAbortSignal",
+                args: [thisRef(), parsed.signal],
+                type: thisType,
+                loc,
+            },
+            loc,
+        });
+    }
     return out;
 }
 /* ── the underscore-method assignment surface ─────────────────────────── */
@@ -1284,6 +1347,85 @@ function lowerEosCallback(lowerer, which, node, thisType) {
     }
     lowerer.noLowering(`${which} with this callback value`, node, "write the callback inline, or pass a function value that crosses the checked-dynamic boundary");
 }
+/** finished()'s options literal: readable/writable/error (and cleanup
+ * for the promise form) as boolean literals, signal as any expression.
+ * readable/writable answer -1 when absent (Node's default: whether the
+ * stream has that side). */
+function eosOptions(lowerer, node, promiseForm) {
+    const out = {
+        readable: -1,
+        writable: -1,
+        error: true,
+        cleanup: false,
+        signal: null,
+    };
+    if (!ts.isObjectLiteralExpression(node)) {
+        lowerer.noLowering("finished options that are not an object literal", node, "write the options inline: finished(stream, { readable, writable, error, signal })");
+    }
+    const literal = (p, key) => {
+        if (p.initializer.kind === ts.SyntaxKind.TrueKeyword)
+            return true;
+        if (p.initializer.kind === ts.SyntaxKind.FalseKeyword)
+            return false;
+        lowerer.noLowering(`the finished option '${key}' with a non-literal value`, p.initializer, "pass true or false");
+    };
+    for (const p of node.properties) {
+        const key = (ts.isPropertyAssignment(p) || ts.isShorthandPropertyAssignment(p)) && ts.isIdentifier(p.name)
+            ? p.name.text
+            : null;
+        if (key === "signal") {
+            out.signal = ts.isShorthandPropertyAssignment(p)
+                ? lowerer.lowerExprExpecting(p.name, DYN)
+                : lowerer.lowerExprExpecting(p.initializer, DYN);
+            continue;
+        }
+        if (key !== null && ts.isPropertyAssignment(p)) {
+            if (key === "readable")
+                out.readable = literal(p, key) ? 1 : 0;
+            else if (key === "writable")
+                out.writable = literal(p, key) ? 1 : 0;
+            else if (key === "error")
+                out.error = literal(p, key);
+            else if (key === "cleanup" && promiseForm)
+                out.cleanup = literal(p, key);
+            else {
+                lowerer.noLowering(`the finished option '${key}'`, p, promiseForm
+                    ? "readable, writable, error, cleanup and signal are the supported options"
+                    : "readable, writable, error and signal are the supported options");
+            }
+            continue;
+        }
+        lowerer.noLowering("finished options with this member", p, "write each option as a plain property");
+    }
+    return out;
+}
+/** pipeline()'s trailing options literal (the promise form): signal as
+ * any expression, end as a boolean literal. */
+function pipelineOptions(lowerer, node) {
+    const out = { end: true, signal: null };
+    for (const p of node.properties) {
+        const key = (ts.isPropertyAssignment(p) || ts.isShorthandPropertyAssignment(p)) && ts.isIdentifier(p.name)
+            ? p.name.text
+            : null;
+        if (key === "signal") {
+            out.signal = ts.isShorthandPropertyAssignment(p)
+                ? lowerer.lowerExprExpecting(p.name, DYN)
+                : lowerer.lowerExprExpecting(p.initializer, DYN);
+            continue;
+        }
+        if (key === "end" && ts.isPropertyAssignment(p)) {
+            if (p.initializer.kind === ts.SyntaxKind.TrueKeyword)
+                continue;
+            if (p.initializer.kind === ts.SyntaxKind.FalseKeyword) {
+                out.end = false;
+                continue;
+            }
+            lowerer.noLowering("the pipeline option 'end' with a non-literal value", p.initializer, "pass true or false");
+        }
+        lowerer.noLowering(key === null ? "pipeline options with this member" : `the pipeline option '${key}'`, p, "signal and end are the supported pipeline options");
+    }
+    return out;
+}
 /** `finished(...)` / `pipeline(...)` / `getDefaultHighWaterMark(...)`
  * imported from node:stream (named imports, destructured requires, and
  * namespace-member calls all land here). Null for members this spoke
@@ -1296,10 +1438,8 @@ export function lowerStreamModuleCall(lowerer, call, bi, loc) {
         // ERR_STREAM_PREMATURE_CLOSE — the callback form's status, boxed
         // through the promise instead). The options argument has no lowering.
         if (bi.member === "finished") {
-            if (args.length !== 1) {
-                lowerer.noLowering(`stream/promises.finished with ${args.length} arguments`, call, args.length === 2
-                    ? "the options argument has no lowering yet — the one-argument form is supported"
-                    : "the supported form is finished(stream)");
+            if (args.length !== 1 && args.length !== 2) {
+                lowerer.noLowering(`stream/promises.finished with ${args.length} arguments`, call, "the supported forms are finished(stream) and finished(stream, options)");
             }
             let recv;
             try {
@@ -1310,6 +1450,24 @@ export function lowerStreamModuleCall(lowerer, call, bi, loc) {
                     return e.expr;
                 throw e;
             }
+            const optsNode = args[1];
+            if (optsNode !== undefined && optsNode.kind !== ts.SyntaxKind.NullKeyword) {
+                const o = eosOptions(lowerer, optsNode, true);
+                const head = [
+                    recv,
+                    numLit(o.readable, loc),
+                    numLit(o.writable, loc),
+                    boolLit(o.error, loc),
+                    boolLit(o.cleanup, loc),
+                ];
+                return {
+                    kind: "libCall",
+                    fn: o.signal ? "sp.finishedOptsSignal" : "sp.finishedOpts",
+                    args: o.signal ? [...head, o.signal] : head,
+                    type: { kind: "promise", inner: VOID },
+                    loc,
+                };
+            }
             return {
                 kind: "libCall",
                 fn: "sp.finished",
@@ -1326,15 +1484,30 @@ export function lowerStreamModuleCall(lowerer, call, bi, loc) {
             if (args.length < 2) {
                 lowerer.noLowering(`stream/promises.pipeline with ${args.length} arguments`, call, "the supported form is pipeline(source, ...streams)");
             }
+            const lastArg = args[args.length - 1];
+            const opts = ts.isObjectLiteralExpression(lastArg) && args.length >= 3
+                ? pipelineOptions(lowerer, lastArg)
+                : null;
+            const stageArgs = opts ? args.slice(0, -1) : args;
             let streams;
             try {
-                streams = args.map((a) => lowerStreamArg(lowerer, a, "pipeline"));
+                streams = stageArgs.map((a) => lowerStreamArg(lowerer, a, "pipeline"));
             }
             catch (e) {
                 if (e instanceof StreamArgTypeThrow)
                     return e.expr;
                 throw e;
             }
+            if (opts) {
+                const head = [numLit(streams.length, loc), ...streams, boolLit(opts.end, loc)];
+                return {
+                    kind: "libCall",
+                    fn: opts.signal ? "sp.pipelineOptsSignal" : "sp.pipelineOpts",
+                    args: opts.signal ? [...head, opts.signal] : head,
+                    type: { kind: "promise", inner: VOID },
+                    loc,
+                };
+            }
             return {
                 kind: "libCall",
                 fn: "sp.pipeline",
@@ -1352,9 +1525,9 @@ export function lowerStreamModuleCall(lowerer, call, bi, loc) {
         // utf8 decode / the parsed JSON dyn tree / the concatenated bytes / an
         // ArrayBuffer dyn over them) or rejects — with the stream's error,
         // ERR_STREAM_PREMATURE_CLOSE on an early close, or json's SyntaxError
-        // on malformed text, Node's own rejection set. blob returns null here:
-        // Blob has no representation, so the module-qualified fence (with the
-        // pointed hint in BUILTIN_MODULE_FENCE_HINTS) speaks.
+        // on malformed text, Node's own rejection set. blob returns null here,
+        // so the module-qualified fence (with the pointed hint in
+        // BUILTIN_MODULE_FENCE_HINTS) speaks.
         if (bi.member === "text" ||
             bi.member === "json" ||
             bi.member === "buffer" ||
@@ -1400,11 +1573,33 @@ export function lowerStreamModuleCall(lowerer, call, bi, loc) {
             return numLit(16, loc);
         lowerer.noLowering("getDefaultHighWaterMark with a non-literal argument", call, "the objectMode flag must be a compile-time boolean");
     }
-    if (bi.member === "finished") {
+    if (bi.member === "addAbortSignal") {
+        // addAbortSignal(signal, stream) → the stream: destroyed with an
+        // AbortError when the signal aborts (now, if it already has).
         if (args.length !== 2) {
-            lowerer.noLowering(`finished with ${args.length} arguments`, call, args.length === 3
-                ? "the options argument has no lowering yet — the two-argument form is supported"
-                : "the supported form is finished(stream, callback)");
+            lowerer.noLowering(`addAbortSignal with ${args.length} arguments`, call, "the supported form is addAbortSignal(signal, stream)");
+        }
+        const signal = lowerer.lowerExprExpecting(args[0], DYN);
+        let stream;
+        try {
+            stream = lowerStreamArg(lowerer, args[1], "addAbortSignal");
+        }
+        catch (e) {
+            if (e instanceof StreamArgTypeThrow)
+                return e.expr;
+            throw e;
+        }
+        return {
+            kind: "libCall",
+            fn: "stream.addAbortSignalFn",
+            args: [signal, stream],
+            type: stream.type,
+            loc,
+        };
+    }
+    if (bi.member === "finished") {
+        if (args.length !== 2 && args.length !== 3) {
+            lowerer.noLowering(`finished with ${args.length} arguments`, call, "the supported forms are finished(stream, callback) and finished(stream, options, callback)");
         }
         let recv;
         try {
@@ -1415,7 +1610,24 @@ export function lowerStreamModuleCall(lowerer, call, bi, loc) {
                 return e.expr;
             throw e;
         }
-        const { cb, dyn } = lowerEosCallback(lowerer, "finished", args[1], recv.type);
+        if (args.length === 3 && args[1].kind !== ts.SyntaxKind.NullKeyword) {
+            const o = eosOptions(lowerer, args[1], false);
+            const { cb } = lowerEosCallback(lowerer, "finished", args[2], recv.type);
+            const head = [
+                recv,
+                numLit(o.readable, loc),
+                numLit(o.writable, loc),
+                boolLit(o.error, loc),
+            ];
+            return {
+                kind: "libCall",
+                fn: o.signal ? "stream.finishedOptsSignal" : "stream.finishedOpts",
+                args: o.signal ? [...head, o.signal, cb] : [...head, cb],
+                type: funcOf([], VOID),
+                loc,
+            };
+        }
+        const { cb, dyn } = lowerEosCallback(lowerer, "finished", args[args.length - 1], recv.type);
         return {
             kind: "libCall",
             fn: dyn ? "stream.finishedDyn" : "stream.finished",