@dudousxd/nestjs-inertia 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,139 @@
+# Changelog — @dudousxd/nestjs-inertia
+
+## 1.0.0
+
+### Minor Changes
+
+- [`c5878e3`](https://github.com/DavideCarvalho/nestjs-inertia/commit/c5878e3f8827d9e89710df0154ea76996b6db62a) - First public release — Inertia.js v3 adapter for NestJS.
+
+  - Core: InertiaModule.forRoot/forRootAsync/forFeature, @Inertia decorator, Inertia.optional/defer/merge/always markers, CSRF with tokenContext, SSR support, Express + Fastify adapters
+  - Vite: setupInertiaVite + nestInertia plugin, @inertia/@vite/@inertiaHead shell directives
+  - Codegen: nestjs-inertia init (full scaffold + auto-patch), auto-watch in dev, static AST discovery, class-validator DTO support, Route/Path type helpers, @As hierarchical naming
+  - Client: defineContract + @ApplyContract, typed Link for React/Vue/Svelte with context providers, createFetcher, SSR hydration, rich error messages
+  - Testing: expectInertia matchers, assertInertia, InertiaTestingModule, fakes
+
+For the full repository changelog see [`../../CHANGELOG.md`](../../CHANGELOG.md).
+
+## 0.9.0-alpha.0 — 2026-05-22
+
+### BREAKING CHANGE — Removed unimplemented CodegenOptions fields
+
+`CodegenOptions.configFile` and `CodegenOptions.debounceMs` have been removed.
+Both fields were declared in the public type but were never read by the implementation —
+setting them had no effect. They were never functional, so this removal is strictly
+a type cleanup. If you referenced these fields in your code, simply remove them.
+
+### BREAKING CHANGE — Inertia v3 protocol
+
+Four changes to align with the Inertia.js v3 wire protocol:
+
+1. **Shell HTML format** — `@inertia` directive now emits `<div id="app"></div><script id="inertia-page" type="application/json">…</script>` instead of `<div id="app" data-page="…">`. Clients must be on Inertia v3+.
+2. **`clearHistory` / `encryptHistory` omitted when falsy** — these page-level properties are no longer sent on the wire when their value is `false`/`undefined`, matching the v3 spec.
+3. **`Inertia.lazy()` deprecated** — renamed to `Inertia.optional()`; the `lazy` alias is kept for backwards compatibility and logs a deprecation warning at runtime.
+4. **Nested partial-reload dot-notation** — `only`/`except` arrays now support dot-notation paths (e.g. `"user.profile"`) to target nested props.
+
+### Changed
+
+- Version bump to `0.9.0-alpha.0`
+
+## 0.8.0-alpha.0 — 2026-05-22
+
+### Added
+
+- **Auto-bootstrap codegen** — `InertiaModule` implements `OnApplicationBootstrap`; codegen is triggered automatically at app startup when `autoCodegen` is enabled in the module options
+- **`RegistryRoutes` helper** — new export enabling module augmentation for typed route names and params; consumers import `RegistryRoutes` to get the full typed route map from the augmented `InertiaRegistry`
+- **Probe loop fix** — `NESTJS_INERTIA_CODEGEN_PROBE` env guard prevents `OnApplicationBootstrap` from re-triggering codegen when the app is bootstrapped by the codegen probe itself
+
+### Changed
+
+- Version bump to `0.8.0-alpha.0`
+
+## 0.7.0-alpha.0 — 2026-05-22
+
+### Changed
+
+- Bundled with example app, CI workflows, Changesets, MIT LICENSE, and slim docs.
+
+## [0.6.0-alpha.0] - 2026-05-22
+
+### Changed
+
+- Version bump to `0.6.0-alpha.0` (monorepo coordination with Plan D client release; no source changes)
+
+## [0.5.0-alpha.0] - 2026-05-22
+
+### Added
+
+- `InertiaRegistry` interface — empty extensible interface for codegen-driven module augmentation. Augment it in your project to get typed page names and route params.
+
+### Changed
+
+- Version bump to `0.5.0-alpha.0` (monorepo coordination with codegen release)
+
+## [0.4.0-alpha.0] - 2026-05-22
+
+### Added (companion packages)
+
+- `@dudousxd/nestjs-inertia-vite@0.1.0-alpha.0` — Vite dev/build helpers + plugin (`nestInertia({ ssr, react|vue|svelte, ... })`)
+- `@dudousxd/nestjs-inertia-testing@0.1.0-alpha.0` — `expectInertia(res)` fluent matchers + `assertInertia(payload)` + `createFakeInertiaRequest/Response` + `InertiaTestingModule.forTest()` + Jest/Vitest `expect.extend` integration
+
+### Changed
+
+- `@dudousxd/nestjs-inertia` core bumped to `0.4.0-alpha.0` (monorepo coordination; no source changes)
+
+## [0.3.0-alpha.0] - 2026-05-22
+
+### Added
+
+- `InertiaModule.forFeature({ scope })` and `forFeatureAsync` — multi-app support
+- `@UseInertia('scope')` decorator (class + method level) for selecting scope
+- `InertiaScopeSwitcherInterceptor` — auto-installed; replaces `req.inertia` with scoped service
+- 4 template engine adapters: Handlebars, EJS, Pug, LiquidJS (peer deps, all optional)
+- `MissingTemplateEngineDepException` with installation hint
+- CSRF: `CsrfCookieInterceptor` (writes XSRF-TOKEN cookie) + `CsrfGuard` (validates X-XSRF-TOKEN header)
+- `generateCsrfToken` / `verifyCsrfToken` HMAC-SHA256 helpers
+- `MissingCookieDepException` + `InvalidCsrfTokenException` (extends `ForbiddenException` → 403)
+- Fastify adapter — full parity with Express: `fastifyAdapter`, `registerFastifyInertia` (decorateRequest + onRequest), `registerFastifyMethodSpoof` (preHandler)
+- Platform detection in `InertiaModule.onApplicationBootstrap` via `HttpAdapterHost.httpAdapter.getType()`
+- `InertiaAuthGuard` is now platform-aware (Express `redirect(status, url)` vs Fastify `redirect(url, status)`)
+- `RedirectInterceptor` patches `reply.code()` on Fastify for `@Res()` handlers that send manually
+
+### Pending for future plans
+
+- Companion packages: `@dudousxd/nestjs-inertia-vite` (Plan B), `-testing` (Plan B), `-codegen` (Plan C), `-client` (Plan D — Tuyau-style)
+- Examples + docs site + CI workflows (Plan E)
+
+## [0.2.0-alpha.0] - 2026-05-22
+
+### Added
+
+- `InertiaModule.forRootAsync()` with `useFactory + inject`, `useClass`, `useExisting` paths
+- `@Inertia('Page')` decorator + `InertiaRenderInterceptor` (coexists with imperative `req.inertia.render()`)
+- `Inertia.once()` prop marker (resolves once per session, refreshed via `X-Inertia-Reset-Once`)
+- `RedirectInterceptor` — auto 302→303 for PUT/PATCH/DELETE Inertia requests
+- `MethodSpoofMiddleware` — `_method=PUT/PATCH/DELETE` override on POST + multipart
+- Shell HTML directives in file-based `rootView`: `@inertia`, `@inertiaHead`, `@vite('entry')`, `@viteRefresh`, `@asset('path')`
+- Real SSR loader (dynamic `import(pathToFileURL)`, cache, `throwOnError`)
+- `InertiaAuthGuard` (409 vs 302 based on X-Inertia header, return_to preserved)
+- `InertiaNotFoundFilter` (JSON for `/api/*`, Inertia 'NotFound' page elsewhere)
+- `ErrorBagInterceptor` (`X-Inertia-Error-Bag` namespaces props.errors)
+- `FlashStore` interface (pluggable session-errors source, default no-op)
+- `X-Inertia-Partial-Except` header
+- `X-Inertia-Reset` header
+- Dot-notation top-level prop unpacking
+- Plain (non-marker) function props auto-invoked and awaited
+
+### Changed
+
+- `undefined` values in props converted to `null` on the JSON wire (Laravel parity)
+- `Inertia` is now a callable function (decorator) AND retains namespace methods
+
+### Pending for 0.3.0 (Plan A.3)
+
+- `forFeature` / multi-app, template engines, CSRF, Fastify adapter
+
+## [0.1.0-alpha.0] - 2026-05-22
+
+### Added
+
+- Initial release with core Express Inertia v2 protocol, partial reloads, prop markers, SSR stub, manifest/asset version providers, suppressPostSendWrites helper

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Davide Carvalho
+
+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.md

@@ -0,0 +1,317 @@
+# @dudousxd/nestjs-inertia
+
+> Inertia.js v3 adapter for NestJS — Express + Fastify, multi-app via `forFeature`, 4 template engines, CSRF protection, full Inertia v3 protocol parity.
+
+[![npm](https://img.shields.io/npm/v/@dudousxd/nestjs-inertia.svg)](https://npmjs.com/package/@dudousxd/nestjs-inertia)
+[![license](https://img.shields.io/npm/l/@dudousxd/nestjs-inertia.svg)](https://github.com/DavideCarvalho/nestjs-inertia/blob/main/LICENSE)
+
+> **Status: alpha.** API is stabilising but may change before `1.0`. Not recommended for production use yet.
+
+## Install
+
+```bash
+pnpm add @dudousxd/nestjs-inertia
+
+# Pick your HTTP platform
+pnpm add express @types/express          # Express adapter (default)
+# OR
+pnpm add fastify @nestjs/platform-fastify @fastify/cookie  # Fastify adapter
+```
+
+## Quick start
+
+```ts
+// app.module.ts
+import { Module } from '@nestjs/common';
+import { InertiaModule } from '@dudousxd/nestjs-inertia';
+
+@Module({
+  imports: [
+    InertiaModule.forRoot({
+      version: () => process.env.ASSET_VERSION ?? 'dev',
+      rootView: 'inertia/root.html',
+      share: async (req) => ({ auth: req.user ?? null }),
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+`inertia/root.html`:
+
+```html
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <title>My App</title>
+  @inertiaHead
+  @vite('app/client.tsx')
+  @viteRefresh
+</head>
+<body>
+  @inertia
+</body>
+</html>
+```
+
+## Controllers
+
+Two equivalent patterns coexist:
+
+```ts
+import { Controller, Get, Req } from '@nestjs/common';
+import { Inertia } from '@dudousxd/nestjs-inertia';
+import type { Request } from 'express';
+
+@Controller()
+export class HomeController {
+  // Decorator pattern (idiomatic for new code)
+  @Get('/')
+  @Inertia('Home')
+  show() {
+    return { hello: 'world' };
+  }
+
+  // Imperative pattern (use when you need fine control)
+  @Get('/crew')
+  async list(@Req() req: Request) {
+    await req.inertia
+      .share({ flash: req.session?.flash ?? {} })
+      .render('Crew', { crew: await this.svc.list() });
+  }
+}
+```
+
+## Async config
+
+```ts
+InertiaModule.forRootAsync({
+  imports: [ConfigModule],
+  inject: [ConfigService],
+  useFactory: (cfg: ConfigService) => ({
+    version: cfg.get('ASSET_VERSION'),
+    rootView: 'inertia/root.html',
+  }),
+});
+```
+
+Three paths: `useFactory + inject` (most common), `useClass`, `useExisting`.
+
+## Multi-app with `forFeature`
+
+Host two or more Inertia apps in the same NestJS process — each with its own Vite entry, shell, version, share, SSR bundle. Useful for admin panels, multi-tenant white-label, or migrations between frontend stacks.
+
+```ts
+@Module({
+  imports: [
+    InertiaModule.forRoot({                  // main app
+      vite: { entry: 'app/client.tsx' },
+      rootView: 'inertia/root.html',
+      share: req => ({ auth: req.user }),
+    }),
+    InertiaModule.forFeature({               // admin app
+      scope: 'admin',
+      vite: { entry: 'admin/client.tsx' },
+      rootView: 'inertia/admin-root.html',
+      share: req => ({ admin: req.adminContext }),
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+Select scope per controller / method with `@UseInertia('scope')`:
+
+```ts
+@Controller('admin')
+@UseInertia('admin')
+export class AdminDashboardController {
+  @Get('/')
+  @Inertia('AdminDashboard')
+  show() { return { stats: ... }; }
+}
+```
+
+`forFeatureAsync` works the same as `forRootAsync` (useFactory/useClass/useExisting). Reserved scope: `'default'` is owned by `forRoot()`.
+
+## Template engines
+
+`rootView` accepts `.html` (own parser) plus `.hbs` / `.ejs` / `.pug` / `.liquid` if the engine package is installed:
+
+```bash
+pnpm add handlebars                    # or: ejs, pug, liquidjs
+```
+
+```ts
+InertiaModule.forRoot({
+  rootView: 'inertia/root.hbs',         // auto-detects Handlebars
+});
+```
+
+Each engine sees locals `{ page, inertia, inertiaHead, vite, viteRefresh, asset }`. Use the engine's own escape rules (e.g., `{{{inertia}}}` triple-stache in Handlebars, `<%- inertia %>` in EJS, `!= inertia` in Pug). The `@inertia`/`@vite`/`@asset` directives are also processed on the engine's output, so you can mix and match.
+
+## CSRF
+
+```ts
+import { CsrfCookieInterceptor, CsrfGuard } from '@dudousxd/nestjs-inertia';
+
+// Global cookie writer
+app.useGlobalInterceptors(new CsrfCookieInterceptor({ secret: process.env.CSRF_SECRET }));
+
+// Per-route validation
+@UseGuards(new CsrfGuard({ secret: process.env.CSRF_SECRET }))
+@Post('/profile')
+async update() { ... }
+```
+
+Cookie name `XSRF-TOKEN`, header name `X-XSRF-TOKEN` — both match the Inertia client convention. Signed via HMAC-SHA256. Requires `cookie-parser` (Express) or `@fastify/cookie` (Fastify) as peer dep.
+
+## Fastify
+
+```ts
+import { FastifyAdapter } from '@nestjs/platform-fastify';
+
+const app = await NestFactory.create<NestFastifyApplication>(AppModule, new FastifyAdapter());
+```
+
+Full feature parity with Express: middleware, decorator, all interceptors, guards, filters, shell directives, SSR, FlashStore. `request.inertia` is wired via `decorateRequest` + `onRequest` hook automatically when the FastifyAdapter is detected.
+
+## Prop markers
+
+```ts
+import { Inertia } from '@dudousxd/nestjs-inertia';
+
+return {
+  user: Inertia.always(() => currentUser()),
+  stats: Inertia.optional(() => heavyStatsCalculation()),
+  activity: Inertia.defer(() => activityFeed(), 'secondary'),
+  rows: Inertia.merge(() => paginated(p), { matchOn: 'id', deep: false }),
+  csrfToken: Inertia.once(() => generateToken()),
+};
+```
+
+- `always` — resolves on every render (including partial reloads)
+- `optional` — resolves only when listed in `X-Inertia-Partial-Data`
+- `defer` — listed in `page.deferredProps`; client v2 dispatches a follow-up request
+- `merge` — resolves + marks as merge target (client appends/replaces)
+- `once` — resolves on first visit, cached until `X-Inertia-Reset-Once` lists the key
+- `lazy` — alias for `optional` (v1 compat)
+
+## Auto-included infrastructure
+
+`forRoot()` installs:
+- `InertiaMiddleware` (Express) or `FastifyInertiaPlugin` (Fastify) — `req.inertia` available everywhere
+- `MethodSpoofMiddleware` (POST + multipart + `_method=PUT/PATCH/DELETE`)
+- `RedirectInterceptor` (302 → 303 upgrade on PUT/PATCH/DELETE Inertia requests)
+- `InertiaRenderInterceptor` (handles `@Inertia('Page')` decorator)
+- `InertiaScopeSwitcherInterceptor` (handles `@UseInertia('scope')`)
+
+Disable via knobs:
+
+```ts
+InertiaModule.forRoot({
+  methodSpoofing: false,
+  autoUpgrade303: false,
+});
+```
+
+## Opt-in utilities
+
+```ts
+import {
+  InertiaAuthGuard,
+  InertiaNotFoundFilter,
+  ErrorBagInterceptor,
+} from '@dudousxd/nestjs-inertia';
+
+// Auth guard — applies per controller / handler
+@UseGuards(new InertiaAuthGuard({ signInUrl: '/signin', allowList: ['/signin/*'] }))
+
+// Not-found filter — register globally
+app.useGlobalFilters(new InertiaNotFoundFilter({ apiPrefix: '/api', component: 'NotFound' }));
+
+// Error bag interceptor — opt-in per route
+@UseInterceptors(ErrorBagInterceptor)
+```
+
+## FlashStore (errors)
+
+NestJS has no session of its own. Plug an adapter:
+
+```ts
+import type { FlashStore } from '@dudousxd/nestjs-inertia';
+
+class ExpressSessionFlashStore implements FlashStore {
+  read(req) {
+    return (req as Request).session?.flash?.errors ?? {};
+  }
+}
+
+InertiaModule.forRoot({
+  flashStore: new ExpressSessionFlashStore(),
+});
+```
+
+## SSR
+
+```ts
+InertiaModule.forRoot({
+  ssr: {
+    enabled: process.env.NODE_ENV === 'production',
+    bundlePath: 'dist/inertia/ssr/ssr.mjs',
+    throwOnError: false,
+  },
+});
+```
+
+Bundle must export `default { render(page) }` or named `render(page)` returning `{ head: string[], body: string }`.
+
+## Codegen auto-watch (dev mode)
+
+When `@dudousxd/nestjs-inertia-codegen` is installed and a `nestjs-inertia.config.ts` config file is present, `InertiaModule` automatically starts the codegen file watcher when your app bootstraps — so `nest start --watch` is the only command you need in dev mode. Generated files appear under `.nestjs-inertia/` and update on every controller or page save. **No extra command, no extra terminal.**
+
+**Auto-watch starts when all of these are true:**
+1. `NODE_ENV !== 'production'`
+2. `@dudousxd/nestjs-inertia-codegen` is installed (peer-optional — silently skipped if absent)
+3. `nestjs-inertia.config.ts` is present at the project root
+4. `NESTJS_INERTIA_DISABLE_AUTO_CODEGEN` is not set to `'1'`
+
+**Running the CLI watcher manually:** `pnpm nestjs-inertia codegen --watch` in a separate terminal gives you explicit control. When both the auto-watcher and the CLI watcher run at the same time, only one holds the lock and generates files; the other logs a warning and becomes a no-op. Stale locks from crashed processes are detected via PID-liveness check and overwritten automatically.
+
+**Disable auto-watch** (CI or explicit control):
+
+```ts
+InertiaModule.forRoot({
+  codegen: { enabled: false },
+});
+```
+
+**Optional `nest-cli.json` snippet** — only useful if your server bundle imports generated files:
+
+```json
+{
+  "compilerOptions": {
+    "assets": [".nestjs-inertia/**/*"],
+    "watchAssets": true
+  }
+}
+```
+
+## Protocol parity
+
+Full Inertia protocol: X-Inertia headers, version mismatch (409 + X-Inertia-Location, GET only), partial reloads, deferred props, merge/deepMerge with matchOn, once, history encryption / clear, error bags, X-Inertia-Reset, X-Inertia-Partial-Except, X-Inertia-Reset-Once, dot-notation unpacking, undefined→null wire conversion.
+
+## Companion packages (planned)
+
+- `@dudousxd/nestjs-inertia-vite` — Vite dev/build helpers (Plan B)
+- `@dudousxd/nestjs-inertia-testing` — `expectInertia(res)` matchers (Plan B)
+- `@dudousxd/nestjs-inertia-codegen` — typed pages (Plan C)
+- `@dudousxd/nestjs-inertia-client` — Tuyau-style typed REST + TanStack Query (Plan D)
+- Examples + docs site + CI workflows (Plan E)
+
+See [`docs/design.md`](../../docs/design.md) for full design.
+
+## License
+
+MIT © Davi Carvalho