---
url: /blog/2026/v0.7.2.md
description: >-
  v0.7.2 derives runtime validation schemas with the oxc toolchain: a full
  rebuild of 500+ routes in about 3 seconds, no dev server lag on heavy routes,
  no more naming conventions, and schemas stored as JSON Schema. Plus each
  backend route loaded on its own first request, and #src/ and #lib/ in place of
  $/.
---

This one is big.

It solves the biggest concern KosmoJS has had in three years: the cost of runtime validation.

## Validation from types, and its price

Runtime validation from plain TypeScript types started as an experiment.
It grew into a full pipeline, then into a workflow you could rely on:
write the type once, and it checks the request at runtime too.

It worked with a high level of precision, but the precision came at a cost.

The types were resolved with the TypeScript type checker,
through a stack of tfusion on top of ts-morph on top of the compiler itself.
The checker is thorough, and thorough is slow.
A route took anywhere from 100ms to a full second, the heavy ones on a big project.

A cache took most of that out of the daily loop.
But only most:

* saving a heavy route, or any file its types depend on, meant seconds of lag in the dev server
* deleting `var/lib/`, or an update that bumped the cache version, meant a full rebuild,
  and on a big project that could take minutes

So runtime validation stayed, in my own head, an experimental toy.
Precise, but not something to lean on in a big project.

## The answer came from Vite's wonderland

Most of what KosmoJS does well comes from Vite.
This came from what Vite itself relies on: the oxc toolchain.

I tried `oxc-resolver` some time ago, and was fascinated.
At the time I somehow could not get into `oxc-parser`,
so the type checker stack stayed, and so did the cost.

Now it is oxc all the way:
`oxc-parser` reads the route and every file its types come from,
`oxc-resolver` follows the imports between them,
and TypeBox turns what they find into JSON Schema at build time.
Nothing is type checked along the way.

## A fraction of a second

On a real project with 500+ backend routes, plenty of types and a heavy dependency graph,
a full rebuild takes around 3 seconds. For all of them.

And a save no longer lags the dev server, however heavy the route or its dependencies.

The cache is still there, but it is no longer what keeps things bearable.
Deleting `var/lib/` costs seconds now, not minutes.

## Name your types anything

Validation used to come with a naming rule:
do not name a type after a built-in, like `Event`, `Response`, `Error` or `Record`.
The schema was derived from a flattened type,
where such a name pointed at the built-in rather than at your type,
and validation failed at runtime while the code typechecked fine.

That rule is gone. Any name works:

```ts
type Event = {
  id: number;
  name: string;
  startsAt: string;
};

POST<{
  json: Event;
}>
```

KosmoJS resolves a name the way your editor does.
A type declared in the route, or imported into it,
is the type the schema is built from, whatever built-in shares its name.

## Schemas stored as JSON Schema

`schemas.ts` in `var/lib/` used to hold each schema as type text,
turned into a schema at runtime.

It now holds what a validation schema is declared to be: JSON Schema.

That makes the OpenAPI generator fast too.
It no longer computes a schema for every route, it just imports the ones already there.

## Each route loads on its first request

Server start time used to grow with the number of backend routes,
since every route was loaded before the server could listen.

Now backend routes are lazy-loaded, just like frontend routes.

At start, every route is registered with its path and methods,
and a middleware that loads that one route when it is first requested.
The first request to a route pays only for that route,
and a route nobody requests is never loaded at all.

That holds in development and in production alike,
so a production server now starts instantly too, however many routes it has.

## `#src/` and `#lib/` replace `$/`

`v0.6.10` added `$/`, to reach the derived code of any folder by name.
It goes already, in favor of two prefixes that say what they reach:

* `#src/` for the modules of any source folder: `#src/front/types/user`
* `#lib/` for the derived code of any folder, what `$/` used to be: `#lib/admin/core`

```ts
// a helper at the project root, building links into the admin folder
import { base } from "#lib/admin/core";

// the admin folder, reusing a type the front folder keeps
import type { User } from "#src/front/types/user";
```

Both work from anywhere: a source folder, or a file at the project root that belongs to no folder.
And validation follows them like any other path alias,
so a type imported through them becomes a schema all the same.

## Upgrading

Lazy routes bring two breaking changes, and `$/` makes a third. All three are mechanical.

### appFactory takes just a callback

The framework registers the routes now, so `api/app.ts` no longer passes them in.
`appFactory` takes a synchronous callback alone:

```ts [api/app.ts]
export default appFactory(routes, ({ app }) => {}); // [!code --]
export default appFactory(({ app }) => {}); // [!code ++]
```

### devSetup takes a function

`devSetup` takes a function returning the hooks, instead of the hooks themselves.
The function can be sync or async:

```ts [api/dev.ts]
export default devSetup(() => {
  return {
    requestHandler() {},
    teardownHandler() {},
  };
});
```

What the function creates is tied to the instance it was created for.
So a pool can be set up inside it, and closed by that same instance's `teardownHandler`:

```ts [api/dev.ts]
export default devSetup(async () => {
  const pool = await createPool(process.env.DATABASE_URL);
  return {
    requestHandler() {
      // ...
    },
    async teardownHandler() {
      await pool.end();
    },
  };
});
```

Define the pool outside the function instead, and it leaks on every reload.

### $/ becomes #lib/

If you import through `$/`, switch to `#lib/`: `$/admin/core` becomes `#lib/admin/core`.
