@scriptc/compiler 0.3.3 → 0.3.5

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

@@ -36,7 +36,11 @@ 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";
+import { lowerDynObjectLiteral } from "./expressions/object-literals.js";
+import { dynUndefinedExpr, varRef } from "../../ir/build.js";
+import { genResultRecord } from "../type-mapper.js";
+import { extractIteratorValue, genStep, genValue, stepDrivable } from "./lower-generators.js";
+import { BOOL, DYN, F64, RUNTIME_STREAM_CLASSES, STRING, VOID, arrayOf, BYTES_U8, canBoxFuncIntoDyn, canConvertToDyn, 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
@@ -155,6 +159,8 @@ export const STREAM_FORCED_EVENT_NAMES = new Set([
     "finish",
     "pipe",
     "unpipe",
+    "open",
+    "ready",
 ]);
 /** The per-base FORCED event tuples (runtime-emitted payloads): consulted
  * by the emitter spoke BEFORE the program-global table, so a stream's
@@ -164,6 +170,8 @@ export function streamForcedTuple(lowerer, info, name) {
     const sides = streamSidesOf(lowerer, info);
     if (!sides)
         return null;
+    // 'open' (the fd) and 'ready' are fs.ReadStream / fs.WriteStream's
+    // (scr_fs_stream.c).
     const readable = {
         data: [BYTES],
         end: [],
@@ -171,8 +179,12 @@ export function streamForcedTuple(lowerer, info, name) {
         readable: [],
         pause: [],
         resume: [],
+        open: [F64],
+        ready: [],
     };
     const writable = {
+        open: [F64],
+        ready: [],
         drain: [],
         prefinish: [],
         finish: [],
@@ -1111,12 +1123,14 @@ export function lowerStreamUnderscoreAssign(lowerer, expr) {
     };
 }
 /* ── the static surface (Readable.from) ───────────────────────────────── */
-/** `Readable.from(iterable)` — the array-seeded object-entry form:
- * string[] / Buffer[] values (or literals) become a fully-seeded
- * readable delivering one WHOLE chunk per element (Node's objectMode
- * accounting; hwm 1), and a single string/Buffer argument is a
- * one-chunk stream (Node's special case). Called from the method-call
- * chain once the receiver resolved to a stream class value. */
+/** `Readable.from(iterable, options)`: string[] / Buffer[] sources
+ * become a readable that pushes one element per _read (whole entries in
+ * object mode, hwm 1), and a single string/Buffer argument is a
+ * one-chunk stream (from.js's special case, the mode's default hwm). The
+ * options lower when they are a literal of `objectMode` and
+ * `highWaterMark`; the JS lane and `any` sources take the runtime's
+ * checked-dynamic form. Called from the method-call chain once the
+ * receiver resolved to a stream class value. */
 export function lowerStreamStaticCall(lowerer, call, access) {
     if (call.questionDotToken || access.questionDotToken)
         return null;
@@ -1165,37 +1179,223 @@ export function lowerStreamStaticCall(lowerer, call, access) {
         lowerer.noLowering(`${cls.slice(1)}.from`, call, "Readable.from is the lowered form");
     }
     const args = call.arguments;
-    if (args.length !== 1) {
-        lowerer.noLowering(`Readable.from with ${args.length} arguments`, call, "the one-argument form (an array, string, or Buffer) is supported");
+    if (args.length > 2) {
+        lowerer.noLowering(`Readable.from with ${args.length} arguments`, call, "Readable.from(iterable, options) is the supported form");
     }
-    const srcT = lowerer.mapTypeOf(lowerer.typeOf(args[0]));
     const type = { kind: "object", className: "%Readable" };
-    if (srcT?.kind === "array" &&
-        (srcT.elem.kind === "string" || (srcT.elem.kind === "bytes" && srcT.elem.elem === "u8"))) {
-        const arr = lowerer.lowerExpr(args[0]);
-        const strings = srcT.elem.kind === "string";
+    const js = isJsSourceFile(call.getSourceFile());
+    const srcNode = args[0];
+    const optsNode = args[1];
+    const srcT = srcNode ? lowerer.mapTypeOf(lowerer.typeOf(srcNode)) : null;
+    const typedElem = (t) => t?.kind === "string" ? "string" : t?.kind === "bytes" && t.elem === "u8" ? "bytes" : null;
+    const single = typedElem(srcT);
+    const elem = srcT?.kind === "array" ? typedElem(srcT.elem) : null;
+    const opts = optsNode ? fromOptions(lowerer, optsNode) : { flags: 0, hwm: null };
+    if (srcNode && srcT?.kind === "generator" && opts && fromGenChunk(lowerer, srcT.yieldT)) {
+        // A compiled generator: the runtime pulls it through interned helpers.
+        const gen = lowerer.lowerExpr(srcNode);
+        const helpers = fromGenHelpers(lowerer, srcT, loc);
+        if (helpers) {
+            const hwm = opts.hwm ? lowerer.lowerExprExpecting(opts.hwm, F64) : numLit(0, loc);
+            return {
+                kind: "libCall",
+                fn: srcT.async ? "readable.fromAsyncGen" : "readable.fromGen",
+                args: [gen, ...helpers, numLit(opts.flags, loc), hwm],
+                type,
+                loc,
+            };
+        }
+    }
+    if (srcNode && (single || elem) && opts) {
+        const v = lowerer.lowerExpr(srcNode);
+        const hwm = opts.hwm ? lowerer.lowerExprExpecting(opts.hwm, F64) : numLit(0, loc);
+        const arr = single ? { kind: "arrayLit", elems: [v], type: arrayOf(v.type), loc } : v;
+        // SCR_FROM_STRINGS 1, SCR_FROM_SINGLE 2 (scr_runtime.h); the options
+        // add SCR_FROM_BYTE_MODE 4 and SCR_FROM_HAS_HWM 8.
+        const flags = ((single ?? elem) === "string" ? 1 : 0) | (single ? 2 : 0) | opts.flags;
         return {
             kind: "libCall",
             fn: "readable.fromArr",
-            args: [arr, boolLit(strings, loc)],
+            args: [arr, numLit(flags, loc), hwm],
             type,
             loc,
         };
     }
-    if (srcT?.kind === "string" || (srcT?.kind === "bytes" && srcT.elem === "u8")) {
-        // Node special-cases a single string/Buffer: ONE whole chunk.
-        const v = lowerer.lowerExpr(args[0]);
-        const strings = srcT.kind === "string";
-        const arr = { kind: "arrayLit", elems: [v], type: arrayOf(v.type), loc };
+    const anySrc = srcT?.kind === "dyn" ||
+        (srcNode !== undefined &&
+            srcT === null &&
+            (lowerer.typeOf(srcNode).flags & ts.TypeFlags.Any) !== 0);
+    if (js || anySrc) {
+        // The checked-dynamic form: the runtime takes from.js's ladder
+        // (ERR_INVALID_ARG_TYPE for a non-iterable, the options, null values).
+        const src = srcNode ? lowerer.lowerExprExpecting(srcNode, DYN) : dynUndefinedExpr(loc);
+        const o = lowerOperatorValue(lowerer, optsNode, "Readable.from options", loc, true);
+        return { kind: "libCall", fn: "readable.fromDyn", args: [src, o], type, loc };
+    }
+    if (srcNode && (single || elem)) {
+        lowerer.noLowering("Readable.from with these options", optsNode, "an object literal with 'objectMode' (true or false) and a number 'highWaterMark' is supported");
+    }
+    lowerer.noLowering(`Readable.from over a '${srcT ? lowerer.fmt(srcT) : "?"}' source`, srcNode ?? call, "string[] / Buffer[] arrays (and a single string or Buffer) are the supported sources — generators and async iterables have no lowering yet");
+}
+/** Whether a generator's yields are stream chunks: strings, Buffers, a
+ * union of them (null included: the runtime destroys the stream with
+ * ERR_STREAM_NULL_VALUES), or checked-dynamic values (checked when
+ * pushed). */
+function fromGenChunk(lowerer, t) {
+    const chunk = (a) => a.kind === "string" || (a.kind === "bytes" && a.elem === "u8") || a.kind === "nullT";
+    if (t.kind === "dyn" || (chunk(t) && t.kind !== "nullT"))
+        return true;
+    if (t.kind !== "union")
+        return false;
+    return lowerer.unions.get(t.unionId)?.arms.every(chunk) ?? false;
+}
+/** The helpers Readable.from pulls a compiled generator through, as
+ * closures in libcall order: a sync generator's next/return/throw answer
+ * the next value as a checked-dynamic value or the done marker
+ * (readable.fromDone); an async generator's next/return/throw answer the
+ * resume's promise, followed by `read`, which maps its IteratorResult the
+ * same way. Interned per generator type. Null when the result record has
+ * no lowering. */
+function fromGenHelpers(lowerer, gen, loc) {
+    const recT = genResultRecord(gen.yieldT, gen.retT, lowerer.shapes, lowerer.unions);
+    const valueT = recT && lowerer.shapes.get(recT.shapeId)?.fields.find((f) => f.name === "value")?.type;
+    if (!recT || !valueT)
+        return null;
+    const done = () => ({
+        kind: "libCall",
+        fn: "readable.fromDone",
+        args: [],
+        type: DYN,
+        loc,
+    });
+    // `r.done ? done : r.value` over a record local.
+    const readRecord = (localId) => {
+        const r = varRef(localId, recT, loc);
+        const value = extractIteratorValue(lowerer, gen.yieldT, valueT, { kind: "recordGet", obj: r, shapeId: recT.shapeId, field: "value", type: valueT, loc }, loc);
+        if (!value)
+            return null;
+        return [
+            {
+                kind: "if",
+                cond: { kind: "recordGet", obj: r, shapeId: recT.shapeId, field: "done", type: BOOL, loc },
+                then: [{ kind: "return", value: done(), loc }],
+                else_: null,
+                loc,
+            },
+            { kind: "return", value: lowerer.coerceToExpected(value, DYN), loc },
+        ];
+    };
+    const promiseT = { kind: "promise", inner: recT };
+    const define = (role, params, returnType, body, locals = []) => {
+        const key = `streamFromGen:${role}:${typeKey(gen)}`;
+        let name = lowerer.valueHelpers.get(key);
+        if (!name) {
+            name = `%stream.fromGen.${role}.${lowerer.valueHelpers.size}`;
+            lowerer.valueHelpers.set(key, name);
+            lowerer.liftedFns.push({
+                name,
+                params: params.map((p) => ({ localId: p.id, name: p.id.split(".")[0], type: p.type })),
+                returnType,
+                locals: [...params, ...locals].map((l) => ({
+                    id: l.id,
+                    name: l.id.split(".")[0],
+                    type: l.type,
+                    mutable: false,
+                })),
+                body,
+                loc,
+            });
+        }
         return {
-            kind: "libCall",
-            fn: "readable.fromArr",
-            args: [arr, boolLit(strings, loc)],
-            type,
+            kind: "closure",
+            fnName: name,
+            captures: [],
+            type: funcOf(params.map((p) => p.type), returnType),
             loc,
         };
+    };
+    const g = { id: "gen.0", type: gen };
+    const e = { id: "err.0", type: DYN };
+    const r = { id: "res.0", type: recT };
+    const genRef = varRef("gen.0", gen, loc);
+    const resume = (mode) => ({
+        kind: "genResume",
+        mode,
+        gen: genRef,
+        arg: mode === "throw" ? varRef("err.0", DYN, loc) : null,
+        type: gen.async ? promiseT : recT,
+        loc,
+    });
+    const read = readRecord("res.0");
+    if (!read)
+        return null;
+    if (gen.async) {
+        const ret = (mode) => [
+            { kind: "return", value: resume(mode), loc },
+        ];
+        return [
+            define("anext", [g], promiseT, ret("next")),
+            define("aread", [r], DYN, read),
+            define("areturn", [g], promiseT, ret("return")),
+            define("athrow", [g, e], promiseT, ret("throw")),
+        ];
+    }
+    const viaRecord = (mode) => [
+        { kind: "varDecl", localId: "res.0", init: resume(mode), loc },
+        ...read,
+    ];
+    const next = stepDrivable(gen)
+        ? [
+            {
+                kind: "if",
+                cond: genStep(genRef, loc),
+                then: [{ kind: "return", value: done(), loc }],
+                else_: null,
+                loc,
+            },
+            { kind: "return", value: lowerer.coerceToExpected(genValue(genRef, loc), DYN), loc },
+        ]
+        : viaRecord("next");
+    const withRecord = stepDrivable(gen) ? [] : [r];
+    return [
+        define("next", [g], DYN, next, withRecord),
+        define("return", [g], DYN, viaRecord("return"), [r]),
+        define("throw", [g, e], DYN, viaRecord("throw"), [r]),
+    ];
+}
+/** Readable.from's typed options: an object literal of `objectMode`
+ * (a boolean literal) and `highWaterMark` (a number), as SCR_FROM_* flag
+ * bits and the hwm expression; null for any other shape. */
+function fromOptions(lowerer, node) {
+    if (!ts.isObjectLiteralExpression(node))
+        return null;
+    let flags = 0;
+    let hwm = null;
+    for (const prop of node.properties) {
+        if (!ts.isPropertyAssignment(prop) ||
+            !(ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name))) {
+            return null;
+        }
+        const value = prop.initializer;
+        if (prop.name.text === "objectMode") {
+            if (value.kind === ts.SyntaxKind.FalseKeyword)
+                flags |= 4;
+            else if (value.kind === ts.SyntaxKind.TrueKeyword)
+                flags &= ~4;
+            else
+                return null;
+        }
+        else if (prop.name.text === "highWaterMark") {
+            if (lowerer.mapTypeOf(lowerer.typeOf(value))?.kind !== "f64")
+                return null;
+            flags |= 8;
+            hwm = value;
+        }
+        else {
+            return null;
+        }
     }
-    lowerer.noLowering(`Readable.from over a '${srcT ? lowerer.fmt(srcT) : "?"}' source`, args[0], "string[] / Buffer[] arrays (and a single string or Buffer) are the supported sources — generators and async iterables have no lowering yet");
+    return { flags, hwm };
 }
 /** `const Writable = stream.Writable` — a runtime stream CLASS bound
  * through a namespace member: alias plumbing with no storage (both
@@ -1273,7 +1473,7 @@ function lowerStreamArg(lowerer, node, what) {
                 argTypeThrow("stream", "an instance of ReadableStream, WritableStream, or Stream");
             }
         }
-        lowerer.noLowering(`${what} over a '${lowerer.fmt(v.type)}'`, node, what === "pipeline"
+        lowerer.noLowering(`${what} over a '${lowerer.fmt(v.type)}'`, node, what === "pipeline" || what === "compose"
             ? "stream stages are the lowered surface — Node also accepts iterables (strings, arrays), generators, plain functions, and { readable, writable } pairs, but those have no lowering yet"
             : "stream arguments are the lowered surface (iterables, generators, and plain functions have no lowering yet)");
     }
@@ -1489,6 +1689,20 @@ export function lowerStreamModuleCall(lowerer, call, bi, loc) {
                 ? pipelineOptions(lowerer, lastArg)
                 : null;
             const stageArgs = opts ? args.slice(0, -1) : args;
+            if (stageArgs.some(isPipelineFunctionStage)) {
+                if (opts) {
+                    lowerer.noLowering("pipeline with function stages and options", lastArg, "pipeline(source, async function* (source) { ... }, destination) without options is supported");
+                }
+                const staged = lowerPipelineStages(lowerer, stageArgs, loc);
+                // A promise destination's value settles the result (same type).
+                return staged.wrap({
+                    kind: "libCall",
+                    fn: "sp.pipelineStages",
+                    args: staged.args,
+                    type: staged.destPromise ?? { kind: "promise", inner: VOID },
+                    loc,
+                });
+            }
             let streams;
             try {
                 streams = stageArgs.map((a) => lowerStreamArg(lowerer, a, "pipeline"));
@@ -1640,6 +1854,33 @@ export function lowerStreamModuleCall(lowerer, call, bi, loc) {
         if (args.length < 3) {
             lowerer.noLowering(`pipeline with ${args.length} arguments`, call, "the supported form is pipeline(source, ...streams, callback)");
         }
+        if (args.slice(0, -1).some(isPipelineFunctionStage)) {
+            const staged = lowerPipelineStages(lowerer, args.slice(0, -1), loc);
+            if (staged.dest !== 0) {
+                // callback(err, value): the destination's value reaches the
+                // callback through the checked-dynamic path. Node answers an
+                // object-mode PassThrough here; reading it has no lowering.
+                if (!ts.isExpressionStatement(call.parent)) {
+                    lowerer.noLowering("using the PassThrough that pipeline() answers for a function destination", call, "read the destination's value in the callback");
+                }
+                const cb = lowerer.lowerExprExpecting(args[args.length - 1], DYN);
+                return staged.wrap({
+                    kind: "libCall",
+                    fn: "stream.pipelineStagesDyn",
+                    args: [...staged.args, cb],
+                    type: staged.last,
+                    loc,
+                });
+            }
+            const { cb, dyn } = lowerEosCallback(lowerer, "pipeline", args[args.length - 1], staged.last);
+            return staged.wrap({
+                kind: "libCall",
+                fn: dyn ? "stream.pipelineStagesDyn" : "stream.pipelineStages",
+                args: [...staged.args, cb],
+                type: staged.last,
+                loc,
+            });
+        }
         let streams;
         try {
             streams = args.slice(0, -1).map((a) => lowerStreamArg(lowerer, a, "pipeline"));
@@ -1659,9 +1900,514 @@ export function lowerStreamModuleCall(lowerer, call, bi, loc) {
             loc,
         };
     }
+    if (bi.member === "compose")
+        return lowerStreamCompose(lowerer, call, loc);
     return null;
 }
+/** A pipeline() argument written as a function: an async generator
+ * function stage. */
+function isPipelineFunctionStage(node) {
+    return ts.isFunctionExpression(node) || ts.isArrowFunction(node);
+}
+/** pipeline(...) with one run of function stages (pipeline.js). The run
+ * may start the pipeline (a source function, called with `{ signal }`)
+ * and may end it (a destination function: an async generator pumped into
+ * a PassThrough, or an async function whose promise's value reaches the
+ * callback or the promise). Each stage's `source` parameter is typed as
+ * what the pipeline passes it: makeAsyncIterable answers the previous
+ * stream itself (a Readable is async iterable) or the previous stage's
+ * generator. */
+function lowerPipelineStages(lowerer, stageArgs, loc) {
+    const first = stageArgs.findIndex(isPipelineFunctionStage);
+    let end = first;
+    while (end < stageArgs.length && isPipelineFunctionStage(stageArgs[end]))
+        end++;
+    if (stageArgs.slice(end).some(isPipelineFunctionStage)) {
+        lowerer.noLowering("pipeline with function stages separated by streams", stageArgs[end], "one run of function stages is supported");
+    }
+    const source = first === 0;
+    const destFn = end === stageArgs.length;
+    const before = [];
+    const after = [];
+    try {
+        for (const a of stageArgs.slice(0, first))
+            before.push(lowerStreamArg(lowerer, a, "pipeline"));
+    }
+    catch (e) {
+        if (e instanceof StreamArgTypeThrow)
+            lowerer.noLowering("pipeline over this value", stageArgs[0]);
+        throw e;
+    }
+    let srcT = source ? null : before[before.length - 1].type;
+    const stages = [];
+    let mask = 0;
+    let dest = 0;
+    let destPromise = null;
+    for (let i = first; i < end; i++) {
+        const fn = stageArgs[i];
+        const isLast = destFn && i === end - 1;
+        const isAsync = (fn.modifiers ?? []).some((m) => m.kind === ts.SyntaxKind.AsyncKeyword);
+        const isGen = ts.isFunctionExpression(fn) && fn.asteriskToken !== undefined;
+        if (isLast && isGen) {
+            // pipeline() pumps it into an object-mode PassThrough, whose
+            // buffering decides when the pipeline finishes
+            lowerer.noLowering("a pipeline destination that is an async generator function", fn, "end the pipeline with a stream or an async function (source) { for await (const chunk of source) ... }");
+        }
+        if (!isAsync || (!isGen && !isLast)) {
+            lowerer.noLowering(isLast
+                ? "a pipeline destination that is not an async function"
+                : srcT === null
+                    ? "a pipeline source function that is not an async generator function"
+                    : "pipeline stages that are not async generator functions", fn, "write the stage as async function* (source) { for await (const chunk of source) ... }");
+        }
+        const optionsAt = srcT === null ? 0 : 1;
+        if (fn.parameters.length > optionsAt + 1) {
+            lowerer.noLowering("pipeline stages with parameters after the options argument", fn.parameters[optionsAt + 1], "a stage takes the source and { signal }");
+        }
+        const lowered = lowerStageFunction(lowerer, fn, srcT);
+        const params = lowered.closure.type.kind === "func" ? lowered.closure.type.params : [];
+        if (params.length > optionsAt) {
+            if (params[optionsAt].kind !== "dyn") {
+                lowerer.noLowering("a pipeline stage's options argument with this type", fn.parameters[optionsAt], "type it as { signal: AbortSignal }");
+            }
+            mask |= 1 << (i - first);
+        }
+        stages.push(lowered.closure);
+        if (lowered.out.kind === "promise") {
+            dest = 2;
+            destPromise = lowered.out;
+            srcT = null;
+        }
+        else {
+            srcT = lowered.out;
+        }
+    }
+    try {
+        for (const a of stageArgs.slice(end))
+            after.push(lowerStreamArg(lowerer, a, "pipeline"));
+    }
+    catch (e) {
+        if (e instanceof StreamArgTypeThrow)
+            lowerer.noLowering("pipeline over this value", stageArgs[end]);
+        throw e;
+    }
+    const helperArgs = [];
+    if (dest !== 2) {
+        // the generator pumped into the next stream or the PassThrough
+        const lastGen = srcT;
+        if (!fromGenChunk(lowerer, lastGen.yieldT)) {
+            lowerer.noLowering(`a pipeline stage yielding '${lowerer.fmt(lastGen.yieldT)}'`, stageArgs[end - 1], "stage values written to a stream are strings or Buffers");
+        }
+        const helpers = fromGenHelpers(lowerer, lastGen, loc);
+        if (!helpers)
+            lowerer.noLowering("a pipeline stage with this generator type", stageArgs[end - 1]);
+        helperArgs.push(helpers[0], helpers[1], helpers[2]);
+    }
+    else {
+        const valueT = destPromise.inner;
+        if (valueT.kind !== "void" &&
+            !canConvertToDyn(valueT, (id) => lowerer.shapes.get(id), (id) => lowerer.unions.get(id))) {
+            lowerer.noLowering(`a pipeline destination resolving to '${lowerer.fmt(valueT)}'`, stageArgs[end - 1]);
+        }
+        helperArgs.push(pipelineBoxHelper(lowerer, destPromise, loc));
+    }
+    const streams = [...before, ...after];
+    // SCR_PIPE_* flags: bit 0 a source function, bits 1-2 the destination,
+    // bit 3 the helpers, bit 4 the box, bit 5 the signal and abort.
+    const flags = (source ? 1 : 0) | (dest << 1) | (dest !== 2 ? 8 : 16) | (mask !== 0 ? 32 : 0);
+    const head = [
+        numLit(streams.length, loc),
+        numLit(before.length, loc),
+        numLit(stages.length, loc),
+        numLit(flags, loc),
+        numLit(mask, loc),
+        ...streams,
+        ...stages,
+        ...helperArgs,
+    ];
+    const last = destFn
+        ? { kind: "object", className: "%PassThrough" }
+        : streams[streams.length - 1].type;
+    if (mask === 0)
+        return { args: head, last, dest, destPromise, wrap: (call) => call };
+    // const ac = new AbortController(): its signal goes to the stages, and
+    // finishImpl's ac.abort() runs through the abort closure.
+    const ac = lowerer.declareHiddenLocal("%pipelineAbort", DYN);
+    const acRef = { kind: "varRef", localId: ac.id, type: DYN, loc };
+    const signal = {
+        kind: "dynKeyGet",
+        value: acRef,
+        key: { kind: "strLit", value: "signal", type: STRING, loc },
+        type: DYN,
+        loc,
+    };
+    return {
+        args: [...head, signal, pipelineAbortHelper(lowerer, acRef, loc)],
+        last,
+        dest,
+        destPromise,
+        wrap: (call) => ({
+            kind: "seqExpr",
+            stmts: [
+                {
+                    kind: "varDecl",
+                    localId: ac.id,
+                    init: { kind: "libCall", fn: "fetch.abortControllerNew", args: [], type: DYN, loc },
+                    loc,
+                },
+            ],
+            result: call,
+            type: call.type,
+            loc,
+        }),
+    };
+}
+/** `(p) => p` boxed: a promise destination's promise as a checked-dynamic
+ * promise, whose payload converts when the destination settles. Interned
+ * per promise type. */
+function pipelineBoxHelper(lowerer, promiseT, loc) {
+    const key = `pipelineBox:${typeKey(promiseT)}`;
+    let name = lowerer.valueHelpers.get(key);
+    if (!name) {
+        name = `%stream.pipelineBox.${lowerer.valueHelpers.size}`;
+        lowerer.valueHelpers.set(key, name);
+        lowerer.liftedFns.push({
+            name,
+            params: [{ localId: "p.0", name: "p", type: promiseT }],
+            returnType: DYN,
+            locals: [{ id: "p.0", name: "p", type: promiseT, mutable: false }],
+            body: [
+                {
+                    kind: "return",
+                    value: { kind: "dynFrom", value: varRef("p.0", promiseT, loc), type: DYN, loc },
+                    loc,
+                },
+            ],
+            loc,
+        });
+    }
+    return { kind: "closure", fnName: name, captures: [], type: funcOf([promiseT], DYN), loc };
+}
+/** `() => ac.abort()` over the pipeline's AbortController: an interned
+ * lifted function takes the controller and answers the closure. */
+function pipelineAbortHelper(lowerer, ac, loc) {
+    const key = "pipelineAbort";
+    let name = lowerer.valueHelpers.get(key);
+    const abortT = funcOf([], VOID);
+    if (!name) {
+        name = `%stream.pipelineAbort.${lowerer.valueHelpers.size}`;
+        lowerer.valueHelpers.set(key, name);
+        const acLocal = { id: "ac.0", name: "ac", type: DYN, mutable: false, boxed: true };
+        const acRef = varRef(acLocal.id, DYN, loc);
+        lowerer.liftedFns.push({
+            name: `${name}.abort`,
+            params: [],
+            returnType: VOID,
+            captures: [{ localId: acLocal.id, name: acLocal.name, type: DYN }],
+            locals: [acLocal],
+            body: [
+                {
+                    kind: "exprStmt",
+                    expr: {
+                        kind: "dynInvoke",
+                        recv: acRef,
+                        method: "abort",
+                        calleeName: "ac.abort",
+                        args: [],
+                        type: DYN,
+                        loc,
+                    },
+                    loc,
+                },
+            ],
+            loc,
+        });
+        lowerer.liftedFns.push({
+            name,
+            params: [{ localId: acLocal.id, name: acLocal.name, type: DYN }],
+            returnType: abortT,
+            locals: [acLocal],
+            body: [
+                {
+                    kind: "return",
+                    value: {
+                        kind: "closure",
+                        fnName: `${name}.abort`,
+                        captures: [acLocal.id],
+                        type: abortT,
+                        loc,
+                    },
+                    loc,
+                },
+            ],
+            loc,
+        });
+    }
+    return { kind: "call", callee: name, args: [ac], type: abortT, loc };
+}
+/** A function stage, lowered with its `source` parameter (absent for a
+ * source function, srcT null) typed as what the pipeline passes (a
+ * stream or the previous stage's generator). The source may only head
+ * `for await` loops. Answers the closure and what it returns: an async
+ * generator, or a promise for a destination async function. */
+function lowerStageFunction(lowerer, fn, srcT) {
+    const param = srcT === null ? undefined : fn.parameters[0];
+    const symbol = param && ts.isIdentifier(param.name)
+        ? lowerer.checker.getSymbolAtLocation(param.name)
+        : undefined;
+    if (param && !symbol) {
+        lowerer.noLowering("pipeline stage parameters that are patterns", param, "name the source parameter");
+    }
+    if (symbol && fn.body) {
+        const visit = (node) => {
+            if (ts.isIdentifier(node) &&
+                node !== param.name &&
+                lowerer.checker.getSymbolAtLocation(node) === symbol) {
+                const parent = node.parent;
+                if (!(parent &&
+                    ts.isForOfStatement(parent) &&
+                    parent.awaitModifier &&
+                    parent.expression === node)) {
+                    lowerer.noLowering("a pipeline stage's source used outside a for await loop head", node, "iterate the source with for await (const chunk of source)");
+                }
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(fn.body);
+    }
+    if (symbol)
+        lowerer.stageSourceTypes.set(symbol, srcT);
+    try {
+        const closure = lowerer.lowerExpr(fn);
+        const out = closure.type.kind === "func" ? closure.type.ret : null;
+        if (!(out?.kind === "generator" && out.async) && out?.kind !== "promise") {
+            lowerer.noLowering("a pipeline stage that does not return an async generator", fn);
+        }
+        return { closure, out: out };
+    }
+    finally {
+        if (symbol)
+            lowerer.stageSourceTypes.delete(symbol);
+    }
+}
+/** `stream.compose(...streams)` over stream instances: a Duplex writing
+ * to the first stream and reading from the last (scr_stream_compose). The
+ * classes fix which positions can be readable and writable; a stream in
+ * the wrong position, a single Readable or Writable (Duplex.from wraps
+ * those), and functions, iterables or web streams have no lowering. */
+function lowerStreamCompose(lowerer, call, loc) {
+    const args = call.arguments;
+    const duplex = { kind: "object", className: "%Duplex" };
+    if (args.some((a) => ts.isSpreadElement(a))) {
+        lowerer.noLowering("compose with spread arguments", call, "pass the streams directly");
+    }
+    if (args.length === 0) {
+        return nodeThrowExpr(1, "ERR_MISSING_ARGS", 'The "streams" argument must be specified', duplex, loc);
+    }
+    let streams;
+    try {
+        streams = args.map((a) => lowerStreamArg(lowerer, a, "compose"));
+    }
+    catch (e) {
+        if (e instanceof StreamArgTypeThrow)
+            return e.expr;
+        throw e;
+    }
+    const sides = streams.map((s) => s.type.kind === "object" ? streamSidesOf(lowerer, lowerer.classes.get(s.type.className)) : null);
+    if (streams.length === 1) {
+        // Duplex.from answers a duplex itself.
+        if (sides[0] === "rw")
+            return streams[0];
+        lowerer.noLowering(`compose of a single ${sides[0] === "r" ? "Readable" : "Writable"}`, args[0], "Duplex.from wraps a lone Readable or Writable, which has no lowering yet; one Duplex, Transform or PassThrough answers itself");
+    }
+    for (let i = 0; i < streams.length; i++) {
+        const s = sides[i];
+        const want = i < streams.length - 1 && s === "w" ? "readable" : i > 0 && s === "r" ? "writable" : null;
+        if (want) {
+            lowerer.noLowering(`compose with a stream that is not ${want} at position ${i}`, args[i], `Node throws ERR_INVALID_ARG_VALUE ('streams[${i}]' must be ${want}); every stream but the last must be readable and every stream but the first writable`);
+        }
+    }
+    return {
+        kind: "libCall",
+        fn: "stream.compose",
+        args: [numLit(streams.length, loc), ...streams],
+        type: duplex,
+        loc,
+    };
+}
 /* ── the method surface ───────────────────────────────────────────────── */
+/* ── the Readable operators ──────────────────────────────────────────── */
+/** The Readable operators (scr_stream_ops.c — Node's operators.js). */
+export const STREAM_OPERATORS = new Set([
+    "map",
+    "filter",
+    "flatMap",
+    "drop",
+    "take",
+    "toArray",
+    "forEach",
+    "some",
+    "every",
+    "find",
+    "reduce",
+]);
+/** An operator callback as a checked-dynamic function value. Callbacks
+ * that declare the options argument ({ signal }) are refused: the
+ * AbortSignal Node passes there has no representation. map and flatMap
+ * callbacks must produce strings or Buffers (flatMap: arrays of them, or
+ * strings) — or checked-dynamic values, which the runtime checks. */
+function lowerOperatorCallback(lowerer, node, member, maxParams) {
+    const loc = locOf(node);
+    const optionsParam = (at) => lowerer.noLowering(`${member} callbacks that declare the options argument`, at, "the { signal } argument has no lowering — take only the chunk");
+    if ((ts.isArrowFunction(node) || ts.isFunctionExpression(node)) &&
+        node.parameters.length > maxParams) {
+        optionsParam(node.parameters[maxParams]);
+    }
+    const v = lowerer.lowerExpr(node);
+    if (v.type.kind === "dyn")
+        return v;
+    if (v.type.kind !== "func" &&
+        isJsSourceFile(node.getSourceFile()) &&
+        lowerer.dynConvertible(v.type)) {
+        // JavaScript passes any value; Node's validateFunction throws.
+        return { kind: "dynFrom", value: v, type: DYN, loc };
+    }
+    if (v.type.kind !== "func") {
+        lowerer.noLowering(`${member} with a '${lowerer.fmt(v.type)}' callback`, node, "pass a function");
+    }
+    if (v.type.params.length > maxParams)
+        optionsParam(node);
+    if (member === "map" || member === "flatMap") {
+        const ret = v.type.ret.kind === "promise" ? v.type.ret.inner : v.type.ret;
+        const chunk = (t) => t.kind === "string" || t.kind === "dyn" || (t.kind === "bytes" && t.elem === "u8");
+        const ok = member === "map"
+            ? chunk(ret)
+            : ret.kind === "dyn" || ret.kind === "string" || (ret.kind === "array" && chunk(ret.elem));
+        if (!ok) {
+            lowerer.noLowering(`${member} callbacks that return '${lowerer.fmt(ret)}'`, node, member === "map"
+                ? "map results are stream chunks: strings or Buffers (object-mode streams of other values are not lowered)"
+                : "flatMap results are arrays of strings or Buffers, or strings");
+        }
+    }
+    const getRecord = (id) => lowerer.shapes.get(id);
+    const getUnion = (id) => lowerer.unions.get(id);
+    if (!canBoxFuncIntoDyn(v.type, getRecord, getUnion)) {
+        lowerer.noLowering(`${member} with this callback`, node, "the callback's parameter and result types must cross the checked-dynamic boundary");
+    }
+    return { kind: "dynFrom", value: v, type: DYN, loc };
+}
+/** An operator's options (or reduce's initial value): an object literal
+ * becomes a checked-dynamic object, checked-dynamic values pass through,
+ * absent arguments are undefined. */
+function lowerOperatorValue(lowerer, node, what, loc, literalObject) {
+    if (node === undefined)
+        return dynUndefinedExpr(loc);
+    if (literalObject && ts.isObjectLiteralExpression(node))
+        return lowerDynObjectLiteral(lowerer, node);
+    const v = lowerer.lowerExpr(node);
+    if (v.type.kind === "dyn")
+        return v;
+    if (literalObject && v.type.kind !== "undefinedT" && v.type.kind !== "nullT") {
+        lowerer.noLowering(`${what} that are not an object literal`, node, "write the options inline, e.g. { concurrency: 2 }");
+    }
+    if (!lowerer.dynConvertible(v.type)) {
+        lowerer.noLowering(`${what} of type '${lowerer.fmt(v.type)}'`, node);
+    }
+    return { kind: "dynFrom", value: v, type: DYN, loc: locOf(node) };
+}
+function lowerStreamOperator(lowerer, call, access, member) {
+    const loc = locOf(call);
+    const args = call.arguments;
+    const recv = lowerer.lowerExpr(access.expression);
+    const readable = { kind: "object", className: "%Readable" };
+    const opts = (i) => lowerOperatorValue(lowerer, args[i], `${member} options`, loc, true);
+    const fnArg = (maxParams) => {
+        if (args[0] === undefined)
+            return dynUndefinedExpr(loc);
+        return lowerOperatorCallback(lowerer, args[0], member, maxParams);
+    };
+    const lib = (fn, a, type) => ({
+        kind: "libCall",
+        fn: fn,
+        args: a,
+        type,
+        loc,
+    });
+    switch (member) {
+        case "map":
+        case "filter":
+        case "flatMap": {
+            const fn = fnArg(1);
+            const fnName = member === "map"
+                ? "readable.opMap"
+                : member === "filter"
+                    ? "readable.opFilter"
+                    : "readable.opFlatMap";
+            return lib(fnName, [recv, fn, opts(1)], readable);
+        }
+        case "drop":
+        case "take": {
+            const n = lowerOperatorValue(lowerer, args[0], `${member}'s count`, loc, false);
+            return lib(member === "drop" ? "readable.opDrop" : "readable.opTake", [recv, n, opts(1)], readable);
+        }
+        case "toArray":
+            return lib("readable.opToArray", [recv, opts(0)], { kind: "promise", inner: DYN });
+        case "forEach":
+            return lib("readable.opForEach", [recv, fnArg(1), opts(1)], { kind: "promise", inner: VOID });
+        case "some":
+        case "every": {
+            const fn = fnArg(1);
+            return lib(member === "some" ? "readable.opSome" : "readable.opEvery", [recv, fn, opts(1)], {
+                kind: "promise",
+                inner: BOOL,
+            });
+        }
+        case "find": {
+            const t = lowerer.typeOf(call);
+            const inner = lowerer.checker.getTypeArguments(t)[0];
+            if (inner && !(inner.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown))) {
+                lowerer.noLowering("find with a type-guard callback", call, "the result is a checked-dynamic value — use a boolean predicate and narrow the result");
+            }
+            return lib("readable.opFind", [recv, fnArg(1), opts(1)], { kind: "promise", inner: DYN });
+        }
+        case "reduce": {
+            const t = lowerer.typeOf(call);
+            const resultTs = lowerer.checker.getTypeArguments(t)[0];
+            let kind = 0;
+            let inner = DYN;
+            if (resultTs && !(resultTs.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown))) {
+                const mapped = lowerer.mapTypeOf(resultTs);
+                if (mapped?.kind === "f64") {
+                    kind = 1;
+                    inner = F64;
+                }
+                else if (mapped?.kind === "bool") {
+                    kind = 2;
+                    inner = BOOL;
+                }
+                else if (mapped?.kind === "string") {
+                    kind = 3;
+                    inner = STRING;
+                }
+                else if (mapped?.kind !== "dyn") {
+                    lowerer.noLowering(`reduce with a '${mapped ? lowerer.fmt(mapped) : lowerer.checker.typeToString(resultTs)}' result`, call, "reduce results are numbers, booleans, strings, or checked-dynamic values");
+                }
+            }
+            const fn = fnArg(2);
+            const init = lowerOperatorValue(lowerer, args[1], "reduce's initial value", loc, false);
+            return lib("readable.opReduce", [recv, fn, init, boolLit(args.length >= 2, loc), opts(2), numLit(kind, loc)], { kind: "promise", inner });
+        }
+    }
+    throw new InternalCompilerError(`unknown stream operator ${member}`);
+}
+/** The literal 'buffer' encoding on write()/end(): Node 24 takes it for a
+ * Buffer chunk and throws ERR_UNKNOWN_ENCODING for a string chunk. */
+function isBufferEncoding(lowerer, arg) {
+    if (arg === undefined)
+        return false;
+    const t = lowerer.typeOf(arg);
+    return t.isStringLiteralType() && t.value === "buffer";
+}
 /** The one supported encoding argument: utf8 (Node's default), as a
  * compile-time literal or absent. */
 function checkUtf8Encoding(lowerer, member, arg) {
@@ -1676,6 +2422,11 @@ function checkUtf8Encoding(lowerer, member, arg) {
  * for members this spoke does not own. */
 export function lowerStreamMethodCall(lowerer, call, access, info) {
     const member = access.name.text;
+    if (STREAM_OPERATORS.has(member)) {
+        const opSides = streamSidesOf(lowerer, info);
+        if (opSides === "r" || opSides === "rw")
+            return lowerStreamOperator(lowerer, call, access, member);
+    }
     if (!STREAM_API_MEMBERS.has(member))
         return null;
     const sides = streamSidesOf(lowerer, info);
@@ -1968,7 +2719,12 @@ export function lowerStreamMethodCall(lowerer, call, access, info) {
         // Disambiguate (chunk, cb?) vs (chunk, encoding, cb?) by the second
         // argument's static type.
         let cbArg;
-        if (args.length === 2) {
+        if (args.length >= 2 && isBufferEncoding(lowerer, args[1])) {
+            if (kind !== "bytes")
+                return nodeThrowExpr(1, "ERR_UNKNOWN_ENCODING", "Unknown encoding: buffer", BOOL, loc);
+            cbArg = args[2];
+        }
+        else if (args.length === 2) {
             const t = lowerer.mapTypeOf(lowerer.typeOf(args[1]));
             if (t?.kind === "string")
                 checkUtf8Encoding(lowerer, "write", args[1]);
@@ -2007,6 +2763,17 @@ export function lowerStreamMethodCall(lowerer, call, access, info) {
             else
                 chunkNode = args[0];
         }
+        else if (args.length >= 2 && isBufferEncoding(lowerer, args[1])) {
+            chunkNode = args[0];
+            const endKind = chunkKind(args[0]);
+            if (endKind === "string") {
+                const endT = lowerer.mapTypeOf(lowerer.typeOf(call)) ?? DYN;
+                return nodeThrowExpr(1, "ERR_UNKNOWN_ENCODING", "Unknown encoding: buffer", endT, loc);
+            }
+            if (endKind !== "bytes")
+                checkUtf8Encoding(lowerer, "end", args[1]);
+            cbArg = args[2];
+        }
         else if (args.length === 2) {
             chunkNode = args[0];
             const t = lowerer.mapTypeOf(lowerer.typeOf(args[1]));