Skip to content
v0.7.2: validation types, resolved by oxc

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:

api/app.ts
ts
export default appFactory(routes, ({ app }) => {});
export default appFactory(({ app }) => {});

devSetup takes a function ​

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

api/dev.ts
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:

api/dev.ts
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.

Released under the MIT License.