@vigajs/core 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,99 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses [Semantic Versioning](https://semver.org/). While the version is `0.x`, minor releases may include breaking changes.
+
+## [0.1.0] - 2026-11-02
+
+First public release.
+
+### Generator
+
+- `viga generate` (`viga g`) creates a `resource`, `module`, `controller` or `service`. It has no dependencies, never changes existing files and prints what to register by hand.
+
+### `@vigajs/create`
+
+- `pnpm create @vigajs my-app`, also with npm, yarn and bun, creates a project with its scripts, TypeScript configuration and a first module. It has no dependencies and runs no installs.
+
+### Core (`@vigajs/core`)
+
+- Modules with `imports`, `exports`, re-exports and global modules (which must be imported by the root module).
+- Dependency injection with `inject()` in class fields: class, `useClass`, `useValue` and `useFactory` providers, `InjectionToken`, and detection of circular dependencies and imports.
+- Inside a controller, routes are sorted by specificity, so `/export` wins over `/:id` whatever the declaration order. Startup fails on routes that match the same requests, and warns when a route in another controller shadows a later one.
+- Controllers with standard TC39 decorators, `@HttpCode`, guards, interceptors and `@Public`. Every guard, including method guards and `@RateLimit`, runs before any interceptor, in HTTP and WebSocket, so a caching interceptor can't skip them. `@Public` isn't inherited: subclasses and overridden methods are private until they declare it again.
+- Private routes by default through `app.useAuthGuard()`. Startup warns when private routes have no auth guard and lists the public routes at debug level (also for WebSocket gateways).
+- Lifecycle hooks `OnModuleInit` and `OnModuleDestroy`, `close()` that only closes providers that finished starting, and `enableShutdownHooks()`, which exits with the signal's standard code (also as PID 1 in a container).
+- Per-request context with `createContextKey` and `runInNewContext`.
+- Security defaults: security headers, body size limit, server timeouts, request id, `X-Powered-By` disabled, `requireValidation` on by default (a route without a body schema doesn't parse a body and answers 400 `errors.unexpectedBody` when one arrives, and `ctx.req.body` holds the validated value), `concealRoutes` on by default when there is an auth guard (which also covers WebSocket handshakes), and a body parsed only on existing routes and after authentication. `trustProxy: true` logs a warning because it lets clients forge their IP. CSRF protection (`csrf`) rejects, before parsing the body, cross-site `POST` requests a browser can send without a CORS preflight, with `trustedOrigins` for callbacks such as OAuth `form_post`.
+- Rate limiting with `rateLimit()` and `@RateLimit()`, with a pluggable store. The default key groups IPv6 clients by /56 network and IPv4-mapped addresses by their IPv4, through the exported `ipKey()`. The exported `CLIENT_IP` token resolves the client IP with the app's `trustProxy` from a raw Node.js request, such as a WebSocket handshake. The in-memory store is bounded (`maxKeys`), hashes long keys, and when full evicts only keys seen once, so a flood of new keys can't reset a counter under attack; with no room left it fails closed.
+- HTTP exceptions with stable codes, `resolveMessage` and developer diagnostics that can be translated with `setDiagnostics`. `HttpException` covers any other status; when its message is free text, the response `code` is `errors.badRequest` for 4xx and `errors.internal` for 5xx. A failure after the response started is logged once and closes the connection.
+- `listen()` defaults to port 3000.
+- `@vigajs/core/tsconfig.json`, a base TypeScript configuration to extend, so a project only needs `extends` and `include`.
+- `OnServerListen`, `OnServerClose` and `OnDrain` lifecycle hooks. `OnDrain` runs once in-flight requests have finished and before any `onModuleDestroy`.
+- `createContextKey(name, { detached: true })` for values that must not reach `@vigajs/core/events` listeners, such as a transaction.
+- Guards and interceptors accept a context type, so they can be used outside HTTP.
+
+### `@vigajs/core/validation`
+
+- `@Validate` for `body`, `query` and `params` with any Standard Schema library, typed against the handler's context (which may extend `HttpContext`). Each error's `code` comes from the library's `code` or `type` field, so it works with Zod, Valibot and ArkType.
+- `ValidationModule.forRoot({ formatIssue })` to customize or translate validation messages.
+
+### `@vigajs/core/i18n`
+
+- `I18n` with nested catalogs, `Accept-Language` negotiation, `resolveLocale` (header name or function), and framework messages in English and Spanish.
+- `diagnosticsEs`, the Spanish dictionary for developer messages.
+
+### `@vigajs/core/health`
+
+- `HealthModule.forRoot()` adds public `/health` and `/ready` routes (configurable, under `globalPrefix`). `/health` never runs the checks; `/ready` answers 503 if a check throws, returns `false` or exceeds `timeoutMs`. Responses carry no details, failures go to the logger, concurrent requests share one run and the result is cached for `cacheMs`.
+- `DatabaseService.ping()` in `@vigajs/core/drizzle`.
+
+### `@vigajs/core/crypto`
+
+- `hashPassword`, `verifyPassword` and `needsRehash` with Argon2id from `node:crypto` (no dependencies), in the standard PHC format, with NFKC normalization.
+- `randomToken`, `hashToken` and `safeEqual`.
+- `CryptoModule.forRoot()` with `UrlSigner` and `@Signed()` for signed URLs with expiry, bound to the path, query and method, and `Encryptor` for AES-256-GCM with a context that binds a value to its owner. Both support key rotation and refuse keys under 32 bytes at startup.
+
+### `@vigajs/core/events`
+
+- `EventsModule.forRoot()`, `EventBus` and `@OnEvent` for an in-memory event bus with class-based events. `emit()` resolves when every listener has finished and never rejects; listener errors are logged and isolated.
+- Listeners inherit a copy of the context without `detached` keys, so they don't join the emitter's transaction. Emitting inside a transaction logs a warning.
+- Shutdown waits for running listeners, up to `drainTimeoutMs`, before any `onModuleDestroy`.
+
+### `@vigajs/core/workers`
+
+- `WORKER_KEY`, `WorkerModule.forKey()` and `startWorker()` so the same worker module runs inside the API, as a child process or on another server, without a queue library of its own. A worker closes in an orderly way on a signal and when its parent dies, with `orphanTimeoutMs` as a limit in the second case.
+- `WorkersModule.forRoot()` and `WorkerSupervisor` fork one process per key, with `start`, `stop` and `list`, restart with backoff, a graceful stop that ends in `SIGKILL` after `stopTimeoutMs`, and a `maxWorkers` limit (8 by default).
+
+### `@vigajs/core/upload`
+
+- `@Upload()` over Multer and `file-type`, both optional peer dependencies. It reads files after authentication and guards, requires `types` or `check`, detects the type from the content, stores files under generated names in a temporary folder and removes what isn't moved with `moveTo` when the response ends, also when a request fails or is cut off. Text fields are rejected unless the route uses `@Validate({ body })`. `optional: true` with `OptionalUploadContext` covers forms where the file may be absent.
+
+### `@vigajs/core/websocket`
+
+- `WebSocketModule.forRoot()` (an object or a function that runs in the container and can use `inject()`, also in `DrizzleModule.forRoot()`), `@Gateway`, `@OnMessage` with Standard Schema validation, `WsContext` and `WsServer`.
+- Rooms with `join`, `leave`, `to(room).send()` and `broadcast()`, limited per connection by `maxRoomsPerClient`.
+- Per-connection language with `i18n` and `resolveLocale`, applied to every message and to error messages.
+- `RateLimit` per event or per gateway, keyed per connection by default or by any value of the context, sharing the bounded in-memory store with HTTP.
+- Public `WsAdapter` interface, with a default adapter on top of `ws` that is loaded only when needed. Adapters receive the gateway paths; a socket.io adapter in the test suite checks that the interface works beyond `ws`.
+- Security defaults: private gateways, handshake authentication with a timeout (`handshakeTimeoutMs`), session expiry from the `expiresAt` that `authenticate` returns (closes with 1008, renewable with `client.expireAt()`), a cap on simultaneous connections (`maxConnections`), a cap per client IP on by default (`connectionsPerKey`, 50, using `trustProxy` and grouping IPv6 by /56), a cap on handshakes still authenticating (`maxPendingHandshakes`), `Origin` allowlist, `maxPayload`, per-connection message rate limit counted on arrival (twice the limit disconnects with 1008, as does piling up more than 100 messages before `onConnection` ends), heartbeat, slow-client protection and `requireValidation`: an event without a schema doesn't accept data and answers 400 `errors.unexpectedData` when it arrives.
+
+### `@vigajs/core/config`
+
+- `ConfigModule.forRoot({ schema, env? })` validates the configuration at startup with any Standard Schema library and fails listing every invalid variable, without showing their values, even short or nested ones.
+- `inject(CONFIG)` is typed through `Register` and returns a deeply frozen object.
+
+### `@vigajs/core/pagination`
+
+- `@Paginate` with `page.offset`, `page.limit` and a generic `page.result(items, total)` that returns `PaginatedResult<T>` with `total`, `lastPage` and relative `next`/`prev` links that keep the query parameters.
+- Security defaults: `maxLimit` caps the page size, `maxPage` and `maxOffset` (10,000 rows) cap the depth, invalid values respond 400, and links never use the `Host` header.
+
+### `@vigajs/core/drizzle`
+
+- `DrizzleModule.forRoot()` and `DatabaseService` with pool shutdown, default timeouts for statements, connections and idle transactions, and a startup warning for connections without verified TLS to a remote host.
+- Transactions with `database.transaction()` and `@Transactional()`, nested savepoints and isolation options.
+
+### `@vigajs/core/testing`
+
+- `createTestingApp(Module, { overrides, configure })` starts the app on a free local port with the production defaults and a silent logger. `overrides` replaces providers in any module and fails on a token that matches no provider; `app.request()` returns the status, headers and parsed body.
+
+[0.1.0]: https://github.com/dialmonsalve/viga/releases/tag/v0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Diego Monsalve
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.es.md

@@ -0,0 +1,240 @@
+# viga
+
+[English](README.md) · **Español** · [Documentación](https://vigajs.dev/es/)
+
+Framework HTTP para Node.js sobre Express 5: módulos, inyección de dependencias, guards e interceptores con **decoradores estándar de JavaScript (TC39)**. Sin `reflect-metadata`, sin `experimentalDecorators` y sin `emitDecoratorMetadata`.
+
+El core solo resuelve lo que todo servidor necesita. Lo demás son subrutas opcionales: si no las importas, no se instala nada extra.
+
+| Importación | Qué trae | Requiere |
+|---|---|---|
+| `@vigajs/core` | Módulos, DI, controladores, guards, interceptores, `@Public`, excepciones HTTP, ciclo de vida, logger | `express` |
+| `@vigajs/core/validation` | `@Validate` y `ValidationModule` con cualquier librería [Standard Schema](https://standardschema.dev) | Nada (tú eliges Zod, Valibot, ArkType…) |
+| `@vigajs/core/i18n` | Catálogos de mensajes, negociación de `Accept-Language`, mensajes del framework en es/en | Nada |
+| `@vigajs/core/drizzle` | `DrizzleModule` y `DatabaseService` con cierre del pool | `drizzle-orm`, `pg` |
+| `@vigajs/core/config` | `ConfigModule` que valida y tipa las variables de entorno al arrancar | Nada |
+| `@vigajs/core/pagination` | `@Paginate` con resultados tipados, enlaces relativos y límites | Nada |
+| `@vigajs/core/websocket` | Gateways, salas y una interfaz de adaptador pública, con valores restrictivos por defecto | `ws` |
+| `@vigajs/core/testing` | `createTestingApp` para probar la app con peticiones HTTP reales y providers reemplazados | Nada |
+| `@vigajs/core/health` | Rutas `/health` y `/ready` con tus propias comprobaciones, sin revelar detalles | Nada |
+| `@vigajs/core/crypto` | Hash de contraseñas con Argon2id, tokens aleatorios, URLs firmadas y cifrado AES-256-GCM | Nada |
+| `@vigajs/core/events` | Bus de eventos en memoria con eventos tipados, errores aislados y listeners que terminan antes de apagar | Nada |
+| `@vigajs/core/workers` | El mismo worker en la API, en procesos hijos o en otro servidor, con un supervisor que los reinicia | Nada |
+| `@vigajs/core/upload` | `@Upload` con límites, tipos de archivo detectados por su contenido y limpieza automática | `multer`, `file-type` |
+
+## Agradecimientos
+
+viga está inspirado en [NestJS](https://nestjs.com). Los módulos, la inyección de dependencias, los controladores con decoradores, los guards y los interceptores vienen de las ideas que Kamil Myśliwiec y la comunidad de Nest llevan años perfeccionando. Gracias por mostrar que en Node se puede construir backends con estructura.
+
+viga no comparte código con Nest. Toma esas ideas y las lleva a otro terreno: decoradores estándar de JavaScript (TC39) en lugar de `experimentalDecorators` y `reflect-metadata`, promesas en lugar de RxJS y un core pequeño con todo lo demás opcional.
+
+También se apoya en el trabajo de [Express](https://expressjs.com), [Standard Schema](https://standardschema.dev) y [Drizzle ORM](https://orm.drizzle.team).
+
+## Requisitos
+
+- Node.js 24.13 o superior
+- Express 5
+- TypeScript con decoradores estándar (sin `experimentalDecorators`). Heredar `@vigajs/core/tsconfig.json` lo configura por ti
+- Un compilador que transforme los decoradores, como `tsc` o `tsx`. Node ejecuta TypeScript quitando los tipos, pero todavía no soporta decoradores: `node main.ts` falla en el primer `@`.
+
+## Instalación
+
+La forma más rápida es crear un proyecto:
+
+```bash
+pnpm create @vigajs mi-app
+```
+
+Para añadir viga a un proyecto existente:
+
+```bash
+pnpm add @vigajs/core express
+pnpm add -D typescript tsx @types/express @types/node
+```
+
+```json
+{
+  "extends": "@vigajs/core/tsconfig.json",
+  "include": ["src"]
+}
+```
+
+Solo si usas `@vigajs/core/drizzle`:
+
+```bash
+pnpm add drizzle-orm@0.45 pg
+pnpm add -D @types/pg
+```
+
+Solo si usas `@vigajs/core/websocket` con el adaptador por defecto:
+
+```bash
+pnpm add ws
+```
+
+Solo si usas `@vigajs/core/upload`:
+
+```bash
+pnpm add multer file-type
+```
+
+## Ejemplo mínimo
+
+```ts
+import { Controller, Get, Injectable, Module, Public, createApp, inject } from '@vigajs/core';
+
+@Injectable()
+class BooksService {
+  list() {
+    return [{ id: 1, title: 'Dune' }];
+  }
+}
+
+@Controller('/books')
+class BooksController {
+  private readonly books = inject(BooksService);
+
+  @Public()
+  @Get()
+  list() {
+    return this.books.list();
+  }
+}
+
+@Module({ controllers: [BooksController], providers: [BooksService] })
+class AppModule {}
+
+const app = createApp({ rootModule: AppModule, globalPrefix: '/api/v1' }).enableShutdownHooks();
+
+await app.listen(3000);
+```
+
+Las rutas son privadas por defecto: sin `@Public()`, `GET /api/v1/books` respondería 401 hasta configurar un guard con `app.useAuthGuard()` (ver [Guards](https://vigajs.dev/es/core/guards/)).
+
+## Core (`@vigajs/core`)
+
+### Módulos e inyección de dependencias
+
+Consulta [Módulos](https://vigajs.dev/es/core/modules/) y [Providers e inyección de dependencias](https://vigajs.dev/es/core/providers/) en la documentación.
+
+### Ciclo de vida
+
+Consulta [Ciclo de vida de la app](https://vigajs.dev/es/core/app-lifecycle/) en la documentación.
+
+### Rutas privadas por defecto
+
+Consulta [Guards](https://vigajs.dev/es/core/guards/) en la documentación. Las mismas reglas, incluido que `@Public` no se hereda, valen para los gateways de `@vigajs/core/websocket`.
+
+### Orden de una petición
+
+Consulta [Ciclo de vida de una petición](https://vigajs.dev/es/core/request-lifecycle/) en la documentación.
+
+### Guards e interceptores
+
+Consulta [Guards](https://vigajs.dev/es/core/guards/) e [Interceptores](https://vigajs.dev/es/core/interceptors/) en la documentación.
+
+### Contexto por petición
+
+Consulta [El contexto de la petición](https://vigajs.dev/es/core/request-lifecycle/#el-contexto-de-la-petición) en la documentación.
+
+### Middlewares de Express
+
+Consulta [Middlewares de Express](https://vigajs.dev/es/core/request-lifecycle/#middlewares-de-express) en la documentación.
+
+### Valores de seguridad por defecto
+
+Consulta [Valores por defecto](https://vigajs.dev/es/security/defaults/) e [IP del cliente y proxies](https://vigajs.dev/es/security/client-ip/) en la documentación. Estos valores reducen riesgos habituales, pero no hacen segura una aplicación por sí solos.
+
+### Rate limiting
+
+Consulta [Límite de peticiones](https://vigajs.dev/es/security/rate-limiting/) en la documentación.
+
+### Checklist para pruebas de seguridad
+
+Consulta [Lista para pruebas de seguridad](https://vigajs.dev/es/security/checklist/) en la documentación.
+
+### Errores
+
+Consulta [Excepciones](https://vigajs.dev/es/core/exceptions/) en la documentación.
+
+### Mensajes para desarrolladores
+
+Consulta [Mensajes para desarrolladores](https://vigajs.dev/es/optional/i18n/#mensajes-para-desarrolladores) en la documentación.
+
+### Logger
+
+Consulta [Usa tu propio logger](https://vigajs.dev/es/core/providers/#usa-tu-propio-logger) en la documentación.
+
+## @vigajs/core/validation
+
+Consulta [@vigajs/core/validation](https://vigajs.dev/es/optional/validation/) en la documentación.
+
+## @vigajs/core/i18n
+
+Consulta [@vigajs/core/i18n](https://vigajs.dev/es/optional/i18n/) en la documentación.
+
+## @vigajs/core/config
+
+Consulta [@vigajs/core/config](https://vigajs.dev/es/optional/config/) en la documentación.
+
+## @vigajs/core/pagination
+
+Consulta [@vigajs/core/pagination](https://vigajs.dev/es/optional/pagination/) en la documentación.
+
+## @vigajs/core/drizzle
+
+Consulta [@vigajs/core/drizzle](https://vigajs.dev/es/optional/drizzle/) en la documentación.
+
+## @vigajs/core/websocket
+
+Consulta [@vigajs/core/websocket](https://vigajs.dev/es/optional/websocket/) en la documentación.
+
+## @vigajs/core/testing
+
+Consulta [@vigajs/core/testing](https://vigajs.dev/es/optional/testing/) en la documentación.
+
+## @vigajs/core/health
+
+Consulta [@vigajs/core/health](https://vigajs.dev/es/optional/health/) en la documentación.
+
+## @vigajs/core/crypto
+
+Consulta [@vigajs/core/crypto](https://vigajs.dev/es/optional/crypto/) en la documentación.
+
+## @vigajs/core/events
+
+Consulta [@vigajs/core/events](https://vigajs.dev/es/optional/events/) en la documentación.
+
+## @vigajs/core/workers
+
+Consulta [@vigajs/core/workers](https://vigajs.dev/es/optional/workers/) en la documentación.
+
+## @vigajs/core/upload
+
+Consulta [@vigajs/core/upload](https://vigajs.dev/es/optional/upload/) en la documentación.
+
+## Generar código
+
+`pnpm exec viga g resource books` crea un módulo, un controlador CRUD, un servicio y sus esquemas, y nunca modifica tus archivos existentes. Consulta [Generar código](https://vigajs.dev/es/start/generate/) en la documentación.
+
+## Desarrollo
+
+| Script | Qué hace |
+|---|---|
+| `pnpm test` | Tests con el runner nativo de Node. Los de PostgreSQL se saltan |
+| `pnpm db:test:up` / `db:test:down` | Levanta o apaga un PostgreSQL desechable en el puerto 55432 (datos en memoria) |
+| `pnpm test:db` | Todos los tests, incluidos los de PostgreSQL (requiere `db:test:up`) |
+| `pnpm test:coverage` | Tests con un informe de cobertura de `src/` (ejecútalo con `VIGA_TEST_DATABASE_URL` para incluir PostgreSQL). Las líneas que solo contienen tipos pueden aparecer como no cubiertas |
+| `pnpm check-types` | Comprueba los tipos |
+| `pnpm build` | Compila a `dist/` con `tsc` (JS + tipos) |
+| `pnpm pack` | Genera el `.tgz` que se publicaría, para probarlo en otro proyecto |
+
+`prepublishOnly` ejecuta tipos, todos los tests (con PostgreSQL) y build antes de cada `npm publish`.
+
+## Contribuciones
+
+viga es un proyecto personal que mantengo en mi tiempo libre, así que no acepto pull requests ni issues. Puedes hacer un fork bajo la licencia MIT.
+
+## Licencia
+
+[MIT](LICENSE)

package/README.md

@@ -1,3 +1,240 @@
-# Temporary Holding Version
+# viga
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**English** · [Español](README.es.md) · [Documentation](https://vigajs.dev/en/)
+
+HTTP framework for Node.js on top of Express 5: modules, dependency injection, guards and interceptors with **standard JavaScript decorators (TC39)**. No `reflect-metadata`, no `experimentalDecorators` and no `emitDecoratorMetadata`.
+
+The core only covers what every server needs. Everything else lives in optional subpaths: if you don't import them, nothing extra gets installed.
+
+| Import | What it provides | Requires |
+|---|---|---|
+| `@vigajs/core` | Modules, DI, controllers, guards, interceptors, `@Public`, HTTP exceptions, lifecycle, logger | `express` |
+| `@vigajs/core/validation` | `@Validate` and `ValidationModule` with any [Standard Schema](https://standardschema.dev) library | Nothing (you pick Zod, Valibot, ArkType…) |
+| `@vigajs/core/i18n` | Message catalogs, `Accept-Language` negotiation, framework messages in en/es | Nothing |
+| `@vigajs/core/drizzle` | `DrizzleModule` and `DatabaseService` with pool shutdown | `drizzle-orm`, `pg` |
+| `@vigajs/core/config` | `ConfigModule` that validates and types environment variables at startup | Nothing |
+| `@vigajs/core/pagination` | `@Paginate` with typed results, relative links and limits | Nothing |
+| `@vigajs/core/websocket` | Gateways, rooms and a public adapter interface, with restrictive defaults | `ws` |
+| `@vigajs/core/testing` | `createTestingApp` to test the app with real HTTP requests and replaced providers | Nothing |
+| `@vigajs/core/health` | `/health` and `/ready` routes with your own checks, without revealing details | Nothing |
+| `@vigajs/core/crypto` | Password hashing with Argon2id, random tokens, signed URLs and AES-256-GCM encryption | Nothing |
+| `@vigajs/core/events` | In-memory event bus with typed events, isolated errors and listeners that finish before shutdown | Nothing |
+| `@vigajs/core/workers` | The same worker in the API, in child processes or on another server, with a supervisor that restarts them | Nothing |
+| `@vigajs/core/upload` | `@Upload` with limits, file types detected from the content and automatic cleanup | `multer`, `file-type` |
+
+## Acknowledgements
+
+viga is inspired by [NestJS](https://nestjs.com). Modules, dependency injection, decorator-based controllers, guards and interceptors come from the ideas Kamil Myśliwiec and the Nest community have spent years refining. Thank you for showing that Node backends can have structure.
+
+viga shares no code with Nest. It takes those ideas somewhere else: standard JavaScript decorators (TC39) instead of `experimentalDecorators` and `reflect-metadata`, promises instead of RxJS, and a small core with everything else optional.
+
+It also builds on the work of [Express](https://expressjs.com), [Standard Schema](https://standardschema.dev) and [Drizzle ORM](https://orm.drizzle.team).
+
+## Requirements
+
+- Node.js 24.13 or later
+- Express 5
+- TypeScript with standard decorators (no `experimentalDecorators`). Extending `@vigajs/core/tsconfig.json` sets this up for you
+- A compiler that transforms decorators, such as `tsc` or `tsx`. Node runs TypeScript by stripping types, but it doesn't support decorators yet: `node main.ts` fails at the first `@`.
+
+## Installation
+
+The fastest way is to create a project:
+
+```bash
+pnpm create @vigajs my-app
+```
+
+To add @vigajs/core to an existing project:
+
+```bash
+pnpm add @vigajs/core express
+pnpm add -D typescript tsx @types/express @types/node
+```
+
+```json
+{
+  "extends": "@vigajs/core/tsconfig.json",
+  "include": ["src"]
+}
+```
+
+Only if you use `@vigajs/core/drizzle`:
+
+```bash
+pnpm add drizzle-orm@0.45 pg
+pnpm add -D @types/pg
+```
+
+Only if you use `@vigajs/core/websocket` with the default adapter:
+
+```bash
+pnpm add ws
+```
+
+Only if you use `@vigajs/core/upload`:
+
+```bash
+pnpm add multer file-type
+```
+
+## Minimal example
+
+```ts
+import { Controller, Get, Injectable, Module, Public, createApp, inject } from '@vigajs/core';
+
+@Injectable()
+class BooksService {
+  list() {
+    return [{ id: 1, title: 'Dune' }];
+  }
+}
+
+@Controller('/books')
+class BooksController {
+  private readonly books = inject(BooksService);
+
+  @Public()
+  @Get()
+  list() {
+    return this.books.list();
+  }
+}
+
+@Module({ controllers: [BooksController], providers: [BooksService] })
+class AppModule {}
+
+const app = createApp({ rootModule: AppModule, globalPrefix: '/api/v1' }).enableShutdownHooks();
+
+await app.listen(3000);
+```
+
+Routes are private by default: without `@Public()`, `GET /api/v1/books` would respond 401 until you set a guard with `app.useAuthGuard()` (see [Guards](https://vigajs.dev/en/core/guards/)).
+
+## Core (`@vigajs/core`)
+
+### Modules and dependency injection
+
+See [Modules](https://vigajs.dev/en/core/modules/) and [Providers and dependency injection](https://vigajs.dev/en/core/providers/) in the documentation.
+
+### Lifecycle
+
+See [App lifecycle](https://vigajs.dev/en/core/app-lifecycle/) in the documentation.
+
+### Private routes by default
+
+See [Guards](https://vigajs.dev/en/core/guards/) in the documentation. The same rules, `@Public` not being inherited included, apply to `@vigajs/core/websocket` gateways.
+
+### Request order
+
+See [Request lifecycle](https://vigajs.dev/en/core/request-lifecycle/) in the documentation.
+
+### Guards and interceptors
+
+See [Guards](https://vigajs.dev/en/core/guards/) and [Interceptors](https://vigajs.dev/en/core/interceptors/) in the documentation.
+
+### Request context
+
+See [The request context](https://vigajs.dev/en/core/request-lifecycle/#the-request-context) in the documentation.
+
+### Express middlewares
+
+See [Express middlewares](https://vigajs.dev/en/core/request-lifecycle/#express-middlewares) in the documentation.
+
+### Security defaults
+
+See [Security defaults](https://vigajs.dev/en/security/defaults/) and [Client IP and proxies](https://vigajs.dev/en/security/client-ip/) in the documentation. These defaults reduce common risks, but they don't make an application secure on their own.
+
+### Rate limiting
+
+See [Rate limiting](https://vigajs.dev/en/security/rate-limiting/) in the documentation.
+
+### Security testing checklist
+
+See [Security testing checklist](https://vigajs.dev/en/security/checklist/) in the documentation.
+
+### Errors
+
+See [Exceptions](https://vigajs.dev/en/core/exceptions/) in the documentation.
+
+### Developer messages
+
+See [Developer messages](https://vigajs.dev/en/optional/i18n/#developer-messages) in the documentation.
+
+### Logger
+
+See [Use your own logger](https://vigajs.dev/en/core/providers/#use-your-own-logger) in the documentation.
+
+## @vigajs/core/validation
+
+See [@vigajs/core/validation](https://vigajs.dev/en/optional/validation/) in the documentation.
+
+## @vigajs/core/i18n
+
+See [@vigajs/core/i18n](https://vigajs.dev/en/optional/i18n/) in the documentation.
+
+## @vigajs/core/config
+
+See [@vigajs/core/config](https://vigajs.dev/en/optional/config/) in the documentation.
+
+## @vigajs/core/pagination
+
+See [@vigajs/core/pagination](https://vigajs.dev/en/optional/pagination/) in the documentation.
+
+## @vigajs/core/drizzle
+
+See [@vigajs/core/drizzle](https://vigajs.dev/en/optional/drizzle/) in the documentation.
+
+## @vigajs/core/websocket
+
+See [@vigajs/core/websocket](https://vigajs.dev/en/optional/websocket/) in the documentation.
+
+## @vigajs/core/testing
+
+See [@vigajs/core/testing](https://vigajs.dev/en/optional/testing/) in the documentation.
+
+## @vigajs/core/health
+
+See [@vigajs/core/health](https://vigajs.dev/en/optional/health/) in the documentation.
+
+## @vigajs/core/crypto
+
+See [@vigajs/core/crypto](https://vigajs.dev/en/optional/crypto/) in the documentation.
+
+## @vigajs/core/events
+
+See [@vigajs/core/events](https://vigajs.dev/en/optional/events/) in the documentation.
+
+## @vigajs/core/workers
+
+See [@vigajs/core/workers](https://vigajs.dev/en/optional/workers/) in the documentation.
+
+## @vigajs/core/upload
+
+See [@vigajs/core/upload](https://vigajs.dev/en/optional/upload/) in the documentation.
+
+## Generating code
+
+`pnpm exec viga g resource books` creates a module, a CRUD controller, a service and its schemas, and never changes your existing files. See [Generating code](https://vigajs.dev/en/start/generate/) in the documentation.
+
+## Development
+
+| Script | What it does |
+|---|---|
+| `pnpm test` | Tests with Node's native runner. PostgreSQL tests are skipped |
+| `pnpm db:test:up` / `db:test:down` | Starts or stops a disposable PostgreSQL on port 55432 (in-memory data) |
+| `pnpm test:db` | All tests, PostgreSQL ones included (requires `db:test:up`) |
+| `pnpm test:coverage` | Tests with a coverage report of `src/` (run it with `VIGA_TEST_DATABASE_URL` set to include PostgreSQL). Lines that only contain types can show as uncovered |
+| `pnpm check-types` | Type checks |
+| `pnpm build` | Compiles to `dist/` with `tsc` (JS + types) |
+| `pnpm pack` | Builds the `.tgz` that would be published, to try it in another project |
+
+`prepublishOnly` runs type checks, every test (with PostgreSQL) and the build before each `npm publish`.
+
+## Contributing
+
+viga is a personal project maintained in my spare time, so I'm not accepting pull requests or issues. You are welcome to fork it under the MIT license.
+
+## License
+
+[MIT](LICENSE)