@amritk/nish-aarch64-darwin 0.34.1 → 0.36.0

package/INSTALL.md

@@ -52,7 +52,14 @@ export PATH="$(brew --prefix llvm@18)/bin:$PATH"   # add to your shell profile
 ```
 
 Xcode's `clang` (`xcode-select --install`) also works for native binaries;
-the Homebrew LLVM is needed for the `wasm` and `wasi` profiles (`wasm-ld`).
+the Homebrew LLVM is needed for the `wasm`, `wasm-host` and `wasi` profiles (`wasm-ld`).
+
+`wasm-opt` (binaryen: `apt-get install binaryen`, `brew install binaryen`) is
+optional. When it is on `PATH`, `scripts/build.sh --profile wasm-host` runs
+`wasm-opt -Oz` on the module, and the build line says whether it ran. Without
+it the module is complete, just not as small.
+
+<a id="wasi-optional-for---profile-wasi" style="scroll-margin-top: 65px"></a>
 
 ### WASI (optional, for `--profile wasi`)
 
@@ -105,7 +112,7 @@ of its own architecture by the release workflow before the release existed, and
 installing is a download and an unpack.
 
 Through npm, which is also how an Nish *program* resolves its dependencies
-([wp21-packages.md](wp21-packages.md)), so this is the one to pick if you want
+([wp21-packages.md](https://github.com/amritk/nish/blob/main/docs/wp21-packages.md)), so this is the one to pick if you want
 the compiler pinned per project in a `package.json`:
 
 ```bash
@@ -169,7 +176,7 @@ release also attaches `nish-<version>.spdx.json`, an SPDX 2.3 software bill of
 materials: every attached file with its SHA-256, the clang, linker, Node.js
 and seed compiler that built each tarball (recorded by the build row itself),
 and the vendored code from
-[THIRD_PARTY_NOTICES.md](../THIRD_PARTY_NOTICES.md) that each of them contains.
+[THIRD_PARTY_NOTICES.md](https://github.com/amritk/nish/blob/main/THIRD_PARTY_NOTICES.md) that each of them contains.
 How these fit the rest of the release's defences is
 [docs/security/supply-chain.md](security/supply-chain.md).
 
@@ -198,13 +205,13 @@ never fails over it.
 > installers above handle it by running the binary through a one-line `exec` of
 > an absolute path. If you unpack a tarball by hand, invoke it by path
 > (`nish-<version>-<asset>/bin/nish`) or write that wrapper yourself. The
-> underlying defect is [wp19 §5a](wp19-stage0-retirement.md#5a-what-r6-is-waiting-on)
+> underlying defect is [wp19 §5a](https://github.com/amritk/nish/blob/main/docs/wp19-stage0-retirement.md#5a-what-r6-is-waiting-on)
 > item 4.
 
 **The package is `nish` from 0.20.0.** Releases up to 0.18.0 were published
 as `@amritk/nish` (0.19.0's publish to npm failed), which is deprecated and
 points here; `npm install -g nish`
-replaces it ([docs/wp12-release.md](wp12-release.md#the-npm-name)). Versions
+replaces it ([docs/wp12-release.md](https://github.com/amritk/nish/blob/main/docs/wp12-release.md#the-npm-name)). Versions
 0.0.0 and 0.0.1 of `nish` are an unrelated 2014 project that held the name
 before it, so pin `nish@^0.20.0` or later rather than an older range.
 
@@ -233,9 +240,9 @@ nish: no prebuilt compiler for freebsd/x64
 Until 0.6.0 it ran the TypeScript compiler that shipped in the same package
 instead — the same compiler by every test here, about eight times slower, and
 no C toolchain needed. That compiler was stage0, which was deleted in R6
-([wp19](wp19-stage0-retirement.md)), so there is nothing left in the package to
+([wp19](https://github.com/amritk/nish/blob/main/docs/wp19-stage0-retirement.md)), so there is nothing left in the package to
 fall back to. The cost is stated where the rest of that deletion's costs are,
-in [wp19 §6](wp19-stage0-retirement.md#6-what-retirement-costs-stated-plainly),
+in [wp19 §6](https://github.com/amritk/nish/blob/main/docs/wp19-stage0-retirement.md#6-what-retirement-costs-stated-plainly),
 and it is a real one: **musl, FreeBSD and 32-bit platforms have no `npm
 install` route to a compiler any more.**
 
@@ -276,7 +283,7 @@ to have on the issue tracker rather than a workaround to discover here.
 `nish` from 0.20.0; 0.19.0 is on GitHub only, because its npm publish
 failed. Every release publishes the main package and its platform packages to
 npm from `release.yml`, by trusted publishing
-([docs/wp12-release.md](wp12-release.md#release-procedure) step 4), so
+([docs/wp12-release.md](https://github.com/amritk/nish/blob/main/docs/wp12-release.md#release-procedure) step 4), so
 `npm install -g nish` is the whole install. The rest of this section is
 for a machine that cannot reach the registry, or a release before 0.10.0.
 
@@ -358,7 +365,7 @@ v0.16.0; v0.1.1 was the first release with a binary attached.
 The `v0.1.0` tag exists but has no release behind it and no assets, so every
 `v0.1.0` download URL is a 404 — the tag was pushed by a workflow, and GitHub
 raises no event for that, so nothing ever built it
-([docs/wp12-release.md](wp12-release.md#release-procedure) step 2). When a newer
+([docs/wp12-release.md](https://github.com/amritk/nish/blob/main/docs/wp12-release.md#release-procedure) step 2). When a newer
 release exists, take its version from
 [the releases page](https://github.com/amritk/nish/releases/latest).
 
@@ -435,7 +442,7 @@ over, `runtime-checksum.c` the CRC-32 kernels of `nish/compress/checksum`,
 `runtime-sandbox.c` the confinement a `--sandbox` build applies, and
 `runtime-shm.c` the shared-memory regions of `nish/sync/shm`.
 They are separate so that each carries its own measured size ceiling
-([docs/wp7-runtime.md](wp7-runtime.md)); nothing in the core calls into the
+([docs/wp7-runtime.md](https://github.com/amritk/nish/blob/main/docs/wp7-runtime.md)); nothing in the core calls into the
 others, so a line that names only `runtime.c` and `runtime-os.c` still links a
 program that uses none of the other nine. `scripts/build.sh` compiles the other
 nine beside any
@@ -451,7 +458,7 @@ beside `-DNISH_THREADS=1`).
 ## 2a. What `npm run build` does
 
 `src/` is the compiler, written in Nish, and it compiles itself
-([docs/wp14-selfhost.md](wp14-selfhost.md)). From a checkout, with clang on
+([docs/wp14-selfhost.md](https://github.com/amritk/nish/blob/main/docs/wp14-selfhost.md)). From a checkout, with clang on
 `PATH`, `npm run build` runs `scripts/bootstrap.sh` with the seed from §2:
 
 ```bash
@@ -486,7 +493,7 @@ in `src/` and becomes usable inside `src/` from the next release on; CI's
 `bootstrap` job is what checks that the released seed still builds stage1.
 Until R6 the seed was a TypeScript compiler, stage0, run under Node; it was
 deleted once the native one answered every flag it did
-([wp19](wp19-stage0-retirement.md)).
+([wp19](https://github.com/amritk/nish/blob/main/docs/wp19-stage0-retirement.md)).
 
 ## 3. Hello world
 
@@ -518,7 +525,7 @@ nish hello.ts -o hello.ll
 
 Other build profiles: `--profile size` (smallest binary), `--profile debug`
 (no optimisation, symbols kept). Run `nish --help` for every flag, and
-see the [README](../README.md) for the language subset.
+see the [README](https://github.com/amritk/nish/blob/main/README.md) for the language subset.
 
 To use a program as a script rather than keep the binary, run it:
 
@@ -549,6 +556,8 @@ it cannot make private, compiles the runtime itself as it always did; the
 wasi profile and `scripts/build.sh` called directly never use the cache.
 Removing the directory is always safe.
 
+<a id="4-exit-codes" style="scroll-margin-top: 65px"></a>
+
 ## 4. Exit codes
 
 | Code | Meaning |

package/docs/AI.md

@@ -108,7 +108,9 @@ the difference is a row of [the user guide's table](guide/using-nish/to-typescri
 or a bug in `nish` worth reporting. A program on `nish:net`, the signal
 descriptor or a C declaration (NL4010, NL4011), a compound assignment whose
 index would run twice (NL4012) or a generic whose element type decides its
-code (NL4013, NL4014) is refused and has no TypeScript to run.
+code (NL4013, NL4014) is refused and has no TypeScript to run. An `async`
+program is written as Node async/await, whose spawned tasks may print in
+another order than native.
 
 Two more surfaces worth knowing: `nish --emit-ast f.ts` prints what was parsed
 and `nish --emit-checked f.ts` prints the side tables the emitter reads. Both
@@ -140,7 +142,11 @@ everywhere, a template literal instead of `String(n)`.
 - A module is one `.ts` file. At the top level it may hold **only**
   declarations: `const` arrows (functions), `class`, `interface`, module
   `const`s, `type` aliases, numeric `enum`s, and `import`s. There is no
-  top-level code, so there is no initialisation order to think about.
+  top-level code, so there is no initialisation order to think about. The
+  one exception is an entry module with no `main`: its top-level statements
+  run as `main` (`docs/LANGUAGE.md` → "Top-level code"). Declare every
+  function above the first statement, and pass a function what it needs
+  rather than naming a variable of the code.
 - `export const main` lives in the entry module only, takes no parameters, and
   returns `void` or an `i32`-lowered `number` — the process exit code. Under
   `--number-mode f64`, declare it `main(): i32`.
@@ -175,12 +181,12 @@ rejects. This table is the highest-value part of the page.
 | `h.get<i32>(7)` (type argument at a method call) | `Type arguments are not written at a call site in Nish` | `h.get(7)` — a generic method infers like a generic function |
 | `<T>(p: T) => p.x` (a member of a type parameter) | `` Cannot read `x` of `T`: an unconstrained type parameter has no members `` | `<T extends Point>(p: T) => p.x`, where `Point` is a class or interface that declares `x` |
 | `identity<i32>(7)` (type argument at a call) | `Type arguments are not written at a call site in Nish` | `identity(7)` — `T` is inferred from the arguments |
-| `async` / `await` / `Promise` | forbidden (no event loop) | the I/O builtins are synchronous |
+| a promise in a variable, `.then`, `Promise.all` | forbidden: a promise is never a value | `await` each call where it is made; see [Async functions](#async-functions) |
 | `namespace N { }`, `declare global { }`, `@decorator` | forbidden | one module per file; a plain function in place of a decorator |
 | `keyof T`, `<T = i32>` (a default type argument) | `` Unsupported type `keyof T` (Phase 1 supports …) `` / `a default type argument … is not supported` | name the type; a type argument is always inferred |
 | `class B extends A` | `` `extends` is not supported: Nish has no inheritance `` | repeat the fields and `implements` an interface |
 | `static` members, `get x()` / `set x(v)` | `` … `static` members are not supported `` / `` Getters and setters are not supported in class `C` (use a method) `` | module `const`s and plain methods |
-| `const [a, b] = xs`, `({ x }: Point) =>`, `(n?: i32)`, `(n = 1)`, `f(...xs)` | `Destructuring is not supported` / `Destructured parameters are not supported` / `Optional parameters are not supported` / `` Parameter `n` has a default and no type annotation `` / `Spread arguments are not supported` | one name per binding; `n: i32 = 1` (a constant or an earlier parameter) for a default; `...ns: i32[]` as the last parameter, or pass the array itself |
+| `const [a, b] = xs`, `({ x }: Point) =>`, `(n?: i32)`, `(n = 1)`, `f(...xs)` | `Destructuring is not supported` / `Destructured parameters are not supported` / `Optional parameters are not supported` / `` Parameter `n` has a default and no type annotation `` / `Spread arguments are not supported` | one name per binding; `n: i32 = 1` (a constant or an earlier parameter) for a default, `o: Opts | null = null` for an options argument; `...ns: i32[]` as the last parameter, or pass the array itself |
 | `function f(): void;` (an overload), `export default function ()` | `Functions must have a body` / `Functions must be named` | one named function, with its body |
 | a method in an `interface` | `` Interface `I` cannot declare methods (interfaces describe layout only) `` | fields only; a top-level function over the interface |
 | `abstract class`, `declare class`, `constructor(public x: i32)`, `interface B extends A`, `[k: string]: T` | `Abstract classes are not supported` / `` `declare class` is not supported `` / `Parameter properties … are not supported; declare the field and assign it` / ``Interface inheritance (`extends`) is not supported; list every field`` / `Index signatures are not supported …` | a plain class with its fields declared and assigned in the constructor; every field listed; a `Map` for a keyed table |
@@ -583,8 +589,11 @@ const double = (n: i32): i32 => n * 2;   // a concise body is that one `return`
 - **Parameters are immutable**: `p = 1`, `p++`, `p += 1` are all rejected. Copy
   into a `let` first.
 - A non-`void` function must return on every path.
-- Rejected: generators, `async`, destructured / rest / optional / default
-  parameters, overloads, nested function declarations. Type parameters *are*
+- Rejected: generators, a method that is `async`, destructured and optional
+  (`x?: T`) parameters, overloads, nested function declarations. A default
+  (`n: i32 = 1`) or a rest parameter (`...ns: i32[]`) is allowed on a
+  function, a method, a constructor or a module `const` arrow — see
+  "Optional parameters" in [Recipes for what is missing](#recipes-for-what-is-missing). Type parameters *are*
   allowed — see [Generic functions](#generic-functions).
 
 ### Generic functions
@@ -850,8 +859,8 @@ export const main = (): i32 => {
   (`(x) => { if (x > limit) { hits.push(x) } }`); each capture becomes one more
   argument of the direct call. It may not assign to one, read a `let`
   (`` The arrow reads `k`, a `let` of the function it is written in: ... bind the value to a `const` before the call ``),
-  read `this` (bind `const self = this`), or read a function parameter of its
-  function. An arrow inside another arrow, or given to a method, a
+  read `this` (bind `const self = this`), or read a function-typed parameter
+  of its function. An arrow inside another arrow, or given to a method, a
   constructor, `expose` or `exposeWith`, captures nothing; `xs.sort(cmp)`'s
   comparator is the exception, and captures as an arrow argument does.
 - **The argument's type must match exactly**: `(x: i32) => i64` for a
@@ -873,6 +882,52 @@ export const main = (): i32 => {
 };
 ```
 
+### Async functions
+
+`async` compiles natively: a function that awaits becomes a frame and a resume
+switch, one that awaits nothing a plain function, and `export async function
+main` runs to its end, then finishes every task it spawned. Nothing waits on
+sockets or timers in this release, so every task runs to completion.
+`--emit-ts` writes it as Node async/await, where `spawn`ed tasks resume in
+Node's order, not the native one. A call
+that can fail answers `Promise<Result<T, E>>`: test the `Result` after the
+`await`. The rules:
+
+- `async` goes on a top-level `function` or an arrow, never a method
+  (`NL1063`). Its return type is `Promise<T>` (`NL2655`), and `Promise<T>`
+  appears nowhere else — not on a parameter, field, local or alias (`NL2654`).
+- **`await` takes a direct call to an `async` function** (`NL2643` for a value,
+  `NL2644` for a plain function's call), **at the top of a statement**: alone,
+  as a `const`/`let` initializer, after `return`, or right of a plain `=`.
+  Anywhere inside a larger expression is `NL2642`, so bind first:
+  `const n = await load(1); console.log(n);`.
+- An `async` call that is not awaited is `NL2645`: a promise is never a value.
+  No `.then` (`NL2650`), no `Promise.all` (`NL2649`), no `for await`
+  (`NL2133`).
+- Several at once: `import { awaitAll, spawn } from "nish:async"`, then
+  `const [a, b] = await awaitAll(f(x), g(y))` (two to eight calls, one name
+  each, `NL2647`). `spawn(f(x))` starts a task without waiting; `f` answers
+  `void` or a `Result` (`NL2646`).
+- No recursion through `await`, direct or mutual (`NL2648`): write a loop.
+- An `async` arrow goes only to a parameter whose function type answers
+  `Promise<T>` (`NL2639`), and only an `async` one goes there (`NL2640`).
+- No `async` under a wasm target or `--profile wasi` (`NL2652`).
+- `spawn(f(x))` runs `f` at once, until it first waits on the outside world,
+  before it returns; Node runs `f` only to its first `await` and the rest
+  after the spawning task yields. Do not rely on either order.
+
+```ts nish:err NL2642
+async function load(id: i32): Promise<i32> {
+  return id;
+}
+
+async function run(): Promise<void> {
+  console.log(await load(1));
+}
+
+export const main = (): i32 => 0;
+```
+
 ### Data parallelism: `nish/threads`
 
 `parallelMapInto(src, dst, f)` writes `f(src[i])` into `dst[i]`, and
@@ -1425,6 +1480,13 @@ export const main = (): i32 => {
 ```
 
 - **No body, and it cannot be `export`ed.**
+- **Not in a `--target wasm32` build, nor an `--emit-dts` one with no
+  `--target`** (NL2666; `--target wasm32-wasi` keeps it): there a function the page
+  supplies is imported from a host module, the page's own TypeScript file
+  named by `--host`, and becomes a wasm import from module `host`. Only
+  scalars, enums and `HostHandle<"kind">` (a nominal `i32` for an object the
+  page keeps) cross; `import { Canvas, fill } from "./host.ts"`, no `type`
+  modifier.
 - **A class with a `CPtr` field is a handle class: open one with `using`.**
   `using f = new File(p)` closes `f` once at every exit of its block (falling
   off the end, `return`, `break`, `continue`, `orReturn()`), so never call the
@@ -2243,7 +2305,8 @@ backlog)`, `tcpAccept(fd, peer)`, `netRead(fd, buf, off, len)`,
 `i32`: **a negative number is a failure, not an exception** — `-11` means "would
 block, call again", `-32` a peer that has gone (never SIGPIPE), `-98` the port
 is in use, `-111` refused, `-22` a bad argument. Every socket is non-blocking,
-and there is no `async` and no callback: your `main` is the loop. A client calls
+and there is no callback, and an `async` function cannot wait on a socket yet
+(its tasks run on an in-process queue): your `main` is the loop. A client calls
 `tcpConnect(addr)`, which answers the descriptor while it is still connecting;
 wait for it to be writable, then `connectResult(fd)` is 0 or the failure. Buffers
 are `u8[]` only; an address is 18 bytes of one (IPv4 as `::ffff:a.b.c.d`, then
@@ -2254,6 +2317,9 @@ To fetch a URL from a CLI, skip all of this: `nish/net/fetch`'s
 response's head is in and answers it with `body.readAll(limit)`, or null on a
 failure (a `FetchSyncClient` keeps the connection and says why in `error`).
 `netRead` / `netWrite` panic on a range outside the buffer.
+`netWrite2(fd, a, aOff, aLen, b, bOff, bLen)` writes two ranges in one
+`sendmsg` (a header and a body without a copy) and answers the bytes written,
+which may stop inside either range; it checks both ranges, the first one first.
 `tcpListenFlags(host, port, backlog, flags)` is `tcpListen` with flag 1
 `SO_REUSEPORT`, so several listeners, in one process or many, share a port (Linux
 spreads the connections), and flag 2 `TCP_NODELAY` on every socket `tcpAccept`
@@ -2796,13 +2862,16 @@ or `PG_LOST` to `fail(run)` (on a spent handle these do nothing and count in
 `stray`), and after each call `next(run)` until
 `PG_BATCH_NONE`: `PG_BATCH_ROW` (the connection's row answers request `tag`),
 then one of `PG_BATCH_DONE`, `PG_BATCH_MISSING` or `PG_BATCH_FAILED` per
-request. It reads no clock: when to take is the loop's choice, or a `PgBatchClock`'s (`PgBatchClockConfig`: `minCount`, `factor` × the moving average of batch sizes, `maxWaitUs`, the idle bypass `lightCount`; defaults are a fixed window), which `takeDue(conn, clock, nowUs, pool.inFlight())` consults after `clock.arrived(nowUs)` per add; `PgBatchTurns` wakes one collecting connection only when its batch is due. (No block;
+request. `sorted = false` drops `q.ord` from the statement's `order by` (and
+its Sort node, with `orderBy` empty): rows route as they come, and every last
+event waits for `end`. The batcher reads no clock: when to take is the loop's choice, or a `PgBatchClock`'s (`PgBatchClockConfig`: `minCount`, `factor` × the moving average of batch sizes, `maxWaitUs`, the idle bypass `lightCount`; defaults are a fixed window), which `takeDue(conn, clock, nowUs, pool.inFlight())` consults after `clock.arrived(nowUs)` per add; `PgBatchTurns` wakes one collecting connection only when its batch is due. (No block;
 `tests/postgres/live`'s `batch` scenario runs it against a server, and the user
 guide's [PostgreSQL page](guide/using-nish/postgres.md#batching-keyed-reads)
 its walk-through.)
 
 **Call another service from a route handler** — there is no `await fetch()`
-in a handler and no event-loop callback: `nish/net/upstream`'s `Upstream(h,
+in a handler (an `async` task does not wait on a socket yet) and no event-loop
+callback: `nish/net/upstream`'s `Upstream(h,
 origin, limits)` is a pool of keep-alive connections to one `http:` origin on
 the `HttpHandler`'s own loop. `users.get(req, path)` returns at once — test it
 for `UPSTREAM_E_FULL`, which holds nothing — and keeps `req` held; after each
@@ -2857,9 +2926,10 @@ export const main = (): i32 => {
 
 **Optional parameters** — write a default instead: `(n: i32 = 1)`. A default
 is a literal, an enum member or an earlier parameter, and the call site fills
-it in. `x?: T` is refused. A variable count of one type is a rest parameter,
-`(...ns: i32[])`, last in the list; a call never spreads (`f(...xs)`), it passes
-`xs` to an array parameter.
+it in. An options argument is `(opts: Options | null = null)`: `null` is the
+one default of a `T | null` parameter. `x?: T` is refused. A variable count
+of one type is a rest parameter, `(...ns: i32[])`, last in the list; a call
+never spreads (`f(...xs)`), it passes `xs` to an array parameter.
 
 **A calendar, regex, JSON, threads of your own** — not in the language (the
 wall clock is `Date.now()`, and that is all of `Date`). Say so rather than
@@ -2956,8 +3026,8 @@ export const first = (xs: i32[]): i32 => uncheckedGet(xs, 0);
 A package that must not touch the network says so in `package.json`,
 `"nish": { "capabilities": { "deny": ["net"] } }`, and `--deny net` or an
 allowlist such as `--allow fs.read,exit` says the same on the command line.
-The `"nish"` field holds `noPanic` and `capabilities` and nothing else, each
-written once; anything more is refused (NL3036) rather than skipped. A
+The `"nish"` field holds `noPanic`, `capabilities` and `host` and nothing
+else, each written once; anything more is refused (NL3036) rather than skipped. A
 program whose `main` — or, in a library or a header build, any export —
 reaches more is refused (NL2459), spanned at the first call and naming the
 whole chain to the builtin; nothing changes in a program

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/nish-aarch64-darwin",
-  "version": "0.34.1",
+  "version": "0.36.0",
   "description": "The nish native compiler for macOS on ARM64",
   "license": "MIT",
   "os": [

package/runtime/async.d.mts

@@ -0,0 +1,49 @@
+// The declarations of `runtime/async.mjs`, `nish:async` under Node.
+
+/** Starts `task` without waiting for it; the launcher waits before it exits. */
+export declare function spawn(task: Promise<void>): void;
+/** Every task's answer, in the order the calls are written, once all of them finish. */
+export declare function awaitAll<A, B>(a: Promise<A>, b: Promise<B>): Promise<[A, B]>;
+export declare function awaitAll<A, B, C>(a: Promise<A>, b: Promise<B>, c: Promise<C>): Promise<[A, B, C]>;
+export declare function awaitAll<A, B, C, D>(
+  a: Promise<A>,
+  b: Promise<B>,
+  c: Promise<C>,
+  d: Promise<D>,
+): Promise<[A, B, C, D]>;
+export declare function awaitAll<A, B, C, D, E>(
+  a: Promise<A>,
+  b: Promise<B>,
+  c: Promise<C>,
+  d: Promise<D>,
+  e: Promise<E>,
+): Promise<[A, B, C, D, E]>;
+export declare function awaitAll<A, B, C, D, E, F>(
+  a: Promise<A>,
+  b: Promise<B>,
+  c: Promise<C>,
+  d: Promise<D>,
+  e: Promise<E>,
+  f: Promise<F>,
+): Promise<[A, B, C, D, E, F]>;
+export declare function awaitAll<A, B, C, D, E, F, G>(
+  a: Promise<A>,
+  b: Promise<B>,
+  c: Promise<C>,
+  d: Promise<D>,
+  e: Promise<E>,
+  f: Promise<F>,
+  g: Promise<G>,
+): Promise<[A, B, C, D, E, F, G]>;
+export declare function awaitAll<A, B, C, D, E, F, G, H>(
+  a: Promise<A>,
+  b: Promise<B>,
+  c: Promise<C>,
+  d: Promise<D>,
+  e: Promise<E>,
+  f: Promise<F>,
+  g: Promise<G>,
+  h: Promise<H>,
+): Promise<[A, B, C, D, E, F, G, H]>;
+/** Waits for every task `spawn` started, the tasks those tasks start included. */
+export declare function settleTasks(): Promise<void>;

package/runtime/async.mjs

@@ -0,0 +1,27 @@
+// `nish:async` under Node (WP49): what `nish --emit-ts` writes an async
+// program against, and what `runtime/nish.mjs` answers `nish:async` with. A
+// file of its own, not `nish/runtime`, because `nish:process` has a `spawn`
+// there already.
+//
+// `awaitAll` is `Promise.all` over its two to eight tasks. `spawn` starts a
+// task without awaiting it and keeps it, so the launcher's `settleTasks` waits
+// for every task started before the process exits, as the native driver
+// drains its queue after `main` answers. Node runs a task only until its first
+// `await` where native runs it until it first waits, so spawned tasks may print
+// in another order (`docs/RUN_UNDER_NODE.md`). A task that throws is Node's
+// unhandled rejection, which exits 1 as a native panic does.
+
+const pending = [];
+
+export const spawn = (task) => {
+  pending.push(task);
+};
+
+export const awaitAll = (...tasks) => Promise.all(tasks);
+
+export const settleTasks = async () => {
+  for (let i = 0; i < pending.length; i++) {
+    await pending[i];
+  }
+  pending.length = 0;
+};