@scriptc/threads

Zero-copy sharing of immutable object graphs between worker threads in scriptc builds, with a Node.js implementation that gives the same graphs the same immutability.

import { Worker, isMainThread, workerData } from "node:worker_threads";
import { publish, sharesPublishedGraphs } from "@scriptc/threads";

if (isMainThread) {
  const program = publish(buildProgram()); // immutable from here on
  new Worker(new URL(import.meta.url), { workerData: { program } });
} else {
  const program = publish((workerData as { program: Program }).program);
  check(program);
}

Contract

publish(value) returns value after making it and everything it reaches immutable.

• Publishable: primitives other than symbols, plain objects, arrays, class instances, Map and Set. Anything else that is actually reached (functions, symbols, accessor properties, Date, RegExp, Error, Promise, typed arrays and other built-in objects) makes publish throw a TypeError (Cannot publish a function, Cannot publish a Date object, ...) and leaves the whole graph unchanged: both implementations validate the graph before changing anything.
• Writes into a published graph throw Node's frozen-object TypeErrors: Cannot assign to read only property 'x' of object '#<Point>', Cannot add property 3, object is not extensible, Cannot delete property '2' of [object Array], and so on. Published Maps and Sets reject set, add, delete and clear with Cannot modify a published Map (or Set).
• publish is idempotent; publishing an already published graph is cheap.

In scriptc builds a published graph is also immortal: it is never reference counted, collected or freed again, and postMessage and workerData deliver it to other threads by reference (sharesPublishedGraphs is true). Node.js clones what it posts (sharesPublishedGraphs is false). Programs that behave identically under both follow three rules:

1. A receiver calls publish on what it receives. In scriptc this is a no-op; in Node.js it freezes the clone, so writes fail the same way.
2. A receiver does not depend on prototypes. scriptc delivers the same class instances, with their methods and instanceof relations; Node's structured clone delivers plain objects. Error messages that name the receiving object's class differ accordingly (#<Point> in scriptc, #<Object> in Node.js).
3. Identity is not compared across messages. Two posts of one published graph arrive as the same object in scriptc and as two clones in Node.js.

scriptc specifics

• Publication walks the graph once (compiler-generated walkers per static type) and marks every object immortal. Static types over-approximate what a graph holds, so an unpublishable type reachable from the root's type is only refused if a value of it is actually present.
• Stores into the static types a program publishes carry a guard (one load and branch). In a store o.x = f(), Node evaluates f() before the write fails; scriptc does too, except for writes into union-typed class fields and for Map/Set/array mutator methods, where the guard runs before the arguments are evaluated.
• Private fields (#x) of published objects cannot be written either (Node.js allows writing private fields of frozen objects).
• Published objects must not be written by any thread; scriptc enforces this for every store the compiler emits.