yatta/universal

Builds an app from a table of routes.

1export const app = createApp({2  getUser: defineRoute(3    { method: "get", path: "/users/:id", params: UserId, response: User },4    async ({ params, services }) => services.db.users.findById(params.id),5  ),6}, {7  // Typed, so a handler's `services.db` is your database.8  services: { db, auth, realtime },9});

Builds the browser client for an app.

This is the other half of the same definition. The app calls handlers in process; this reaches them over HTTP. Both surfaces come from the table, so the developer writes neither.

1// Server Component — direct, no HTTP.2const user = await app.getUser({ params: { id } });3 4// Browser — over HTTP, same shape.5const api = createClient(app, { baseUrl: "/api" });6const user2 = await api.getUser({ params: { id } });

A default service set.

Reads the framework's singletons lazily. A getter rather than a value, so importing a route file does not start a database connection or a socket — the failure mode being that reading a route table on the server to mount it would spin up everything the app owns.

Declares one route.

The handler returns a plain value, not a `Response`. That is the change that makes a direct call meaningful: `invoke()` hands back the value itself rather than something that has to be unwrapped from a transport. The return type is constrained to the declared response when there is one, so a handler that drifts from its contract fails here rather than at the browser.

1const getUser = defineRoute(2  { method: "get", path: "/users/:id", params: UserId, response: User },3  async ({ params, services }) => {4    const user = await services.db.users.findById(params.id);5    if (!user) throw new HttpError(404, "No such user");6    return user;7  },8);

Calls a route as a function. No HTTP, no serialization, no connection pool.

This is the point of the whole module. On a server the caller and the handler are in the same process, so a network hop between them buys no isolation and costs a round trip, a socket, and a failure mode.

1// A Server Component. The handler runs here, with your `db`.2const user = await invoke(app, "getUser", { params: { id } });3 4// Type inferred from the handler, not from a shared interface.5const name: string = user.name;

Serves an app over HTTP.

The transport. It matches a path, validates the arguments, runs the same handler `invoke` would, and turns the plain value it returns into a response. Nothing about the route is re-declared here.

1Bun.serve({ fetch: mount(app) });

Reads the routes off either an app or a bare table.

Both accepted because both are natural to have on hand, and a developer should not have to know which one a function expects — or unwrap it at the call site.

Adds middleware to a route.

Mutates and returns the route, so it reads as a modifier: `withAuth(defineRoute(...))`.

A declared route: its spec, its handler, and the handler's return type kept so

The framework objects a handler can use.

Injected rather than imported, so a handler can be called directly, over HTTP, or in a test with a stand-in. An open map by default, because which engines an app uses is its own business.

Services with the engines an app actually has, so handlers get real types.

A request, as far as the transport layer needs to know.

Arguments for a direct call.

What a route accepts, minus the request context: there is no HTTP request, because nothing crossed a network. Each input is contributed only when the route declares it, so passing a body to a route without one is an error rather than a field quietly dropped.

What a direct call hands back: the handler's own return type.

A client for an app.

The value a handler returns when a response schema is declared.

A set of routes plus the services they use.

One of these per process on the server, and per request on a server render — never a module-level singleton that outlives a request, which would serve one user's data to the next. One method per route, each callable directly. Derived from the table, so the developer writes routes and nothing else — no wrapper per endpoint, no name string to keep in step, no signature to maintain. The method's argument and return types come from the route itself.

A method per route, reached over HTTP.

The same names, the same arguments and the same return types as the app's direct methods. Derived from the same table, so there is nothing to keep in step — a renamed route is a compile error here too.

Everything a handler is given.

Runs before a handler, on both paths.

Return a value to answer instead of calling the handler — that is how an auth check rejects. Return `undefined` to continue. The point of it being here rather than only on the transport: a check that lives in HTTP middleware is *not* run by `app.getUser()` or `invoke()`. A Server Component calling a route directly would sail straight past an authorisation check that HTTP enforces, which is the worst possible place for that gap — the code looks guarded and is not.

Path parameters as plain strings, read from the path template.

The shape a route declares: method, path, and validators.

A table of routes.