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
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
`unsafe` is bound by the consumer. These are stopgaps: decided with the maintainer on
2026-10-27, a stock crate translates with no annotations or config, so
[unsafe code the translator can model](/quest/m3/ts-unsafe.md) and
[trait objects](/quest/m3/ts-dyn.md) remove them. Only true platform boundaries (clocks,
`rand`, DEFLATE) stay bound.
[trait objects](/quest/m3/ts-dyn.md) remove them. Only true platform boundaries (clocks and
DEFLATE) stay bound.
- 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
Expand All @@ -49,5 +49,4 @@ Public API: the translator's output for moq-net's model.
- [Shared ownership](/quest/m2/ts-shared.md) - kio's waiters are `Arc`/`Weak` with observable counts, and its atomics and locks are plain values
- [Float formatting](/quest/m2/ts-model/floats.md) - `f64` formats and parses as std does
- [The rest of std the model reaches](/quest/m2/ts-model/std-rest.md) - the std calls the census still refuses
- [Well-known crates without config](/quest/m2/ts-model/stock.md) - rust2-ts maps `bytes`, `rand`, and `tracing` itself, so `model.toml` stops binding and ignoring them
- [Async in the TypeScript translator](/quest/m2/ts-async.md) - kio's producers and consumers are futures
26 changes: 0 additions & 26 deletions quest/m2/ts-model/stock.md

This file was deleted.

86 changes: 85 additions & 1 deletion ts/Cargo.lock

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

4 changes: 4 additions & 0 deletions ts/MIGRATE.md
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,10 @@
`true`.
- `rt.FromUtf8Error` holds its `rt.Utf8Error` as std's does: `e.validUpTo` and
`e.errorLen` are `e.error.validUpTo` and `e.error.errorLen`.
- `ts.toml` no longer takes `ignore-macros`: `tracing`'s events are left out without it,
and no other macro is. Delete the key.
- `bytes::Bytes` and `rand::rngs::ThreadRng` can't be bound: translation maps them, a
`Bytes` as an `rt.ByteSlice`. Delete their `[bind]` entries and the files they name.
- The runtime no longer exports `ownedNth`, `ownedNthBack`, `ownedSkip`, `ownedTake`, or
`ownedStepBy`: `iterNth`, `iterNthBack`, `iterSkip`, `iterTake`, and `iterStepBy` take
what drops an item last. `rt.Iter`'s `nthItem` and `nthBackItem` are `nth` and
Expand Down
47 changes: 37 additions & 10 deletions ts/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -32,13 +32,11 @@ roots = ["coding::Decoder", "lite::Group"]
# Types whose `Display` and `Debug` impls come along, whichever they have, so callers can
# print them. Another crate's trait otherwise comes along only when something calls it.
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"
"model::flate::Encoder" = "bind/encoder.ts"
"util::TaskSet" = { file = "bind/tasks.ts", drop = true }
```

Expand Down Expand Up @@ -109,6 +107,8 @@ crate translation reaches is refused, and so are two versions of one crate it re
| `Poll<T>`, `Waker`, `Context` | `T \| typeof rt.Pending`, refused if `T` can already be pending; `rt.Waker`, which is also the context |
| `pin!(x)`, `poll_fn(f)`, `future::pending()` | `x`; `rt.PollFn`, which drops `f` with itself; `rt.NEVER` |
| `Box::pin(x)`, `dyn Future<Output = T>` | `x`; `rt.Future<T>`: an `async` body or std's future as it is, and another future as an `rt.DynFuture` over its `poll`, which drops it with itself unless borrowed |
| `bytes::Bytes` | `rt.ByteSlice`, as `&[u8]` is: its clones and slices share bytes that never change |
| `rand::rngs::ThreadRng` | `rt.ThreadRng`, which holds no state |

`Vec<u8>` storage and `[x; N]` byte arrays up to 1 KiB share 8 KiB `ArrayBuffer`s, as Node's
`Buffer` pool does, so the `buffer` behind a view holds other bytes too: read it through
Expand Down Expand Up @@ -280,27 +280,50 @@ 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`.

## Well-known crates

rust2-ts maps a few crates itself, as it maps std, so a consumer binds and configures none
of them:

- `bytes::Bytes` is an `rt.ByteSlice`. Its constructors, `len`, `is_empty`, `slice`,
`Clone`, `Deref`, `AsRef`, `PartialEq` with bytes, `Default`, `Debug`, and `From`
between it and `Vec<u8>`, `String`, `&'static [u8]`, and `&'static str` map to
`rt/bytes.ts`, panicking as `bytes` does. `Bytes::from_owner` reads its owner's bytes
once, as `bytes` does, and is refused for an owner that drops, which would drop with the
last clone of what it makes.
- `rand::rng()` is an `rt.ThreadRng`, whose `random` of an integer or `bool` and
`random_range` of an integer range map to `rt/rand.ts`. Each value comes from
`crypto.getRandomValues`, uniform as `rand`'s are, though no seed reproduces them, as
none reproduces `rand::rng()`'s. An empty range panics as `rand`'s does. A seeded
generator, such as `StdRng`, is refused, since its values would have to be `rand`'s.
- `tracing`'s events, `trace!` through `error!` and `event!`, are left out where they are
written. Translated code installs no subscriber, and without one an event evaluates none
of its fields and does nothing, so leaving it out is exact. Installing one, as
`tracing::subscriber::set_global_default` does, is refused as any unmapped call is.

## 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`,
runtime. It imports `rt.ts` as the output's modules do, `../rt.ts` from `bind/blob.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"`.
type's module, `import * as Blob from "./bind/blob.ts"`.

A bound type is the file's export of its name, `Bytes.Bytes`, with the Rust type's type
A bound type is the file's export of its name, `Blob.Blob`, 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
export serves every instance and a generic one is a generic TS function. `Blob::slice` is
`Blob.slice`, `<Blob as PartialEq>::eq` is `Blob.eq$PartialEq`, and
`<Blob as From<Vec<u8>>>::from` is `Blob.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.

A type with a representation of its own, std's or a well-known crate's, can't be bound.

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
Expand Down Expand Up @@ -555,7 +578,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
- `stock` calls `bytes`, `rand`, and `tracing` with no config, against native Rust, whose
`rand::rng()` reads the fixture's own getrandom backend on wasm32. It checks `Bytes`'s
slices and panics, how each is made and printed, that no event evaluates a field, and
that each random value is in its range, every value of a small range drawn.
- `bind` binds `blob::Blob`, a dependency's type with `unsafe` inside, 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`.
Expand Down
2 changes: 1 addition & 1 deletion ts/fixtures/bind/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ publish = false
crate-type = ["lib", "cdylib"]

[dependencies]
bytes = "1.12.1"
blob = { path = "blob" }

[lints]
workspace = true
22 changes: 11 additions & 11 deletions ts/fixtures/bind/bind/bytes.ts → ts/fixtures/bind/bind/blob.ts
Original file line number Diff line number Diff line change
@@ -1,31 +1,31 @@
// `bytes::Bytes`, which contains `unsafe`: immutable bytes that its slices and clones
// `blob::Blob`, 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 type Blob = rt.ByteSlice;

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

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

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

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

/** Over each range translated code makes: `a..b`, `a..=b`, `a..`, `..b`, and `..`. */
export function slice(
self: Bytes,
self: Blob,
range: rt.Range<rt.usize> | rt.RangeInclusive<rt.usize> | { start: rt.usize } | { end: rt.usize } | undefined,
): Bytes {
): Blob {
let begin = 0;
let end = self.length;
if (range instanceof rt.RangeInclusive) {
Expand All @@ -40,14 +40,14 @@ export function slice(
return new rt.ByteSlice(self.data, self.start + begin, end - begin);
}

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

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

export function eq$PartialEq(self: Bytes, other: Bytes): boolean {
export function eq$PartialEq(self: Blob, other: Blob): boolean {
return rt.byteSliceEq(self, other);
}
10 changes: 10 additions & 0 deletions ts/fixtures/bind/blob/Cargo.toml
Original file line number Diff line number Diff line change
@@ -0,0 +1,10 @@
[package]
name = "blob"
description = "Shared bytes with `unsafe` inside, which bind-fixture binds as a dependency's type"
version = "0.0.0"
edition.workspace = true
license.workspace = true
publish = false

[lints]
workspace = true
Loading