feat(nuxt-typed-handler): add the nuxt-typed-handler module

.changeset/dull-pens-love.md

@@ -0,0 +1,5 @@
+---
+'@dphonys/nuxt-typed-handler': minor
+---
+
+Initial release. `@dphonys/nuxt-typed-handler` is one Nuxt module installed instead of `@dphonys/nuxt-handler-errors` and `@dphonys/nuxt-handler-validation`, composing both through their `internals/*` entries. `defineTypedEventHandler({ validate, errors }, fn)` declares a route's request schemas and its expected failures in one place and hands the handler one flat context - the validated sources, plus `fail` when errors were declared - with a built-in `validation-failed` variant that every validating route carries and no route may declare. The Typed fetch family (`useTypedFetch`, `useLazyTypedFetch`, `useRequestTypedFetch`, `useTypedAsyncData`, `useLazyTypedAsyncData`, `$typedFetch` with `.try`, and `event.$typedFetch`) types every call site per route and method for what it may send - `body` and `query` from the schemas' input types - and for what it can fail with. Both parents' public surfaces are re-exported from `/server`, `/shared` and `/types`, so an app imports everything from one package; both parents are pinned exactly, and a project lists this module or them, never both.

.changeset/nuxt-declared-as-peer.md

@@ -0,0 +1,6 @@
+---
+'@dphonys/nuxt-handler-errors': patch
+'@dphonys/nuxt-handler-validation': patch
+---
+
+Declare `nuxt` as a peer dependency (`>=4.5.1 <5.0.0`), so the Nuxt range the readme already states is one the package manager checks as well.

knip.ts

@@ -79,6 +79,22 @@ export default {
       ],
     },
 
+    'packages/nuxt-typed-handler': {
+      ...nuxtModuleWorkspace,
+
+      // As in both parents: this package's suites import `@nuxt/schema`'s types.
+      ignoreDependencies: ['@nuxt/devtools'],
+
+      entry: [
+        ...nuxtModuleWorkspace.entry,
+
+        // Deliberately broken sources, compiled by path by
+        // `test/types/compile-harness.ts` so a suite can assert on their
+        // diagnostics. The package tsconfig excludes them for the same reason.
+        'test/types/fixtures/**/*.ts',
+      ],
+    },
+
     'packages/nuxt-handler-validation/playground': {
       ...playgroundWorkspace,
 
@@ -87,5 +103,14 @@ export default {
       // `.nuxt`.
       entry: ['module-options.check.ts'],
     },
+
+    'packages/nuxt-typed-handler/playground': {
+      ...playgroundWorkspace,
+
+      // As in the validation playground above: compiler-asserted by `vue-tsc`,
+      // never imported. It lives in an app because the route map it reads is
+      // only generated inside one.
+      entry: ['request-typing.check.ts'],
+    },
   },
 } satisfies KnipConfig

packages/nuxt-handler-errors/README.md

@@ -21,6 +21,8 @@ The module has one option, `channelToken` - see
 counterpart, and nothing about a route's failures is configured - it is
 declared, in the route.
 
+**Requirements:** Nuxt `>=4.5.1 <5.0.0`, Node 22.19+ / 24.11+ / 26+.
+
 ## Declaring what a route can fail with
 
 ```ts

packages/nuxt-handler-errors/package.json

@@ -122,6 +122,9 @@
     "vue-tsc": "catalog:",
     "zod": "catalog:"
   },
+  "peerDependencies": {
+    "nuxt": ">=4.5.1 <5.0.0"
+  },
   "engines": {
     "node": "^22.19.0 || ^24.11.0 || >=26.0.0"
   }

packages/nuxt-handler-errors/vitest.config.ts

@@ -1,13 +1,6 @@
 import { fileURLToPath } from 'node:url'
 import { defineConfig } from 'vitest/config'
 
-// Three tiers: `unit` is fast, `types` suites are asserted by the compiler
-// under `typecheck`, and `e2e` builds real apps. The `include` patterns also
-// feed knip's entry points.
-
-// These specifiers only resolve inside a real build, so `unit` aliases them
-// to doubles. Scoping the aliases to `unit` is deliberate: the e2e tier must
-// see the real thing.
 const aliases = [
   {
     find: /^#app$/,
@@ -43,16 +36,18 @@ export default defineConfig({
         test: {
           name: 'types',
           include: ['test/types/**/*.test.ts'],
+          // Each file compiles a real TypeScript program, which a loaded CI runner
+          // stretches well past vitest's 5s default.
+          testTimeout: 60_000,
         },
       },
       {
         test: {
           name: 'e2e',
           include: ['test/e2e/**/*.test.ts'],
           testTimeout: 120_000,
-          // Every file here writes into a real app's build directory - one
-          // prepares the playground and edits its emitted map, another builds
-          // and boots it. Run in parallel they race over the same `.nuxt`.
+          // Every file here works against a real build directory - run in
+          // parallel they race over the same `dist` and `.nuxt`.
           fileParallelism: false,
         },
       },

packages/nuxt-handler-validation/package.json

@@ -98,6 +98,9 @@
     "vue-tsc": "catalog:",
     "zod": "catalog:"
   },
+  "peerDependencies": {
+    "nuxt": ">=4.5.1 <5.0.0"
+  },
   "engines": {
     "node": "^22.19.0 || ^24.11.0 || >=26.0.0"
   }

packages/nuxt-handler-validation/vitest.config.ts

@@ -1,9 +1,5 @@
 import { defineConfig } from 'vitest/config'
 
-// Three tiers, mirroring the sibling: `unit` is fast, `types` suites are
-// asserted by the compiler under `typecheck`, and `e2e` works against real
-// built artifacts. The `include` patterns also feed knip's entry points.
-
 export default defineConfig({
   test: {
     projects: [
@@ -17,6 +13,9 @@ export default defineConfig({
         test: {
           name: 'types',
           include: ['test/types/**/*.test.ts'],
+          // Each file compiles a real TypeScript program, which a loaded CI runner
+          // stretches well past vitest's 5s default.
+          testTimeout: 60_000,
         },
       },
       {

packages/nuxt-typed-handler/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Petr Honys
+
+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.