grest-ts

grest-ts

TypeScript framework for building services around contracts — typed API definitions that serve as the single source of truth between client, server, and tests.

Why grest-ts?

• AI-era ready — Clean, explicit service code is exactly what AI assistants thrive on — no magic to misunderstand, no hidden wiring to hallucinate about. And in an era where AI writes more of your code, integration tests are the one testing layer that actually gives you confidence it works end-to-end. Unit tests check pieces; integration tests prove the system.
• Very fast — @grest-ts/schema validation and serialization performs equally well compared to Typia — the fastest in the ecosystem. @grest-ts/http benchmarks close to fastify with logging disabled.
• Contract-first — Define your API once. Get typed server handlers, typed clients, and typed test utilities automatically.
• Testing that survives refactors — Integration tests at the contract level with per-request mocks and spies. Each test suite launches its own runtime instance with isolated ports and database — no shared state between suites. Mocks apply to exactly the request you specify, not globally.
• Zero-config local dev — tsx src/MyRuntime.ts and your service is running. Launch multiple services, discovery handles routing. Launch multiple instances, get load balancing.
• Scalable — From a single runtime to hundreds of microservices. Same patterns, same contracts, same tests. Service discovery is pluggable — built-in discovery handles local dev automatically, swap in your production implementation (Kubernetes, Consul, etc.) without changing service code.
• No magic — No DI containers, no decorators-as-wiring, no hidden resolution. Your Runtime's compose() is your bootstrap — all wiring visible in one place, plain constructors. Framework packages are thin layers over standard libraries (for example, mysql2, pg, vitest) — use them or bring your own.
• Monorepo or multi-repo — Run everything in one monorepo or split across multiple repos. The framework doesn't care — contracts are shared via packages (if you want to), choose the strategy that fits your team.
• Tree-shakable — Fully tree-shakable for minimal bundle sizes (for server package 400mb vs 5mb starts to matter at scale for release speeds)
• Typed errors across boundaries — Errors carry reference IDs, typed data, and flow across service boundaries as discriminated unions. await to throw, .asResult() to handle explicitly — callers choose per call site.
• Framework-enforced permissions — Every contract method declares a required permission (mandatory at compile time; GG_NO_PERMISSIONS marks a method explicitly public). The framework gates every HTTP request and every clientToServer WebSocket message before the handler runs. See the @grest-ts/http and @grest-ts/websocket READMEs for the mechanism and guarantees.
• Extendable — Testkit, config sources, loggers, metrics exporters — all pluggable. Or don't even use them if you like your own opensource version – they most likely work just fine.

Purpose

Set the standard for your whole company — from zero to unicorn, you will be ready. Built from experience of doing exactly that.

Current State

Being transparent: grest-ts is a new framework. Everything described here works — it's not a roadmap, it's shipped code.

The framework is designed by a developer who co-founded and scaled a tech company well past unicorn, solving the same infrastructure problems at every stage of growth. grest-ts is the distillation of those lessons into a framework — what he wishes existed from day one.

It's currently battle-tested on one production project: a real estate management platform with real users and non-trivial complexity — JWT auth with multi-level permissions, multi-tenancy, bank integrations, automated invoice processing, expense documents parsing (pdf), S3 file management, SQS background jobs, bookkeeping system integrations, audit logging, and a full React + Vite frontend consuming 100+ typed API contracts. That's one project more than most frameworks have at launch, but still one project. APIs may evolve, rough edges exist, and you'd be an early adopter. If that excites rather than scares you — welcome. Fair warning though: once you get used to how testing works here, you'll miss it everywhere else.

---

Getting Started

Copy the starter folder, rename it, and you have a working app:

# Start with a simple starter template
npm create @grest-ts/starter my-app

# Terminal 1 — server
cd server && npm run dev

# Terminal 2 — client
cd client && npm run dev

The starter is an npm workspaces monorepo with three packages: