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
4 changes: 4 additions & 0 deletions .changeset/chubby-books-know.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,4 @@
---
---

README: list rbcop as the Ruby reference, add a Kotlin section, drop leftover Ruby VM wording, and correct the Java and Kotlin artifact sizes.
57 changes: 42 additions & 15 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,20 +26,21 @@ Composer, no native binaries, no postinstall downloads.

| Package | Reference | Artifact | Status | Browser |
|:---|:---|---:|:---|:---|
| [`@scalar/ruby-fmt`](packages/ruby) | RuboCop (Layout) | 2.2 MB | ✅ exact by test | ✅ |
| [`@scalar/java-fmt`](packages/java) | google-java-format | 0.77 MB | ✅ exact | ✅ |
| [`@scalar/kotlin-fmt`](packages/kotlin) | ktfmt | 0.82 MB | ✅ exact | ✅ |
| [`@scalar/ruby-fmt`](packages/ruby) | rbcop | 2.2 MB | ✅ exact by test | ✅ |
| [`@scalar/java-fmt`](packages/java) | google-java-format | 0.76 MB | ✅ exact | ✅ |
| [`@scalar/kotlin-fmt`](packages/kotlin) | ktfmt | 0.81 MB | ✅ exact | ✅ |
| [`@scalar/csharp-fmt`](packages/csharp) | CSharpier | 4.2 MB | ✅ exact | ✅ |
| [`@scalar/swift-fmt`](packages/swift) | swift-format | 12.5 MB | ✅ exact | ✅ |
| [`@scalar/php-fmt`](packages/php) | PHP CS Fixer | 0.45 MB | ✅ exact | — |
| [`@scalar/rust-fmt`](packages/rust) | rustfmt | 1.3 MB | ✅ exact | ✅ |

Artifact is the brotli-compressed module as committed and published — the whole
tool, its parser and its language runtime in one file. The JavaScript that loads
it is small by comparison: nothing for Ruby, Swift, PHP and Rust, a 16 KB
it is small by comparison: nothing for Ruby, Swift, PHP and Rust, a 17 KB
generated runtime for Java and Kotlin, and 0.46 MB of .NET loader scripts for C#.

Ruby's reference is `rubocop --autocorrect --only Layout`: the package corrects
Ruby runs rbcop, and the reference it is held to is
`rubocop --autocorrect --only Layout`: the package corrects
Layout within the line structure it is handed and does not reprint, which suits
line-structured input such as generated code. See
[`packages/ruby`](packages/ruby#what-it-does-and-what-it-does-not).
Expand Down Expand Up @@ -84,8 +85,8 @@ const formatted: string = await format('x=[1,2,3].map{|n| n*2}', options)
// x = [1, 2, 3].map { |n| n * 2 }
```

`format` is async because the first call boots a Ruby VM. The VM is cached, so
every later call is milliseconds.
`format` is async because the first call has to load and compile the wasm. That
work is cached, so every later call is milliseconds.

### Formatting without awaiting

Expand All @@ -106,8 +107,9 @@ until it has. Everything after that already was synchronous; `format` was only
ever awaiting the boot.

Prefer `format` where you can await: it needs no setup call and cannot throw that
error. Ruby carries one extra caveat — see [its README](packages/ruby#readme) —
because recycling its VM is asynchronous too.
error. The one exception to the `init` rule is Ruby under Node, whose module
boots synchronously, so there `formatSync` works straight away — see
[its README](packages/ruby#formatting-without-awaiting).

## Browsers

Expand Down Expand Up @@ -254,7 +256,7 @@ reproduces that at every pass, which means formatting here and then verifying
with the jar compares pass one against pass two and looks like a divergence that
is not one. `packages/java/README.md` has the detail and the two ways out.

It ships as a 0.77 MB `java_fmt.wasm.br` plus TeaVM's generated runtime, which
It ships as a 0.76 MB `java_fmt.wasm.br` plus TeaVM's generated runtime, which
supplies the module's imports. Both are committed, so a fresh clone needs
nothing extra; `bun run java:build:teavm` rebuilds them from a JDK 21, Maven,
git and Node.
Expand All @@ -276,6 +278,31 @@ exception handling TeaVM emits. bun is unaffected. And the module
has no filesystem and no stdin, so source goes in as a string and comes back as
one - enough for `format()`, but it rules out shipping the CLI itself.

## Kotlin

See [`packages/kotlin`](packages/kotlin). It runs the real ktfmt 0.64 - the
Kotlin compiler's own PSI parser included - compiled to WasmGC by
[TeaVM](https://teavm.org), with the same patched TeaVM as the Java package.
The claim is checked in two halves over 589 real Kotlin files (kotlin-stdlib,
kotlinx-coroutines and ktfmt itself) in all three styles: the one patched file
leaves ktfmt's output unchanged on a JVM, and compiling that to wasm leaves it
unchanged again - 1767 of 1767 identical at each step, diagnostics included. A
conformance test asserts byte-identical output against the real ktfmt jar.

The patch is 20 lines of ktfmt's `Parser`. ktfmt parses through the compiler's
`KotlinCoreEnvironment`, which resolves a JVM classpath, opens jars and registers
extension points named in XML - none of which an ahead-of-time compiler can
follow, and none of which parsing needs - so the patch builds the smaller
container that environment builds underneath, and everything below it is
ktfmt's own.

Like Java it exports the release it carries, as `ktfmtVersion`, and a test reads
the build script so that export cannot go stale across a bump. It ships as a
0.81 MB `kotlin_fmt.wasm.br` plus the same TeaVM runtime as Java, both committed;
`bun run kotlin:build` rebuilds them from a JDK 21, Maven, git and Node. It shares
Java's caveat too: **Node 24.15 or newer**, for the same exception-handling
reason.

## C#

See [`packages/csharp`](packages/csharp). It runs the real CSharpier 1.3.0 -
Expand Down Expand Up @@ -324,14 +351,14 @@ read and passed in.
It ships as a 12.5 MB `swift_fmt.wasm.br`, built by
[`build/swift_fmt/build.sh`](build/swift_fmt/build.sh), which downloads its own
Swift toolchain and SDK. It is committed, so a fresh clone needs nothing extra;
`bun run swift:build` rebuilds it. Three times the size of the other packages,
`bun run swift:build` rebuilds it. Three times the size of the next largest package,
almost all of it swift-syntax - `-Osize` and `wasm-opt -Oz` were both tried and
moved the compressed total by under 60KB, so it is built with `-O` instead, which
spends about 20% less time formatting.

Two caveats worth knowing. The module is a **WASI reactor**: instantiated once,
then `run` per format, which measured 2.5x faster than a fresh instance each
time and, unlike the Ruby VM, does not leak - memory plateaus at 75MB and stays
time and does not leak - memory plateaus at 75MB and stays
there. And **the licence is unrestricted**, unlike the Java package: everything
embedded is Apache-2.0 with the Runtime Library Exception, so a paid product may
ship a copy.
Expand All @@ -346,8 +373,8 @@ sources and the Symfony, ReactPHP and PSR components vendored into its phar),
all of which came out identical - 1100 of them files the fixer actually
rewrote.

It is also the one package with a synchronous entry point. PHP on wasm has none
and cannot be given one - both builds suspend through Asyncify or JSPI, so every
It is also the one package whose `formatSync()` cannot just run the module
synchronously. PHP on wasm has no synchronous entry point and cannot be given one - both builds suspend through Asyncify or JSPI, so every
export returns a promise - so `formatSync()` gets its synchrony from the thread
instead: PHP runs in a worker and the calling thread parks on `Atomics.wait`
until the result lands in shared memory. Same fixer, byte-identical output, and
Expand Down Expand Up @@ -425,7 +452,7 @@ trap on deeply nested expressions native handles fine.
bun install
bun run build # compile each package's TypeScript to dist/
bun run test # bun test suite
bun run test:node # load the built packages under plain Node (24+ for Java)
bun run test:node # load the built packages under plain Node (24.15+ for Java and Kotlin)
bun run test:browser # load the built browser packages in real Chromium
bun run check # biome lint + format check
bun run types:check
Expand Down
6 changes: 3 additions & 3 deletions packages/java/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -124,14 +124,14 @@ await init({ url: '/assets/java_fmt.wasm.br' })
await format(source)
```

Run it in a worker. Booting compiles 3.3 MB of wasm, which is a visibly frozen
Run it in a worker. Booting compiles 3.2 MB of wasm, which is a visibly frozen
tab if it happens on the main thread.

The engine floor is checked at boot and is real: the module uses the final wasm
exception-handling opcodes, so Chrome 137, Firefox 131 or Safari 18.4 at the
earliest.

The browser reads the same brotli artifact as Node (0.77 MB over the wire) and
The browser reads the same brotli artifact as Node (0.76 MB over the wire) and
expands it with `DecompressionStream('brotli')` where the engine has it, or a
208 KB wasm decoder where it does not — Chrome, today. Serving the artifact with
`Content-Encoding: br`, or serving an uncompressed `.wasm`, skips the decoder
Expand Down Expand Up @@ -202,7 +202,7 @@ replicates all four, in that order.

`build/java_fmt_teavm/build.sh` produces two files, both committed:

- `java_fmt.wasm.br` — the module, 0.77MB brotli-compressed (3.3MB raw)
- `java_fmt.wasm.br` — the module, 0.76MB brotli-compressed (3.2MB raw)
- `java_fmt.runtime.mjs` — TeaVM's generated runtime, which supplies the
module's imports and the string and exception bridges

Expand Down
4 changes: 2 additions & 2 deletions packages/kotlin/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -129,14 +129,14 @@ await init({ url: '/assets/kotlin_fmt.wasm.br' })
await format(source)
```

Run it in a worker. Booting compiles 3.5 MB of wasm, which is a visibly frozen
Run it in a worker. Booting compiles 3.4 MB of wasm, which is a visibly frozen
tab if it happens on the main thread.

The engine floor is checked at boot and is real: the module uses the final wasm
exception-handling opcodes, so Chrome 137, Firefox 131 or Safari 18.4 at the
earliest.

The browser reads the same brotli artifact as Node (0.82 MB over the wire) and
The browser reads the same brotli artifact as Node (0.81 MB over the wire) and
expands it with `DecompressionStream('brotli')` where the engine has it, or a
208 KB wasm decoder where it does not — Chrome, today. Serving the artifact with
`Content-Encoding: br`, or serving an uncompressed `.wasm`, skips the decoder
Expand Down