Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .github/workflows/nightly.yml
Original file line number Diff line number Diff line change
Expand Up @@ -210,7 +210,7 @@ jobs:

# The ranked tables: the spans would pass the summary's size limit.
- name: Summarize
run: awk 'FNR == 1 { spans = 0 } /^## Spans/ { spans = 1 } !spans' ts/target/census/moq-net.md ts/target/census/kio.md >> "$GITHUB_STEP_SUMMARY"
run: awk 'FNR == 1 { spans = 0 } /^## Spans/ { spans = 1 } !spans' ts/target/census/moq-net.md ts/target/census/model.md ts/target/census/kio.md >> "$GITHUB_STEP_SUMMARY"

- name: Upload
uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
Expand Down
4 changes: 3 additions & 1 deletion flake.nix
Original file line number Diff line number Diff line change
Expand Up @@ -98,8 +98,10 @@
];
RUSTFLAGS = "-C link-args=-Wl,-rpath,${tsToolchain}/lib";
nativeBuildInputs = [ pkgs.makeWrapper ];
# tsc checks bindings, from the caller's PATH first.
postInstall = ''
wrapProgram $out/bin/rust2-ts --set-default CARGO ${tsToolchain}/bin/cargo
wrapProgram $out/bin/rust2-ts --set-default CARGO ${tsToolchain}/bin/cargo \
--suffix PATH : ${pkgs.typescript}/bin
'';
# The tests need node, tsc, and wasm builds: `just ts test` runs them.
doCheck = false;
Expand Down
2 changes: 1 addition & 1 deletion quest/m2/ts-async.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ What moq-net still needs, by its census from MIR at the pinned revision:
- kio's own API, reached across crates (`Pending`, `Consumer::poll`,
`Waiter::poll_future`, `Tasks`), translates through
[safe dependencies](/quest/m2/ts-model/crates.md), and kio's `RawWaker` vtable and
`Box<dyn Future>` tasks are [bindings](/quest/m2/ts-model/bind.md).
`Box<dyn Future>` tasks are [bindings](/ts/README.md#bindings).

The model itself (its census of 2026-10-27) needs only `Poll`'s helpers and
`Waker::from(Arc<W>)`, 61 refusals; `pin!`, `poll_fn`, `Box::pin`, and async closures are
Expand Down
5 changes: 2 additions & 3 deletions quest/m2/ts-model/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,8 +35,8 @@ Decided with the maintainer on 2026-10-27, from a census of the model's 22 publi
it; only true boundaries (`Box<dyn Future>`, clocks, `rand`, DEFLATE) bind to
hand-written TS. A dependency containing `unsafe` is bound by the consumer, until
[unsafe code the translator can model](/quest/m3/ts-unsafe.md) translates.
- Check in `ts/moq/model.toml`, rooted at those 22 types, and have nightly's census
report it beside the whole crate, so each child measures this target.
- Each child measures this target by the census of `ts/moq/model.toml`, rooted at those
types with the boundaries bound, which nightly reports beside the whole crate.
- The end-to-end work stays here: the model's roots, its differential harness, and the
`frames.ts` workload.

Expand All @@ -46,7 +46,6 @@ Public API: the translator's output for moq-net's model.

- [Drop in the TypeScript translator](/quest/m2/ts-drop.md) - kio closes a channel when its last producer drops
- [Shared ownership](/quest/m2/ts-shared.md) - kio's waiters are `Arc`/`Weak` with observable counts, and its atomics and locks are plain values
- [Bind to hand-written TypeScript](/quest/m2/ts-model/bind.md) - a config names TS that stands in for a Rust item at a boundary
- [Translate safe dependencies with the package](/quest/m2/ts-model/crates.md) - kio, moq-clock, moq-pattern, and rangemap translate as one program with moq-net
- [Std combinators from core's MIR](/quest/m2/ts-model/core-mir.md) - `Option`'s and `Result`'s combinators lower from core's own bodies
- [Std gaps the model reaches](/quest/m2/ts-model/std-more.md) - ranges, wrappers, and `Vec`'s editing methods
Expand Down
30 changes: 0 additions & 30 deletions quest/m2/ts-model/bind.md

This file was deleted.

2 changes: 1 addition & 1 deletion quest/m2/ts-model/crates.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ else. rangemap adds 266.
- Each crate's output goes in its own module directory, and the instances a crate's
generics get from the package go with the crate that defines them.
- The rule is general: a dependency without `unsafe` translates from source; one with
`unsafe` is refused with a span unless the consumer [binds](/quest/m2/ts-model/bind.md)
`unsafe` is refused with a span unless the consumer [binds](/ts/README.md#bindings)
it.
- A named crate's own refusals belong to other quests: kio's atomics and `thread_local!`
to [shared ownership](/quest/m2/ts-shared.md), and its `RawWaker` vtable to bindings.
Expand Down
2 changes: 1 addition & 1 deletion quest/m3/ts-unsafe.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ source instead of being bound by hand.
## Plan

Decided with the maintainer on 2026-10-27: a dependency containing `unsafe` is bound by
the consumer [at first](/quest/m2/ts-model/bind.md); this follows once a consumer binds
the consumer [at first](/ts/README.md#bindings); this follows once a consumer binds
enough of them to justify it. The census of moq-net's model found `bytes`, `hashlink`,
`slab`, and `smallvec` bound, and kio's lock-free `log`.

Expand Down
7 changes: 7 additions & 0 deletions ts/Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 2 additions & 0 deletions ts/MIGRATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,8 @@

## Unreleased

- `--census` starts from the config's roots, as translation does. For the census of every
item, census with a config that names no roots: `roots = []`.
- A struct is a plain object typed by an interface, unless it may drop: build one as a
literal, `{ subscribe, sequence, frameStart: 0 }` rather than
`new Group({ subscribe, sequence, frameStart: 0 })`.
Expand Down
77 changes: 66 additions & 11 deletions ts/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,23 +26,31 @@ roots = ["coding::Decoder", "lite::Group"]
printable = ["coding::DecodeError"]
# Macros whose invocations are left out, such as logging. Each must evaluate to `()`.
ignore-macros = ["tracing::trace"]

# Hand-written TypeScript that stands in for an item, by its path from the crate root or
# else from a crate it depends on: a function, or a type and its functions.
[bind]
"bytes::Bytes" = "bind/bytes.ts"
"util::TaskSet" = { file = "bind/tasks.ts", drop = true }
```

moq consumes it as the `ts` package of this repository's flake. In this repository,
`just ts run ...` runs it from source on the pinned nightly.

## Census

`--census file.md` translates nothing. It treats every item in the library as a root,
except derived impls, which come along only when called or printable, and writes a Markdown report of
every construct translation refuses, with counts and spans. Refusals are ranked by
construct, by the type or module they name, and by each type or path. A generic function
that no instance reaches is lowered over its own type parameters, refusing nothing that
hinges on what they are, since each instance decides that. A census succeeds whatever
it finds; translation still fails on any refusal.
`--census file.md` translates nothing. It writes a Markdown report of every construct
translation refuses, with counts and spans, ranked by construct, by the type or module
they name, and by each type or path. It starts from the config's roots, as translation
does. A config that names none makes every item in the library a root, except derived
impls, which come along only when called or printable, and lowers a generic function
that no instance reaches over its own type parameters, refusing nothing that hinges on
what they are, since each instance decides that. A census succeeds whatever it finds;
translation still fails on any refusal.

`just ts census` runs it on moq-net and kio at the pinned moq revision, into
`target/census`, and the nightly job publishes their tables.
`just ts census` runs it at the pinned moq revision, into `target/census`, on moq-net
whole (`moq/net.toml`), on its model's public types with their boundaries bound
(`moq/model.toml`), and on kio, and the nightly job publishes their tables.

## Output

Expand Down Expand Up @@ -206,6 +214,48 @@ full type arguments.
Imports name the `.ts` file, which Node, Bun, and bundlers run as is. A `tsc` build sets
`rewriteRelativeImportExtensions`, or `allowImportingTsExtensions` with `noEmit`.

## Bindings

A binding stands in for what the subset refuses, such as `unsafe` code or a boxed future.
Its file, relative to `ts.toml`, is copied to the same path in the output, beside the
runtime. It imports `rt.ts` as the output's modules do, `../rt.ts` from `bind/bytes.ts`,
and may import the translated modules and npm packages too. Callers import it whole, as a
type's module, `import * as Bytes from "./bind/bytes.ts"`.

A bound type is the file's export of its name, `Bytes.Bytes`, with the Rust type's type
parameters. A call of a bound function, or of a function that an impl for a bound type in
the type's own crate defines, calls the file's export. The export is named as the
translated function would be, without the type's or the function's type arguments, so one
export serves every instance and a generic one is a generic TS function. `Bytes::slice` is
`Bytes.slice`, `<Bytes as PartialEq>::eq` is `Bytes.eq$PartialEq`, and
`<Bytes as From<Vec<u8>>>::from` is `Bytes.from$From_Vec_u8`. A trait's provided function
that the impl doesn't override, such as `ne`, and a blanket impl's, such as `ToOwned`'s,
stay the trait's, as for any other type. A generic export sees a type argument only in the
values it takes, so a function with a bounded type parameter that no argument holds, such
as `fn zero<T: Default>() -> T`, or with a const parameter, can't be bound. `tsc` checks a
generic bound type's value at each of its instantiations translation reaches.

Translation can't see into a bound type, so a field, variant, or constructor of one is
refused, as are iterating one, keying a collection by one, and assigning a whole one
through a `&mut`. Its value is never `undefined` or `rt.Pending`, which `None` and
`Poll::Pending` are, and is an object unless the Rust type is `Copy`. A `&mut` to one
passes that object, which the binding's functions change in place. Where the type is
`Copy`, such a `&mut` is refused, since JS shares the value where Rust copies it, and a
binding never changes a `Copy` value in place. Nor does a binding change in place what it
takes by value or by `&`, or share with a clone what a `&mut` changes, and an integer it
returns is in its Rust type's range.

Once the output is written, `tsc` 7.0 or later, from `PATH`, checks each export against the
translated signature of every instance translation calls, and each bound type's value. A
missing or mismatched binding fails the translation at the Rust item's span, and the
output is removed. Only the binding files translation reaches are copied, so one imports
another only where translation reaches both. A binding inside the output is refused, since
a translation replaces it.

A bound type with `drop = true` drops where Rust drops it, through its
`[Symbol.dispose]`, which `tsc` checks it has. Without it, dropping one does nothing JS
sees, `tsc` checks it has no `[Symbol.dispose]`, and a type argument that drops is refused.

## Design

Output is ranked correctness first, speed second, and bundle size third: the
Expand Down Expand Up @@ -328,8 +378,8 @@ they need.
## Never

Outside the subset for good: `unsafe` and raw pointers, and trait objects other than
`&dyn Debug` and `&dyn Display`. A boundary that needs one, such as a boxed future, will
bind to hand-written TS through config ([model](/quest/m2/ts-model/README.md)).
`&dyn Debug` and `&dyn Display`. A boundary that needs one, such as a boxed future, binds
to hand-written TS ([bindings](#bindings)).

## Not yet

Expand Down Expand Up @@ -394,6 +444,11 @@ built natively for wasm32 and run beside its translation on the same inputs by
also runs the scripts natively on the host (`examples/unwind.rs`), where a panic
unwinds, catching and logging each step's panic and going on, so what a panic drops
must match too.
- `bind` binds `bytes::Bytes`, and a function and a type of its own that read through raw
pointers, the type dropping an `Arc` where Rust drops it, to the TS in `bind/`. Its
differential test runs them against native Rust. `wrong.toml` binds TS that doesn't match
the Rust signatures, which `tsc` refuses at each item, with the errors in `wrong.txt`.
`refused.toml` holds bindings the config can't make, with the errors in `refused.txt`.
- `reject` holds constructs outside the subset; its expected errors are `expected.txt`,
and its expected census is `census.md`.

Expand Down
17 changes: 17 additions & 0 deletions ts/fixtures/bind/Cargo.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
[package]
name = "bind-fixture"
description = "Items outside rust2-ts's subset, bound to hand-written TypeScript"
version = "0.0.0"
edition.workspace = true
license.workspace = true
publish = false

[lib]
# The cdylib is the native side of the differential test, built for wasm32.
crate-type = ["lib", "cdylib"]

[dependencies]
bytes = "1.12.1"

[lints]
workspace = true
53 changes: 53 additions & 0 deletions ts/fixtures/bind/bind/bytes.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
// `bytes::Bytes`, which contains `unsafe`: immutable bytes that its slices and clones
// share, as a byte slice of them is.

import * as rt from "../rt.ts";

export type Bytes = rt.ByteSlice;

export function copyFromSlice(data: rt.ByteSlice): Bytes {
return rt.byteSliceFrom(rt.byteSliceView(data).slice());
}

export function from$From_Vec_u8(vec: rt.ByteVec): Bytes {
return rt.byteVecSlice(vec);
}

export function len(self: Bytes): rt.usize {
return self.length;
}

export function isEmpty(self: Bytes): boolean {
return self.length === 0;
}

/** Over each range translated code makes: `a..b`, `a..=b`, `a..`, `..b`, and `..`. */
export function slice(
self: Bytes,
range: rt.Range<rt.usize> | rt.RangeInclusive<rt.usize> | { start: rt.usize } | { end: rt.usize } | undefined,
): Bytes {
let begin = 0;
let end = self.length;
if (range instanceof rt.RangeInclusive) {
begin = range.lo;
end = rt.usizeAdd(range.hi, 1);
} else if (range !== undefined) {
if ("start" in range) begin = range.start;
if ("end" in range) end = range.end;
}
if (begin > end) rt.panic(`range start must not be greater than end: ${begin} <= ${end}`);
if (end > self.length) rt.panic(`range end out of bounds: ${end} <= ${self.length}`);
return new rt.ByteSlice(self.data, self.start + begin, end - begin);
}

export function clone$Clone(self: Bytes): Bytes {
return self;
}

export function deref$Deref(self: Bytes): rt.ByteSlice {
return self;
}

export function eq$PartialEq(self: Bytes, other: Bytes): boolean {
return rt.byteSliceEq(self, other);
}
9 changes: 9 additions & 0 deletions ts/fixtures/bind/bind/checksum.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
// `raw::checksum`, which reads through a raw pointer.

import type * as rt from "../rt.ts";

export function checksum(bytes: rt.ByteSlice): rt.u32 {
let sum = 0;
for (let i = 0; i < bytes.length; i++) sum = (Math.imul(sum, 31) + bytes.data[bytes.start + i]) >>> 0;
return sum;
}
25 changes: 25 additions & 0 deletions ts/fixtures/bind/bind/tally.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,25 @@
// `raw::Tally`, which holds its `Arc` by a raw pointer, and drops it where Rust drops
// the tally.

import * as rt from "../rt.ts";

export class Tally implements Disposable {
readonly count: rt.Arc<rt.u32>;

constructor(count: rt.Arc<rt.u32>) {
this.count = rt.arcClone(count);
}

[Symbol.dispose](): void {
rt.arcDrop(this.count);
}
}

function make(count: rt.Arc<rt.u32>): Tally {
return new Tally(count);
}
export { make as new };

export function get(self: Tally): rt.u32 {
return self.count.value;
}
54 changes: 54 additions & 0 deletions ts/fixtures/bind/expected/bind/bytes.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,54 @@
// Generated by rust2-ts. Do not edit.
// `bytes::Bytes`, which contains `unsafe`: immutable bytes that its slices and clones
// share, as a byte slice of them is.

import * as rt from "../rt.ts";

export type Bytes = rt.ByteSlice;

export function copyFromSlice(data: rt.ByteSlice): Bytes {
return rt.byteSliceFrom(rt.byteSliceView(data).slice());
}

export function from$From_Vec_u8(vec: rt.ByteVec): Bytes {
return rt.byteVecSlice(vec);
}

export function len(self: Bytes): rt.usize {
return self.length;
}

export function isEmpty(self: Bytes): boolean {
return self.length === 0;
}

/** Over each range translated code makes: `a..b`, `a..=b`, `a..`, `..b`, and `..`. */
export function slice(
self: Bytes,
range: rt.Range<rt.usize> | rt.RangeInclusive<rt.usize> | { start: rt.usize } | { end: rt.usize } | undefined,
): Bytes {
let begin = 0;
let end = self.length;
if (range instanceof rt.RangeInclusive) {
begin = range.lo;
end = rt.usizeAdd(range.hi, 1);
} else if (range !== undefined) {
if ("start" in range) begin = range.start;
if ("end" in range) end = range.end;
}
if (begin > end) rt.panic(`range start must not be greater than end: ${begin} <= ${end}`);
if (end > self.length) rt.panic(`range end out of bounds: ${end} <= ${self.length}`);
return new rt.ByteSlice(self.data, self.start + begin, end - begin);
}

export function clone$Clone(self: Bytes): Bytes {
return self;
}

export function deref$Deref(self: Bytes): rt.ByteSlice {
return self;
}

export function eq$PartialEq(self: Bytes, other: Bytes): boolean {
return rt.byteSliceEq(self, other);
}
Loading