NL4xxx: the interop sidecars

The 21 codes of band 4. Diagnostics says what a code promises and how a rule's fragment is matched.

NL4001

The message of an error contains:

… functions (identical to --emit-header). */

No program provokes it: a comment in the C header --emit-napi writes

NL4002

The message of an error contains:

… modules listed below. Link the .ll module(s) and

No program provokes it: a comment in the C header --emit-header writes

NL4003

The message of an error contains:

…: cannot create the result

No program provokes it: an error string in the generated N-API shim

NL4004

The message of an error contains:

`, which needs the …

No program provokes it: a sentence in the --emit-dts loader's marshalling report

NL4005

The message of an error contains:

…could not be converted

No program provokes it: an error string in the generated N-API shim

NL4006

The message of an error contains:

…must be a string

No program provokes it: an error string in the generated N-API shim

NL4007

The message of an error contains:

… only where it is instantiated, and this program instantiates none

nl4007_generic_never_instantiated.ts (compiled with --emit-dts build/test/wordings/nl4007_generic_never_instantiated.d.ts):

// NL4007: an exported generic with no instantiation has no symbol, so a
// sidecar flag refuses it rather than describe an ABI without it.
export const identity = <T>(x: T): T => x;
`identity` is generic, so it has no single C signature: a generic function becomes a symbol only where it is instantiated, and this program instantiates none

NL4008

The message of an error contains:

…` in C, so a header that declared both would not compile: rename one of them

nl4008_c_name_clash.ts (compiled with --emit-header build/test/wordings/nl4008_c_name_clash.h):

// NL4008: a method and a function whose C spellings are one identifier; a
// header that declared both would not compile.
export class Point {
  x: i32 = 0;

  shifted(d: i32): i32 {
    return this.x + d;
  }
}

export const Point_shifted = (p: Point): i32 => p.x;
`Point.shifted` and `Point_shifted` are both `Point_shifted` in C, so a header that declared both would not compile: rename one of them

NL4009

The message of an error contains:

…`, which holds a union no sidecar can describe: a union has no C spelling in this version

nl4009_union_export.ts (compiled with --emit-header build/test/wordings/nl4009_union_export.h):

// NL4009 (with --emit-header): an exported function that takes a union.
enum Kind {
  Dot,
  Box,
}

interface Dot {
  readonly kind: Kind.Dot;
  x: i32;
}

interface Box {
  readonly kind: Kind.Box;
  side: i32;
}

export const tagOf = (m: Dot | Box): Kind => m.kind;
`tagOf`'s parameter `m` is `Dot | Box`, which holds a union no sidecar can describe: a union has no C spelling in this version

NL4010

The message of an error contains:

…--emit-ts cannot write a module that declares C functions; keep it native and import it through --emit-napi

NL4011

The message of an error contains:

…--emit-ts cannot yet write signalFd, readSignal or nish:net, whose translation is not local to its statement

NL4012

The message of an error contains:

…--emit-ts cannot write this compound assignment, whose target it would read twice and which holds a call, a step or an element read: hoist the index into a const

NL4013

The message of an error contains:

…--emit-ts cannot write this generic, whose instances would be written as different TypeScript: an element held inline in one and by reference in another, or two element types with different zeros; write a function per element type

NL4014

The message of an error contains:

--emit-ts cannot write this generic, which no instance reaches: its body copies or zero-fills an element whose type only an instance would say; call it with the element type it is for, or write a function per element type

nl4014_uncalled_zero_fill.ts (compiled with --emit-ts build/test/wordings/nl4014_uncalled_zero_fill):

// NL4014: `make` is called at no type, so the checker never typed its body,
// and nothing says whether `--emit-ts` fills its slots with `0`, `0n` or
// `false`.
const make = <T>(like: T[], n: i32): T[] => {
  const out = new Array<T>(n)
  return out
}

export const main = (): number => 0
--emit-ts cannot write this generic, which no instance reaches: its body copies or zero-fills an element whose type only an instance would say; call it with the element type it is for, or write a function per element type

NL4015

The message of an error contains:

…--emit-ts cannot yet write a module that imports nish:region, whose regions the TypeScript runtime does not answer; keep it native

NL4016

The message of an error contains:

…--emit-ts cannot yet write an async function, whose resume order the TypeScript runtime does not answer yet; keep it native

Retired: --emit-ts cannot yet write an async function, the refusal until --emit-ts wrote async functions as Node's async/await (tests/emit-ts/async)

NL4017

The message of an error contains:

--emit-ts cannot write readable or writable from nish:async: Node has no wait on a descriptor's readiness that a task can await; keep the program native

nl4017_wait_on_descriptor.ts (compiled with --emit-ts build/test/wordings/nl4017_wait_on_descriptor):

// NL4017: Node polls no descriptor JavaScript can name, so a task that awaits
// `readable` has no translation, and `--emit-ts` refuses it at the wait.
import { readable } from "nish:async"

export async function main(): Promise<i32> {
  const ok = await readable(0)
  return ok ? 0 : 1
}
--emit-ts cannot write readable or writable from nish:async: Node has no wait on a descriptor's readiness that a task can await; keep the program native

NL4018

The message of an error contains:

--emit-ts cannot write readableWithin, writableWithin, taskId, cancel, cancelled or cancelAfter from nish:async: a Node promise is not a task the executor can cancel; keep the program native

nl4018_task_cancel.ts (compiled with --emit-ts build/test/wordings/nl4018_task_cancel):

// NL4018: a Node promise is not a task anything can cancel, so `--emit-ts`
// refuses the cancellation calls and the bounded waits of `nish:async`.
import { cancelAfter, taskId } from "nish:async"

export async function main(): Promise<i32> {
  cancelAfter(taskId(), 10)
  return 0
}
--emit-ts cannot write readableWithin, writableWithin, taskId, cancel, cancelled or cancelAfter from nish:async: a Node promise is not a task the executor can cancel; keep the program native

NL4019

The message of an error contains:

…which holds a string enum: a string enum has no C, N-API or wasm spelling…

nl4019_string_enum_export.ts (compiled with --emit-header build/test/wordings/nl4019_string_enum_export.h):

// NL4019 (with --emit-header): an exported function that returns a string enum.
enum Role {
  Admin = "admin",
  Guest = "guest",
}

export const fallback = (): Role => Role.Guest
`fallback` returns `Role`, which holds a string enum: a string enum has no C, N-API or wasm spelling in this version, so take or return a `string` and convert with `String(r)` and a `switch`

NL4020

The message of an error contains:

…`, which implements `Compact`: a compact class's links have no C or N-API spelling, so an export takes and returns no compact object

nl4020_compact_export.ts (compiled with --emit-napi build/test/wordings/nl4020_compact_export.c):

// WP48 rule 4: an export whose signature holds a compact class is refused at the signature.
import { Compact } from "nish:compact"

export class Cell implements Compact {
  value: i32
  next: Cell | null
  constructor(value: i32, next: Cell | null) {
    this.value = value
    this.next = next
  }
}

export const push = (value: i32, head: Cell | null): Cell => new Cell(value, head)

export const main = (): number => push(3, null).value
`Cell.constructor` is exported to C or Node and its signature holds `Cell`, which implements `Compact`: a compact class's links have no C or N-API spelling, so an export takes and returns no compact object

NL4021

The message of an error contains:

…` describes the program to C or Node, which would read its 32-bit links as pointers; build without `…

nl4021_compact_header.ts (compiled with --emit-header build/test/wordings/nl4021_compact_header.h):

// WP48 rule 1: a build C or Node reads refuses every compact class, named at its class.
import { Compact } from "nish:compact"

class Cell implements Compact {
  value: i32
  next: Cell | null
  constructor(value: i32, next: Cell | null) {
    this.value = value
    this.next = next
  }
}

const sum = (head: Cell | null): i32 => {
  let total: i32 = 0
  let at = head
  while (at !== null) {
    total = total + at.value
    at = at.next
  }
  return total
}

export const total = (n: i32): i32 => {
  let head: Cell | null = null
  for (let i: i32 = 0; i < n; i++) {
    head = new Cell(i, head)
  }
  return sum(head)
}

export const main = (): number => total(4)
`Cell` implements `Compact`, and `--emit-header` describes the program to C or Node, which would read its 32-bit links as pointers; build without `--emit-header`, or drop the marker