Give constructor functions native stream state over the stream classes

docs/content/limitations/builtin-function-values.mdx

@@ -19,7 +19,11 @@ Native calls accept standard process streams; custom native streams and mutation
 In JavaScript, a constructor function can inherit from `EventEmitter`, the legacy `Stream` constructor, or a stream class through `util.inherits` or `Object.setPrototypeOf`.
 `EventEmitter.call(this)` and `Stream.call(this)` initialize the object as Node does, and its listener methods keep their state in the object's own `_events`, `_eventsCount`, and `_maxListeners` properties.
 The `captureRejections` option and `events.errorMonitor` listeners are not supported on such objects.
-Calling `Readable`, `Writable`, `Duplex`, `Transform`, or `PassThrough` with a constructor function's receiver throws `SC2020` where the call runs.
+`Readable.call(this, options)` and the same call on `Writable`, `Duplex`, `Transform`, or `PassThrough` give the object a native stream.
+The stream calls the object's `_read`, `_write`, `_final`, `_transform`, `_flush`, and `_destroy` with the object as `this`, and the stream prototypes' methods and accessors work on it.
+Its listeners live in the native stream rather than in `_events`, and `_readableState` and `_writableState` are read-only views that answer the commonly read fields.
+Typed code that receives such an object as a stream class uses its native stream, and piping a native stream into it works.
+The options the native streams refuse (`objectMode`, `decodeStrings: false`, `signal`, and others) are refused here too, as are `_writev`, `_construct`, symbol event names, `listeners()`, `rawListeners()`, `wrap()`, strings written in encodings other than UTF-8, and pipes into a destination that overrides `write()` or `end()`.
 Other class constructors passed to `util.inherits` or `util.deprecate` are refused.
 Deprecation warnings are emitted on the next tick and follow assignments to `process.noDeprecation` and `process.throwDeprecation`; compiled binaries take no Node command-line flags such as `--no-deprecation` or `--trace-deprecation`, and `process.traceDeprecation` is unsupported.
 A stored `util.deprecate` reports a `length` of 4, where Node reports 3.

packages/compiler/src/backend/executable-features.ts

@@ -33,6 +33,7 @@ export function executableLinkFeatures(mod: IrModule): NativeLinkFeatures {
     searchParams: features.searchParams,
     qs: features.qs,
     dynBuiltinClass: features.dynBuiltinClass,
+    dynBuiltinStream: features.dynBuiltinStream,
     parseArgs: features.parseArgs,
     stream: features.stream,
     net: features.net,

packages/compiler/src/backend/library-pack.ts

@@ -43,6 +43,7 @@ export async function compilePackedLibrary(
     searchParams: options.searchParams ?? false,
     qs: false,
     dynBuiltinClass: false,
+    dynBuiltinStream: false,
     parseArgs: false,
     stream: false,
     net: false,

packages/compiler/src/backend/llvm/dyn.ts

@@ -130,6 +130,8 @@ export interface DynHost extends WalkerHost {
   /** The shared adapter record: live array capsules read its `arrayOps`, so a
    * narrower return type would hand the native compiler a copy without it. */
   liveDynRefAdapter(t: IrType): LlStreamTypedRefAdapter;
+  /** See moduleUsesDynBuiltinStream. */
+  usesDynBuiltinStream?(): boolean;
   liveDynUnionRefAdapter(t: IrType & { kind: "union" }): string;
   dynPromiseAdapter(t: IrType): string;
   isErrorClass(className: string): boolean;
@@ -140,6 +142,19 @@ export interface DynHost extends WalkerHost {
 
 const FN_ATTRS = "#0";
 
+/** scr_dyn_builtin_stream_check's kind for a runtime stream class (the
+ * numbering of scr_dyn_builtin_class.c), or null. */
+function builtinStreamKind(className: string): number | null {
+  const kinds: Record<string, number> = {
+    "%Readable": 2,
+    "%Writable": 3,
+    "%Duplex": 4,
+    "%Transform": 5,
+    "%PassThrough": 6,
+  };
+  return kinds[className] ?? null;
+}
+
 export class LlDyn {
   private readonly dynMatchers = new Map<string, string>();
   private readonly dynBuilders = new Map<string, string>();
@@ -1491,6 +1506,24 @@ export class LlDyn {
       B.line(`${ref} = call ptr @scr_dyn_typed_ref_unbox(ptr %d)`);
       B.terminate(`ret ptr ${ref}`);
       B.startBlock(lNext);
+      // A constructor-function stream (scr_dyn_builtin_stream.c) carries
+      // its runtime stream.
+      const streamKind = t.kind === "object" ? builtinStreamKind(t.className) : null;
+      if (streamKind !== null && this.host.usesDynBuiltinStream?.() === true) {
+        host.declare(`declare ptr @scr_dyn_builtin_stream_check(ptr, double)`);
+        const own = B.tmp(),
+          hit = B.tmp();
+        B.line(
+          `${own} = call ptr @scr_dyn_builtin_stream_check(ptr %d, double ${f64Lit(streamKind)})`,
+        );
+        B.line(`${hit} = icmp ne ptr ${own}, null`);
+        const lOwn = B.newLabel("dc.ctor"),
+          lNotOwn = B.newLabel("dc.notctor");
+        B.condBr(hit, lOwn, lNotOwn);
+        B.startBlock(lOwn);
+        B.terminate(`ret ptr ${own}`);
+        B.startBlock(lNotOwn);
+      }
       if (t.kind !== "union" && preserveRefs) {
         const kind = this.kindOf(B, "%d");
         const capsule = B.tmp();

packages/compiler/src/backend/llvm/emitter.ts

@@ -53,7 +53,11 @@ import {
   VOID,
   classJsName,
 } from "../../ir/ir.js";
-import { moduleRuntimeFeatures, moduleUsesMockTimers } from "../../ir/runtime-features.js";
+import {
+  moduleRuntimeFeatures,
+  moduleUsesDynBuiltinStream,
+  moduleUsesMockTimers,
+} from "../../ir/runtime-features.js";
 import { captureFreeFunctions, observesStacks } from "../stack-observations.js";
 import { type DenseArrayLoop } from "./dense-array-loops.js";
 import { findInitializedByteLoopBindings } from "./byte-windows.js";
@@ -902,6 +906,11 @@ export class LlEmitter {
   /** Identity-preserving static→dyn capsules for program classes and Web
    * APIs whose values remain directly observable. */
   readonly liveDynRefAdapters = new Map<string, LlStreamTypedRefAdapter>();
+  private dynBuiltinStreamUse: boolean | undefined;
+  /** See moduleUsesDynBuiltinStream. */
+  get usesDynBuiltinStream(): boolean {
+    return (this.dynBuiltinStreamUse ??= moduleUsesDynBuiltinStream(this.mod));
+  }
   /** Runtime-arm dispatchers for live union values. */
   readonly liveDynUnionRefAdapters = new Map<string, string>();
   readonly dynPromiseAdapters = new Map<string, string>();
@@ -1405,6 +1414,7 @@ export class LlEmitter {
       fieldAbsentTestIn: (B, value, unionId) => this.fieldAbsentTestIn(B, value, unionId),
       absentInstanceRef: (unionId) => this.absentInstanceRef(unionId),
       liveDynRefAdapter: (type) => this.liveDynRefAdapter(type),
+      usesDynBuiltinStream: () => this.usesDynBuiltinStream,
       liveDynUnionRefAdapter: (type) => this.liveDynUnionRefAdapter(type),
       dynPromiseAdapter: (type) => this.dynPromiseAdapter(type),
       isErrorClass: (name) => this.classMeta.get(name)?.root.def.name === "%Error",

packages/compiler/src/backend/llvm/expr-stream-bridges.ts

@@ -766,8 +766,13 @@ export function streamTypedRefMaterializeAdapter(
       !meta.def.instancePrototypeHelper &&
       !meta.def.prototypeDataHelper
     ) {
-      host.declare(`declare ptr @scr_stream_dyn_view(ptr)`);
-      B.line(`${out} = call ptr @scr_stream_dyn_view(ptr %p)`);
+      // Programs with constructor-function streams view them through
+      // scr_dyn_builtin_stream.c, which answers their own objects.
+      const view = host.usesDynBuiltinStream
+        ? "scr_dyn_builtin_stream_view"
+        : "scr_stream_dyn_view";
+      host.declare(`declare ptr @${view}(ptr)`);
+      B.line(`${out} = call ptr @${view}(ptr %p)`);
     } else B.line(`${out} = call ptr @scr_dyn_new_obj()`);
     const withAttributes = meta.def.fields.some((field) => field.name === CLASS_ATTRIBUTES);
     if (meta.def.tracksOwnFields) {

packages/compiler/src/backend/llvm/lib-dispatch.ts

@@ -548,7 +548,12 @@ export function emitGenericLibCall(host: LlvmEmitterContext, e: LibCallExpr): Ll
     mockTimerSym(host, e) ??
     (e.fn === "timers.queueMicrotaskDyn" && host.schedulesInContext
       ? "scr_queue_microtask_dyn_als"
-      : LIB_FN_SYMS[e.fn]);
+      : // Programs with constructor-function streams unbox untyped pipe
+        // destinations and pipeline stages through scr_dyn_builtin_stream.c,
+        // which also takes those streams.
+        e.fn === "stream.unboxDyn" && host.usesDynBuiltinStream
+        ? "scr_dyn_builtin_stream_unbox"
+        : LIB_FN_SYMS[e.fn]);
   if (sym === undefined) throw new LlvmUnsupportedError(`libCall:${e.fn}`, e.loc);
   const args = READ_ONLY_STRING_LIB_FNS.has(e.fn)
     ? emitBorrowedInputs(host, e.args)

packages/compiler/src/backend/llvm/lib-shared.ts

@@ -1438,6 +1438,7 @@ export const LIB_FN_SYMS: Record<string, string> = {
   "dyn.classBasePrototype": "scr_dyn_class_base_prototype",
   "dyn.classInherit": "scr_dyn_class_inherit",
   "dyn.builtinClass": "scr_dyn_builtin_class",
+  "dyn.builtinStreamClass": "scr_dyn_builtin_stream_class",
   "dyn.builtinInstanceOf": "scr_dyn_builtin_instanceof",
   "dyn.functionInstanceOf": "scr_dyn_function_instanceof",
   "dyn.classSuper": "scr_dyn_class_super",
@@ -1516,6 +1517,8 @@ export function mockTimerSym(
 
 export const USES_TIMERS_LIB_FNS = new Set<string>([
   "process.emitWarning",
+  // Constructor-function streams defer their events on the stream ticks.
+  "dyn.builtinStreamClass",
   // Decipheriv.setAuthTag reports DEP0182 on the next tick.
   "crypto.cipherNew",
   // WebCrypto results settle through the deferred crypto queue.

packages/compiler/src/backend/native-link-info-core.ts

@@ -50,6 +50,7 @@ export interface NativeLinkFeatures {
   searchParams: boolean;
   qs: boolean;
   dynBuiltinClass: boolean;
+  dynBuiltinStream: boolean;
   parseArgs: boolean;
   stream: boolean;
   net: boolean;

packages/compiler/src/backend/native/contracts.ts

@@ -157,6 +157,10 @@ export interface CcOptions {
    * scr_dyn_builtin_class.c, which also references the inspection,
    * dyn-invoke and symbol units. */
   dynBuiltinClass?: boolean;
+  /** The program uses a stream class as an untyped constructor value:
+   * compiles scr_dyn_builtin_stream.c, the constructors' stream half, which
+   * also references the stream unit. */
+  dynBuiltinStream?: boolean;
   /** The program uses native util parsing, comparison, or styling. Optional
    * utility units also require their symbol, inspection, and warning features. */
   parseArgs?: boolean;

packages/compiler/src/backend/native/executable.ts

@@ -245,6 +245,16 @@
       (u.opts.emitter || u.opts.workers),
     "scr_dyn_builtin_class.c",
   ),
+  unit(
+    (u) =>
+      u.opts.dynBuiltinStream &&
+      u.opts.dynBuiltinClass &&
+      u.opts.stream &&
+      u.opts.inspect &&
+      u.opts.dynInvoke &&
+      u.opts.symbol,
+    "scr_dyn_builtin_stream.c",
+  ),
   unit((u) => u.opts.stream, "scr_stream.c", "scr_fs_stream.c"),
   // The zlib stream classes reference both the zlib engine and the
   // stream unit.
@@ -784,7 +794,7 @@
     }
   };
   const buildExecutable = async (
     runtimeInput: (path: string) => string,
     build: { programPath?: string; outPath?: string; compilerVisibleSource?: string } = {},
   ): Promise<void> => {
     if (!separateSanitizedProgram) {

packages/compiler/src/backend/runtime-pack-targets.test.ts

@@ -108,6 +108,7 @@ const features = {
   searchParams: false,
   qs: false,
   dynBuiltinClass: false,
+  dynBuiltinStream: false,
   parseArgs: false,
   stream: false,
   net: false,

packages/compiler/src/backend/runtime-pack.test.ts

@@ -45,6 +45,7 @@ const BASE: NativeLinkFeatures = {
   searchParams: false,
   qs: false,
   dynBuiltinClass: false,
+  dynBuiltinStream: false,
   parseArgs: false,
   stream: false,
   net: false,

packages/compiler/src/backend/warm-cache.ts

@@ -51,6 +51,7 @@ export async function warmNativeCaches(
         searchParams: false,
         qs: false,
         dynBuiltinClass: false,
+        dynBuiltinStream: false,
         parseArgs: false,
         stream: false,
         net: false,

packages/compiler/src/executable/executable-cache.test.ts

@@ -46,6 +46,7 @@ const native: EarlyExecutableNativeFeatures = {
   searchParams: false,
   qs: false,
   dynBuiltinClass: false,
+  dynBuiltinStream: false,
   parseArgs: false,
   stream: false,
   net: false,

packages/compiler/src/executable/executable-cache.ts

@@ -73,6 +73,7 @@ export interface EarlyExecutableNativeFeatures {
   searchParams: boolean;
   qs: boolean;
   dynBuiltinClass: boolean;
+  dynBuiltinStream: boolean;
   parseArgs: boolean;
   stream: boolean;
   net: boolean;
@@ -192,6 +193,7 @@ const BOOLEAN_NATIVE_KEYS = [
   "searchParams",
   "qs",
   "dynBuiltinClass",
+  "dynBuiltinStream",
   "parseArgs",
   "stream",
   "net",

packages/compiler/src/frontend/lowering/builtins/builtin-class-dyn.ts

@@ -111,8 +111,18 @@ export function builtinClassDynValueOf(lowerer: Lowerer, node: ts.Expression): I
   };
 }
 
+/** EventEmitter and the legacy Stream are dyn.builtinClass; the stream
+ * classes, which carry native stream state for constructor functions, are
+ * dyn.builtinStreamClass, so only programs that use them link the stream
+ * half. */
 export function builtinClassValue(kind: number, loc: SrcLoc): IrExpr {
-  return { kind: "libCall", fn: "dyn.builtinClass", args: [numLit(kind, loc)], type: DYN, loc };
+  return {
+    kind: "libCall",
+    fn: kind <= 1 ? "dyn.builtinClass" : "dyn.builtinStreamClass",
+    args: [numLit(kind, loc)],
+    type: DYN,
+    loc,
+  };
 }
 
 /** `Base.call(this, …)` / `Base.apply(this, args)` on one of those class

packages/compiler/src/index.ts

@@ -552,6 +552,7 @@ async function compileExecutableNative(
     searchParams: features.searchParams,
     qs: features.qs,
     dynBuiltinClass: features.dynBuiltinClass,
+    dynBuiltinStream: features.dynBuiltinStream,
     parseArgs: features.parseArgs,
     stream: features.stream,
     net: features.net,

packages/compiler/src/ir/builtin-signatures.ts

@@ -3540,6 +3540,10 @@ export const LIB_FN_SIGS = defineLibFnSignatures({
    * Transform (5) and PassThrough (6) as untyped constructor values, one
    * per thread (scr_dyn_builtin_class.c). */
   "dyn.builtinClass": { argTypes: [F64], result: DYN },
+  /** The stream classes (2-6 above) with their stream half: constructor
+   * functions over them get native stream state
+   * (scr_dyn_builtin_stream.c). */
+  "dyn.builtinStreamClass": { argTypes: [F64], result: DYN },
   /** `value instanceof C` for those constructors, over the value's
    * prototype chain. */
   "dyn.builtinInstanceOf": { argTypes: [DYN, F64], result: BOOL },

packages/compiler/src/ir/runtime-features.ts

@@ -248,6 +248,8 @@ const CHILD_PROCESS_LIB_PREFIXES: readonly string[] = ["child.", "cp.", "spawnRe
  * emitter unit, so each of them links all five. */
 const BUILTIN_CLASS_LIB_FNS: readonly IrLibFn[] = [
   "dyn.builtinClass",
+  // the stream classes, through scr_dyn_builtin_stream.c
+  "dyn.builtinStreamClass",
   "dyn.builtinInstanceOf",
   "dyn.functionInstanceOf",
 ];
@@ -539,6 +541,10 @@ const RUNTIME_FEATURE_RULES = {
   dynBuiltinClass: rule({
     fns: [...BUILTIN_CLASS_LIB_FNS],
   }),
+  /** The stream classes as untyped constructor values with their stream
+   * half (scr_dyn_builtin_stream.c): native stream state for constructor
+   * functions, over the stream unit. */
+  dynBuiltinStream: rule({ fns: ["dyn.builtinStreamClass"] }),
   dynInvoke: rule({
     initial: (mod) => mod.workers === true,
     fns: [...DYN_INVOKE_LIB_FNS, ...UTIL_CALLABLE_LIB_FNS, ...BUILTIN_CLASS_LIB_FNS],
@@ -660,7 +666,7 @@ const RUNTIME_FEATURE_RULES = {
   }),
   stream: rule({
     initial: (mod) => (mod.classes ?? []).some((c) => RUNTIME_STREAM_CLASSES.has(c.name)),
-    fns: [...STREAM_LIB_FNS],
+    fns: [...STREAM_LIB_FNS, "dyn.builtinStreamClass"],
     prefixes: STREAM_LIB_PREFIXES,
   }),
   /** A Dirent row converted to dyn carries Node's Symbol(type) key
@@ -705,6 +711,7 @@ function noRuntimeFeatures(): RuntimeFeatures {
     dnsPromises: false,
     dynAsync: false,
     dynBuiltinClass: false,
+    dynBuiltinStream: false,
     dynInvoke: false,
     dynTier: false,
     emitter: false,
@@ -869,6 +876,14 @@ export function moduleUsesStream(mod: IrModule): boolean {
   return scanRuntimeFeatures(mod, "stream").stream;
 }
 
+/** True when the program links scr_dyn_builtin_stream.c (stream classes
+ * as untyped constructor values): its runtime streams box through that
+ * unit's view and checked casts to the stream classes accept constructor-
+ * function streams. Programs without it keep their exact code. */
+export function moduleUsesDynBuiltinStream(mod: IrModule): boolean {
+  return scanRuntimeFeatures(mod, "dynBuiltinStream").dynBuiltinStream;
+}
+
 export const NPM_COMPRESS_MIN = 1024;
 
 export function moduleUsesZlib(mod: IrModule): boolean {

packages/compiler/src/native/cli.ts

@@ -90,6 +90,7 @@ async function main(): Promise<number> {
               searchParams: false,
               qs: false,
               dynBuiltinClass: false,
+              dynBuiltinStream: false,
               parseArgs: false,
               stream: false,
               net: false,

packages/compiler/src/native/prepare.ts

@@ -144,6 +144,7 @@ function validFeatures(value: unknown): value is NativeLinkFeatures {
     "searchParams",
     "qs",
     "dynBuiltinClass",
+    "dynBuiltinStream",
     "parseArgs",
     "stream",
     "net",

packages/compiler/src/native/sanitizer.test.ts

@@ -97,6 +97,7 @@ test.skipIf(process.platform !== "linux" && process.platform !== "darwin")(
               searchParams: false,
               qs: false,
               dynBuiltinClass: false,
+              dynBuiltinStream: false,
               parseArgs: false,
               stream: false,
               net: false,

packages/compiler/test/ts7/baselines/order-parity/tests/corpus/6560-constructor-function-readable.cjs.json

@@ -0,0 +1,6 @@
+{
+ "order": [
+  "<repo>/tests/corpus/6560-constructor-function-readable.cjs"
+ ],
+ "diags": []
+}

packages/compiler/test/ts7/baselines/order-parity/tests/corpus/6561-constructor-function-writable.cjs.json

@@ -0,0 +1,6 @@
+{
+ "order": [
+  "<repo>/tests/corpus/6561-constructor-function-writable.cjs"
+ ],
+ "diags": []
+}

packages/compiler/test/ts7/baselines/order-parity/tests/corpus/6562-constructor-function-transform.cjs.json

@@ -0,0 +1,6 @@
+{
+ "order": [
+  "<repo>/tests/corpus/6562-constructor-function-transform.cjs"
+ ],
+ "diags": []
+}

packages/compiler/test/ts7/baselines/order-parity/tests/corpus/6563-constructor-function-stream-errors.cjs.json

@@ -0,0 +1,6 @@
+{
+ "order": [
+  "<repo>/tests/corpus/6563-constructor-function-stream-errors.cjs"
+ ],
+ "diags": []
+}

packages/compiler/test/ts7/baselines/order-parity/tests/corpus/6564-constructor-function-stream-late-hooks.cjs.json

@@ -0,0 +1,6 @@
+{
+ "order": [
+  "<repo>/tests/corpus/6564-constructor-function-stream-late-hooks.cjs"
+ ],
+ "diags": []
+}