Express on Osprey: the TypeScript flavor, measured against Node.js
Safe, elegant, fast: the TypeScript flavor is Osprey written in TypeScript syntax. The film opens on the Express port's comparison bench, run live: the same Express applications, served by Osprey and by Express on Node.js, under the same load. Then it serves the Express README example natively, requests it, runs Express's own web-service example as ported, and changes a reply.
The flavor is in progress. What works today is listed below, beside what does not. The contract is spec 0054, and plan 0061 records what is built.
Express on Osprey, measured against Node.js
@osprey/express is a port of Express 5 written in the TypeScript flavor. Its bench serves each example file three ways: compiled by Osprey with the tracing garbage collector (GC), compiled by Osprey with reference counting (ARC), and run by Express 5.3.0 on Node.js.
Each server gets the same requests over loopback: 16 in flight, a new connection for each request, 1,000 warm-up requests and then 10,000 timed ones. That runs for five trials, with the servers taking turns. Every timed reply is checked against the reply Express recorded for the same file, so a wrong answer does not count.
A run on an Apple M4 Max with Node.js 24.19.0 on 16 November 2026, with nothing else heavy running. Each figure is the median of five trials: requests per second, then peak memory. The film shows an earlier run, from before Osprey's HTTP handlers ran one at a time.
| Example | Osprey, ARC | Osprey, GC | Express on Node.js |
|---|---|---|---|
| hello-world | 24,260/s · 3 MiB | 19,888/s · 103 MiB | 25,736/s · 145 MiB |
| routes | 24,264/s · 3 MiB | 19,609/s · 108 MiB | 25,485/s · 146 MiB |
| web-service | 24,680/s · 3 MiB | 15,066/s · 214 MiB | 25,263/s · 126 MiB |
Median latency was between 574 and 657 µs for every server except the GC build of web-service, at 836 µs. The package README has the full table with 95th-percentile latency.
How to read it:
- Express is slightly faster. Under ARC, Osprey answered 2 to 6 percent fewer requests per second than Express on every example. Its 95th-percentile latency was lower on two of the three.
- Memory is not close. The ARC build peaked at 3 MiB. Node.js peaked at 126 to 146 MiB.
- GC is the slowest. The GC build answered 23 percent fewer requests per second than Express on the two small examples and 40 percent fewer on web-service, which allocates a JSON reply for every request.
- The examples are small. web-service is Express's own example, with middleware, JSON replies and an error handler, but three small applications say nothing about a large service. Osprey runs one handler at a time, so its handlers do not yet use more than one core (issue 397).
Run it on your own machine from a checkout. It needs Node.js for the Express side:
make build
(cd src/osprey/packages/express/oracle && npm ci)
make -C src/osprey/packages express-bench
The Express README example runs unchanged
This is the example application from the Express 5.3.0 README, byte for byte. It is examples/hello-world/index.ts in the package:
import express from 'express'
const app = express()
app.get('/', (req, res) => {
res.send('Hello World')
})
app.listen(3000, () => {
console.log('Server is running on http://localhost:3000')
})
Compile and serve it, then request it from a second terminal:
target/release/osprey src/osprey/packages/express/examples/hello-world --run
curl -i http://127.0.0.1:3000/
HTTP/1.1 200 OK
X-Powered-By: Express
Content-Type: text/html; charset=utf-8
Content-Length: 11
Connection: keep-alive
Keep-Alive: timeout=5
Hello World
The process keeps serving until you stop it, as the same file does under Node.js. A path with no route gets Express's own 404 page and security headers. The package's end-to-end test compares 164 replies from four example applications with what Express 5.3.0 sent: status line, body and the headers Express sets. ETag and Date are not sent yet (issue 398), so the replies are not byte-identical to Express.
How the TypeScript flavor differs from TypeScript
A syntax flavor is a way to write Osprey. Default, ML, Python and TypeScript flavors share one compiler, one type checker and one effect checker. TypeScript-flavor files end in .ts, as TypeScript files do, but a different program runs them:
| TypeScript flavor | TypeScript | |
|---|---|---|
| Language | Osprey | TypeScript, compiled to JavaScript |
| Run by | osprey, which compiles a native binary |
Node.js or a browser |
| Types | Inferred by Osprey and checked before the program runs | Checked by tsc, erased at run time |
| Unannotated parameter | Its type is inferred | any |
| Values | Immutable records; failure is a Result |
Mutable objects; exceptions |
null, Promise, the Node.js API |
Not available | Available |
| Imports | Osprey modules, including Osprey's ports | npm packages |
Osprey rejects valid TypeScript that breaks its rules, such as null, assignment to a field or a switch that misses a case. The error is reported at the TypeScript line. It never falls back to JavaScript behaviour, and an arbitrary TypeScript program or npm package does not run unchanged.
A project opts its .ts files in by listing them, so the compiler never claims every TypeScript file in a folder:
[project]
name = "express-hello-world"
source_roots = [".", "../../src"]
typescript_sources = ["../../src/express.ts", "index.ts"]
entry = "index.ts"
A single file can opt in with a first line of // osprey: flavor=typescript, or with --flavor typescript on the command line.
Checking with tsc is optional
Because the syntax is TypeScript, you can also run tsc over the same files, as you would run any linter. Editors and formatters that know TypeScript then see the same program. The Osprey compiler never runs tsc, never reads tsconfig.json and builds the same binary whether or not the lint has run. In the repository the lint is make typescript-lint.
What works today
Built and tested, with TypeScript twins of the corpus programs sharing the Default goldens:
- Functions and arrow functions, with inferred parameter and return types;
letand parameters that are reassigned. - Interfaces as records, and unions discriminated by a
kindfield, withswitchonkindchecked for missing cases. - Object literals, which take the record type a declared context gives them, and object spread.
xs.map,xs.filterandxs.reduceon lists, template literals,for … of, ESimportandexport, and documentation comments.- Effects:
interface Log extends Effect,perform<Log>().write(…),handler<Log>({ … }),handle<Log>({ … }, () => …),resume, handler state, static handlers andRequires<T, [Log]>. - Fibers:
spawn,awaitFiber,sendandrecv. - Imports between all four syntax flavors in one project.
- Editor support: the Osprey extension checks each
.tsfile a project lists, beside VS Code's own TypeScript checks, andosprey testfinds.test.tssuites. - In
@osprey/express: routing and:nameparameters,req.params,req.query,req.get, JSON request bodies throughjsonBody(req), middleware withapp.useandreq.next(), error handlers,express.Router()mounted withapp.mount,res.status,res.set,res.send,res.json,app.listenand Express's 404 page.
Not built yet:
null,undefined, classes, exceptions,asyncandawait; failure is aResult, and concurrency is fibers.- An object literal with no declared type that is used later as a record (issue 405).
- In
@osprey/express: HEAD and OPTIONS handling, redirects, static files,ETagandDateheaders, and Express's overloads by parameter count, such asapp.use(handler)without a path.
Osprey is actively evolving. Try it on your projects, validate it against your workload, and assess the risks before relying on it in production.
Next step
Read src/express.ts, the port's main module, written in the flavor it serves, then the ported web-service example.